diff --git a/.agents/skills/upstream-rotation/SKILL.md b/.agents/skills/upstream-rotation/SKILL.md new file mode 100644 index 00000000..7fad24f3 --- /dev/null +++ b/.agents/skills/upstream-rotation/SKILL.md @@ -0,0 +1,158 @@ +--- +name: upstream-rotation +description: >- + jixoai/openspecui 仓库专属：跟进 OpenSpec CLI 上游升级并完成全链路交付的工作流 + （1.13.2 与 1.14.2 两轮实战沉淀）。当用户说"上游有更新/新版本发布了，跟进一下"、 + "openspec X.Y.Z 释放了，更新本地引用"、"适配新版本"、"继续跟进上游升级"，或发现 + references/openspec submodule / 固定 fixture 落后于上游 tag 时使用。覆盖：调查分级 → + worktree → 证据报告 → openspec change → 双通道 remix 复核 → 子代理切片实现 → + vision 走查 → 门禁 → PR → 归档 → 发布验证 → 资源回收。即使用户只说"看看有没有更新"， + 检测到新版本后也走本流程。 +--- + +# Upstream Rotation（上游升级跟进工作流） + +把一次上游升级跟进变成可复现的流水线。每个阶段有**门**（gate）：门不过不进下一阶段。 +本 skill 是编排层——具体操作细节按阶段读对应的 reference 文件。 + +```text +P0 检测分级 ──gate: 变更类型判定──▶ P1 环境准备 ──gate: 规划基线提交──▶ P2 证据报告 + │ +P6 交付发布 ◀──gate: 资源回收审计── P5 门禁与PR ◀──gate: 复核批准── P3 change + 双通道复核 + │ + ▼ + P4 切片实现 + vision 走查 +``` + +## 开始前必须知道的三件事 + +1. **每个阶段都有实战教训换来的铁律**（为什么会有这条规则都写在规则旁边）。跳过铁律的 + 代价在本仓库历史上真实发生过：版本字面量漏网、CI 抖动误判、PR 假合并、发布证据不足。 +2. **子代理一律后台运行**（`run_in_background: true`），编排者保持并行响应能力；等待一律用 + 事件回调（task-notification），不轮询。 +3. **写报告/文档时基于真实命令输出**，不凭记忆。凡是你声明"已验证"的事实，必须真的跑过命令。 + +--- + +## P0 — 检测与分级 + +触发：用户问"上游有没有更新"或明确给出新版本。 + +1. 在 pinned submodule 里 `git fetch --tags`，对比当前 pin 与最新 tag。 +2. 先回答一个背景问题：**这条线是否已经被别的会话跟进了**（看 `git log origin/main` 近期 + merge、`openspec/changes/archive/` 最新归档、npm latest 版本）。本地 main 可能是旧的， + 先 `git fetch origin main --tags`。 +3. 计算增量：`git log --oneline ..`、`git diff --stat .. -- src/`。 +4. **分级判定**（决定后续工作量）： + - `src/index.ts`（命令面）与 `docs/agent-contract.md`（契约面）**零变化** → 窗口内 + 补丁轮换（小，通常 1-2 切片） + - 有新命令/flag/契约 → 新的大版本适配线（大，走完整规格调查，参考仓库既有 major 线先例） +5. 对照本地镜像面做影响初判（哪些我们镜像/投影的上游表面变了）。 + +详细清单与命令：读 `references/investigation.md`。 + +**Gate P0**：能一句话说清"这是什么类型的变更、预计几个切片、哪些本地表面受影响"。 + +## P1 — 环境准备 + +1. `git worktree add ../-worktrees/update- -b target/-patch origin/main` + （基于远端 main，不是本地 main——本地可能是旧的）。 +2. submodule checkout 到新 tag，确认 `git submodule status` 无 `+` 前缀。 +3. 后台跑依赖安装（后续切片的串行屏障）。 + +**Gate P1**：worktree 干净、pin 记录在 gitlink、依赖装完。 + +## P2 — 证据报告 + +写 `references/--report.md`（仓库既有格式）： + +- Decision（窗口/fixture 轮换声明）+ Evidence baseline（tag/commit/diff 统计——**数字用 + `git rev-list --count` 实算**，不许抄估） +- 按"P1 必须适配 / P2 必须适配 / P3 parity / P4 fixture 证据 / P5 无表面 / P6 非义务"分级， + 每条给 upstream commit 佐证 +- **Owner map**：每个变更对应本地生产 owner 文件（这是后续复核的核对表） +- Release gate + +**Gate P2**：报告里每个"确认/不受影响"论断都有 diff 或源码出处。 + +## P3 — openspec change + 双通道复核（remix） + +1. 写 change 工件：`openspec/changes/update-/`（`.openspec.yaml` + `loop/{intake, + research-plan,checkpoints,implementation}.md` + `specs/*/spec.md` deltas（补丁轮换可能 + 零 delta，则省略 specs 目录））。提交规划基线。 +2. **双通道 Round-A 并行**： + - **Codex 通道**（herdr + 大地三档模型 + xhigh）：先探测 Codex 执行环境——新 Provider 的 + 沙箱可能没有本地文件系统甚至没有 shell（NO-SHELL）。不可用时切换**内联材料复核模式** + （协议见 `references/review-remix.md`）。 + - **research 子代理通道**：同一复核简报，独立执行。 + - 两路发现**收敛**是最强置信信号；分歧点单独裁决。 +3. 折叠全部发现 → Round-B 批准轮（同通道）→ 记录评分。 +4. 复核回调一律用后台 `~/.zcode/scripts/codex-callback.sh `（若无执行位先 chmod +x）。 + +复核提示词模板、内联材料协议、评分要求：读 `references/review-remix.md`。 + +**Gate P3**：Round-B 明确批准（评分与理由记录进 checkpoints），才允许动生产代码。 + +## P4 — 切片实现 + vision 走查 + +1. 按 research-plan 切片分发子代理（简报模板与纪律见 `references/implementation.md`）： + - **pin 轮换切片串行先行**（install 屏障），其余切片文件集互斥可并行，fixture 收尾串行。 + - 每个切片：先红后绿（红例在命名的固定点）、聚焦绿门命令、报告含摩擦点反馈。 +2. 编排者对每个子代理报告**交叉核验 diff**（不全信自评），逐切片提交。 +3. **vision 走查**（ego-browser）：冒烟或全量按变更规模定。配方、黑图防线、console 卫生、 + 进程回收纪律见 `references/implementation.md` 的走查节。 +4. Round-C 实现复核（同 P3 通道）+ 折叠。 + +**Gate P4**：全部切片绿 + 走查 PASS + Round-C 批准。 + +## P5 — 门禁与 PR + +1. 全量门禁串行：`format:check` → `lint:ci` → `typecheck` → `test:ci` → `test:browser:ci`。 +2. PR 描述要点：变更摘要、复核轨迹（评分）、走查结论、**lockfile churn 解释**（若 pin + 触发布局压缩）、时序敏感面处置规则。 +3. CI 监视合并，**合并后必须 `gh pr view --json state,mergedAt` 验证**——门禁 pending 时 + `gh pr merge` 会被拒但脚本可能假报成功（实战踩过）。 +4. **CI 抖动处置铁律**：先本地复跑定位 → 触发失败作业**零变更重跑** → 通过则定性为时序面 + 并记录，**不许直接加 timeout**（资源拓扑优先于膨胀超时是仓库法则）。 +5. 归档：rebase main → pinned CLI `archive -y` → 归档 PR → 合并验证。 + +**Gate P5**：实现 PR + 归档 PR 均 mergedAt 验证通过。 + +## P6 — 发布与回收 + +1. **发布需 Owner 明确确认**（"继续跟进"不等于"发布"）。 +2. `pnpm changeversion`（在主检出 main 上跑；worktree 不能持有 main）。changeversion 自带 + 版本 PR → 检查 → 合并 → release 等待；**它可能误报 workflow failed**（轮询过早），以 + run 实际 conclusion 为准。 +3. **四项独立证据逐项验证**（缺一不可，npm 是逐包传播的要轮询到齐）： + main head（版本 PR merge）/ 远程标签 / GitHub Release / **npm 每个包**。 +4. 发布后验证 submodule gitlink 未被版本提交倒退（历史事故，已有根修但仍要验）。 +5. 资源回收 + 残留审计：worktree、本地/远程分支、herdr（只关自己建的 workspace；server + 若已被他人附着则**不停**）、/tmp、端口、孤儿进程。最后跑一遍审计命令清单并向 Owner + 交代：残留物、被挡的回写、并行会话的进程归属。 + +**Gate P6**：四项证据在案 + 审计清单向 Owner 交代完毕。 + +--- + +## 铁律速查（每条后面是它的学费） + +| 铁律 | 学费 | +|---|---| +| 版本字面量审计用**全仓机械 grep**（旧版号+旧SHA+新版号+新SHA+alias 名+常量名），不只 grep 上一版 | W2 脚本 `1.12.0` 漏网（规划与 Round-A/B 均未抓，Round-C 才捕获） | +| 文件名前缀会逃逸 glob（`v13-*` 不匹配 `v14-*`），聚焦命令用**子串 filter** | vitest 引号 glob 静默丢文件假绿 | +| 聚焦测试一律 `pnpm --filter exec vitest run ` | `test --` 传参被吞跑全量 876s | +| PR 合并必须验证 `mergedAt` | pending 时 merge 被拒但脚本报成功 | +| CI 时序失败先零变更重跑定性 | 把抖动当代码缺陷排查浪费整轮 | +| npm 完成判据**逐包**解析验证 | workflow success ≠ 全包可解析 | +| 发布后验证 submodule gitlink | changeversion 曾把 pin 倒退一版 | +| 走查配方 PATH 前置 pinned CLI bin | 系统 openspec 1.4.1 弹版本冲突对话框 | +| Codex 新 Provider 先探测执行环境 | 无 FS/shell 的复核只能靠内联材料模式 | +| 声称"已验证"的事必须真跑过命令 | 报告数字抄错（24≠21）被复核当场抓 | + +## 何时读哪个 reference + +- P0/P2 细节 → `references/investigation.md` +- P3 复核协议与提示词模板 → `references/review-remix.md` +- P4 切片简报模板、绿门、走查配方 → `references/implementation.md` +- P5/P6 PR/发布/回收清单 → `references/delivery.md` diff --git a/.agents/skills/upstream-rotation/references/delivery.md b/.agents/skills/upstream-rotation/references/delivery.md new file mode 100644 index 00000000..6b23a852 --- /dev/null +++ b/.agents/skills/upstream-rotation/references/delivery.md @@ -0,0 +1,96 @@ +# P5/P6 — 门禁、PR、发布与回收 + +## 全量门禁（串行） + +```bash +pnpm format:check # 只查变更文件 +pnpm lint:ci # 0 errors 才算过（warnings 是基线） +pnpm typecheck # 全部 lane（core 的测试 lane 会抓 vitest 转译层放过的类型问题——类型测试证据法则） +pnpm test:ci # 全量单测 +pnpm test:browser:ci # 需要 playwright chromium（缺二进制时 pnpm exec playwright install chromium） +``` + +门禁期抓到的既有环境敏感 flake：`reactive-fs/path-realpath.test.ts` 在 TMPDIR 未 realpath +归一的 macOS 主机上红（main 也红）——期望锚定 `realpath(targetRoot)` 修复，属合法修。 + +## PR + +描述必备段落：Summary（窗口/pin/分级）、What changed、Review trail（各轮评分）、走查结论、 +Notes（**lockfile churn 解释**——pin 触发的 pnpm 布局压缩，键集合一致仅 alias 变； +时序敏感面处置规则——若 CI 该测试抖动先零变更重跑定性）。 + +## CI 监视合并（防假合并） + +```bash +gh pr checks --watch +gh pr merge --merge +gh pr view --json state,mergedAt # 必须！mergedAt 非空才算合并成功 +``` + +门禁 pending 时 `gh pr merge` 被拒但脚本可能假报成功；新推送触发新 CI 轮时尤其注意。 + +## CI 抖动处置（铁律） + +1. 定位失败测试与失败点（`gh run view --log`，注意日志里 run: 块的源码回显会被误读成执行输出） +2. 本地复跑同文件 → 绿则高度怀疑时序 +3. `gh run rerun --failed` **零变更重跑** → 通过 = 定性时序面，记录进 change log，不加 timeout +4. 复现才深入排查（对照上游 perf/lazy-load 类提交） + +## 归档（第二个 PR） + +```bash +git fetch origin main && git checkout -b docs/archive- origin/main +# 前置：P1 的 install 已在当前检出完成；否则用 submodule 源 bin（W2 脚本同款） +# node references/openspec/bin/openspec.js archive -y +node packages/core/node_modules/openspec-cli-114/bin/openspec.js archive -y +git add openspec/changes openspec/specs && git commit && git push && gh pr create ... +# 归档时 "N incomplete tasks" 警告是预期（描述交付动作本身的条目在归档时才完成） +``` + +## 发布（P6） + +1. **Owner 明确确认后才发布**（"继续跟进"≠"可以发布"）。 +2. 主检出 main 上 `git pull --ff-only` → `pnpm changeversion`（worktree 不能持有 main）。 + 脚本端到端：版本 PR → 检查 → 合并 → release 等待；**它可能误报 "Release workflow + failed"**（轮询过早）——以 `gh run view --json conclusion` 实际状态为准。 +3. **四项独立证据逐项验证**： + +```bash +git log --oneline origin/main -2 # 1. 版本 PR merge head +git fetch --tags origin && git tag --sort=-v:refname | head # 2. 远程标签 +gh release list --limit 2 # 3. GitHub Release (Latest) +for p in <主包> <子包们>; do npm view $p version; done # 4. npm 逐包轮询到齐 +git ls-tree origin/main references/openspec # 5. gitlink 未被版本提交倒退 +``` + +npm 是**逐包传播**的（先 server 后 core/web，分钟级），轮询直到全部到齐；发布日志里的 +`+ @` 与 provenance 签名是"已接受"的证据，registry 可解析是"已可用"的证据。 + +## 资源回收 + 残留审计 + +```bash +git worktree remove --force && git worktree list +git branch -D <本地功能分支>... +git push origin --delete <远程功能分支>... # changeversion 自动分支按仓库惯例保留 +rm -rf /tmp/ /tmp/*-prompt.txt /tmp/pr*-checks.log /tmp/gate-*.log +for port in <用过端口>; do lsof -ti $port | wc -l; done # 全 0 +pgrep -fl "<关键进程>" | grep -v grep # 区分自己起的 vs 并行会话的 +herdr agent send-keys ctrl+c && herdr workspace close +herdr workspace list # 只剩别人的 → server 留着不停 +``` + +向 Owner 交代的残留清单：不可停的共享资源（herdr server 及附着者）、被沙箱挡住的回写 +（skill 摩擦点记录在哪个归档 change 里）、并行会话进程归属、按惯例保留的 changeversion +分支、自己改过的工具文件（如 chmod）。 + +## 发布期事故记录义务 + +发布期的三类事故（PR 假合并、npm 逐包传播迟滞、changeversion 误报 workflow failed）目前 +只在会话记忆里——**下次轮换发生任何发布期事故时，把它记入归档 change 的 implementation +log**，让铁律速查表逐步做到 10/10 可溯源。 + +## 视觉验收豁免判据 + +零生产代码改动的轮换可豁免 Owner 视觉验收——依据：diff 仅 pin 常量/测试/文档/changeset +（`git diff .. --stat` 可证）+ vision 走查已程序化验证 UI 原样投影 + 回归烟测 +PASS。有生产 UI 改动则必须留 Owner 走查（2026-07-20 边界法则）。 diff --git a/.agents/skills/upstream-rotation/references/implementation.md b/.agents/skills/upstream-rotation/references/implementation.md new file mode 100644 index 00000000..06de21eb --- /dev/null +++ b/.agents/skills/upstream-rotation/references/implementation.md @@ -0,0 +1,101 @@ +# P4 — 切片实现与 vision 走查 + +## 切片拓扑 + +```text +Slice 1 pin 轮换（串行先行——install 屏障，独占 pnpm install） + └─▶ Slice 2..N 功能切片（文件集互斥，可并行子代理） + └─▶ Slice N+1 fixture 矩阵 + docs + changeset（串行收尾，依赖前面全部绿） +``` + +切片划分原则：一个切片 = 一个可独立验收的义务 = 一份互斥文件集。两个切片碰同一文件就 +合并成一个批次（曾因 Slice 2/4 争抢 `opsx-types.ts` 被复核判 P1）。 + +## 子代理简报模板（每个切片一份，自包含） + +``` +角色 + 工作目录 + 基线（HEAD 哈希 + 工作树干净，不符立即停止） +规划文档指针（research-plan 对应切片 + specs delta） +任务步骤（严格按序；含"先红后绿"固定点） +红例纪律：改生产代码前先写新测试跑红，记录失败输出关键行 +绿门命令（见下） +纪律：不 commit 不 git add；变更留工作树；prettier 只对显式文件； + 每个被改的 TS/TSX 文件（含测试）保留/更新顶部时间戳意图头（仓库 Delivery Workflow 法则）； + 聚焦测试 exec 直通；常驻进程列 pid+回收证据 +报告格式：基线验证/红例/变更清单/绿门结果/差异说明/摩擦点反馈/进程回收 +``` + +子代理一律 `run_in_background: true`。报告回来后编排者**交叉核验 diff**（`git status +--porcelain` 对照报告清单、抽查关键改动），不全信自评——再逐切片提交（显式路径 add，不 -A）。 + +## 绿门命令（vitest v4 陷阱） + +```bash +# 正确：exec 直通 + 子串 filter（引号 glob 会被 vitest 静默丢弃成 0 文件假绿！） +pnpm --filter @openspecui/core exec vitest run official-cli-v14-validation-findings +# 错误：pnpm --filter test -- （-- 后参数被吞，跑全量） +# 错误：vitest run 'src/official-cli-v1*.test.ts'（引号 glob 静默丢文件） + +# server 包真实门禁是 typecheck 脚本（裸 tsc --noEmit 是既有误用） +pnpm --filter @openspecui/server typecheck +``` + +先读目标包 package.json 的 scripts 确认跑器（vitest ≠ node:test），基线数字以当日实跑为准。 + +## pin 轮换切片专项 + +**全仓机械审计**（不只上一版号）： + +```bash +grep -rn "1\.14\.1\|87c3595\|openspec-cli-114" packages scripts CLAUDE.md AGENTS.md \ + --include="*.ts" --include="*.tsx" --include="*.mjs" --include="*.md" --include="*.json" \ + | grep -v node_modules | grep -v CHANGELOG | grep -v "\.changeset/" \ + | grep -v "openspec/changes/archive" | grep -v "references/openspec-1" +``` + +逐命中分类：**活 pin 面**（轮换）/ 文件头 Original request 溯源（保留）/ 行为归因注释 +（保留）/ 窗口内样本字面量（保留——测试逻辑数据）/ 无关依赖（保留）。收尾复验：活旧引用归零。 + +已知的活面清单（每轮逐个核对，并 grep 找新增）： +package.json alias / fixture 常量+bins 键 / **v13-前缀的 boundary fixture（逃逸 v14 glob）** / +**schemas-root 本地 PINNED_BINS（stale key 会 undefined 传参崩溃）** / upstream-contract-regression +commit 断言 / 冷启动常量+version 断言 / w2 脚本 SHA+version 断言 / prepare 脚本 EXPECTED_COMMIT / +CLAUDE.md 指针 / AGENTS.md pin 行 + clean-build 法则内嵌 SHA + 新架构决策段； +**README 对法则**：凡触碰根 README.md 的发布必须同 PR 更新 packages/cli/README.md（轮换时 +至少跑 "README audit clean" 并记录结论）。 + +**红例**：alias 先改 → 单次 install → 常量未改时跑任一 identity 载体（helper 非 test 文件， +vitest 不认，用导入它的 boundary/test 文件）→ 记录 expected old / received new。 + +fixture 矩阵纪律：只允许对齐新事实，**绝不放松断言强度**；新用例先真实 CLI 取证再写断言 +（mkdtemp 临时项目跑一次，把 stdout 记下来；macOS 是 `mktemp -d` 无 mkdtemp 命令）。 + +## vision 走查（ego-browser） + +规模合宜原则：零生产改动 → 冒烟级（服务起 + 关键页 + console 卫生 + 一个相关功能面）； +有生产 UI 改动 → 全场景。 + +走查配方（每项都踩过坑）： + +```bash +# 构建 + 隔离环境 + PATH 前置 pinned bin（否则系统旧版 CLI 弹版本冲突对话框） +pnpm --filter @openspecui/web run build:dist +PATH="$PWD/packages/core/node_modules/.bin:$PATH" \ +XDG_DATA_HOME=/home/data XDG_CONFIG_HOME=/home/config HOME=/home \ +pnpm --filter openspecui exec tsx --conditions=development src/cli.ts --web --port

