AGENT

任务包与能力分层路由规范

2026/04/21 40 min read AGENT 任务包与能力分层路由规范

任务包与能力分层路由规范

目标

这份规范是当前 Atramenti-Console 的执行基线,用来把“用户一句话需求” 收口成可执行、可验证、可交接、可复用的工作流,而不是每次都从零靠即时发挥。

这轮基线先做五件事:

  1. 建立任务简报
  2. 建立复杂任务规格
  3. 建立验证包与证据链
  4. PROJECT-CONTEXT.md / SESSION-HANDOFF.md / plan.md 绑定成三件套
  5. 建立能力分层路由,最后才考虑大规模 Skill 化

一、任务包基线

1.1 标准落点

任务包默认落到:

  • E:\My Project\Atramenti-Console\codex\_artifacts\task-packs\<timestamp>-<slug>\

标准文件:

  • TASK-BRIEF.md
  • COMPLEX-TASK-SPEC.md
  • VERIFICATION-BUNDLE.md
  • evidence\

创建脚本:

  • E:\My Project\Atramenti-Console\codex\skills\task-pack-baseline\scripts\new-task-pack.ps1

模板目录:

  • E:\My Project\Atramenti-Console\codex\templates\task-pack

1.2 什么时候必须建任务简报

满足任一条件就默认要建:

  • 任务超过一步
  • 会改多个文件
  • 需要验证
  • 属于 review / 调研 / 排障
  • 可能跨回合继续

任务简报的职责不是写长文,而是先锁定:

  • 用户真正要的结果
  • 本轮边界
  • 非目标
  • 立即成功标准

1.3 什么时候必须补复杂任务规格

满足任一条件就默认补:

  • 跨系统或跨服务
  • 涉及文档、脚本、代码、配置多种载体
  • 需要分阶段验收
  • 存在显著影响面或回滚边界
  • 后续很可能被做成稳定 workflow / Skill

复杂任务规格要明确:

  • 影响面
  • 分层路由决策
  • 分阶段实施
  • 证据要求
  • 回滚点

二、验证包与证据链

2.1 验证包不是“跑过命令”

验证包要回答的是:

  • 最终证明了什么
  • 哪些已经 verified
  • 哪些仍然 unverified
  • 哪些 failed
  • 每条结论的证据在哪里

生成脚本:

  • E:\My Project\Atramenti-Console\codex\skills\task-pack-baseline\scripts\task-verify.ps1

2.2 证据链的最小结构

证据链至少要把三件事连起来:

  1. 结论
  2. 证据文件 / 命令 / 截图 / 日志
  3. 这条证据具体证明什么

禁止只堆文件名不解释含义。

2.3 分类口径

  • verified:关键结论已经被当前证据直接支撑
  • unverified:工作可能已完成,但证据仍不足
  • failed:明确未达成或出现阻断

三、项目上下文 / handoff / plan 三件套

3.1 三件套分工

  • PROJECT-CONTEXT.md:长期真源,记录站点、路径、脚本、能力根、固定约束
  • SESSION-HANDOFF.md:当前会话已做什么、现在是什么状态、下一步是什么
  • plan.md:唯一活计划台账,记录计划与状态更新

这里要明确:三件套是项目 current-state 的唯一活入口。

  • 如果要判断“项目现在是什么状态、下一步应该接着做什么”,先看三件套
  • docs/agent 下的其它文档可以是单专题 canonical,但默认不承担项目总体 current-state 总台账职责
  • 本文本身是执行基线 / 流程规范,不是项目总体状态说明页

3.2 三件套的最低同步规则

非 trivial 任务完成前,至少要做到:

  1. plan.md 有计划或状态更新
  2. SESSION-HANDOFF.md 能让下一个代理接着干
  3. 若形成了新的长期规则或 canonical 路径,回写 PROJECT-CONTEXT.md

3.3 任务包如何挂到三件套

  • 计划记录可以挂关联产物路径
  • handoff 里要能看出当前 task pack / verification bundle 在哪里
  • context 只登记长期会复用的模板、脚本、固定规则,不登记一次性 task pack

