docs: 归档任务 #9

AGENTS.md

@@ -41,6 +41,21 @@
 
 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。
 
+### 自然语言快捷指令
+
+快捷指令只是本工作流的自然语言别名，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收：
+
+- `只分析`：只读检查并给出方案；不建单、不修改，停在等待确认。
+- `建工单`：根据已确认方案创建单元任务工单；建单后停止，不修改代码。
+- `执行工单 #N`：检查工单和依赖，实施、测试、提交、归档、推送并回写证据；停在“待验收”。
+- `建工单并做`：依次建单和执行，`建工单，做`、`建工单,做` 含义相同；停在“待验收”。
+- `继续工单 #N`：核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查。
+- `检查工单 #N`：只读核对范围、验收、测试和证据并输出报告；不自动修复。
+- `同步文档`：读取 Wiki、导出 `docs/` 并检查一致性；不修改 Wiki、不自动提交。
+- `#N 验收通过`：仅在用户明确验收后，更新归档、同步并提交镜像、推送、同步父工单并关闭任务。
+
+方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。Gitea 工单不导出全文，本地只保存 Wiki 任务归档镜像。详细语义见 [开发工作流](docs/01-workflow.md)。
+
 ### 效率与范围控制
 
 本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。

dev_scripts/check_harness.py

@@ -44,6 +44,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 面向初级维护者的修改边界",
         "## 每个任务的文档影响",
         "## 稳定文档与任务归档",
+        "## 自然语言快捷指令",
         "## 效率与范围控制",
         "### 严格控制范围",
         "### 渐进执行和修复",
@@ -191,6 +192,15 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "用户没有明确验收通过前不得关闭",
         "长期文档必须先修改 Wiki",
         "提交只包含当前工单相关文件",
+        "### 自然语言快捷指令",
+        "`只分析`",
+        "`建工单`",
+        "`执行工单 #N`",
+        "`建工单并做`",
+        "`继续工单 #N`",
+        "`检查工单 #N`",
+        "`同步文档`",
+        "`#N 验收通过`",
     )
     for section in missing_sections(content, required):
         errors.append(f"AGENTS.md 缺少：{section}")

docs/01-workflow.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
-wiki_revision: dcef8c85c6c99d4ff2ce4678736092479b505794
-synchronized_at: 2026-08-09T16:28:05Z
+wiki_revision: fff33e44e1ffe39681ff42e4ac05529e973d1cd6
+synchronized_at: 2026-08-09T17:06:33Z
 <!-- gitea-wiki-mirror:end -->
 
 # 开发工作流
@@ -170,6 +170,29 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 - “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
 - 未影响当前验收的相邻问题只提示或建单，不顺手处理。
 
+## 自然语言快捷指令
+
+快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。
+
+| 指令 | 执行动作 | 停止位置 |
+|---|---|---|
+| `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 |
+| `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 |
+| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” |
+| `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
+| `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
+| `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
+| `同步文档` | 读取 Wiki，导出已映射的 `docs/` 镜像并检查一致性 | 显示结果和差异；不修改 Wiki、不自动提交 |
+| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，导出并提交镜像，推送、同步父工单并关闭任务 | 工单“已完成”并关闭 |
+
+补充边界：
+
+- 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。
+- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
+- `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
+- `同步文档` 发现镜像有未提交改动时停止，不覆盖现有修改。
+- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存 Wiki 最终任务归档的镜像。
+
 ## 什么时候重新确认方案
 
 以下变化必须先更新工单，再由用户确认：

docs/task/9-Agent自然语言快捷指令.md

