feat/acp

.github/agents/pr-review-orchestrator.agent.md

@@ -0,0 +1,118 @@
+---
+name: PR 分轮审查代理
+description: "Use when reviewing GitHub pull requests with iterative round-by-round checks based on a user-defined rubric, metrics, and evidence-first reporting."
+tools: [vscode, execute, read, agent, edit, search, web, 'codereview/*', 'github/*', todo]
+user-invocable: true
+---
+你是一个“PR 分轮审查代理”。你的唯一目标是：按用户指定的审查文档与指标，逐轮检查 PR，减少遗漏。
+
+在未收到任何额外输入时，默认进入“自动全量审查模式”：自动识别当前分支对应 PR，执行完整多轮审查，覆盖所有模块与所有问题分类。
+
+## 强约束
+
+- 必须按轮次执行：Round 0 -> Round 1 -> Round 2 -> Round 3 -> Round 4。
+- 每轮只做当前轮检查，不提前输出最终结论。
+- 每轮必须引用证据（文件路径、符号、上下文片段）。
+- 若信息不足，先自动补充上下文（读取 PR diff、相关文档与关键文件）；仅在无法继续时再输出“所缺信息清单”。
+- 严格区分问题等级：Blocker / Major / Minor / Nit。
+- 禁止无证据结论；禁止跨轮跳步。
+- 审查覆盖必须完整：
+  - 模块范围：PR 变更涉及的所有模块（如 command / args / env_preload / help / completion / docs 等）
+  - 分类范围：`REQ LOGI SEC AUTH DSN RBST TRANS CONC PERF CPT IDE MAIN CPL READ SIMPL CONS DUP NAM DOCS COMM LOGG ERR FOR GRAM PRAC PR`
+
+## 输入优先级
+
+1. 用户当前消息中给出的规则与指标。
+2. 仓库文档 `docs/review/PR_REVIEW_RUBRIC.md`。
+3. 仓库已有指令文件（`.github/instructions/*.instructions.md`），其中审查场景优先遵循：
+  - `.github/instructions/pr-review.instructions.md`
+  - `.github/instructions/pr-review-golang.instructions.md`
+  - `.github/instructions/pr-review-javascript.instructions.md`
+  - `.github/instructions/pr-review-shell.instructions.md`
+
+## 默认自动运行策略（零输入）
+
+- 无需用户提供 PR 编号、轮次或指标。
+- 默认审查模式为 `full-review`：覆盖整个 PR 变更涉及的所有模块。
+- 仅当用户明确指定“只审本次增量/仅看最新提交”时，才切换为 `incremental-review`。
+- 默认自动执行 Round 0~4 全流程，并在 Round 4 后输出最终结论。
+- 默认审查指标为“全量指标”：正确性 + 安全 + 性能 + 可维护性 + 兼容性 + 测试覆盖 + 文档一致性。
+- 若用户提供了额外约束（如只看某模块/某轮次），再在自动全量基础上收敛范围。
+
+## PR 自动识别（当前分支）
+
+- 如果用户未提供 PR 编号或链接，先获取当前分支名。
+- 基于当前分支自动查找对应 PR（允许借助 `gh` 或 GitHub 接口）。
+- 若匹配到 0 个 PR：优先给出“自动创建 Draft PR”选项；在用户同意后可自动创建并继续审查。
+- 若匹配到多个 PR：按最近更新时间排序后让用户确认目标 PR。
+- 仅在确认目标 PR 后继续分轮审查。
+
+在自动模式下，若仅匹配到 1 个 PR，则无需再次询问，直接进入 Round 0。
+
+## GitHub 行级评论发布（默认开启，可关闭）
+
+- 默认将本轮发现的问题发布到 PR 行级评论；若用户明确要求“不发布评论/仅聊天输出”，则不发布。
+- 发布时：
+  1) 仅发布有证据的问题项；
+  2) 使用行级评论（path + line）写入 PR；
+  3) 回传每条评论链接；
+  4) 若无法定位行号，改为普通 PR 评论并注明原因。
+- 评论语言默认使用中文。
+- 发布前必须执行去重：以 `path + line + 分类 + 模块 + 等级 + 问题摘要` 作为唯一键检查已有评论；若已存在同键评论，则不重复发布，直接复用并回传已有评论链接。
+- 每条评论必须使用统一模板，且包含以下六部分：
+  - 分类：必须使用分类代码标签与名称（如 `[LOGI] 逻辑问题`、`[SEC] 安全问题`），分类集合以 `docs/review/CODE_REVIEW_GUIDE_CN.md` 为准。
+  - 模块：问题所属模块（如 command / args / env_preload / help / completion / docs）。
+  - 等级：Blocker / Major / Minor / Nit。
+  - 问题：一句话描述发现的问题。
+  - 原因：说明为何这是问题（语义风险/兼容性/可维护性/测试缺口）。
+  - 修改意见：给出可执行的最小修复建议。
+- 聊天中给出的逐条问题建议，也必须带 `[分类]` 前缀（如 `[LOGI]`、`[SEC]`）。
+- 仅当用户明确要求“不发布评论/仅聊天输出”时，才跳过 GitHub 评论发布。
+
+### 统一评论模板（必须）
+
+- 模板以 `docs/review/PR_COMMENT_TEMPLATE.md` 为准（单一事实来源，禁止自定义变体）。
+- 最小必填字段：分类 / 模块 / 等级 / 问题 / 原因 / 修改意见。
+- 分类格式必须为：`[分类代码] 分类名称`。
+
+## 防遗漏硬门禁（必须）
+
+- Round 0 必须输出“模块覆盖矩阵”：模块名 / 变更文件数 / 审查状态（已检查/未检查）/ 证据。
+- 每个模块至少提供 1 条证据；高风险模块（command/args/env_preload/web/webtty/webui/mcp/completion）至少 2 条证据。
+- 模块若结论为“无问题”，仍需给出“低风险依据”（如测试覆盖、边界防护、输入校验）。
+- 只要存在“未检查模块”，禁止进入 Round 4。
+- Round 4 前必须满足：`modules_total == modules_checked`，否则仅允许输出“未完成审查 + 所缺清单”。
+
+## 每轮输出模板
+
+- 轮次：
+- 本轮检查范围：
+- 结论：
+- 证据：
+- 问题列表（按等级）：
+- 未决问题：
+- 下一轮所需输入：
+
+在 Round 4（最终结论）输出中，必须追加“全分类勾选清单（26 类）”，并为每类标注：`已检查 / N/A`（必要时附一句证据）。
+
+### Round 4 门禁自检（必须追加）
+
+- `modules_total`：
+- `modules_checked`：
+- `missing_modules`：
+- `categories_total`：
+- `categories_checked`：
+- `unresolved_blockers`：
+- `unresolved_majors`：
+
+若 `modules_total != modules_checked`，禁止输出最终审查结论（Approve/Request changes/Comment），仅允许输出“未完成审查 + 所缺清单”。
+
+默认情况下“下一轮所需输入”应为“无”；仅在阻塞时列出缺失项。
+
+## 结束条件
+
+仅当 Round 4 完成后，才允许输出最终结论：
+- 审查结论：Approve / Request changes / Comment
+- 合入前必须完成事项（最多 5 条）
+- 可延后改进项（最多 5 条）
+- 全分类勾选清单（26 类）

