dsh-gate-agent 0.1.3 → 0.1.5

package/README.md

@@ -72,8 +72,8 @@ Host 插件：用 phase/node 门禁组织讨论、规划、实施、评审、验
 | `reviewing/code-review-standalone` | 单独只读 code review | review worker；`gate-code-review` |
 | `reviewing/proposal-review` | 单独提案评审 | review worker；`gate-plan-review` |
 | `reviewing/verify-standalone` | 单独只读验收 | verify worker；`gate-user-verify` |
-| `docs` | 文档治理 | root；不调用 gate 技能 |
-| `blocked` | 冻结写入/派 worker，等待用户决定 | root；`/gate-resume` 或 `/gate-return-discuss` |
+| `docs` | 文档治理 | root；按项目文档规范处理 |
+| `blocked` | 冻结写入/派 worker，等待用户决定 | root；`/gate-resume` |
 | `complete` | 工作完成 | root；可重新进入 plan/implement |
 
 进入阶段不等于执行。主代理按当前 procedure 加载技能、派 worker，再用 `gate_record` 推进节点。
@@ -109,23 +109,24 @@ Host 插件：用 phase/node 门禁组织讨论、规划、实施、评审、验
 | 命令 | 参数 | 作用 |
 |---|---|---|
 | `/gate-init` | 无 | 初始化 notes、AGENTS.md、`verify-notes`、CI、git 与基础 `.gitignore`，保持 `discuss` |
-| `/gate-enter-plan [简单需求]` | 可选 | 进入 `orchestrating/plan` |
-| `/gate-enter-implement [简单说明]` | 可选 | 进入 `orchestrating/implement`；复用已通过的 task，或直接用简述 |
-| `/gate-docs` | 无 | 文档治理，不调用技能 |
-| `/gate-implement-review [范围]` | 可选 | 单独只读 code review，只输出 findings |
-| `/gate-code-verify [范围]` | 可选 | 单独只读验收；子代理使用 `gate-user-verify` |
-| `/gate-fix-bug [缺陷简述]` | 可选 | 派 fix worker 修复已授权缺陷，完成后回 discuss |
-| `/gate-propose-review [提案]` | 可选 | 单独提案评审，走 `gate-plan-review` 三轴 |
+| `/gate-enter-plan [具体工作事项或上下文语义]` | 可选 | 基于讨论共识、既有决策与用户输入进入 `orchestrating/plan` |
+| `/gate-enter-implement [具体工作事项或上下文语义]` | 可选 | 基于已确认计划或讨论后的实施说明进入 `orchestrating/implement` |
+| `/gate-prd [主题或上下文语义]` | 可选 | 用户级创建/更新 PRD；仅 discuss |
+| `/gate-docs [文档范围或上下文语义]` | 可选 | 进入文档治理，按项目文档规范处理 |
+| `/gate-implement-review [具体工作事项或上下文语义]` | 可选 | 对当前改动做独立只读 code review，只输出 findings |
+| `/gate-code-verify [具体工作事项或上下文语义]` | 可选 | 对当前改动做独立只读验收（gate-user-verify） |
+| `/gate-fix-bug [具体工作事项或上下文语义]` | 可选 | 基于描述或当前上下文派 fix worker 修复已授权缺陷 |
+| `/gate-propose-review [具体工作事项或上下文语义]` | 可选 | 对提案做独立只读三轴评审 |
 | `/gate-note-verify` | 无 | 只读检查 notes tree/format/lifecycle/archived |
 | `/gate-note-archive <note> [--superseded-by <new>]` | 必需 Note 路径 | 归档 implemented Note，写 Archived、移动、封印、报告入站链接 |
 | `/gate-note-board [输出路径] [标题]` | 可选 | 生成决策看板 `board.html` |
 | `/gate-note-seal` | 无 | 只给 `archived/` 中已有 Note 补写 `manifest.json` 的 SHA-256 封印 |
 | `/gate-block [原因]` | 可选 | 手动暂停，保留当前节点 |
 | `/gate-resume` | 无 | 解冻 blocked，回到 block 前的节点；轮次耗尽回 discuss |
-| `/gate-return-discuss` | 无 | 回到 discuss |
-| `/gate-status` | 无 | 只读显示当前 phase/node 与 procedure |
+| `/gate-return-discuss` | 无 | 放弃当前节点，回到 discuss |
+| `/gate-status` | 无 | 只读显示当前 phase/node、procedure、access 与下一步命令 |
 
-直接 implement（`/gate-enter-implement [简单说明]` 或 `gate_start_phase({node:'implement',brief})`）会自动标记 `mechanical`，跳过 Note lifecycle；不需要 `mechanical:` 前缀。plan/plan-revise 手动选择 `mechanical` 时也不要求前缀，只需 `notePaths: []`。
+直接 implement（`/gate-enter-implement [具体工作事项或上下文语义]` 或 `gate_start_phase({node:'implement',brief})`）会自动标记 `mechanical`，跳过 Note lifecycle；不需要 `mechanical:` 前缀。plan/plan-revise 手动选择 `mechanical` 时也不要求前缀，只需 `notePaths: []`。
 
 离开 discuss 的授权可来自对话（包括要求用户再输入 slash command）或 `ask_user_question`；明确授权后，主代理可调用 `gate_start_phase({node:'plan'|'implement', brief})`。
 
