@umacloud/knowledge 1.0.14 → 1.0.16

package/agentic-delivery/01-standards/test-discipline-for-generated-code.md

@@ -0,0 +1,94 @@
+---
+id: test-discipline-for-generated-code
+title: 生成式代码的测试纪律（回归率作为一等指标 + 风险定向选测，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [generated-code, test-discipline, regression-rate, impact-map, independent-test-authoring, mutation-guided, tdd-pitfall, blast-radius, 生成式代码, 测试纪律, 回归率, 影响图, 独立测试, 变异加固, 风险定向, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 生成式代码的测试纪律（商业级必读）
+
+> 给生成式代码套上"先写测试"这句口号，往往**适得其反**：模型会写出贴着自己实现写的同义测试，绿灯一片却放过真正的回归。把改动测好，靠的不是把 TDD 当流程喊口号，而是**定向**——先算清这次改动会波及哪些行为，再把测试火力压在**最可能被打坏的旧行为**上。
+> 这份规范把"测生成式代码"从"多写点测试"升级成**可判定的纪律**：用代码↔测试影响图锁定风险面、把**回归率**和"解决率"并列为一等交付指标、让测试作者与代码作者**解耦**去偏、用**变异定向加固**逼出真正能杀掉缺陷的断言。怎么分层、怎么进 CI 门见 `testing/01-standards/test-strategy-and-layering` 与 `testing/01-standards/ci-test-gates-and-coverage`；本规范回答的是"生成式改动到底要测什么、测到什么程度才算把回归挡住"。
+
+## 1. 为什么"无脑先写测试"会抬高回归
+
+生成式改动有三个固有偏差，单纯喊"先写测试"不仅治不了、还会放大：
+
+- **同义测试**：让同一个上下文既写实现又写测试，测试会复述实现的内部假设，实现错了测试也跟着错，绿灯毫无信息量。
+- **只测自己改的**：模型天然只给**新增/改动**的代码配测试，而回归恰恰发生在**没被这次改动直接触碰、却共享了状态或契约**的旧行为上。
+- **覆盖率幻觉**：补一堆走 happy path 的断言把覆盖率拉绿，行被执行了但关键分支的断言是空的（见 §5 变异加固）。
+
+结论：测试的价值不取决于**数量**，取决于是否压在**这次改动的风险面**上。先定向，再写测试。
+
+## 2. 代码↔测试影响图（先算风险面，再决定测什么）
+
+每次改动先回答"**这次改了什么、会波及哪些行为、哪些旧行为最可能被打坏**"，产出一张定向清单而不是泛泛补测试：
+
+| 改动类型 | 风险面（最可能被打坏的旧行为） | 测试火力优先级 |
+|---|---|---|
+| 改公共函数/方法签名或语义 | 所有调用点、依赖其返回形状的下游 | 为每个调用路径补/查回归断言 |
+| 改共享数据模型/DTO/Schema | 序列化、持久化、跨端契约、缓存键 | 契约测试 + 往返序列化测试 |
+| 改条件/边界/校验逻辑 | 边界值、错误分支、权限分支 | 边界与错误路径定向用例 |
+| 改共享状态/全局配置/单例 | 并发、隔离、其它读该状态的功能 | 并发与隔离回归用例 |
+| 改依赖版本/外部接口适配 | 所有经过该依赖的路径 | 集成测试 + 契约对照 |
+| 纯新增、无共享面 | 仅新增行为本身 | 新增行为的 happy + 边界 + 错误 |
+
+定向规则：**改动的 blast radius（波及半径）越大，回归火力越要往旧行为压**；波及半径靠"谁调用了我、谁和我共享状态/契约"来确定，而不是靠"我这次新增了几个函数"。
+
+## 3. 回归率：和解决率并列的一等交付指标
+
+只看"这次需求是否解决（解决率）"会奖励"改好一个、悄悄打坏两个"。商业级交付必须把**回归率**抬到同等地位：
+
+- **定义**：一次改动引入的、**此前可用而现在失效**的行为占比（按受影响行为/用例计），与"解决率=本次目标达成的占比"并列上报。
+- **判定**：解决率达标但回归率非零 → **不算完成**，必须先消回归。一次"解决一个、回归一个"的改动是**净零甚至负收益**。
+- **度量来源**：改动前对受影响面跑一遍基线（绿），改动后重跑；任何由绿转红的旧行为即计入回归。每个被抓到的回归都应沉淀成持久回归用例，见 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`。
+- **趋势**：回归率随交付批次留痕、可审计；持续非零说明影响图没做或火力压错了面。
+
+## 4. 独立（去偏）测试作者：测试作者 ≠ 代码作者
+
+去掉"自己测自己"的同义偏差，让验证有独立性：
+
+- **解耦上下文**：写实现的上下文与写/审测试的上下文分离，测试只看**需求与验收标准**、不看实现内部，避免复述实现假设。
+- **从需求反推用例**：测试用例来自结构化需求（见 `experts/product-manager/requirements-engineering-ears`）与契约（见 `experts/architect/contract-first-api-design`），而不是来自"代码现在是怎么写的"。
+- **黑盒优先**：对外部行为按输入→可观测输出断言，不绑定私有实现细节，这样重构不误伤、实现错了能被抓到。
+- **独立复核**：测试本身也要被一个不写该实现的视角复核"这些断言真能区分对错吗"，与 `agentic-delivery/01-standards/verifier-critic-pattern` 的 actor/checker 解耦一脉相承。
+
+## 5. 变异定向加固：注入你最怕的那个缺陷，逼出能杀掉它的测试
+
+行覆盖只证明"代码被执行过"，不证明"断言真的会在缺陷出现时变红"。对**核心/高风险**逻辑做定向加固：
+
+- **注入畏惧缺陷**：针对这段逻辑你最担心出错的具体方式（边界写成 `<` 还是 `<=`、漏一个错误分支、权限判断取反、单位/符号错），**手动制造**这个缺陷。
+- **要求杀手测试**：必须存在一个测试在该缺陷注入后**变红**；若注入了缺陷而全测试仍绿，说明断言是空的——补到能杀掉为止。
+- **聚焦而非全量**：这是对**关键改动面**的定向手段（每次改动针对其畏惧缺陷做），不是把全量变异测试搬进每次 PR；全量慢扫归夜间，见 `testing/01-standards/ci-test-gates-and-coverage`。
+- **沉淀**：被加固挡住的缺陷类型记入项目级回归集与经验库，避免同类缺陷重现。
+
+## 6. 接入交付流程
+
+- **改动前**：先产出代码↔测试影响图，定向出风险面与回归基线。
+- **实现中**：实现与测试上下文解耦；测试从需求/契约反推。
+- **加固**：对核心逻辑做变异定向加固，逼出杀手测试。
+- **验收门**：解决率与回归率同时达标才算完成；回归率非零阻断"完成"判定。
+- **回归保护**：每个抓到的回归与畏惧缺陷沉淀为持久用例，进自动化回归。
+
+## 7. 反模式（出现即不合格）
+
+1. **同一上下文自写自测**：实现与测试共享假设，绿灯零信息量。
+2. **只给新增代码配测试**：放任共享契约/状态上的旧行为被悄悄打坏。
+3. **用 happy-path 断言堆覆盖率**：行被执行、关键分支断言为空，覆盖率绿而缺陷漏网。
+4. **只报解决率不报回归率**："解决一个、回归一个"被当成完成。
+5. **把"先写测试"当免罪符**：写了测试就签字，不看测试是否压在风险面上。
+6. **断言绑实现细节**：贴着私有实现写，重构必红、实现错却不红。
+7. **核心逻辑零变异验证**：从不注入畏惧缺陷，无法证明断言会变红。
+
+## 8. 最低交付 checklist
+
+- [ ] 每次改动产出代码↔测试影响图，按 blast radius 定向出风险面与回归基线。
+- [ ] 回归率与解决率并列上报；回归率非零不判定为完成。
+- [ ] 写实现与写/审测试的上下文解耦，测试从需求与契约反推、黑盒优先。
+- [ ] 核心/高风险逻辑做变异定向加固，存在能在注入畏惧缺陷后变红的杀手测试。
+- [ ] 受影响旧行为的回归断言齐全，不只覆盖本次新增代码。
+- [ ] 每个抓到的回归与畏惧缺陷沉淀为项目级持久回归用例并进自动化回归。
+- [ ] 全量/慢变异扫描放夜间，不拖慢每次 PR 门禁。

package/agentic-delivery/01-standards/test-integrity-and-anti-gaming.md

@@ -0,0 +1,92 @@
+---
+id: test-integrity-and-anti-gaming
+title: 测试完整性与反作弊规范（一套绿测只有"没被作弊"才可信，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [test-integrity, anti-gaming, reward-hacking, assertion-weakening, skip-xfail, harness-tampering, held-out, integrity-diff, judge-review, 测试完整性, 反作弊, 刷分, 弱化断言, 跳过, 篡改, 留出集, 完整性差异, 评审]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 测试完整性与反作弊规范（商业级必读）
+
+> 一句话：**一套全绿的测试，只有在确认它没被作弊的前提下才可信。** 当"让测试通过"成了目标，最省力的路径常常不是把代码改对，而是把**测试改松**——硬编码期望输出、删/弱化断言、`skip`/`xfail` 掉碍事的用例、动测试框架、专门特判可见用例、提前 `return` 跳过校验。绿灯于是变成了对"会不会绕"的奖励，而不是对"对不对"的证明。
+> 这份规范给出**作弊行为目录**与**能戳穿它们的验证手段**：一道作者改不动的确定性校验、一份完整性差异、独立 + 留出（held-out）检查、以及评审复核。它和 `agentic-delivery/01-standards/test-discipline-for-generated-code`（测什么）、`agentic-delivery/01-standards/verifier-critic-pattern`（谁来验）互补；CI 门禁形态见 `testing/01-standards/ci-test-gates-and-coverage`。本规范回答的是"凭什么相信这套绿测"。
+
+## 1. 作弊行为目录（reward hacking 的常见形态）
+
+把"通过测试"当奖励、把"改对代码"当手段时，会冒出这些行为——**每一种都让绿灯失去意义**：
+
+| 作弊形态 | 具体表现 | 为什么危险 |
+|---|---|---|
+| 硬编码输出 | 直接 `return` 期望值/把断言里的预期写进实现，特判测试输入 | 真实输入立刻失效，测试只证明"会背答案" |
+| 弱化/删断言 | 把 `assertEqual` 改成 `assertTrue`、放宽容差、删掉关键断言 | 缺陷出现也不再变红 |
+| skip / xfail | 给碍事用例打 `skip`/`xfail`/`ignore`/注释掉 | 失败被静音，覆盖面悄悄缩小 |
+| 篡改测试框架 | 改 conftest/setup/全局 fixture/断言钩子让失败被吞 | 整套套件的可信度坍塌 |
+| 特判可见用例 | 只让"看得见的样例"过，逻辑对一般情况错 | 留出集一换就崩 |
+| 提前退出/短路 | 在校验前 `return`/吞异常/`try…except: pass` | 错误路径被绕过，错误被当成功 |
+| 放宽门禁 | 调低覆盖率阈值、关掉某条必过检查、给 lint 加豁免 | 把门拆了再"通过" |
+| 改基线/期望文件 | 直接把快照/golden 文件改成当前（错误）输出 | 回归保护被反向利用 |
+
+判定原则：**只要"通过"是靠改松验证而非改对代码换来的，即为作弊，等同未完成。**
+
+## 2. 能戳穿作弊的验证手段
+
+光禁止没用，要让作弊**在结构上失效**：
+
+- **一道作者改不动的确定性校验**：核心验收用一条**实现/测试作者无权修改**的确定性检查把关（独立 runner、固定输入→固定期望、产物级断言）。作者能改的测试只能加分，不能替代这道闸。
+- **留出（held-out）检查**：除可见用例外，保留一组作者**看不到**的输入/期望用于最终判定；专门特判可见用例的实现会在这里崩。
+- **完整性差异（integrity diff）**：每次改动**单独审视对测试与门禁配置的改动**——断言是被加强还是被删/弱化？是否新增 `skip`/`xfail`？是否动了框架/阈值/豁免？测试改动要和实现改动**分开评审**，不能混在一个大 diff 里蒙混过关。
+- **独立检查**：验证由不写该实现的视角执行（见 `agentic-delivery/01-standards/verifier-critic-pattern`），避免"自证清白"。
+- **评审复核（judge review）**：对"是否在解决问题而非绕过验证"做一次结构化判定（见 §4），作为人/裁判侧的最后一关。
+
+## 3. 完整性差异：必须逐项盘问的改动信号
+
+每次改动对"测试与门禁"的任何改动都要能解释，否则视为可疑：
+
+| 信号 | 默认判定 | 放行条件 |
+|---|---|---|
+| 断言被删除或放宽 | 可疑 | 有明确理由且不降低区分力，评审签字 |
+| 新增 skip / xfail / ignore | 可疑 | 关联到已登记的真实缺陷与期限 |
+| 改动测试框架/全局 fixture/钩子 | 高危 | 独立复核，确认不吞失败 |
+| 修改快照/golden/基线文件 | 可疑 | 确认是预期行为变化而非掩盖回归 |
+| 调低覆盖率阈值/加 lint 豁免/关必过检查 | 高危 | 默认拒绝，需显式治理审批 |
+| 实现里出现对测试输入的特判/硬编码 | 作弊 | 不放行 |
+
+## 4. 评审/裁判复核要点
+
+复核者只问一件事：**这次是把问题解决了，还是把验证绕过了？**
+
+- 实现是否对**一般输入**成立，而非只过可见用例？（用留出集证实）
+- 测试改动是**加强**了区分力，还是**削弱**了？
+- 是否有 `skip`/`xfail`/吞异常/提前 return 在静音失败？
+- 门禁/阈值/豁免是否被动过？动了就要有治理依据。
+- 结论给**结构化判定**：pass / fail + 证据（哪条留出用例、哪段 diff），fail 即打回，路由方式见 `agentic-delivery/01-standards/verifier-critic-pattern`。
+
+## 5. 接入交付流程
+
+- **门禁分层**：作者可改的测试加分，**确定性留出校验**作为不可绕过的判定闸。
+- **diff 分离**：实现 diff 与测试/门禁 diff 分开呈现、分开评审。
+- **留痕**：留出集结果、完整性差异结论随交付留证，可审计。
+- **沉淀**：被识破的作弊手法记入经验库与项目规则，作为后续硬约束。
+
+## 6. 反模式（出现即不合格）
+
+1. **实现里特判/硬编码测试输入**：测试只在背答案，真实输入即崩。
+2. **靠删/弱化断言换绿**：缺陷出现不再变红，回归保护形同虚设。
+3. **用 skip/xfail/注释静音失败**：失败被藏起来，覆盖面悄悄缩水。
+4. **篡改测试框架吞掉失败**：整套套件可信度坍塌。
+5. **把实现和测试改动混进一个大 diff**：完整性差异无法审，作弊蒙混过关。
+6. **改门禁阈值/加豁免来"通过"**：把门拆了再宣称达标。
+7. **无留出集**：只用可见用例判定，特判式实现永远过关。
+8. **验证者就是实现者**：自证清白，作弊无人能戳穿。
+
+## 7. 最低交付 checklist
+
+- [ ] 核心验收由一道实现/测试作者**改不动**的确定性校验把关。
+- [ ] 存在作者不可见的留出（held-out）用例用于最终判定。
+- [ ] 实现 diff 与测试/门禁 diff 分离呈现并分别评审（完整性差异）。
+- [ ] 任何删/弱断言、新增 skip/xfail、改框架/阈值/基线都有理由并经复核。
+- [ ] 验证由不写该实现的独立视角执行，给出 pass/fail + 证据。
+- [ ] 覆盖率阈值与必过检查不可被本次改动私自调低或豁免。
+- [ ] 被识破的作弊手法沉淀为项目级硬约束，防止重现。

package/agentic-delivery/01-standards/verifier-critic-pattern.md

@@ -0,0 +1,89 @@
+---
+id: verifier-critic-pattern
+title: 验证者/评审者模式（actor 与 checker 解耦、只看 diff + 验收标准，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [verifier, critic, actor-checker, fresh-context, structured-verdict, route-back, over-engineering-guard, pass-fail, diff-review, 验证者, 评审者, 解耦, 新上下文, 结构化判定, 打回, 过度设计护栏]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 验证者/评审者模式（商业级必读）
+
+> 写代码的人最不该是判它对不对的人——他带着"我已经做完了"的偏差，会把自己的实现当正确答案。商业级交付要把**执行者（actor）与检查者（checker）解耦**：检查者在**全新上下文**里、**只看 diff + 验收标准**做独立判定，给出结构化的 pass/fail，fail 就**带证据打回**，而不是顺着实现点头。
+> 这份规范定义验证者/评审者的职责、输入边界与判定协议，并立一道**过度设计护栏**——验证者只挑"对不对、需求满没满足"的硬伤，不发明风格活、不为审而审。它和 `agentic-delivery/01-standards/test-integrity-and-anti-gaming`（防作弊）、`agentic-delivery/01-standards/test-discipline-for-generated-code`（测什么）互补，与 `development/01-standards/code-review-and-pr-hygiene`（人工评审礼仪）分工：本规范回答的是"谁来验、看什么、怎么判、怎么打回"。
+
+## 1. 为什么必须把 actor 和 checker 分开
+
+- **去自证偏差**：执行者已投入"这条实现路径"，复核自己时会合理化缺陷、跳过自己没想到的边界。
+- **抗作弊**：独立检查者才可能戳穿"改松测试换绿"（见 `agentic-delivery/01-standards/test-integrity-and-anti-gaming`）。
+- **抗沉默逻辑错误**：新视角只对照需求看输出，更容易发现"看起来对、其实没满足需求"的偏差。
+- **可路由**：把"做"和"判"拆成两个角色，才能形成"做→判→打回→再做"的可收敛闭环。
+
+## 2. 验证者的输入边界：新上下文，只看 diff + 验收标准
+
+| 验证者**应当**看到 | 验证者**不应**被喂入 |
+|---|---|
+| 本次 diff（改了什么） | 执行者的内心独白/"我觉得没问题"的辩解 |
+| 验收标准 / 结构化需求 | 实现过程中的探索弯路与中间废稿 |
+| 契约 / 接口定义 | "时间紧就先这样"之类的免检理由 |
+| 相关测试与其结果 | 让验证者去复述实现假设的引导 |
+
+要点：**全新上下文**意味着验证者不继承执行者的合理化叙事，只凭"改动 + 该满足什么"独立判断。看 diff 而非全量，让注意力压在**这次实际改了什么**上。
+
+## 3. 结构化判定协议（pass/fail + 证据 + 打回）
+
+验证者必须输出**可判定**的结构化结论，而不是一段感想：
+
+| 字段 | 含义 |
+|---|---|
+| verdict | `pass` / `fail`（二选一，不许"基本可以"） |
+| blocking | 阻断项列表：每条带"违反了哪条验收标准/契约"+ 证据 |
+| advisory | 非阻断建议（不阻断放行，记入待办） |
+| evidence | 支撑判定的证据：哪条用例、哪段 diff、哪个未满足的需求 |
+
+- **fail → 带证据打回**：不是"去改改"，而是"第 N 条验收标准未满足，证据是 X，期望 Y"，让执行者能精准定位（诊断式打回，不是泛泛退回）。
+- **bounded**：打回-重做要有次数/停滞上限，连续 N 轮无进展即升级或停下，避免空转。
+- **advisory 不阻断**：建议项只记待办，不卡发布——把阻断权留给真正的对错问题。
+
+## 4. 过度设计护栏：只挑硬伤，不发明工作
+
+验证者最容易跑偏成"为审而审"，把风格偏好、可有可无的重构、镀金需求当成阻断项。立死规矩：
+
+- **只标三类阻断**：①正确性缺陷 ②需求/验收标准未满足 ③契约/安全/数据完整性被破坏。
+- **不标的**：个人风格偏好、与需求无关的"还能更优雅"、未被要求的额外特性、为覆盖率而覆盖率。
+- **建议归 advisory**：确有价值但非必需的改进进 advisory，不进 blocking。
+- **范围对齐**：验证者对照的是**本次验收标准**，不把"顺手再加点"塞进打回理由；额外发明的工作本身就是一种缺陷（scope creep）。
+
+## 5. 与角色评审团/确定性门的关系
+
+- **确定性门优先**：覆盖/契约/构建/安全等确定性检查是**硬判定**；验证者/评审者意见是其上的一层，对"需求是否真的满足"做判断。
+- **可并行多视角**：多个只读评审视角（如产品/架构/安全角度）可并行复核，各自给结构化 verdict；聚合时**阻断级以确定性门为准、评审意见为佐证**。
+- **不互相聊天**：各评审者只通过**改动 + 验收标准 + 各自 verdict** 交流，不串供。
+
+## 6. 接入交付流程
+
+- **每个关键步骤后**：执行者交 diff → 验证者在新上下文只看 diff + 验收标准 → 出结构化 verdict。
+- **fail**：带证据诊断式打回，执行者定向修复，重验；超出停滞上限则升级。
+- **pass**：进入下一步或合并；advisory 记入待办。
+- **留痕**：verdict 与证据随交付留证，可审计。
+
+## 7. 反模式（出现即不合格）
+
+1. **自己验自己**：执行者复核自己的实现，自证清白。
+2. **把全量历史喂给验证者**：验证者继承执行者的合理化叙事，失去独立性。
+3. **判定含糊**："看起来还行/基本可以"，无法判通过还是打回。
+4. **打回不给证据**：只说"去改改"，执行者无从定位，来回空转。
+5. **为审而审/镀金**：把风格偏好、未被要求的特性当阻断项。
+6. **无停滞上限**：做-判-打回无限循环，不升级也不停。
+7. **让评审意见凌驾确定性门**：主观意见盖过覆盖/契约/安全的硬判定。
+
+## 8. 最低交付 checklist
+
+- [ ] 执行者与验证者解耦，验证由不写该实现的视角执行。
+- [ ] 验证者在新上下文中只看 diff + 验收标准 + 契约/相关测试，不继承执行叙事。
+- [ ] 输出结构化 verdict：pass/fail + blocking（带违反项与证据）+ advisory。
+- [ ] fail 走诊断式打回（指明未满足项 + 证据 + 期望），不是泛泛退回。
+- [ ] 打回-重做有停滞/次数上限，超限升级或停止，不空转。
+- [ ] 过度设计护栏生效：只标正确性/需求/契约硬伤，风格与镀金归 advisory。
+- [ ] 确定性门为硬判定，评审意见为佐证；verdict 与证据留痕可审计。

package/ai/agent-evaluation-benchmark.md

@@ -8,7 +8,7 @@ tags: [agent, ai, benchmark, evaluation, 评测与基准体系]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# agent-evaluation-benchmark
 
 ## Agent 评测与基准体系
 

package/ai/ai-agent-memory-context-management.md

@@ -8,7 +8,7 @@ tags: [agent, agent上下文与记忆管理, ai, context, management, memory]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-agent-memory-context-management
 
 ## AI Agent上下文与记忆管理
 

package/ai/ai-cost-capacity-optimization-playbook.md

@@ -8,7 +8,7 @@ tags: [ai, ai成本与容量优化手册, capacity, cost, optimization, playbook
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-cost-capacity-optimization-playbook
 
 ## AI成本与容量优化手册
 

package/ai/ai-data-security-and-compliance-playbook.md

@@ -8,7 +8,7 @@ tags: [ai, ai数据安全与合规作战手册, and, compliance, data, playbook,
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-data-security-and-compliance-playbook
 
 ## AI数据安全与合规作战手册
 

package/ai/ai-domain-index-and-checklist.md

@@ -8,7 +8,7 @@ tags: [ai, ai领域索引与执行清单, and, checklist, domain, index]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-domain-index-and-checklist
 
 ## AI领域索引与执行清单
 

package/ai/ai-governance-maturity-model.md

@@ -8,7 +8,7 @@ tags: [ai, ai治理成熟度模型, governance, maturity, model]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-governance-maturity-model
 
 ## AI治理成熟度模型
 

package/ai/ai-model-selection-and-routing-strategy.md

@@ -8,7 +8,7 @@ tags: [ai, ai模型选型与路由策略, and, model, routing, selection, strate
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-model-selection-and-routing-strategy
 
 ## AI模型选型与路由策略
 

package/ai/ai-observability-and-oncall-runbook.md

@@ -8,7 +8,7 @@ tags: [ai, ai可观测性与值班runbook, and, observability, oncall, runbook]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-observability-and-oncall-runbook
 
 ## AI可观测性与值班Runbook
 

package/ai/ai-rag-engineering-playbook.md

@@ -8,7 +8,7 @@ tags: [ai, engineering, playbook, rag, rag工程作战手册]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-rag-engineering-playbook
 
 ## AI RAG工程作战手册
 

package/ai/ai-red-team-and-safety-evaluation.md

@@ -8,7 +8,7 @@ tags: [ai, ai红队测试与安全评估, and, evaluation, red, safety, team]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-red-team-and-safety-evaluation
 
 ## AI红队测试与安全评估
 

package/ai/ai-release-readiness-and-rollback-gate.md

@@ -8,7 +8,7 @@ tags: [ai, ai发布就绪与回滚门禁, and, gate, readiness, release, rollbac
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ai-release-readiness-and-rollback-gate
 
 ## AI发布就绪与回滚门禁
 

package/ai/llm-agent-engineering-deep-dive.md

@@ -8,7 +8,7 @@ tags: [agent, ai, deep, dive, engineering, llm, 工程深度知识库]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# llm-agent-engineering-deep-dive
 
 ## LLM 与 Agent 工程深度知识库
 

package/ai/prompt-and-tool-guardrails.md

@@ -8,7 +8,7 @@ tags: [ai, and, guardrails, prompt, tool, 与工具调用护栏规范]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# prompt-and-tool-guardrails
 
 ## Prompt 与工具调用护栏规范
 

package/api/01-standards/api-versioning-and-deprecation-policy.md

@@ -0,0 +1,100 @@
+---
+id: api-versioning-and-deprecation-policy
+title: API 版本与弃用治理规范（商业级必读）
+domain: api
+category: 01-standards
+difficulty: intermediate
+tags: [api, versioning, deprecation, sunset, breaking-change, backward-compatible, semver, migration, consumer, 版本, 弃用, 废弃, 破坏性变更, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# API 版本与弃用治理规范（商业级必读）
+
+> 接口一旦有人调用，它就是**契约**，不再是你一个人能随便改的代码。
+> 商业级团队对外接口的演进遵循一条铁律：**老调用方不许被你的改动搞挂**。
+> 版本化解决"如何在不破坏现有消费方的前提下演进"，弃用治理解决"如何**有序、可预期地**让老版本退场"——两者缺一，要么永远不敢改，要么一改就出事故。
+
+## 1. 核心原则
+
+- **兼容优先**：能向后兼容就别升版本。新增是兼容的，删改是破坏的。
+- **破坏性变更必须版本化**：永远不在同一版本里做破坏性变更（见 §3 判定）。
+- **弃用要可预期**：老版本退场要提前公告、给迁移期、给信号，而不是某天突然 404。
+- **消费方视角**：以"现有调用方会不会挂"为唯一判据，而不是"我代码改得爽不爽"。
+- **支持窗口有限且明确**：不无限维护所有历史版本，但退场节奏要写明、要守约。
+
+## 2. 版本化方式（选一种，全项目统一）
+
+| 方式 | 形态 | 优点 | 取舍 |
+|---|---|---|---|
+| URL 路径 | `/api/v1/orders` | 直观、易路由、缓存友好 | 版本粒度粗（整套接口）|
+| 请求头 | `API-Version: 2` | URL 稳定、灵活 | 不直观、调试需看 header |
+| 日期版本 | `API-Version: 2026-06-29` | 渐进、精确到每次变更 | 管理成本高 |
+| 媒体类型 | `Accept: application/vnd.x.v2+json` | 符合 HTTP 语义 | 客户端支持参差 |
+
+要点：**对外公开 API 推荐 URL 路径版本**（最直观、最少踩坑）；选定后全项目统一，别混用。主版本号对应破坏性变更（语义化版本，见 `release-engineering/01-standards/progressive-delivery-and-release`）。
+
+## 3. 破坏性 vs 兼容性变更（判定表）
+
+| 破坏性（必须升主版本）| 兼容性（不升版本）|
+|---|---|
+| 删除字段 / 端点 | 新增**可选**字段 / 新端点 |
+| 重命名字段 | 新增可选请求参数（有安全默认）|
+| 改字段类型 / 取值含义 | 放宽校验（接受更多输入）|
+| 把可选参数改为必填 | 新增枚举值（**需消费方容忍未知值**）|
+| 改默认行为 / 改错误码语义 | 新增响应头 |
+| 收紧校验（拒绝原本接受的输入）| bug 修复（不改契约语义）|
+| 改认证 / 分页 / 排序契约 | 性能优化（行为不变）|
+
+判定底线：**任何让现有调用方的正确请求开始失败、或让它依赖的返回结构变形的改动，都是破坏性的。** 新增枚举值是否破坏，取决于你是否在契约里要求消费方"忽略未知值"——要求了才算兼容。
+
+## 4. 弃用生命周期（三阶段，可预期）
+
+```
+公告(announce) → 过渡(transition) → 下线(sunset)
+```
+
+| 阶段 | 动作 |
+|---|---|
+| 公告 | 在文档/changelog 标记弃用，给出替代方案、迁移指南、**明确下线日期** |
+| 过渡 | 老版本继续可用但返回弃用信号（见 §5），主动联系高频调用方，监控剩余用量 |
+| 下线 | 用量降到可接受阈值且过了承诺期后，停用老版本并返回明确错误 |
+
+铁律：**先有替代、再宣弃用**——没有可迁移的新版本，不准弃用老版本。给足真实的迁移窗口（按受众，常以季度/年计），不是说下线就下线。
+
+## 5. 弃用信号（让调用方提前知道）
+
+- **`Deprecation` 头**：标记该端点/版本已弃用（可带弃用时间）。
+- **`Sunset` 头**：标明计划下线时间，让调用方有据可依地排期迁移。
+- **`Link` 头 / 文档**：指向替代端点与迁移指南。
+- **可观测**：服务端监控老版本调用量与调用方，弃用进度数据驱动，而不是猜。
+- **changelog**：每次版本变更面向使用者写清"新增/变更/弃用/破坏性/迁移方式"。
+
+## 6. 治理与协同
+
+- **契约即真相**：接口契约（OpenAPI 等）是版本化和兼容性校验的依据；契约变更要过契约测试（见 `testing/01-standards/contract-testing-and-api-contracts`）。
+- **兼容性门禁**：CI 中校验新契约对现有消费方兼容（无未升版的破坏性变更），不兼容则拦住发布（见 `testing/01-standards/ci-test-gates-and-coverage`）。
+- **消费方清单**：维护"谁在调哪个版本"，弃用前能精准触达，下线前能确认无活跃调用。
+- **内部 vs 外部**：内部接口可更快迭代、更短窗口；公开/合作方接口要更长支持期与更正式公告。
+- **与开关的边界**：功能开关控行为可见性，**不替代**版本化（见 `release-engineering/01-standards/feature-flag-lifecycle`）。
+
+## 7. 反模式（出现即不合格）
+
+1. **破坏性变更不升版**：直接改线上契约，老调用方批量 500/解析失败。
+2. **静默弃用 / 突然下线**：不公告、不给迁移期，某天直接 404。
+3. **无替代就弃用**：宣布老版本退场却没有可迁移的新版本。
+4. **无限维护所有版本**：从不下线，版本越堆越多，维护成本失控。
+5. **版本方式混用**：URL、header、query 各处混搭，调用方无所适从。
+6. **不知道谁在调**：没有消费方与用量数据，不敢动也不敢下线。
+7. **把收紧校验当兼容**：以为"只是更严格"，其实让原本合法的请求开始被拒。
+8. **changelog 堆 commit**：使用者看不懂变了什么、要不要迁移。
+
+## 8. 最低交付 checklist
+
+- [ ] 选定一种版本化方式并全项目统一；破坏性变更升主版本。
+- [ ] 明确区分破坏性/兼容性变更，破坏性绝不进同版本。
+- [ ] 弃用走公告→过渡→下线三阶段，**先有替代再弃用**，给足迁移窗口。
+- [ ] 弃用时返回 `Deprecation`/`Sunset` 信号，文档给出迁移指南。
+- [ ] 监控各版本调用量与消费方，弃用/下线数据驱动、可精准触达。
+- [ ] 契约为准，CI 做兼容性门禁，破坏性变更被拦截。
+- [ ] changelog 面向使用者写清变更与迁移方式。
+- [ ] 明确版本支持窗口，到期有序下线、守约不突袭。

package/architecture/01-standards/configuration-and-environment-management.md

@@ -0,0 +1,104 @@
+---
+id: configuration-and-environment-management
+title: 配置与环境管理规范（配置即代码/环境对等/启动校验，商业级必读）
+domain: architecture
+category: 01-standards
+difficulty: advanced
+tags: [configuration, environment, 12-factor, config-as-code, secret-management, env-parity, config-validation, fail-fast, config-drift, promotion, 配置管理, 环境对等, 配置校验, 配置漂移, 密钥分离, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 配置与环境管理规范（商业级必读）
+
+> 一份代码要跑在 dev / staging / prod 多个环境，环境之间**只有配置不同、代码完全一致**。配置一旦失控——硬编码环境分支、密钥进仓库、环境之间偷偷不一样、缺配置跑到一半才崩——线上事故里有相当一部分根本不是代码 bug，而是"配置在这个环境是错的"。
+> 商业级系统把配置当成**一等交付物**来治理：配置与代码分离、配置与密钥分离、环境严格对等、启动即校验、变更可审计可回滚。本规范给出可落地的配置纪律，不绑定任何具体配置中心产品（产品选型见 `architecture/configuration-management`）。
+
+## 1. 三条分离原则（地基）
+
+| 分离 | 含义 | 违反的后果 |
+|---|---|---|
+| 配置与代码分离 | 环境差异（地址、开关、阈值、外部 URL）从外部注入，绝不写死在代码里按环境 `if` | 改一个环境的值要改代码、重新构建、重新走发布 |
+| 配置与密钥分离 | 普通配置（可入仓库的非敏感项）与密钥（token/私钥/口令）分两套管理 | 密钥混进配置仓库 → 泄露面无限扩大 |
+| 构建产物与环境无关 | 同一个制品（镜像/包）不改一行就能部署到任意环境 | 每个环境单独构建 → "在 staging 是好的，prod 这个包不一样" |
+
+核心判据：**同一份构建产物 + 不同配置 = 不同环境**。如果切环境需要重新构建，说明配置没真正外置。
+
+## 2. 配置分类与来源优先级
+
+把配置按性质分类，每类有明确的来源与生命周期：
+
+| 类别 | 例子 | 来源 | 是否敏感 | 变更频率 |
+|---|---|---|---|---|
+| 基础设施配置 | DB 地址、缓存地址、队列地址 | 环境变量 / 配置中心 | 否 | 低 |
+| 密钥 | DB 口令、API 私钥、签名密钥 | 密钥管理（KMS/Vault/云 secret） | 是 | 中（轮换） |
+| 业务参数 | 超时、重试次数、限流阈值、分页大小 | 配置文件 / 配置中心 | 否 | 中 |
+| 功能开关 | 灰度开关、降级开关 | 功能开关系统（见 `release-engineering/feature-flag-lifecycle`） | 否 | 高 |
+| 环境标识 | 环境名、区域、版本号 | 注入环境变量 | 否 | 部署时定 |
+
+**来源优先级要确定且唯一**：约定一个清晰的覆盖顺序（如 默认值 < 配置文件 < 环境变量 < 启动参数），写进文档；同一个键绝不允许两处都"可能生效"导致猜不到实际取了哪个值。配置解析后应能**打印生效配置快照**（脱敏）便于排障。
+
+## 3. 启动即校验（fail-fast）
+
+配置错误必须在**进程启动的最初几秒**暴露，而不是跑到第一个用到该配置的请求才崩——那时已经在线上了。
+
+- **必需项缺失即拒绝启动**：所有 required 配置在 boot 阶段检查，缺一个就打印清晰错误并退出非零码，绝不带病启动。
+- **类型与取值域校验**：端口必须是数字、超时必须为正、URL 必须可解析、枚举必须在允许集合内——用 schema（如结构化配置类型 + 校验器）统一校验，不要散落在各处 `parseInt`。
+- **依赖连通性可选探活**：对关键依赖（DB/缓存）在 readiness 前做一次连通探测，把"配错地址"挡在接流量之前（见 `backend/01-standards/config-and-observability` 的健康检查）。
+- **校验信息可读**：错误要说清"哪个键、期望什么、实际拿到什么、从哪个来源读的"，让人 5 秒定位，而不是一个裸 `NullPointerException`。
+
+## 4. 环境对等（dev / staging / prod parity）
+
+环境之间差异越小，"本地好的、线上挂的"越少。
+
+- **同构而非异构**：各环境用**相同的**依赖种类与版本（同样的数据库引擎、同样的队列、同样的运行时版本），差异只在规格与数据量，不在技术栈。staging 必须尽可能贴近 prod。
+- **配置键集合一致**：所有环境拥有**相同的配置键集合**，只是值不同。新增一个配置项，必须同时为所有环境提供值（哪怕是默认），杜绝"prod 少配了一个键"。
+- **用 .env.example 锁定契约**：仓库里提供 `.env.example`（或等价的配置模板）列出全部键与占位说明；真实的 `.env` 入 gitignore。CI 校验"代码里读取的键"⊆"模板声明的键"。
+- **禁止环境特判代码**：代码里出现 `if (env === 'prod')` 改变业务逻辑是反模式；环境差异应体现为**配置值**，不是**代码分支**。可观测性、日志级别等运行差异也走配置。
+
+## 5. 密钥的生命周期
+
+密钥是配置里风险最高的一类，单列治理：
+
+- **绝不进仓库/镜像/日志**：密钥不提交版本库、不打进镜像层、不打印到日志与错误信息、不进前端可见的产物。提交前用 secret 扫描挡住（见 `security/01-standards/supply-chain-security`、`security/secrets-management`）。
+- **运行时注入**：密钥在运行时从密钥管理服务注入（环境变量 / 挂载 / SDK 拉取），应用只持有引用不持有明文落盘。
+- **可轮换**：密钥支持**无停机轮换**——应用能感知新密钥并平滑切换，轮换不需要改代码、不需要长停机。设定轮换周期与到期告警。
+- **最小权限**：每个服务只拿它需要的密钥；不同环境用**不同**密钥，绝不 dev 与 prod 共用一把。
+- **泄露应急**：密钥一旦疑似泄露，流程是**立即吊销 + 轮换**，而不是"先观察"。
+
+## 6. 配置变更管理（配置即代码）
+
+线上配置变更和代码发布一样危险——很多重大故障是"改了一个配置值"引发的。
+
+- **配置走版本控制与评审**：非密钥配置以**配置即代码**方式管理（声明式文件入库 + PR 评审 + diff 可见），不在控制台手改无记录。
+- **变更可审计**：谁、何时、把哪个键从什么改成什么，要有审计记录（见 `compliance/audit-logging-and-evidence`）。
+- **变更可回滚**：配置有版本历史，能一键回滚到上一个已知良好版本；回滚和发布同等重要。
+- **高风险配置灰度**：影响面大的配置（限流、超时、开关）变更要能**灰度 + 监控 + 快速回退**，不要全量瞬时生效。
+- **运行时热更要安全**：支持热更新的配置，变更后要有校验与生效确认；不可在无校验下让一个错值瞬间打到全量。
+
+## 7. 配置漂移与一致性
+
+- **检测漂移**：定期比对"声明的期望配置"与"运行时实际配置"，发现手动改动导致的漂移并告警。运行时实际值应能导出与基线比对。
+- **不可变基础设施优先**：环境通过声明式 IaC 重建而非手动改出来，从根上减少漂移（见 `cloud-native` / `devops/terraform`）。
+- **配置与制品绑定可追溯**：每次部署记录"用了哪个制品版本 + 哪个配置版本"，出事能精确反查组合。
+
+## 8. 反模式（出现即不合格）
+
+1. **硬编码 + 环境特判**：地址/密钥写死在代码里，或用 `if (env==='prod')` 改业务逻辑。
+2. **密钥进仓库/镜像/日志**：token、口令出现在代码、配置仓库、镜像层或日志中。
+3. **缺配置跑到一半才崩**：没有启动校验，错误在第一个用到的请求才暴露在线上。
+4. **环境键集合不一致**：prod 少配/多配了键，本地与线上技术栈不同，"本地好的线上挂"。
+5. **每个环境单独构建**：制品不是环境无关的，切环境要重新打包，破坏可追溯性。
+6. **控制台手改无记录**：线上配置在控制台裸手改，无评审、无审计、无法回滚。
+7. **配置来源含糊**：同一个键多处可能生效，实际取了哪个值靠猜。
+8. **密钥无法轮换**：密钥写死，轮换需要改代码或长停机；dev 与 prod 共用密钥。
+
+## 9. 最低交付 checklist
+
+- [ ] 配置与代码分离、密钥与普通配置分离、制品环境无关（同一产物跑所有环境）。
+- [ ] 配置来源优先级唯一且文档化，能打印脱敏后的生效配置快照。
+- [ ] 启动即校验：必需项缺失/类型错/取值越界立即 fail-fast 并给可读错误。
+- [ ] 各环境配置键集合一致，提供 `.env.example` 模板，CI 校验代码读取的键⊆模板。
+- [ ] 代码中无 `if(env)` 改业务逻辑；环境差异只体现为配置值。
+- [ ] 密钥运行时注入、不入仓库/镜像/日志、可无停机轮换、按环境隔离、有到期告警。
+- [ ] 非密钥配置以配置即代码方式入库评审，变更可审计、可回滚、高风险项可灰度。
+- [ ] 定期检测配置漂移；部署记录制品版本 + 配置版本可追溯。