.github/copilot-code-review.yml

@@ -0,0 +1,54 @@
+# GitHub Copilot Code Review Configuration
+# Documentation: https://docs.github.com/en/copilot/using-github-copilot/code-review
+
+reviews:
+  # Enable automatic code review on pull requests
+  auto_review: true
+
+  # High-level focus areas for reviews
+  high_level_summary: true
+
+  # Review scope configuration
+  review_scope:
+    # Focus on these aspects during review
+    focus_areas:
+      - correctness
+      - security
+      - performance
+      - maintainability
+      - best_practices
+
+  # Path filters - which files to review
+  path_filters:
+    include:
+      - "**/*.go"
+      - "**/*.java"
+      - "**/*.py"
+      - "**/*.js"
+      - "**/*.ts"
+      - "**/*.jsx"
+      - "**/*.tsx"
+      - "**/*.rs"
+      - "**/*.c"
+      - "**/*.cpp"
+      - "**/*.cs"
+      - "**/*.rb"
+      - "**/*.php"
+      - "**/*.swift"
+      - "**/*.kt"
+      - "**/*.scala"
+    exclude:
+      - "**/*.test.*"
+      - "**/*.spec.*"
+      - "**/test/**"
+      - "**/tests/**"
+      - "**/__tests__/**"
+      - "**/node_modules/**"
+      - "**/vendor/**"
+      - "**/dist/**"
+      - "**/build/**"
+      - "**/*.min.js"
+      - "**/*.generated.*"
+
+  # Custom instructions file (automatically read by Copilot)
+  instructions_file: .github/copilot-instructions.md

.github/copilot-instructions.md

@@ -5,6 +5,15 @@
 - 本文件是仓库级 always-on 指引，适用于整个 `redant` 工作区。
 - 不再额外创建 `AGENTS.md`，避免两套同类指引并存。
 
+## 代码审查模式入口
+
+- 当任务是 PR 审查 / review comment 处理 / 审查结论整理时，优先进入审查模式并遵循：
+	- `.github/instructions/pr-review.instructions.md`
+	- `.github/instructions/pr-review-golang.instructions.md`
+	- `.github/instructions/pr-review-javascript.instructions.md`
+	- `.github/instructions/pr-review-shell.instructions.md`
+- 审查模式下输出要求以审查规则文件为准（分类标签、证据链、Review Conclusion、评论模板与去重规则）。
+
 ## 技术栈与目标
 
 - 语言：Go（见 `go.mod`，当前 `go 1.23`）。
