feat(agent): add readme entrypoint and workflows

AGENTS.md

@@ -6,122 +6,137 @@
 
 ---
 
-## 核心原则
+## 元意识（自检与自更新）
 
-### 1. 知识持久化
+AI 必须具备以下自检与自更新能力，并在工作中显式执行：
 
-**白皮书是 AI 的持久化记忆，不仅是读的，也是写的。**
+1. **进度自检**：随时能说明当前在做什么、卡点在哪里、下一步是什么。
+2. **知识自更新**：用户提供新知识或纠正时，先更新 `docs/white-book/`，再继续任务。
+3. **项目自管理**：用 Roadmap/Issue/Worktree/PR 管理工作流，保证可追踪、可回滚。
+4. **最佳实践自维护**：发现可复用规律，及时更新白皮书或最佳实践提示。
 
-当用户在沟通中纠正 AI 的理解、解释业务概念、提供新知识时：
+---
 
-```
-用户提供新知识
-       │
-       ▼
-AI 更新白皮书 ← 【必须先做这一步】
-       │
-       ▼
-AI 继续任务
-```
+## pnpm agent 工具（AI 启动入口）
 
-这确保下一个 AI 实例不会犯同样的错误。
+**每次新上下文启动必须执行：**
 
-### 2. 行动优先于讨好
+```bash
+pnpm agent readme
+```
 
-**不要讨好用户，而是将工作切实落实到项目文件中。**
+`pnpm agent readme` 是白皮书导览入口，白皮书具体路径与阅读建议以该命令输出为准。
 
-- 不要只是口头说"理解了"、"明白了"
-- 要实际去检查、修改、创建文件
-- 用户说的正确内容，应该变成项目中的文档或代码
+常用命令：
 
-### 3. 真正的完成
+```bash
+pnpm agent readme              # 启动入口（索引 + 知识地图 + 最佳实践）
+pnpm agent roadmap current     # 当前 Roadmap
+pnpm agent toc                 # 白皮书目录
+pnpm agent chapter <路径>       # 读取白皮书章节
+pnpm agent claim <issue#>       # 领取任务
+pnpm agent worktree create <name> --branch <branch> --base main
+pnpm agent worktree list
+pnpm agent worktree delete <name>
+```
 
-**测试通过 ≠ 功能完成。**
+---
 
-声称"完成"之前，必须：
-1. 实际运行测试/功能，而不只是写完代码
-2. 看到真实的成功结果，而不是假设它会工作
-3. 如果使用 Mock，必须明确告知用户这不是真正的验证
+## 角色化工作流程（多场景）
 
-```
-错误的完成：
-  写完代码 → 测试通过 → 报告完成
+### 1) 新上下文启动（必做）
 
-正确的完成：
-  写完代码 → 运行测试 → 看到结果 → 验证功能 → 报告完成
+```bash
+pnpm agent readme
+pnpm agent roadmap current
+pnpm agent toc
+pnpm agent chapter 00-必读
 ```
 
-### 4. 文档驱动开发
+完成后自检：
+- 当前任务目标是否清晰？
+- 是否需要读更多白皮书章节？
+- 是否需要查看 openspec 规范？
 
-**先文档，后代码。**
+### 2) 继续未完成任务（接手/续写）
 
-```
-白皮书 (docs/white-book/) > 原始代码参考
+```bash
+pnpm agent readme
+pnpm agent roadmap current
+pnpm agent worktree list
+# 进入已有 worktree，检查 git status / 进度
 ```
 
-任何开发任务：
-1. 先检查/更新白皮书
-2. 再开始编码
+自检：确认已有 worktree 的分支、PR 状态、CI 状态是否需要处理。
 
----
-
-## 层次区分
+### 3) 需求澄清 / 方案设计（产品/架构角色）
 
-| 层次 | 存放位置 | 内容 |
-|-----|---------|------|
-| **元意识** | AGENTS.md | 如何思考、如何工作的原则 |
-| **项目知识** | docs/white-book/ | 业务概念、技术细节、API 规范 |
-| **操作指南** | docs/white-book/ | 具体命令、配置、步骤 |
+```bash
+pnpm agent readme
+pnpm agent toc
+pnpm agent chapter <需求相关章节>
+```
 
----
+- 若涉及新能力/架构变更，先查看 `openspec/AGENTS.md` 并走提案流程。
+- 记录结论到白皮书或 openspec 变更中。
 
