dsh-sa-workbench 0.1.30 → 0.1.32

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

@@ -0,0 +1,291 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { fingerprint, PmError } from './engine.js'
+import { knowledgeRecord } from './knowledge-model.mjs'
+
+export const CANDIDATE_PATH = 'notes/knowledge-candidates.md'
+const MAX_DOCUMENT = 256 * 1024
+
+function reject(code, message) {
+  throw new PmError(code, message)
+}
+
+function text(value, label, limit = 240, required = true) {
+  if (typeof value !== 'string' || value.length > limit || (required && !value.trim())) {
+    reject('bad_input', `${label}为空或超过长度限制。`)
+  }
+  return value.trim()
+}
+
+function scalar(value, label, required = true) {
+  const result = text(value ?? '', label, 240, required)
+  if (/[\r\n]/.test(result)) reject('bad_input', `${label}请填写单行文本。`)
+  return result
+}
+
+function list(value, label) {
+  if (!Array.isArray(value) || value.length > 12) reject('bad_input', `${label}请填写数组，最多12项。`)
+  return [...new Set(value.map(item => scalar(item, label))) ]
+}
+
+async function optional(file) {
+  try { return await fs.readFile(file, 'utf8') }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+
+export async function safePath(root, relative) {
+  const absoluteRoot = path.resolve(root)
+  const absolute = path.resolve(absoluteRoot, relative)
+  if (absolute !== absoluteRoot && !absolute.startsWith(absoluteRoot + path.sep)) reject('bad_path', '路径超出知识目录。')
+  // Check ancestors too: configured roots can themselves be redirected.
+  const parsed = path.parse(absolute)
+  let current = parsed.root
+  for (const part of absolute.slice(parsed.root.length).split(path.sep)) {
+    current = path.join(current, part)
+    const stat = await fs.lstat(current).catch(error => { if (error.code === 'ENOENT') return null; throw error })
+    if (!stat) break
+    if (stat.isSymbolicLink()) reject('bad_path', '知识目录包含重定向，请使用普通目录。')
+  }
+  return absolute
+}
+
+function knowledgePath(relative) {
+  const parts = String(relative).split('/')
+  if (parts.length > 2 || !/\.md$/i.test(relative) || parts.some(part =>
+    !/^[\p{L}\p{N}][\p{L}\p{N} _().（）【】-]*$/u.test(part) || /[ .]$/.test(part) ||
+    /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
+    reject('bad_path', '知识文件路径需为根目录或一层子目录下的普通 Markdown 文件。')
+  }
+  return relative
+}
+
+export async function atomicWrite(file, content) {
+  await fs.mkdir(path.dirname(file), { recursive: true })
+  const temporary = file + '.' + randomUUID() + '.tmp'
+  try {
+    await fs.writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' })
+    await fs.rename(temporary, file)
+  } finally {
+    await fs.unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error })
+  }
+}
+
+function metadataHeader(before, fields) {
+  const managed = new Set(Object.keys(fields))
+  const previous = before?.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+  const retained = []
+  let skip = false
+  for (const line of (previous?.[1] || '').split(/\r?\n/)) {
+    const key = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):/)
+    if (key) skip = managed.has(key[1])
+    if (!skip && line.trim()) retained.push(line)
+  }
+  const updated = Object.entries(fields).map(([key, value]) => key + ': ' +
+    (Array.isArray(value) ? '[' + value.map(entry => JSON.stringify(entry)).join(', ') + ']' : JSON.stringify(value)))
+  return [...retained, ...updated].join('\n')
+}
+
+export async function withKnowledgeLock(root, run) {
+  const control = await safePath(root, '.sa-knowledge-control')
+  await fs.mkdir(control, { recursive: true })
+  const file = await safePath(root, '.sa-knowledge-control/write.lock')
+  const identity = JSON.stringify({ pid: process.pid, token: randomUUID() })
+  let lock
+  try { lock = await fs.open(file, 'wx') }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    const previous = await optional(file)
+    let dead = false
+    try {
+      const owner = JSON.parse(previous)
+      if (!Number.isInteger(owner.pid) || owner.pid < 1) throw Error('Invalid lock owner')
+      try { process.kill(owner.pid, 0) } catch (probe) { dead = probe.code === 'ESRCH' }
+    } catch { /* A malformed lock requires explicit repair. */ }
+    if (dead && await optional(file) === previous) {
+      await fs.unlink(file)
+      return withKnowledgeLock(root, run)
+    }
+    reject('conflict', '知识库正在保存，请稍后重试。')
+  }
+  let recorded = false
+  try { await lock.writeFile(identity); recorded = true; return await run(control) }
+  finally {
+    await lock.close()
+    if (!recorded || await optional(file) === identity) await fs.unlink(file).catch(error => { if (error.code !== 'ENOENT') throw error })
+  }
+}
+
+export class KnowledgeWorkflow {
+  constructor(pm) { this.pm = pm }
+
+  async read(relative) {
+    const target = knowledgePath(relative)
+    const file = (await this.pm.listKnowledge()).find(entry => entry.path === target)
+    if (!file) reject('not_found', '知识文件不存在或超出当前枚举范围。')
+    if (file.bytes > MAX_DOCUMENT) reject('bad_input', '知识文件超过256KiB，请分拆后再通过助手复核。')
+    await safePath(this.pm.knowledgeDir, target)
+    const content = await this.pm.readKnowledge(target)
+    if (content === null) reject('not_found', '知识文件已移走，请刷新。')
+    return { path: target, content, fingerprint: fingerprint(content) }
+  }
+
+  async search(query = '') {
+    const files = await this.pm.listKnowledge()
+    const terms = String(query).toLocaleLowerCase().split(/\s+/).filter(Boolean)
+    const matches = []
+    let budget = 4 * 1024 * 1024
+    for (const file of files) {
+      if (file.bytes > MAX_DOCUMENT || file.bytes > budget) continue
+      const content = await this.pm.readKnowledge(file.path)
+      if (content === null) continue
+      budget -= Buffer.byteLength(content, 'utf8')
+      const record = knowledgeRecord(file, content)
+      const haystack = (record.title + '\n' + content).toLocaleLowerCase()
+      if (!terms.length || terms.some(term => haystack.includes(term))) {
+        matches.push({ path: file.path, title: record.title, type: record.kind, domains: record.domains,
+          status: record.status, fingerprint: fingerprint(content), excerpt: content.slice(0, 6000) })
+      }
+    }
+    return { matches: matches.slice(0, 12), total: matches.length,
+      coverage: 'Markdown根目录与下一层，单文件256KiB、总读取4MiB，最多返回12条。修改目标需重新完整读取原文件。' }
+  }
+
+  async load(id) {
+    const { record } = await this.pm.findRequirement(id)
+    let document
+    try { document = await this.pm.readDocument(id, CANDIDATE_PATH) }
+    catch (error) {
+      if (error.code === 'ENOENT') return { id, code: record.code, items: [], fingerprint: null }
+      throw error
+    }
+    if (Buffer.byteLength(document.content, 'utf8') > MAX_DOCUMENT) reject('bad_input', '候选文件超过256KiB，请分批提取。')
+    const raw = document.content.trim().replace(/^```json\s*\n([\s\S]*?)\n```$/, '$1')
+    let batch
+    try { batch = JSON.parse(raw) } catch { reject('bad_input', '知识候选格式有误，请让助手按约定保存JSON。') }
+    if (batch.schemaVersion !== 1 || !Array.isArray(batch.items) || batch.items.length > 30) reject('bad_input', '知识候选需为schemaVersion 1，最多30条。')
+    const identifiers = new Set()
+    const items = []
+    for (const item of batch.items) {
+      if (!item || typeof item !== 'object' || typeof item.id !== 'string' ||
+        !/^[a-zA-Z0-9_-]{1,64}$/.test(item.id) || identifiers.has(item.id)) reject('bad_input', '候选编号为空、重复或格式有误。')
+      scalar(item.title, '候选标题')
+      text(item.body, '候选正文', 60000)
+      list(item.domains || [], '候选领域')
+      list(item.uncertainties || [], '待确认问题')
+      for (const field of ['type', 'owner', 'scope']) scalar(item[field] || '', field, false)
+      if (!Array.isArray(item.sources) || !item.sources.length || item.sources.length > 8 ||
+        item.sources.some(source => !source || typeof source.path !== 'string' || typeof source.quote !== 'string' || typeof source.fingerprint !== 'string')) {
+        reject('bad_input', '候选依据需包含文件、原文和指纹。')
+      }
+      identifiers.add(item.id)
+      const candidateFingerprint = fingerprint(JSON.stringify(item))
+      const key = fingerprint(this.pm.root + ':' + id + ':' + item.id + ':' + candidateFingerprint)
+      const receiptFile = await safePath(this.pm.knowledgeDir, '.sa-knowledge-control/' + key + '.json')
+      const transaction = await optional(receiptFile)
+      const saved = transaction ? JSON.parse(transaction) : null
+      items.push({ ...item, candidateFingerprint, receipt: saved?.state === 'applied' ? saved.receipt : null,
+        pendingReview: saved?.state === 'prepared' ? saved.preview : null })
+    }
+    return { id, code: record.code, requirementTitle: record.title, archived: !!record.archived,
+      sourceDeliveryId: record.sourceDeliveryId, sourceRequirementId: record.sourceRequirementId,
+      fingerprint: document.fingerprint, items }
+  }
+
+  async verifySources(id, sources) {
+    if (!Array.isArray(sources) || !sources.length || sources.length > 8) reject('bad_input', '每条候选需提供1至8份原文依据。')
+    const checked = []
+    for (const source of sources) {
+      const relative = this.pm.authorizeArtifact(id, source.path)
+      if (relative === CANDIDATE_PATH || !/\.md$/i.test(relative)) reject('bad_input', '请引用需求的Markdown原文，候选文件不能作为自身依据。')
+      const document = await this.pm.readDocument(id, relative)
+      if (document.fingerprint !== source.fingerprint) reject('stale_artifact', `原文 ${relative} 已变化，请重新提取候选。`)
+      const quote = text(source.quote, '依据原文', 12000)
+      if (!document.content.includes(quote)) reject('bad_input', `依据原文与 ${relative} 内容不匹配。`)
+      checked.push({ path: relative, quote, fingerprint: document.fingerprint, version: document.documentVersion })
+    }
+    return checked
+  }
+
+  async preview(input) {
+    const batch = await this.load(input.id)
+    if (batch.archived) reject('archived', '历史归档需求只读。')
+    if (!batch.fingerprint || batch.fingerprint !== input.candidatesFingerprint) reject('conflict', '候选已变化，请刷新复核。')
+    const item = batch.items.find(entry => entry.id === input.itemId)
+    if (!item) reject('not_found', '候选不存在。')
+    if (item.receipt) reject('conflict', '此候选已入库，请刷新查看回执。')
+    if (input.candidateFingerprint !== item.candidateFingerprint) reject('conflict', '候选内容已变化，请刷新复核。')
+    const edits = input.edits || item
+    const values = {
+      title: scalar(edits.title, '标题'), type: scalar(edits.type, '知识类型'),
+      domains: list(edits.domains, '领域'), scope: scalar(edits.scope, '适用范围'),
+      owner: scalar(edits.owner, '维护人'), body: text(edits.body, '知识正文', 60000),
+      uncertainties: list(edits.uncertainties || [], '待确认问题'),
+      reviewedBy: scalar(input.reviewedBy, '确认人'),
+    }
+    if (values.uncertainties.length) reject('bad_input', '请先解决列出的待确认问题，再确认入库。')
+    if (values.domains.some(domain => /[,，\[\]"]/.test(domain))) reject('bad_input', '领域名称请使用不含逗号、括号和双引号的短名称。')
+    const sources = await this.verifySources(input.id, item.sources)
+    const targetPath = knowledgePath(item.targetPath || 'entries/k-' + fingerprint(this.pm.root + ':' + input.id + ':' + item.id).slice(0, 20) + '.md')
+    const target = await safePath(this.pm.knowledgeDir, targetPath)
+    const targetStat = await fs.stat(target).catch(error => { if (error.code === 'ENOENT') return null; throw error })
+    if (targetStat && targetStat.size > MAX_DOCUMENT) reject('bad_input', '目标知识超过256KiB，请分拆后复核。')
+    const before = await optional(target)
+    const targetFingerprint = before === null ? null : fingerprint(before)
+    if (item.targetPath && targetFingerprint !== (item.targetFingerprint ?? null)) reject('conflict', '目标知识已变化，请让助手重新比较差异。')
+    if (!item.targetPath && before !== null) reject('conflict', '同一候选已有知识文件，请刷新或以更新方式提取。')
+    const context = { root: path.resolve(this.pm.knowledgeDir), requirementRoot: this.pm.root,
+      id: input.id, itemId: item.id, candidateFingerprint: item.candidateFingerprint,
+      candidatesFingerprint: batch.fingerprint, targetPath, targetFingerprint, values, sources }
+    // Independent candidates in the same note can change while a prepared
+    // write is recovered. The individual candidate and all evidence stay bound.
+    const token = fingerprint(JSON.stringify({ ...context, candidatesFingerprint: null }))
+    const fields = { title: values.title, type: values.type, domains: values.domains, status: '已确认',
+      scope: values.scope, owner: values.owner, version: 'review-' + token.slice(0, 12),
+      source: batch.code + ' ' + sources.map(source => source.path + '@' + source.version).join('、'),
+      source_fingerprints: sources.map(source => source.fingerprint),
+      reviewed_by: values.reviewedBy, review_id: token }
+    if (batch.sourceDeliveryId) fields.source_delivery_id = batch.sourceDeliveryId
+    if (batch.sourceRequirementId) fields.source_requirement_id = batch.sourceRequirementId
+    const metadata = metadataHeader(before, fields)
+    const provenance = sources.map(source => `- ${batch.code} / ${source.path} / ${source.version}\n\n> ${source.quote.replace(/\n/g, '\n> ')}`).join('\n\n')
+    const content = '---\n' + metadata + '\n---\n# ' + values.title + '\n\n' + values.body +
+      '\n\n## 原文依据\n\n' + provenance + '\n'
+    if (Buffer.byteLength(content, 'utf8') > MAX_DOCUMENT) reject('bad_input', '入库内容超过256KiB，请拆成更小的知识条目。')
+    return { ...context, token, content, before, operation: before === null ? 'create' : 'update' }
+  }
+
+  async approve(input) {
+    if (input.confirmed !== true || !/^[a-f0-9]{64}$/.test(input.token || '') || !/^[a-f0-9]{64}$/.test(input.candidateFingerprint || '')) reject('bad_input', '请完成复核并明确确认入库。')
+    return withKnowledgeLock(this.pm.knowledgeDir, async () => {
+      const key = fingerprint(this.pm.root + ':' + input.id + ':' + input.itemId + ':' + input.candidateFingerprint)
+      const receiptFile = await safePath(this.pm.knowledgeDir, '.sa-knowledge-control/' + key + '.json')
+      const saved = await optional(receiptFile)
+      let transaction = saved ? JSON.parse(saved) : null
+      if (transaction?.state === 'applied') return transaction.receipt
+      if (transaction && transaction.preview.token !== input.token) reject('conflict', '这条候选已有待完成的保存，请恢复原复核内容后重试。')
+      if (!transaction) {
+        const preview = await this.preview(input)
+        if (preview.token !== input.token) reject('conflict', '复核内容已变化，请重新预览差异。')
+        transaction = { state: 'prepared', preview, acceptedAt: new Date().toISOString() }
+        await atomicWrite(receiptFile, JSON.stringify(transaction, null, 2))
+      }
+      const preview = transaction.preview
+      if (preview.root !== path.resolve(this.pm.knowledgeDir)) reject('conflict', '知识库目录已切换，请重新复核。')
+      const target = await safePath(this.pm.knowledgeDir, knowledgePath(preview.targetPath))
+      const current = await optional(target)
+      if (current !== preview.content) {
+        const live = await this.load(input.id)
+        const fresh = await this.preview({ ...input, candidatesFingerprint: live.fingerprint })
+        if (fresh.token !== preview.token || (current === null ? null : fingerprint(current)) !== preview.targetFingerprint) {
+          reject('conflict', '原文或目标知识已变化，保存停止，请重新复核。')
+        }
+        await atomicWrite(target, preview.content)
+      }
+      const receipt = { path: preview.targetPath, title: preview.values.title, fingerprint: fingerprint(preview.content),
+        operation: preview.operation, reviewedBy: preview.values.reviewedBy, acceptedAt: transaction.acceptedAt, token: preview.token }
+      await atomicWrite(receiptFile, JSON.stringify({ ...transaction, state: 'applied', receipt }, null, 2))
+      return receipt
+    })
+  }
+}

package/modules/dsh-pm-core/product-context.mjs

@@ -0,0 +1,74 @@
+import fs from 'node:fs/promises'
+import { fingerprint, PmError } from './engine.js'
+import { safePath, atomicWrite, withKnowledgeLock } from './knowledge-workflow.mjs'
+
+const FILE = '.sa-knowledge-control/products.json'
+const fail = message => { throw new PmError('bad_input', message) }
+
+export function validateProducts(input) {
+  if (input?.schemaVersion !== 1 || !Array.isArray(input.nodes) || input.nodes.length > 1000) fail('产品目录需为 schemaVersion 1，最多1000个节点。')
+  const nodes = input.nodes.map(node => {
+    if (!node || typeof node.id !== 'string' || !/^[a-zA-Z0-9_.-]{1,100}$/.test(node.id) ||
+        typeof node.name !== 'string' || !node.name.trim() || node.name.length > 120 ||
+        !['产品体系', '产品', '子产品', '模块'].includes(node.type) ||
+        (node.parentId != null && typeof node.parentId !== 'string')) fail('请检查节点 ID、名称、类型和 parentId。')
+    return { id: node.id, name: node.name.trim(), type: node.type, parentId: node.parentId || null }
+  })
+  const byId = new Map(nodes.map(node => [node.id, node]))
+  if (byId.size !== nodes.length) fail('产品节点 ID 不可重复。')
+  for (const node of nodes) {
+    const visited = new Set([node.id])
+    let parent = node.parentId
+    while (parent) {
+      if (!byId.has(parent)) fail('产品目录有不存在的父节点。')
+      if (visited.has(parent)) fail('产品包含关系存在循环。')
+      visited.add(parent)
+      if (visited.size > 16) fail('产品层级最多16层。')
+      parent = byId.get(parent).parentId
+    }
+  }
+  return nodes
+}
+
+export class ProductContext {
+  constructor(pm) { this.pm = pm }
+  async document(relative) {
+    if (!(await this.pm.listKnowledge()).some(file => file.path === relative)) fail('知识文档不存在，请刷新。')
+    await safePath(this.pm.knowledgeDir, relative)
+    const content = await this.pm.readKnowledge(relative)
+    if (content === null) fail('知识文档不存在，请刷新。')
+    return { path: relative, content, fingerprint: fingerprint(content) }
+  }
+  async read() {
+    const file = await safePath(this.pm.knowledgeDir, FILE)
+    let raw
+    try { raw = await fs.readFile(file, 'utf8') }
+    catch (error) { if (error.code !== 'ENOENT') throw error }
+    if (!raw) return { schemaVersion: 1, nodes: [], links: {}, revision: null }
+    const data = JSON.parse(raw)
+    return { schemaVersion: 1, nodes: validateProducts(data), links: data.links || {}, revision: fingerprint(raw) }
+  }
+  async save(input) {
+    return withKnowledgeLock(this.pm.knowledgeDir, async () => {
+      const current = await this.read()
+      if (input.revision !== current.revision) throw new PmError('conflict', '目录或关联已变化，请刷新后重试。')
+      let nodes = current.nodes, links = { ...current.links }
+      if (input.operation === 'import') {
+        nodes = validateProducts(input.catalog)
+        const ids = new Set(nodes.map(node => node.id))
+        if (Object.values(links).some(link => link.nodeIds.some(id => !ids.has(id)))) fail('新目录移除了已关联节点，请先解除关联或保留原 ID。')
+      } else if (input.operation === 'link') {
+        if (typeof input.path !== 'string' || !/\.md$/i.test(input.path)) fail('请选择 Markdown 知识。')
+        // Reuse the existing authorized full read, path checks and document fingerprint.
+        const document = await this.document(input.path)
+        if (document.fingerprint !== input.documentFingerprint) throw new PmError('conflict', '知识正文已变化，请重新打开后关联。')
+        const ids = new Set(nodes.map(node => node.id))
+        if (!Array.isArray(input.nodeIds) || input.nodeIds.length > 100 || input.nodeIds.some(id => !ids.has(id))) fail('关联节点不存在或超过100项。')
+        links[input.path] = { nodeIds: [...new Set(input.nodeIds)], documentFingerprint: document.fingerprint, updatedAt: new Date().toISOString() }
+      } else fail('未知目录操作。')
+      const raw = JSON.stringify({ schemaVersion: 1, nodes, links }, null, 2) + '\n'
+      await atomicWrite(await safePath(this.pm.knowledgeDir, FILE), raw)
+      return { schemaVersion: 1, nodes, links, revision: fingerprint(raw) }
+    })
+  }
+}

package/modules/dsh-pm-core/requirement-deletion.mjs

@@ -0,0 +1,276 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { assertRequirementId, fingerprint, loadState, saveState, PmError } from './engine.js'
+import { safePath, atomicWrite, withKnowledgeLock } from './knowledge-workflow.mjs'
+import { knowledgeRecord } from './knowledge-model.mjs'
+
+const CONTROL = '.sa-requirement-deletions'
+const REQUEST = /^[a-f0-9-]{36}$/i
+const labels = { workspace: '需求与交付', knowledge: '知识库', prd: '历史交付' }
+const missing = error => { if (error.code !== 'ENOENT') throw error; return null }
+
+function hasCode(value, code) {
+  if (!code) return false
+  const escaped = code.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp('(^|[^a-zA-Z0-9])' + escaped + '(?=$|[^a-zA-Z0-9])', 'i').test(String(value || ''))
+}
+
+async function readOptional(file) {
+  return fs.readFile(file, 'utf8').catch(missing)
+}
+
+async function tree(root, relative) {
+  const absolute = await safePath(root, relative)
+  const stat = await fs.lstat(absolute).catch(missing)
+  if (!stat) return null
+  if (stat.isSymbolicLink()) throw new PmError('bad_path', '删除范围含重定向，请先核对原目录。')
+  if (stat.isDirectory()) {
+    const children = []
+    for (const name of (await fs.readdir(absolute)).sort()) {
+      const child = await tree(root, path.join(relative, name))
+      if (child) children.push([name, child])
+    }
+    return { directory: true, children }
+  }
+  if (!stat.isFile()) throw new PmError('bad_path', '删除范围含非普通文件。')
+  const hash = createHash('sha256')
+  for await (const chunk of createReadStream(absolute)) hash.update(chunk)
+  return { bytes: stat.size, hash: hash.digest('hex') }
+}
+
+function fileCount(snapshot) {
+  return snapshot.directory ? snapshot.children.reduce((sum, [, child]) => sum + fileCount(child), 0) : 1
+}
+
+export class RequirementDeletion {
+  constructor(pm) {
+    this.pm = pm
+    this.roots = () => ({ workspace: path.resolve(pm.root), knowledge: path.resolve(pm.knowledgeDir), prd: path.resolve(pm.prdArchiveDir || path.join(pm.root, 'prd-archive')) })
+    this.ready = this.recover()
+  }
+
+  async locked(run) {
+    const roots = [...new Set([this.pm.root, this.pm.knowledgeDir, this.pm.deliveryLibrary.root].map(root => path.resolve(root)))].sort()
+    const enter = index => index === roots.length ? run() : withKnowledgeLock(roots[index], () => enter(index + 1))
+    return enter(0)
+  }
+
+  async scan(id) {
+    const state = await loadState(this.pm.root)
+    const record = state.requirements[assertRequirementId(id)]
+    if (!record) throw new PmError('not_found', '需求已不存在，请刷新清单。')
+    const code = String(record.code || '')
+    if (code && Object.values(state.requirements).some(other => other.id !== id && other.code === code)) {
+      throw new PmError('conflict', '需求编码重复，请先核对重复记录。')
+    }
+    const roots = this.roots(), targets = []
+    async function add(area, relative, kind) {
+      const snapshot = await tree(roots[area], relative)
+      if (snapshot) targets.push({ area, relative: relative.replaceAll('\\', '/'), kind, snapshot })
+    }
+    await add('workspace', (record.archived ? 'archive/' : 'requirements/') + id, 'requirement')
+    const deliveries = (await this.pm.deliveryLibrary.catalog()).filter(entry => entry.requirementId === id || code && entry.code === code || entry.origin === 'file' && hasCode(entry.legacyName, code))
+    for (const entry of deliveries) {
+      if (entry.requirementId && entry.requirementId !== id) throw new PmError('conflict', '交付编码与来源需求不一致，请先核对交付记录。')
+      if (entry.origin === 'local') await add('workspace', '.sa-deliveries/records/' + entry.id, 'delivery')
+      if (entry.origin === 'file') await add('prd', entry.legacyVersion + '/' + entry.legacyName, 'delivery')
+      await add('workspace', '.sa-deliveries/candidates/' + entry.id + '.md', 'candidate')
+    }
+    const deliveryIds = new Set(deliveries.map(entry => entry.id))
+    const knowledgePaths = new Set()
+    for (const file of await this.pm.listKnowledge()) {
+      const absolute = await safePath(roots.knowledge, file.path)
+      const content = await fs.readFile(absolute, 'utf8')
+      const metadata = knowledgeRecord(file, content)
+      const attached = metadata.sourceRequirementId === id || deliveryIds.has(metadata.sourceDeliveryId) ||
+        hasCode(metadata.source, code) || hasCode(file.path, code)
+      if (!attached) continue
+      if (metadata.sourceRequirementId && metadata.sourceRequirementId !== id) throw new PmError('conflict', '知识编码与来源需求不一致，请先核对来源。')
+      knowledgePaths.add(file.path)
+      await add('knowledge', file.path, 'knowledge')
+    }
+    const control = await safePath(roots.knowledge, '.sa-knowledge-control')
+    const receipts = await fs.readdir(control).catch(error => { if (error.code === 'ENOENT') return []; throw error })
+    for (const name of receipts.filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+      const relative = '.sa-knowledge-control/' + name
+      const receipt = JSON.parse(await fs.readFile(await safePath(roots.knowledge, relative), 'utf8'))
+      if (receipt.preview?.id === id || deliveryIds.has(receipt.preview?.id) || knowledgePaths.has(receipt.receipt?.path) || knowledgePaths.has(receipt.preview?.targetPath)) {
+        await add('knowledge', relative, 'receipt')
+      }
+    }
+    const productsFile = await safePath(roots.knowledge, '.sa-knowledge-control/products.json')
+    const productsBefore = await readOptional(productsFile)
+    let productsAfter = productsBefore
+    if (productsBefore) {
+      const products = JSON.parse(productsBefore)
+      const linked = [...knowledgePaths].filter(relative => Object.hasOwn(products.links || {}, relative))
+      for (const relative of linked) delete products.links[relative]
+      if (linked.length) productsAfter = JSON.stringify(products, null, 2) + '\n'
+    }
+    targets.sort((a, b) => (a.area + '/' + a.relative).localeCompare(b.area + '/' + b.relative))
+    const unique = targets.filter((target, index) => !targets.some((parent, parentIndex) => parentIndex !== index &&
+      path.resolve(roots[target.area], target.relative).startsWith(path.resolve(roots[parent.area], parent.relative) + path.sep)))
+    const result = { id, code, title: record.title, roots, targets: unique, productsBefore, productsAfter,
+      totals: { requirementFiles: targets.filter(target => target.kind === 'requirement').reduce((sum, target) => sum + fileCount(target.snapshot), 0),
+        deliveries: deliveries.length, knowledge: knowledgePaths.size, cloudReceipts: deliveries.filter(entry => entry.origin === 'cloud').length } }
+    result.fingerprint = fingerprint(JSON.stringify({ record, roots, targets: unique, productsBefore }))
+    return result
+  }
+
+  publicPlan(plan) {
+    return { id: plan.id, code: plan.code, title: plan.title, fingerprint: plan.fingerprint, totals: plan.totals,
+      files: plan.targets.filter(target => !['receipt', 'candidate'].includes(target.kind)).map(target => ({
+        group: labels[target.area], path: target.relative, files: fileCount(target.snapshot) })) }
+  }
+
+  async preview(id) {
+    await this.ready
+    return this.locked(async () => this.publicPlan(await this.scan(id)))
+  }
+
+  async journalFile(requestId) {
+    if (!REQUEST.test(requestId || '')) throw new PmError('bad_input', '删除请求编号无效。')
+    return safePath(this.pm.root, CONTROL + '/' + requestId + '.json')
+  }
+
+  async save(transaction) {
+    await atomicWrite(await this.journalFile(transaction.requestId), JSON.stringify(transaction, null, 2))
+  }
+
+  async locations(transaction, move) {
+    const roots = this.roots()
+    if (JSON.stringify(transaction.roots) !== JSON.stringify(roots) || !Object.hasOwn(roots, move.area)) {
+      throw new PmError('conflict', '目录配置已变化，请恢复删除时的配置后完成清理。')
+    }
+    const from = await safePath(roots[move.area], move.relative)
+    const stagedRelative = path.join(path.dirname(move.relative), '.' + path.basename(move.relative) + '.delete-' + transaction.requestId)
+    const staged = await safePath(roots[move.area], stagedRelative)
+    return { from, staged }
+  }
+
+  async restore(transaction) {
+    for (const move of [...transaction.moves].reverse()) {
+      const { from, staged } = await this.locations(transaction, move)
+      if (!await fs.lstat(staged).catch(missing)) continue
+      if (await fs.lstat(from).catch(missing)) throw new PmError('conflict', '删除恢复遇到同名新文件，请先核对目录。')
+      await fs.rename(staged, from)
+    }
+    const productsFile = await safePath(this.pm.knowledgeDir, '.sa-knowledge-control/products.json')
+    const current = await readOptional(productsFile)
+    if (current !== transaction.productsBefore) {
+      if (current !== transaction.productsAfter || transaction.productsBefore === null) throw new PmError('conflict', '知识关联索引已变化，删除恢复停止。')
+      await atomicWrite(productsFile, transaction.productsBefore)
+    }
+    transaction.phase = 'rolled-back'
+    await this.save(transaction)
+  }
+
+  async finish(transaction) {
+    try {
+      for (const move of transaction.moves) {
+        const { staged } = await this.locations(transaction, move)
+        await fs.rm(staged, { recursive: true, force: true })
+      }
+    } catch {
+      throw new PmError('conflict', '需求已删除，文件清理未完成，请重试清理。')
+    }
+    transaction.phase = 'complete'
+    // Completed receipts retain identity and counts only, so retries are safe.
+    delete transaction.moves
+    delete transaction.productsBefore
+    delete transaction.productsAfter
+    await this.save(transaction)
+    return transaction.result
+  }
+
+  async recover() {
+    const directory = await safePath(this.pm.root, CONTROL)
+    const names = await fs.readdir(directory).catch(error => { if (error.code === 'ENOENT') return []; throw error })
+    if (!names.length) return
+    await this.locked(async () => {
+      for (const name of names.filter(name => REQUEST.test(name.replace(/\.json$/, '')))) {
+        const transaction = JSON.parse(await fs.readFile(await safePath(directory, name), 'utf8'))
+        if (!['prepared', 'committed'].includes(transaction.phase)) continue
+        const state = await loadState(this.pm.root)
+        if (transaction.phase === 'committed' || !state.requirements[transaction.id]) await this.finish(transaction)
+        else await this.restore(transaction)
+      }
+    })
+  }
+
+  async delete(id, input) {
+    await this.ready
+    if (input?.confirmed !== true || typeof input.expectedFingerprint !== 'string') throw new PmError('bad_input', '请先核对删除范围并确认删除。')
+    return this.locked(async () => {
+      const file = await this.journalFile(input.requestId)
+      const saved = await readOptional(file)
+      let transaction = saved && JSON.parse(saved)
+      if (transaction && (transaction.id !== id || transaction.fingerprint !== input.expectedFingerprint)) throw new PmError('conflict', '删除请求与原确认范围不一致。')
+      if (transaction?.phase === 'complete') return transaction.result
+      if (transaction?.phase === 'committed') return this.finish(transaction)
+      if (transaction?.phase === 'prepared') {
+        const state = await loadState(this.pm.root)
+        if (!state.requirements[id]) return this.finish(transaction)
+        await this.restore(transaction)
+      }
+      const plan = await this.scan(id)
+      if (plan.fingerprint !== input.expectedFingerprint) throw new PmError('conflict', '需求或关联资料已变化，请刷新删除清单后重新确认。')
+      transaction = { schemaVersion: 1, requestId: input.requestId, id, roots: plan.roots, fingerprint: plan.fingerprint, phase: 'prepared',
+        moves: plan.targets.map(({ area, relative }) => ({ area, relative })), productsBefore: plan.productsBefore, productsAfter: plan.productsAfter,
+        result: { deleted: true, id, code: plan.code, totals: plan.totals } }
+      await this.save(transaction)
+      try {
+        for (const move of transaction.moves) {
+          const { from, staged } = await this.locations(transaction, move)
+          if (await fs.lstat(staged).catch(missing)) throw new PmError('conflict', '存在待恢复的删除文件，请先完成恢复。')
+          await fs.rename(from, staged)
+        }
+        for (const target of plan.targets) {
+          const { staged, from } = await this.locations(transaction, target)
+          const targetRoot = plan.roots[target.area]
+          const stagedSnapshot = await tree(targetRoot, path.relative(targetRoot, staged))
+          if (fingerprint(JSON.stringify(stagedSnapshot)) !== fingerprint(JSON.stringify(target.snapshot)) || await fs.lstat(from).catch(missing)) {
+            throw new PmError('conflict', '关联文件在删除期间发生变化，请重新核对。')
+          }
+        }
+        if (plan.productsBefore !== plan.productsAfter) await atomicWrite(await safePath(this.pm.knowledgeDir, '.sa-knowledge-control/products.json'), plan.productsAfter)
+        const state = await loadState(this.pm.root)
+        delete state.requirements[id]
+        await saveState(this.pm.root, state)
+      } catch (error) {
+        const state = await loadState(this.pm.root)
+        if (!state.requirements[id]) return this.finish(transaction)
+        await this.restore(transaction)
+        throw error
+      }
+      transaction.phase = 'committed'
+      await this.save(transaction)
+      return this.finish(transaction)
+    })
+  }
+}
+
+export function installRequirementDeletion(pm) {
+  const deletion = new RequirementDeletion(pm)
+  deletion.ready.catch(error => console.error('[sa-deletion] 恢复未完成：', error.message))
+  pm.requirementDeletion = deletion
+  // Share one workspace write guard with existing state writers. Delivery and
+  // knowledge writers retain their own locks, also held by cascade deletion.
+  for (const name of ['createRequirement', 'updateRequirement', 'startRequirement', 'archive', 'beginDocumentArchive', 'recordDocumentArchive', 'saveArtifact', 'mutateAnnotation', 'addThread', 'updateThread', 'saveSource', 'saveSettings']) {
+    const original = pm[name]
+    if (original) pm[name] = async (...args) => { await deletion.ready; return withKnowledgeLock(pm.root, () => original(...args)) }
+  }
+  for (const name of ['loadState', 'findRequirement', 'viewAll', 'viewRequirement']) {
+    const original = pm[name]
+    if (original) pm[name] = async (...args) => { await deletion.ready; return original(...args) }
+  }
+  for (const [service, methods] of [[pm.deliveryLibrary, ['capture', 'saveCandidates']], [pm.knowledgeWorkflow, ['approve']], [pm.deliveryLibrary.workflow, ['approve']], [pm.productContext, ['save']]]) {
+    for (const name of methods) {
+      const original = service?.[name]
+      if (original) service[name] = async (...args) => { await deletion.ready; return original.apply(service, args) }
+    }
+  }
+  pm.deleteRequirement = (id, input) => deletion.delete(id, input)
+}