3.4 plan / plan.md / SESSION-HANDOFF / experience / MCP 的最小分工

  • plan:当前回合的即时执行骨架,只负责眼前步骤、进行中的判断和局部推进。
  • plan.md:唯一活计划台账,负责跨回合里程碑、状态更新、关联产物与最终结果。
  • SESSION-HANDOFF.md:当前停在哪里、已经验证到哪、下一轮应该接什么。
  • experience-manager:只收可复用结论,不收每一次中间状态;它是长期经验入口,不替代 plan.md
  • MCP / 工具层:负责搜索、执行、浏览器验证、健康检查和证据采集,不负责替代 triad 文档。

判断规则:

  1. 只影响当前回合推进时,用 plan
  2. 多步、多文件、要跨回合接续时,必须写 plan.md
  3. 本轮结束需要可接续上下文时,更新 SESSION-HANDOFF.md
  4. 结论未来大概率复用且已被验证时,才进入 experience-manager
  5. 需要事实、工具执行或证据时,优先走 MCP / 开发者工具。

3.5 自动回灌顺序

非 trivial 任务收尾时,默认按这个顺序回灌:

  1. 先完成验证包与证据链
  2. 再更新 plan.md 状态
  3. 再更新 SESSION-HANDOFF.md 当前状态与下一步
  4. 若形成长期规则或固定路径,再回写 PROJECT-CONTEXT.md
  5. 只有满足经验准入门槛的结论,才同步到 experience-manager
    • 若需要强制写入或跳过,可在 plan.md 状态更新里显式记录 经验沉淀决策:record / auto / skip

这里的关键点是:

  • 先有验证,再有回灌
  • 先有 triad,再有长期经验
  • 经验层是压缩后的复用结论,不是逐条复制计划日志

四、能力分层路由

4.1 分层顺序

默认从低成本层往高能力层走:

  1. 直接执行层
  2. 任务简报层
  3. 复杂规格层
  4. 验证包层
  5. triad 层
  6. Skill 层
  7. MCP / 工具层
  8. 子代理层

4.2 每层负责什么

直接执行层

适合单步、低复杂、无需完整任务包的请求。

任务简报层

把模糊目标变成可执行边界,避免上来就改大块内容。

复杂规格层

把复杂任务拆成可验证阶段,避免后期才发现影响面没锁住。

验证包层

把“我觉得好了”变成有分类、有证据链的交付记录。

triad 层

把一次执行沉淀进长期上下文,而不是只留在聊天记录里。

Skill 层

当工作流已经稳定、重复出现、需要复用时,再收口为 Skill。

MCP / 工具层

当任务需要浏览器、repo 检索、结构化验证、外部页面、远程系统等强工具时启用。

子代理层

只在用户明确允许委派或并行代理时启用,不把它当默认路径。

4.2.1 MCP 默认优先级

当任务已经进入工具层时,默认优先顺序是:

  1. ripgrep-search:文本、文件、字面搜索
  2. dev-quality-mcp:结构搜索、静态扫描、代码质量定位
  3. cloud-repo-mcp:只读仓库内容和轻量审计
  4. workspace-toolkit-mcp / agent-runtime-mcp:工作区与运行态验证
  5. github-workflow-mcp:PR / workflow / run 健康检查
  6. chrome-devtools-mcp:浏览器页面、控制台、网络与视觉验证
  7. fetch-mcp / markitdown-mcp:外部页面抓取与内容抽取

目的不是死板限制工具,而是减少每次都从零决定“先打哪个 MCP”的切换成本。

4.3 路由决策脚本

当前决策脚本:

  • E:\My Project\Atramenti-Console\codex\skills\capability-layer-routing\scripts\resolve-capability-route.ps1

配置文件:

  • E:\My Project\Atramenti-Console\codex\skills\capability-layer-routing\policy\capability-route-map.json

这个脚本不替代判断,它负责把“这次该走到哪一层”说清楚并落盘。

五、与 Skill 化的关系