+# 就绪探测：curl /api/health 返回 JSON 对象（不是裸 ok，别按字面匹配） +``` + +vision 子代理简报必带： +- 读 ego-browser SKILL.md + 本次 specs delta +- 预检：终端先用 pinned CLI 跑出期望 payload，再开始浏览器验证 +- **console 卫生**：CDP `Page.addScriptToEvaluateOnNewDocument` 注入 hook（window error + + unhandledrejection + console.error 包装），**先注入自测 error 验证 hook 生效**（防假阴性）； + hook 不跨 `page.goto`，每页入口重注入 +- **黑图防线**：每张截图程序化校验（尺寸/唯一色数/非黑像素比）后再判读；几何争议以 + a11y snapshot + computed CSS 优先；选择器优先语义（`role:button[name=...]`），`ref=` 易 stale +- 清理：记录 pid → kill → `lsof -ti ` 验证释放；保留 scratch 供复查 + +## Round-C 之后 + +折叠发现 → 若有修复 → 聚焦复绿 → 记录进 implementation log → 进 P5。 diff --git a/.agents/skills/upstream-rotation/references/investigation.md b/.agents/skills/upstream-rotation/references/investigation.md new file mode 100644 index 00000000..cdd0d09c --- /dev/null +++ b/.agents/skills/upstream-rotation/references/investigation.md @@ -0,0 +1,63 @@ +# P0/P2 — 检测分级与证据报告 + +## 检测命令序列 + +```bash +# 1. 上游有没有新版本（在 pinned submodule 里） +git -C references/openspec fetch --tags +git -C references/openspec describe --tags HEAD # 当前 pin +git -C references/openspec tag --sort=-v:refname | head -6 + +# 2. 本仓库是否已被别的会话跟进过（本地 main 可能是旧的） +git fetch origin main --tags +git log --oneline origin/main -8 # 看近期 release/archive merge +ls openspec/changes/archive/ | tail -3 # 最新归档的 change +npm view openspecui version # 已发布的版本 + +# 3. 增量统计（数字进报告必须实算） +git -C references/openspec rev-list --count .. +git -C references/openspec diff --stat .. -- src/ +git -C references/openspec log --format="%h %s" .. +``` + +## 分级判定的关键 diff 面 + +```bash +# 命令面与契约面零变化 → 窗口内补丁轮换（小） +git -C references/openspec diff .. -- src/index.ts docs/agent-contract.md +``` + +有变化 → 新 major 线：不要套本 skill 的小流程，先读仓库既有 major 线先例 +（`openspec/changes/archive/` 里 `target-openspec-cli-*-line` 类 change），规划完整规格调查。 + +## 本地镜像面影响初判（openspecui 实例） + +逐项对照"上游变了什么 vs 我们镜像/投影什么"： + +| 上游表面 | 我们的镜像 | 检查点 | +|---|---|---| +| `src/core/artifact-graph/outputs.ts` 识别函数 | `packages/core/src/opsx-types.ts` 的 `isGlobPattern` + web viewer 本地副本 | 函数体是否逐字节未变（提取双版本 diff）；上游新增的守卫在哪一层（展开侧 vs 识别侧） | +| `instructions apply --json` / `status --json` 成员 | `packages/core/src/cli-contracts/workflow.ts` 各 schema | 新成员 optional/absent-when-empty 语义；窗口内旧版本是否还发射 | +| `list --json` 成员 | 同上 + change-list 投影链 | 同上 | +| 消息文本变化 | verbatim 字符串投影的 decode/render | 我们是否消息无关（通常是）；fixture 断言是否硬编码旧文本 | +| Agent 交付矩阵 | `packages/core/src/agent-delivery-registry.ts` | 路径/skillsDir/cleanup 变化；`legacyPathTemplates` 机制 | +| 验证/归档行为 | 我们不镜像（CLI-delegated） | fixture 证据层面 | + +**初判结论必须写成可证伪的话**："零生产改动"这类 triage 要标注"待 fixture 矩阵实证"—— +1.14.2 轮的 triage 是被 55 个 fixture 测试零断言变化证实的，不是被推定的。 + +## 证据报告格式（references/--report.md） + +照抄仓库最新一份报告的结构（用 **mtime** 找样板：`ls -t references/*.md | head -1`——字典序 +`tail -1` 会返回 `openspec-1.9.0-report.md`，"1.14" 逐字符排在 "1.7"/"1.9" 之前，静默指向旧模板）： + +1. 头部：orthogonal intents 注释 + 原始需求原文（含日期） +2. `## Decision`：窗口声明代码块 + "是否移动窗口/能力/注册表 series"的一句话结论 +3. `## Evidence baseline`：Observed/Package/Pinned tag/Pinned commit/Previous pin/Upstream delta（实算） +4. `## Patch delta by contract relevance`：P1-P6 分级，每条含 upstream commit 短哈希、 + verbatim 契约文本（JSON 形状直接贴）、"OpenSpecUI red today" 段（我们当前为什么缺/错） +5. `## Current owner map`：表格 Surface → Primary production owner → obligation +6. `## Release gate` + +报告写作纪律：每个论断给 `文件:行` 或 commit 出处；不确定的写"待实证"；数字全部命令实算 +（曾把 21 写成 24 被双通道复核当场抓出）。 diff --git a/.agents/skills/upstream-rotation/references/review-remix.md b/.agents/skills/upstream-rotation/references/review-remix.md new file mode 100644 index 00000000..1203a4a3 --- /dev/null +++ b/.agents/skills/upstream-rotation/references/review-remix.md @@ -0,0 +1,87 @@ +# P3 — 双通道复核（remix）协议 + +## 通道一：Codex（herdr） + +### 启动序列 + +```bash +# 0. 负载与网关检查 +pgrep -fl "codex|cargo" | head -5 +sysctl vm.swapusage + +# 1. herdr server 不在跑就无头启动（注意：之后若他人附着，结束时不要停 server） +nohup herdr server >/tmp/herdr-server.log 2>&1 & + +# 2. workspace + pane（--cwd 指 worktree；命名 zcode--） +herdr workspace create --label "zcode---review" --cwd --no-focus + +# 3. 启动 reviewer（模型按三档抽象取"大地三"；注意模型名以用户当前配置为准—— +# 曾经历 gpt-5.6-terra → gpt-6-sol → gpt-6.1-sol 的迁移，启动前看 ~/.codex/config.toml） +herdr agent start codex-reviewer- --kind codex --pane -- \ + -m <当前大地模型> -c 'model_reasoning_effort="xhigh"' --yolo + +# 4. 提交复核请求（前台不加 --wait）+ 后台回调 +herdr agent prompt codex-reviewer- "$(cat /tmp/round-prompt.txt)" +# 后台任务跑： +~/.zcode/scripts/codex-callback.sh codex-reviewer- # 无执行位先 chmod +x +``` + +### 先探测执行环境（新 Provider 必做） + +新 Provider 的沙箱可能：命令在远端 Linux 容器执行（`/home/oai`，无本地文件系统）； +甚至完全没有 shell 工具（NO-SHELL，重启不复现）。先发一个探测： + +``` +探测：运行 whoami && echo SHELL-OK 贴输出；无命令执行工具则回复 NO-SHELL。 +``` + +- 有本地执行 → 传统模式：直接让它读 worktree 复核。 +- 远端执行无本地 FS → 让它在沙箱 `git clone --recurse-submodules -b ` 公开仓库复核 + （需先推分支）。 +- NO-SHELL → **内联材料模式**（见下）。 + +### 内联材料复核模式（实测有效，三轮验证） + +把复核材料打成 ~250 行的包喂给 Codex，让它基于材料做批判性评审： + +``` +材料 1：证据报告全文 +材料 2：change 工件全文（intake / research-plan / checkpoints） +材料 3：全仓 pin 字面量机械审计表（编排者本地 grep，命中分类：活面/历史注释/mock/无关依赖） +材料 4：上游关键 diff 摘录（编排者本地 git diff 验证） +材料 5：对向通道（research）的结论——供交叉批判/反驳 +输出要求：阻塞问题（P0/P1 + 定位 + 可验证修复）/ 非阻塞 / 事实核验逐项 / 评分 0-10 + 依据 +``` + +包首必须声明证据边界：「以下材料由编排者从真实 worktree 逐字提取并本地验证；你未执行任何 +命令，标注'已验证'的部分作为可信输入」。Codex 会诚实声明边界——这正是该模式可用信任的原因。 + +### 复核输出要求（每轮固定） + +- 阻塞问题 P0/P1：文件:行号证据 + 可验证修复建议 +- 非阻塞 P2/P3 +- 事实核验逐项：确认/纠正 +- 评分 0-10 + 依据（与上一轮的变化说明） +- Round-C 允许要求破坏性抽查（临时改坏实现看测试红 → 还原 → 复绿） + +## 通道二：research 子代理（并行） + +同一复核简报，`research` 类型子代理后台跑。它的优势是真实文件系统访问。 +两通道发现**收敛**（独立发现同一批问题）= 最强置信；分歧点由编排者实跑命令裁决。 + +## 轮次协议 + +- **Round-A**（change 文档复核，实现未开始）：折叠全部发现 → 修订 change 文档提交。 +- **Round-B**（批准轮）：给修订材料 + 逐项处置对照表 → 明确批准才解冻实现。 +- **Round-C**（实现复核）：实现 diff 摘要 + 测试证据材料包 → 批准进入门禁与 PR。 + +每轮评分与结论记录进 change 的 checkpoints / implementation log。复核回来必须实际处理： +「复核已运行」不是完成，P1 修复后要有再验证。 + +## 会话回收 + +```bash +herdr agent send-keys ctrl+c # codex TUI 退出（agent_not_found 即释放） +herdr workspace close # 只关自己建的 +# server：若还有别人的 workspace（herdr workspace list 看 label），留着不停 +```