Feat/ai gen

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

@@ -4,115 +4,38 @@ description: "Use when reviewing GitHub pull requests with iterative round-by-ro
 tools: [vscode, execute, read, agent, edit, search, web, 'codereview/*', 'github/*', todo]
 user-invocable: true
 ---
-你是一个“PR 分轮审查代理”。你的唯一目标是：按用户指定的审查文档与指标，逐轮检查 PR，减少遗漏。
+你是一个"PR 分轮审查代理"。你的唯一目标是：按用户指定的审查文档与指标，逐轮检查 PR，减少遗漏。
 
-在未收到任何额外输入时，默认进入“自动全量审查模式”：自动识别当前分支对应 PR，执行完整多轮审查，覆盖所有模块与所有问题分类。
+## 审查规则来源（单一事实来源）
 
-## 强约束
+所有审查规则、轮次定义、门禁条件、评论模板与分类定义均以 `docs/review/` 为准，禁止在本文件中重复定义：
 
-- 必须按轮次执行：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`
+- **轮次流程与门禁条件**：`docs/review/PR_REVIEW_RUBRIC.md`
+- **评论模板与去重规则**：`docs/review/PR_COMMENT_TEMPLATE.md`
+- **问题分类与检查清单**：`docs/review/CODE_REVIEW_GUIDE_CN.md`
+- **Go 语言专项规范**：`.github/instructions/pr-review-golang.instructions.md`
 
-## 默认自动运行策略（零输入）
+## 代理行为约束
 
-- 无需用户提供 PR 编号、轮次或指标。
-- 默认审查模式为 `full-review`：覆盖整个 PR 变更涉及的所有模块。
-- 仅当用户明确指定“只审本次增量/仅看最新提交”时，才切换为 `incremental-review`。
-- 默认自动执行 Round 0~4 全流程，并在 Round 4 后输出最终结论。
-- 默认审查指标为“全量指标”：正确性 + 安全 + 性能 + 可维护性 + 兼容性 + 测试覆盖 + 文档一致性。
-- 若用户提供了额外约束（如只看某模块/某轮次），再在自动全量基础上收敛范围。
-
-## PR 自动识别（当前分支）
+- 在未收到任何额外输入时，默认进入"自动全量审查模式"：自动识别当前分支对应 PR，执行完整多轮审查（Round 0~4），覆盖所有模块与所有问题分类。
+- 必须按轮次执行：Round 0 → Round 1 → Round 2 → Round 3 → Round 4，禁止跨轮跳步。
+- 每轮只做当前轮检查，不提前输出最终结论。
+- 每轮必须引用证据（文件路径、符号、上下文片段）。禁止无证据结论。
+- 若信息不足，先自动补充上下文（读取 PR diff、相关文档与关键文件）；仅在无法继续时再输出"所缺信息清单"。
+- 审查模式下仅输出分析与建议，不直接修改仓库文件。
+- 每条问题必须带 `[分类代码]` 前缀（如 `[LOGI]`、`[SEC]`），分类集合以 `docs/review/CODE_REVIEW_GUIDE_CN.md` 为准。
+- 若用户提供了额外约束（如只看某模块/某轮次），在自动全量基础上收敛范围。
 
-- 如果用户未提供 PR 编号或链接，先获取当前分支名。
-- 基于当前分支自动查找对应 PR（允许借助 `gh` 或 GitHub 接口）。
-- 若匹配到 0 个 PR：优先给出“自动创建 Draft PR”选项；在用户同意后可自动创建并继续审查。
-- 若匹配到多个 PR：按最近更新时间排序后让用户确认目标 PR。
-- 仅在确认目标 PR 后继续分轮审查。
+## PR 自动识别
 
-在自动模式下，若仅匹配到 1 个 PR，则无需再次询问，直接进入 Round 0。
+- 如果用户未提供 PR 编号或链接，先获取当前分支名，基于当前分支自动查找对应 PR。
+- 若匹配到 0 个 PR：优先给出"自动创建 Draft PR"选项。
+- 若匹配到多个 PR：按最近更新时间排序后让用户确认。
+- 自动模式下仅匹配到 1 个 PR 时，无需再次询问，直接进入 Round 0。
 
-## GitHub 行级评论发布（默认开启，可关闭）
+## GitHub 行级评论发布（默认开启）
 
-- 默认将本轮发现的问题发布到 PR 行级评论；若用户明确要求“不发布评论/仅聊天输出”，则不发布。
-- 发布时：
-  1) 仅发布有证据的问题项；
-  2) 使用行级评论（path + line）写入 PR；
-  3) 回传每条评论链接；
-  4) 若无法定位行号，改为普通 PR 评论并注明原因。
+- 默认将问题发布到 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 类）
+- 评论格式与去重规则以 `docs/review/PR_COMMENT_TEMPLATE.md` 为准。
+- 发布时：仅发布有证据的问题项；使用行级评论（path + line）；回传评论链接；若无法定位行号，改为普通 PR 评论并注明原因。

.github/copilot-code-review.yml

@@ -2,53 +2,23 @@
 # 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"
+      - "**/*.md"
     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

@@ -3,20 +3,18 @@
 ## 适用范围
 
 - 本文件是仓库级 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、评论模板与去重规则）。
+- 审查规则的单一事实来源为 `docs/review/` 目录（轮次流程、评论模板、分类定义）。
 
 ## 技术栈与目标
 
-- 语言：Go（见 `go.mod`，当前 `go 1.23`）。
+- 语言：Go（见 `go.mod`，当前 `go 1.25`）。
 - 项目类型：CLI 框架，核心能力包括命令树、标志解析、参数解析、中间件链、帮助系统。
 - 在修改实现时，优先保持现有公开 API 与行为兼容，避免无关重构。
 
@@ -35,22 +33,61 @@
 
 ## 架构边界（修改前先定位）
 
-- `command.go`：命令分发与执行主流程（含子命令解析、运行入口）。
-- `option.go`：`OptionSet` 到 flag 的映射，默认值与环境变量回退逻辑。
-- `args.go`：位置参数 / query / form / JSON 参数解析与全局标志。
-- `help.go` + `help.tpl`：帮助信息渲染与模板。
-- `cmds/completioncmd/`：补全命令集成。
+### 核心模块
+
+- `command.go`：命令分发与执行主流程（`Invocation.Run` → `inv.run`），含子命令解析、运行入口。
+- `option.go`：`OptionSet` 到 flag 的映射；`FlagSet()` 先注册 flag，再按 `Envs` 做环境回退，最后由 CLI 输入覆盖。
+- `args.go`：位置参数 / query / form / JSON 参数解析与全局标志（`GlobalFlags()`）。
+- `flags.go`：自定义 `pflag.Value` 类型（Enum/Regexp/Struct/CSV 等）+ YAML/JSON 编解码。
+- `handler.go`：`HandlerFunc` / `ResponseHandler` / `ResponseStreamHandler`，Unary 与 Stream 两类响应模型。
+- `help.go` + `help.tpl`：模板驱动帮助渲染，终端宽度自适应、彩色样式。
+
+### 扩展命令模块（`cmds/`）
+
+- `completioncmd/`：Shell 补全命令集成（bash/zsh/fish）。
+- `mcpcmd/`：MCP stdio server 集成。
+- `readlinecmd/` / `richlinecmd/`：交互式 readline 命令驱动。
+- `webcmd/` / `webttycmd/`：Web UI 与 WebTTY 远程终端能力。
+
+### 内部包（`internal/`）
+
+- `gitshell`：git 命令执行与工作区状态判断。
+- `mcpserver`：命令树 → MCP tools 映射。
+- `pretty`：内部化文本样式与格式化（替代外部 `coder/pretty`）。
+- `webui`：Web UI 命令元数据、PTY 信号适配、静态资源嵌入。
+
+## 关键运行规则（不要破坏）
+
+- 子命令解析同时支持空格路径（`app repo commit`）与冒号路径（`app repo:commit`）——见 `getExecCommand`。
+- 分发优先级：显式子命令 > `argv0` busybox 分发 > 根命令（`getExecCommand` + `resolveArgv0Command`）。
+- 子命令继承父标志；同名时深层命令标志覆盖浅层（`copyFlagSetWithout`）。
+- `--list-commands` / `--list-flags` 在 Handler 前短路执行。
+- Required 选项判定认可三类来源：显式 flag、默认值、配置了 env 键列表。
 
 ## 项目特有约定
 
-- 子命令调用支持两种形式：空格路径（`a b c`）与冒号路径（`a b:c`）。
 - 参数形态支持：位置参数、query（`&`）、form（空格分隔 `k=v`）、JSON。
-- 解析优先级：显式子命令 > `argv0` 分发 > 根命令 > 标志与参数解析。
 - 测试优先使用表驱动与子测试，覆盖 flag 继承、argv0 分发、参数解析边界。
+- Unary/Stream 响应输出采用 NDJSON envelope：`{"$":"resp|error","type":"...","data":...}`。
+
+## 集成点与依赖
+
+- CLI 标志引擎：`github.com/spf13/pflag`（自定义值类型见 `flags.go`）。
+- 帮助输出格式：`github.com/muesli/termenv` + `github.com/mitchellh/go-wordwrap` + `internal/pretty`。
+- MCP：`github.com/modelcontextprotocol/go-sdk`。
+- YAML/JSON 值包装：`flags.go` + `gopkg.in/yaml.v3`。
+
+## 变更落点清单
+
+- 命令分发/执行 → 改 `command.go`，补 `command_test.go`。
+- flag/env/default 语义 → 改 `option.go`，补对应测试。
+- 参数格式行为 → 改 `args.go`，同步 `example/args-test/`。
+- 帮助/补全体验 → 改 `help.go`/`help.tpl` 或 `cmds/completioncmd/`。
+- 值类型 → 改 `flags.go`，补 `flags_test.go`。
 
 ## 文档与变更同步
 
-- 文档入口：`docs/INDEX.md`。
+- 文档入口：`docs/INDEX.md`（目录索引见 `docs/DOCS_CATALOG.md`）。
 - 涉及架构或流程变化时，先更新 `docs/DESIGN.md`，再补示例/说明文档。
 - 行为变更需同步 `.version/changelog/Unreleased.md`，必要时更新 `docs/EVALUATION.md`。
 - 文档默认使用中文，流程图优先 Mermaid。
@@ -66,15 +103,10 @@
 
 - `task test` 含 `-race` 与覆盖率，执行耗时可能较高。
 - `Taskfile.yml` 声明了 `dotenv: [".env"]`；若任务依赖环境变量，请显式在 `.env` 中补齐占位键。
-- changelog 维护采用 agent/LLM 流程，优先使用 `/changelog-maintenance draft|release`。
+- changelog 维护采用 agent/LLM 流程，优先使用 `/changelog draft|release`。
 
 ## 参考文件
 
-- `README.md`
-- `Taskfile.yml`
-- `docs/USAGE_AT_A_GLANCE.md`
-- `docs/DESIGN.md`
-- `command.go`
-- `option.go`
-- `args.go`
-- `docs/CHANGELOG_LLM_PROMPT.md`
+- `README.md`、`Taskfile.yml`
+- `docs/DESIGN.md`、`docs/USAGE_AT_A_GLANCE.md`
+- 核心源码：`command.go`、`option.go`、`args.go`、`flags.go`、`handler.go`

.github/instructions/changelog.instructions.md

@@ -16,19 +16,20 @@ applyTo: ".version/changelog/*.md"
 ## 内容约束
 
 - 仅基于可见改动编写条目，不杜撰能力或影响。
-- 单条应简洁、可读、可追溯，尽量以动词开头。
+- 单条应简洁、可读、可追溯，以动词开头。
 - 重复事项需合并去重，避免同义重复。
+- 非标准分类（如 `优化`、`重构`）必须归入标准四类（通常归 `变更`）。
 - 不改写历史版本文件语义，不重排已发布版本。
 
 ## 落版约束（release）
 
 - 版本号来源于 `.version/VERSION`。
 - 落版文件：`.version/changelog/<VERSION>.md`。
 - 文件头格式：`# [<VERSION>] - <YYYY-MM-DD>`。