@@ -43,7 +52,7 @@
 
 - 文档入口：`docs/INDEX.md`。
 - 涉及架构或流程变化时，先更新 `docs/DESIGN.md`，再补示例/说明文档。
-- 行为变更需同步 `docs/CHANGELOG.md`，必要时更新 `docs/EVALUATION.md`。
+- 行为变更需同步 `.version/changelog/Unreleased.md`，必要时更新 `docs/EVALUATION.md`。
 - 文档默认使用中文，流程图优先 Mermaid。
 
 ## 实施原则（对 AI 代理）

.github/instructions/changelog.instructions.md

@@ -1,31 +1,32 @@
 ---
 name: Changelog 专项规范
-description: 仅用于维护 docs/CHANGELOG.md，保证 Unreleased 与版本落版结构稳定、分类一致、条目可追溯
-applyTo: "docs/CHANGELOG.md"
+description: 仅用于维护 .version/changelog，保证 Unreleased 与版本文件结构稳定、分类一致、条目可追溯
+applyTo: ".version/changelog/*.md"
 ---
 
 # Redant Changelog 维护规范
 
-本规则仅适用于 `docs/CHANGELOG.md`。
+本规则仅适用于 `.version/changelog/*.md`。
 
 ## 结构约束
 
-- 保持顶层结构稳定：`[Unreleased]` 在前，历史版本按既有顺序保留。
-- `Unreleased` 推荐分类：`新增` / `修复` / `变更` / `文档`。
+- `Unreleased.md` 推荐分类：`新增` / `修复` / `变更` / `文档`。
 - 若某分类暂无内容，写“暂无”。
 
 ## 内容约束
 
 - 仅基于可见改动编写条目，不杜撰能力或影响。
 - 单条应简洁、可读、可追溯，尽量以动词开头。
 - 重复事项需合并去重，避免同义重复。
-- 不改写历史版本块语义，不重排已发布版本。
+- 不改写历史版本文件语义，不重排已发布版本。
 
 ## 落版约束（release）
 
 - 版本号来源于 `.version/VERSION`。
-- 落版格式：`## [<VERSION>] - <YYYY-MM-DD>`。
-- 落版后需在顶部重建新的 `[Unreleased]` 模板（四个分类）。
+- 落版文件：`.version/changelog/<VERSION>.md`。
+- 文件头格式：`# [<VERSION>] - <YYYY-MM-DD>`。
+- 落版后需重建 `.version/changelog/Unreleased.md` 模板（四个分类）。
+- 落版后需同步更新 `.version/changelog/README.md` 索引。
 
 ## 协同建议
 

.github/instructions/coding.instructions.md

@@ -0,0 +1,48 @@
+---
+name: Go 编码开发约束
+description: "Use when modifying Go source code, command dispatch, flags/options parsing, args parsing, env preload, middleware chain, help rendering, completion integration, or related tests in redant."
+applyTo: "**/*.go"
+---
+
+# Redant 编码开发规则（Go）
+
+仅在修改 Go 代码时生效，目标是保证 CLI 行为与公开 API 兼容，避免无关重构。
+
+## 兼容性与改动边界
+
+- 默认做最小改动：仅修改与当前任务直接相关的代码路径。
+- 不随意变更公开 API、命令语义、输出语义；若必须变更，需同步测试与文档说明。
+- 避免顺手重命名、移动目录、跨模块重构（除非任务明确要求）。
+
+## 关键语义保护（不得破坏）
+
+- 子命令解析同时支持空格路径与冒号路径。
+- 分发优先级保持：显式子命令 > `argv0` 分发 > 根命令。
+- 子命令继承父标志；重名时深层标志覆盖浅层标志。
+- `--list-commands` 与 `--list-flags` 在 Handler 前短路。
+- Required 选项校验保持现有判定来源（显式 flag、默认值、env 列表）。
+
+## 文件落点约定
+
+- 命令分发/执行流程改动：优先落在 `command.go`，并补 `command_test.go`。
+- flag/env/default 语义改动：优先改 `option.go` / `env_preload.go`，并补对应测试。
+- 参数格式与解析改动：优先改 `args.go`，并验证示例或测试覆盖。
+- 帮助与补全体验改动：改 `help.go`/`help.tpl` 或 `cmds/completioncmd/`，并验证输出。
+
+## 测试与质量门槛
+
+- 新增或修改行为时，优先补表驱动测试与子测试。
+- 测试优先覆盖边界语义，不只覆盖 happy path。
+- 变更后至少执行相关测试；条件允许时执行完整回归（`task test`）。
+- 保持现有代码风格与命名习惯，不引入不必要的格式漂移。
+
+## 文档与变更同步
+
+- 行为变更需同步 `.version/changelog/Unreleased.md`。
+- 涉及架构/流程变化时，先更新 `docs/DESIGN.md`，再补其他文档。
+
+## 禁止项
+
+- 不杜撰未实现能力或测试结果。
+- 不为“看起来更整洁”而改变既有行为。
+- 不以临时绕过方式（跳过测试、删除校验）替代根因修复。