当前顺序是:

  1. 先有任务包
  2. 先有验证包
  3. 先有三件套同步
  4. 先有能力路由
  5. 再决定哪些模式值得做成 Skill

也就是说,Skill 化应该建立在已经稳定的 brief / spec / verify / handoff / route 基线上,而不是反过来让 Skill 承担所有治理责任。

五点五、经验准入与验证证据

5.5.1 什么值得进入 experience-manager

默认只把下面几类结果写入长期经验:

  • 同类问题重复出现两次以上
  • 明显节省后续排障时间的修复路径
  • 有明确前置条件、适用边界和风险说明的方法
  • 已经有当前轮验证证据支撑的稳定结论
  • auto 默认只针对 已验证 / 失败 且带强复用信号的结果,不自动接收普通 已完成

默认不写入长期经验的内容:

  • 单次试探性的中间状态
  • 还没有验证完成的猜想
  • 只对当前一次性任务有意义的局部进度
  • 只是文件已修改、但没有说明可复用价值的记录
  • routine audit / 候选核对 / feature delivery / 导航补面 / deploy-ready 打包 / 部署上线 / 删仓删除 / 目录改名 / 清理收尾这类一次性交付记录

5.5.2 经验最小字段

当结论要进入 experience-manager 时,至少应能回答:

  • 场景:在什么任务/症状下会用到
  • 解决法:实际采取了什么路径
  • 边界:前置条件、限制和风险是什么
  • 证据:哪份验证、日志、截图或产物支撑这条结论

5.5.2.1 auto 的默认门槛

经验沉淀决策=auto 时,默认要同时满足:

  • 状态是 已验证失败
  • 标题不属于 routine audit / 候选核对 / feature delivery / deploy-ready / 部署上线 / 删仓删除 / 清理收尾 / 改名归档
  • 满足至少一个强复用信号:
    • 避免重走 非空
    • 标题属于修复 / 根因 / 规则 / 门禁 / 真源 / 路由类 durable 主题,且状态说明里给出明确根因、默认口径、门槛或修复路径

如果不满足这些条件,默认应停留在 plan.md / SESSION-HANDOFF.md,而不是自动升级为长期经验。

5.5.3 验证包里的两个显式决策

非 trivial 任务 closeout 时,验证包应尽量显式写出:

  • Deploy Decisiondeployed / not-needed / blocked
  • Live Verification Decisionpassed / not-needed / blocked
  • 经验沉淀决策record / auto / skip

这样 plan.mdSESSION-HANDOFF.mdexperience-manager 后续引用的是同一套 closeout 语言,而不是各写各的。

六、本轮落地文件

  • codex/templates/task-pack/README.md
  • codex/templates/task-pack/TASK-BRIEF.md
  • codex/templates/task-pack/COMPLEX-TASK-SPEC.md
  • codex/templates/task-pack/VERIFICATION-BUNDLE.md
  • codex/skills/task-pack-baseline/scripts/new-task-pack.ps1
  • codex/skills/task-pack-baseline/scripts/task-verify.ps1
  • codex/skills/plan-history-recall/scripts/append-plan.ps1
  • codex/skills/capability-layer-routing/scripts/resolve-capability-route.ps1
  • codex/skills/capability-layer-routing/policy/capability-route-map.json

七、默认执行顺序

后续遇到非 trivial 任务时,默认按这个顺序走:

  1. invoke-plan-preflight.ps1
  2. resolve-capability-route.ps1
  3. new-task-pack.ps1
  4. 实施改动
  5. task-verify.ps1
  6. 更新 plan.md
  7. 更新 SESSION-HANDOFF.md
  8. 若形成长期规则,再回写 PROJECT-CONTEXT.md

八、AI 时代单真源开发与交付模式

这条模式现在作为默认开发基线,适用于代码、脚本、配置、内容站点、前端页面、 自动化和大多数需要 Git 交付的工作。

核心目标不是“所有东西只留一份副本”,而是:

  • 只有一个第一开发真源
  • 允许按需创建临时工作副本
  • 运行环境只承担运行,不再长期承担第二源码真源

8.1 四个默认角色

