@twinsearth/dsh-master 3.3.3 → 3.3.4

package/docs/REVIEW-PM-PJM-3.3.4.md

@@ -0,0 +1,153 @@
+# 房主 PM/PJM 智能体：产品盘点与项目计划（3.3.4）
+
+> 产出时间：2026-11-14 · 范围：`E:\GPT\dsh-master`（房主）· 版本：已发布 3.3.3 / 在研 3.3.4-dev
+> 本文件由「房主智能体」的角色契约产出（PM 六类盘点 + PJM 七类项目管理），**只写有证据的结论**。
+
+---
+
+## 第一部分 · 产品经理（PM）
+
+### WHY · 解决什么问题
+
+用户与开发者的需求是口语的，而代码、测试、发布是严格的。中间缺一层**可核对的翻译**：
+
+- 需求含糊时没人先问清楚 → 做完了才发现理解错，返工成本最高；
+- "完成度"靠口头声明 → 设计稿被当成交付，测试没跑也敢说 100%；
+- 冲突与歧义埋在聊天记录里 → 决策反复，前后矛盾没人指出；
+- 项目执行没有 WBS/owner/验收 → 谁做、多久、做成什么样都说不清。
+
+### WHAT · 交付了什么
+
+两个**可被新会话选择的 Agent preset** + 一个共享结构化服务：
+
+| 交付物 | 位置 | 证据 |
+|---|---|---|
+| PM preset `master-pm` + 4 个工具 | `cordis.patch.yml`、`src/agents/pm-agent.ts` | `test/dual-agents.test.mjs`、`test/package-contract.test.mjs` |
+| PJM preset `master-pjm` + 6 个工具 | 同上、`src/agents/pjm-agent.ts` | 同上 |
+| 角色 Prompt（WHY/WHAT/六类；HOW/WHO/WHERE/WHEN/七类） | `src/agents/prompts.ts` | preset 注册断言、Prompt 文本断言 |
+| 结构化契约与门禁 | `src/dual/schema.ts` | 10 条测试 |
+| 文档渲染（PRD/盘点/项目/结案） | `src/dual/documents.ts` | 文档写入测试 |
+| 共享服务（PRD/盘点/计划/进度/结案） | `src/plugins/dual-manager.ts` | `test/dual.test.mjs` + `test/dual-agents.test.mjs` |
+| 智囊团只读面板 | `client.js`、`status().dual` | 面板与状态测试 |
+
+**关键设计**：preset 决定"这个会话是谁"，`ROLE_MATRIX` 决定"子插件在哪个角色装配"，两者都不授予额外权限；
+智能体工具边界写在 preset 里（只读 fs + 提问/待办/交付，**无 shell、无写文件**）。
+
+### 六类盘点（房主范围，逐条带证据）
+
+#### 1. 已完成（进度与证据）
+
+| 项 | 进度 | 证据 |
+|---|---|---|
+| 成本优化系统层 + A/B 模块 + 报表/门禁/里程碑（3.3.0） | 100% | 449→462 测试；§10.2 门禁 G1–G7 全绿；真实 A/B −37.6% |
+| 瓮城回流 contract 1.1.1 + 房主 relay 适配（3.3.1/3.3.2） | 100% | npm `1.1.1`；dsh-Fang 3.1.35 双进程实测 6 条回执、幂等重投通过 |
+| 角色矩阵放开：母体全开 + 分身挂双主管（3.3.3） | 100% | `7e2c132`；7 条测试断言；`test:clean` 449/449 |
+| PM/PJM 双智能体 + 共享服务 + 面板（3.3.4-dev） | 100%（代码） | `666f9bc`、`d1cf443`；`test:clean` 462/462 |
+| 三方发布流水线（tag + Release + npm 各四次） | 100% | `v3.3.0`–`v3.3.3`，资产 sha256 与本地一致 |
+
+#### 2. 未完成（原因与后续）
+
+| 项 | 原因 | 后续 |
+|---|---|---|
+| 3.3.4 发布 | 未获发布授权 | 拿到授权后走同一套门禁 + 三方发布（估 30–45 分钟） |
+| preset 在真实 Host 可选验证 | 守则 §二 禁止向任何 profile 安装 | 需一次**受限安装授权**，装到指定 profile 点选验证 |
+| 面板卡片渲染验证 | 同上，且当前会话面板读的是已安装版本 | 与上一条合并做 |
+| 智能体工具真实会话跑通 | 只有 fake ctx 级测试 | 同上 |
+
+#### 3. 无法实现 / 受阻（卡点）
+
+| 项 | 卡点 | 性质 |
+|---|---|---|
+| 宿主级 co-load / preset 点选 | 守则 §二：禁止把插件装进任何 profile | **策略限制**，非技术问题 |
+| `vm_create/vm_exec` 那 27 个工具 | 房主仓库与本 Host 都不存在该工具面 | 依赖不存在，不是没写 |
+| 房主的三层磁盘架构 / 蓝绿 / 快照回滚 | **那是瓮城 dsh-fang 的实现**，房主没有也不该有 | 跨仓库、跨项目 |
+
+#### 4. 已计划（后续开发计划）
+
+| 项 | 优先级 | 估时 |
+|---|---|---|
+| 3.3.4 三方发布 | P1 | 30–45 分钟 |
+| 受限安装 + preset/面板验证 | P1（依赖授权） | 30 分钟 |
+| PM → PJM 一键交接（PM 结案后生成 PRD 摘要供 PJM 建计划） | P2 | 2–3 小时 |
+| 若确需真 VM：新增 vm-sandbox 适配层 | P3（依赖授权） | 3–5 天 |
+
+#### 5. 相互矛盾 / 冲突（需你重新判断）
+
+| # | 冲突 | 影响 | 我的处理 |
+|---|---|---|---|
+| A | 规格里"已完成：架构设计 100%、权限矩阵、UI 左厂右车、VM 27 工具映射、v3.0.8–v3.0.12" —— 这些是**瓮城**的成果，不是房主的 | 若照抄成房主完成度，就是伪造证据（PM 门禁本身禁止） | 已按房主真实仓库盘点；瓮城成果不计入房主 |
+| B | "Agent = 后台调度官自动接管项目" vs "用户面板呼叫" | 自动接管会绕过用户决策 | 实现为 **preset 由用户选择**，不自动接管 |
+| C | 旧文档"母体不接纳执行体" vs 3.3.3 已放开 | 文档与实现不一致 | 3.3.3 已改文档与测试，按你的选择执行 |
+| D | 交付物要求"27 工具的 VM 沙箱插件" vs 房主只有 `fangForker` | 交付物清单无法满足 | PJM 派发走 `fangForker.spawn`，无 forker 即 fail-closed |
+
+#### 6. 理解歧义（请确认是否理解错）
+
+| # | 歧义 | 当前理解 |
+|---|---|---|
+| A | PM 是否应能改代码/跑测试？ | **不能**：只读 + 文档 + 提问 |
+| B | PJM 要真 VM 隔离，还是 `fangForker` 分身就够？ | 当前按 `fangForker` 实现 |
+| C | PM 结案后是否自动交给 PJM？ | 不自动，人工选择（避免越权） |
+| D | 这次是"发 3.3.4"还是"继续加功能"？ | 代码已就绪，等你决定发布/验证/扩范围 |
+
+---
+
+## 第二部分 · 项目经理（PJM）
+
+### 一、项目会审
+
+- **目标**：3.3.4 可发布、可验证；PM/PJM 在真实 Host 中可选择并可用。
+- **范围**：发布 + 验证（不含 VM/三层架构移植，那属瓮城）。
+- **依赖**：① 发布授权；② 受限安装授权（验证 preset）；③ 若要做 VM 适配，需要范围与授权。
+- **风险**：安装验证会改 profile；发布不可回滚；两者都需要你明确点头。
+
+### 二、项目计划（WBS）
+
+| # | 步骤 | Owner | 场景 | 估时 | 依赖 | 验收 |
+|---|---|---|---|---|---|---|
+| P1 | 3.3.4 版本对齐 + CHANGELOG 收口 | 房主 Agent | 本仓库 | 20 分钟 | 发布授权 | 版本号/标题一致 |
+| P2 | 门禁：check/build/test:clean + gate + milestones | 房主 Agent | 本仓库 | 15 分钟 | P1 | 462/462、G1–G7 全绿 |
+| P3 | 三方发布：tag + Release + npm + 一致性核验 | 房主 Agent | 本仓库/registry | 30 分钟 | P2 | 资产 sha256 一致、latest 正确 |
+| P4 | 受限安装到指定 profile | 房主 Agent | 指定 profile | 10 分钟 | **安装授权** | 插件行激活 |
+| P5 | 点选 `master-pm`/`master-pjm`，确认工具可见 | 房主 Agent | 该 profile 新会话 | 15 分钟 | P4 | 工具清单与文档一致 |
+| P6 | 面板智囊团卡片渲染验证 | 房主 Agent | 该 profile Web | 10 分钟 | P4 | 卡片与计数可见 |
+
+### 三、项目需求与内容
+
+- 发布物：`@twinsearth/dsh-master@3.3.4`，含 `dist-host/agents/*`、`dist-host/dual/*`、`docs/AGENTS-PM-PJM.md`。
+- 验证记录：预设可选择、工具可调用、结案门禁生效、文档写入 workspace。
+- 文档：`docs/AGENTS-PM-PJM.md`（本文件之外的实现说明）。
+
+### 四、项目时间
+
+- P1–P3：约 65 分钟（含 npm 传播等待）。
+- P4–P6：约 35 分钟（依赖安装授权）。
+- 合计：**约 1.5–2 小时**，不含 VM 适配（3–5 天，另议）。
+
+### 五、项目人员
+
+| 角色 | 人 | 职责 |
+|---|---|---|
+| 实现/测试/发布 | 房主 Agent（本会话） | P1–P6 执行与证据 |
+| 决策/授权 | 你 | 发布授权、安装授权、范围变更 |
+| 需求方 | 你 | 验收标准与优先级 |
+
+### 六、测试、部署与交付验收
+
+- **测试**：`npm run check`、`npm run build`、`npm run test:clean`（462/462）、§10.2 门禁、§14 里程碑。
+- **部署**：npm public + GitHub Release；安装需单独授权，且只装指定 profile。
+- **交付**：tarball + `.sha256` + `manifest.json`；`manifest.tagObject` 必须是 annotated tag。
+- **验收**：三方产物 sha256 一致；CI 通过；preset 点选可用（若做 P4–P6）。
+
+### 七、项目结案
+
+- **评审报告**：本文件 + `docs/CHANGELOG.md` 3.3.4 段 + `docs/AGENTS-PM-PJM.md`。
+- **资料汇总**：设计文档、Prompt 源码、测试清单、发布 manifest、验证记录。
+- **结案门禁**：P1–P3 全绿即可结案发布；P4–P6 未做则结案报告必须写明"host 级验证未做"，不得写成已验证。
+
+---
+
+## 需要你做的决定
+
+1. 是否发布 **3.3.4**？
+2. 是否授权把 3.3.4 **装到某个 profile** 做 preset 点选验证（会改动该 profile）？
+3. 规格里的 VM 沙箱 / 三层架构 / 蓝绿升级，是否要**移植进房主**（这属于瓮城能力，需要明确范围）？

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.3.3",
+  "version": "3.3.4",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -37,6 +37,8 @@
     "./contract": "./dist-host/contract/index.js",
     "./cost-optimizer": "./dist-host/plugins/cost-optimizer.js",
     "./dual-manager": "./dist-host/plugins/dual-manager.js",
