docs: 更新TRA编程培训课程材料、课件与AI技能交付包

- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
2026-08-08 11:00:36 +08:00
parent e7d6db93c3
commit 67837df8d0
169 changed files with 6618 additions and 2887 deletions
@@ -0,0 +1,132 @@
+# 模块 1：案例引子：从状态变更提取资产原料
+
+<div class="mt-6 text-sm">
+
+“取消原因不能为空”看起来只是一个字段校验，实际却处在派车、车辆、司机和行程状态交汇的位置。
+
+这里不讨论如何完成这一项改动，而是用它识别后续可沉淀的约束、提问框架与验证方法。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">申请</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">派车</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">车辆 / 司机</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">行程</div>
+</div>
+
+<!--
+逐字稿：先看这个案例的表面，它只是“取消时原因不能为空”。但它触及派车、车辆、司机和行程四条状态线，所以真正要处理的不是一个表单字段，而是状态写入前的业务保护。我们用这个案例提取后续能够复用的判断原料，而不把它当作通用业务答案。
+
+第五天不从“工具能做什么”开始，而是先用真实的状态机模块建立问题背景。模型能看到代码片段，但只有理解状态之间的关系，才有能力判断改动是否越界。
+-->
+
+---
+
+# 公务用车模块中的三条状态线
+
+<div class="mt-5 text-xs">
+
+| 对象 | 正常演进 | 取消或完成后的变化 |
+|---|---|---|
+| 申请 | `DRAFT -> PROCESSING -> COMPLETED` | 取消回到 `CANCELLED` |
+| 派车 | `DISPATCHED -> COMPLETED` | 取消变为 `CANCELLED` |
+| 车辆 | `AVAILABLE -> RESERVED -> IN_USE` | 取消或行程完成后回到 `AVAILABLE` |
+| 司机 | `AVAILABLE -> ON_TASK` | 行程完成后回到 `AVAILABLE` |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+一个派车动作会改变多个对象；校验位置错了，错误状态就会扩散。
+</div>
+
+<!--
+逐字稿：这里要先建立一个判断：派车不是孤立对象。取消派车会同时改变派车状态和车辆可用状态，后续还可能影响申请和行程的衔接。因此，任何校验如果放在状态写入之后，错误就可能扩散到多个对象。
+
+表中的状态来自 OfficialVehicleConstants，以及派车、出车、归还和验收的 Service 实现。这里不需要讲完整模块，而是让学员建立一个基本认识：不同对象的状态并不是独立的。
+
+取消派车时，派车状态改为 CANCELLED，车辆被释放回 AVAILABLE。任何无效取消都必须在这些写入动作之前被挡住。
+-->
+
+---
+
+# 取消派车的真实调用链
+
+<div class="mt-7 text-sm">
+
+```text
+取消按钮（仅 DISPATCHED 状态可见）
+  -> 取消弹窗（cancelReason 必填）
+  -> POST /official/vehicle/dispatch/cancel
+  -> Controller（权限 + 审计）
+  -> DispatchService.cancel
+  -> 派车状态 CANCELLED + 车辆状态 AVAILABLE
+```
+
+</div>
+
+<div class="mt-6 grid grid-cols-3 gap-3 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">前端：减少误操作</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">权限：限制谁能调用</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">Service：保护业务状态</div>
+</div>
+
+<!--
+逐字稿：这条链路说明了三层保护的职责差异。前端必填是为了减少误操作，权限控制的是谁有资格调用，而 Service 才负责保证业务状态不能被无效请求破坏。只要绕过前端仍能发请求，真正的业务保护就必须落在 Service 的状态写入之前。
+
+这是从 Vue 页面、API 文件、Controller 和 Service 真实读取出的调用链。三种保护不要混为一谈：前端负责交互体验，权限负责调用资格，Service 负责业务规则。
+
+这个区分直接决定了最小改动应该放在哪一层。
+-->
+
+---
+
+# 把业务语言变成可验证的目标
+
+<div class="mt-5 text-xs">
+
+| 业务表达 | 可验证的技术表达 |
+|---|---|
+| 取消必须写原因 | `cancelReason` 不能是 `null`、空串或全空白 |
+| 不允许无效取消 | 在读取派车记录、更新派车和释放车辆之前拒绝请求 |
+| 不能影响正常取消 | 非空原因仍沿用原有状态更新与资源释放逻辑 |
+| 不扩大改动 | 不改变权限、审计、页面交互、数据库字段或行程协议 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+目标越可验证，TRAE 越不容易把一个小需求扩写成跨层重构。
+</div>
+
+<!--
+逐字稿：业务语言必须被翻译成可验证的技术条件。这里不是笼统地说“原因必填”，而是明确空白值要在读取和写入之前被拒绝，同时确认正常取消仍会完成既有的状态更新和资源释放。这样才能约束改动范围，不让模型把小需求扩大成跨层重构。
+
+这张表建立后续所有分析和提示词的共同输入。业务语言如果只剩“取消原因必填”，模型很容易提出数据库 NOT NULL、Controller 参数校验、前端重构等多种方案。
+
+把边界写成可验证的技术表达，才能比较不同方案是否贴合当前项目。
+-->
+
+---
+
+# 从案例中提取资产原料
+
+<div class="grid grid-cols-3 gap-4 mt-8 text-sm">
+<div class="p-4 rounded-xl bg-blue-500/10 border border-blue-500/30">
+<div class="font-bold">项目事实</div>
+<div class="mt-2 text-xs op-70">状态、入口、权限、写入顺序和测试结构。</div>
+</div>
+<div class="p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30">
+<div class="font-bold">重复判断</div>
+<div class="mt-2 text-xs op-70">哪些结论下次同类任务仍然需要重新做。</div>
+</div>
+<div class="p-4 rounded-xl bg-amber-500/10 border border-amber-500/30">
+<div class="font-bold">可沉淀资产</div>
+<div class="mt-2 text-xs op-70">Rule、Prompt、Skill、检查单和反例各自承接什么。</div>
+</div>
+</div>
+
+<!--
+逐字稿：到这里，案例本身的任务已经完成了。我们已经拿到项目事实，也识别出哪些判断会在同类任务中反复出现。接下来要做的是把这些判断分别交给合适的资产承载，而不是把代码结论原样复制到下一个项目。
+
+案例到这里完成它的作用：提供真实、可核对的资产原料。第五天后续模块的核心不再是这一次改动，而是如何把这些原料拆成可以在下一次任务中复用的工程资产。
+-->
@@ -0,0 +1,163 @@
+# 模块 10：自定义 Agent 如何调用 Skill
+
+<div class="mt-6 text-sm">
+
+一个成熟的 Agent 不把所有知识写进自己身上。
+
+它负责选择合适的工作流、加载必要资产，并将结果交给下一步；Skill 继续负责具体任务的判断顺序和交付格式。
+
+</div>
+
+<div class="mt-8 text-sm">
+
+```text
+自定义 Agent（角色 + 工具边界）
+        -> 选择 Skill（任务工作流）
+        -> 加载 Rule / 任务上下文契约 / Checklist / Example
+        -> 输出结构化结论
+        -> 交给 Review、PR 或下一项任务
+```
+
+</div>
+
+<!--
+逐字稿：成熟 Agent 不应该把所有规则、流程和项目事实都写进默认指令。它的职责是以受控角色选择合适的 Skill，加载必要资产，并把结果结构化交给下一步。Skill 则继续负责具体任务的判断顺序和交付格式，两者的职责必须分开。
+
+Trae 具备 runSubagent 调用自定义 Agent 的能力，且必须使用准确的 Agent 名称。这说明角色可以被显式调度；但课程不依赖学员现场建立多 Agent 团队，重点是把 Agent 作为资产入口，保持名称、职责和输出可辨识。
+-->
+
+---
+
+# Agent、Skill 与 MCP 的本质区别
+
+<div class="mt-5 text-xs">
+
+| 对象 | 本质 | 负责什么 | 不负责什么 |
+|---|---|---|---|
+| Agent | 执行角色与权限边界 | 选择任务、调用 Skill 和工具、控制停止与交接 | 承载全部业务流程与项目事实 |
+| Skill | 可复用的任务工作流 | 规定输入、判断步骤、输出与验收 | 决定谁可调用、拥有什么工具权限 |
+| MCP | 外部能力接口 | 提供查询、读取、写入等工具能力 | 判断业务规则、决定任务流程 |
+
+</div>
+
+<div class="mt-7 grid grid-cols-3 gap-3 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">谁来做：Agent</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">如何做：Skill</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">能调用什么：MCP</div>
+</div>
+
+<!--
+逐字稿：三者可以用三个问题区分。谁来做，是 Agent，它定义角色、工具权限和停止边界；如何做，是 Skill，它定义任务步骤、输入、输出和验收；能调用什么外部能力，是 MCP，它提供查询、读取和写入接口。MCP 不做业务判断，Skill 不决定权限，Agent 也不应承载全部项目事实。
+
+Agent 是角色与权限边界，Skill 是任务工作流，MCP 是外部能力接口。三者组合时，不应让 MCP 承担业务判断，也不应把 Skill 复制成 Agent 的默认指令。
+-->
+
+---
+
+# 不同信息应该放在哪里？
+
+<div class="mt-5 text-xs">
+
+| 信息类型 | 最合适的位置 | 原因 |
+|---|---|---|
+| “先取证，缺口必须暴露” | Rule / Agent 默认指令 | 多个任务都必须遵守 |
+| “状态变更如何审查” | Skill | 需要多步判断与停止条件 |
+| “影响分析报告长什么样” | 任务上下文契约 / Template | 下游需要固定结构 |
+| “五项不可遗漏检查” | Checklist | 适合逐项核对 |
+| “数据库 NOT NULL 不适用的条件” | Example / 反例 | 防止机械套用 |
+| 某项目的路径、字段和日志 | 运行时输入 | 换任务或换项目会变化 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+一份内容只应有一个权威位置；重复复制到 Agent、Skill 和任务上下文契约中，更新时一定会漂移。
+</div>
+
+<!--
+逐字稿：同一份内容只能有一个权威位置。长期约束放 Rule，多步审查放 Skill，报告结构放任务上下文契约或模板，固定遗漏点放 Checklist，项目路径和字段留在运行时输入。复制到多个位置看似方便，实际会在更新时产生相互矛盾的版本。
+
+这里回答了“为什么不是把所有内容写进自定义 Agent”。正确做法是给每种资产一个单一职责和权威来源，Agent 通过引用或选择来组合它们。
+-->
+
+---
+
+# 上下文分层：稳定、任务与事实
+
+<div class="mt-5 text-xs">
+
+| 层级 | 内容 | 更新频率 | 典型落点 |
+|---|---|---|---|
+| 稳定层 | 角色职责、最小授权、通用安全规则 | 低 | 自定义 Agent、Rule |
+| 任务层 | 事实提取、方案比较、验证设计流程 | 中 | Skill、任务上下文契约、Checklist |
+| 事实层 | 当前需求、源码、diff、日志和测试结果 | 高 | 本次对话或任务输入 |
+
+</div>
+
+<div class="mt-6 grid grid-cols-3 gap-3 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">稳定层错了<br><span class="text-xs op-70">所有任务都会偏</span></div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">任务层错了<br><span class="text-xs op-70">同类任务反复偏</span></div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">事实层缺失<br><span class="text-xs op-70">当前结论必须停止</span></div>
+</div>
+
+<!--
+逐字稿：上下文可以按更新频率分成三层。稳定层是角色职责和安全规则，任务层是事实提取和验证流程，事实层是当前需求、源码、diff 和日志。输出偏差时先判断问题在哪一层，而不是随机改一段长指令；事实缺失时，当前结论就应停止。
+
+这是资产维护的关键模型。它让问题可定位：每次输出不对，先判断是 Agent 职责定义、Skill 流程、任务上下文契约还是当前事实不够，而不是随机重写一段长提示词。
+-->
+
+---
+
+# Agent 之间只交接结构化结果
+
+<div class="mt-5 text-xs">
+
+```md
+## 已确认事实
+- <证据路径或记录>
+
+## 交接去向
+- <应调用的 Skill 或应执行的验证>
+
+## 输入缺口
+- <缺少什么，为什么不能继续>
+
+## 不可覆盖的边界
+- <权限、范围、状态或发布限制>
+```
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+交接的是可复核结论，不是把完整对话、推理过程和未经验证的猜测交给下一个 Agent。
+</div>
+
+<!--
+逐字稿：Agent 之间不应交接完整对话或未验证推理，而应交接结构化结果。下一个角色需要知道哪些事实已经确认、建议下一步是什么、还缺什么输入，以及哪些权限或范围不能覆盖。即使只有一个 Agent，这种结构也能让后续 Review 和实施不必重新猜上下文。
+
+即使不使用多 Agent，这个结构同样适用于“分析 Agent 的输出交给实施 Agent”或“实施结果交给 Review Agent”。结构化结果让后续 Agent 知道哪些是事实、哪些是建议、哪些不能继续推断。
+-->
+
+---
+
+# Agent 与 Skill 组合的三种失效方式
+
+<div class="mt-5 text-xs">
+
+| 失效方式 | 表现 | 修正方向 |
+|---|---|---|
+| Agent 变成万能角色 | 读、改、测、发、审全都默认允许 | 按职责拆分，降低工具权限 |
+| Skill 被复制进 Agent | 多份流程说明彼此不一致 | Skill 保持唯一工作流来源 |
+| 交接只有自然语言总结 | 下游重新猜事实、范围和验证状态 | 使用固定输出契约 |
+| 运行时事实混入资产 | 换项目仍引用旧路径、字段和权限 | 把事实移回每次任务输入 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+组合的目的不是增加层数，而是让角色、工作流和事实各自保持可维护。
+</div>
+
+<!--
+逐字稿：组合 Agent 和 Skill 的目标不是增加层数，而是减少重复和失控。万能 Agent 会造成越权，Skill 被复制进 Agent 会产生多份流程，纯自然语言交接会让下游重新猜事实，运行时事实混入资产会误用旧项目。只要出现这些信号，就应收缩角色和工作流设计。
+
+提醒学员：Agent、Skill 的组合不是“堆更多配置”。如果组合后找不到哪份文件是权威来源，或者没有减少重复判断，就应当收缩设计。
+-->
@@ -0,0 +1,285 @@
+# 模块 11：历史代码治理与可交付资产库
+
+<div class="mt-6 text-sm">
+
+资产库不是提示词文件夹。
+
+一份可交付资产要让使用者看得出：解决什么重复问题、需要什么输入、如何运行、输出什么、什么情况下不能继续，以及如何验证它仍然有效。
+
+</div>
+
+<div class="grid grid-cols-5 gap-3 mt-8 text-xs">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">项目约束生成</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">项目知识构建</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">复杂业务设计</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">业务交付 Review</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">Review 修复闭环</div>
+</div>
+
+<!--
+逐字稿：资产库不是把好用的提示词集中存放，而是让使用者可以判断何时该用、需要什么输入、会得到什么结果、在哪些情况下不能继续。当前交付包中的五个 Skill 都是已有真实材料，它们的共同点是能被发现、运行、验证和维护，而不是目录看起来整齐。
+
+课程交付包中已存在以上五个真实 Skill 包，均有 SKILL.md，部分还包含 agents/openai.yaml、Prompt、模板、检查单、反例、参考资料或脚本。本模块直接以这些现有资产为原料，不捏造新的目录规范。
+-->
+
+---
+
+# 历史代码识别：先定位职责交界
+
+<div class="mt-5 text-xs">
+
+`OfficialVehicleDispatchServiceImpl.assign` 不是已被判定的缺陷；源码能确认的是，它是一个同时协调多个业务对象的入口。
+
+| 源码事实 | 涉及对象 | 重构时必须保留的含义 |
+|---|---|---|
+| 申请已完成、且不能重复派车 | 申请 / 派车 | 拒绝条件仍在任何写入之前 |
+| 车辆可用且时间不冲突 | 车辆 / 派车 | 车辆选择不是只看当前状态 |
+| 需要司机时司机必填、且时间不冲突 | 司机 / 派车 | `needDriver` 决定额外前置条件 |
+| 创建派车任务后预占车辆 | 派车 / 车辆 | 两次写入处于同一个事务中 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
+“职责交界较多”是重构候选，不等同于“现有实现有错误”。
+</div>
+
+<!--
+逐字稿：远程大纲里的历史代码问题识别，不能靠看函数长短就下结论。这个真实的 assign 方法大约四十行，但已经协调申请、车辆、司机和派车任务四类对象。它既校验状态和时间冲突，又写入派车任务和车辆状态。
+
+这里能得出的专业结论是：它是值得评估的重构候选，因为职责交界多；不能直接说它是坏代码或有生产缺陷。TRAE 的第一步应该把每一条源码事实、涉及对象和不可改变的含义列清楚，而不是立刻要求它输出一份重构 Diff。
+-->
+
+---
+
+# 重构方案先比选，再决定是否拆分
+
+<div class="mt-5 text-xs">
+
+| 方案 | 对当前 `assign` 的处理 | 依据与判断 |
+|---|---|---|
+| 保留编排入口，提取校验段 | 分出申请、车辆、司机校验与派车创建的内部方法 | 保持事务、写入顺序和接口不变，便于定向测试 |
+| 合并车辆与司机冲突校验 | 抽成通用“资源冲突”组件 | 当前只有查询形状相似，数据模型和错误语义是否统一尚无证据 |
+| 将业务校验移动到前端 | 依赖页面下拉选项和表单必填 | 前端可被绕过，不能代替 Service 的业务保护 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+当前源码支持“先做内部拆分的可行性评估”，不支持直接引入跨领域的通用抽象。
+</div>
+
+<!--
+逐字稿：有了职责事实，第二步才是方案比选。对当前代码，最小且可证实的候选方案是保留 assign 作为事务编排入口，把申请、车辆、司机校验以及派车创建拆成内部职责段。这样不改变 Controller、接口和写入顺序，同时让关键判断可以被单独阅读和测试。
+
+车辆和司机的时间冲突查询看起来相似，但它们的对象、字段和错误语义是否适合统一，目前没有足够事实。因此不能因为“看到重复”就强行抽象。把校验搬到前端同样不成立，因为接口仍可被绕过。TRAE 输出的应是方案比选与依据，而不是未经审查的改写代码。
+-->
+
+---
+
+# 重构风险审查要逐项回到现有行为
+
+<div class="mt-5 text-xs">
+
+以 `cancel` 为例，以下行为来自当前 Service、Controller 和事务注解：
+
+| 风险点 | 当前行为 | 重构后的验证点 |
+|---|---|---|
+| 输入保护 | 空白取消原因在查询与写入之前被拒绝 | 无效输入不能读取或修改业务状态 |
+| 状态保护 | 只有 `DISPATCHED` 的派车任务可取消 | 非法状态被拒绝，不能释放车辆 |
+| 写入耦合 | 派车变为 `CANCELLED` 并记录原因；车辆恢复 `AVAILABLE` | 两类状态同时成功，异常时整体回滚 |
+| 接口边界 | Controller 保留取消权限、审计记录与成功语义 | 不因内部拆分丢失权限或审计入口 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+风险清单不是重构方案的附录，而是判断“能否改”的前提。
+</div>
+
+<!--
+逐字稿：重构风险审查要回到可以观察的现有行为。这里以 cancel 为例：空白原因必须先被拒绝；只有已派车状态才能取消；取消会同时更新派车和车辆；Controller 还承载权限和审计入口。这些都不是一般性原则，而是当前项目源码已经具备的行为。
+
+任何拆分或整理代码的方案，都必须逐项说明如何保护这些行为。否则即使方法更短，也可能让非法取消释放车辆，或者在异常时留下半完成状态。第五天在这里讲的是重构前的风险清单；第六天才会处理改动完成后的 PR、CI 和回退证据。
+-->
+
+---
+
+# TypeScript 类型治理：类型不能遮住契约冲突
+
+<div class="mt-5 text-xs">
+
+当前公务用车模块已经提供了一个需要核验的跨端契约案例：
+
+| 位置 | 现有定义或行为 | 需要确认的事实 |
+|---|---|---|
+| 后端常量 | 审批结果仅定义 `pass` / `reject` | Service 只接受这两个小写值 |
+| 前端类型 | `ApproveResult` 同时允许大小写字符串和 `boolean` | 放宽联合类型掩盖了实际允许范围 |
+| 前端表单 | 审批选项提交 `PASS` / `REJECT` | 请求载荷与后端接收值是否一致 |
+| 申请状态模型 | 后端为字符串，前端同时接受字符串与 `number` | 需要明确接口中的唯一表示方式 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+源码已证明存在定义差异；是否发生运行时错误，仍需以实际请求和接口验证为准。
+</div>
+
+<!--
+逐字稿：远程大纲里的 TypeScript 类型治理，在当前项目中不是补一份 interface，而是发现跨端契约被宽泛类型掩盖的情况。后端审批常量只定义小写 pass 和 reject；前端类型却允许大小写字符串和布尔值，表单实际配置的是大写值。申请状态也同时接受字符串和数字，而后端实体是字符串。
+
+这里要严格区分事实和推断：源码已经能证明定义存在差异，但没有实际请求或接口执行记录，不能直接声称线上一定报错。正确的资产产出是类型契约和核验项：每个字段的唯一表示、允许值、请求样例、服务端拒绝语义以及对应测试，而不是继续用更宽的联合类型把问题藏起来。
+-->
+
+---
+
+# 现有测试证明了什么，也暴露了什么
+
+<div class="mt-5 text-xs">
+
+| 已有测试证据 | 能支持的结论 | 仍不能支持的结论 |
+|---|---|---|
+| `OfficialVehicleDispatchServiceImplTest` | 空白取消原因会在依赖访问前被拒绝 | 正常取消是否更新派车和车辆状态 |
+| `OfficialVehicleDispatchControllerTest` | 接口委派、成功提示和 Service 异常透传 | Service 内的状态校验、事务与持久化结果 |
+| 官方车辆模块的 Maven 测试配置 | 该后端模块可以执行 Surefire 测试 | 所有状态分支均已覆盖 |
+| 前端 `jest.config.mjs` | 当前前端已有 Jest 测试基座 | 派车页面或模型已经具备测试 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-purple-500/10 border border-purple-500/30 text-sm">
+“已有单测通过”只能说明已运行的场景通过，不能替代对未覆盖状态和副作用的判断。
+</div>
+
+<!--
+逐字稿：这张表只陈述已经找到的测试证据。Service 测试验证空白原因会立即抛出异常；Controller 测试验证请求是否正确委派、成功消息和异常透传。它们都很有价值，但还不能证明正常取消后派车状态和车辆状态是否按预期同时更新，也不能证明 assign 的多种拒绝条件。
+
+前端项目使用 Jest 配置，后端官方车辆模块使用 JUnit 和 Maven Surefire。测试通过的正确表述应该是“已覆盖某个场景”，而不是“取消功能已经全面验证”。这也是让 TRAE 生成测试前必须提供的基线信息。
+-->
+
+---
+
+# 单测补齐必须服从当前项目的测试基座
+
+<div class="mt-5 text-xs">
+
+远程大纲中的“Vitest 单测补齐”，在当前项目应转换为“按既有测试框架补齐行为证据”。
+
+| 测试目标 | 当前适用基座 | 应补的行为证据 |
+|---|---|---|
+| Service 规则 | JUnit 5 / Mockito | 非 `DISPATCHED` 取消被拒绝且不写入；正常取消同步更新派车与车辆 |
+| 派车前置条件 | JUnit 5 / Mockito | 未审批、重复派车、车辆不可用、需司机但缺司机等分支 |
+| 前端请求与模型 | Jest / Vue Test Utils | 审批值的真实载荷、派车表单的必填与可见条件 |
+| 跨端类型契约 | API 验证或集成测试 | 大小写审批值、状态值表示与服务端拒绝语义 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-cyan-500/10 border border-cyan-500/30 text-sm">
+不为引入新工具而另起 Vitest；先让现有 JUnit 和 Jest 覆盖真实业务行为。
+</div>
+
+<!--
+逐字稿：原远程大纲写的是 Vitest 单测补齐，但当前前端仓库实际配置的是 Jest，后端官方车辆模块已有 JUnit 和 Surefire。因此课程不应该为了贴合一个框架名而新增第二套前端测试体系。正确做法是沿用当前项目基座，把测试补到真实业务风险上。
+
+后端优先补状态拒绝、正常取消的两类写入，以及 assign 的关键前置条件；前端优先验证请求载荷和动态表单条件；跨端类型差异需要 API 或集成验证。这样“测试用例生成”和“单测补齐”才是对现有工程负责的工作，而不是制造新的工具负担。
+-->
+
+---
+
+# 拆开一个真实 Skill 包
+
+<div class="mt-5 text-xs">
+
+```text
+track-review-fix-loop/
+├── SKILL.md                         # 输入、状态模型、流程、输出与质量门禁
+├── agents/openai.yaml               # 展示名、简介和默认触发语
+└── assets/
+    ├── 修复记录生成.prompt.md         # 将原始材料整理为固定结构
+    ├── 修复记录.template.md           # 下游可消费的结果格式
+    ├── Review修复闭环检查清单.md       # 固定遗漏点
+    └── 多份反例.md                    # 权限、审计、状态等典型误用
+```
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
+核心文档不求长，而是把“输入、判断、输出、停止、验证”写成能被人和 Agent 同时执行的契约。
+</div>
+
+<!--
+逐字稿：以这个真实 Skill 包为例，核心不在某个文件名，而在于每份文件都有明确职责。`SKILL.md` 定义输入、状态模型和质量门禁，模板定义下游结果，检查单保护固定遗漏点，反例帮助识别典型误用。完整交付的是一套能执行的判断结构，不是一段单独的文本。
+
+目录和文件名均来自当前交付包中的真实 track-review-fix-loop Skill。讲解时可打开对应文件，展示为何一个成熟 Skill 不会只有一段大 Prompt：它还要有固定输出、检查清单和反例。
+-->
+
+---
+
+# 资产库需要一个可检索的索引
+
+<div class="mt-5 text-xs">
+
+| 索引字段 | 要回答的问题 | 示例 |
+|---|---|---|
+| 资产名称与类型 | 这是 Rule、Prompt、Skill 还是 Agent？ | 状态变更审查 Agent |
+| 适用信号 | 什么任务应该选择它？ | 涉及状态写入或资源释放 |
+| 必要输入 | 缺少什么就不能运行？ | 目标、源码、状态规则、验证记录 |
+| 输出契约 | 结果能交给谁使用？ | 事实表、方案比较、验证清单 |
+| 权威位置 | 应到哪个文件更新？ | Skill 的 SKILL.md 或 assets/ |
+| 复核触发 | 什么变化会使它失效？ | 框架、流程、接口或真实误用变化 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+索引不记录“有哪些好提示词”，而是帮助使用者快速判断“此刻该用哪一份资产”。
+</div>
+
+<!--
+逐字稿：资产库必须有索引，否则使用者只能凭文件名猜。索引要说明资产是什么、何时使用、缺什么不能运行、输出给谁、权威位置在哪里，以及什么变化会触发复核。它服务的是正确选择和正确使用，不是管理动作的清单。
+
+资产目录不是客户组织管理方案，而是技术资产的使用入口。索引字段的目的在于定位和正确使用，尤其避免一个新任务随意挑选错误的 Skill 或 Agent。
+-->
+
+---
+
+# 用测试夹具验证资产，而不是验证文案
+
+<div class="mt-5 text-xs">
+
+| 夹具类型 | 提供的材料 | 应观察的行为 |
+|---|---|---|
+| 完整事实 | 入口、状态、diff 与测试记录齐全 | 结论可追溯，输出结构完整 |
+| 证据缺失 | 缺少关键 Service 或验证记录 | 明确列出缺口并停止结论 |
+| 范围冲突 | 同时要求改数据库、权限和页面 | 指出越界，不默认扩大改动 |
+| 反例输入 | 已知的权限、审计或状态误用 | 能识别风险并引用检查项 |
+| 跨项目输入 | 不同目录、字段、框架和测试基座 | 重新取证，不复制旧项目结论 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+资产测试关心的是边界是否正确，不要求模型每次生成完全相同的句子。
+</div>
+
+<!--
+逐字稿：验证资产时要使用夹具，而不是只读文案。完整材料用于确认结果能回指证据，缺失材料用于确认会停止，范围冲突用于确认不会扩大改动，反例用于确认能识别风险，跨项目材料用于确认不会复制旧结论。生成式资产的正确性看边界和结构，不看每个字是否一样。
+
+测试夹具是资产长期可靠的关键。它可以只是几个整理好的输入目录和预期行为，也可以逐步发展为自动化评测。无论形式如何，都要覆盖完整、缺失、冲突、反例和跨项目五类场景。
+-->
+
+---
+
+# 资产库还应包含 MCP 能力契约
+
+<div class="mt-8 text-lg">
+案例提供事实；资产保存判断；自定义 Agent 在受控权限下调用这些资产。连接外部系统的 MCP 还需要独立的能力与权限契约。
+</div>
+
+<div class="grid grid-cols-6 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">选型</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">Rule</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">Prompt</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">Skill</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">Agent</div>
+<div class="p-3 rounded-xl bg-cyan-500/10 border border-cyan-500/30">验证</div>
+</div>
+
+<!--
+逐字稿：资产库不仅管理给 Agent 的知识，也要管理 Agent 能调用的外部能力。一旦连接外部系统，就必须另外说明 MCP 能做什么、谁能调用、失败时怎样降级、调用后怎样验证。下一模块专门把这层能力、权限和验收契约补齐。
+
+资产库还不能止步于“给 Agent 什么知识”。当 Agent 需要调用外部系统时，还必须定义 MCP 能力可以做什么、由谁调用、失败后怎样停止与怎样验证。下一模块补上这一层。
+-->
@@ -0,0 +1,152 @@
+# 模块 12：MCP 也必须沉淀为能力资产
+
+<div class="mt-6 text-sm">
+
+MCP 不是一条连接地址，也不是把所有外部系统工具都暴露给 Agent。
+
+它是“可被 Agent 调用的外部能力”，因此同样需要清楚的输入输出、权限、审计、失败处理和验证边界。
+
+</div>
+
+<div class="grid grid-cols-5 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">能力说明</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">工具契约</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">权限范围</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">失败降级</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">验收夹具</div>
+</div>
+
+<!--
+逐字稿：MCP 不是一条配置地址，也不是把外部工具全部暴露给 Agent。它把外部系统能力带入任务，因此必须像代码接口一样说明输入、输出、权限、副作用、错误和验证。能连通只说明技术上可访问，不能说明业务上可以安全调用。
+
+当前课程已有 CLI / MCP / Skill 封装决策表，说明 MCP 适合跨系统取数、浏览器等交互式外部能力。但决策表只是入口，不足以保证某个 MCP Server 可安全复用。
+-->
+
+---
+
+# MCP 资产包应包含什么？
+
+<div class="mt-5 text-xs">
+
+```text
+mcp-assets/
+├── README.md                       # 接入边界、适用场景与不适用场景
+├── MCP能力契约.template.md          # 服务、工具、输入、输出、错误与审计
+├── MCP工具权限与验收清单.md          # 最小授权、敏感数据与副作用验证
+├── MCP故障降级清单.md                # 超时、鉴权、限流、不可用时的处理
+└── fixtures/                        # 完整、拒绝、失败与脱敏结果样例
+```
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+连接配置只说明“连得上”；资产包还要说明“什么时候可以调用、调用后能相信到什么程度”。
+</div>
+
+<!--
+逐字稿：一份 MCP 资产包至少要让使用者知道五件事：它适合什么场景，工具契约是什么，权限如何控制，故障如何降级，以及如何用夹具验收。这里不预置任何业务服务器、地址或密钥，因为这些必须由具体项目在合规范围内提供。配置能连上只是起点，调用后的可信范围才是重点。
+
+本课件交付包已补充前三份真实模板文件。没有配置任何业务服务器、Token 或外部地址；这些必须由使用项目在合规范围内另行提供。
+-->
+
+---
+
+# 每个 MCP 工具都需要输入输出契约
+
+<div class="mt-5 text-xs">
+
+| 契约字段 | 必须说明的问题 |
+|---|---|
+| 工具名称与用途 | 它解决哪一类外部事实或操作？ |
+| 输入 | 必填字段、格式、数据范围和敏感参数处理方式是什么？ |
+| 输出 | 返回哪些已确认字段，哪些字段可能为空或过期？ |
+| 副作用 | 只读、可逆写入，还是不可逆操作？ |
+| 错误 | 鉴权、限流、超时、无结果和服务错误如何区分？ |
+| 审计 | 调用主体、目标对象、时间和结果如何留痕并脱敏？ |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+工具名叫“查询”不代表一定只读；是否有副作用必须由契约明确，而不是让 Agent 猜测。
+</div>
+
+<!--
+逐字稿：每个 MCP 工具都必须有独立契约。名称叫“查询”并不代表一定只读，返回字段也不一定都新鲜可靠；因此要明确输入范围、输出可信度、副作用、错误类型和审计信息。Agent 不能根据工具名自行推断权限或风险。
+
+在真实项目中，MCP 工具的名字可能不准确或随版本变化，因此不根据名字推断权限。契约必须单独说明每个工具的读写性质、输入范围、输出可信度和错误语义。
+-->
+
+---
+
+# Agent 调用 MCP 时，权限要再收一层
+
+<div class="mt-5 text-xs">
+
+| 外部能力类型 | Agent 默认策略 | 必须补充的保护 |
+|---|---|---|
+| 读取公开或脱敏信息 | 可按职责开放 | 结果范围、来源时间与引用记录 |
+| 读取受限业务信息 | 仅在明确授权后调用 | 数据范围、脱敏与审计 |
+| 创建草稿或临时资源 | 需要用户确认 | 幂等键、撤销方式和可见结果 |
+| 修改业务状态或数据 | 不作为默认工具权限 | 二次确认、最小范围和回滚路径 |
+| 删除、发布、外发 | 不交给通用 Agent | 专用流程与人工最终确认 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+自定义 Agent 的工具选择只是第一层；MCP 工具自身仍要定义调用级的权限与确认边界。
+</div>
+
+<!--
+逐字稿：Agent 的工具选择只是第一层权限控制，MCP 调用本身还需要第二层边界。公开脱敏信息可以按职责读取，受限信息必须明确授权，创建临时资源需要确认，修改业务状态必须有更严格的最小范围和回滚条件，删除、发布和外发不应交给通用 Agent。角色权限和调用权限必须同时收敛。
+
+这页与模块 9 的最小授权形成两层保护：第一层是 Agent 能否看到这个 MCP 工具，第二层是 MCP 服务是否允许本次调用的身份、数据范围和操作类型。
+-->
+
+---
+
+# MCP 的验收不只检查“调用成功”
+
+<div class="mt-5 text-xs">
+
+| 验收夹具 | 预期行为 |
+|---|---|
+| 合法完整请求 | 返回结构符合契约，来源和时间可追溯 |
+| 缺少必填参数 | 拒绝并说明字段缺口，不自动补造参数 |
+| 越权请求 | 拒绝或要求确认，不泄露超范围数据 |
+| 限流、超时或服务不可用 | 区分故障类型，输出降级结论，不伪装成无结果 |
+| 敏感字段返回 | 按契约脱敏，日志不写入密钥、Token 或完整隐私数据 |
+| 有副作用的重复调用 | 符合幂等或明确阻止重复执行 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
+MCP 失败时，Agent 应该报告“外部事实未取得”，而不是用已有代码或常识补出一个答案。
+</div>
+
+<!--
+逐字稿：MCP 的验收不能只看调用是否返回成功。合法请求要验证返回结构和来源，缺参数要明确拒绝，越权请求不能泄露数据，超时和限流不能伪装成无结果，敏感字段必须脱敏，有副作用的调用还要验证幂等。外部事实没取到时，Agent 应直接说明缺口，而不是用常识补答案。
+
+这里的夹具可用于人工试跑或自动化契约测试。重点是身份、范围、错误和副作用边界，不是仅看 HTTP 或工具调用是否返回成功。
+-->
+
+---
+
+# MCP 能力资产的交付标准
+
+<div class="mt-8 text-lg">
+一份 MCP 资产的完成标准，不是 Agent 调用成功，而是能力、契约、权限、故障处置和验证边界均可被复核。
+</div>
+
+<div class="grid grid-cols-5 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">适用边界</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">工具契约</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">调用权限</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">故障降级</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">验收夹具</div>
+</div>
+
+<!--
+逐字稿：MCP 模块到这里的结论是：一份 MCP 资产不能只交付连接配置或工具名称。它至少应写清适用边界、每个工具的输入输出契约、调用权限、超时和故障时的降级方式，以及可重复执行的验收夹具。
+
+这五项信息让 Agent 对外部能力的使用可控、可审查。没有它们，即使调用成功，也无法判断是否取到了可信事实、是否越权，或是否产生了无法回退的副作用。
+-->
@@ -0,0 +1,210 @@
+# 模块 13：历史代码治理、类型契约与测试补齐
+
+<div class="mt-6 text-sm">
+
+Rule、Skill、Agent 和 MCP 解决的是“如何沉淀判断”。
+
+回到真实项目，历史代码治理还需要回答：哪些结构可以调整、哪些行为必须保持、类型是否真的表达了接口契约，以及测试到底覆盖到哪里。
+
+</div>
+
+<div class="grid grid-cols-6 gap-3 mt-8 text-xs">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">职责结构</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">行为基线</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">命令模型</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">类型契约</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">测试矩阵</div>
+<div class="p-3 rounded-xl bg-cyan-500/10 border border-cyan-500/30">断言边界</div>
+</div>
+
+<!--
+逐字稿：第五天最后一个模块把前面的资产方法落回历史代码治理。前面已经讲过 Rule、任务上下文契约、Skill、Agent 和 MCP 如何承载稳定判断；这里专门处理远程原大纲中尚未展开的重构、类型和测试主题。
+
+仍然使用当前公务用车模块作为证据来源。重点不是让大家现场背一套重构套路，而是建立可审查的判断：哪些结构可动、哪些状态行为不能动、跨端类型怎样核验、测试如何证明副作用。
+-->
+
+---
+
+# 派车重构的候选职责结构
+
+<div class="mt-5 text-xs">
+
+当前 `assign` 保持事务编排入口，候选拆分只调整内部职责，不改变 Controller、接口或写入顺序：
+
+```text
+assign(vo)  @Transactional
+  |- 校验申请：存在、已审批、未重复派车
+  |- 校验车辆：存在、可用、时间不冲突
+  |- 校验司机：按 needDriver 决定必填、可用、时间不冲突
+  |- 创建派车任务：写入申请、车辆、司机、计划时间与状态
+  `- 预占车辆：AVAILABLE -> RESERVED
+```
+
+| 可调整的内部边界 | 不能借拆分改变的行为 |
+|---|---|
+| 私有校验方法、局部命名、组装对象的位置 | 事务边界、拒绝顺序、接口字段、派车与车辆的写入语义 |
+
+</div>
+
+<!--
+逐字稿：这页补上远程大纲中的重构实操目标。我们不在课件中伪造一份已经合入的重构 Diff，而是依据当前 assign 的真实代码给出候选职责结构。它仍保留 assign 作为事务编排入口，按申请、车辆、司机、任务创建和车辆预占分段。
+
+关键不在于拆出几个方法，而在于拆分后外部行为不变：拒绝仍发生在写入前，接口字段不变，派车任务和车辆预占仍在同一事务里。这个结构是 TRAE 可以协助形成并接受审查的最小重构目标，而不是让模型自作主张改 Controller、页面或数据库。
+-->
+
+---
+
+# 用行为基线验收无损重构
+
+<div class="mt-5 text-xs">
+
+`assign` 的当前源码可先整理为行为基线；重构后的代码和测试都应逐项回到这张表。
+
+| 输入条件 | 预期结果 | 允许的写入 |
+|---|---|---|
+| 申请不存在、未完成或已派车 | 拒绝派车 | 无派车任务、无车辆状态变更 |
+| 车辆不存在、不可用或时间冲突 | 拒绝派车 | 无派车任务、无车辆状态变更 |
+| 需要司机但未提供，或司机不可用/冲突 | 拒绝派车 | 无派车任务、无车辆状态变更 |
+| 所有前置条件满足 | 创建 `DISPATCHED` 派车任务 | 车辆由 `AVAILABLE` 变为 `RESERVED` |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+“无损”不是代码未报错，而是每个拒绝路径和成功副作用仍与基线一致。
+</div>
+
+<!--
+逐字稿：重构验收不能只看编译通过或页面能打开。assign 的原始代码已经给出四类行为：申请不符合条件时拒绝，车辆不符合条件时拒绝，司机条件不满足时拒绝，所有条件满足才创建已派车任务并预占车辆。
+
+这张行为基线把远程大纲中的“行为一致性”和“测试缺口”连接起来。重构后的每一个测试都要能回到其中一行，特别是三类拒绝路径都不能产生派车任务或车辆状态变更。这样才能判断结构整理是否真正无损。
+-->
+
+---
+
+# 类型治理要分开命令、实体与展示模型
+
+<div class="mt-5 text-xs">
+
+派车模块已有一组可对照的模型边界：
+
+| 模型 | 当前字段范围 | 应承担的职责 |
+|---|---|---|
+| `OfficialVehicleDispatchVo` | `applyId`、`carId`、可选 `driverId`、`remark` | 派车命令的唯一输入 |
+| `OfficialVehicleDispatch` | ID、调度人、时间、状态、取消原因等 | 服务端持久化与列表展示结果 |
+| 前端 `OfficialVehicleDispatchVo` | 与派车命令相同的四类字段 | 提交时只发送用户可提供的内容 |
+| 前端 `OfficialVehicleDispatch` | 读取列表中的状态、时间和调度人等 | 展示与操作条件判断 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
+命令类型不是实体类型的 `Partial`：状态、时间和操作人不应由派车表单决定。
+</div>
+
+<!--
+逐字稿：类型治理还要区分同一业务对象在不同方向上的模型。当前后端的 OfficialVehicleDispatchVo 只有派车时需要提交的四类字段；实体则多了系统生成的调度人、时间、状态和取消原因。前端也分别定义了命令模型和展示模型，提交时显式组装四个字段。
+
+这个对照说明了类型抽取的正确目标：不要让页面用 Partial 实体随意提交状态、时间或操作人。命令模型描述“用户能请求什么”，实体或展示模型描述“系统已经产生什么”。这比单纯增加 interface 更能防止重构后字段权限漂移。
+-->
+
+---
+
+# 类型差异必须形成可执行的核验用例
+
+<div class="mt-5 text-xs">
+
+审批结果和申请状态的定义差异，不能只记录在问题单中，应转换为可验证的契约。
+
+| 核验对象 | 输入或观察值 | 需要确认的结论 |
+|---|---|---|
+| 审批命令 | `pass`、`reject`、`PASS`、`REJECT` | 哪些值能被接口接受；拒绝时返回什么语义 |
+| 审批表单 | 单选组件实际提交的 `result` | 页面提交值是否与接口契约一致 |
+| 申请状态 | `1`、`"1"` 及接口返回值 | 前端渲染和状态判断使用的唯一表示 |
+| 类型定义 | 联合类型、表单选项、后端常量 | 三处是否指向同一组允许值 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+类型契约完成的标准是“能执行的接受与拒绝用例”，不是文档里多了一行枚举。
+</div>
+
+<!--
+逐字稿：上一页发现了审批结果和状态值的跨端定义差异，这一页进一步说明怎样处理。正确的产出不是写一句“统一大小写”，而是形成可执行的核验用例：四种审批值分别怎样处理，页面实际发出的是什么，状态在接口和页面中的唯一表示是什么，类型定义、表单选项和后端常量是否一致。
+
+这样一份类型契约可以交给 TRAE 生成检查项或测试草案，也可以作为 Review 的依据。最终仍要以 API 或集成测试确认真实请求的接受和拒绝语义，不能仅根据类型声明下结论。
+-->
+
+---
+
+# 取消派车的测试用例应覆盖状态与副作用
+
+<div class="mt-5 text-xs">
+
+| 场景 | 期望行为 | 当前证据状态 |
+|---|---|---|
+| `cancelReason` 全空白 | 立即拒绝，不访问后续依赖 | 已有 Service 单测 |
+| 派车任务不存在 | 拒绝，不更新派车或车辆 | 待补 |
+| 派车状态不是 `DISPATCHED` | 拒绝，不释放车辆 | 待补 |
+| 任务可取消且车辆存在 | 记录取消原因，派车变 `CANCELLED`，车辆变 `AVAILABLE` | 待补 |
+| 任务可取消但车辆记录缺失 | 派车仍完成取消，避免空指针 | 待补，当前源码有空值保护 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-purple-500/10 border border-purple-500/30 text-sm">
+测试用例的粒度应跟随状态与副作用，不以“覆盖了 cancel 方法”作为完成标准。
+</div>
+
+<!--
+逐字稿：远程大纲中的测试用例生成，应针对当前 cancel 方法的真实分支。现有服务单测只覆盖了空白原因。接下来至少还要覆盖派车任务不存在、状态不允许、正常取消且车辆存在、以及车辆记录缺失这五种场景。
+
+最后一种很容易漏掉，但源码明确用 if 判断保护了车辆为空的情况。因此它既是行为分支，也是有价值的回归点。每个用例要同时写清拒绝或成功结果，以及派车和车辆是否应发生写入，避免只断言异常消息或方法被调用。
+-->
+
+---
+
+# 断言要与被测层级匹配
+
+<div class="mt-5 text-xs">
+
+| 被测层级 | 当前可见证据 | 应断言什么 | 不能替代什么 |
+|---|---|---|---|
+| Controller | Mockito 验证 `cancel` 的委派与结果消息 | 接口是否交给正确的 Service 参数 | Service 内部状态和持久化行为 |
+| Service 拒绝路径 | 空白原因抛出异常 | 不满足条件时无后续写入或资源释放 | 正常取消的双对象更新 |
+| Service 成功路径 | 当前尚无定向单测 | 派车状态、取消原因、车辆状态及更新次数 | 前端实际请求载荷 |
+| API / 集成层 | 当前尚无契约验证记录 | 前后端值、权限、序列化与错误响应 | 未执行环境的全链路结论 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+Controller Mock 测试通过，不等于业务状态机已经被测试。
+</div>
+
+<!--
+逐字稿：最后一页补的是测试质量判断。当前 Controller 测试使用 Mockito 验证委派关系和结果消息，这正是 Controller 层应保护的内容；它不能替代 Service 层的状态和持久化验证。现有 Service 空白原因测试证明了一个拒绝路径，但还没有覆盖正常取消的双对象更新。
+
+因此，TRAE 生成测试时要先说明被测层级和断言对象：Controller 看参数转交，Service 看规则和副作用，API 或集成层看真实请求、序列化、权限与错误响应。把这三类测试混在一起，最常见的结果就是 Mock 测试通过，却误以为业务状态机已经安全。
+-->
+
+---
+
+# 从案例到可执行资产
+
+<div class="mt-8 text-lg">
+案例提供事实；资产保存判断；重构守住行为；类型表达契约；测试证明副作用；MCP 将外部能力纳入同一套边界。
+</div>
+
+<div class="grid grid-cols-8 gap-2 mt-8 text-xs">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">事实</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">Rule</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">任务契约</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">Skill</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">Agent</div>
+<div class="p-3 rounded-xl bg-cyan-500/10 border border-cyan-500/30">MCP</div>
+<div class="p-3 rounded-xl bg-orange-500/10 border border-orange-500/30">类型</div>
+<div class="p-3 rounded-xl bg-slate-500/10 border border-slate-500/30">测试</div>
+</div>
+
+<!--
+逐字稿：第五天从真实案例开始，最终交付不止是一组提示词或一处功能改动。案例和源码提供事实，Rule、任务上下文契约、检查单和 Skill 保存判断，Agent 固化职责，MCP 管理外部能力；历史代码重构用行为基线限制改动，类型契约消除跨端歧义，测试证明状态和副作用。
+
+因此，AI 工程资产不是单独存放的 Markdown 文件，而是一组能支持真实工程判断、修改和验证的契约。第六天将把这些资产放入 PR、Git、CI 和变更证据链中，处理工程协作与质量闭环。
+-->
@@ -0,0 +1,125 @@
+# 模块 2：从案例判断资产边界
+
+<div class="mt-6 text-sm">
+
+资产化最难的不是给文件命名，而是把可长期复用的判断，与一次任务中的项目事实分开。
+
+稳定约束可以沉淀；字段名、路径、权限码和未验证结论必须留在运行时输入中。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">稳定约束</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">运行时事实</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">已知反例</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">证据缺口</div>
+</div>
+
+<!--
+逐字稿：资产化的第一步不是建立文件夹，而是先划边界。稳定的判断可以沉淀，当前项目的字段、路径、权限码和没有验证的结论不能沉淀。把两类信息混在一起，资产一旦换项目就会带着旧事实继续工作。
+
+资产的第一道边界，是不把项目事实伪装成通用规则。字段名、路径、权限码、异常文案等信息会随着项目或任务变化，必须作为运行时事实重新核对。
+-->
+
+---
+
+# 资产选型先看变化与风险
+
+<div class="mt-5 text-xs">
+
+| 判断维度 | 信号 | 更合适的承载方式 |
+|---|---|---|
+| 约束变化频率 | 长期稳定，违反代价高 | Rule：明确必须项、禁止项与验收 |
+| 任务输入变化 | 问法稳定，但每次事实材料不同 | 任务上下文契约：固定约束，替换运行时输入 |
+| 漏检风险 | 风险项有限且常被忽略 | Checklist：让关键检查可以逐项确认 |
+| 决策复杂度 | 需要多步读取、判断、交接和验证 | Skill：编排资产与停止条件 |
+| 误解成本 | 正确做法容易被错误套用 | Example：保留正例、反例和适用边界 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+同一条经验不一定只对应一种资产；选择依据是变化速度、误用风险和决策复杂度。
+</div>
+
+<!--
+逐字稿：选择资产不能只看名称，而要看变化和风险。高风险且长期稳定的约束适合 Rule，任务事实每次不同但判断框架稳定时适合任务上下文契约，多个检查点容易遗漏时适合检查单。需要连续读取、判断、交接和验证时，才值得封装为 Skill。
+
+这张表不再平铺定义资产类型，而是用变化与风险做选型。稳定而高风险的约束适合 Rule；不断变化的任务事实不应写死在资产中。
+-->
+
+---
+
+# 公务用车案例能沉淀什么？
+
+<div class="mt-5 text-xs">
+
+| 案例中的发现 | 不应直接沉淀为 | 更合适的资产 |
+|---|---|---|
+| 前端必填不能代替后端业务保护 | “取消原因不能为空”的全局 Rule | 状态变更必要信息后端保护 Rule |
+| 分析时要同时看页面、API、权限和 Service | 一段固定答案 | 影响分析任务上下文的输入清单 |
+| 状态写入前要检查必需字段 | 一次性代码片段 | 状态变更检查单与反例 |
+| 需要读源码、判断边界、列验证项 | 超长 Prompt | 多步状态变更审查 Skill |
+| 数据库 NOT NULL 在此场景不合适 | “永远不要改数据库” | 条件化反例与取舍说明 |
+
+</div>
+
+<!--
+逐字稿：同一个案例里会同时产生多种资产，但它们保存的是不同层次的信息。前端必填不能代替后端保护，可以沉淀成状态变更规则；页面、接口、权限和 Service 都要阅读，可以沉淀成任务上下文要求。字段名和异常文案仍然属于当前项目事实，不能直接推广。
+
+案例事实不能原样搬到所有项目。可沉淀的是可重复的判断方法，例如“状态写入前检查必需信息”；字段名、异常文案、权限码和表结构仍需在新项目中重新取证。
+-->
+
+---
+
+# 资产候选必须有证据来源
+
+<div class="mt-5 text-xs">
+
+| 证据来源 | 可以升级的资产 | 还需要补什么 |
+|---|---|---|
+| 明确的项目规范、配置或接口契约 | Rule | 适用范围和验收方式 |
+| 多次出现的同类提问与交付结构 | Prompt / Template | 必填输入与输出 Schema |
+| 已发生的漏检、误用或缺陷 | Checklist / Example | 反例、触发条件和修复依据 |
+| 可重复的多步分析与验证路径 | Skill | 各步骤输入、交接和停止条件 |
+| 未经核对的模型建议或单次对话 | 暂不沉淀 | 先补项目事实或验证记录 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+资产不是知识收藏；没有来源证据的内容只能是候选建议。
+</div>
+
+<!--
+逐字稿：资产不是凭感觉升级的。项目规范和接口契约可以支撑 Rule，反复出现的任务结构可以支撑任务上下文契约，真实漏检和误用才能支撑检查单与反例。只有单次对话或模型建议时，最正确的动作是先保留为候选，不要急着写进团队资产。
+
+这一页讲资产升级门槛。真正可用的资产应能回答：为什么形成、适用于哪里、遇到什么输入会失效。
+-->
+
+---
+
+# 不值得沉淀的内容
+
+<div class="grid grid-cols-2 gap-4 mt-8 text-sm">
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">单次对话结论</div>
+<div class="mt-2 text-xs op-70">没有输入、证据和适用范围，下一次无法复核。</div>
+</div>
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">项目特有字段或权限码</div>
+<div class="mt-2 text-xs op-70">换项目后很可能失效，必须留在运行时输入中。</div>
+</div>
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">没有验证过的模型建议</div>
+<div class="mt-2 text-xs op-70">只能作为候选方案，不能升级为规则。</div>
+</div>
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">一次性检查列表</div>
+<div class="mt-2 text-xs op-70">重复价值不足时，保留在任务记录即可。</div>
+</div>
+</div>
+
+<!--
+逐字稿：不沉淀同样是一项工程能力。一次性的聊天结论、项目私有字段、没有验证的模型建议和没有重复价值的清单，都不应该进入共享资产库。资产库保存的是下一次任务仍然可以复核的判断，而不是所有曾经出现过的内容。
+
+资产化的关键能力也包括“不沉淀”。没有重复价值、缺少证据、脱离项目仍无意义的内容，继续保留在当前任务记录即可。
+-->
@@ -0,0 +1,112 @@
+# 模块 3：Rule 的设计契约
+
+<div class="mt-6 text-sm">
+
+Rule 不是“代码要规范”这类口号。
+
+一条可执行 Rule 必须说明：它基于什么证据、在哪些场景生效、必须做什么、不能做什么，以及如何验收。
+
+</div>
+
+<div class="grid grid-cols-3 gap-4 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">来源可信</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">边界明确</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">结果可验</div>
+</div>
+
+<!--
+逐字稿：Rule 的价值不在于写得严厉，而在于能够被执行和验收。它必须说清来源、适用范围、必须动作、禁止动作和验证方法。否则“代码要规范”这种表述只能表达态度，不能约束 Agent 或开发行为。
+
+这里讲的是高级 Rule 编写：从项目事实提取约束，而不是用个人偏好覆盖项目结构。现有 generate-project-constraints Skill 使用了同样的证据分级方法。
+-->
+
+---
+
+# 先给 Rule 标注证据等级
+
+<div class="mt-5 text-xs">
+
+| 等级 | 什么时候使用 | 典型写法 |
+|---|---|---|
+| 硬约束 | 配置、构建、CI 或显式规范直接证明 | 必须 / 禁止 |
+| 观察性约束 | 多处源码反复出现，但没有书面规范 | 默认采用 / 优先复用 |
+| 待确认约束 | 对交付很重要，但当前项目无法证明 | 需确认 / 不下结论 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+不要把“一个代码样例”或“通用最佳实践”直接升级成项目硬规则。
+</div>
+
+<!--
+逐字稿：Rule 首先要标注证据等级。配置、构建和明确规范能够支持“必须”或“禁止”；多处实现形成的惯例只能写成“优先”或“默认”；当前无法证明但又重要的内容必须保留为待确认。这样可以避免把一段样例代码误写成项目硬规则。
+
+证据等级来自现有的项目约束生成 Skill。它能防止一个常见错误：看到一次实现就写成“本项目必须如此”，或者把普适经验伪装为项目事实。
+-->
+
+---
+
+# 一条 Rule 的六个字段
+
+<div class="mt-5 text-xs">
+
+```md
+## 状态变更必要信息保护
+
+- 级别：观察性约束
+- 适用场景：Service 方法会写入业务状态或释放、占用资源。
+- 必须：在任何写入前校验本次状态变更必需的信息。
+- 禁止：仅依赖前端必填；将条件必填扩大为全表非空。
+- 来源证据：状态更新、资源更新与现有调用链。
+- 验收方式：无效输入被拒绝；正常路径及副作用单独验证。
+```
+
+</div>
+
+<!--
+逐字稿：这六个字段把 Rule 变成了可运行的约束。注意这里没有把 cancelReason、接口路径或权限码写进去，因为那些会随项目变化。真正可迁移的是：涉及状态写入和资源变更时，要在写入前校验必要信息，并分别验证无效输入和正常副作用。
+
+这六个字段使 Rule 能被 Agent 和人共同使用。Rule 中没有写取消原因字段名、接口路径或权限码，因为它们属于项目输入，而不是可迁移的约束本身。
+-->
+
+---
+
+# 常见的 Rule 失效方式
+
+<div class="mt-5 text-xs">
+
+| 写法 | 为什么失效 | 改写方向 |
+|---|---|---|
+| “后端要做好校验” | 没有触发点、位置和验收 | 指出状态写入前的必要信息保护 |
+| “所有字段都不能空” | 把条件规则扩大为数据模型规则 | 写清具体状态与字段条件 |
+| “统一使用 Service” | 把架构偏好误当业务约束 | 说明为什么该规则需要覆盖复用入口 |
+| “严格测试” | 无法判断是否满足 | 写出无效输入、正常路径和副作用验证 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+好的 Rule 约束行为，不替人猜业务，也不替项目做架构重写。
+</div>
+
+<!--
+逐字稿：Rule 失效常常不是因为方向错，而是因为范围过大或没有验收条件。比如“所有字段都不能空”把条件校验扩大成数据模型规则，“严格测试”又没有说清要测什么。好的 Rule 只约束真正需要保护的行为，不替项目做无依据的架构重写。
+
+可以让学员对照这张表检查自己的 Rule。Rule 的力量来自足够具体，但又不携带一个项目的字段名和临时结论。
+-->
+
+---
+
+# Rule 的验收不是“读起来像规范”
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">能触发<br><span class="text-xs op-70">知道什么时候应用</span></div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">能约束<br><span class="text-xs op-70">必须与禁止清楚</span></div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">能取证<br><span class="text-xs op-70">来源不是主观偏好</span></div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">能验证<br><span class="text-xs op-70">可用代码、测试或检查确认</span></div>
+</div>
+
+<!--
+逐字稿：一条 Rule 是否进入长期资产，至少看四件事：能否触发、能否约束、能否追溯来源、能否验证结果。任何一项缺失，都意味着它只能作为建议，不能作为默认工作方式。这个门槛能避免资产库逐渐变成个人偏好的集合。
+
+这一页可作为 Rule 的质量门禁。只要其中一项回答不上来，Rule 就不应进入长期资产。
+-->
@@ -0,0 +1,126 @@
+# 模块 4：任务上下文契约
+
+<div class="mt-6 text-sm">
+
+任务上下文契约不是一句“帮我分析”。它规定任务需要哪些事实、遵守哪些约束、缺少什么时停止，以及结果如何交给下一步使用。
+
+Prompt 只是这份契约的常见承载形式之一。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">固定约束</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">运行时事实</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">输出结构</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">停止边界</div>
+</div>
+
+<!--
+逐字稿：任务上下文契约规定的不是一句提问，而是任务如何被可靠地执行。它把不变的约束、每次都要补充的事实、固定的输出结构和停止条件放在一起。Prompt 可以承载这份契约，但真正有价值的是上下文工程本身。
+
+任务上下文契约将上下文工程固化为可维护资产：固定约束不随任务漂移，项目事实每次重新提供，输出可以被后续步骤稳定消费。
+-->
+
+---
+
+# 固定约束与运行时事实要分开
+
+<div class="mt-5 text-xs">
+
+| 固定上下文 | 每次任务重新提供的事实 |
+|---|---|
+| 先取证、再判断、最后给方案的要求 | 本次变更目标 |
+| 证据不足时标记待确认 | 已读文件、diff、日志和测试结果 |
+| 输出必须区分事实、建议和未知项 | 当前接口、字段、状态和权限信息 |
+| 不得编造运行结果或业务结论 | 本次允许与禁止修改的范围 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+可复用的是判断框架；项目事实必须作为运行时上下文重新提供。
+</div>
+
+<!--
+逐字稿：这里最关键的分界是固定约束和运行时事实。先取证、证据不足要标记、输出必须区分事实和建议，这些可以固定；本次需求、源码、diff、日志和权限信息必须每次重新提供。把事实写死会误用旧项目，没有事实又会让模型猜测。
+
+将固定约束与运行时事实拆开，任务上下文契约才能跨任务复用。把某个项目的 Service 名称或权限码写死，会使资产失去迁移能力；反过来，完全没有项目输入则会让模型猜测。
+-->
+
+---
+
+# 影响分析的输出契约
+
+<div class="mt-5 text-xs">
+
+```md
+任务：基于提供的源码与记录分析本次变更，不要修改代码。
+
+必备上下文：变更目标、已读源码、状态或权限规则、diff 或测试记录。
+
+输出必须包含：
+1. 已确认事实：每项关联来源路径或输入证据。
+2. 影响链路：入口、业务边界、状态/数据副作用。
+3. 候选方案：范围、优缺点、验证方式。
+4. 最小改动建议：允许修改与明确不改内容。
+5. 待确认项：证据缺口以及不能推出的结论。
+
+约束：没有证据时写“待确认”；不得补充测试、接口或业务结果。
+```
+
+</div>
+
+<!--
+逐字稿：输出契约的作用是让结果可以继续被消费。影响分析不能只给一段建议，而要交付已确认事实、影响链路、候选方案、最小改动建议和待确认项。这样后续的 Skill、检查单、PR 说明才能直接引用同一份结构，而不需要再从自然语言里二次提取。
+
+输出 Schema 是任务上下文契约可被复用的关键。后续 Skill、检查单和 PR 说明都可以消费同一份结构化结果，而不是重新从一段自然语言总结中提取信息。
+-->
+
+---
+
+# 任务上下文契约也需要测试用例
+
+<div class="mt-5 text-xs">
+
+| 输入情况 | 期望行为 | 不能接受的行为 |
+|---|---|---|
+| 入口、Service 与测试齐全 | 输出可追溯的影响分析 | 只给泛化最佳实践 |
+| 只有页面截图或单个文件 | 明确缺少 API、状态或验证证据 | 自行补全调用链 |
+| 要求跨层重构但无依据 | 标记范围风险并给出最小方案 | 默认修改数据库、权限和页面 |
+| 测试结果缺失 | 输出待执行验证项 | 写成“测试已通过” |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+一份任务上下文契约在不同事实输入下都能保持边界，才具备复用价值。
+</div>
+
+<!--
+逐字稿：任务上下文契约也要像代码一样接受代表性输入测试。材料齐全时应输出完整分析，材料缺失时应明确缺口，范围过大时应提示风险，测试未执行时只能输出待执行项。验收的重点不是文案是否漂亮，而是模型会不会在证据不足时越界下结论。
+
+任务上下文契约的测试不依赖自动化框架，也可以用四类代表性输入进行人工验收。真正要观察的是：模型面对证据缺口时是否会停下并提出需要什么，而不是生成貌似完整的答案。
+-->
+
+---
+
+# 上下文契约失控的三个信号
+
+<div class="grid grid-cols-3 gap-4 mt-8 text-sm">
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">输入缺失仍结论完整</div>
+<div class="mt-2 text-xs op-70">说明模型在补猜，缺少待确认出口。</div>
+</div>
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">输出无法进入下一步</div>
+<div class="mt-2 text-xs op-70">说明没有固定输出结构或验收字段。</div>
+</div>
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">
+<div class="font-bold">每次都要重写长背景</div>
+<div class="mt-2 text-xs op-70">说明固定约束和变量输入没有拆开。</div>
+</div>
+</div>
+
+<!--
+逐字稿：这三个信号可以快速判断任务上下文是否失控。输入不全却结论完整，说明模型在补猜；输出无法交给下一步，说明没有结构；每次都重写背景，说明固定约束和运行时事实没有分开。发现这些信号后，应该修契约，而不是继续把提示词写得更长。
+
+这三个信号帮助识别“看起来很长但不能复用”的任务上下文。修复方向分别是补待确认规则、补输出 Schema、拆分固定约束与运行时事实。
+-->
@@ -0,0 +1,137 @@
+# 模块 5：Skill 的难点是决策边界
+
+<div class="mt-6 text-sm">
+
+Skill 的价值不在于堆叠说明，而在于把任务拆成可核对的输入条件、决策顺序、交接结果和停止边界。
+
+只有这些边界被显式定义，复杂任务才能在不同项目事实下保持可控。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">输入条件</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">决策顺序</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">交接结果</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">停止边界</div>
+</div>
+
+<!--
+逐字稿：Skill 的难点不是把步骤写得很长，而是把一次复杂任务的决策边界拆清楚。它要明确输入是否齐全、判断按什么顺序进行、结果交给谁，以及在哪些情况下必须停止。只有这四件事稳定，Skill 才能跨任务复用而不失控。
+
+这一模块使用交付包中真实的 Skill 目录结构，重点是解释每类文件如何承接判断、输入、输出和验证，而不是记住固定目录。
+-->
+
+---
+
+# 一个真实 Skill 包如何按职责拆开
+
+<div class="mt-5 text-xs">
+
+```text
+skill-name/
+├── SKILL.md                 # 触发条件、输入、工作流、输出与门禁
+├── agents/
+│   └── openai.yaml          # 展示名、简介与默认触发提示
+├── assets/
+│   ├── 生成.prompt.md       # 可复用任务 Prompt
+│   ├── 检查清单.md           # 固定遗漏点
+│   └── 报告.template.md      # 结构化输出模板
+├── references/              # 稳定背景知识与兼容性说明
+└── scripts/                 # 可重复执行的机械检查
+```
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+`SKILL.md` 负责决策和编排；模板、检查单、参考资料和脚本各自承担单一职责，避免同一约束出现多个版本。
+</div>
+
+<!--
+逐字稿：这个目录不是必须照抄的模板，而是一种职责拆分方式。`SKILL.md` 保存判断和编排，检查单保存固定遗漏点，模板保存输出结构，参考资料保存稳定背景，脚本保存机械检查。把它们全部堆进一个文件，后续更新时就很难判断哪一份是权威来源。
+
+这个目录来自当前工程 Skill 交付包，例如 project-knowledge-builder、generate-project-constraints 与 track-review-fix-loop。并非所有 Skill 都需要全部子目录，但不应把每类内容都堆进 SKILL.md。
+-->
+
+---
+
+# SKILL.md 的核心结构
+
+<div class="mt-5 text-xs">
+
+```md
+---
+name: state-change-safety
+description: 当任务涉及业务状态写入、资源占用或释放时使用。
+---
+
+## Inputs
+变更目标、相关源码、状态规则、测试或 diff、项目约束。
+
+## Workflow
+提取事实 -> 判断状态与副作用 -> 比较候选方案 -> 生成验证清单。
+
+## Output Contract
+事实表、影响链路、最小改动建议、验证项、待确认事项。
+
+## Stop Conditions
+证据不足、规则冲突、范围越界或关键验证失败时停止并说明原因。
+```
+
+</div>
+
+<!--
+逐字稿：`SKILL.md` 的核心不是说明文字，而是四个契约。Inputs 说明需要什么证据，Workflow 说明判断顺序，Output Contract 说明交付格式，Stop Conditions 说明什么情况下不能继续。缺少停止条件的 Skill 很容易在证据不足时继续生成看似完整的答案。
+
+Frontmatter 决定 Agent 能否发现和触发 Skill；正文决定它读什么、怎么判断和交付什么。真正的 Skill 必须有 Stop Conditions，否则模型遇到证据缺口时容易继续编造。
+-->
+
+---
+
+# agent 配置只解决“如何被发现”
+
+<div class="mt-5 text-xs">
+
+```yaml
+interface:
+  display_name: "状态变更安全审查"
+  short_description: "分析状态写入、资源副作用与验证边界"
+  default_prompt: "Use $state-change-safety to review this change."
+
+policy:
+  allow_implicit_invocation: true
+```
+
+</div>
+
+<div class="mt-6 grid grid-cols-2 gap-3 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">配置文件：让 Agent 找得到</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">SKILL.md：让 Agent 做得对</div>
+</div>
+
+<!--
+逐字稿：这里要区分发现层和执行层。agent 配置只帮助系统识别 Skill 的名称、简介和触发入口，不负责承载业务流程。真正的判断、输入要求和停止边界仍然在 `SKILL.md` 中，这样展示配置变化时不会误伤业务工作流。
+
+agents/openai.yaml 的真实格式包含 display_name、short_description、default_prompt 与 allow_implicit_invocation。它是发现层，不应复制业务工作流；工作流仍放在 SKILL.md 中。
+-->
+
+---
+
+# 什么不该做成 Skill？
+
+<div class="mt-5 text-xs">
+
+| 情况 | 更合适的资产 | 原因 |
+|---|---|---|
+| 只有一条永远成立的约束 | Rule | 没有多步决策必要 |
+| 只需固定格式生成一段内容 | Prompt 或 Command | 不需要上下文编排 |
+| 只检查五个固定项目 | Checklist | 不需要 Agent 主动分析 |
+| 只有一个项目的临时异常 | 任务记录或 Example | 复用价值不足 |
+| 需要读取、判断、生成、验证并输出结构化结果 | Skill | 需要多个资产协同 |
+
+</div>
+
+<!--
+逐字稿：不要因为任务复杂就一律创建 Skill。只有一条长期约束时用 Rule，固定格式输出时用任务上下文契约或 Command，少量固定检查时用 Checklist。只有任务同时需要读取证据、做多步判断、组织验证并输出结构化结果时，Skill 才能真正降低重复成本。
+
+Skill 过度膨胀会造成触发不准、维护困难和上下文浪费。只有当任务确实存在多步判断和明确交付契约时，才值得封装为 Skill。
+-->
@@ -0,0 +1,131 @@
+# 模块 6：Skill 如何组合 Rule、Prompt 与检查单
+
+<div class="mt-6 text-sm">
+
+Skill 的难点不是写步骤，而是把每一步需要的判断、材料和停止条件拆开。
+
+一次状态变更审查，至少要完成“事实、方案、验证、边界”四类判断。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">事实</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">方案</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">验证</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">边界</div>
+</div>
+
+<!--
+逐字稿：这一部分讨论的是 Skill 如何编排已有资产。Rule、任务上下文契约、检查单和模板都不是彼此替代的关系，它们分别解决约束、事实输入、遗漏控制和交付结构。Skill 的作用是在正确的时间加载正确资产，并在证据不足时停止。
+
+这一模块不再平铺介绍 Rule、Prompt、Skill，而是讲 Skill 的编排：什么时候加载哪个资产，何时需要停下来，最终怎样让输出可被下一步消费。
+-->
+
+---
+
+# 状态变更 Skill 的四个决策阶段
+
+<div class="mt-6 text-sm">
+
+```text
+1. 事实提取
+   读取入口、状态、写入顺序、权限、审计和已有验证。
+
+2. 方案比较
+   用 Rule 判断最终保护边界；排除范围越界方案。
+
+3. 验证设计
+   用检查单覆盖无效输入、正常路径和关键副作用。
+
+4. 结论输出
+   区分已确认、待执行和待确认；证据不足时停止。
+```
+
+</div>
+
+<!--
+逐字稿：状态变更审查至少要经历四个阶段。先提取事实，避免从一句需求直接推结论；再比较方案，明确保护位置和禁止范围；随后设计验证，覆盖无效输入、正常路径和副作用；最后按证据强度输出结论。这个顺序不能被压缩成一句“请安全修改状态”。
+
+这是一个 Skill 中真正需要编排的决策过程。每一阶段都有不同输入和不同输出，不能压缩成一句“请帮我安全修改状态流转”。
+-->
+
+---
+
+# 每一步应加载什么资产？
+
+<div class="mt-5 text-xs">
+
+| 阶段 | 使用的资产 | 作用 |
+|---|---|---|
+| 事实提取 | 影响分析 Prompt、项目约束 | 防止遗漏入口和把猜测写成事实 |
+| 方案比较 | 状态变更 Rule、反例 | 判断保护位置与禁止范围 |
+| 验证设计 | 状态流转检查单、测试模板 | 覆盖正常、异常与副作用 |
+| 结论输出 | 报告模板、输出契约 | 使后续 Review 或 PR 能继续使用 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+Skill 的每一步都应能指出“为什么读这个资产、产出交给谁”。
+</div>
+
+<!--
+逐字稿：每一步都要能回答两个问题：为什么现在要读这份资产，产出要交给谁。事实提取依赖项目事实和任务上下文契约，方案比较依赖 Rule 和反例，验证设计依赖检查单，最终由报告模板形成可复核结果。这样 Skill 才不是把所有材料拼在一起，而是有明确的决策流。
+
+这张表借鉴现有 review-fix-loop Skill：它将 Review 报告、修复记录、检查清单和资产决策表分开，而不是把所有内容复制到一段 Prompt 中。
+-->
+
+---
+
+# Output Contract 决定 Skill 是否可用
+
+<div class="mt-5 text-xs">
+
+```md
+## 已确认事实
+<来源路径 / 记录 / 证据>
+
+## 方案比较
+<候选方案、覆盖范围、取舍理由>
+
+## 验证清单
+<已覆盖、待执行、阻断条件>
+
+## 待确认事项
+<证据缺口与不能下结论的原因>
+
+## 资产建议
+<Rule / Prompt / Checklist / Example / 不沉淀>
+```
+
+</div>
+
+<!--
+逐字稿：Output Contract 是 Skill 和下游环节之间的接口。下游不应该接收到一段自由总结，而应该拿到事实、方案比较、验证清单、待确认事项和资产建议。固定结构让 Review、PR 或后续资产沉淀可以直接使用结果，也便于检查模型有没有把推断写成事实。
+
+Output Contract 是 Skill 与下游资产之间的接口。固定结构让下一次 Review、PR 或知识沉淀可以直接使用结果，避免再次让模型总结一段自由文本。
+-->
+
+---
+
+# Stop Conditions 比步骤更重要
+
+<div class="mt-5 text-xs">
+
+| 停止信号 | Skill 应做什么 | 不应做什么 |
+|---|---|---|
+| 缺少入口或状态源码 | 列出缺失材料并停止结论 | 自行补全调用链 |
+| 业务规则互相矛盾 | 标记待确认并列出冲突来源 | 擅自选一个规则执行 |
+| 方案超出允许范围 | 明确指出越界位置 | 顺手改数据库、权限或页面 |
+| 关键验证没有证据 | 输出待执行项 | 写成“已验证” |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+能在证据不足时停下来的 Skill，比能不断生成内容的 Skill 更可靠。
+</div>
+
+<!--
+逐字稿：停止条件比流程步骤更重要。缺入口源码时不能补全调用链，规则冲突时不能擅自选择一方，方案越界时不能顺手扩大修改，验证没有证据时不能写成通过。一个愿意明确停下并暴露缺口的 Skill，比不断生成内容的 Skill 更可信。
+
+Stop Conditions 是防幻觉和防越界的核心。它把“没法继续”的场景变成结构化输出，而不是让 Agent 在信息不足时给出虚假的确定性。
+-->
@@ -0,0 +1,115 @@
+# 模块 7：资产也要验证与演进
+
+<div class="mt-6 text-sm">
+
+代码需要测试，Rule、Prompt 和 Skill 同样需要验证。
+
+一份资产能否长期使用，不取决于措辞是否漂亮，而取决于面对完整信息、缺失信息和越界请求时能否保持正确边界。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">完整输入</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">缺失证据</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">范围冲突</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">跨项目复用</div>
+</div>
+
+<!--
+逐字稿：资产也要接受边界验证。代码测试验证的是实现行为，资产测试验证的是模型面对不同输入时会不会保持正确判断。我们不要求每次输出逐字一致，而是要求完整信息时能交付、缺少证据时会停止、越界请求时会拒绝。
+
+资产验证是第五天的收束。它不是额外流程，而是对前面写出的 Rule、Prompt 和 Skill 做代表性输入测试，确保资产不会诱导 Agent 过度自信或跨项目误用。
+-->
+
+---
+
+# 用四类输入测试资产边界
+
+<div class="mt-5 text-xs">
+
+| 测试输入 | 期望结果 | 失败信号 |
+|---|---|---|
+| 入口、状态与测试材料齐全 | 输出事实、方案和验证项都可追溯 | 只给泛化建议，无法指向输入 |
+| 缺少 Controller 或状态规则 | 明确列出缺失证据 | 擅自补全权限或调用链 |
+| 请求修改数据库、权限和页面 | 标出范围冲突与风险 | 把扩展改动当作默认方案 |
+| 换到另一个项目 | 重新扫描项目事实和约束 | 直接复制字段名、路径和异常文案 |
+
+</div>
+
+<!--
+逐字稿：这四类输入基本覆盖了工程资产最常见的失效方式。材料齐全时要能回指证据，材料缺失时要指出缺口，范围冲突时要说明风险，换项目时要重新读取事实。验证的是边界和结论等级，不是模型每次是否输出同样的句子。
+
+这四类输入对应资产最常见的失效方式。它们可以用于人工试跑，也能进一步发展为自动化评测样例。重点不是每次输出字面一致，而是边界和结论等级正确。
+-->
+
+---
+
+# 资产更新只接受两类证据
+
+<div class="mt-5 text-xs">
+
+| 更新依据 | 应如何处理 |
+|---|---|
+| 项目规则、框架、接口或测试基座发生变化 | 更新适用范围、来源路径和验证方式 |
+| 资产在真实任务中造成误用、遗漏或无效输出 | 补充反例、停止条件或拆分更小资产 |
+| 只是觉得“提示词不够顺” | 保留意见，不能直接升级为规则 |
+| 想把另一个项目的细节抄进来 | 先标记为待确认，并重新获取证据 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+资产演进依赖新证据，不依赖个人偏好或模型建议本身。
+</div>
+
+<!--
+逐字稿：资产可以更新，但更新必须有新证据。项目规则、框架、接口或测试基座变化时，可以调整适用范围和验证方式；真实任务暴露误用或遗漏时，可以补反例和停止条件。仅仅觉得一句话不够顺，不能成为改变团队资产的理由。
+
+这里的更新原则与项目约束 Skill 相同：规则、Prompt 和 Skill 的变化需要对应新的项目事实或真实失效记录。否则资产会很快从“经验”退化成“偏好集合”。
+-->
+
+---
+
+# 可复用与必须重查的内容
+
+<div class="mt-5 text-xs">
+
+| 可以跨项目复用 | 换项目必须重新获取 |
+|---|---|
+| 事实、方案、验证、边界的输出结构 | 路径、模块名、字段、接口与权限码 |
+| 证据不足时停止的规则 | 状态枚举、异常映射和事务边界 |
+| Prompt 的输入输出契约 | 构建命令、测试基座和目录结构 |
+| Skill 的质量门禁与测试矩阵 | 业务必填条件与发布前置条件 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+资产复用的是判断方法，不是上一次项目的结论。
+</div>
+
+<!--
+逐字稿：跨项目复用的不是上一个项目的结论，而是判断结构。事实、方案、验证和边界的输出方式可以复用；路径、字段、接口、权限码、状态枚举和测试命令必须重新获取。把这条边界守住，资产才能帮助新项目而不是带去旧项目的错误假设。
+
+这张表把“可复用”和“需重查”说清楚。正是这个边界，让资产可以被长期使用，而不会成为把旧项目结论硬套到新项目的风险来源。
+-->
+
+---
+
+# 资产验证后，进入 Agent 封装
+
+<div class="mt-8 text-lg">
+案例提供事实和反例；资产把事实背后的判断方法保存下来。
+</div>
+
+<div class="grid grid-cols-5 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">资产选型</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">Rule 契约</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">Prompt 契约</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">Skill 组合</div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">资产验证</div>
+</div>
+
+<!--
+逐字稿：经过资产边界验证后，下一步不是继续堆更多说明，而是把稳定职责封装成受控 Agent。案例提供事实和反例，资产保存判断方法，Agent 则在运行时选择资产并受工具权限约束。这样才能让复用发生在正确的层次。
+
+Rule、Prompt、检查单、示例和 Skill 已经具备可复用的内容边界。接下来要解决的是：怎样把它们加载给一个职责固定、权限受控的自定义 Agent，使资产在运行时仍能保持边界。
+-->
@@ -0,0 +1,138 @@
+# 模块 8：自定义 Agent：把稳定角色做成资产
+
+<div class="mt-6 text-sm">
+
+自定义 Agent 不是另起一套 Prompt。
+
+它把一个稳定的职责、可用工具、默认指令和交付边界封装为可选择的角色，让每次任务不必从“你是谁、能做什么”重新说明。
+
+</div>
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">职责固定</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">工具受控</div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">指令稳定</div>
+<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">结果可验</div>
+</div>
+
+<!--
+逐字稿：自定义 Agent 的本质是稳定角色配置，不是再写一份更长的说明。它把职责、默认指令、可用工具和交付边界固定下来，让任务启动时不必重复解释角色应该做什么。当前项目事实仍然必须在运行时提供，不能写死在角色里。
+
+本机 Trae CN 3.3.70 已包含“自定义智能体”的创建、配置和工具选择界面。产品内置文案明确支持 Agent 名称、用途说明、参数提示、模型和可访问工具。
+
+本模块不重复第三天“单 Agent / 多 Agent”的概念，而是把自定义 Agent 作为一份可维护的运行时资产来拆解。
+-->
+
+---
+
+# 它和其他资产分别解决什么？
+
+<div class="mt-5 text-xs">
+
+| 资产 | 固化的内容 | 不承担的内容 |
+|---|---|---|
+| Rule | 必须遵守的长期约束 | 多步任务编排 |
+| Prompt | 一类提问的输入输出结构 | 角色权限与默认工具 |
+| Checklist | 固定遗漏点 | 源码分析与方案判断 |
+| Skill | 多步工作流、资源与停止条件 | 对话入口的默认身份 |
+| 自定义 Agent | 角色、指令、模型和工具边界 | 某个任务的项目事实 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+自定义 Agent 负责“谁来做、能做什么”；Skill 负责“这类任务按什么流程完成”。
+</div>
+
+<!--
+逐字稿：这张表的重点是职责不能混。Rule 保存长期约束，任务上下文契约保存一类任务的输入输出，Checklist 保存固定遗漏点，Skill 保存工作流，Agent 保存角色和工具边界。Agent 负责谁来做、能做什么，但不应把所有规则和项目事实复制进自己身上。
+
+这个边界非常关键。Agent 不应该把 Rule、Prompt 和 Skill 的正文全部复制进去，否则会产生多份相互漂移的知识。
+
+Agent 是入口和角色；Skill 是任务工作流；Rule 和检查单仍然是可独立更新的资产。
+-->
+
+---
+
+# 一个自定义 Agent 的配置契约
+
+<div class="mt-5 text-xs">
+
+```md
+---
+name: 状态变更审查
+description: 分析状态写入、资源副作用与验证边界。
+argument-hint: "变更目标、相关源码、测试或 diff"
+model: <当前环境允许的模型>
+tools: <仅选择完成该职责所需的工具>
+---
+
+先提取事实；证据不足时列出缺口；
+不修改代码；输出影响链路、方案比较、验证项和待确认事项。
+```
+
+</div>
+
+<div class="mt-6 grid grid-cols-2 gap-3 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">标头：让 Trae 识别角色、入口与能力边界</div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">正文：让 Agent 在任务中保持判断与交付边界</div>
+</div>
+
+<!--
+逐字稿：一个可维护 Agent 至少要有两层契约。标头让系统识别角色、输入提示和工具范围，正文规定取证方式、输出格式和停止条件。这里的示例设置为只读分析，是为了先建立事实和边界，再决定是否进入实施，不让 Agent 一开始就拥有不必要的写权限。
+
+这是字段示意，不承诺某个模型名或工具 ID。Trae 内置帮助文字说明：名称用于 UI 展示；description 说明职责与使用时机；argument-hint 描述期望输入；model 指定 Agent 运行模型；tools 决定可访问的工具集。
+
+该示例特意设置为“只分析、不修改”，因为从真实案例中抽取资产时先要建立可验证事实，不能直接执行写入操作。
+-->
+
+---
+
+# 固定配置与运行时输入必须分开
+
+<div class="mt-5 text-xs">
+
+| 固定在自定义 Agent 中 | 每次任务重新提供 |
+|---|---|
+| 角色名称与职责范围 | 本次变更目标 |
+| 先取证、后判断的工作原则 | 相关目录、文件、diff、日志 |
+| 可用工具与停止条件 | 当前状态、字段、接口与权限事实 |
+| 结构化输出要求 | 实际执行过的测试或验证结果 |
+| 引用哪些 Rule / Skill | 本次允许与禁止的改动范围 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
+把项目路径、字段名和历史结论写死在 Agent 中，会让它离开原项目后继续错误复用。
+</div>
+
+<!--
+逐字稿：Agent 中只放稳定的角色配置，项目事实必须每次重新提供。角色职责、最小授权、输出结构和停止条件可以固定；本次目录、字段、diff、测试结果和允许修改范围必须随任务更新。否则 Agent 会把上一项目的路径和结论误用到新任务中。
+
+可以把自定义 Agent 理解为“稳定角色配置”，而不是项目知识库。项目事实必须作为运行时上下文输入；这是避免 Agent 把旧项目结论套到新项目上的根本原则。
+-->
+
+---
+
+# 什么时候不该创建自定义 Agent？
+
+<div class="mt-5 text-xs">
+
+| 需求 | 更合适的做法 | 原因 |
+|---|---|---|
+| 只要一句固定约束 | Rule | 不需要独立角色 |
+| 只生成一段固定格式文本 | Prompt / Command | 无需工具与长期指令 |
+| 只核对少数固定项 | Checklist | 无需自主检索判断 |
+| 只有一次临时排查 | 普通对话与任务记录 | 长期复用价值不足 |
+| 需要稳定职责、工具边界和结构化交付 | 自定义 Agent | 角色本身有重复价值 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+“每个任务一个 Agent”会造成角色泛滥、说明重复和难以维护。
+</div>
+
+<!--
+逐字稿：并不是所有任务都值得创建自定义 Agent。固定规则用 Rule，固定格式输出用任务上下文契约或 Command，少数检查项用 Checklist，一次性排查用普通任务记录。只有职责稳定、需要独立工具边界并且能够结构化交付时，创建 Agent 才有长期价值。
+
+资产化的核心依然是识别重复。自定义 Agent 的适用条件是角色稳定且需要独立工具边界；不是因为一个提示词写得很长，就应该升级为 Agent。
+-->
@@ -0,0 +1,121 @@
+# 模块 9：Agent 的权限与停止边界
+
+<div class="mt-6 text-sm">
+
+给 Agent 更多工具，不会让结论更可靠，只会扩大它可能造成的影响。
+
+角色、上下文和工具权限必须同时收敛，才能让一份 Agent 资产在不同任务中保持可控。
+
+</div>
+
+<div class="grid grid-cols-3 gap-4 mt-8 text-sm">
+<div class="p-4 rounded-xl bg-blue-500/10 border border-blue-500/30 text-center">角色<br><span class="text-xs op-70">允许承担什么判断</span></div>
+<div class="p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-center">上下文<br><span class="text-xs op-70">允许读取什么材料</span></div>
+<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30 text-center">工具<br><span class="text-xs op-70">允许产生什么副作用</span></div>
+</div>
+
+<!--
+逐字稿：给 Agent 更多工具，不会自动提高结论质量，反而会扩大错误操作的影响。可靠的 Agent 必须同时收敛三件事：它承担什么角色、能读取哪些材料、可以产生哪些副作用。最小授权不是使用时的提醒，而是 Agent 定义的一部分。
+
+自定义 Agent 的工具集是 Trae 可配置字段，因此权限不是课后补充项，而是 Agent 定义的一部分。这里把“最小授权”落在编写 Agent 时，而不是只靠使用者记住。
+-->
+
+---
+
+# 按风险选择最小工具集
+
+<div class="mt-5 text-xs">
+
+| Agent 类型 | 典型职责 | 最小能力方向 | 不应默认拥有 |
+|---|---|---|---|
+| 代码理解 Agent | 定位入口、调用链与事实 | 代码搜索、文件读取 | 写文件、执行发布 |
+| 方案审查 Agent | 比较方案与范围风险 | 读取源码、diff、规则 | 直接修改业务代码 |
+| 测试设计 Agent | 生成测试点与验证方案 | 读取需求、代码、测试 | 宣称测试已经通过 |
+| CI 分析 Agent | 分层解释失败日志 | 读取日志、配置、diff | 修改环境或密钥 |
+| 实施 Agent | 在确认范围内生成变更 | 受控编辑与验证 | 自行扩大任务范围 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
+先定义角色，再分配最少工具；不要先打开全部权限，再期待提示词自己约束行为。
+</div>
+
+<!--
+逐字稿：工具权限要从职责反推，而不是先把所有能力打开。代码理解 Agent 只需要搜索和读取，方案审查 Agent 不应直接改代码，CI 分析 Agent 不应碰环境和密钥，实施 Agent 也只能在确认范围内编辑和验证。角色越具体，授权就越容易解释和审查。
+
+表格讨论的是权限设计原则，不绑定 Trae 某个工具 ID。实际配置时按当前工具选取器中可用的读、写、终端和 MCP 能力选择，并遵守项目已有安全规则。
+-->
+
+---
+
+# 用真实案例设计一个只读审查 Agent
+
+<div class="mt-5 text-xs">
+
+```text
+角色：状态变更审查 Agent
+输入：变更目标、入口与 Service 源码、状态定义、相关测试或 diff
+可读材料：页面/API、权限与审计入口、状态写入代码、测试结构
+输出：事实表、影响链路、最小改动建议、验证清单、待确认项
+禁止：修改代码、执行发布、把前端必填当作最终业务保护
+停止：缺少状态写入点、关键规则冲突、验证证据缺失
+```
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
+公务用车案例在这里只贡献“状态变更要先取证”的素材，不把任何字段名或接口路径固化为通用规则。
+</div>
+
+<!--
+逐字稿：这个只读审查 Agent 是案例中真正值得沉淀的部分。它读取页面、接口、权限、审计、状态写入和测试结构，交付事实表、影响链路和验证清单；但它不修改代码，也不把前端必填当成最终保护。保留下来的是“状态变更先取证”的判断框架，而不是某个字段或接口路径。
+
+这是本课程的真实案例如何进入 Agent 资产：只抽取“状态写入前的必要信息保护”这一判断框架，不把 cancelReason、Controller 路径或权限码固化进去。
+-->
+
+---
+
+# Stop Conditions 是 Agent 的安全阀
+
+<div class="mt-5 text-xs">
+
+| 停止信号 | Agent 应输出 | Agent 不应做 |
+|---|---|---|
+| 缺少入口或关键 Service | 缺失材料清单 | 补猜调用链 |
+| 状态规则与需求冲突 | 冲突来源与待确认问题 | 自行选择业务规则 |
+| 请求超出角色权限 | 范围风险与转交建议 | 临时取得写入或发布权限 |
+| 验证记录不完整 | 待执行验证项 | 写成“已通过” |
+| 需要外部系统事实 | 所需日志、接口或外部确认项 | 将源码推断包装成运行结论 |
+
+</div>
+
+<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
+可靠 Agent 的表现不是总能继续，而是知道何时不能再继续。
+</div>
+
+<!--
+逐字稿：停止不是失败，而是 Agent 的安全能力。缺关键源码、规则与需求冲突、请求超出权限、验证记录不完整，或者需要外部事实时，Agent 应交付缺口与下一步，而不是补猜调用链、临时扩大权限或把推断写成通过。可靠性来自知道何时不能继续。
+
+Stop Conditions 应同时写进 Agent 指令和 Skill 工作流。对于只读 Agent，停下来并提出缺口是正确结果；它不应为了给出结论而越权调用工具或编造外部事实。
+-->
+
+---
+
+# 自定义 Agent 的验收标准
+
+<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
+<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">职责清楚<br><span class="text-xs op-70">知道何时选择它</span></div>
+<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">权限收敛<br><span class="text-xs op-70">只拥有必要工具</span></div>
+<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">输出稳定<br><span class="text-xs op-70">可被后续 Skill 或 Review 使用</span></div>
+<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">会正确停止<br><span class="text-xs op-70">证据不足不虚构</span></div>
+</div>
+
+<div class="mt-8 text-sm text-center op-75">
+不能说明“为什么需要这个角色、为什么给这些工具”的 Agent，不应进入共享资产库。
+</div>
+
+<!--
+逐字稿：验收一个自定义 Agent，不能只看它能否回答问题。还要确认职责是否清楚、工具是否收敛、输出是否可以被下游使用，以及证据不足时会不会正确停止。无法解释为什么需要这个角色、为什么给这些工具的 Agent，不应进入共享资产库。
+
+这页是自定义 Agent 的质量门禁。每一项都可以通过代表性任务试跑检查：正常任务是否交付，缺失材料是否停下，越权要求是否拒绝，输出是否可被下游资产消费。
+-->