后续默认把开发现场拆成四个角色,而不是混成一团:

  1. canonical source
    • 唯一第一开发真源
    • 默认是远端 Git 仓,或该轮真正 owning repo 的可推送边界
  2. working copy
    • 按需创建的本地工作副本
    • 用来编辑、验证、构建、截图、跑测试
    • 默认可回收,不视为长期镜像
  3. deploy target
    • 服务器、容器、静态站运行目录、系统服务宿主
    • 默认只接收运行必需内容,例如构建产物、配置、镜像
  4. mirror / backup
    • 备份仓、外层 umbrella 仓、归档仓
    • 可以吸收结果,但不是第一开发真源

8.2 默认工作方式

默认工作方式收口为:

  1. 找到唯一 canonical source
  2. 在本地创建或更新 working copy
  3. 只在这份工作副本里改动、验证、构建
  4. 把结果先提交并 push 回 canonical source
  5. 再把运行所需结果部署到 deploy target
  6. 最后做 live 验证与 triad 收口

更短的口径就是:

单一真源 -> 临时工作副本 -> 验证 -> push -> deploy -> live 验证

当前默认工作副本根路径:

  • C:\Users\ASUS-KL\.codex\.tmp\working-copies

当前默认操作入口:

  • 查看 repo manifest:github-delivery-mcp.list_repo_manifests
  • 准备 / 刷新工作副本:github-delivery-mcp.prepare_working_copy
  • 查看工作副本根状态:github-delivery-mcp.list_working_copies
  • 回收工作副本:github-delivery-mcp.retire_working_copy
  • 清理旧工作副本:github-delivery-mcp.prune_working_copies

如果某个 canonical repo 会被反复以 working-copy 方式打开,默认在:

  • E:\My Project\Atramenti-Console\codex\mcps\github-delivery-mcp\manifests

维护一份轻量 repo manifest,把 repoUrlbranchfolderNamedeployTarget 等默认值收口进去,避免每次任务都从聊天里重复描述。

8.3 默认禁止项

如果用户没有明确要求例外,默认不要做下面这些事:

  • 不把服务器上的源码仓当成长期开发现场
  • 不让“本地副本 + 服务器副本 + 远端仓”三边同时变成活真源
  • 不把长期本地镜像当成默认前提
  • 不在运行目录里直接手改源码并把它留成未回灌状态
  • 不为了图省事重新引入双写、双轨、兼容层、兜底分支
  • 不把“临时 clone / 临时 worktree”放着不管,最后变成隐性第二真源

8.4 为什么 AI 时代更要这样做

这条模式在 AI 时代要比手工开发时代更强制,原因有四个:

  1. AI 改动范围更大
    • 常常一次跨多个文件、多个目录、多个文档联动修改
    • 如果真源不唯一,漂移会被快速放大
  2. AI 更依赖可重复流程
    • clone -> 改 -> 验证 -> push -> deploy 比“哪里都能改一点”更适合自动执行
  3. AI 更容易制造隐性平行实现
    • 如果没有单真源约束,就会自然长出第二份页面、第二份脚本、第二份兼容逻辑
  4. AI 排障更依赖现场一致性
    • 运行目录、服务器 repo、本地 repo 三边不一致时,诊断成本会明显上升

8.5 默认交付顺序

对大多数 Git 交付任务,默认顺序现在明确为:

  1. 预检规则、计划和 owning repo
  2. 进入或创建本地 working copy
  3. 搜已有实现,避免平行重写
  4. 修改 canonical 实现
  5. 跑最小必要验证
  6. 在 owning repo 完成 status -> commit -> push
  7. 如果任务涉及运行环境,再部署到 deploy target
  8. 做 live 验证
  9. 更新 plan.mdSESSION-HANDOFF.md、必要时更新 PROJECT-CONTEXT.md

8.6 服务器 / 静态站 / 内容站的默认口径

对于服务器、静态站、博客、前端站点,默认进一步收紧为:

  • 远端 Git 仓是源码真源
  • 本地只保留按需工作副本
  • 服务器只保留运行目录、容器、服务配置或构建产物
  • 如果需要重新编辑,就重新 clone 或更新工作副本,而不是直接在服务器源码仓里改

