Yuxi 工程事故复盘Postmortem机制门槛判定、七段式模板与安全网闭环实践【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi事故复盘Postmortem是 Yuxi 工程信任体系中的收尾环节它只针对已经逃逸、且具备高影响、系统性或高再发现成本的真实缺陷把一次失败转化为可复现的负向案例、更早的拒绝机制和可问责的防复发措施。本文以 docs/develop-guides/postmortems/README.md 与配套的 TEMPLATE.md 为骨架结合仓库中scripts/verify_engineering_contracts.py的机械校验逻辑与 工程信任体系 的证据等级讲解 Yuxi 何时必须写复盘、每份复盘必须包含哪些可验证事实以及复盘如何与决策记录、Gate 和测试形成闭环。读完你可以直接照模板为一次逃逸事故撰写合格的 Postmortem并通过项目自带的只读校验命令确认结构完整。复盘门槛什么样的缺陷才值得形成正式事故文档Yuxi 对事故文档的使用是克制的。postmortems/README.md明确限定Postmortem 只用于已经逃逸、且同时具有较高影响、系统性或高再发现成本的缺陷。普通 bug、开发中被测试及时发现的问题、无用户/数据/安全/可用性影响的局部错误不强制复盘但仍需保留与风险相称的回归证据。满足以下任一条件由修复负责人和 Reviewer 共同判断是否达到门槛造成安全、权限、数据完整性、数据丢失或外部副作用风险关键用户链路或生产可用性受到显著影响多个模块、入口或部署会以同一机制重复失败既有测试、Gate 或 Review 全绿仍让高价值错误逃逸且原因不显然、未来重新发现成本高。前两条衡量影响的真实性与范围后两条衡量逃逸的系统性一条链路只挂一次可能是运气而既有防护全绿仍放行高价值错误意味着防护本身存在结构性缺口这正是复盘最有价值的素材。判定权落在修复负责人与 Reviewer 手中属于语义判断而不是由 diff 大小或文件数量这类静态启发式自动触发的该原则与 Spec Loop 中 trivial/substantial 的判定规则 一脉相承。复盘的目的与底线要求复盘的价值不是记录发生了什么而是把已经逃逸的事故转化为更早、更明确的未来失败。因此 README 强调了两条纪律不承担归责也不保存推理过程记录复盘是对事实与机制的整理不是人员评价或思考流水账仅增加 checklist、培训提醒或加强 Review不能单独关闭复盘这些措施没有可执行后果无法被验证也不构成更早的拒绝机制。每份复盘必须指定真实 Owner指向当前拥有该行为语义的代码、契约或文档而非个人头衔链接对应的修复与 decision 记录并保存以下可验证材料必须保存的事实说明事实时间线可验证事件、时间与观察来源因果链从触发条件到用户影响的必要因果区分直接事实与推断安全网漏过机制既有测试、oracle、workflow、Review 或运行时 guard 为何没有更早拒绝Reproducer可复现缺陷的最小路径直接 oracle最接近风险且与实现失败方式不同的独立校验负向案例恢复目标缺陷后会因正确原因失败的测试实际 gate真实接线、可执行的阻断 workflow 或 standing order未解决风险仍未知、未执行或需外部校准的范围Owner 修复/decision 链接 可验证证据这一组合与 工程信任体系 中完成状态需要明确 Owner、真实系统事实、与风险匹配的 oracle、只读 gate 和可问责语义 Review 共同证明的权威模型完全一致——事故文档本身也是信任闭环的一部分而不是独立的叙事文件。七段式复盘模板逐章解读使用 TEMPLATE.md 创建YYYY-MM-DD-topic.md日期 主题与决策记录命名规则相同。模板固定七个章节每个章节都有明确的功能边界影响说明真实用户、数据、安全、可用性或外部系统影响以及已确认的范围。未知范围明确写为未知——这是事实准确的底线不允许用模糊措辞掩盖范围未确认的事实。事实时间线只记录可验证事件、时间和观察来源不保存推理流水账或人员评价。这条约束对应 README 中不承担推理过程记录的定位时间线是后续因果分析的证据底座。因果链从触发条件、系统行为、失效边界到用户影响解释必要因果区分直接事实和推断。因果链是整份复盘的分析核心直接服务于更早、更明确的未来失败这一目标——只有因果清楚才能知道应该在哪个环节提前拦截。安全网为何漏过说明既有测试、oracle、workflow、Review 或运行时 guard 为什么没有在更早位置拒绝该错误。这是复盘区别于普通 bug 报告的关键章节它要求对为什么全绿还放行了给出机制层面的解释而不是简单归因于疏忽。修正与验证链接修复 Owner列出 reproducer、直接 oracle、负向案例、准确命令、实际结果和未验证范围。这里的验证遵循项目统一的证据语言——Spec Loop 规定结果词只有四种固定取值Passed命令实际成功且结果已核对、Inspected只读检查了事实、Not run未执行并说明原因/风险、Inferred根据间接证据推断后三者都不能写成测试通过。复盘中的验证结论同样适用这套词汇。防复发措施记录已经落地的 generalized guard、gate、decision 或 standing order每项必须有 Owner 和拒绝后果。已经落地与必须有拒绝后果是两条硬约束没有实际接线、没有失败后果的措施如加强 Review不能写进这一节更不能用于关闭复盘。未解决风险列出仍未知、未执行或需要外部校准的范围没有则写无。源码级校验Verifier 如何防止模板结构漂移Yuxi 不仅用文档约束复盘格式还用只读校验脚本保证结构不会静默漂移。在 scripts/verify_engineering_contracts.py 中第 39–47 行定义了POSTMORTEM_TEMPLATE_HEADINGS元组固化上述七个##章节_validate_postmortems()第 787–808 行检查README.md与TEMPLATE.md两个文件都存在并逐一确认模板包含全部七个标题、且每个标题下都有非空内容注释行不计入该检查被纳入verify()汇总随 信任 Gate 的运行与维护 一节说明的命令执行python3 scripts/verify_engineering_contracts.py python3 -m unittest scripts.test_verify_engineering_contracts第一条命令做仓库事实的静态校验第二条运行校验逻辑自身的负向测试每项检查都有能恢复目标缺陷的用例。这两条命令由.github/workflows/trust.yml在每个 PR 无条件阻塞——verifier 在 WORKFLOW_CONTRACTS 中被声明为unfiltered_pull_requestTrue即不允许用 path filter 缩小覆盖范围任何改动都不能绕过对 postmortem 入口与模板结构的检查。需要注意 Verifier 的能力边界它只证明入口与模板存在、标题齐全且有内容不判断某次事故是否达到门槛、复盘内容是否真实、oracle 是否独立——这些语义仍由修复负责人与 Reviewer 结合真实系统证据裁决这与 verifier 对 decision 与 workflow 的检查边界一致。复盘在工程信任体系中的位置复盘不是孤立流程它是 Yuxi 工程信任体系的事故反馈出口。engineering-trust.md 的事故反馈一节明确了它的位置只有已经逃逸且达到项目复盘门槛的高影响缺陷才形成正式 postmortem。每个符合门槛的事故有 Owner说明真实影响、因果链、为什么既有安全网漏过以及新增或修正的 reproducer、oracle、gate、decision 或 standing order。学习需要主动实现和 Review不会自动发生普通缺陷仍保留与风险相称的回归证据但不强制制造事故文档。与此配套的证据等级表定义了各层证据的证明范围与局限证据证明什么不能替代什么Unit纯逻辑、边界值、状态转换和失败分支PostgreSQL、Redis、HTTP、worker 或浏览器真实语义Integration真实 API、认证、事务、锁和服务副作用完整用户/模型 journey 与外部 provider 漂移E2ECompose 中的 shipping entry、worker、SSE、文件/对象和最终业务结果每个局部分支与确定性故障注入Deterministic replay不依赖真实 provider 的 assembled-path 回归实时模型/provider 行为Real probe外部模型、浏览器或部署实例的现实校准低噪声、每 PR 都可执行的阻塞 gateSemantic Review目标、取舍、oracle 独立性和 expected-output 语义可机械判断的格式、引用、选择器和构建错误复盘中的负向案例与直接 oracle必须落在这些证据等级里——理想情况下防复发措施应该把负向案例接到一条真实、低噪声、每 PR 可执行的 gate 上而不是只停留在文档承诺。复盘同时是 Yuxi Spec Loop 八阶段闭环的收尾阶段Learn达到门槛的高影响逃逸缺陷必须留下 reproducer、因果链、安全网漏过原因和更早的拒绝机制普通缺陷仍需要风险相称的回归测试但不制造事故文档。也就是说Postmortem 是 Spec Loop 从验证Verify失败结果中提炼学习证据的唯一正式载体它与 Propose/Verify 阶段使用的同一套验收字段验收主张、失败面、语义 Owner、直接 oracle、负向案例、结果形成呼应。与决策记录和 Owner 的联动复盘文档不是孤立的叙事文件它必须链接到 工程决策记录 体系每份复盘必须链接对应修复或 decision防复发措施如果引入了新的工程取舍例如调整持久状态、权限、长生命周期或模型可见输入按 decisions 的何时需要规则 属于非平凡变更需要先建proposed/记录收敛后再移入implemented/Owner 字段指向当前拥有该行为语义的首要代码、契约或文档verifier 会校验Owner必须指向仓库内真实存在的文件见_require_repository_path对 decision Owner 的检查复盘被后续事实取代时保留历史并链接当前 Owner不把历史事故文档改写成当前运行契约——这与 decision 的archived/处理原则一致历史文档是冻结的教训来源当前行为以最新的代码、契约和 implemented decision 为准。仓库内已有的 implemented 决策记录如 2026-08-16-agent-first-engineering-trust.md、2026-08-16-yuxi-spec-loop.md展示了这套体系如何落地它们只保留问题、决策、替代方案、后果、验证验证部分给出实际命令与结果词并明确Not run的范围——这正是复盘修正与验证章节应当效仿的写法。撰写一份合格复盘的实操路径结合以上机制一次合规的 Postmortem 撰写可以按以下步骤推进过门槛修复负责人与 Reviewer 对照四条标准判断——是否涉及安全/权限/数据/外部副作用风险是否影响关键链路或可用性是否多入口同机制复现是否防护全绿仍逃逸。任一成立即建文档都不成立则只需保留与风险相称的回归测试。建文件在docs/develop-guides/postmortems/下创建YYYY-MM-DD-topic.md复制 TEMPLATE.md 的七个章节骨架填写日期、Owner仓库相对路径与关联决策。填事实按章节填入影响范围未知即写未知、事实时间线只记可验证事件与来源、因果链区分事实与推断、安全网漏过机制、修正与验证reproducer oracle 负向案例 准确命令 实际结果 未验证范围、防复发措施每项有 Owner 与拒绝后果、未解决风险没有写无。接入防护防复发措施尽量落地为真实 guard——要么是带负向案例的测试、要么是 workflow 中的阻断 gate、要么是 tracked decision写完后运行python3 scripts/verify_engineering_contracts.py确认模板结构与引用通过机械校验。闭环收敛与对应修复、decision 互相链接后续事实出现时保留历史、更新 Owner 链接不重写历史文档。这套流程让事故复盘从一次性的写作任务变成仓库工程信任循环中可审计、可校验、可复用的正式机制门槛把注意力集中在真正高价值的失败上七段式模板强制保存可验证事实与更早的拒绝机制Verifier 防止结构漂移而 Owner 与 decision 链接保证每一份教训都能追溯到当前行为的语义权威。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考