Codex
20 KiB
20 KiB
UniDesk 分布式敏捷开发扩展参考
本文件承载从 SKILL.md 拆出的低频细节，保持高频路由文件紧凑。
- 阻塞评论必须讲清"为什么这是阻塞、它和当前 issue 的关系、下一步怎么解阻"。
- 不能只贴错误码、stack、JSON 摘抄或 ID 清单。
- 两层验证
- 源码层快速回归
- P1 定位根因后，默认找最小代码路径，用单元测试、合同测试、fake store、fake HTTP request、fake runtime env 等复现 bug。
- 修复后的目标行为必须固化成可重复运行的测试。
- 能 mock 的 bug 必须补源码层测试再进入 PR。
- 真实运行面验收
- CLI / Web 等价 / 原入口层必须打到目标 lane / URL / namespace / provider / device-pod / trace dispatcher，证明已发布 runtime 真的修好。
- 单元/mock 通过不能关闭 issue，关闭仍必须有 P4 原入口或真实 runtime 验收。
- 缺层说明
- 真实入口通过也不能替代可行的源码层回归测试。
- 没补源码层测试时，PR/issue 必须说明硬件物理状态、第三方 provider 非确定行为、缺少可注入边界且本次不宜扩 scope 等具体原因，并考虑最小合同、parser、env/配置选择测试或 follow-up issue。
- Closeout 必须同时写清两层证据；任一层不适用时写明原因。
- 源码层快速回归
4 阶段流程
┌────────────────────────────────────────────────────────────────────┐
│ P1 实地探测 → P2 最小运行面实验 → P3 持久化交付 → P4 原入口验收 │
│ SSH 透传定位根因 热补丁/替代实验 Git/项目交付收敛 用户入口复测 │
│ 只读优先，可控探针 能热补就热补 按项目适配器执行 证据落 issue │
└────────────────────────────────────────────────────────────────────┘
P1：SSH 透传实地探测（只读优先，可控探针）
目标：先用真实运行面数据定位根因。结束时必须能给出"症状 + 触发路径 + 根因 + 影响面 + 期望修复方向"。
| 子步骤 | 命令 / 动作 | 退出条件 |
|---|---|---|
| 1.1 重读目标 AGENTS.md | trans <route>:/<fixed-repo> sh -- 'cat AGENTS.md' + 相关 docs/reference/* |
取得目标仓库的当前任务约束（不靠主 server 记忆） |
| 1.2 grep 关键字定位 | rg "<symptom-keyword>" --type ts --type mjs 等 |
找到嫌疑文件 + 行号 |
| 1.3 实测复现 | trans <route> sh -- '<repro command>' / 原入口 CLI / bounded logs / trace |
拿到真实 trace / error / argv，不靠理论推导 |
| 1.3b 临时探针（可选） | 只读证据不足时，最小 apply-patch 插入临时日志或旁路探针 |
记录目标、基线、diff、撤回方式和证据；不得混成正式修复 |
| 1.4 写根因小结 | 用 issue 原文 + 探测证据，先自然语言说明用户现象、触发路径、根因、影响面、期望修复方向和可行的单元/mock 复现点，再列关键 trace/argv/status | 可贴回 issue 评论区作为进展锚点，读者不看命令细节也能明白当前判断 |
P1 强约束：
- 证据边界
- 事实优先：严禁以"理论推导"代替实地探测；外部 API、设备、provider 的行为可能在变，必须先复现再下结论。
- 影响面：跨 lane / 跨 host 一致性问题，先在目标 lane 做最小真实闭环，再讨论通用解。
- 写入边界
- 探针：P1 默认只读；只有只读证据不足时才进入 1.3b 临时探针，且探针必须可撤、可解释、可审计。
- 修复：P1 禁止写持久化修复；临时探针不算修复完成，也不能带入 P3 正式 diff。
P2：最小运行面实验（热补丁优先，可解释跳过）
目标：用最短反馈路径证明修复方向有效。能在目标运行面安全热补时，优先直接对 pod / host workspace 运行 trans <runtime-route> apply-patch；不能热补时，必须写清不可热补原因和替代验证路径。结束时必须能给出"实验前状态 vs 实验后状态"的可比证据。
P2 决策树：
- 热补判定
- 必须热补：问题依赖真实 runtime config / Secret / env / proxy / provider / 硬件 / k3s 对象，且目标文件或配置能被安全、可撤地热修改。
- 可跳过热补但不可跳过验证：编译型二进制、静态 bundle、schema/migration、构建产物、短连接 CLI、文档治理、测试修复或必须经 CI/CD 产物才能生效的改动。
- 跳过记录：在进展评论或 closeout 中记录
P2 disposition=not-hotpatchable、原因、替代证据和后续 P3/P4 验证命令。
| 子步骤 | 命令 / 动作 | 退出条件 |
|---|---|---|
| 2.1 记录运行面基线 | 记录目标 pod / host / service、source commit 或镜像版本、修复前 trace / argv / status | 后续 P3 能对齐同一基线 |
| 2.2 设计最小运行面改动或替代实验 | 找到最小的代码 / 配置 / 命令行 / 单元或合同 mock 测试改动，能证明方向 | 热补丁优先；不可热补时替代路径可解释；可 mock 的 bug 必须同时设计快速回归测试 |
| 2.3 实地热实验补丁（适用时） | 直接对目标 pod / workspace 执行 trans <runtime-route> apply-patch |
运行面只包含本次实验改动，可撤回 |
| 2.4 真实环境试跑 | 用目标运行面、原入口 CLI 或获批执行面直连真实 cloud-api / k3s / 设备 pod；不可热补时跑最小等价验证 | 修复路径在目标运行面或等价验证面走通 |
| 2.5 写闭环证据 | 先用正文说明实验验证了哪个修复方向、实验前后行为差异和是否可进入 P3，再列修复前/后 trace / argv / status | 能解释 P2 结论、P3 目标和是否仍需原入口复测 |
P2 强约束：
- 实验纪律
- 热补真实性：不要把需要 CI/CD 重建或镜像重推才能验证的改动伪装成热补；这类任务记录不可热补原因并转入 P3 的受控交付验证。
- 控制面冲突：热修复动作和标准 Tekton/Argo CD 打架，或被自动滚动覆盖时，创建旁路 pod 实验，不和标准 CI/CD 抢夺控制权。
- 阶段边界：P2 热补通过前禁止 commit、push、开 PR、触发 CI/CD 或把运行面热补当成正式修复；不可热补任务必须先完成 P2 disposition 说明。
- 证据纪律
- 临时改动：P2 临时改动只作为 P3 持久化交付的证据来源；pod 内 sed、临时 apply-patch、单测 mock 通过都不是修复完成证据。
- 外部依赖：第三方模型 / API / 硬件异常，必须用受控透传在真实 pod/host/provider 上复现后再下结论。
P2 推荐补丁方式：
- 入口
- 默认直接把 Codex
apply-patchenvelope 用 heredoc 投到目标运行面，不强制写临时 patch 文件。
- 默认直接把 Codex
- 示例
trans G14:k3s:hwlab-v02:hwlab-cloud-api/app apply-patch <<'PATCH'
*** Begin Patch
*** Update File: internal/cloud/example.ts
@@
old context
-old line
+new line
next context
*** End Patch
PATCH
- 特殊情况
- 大补丁：可以临时落文件后
< patch.diff，但这只是便利手段，不是流程要求。 - 路径映射：运行面路径与源码路径不一致时，P2 可以只写 runtime-specific envelope；P3 再把同一逻辑用源码路径落回 worktree，并在 issue 证据里说明路径映射和逻辑等价关系。
- 禁止绕路：不要从 host/worktree 取
git diff、改路径、再用复杂 shell quoting 拼到 pod；文本热修优先走trans <目标运行面 route> apply-patch，第一个 route token 直接定位到目标 pod / workspace。
- 大补丁：可以临时落文件后
P3：持久化交付（落回 source truth + 项目适配器）
目标：把 P2 验证有效的修复落到目标项目声明的 source truth，并通过项目适配器完成交付。结束时必须能给出可审计 provenance：commit / PR / artifact / PipelineRun / deploy job / runtime metadata 中与本次任务相符的一组证据。
P3 交付画像在上方 DAD-DEV SPEC 定义；3.1 必须从 pr-rollout、pr-lightweight、artifact-deploy、config-docs-only、runtime-recovery-followup 中选择一种，并写清选择理由。
| 子步骤 | 命令 / 动作 | 退出条件 |
|---|---|---|
| 3.1 选择交付画像 | 重读目标 AGENTS.md + 相关 docs/reference/*，确认分支、workspace、PR/CD 边界 |
明确本任务使用哪种 P3 画像和为什么 |
| 3.2 准备 source workspace | 按项目规则快进 fixed repo；从最新 remote/base 创建独立 .worktree/<task>，后续只在该 worktree 内工作 |
base、remote、branch、worktree 路径和 fixed repo 并行修改状态可审计 |
| 3.3 整理正式修改 | 用 apply-patch 对源码收敛最终修改 |
diff 聚焦，不带 P1/P2 临时日志、探针或旁路脚本 |
| 3.4 验证 | 跑仓库声明且与本变更相关的 check / test / smoke；对已定位 bug 优先跑新增或修改的单元 / 合同 / mock 复现测试；缺依赖按 lockfile 安装后继续 | 相关验证通过；新增回归测试能在源码层表达目标行为；预存失败或不可运行有证据和分类 |
| 3.5 提交 / PR / merge | 按交付画像执行 commit、push、PR、merge；GitHub 写走项目受控 CLI | commit / PR / merge 可追溯 |
| 3.6 受控交付 | 按项目适配器执行 CI/CD、artifact、rollout、deploy 或跳过 CI/CD（pr-lightweight / config-docs-only） | 不用裸 kubectl / argo / 原生 gh / 手写 REST 作为长期正式入口 |
| 3.7 provenance 验证 | 用项目 status/health/target validation 查看目标 commit/artifact 是否进入运行面（若适用） | runtime provenance 与本任务 source truth 对齐 |
P3 强约束：
- 入口与执行面
- 受控入口：GitHub 写、CI/CD 写、rollout 写一律走项目受控 CLI；具体命令以目标仓库当前 reference 和 CLI help/source 为准；CLI 字段不够先改 CLI 再用，不能把过期 skill 示例当成绕过理由。
- 构建边界：禁止 master server 做 build / 镜像构建；master 只做轻量源码编辑、Git 和受控 CD 观察；CI/CD 编译产物在外部 builder 跑。
- source truth
- 文本修改：源码和远端文本修改一律走
apply-patch（包括trans <route> apply-patch）；禁止用 heredoc / sed / 复杂 shell quoting 拼接大段 patch；apply-patch语法见AGENTS.mdCritical Apply Patch Syntax。 - source / worktree：禁止把落后 fixed repo 或带并行修改的 fixed repo 当 scratch 区；必须先按项目规则 fetch、状态核查，再从最新 remote/base 创建 P3 独立
.worktree/<task>/ branch / PR；无服务任务也使用pr-lightweight的轻量 PR 形态。 - P2/P3 对账：记录 P2 热实验基线和 P3 source base；若目标分支已推进，比较中间提交是否影响触发路径；有影响则 replay 后重跑必要 P2/P4，没影响则记录 targeted revalidation 依据。
- 文本修改：源码和远端文本修改一律走
- 回归保护
- 根因能稳定抽到代码路径、配置选择、请求/响应、parser、状态机、权限或 dispatcher 合同时，P3 PR 必须包含相应单元 / 合同 / mock 测试；没有补时，PR/issue 必须说明不可行原因和替代快速拦截方案。
项目适配器
本 skill 不复制项目 runbook。进入 P3/P4 前，按目标项目读取适配器：
- HWLAB：以目标 HWLAB workspace 的
AGENTS.md和 UniDeskdocs/reference/hwlab.md为准。无服务 CaseRun、短连接 CLI、trace、config、docs、helper 和配置治理类任务走pr-lightweight；node、lane、自动 CI/CD、target validation、public endpoint 和 device-pod closeout 只由当前项目适配器与 owning YAML 决定，不是 unidesk-daddev 通用步骤。 - AgentRun：以
docs/reference/agentrun.md为准；目标 node、lane、source worktree 与自动 CI/CD authority 只从当前 owning YAML 和项目适配器解析。 - UniDesk CLI/trans/helper：以 UniDesk
AGENTS.md、docs/reference/cli.md、docs/reference/dev-environment.md为准。无服务 CLI、trans/tran/helper、docs、config、trace 和治理类变更走pr-lightweight（独立 worktree、分支、PR，可自合并，跳过 CI/CD/rollout）；业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 等高风险改动按对应发布画像处理。仍不得在 master server 跑仓库级 check/build/smoke。 - 其他项目：先从目标 repo 的
AGENTS.md或 reference 提取：source truth、workspace、branch、交付画像、验证入口、issue close 规则和禁止动作。缺适配器时先写最小适配决策，再执行 P3。
P4：交互式验收（原入口复测 + issue 关闭）
目标：用与用户最初报告的相同入口（同一 CLI、同一 device pod、同一 job id）跑一遍验收清单，把能证明修复有效的运行面证据贴回 issue，再关 issue。
| 子步骤 | 命令 / 动作 | 退出条件 |
|---|---|---|
| 4.1 准备验收清单 | 梳理 issue 里的"复现步骤 / 验收清单" | 每条都可独立跑、可独立判定 |
| 4.2 原 CLI 跑全清单 | hwpod ... / trans <route> sh -- '<cli ...>' |
每条"期望 vs 实际"都记录 |
| 4.3 关键步骤抽 trace | 抓取 job id + argv + status + blocker 全文 | argv 是修复是否生效的硬证据 |
| 4.4 写 closeout comment | 用项目受控 GitHub/issue CLI 写语义化 closeout：先用自然语言说明问题、根因、修复、验收结果和剩余边界，再列审计证据；长正文优先 --body-file 评论 |
读者能不解析 telemetry 就看懂结论，同时包含 PR/commit/artifact/rollout/provenance、耗时、原入口验收结果、已知未关项 |
| 4.5 关 issue | 按当前项目 CLI lifecycle 规则关闭；若 close 命令只接受短评论，先写长证据评论再用短引用关闭 | issue state=closed |
P4 强约束：
- closeout 文本
- 语义正文：开头用自然语言讲清"这个 issue 原来坏在哪里、这次根因是什么、做了什么修改、为什么现在可以认为修好了、还有什么不属于本次范围"；命令、trace、job id、commit、artifact stats 放在后面的证据区，不能用证据区替代正文说明。
- provenance：不强制使用"修复前 / 修复后"配对表，也不强制所有任务列 image digest；必须列出与交付画像匹配的 provenance，例如 commit、PR、artifact、PipelineRun、deploy job、runtime metadata 或 docs/config validation。
- scope：out-of-scope 项必须显式列出（D601 host stale / COM 漂移 / 等）；不能"顺手发现就修"，避免 scope creep。
- 验收证据
- 两层验证：必须区分源码层单元 / 合同 / mock 回归测试和 CLI / Web 等价 / 原入口复测；缺任一层必须写明不适用原因；只跑源码层证据不能关闭 issue，必须用原入口在真实运行面跑过。
- 运行面审计：关键 argv 必须在验收报告里出现原文；关闭评论的"实际命令 / lane / URL / trace / session / job id"必须可被独立审计员复现。
- rollout 耗时：PR/CI/CD/部署滚动实际耗时必须写入 issue 评论区，至少记录起止点、总耗时、明显等待段或重跑次数；无 rollout 的任务说明
rollout=not-applicable。
跨阶段强约束（贯穿 P1-P4）
- 变更纪律
- worktree：P3 默认先按项目规则更新 fixed repo，再从最新 remote/base 创建独立
.worktree/<task>/ branch / PR；所有会写文件、提交、推送、issue closeout 或受控部署的动作都在该 worktree 内执行，fixed repo 只做只读预检和 worktree anchor。 - push 条件：worktree 干净且 P2 disposition 明确后才能 push；发现 P3 入口时 source commit 与 P2 运行面基线不一致，先做影响面对账。
- 并行变更：fixed repo 或其他 worktree 中的并行变更默认保持原样；当前任务用独立
.worktree隔离，必要时只 cherry-pick 明确相关提交，不要 stash / 丢弃 /git reset --hard。
- worktree：P3 默认先按项目规则更新 fixed repo，再从最新 remote/base 创建独立
- 证据纪律
- trace 落盘：issue 原始复现证据与最终验收 trace / job id / argv 要写到 issue 评论区；不要求逐条整理成配对表，但必须先有自然语言正文解释证据含义。
- rollout 记录：PR/CI/CD/部署滚动的起止时间、总耗时、重跑次数或等待段必须写到 issue 评论区；无 rollout 的任务写明不适用，并用正文解释交付路径。
- 进展锚点：用 issue 评论作进展锚点；不把 commit message、临时文件或 agent session memory 当进展锚点。
- 治理纪律
- 可见性优先：命令无输出、状态不可见、日志尾部缺失、trace 被截断或耗时不可见时，先修可见性再继续原任务；不用长日志全量 dump 代替结构化状态，优先补 CLI summary、job status、bounded tail 和 raw drill-down。
- 门禁最小化：拦截当前最新任务目标的旧测试、旧门禁、旧合同检查、旧预检、旧断言和旧 guard 一律拆除；新增 gate 只覆盖当前目标下明确且高价值的风险，优先用证据、文档共识、代码结构和标准入口自然收敛。
禁止行为
- 阶段错位
- 流程绕过：跳过 P1 实地探测直接改 pod 文件、跳过 P2 disposition 直接 P3 持久化、跳过 P3 持久化交付直接靠热修宣称"修好了"，每次出现都强制回到 P1 重做。
- 临时当正式：pod 内热修 / 临时 apply-patch / 单测 mock 通过 ≠ 修复完成；P2 的产物是"修复需求来源"，P3 的 source truth + provenance 才是"修复证据"。
- 入口绕过
- master 构建：master 是生产入口，构建会拖垮生产；任何"在 master 跑 check 通过"都不能作为有效证据。
- 原生命令写入：
kubectl apply/ 原生gh issue edit/ 手写 REST 写入 GitHub = 绕过项目受控 CLI，会失去 body guard、字段约束、token 轮换和审计日志；若项目允许某个 repo-owned merge path，必须在适配器里写明。
- 验证反模式
- 大回环试错：Tekton pipeline / Argo rollout 不是"兼容性探索工具"；改一行 → push → 等 CI → 看结果 → 再改 → 再 push = 把 CI 当成编译器调试器用。
- 缺依赖 skip："因为 deps 没装所以跳过这个 check" = 把 noise 当 signal，必须按 lockfile 装上再验证。
- 只做 CLI 交互验收：CLI/Web 等价入口能证明真实 runtime 修好，但不能提供快速回归拦截；可 mock 的 bug 不补源码层测试就关闭 issue = 把回归风险留给用户和慢速验收。
- 边界污染
- 旧路径：旧测试、旧合同检查、旧 guard、旧 gate 与当前任务目标冲突时，不允许继续修补、加例外、旁路兼容或长期双路径；删除旧门禁后只补最小必要的新验证。
- scope creep：顺手修不在 issue scope 内的 bug、优化或命名会制造合并冲突并模糊本次修复证据；从 changeset 排除无关修改，若确认是自己刚引入的无关改动，用最小反向 patch 移除；不得回滚或删除他人并行变更。
- 适配器泛化：HWLAB v0.2 的 git mirror、AgentRun v0.1 的 control-plane、UniDesk 的 CI/CD skip 规则等只在对应项目适配器内生效，不要复制到其他项目。
- 基础设施缺陷混入业务 scope：monitor / cron / CLI 字段缺失 / 可见性不足等基础设施问题可先补最小能力解阻；长期恢复应单独 issue 跟踪，不能混入当前业务 PR。
- 证据反模式
- 无证据 close：在 issue 评论里说"应该修好了"不是证据；没有 trace / job id / argv / 截图 = 不能 close issue；证据必须是可被独立审计员复现的命令输出原文。
- telemetry dump：只有 job id、trace、commit、PipelineRun、JSON 片段而没有自然语言正文说明，读者无法理解决策；必须先写语义化正文，再列审计证据。
- session memory：agent session memory / 历史对话不可审计；证据必须落在 issue comment / git commit / PipelineRun / k8s object 这类可被外部引用的位置。