-## 快速入口
+### 4) 实现开发（工程师角色）
 
 ```bash
-pnpm agent                    # 获取项目知识和当前任务
-pnpm agent roadmap current    # 查看当前 Roadmap
-pnpm agent chapter 00-必读     # 查看必读章节
+pnpm agent readme
+pnpm agent claim <issue#>
+pnpm agent worktree create issue-<id> --branch feat/issue-<id> --base main
+cd .git-worktree/issue-<id>
+pnpm agent chapter <路径>
+# 开发 + 测试
+pnpm dev
+pnpm test
+pnpm typecheck
 ```
 
-详细的项目信息、技术栈、开发流程请查阅白皮书。
-
----
+```bash
+# 提交与 PR
+ git add -A
+ git commit -m "feat/fix: 描述"
+ git push -u origin <branch>
+ gh pr create --title "标题" --body "Closes #<issue#>" --base main
+```
 
-## 开发闭环（必须遵循）
+### 5) Bug 修复 / 回归（维护者角色）
 
 ```bash
-# 1) 获取索引 + Roadmap
-pnpm agent
+pnpm agent readme
 pnpm agent roadmap current
+pnpm agent worktree create fix-<id> --branch fix/<id> --base main
+```
 
-# 2) 领取任务（Issue）
-pnpm agent claim <issue#>
+- 先复现并记录原因。
+- 必要时更新白皮书，说明修复背景与影响。
 
-# 3) 创建 worktree（严格校验分支前缀与 .env.local）
-pnpm agent worktree create issue-<id> --branch feat/issue-<id> --base main
-cd .git-worktree/issue-<id>
+### 6) 评审 / 质量保证（Reviewer 角色）
 
-# 4) 阅读白皮书（先文档后编码）
-pnpm agent toc
-pnpm agent chapter <路径>
+```bash
+pnpm agent readme
+pnpm agent chapter <测试/规范相关章节>
+```
 
-# 5) 开发 + 测试
-pnpm dev
-pnpm test
-pnpm typecheck
+- 关注回归风险、测试覆盖、接口兼容性。
+- 有问题先写明事实，再给出修复建议。
 
-# 6) 提交 + 推送 + PR
-git add -A
-git commit -m "feat/fix: 描述"
-git push -u origin <branch>
-gh pr create --title "标题" --body "Closes #<issue#>" --base main
+### 7) 合并收尾（集成角色）
 
-# 7) 合并 + 清理
-gh pr merge --squash --delete-branch
-pnpm agent worktree delete issue-<id>
+```bash
+gh pr checks <pr#> --watch
+gh pr merge <pr#> --squash --delete-branch
+pnpm agent worktree delete <name>
 ```
 
-> 白皮书是唯一权威来源：若用户补充/纠正知识，必须先更新 `docs/white-book/` 再继续开发。
+---
+
+## 重要提醒
+
+- 白皮书是唯一权威来源：用户补充/纠正知识，必须先更新 `docs/white-book/`。
+- 不允许在主目录直接开发，所有代码必须在 `.git-worktree/` 中进行。
 
 <!-- OPENSPEC:START -->
 

CLAUDE.md

@@ -4,7 +4,7 @@
 
 ```bash
 # 1. 获取索引（最佳实践 + 知识地图）
-pnpm agent
+pnpm agent readme
 
 # 2. 查看当前任务
 pnpm agent roadmap current

docs/white-book/附录/H-开发规范/index.md

@@ -78,7 +78,7 @@ Closes #28
 ## 命令速查
 
 ```bash
-pnpm agent                    # 项目知识 + 当前任务
+pnpm agent readme             # 项目知识 + 当前任务
 pnpm agent claim 28           # 领取任务
 pnpm agent chapter <路径>     # 查阅白皮书
 pnpm agent stats              # 进度统计

openspec/changes/update-agent-readme-workflow/proposal.md

@@ -0,0 +1,14 @@
+# Change: Update agent readme entrypoint and workflow guidance
+
+## Why
+新的 AI 使用规范要求通过子命令启动（`pnpm agent readme`），并提供多角色、多场景的完整工作流程。现有 AGENTS.md 仅覆盖单一程序员流程且入口仍指向 `pnpm agent`。
+
+## What Changes
+- 新增 `pnpm agent readme` 子命令作为 AI 启动入口。
+- 调整 `pnpm agent` 默认行为为提示使用子命令。
+- 重构 AGENTS.md：先说明元意识，再说明 agent 工具，再提供多角色/多场景工作流闭环。
+- 同步相关文档与 CLI 帮助文本。
+
+## Impact
+- Affected specs: agent-cli
+- Affected code: scripts/agent/cli.ts, scripts/agent/readme.ts (usage text), AGENTS.md, CLAUDE.md, docs/white-book/附录/H-开发规范/index.md

