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。
@@ -70,11 +109,6 @@
 
 ## 参考文件
 
-- `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`、`docs/CHANGELOG_LLM_PROMPT.md`
+- 核心源码：`command.go`、`option.go`、`args.go`、`flags.go`、`handler.go`

.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/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/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`

.github/skills/add-command/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: add-command
+description: "Add a new subcommand to a redant CLI app. Use when: adding subcommand, creating CLI command, new command with flags and options, extending command tree, adding middleware."
+argument-hint: "命令名称，如 deploy"
+---
+
+# 添加子命令
+
+## 使用场景
+
+- 给现有 redant CLI 应用添加新的子命令
+- 需要带选项、参数、中间件的完整命令
+
+## 操作步骤
+
+### 1. 确定命令位置
+
+子命令通过 `Children` 挂载。确认挂载到哪个父命令下：
+
+```go
+// 一级子命令
+rootCmd.Children = append(rootCmd.Children, newCmd)
+
+// 二级子命令
+parentCmd.Children = append(parentCmd.Children, newCmd)
+```
+
+### 2. 定义命令
+
+#### 最小命令（仅 Handler）
+
+```go
+cmd := &redant.Command{
+	Use:   "<name>",
+	Short: "<描述>",
+	Handler: func(ctx context.Context, inv *redant.Invocation) error {
+		fmt.Fprintln(inv.Stdout, "done")
+		return nil
+	},
+}
+```
+
+#### 带选项的命令
+
+```go
+var (
+	output string
+	force  bool
+	count  int64
+)
+
+cmd := &redant.Command{
+	Use:   "<name> [args...]",
+	Short: "<描述>",
+	Options: redant.OptionSet{
+		{
+			Flag:        "output",
+			Shorthand:   "o",
+			Description: "输出格式",
+			Default:     "text",
+			Value:       redant.EnumOf(&output, "text", "json", "yaml"),
+		},
+		{
+			Flag:        "force",
+			Shorthand:   "f",
+			Description: "强制执行",
+			Value:       redant.BoolOf(&force),
+		},
+		{
+			Flag:        "count",
+			Description: "数量",
+			Value:       redant.Int64Of(&count),
+			Default:     "10",
+			Envs:        []string{"APP_COUNT"},  // 环境变量回退
+			Required:    true,                    // 必填
+		},
+	},
+	Handler: func(ctx context.Context, inv *redant.Invocation) error {
+		fmt.Fprintf(inv.Stdout, "output=%s force=%v count=%d args=%v\n",
+			output, force, count, inv.Args)
+		return nil
+	},
+}
+```
+
+#### 带中间件的命令
+
+```go
+cmd := &redant.Command{
+	Use:   "<name>",
+	Short: "<描述>",
+	Middleware: redant.Chain(
+		func(next redant.HandlerFunc) redant.HandlerFunc {
+			return func(ctx context.Context, inv *redant.Invocation) error {
+				// 前置逻辑
+				fmt.Fprintln(inv.Stderr, "middleware: before")
+				err := next(ctx, inv)
+				// 后置逻辑
+				fmt.Fprintln(inv.Stderr, "middleware: after")
+				return err
+			}
+		},
+	),
+	Handler: func(ctx context.Context, inv *redant.Invocation) error {
+		return nil
+	},
+}
+```
+
+#### 带位置参数定义
+
+```go
+cmd := &redant.Command{
+	Use:   "<name> <file> [message]",
+	Short: "<描述>",
+	Args: redant.ArgSet{
+		{Name: "file", Description: "目标文件", Value: redant.StringOf(new(string))},
+		{Name: "message", Description: "提交信息", Value: redant.StringOf(new(string))},
+	},
+	Handler: func(ctx context.Context, inv *redant.Invocation) error {
+		// inv.Args[0] = file, inv.Args[1] = message
+		return nil
+	},
+}
+```
+
+### 3. 可用值类型速查
+
+| 类型 | 构造函数 | 示例 |
+|---|---|---|
+| 字符串 | `redant.StringOf(&s)` | `--name alice` |
+| 布尔 | `redant.BoolOf(&b)` | `--verbose` |
+| 整数 | `redant.Int64Of(&n)` | `--count 5` |
+| 浮点 | `redant.Float64Of(&f)` | `--rate 0.95` |
+| 时长 | `redant.DurationOf(&d)` | `--timeout 30s` |
+| URL | `redant.URLOf(&u)` | `--endpoint https://...` |
+| 枚举 | `redant.EnumOf(&s, "a","b","c")` | `--level info` |
+| 枚举数组 | `redant.EnumArrayOf(&ss, "a","b")` | `--tags feat,fix` |
+| 字符串数组 | `redant.StringArrayOf(&ss)` | `--files a.go,b.go` |
+| 正则 | `&redant.Regexp{}` | `--pattern ^feat:` |
+| Host:Port | `&redant.HostPort{}` | `--addr 127.0.0.1:8080` |
+| 结构体 | `&redant.Struct[T]{Value: T{}}` | JSON/YAML 输入 |
+
+### 4. 选项字段完整参考
+
+```go
+redant.Option{
+	Flag:        "name",          // 长标志名（必填）
+	Shorthand:   "n",             // 短标志名
+	Description: "说明文字",       // 帮助文本
+	Default:     "value",         // 默认值（字符串形式）
+	Envs:        []string{"KEY"}, // 环境变量回退列表
+	Required:    true,            // 是否必填
+	Hidden:      true,            // 帮助中隐藏
+	Deprecated:  "use --new",     // 弃用提示
+	Value:       redant.StringOf(&s), // 值绑定
+}
+```
+
+## 命名规约
+
+- `Use` 首词即命令名：`Use: "deploy [env]"` → 命令名 `deploy`
+- 支持别名：`Aliases: []string{"dp"}`
+- 子命令可用空格或冒号调用：`app repo commit` = `app repo:commit`