需求变更后，哪些设计已经不可信？用 DocuMan 把 AI 生成、追踪链与复核任务放回同一张工程台账
在复杂系统里，真正危险的往往不是“需求还没写完”，而是某条上游需求已经改了，设计说明、接口表、测试计划却仍然看起来完整。文档彼此独立、链接靠人脑记忆时，团队很难回答一个看似简单的问题：这次修改究竟影响了哪些下游设计，谁需要重新确认？
DocuMan 是 bbayer 发布的一个需求管理与系统工程工作区。它把源规格的导入、AI 派生文档、需求条目、版本快照和追踪链接放在同一个 Next.js 应用中。项目 README 将其定位为面向 MIL-STD-498 以及 IEEE/ISO 文档基线的工作流；不过仓库目前未提供可识别的 LICENSE 文件，因此这里把它当作一个可审阅源码的原型/工程项目，而不把它称为开源软件。
它最值得拆开的地方并非“让模型写文档”，而是试图把 AI 输出变成可回溯、可标记、可复核的工程对象。
从一段规格到一组工程对象
传统做法里，产品或系统规格常以 PDF、DOCX、TXT 进入项目。随后有人把段落复制到 SRS、SSDD、接口说明和测试计划，再分别维护表格。这样做的代价是，文档的展示层很丰富，数据层却很薄：需求编号、上下游关系、版本和审查状态没有稳定结构。
DocuMan 的 README 描述了三段派生过程。第一段先对整份文档做全局分析，提取摘要、术语表，并把父需求归并为系统功能；第二段先建立范围、参考资料以及架构/运行/安全决策等全局基线；第三段再细化功能架构。重点是先有跨文档的上下文，再展开局部条目，而不是把每条需求孤立地交给模型续写。
仓库中的 Prisma schema 也能看到这种意图：Document 记录原始文档与派生文档的父子关系；Requirement 保存条目编号、显示 ID、层级和排序；DocumentVersion、RequirementVersion 分别保存文档与需求粒度的版本；GlossaryTerm 则把术语限定在项目范围内。AI 生成的内容不是唯一事实来源，而是与这些结构化记录一起保存。
这不能保证模型不犯错。它解决的是另一个问题：一旦发现错误，团队至少能定位到某个需求、某个版本和某段派生内容，而不是在一份静态导出文件里全文搜索。
把“影响分析”设计成数据，而不是会议纪要
DocuMan 的追踪链接有三种已在 schema 中定义的关系：DERIVED_FROM、SATISFIES、RELATED_TO。例如，一条设计需求由系统需求派生，可建立 DERIVED_FROM；一个实现或验证条目满足某项需求，可建立 SATISFIES；仅存在关联但没有严格派生关系时，则使用 RELATED_TO。
更关键的是 isSuspect 标记。上游规格被编辑后，相关下游链接可被标成待确认，而不是自动假定下游内容仍正确。这个动作看似朴素，却改变了变更后的默认状态：默认不再是“文档已同步”，而是“关系存在，但需要人工确认”。对于涉及安全、接口兼容性或合规证据的系统，这种保守默认值通常更可靠。
可以把一个简化的追踪链理解为：
SSS-001（系统级需求）
└─ DERIVED_FROM → Fn-001（系统功能）
└─ SATISFIES → SDD-4.2（设计段落）
└─ RELATED_TO → STP-07（测试过程）
当 SSS-001 改动时，正确的后续动作不是让 AI 无提示地重写所有文档，而是先沿链接找到 Fn-001、SDD-4.2 与 STP-07，把它们列入审查队列。审查者可以确认设计仍成立、修改设计、补充测试，或删除已经失效的关系。AI 在这里适合协助生成差异说明和初稿，但不应替代最终的工程签核。
为什么“功能表”比大段生成文本更可审
README 中给出的功能架构表采用固定四行：功能名称、功能描述、输入/输出，以及上游需求引用。固定格式的价值不是排版整齐，而是把评审问题强制落到可检查字段上：功能到底做什么？输入输出是否写清了数据子字段？它对应哪几条父需求？
例如，团队可以在设计评审中要求每个功能都显式列出来源：
Fn-014：姿态解算 描述：融合传感器测量值，输出控制所需姿态估计。 输入/输出：imu_samples、timestamp → attitude, confidence 上游需求：SSS-021、SSS-034
这不是 DocuMan 的可直接复制 API，而是按其 README 所述“四行功能表”和追踪引用原则构造的评审示例。它的作用是暴露空洞生成：如果模型只能写出“进行智能处理”，却给不出输入、输出和来源需求，条目就不应进入已发布设计。
同理，接口汇总表和信号数据字典应把接口 ID、源/目标子系统、协议、数据描述，以及数据类型、范围、载荷子字段、更新频率等信息分列。模型可以帮助从原始规格提取候选字段，但协议名、范围、单位、时序和安全约束必须回到源规格或接口负责人处核对。
在本地先跑通一个可验证闭环
DocuMan 使用 Next.js、Prisma、Mermaid、Vercel AI SDK，并接受 OpenAI 兼容端点。README 的开发环境默认使用 SQLite；schema 注释说明，如需 PostgreSQL，要同步调整 Prisma 数据源 provider 与 DATABASE_URL。下面的命令依据仓库当前 package.json 和 README 整理，其中仓库默认分支为 master：
git clone https://github.com/bbayer/DocuMan.git cd DocuMan npm install cat > .env <<'EOF' DATABASE_URL="file:./dev.db" AI_API_BASE_URL="https://api.openai.com/v1" AI_API_KEY="替换为你自己的密钥" AI_MODEL="gpt-4o" EOF npm run db:push npm run dev
启动后可先用一个小型、无敏感数据的规格验证流程：导入源文件；检查抽取后的条目层级和编号；人工补全关键术语；让系统生成一份派生文档；抽查几个功能表的输入输出与引用；然后故意修改一条上游需求，确认关联项是否进入待审状态。最后再执行构建和 TypeScript 检查：
npx tsc --noEmit npm run build
这里有三个边界必须提前接受。第一，AI API 密钥、原始规格和导出文件都可能是敏感资产，生产环境不能沿用示例中的本地 SQLite 与明文 .env 管理方式。第二，标准模板能让文档结构更一致，不代表自动满足某个合同、认证或组织流程；标准映射与最终合规结论仍需由负责人员确认。第三，SUSPECT 是复核信号，不是自动修复：链接完整并不能证明下游设计已被正确更新。
还应把“可追踪”与“可验证”分开。系统可以记录某条需求在何时、被谁修改，也可以把关联的下游内容列出来；但是否真的覆盖了需求意图、是否引入了新的安全风险，仍然依赖领域审查。一个实用的团队规则是：对每个被标记的下游项，审查结果必须明确写为“无需修改”“已修改并复测”或“关系已失效”，而不是只把标记清掉。这样，追踪链才会沉淀为变更决策的证据，而非越来越多却无人阅读的连线。
对于 AI 派生的内容，建议再加一层输入约束。将项目术语、缩写、接口单位、禁止臆测的字段以及文档章节目标写入项目上下文；生成后优先审查那些最容易被语言流畅性掩盖的内容：量纲、边界条件、失败处理、权限主体和验收条件。DocuMan 的项目模型中包含项目级 aiContext 与术语记录，适合作为这类约束的承载位置。小批量试运行时，可以挑选十条左右有明确验收条件的需求，人工保留基线，然后比较派生结果是否保留了 ID、约束和来源引用。若这些基本字段都不稳定，就不应把生成范围扩展到整套设计文档。
最后，图表也需要纳入同一条变更链。README 描述了 Mermaid 的可编辑代码与 SVG 视图切换，以及 PDF/HTML 导出。图能快速暴露组件边界和数据流矛盾，却不能成为脱离文本的“漂亮附件”：每条关键数据流最好能回指接口或需求 ID。否则需求改动后，表格可能被重新生成，架构图却仍停留在旧假设上。
适用场景与取舍
如果团队只需要写一份短 PRD，建立完整追踪链可能比文档本身更昂贵。DocuMan 更适合需求多层派生、接口和验证材料需要同步、且变更成本较高的系统工程场景，例如软硬件协同、设备控制或需要正式评审的项目。
采用这类工作区的核心取舍是：前期必须约束需求 ID、文档类型、链接语义和审查责任人；换来的不是“AI 自动完成系统设计”，而是变更发生时能给出一份可审计的影响清单。对于已经被 AI 生成速度放大的文档产出而言，这份清单往往比再生成几页文字更有价值。
相关链接