+    "./pm-agent": "./dist-host/agents/pm-agent.js",
+    "./pjm-agent": "./dist-host/agents/pjm-agent.js",
     "./client": {
       "browser": "./client.js",
       "default": "./client.js"

package/src/agents/pjm-agent.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { PJM_SYSTEM_PROMPT } from './prompts.ts'
+import { dualService, dualUnavailable, id, installAgent, jsonTool, objectSchema, objects, string, strings } from './toolkit.ts'
+
+export const name = 'dsh-master-pjm-agent'
+export const inject = ['systemPrompt', 'tools']
+
+/** PJM preset：项目计划、节点、隔离派发、结案；不替 PM 决定需求。 */
+export function apply(ctx) {
+  const dual = () => dualService(ctx)
+  const tools = [
+    jsonTool('pjm_create_plan', '把已确认 PRD 拆成 WBS 与七类项目计划，返回 plan id；估时必须以分钟给出。', objectSchema({
+      prdId: id('PRD id'), title: string('项目计划标题'), how: string('实施路径'), where: string('执行场景'),
+      projectReview: strings('项目会审结论'), requirements: strings('项目需求与内容'),
+      steps: objects('WBS：id/title/prompt/owner/where/estimateMinutes/dependsOn/acceptance/kind'),
+      schedule: { type: 'object', description: 'startAt 与 milestones[]（title/owner/estimateMinutes/dependsOn）', additionalProperties: true },
+      team: objects('人员：role/owner/responsibility'),
+      quality: { type: 'object', description: 'tests[] / deployment[] / acceptance[]', additionalProperties: true },
+    }, ['prdId', 'steps']), async (args) => dual() ? dual().pjm.plan(args.prdId, args) : dualUnavailable()),
+    jsonTool('pjm_dispatch_step', '通过 fangForker.spawn 在隔离分身中执行一个 WBS 步骤；不可用会 fail-closed，不在宿主本地执行。', objectSchema({
+      planId: id('计划 id'), stepId: id('步骤 id'),
+    }, ['planId', 'stepId']), async (args) => dual() ? await dual().pjm.dispatch(args.planId, { stepId: args.stepId }) : dualUnavailable()),
+    jsonTool('pjm_complete_step', '记录步骤完成/失败、证据与实际用时；不得把失败写成完成。', objectSchema({
+      planId: id('计划 id'), stepId: id('步骤 id'),
+      status: { type: 'string', enum: ['done', 'failed'] }, summary: string('结果摘要'),
+      evidence: strings('测试/文件/报告证据'), actualMinutes: { type: 'number', description: '实际用时（分钟）' },
+    }, ['planId', 'stepId', 'status']), async (args) => dual() ? dual().pjm.completeStep(args.planId, args.stepId, args) : dualUnavailable()),
+    jsonTool('pjm_project_status', '读取项目看板：完成/进行/待办/失败、估时、实际用时、是否可结案。', objectSchema({ planId: id('计划 id') }, ['planId']), async (args) => dual() ? dual().pjm.progress(args.planId) : dualUnavailable()),
+    jsonTool('pjm_write_project', '把项目计划与当前节点写成 workspace/docs/pjm 下的 Markdown。', objectSchema({ planId: id('计划 id') }, ['planId']), async (args, exec) => dual() ? await dual().pjm.writeProject(args.planId, { agent: exec.agent }) : dualUnavailable()),
+    jsonTool('pjm_close_project', '全部步骤完成后结案：写入总结、评审报告、验收与资料清单，并可生成结案文档。', objectSchema({
+      planId: id('计划 id'), summary: string('结案总结（必填）'), reviewReport: string('评审报告'),
+      acceptance: strings('验收记录'), artifacts: strings('项目资料路径'), write: { type: 'boolean', description: '是否同时写结案 Markdown，默认 true' },
+    }, ['planId', 'summary']), async (args, exec) => {
+      if (!dual()) return dualUnavailable()
+      const closed = dual().pjm.close(args.planId, args)
+      if (!closed.ok) return closed
+      if (args.write === false) return closed
+      const document = await dual().pjm.writeClosure(args.planId, { agent: exec.agent })
+      return { ...closed, document }
+    }),
+  ]
+  return installAgent(ctx, { prompt: PJM_SYSTEM_PROMPT, tools })
+}

package/src/agents/pm-agent.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { PM_SYSTEM_PROMPT } from './prompts.ts'
+import { dualService, dualUnavailable, id, installAgent, jsonTool, objectSchema, objects, string, strings } from './toolkit.ts'
+
+export const name = 'dsh-master-pm-agent'
+export const inject = ['systemPrompt', 'tools']
+
+/** PM preset：只提供需求/盘点/文档工具，不提供任何执行或派生能力。 */
+export function apply(ctx) {
+  const dual = () => dualService(ctx)
+  const tools = [
+    jsonTool('pm_create_prd', '创建结构化产品需求文档（WHY/WHAT/模块/约束/验收），返回 PRD id。', objectSchema({
+      title: string('需求标题'), goal: string('要解决的问题与目标'),
+      why: string('背景与价值'), what: strings('功能范围'), architecture: string('架构说明'),
+      outcomes: strings('预期结果'), modules: objects('模块：name/result/architecture/status'),
+      priority: { type: 'string', enum: ['low', 'normal', 'high', 'critical'] },
+      constraints: strings('约束'), acceptance: strings('验收标准'), nonGoals: strings('非目标'),
+      assumptions: strings('假设'), openQuestions: strings('待澄清问题'), requester: string('请求方'),
+    }, ['title', 'goal']), async (args) => dual() ? dual().pm.createPrd(args) : dualUnavailable()),
+    jsonTool('pm_create_assessment', '保存六类产品现状盘点。completed 每项必须附 evidence；其它类给原因、计划、冲突或歧义。', objectSchema({
+      prdId: id('可选：关联的 PRD id'), title: string('盘点标题'), why: string('目标'), what: strings('范围'),
+      completed: objects('已完成：title/progress/evidence[]（证据必填）'),
+      unfinished: objects('未完成：title/reason/nextStep/progress'),
+      blocked: objects('受阻：title/reason/blocker/nextStep'),
+      planned: objects('已计划：title/plan/estimateMinutes/priority'),
+      conflicts: objects('冲突：title/question/options[{value,label,consequence}]'),
+      ambiguities: objects('歧义：title/question/currentInterpretation'),
+    }, ['title']), async (args) => dual() ? dual().pm.createAssessment(args) : dualUnavailable()),
+    jsonTool('pm_write_prd', '把 PRD（可带六类盘点）写成 workspace/docs/pm 下的 Markdown，返回文档路径。', objectSchema({
+      prdId: id('PRD id'), assessmentId: id('可选：关联的 Assessment id'),
+    }, ['prdId']), async (args, exec) => dual() ? await dual().pm.writePrd(args.prdId, { assessmentId: args.assessmentId, agent: exec.agent }) : dualUnavailable()),
+    jsonTool('pm_list_prds', '列出当前 Host 中的 PRD 与六类盘点索引。', objectSchema({}), async () => dual() ? ({ ok: true, prds: dual().pm.listPrds().items, assessments: dual().pm.listAssessments().items }) : dualUnavailable()),
+  ]
+  return installAgent(ctx, { prompt: PM_SYSTEM_PROMPT, tools })
+}

package/src/agents/prompts.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+export const PM_AGENT_ID = 'master-pm'
+export const PJM_AGENT_ID = 'master-pjm'
+
+export const PM_SYSTEM_PROMPT = String.raw`# Role
+你是 DSH-Master「房主」的产品经理 Agent（PM，preset: master-pm）。你把用户和开发者的大白话转换成可核对、可验收的产品需求与文档。
+
+# Goals — WHY / WHAT
+1. WHY：说清解决什么问题、为什么值得做、达成什么目标。
+2. WHAT：说清功能、模块、架构、预期结果、约束、非目标和验收标准。
+3. 对现状做证据驱动的六类盘点：已完成、未完成、无法实现/受阻、已计划、冲突、歧义。
+
+# Workflow
+1. 先识别目标、范围、约束和未决项；重大歧义或不可逆选择必须用 ask_user_question 提出一个具体决策点，给 2–4 个选项并标推荐项。不要为琐碎实现细节打断用户。
+2. 盘点前先用 read/grep/glob 读取真实代码、测试和文档。没有证据的“完成”不得写 100%，不得把设计稿当成已交付。
+3. 用 pm_create_prd 保存结构化 PRD；用 pm_create_assessment 保存六类盘点。每个 completed 项必须附文件、测试或报告证据。
+4. 用 pm_write_prd 生成 Markdown 文档；需要用户打开时用 present 交付。需要 PJM 执行时，只移交 PRD id、验收标准、未决问题，不代替 PJM 派工。
+
+# Rules
+- 不臆测、不伪造证据、不把“可以实现”写成“已经完成”。
+- 冲突必须列出冲突双方、影响、可选方案和需要用户重新判断的问题。
+- 歧义必须写出当前理解与待确认问题；用户未回答前不得把该理解当成事实。
+- PM 不写生产代码、不跑 shell、不发布、不安装、不调度 VM/分身。
+- 只写 PRD/盘点文档；不改需求范围外的文件。
+
+# Output Format
+默认用简洁 Markdown 汇报，必须按任务需要包含：
+- WHY & WHAT
+- 六类现状矩阵：completed / unfinished / blocked / planned / conflicts / ambiguities
+- 冲突与歧义的用户决策点
+- 已保存的 PRD/Assessment id 与文档路径
+只输出已核实内容；未知、未验证、受限分别标明。`
+
+export const PJM_SYSTEM_PROMPT = String.raw`# Role
+你是 DSH-Master「房主」的项目经理 Agent（PJM，preset: master-pjm）。你把已确认的 PRD 变成可执行、可追踪、可验收的项目计划，并按节点汇报直至结案。
+
+# Goals — HOW / WHO / WHERE / WHEN
+1. HOW：把 PRD 拆成 WBS，每步写清 prompt、依赖、验收、估时。
+2. WHO：给每一步分配 owner 与责任；未分配必须写 unassigned，不得虚构人员。
+3. WHERE：明确执行场景（宿主、fork、workspace、DSH Web）；脏任务只能在隔离执行体中运行。
+4. WHEN：给里程碑与估时；估时是计划，不是承诺工期。
+
+# Workflow
+1. 项目会审：核对 PRD、验收标准、约束、未决问题；未决项未解决不得自行扩权。
+2. 用 pjm_create_plan 建立七类项目内容：项目会审、WBS、需求内容、时间、人员、测试部署验收、结案。
+3. 执行前申请隔离资源，通过 pjm_dispatch_step 走 fangForker.spawn；不可用就 fail-closed，绝不在母体/原身本地降级执行，不虚构 vm_create/vm_exec。
+4. 用 pjm_project_status 汇总节点，用 todo_write 跟踪当前工作；完成步骤时记录 summary/evidence/actualMinutes。
+5. 用 pjm_write_project 保存计划与节点报告。全部步骤完成后才能 pjm_close_project；结案必须有总结、验收记录、评审报告和资料清单，并交付文档。
+
+# Rules
+- 按时、按质、按量报告真实状态；失败、阻塞、未测量不得包装成完成。
+- 不发布、不部署到生产、不修改 profile、不触碰凭据，除非用户对该动作另行明确授权。
+- 不代替 PM 决定需求，不替用户回答选择题；阻塞时给出原因、影响、可选方案和所需决策。
+- 不做无限轮询；节点汇报写完成/进行/待办/失败及下一步。
+
+# Output Format
+- 项目会审与范围
+- WBS 看板（Todo / In Progress / Done / Failed）
+- Owner、场景、估时、实际用时与依赖
+- 测试/部署/交付/验收证据
+- 结案：评审报告、验收记录、资料汇总
+- 仍需人类决策的事项（如有）`

package/src/agents/toolkit.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { SERVICE, masterError, safeGet } from '../kernel.ts'
+
+export function dualService(ctx) {
+  const service = safeGet(ctx, SERVICE.dual)
+  return service && service.pm && service.pjm ? service : null
+}
+
+export function dualUnavailable() {
+  return masterError('dual-service-unavailable', 'dshMasterDual is required; enable master-dual-manager in this Host')
+}
+
+/** 注册一个返回结构化 JSON 的模型工具；异常也转成具名错误，不吞掉。 */
+export function jsonTool(name, description, parameters, execute) {
+  return {
+    name,
+    description,
+    parameters,
+    output: {
+      schema: { type: 'object' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    async execute(args, exec) {
+      try { return await execute(args && typeof args === 'object' ? args : {}, exec) }
+      catch (error) { return masterError('agent-tool-threw', String(error?.message ?? error), { tool: name }) }
+    },
+  }
+}
+
+/** 在 preset scope 内挂 persona 与 scoped tools，全部纳入 Cordis effect 生命周期。 */
+export function installAgent(ctx, { prompt, tools }) {
+  const systemPrompt = safeGet(ctx, 'systemPrompt')
+  const registry = safeGet(ctx, 'tools')
+  if (!systemPrompt || typeof systemPrompt.section !== 'function') {
+    return { ok: false, code: 'system-prompt-unavailable', error: 'ctx.systemPrompt with section() is required' }
+  }
+  if (!registry || typeof registry.register !== 'function') {
+    return { ok: false, code: 'tools-unavailable', error: 'ctx.tools with register() is required' }
+  }
+  const registered = []
+  try {
+    ctx.effect(() => systemPrompt.section({ name: 'deployment:persona-prefix', order: 0, text: prompt }))
+  } catch (error) {
+    return { ok: false, code: 'prompt-registration-failed', error: String(error?.message ?? error) }
+  }
+  for (const definition of tools) {
+    try {
+      ctx.effect(() => registry.register(definition))
+      registered.push(definition.name)
+    } catch (error) {
+      return { ok: false, code: 'tool-registration-failed', error: String(error?.message ?? error), tool: definition.name, registered }
+    }
+  }
+  return { ok: true, tools: registered }
+}
+
+export const objectSchema = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: true })
+export const string = (description = '') => ({ type: 'string', description })
+export const strings = (description = '') => ({ type: 'array', items: { type: 'string' }, description })
+export const objects = (description = '') => ({ type: 'array', items: { type: 'object', additionalProperties: true }, description })
+export const id = (description) => ({ type: 'string', description })

package/src/dual/documents.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { ASSESSMENT_CATEGORIES, planProgress } from './schema.ts'
+
+const lines = (items, render) => items.length ? items.map(render).join('\n') : '- （无）'
+const bullets = (items) => lines(items, (item) => `- ${item}`)
+const cell = (value) => String(value ?? '—').replaceAll('|', '\\|').replaceAll('\n', ' ')
+
+const CATEGORY_TITLES = {
+  completed: '1. 已完成（进度与证据）',
+  unfinished: '2. 未完成（原因与后续）',
+  blocked: '3. 无法实现 / 受阻（卡点）',
+  planned: '4. 已计划待开发',
+  conflicts: '5. 相互矛盾 / 冲突（待重新判断）',
+  ambiguities: '6. 理解歧义（待确认）',
+}
+
+export function renderPrdDocument(prd, assessment = null) {
+  return [
+    `# PRD · ${prd.title}`, '',
+    `- 文档 ID：\`${prd.id}\``,
+    `- 状态：${prd.status}`,
+    `- 优先级：${prd.priority}`,
+    `- 请求方：${prd.requester}`, '',
+    '## WHY · 解决什么问题、达成什么目标', '',
+    prd.why || prd.goal, '',
+    `**目标**：${prd.goal}`, '',
+    '## WHAT · 功能、模块、架构与结果', '',
+    bullets(prd.what), '',
+    '### 架构', '', prd.architecture || '（待补充）', '',
+    '### 模块', '',
+    lines(prd.modules, (item) => `- **${item.name}**（${item.status}）：${item.result || item.architecture || '待补充'}`), '',
+    '### 预期结果', '', bullets(prd.outcomes), '',
+    '## 约束与非目标', '',
+    '### 约束', '', bullets(prd.constraints), '',
+    '### 非目标', '', bullets(prd.nonGoals), '',
+    '## 验收标准', '', bullets(prd.acceptance), '',
+    '## 假设与待澄清问题', '',
+    '### 假设', '', bullets(prd.assumptions), '',
+    '### 待澄清', '', bullets(prd.openQuestions), '',
+    assessment ? `\n---\n\n${renderAssessmentDocument(assessment)}` : '',
+  ].join('\n').trim() + '\n'
+}
+
+export function renderAssessmentDocument(assessment) {
+  const out = [`# 产品现状盘点 · ${assessment.title}`, '', `- 盘点 ID：\`${assessment.id}\``, `- 关联 PRD：${assessment.prdId ?? '未关联'}`, '']
+  if (assessment.why) out.push('## WHY', '', assessment.why, '')
+  if (assessment.what.length) out.push('## WHAT', '', bullets(assessment.what), '')
+  for (const category of ASSESSMENT_CATEGORIES) {
+    out.push(`## ${CATEGORY_TITLES[category]}`, '')
+    const items = assessment[category]
+    out.push(lines(items, (item) => {
+      if (category === 'completed') return `- **${item.title}**（${item.progress}%）${item.detail ? `：${item.detail}` : ''}\n  - 证据：${item.evidence.join('；')}`
+      if (category === 'unfinished') return `- **${item.title}**：${item.reason}\n  - 后续：${item.nextStep || '待计划'}`
+      if (category === 'blocked') return `- **${item.title}**：${item.reason}\n  - 卡点：${item.blocker}\n  - 下一步：${item.nextStep || '待决策'}`
+      if (category === 'planned') return `- **${item.title}**（${item.priority}）：${item.plan || '待拆解'}${item.estimateMinutes ? `\n  - 估时：${item.estimateMinutes} 分钟` : ''}`
+      if (category === 'conflicts') return `- **${item.title}**：${item.question}\n  - 选项：${item.options.map((option) => `${option.value}=${option.label}`).join('；') || '待补充'}`
+      return `- **${item.title}**：${item.question}\n  - 当前理解：${item.currentInterpretation || '未形成结论'}`
+    }), '')
+  }
+  return out.join('\n').trim() + '\n'
+}
+
+export function renderProjectDocument(plan) {
+  const progress = planProgress(plan)
+  return [
+    `# 项目计划 · ${plan.title}`, '',
+    `- 计划 ID：\`${plan.id}\``,
+    `- 关联 PRD：\`${plan.prdId}\``,
+    `- 状态：${plan.status}`,
+    `- 进度：${progress.done}/${progress.total}（${progress.percent}%）`,
+    `- 总估时：${progress.estimatedMinutes} 分钟（估算，不是承诺工期）`, '',
+    '## 1. 项目会审', '', bullets(plan.projectReview), '',
+    '## 2. 项目计划（HOW / WHERE）', '', plan.how || '（待补充）', '', `**场景**：${plan.where}`, '',
+    '### WBS', '',
+    '| 步骤 | 内容 | Owner | 场景 | 估时(分钟) | 依赖 | 状态 |',
+    '|---|---|---|---|---:|---|---|',
+    ...plan.steps.map((step) => `| ${cell(step.id)} | ${cell(step.title)} | ${cell(step.owner)} | ${cell(step.where)} | ${step.estimateMinutes} | ${cell(step.dependsOn.join(', '))} | ${cell(step.status)} |`), '',
+    '## 3. 项目需求与内容', '', bullets(plan.requirements), '',
+    '## 4. 项目时间', '',
+    `- 开始时间：${plan.schedule.startAt ?? '待定'}`,
+    `- 总估时：${plan.schedule.totalEstimateMinutes} 分钟`, '',
+    lines(plan.schedule.milestones, (item) => `- **${item.title}**：${item.estimateMinutes} 分钟 · ${item.owner} · 依赖 ${item.dependsOn.join(', ') || '无'}`), '',
+    '## 5. 项目人员', '',
+    lines(plan.team, (item) => `- **${item.role}** · ${item.owner}：${item.responsibility || '待分配'}`), '',
+    '## 6. 测试、部署、交付与验收', '',
+    '### 测试', '', bullets(plan.quality.tests), '',
+    '### 部署', '', bullets(plan.quality.deployment), '',
+    '### 验收', '', bullets(plan.quality.acceptance), '',
+    '## 7. 项目结案', '',
+    plan.closure.status === 'closed' ? renderClosureDocument(plan) : '- 尚未结案；必须全部步骤完成后才能结案。',
+  ].join('\n').trim() + '\n'
+}
+
+export function renderClosureDocument(plan) {
+  const closure = plan.closure
+  return [
+    `### 结案状态：${closure.status}`, '',
+    `- 结案时间：${closure.closedAt ?? '未结案'}`,
+    `- 总结：${closure.summary || '未填写'}`, '',
+    '#### 评审报告', '', closure.reviewReport || '（待补充）', '',
+    '#### 验收记录', '', bullets(closure.acceptance), '',
+    '#### 项目资料汇总', '', bullets(closure.artifacts), '',
+  ].join('\n')
+}