@umacloud/knowledge 1.0.15 → 1.0.17

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/01-standards/app-runtime-model-configurable.md

@@ -0,0 +1,76 @@
+---
+id: app-runtime-model-configurable
+title: 应用运行时模型可配置（别硬编码开发底座的厂商）
+domain: ai
+category: 01-standards
+difficulty: intermediate
+tags: [llm, 运行时模型, 可配置, provider-abstraction, openai-compatible, dashscope, qwen, 大模型, 多厂商, env, 配置, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+
+# 应用运行时模型可配置（别硬编码开发底座的厂商）
+
+> 常见踩坑：用某个 AI 编码工具开发一个“会在运行时调用大模型”的应用时，生成的后端把运行时的 LLM 直接写死成开发工具自己用的那家（例如 Anthropic/Claude + `ANTHROPIC_API_KEY`）。用户想让交付的应用跑通义千问 / OpenAI / 本地模型，还得手工改后端。**开发用的工具底座，和应用运行时调用的模型，是两件完全不同的事，绝不能混为一谈。**
+
+## 1. 核心原则
+
+- **两层模型分离**：「开发期借用的大脑（写代码的工具）」≠「应用运行时调用的模型」。后者是业务选型，由需求/用户决定，不是由你用什么工具写代码决定。
+- **运行时模型是配置项，不是常量**：模型 id、base URL、API Key 的环境变量名，三者都必须来自配置（环境变量 / 配置文件），代码里不出现写死的厂商端点或密钥。
+- **默认值跟随需求**：需求里点名了运行时模型/厂商（如“运行时用千问 Max”“用 DashScope”“用 OpenAI”），就把默认配置指向它；没点名时，生成一个清晰可替换的 provider 占位层，并在交付物里说明“运行时模型可配置、怎么切换”。
+- **绝不静默套用开发底座的厂商**：不要因为写代码时用的是某家工具，就把应用运行时也默认写成那家。
+
+## 2. Provider 抽象层（最小骨架）
+
+把对模型的调用收敛到一个薄抽象层，业务代码只依赖这个层，不直接耦合任意一家 SDK 的端点。
+
+- 三元组来自配置：`model`（模型 id）、`base_url`（接入地址）、`api_key`（从指定环境变量读取）。
+- 优先用 **OpenAI 兼容协议**的客户端：同一套 `base_url + api_key + model` 即可覆盖 OpenAI、DashScope/通义千问、DeepSeek、智谱 GLM、Moonshot/Kimi、本地 Ollama 等大多数主流厂商——换厂商是改配置，不是改代码。
+- 不兼容 OpenAI 协议的厂商（个别国产/自研网关），在抽象层内部各写一个 adapter，对外暴露统一接口。
+
+```bash
+# .env.example —— 运行时模型可配置（默认值跟随需求；未点名则留可替换占位）
+LLM_PROVIDER=openai-compatible
+LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1   # 例：通义千问 DashScope 兼容端点
+LLM_MODEL=qwen-max                                               # 切换模型只改这一行
+LLM_API_KEY_ENV=DASHSCOPE_API_KEY                                # 真正的密钥放在被引用的环境变量里
+DASHSCOPE_API_KEY=                                               # 由部署方注入，不进版本库
+```
+
+```ts
+// llm.ts —— 业务只调用这一层，端点/密钥/模型全部来自配置
+import OpenAI from "openai"; // OpenAI 兼容客户端可对接多数厂商
+
+const apiKeyEnv = process.env.LLM_API_KEY_ENV ?? "OPENAI_API_KEY";
+const client = new OpenAI({
+  baseURL: process.env.LLM_BASE_URL,          // 配置驱动，可指向千问/OpenAI/本地
+  apiKey: process.env[apiKeyEnv],             // 从“被指定的环境变量名”读取真实密钥
+});
+
+export async function chat(messages: { role: string; content: string }[]) {
+  return client.chat.completions.create({
+    model: process.env.LLM_MODEL ?? "gpt-4o-mini", // 默认值跟随需求；切换只改配置
+    messages,
+  });
+}
+```
+
+## 3. 落地清单（Checklist）
+
+- [ ] 运行时 `model` / `base_url` / `api_key` 全部来自环境变量或配置文件，源码里没有写死的厂商端点或密钥。
+- [ ] 需求点名了运行时厂商/模型 → 默认配置已指向它；未点名 → 留下清晰可替换的 provider 占位，且在 README/`.env.example` 写明如何切换。
+- [ ] 对接走 provider 抽象层，业务代码不直接依赖某一家 SDK 的硬编码端点。
+- [ ] 优先 OpenAI 兼容协议；非兼容厂商在抽象层内做 adapter，对外接口统一。
+- [ ] 密钥只从环境变量注入，`.env` 不进版本库，仓库里只放 `.env.example` 占位。
+- [ ] 交付物（README / 配置说明）明确写出“运行时模型可配置”，并给出切换到千问/OpenAI/本地模型的具体步骤。
+- [ ] 提供超时、重试、错误兜底；切换厂商不需要改业务代码，只改配置即可生效。
+- [ ] 不把开发所用工具底座的厂商（如 Anthropic/Claude）当成应用运行时的默认值。
+
+## 4. 反模式（出现即不合格）
+
+- 把应用运行时的 LLM 写死成开发工具自己用的那家（典型：默认 `ANTHROPIC_API_KEY` + Claude 端点），无视用户在需求里指定的运行时模型。
+- 厂商端点 / 模型 id / 密钥硬编码在业务代码里，换模型要改源码、重新构建。
+- 用户明确说“运行时用千问 / DeepSeek / 本地模型”，生成的代码却仍调另一家。
+- 只支持单一厂商、没有 provider 抽象层，后续接第二家要大改。
+- 把真实密钥写进源码或提交进版本库；没有 `.env.example` 占位与切换说明。
+- 没在交付物里说明运行时模型可配置，用户只能逆向源码才知道怎么换。

package/ai/agent-evaluation-benchmark.md

@@ -1,16 +1,14 @@
 ---
 id: agent-evaluation-benchmark
-title: agent-evaluation-benchmark
+title: Agent 评测与基准体系
 domain: ai
-category: agent-evaluation-benchmark.md
+category: 01-standards
 difficulty: intermediate
-tags: [agent, ai, benchmark, evaluation, 评测与基准体系]
+tags: [agent, 评测, benchmark, evaluation, 基准集, 发布门禁, 回归评测, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## Agent 评测与基准体系
+# Agent 评测与基准体系
 
 ### 目标
 - 让 Agent 能力可量化、可回归、可持续优化。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-agent-memory-context-management
-title: ai-agent-memory-context-management
+title: AI Agent上下文与记忆管理
 domain: ai
-category: ai-agent-memory-context-management.md
+category: 01-standards
 difficulty: intermediate
-tags: [agent, agent上下文与记忆管理, ai, context, management, memory]
+tags: [agent, 记忆管理, memory, context, 上下文压缩, 多轮对话, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI Agent上下文与记忆管理
+# AI Agent上下文与记忆管理
 
 ### 目标
 - 在成本可控前提下提升多轮任务连续性与决策一致性。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-cost-capacity-optimization-playbook
-title: ai-cost-capacity-optimization-playbook
+title: AI成本与容量优化手册
 domain: ai
-category: ai-cost-capacity-optimization-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai成本与容量优化手册, capacity, cost, optimization, playbook]
+tags: [成本优化, cost, capacity, 容量规划, 模型路由, prompt压缩, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI成本与容量优化手册
+# AI成本与容量优化手册
 
 ### 目标
 - 在保证业务效果的前提下，实现可持续的AI成本与容量治理。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-data-security-and-compliance-playbook
-title: ai-data-security-and-compliance-playbook
+title: AI数据安全与合规作战手册
 domain: ai
-category: ai-data-security-and-compliance-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai数据安全与合规作战手册, and, compliance, data, playbook, security]
+tags: [数据安全, compliance, 合规, 脱敏, 审计日志, 数据治理, ai, security]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI数据安全与合规作战手册
+# AI数据安全与合规作战手册
 
 ### 目标
 - 确保AI系统在数据采集、处理、存储、传输全链路满足安全与合规要求。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-domain-index-and-checklist
-title: ai-domain-index-and-checklist
+title: AI领域索引与执行清单
 domain: ai
-category: ai-domain-index-and-checklist.md
+category: 03-checklists
 difficulty: intermediate
-tags: [ai, ai领域索引与执行清单, and, checklist, domain, index]
+tags: [索引, checklist, 执行清单, 上线门禁, ai, llm, rag, 核查清单]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI领域索引与执行清单
+# AI领域索引与执行清单
 
 ### 目标
 - 为AI需求、方案、上线、运行提供统一入口和核查清单。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-governance-maturity-model
-title: ai-governance-maturity-model
+title: AI治理成熟度模型
 domain: ai
-category: ai-governance-maturity-model.md
+category: 01-standards
 difficulty: intermediate
-tags: [ai, ai治理成熟度模型, governance, maturity, model]
+tags: [治理, 成熟度模型, maturity, governance, 能力评估, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI治理成熟度模型
+# AI治理成熟度模型
 
 ### 目标
 - 用统一量表评估AI研发和运营能力，指导分阶段治理提升。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-model-selection-and-routing-strategy
-title: ai-model-selection-and-routing-strategy
+title: AI模型选型与路由策略
 domain: ai
-category: ai-model-selection-and-routing-strategy.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai模型选型与路由策略, and, model, routing, selection, strategy]
+tags: [模型选型, 路由, routing, model-selection, 多模型, 灰度, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI模型选型与路由策略
+# AI模型选型与路由策略
 
 ### 目标
 - 在准确率、时延、成本和稳定性之间取得可量化最优平衡。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-observability-and-oncall-runbook
-title: ai-observability-and-oncall-runbook
+title: AI可观测性与值班Runbook
 domain: ai
-category: ai-observability-and-oncall-runbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai可观测性与值班runbook, and, observability, oncall, runbook]
+tags: [可观测性, observability, oncall, runbook, 值班, 告警, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI可观测性与值班Runbook
+# AI可观测性与值班Runbook
 
 ### 目标
 - 建立AI系统运行态监控、告警、处置、复盘的标准流程。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-rag-engineering-playbook
-title: ai-rag-engineering-playbook
+title: AI RAG工程作战手册
 domain: ai
-category: ai-rag-engineering-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, engineering, playbook, rag, rag工程作战手册]
+tags: [rag, 检索增强, retrieval, 召回, 重排序, 向量检索, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI RAG工程作战手册
+# AI RAG工程作战手册
 
 ### 目标
 - 构建高召回、高精度、低幻觉的检索增强生成系统。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-red-team-and-safety-evaluation
-title: ai-red-team-and-safety-evaluation
+title: AI红队测试与安全评估
 domain: ai
-category: ai-red-team-and-safety-evaluation.md
+category: 01-standards
 difficulty: intermediate
-tags: [ai, ai红队测试与安全评估, and, evaluation, red, safety, team]
+tags: [红队, red-team, 安全评估, safety, 提示注入, 越权, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI红队测试与安全评估
+# AI红队测试与安全评估
 
 ### 目标
 - 在上线前识别提示注入、越权调用、敏感泄漏、内容安全等高风险问题。

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

@@ -1,16 +1,14 @@
 ---
 id: ai-release-readiness-and-rollback-gate
-title: ai-release-readiness-and-rollback-gate
+title: AI发布就绪与回滚门禁
 domain: ai
-category: ai-release-readiness-and-rollback-gate.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai发布就绪与回滚门禁, and, gate, readiness, release, rollback]
+tags: [发布门禁, 回滚, rollback, release-gate, 灰度, 就绪评估, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## AI发布就绪与回滚门禁
+# AI发布就绪与回滚门禁
 
 ### 目标
 - 将AI能力发布纳入可量化门禁，确保上线可控与可回退。

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

@@ -1,16 +1,14 @@
 ---
 id: llm-agent-engineering-deep-dive
-title: llm-agent-engineering-deep-dive
+title: LLM 与 Agent 工程深度知识库
 domain: ai
-category: llm-agent-engineering-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [agent, ai, deep, dive, engineering, llm, 工程深度知识库]
+tags: [llm, agent, 工程化, prompt, 工具调用, 编排, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## LLM 与 Agent 工程深度知识库
+# LLM 与 Agent 工程深度知识库
 
 ### 目标
 - 建立可控、可测、可审计的 AI 研发与运行标准。