@twinsearth/dsh-master 3.3.2 → 3.3.4

package/src/plugins/dual-manager.ts

@@ -3,19 +3,26 @@
 // @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
 
 /**
- * 子插件 3：双主管（PM + PJM）。
+ * 双智能体共享服务（PM + PJM）。
  *
- * 定位：运行在母体/元主内的元 Agent；PM 把模糊需求变成结构化 PRD，PJM 把 PRD
- * 拆成步骤并通过瓮城的 fangForker 调度分身执行。本子插件不直接运行生产任务：
- *   * 没有 fangForker.spawn 时 dispatch fail-closed；
- *   * 歧义澄清复用瓮城决策中心（fangDecisionCenter），不另造一套审批；
- *   * 角色：只允许 mother / essence（分身里没有“管理层”）。
+ * `master-pm` / `master-pjm` 是两个独立的 DSH Agent preset；本服务保存它们协作的
+ * 结构化 PRD、六类盘点、WBS、节点与结案状态，并负责文档落盘。
+ *
+ * 边界：
+ *   * PM 只做需求与证据盘点，不执行代码、不派发分身；
+ *   * PJM 只做计划、隔离派发、进度与结案，不替用户决定需求；
+ *   * 没有 fangForker.spawn 时 dispatch fail-closed，绝不在宿主本地降级执行；
+ *   * 歧义澄清复用瓮城决策中心，不另造一套审批；
+ *   * 文档只写当前 Session workspace 下的 docs/pm 或 docs/pjm，不接受任意路径。
  */
 
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
 import {
   FANG_SERVICE,
+  MASTER_VERSION,
   ROW,
-  ROLE,
   SERVICE,
   createIdFactory,
   detectRole,
@@ -24,34 +31,26 @@ import {
   roleAllowed,
   safeGet,
 } from '../kernel.ts'
+import { closePlan, normalizeAssessment, normalizePlan, normalizePrd, planProgress } from '../dual/schema.ts'
+import { renderAssessmentDocument, renderClosureDocument, renderPrdDocument, renderProjectDocument } from '../dual/documents.ts'
 
 export const name = 'dsh-master-dual-manager'
 export const inject = ['dshMaster']
 export const ROW_ID = ROW.dual
 
-const PRIORITIES = Object.freeze(['low', 'normal', 'high', 'critical'])
-const DEFAULT_STEP_KIND = 'development'
-
-function stringList(value) {
-  if (!Array.isArray(value)) return []
-  return value.map((item) => String(item ?? '').trim()).filter(Boolean)
-}
-
 function missing(name) {
   return masterError(`${name}-required`, `${name} is required`)
 }
 
 /**
  * @param {object} ctx
- * @param {{enabled?:boolean}} [config]
+ * @param {{enabled?:boolean, dispatch?:object}} [config]
  */
 export function apply(ctx, config = {}) {
   if (!enabledOf(config)) return { skipped: true, reason: 'disabled-by-config' }
   const role = detectRole()
   if (!roleAllowed(ROW_ID, role)) {
-    try {
-      ctx?.logger?.info?.(`[dsh-master] dual-manager skipped: role=${role} not in mother/essence`)
-    } catch { /* ignore */ }
+    try { ctx?.logger?.info?.(`[dsh-master] dual-manager skipped: role=${role}`) } catch { /* ignore */ }
     return { skipped: true, reason: `role-not-allowed:${role}` }
   }
   const master = safeGet(ctx, SERVICE.master)
@@ -60,8 +59,10 @@ export function apply(ctx, config = {}) {
   }
 
   const newPrdId = createIdFactory('prd')
+  const newAssessmentId = createIdFactory('review')
   const newPlanId = createIdFactory('plan')
   const prds = new Map()
+  const assessments = new Map()
   const plans = new Map()
 
   const decisionCenter = () => safeGet(ctx, FANG_SERVICE.decisionCenter)
@@ -70,27 +71,35 @@ export function apply(ctx, config = {}) {
     return service && typeof service.spawn === 'function' ? service : null
   }
 
+  /** 文档写口：只接受代码内生成的相对路径，根目录来自当前 Session。 */
+  async function writeWorkspaceDocument(agent, relativePath, content) {
+    const workingDirectory = safeGet(ctx, 'workingDirectory')
+    if (!workingDirectory) return masterError('working-directory-unavailable', 'workingDirectory service is required to write agent documents')
+    try {
+      const root = agent && typeof workingDirectory.ensure === 'function'
+        ? await workingDirectory.ensure(agent)
+        : String(workingDirectory.defaultDirectory ?? '')
+      if (!root) return masterError('working-directory-unavailable', 'no active Session workspace')
+      const base = path.resolve(String(root))
+      const target = path.resolve(base, relativePath)
+      if (target !== base && !target.startsWith(`${base}${path.sep}`)) {
+        return masterError('document-path-outside-workspace', 'document path must stay inside the Session workspace')
+      }
+      await fs.mkdir(path.dirname(target), { recursive: true })
+      await fs.writeFile(target, String(content), 'utf8')
+      return { ok: true, path: target, bytes: Buffer.byteLength(String(content), 'utf8') }
+    } catch (error) {
+      return masterError('document-write-failed', String(error?.message ?? error))
+    }
+  }
+
   const pm = {
-    /** 需求 → 结构化 PRD（不调用模型；3.2.x 接入 PM agent 后由模型填充字段）。 */
+    /** 需求 → 结构化 PRD（模型通过 pm-agent 工具填充；服务本身不调用模型）。 */
     createPrd(input = {}) {
-      const title = String(input.title ?? '').trim()
-      const goal = String(input.goal ?? '').trim()
-      if (!title) return missing('title')
-      if (!goal) return missing('goal')
-      const priority = PRIORITIES.includes(String(input.priority ?? 'normal')) ? String(input.priority ?? 'normal') : 'normal'
-      const prd = Object.freeze({
-        id: newPrdId(),
-        title,
-        goal,
-        priority,
-        constraints: Object.freeze(stringList(input.constraints)),
-        acceptance: Object.freeze(stringList(input.acceptance)),
-        requester: String(input.requester ?? 'user'),
-        status: 'draft',
-        createdAt: Date.now(),
-      })
-      prds.set(prd.id, prd)
-      return { ok: true, prd }
+      const made = normalizePrd(input, { id: newPrdId() })
+      if (!made.ok) return made
+      prds.set(made.prd.id, made.prd)
+      return made
     },
     getPrd(id) {
       const prd = prds.get(String(id ?? ''))
@@ -99,6 +108,39 @@ export function apply(ctx, config = {}) {
     listPrds() {
       return { ok: true, items: [...prds.values()] }
     },
+    /** 六类现状盘点；completed 必须由调用方给出可复核证据。 */
+    createAssessment(input = {}) {
+      const prdId = String(input.prdId ?? '').trim()
+      if (prdId && !prds.has(prdId)) return masterError('prd-not-found', 'PRD not found', { id: prdId })
+      const made = normalizeAssessment(input, { id: newAssessmentId() })
+      if (!made.ok) return made
+      assessments.set(made.assessment.id, made.assessment)
+      return made
+    },
+    getAssessment(id) {
+      const assessment = assessments.get(String(id ?? ''))
+      return assessment ? { ok: true, assessment } : masterError('assessment-not-found', 'Assessment not found', { id: String(id ?? '') })
+    },
+    listAssessments() {
+      return { ok: true, items: [...assessments.values()] }
+    },
+    renderPrd(id, { assessmentId = '' } = {}) {
+      const prd = prds.get(String(id ?? ''))
+      if (!prd) return masterError('prd-not-found', 'PRD not found', { id: String(id ?? '') })
+      const assessment = assessmentId ? assessments.get(String(assessmentId)) : null
+      if (assessmentId && !assessment) return masterError('assessment-not-found', 'Assessment not found', { id: String(assessmentId) })
+      return { ok: true, markdown: renderPrdDocument(prd, assessment) }
+    },
+    async writePrd(id, { assessmentId = '', agent } = {}) {
+      const rendered = pm.renderPrd(id, { assessmentId })
+      if (!rendered.ok) return rendered
+      return await writeWorkspaceDocument(agent, path.join('docs', 'pm', `PRD-${id}.md`), rendered.markdown)
+    },
+    async writeAssessment(id, { agent } = {}) {
+      const assessment = assessments.get(String(id ?? ''))
+      if (!assessment) return masterError('assessment-not-found', 'Assessment not found', { id: String(id ?? '') })
+      return await writeWorkspaceDocument(agent, path.join('docs', 'pm', `REVIEW-${id}.md`), renderAssessmentDocument(assessment))
+    },
     /** 歧义澄清：复用瓮城决策中心，返回 ticket 或明确的 unavailable。 */
     async askUser({ question, context = '', options = [], level = 'yellow' } = {}) {
       const q = String(question ?? '').trim()
@@ -124,54 +166,38 @@ export function apply(ctx, config = {}) {
   }
 
   const pjm = {
-    /** PRD → 可调度步骤计划。 */
-    plan(prdId, { steps = [] } = {}) {
+    /** PRD → 七类项目计划与可调度 WBS。 */
+    plan(prdId, input = {}) {
       const prd = prds.get(String(prdId ?? ''))
       if (!prd) return masterError('prd-not-found', 'PRD not found', { id: String(prdId ?? '') })
-      if (!Array.isArray(steps) || steps.length === 0) return missing('steps')
-      const normalized = []
-      for (const [index, step] of steps.entries()) {
-        const title = String(step?.title ?? '').trim()
-        const prompt = String(step?.prompt ?? '').trim()
-        if (!title) return missing(`steps[${index}].title`)
-        if (!prompt) return missing(`steps[${index}].prompt`)
-        normalized.push({
-          id: String(step?.id ?? `step-${index + 1}`),
-          title,
-          prompt,
-          kind: String(step?.kind ?? DEFAULT_STEP_KIND),
-          status: 'pending',
-          fork: null,
-        })
-      }
-      const plan = {
-        id: newPlanId(),
-        prdId: prd.id,
-        status: 'planned',
-        steps: normalized,
-        createdAt: Date.now(),
-      }
-      plans.set(plan.id, plan)
-      return { ok: true, plan }
+      const made = normalizePlan(prd, input, { id: newPlanId() })
+      if (!made.ok) return made
+      plans.set(made.plan.id, made.plan)
+      return made
     },
     getPlan(id) {
       const plan = plans.get(String(id ?? ''))
       return plan ? { ok: true, plan } : masterError('plan-not-found', 'Plan not found', { id: String(id ?? '') })
     },
+    progress(id) {
+      const plan = plans.get(String(id ?? ''))
+      if (!plan) return masterError('plan-not-found', 'Plan not found', { id: String(id ?? '') })
+      return { ok: true, planId: plan.id, status: plan.status, progress: planProgress(plan), steps: plan.steps }
+    },
     /** 调瓮城 fangForker.spawn 派生执行分身；无 forker 时 fail-closed。 */
     async dispatch(planId, { stepId } = {}) {
       const plan = plans.get(String(planId ?? ''))
       if (!plan) return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') })
+      if (plan.status === 'closed') return masterError('plan-already-closed', 'Closed plans cannot dispatch new steps')
       const step = plan.steps.find((item) => item.id === String(stepId ?? ''))
       if (!step) return masterError('step-not-found', 'Step not found', { id: String(stepId ?? '') })
       if (step.fork) return masterError('step-already-dispatched', 'Step already dispatched', { stepId: step.id, fork: step.fork })
       const fangForker = forker()
-      if (!fangForker) {
-        return masterError('fang-forker-unavailable', 'dsh-fang fangForker.spawn is required to dispatch a step')
-      }
+      if (!fangForker) return masterError('fang-forker-unavailable', 'dsh-fang fangForker.spawn is required to dispatch a step')
       // 先占位再 await，避免两个并发 dispatch 同时看到 step.fork=null 而重复派生。
       step.status = 'dispatching'
       step.fork = { pending: true }
+      plan.updatedAt = Date.now()
       try {
         const spawnConfig = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {}
         const fork = await fangForker.spawn({
@@ -194,26 +220,54 @@ export function apply(ctx, config = {}) {
         step.status = 'running'
         step.fork = fork ?? null
         plan.status = 'running'
+        plan.updatedAt = Date.now()
         return { ok: true, planId: plan.id, stepId: step.id, step, fork }
       } catch (error) {
         step.status = 'pending'; step.fork = null
         return masterError('fang-spawn-threw', String(error?.message ?? error))
       }
     },
-    completeStep(planId, stepId, { status = 'done', summary = '' } = {}) {
+    completeStep(planId, stepId, { status = 'done', summary = '', evidence = [], actualMinutes = null } = {}) {
       const plan = plans.get(String(planId ?? ''))
       if (!plan) return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') })
+      if (plan.status === 'closed') return masterError('plan-already-closed', 'Closed plans cannot be modified')
       const step = plan.steps.find((item) => item.id === String(stepId ?? ''))
       if (!step) return masterError('step-not-found', 'Step not found', { id: String(stepId ?? '') })
-      const next = status === 'failed' ? 'failed' : 'done'
-      step.status = next
+      step.status = status === 'failed' ? 'failed' : 'done'
       step.summary = String(summary)
+      step.evidence = Array.isArray(evidence) ? evidence.map(String).filter(Boolean) : []
+      const minutes = Number(actualMinutes)
+      step.actualMinutes = Number.isFinite(minutes) && minutes >= 0 ? minutes : null
       const states = plan.steps.map((item) => item.status)
       plan.status = states.every((state) => state === 'done')
         ? 'done'
-        : (states.some((state) => state === 'running') ? 'running' : 'planned')
+        : (states.some((state) => state === 'running' || state === 'dispatching') ? 'running' : 'planned')
+      plan.updatedAt = Date.now()
       return { ok: true, plan }
     },
+    close(planId, input = {}) {
+      const plan = plans.get(String(planId ?? ''))
+      if (!plan) return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') })
+      if (plan.status === 'closed') return masterError('plan-already-closed', 'Plan is already closed')
+      return closePlan(plan, input)
+    },
+    renderProject(planId) {
+      const plan = plans.get(String(planId ?? ''))
+      if (!plan) return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') })
+      return { ok: true, markdown: renderProjectDocument(plan) }
+    },
+    async writeProject(planId, { agent } = {}) {
+      const rendered = pjm.renderProject(planId)
+      if (!rendered.ok) return rendered
+      return await writeWorkspaceDocument(agent, path.join('docs', 'pjm', `PROJECT-${planId}.md`), rendered.markdown)
+    },
+    async writeClosure(planId, { agent } = {}) {
+      const plan = plans.get(String(planId ?? ''))
+      if (!plan) return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') })
+      if (plan.closure.status !== 'closed') return masterError('plan-not-closed', 'Project must be closed before writing its closure report')
+      const markdown = `# 项目结案 · ${plan.title}\n\n- 计划 ID：\`${plan.id}\`\n- 关联 PRD：\`${plan.prdId}\`\n\n${renderClosureDocument(plan)}\n`
+      return await writeWorkspaceDocument(agent, path.join('docs', 'pjm', `CLOSURE-${planId}.md`), markdown)
+    },
     listPlans() {
       return { ok: true, items: [...plans.values()] }
     },
@@ -221,18 +275,20 @@ export function apply(ctx, config = {}) {
 
   const service = {
     id: SERVICE.dual,
-    version: '3.2.5',
+    version: MASTER_VERSION,
     role,
     pm,
     pjm,
+    agents: Object.freeze({ pm: 'master-pm', pjm: 'master-pjm' }),
     status() {
       return {
         ok: true,
         id: 'dual-manager',
-        version: '3.2.5',
+        version: MASTER_VERSION,
         role,
-        pm: { prds: prds.size },
-        pjm: { plans: plans.size },
+        agents: { pm: 'master-pm', pjm: 'master-pjm' },
+        pm: { prds: prds.size, assessments: assessments.size },
+        pjm: { plans: plans.size, closed: [...plans.values()].filter((plan) => plan.status === 'closed').length },
         cooperation: {
           decisionCenter: Boolean(decisionCenter()),
           forker: Boolean(forker()),
@@ -245,8 +301,8 @@ export function apply(ctx, config = {}) {
   master.registerSubplugin({
     id: 'dual-manager',
     name: 'dsh-master-dual-manager',
-    capabilities: ['pm-prd', 'pm-ask-user', 'pjm-plan', 'pjm-dispatch'],
-    description: 'PM + PJM 双主管（仅 mother/essence）',
+    capabilities: ['pm-prd', 'pm-assessment', 'pm-document', 'pm-ask-user', 'pjm-plan', 'pjm-dispatch', 'pjm-progress', 'pjm-close'],
+    description: 'PM/PJM 双智能体共享服务；master-pm 与 master-pjm preset 复用此服务',
   })
   return service
 }