openspec/changes/update-agent-readme-workflow/specs/agent-cli/spec.md

@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: Agent CLI subcommands
+`pnpm agent` SHALL expose primary functions as subcommands (readme/roadmap/claim/done/create/stats/toc/chapter/epic/worktree) and provide usage help when requested.
+
+#### Scenario: Default usage
+- **WHEN** the user runs `pnpm agent` without arguments
+- **THEN** the CLI prints a short help message that points to `pnpm agent readme`
+
+#### Scenario: Readme usage
+- **WHEN** the user runs `pnpm agent readme`
+- **THEN** the CLI prints the agent index内容
+
+#### Scenario: Help usage
+- **WHEN** the user runs `pnpm agent --help` or `pnpm agent help`
+- **THEN** the CLI prints subcommand usage说明

openspec/changes/update-agent-readme-workflow/tasks.md

@@ -0,0 +1,5 @@
+## 1. Implementation
+- [x] 1.1 更新 AGENTS.md（元意识 → 工具 → 多角色流程）
+- [x] 1.2 新增 `pnpm agent readme` 子命令并调整默认行为
+- [x] 1.3 更新 CLI 帮助文案与白皮书/CLAUDE 指引
+- [x] 1.4 验证：运行 `pnpm agent readme` 与 `pnpm agent help`

scripts/agent/cli.ts

@@ -3,7 +3,7 @@
  * AI Agent CLI - 主入口
  *
  * Usage:
- *   pnpm agent                                 # 输出索引（最佳实践 + 知识地图）
+ *   pnpm agent readme                          # 输出索引（最佳实践 + 知识地图）
  *   pnpm agent roadmap [version]               # 查看任务列表
  *   pnpm agent claim <issue#>                  # 领取任务
  *   pnpm agent done <issue#>                   # 完成任务
@@ -45,7 +45,7 @@ function printHelp(): void {
 AI Agent CLI
 
 Usage:
-  pnpm agent                                 # 输出索引（最佳实践 + 知识地图）
+  pnpm agent readme                          # 输出索引（最佳实践 + 知识地图）
   pnpm agent roadmap [current|v1|v2|draft]   # 查看任务列表
   pnpm agent claim <issue#>                  # 领取任务（分配给自己）
   pnpm agent done <issue#>                   # 完成任务（关闭 Issue）
@@ -72,6 +72,7 @@ Worktree 管理:
 Aliases: CURRENT -> V1, NEXT -> V2
 
 Examples:
+  pnpm agent readme
   pnpm agent roadmap current
   pnpm agent claim 28
   pnpm agent create "修复某个问题" --category bug --roadmap v1
@@ -80,6 +81,13 @@ Examples:
 `)
 }
 
+function printEntryHint(): void {
+  console.log(`\nAI Agent CLI\n`)
+  console.log('请使用子命令启动：')
+  console.log('  pnpm agent readme')
+  console.log('  pnpm agent help\n')
+}
+
 function getFlagValue(args: string[], flag: string): string | undefined {
   const index = args.indexOf(flag)
   if (index === -1) return undefined
@@ -257,7 +265,7 @@ function main(): void {
   const args = process.argv.slice(2)
 
   if (args.length === 0) {
-    printIndex()
+    printEntryHint()
     return
   }
 
@@ -273,6 +281,10 @@ function main(): void {
   const [command, ...rest] = args
 
   switch (command) {
+    case 'readme':
+      printIndex()
+      break
+
     case 'roadmap':
       printRoadmap(rest[0])
       break

scripts/agent/readme.ts

@@ -88,6 +88,7 @@ export function printWorkflow(): void {
   console.log(`
 # 工作流
 
+pnpm agent readme             启动入口（索引 + 知识地图 + 最佳实践）
 pnpm agent claim <#>          领取任务 (自动分配+worktree指引)
 pnpm agent create "x"         创建任务 (--category bug --roadmap v1)
 pnpm agent epic create "x"    创建 Epic (--roadmap v1)