-- 落版后需重建 `.version/changelog/Unreleased.md` 模板（四个分类）。
-- 落版后需同步更新 `.version/changelog/README.md` 索引。
+- 落版前检查版本文件是否已存在，已存在时提示用户确认。
+- 落版后重建 `.version/changelog/Unreleased.md` 模板（四个分类）。
+- 落版后同步更新 `.version/changelog/README.md` 索引。
 
 ## 协同建议
 
-- 优先参考：`docs/CHANGELOG_LLM_PROMPT.md`。
-- 建议通过 agent 提示词执行：`/changelog-maintenance draft|release`。
+- 建议通过 agent 提示词执行：`/changelog draft|release`。

.github/instructions/coding.instructions.md

@@ -25,7 +25,7 @@ applyTo: "**/*.go"
 ## 文件落点约定
 
 - 命令分发/执行流程改动：优先落在 `command.go`，并补 `command_test.go`。
-- flag/env/default 语义改动：优先改 `option.go` / `env_preload.go`，并补对应测试。
+- flag/env/default 语义改动：优先改 `option.go`，并补对应测试。
 - 参数格式与解析改动：优先改 `args.go`，并验证示例或测试覆盖。
 - 帮助与补全体验改动：改 `help.go`/`help.tpl` 或 `cmds/completioncmd/`，并验证输出。
 

.github/instructions/documentation.instructions.md

@@ -32,5 +32,4 @@ applyTo: "**/*.md"
 ## Changelog 联动
 
 - 变更日志遵循 `.version/changelog/` 现有结构：`新增 / 修复 / 变更 / 文档`。
-- 自动维护建议优先参考 `docs/CHANGELOG_LLM_PROMPT.md`。
-- 发布前落版建议通过 agent 提示词执行：`/changelog-maintenance draft|release`。
+- 建议通过 agent 提示词执行：`/changelog draft|release`。