8.7 源码 / 运行时状态 / 部署产物 / 实时数据边界

以后默认把系统里的内容分成四类,不再混写:

类型 默认放置位置 是否进入 GitHub 真源 说明
源码 canonical source / owning repo 前端、后端、脚本、配置模板、迁移脚本、基础文档
运行时状态 数据库、缓存、队列、对象存储、日志系统 用户数据、任务状态、在线状态、实时统计、消息流
部署产物 服务器运行目录、镜像、发布目录 否(可重建) dist、打包产物、构建后静态文件、镜像层
本地工作副本 本地 clone / worktree 否(本体不是) 只是开发现场,不是长期真源

默认判断规则:

  • GitHub 真源负责“可再生成”的东西
  • 运行时系统负责“正在变化”的东西
  • 部署目录负责“当前正在跑”的东西
  • 本地工作副本负责“本轮正在修改”的东西

不要再把这四种东西混成“反正都算项目文件”。

8.8 实时数据的默认规则

实时变化的数据并不会推翻单真源开发模式,真正要分清的是:

  • 实时变化的是数据,不是源码位置
  • 需要动态的是运行时链路,不是 Git 真源本身

默认规则:

  1. 实时数据不写回 GitHub 当真源
  2. 实时数据默认放数据库 / Redis / 队列 / 实时 API / SSE / WebSocket
  3. GitHub 里可以保留:
    • 数据模型
    • schema / migration
    • 初始化脚本
    • mock / fixture / 示例数据
    • 数据拉取与渲染逻辑
  4. GitHub 里不应保留:
    • 当前在线人数
    • 秒级状态面板数据
    • 实时日志流
    • 当前任务进度
    • 动态缓存内容

更直接地说:

  • GitHub 放“怎么产生数据、怎么处理数据、怎么展示数据的代码”
  • 运行时系统放“此刻的数据本身”

8.9 静态内容与动态内容的默认分层

以后默认按变化频率决定放哪一层:

  1. 低频变化
    • 文章正文
    • About
    • 说明页
    • 视觉壳层
    • 大部分前端页面结构
    • 默认静态化
  2. 中频变化
    • 每小时 / 每天刷新一次的统计
    • 周期性抓取的公开数据
    • 可用“构建快照 + 页面刷新”或“定时重建”
  3. 高频变化
    • 在线状态
    • 任务队列
    • 监控面板
    • 聊天流
    • 日志流
    • 默认走 API / polling / SSE / WebSocket

不要把高频变化的数据硬编译进静态产物里,再靠频繁整站重建假装“实时”。

8.10 静态站里的实时能力默认做法

静态站不是不能做实时,而是要按“静态壳 + 动态数据块”拆开:

  1. 静态部分
    • 页面壳
    • 布局
    • 文本主体
    • 低频数据快照
  2. 动态部分
    • 客户端请求 API
    • 周期刷新
    • SSE
    • WebSocket

默认优先级:

  1. 能静态的先静态
  2. 需要最新但不必秒级的,用定时刷新
  3. 需要实时流的,再上 SSE / WebSocket

8.11 每次新构建后旧静态文件怎么处理

以后默认把“旧文件去哪了”也写清楚,不靠模糊处理:

常见模式只有三种:

  1. 覆盖替换
    • 新文件覆盖旧文件
    • 最简单,但回滚能力最弱
  2. 同步替换
    • rsync --delete 或同类机制让部署目录和新产物完全一致
    • 旧文件若不在新版本中,则被删除
  3. 版本化发布目录
    • 每次发布到新目录
    • 用软链接或切换目标目录上线
    • 旧目录保留作回滚

默认原则:

  • 对小型静态站,同步替换 通常是最干净的默认值
  • 对需要稳回滚的系统,优先 版本化发布目录
  • 不要长期把多代无引用旧产物堆在运行目录里

8.12 构建产物的默认态度

构建产物不是源码真源,它们默认应被视为:

  • 可重建
  • 可替换
  • 可删除
  • 必要时可版本化保留用于回滚

