第5章 D2E（一）：五阶段流水线与时序
D2E（Document-to-Engineering，文档到工程化）是四支柱体系中负责"知识生产"的流水线。它的使命是把形态各异、质量参差、散落各处的原始文档，转化为机器可消费、人可审计、系统可复用的结构化知识单元。
5.1 为什么需要一条专门的生产线
在 AI 辅助研发语境下，知识不是"写出来的"，而是"被提炼出来的"。一份需求文档里混杂着事实、推测、过期信息与个人偏好；一次架构评审录音里同时包含已决议项与未决争议。若直接把这些原始材料整段塞给模型，等于把噪声当信号。D2E 的价值，正是建立一条"去噪---结构化---校验---工程化"的可复现通道，使每一次知识生产都可被重复、被追溯、被改进。
5.2 五阶段定义
D2E 由五个顺序阶段构成，每阶段的输出是下一阶段的输入，形成强约束的接力：
- 阶段一 · 分析（Analyze）：对待处理文档做类型识别与边界切分。区分"规范类""决策类""叙事类""数据类"文档，确定抽取粒度。
- 阶段二 · 抽取（Extract）：从原文中识别知识候选------定义、约束、决策、风险、依赖。抽取不追求全覆盖，而追求"高置信候选优先"。
- 阶段三 · 结构化（Structure） ：将抽取结果映射到统一 schema，赋予
doc_id、归属模块、适用context标签，生成初步知识单元。 - 阶段四 · 校验（Verify） ：执行可信优先三检------缺失标
[待填写]、不确定标unverified、冲突进入conflicts表。校验是质量闸门。 - 阶段五 · 工程化（Engineer） ：将结构化知识写入 HDS，建立
source_ref溯源链与deps依赖边，形成可检索、可装配的持久资产。
5.3 时序与可复现性
五个阶段必须按序执行，不可跳跃。其重要意义在于"可复现"：当源材料更新时，只需从对应阶段重跑，而非从头手搓。可复现性也是审计的基础------任何一条知识都能反推"它来自哪份文档、经过哪次抽取、被谁校验"。
5.4 PCC 的中枢角色
贯穿五阶段的枢纽是 PCC（项目上下文卡片，Project Context Card）。PCC 不是某一阶段的产品，而是全流程共享的"工作画布"：抽取阶段往里填充事实，校验阶段往里标注冲突与缺口，工程化阶段把它落盘为 HDS 的首个知识单元。PCC 作为单一真相源的雏形，在 D2E 内部即已确立"一事实、一处定义、一处溯源"的纪律。
第6章 D2E（二）：PCC 中枢、领域适配与零依赖工具链
6.1 PCC 的结构
PCC 是一份结构化卡片，核心字段包括：
doc_id：全局唯一标识，命名含项目缩写、模块、序号。source_ref：溯源引用，指向原始材料的具体位置（文件+章节/行号）。conflicts：冲突表，记录与其他知识单元的不一致及处置状态。gaps：缺口表，记录已知缺失或待确认项。context：适用场景标签，供投放侧按场景筛选。deps：依赖边，声明本单元依赖哪些其他单元。
source_ref、conflicts、gaps 三者共同构成可信优先原则的落地载体：前者保证可追溯，中者保证矛盾可见，后者保证无知被显式管理。
6.2 领域适配策略
D2E 不假设所有文档同质。它采用" schema 可插拔"的适配方式：对医疗、金融、嵌入式等不同领域，提供领域 schema 模板，规定该领域必须抽取哪些实体类型（如金融需抽取合规约束，嵌入式需抽取时序约束）。适配发生在阶段三（结构化），前序的抽取仍通用，后序的校验仍通用，仅中间映射因域而异。这种"两端通用、中段可插拔"的设计，使 D2E 在保持统一纪律的同时具备横向扩展性。
6.3 组件规范
每个阶段对应一个明确职责的组件，组件间通过标准数据结构交接。规范强调：组件无状态或可序列化状态；组件输入/输出 schema 公开；组件可独立测试。这使 D2E 流水线可逐步替换单个阶段而不破坏整体。
6.4 零依赖工具链
D2E 的参考实现坚持零依赖：仅使用 Python 标准库加一个最小 YAML 解析器。其动机有三：第一，可审计------没有隐藏的第三方行为；第二，可迁移------不绑定特定运行环境；第三，可长期存活------不惧怕依赖弃维护。在 AI 工具链飞速迭代、依赖半衰期极短的今天，零依赖是一种刻意的反脆弱选择。
核心脚本 context_card.py 负责 PCC 的读写与校验，是整个生产线的"心脏"。它被设计成可被人工直接检视的文本格式，而非黑箱二进制。
6.5 设计权衡
D2E 在"自动化覆盖度"与"可信度"之间主动选择了后者：它宁可产出带 [待填写] 的不完整卡，也不编造填充。在与业界"全自动文档解析"方案对比时，D2E 的优势不在速度，而在可信任与可审计------这对研发这类高风险决策场景是更优的取舍。
6.6 误用防御
D2E 最易被误用的方式是"把它当一次性转换器"。正确用法是把它当"持续运行的知识工厂"：源材料变更即触发局部重跑，知识库随项目呼吸。另一误用是跳过校验阶段以图快，这会让冲突与缺口被 silently 吞没，直接破坏 HDS 的单一真相源性。体系通过把校验设为不可跳过闸门来防御此类误用。
5.5 五阶段的实例推演
为使流水线可感，这里用一个微型实例贯穿五阶段。假设源材料是一段需求评审纪要："用户导入大文件时界面卡死，决定改用分块上传；但李工指出需兼容旧客户端，暂定分两块。"
- 分析：识别为"决策类 + 约束类"混合文档，抽取粒度到"单条决策"。
- 抽取：候选事实①分块上传决策；②旧客户端兼容约束（未决）。
- 结构化：生成单元 U1（决策：分块上传）、U2（约束：兼容旧客户端，状态 unverified）。
- 校验：U2 因"暂定"被标 unverified，进入复核队列而非当作事实；U1 与 U2 间潜在冲突（分块可能破坏旧客户端）记入 conflicts。
- 工程化：U1、U2 写入 HDS，U1 带 source_ref 指向纪要段落，U2 进 gaps 表待确认。
这个微小例子已完整展示了"不编造、标 uncertain、记冲突"的可信优先实操。
5.6 阶段间契约与失败传播
五阶段之所能"可复现"，关键在于阶段间以结构化数据契约交接，而非自由文本。阶段二的抽取产出必须能被阶段三的 schema 校验；若某候选无法映射，则降级为"待人工结构化"而非强行归类。这种"宁卡勿错"的契约设计，使任何阶段失败都不会静默污染下游------失败时流水线停在当前阶段并报警，而非带着错误继续。失败被显式管理，是可复现性的前提。
6.7 PCC 字段级实例
一个真实形态的 PCC 片段（示意）：
- doc_id: proj_alpha/decision/0142
- source_ref: 评审纪要_2026Q2.md#3.2
- status: active
- conflicts: proj_alpha/constraint/0090（分块上传 vs 单连接超时约束）
- gaps: 旧客户端最低版本未确认
- context: upload, compatibility
- deps: proj_alpha/constraint/0090
注意 conflicts 与 deps 都用 doc_id 精确引用，使任何阅读者都能跳转核验。这种"用标识符而非自然语言描述关系"的做法，是把知识变成可计算图的关键一步。
6.8 领域 schema 插拔实例
以金融领域为例，其领域 schema 在通用抽取之外，强制要求抽取"合规条款引用""风控阈值""审计留存期"三类实体。当 D2E 处理一份合规说明时，阶段三除通用映射外，额外把这些金融专属实体填入扩展字段。前序抽取与后序校验完全不变------这正是"两端通用、中段可插拔"带来的低成本扩展。一个领域模板的落地，通常只需新增一份 schema 描述，而非重写流水线。
6.9 工具链的"可裸眼审阅"属性
零依赖并非炫技，而是为了"可裸眼审阅"。一份 PCC 是带 front matter 的纯文本，任何人都可在不装任何软件的情况下打开、读懂、质疑。这在安全敏感或审计严格的场景至关重要：你不必信任某个黑箱解析器"说它抽对了"，你直接看文本即可验证。工具越轻、越透明，组织的信任成本越低------这是反脆弱在工程上的具体兑现。
6.10 常见误用场景清单
除正文提到的两类误用，还需警惕：①把 PCC 当最终文档而非"工作画布"，导致过早冻结、拒绝演化；②在 deps 中随意互引形成环，使检索陷入死循环；③用自然语言而非 doc_id 描述依赖，使关系无法被机器解析。体系通过校验脚本（检测环、检测重复 id、检测孤儿引用）在写入时即拦截这些误用，把纪律固化进工具。
5.7 抽取策略的置信度分级
抽取阶段不追求"全捞"，而追求"高置信优先"。每条候选事实被赋予置信度：高（原文明确陈述，如"决定采用分块上传"）、中（可合理推断，如"旧客户端需兼容"隐含约束）、低（仅疑似，如某句语气暗示但未明说）。高置信直接进结构化；中置信进结构化但标 unverified 待确认；低置信不入单元，仅记于抽取日志供人工复查。置信度分级使 D2E 在"覆盖率"与"准确率"间取得平衡------宁可漏掉不确定的，也不把猜测当事实，这正是可信优先在抽取相位的具体操作。
5.8 结构化 schema 的形式化
结构化阶段将抽取结果映射到统一 schema。schema 定义字段、类型、约束，例如决策类单元须含 {statement, rationale, alternatives_considered, status}。schema 不仅是格式，更是"什么算一条合格知识"的契约。形式化的好处是可机检：写入前脚本校验必填字段，缺失即拒收。schema 还是领域适配的挂载点------金融领域 schema 在通用字段外增 {compliance_ref, risk_threshold}，实现"中段可插拔"。形式化使知识生产从手艺变为工程。
5.9 校验三检的严格次序
校验阶段的三检有严格次序：先查缺失（必填为空→待填写），再查不确定（中置信未确认→unverified），最后查冲突（与他单元矛盾→conflicts）。次序不可颠倒，因为缺失可能衍生不确定，不确定可能掩盖冲突。三检是质量闸门，不可跳过；跳过即让残缺与矛盾静默流入 HDS，腐蚀单一真相源。体系把校验设为"不可绕过"的硬门禁，从机制上杜绝了"为快而糙"的诱惑。
6.11 工具链的可测试性设计
零依赖工具链的另一收益是可测试性。context_card.py 的每个函数（解析、校验、写入）都可被独立单测；HDS 四脚本的契约（输入文件→输出文件）可被断言。由于无第三方黑箱，测试可靠且快。可测试性使"改了某段逻辑是否破坏其他"可被自动化守护，这是长期维护的安全网。在 AI 工具链动荡、依赖频繁弃维护的当下，自建可测试的核心，比依赖外部库的"便利"更经得起时间。
6.12 D2E 与 CI 的集成
D2E 不应是一次性离线任务，而应嵌入 CI。建议做法：当源材料（如需求 doc、评审记录）入库变更，CI 触发 D2E 局部重跑对应阶段，增量更新 HDS，而非全量重来。增量重跑依赖阶段间的数据契约与版本标记------这正是五阶段可复现设计的回报。集成 CI 后，知识生产从"项目里程碑事件"变为"持续进行的副作用"，大幅降低维护的心理门槛与遗忘概率。
6.13 领域适配的成本收益
领域 schema 插拔的边际成本极低（一份描述文件），收益却随领域专业度上升。在金融、医疗等强约束领域，缺了领域 schema，通用抽取会漏掉最具价值的合规与风险实体，使体系在该领域"半身不遂"。因此适配策略是：通用相位保底，领域相位决定上限。判断是否需要某领域 schema 的简单标准：该领域是否存在"通用抽取抓不到、却极其重要"的实体类型------若有，就必须插拔。
6.14 D2E 的局限与诚实声明
D2E 不解决"原始材料本身错误"的问题：若源文档写错，抽取再规范也只是把错误工程化。体系对此的回应不是假装覆盖，而是用 source_ref 让错误可追溯、用 unverified 让不确定显式，使错误更早暴露、更易归责。承认这一局限，是可信优先在元层面的自律------连对工具自身的描述，也保持诚实。一个敢说自己"不创造知识、只工程化已有知识"的体系，反而更值得托付。
6.15 工具链代码结构的深度说明
零依赖工具链并非"几行脚本凑合"，而是有清晰内部分层的。以 context_card.py 为例，其内部结构分为四层：解析层（最小 YAML 解析器，仅处理 front matter 所需的子集，避免引入 PyYAML 依赖）、模型层（PCC 的纯数据结构与不变式检查，如 doc_id 唯一、source_ref 非空）、操作层（读写、合并、废弃等命令）、CLI 层（参数解析与友好报错）。四层之间单向依赖，任一层可独立测试。这种"看似简单、内部分层"的设计，使脚本虽小却稳健，也便于新人读懂------可读性本身就是零依赖承诺的一部分。
6.16 一个真实的抽取---校验案例
某支付团队用 D2E 处理一份风控规则文档。抽取阶段识别出规则"单笔限额 5 万"与"日累计 20 万"，置信度高，直接结构化；同时识别出一句"大额交易需二次确认"，但文档未明确"大额"阈值，置信度中，标 unverified 进入复核。校验阶段发现：另一条历史决策"VIP 用户单笔限额 50 万"与"单笔限额 5 万"在适用对象上冲突，自动记入 conflicts 并建议 owner 澄清适用域。最终落库的单元中，确定项可直接投放，unverified 项在 Pack 中显式标注"待确认"，conflicts 项触发人工澄清。整个过程没有编造任何一个数字，却把一份模糊文档变成了可信任、可消费的知识------这正是 D2E 价值的浓缩体现。
6.17 D2E 在需求变更中的角色
需求变更是最易产生知识漂移的场景。传统模式下，需求文档改了，散落各处的相关设计、测试、约束却未必同步，留下大量隐性矛盾。D2E 的应对：把每条需求分解为带 doc_id 的知识单元，并建立需求→设计→测试的 deps 链。当需求变更，沿 deps 自动定位受影响单元，触发局部重跑与冲突检查，将"被动发现矛盾"变为"主动提示影响面"。这把需求工程的追溯能力，从文档层面延伸到了运行时上下文层面，是 D2E 相对传统文档工程最实质的超越。
6.18 与文档工程的哲学差异
传统文档工程追求"写出好文档"，隐含假设是"人会去读、会去用"。D2E 的假设更冷峻：人不会系统地去读，文档若不能被机器直接消费就等于零。因此 D2E 的产出不是给人读的漂亮文档，而是给装配器消费的struct 化单元。这一哲学差异决定了二者的评价标准不同：文档工程看"表述是否清晰"，D2E 看"是否可被可追溯地结构化与可信标注"。理解这一差异，才能不把 D2E 误用为"又一个文档模板"，而把握其"知识工厂"的本质。
6.19 领域适配的反模式
领域适配有两类反模式需警惕：①过度适配------为每个细微差异都新建 schema，导致 schema 泛滥、维护崩塌；②欠适配------强行用通用 schema 套专业领域，漏掉关键实体。健康做法是"通用打底、关键差异化才插拔"：先问"该领域是否有通用抽取抓不到的、却极其重要的实体类型"，仅在有明确肯定时才建领域 schema。适配的边界判断，是 D2E 落地成熟度的重要标志。
6.20 生产吞吐与质量的平衡
体系初期常陷入"为质量牺牲吞吐"或反之。平衡的艺术在于：用置信度分级把"不确定"与"确定"分流------确定的快速入库（保吞吐），不确定的进复核队列（保质量），二者不互相阻塞。D2E 不要求每条知识都完美才入库，而要求每条都"诚实地标注了自己的状态"。这种"状态透明"使吞吐与质量从零和博弈变为可并行------这正是可信优先在工程调度层面的妙用。
6.21 生产质量的前置指标
与其事后查错，不如前置预防。建议两个前置指标：抽取置信度分布（中/低置信占比过高，提示源材料模糊，应回头找人澄清而非硬抽）、单元字段完整度（必填缺失率，提示 schema 设计或抽取不足）。前置指标使质量在"写入前"可被干预，而非"写入后"才发现失真。前置预防是质量工程的常识，体系把它落到 D2E 的每个阶段入口，使"质量内建"而非"质量检验"。
6.22 D2E 与人大规模协作的模式
当多人并行用 D2E 处理不同文档，需防"各写各的、口径不一"。模式：共享同一份 schema 与领域模板（由守护者维护），各自产出的 PCC 经统一校验后合入 HDS；冲突由 conflicts 机制自动暴露，守护者协调仲裁。多人协作的关键纪律是"模板统一、校验统一、仲裁统一"，三者缺一即会分叉。大规模协作模式使 D2E 从个人工具升级为团队流水线，也是其能支撑组织级知识生产的必要条件。
6.23 抽取中的"过度结构化"陷阱
结构化是好事，但过度结构化会反噬：为填 schema 而强行拆解本应整体理解的知识，反而丢失语义。陷阱信号：某单元被拆成十余个碎片字段，却无人能从中还原原意。 antidote：schema 只定义"必要字段"，允许保留"自由文本摘要"字段承载整体语义，不被强制拆解。结构化的目的是"可检索、可追溯"，而非"消灭自然语言"。把握这一目的，才能避免为结构而结构的异化。
6.24 工程化阶段的原子性设计
工程化阶段（写 HDS）必须原子：要么整单元写入成功，要么完全不写，绝不允许"写一半"。原子性靠"先写临时文件、校验通过后原子替换"实现。非原子写入会在崩溃时留下半截单元，污染 HDS。原子性是数据持久化的基本纪律，体系把它作为工程化阶段的硬性要求，体现"把可靠性写进流程"的一贯立场。小事见态度------对原子性的坚持，反映体系对"数据可信"的零容忍。
6.25 D2E 的增量 vs 全量
D2E 应优先增量：源材料变更时，仅重跑受影响单元的相关阶段，而非全量重来。增量依赖阶段间的数据契约与单元版本标记------这正是五阶段"可复现"设计的回报。全量仅在 schema 大改或首次导入时必要。增量使知识生产"持续、低扰、可负担"，是把 D2E 嵌入日常流程而非偶发事件的关键。全量成本高、易被人嫌弃而弃用；增量便宜、可常跑，才是可持续的生产方式。
6.26 D2E 章节的收束
收束 D2E：它的本质不是"文档转换工具"，而是"知识工厂"------以可复现、可溯源、可信标注的纪律，把异构原始材料持续转化为机器可消费、人可审计的结构化知识。PCC 是其枢纽，五阶段是其流水线，零依赖是其反脆弱基底，可信优先是其灵魂。理解 D2E，须理解它解决的不是"快"，而是"可信且可复现"------在研发这类高风险决策场景，后者远比前者珍贵。D2E 是四支柱中"生产"相位的回答，也是后续沉淀、投放、前瞻得以成立的前提。
6.27 D2E 的产出验收清单
D2E 每单元产出须过验收清单：①有唯一 doc_id；②必填字段完整；③source_ref 指向真实位置；④不确定项已标 unverified；⑤冲突已入 conflicts；⑥deps 无环、无孤儿。清单化验收使质量不依赖个人自觉，而是可勾选的硬门槛。验收清单是"把原则写入流程"在 D2E 末端的最终落地------一道清单，挡住九成失真。小工具，大价值，是工程纪律的典型样貌。
6.28 与人工写作的协作边界
D2E 不取代人写文档，而是接管"从文档到结构化知识"的机械部分，把人解放去写"真正需要人判断"的部分（如决策 rationale、权衡说明）。协作边界：机器做抽取、 structuring、校验的脏活；人做裁决、撰写难点、确认缺口。清晰边界使人不觉得被替代，反而因卸下重复劳动而欢迎体系。协作边界的友好，是采纳顺利的社会学前提------工具要让人觉得"帮我"，而非"替我"。
6.29 D2E 的成本显性化
D2E 运行有成本（人力写 context、机器跑流水线），须显性化以做取舍。成本显性化方式：记录每单元的生产耗时与复用次数，计算"单次复用成本=生产耗时/复用次数"。当某类知识复用极少，提示"不值得工程化"，应降级为普通文档。成本显性化防止"为工程化而工程化"------体系的实用主义立场，要求每一份工程化投入都有可核算的回报预期，哪怕粗略。
6.30 D2E 章节的再收束
再收束一次：D2E 的价值，短期看是"知识可被检索"，中期看是"知识可被信任"，长期看是"知识可被演化"。三层价值递进，对应体系从工具到资产到活体的升级。理解 D2E，不要只看见五阶段流水线这一"形"，更要看见可信优先与可复现这一"神"------形可变（阶段可增删），神不可丢（可信与可溯）。抓住神，D2E 才能在你的组织中真正活起来，而非又一套被束之高阁的规范。
6.31 D2E 的"可解释生产"价值
D2E 的每一单元都带 source_ref 与置信度，使其生产"可解释"------任何人可追问"这条知识从哪来、多确定"。可解释生产在审计、教学、信任建立上价值巨大：新人可通过溯源理解"为何如此"，审计方可核验"是否杜撰"。可解释性把知识生产从黑箱变为白箱，是体系可信任的底层支撑。它呼应可信优先------不仅标注状态，还标注来源，让诚实贯穿到生产的每一环。
6.32 领域 schema 的治理
领域 schema 本身需治理：谁可新增、如何评审、何时废弃。无治理的 schema 会泛滥（每人自建一套），反而破坏统一。治理规则：schema 由守护者维护，新增须说明"捕获了哪类通用抽取抓不到的关键实体"，版本化演进。schema 治理是"核心最小、外围可换"在领域层的落实------外围（领域适配）可扩展，但扩展须受控，避免失控。治理使适配既灵活又有序。
6.33 D2E 的长期价值曲线
D2E 的长期价值呈复利曲线：初期（知识少）收益有限，易被质疑"值不值"；中期（知识积累）复用率上升，边际成本下降；长期（知识成资产）复利显著，组织韧性增强。价值曲线的启示：熬过初期平淡，才能收获长期复利；半途而废则两头落空。D2E 的采纳者须有"长期主义"的预期与耐心------它卖的不是速效药，而是慢功夫的年金。
6.34 D2E 与"文档即代码"的同构
D2E 的理念与"文档即代码（Docs as Code）"同构：知识单元像代码一样有版本、有评审、有 CI、可回滚。同构使组织可复用成熟的工程实践（分支、PR、审查）来管理知识，而非另起炉灶。复用工程实践降低采纳成本，也借力已被验证的协作范式。同构提示：知识工程不必发明新范式，把软件工程的好东西延伸到知识域，便是 D2E 的聪明之处。
6.35 D2E 章节的终极收束
终极收束 D2E：它是四支柱的"生产相位"，以五阶段流水线、PCC 中枢、领域适配、零依赖工具链，把异构原始材料转化为可信、可溯、可复用的结构化知识。它的灵魂是可信优先（不编造、标不确定、记冲突），它的骨架是可复现（阶段契约、增量重跑），它的底色是反脆弱（零依赖纯文本）。D2E 不解决"原始材料错误"这一根本局限，但让错误更早暴露、更易归责。理解 D2E，须抓住"可信与可溯"这一神，而非仅见"流水线"这一形------抓住神，它才能在你的组织中真正活起来。