@weotro/dx 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/ship-issue-pr/SKILL.md

@@ -37,20 +37,56 @@ description: 仅在用户显式调用 $ship-issue-pr 或明确要求使用 ship-
 | Issue/PR 形状 | 必须产出“标准样本”级正文；空 PR body、泛泛模板、占位文字一律阻塞 |
 | PR body | 必须使用本技能内置 PR 模板，不得只写“已通过本地测试” |
 | 评论发布 | 审查、验收、修复、验证总结由主流程统一发布 |
-| 独立审查 | 每轮代码审查和每个重大决策必须完成第三方对抗审查；无法完成时阻塞，不能静默跳过 |
+| 独立审查 | 仅命中 `$third-party-review` 风险门槛时调用；同一 PR 的第三方代码审查最多一次 |
 | 合并 | 只能 `gh pr merge --squash --auto`，禁止 `--admin` 和无 `--auto` 合并 |
 | 真完成 | 必须轮询到 `mergedAt` 非空，并回访关联 Issue 状态 |
 
 ## 第三方对抗审查
 
-进入以下任一分支前，完整读取并执行 [third-party-review.md](references/third-party-review.md)：
+本技能负责判断是否调用、记录理由和控制预算；`$third-party-review` 只负责执行已经批准的审查。
 
-- **代码审查：**主流程先独立完成初审，再调用第三方审查同一 diff，核验并合并双方 findings 后才能发布报告或开始修复。
-- **重大决策：**主流程先形成有证据的初步决策，再调用第三方专门反驳，最后记录采纳/拒绝理由并作出最终决策。
+### 重大决策门槛
 
-重大决策包括架构、API、数据、安全、兼容性、用户可见行为、范围边界、冲突语义，以及 `修复 / 拒绝 / follow-up` 等会改变交付结果的取舍。规则已经唯一确定的机械动作不属于重大决策。
+仅当至少命中一项时调用 `mode=decision-review`：
 
-第三方只能提供审查意见，不得代替主流程修改文件、提交、发布评论或合并。主流程对事实核验和最终结论负责。
+1. 变更跨越两个以上需要协调契约或发布的独立模块、服务或 package。
+2. 变更跨端，例如 backend 与 web/admin/mobile 之间的 API、状态、鉴权或数据契约改变。
+3. 引入、替换或重大升级框架、运行时、数据库/ORM、鉴权、消息系统、构建链或部署基础设施，并需要迁移或大面积适配。
+4. 改变公共 API、持久化 schema、协议、权限/安全边界或向后兼容策略，需要迁移、灰度或回滚方案。
+5. 决策具有明显不可逆性或生产爆炸半径，例如数据迁移、破坏性操作或核心基础设施切换。
+
+沿用既有模式的局部实现、单模块内部重构、命名、文件组织、Git 文案、验证命令选择，以及规则已有唯一答案的流程动作，不属于重大决策。
+
+命中时先形成初步决策，把同一问题的相关取舍合并成一次调用，再明确调用 `$third-party-review`，并把当前已有的初步决策、命中项、证据和相关材料放入调用上下文。未命中时由主流程直接决策，不调用第三方。
+
+若独立技能需要补充信息，它可以直接反问。反问、用户补充和恢复执行都属于这一次调用；不要再次调用 `$third-party-review`。
+
+### 代码审查门槛
+
+以下任一情况直接跳过第三方：
+
+- 仅修改文档、注释、拼写、格式、静态文案、测试快照或无运行时影响的元数据。
+- 局部代码修改同时满足：不超过 2 个实现文件、不超过 50 行有效可执行改动、只在一个既有模块内、没有改变公共契约/数据/安全/依赖/构建部署/并发语义，且相关验证通过。
+
+只有命中至少一项风险信号时才调用 `mode=code-review`：
+
+- 改变公共 API、schema、权限、安全、持久化数据或迁移逻辑；
+- 改变并发、缓存、事务、重试、幂等、状态机或关键错误恢复；
+- 改变框架、核心依赖、运行时、构建、发布或部署行为；
+- 跨两个以上独立模块、服务、package 或客户端，并存在契约/回归风险；
+- 主流程初审发现尚未确认的 Critical/Major 风险，需要独立证据判断。
+
+未命中风险信号时直接跳过，不要因为“保险起见”调用。
+
+### PR 审查预算
+
+- 同一 PR 的第三方代码审查最多一次，覆盖整个 PR 生命周期。
+- 调用前检查 PR body 和评论是否已有 `<!-- third-party-code-review:used -->`；存在即跳过。
+- 命中门槛且预算未用时，先发布预算标记评论，记录 `reviewer=pending` 和当前 head SHA；标记成功后再明确调用 `$third-party-review`，把 PR、diff、命中风险和验证结果放入当前上下文。实际 reviewer 由独立技能选择并写入最终审查报告。
+- 标记写入即消耗预算；调用成功、失败或超时都不得再次调用。
+- 独立技能反问和等待补充仍属于已经标记的这一次调用；回答后继续原调用，禁止重新触发技能。
+- 初次未命中门槛不消耗预算；后续 diff 扩大并首次命中风险门槛时仍可调用一次。
+- 第三方返回后由主流程核验结论；调用失败或超时不重试、不改派第二个 reviewer。
 
 ## 快速流程
 