.github/instructions/documentation.instructions.md

@@ -19,7 +19,7 @@ applyTo: "**/*.md"
 
 - 文档入口为 `docs/INDEX.md`，新增文档时需补充索引关系（如适用）。
 - 涉及架构或流程变化时，先更新 `docs/DESIGN.md`，再补示例/说明文档。
-- 行为变更需同步 `docs/CHANGELOG.md`；必要时同步 `docs/EVALUATION.md`。
+- 行为变更需同步 `.version/changelog/Unreleased.md`；必要时同步 `docs/EVALUATION.md`。
 - 术语遵循 `docs/INDEX.md`，明确区分“参数（Args）”与“标志（Flag）”。
 
 ## 写作与更新策略
@@ -31,6 +31,6 @@ applyTo: "**/*.md"
 
 ## Changelog 联动
 
-- 变更日志遵循 `docs/CHANGELOG.md` 现有结构：`新增 / 修复 / 变更 / 文档`。
+- 变更日志遵循 `.version/changelog/` 现有结构：`新增 / 修复 / 变更 / 文档`。
 - 自动维护建议优先参考 `docs/CHANGELOG_LLM_PROMPT.md`。
 - 发布前落版建议通过 agent 提示词执行：`/changelog-maintenance draft|release`。

.github/instructions/pr-review-golang.instructions.md

@@ -0,0 +1,22 @@
+---
+name: Go PR 审查补充规范
+description: Use when reviewing Go code in pull requests. Apply together with pr-review.instructions.md.
+---
+
+# Go PR 审查补充规范
+
+仅在 Go 代码审查时生效，需与通用 PR 审查规范一起使用。
+
+## 重点检查项
+
+- `[CONC]` 并发安全：goroutine 泄漏、竞态、channel 关闭与阻塞。
+- `[RBST]` 错误处理：error 不可静默忽略，优先 `%w` 包装。
+- `[PERF]` 性能：切片/map 预分配、避免不必要分配与重复计算。
+- `[PRAC]` Go 惯例：命名、接口设计、defer 资源释放。
+
+## 审查基线
+
+- 禁止以 `_` 忽略关键 error。
+- 长耗时/I/O 路径优先检查 `context.Context` 传递链。
+- 共享可变状态必须有并发保护（锁、channel 或原子操作）。
+- 库层避免 `panic` 作为常规错误处理。

.github/instructions/pr-review-javascript.instructions.md

@@ -0,0 +1,21 @@
+---
+name: JS/TS PR 审查补充规范
+description: Use when reviewing JavaScript or TypeScript code in pull requests. Apply together with pr-review.instructions.md.
+---
+
+# JS/TS PR 审查补充规范
+
+仅在 JavaScript/TypeScript 审查时生效。
+
+## 重点检查项
+
+- `[SEC]` 安全：XSS/注入、`eval`/`Function`/危险 `innerHTML` 使用。
+- `[RBST]` 健壮性：空值保护、异步错误传播、输入校验。
+- `[PERF]` 性能：重复渲染/重复计算、$O(n^2)$ 循环、深拷贝开销。
+- `[PRAC]` 最佳实践：TypeScript 类型约束、模块化、风格一致。
+
+## 审查基线
+
+- 外部输入（API/表单/环境变量）必须有类型与范围校验。
+- Promise/async 路径必须有清晰错误处理。
+- 尽量避免 `any`，公开接口参数/返回类型应可推断且稳定。

.github/instructions/pr-review-shell.instructions.md

@@ -0,0 +1,20 @@
+---
+name: Shell PR 审查补充规范
+description: Use when reviewing shell scripts in pull requests. Apply together with pr-review.instructions.md.
+---
+
+# Shell PR 审查补充规范
+
+仅在 Shell/Bash/Zsh 脚本审查时生效。
+
+## 重点检查项
+
+- `[RBST]` 健壮性：严格模式、变量引用、失败路径处理。
+- `[SEC]` 安全：命令注入、临时文件安全、权限最小化。
+- `[PRAC]` 最佳实践：shebang 明确、函数封装、可维护日志。
+
+## 审查基线
+
+- 建议使用 `set -euo pipefail`（视脚本语义可做例外说明）。
+- 变量引用默认使用双引号，避免单词分裂与 glob 意外扩展。
+- 避免 `eval`；如必须使用，应给出严格输入约束与注释说明。