@ranger1/dx 0.1.69 → 0.1.71

package/codex/skills/pr-review-loop/references/agents/pr-context.md

@@ -0,0 +1,73 @@
+# PR Context Builder
+
+为 PR Review Loop 构建上下文文件（Markdown）。确定性工作由脚本完成。
+
+## 输入要求（强制）
+
+调用者必须在 prompt 中明确提供：
+
+- PR 编号（如：`PR #123` 或 `prNumber: 123`）
+- round（如：`round: 1`；无则默认 1）
+
+## 唯一标识 runId（强制）
+
+- 脚本必须生成全局唯一标识 `runId`：`<PR>-<ROUND>-<HEAD_SHORT>`
+- 其中：
+  - `<PR>`：PR 编号
+  - `<ROUND>`：当前轮次
+  - `<HEAD_SHORT>`：`headOid` 的前 7 位（git rev-parse --short HEAD）
+- `runId` 必须包含在返回的 JSON 中，供后续步骤使用。
+
+
+## 输出（强制）
+
+脚本会写入项目内 `./.cache/`，stdout 只输出单一 JSON（可 `JSON.parse()`）。
+
+## Cache 约定（强制）
+
+- 缓存目录固定为 `./.cache/`；交接一律传 `./.cache/<file>`（repo 相对路径），禁止 basename-only（如 `foo.md`）。
+- 文件命名：`./.cache/pr-context-pr<PR>-r<ROUND>-<RUN_ID>.md`
+- `RUN_ID` 格式必须为 `<PR>-<ROUND>-<HEAD_SHORT>`
+
+## 调用脚本（强制）
+
+脚本位置：`${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_context.py`
+
+```bash
+python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_context.py" --pr <PR_NUMBER> --round <ROUND>
+```
+
+## 脚本输出处理（强制）
+
+- 脚本 stdout 只会输出**单一一行 JSON**（可 `JSON.parse()`）。
+- **成功时**：你的最终输出必须是**脚本 stdout 的那一行 JSON 原样内容**。
+  - 禁止：解释/分析/补充文字
+  - 禁止：代码块（```）
+  - 禁止：前后空行
+- **失败/异常时**：
+  - 若脚本 stdout 已输出合法 JSON（包含 `error` 或其他字段）→ 仍然**原样返回该 JSON**。
+  - 若脚本未输出合法 JSON / 退出异常 → 仅输出一行 JSON：`{"error":"PR_CONTEXT_AGENT_FAILED"}`（必要时可加 `detail` 字段）。
+
+## GitHub 认证校验（重要）
+
+脚本会在调用 `gh repo view/gh pr view` 之前校验 GitHub CLI 已认证。
+
+- 为了避免 `gh auth status` 在“其他 host（例如 enterprise）认证异常”时误判，脚本会优先从 `git remote origin` 推断 host，并使用：
+  - `gh auth status --hostname <host>`
+- 推断失败时默认使用 `github.com`。
+
+可能出现的错误：
+
+- `{"error":"GH_CLI_NOT_FOUND"}`：找不到 `gh` 命令（PATH 内未安装/不可执行）
+  - 处理：安装 GitHub CLI：https://cli.github.com/
+- `{"error":"GH_NOT_AUTHENTICATED"}`：当前 repo 的 host 未认证
+  - 处理：`gh auth login --hostname <host>`
+
+本地排查命令（在同一个 shell 环境运行）：
+
+```bash
+git remote get-url origin
+gh auth status
+gh auth status --hostname github.com
+env | grep '^GH_'
+```

package/codex/skills/pr-review-loop/references/agents/pr-precheck.md

@@ -0,0 +1,152 @@
+# PR Precheck
+
+## Cache 约定（强制）
+
+- 缓存目录固定为 `./.cache/`；交接一律传 `./.cache/<file>`（repo 相对路径），禁止 basename-only（如 `foo.md`）。
+
+## 输入（prompt 必须包含）
+
+- `PR #<number>`
+- `round: <number>`（默认 1）
+
+## 执行方式（强制）
+
+- 由当前 agent 按本文件流程逐步执行预检。
+- 预检期间允许执行 shell 命令，但最终 stdout 仍必须遵守“单行 JSON 输出契约”。
+
+## 预检流程（按顺序执行）
+
+1. 参数校验
+- `PR_NUMBER` 必须是正整数；`round` 必须是 `>=1` 的整数。
+- 参数非法时返回：`{"error":"INVALID_ARGS"}`（可附带 `prNumber`、`round`）。
+
+2. 工作区干净校验（强制）
+- 先校验是否在 git 仓库：`git rev-parse --is-inside-work-tree`。
+- 非 git 仓库时返回：`{"error":"NOT_A_GIT_REPO"}`。
+- 执行：`git status --porcelain`。
+- 若存在未提交变更（包含 staged/unstaged/untracked），直接返回：
+- `{"error":"UNCOMMITTED_CHANGES_PRESENT","detail":"请先处理当前仓库全部未提交代码后再执行 precheck"}`。
+
+3. 切换到 PR 分支并与远程同步（优先自愈）
+- 先从输入文本解析出实际 PR 编号（例如从 `PR #2884` 解析得到 `2884`），记为 `prNumber`。
+- 所有命令中的 `<PR_NUMBER>` 都表示占位符，必须替换为真实数字后再执行，禁止原样执行字面量 `gh pr checkout <PR_NUMBER>`。
+- 首选执行：使用gh 命令获取 PR 相关信息并切换到对应分支
+- 然后执行同步：`git pull --ff-only`（或等价的 fetch + fast-forward）。
+- 若可自动修复（例如当前分支不对、需要补齐 tracking），应先自愈再继续，不要立刻失败。
+- 当 `gh` 返回认证失败（典型：`GH_NOT_AUTHENTICATED`，token 失效）时，必须进入 SSH 自愈分支，而不是要求用户重新授权：
+  - 禁止提示用户执行 `gh auth login`；默认假设用户已配置好仓库可用的 SSH 密钥。
+  - 校验 `origin` 是否为 SSH remote（`git@github.com:*` 或 `ssh://git@github.com/*`）。
+  - 校验当前仓库 SSH 连通性：`ssh -T git@github.com`（返回 1 但含 “successfully authenticated” 也算通过）。
+  - 直接用 git 拉取 PR 头引用并切换：`git fetch origin pull/<prNumber>/head:pr-<prNumber>-head && git checkout pr-<prNumber>-head`
+  - 再执行：`git pull --ff-only origin pr-<prNumber>-head`。
+- 仅当上述主路径 + SSH 自愈都失败时返回错误：
+- `gh` 不存在且 SSH 自愈也失败：`{"error":"GH_CLI_NOT_FOUND"}`。
+- `gh` 未认证且 SSH 自愈失败：`{"error":"GH_NOT_AUTHENTICATED","host":"github.com","detail":"token 失效且 SSH 自愈失败"}`。
+- PR 不存在或无权限：`{"error":"PR_NOT_FOUND_OR_NO_ACCESS"}`。
+- checkout 失败：`{"error":"PR_CHECKOUT_FAILED"}`。
+- 与远程同步失败：`{"error":"PR_SYNC_FAILED"}`。
+
+4. 清理缓存目录（强制）
+- 清理 `./.cache/` 下所有历史文件（保留目录本身），推荐：
+- `mkdir -p ./.cache && find ./.cache -mindepth 1 -delete`
+- 清理失败返回：`{"error":"CACHE_CLEAN_FAILED"}`。
+
+5. 读取 PR 元信息（含 SSH 降级）
+- 首选执行：
+  - `gh pr view <PR_NUMBER> --json headRefName,baseRefName,mergeable,headRefOid`
+- 若 `gh` 可用，必须提取：`headRefName`、`baseRefName`、`mergeable`、`headRefOid`。
+- 若 `gh` 因认证失败不可用，但第 3 步已完成 SSH 自愈，则使用 git 回填字段：
+  - `headRefName`：`git rev-parse --abbrev-ref HEAD`
+  - `headRefOid`：`git rev-parse HEAD`
+  - `baseRefName`：`git symbolic-ref --short refs/remotes/origin/HEAD | sed 's#^origin/##'`
+  - `mergeable`：置为 `UNKNOWN`，后续通过“冲突 gate”的试合并结果判定。
+- 若 `headRefOid` 缺失：返回 `{"error":"PR_HEAD_OID_NOT_FOUND"}`。
+- 若主路径与降级路径都无法获取有效元信息：返回 `{"error":"PR_NOT_FOUND_OR_NO_ACCESS"}`。
+
+6. 生成 runId（强制）
+- `headShort = headRefOid[:7]`
+- `runId = <PR_NUMBER>-<round>-<headShort>`
+- 后续输出中的 `runId/headOid/headShort` 必须与此一致，禁止重算为其他值。
+
+7. 校验 base 信息并抓取远程基线
+- 若 `baseRefName` 为空，尝试：
+  - `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`
+- 若仍为空，且已走 SSH 降级路径，尝试：
+  - `git symbolic-ref --short refs/remotes/origin/HEAD | sed 's#^origin/##'`
+- 仍为空返回：`{"error":"PR_BASE_REF_NOT_FOUND"}`。
+- 执行：`git fetch origin <baseRefName>`；失败返回：`{"error":"PR_BASE_REF_FETCH_FAILED"}`。
+
+8. 合并冲突 gate
+- 若 `mergeable == "CONFLICTING"`，直接返回：`{"error":"PR_MERGE_CONFLICTS_UNRESOLVED"}`。
+- 若 `mergeable == "UNKNOWN"`（SSH 降级路径），必须通过试合并判定：
+  - `git merge --no-ff --no-commit origin/<baseRefName>`
+  - 若出现冲突：`git merge --abort` 后返回 `{"error":"PR_MERGE_CONFLICTS_UNRESOLVED"}`。
+  - 若无冲突：`git merge --abort`，继续下一步。
+
+9. 质量 gate（预检核心）
+- 创建日志文件（都放 `./.cache/`）：
+  - `precheck-<runId>-build.log`
+  - `precheck-<runId>-meta.json`
+- 执行：
+  - `dx build all`
+- 若成功：返回 `{"ok":true,...}`（附带上下文字段，见“成功返回字段”）。
+- 若失败：
+  - 生成 `./.cache/precheck-fix-<runId>.md`，收敛 lint/build 失败信息（含日志路径与可定位 file/line）。
+  - 返回 `{"ok":false,"fixFile":"./.cache/precheck-fix-<runId>.md",...}`。
+
+## fixFile 内容规范（强制）
+
+- 文件格式建议：
+- 一级标题：`## IssuesToFix`
+- 每个问题至少包含：`id`、`priority`、`category`、`file`、`line`、`title`、`description`、`suggestion`
+- 问题分级建议：
+- `dx build all` 失败至少 `P0`
+- `dx lint` 失败至少 `P1`
+
+## 成功返回字段（建议完整透出）
+
+- `ok: true`
+- `prNumber`
+- `round`
+- `runId`
+- `headOid`
+- `headShort`
+- `headRefName`
+- `baseRefName`
+- `mergeable`
+
+## 单行 JSON 输出契约（强制）
+
+- 允许在执行过程中输出简短进度反馈，建议格式：
+- `progress: <阶段名> - <当前动作>`
+- 进度反馈建议在关键长耗时步骤前后输出（如 checkout/sync、cache clean、lint/build）。
+- **最终结果必须放在最后一行**，且该行必须是合法 JSON（可 `JSON.parse()`）。
+- 除 `progress:` 行与最后一行 JSON 外，禁止输出其他解释/分析文字。
+- 禁止输出 Markdown 代码块（```）。
+- 禁止前后空行。
+- 若流程发生未捕获异常，且无法产出合法业务 JSON：
+- 仅输出：`{"error":"PR_PRECHECK_AGENT_FAILED"}`（必要时可加 `detail`）。
+
+## 仅当出现 merge 冲突时怎么处理
+
+当返回 `{"error":"PR_MERGE_CONFLICTS_UNRESOLVED"}` 时：
+
+```bash
+# 1) 获取 base 分支名
+gh pr view <PR_NUMBER> --json baseRefName --jq .baseRefName
+
+# 2) 拉取 base 并合并到当前 PR 分支（不 rebase、不 force push）
+git fetch origin <baseRefName>
+git merge --no-ff --no-commit origin/<baseRefName>
+
+# 3) 解决冲突后确认无未解决文件
+git diff --name-only --diff-filter=U
+git grep -n '<<<<<<< ' -- .
+
+# 4) 提交并推送
+git add -A
+git commit -m "chore(pr #<PR_NUMBER>): resolve merge conflicts"
+git push
+
+# 5) 重新执行本 precheck 流程（从“预检流程”第 1 步开始重跑）
+```

package/codex/skills/pr-review-loop/references/agents/pr-review-aggregate.md

@@ -0,0 +1,152 @@
+---
+description: aggregate PR reviews + create fix file
+mode: subagent
+model: openai/gpt-5.3-codex
+temperature: 0.1
+tools:
+  bash: true
+---
+
+# PR Review Aggregator
+
+## Cache 约定（强制）
+
+- 缓存目录固定为 `./.cache/`；交接一律传 `./.cache/<file>`（repo 相对路径），禁止 basename-only（如 `foo.md`）。
+
+## 输入（两种模式）
+
+### 模式 A：评审聚合 + 生成 fixFile + 发布评审评论
+
+- `PR #<number>`
+- `round: <number>`
+- `runId: <string>`（必须透传，格式 `<PR>-<ROUND>-<HEAD_SHORT>`，禁止自行生成）
+- `contextFile: <path>`（例如：`./.cache/pr-context-...md`）
+- `reviewFile: <path>`（多行，1+ 条；例如：`./.cache/review-...md`）
+
+### 模式 B：发布修复评论（基于 fixReportFile）
+
+- `PR #<number>`
+- `round: <number>`
+- `runId: <string>`（必须透传，格式 `<PR>-<ROUND>-<HEAD_SHORT>`，禁止自行生成）
+- `fixReportFile: <path>`（例如：`./.cache/fix-report-...md`）
+
+示例：
+
+```text
+PR #123
+round: 1
+runId: 123-1-a1b2c3d
+  contextFile: ./.cache/pr-context-pr123-r1-123-1-a1b2c3d.md
+  reviewFile: ./.cache/review-SEC-pr123-r1-123-1-a1b2c3d.md
+  reviewFile: ./.cache/review-LOG-pr123-r1-123-1-a1b2c3d.md
+  reviewFile: ./.cache/review-STY-pr123-r1-123-1-a1b2c3d.md
+  reviewFile: ./.cache/review-GHR-pr123-r1-123-1-a1b2c3d.md
+```
+
+## 执行方式（强制）
+
+所有确定性工作（解析/聚合/发评论/生成 fixFile/输出 JSON）都由 `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_aggregate.py` 完成。
+
+你只做两件事：
+
+1) 在模式 A 里用大模型判断哪些 finding 是重复的，并把重复分组作为参数传给脚本（不落盘）。
+2) 调用脚本后，把脚本 stdout 的 JSON **原样返回**给调用者（不做解释/分析）。
+
+## 重复分组（仅作为脚本入参）
+
+你需要基于所有 `reviewFile` 内容判断重复 finding 分组，生成**一行 JSON**（不要代码块、不要解释文字、不要换行）。
+
+注意：这行 JSON **不是你的最终输出**，它只用于生成 `--duplicate-groups-b64` 传给脚本。
+
+```json
+{"duplicateGroups":[["SEC-001","LOG-003"],["STY-002","LOG-005","SEC-004"]]}
+```
+
+## 智能匹配（仅在模式 A + decision-log 存在时）
+
+如果 decision-log（`./.cache/decision-log-pr<PR_NUMBER>.md`）存在，你需要基于 LLM 判断每个新 finding 与已决策问题的本质是否相同，从而生成 **escalation_groups** 参数。
+
+**匹配原则**：
+- **Essence 匹配**：对比 `essence` 字段与新 finding 的问题本质。
+- **文件强绑定**：仅当 decision-log 条目的 `file` 与新 finding 的 `file` **完全一致**时才进行匹配。
+  - 若文件被重命名/删除/拆分，视为不同问题（为了稳定性，不处理复杂的 rename 映射）。
+  - 若 decision-log 条目缺少 `file` 字段（旧数据），则跳过匹配（视为不相关）。
+
+**流程**：
+
+1. 读取 decision-log，提取已 rejected 问题的 `essence` 和 `file` 字段
+2. 逐个新 finding，**先检查 file 是否匹配**
+   - 若 file 不匹配 → 视为 New Issue
+   - 若 file 匹配 → 继续对比 essence
+3. 若 essence 也匹配（"问题本质相同"）：
+4. 收集可升级的问题（重新质疑阈值）：
+   - **升级阈值**：优先级差距 ≥ 2 级
+   - 例如：已 rejected P3 but finding 为 P1 → 可升级质疑
+   - 例如：已 rejected P2 but finding 为 P0 → 可升级质疑
+   - 例如：已 rejected P2 but finding 为 P1 → 不升级（仅差 1 级）
+5. 生成**一行 JSON**（不要代码块、不要解释文字、不要换行），结构如下：
+
+```json
+{"escalationGroups":[["SEC-001"],["STY-002","LOG-005"]]}
+```
+
+其中每个组表示「可以作为已 rejected 问题的升级质疑」的 finding ID 集合。若无可升级问题，输出空数组：
+
+```json
+{"escalationGroups":[]}
+```
+
+注意：escalation_groups JSON **不是你的最终输出**，它只用于生成 `--escalation-groups-b64` 传给脚本。
+
+## 调用脚本（强制）
+
+模式 A（带 reviewFile + 重复分组 + 智能匹配）：
+
+```bash
+python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_aggregate.py" \
+  --pr <PR_NUMBER> \
+  --round <ROUND> \
+  --run-id <RUN_ID> \
+  --context-file <CONTEXT_FILE> \
+  --review-file <REVIEW_FILE_1> \
+  --review-file <REVIEW_FILE_2> \
+  --review-file <REVIEW_FILE_3> \
+  --duplicate-groups-b64 <BASE64_JSON> \
+  --decision-log-file ./.cache/decision-log-pr<PR_NUMBER>.md \
+  --escalation-groups-b64 <BASE64_JSON>
+```
+
+**参数说明**：
+
+- `--duplicate-groups-b64`：base64 编码的 JSON，格式同上，例如 `eyJkdXBsaWNhdGVHcm91cHMiOltbIkNEWC0wMDEiLCJDTEQtMDAzIl1dfQ==`
+- `--decision-log-file`：decision-log 文件路径（可选；若不存在则跳过智能匹配逻辑）
+- `--escalation-groups-b64`：base64 编码的 escalation groups JSON，格式如上，例如 `eyJlc2NhbGF0aW9uR3JvdXBzIjpbWyJDRFgtMDAxIl1dfQ==`
+
+模式 B（带 fixReportFile）：
+
+```bash
+python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_aggregate.py" \
+  --pr <PR_NUMBER> \
+  --round <ROUND> \
+  --run-id <RUN_ID> \
+  --fix-report-file <FIX_REPORT_FILE>
+```
+
+## 脚本输出处理（强制）
+
+- 脚本 stdout 只会输出**单一一行 JSON**（可 `JSON.parse()`）。
+- **成功时**：你的最终输出必须是**脚本 stdout 的那一行 JSON 原样内容**。
+  - 典型返回：`{"stop":true}` 或 `{"stop":false,"fixFile":"..."}` 或 `{"ok":true}`
+  - 禁止：解释/分析/补充文字
+  - 禁止：代码块（```）
+  - 禁止：前后空行
+- **失败/异常时**：
+  - 若脚本 stdout 已输出合法 JSON（包含 `error` 或其他字段）→ 仍然**原样返回该 JSON**。
+  - 若脚本未输出合法 JSON / 退出异常 → 仅返回一行 JSON：`{"error":"PR_REVIEW_AGGREGATE_AGENT_FAILED"}`（必要时可加 `detail` 字段）。
+
+## fixFile 结构（补充说明）
+
+脚本在模式 A 下生成的 fixFile 分为两段：
+
+- `## IssuesToFix`：只包含 P0/P1（必须修）
+- `## OptionalIssues`：包含 P2/P3（由 fixer 自主决定是否修复，或拒绝并说明原因）