@@ -62,7 +98,7 @@ description: 仅在用户显式调用 $ship-issue-pr 或明确要求使用 ship-
 | Commit | Conventional Commit，正文末尾 `Refs: #<issue-id>` |
 | 验证 | `dx lint`、目标构建、相关测试，记录关键输出 |
 | PR | 标题 Conventional Commit，正文含本仓模板，`Closes: #<issue-id>` |
-| 审查修复 | Issue 验收、验证流水线、主流程初审、第三方对抗审查、逐项修复并提交 |
+| 审查修复 | Issue 验收、验证流水线、主流程审查、条件式第三方审查（每 PR 最多一次）、逐项修复 |
 | 合并 | 设置 auto-merge，等待真实 merged |
 | 回访 | 确认 Issue 自动关闭；未完成则重开或拆 follow-up |
 
@@ -426,12 +462,14 @@ MSG
 
 ### 7.3 代码审查
 
-本节是强制第三方审查门禁。每一轮都按以下顺序执行：
+每轮都由主流程审查。第三方审查是条件式补充，不是每轮固定步骤：
 
-1. 主流程在不查看第三方结论的情况下完成初审，形成候选 findings，但暂不发布 PR 评论。
-2. 按 [third-party-review.md](references/third-party-review.md) 的宿主路由调用独立 reviewer；提供 Issue、PR body、base/head、完整 diff、相关文件和验证结果，要求只读审查。
-3. 主流程逐条核验双方 findings：合并重复项，删除无证据项，补充遗漏项；接受或拒绝第三方意见都要写明依据。
-4. 只有对账完成后，才能发布本轮代码审查报告并进入修复。
+1. 主流程完成本轮审查和验证。
+2. 第一次准备发布正式代码审查报告前，由本技能依据上面的代码审查门槛判断当前完整 PR diff。
+3. 未命中门槛：记录简短跳过理由，不调用 `$third-party-review`；若后续 diff 扩大，可重新判断。
+4. 命中门槛：先检查并锁定 PR 一次性预算，再调用 `$third-party-review` 执行审查。
+5. `$third-party-review` 返回 `REVIEWED` 或 `UNAVAILABLE` 后，该 PR 后续轮次禁止再次调用第三方，只由主流程复审修复内容。
+6. 第三方有结果时，主流程逐条核验、合并重复项并记录拒绝依据，再发布报告。
 
 审查范围：
 
@@ -487,7 +525,7 @@ gh pr comment <PR_NUMBER> --body-file - <<'MSG'
 ### 处理决策
 
 - 每条问题标记：修复 / 拒绝 / follow-up
