Feat/ai gen

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

@@ -17,7 +17,7 @@ user-invocable: true
 - 严格区分问题等级：Blocker / Major / Minor / Nit。
 - 禁止无证据结论；禁止跨轮跳步。
 - 审查覆盖必须完整：
-  - 模块范围：PR 变更涉及的所有模块（如 command / args / env_preload / help / completion / docs 等）
+  - 模块范围：PR 变更涉及的所有模块（如 command / args / 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`
 
 ## 输入优先级
@@ -61,7 +61,7 @@ user-invocable: true
 - 发布前必须执行去重：以 `path + line + 分类 + 模块 + 等级 + 问题摘要` 作为唯一键检查已有评论；若已存在同键评论，则不重复发布，直接复用并回传已有评论链接。
 - 每条评论必须使用统一模板，且包含以下六部分：
   - 分类：必须使用分类代码标签与名称（如 `[LOGI] 逻辑问题`、`[SEC] 安全问题`），分类集合以 `docs/review/CODE_REVIEW_GUIDE_CN.md` 为准。
-  - 模块：问题所属模块（如 command / args / env_preload / help / completion / docs）。
+  - 模块：问题所属模块（如 command / args / help / completion / docs）。
   - 等级：Blocker / Major / Minor / Nit。
   - 问题：一句话描述发现的问题。
   - 原因：说明为何这是问题（语义风险/兼容性/可维护性/测试缺口）。
@@ -78,7 +78,7 @@ user-invocable: true
 ## 防遗漏硬门禁（必须）
 
 - Round 0 必须输出“模块覆盖矩阵”：模块名 / 变更文件数 / 审查状态（已检查/未检查）/ 证据。
-- 每个模块至少提供 1 条证据；高风险模块（command/args/env_preload/web/webtty/webui/mcp/completion）至少 2 条证据。
+- 每个模块至少提供 1 条证据；高风险模块（command/args/web/webtty/webui/mcp/completion）至少 2 条证据。
 - 模块若结论为“无问题”，仍需给出“低风险依据”（如测试覆盖、边界防护、输入校验）。
 - 只要存在“未检查模块”，禁止进入 Round 4。
 - Round 4 前必须满足：`modules_total == modules_checked`，否则仅允许输出“未完成审查 + 所缺清单”。

.github/copilot-instructions.md

@@ -3,7 +3,7 @@
 ## 适用范围
 
 - 本文件是仓库级 always-on 指引，适用于整个 `redant` 工作区。
-- 不再额外创建 `AGENTS.md`，避免两套同类指引并存。
+- 本文件为唯一工作区指引入口。
 
 ## 代码审查模式入口
 
@@ -16,7 +16,7 @@
 
 ## 技术栈与目标
 
-- 语言：Go（见 `go.mod`，当前 `go 1.23`）。
+- 语言：Go（见 `go.mod`，当前 `go 1.25`）。
 - 项目类型：CLI 框架，核心能力包括命令树、标志解析、参数解析、中间件链、帮助系统。
 - 在修改实现时，优先保持现有公开 API 与行为兼容，避免无关重构。
 
@@ -35,22 +35,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 +105,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`。

.github/instructions/release.instructions.md

@@ -15,12 +15,13 @@ description: "Use when preparing a release or completing behavior-impacting chan
 
 ## 质量门槛
 
-- 至少完成相关范围测试；条件允许时执行完整测试回归。
+- 执行完整回归：`task test`、`task vet`、`task lint`，三项均通过。
 - 不以“暂时跳过测试/校验”作为发布前状态。
 - 仅基于真实改动与真实测试结果编写发布说明，不杜撰。
 
-## 落版约束提示
+## 落版流程
 
-- 若进入正式落版，版本号来源于 `.version/VERSION`。
-- 落版后应重建 `Unreleased` 模板并更新 changelog 索引。
+- 首选通过 agent 提示词执行：`/changelog release`。
+- 版本号来源于 `.version/VERSION`；若版本文件已存在，需确认是否递增。
+- 落版后重建 `Unreleased` 模板并更新 changelog 索引。
 - changelog 结构与落版细节以 `.github/instructions/changelog.instructions.md` 为准。

.github/instructions/testing.instructions.md