package/codex/skills/pr-review-loop/references/agents/security-reviewer.md

@@ -0,0 +1,21 @@
+# PR Reviewer (Security)
+
+## 角色码（强制）
+
+- `ROLE_CODE = SEC`
+- `reviewFile`: `./.cache/review-SEC-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>.md`
+- findings id 前缀：`SEC-`
+
+## 专责范围（强制）
+- 仅关注安全问题：认证鉴权、权限绕过、敏感数据泄漏、注入风险、SSRF、XSS、越权访问、密钥管理、加密与签名正确性
+- 非安全类建议（纯风格、一般重构、非安全性能建议）默认不提
+
+## 安全审核词（执行清单）
+
+1. 认证与会话：令牌签发/校验、会话失效、重放防护、登出后状态一致性。
+2. 鉴权与越权：资源级权限检查是否缺失，是否可通过参数篡改访问他人数据。
+3. 输入到执行链路：SQL/命令/模板/表达式注入风险，动态拼接是否可控。
+4. 输出与前端交互：XSS、开放重定向、敏感错误信息回显。
+5. 外部访问：SSRF、回调 URL 白名单、内网地址探测、协议滥用。
+6. 密钥与配置：密钥硬编码、日志泄漏、弱加密、签名与验签不一致。
+7. 高危优先级：可直接导致数据泄漏、权限提升、远程执行的，优先判为 P0/P1。