不要反过来把部署目录里的构建产物当作第一编辑面。

如果必须从线上产物回灌,也要明确:

  • 这是恢复动作,不是新的日常工作流
  • 回灌后的结果仍要回到 GitHub 真源收口

8.13 默认决策顺序

以后遇到“这个系统到底该静态、动态、还是混合”的问题,默认按这个顺序判断:

  1. 这是不是源码?
    • 是 -> 去 canonical source
  2. 这是不是运行时状态?
    • 是 -> 去数据库 / 缓存 / 队列 / API
  3. 这是不是部署产物?
    • 是 -> 去 deploy target
  4. 这是不是本轮临时开发现场?
    • 是 -> 去本地 working copy
  5. 这个页面的数据变化频率高不高?
    • 低 -> 静态
    • 中 -> 快照 + 刷新
    • 高 -> 动态链路

8.14 默认维护目标

这条模式最终追求的是四个结果:

  1. 路径少
    • 不到处都能改
  2. 真源清楚
    • 永远知道该 push 哪份
  3. 运行态和源码分离
    • 排障时不把数据问题和源码问题混在一起
  4. 回滚容易
    • 能回滚代码、回滚部署、回滚数据策略,而不是所有东西搅成一团

8.15 例外边界

只有在用户明确要求,或任务天然属于下面这些场景时,才允许偏离这条默认模式:

  • 用户明确要求保留服务器源码仓
  • 该系统必须在云端直接构建,且当前没有更稳的 CI / 本地构建路径
  • 该 repo 天然就是本机专用 consumer/config 层,而不是部署型应用源码
  • 当前任务是应急修复,且必须先在 live 现场止血

即便出现例外,也要做到:

  • 明确这只是例外,不是新的默认模式
  • 明确谁是临时真源,谁要回灌
  • 例外结束后尽快恢复到单真源口径

8.16 默认汇报字段

以后遇到这类开发 / 部署 / 收口任务,默认内部判断与对外汇报都应尽量压成下面这些字段:

  • canonical source
  • working copy
  • owning repo
  • deploy target
  • runtime state
  • deploy artifact
  • data path
  • mirror / backup
  • verification
  • 是否需要回收本地副本

这样做的目的,是让“当前到底该改哪份、推哪份、部署哪份、删哪份”始终清楚。

8.17 编码级审查清单:默认禁止的 defensive code

从这一条开始,单真源规范不只约束“仓位和路径”,也直接约束“代码里怎么写”。

默认目标是:

  • 修契约
  • 修数据模型
  • 修真实入口
  • 修上游调用链

而不是靠 defensive code 把主路径包起来继续跑。

以后在代码审查里,默认先问这几个问题:

  1. 这个值为什么会缺?
    • 是契约真的允许缺失
    • 还是上游本来就写错了
  2. 这个分支是在修根因
    • 还是只是在吞错误
  3. 这段代码是在边界层处理第三方不稳定输入
    • 还是在核心主路径里给自己加兜底
  4. 如果删掉这层 defensive code,真正应该修哪一层?

默认禁止直接引入下面这些写法,除非后面“允许条件”成立:

  1. fallback / compat / downgrade / graceful degradation 之类双轨语义
  2. ensure* 风格包装函数
  3. 没有证据支撑的 ?. / ??
  4. 用空对象、空数组、空字符串把缺失值直接吞掉
  5. if (!x) returnreturn nullreturn [] 之类静默退出
  6. 只为了“别报错”而加的 retry wrapper、兼容分支、默认对象

默认允许 defensive code 的条件,只能是下面这些:

  1. 类型、schema、协议、接口文档明确声明该字段可缺失
  2. 有真实失败证据证明外部输入天然不稳定
    • 例如第三方 API payload、历史脏数据、跨版本迁移数据
  3. 该处理明确位于边界层
    • 例如 adapter、parser、ingest、migration、compat import
  4. 用户明确要求短期过渡层
  5. 当前任务本身就是修复旧数据或迁移现场

