dsh-sa-workbench 0.1.30 → 0.1.32

package/modules/dsh-pm-core/delivery-library.mjs

@@ -0,0 +1,279 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fingerprint, PmError, readDocumentArchiveLedger } from './engine.js'
+import { safeDocumentPath } from './documents.js'
+import { atomicWrite, safePath, withKnowledgeLock, KnowledgeWorkflow, CANDIDATE_PATH } from './knowledge-workflow.mjs'
+
+const MAX_DOCUMENT = 2 * 1024 * 1024
+const MAX_CAPTURE = 12 * 1024 * 1024
+const deliveryId = value => {
+  if (!/^(?:local|cloud|history|file)-[a-f0-9]{32}$/.test(String(value))) throw new PmError('bad_input', '交付记录编号无效。')
+  return value
+}
+const identity = (kind, key) => kind + '-' + fingerprint(key).slice(0, 32)
+const owner = record => record.collaboration?.pmOwner || ''
+const summary = entry => {
+  const { origin, ...result } = entry
+  return result
+}
+
+export class DeliveryLibrary {
+  constructor(pm) {
+    this.pm = pm
+    this.root = path.join(pm.root, '.sa-deliveries')
+    const library = this
+    this.workflow = new KnowledgeWorkflow({
+      root: this.root,
+      get knowledgeDir() { return pm.knowledgeDir },
+      findRequirement: async id => {
+        const delivery = await library.get(id)
+        return { record: { code: delivery.code || '历史交付', title: delivery.title, archived: false,
+          sourceDeliveryId: delivery.id, sourceRequirementId: delivery.requirementId || '' } }
+      },
+      authorizeArtifact: (_id, relative) => String(relative),
+      readDocument: async (id, relative) => relative === CANDIDATE_PATH ? library.candidates(id) : library.read(id, relative),
+      listKnowledge: () => pm.listKnowledge(),
+      readKnowledge: relative => pm.readKnowledge(relative)
+    })
+  }
+
+  async localEntries() {
+    const directory = await safePath(this.root, 'records')
+    const names = await fs.readdir(directory).catch(error => { if (error.code === 'ENOENT') return []; throw error })
+    const entries = []
+    for (const name of names.filter(name => /^local-[a-f0-9]{32}$/.test(name))) {
+      const file = await safePath(directory, name + '/manifest.json')
+      try {
+        const entry = JSON.parse(await fs.readFile(file, 'utf8'))
+        if (entry.id !== name || entry.schemaVersion !== 1 || !Array.isArray(entry.documents)) throw Error('Invalid manifest')
+        entries.push({ ...entry, origin: 'local' })
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw new PmError('corrupt_state', '交付清单无法读取，请核对 ' + name)
+      }
+    }
+    return entries
+  }
+
+  async catalog() {
+    const entries = await this.localEntries()
+    const state = await this.pm.loadState()
+    const records = Object.values(state.requirements || {})
+    for (const record of records) {
+      const ledger = await readDocumentArchiveLedger(this.pm.root, record)
+      const receipts = new Map()
+      for (const entry of [...Object.values(ledger.files || {}), ledger.solution, ledger.prd].filter(Boolean)) {
+        for (const receipt of [entry.receipt, ...(entry.history || [])].filter(Boolean)) receipts.set(receipt.requestId, receipt)
+      }
+      for (const receipt of receipts.values()) {
+        if (!receipt.path || !receipt.requestId) continue
+        entries.push({ id: identity('cloud', record.id + ':' + receipt.requestId), requirementId: record.id,
+          code: record.code, title: receipt.requirementTitle || record.title,
+          version: receipt.deliveryVersion || '', owner: receipt.owner || '',
+          archivedAt: receipt.archivedAt, kind: 'DBOX交付', note: '', origin: 'cloud',
+          documents: [{ path: receipt.path, label: receipt.stage === 'prd' ? 'PRD' : '高阶方案',
+            stage: receipt.stage, documentVersion: receipt.documentVersion, fingerprint: receipt.fingerprint,
+            snapshotPath: receipt.snapshotPath || receipt.path }], receipt })
+      }
+      if (record.archived) {
+        const view = await this.pm.viewRequirement(record.id)
+        entries.push({ id: identity('history', record.id), requirementId: record.id, code: record.code,
+          title: record.title, version: record.version || '', owner: owner(record),
+          archivedAt: record.archivedAt, kind: '历史本地归档', note: '', origin: 'history',
+          documents: view.stages.flatMap(stage => stage.artifacts.filter(doc => doc.exists).map(doc => ({
+            path: doc.legacyPath || doc.path, label: doc.label, stage: stage.id,
+            documentVersion: doc.documentVersion, fingerprint: doc.fingerprint }))) })
+      }
+    }
+    const groups = await this.pm.listPrdArchive()
+    for (const group of groups) {
+      for (const file of group.files) {
+        const matches = records.filter(record => record.code && file.name.startsWith(record.code + '-'))
+        const record = matches.length === 1 ? matches[0] : null
+        const historical = entries.find(entry => entry.origin === 'history' && entry.requirementId === record?.id &&
+          (entry.version || '未排期') === group.version)
+        if (historical) {
+          try {
+            const copy = await this.pm.readPrdArchiveFile(group.version, file.name)
+            if (historical.documents.some(doc => doc.stage === 'prd' && doc.fingerprint === fingerprint(copy))) continue
+          } catch { /* Keep the independent file visible so its read error can be inspected. */ }
+        }
+        entries.push({ id: identity('file', group.version + '/' + file.name), requirementId: record?.id || null,
+          code: record?.code || '', title: file.name.replace(/-prd\.md$/i, ''),
+          version: group.version === '未排期' ? '' : group.version, owner: record ? owner(record) : '',
+          archivedAt: file.updatedAt, kind: '历史PRD文件', note: '', origin: 'file',
+          legacyVersion: group.version, legacyName: file.name,
+          documents: [{ path: 'prd.md', label: 'PRD', stage: 'prd', documentVersion: '历史文件' }] })
+      }
+    }
+    return entries.map(entry => ({ ...entry, versionLabel: entry.version ||
+      (entry.origin === 'cloud' && !Object.hasOwn(entry.receipt, 'deliveryVersion') ? '版本未记录' : '未排期') }))
+      .sort((a, b) => String(b.archivedAt || '').localeCompare(String(a.archivedAt || '')))
+  }
+
+  async get(id) {
+    const found = (await this.catalog()).find(entry => entry.id === deliveryId(id))
+    if (!found) throw new PmError('not_found', '交付记录不存在，请刷新交付库。')
+    return found
+  }
+
+  async withDeliveryFacts(requirements) {
+    const entries = await this.catalog()
+    return Promise.all(requirements.map(async requirement => {
+      const deliveries = entries.filter(entry => entry.requirementId === requirement.id &&
+        entry.documents.some(document => document.stage === 'prd'))
+      const latest = deliveries[0]
+      if (!latest) return { ...requirement, delivery: { delivered: false } }
+      const current = requirement.stages.flatMap(stage => stage.artifacts.filter(document => document.exists)
+        .map(document => ({ ...document, path: document.legacyPath || document.path })))
+      let updated = false
+      for (const document of latest.documents) {
+        let hash = document.fingerprint
+        if (!hash) {
+          try { hash = (await this.readEntry(latest, document.path)).fingerprint }
+          catch { updated = null; break }
+        }
+        if (current.find(file => file.path === document.path)?.fingerprint !== hash) updated = true
+      }
+      if (updated !== null && latest.origin === 'local' && current.some(file => !latest.documents.some(document => document.path === file.path))) updated = true
+      return { ...requirement, delivery: { delivered: true, latestId: latest.id,
+        deliveredAt: latest.archivedAt, count: deliveries.length, updated } }
+    }))
+  }
+
+  async read(id, relative) {
+    const entry = await this.get(id)
+    return this.readEntry(entry, relative)
+  }
+
+  async readEntry(entry, relative) {
+    const document = entry.documents.find(document => document.path === relative)
+    if (!document) throw new PmError('bad_path', '文件不属于此交付记录。')
+    let content
+    if (entry.origin === 'local') {
+      if (!/^[0-9]+\.(md|html)$/.test(document.storageName)) throw new PmError('bad_path', '交付文件索引无效。')
+      const file = await safePath(this.root, 'records/' + entry.id + '/' + document.storageName)
+      if ((await fs.stat(file)).size > MAX_DOCUMENT) throw new PmError('bad_input', '交付文件过大，请在原目录查看。')
+      content = await fs.readFile(file, 'utf8')
+    } else if (entry.origin === 'file') {
+      content = await this.pm.readPrdArchiveFile(entry.legacyVersion, entry.legacyName)
+    } else if (entry.origin === 'cloud') {
+      const { record } = await this.pm.findRequirement(entry.requirementId)
+      const file = await safeDocumentPath(this.pm.root, record, document.snapshotPath)
+      if ((await fs.stat(file)).size > MAX_DOCUMENT) throw new PmError('bad_input', '交付文件过大，请在原目录查看。')
+      content = await fs.readFile(file, 'utf8')
+    } else {
+      content = (await this.pm.readDocument(entry.requirementId, relative)).content
+    }
+    if (typeof content !== 'string') throw new PmError('not_found', '交付原文已移走，无法读取。')
+    if (Buffer.byteLength(content, 'utf8') > MAX_DOCUMENT) throw new PmError('bad_input', '交付文件过大，请在原目录查看。')
+    const hash = fingerprint(content)
+    if (document.fingerprint && document.fingerprint !== hash) throw new PmError('stale_artifact', '交付原文与记录指纹不一致，请核对原文件。')
+    return { ...document, content, fingerprint: hash, deliveryId: entry.id }
+  }
+
+  async capture(input) {
+    if (!/^[a-zA-Z0-9-]{8,80}$/.test(String(input.requestId || ''))) throw new PmError('bad_input', '请从需求重新打开提交交付。')
+    const id = identity('local', input.id + ':' + input.requestId)
+    return withKnowledgeLock(this.root, async () => {
+      const existing = (await this.localEntries()).find(entry => entry.id === id)
+      if (existing) return summary(existing)
+      const view = await this.pm.viewRequirement(input.id)
+      const documents = view.stages.flatMap(stage => stage.artifacts.filter(doc => doc.exists).map(doc => ({
+        path: doc.legacyPath || doc.path, label: doc.label, stage: stage.id,
+        fingerprint: doc.fingerprint, documentVersion: doc.documentVersion })))
+      if (!documents.some(doc => doc.stage === 'prd')) throw new PmError('bad_input', '请先准备PRD，再提交交付。')
+      if (view.updatedAt !== input.expectedUpdatedAt || JSON.stringify(documents.map(doc => [doc.path, doc.fingerprint])) !== JSON.stringify(input.documents)) {
+        throw new PmError('stale_artifact', '需求或交付文档已变化，请刷新后重新确认交付。')
+      }
+      const note = String(input.note || '').trim()
+      if (note.length > 4000) throw new PmError('bad_input', '交付说明请控制在4000字内。')
+      const contents = []
+      let bytes = 0
+      for (const document of documents) {
+        const source = await this.pm.readDocument(view.id, document.path)
+        bytes += Buffer.byteLength(source.content, 'utf8')
+        if (Buffer.byteLength(source.content, 'utf8') > MAX_DOCUMENT || bytes > MAX_CAPTURE) throw new PmError('bad_input', '交付文档过大，请分批整理。')
+        if (source.fingerprint !== document.fingerprint) throw new PmError('stale_artifact', '交付文档已变化，请刷新后重试。')
+        contents.push(source.content)
+      }
+      // Publish the manifest last. An interrupted capture remains invisible and retries safely.
+      for (let index = 0; index < documents.length; index++) {
+        const extension = /\.html$/i.test(documents[index].path) ? 'html' : 'md'
+        documents[index].storageName = index + '.' + extension
+        await atomicWrite(await safePath(this.root, 'records/' + id + '/' + documents[index].storageName), contents[index])
+      }
+      const entry = { schemaVersion: 1, id, requirementId: view.id, code: view.code, title: view.title,
+        version: view.version || '', owner: owner(view), archivedAt: new Date().toISOString(),
+        kind: '本地交付快照', note, documents }
+      await atomicWrite(await safePath(this.root, 'records/' + id + '/manifest.json'), JSON.stringify(entry, null, 2))
+      return entry
+    })
+  }
+
+  async candidates(id) {
+    await this.get(id)
+    const file = await safePath(this.root, 'candidates/' + deliveryId(id) + '.md')
+    let content
+    try { content = await fs.readFile(file, 'utf8') }
+    catch (error) { if (error.code !== 'ENOENT') throw error; content = '{"schemaVersion":1,"items":[]}' }
+    return { path: CANDIDATE_PATH, content, fingerprint: fingerprint(content), documentVersion: '候选工作稿' }
+  }
+
+  async saveCandidates(input) {
+    return withKnowledgeLock(this.root, async () => {
+      const previous = await this.candidates(input.id)
+      if (input.expectedFingerprint !== previous.fingerprint) throw new PmError('conflict', '候选已变化，请读取最新候选后重试。')
+      if (typeof input.content !== 'string' || Buffer.byteLength(input.content, 'utf8') > 256 * 1024) throw new PmError('bad_input', '候选内容为空或超过256KiB。')
+      let batch
+      try { batch = JSON.parse(input.content.trim().replace(/^```json\s*\n([\s\S]*?)\n```$/, '$1')) }
+      catch { throw new PmError('bad_input', '请保存有效的候选JSON。') }
+      if (batch.schemaVersion !== 1 || !Array.isArray(batch.items) || batch.items.length > 30) throw new PmError('bad_input', '候选格式应为schemaVersion 1，最多30项。')
+      const validation = new KnowledgeWorkflow({ ...this.workflow.pm,
+        readDocument: async (id, relative) => relative === CANDIDATE_PATH
+          ? { content: input.content, fingerprint: fingerprint(input.content) }
+          : this.read(id, relative) })
+      await validation.load(input.id)
+      for (const item of batch.items) await this.workflow.verifySources(input.id, item.sources)
+      const file = await safePath(this.root, 'candidates/' + deliveryId(input.id) + '.md')
+      await atomicWrite(file, input.content)
+      return { id: input.id, fingerprint: fingerprint(input.content), count: batch.items.length }
+    })
+  }
+
+  async detail(id) {
+    const entry = await this.get(id)
+    const batch = await this.workflow.load(id)
+    return { ...summary(entry), knowledge: { pending: batch.items.filter(item => !item.receipt).length,
+      accepted: batch.items.filter(item => item.receipt).map(item => item.receipt) } }
+  }
+
+  async assistant(id) {
+    await this.get(id)
+    const directory = await safePath(this.root, 'assistants/交付知识助手-' + deliveryId(id).slice(-8))
+    await fs.mkdir(directory, { recursive: true })
+    return { path: directory }
+  }
+
+  async list(query = '') {
+    const entries = await this.catalog()
+    const terms = String(query).trim().toLocaleLowerCase().split(/\s+/).filter(Boolean)
+    if (!terms.length) return { entries: entries.map(summary) }
+    let budget = 8 * 1024 * 1024
+    let limited = false
+    const matches = []
+    for (const entry of entries) {
+      let haystack = [entry.code, entry.title, entry.version, entry.owner, entry.note].join(' ').toLocaleLowerCase()
+      if (terms.every(term => haystack.includes(term))) { matches.push(summary(entry)); continue }
+      for (const document of entry.documents) {
+        if (budget <= 0) { limited = true; break }
+        try {
+          const read = await this.readEntry(entry, document.path)
+          budget -= Buffer.byteLength(read.content, 'utf8')
+          haystack += '\n' + read.content.toLocaleLowerCase()
+        } catch { limited = true }
+      }
+      if (terms.every(term => haystack.includes(term))) matches.push(summary(entry))
+    }
+    return { entries: matches, searchLimited: limited }
+  }
+}