@@ -21,7 +21,6 @@ applyTo: "**/*_test.go"
 - 标志行为：继承、重名覆盖、默认值/env 回退、required 判定。
 - 参数解析：位置参数、query、form、JSON 及边界输入。
 - 特殊开关：`--list-commands` / `--list-flags` 的短路行为。
-- env 预加载：`--env` / `-e` / `--env-file` 与恢复逻辑。
 
 ## 质量约束
 

.github/prompts/changelog.prompt.md

@@ -0,0 +1,59 @@
+---
+name: changelog
+description: 维护 .version/changelog（更新 Unreleased 或执行版本落版）
+argument-hint: "模式：draft（更新 Unreleased）或 release（按 .version/VERSION 落版）"
+agent: agent
+---
+
+你是本仓库的 Changelog 维护助手。
+
+## 目标
+
+- `draft` 模式：根据当前改动更新 `.version/changelog/Unreleased.md`。
+- `release` 模式：将 `Unreleased.md` 落版为版本文件，并重建空模板。
+
+## 必读上下文
+
+在开始前先读取：
+
+- `.version/changelog/Unreleased.md`
+- `.version/VERSION`
+
+## 通用规则
+
+1. 只基于可见改动生成条目，不杜撰。
+2. **标准分类**：`新增` / `修复` / `变更` / `文档`。
+   - 非标准分类（如 `优化`、`重构`）必须归入上述四类（通常归 `变更`）。
+3. 语言使用中文技术文风，单条以动词开头，简洁可追溯。
+4. 去重：同类项合并，避免语义重复。
+5. 不改写历史版本文件语义与顺序。
+
+## draft 模式
+
+1. 获取工作区 diff：运行 `git diff main --stat` 和 `git diff main --name-only` 确认改动范围。
+2. 仅更新 `.version/changelog/Unreleased.md`。
+3. 若缺少分类小节则补齐；无内容的小节写"暂无"。
+4. 归类规则：
+   - feat / 新增能力 → `新增`
+   - fix / bug 修正 → `修复`
+   - 重构、依赖迁移、行为调整、优化 → `变更`
+   - README、docs、注释更新 → `文档`
+
+## release 模式
+
+1. 读取 `.version/VERSION` 获取目标版本号（如 `v0.3.0`）。
+2. **版本冲突检查**：若 `.version/changelog/<VERSION>.md` 已存在，提示用户确认是否需要递增版本号，不自行覆盖。
+3. 创建版本文件 `.version/changelog/<VERSION>.md`：
+   - 标题格式：`# [<VERSION>] - <YYYY-MM-DD>`。
+   - 将 `Unreleased.md` 的内容迁移过去（分类统一为标准四类）。
+4. 重建 `Unreleased.md` 空模板（四个分类均写"暂无"）。
+5. 更新 `.version/changelog/README.md` 索引：在列表顶部（`Unreleased` 之后）插入新版本链接。
+6. 更新 `.version/VERSION` 为下一个预期版本号（**仅在用户确认后**，否则保持当前值）。
+
+## 输出要求
+
+- 直接给出文件修改结果。
+- 末尾附一段简短自检：
+  - 是否仅改动 `.version/` 范围内的文件；
+  - 分类是否统一为标准四类，是否完成去重；
+  - 历史版本文件是否未被修改。

.github/prompts/pr-review-round.prompt.md

@@ -18,7 +18,7 @@ agent: "PR 分轮审查代理"
 - 结论必须给证据（文件路径 + 关键片段）
 - 问题建议必须使用 `[分类]` 前缀（如 `[LOGI]`、`[SEC]`、`[PERF]`）
 - Round 0 必须输出“模块覆盖矩阵”（模块 / 变更文件数 / 状态 / 证据）
-- 每个模块至少 1 条证据；高风险模块（command/args/env_preload/web/webtty/webui/mcp/completion）至少 2 条证据
+- 每个模块至少 1 条证据；高风险模块（command/args/web/webtty/webui/mcp/completion）至少 2 条证据
 - 模块即使“无问题”也必须给出低风险依据
 - 若存在未检查模块，禁止进入 Round 4
 - Round 4 最终结论必须包含“全分类勾选清单（26 类）”，并标注每类 `已检查 / N/A`