@@ -0,0 +1,92 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-9-Agent自然语言快捷指令
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-9-Agent%E8%87%AA%E7%84%B6%E8%AF%AD%E8%A8%80%E5%BF%AB%E6%8D%B7%E6%8C%87%E4%BB%A4.-
+wiki_revision: c76cdb6317870365bea190c775bfa51451a19025
+synchronized_at: 2026-08-09T17:12:07Z
+<!-- gitea-wiki-mirror:end -->
+
+# 9 Agent 自然语言快捷指令
+
+- 类型：开发流程优化
+- 所属 Epic：无
+- 所属 MVP / 版本：无
+- 状态：待验收
+- 日期：2026-08-10
+- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/9
+- Wiki 页面：Task-9-Agent自然语言快捷指令
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+Agent 过去能够结合上下文理解“建工单，做”，但仓库没有正式定义快捷指令的名称、允许操作和停止位置，不同平台或会话可能产生不同理解。
+
+本任务定义一组共享的自然语言快捷指令，让 Claude Code、Codex 和维护者使用同一套工作流语义，同时保持方案确认、依赖、安全、Wiki 主源和人工验收门禁。
+
+## 最终方案
+
+正式定义以下 8 个快捷指令：
+
+- `只分析`：只读检查并给出方案，停在等待确认。
+- `建工单`：根据已确认方案创建工单，建单后停止。
+- `执行工单 #N`：实施现有工单并完成提交、归档和证据，停在“待验收”。
+- `建工单并做`：依次建单和执行；`建工单，做`、`建工单,做` 是等价表达，停在“待验收”。
+- `继续工单 #N`：从首个未完成步骤继续，不重复仍然有效的检查。
+- `检查工单 #N`：只读核对范围、验收、测试和证据，不自动修复。
+- `同步文档`：Wiki → `docs/` 同步并检查，不修改 Wiki、不自动提交。
+- `#N 验收通过`：仅在用户明确验收后完成验收归档、推送、父工单同步并关闭任务。
+
+补充边界：
+
+- 快捷指令只是自然语言别名，不绕过任何强制规则。
+- 方案未确认时，建单或实施类指令停在方案确认。
+- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
+- 除 `#N 验收通过` 外，不关闭待验收工单。
+- Gitea 工单保留讨论过程，本地只保存 Wiki 最终任务归档镜像。
+- Harness 检查 Wiki 章节和 8 个指令名称。
+- 没有增加脚本、Skill、Slash Command 或自动编排器。
+
+实施结果与已确认方案一致。
+
+## 修改文件
+
+- `AGENTS.md`：增加 8 个共享自然语言快捷指令和强制边界。
+- `dev_scripts/check_harness.py`：检查 Wiki 章节和快捷指令名称。
+- `tests/test_harness_docs.py`：调整 Agent 规则测试名称以覆盖全部必需规则。
+- `docs/01-workflow.md`：Development-Workflow Wiki 的只读镜像。
+- `wiki-docs.json`：登记本任务 Wiki 归档镜像。
+- `docs/task/9-Agent自然语言快捷指令.md`：本页的自动导出镜像。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 8 个指令有明确语义和停止位置 | 通过 |
+| 建工单并做及逗号变体停在待验收 | 通过 |
+| 只有明确验收指令会关闭工单 | 通过 |
+| 只分析和检查工单默认只读 | 通过 |
+| 同步文档不修改 Wiki、不自动提交 | 通过 |
+| 不绕过确认、依赖、安全和验收 | 通过 |
+| 未新增平台专用命令或脚本 | 通过 |
+| Wiki 先更新并确认再导出 | 通过 |
+| Harness、测试和镜像检查 | 通过 |
+| 实现和归档提交分离 | 通过 |
+
+## 测试
+
+- 执行命令：`python -m unittest discover -s tests -v`
+- 结果：20/20 通过。
+- 执行命令：`python dev_scripts/check_harness.py --strict`
+- 结果：通过。
+- 执行命令：`python dev_scripts/sync_wiki_docs.py --check`
+- 结果：归档前 18/18 映射一致；归档后重新检查 19/19。
+- 执行命令：`python -m compileall -q dev_scripts tests`
+- 结果：通过。
+- 执行命令：`git diff --check`
+- 结果：通过。
+- **未验证部分**：没有实现或运行平台专用 Slash Command、Skill 或自动编排器，这些是已确认的非目标。
+
+## 相关提交
+
+- `10e82d6` `feat: 定义 Agent 快捷指令 (#9)`
+- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。

tests/test_harness_docs.py

@@ -77,7 +77,7 @@ class TaskTemplateTests(unittest.TestCase):
 
 
 class AgentRuleTests(unittest.TestCase):
-    def test_agent_efficiency_sections_are_required(self) -> None:
+    def test_required_agent_rules_are_present(self) -> None:
         errors: list[str] = []
         check_agent_efficiency_rules(errors)
         self.assertEqual(errors, [])

wiki-docs.json

@@ -75,6 +75,10 @@
     {
       "page": "Task-8-最小工单依赖规则",
       "path": "docs/task/8-最小工单依赖规则.md"
+    },
+    {
+      "page": "Task-9-Agent自然语言快捷指令",
+      "path": "docs/task/9-Agent自然语言快捷指令.md"
     }
   ]
 }