package/modules/dsh-pm-core/engine.js

@@ -864,7 +864,7 @@ export async function beginDocumentArchive(root, input) {
     const requestId = randomUUID(), snapshotPath = `.publications/${requestId}/${path.basename(rel)}`
     const absolutePath = await safeDocumentPath(root, record, snapshotPath)
     await writeText(absolutePath, content)
-    const request = { requestId, stage: input.stage, path: rel, main: !!selectedArtifact.main, sourceVersion: labelRevision(revision), documentVersion: `v${revision.major + 1}.0`, major: revision.major + 1, baseMinor: revision.minor, snapshotPath, fingerprint: hash, requestedAt: new Date().toISOString() }
+    const request = { requestId, deliveryVersion: record.version || '', requirementTitle: record.title, owner: record.collaboration?.pmOwner || '', stage: input.stage, path: rel, main: !!selectedArtifact.main, sourceVersion: labelRevision(revision), documentVersion: `v${revision.major + 1}.0`, major: revision.major + 1, baseMinor: revision.minor, snapshotPath, fingerprint: hash, requestedAt: new Date().toISOString() }
     ledger.files ||= {}
     // One in-flight publication per document; another stage/file does not replace it.
     ledger.files[rel] = { ...(ledger.files[rel] || {}), pending: request }

package/modules/dsh-pm-core/index.js

@@ -1,3 +1,7 @@
+import {installRequirementDeletion} from './requirement-deletion.mjs'
+import {ProductContext} from './product-context.mjs'
+import {DeliveryLibrary} from './delivery-library.mjs'
+import {KnowledgeWorkflow} from './knowledge-workflow.mjs'
 /**
  * dsh-pm-core — host half.
  *
@@ -106,6 +110,10 @@ export function apply(ctx, config = {}) {
     readPrdArchiveFile: (version, name) => engine.readPrdArchiveFile(root, settings.value.prdArchiveDir, version, name),
   }
   // Cordis 4：服务必须先 provide 才能被 inject（"cannot set property without provide"）。
+  pm.knowledgeWorkflow = new KnowledgeWorkflow(pm)
+  pm.deliveryLibrary = new DeliveryLibrary(pm)
+  pm.productContext = new ProductContext(pm)
+  installRequirementDeletion(pm)
   ctx.provide('pmCore', pm)
 
   // 播种全局知识库（SKILL / PRD 模板 / 决策记忆）；只写缺失文件，失败不拖垮启动。
@@ -119,7 +127,39 @@ export function apply(ctx, config = {}) {
   })
 
   // -------------------------------------------------------------------------
-  // Agent 工具
+  // Agent 工具
+  ctx.tools.register(defineTool({
+    name:'pm_product_context_read',
+    description:'读取已接入的权威产品包含目录与人工确认的知识关联。空目录表示尚未接入，不可自行编造层级。关联只表示知识涉及这些产品，正文适用性仍须查阅知识内容与确认状态。可以建议关联，由用户在知识详情中确认。',
+    parameters:{},output:jsonOut,
+    execute:async ()=>pm.productContext.read()
+  }))
+  ctx.tools.register(defineTool({
+    name:'pm_delivery_read',
+    description:'读取交付库某次交付的固定文档及指纹。path省略时返回交付清单，path为notes/knowledge-candidates.md时返回该交付独立候选及指纹。历史交付用于追溯，提炼时核对适用范围。',
+    parameters:{id:req('交付记录ID，使用工作台提取任务给出的ID'),path:str('交付清单中的文件相对路径，或notes/knowledge-candidates.md')},output:jsonOut,
+    execute:async args=>!args.path?pm.deliveryLibrary.detail(args.id):args.path==='notes/knowledge-candidates.md'?pm.deliveryLibrary.candidates(args.id):pm.deliveryLibrary.read(args.id,args.path)
+  }))
+  ctx.tools.register(defineTool({
+    name:'pm_delivery_candidates_save',
+    description:'将知识候选JSON保存到交付记录的独立候选区。先读取旧候选并保留已有条目，提供旧指纹。每项sources必须逐字引用此交付清单中的Markdown。用户复核后才入知识库。',
+    parameters:{id:req('交付记录ID'),content:req('schemaVersion 1候选JSON全文'),expectedFingerprint:req('先读取候选获得的原指纹')},output:jsonOut,
+    execute:async args=>pm.deliveryLibrary.saveCandidates(args)
+  }))
+  ctx.tools.register(defineTool({
+    name:'pm_knowledge_search',
+    description:'检索SA知识库的Markdown，返回类型、领域、确认状态、原文片段和指纹。知识候选提取前先查已有知识。准备更新某文件时必须再完整读取该文件，保留无关内容。',
+    parameters:{query:str('用空格分隔关键词，任一关键词匹配。空值列出前12项。')},
+    output:jsonOut,
+    execute:async args=>pm.knowledgeWorkflow.search(args.query || '')
+  }))
+  ctx.tools.register(defineTool({
+    name:'pm_knowledge_read',
+    description:'读取知识库中一份Markdown全文及其指纹。更新知识前用此工具完整读取，保留未涉及的内容。',
+    parameters:{path:req('知识根目录相对路径')},
+    output:jsonOut,
+    execute:async args=>pm.knowledgeWorkflow.read(args.path)
+  }))
   // -------------------------------------------------------------------------
 
   ctx.tools.register(

package/modules/dsh-pm-core/knowledge-model.mjs

@@ -0,0 +1,36 @@
+// Deliberately restricted front matter: plain scalar fields and string lists only.
+// Never infer business confirmation or domains from prose or filenames.
+export function knowledgeRecord(file, text='') {
+  const fields={}, match=String(text).match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+  const scalar=s=>{
+    const value=String(s).trim()
+    if(value.startsWith('"')){try{return String(JSON.parse(value))}catch{}}
+    return value.replace(/^(['"])(.*)\1$/,'$2')
+  }
+  if(match){let key='';for(const line of match[1].split(/\r?\n/)){
+    const pair=line.match(/^([a-z_]+):\s*(.*?)\s*$/)
+    if(pair){key=pair[1];fields[key]=pair[2] ? scalar(pair[2]) : []}
+    else {const item=line.match(/^\s+-\s+(.+)$/);if(item && Array.isArray(fields[key]))fields[key].push(scalar(item[1]))}
+  }}
+  const list=v=>Array.isArray(v)?v.map(scalar):typeof v==='string'?v.replace(/^\[|\]$/g,'').split(/[,，]/).map(scalar).filter(Boolean):[]
+  const body=match?text.slice(match[0].length):String(text)
+  return {...file,title:scalar(fields.title || body.match(/^#\s+(.+)$/m)?.[1] || file.path.replace(/.*\//,'').replace(/\.[^.]+$/,'')),
+    kind:scalar(fields.type || '未分类'),domains:list(fields.domains),status:scalar(fields.status || '未标注'),
+    summary:scalar(fields.summary || body.replace(/^#+\s+.*$/gm,'').replace(/[`*_>#\[\]]/g,'').trim().slice(0,160)),
+    source:scalar(fields.source || ''),owner:scalar(fields.owner || ''),version:scalar(fields.version || ''),
+    scope:scalar(fields.scope || ''),reviewedBy:scalar(fields.reviewed_by || ''),
+    sourceDeliveryId:scalar(fields.source_delivery_id || ''),sourceRequirementId:scalar(fields.source_requirement_id || ''),
+    related:list(fields.related),searchText:body.slice(0,262144),metadata:!!match}
+}
+
+export async function knowledgeCatalog(pm){
+  const files=await pm.listKnowledge(), records=[]
+  let budget=4*1024*1024
+  // Sequential, bounded reads avoid unbounded I/O on a large knowledge directory.
+  for(const file of files){
+    if(file.bytes>262144 || file.bytes>budget){records.push({...knowledgeRecord(file),previewLimited:true});continue}
+    try{const content=await pm.readKnowledge(file.path) || '';budget-=Math.max(file.bytes,content.length);records.push(knowledgeRecord(file,content))}
+    catch{records.push({...knowledgeRecord(file),metadataError:true})}
+  }
+  return records
+}