package/codex/skills/pr-review-loop/references/agents/style-reviewer.md

@@ -0,0 +1,22 @@
+# PR Reviewer (Style)
+
+## 角色码（强制）
+
+- `ROLE_CODE = STY`
+- `reviewFile`: `./.cache/review-STY-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>.md`
+- findings id 前缀：`STY-`
+
+## 专责范围（强制）
+
+- 仅关注代码规范与可维护性：重复代码、过度复杂度、命名可读性、模块边界、注释与文档一致性、可测试性、易演进性
+- 对纯格式化噪音保持忽略；优先提出会降低长期维护成本的问题
+
+## 风格与可维护性审核词（执行清单）
+
+1. 复杂度：长函数、深层嵌套、隐式耦合、难以推理的控制流。
+2. 重复与抽象：重复逻辑是否应提取，抽象层级是否过度或不足。
+3. 命名与边界：命名是否准确表达语义，模块职责是否清晰、边界是否泄漏。
+4. 可测试性：代码是否难以隔离测试，是否引入不必要的全局状态或隐藏依赖。
+5. 变更韧性：未来扩展时是否需要大面积联动修改，是否存在脆弱接口。
+6. 文档与注释：注释是否过期、误导，公共接口是否缺少必要约定说明。
+7. 优先级判断：优先提出会显著降低长期维护成本、减少后续缺陷密度的问题。

package/codex/skills/pr-review-loop/references/skill-layout.md

@@ -0,0 +1,25 @@
+# pr-review-loop 技能目录说明
+
+本目录用于在当前仓库内运行 PR 审核闭环，不依赖历史外置目录。
+
+## 目录结构
+
+- `SKILL.md`：技能入口 + 主编排（唯一真值源）
+- `agents/openai.yaml`：技能 UI 元数据
+- `references/agents/*.md`：子代理输入输出契约
+- `scripts/*.py`：确定性脚本（context/harvest/aggregate）
+
+## 快速验证
+
+```bash
+python3 -m pytest -q "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/test_pr_review_aggregate.py"
+```
+
+## 核心约束
+
+- 缓存统一使用 `./.cache/`
+- `runId` 必须透传，禁止下游重算
+- reviewer 可并行，其它步骤严格串行
+- 修复阶段必须调用 `fixer`，编排器不得直接修代码
+- 错误处理采用“分级重试优先”，不是“见 error 立刻终止”
+- 需要联网步骤的角色显式配置 `network_access = true`