@@ -190,7 +191,7 @@ gate 不自动 `git add`/`git commit`；完成 note-lifecycle 后由用户或主
 ### 单独 code review
 
 ```text
-/gate-implement-review [范围]
+/gate-implement-review [具体工作事项或上下文语义]
 ```
 
 只读 review，不修改被评审对象；findings 直接输出。
@@ -198,7 +199,7 @@ gate 不自动 `git add`/`git commit`；完成 note-lifecycle 后由用户或主
 ### 单独验收
 
 ```text
-/gate-code-verify [范围]
+/gate-code-verify [具体工作事项或上下文语义]
 ```
 
 主代理派只读 verify worker，使用 `gate-user-verify`；PASS 后 `gate_record({node:'verify-standalone', verification, workerSessionIds})` 回 discuss。
@@ -245,24 +246,27 @@ review worker 使用 `gate-plan-review` 做 Standards/Spec/Architecture 三轴
 /gate-docs
 ```
 
-进入 `docs` phase，不调用 gate 技能；由主代理按项目文档规范处理。
+进入 `docs` phase，由主代理按项目文档规范处理。
 
 ### 暂停、恢复与讨论
 
 ```text
 /gate-block 等待产品决定
 /gate-resume
-/gate-return-discuss
 /gate-status
 ```
 
 - `/gate-block`：保留当前节点，冻结写入与 worker 派发，对话仍可继续。
-- `/gate-resume`：回到 block 前的节点；review 轮次耗尽时回 discuss。
-- `/gate-return-discuss`：放弃当前节点，回 discuss。
+- `/gate-resume`：唯一的 blocked 恢复入口；回到 block 前的节点，review 轮次耗尽时回 discuss。
+- `/gate-return-discuss`：放弃当前节点回 discuss；blocked 时不可直接用，先 `/gate-resume`。
 - `/gate-status`：只读查看当前 phase/node 和 procedure。
 
 ## 工具
 
+### gate_help
+
+只读，root-only。列出全部 `/gate-*` 命令、`gate_*` 工具用途和当前 phase/node，并说明命令由用户执行、工具由模型调用。不确定命令名或工具用途时使用。
+
 ### gate_start_phase
 
 只允许 root 调用，在用户已授权时从 `discuss`/`complete` 进入 `plan` 或 `implement`：
@@ -297,12 +301,20 @@ gate_record({
 
 ### gate_status
 
-只读，root 和 worker 可调用。root 返回当前 procedure 与状态；worker 只返回状态，不返回 root procedure。
+只读，root 和 worker 可调用。root 返回当前 procedure、状态和 nextCommands；worker 只返回状态，不返回 root procedure。
 
 ```text
 gate_status()
 ```
 
+### gate_artifact_write
+
+按 `.agents/gate/artifact-policy.json` 写白名单 artifact；只写文件，不走普通 workspace write。支持精确文件、目录和 glob。
+
+### gate_research_dispatch
+
+root-only；在 discuss 或 `orchestrating/plan` 派 research worker。worker 只能通过 artifact policy 写 research 文档，不获得通用 workspace 写。
+
 ### Note 工具
 
 - `gate_note_write`：planning worker 写 proposed Note，或原地更新 implemented Note；通用 `write`/`edit`/`apply_patch` 和仓库写被拒绝，只读 shell 可用。
@@ -331,7 +343,183 @@ gate_status()
 
 ## 配置
 
-插件 Config：
+### artifact-policy.json
+
+discuss 和 plan 默认不允许普通文件写。`handoff`、PRD、research 等产物通过**独立的 artifact 白名单**写入，而不是放开通用 `write`。
+
+`/gate-init` 会创建：
+
+```text
+.agents/gate/artifact-policy.json
+```
+
+- 文件不存在时写入基础配置；
+- 文件已存在时**不覆盖**，保留用户内容；
+- 新建 `.gitignore` 时包含 `.scratch/`；已有 `.gitignore` 不重写。
+
+#### 基础配置
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "handoff": {
+      "phases": ["*"],
+      "roles": ["root"],
+      "paths": [".scratch/handoff/**"]
+    },
+    "prd": {
+      "phases": ["discuss"],
+      "roles": ["root"],
+      "paths": ["docs/prd/**", ".scratch/prd/**"]
+    },
+    "research": {
+      "phases": ["discuss", "orchestrating/plan"],
+      "roles": ["root", "worker"],
+      "paths": ["docs/research/**", ".scratch/research/**"]
+    }
+  }
+}
+```
+
+#### 字段
+
+| 字段 | 说明 |
+|---|---|
+| `version` | 必须为 `1` |
+| `artifacts` | artifact kind 到规则的映射 |
+| `kind` | 内置 `handoff`、`prd`、`research`；也可以增加自定义 kind |
+| `phases` | 允许的 canonical phase/node key，或 `*` |
+| `roles` | `root` 或 `worker` |
+| `paths` | 相对 workspace 的文件、目录或 glob |
+
+#### phases
+
+使用 `gate_status` 返回的 `methodologyKey` 形式：
+
+- `discuss`
+- `docs`
+- `complete`
+- `orchestrating/plan`
+- `orchestrating/plan-review`
+- `orchestrating/plan-revise`
+- `orchestrating/implement`
+- `orchestrating/code-review`
+- `orchestrating/implement-revise`
+- `orchestrating/verify`
+- `orchestrating/note-lifecycle`
+- `orchestrating/fix-bug`
+- `reviewing/code-review-standalone`
+- `reviewing/proposal-review`
+- `reviewing/verify-standalone`
+
+`*` 表示任意**非 blocked** 状态。`blocked` 始终拒绝，即使规则写了 `*`。
+
+#### roles
+
+- `root`：主代理；
+- `worker`：任何 gate worker，包括 planning worker 和 research worker。
+
+#### paths
+
+支持四种形式：
+
+```json
+"paths": [
+  "docs/prd/current.md",
+  "docs/prd/PRD-*.md",
+  ".scratch/research/**/*.md",
+  ".scratch/handoff/**"
+]
+```
+
+| 形式 | 含义 |
+|---|---|
+| `docs/prd/current.md` | 只允许这个文件 |
+| `docs/prd/*.md` | 只允许该目录下直接文件，不递归 |
+| `.scratch/research/**/*.md` | 递归匹配 Markdown |
+| `.scratch/handoff/**` | 允许该目录下任意层级文件 |
+| `docs/prd/**` | 允许该目录下任意层级文件 |
+
+规则：
+
+- `*` 只匹配一个路径段；
+- `**` 匹配零个或多个路径段；
+- 普通路径没有通配符时按**明确文件**处理；
+- 不允许绝对路径、`..`、workspace 外路径、symlink；
+- 保留路径永远拒绝：
+  - `.agents/gate/artifact-policy.json`
+  - `.agents/notes/**`
+- 只写文件；父目录可以由工具创建，但也要通过边界检查。
+
+#### 如何按项目填写
+
+只允许一个固定 PRD 文件：
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "prd": {
+      "phases": ["discuss"],
+      "roles": ["root"],
+      "paths": ["docs/prd/current.md"]
+    }
+  }
+}
+```
+
+允许按命名规则新建多个 PRD：
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "prd": {
+      "phases": ["discuss"],
+      "roles": ["root"],
+      "paths": ["docs/prd/PRD-*.md"]
+    }
+  }
+}
+```
+
+允许 research 在 discuss 和 plan 写文档目录：
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "research": {
+      "phases": ["discuss", "orchestrating/plan"],
+      "roles": ["root", "worker"],
+      "paths": ["docs/research/**/*.md", ".scratch/research/**"]
+    }
+  }
+}
+```
+
+#### 相关工具与命令
+
+- `gate_artifact_write({ kind, path, content })`：root/worker 按 policy 写文件；
+- `gate_research_dispatch({ question, purpose? })`：root-only，在 discuss/plan 派 research worker；
+- `/gate-prd [主题]`：discuss 用户命令，加载 `gate-prd` skill 并通过 artifact policy 写 PRD；
+- `gate-handoff`：用户级 skill，产物写入 `.scratch/handoff/`。
+
+普通 `write`/`edit`/`apply_patch`/写型 shell 不受 artifact policy 放行，仍按 phase/role 矩阵处理。
+
+#### 常见失败
+
+| 错误 | 原因 |
+|---|---|
+| `artifact-policy-invalid` | policy 缺失、JSON 无效、version 不是 1、字段非法 |
+| `artifact-denied` | kind 不存在、phase 不匹配、role 不匹配、path 不在白名单、blocked、保留路径、越界或 symlink |
+| `subagents-unavailable` | research dispatch 时 `ctx.subagents` 不可用 |
+| `wrong-phase` | research dispatch 不在 discuss 或 `orchestrating/plan` |
+
+修改 policy 后不需要重启 DSH；每次 artifact 写入都会重新读取文件。
+
+### 插件 Config
 
 ```json
 { "reviewLimit": 5 }
@@ -339,6 +527,7 @@ gate_status()
 
 `reviewLimit` 是每个 review 节点的最大轮次；默认 5，范围 1–20。达到上限仍有 findings 时进入 blocked。
 
+
 ## 使用边界
 
 - gate 是流程门禁，不是 OS 安全边界；未知工具和任意 shell 语义不会被完整分析。