即便满足允许条件,也必须同时做到:

  • 把 defensive code 限制在边界层,不要扩散到核心主路径
  • 写清楚为什么允许缺失,而不是只写“防止报错”
  • 优先修 schema / contract / upstream,再保留最小必要防御

默认不允许的说法:

  • “先加个 fallback 再说”
  • “先 optional chaining 一下免得炸”
  • “先给个空对象,后面就能跑了”
  • “先 ensure 一层比较保险”

默认允许的说法应该更像:

  • “接口契约明确允许该字段为空,所以这里只在 adapter 层做一次归一化”
  • “这是第三方 payload 的历史脏数据入口,证据已确认,因此只在 parser 层收口”
  • “这是用户明确批准的短期迁移兼容层,后续要拆除”

以后 review / 自查默认按下面这份执行清单过一遍:

  • 这段 defensive code 是否有明确契约依据?
  • 它是否被压在边界层,而不是核心业务路径?
  • 如果去掉它,是否能直接定位出真正该修的上游?
  • 它是否引入了第二条行为路径?
  • 它是否掩盖了本应失败并暴露的问题?
  • 它是否只是为了“看起来更稳”,而不是让系统结构更正确?

如果以上问题里有任意一项答不上来,默认就不该加。

8.18 自动化门禁:defensive-code guard

为了不让这条规则只停留在文字层,仓内默认再加一层自动化门禁:

  • 新增 codex/skills/plugin-github--git-delivery/scripts/check-defensive-code.mjs
  • 规则真源放在 codex/skills/plugin-github--git-delivery/policy/defensive-code-guard.json
  • 提交闭环 codex/skills/plugin-github--git-delivery/scripts/repo-finalize.ps1 在 commit 前默认执行这道检查

当前 guard 默认检查 staged 改动里的新增代码行,并重点拦截:

  1. fallback / compat / downgrade / graceful degradation
  2. ensure*
  3. ?.
  4. ??
  5. 空对象 / 空数组 / 空字符串式吞错默认值

这道门禁默认只检查第一方代码路径,不把 docs、cache、dist、archive、vendor 之类目录混进来。

如果确实存在经过证明的例外,允许用同一行注释显式豁免:

  • defensive-code-allow

但这不是鼓励常态化豁免,而是要求:

  • 只有契约允许缺失时才可豁免
  • 只有边界层处理时才可豁免
  • 豁免应带简短理由

一句话说,这道 guard 的目标不是“让代码更难提交”,而是强制把“先修根因, 别靠 defensive code 糊住主路径”变成默认机械动作。

九、第二批 live smoke 与第三批垂直 lane

第二批 5 条 lane 不应长期停留在“只有文本结构成立”的状态;至少要用真实任务补一轮 live smoke,证明这些 lane 不只是命名漂亮,而是真的能挂到当前 repo 的高频工作流上。

9.1 第二批 lane 的 smoke 映射

当前推荐用 2-3 个真实高频任务覆盖这 5 条 lane:

  1. research-decision-lane
    • 真实任务:根据 repo 与计划台账决定下一批优先垂直 lane
  2. frontend-closed-loop-lane
    • 真实任务:对真实前端或内容站点执行 build + preview + 浏览器证据
  3. canonical-doc-workflow
    • 真实任务:把 smoke 结论和 lane 图谱回写到 canonical 文档
  4. capability-implementation-lane
    • 真实任务:把研究结论直接落成新的垂直 lane skills
  5. repo-delivery-closeout-lane
    • 真实任务:对本轮文档、skill、artifact、triad 做 scoped commit + push

9.2 第三批优先方向

在第二批通用 lane 之后,第三批默认优先补“更垂直、但仍保持 thin orchestrator”的 lane。

当前优先顺序:

  1. content-source-publish-lane
  2. server-estate-sync-lane
  3. mcp-capability-lifecycle-lane

选择原则:

  • 优先贴近 repo 里的真实高频任务,而不是继续泛化通用 orchestrator
  • 优先包装现有 canonical skills,而不是复制正文实现
  • 若某条业务线已有独立在途边界,则先避让,避免 lane 扩展和在途交付撞车