文档指引体系概览

Block 是一期个人博客（Vue 3 + NestJS + PostgreSQL），采用 pnpm Monorepo 与 Cursor Agent 协作开发。项目的文档指引以根目录 AGENTS.md 为唯一核心入口。

权威层级

1. AGENTS.md — 项目进度、Agent 流程与任务分型
2. module 方案 — 模块实现与 §14 验收项
3. 总体技术方案 — 架构边界与 Decision Log
4. 服务器部署现状 — 生产环境事实

一期 Phase 0–6 已全部验收通过；新功能默认属于维护类改动，或用户明确指定的未来 Phase。

四类 Agent

类型	适用场景
Phase 开发	新 Phase 的方案编写（A）、评审（B）、开发与验收（C）
维护 / Bug 修复	缺陷修复、小范围改码；只验证变更影响面
文档修订	AGENTS、module、deploy 等文档；含占位方案与方向讨论
运维	SSH 远端更新、排障、备份；发布时可选本地 build/scp

UI 验收（Playwright MCP）不是独立 Agent，而是 Phase C 与维护任务的 L2 分层手段。

分层验收（L1 → L2 → L3）

• L1：pnpm accept:phase3 ~ accept:phase6 等自动化脚本
• L2：Playwright MCP 做 Admin/Web UI 验收
• L3：用户手动验收（例外，仅当 L1/L2 无法覆盖 §14 项）

Phase 开发工作流（A/B/C）

• A 方案编写：补全 module 方案，不写业务代码，不 git 提交
• B 方案评审：可行性、环境检查；用户许可后 commit/push
• C 开发与验收：pnpm check:env → 编码 → 分层验收 + §14 → 用户许可后 commit/push

新会话 Quick Start

1. 读 AGENTS.md，识别任务类型
2. Phase 开发再确认 A/B/C
3. 按类型读 module / deploy / rules
4. 验收通过后分别确认 commit 与 push

---

本文介绍 Block 项目面向 Cursor Agent 的文档与工作流设计，便于后续协作开发。