-- 拒绝必须写具体理由；重大取舍必须记录第三方反驳与最终依据
+- 拒绝必须写具体理由；命中重大决策门槛时使用 `$third-party-review` 后再给最终依据
 MSG
 ```
 
@@ -676,9 +714,12 @@ Ship Issue PR 阻塞
 | E2E 无参全量运行 | 指定文件或目录 |
 | 验证失败说“历史遗留不管” | 修复或登记 follow-up Issue |
 | 多个审查修复攒一个 commit | 每个问题一个 commit |
-| 主流程独自完成代码审查 | 先完成初审，再按宿主路由调用第三方并对账 findings |
-| 先问第三方再形成自己的判断 | 先写初步决策或初审结果，防止主流程被第三方结论锚定 |
-| 第三方调用失败就跳过 | 按路由降级到 subagent；仍不可用则阻塞 |
+| 把是否调用交给 `$third-party-review` 判断 | 本技能先按门槛决定；独立技能只执行已批准审查 |
+| 简单修改也调用第三方 | 使用本技能的代码审查门槛；未命中风险信号直接跳过 |
+| 同一 PR 每轮都调用第三方 | 整个 PR 最多派发一次，后续由主流程复审 |
+| 第三方反问后重新调用技能 | 回答缺失信息并恢复原调用；反问链始终只算一次 |
+| 先问第三方再形成自己的判断 | 先写初步决策或初审结果，避免被第三方结论锚定 |
+| 第三方失败后连续改派 | 一次只派一个 reviewer；失败记录 `UNAVAILABLE`，不重试 |
 | `gh pr merge --squash` 不带 `--auto` | 只允许 `--squash --auto` |
 | 设置 auto-merge 后立即宣称完成 | 必须轮询到 `mergedAt` |
 | 合并后不看 Issue | 必须回访 Issue 状态和验收覆盖 |
@@ -691,7 +732,8 @@ Ship Issue PR 阻塞
 - “PR body 之后再补。”
 - “CI 应该会过，先合并。”
 - “历史遗留错误不是我引入的，跳过。”
-- “我已经审过了，不需要第三方再看。”
+- “这个改动很简单，也调用一次更保险。”
+- “修了一轮代码，再调用第三方复查一次。”
 - “先让第三方替我决定，我直接照做。”
 - “GitHub 已显示 mergeable，不用逐条核对验收标准。”
 - “auto-merge 已设置，所以算完成。”

package/skills/third-party-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: third-party-review
+description: ""
+---
+
+# Third-Party Review
+
+只执行已经批准的审查任务。调用门槛、简单修改判断、次数预算和业务决策均由调用方负责。
+
+仅通过以下方式启动：
+
+- 用户明确调用 `$third-party-review`；
+- 另一个已激活技能明确写出并调用 `$third-party-review`。
+
+不要根据“代码审查”“重大决策”等普通关键词自行触发。
+
+## 上下文补全
+
+不要要求调用方提供固定参数。启动后先从当前对话、调用技能、仓库状态、Issue/PR 和已有工具结果中推断：
+
+- 审查模式：代码审查或决策审查；
+- 审查对象与范围；
+- 调用理由和上游已经做出的初步判断；
+- 完成审查所需的 diff、源码、验证结果或决策材料。
+
+优先自行读取可安全获取的信息。只有关键内容无法从上下文或仓库获得时才反问；一次集中询问所有真正缺失的信息，避免逐项追问。
+
+反问与用户补充属于当前 `$third-party-review` 调用的延续，不得重新调用技能，也不得重复计算调用次数。收到补充后从暂停点继续执行。
+
+若能确定审查对象但部分辅助信息缺失，标注假设并继续。只有连审查对象或目标都无法确定时才必须反问。
+
+## Reviewer 路由
+
+派发前一次性选择 reviewer：
+
+| 当前宿主 | reviewer |
+|---|---|
+| Codex | 已暴露且可直接调用 Claude Code 时使用 Claude Code；否则派一个 fresh-context reviewer subagent |
+| Claude Code | 有匹配的 `codex:*` 技能时使用该技能；代码审查优先 `codex:review`，否则派一个 fresh-context reviewer subagent |
+| 其他宿主 | 派一个 fresh-context reviewer subagent |
+
+一次任务只派发一个 reviewer。调用失败或超时后不重试、不改派第二个 reviewer；返回 `UNAVAILABLE`。reviewer 不得递归委派。
+
+## 执行流程
+
+1. 从上下文补全审查任务；必要时集中反问并等待补充。
+2. 不重新评估调用理由是否达到上游技能的门槛。
+3. 移除 token、密码、私钥、真实环境变量与无关个人数据。
+4. 选择一个 reviewer，要求只读：不改文件、不执行 Git/GitHub 写操作、不发布评论、不提交、不推送、不合并。
+5. 传递必要原始材料和调用方的初步结论，要求 reviewer 主动寻找反例、遗漏、错误假设与回归风险。
+6. 返回 reviewer 原始结论和结构化摘要，不替调用方接受、拒绝或落实 findings。
+
+## 审查要求
+
+`code-review` 要求每条 finding 包含：严重级、稳定位置、证据、影响和最小安全修复。无 finding 时说明检查范围和剩余风险。
+
+`decision-review` 要求列出：最强反对理由、隐藏假设、替代方案、兼容性或失败风险、需要补充的证据，以及是否建议维持调用方的初步选择。
+
+## 输出契约
+
+- `REVIEWED`：reviewer、审查范围、原始结论、结构化 findings 和剩余风险。
+- `UNAVAILABLE`：已选 reviewer、失败或超时原因；明确没有重试或改派。
+
+第三方意见仅作为证据。调用方负责事实核验、采纳/拒绝理由和最终结论。

package/skills/third-party-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Third-Party Review"
+  short_description: "Execute one approved independent adversarial review"
+  default_prompt: "Use $third-party-review to execute one approved read-only adversarial review, inferring context and asking once if essential information is missing."
+policy:
+  allow_implicit_invocation: false

package/skills/ship-issue-pr/references/third-party-review.md

@@ -1,65 +0,0 @@
-# 第三方对抗审查
-
-第三方审查用于打破主流程的自证闭环。它是强制质量门禁，不是把责任转交给另一个 agent。
-
-## 宿主路由
-
-先识别当前实际宿主和已暴露能力；根据系统身份与可调用工具判断，不根据仓库中的 `.codex`、`.claude` 目录猜测。
-
-| 当前宿主 | 首选第三方 | 降级 |
-|---|---|---|
-| Codex | 调用可用的 Claude Code 能力完成只读审查 | 无法调用、调用失败或超时后，派出一个 fresh-context reviewer subagent |
-| Claude Code | 调用最匹配的可用 `codex:*` 技能；代码审查优先 `codex:code-review` | 没有适用的 `codex:*` 技能、调用失败或超时后，派出一个 fresh-context reviewer subagent |
-| 其他宿主 | 使用可用的异构 reviewer | 没有异构 reviewer 时派出一个 fresh-context reviewer subagent |
-
-“可用”表示能力已在当前会话暴露且能直接调用；不要要求用户临时安装或配置第三方。首选调用失败一次即可降级，不要反复重试。第三方和 fallback subagent 都不得继续递归委派。
-
-若第三方与 subagent 均不可用，报告阻塞。没有独立审查结果时，不得发布最终代码审查、落定重大决策或继续合并。
-
-## 输入边界
-
-- 传递 repo root、base/head、Issue/PR、原始 diff、相关源码、验证输出和必要约束。
-- 对重大决策，同时传递主流程的初步决策、备选方案、证据、假设和已知风险，并明确要求 reviewer 反驳。
-- 提供原始材料，不提供期望结论，不暗示 reviewer 应该赞同。
-- 删除 token、密码、私钥、真实环境变量和无关个人数据。外部 reviewer 不需要的机密不得发送。
-- 要求只读：不改文件、不执行 Git/GitHub 写操作、不发布评论、不提交、不推送、不合并。
-
-## 代码审查协议
-
-主流程先独立完成初审，再调用第三方。第三方必须检查：
-
-- correctness、回归、边界条件、错误路径和安全风险；
-- Issue 验收标准与 PR 实际 diff 是否一致；
-- 测试是否真正覆盖行为，验证证据是否足够；
-- 兼容性、性能、并发、数据迁移和运维风险（按改动适用）；
-- 主流程初审可能遗漏或错误判断的地方。
-
-要求每条 finding 包含：严重级、文件与稳定符号（行号仅作导航）、可复现或可推导的证据、影响、最小安全修复。无 finding 时也要说明检查范围和剩余风险。
-
-主流程对账时逐条标记：`接受`、`合并重复`、`拒绝`。拒绝必须基于代码、测试、Issue 范围或仓库约定，不能只写“不同意”。最终 PR 评论由主流程统一发布，并标明 finding 来源为主流程或第三方。
-
-## 重大决策协议
-
-以下顺序不可颠倒：
-
-1. **初步决策：**主流程写明问题、约束、证据、备选方案、首选方案、最大风险和可逆性。
-2. **对抗审查：**第三方寻找反例、隐藏假设、遗漏方案、兼容性破坏、失败模式和更简单路径，并指出需要补证的部分。
-3. **最终决策：**主流程核验审查意见，记录每项采纳或拒绝理由，再确定方案；第三方意见是证据，不是命令。
-
-最终决策至少记录：`初步选择`、`第三方挑战`、`采纳/拒绝`、`最终选择`、`剩余风险`。若第三方指出的关键事实无法核验，决策保持阻塞，不要靠猜测继续。
-
-## Reviewer 提示词骨架
-
-```text
-你是独立、只读的对抗 reviewer。不要修改文件，不要执行任何 Git/GitHub 写操作，也不要委派其他 agent。
-
-任务类型：代码审查 / 重大决策审查
-仓库：<repo-root>
-原始材料：<issue-pr-diff-files-validation-or-decision-artifact>
-
-目标：主动寻找主流程遗漏、错误假设、反例、回归与更简单方案。不要为了形成意见而制造问题，也不要默认赞同主流程。
-
-输出：
-- 代码审查：按严重级列 findings；每条包含稳定位置、证据、影响和最小修复。若无 finding，列检查范围与剩余风险。
-- 决策审查：列最强反对理由、隐藏假设、替代方案、需要补充的证据，以及是否建议维持初步选择。
-```