From bee63ed54cea1625e00857bef2c17af0c665ed5c Mon Sep 17 00:00:00 2001
From: Gaubee <GaubeeBangeel@Gmail.com>
Date: Thu, 25 Dec 2025 08:24:57 +0800
Subject: [PATCH] feat(agent): align help entrypoint

---
 AGENTS.md                                      |  1 +
 .../update-agent-help-default/proposal.md      | 13 +++++++++++++
 .../specs/agent-cli/spec.md                    | 16 ++++++++++++++++
 .../changes/update-agent-help-default/tasks.md |  4 ++++
 scripts/agent/cli.ts                           | 18 +++++++++---------
 5 files changed, 43 insertions(+), 9 deletions(-)
 create mode 100644 openspec/changes/update-agent-help-default/proposal.md
 create mode 100644 openspec/changes/update-agent-help-default/specs/agent-cli/spec.md
 create mode 100644 openspec/changes/update-agent-help-default/tasks.md

diff --git a/AGENTS.md b/AGENTS.md
index c647e725..98a0d901 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,7 @@ pnpm agent readme
 
 ```bash
 pnpm agent readme              # 启动入口（索引 + 知识地图 + 最佳实践）
+pnpm agent --help              # 查看帮助
 pnpm agent roadmap current     # 当前 Roadmap
 pnpm agent toc                 # 白皮书目录
 pnpm agent chapter <路径>       # 读取白皮书章节
diff --git a/openspec/changes/update-agent-help-default/proposal.md b/openspec/changes/update-agent-help-default/proposal.md
new file mode 100644
index 00000000..6ae5aff7
--- /dev/null
+++ b/openspec/changes/update-agent-help-default/proposal.md
@@ -0,0 +1,13 @@
+# Change: Align agent help behavior with --help
+
+## Why
+当前 CLI 仍支持 `pnpm agent help` 且无参数时仅提示入口，而最新规范要求：帮助只能通过 `--help`，且 `pnpm agent` 无子命令时直接输出完整帮助内容。
+
+## What Changes
+- `pnpm agent` 无参数直接打印 `--help` 内容。
+- 移除 `pnpm agent help` 入口，改为提示使用 `--help`。
+- 同步相关文档与 CLI 使用说明。
+
+## Impact
+- Affected specs: agent-cli
+- Affected code: scripts/agent/cli.ts, AGENTS.md (help 指引), CLAUDE.md (入口提示), docs/white-book/附录/H-开发规范/index.md
diff --git a/openspec/changes/update-agent-help-default/specs/agent-cli/spec.md b/openspec/changes/update-agent-help-default/specs/agent-cli/spec.md
new file mode 100644
index 00000000..cc89672f
--- /dev/null
+++ b/openspec/changes/update-agent-help-default/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 the same help content as `pnpm agent --help`
+
+#### Scenario: Help usage
+- **WHEN** the user runs `pnpm agent --help`
+- **THEN** the CLI prints subcommand usage说明
+
+#### Scenario: Legacy help command
+- **WHEN** the user runs `pnpm agent help`
+- **THEN** the CLI exits with an explicit message to use `--help`
diff --git a/openspec/changes/update-agent-help-default/tasks.md b/openspec/changes/update-agent-help-default/tasks.md
new file mode 100644
index 00000000..e67e34db
--- /dev/null
+++ b/openspec/changes/update-agent-help-default/tasks.md
@@ -0,0 +1,4 @@
+## 1. Implementation
+- [x] 1.1 调整 CLI 默认行为与 help 入口
+- [x] 1.2 更新文档中 help 命令指引
+- [x] 1.3 验证：运行 `pnpm agent` 与 `pnpm agent --help`
diff --git a/scripts/agent/cli.ts b/scripts/agent/cli.ts
index 2e84a961..92c69958 100644
--- a/scripts/agent/cli.ts
+++ b/scripts/agent/cli.ts
@@ -46,6 +46,7 @@ AI Agent CLI
 
 Usage:
   pnpm agent readme                          # 输出索引（最佳实践 + 知识地图）
+  pnpm agent --help                          # 查看帮助
   pnpm agent roadmap [current|v1|v2|draft]   # 查看任务列表
   pnpm agent claim <issue#>                  # 领取任务（分配给自己）
   pnpm agent done <issue#>                   # 完成任务（关闭 Issue）
@@ -81,13 +82,6 @@ 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
@@ -265,11 +259,11 @@ function main(): void {
   const args = process.argv.slice(2)
 
   if (args.length === 0) {
-    printEntryHint()
+    printHelp()
     return
   }
 
-  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+  if (args.includes('--help') || args.includes('-h')) {
     printHelp()
     return
   }
@@ -350,6 +344,12 @@ function main(): void {
       handleWorktree(rest)
       break
 
+    case 'help':
+      log.error('请使用 --help 查看帮助')
+      printHelp()
+      process.exit(1)
+      break
+
     default:
       log.error(`未知命令: ${command}`)
       printHelp()