feihong-code 0.2.3 → 0.6.0

package/docs//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -1,196 +1,196 @@
-# 飞虹 Code 用户手册
-
-> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-
-本手册面向**使用者**，讲解每个命令、工具与安全机制，并给出最佳实践。开发向内容见《架构与 API》《配置参考》。
-
----
-
-## 1. 安装与初始化
-
-```bash
-git clone https://github.com/wch887292/feihong-code.git
-cd feihong-code && npm install && npm run build
-cp .env.example .env      # 然后编辑填入 FH_PROVIDERS
-```
-
-- 未配置 `FH_PROVIDERS` → 自动**离线模式**（内置 Mock 闭环，零成本）。
-- 已配置 `FH_PROVIDERS` → **真实模型模式**。
-- 环境变量可从 `.env` 自动加载（仅注入未设置的键），也可直接 `export`。
-
----
-
-## 2. 命令详解
-
-### 2.1 单命令模式
-
-```bash
-fhcode "把 src/utils 的日期格式化抽成独立模块并补测试"
-```
-
-一次需求一次执行。编排器按 ReAct 循环：勘察 → 改码 → 测试/构建验证 → 总结。结束后打印最终结果、迭代次数、成本与日志路径。
-
-### 2.2 交互 REPL
-
-```bash
-fhcode          # 进入 REPL
-飞虹> 给登录页加一个表单校验
-飞虹> exit      # 退出
-```
-
-逐条输入需求，每条独立执行一次编排。适合探索式开发。
-
-### 2.3 多子代理并行 `--parallel`
-
-```bash
-fhcode --parallel "实现登录模块并且添加用户管理并且写集成测试"
-```
-
-- **分解**：按中文并列连词（`并且/同时/分别/以及` 等）拆分为多个子任务。
-- **隔离**：为每个子任务创建独立的 `git worktree`（独立目录 + 独立分支），子代理只在自己的 worktree 内读写，互不干扰。
-- **并发**：`Promise.allSettled` 并发执行；单子任务失败不影响其他。
-- **清理**：结束后强制移除所有 worktree，子代理产物不进入主仓库。
-- ⚠️ 真实模式下会并发调用 API，免费套餐易触发 429 限流（见 FAQ）。
-
-### 2.4 只读技能（不修改任何文件）
-
-| 命令 | 作用 | 示例 |
-| --- | --- | --- |
-| `/plan` | 生成结构化实现计划 | `fhcode /plan "实现登录并且添加支付"` |
-| `/grill` | 红队式代码审查（密钥/注入/穿越/校验/待办） | `fhcode /grill src` |
-| `/goal` | 分解并保存高层目标到 `~/.feihong-code/goals` | `fhcode /goal "搭建体系并且完善文档"` |
-
-三者均为只读，可放心在任何仓库运行。
-
-### 2.5 版本与帮助
-
-```bash
-fhcode --version   # 或 -v：版本 + 署名
-fhcode --help      # 或 -h：完整用法
-```
-
-### 2.6 恢复与审计（M3）
-
-每次任务都会把完整对话、迭代计数、成本、被改动文件落盘为会话检查点（`<runId>.session.json`），可随时恢复与审计。
-
-| 命令 | 作用 | 示例 |
-| --- | --- | --- |
-| `sessions` | 列出历史会话（状态 / 迭代 / 成本 / 文件数 / 更新时间） | `fhcode sessions` |
-| `resume <id>` | 从检查点重建对话并续跑中断任务（支持 8 位前缀） | `fhcode resume 6f7f734f` |
-| `diff [<id>]` | 展示会话作用域变更；省略 id 则显示当前工作区全量 diff | `fhcode diff 6f7f734f` |
-| `rollback <id> [--yes]` | 回滚会话产生的改动（**危险，必须 `--yes` 确认**） | `fhcode rollback 6f7f734f --yes` |
-
-**resume 适用场景**：进程崩溃、手动中断、达到最大迭代仍无结果。续跑会接着已有对话继续 ReAct 循环，直到产出最终答案，新过程仍写入同一 `runId` 的事件日志，审计连续。
-
-**diff / rollback 安全边界**：
-- 仅作用于本会话 `touchedFiles`（被 `write_file`/`edit_file` 创建或修改的文件），绝不整仓回滚。
-- `diff` 对已跟踪文件走 `git diff`，未跟踪文件走 `git diff --no-index` 展示新增内容。
-- `rollback` 对已跟踪文件 `git checkout --`，未跟踪文件直接删除；**未确认（`--yes`）或非 git 仓库时一律拒绝执行**，避免误删。
-
-### 2.7 企业能力（M4）
-
-企业模式默认开启（受 `FH_ENTERPRISE` 控制，设 `false` 即退回社区版无感行为）。开启后提供四类能力：
-
-| 命令 | 作用 | 示例 |
-| --- | --- | --- |
-| `whoami` | 查看当前租户 / 用户 / 角色 / 隔离目录 / 当日成本 | `fhcode whoami` |
-| `policy` | 渲染当前生效的策略矩阵（角色-工具、配额、黑名单） | `fhcode policy` |
-| `audit [--limit N]` | 查看审计链（脱敏后），`--limit` 控制条数 | `fhcode audit --limit 20` |
-| `audit verify` | 校验审计哈希链完整性，定位被篡改断点 | `fhcode audit verify` |
-| `tenants` | 列出所有租户及各自用量（成本/会话数，互不串台） | `fhcode tenants` |
-
-**权限（RBAC）**：四角色 `viewer / developer / operator / admin`，判定顺序 **deny 优先**：
-
-1. `run_shell` 命中危险命令（如 `rm -rf /`、`mkfs`、`curl|sh` 等 23 条）→ 直接拒绝；
-2. 访问敏感路径（`.env`、`.ssh`、`id_rsa`、`.git/config` 等 11 类）或越界沙箱 → 直接拒绝（**admin 也拦**）；
-3. 角色矩阵判定：deny / 需审批（approval）/ 允许；
-4. shell 白名单命中的命令免审批。
-
-**多租户隔离**：数据按 `<FH_HOME>/tenants/<tenantId>/{sessions,audit,goals}` 物理目录隔离，租户 ID 强制正则 `^[A-Za-z0-9._-]{1,64}$` 校验防穿越；未指定租户时兼容旧版 `<FH_HOME>/sessions`。
-
-**成本治理**：单任务 `maxCostUsd` 熔断（达上限即终止并给结论）+ 租户日预算 `FH_TENANT_BUDGET_USD` fail-fast（任务启动前拦截，超限返回 `QUOTA_EXCEEDED`）。
-
-**审计**：每次工具执行前由「守卫（guard）」一次性完成 *策略判定→人工审批→审计留痕*，写入按月切分的 `audit-YYYY-MM.jsonl`，采用 **sha256 哈希链（防篡改）**，敏感字段自动脱敏。可用 `audit verify` 检验链完整性。
-
----
-
-## 3. 工具系统
-
-智能体在真实模式下可调用以下 8 个工具（离线模式用 Mock 模拟）：
-
-| 工具 | 用途 | 关键参数 | 安全约束 |
-| --- | --- | --- | --- |
-| `read_file` | 读文件 | `path` | 沙箱内 |
-| `write_file` | 写/覆盖文件 | `path`, `content` | 沙箱内，自动建父目录 |
-| `edit_file` | 精确替换 | `path`, `oldText`, `newText` | 沙箱内 |
-| `list_dir` | 列目录 | `path`（可选） | 沙箱内 |
-| `grep` | 递归搜索 | `pattern`, `path`（可选） | 忽略 node_modules/.git |
-| `run_shell` | 执行命令 | `command` | **白名单 + 审批** |
-| `run_tests` | 跑测试 | `command`（默认 `npm test`） | 同 run_shell 调度 |
-| `build_check` | 构建校验 | `command`（默认 `npm run build`） | 同 run_shell 调度 |
-
-所有工具入参经 zod 校验，异常归一为 `ToolError`，不会让进程崩溃。
-
----
-
-## 4. 审批与安全模型
-
-- **路径沙箱**：任何文件操作只允许在 `cwd`（当前目录或子代理 worktree）内，越界（`../` 等）直接拒绝。
-- **Shell 白名单**：`run_shell` 仅当命令首词（如 `git`、`npm`）命中 `FH_SHELL_ALLOW` 才放行；否则直接拒绝。
-- **默认审批器**（非交互 CLI）：命中白名单者自动通过；未命中者拒绝并写日志。若设置 `FH_REQUIRE_APPROVAL=false` 则完全放开（不推荐）。
-- **交互式审批（M3）**：当运行在 TTY 终端时，危险操作（如 `run_shell`、写文件）会**逐条弹出 `y/n` 确认**，须用户显式批准才执行；非 TTY（CI / 管道）自动回退到上述白名单审批器。
-- **密钥脱敏**：日志中 `apikey/secret/token/...` 字段值一律 `[REDACTED]`；企业审计日志亦对 `apiKey=/secret=/sk-*` 等做 `***` 替换。
-- **`.env` 不入库**：`gitignore` + `package.json` 的 `files` 白名单双重保障。
-- **企业权限（M4）**：四角色 RBAC + deny 优先矩阵，危险命令/敏感路径在角色判定前即拦截（含 admin）。未注入企业 guard 时行为同社区版，可用 `FH_ENTERPRISE=false` 关闭。
-- **防篡改审计（M4）**：工具执行前由守卫统一留痕，审计日志按月切分并以 sha256 哈希链串联，任意篡改均会被 `audit verify` 定位断点。
-- **多租户隔离（M4）**：租户数据按物理目录隔离，ID 正则防穿越，成本与审计互不串台。
-- **成本熔断（M4）**：单任务成本上限 + 租户日预算双重熔断，超限直接拒绝不静默放行。
-
----
-
-## 5. 真实模型接入（示例）
-
-已验证可用的 Agnes 网关配置（写入 `.env`）：
-
-```bash
-FH_PROVIDERS='[{"id":"agnes","type":"openai-compatible","baseURL":"https://api.agnes-ai.cn/v1","apiKey":"<你的key>","model":"agnes-2.5-flash","tags":["code-gen"],"costPer1k":0.001}]'
-FH_MODEL_STRATEGY=cost
-FH_SHELL_ALLOW=git,npm,node,ls,cat
-FH_REQUIRE_APPROVAL=true
-```
-
-更多供应商（DeepSeek / 通义 / Ollama）见《配置参考》。
-
----
-
-## 6. 最佳实践
-
-1. **先只读探查**：大改前先 `/grill src` 看风险、`/plan "..."` 看方案。
-2. **注意 cwd**：真实模式下 `cwd = 当前目录`，文件写入/命令执行都作用于此。建议从**干净目录**或**专用仓库**运行，避免误改。
-3. **并行用隔离**：多模块任务优先 `--parallel`，物理隔离最安全。
-4. **白名单最小化**：`FH_SHELL_ALLOW` 只放确实需要的命令。
-5. **离线先验证**：CI 或演示用 `FH_OFFLINE=true`，零成本且确定性强。
-6. **看日志**：每次运行生成 `~/.feihong-code/sessions/<runId>.jsonl`，排错首选。
-
----
-
-## 7. 典型工作流
-
-```
-# 1) 评估现状（只读）
-fhcode /grill src
-fhcode /plan "重构配置模块并且补集成测试"
-
-# 2) 并行推进（隔离）
-fhcode --parallel "重构配置模块并且补集成测试"
-
-# 3) 单点精修（真实改码）
-fhcode "把配置校验抽到 config.ts 并补单测"
-
-# 4) 目标跟踪
-fhcode /goal "Q3 完成模块化与测试覆盖率 80%"
-```
-
----
-
-© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+# 飞虹 Code 用户手册
+
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+本手册面向**使用者**，讲解每个命令、工具与安全机制，并给出最佳实践。开发向内容见《架构与 API》《配置参考》。
+
+---
+
+## 1. 安装与初始化
+
+```bash
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code && npm install && npm run build
+cp .env.example .env      # 然后编辑填入 FH_PROVIDERS
+```
+
+- 未配置 `FH_PROVIDERS` → 自动**离线模式**（内置 Mock 闭环，零成本）。
+- 已配置 `FH_PROVIDERS` → **真实模型模式**。
+- 环境变量可从 `.env` 自动加载（仅注入未设置的键），也可直接 `export`。
+
+---
+
+## 2. 命令详解
+
+### 2.1 单命令模式
+
+```bash
+fhcode "把 src/utils 的日期格式化抽成独立模块并补测试"
+```
+
+一次需求一次执行。编排器按 ReAct 循环：勘察 → 改码 → 测试/构建验证 → 总结。结束后打印最终结果、迭代次数、成本与日志路径。
+
+### 2.2 交互 REPL
+
+```bash
+fhcode          # 进入 REPL
+飞虹> 给登录页加一个表单校验
+飞虹> exit      # 退出
+```
+
+逐条输入需求，每条独立执行一次编排。适合探索式开发。
+
+### 2.3 多子代理并行 `--parallel`
+
+```bash
+fhcode --parallel "实现登录模块并且添加用户管理并且写集成测试"
+```
+
+- **分解**：按中文并列连词（`并且/同时/分别/以及` 等）拆分为多个子任务。
+- **隔离**：为每个子任务创建独立的 `git worktree`（独立目录 + 独立分支），子代理只在自己的 worktree 内读写，互不干扰。
+- **并发**：`Promise.allSettled` 并发执行；单子任务失败不影响其他。
+- **清理**：结束后强制移除所有 worktree，子代理产物不进入主仓库。
+- ⚠️ 真实模式下会并发调用 API，免费套餐易触发 429 限流（见 FAQ）。
+
+### 2.4 只读技能（不修改任何文件）
+
+| 命令 | 作用 | 示例 |
+| --- | --- | --- |
+| `/plan` | 生成结构化实现计划 | `fhcode /plan "实现登录并且添加支付"` |
+| `/grill` | 红队式代码审查（密钥/注入/穿越/校验/待办） | `fhcode /grill src` |
+| `/goal` | 分解并保存高层目标到 `~/.feihong-code/goals` | `fhcode /goal "搭建体系并且完善文档"` |
+
+三者均为只读，可放心在任何仓库运行。
+
+### 2.5 版本与帮助
+
+```bash
+fhcode --version   # 或 -v：版本 + 署名
+fhcode --help      # 或 -h：完整用法
+```
+
+### 2.6 恢复与审计（M3）
+
+每次任务都会把完整对话、迭代计数、成本、被改动文件落盘为会话检查点（`<runId>.session.json`），可随时恢复与审计。
+
+| 命令 | 作用 | 示例 |
+| --- | --- | --- |
+| `sessions` | 列出历史会话（状态 / 迭代 / 成本 / 文件数 / 更新时间） | `fhcode sessions` |
+| `resume <id>` | 从检查点重建对话并续跑中断任务（支持 8 位前缀） | `fhcode resume 6f7f734f` |
+| `diff [<id>]` | 展示会话作用域变更；省略 id 则显示当前工作区全量 diff | `fhcode diff 6f7f734f` |
+| `rollback <id> [--yes]` | 回滚会话产生的改动（**危险，必须 `--yes` 确认**） | `fhcode rollback 6f7f734f --yes` |
+
+**resume 适用场景**：进程崩溃、手动中断、达到最大迭代仍无结果。续跑会接着已有对话继续 ReAct 循环，直到产出最终答案，新过程仍写入同一 `runId` 的事件日志，审计连续。
+
+**diff / rollback 安全边界**：
+- 仅作用于本会话 `touchedFiles`（被 `write_file`/`edit_file` 创建或修改的文件），绝不整仓回滚。
+- `diff` 对已跟踪文件走 `git diff`，未跟踪文件走 `git diff --no-index` 展示新增内容。
+- `rollback` 对已跟踪文件 `git checkout --`，未跟踪文件直接删除；**未确认（`--yes`）或非 git 仓库时一律拒绝执行**，避免误删。
+
+### 2.7 企业能力（M4）
+
+企业模式默认开启（受 `FH_ENTERPRISE` 控制，设 `false` 即退回社区版无感行为）。开启后提供四类能力：
+
+| 命令 | 作用 | 示例 |
+| --- | --- | --- |
+| `whoami` | 查看当前租户 / 用户 / 角色 / 隔离目录 / 当日成本 | `fhcode whoami` |
+| `policy` | 渲染当前生效的策略矩阵（角色-工具、配额、黑名单） | `fhcode policy` |
+| `audit [--limit N]` | 查看审计链（脱敏后），`--limit` 控制条数 | `fhcode audit --limit 20` |
+| `audit verify` | 校验审计哈希链完整性，定位被篡改断点 | `fhcode audit verify` |
+| `tenants` | 列出所有租户及各自用量（成本/会话数，互不串台） | `fhcode tenants` |
+
+**权限（RBAC）**：四角色 `viewer / developer / operator / admin`，判定顺序 **deny 优先**：
+
+1. `run_shell` 命中危险命令（如 `rm -rf /`、`mkfs`、`curl|sh` 等 23 条）→ 直接拒绝；
+2. 访问敏感路径（`.env`、`.ssh`、`id_rsa`、`.git/config` 等 11 类）或越界沙箱 → 直接拒绝（**admin 也拦**）；
+3. 角色矩阵判定：deny / 需审批（approval）/ 允许；
+4. shell 白名单命中的命令免审批。
+
+**多租户隔离**：数据按 `<FH_HOME>/tenants/<tenantId>/{sessions,audit,goals}` 物理目录隔离，租户 ID 强制正则 `^[A-Za-z0-9._-]{1,64}$` 校验防穿越；未指定租户时兼容旧版 `<FH_HOME>/sessions`。
+
+**成本治理**：单任务 `maxCostUsd` 熔断（达上限即终止并给结论）+ 租户日预算 `FH_TENANT_BUDGET_USD` fail-fast（任务启动前拦截，超限返回 `QUOTA_EXCEEDED`）。
+
+**审计**：每次工具执行前由「守卫（guard）」一次性完成 *策略判定→人工审批→审计留痕*，写入按月切分的 `audit-YYYY-MM.jsonl`，采用 **sha256 哈希链（防篡改）**，敏感字段自动脱敏。可用 `audit verify` 检验链完整性。
+
+---
+
+## 3. 工具系统
+
+智能体在真实模式下可调用以下 8 个工具（离线模式用 Mock 模拟）：
+
+| 工具 | 用途 | 关键参数 | 安全约束 |
+| --- | --- | --- | --- |
+| `read_file` | 读文件 | `path` | 沙箱内 |
+| `write_file` | 写/覆盖文件 | `path`, `content` | 沙箱内，自动建父目录 |
+| `edit_file` | 精确替换 | `path`, `oldText`, `newText` | 沙箱内 |
+| `list_dir` | 列目录 | `path`（可选） | 沙箱内 |
+| `grep` | 递归搜索 | `pattern`, `path`（可选） | 忽略 node_modules/.git |
+| `run_shell` | 执行命令 | `command` | **白名单 + 审批** |
+| `run_tests` | 跑测试 | `command`（默认 `npm test`） | 同 run_shell 调度 |
+| `build_check` | 构建校验 | `command`（默认 `npm run build`） | 同 run_shell 调度 |
+
+所有工具入参经 zod 校验，异常归一为 `ToolError`，不会让进程崩溃。
+
+---
+
+## 4. 审批与安全模型
+
+- **路径沙箱**：任何文件操作只允许在 `cwd`（当前目录或子代理 worktree）内，越界（`../` 等）直接拒绝。
+- **Shell 白名单**：`run_shell` 仅当命令首词（如 `git`、`npm`）命中 `FH_SHELL_ALLOW` 才放行；否则直接拒绝。
+- **默认审批器**（非交互 CLI）：命中白名单者自动通过；未命中者拒绝并写日志。若设置 `FH_REQUIRE_APPROVAL=false` 则完全放开（不推荐）。
+- **交互式审批（M3）**：当运行在 TTY 终端时，危险操作（如 `run_shell`、写文件）会**逐条弹出 `y/n` 确认**，须用户显式批准才执行；非 TTY（CI / 管道）自动回退到上述白名单审批器。
+- **密钥脱敏**：日志中 `apikey/secret/token/...` 字段值一律 `[REDACTED]`；企业审计日志亦对 `apiKey=/secret=/sk-*` 等做 `***` 替换。
+- **`.env` 不入库**：`gitignore` + `package.json` 的 `files` 白名单双重保障。
+- **企业权限（M4）**：四角色 RBAC + deny 优先矩阵，危险命令/敏感路径在角色判定前即拦截（含 admin）。未注入企业 guard 时行为同社区版，可用 `FH_ENTERPRISE=false` 关闭。
+- **防篡改审计（M4）**：工具执行前由守卫统一留痕，审计日志按月切分并以 sha256 哈希链串联，任意篡改均会被 `audit verify` 定位断点。
+- **多租户隔离（M4）**：租户数据按物理目录隔离，ID 正则防穿越，成本与审计互不串台。
+- **成本熔断（M4）**：单任务成本上限 + 租户日预算双重熔断，超限直接拒绝不静默放行。
+
+---
+
+## 5. 真实模型接入（示例）
+
+已验证可用的 Agnes 网关配置（写入 `.env`）：
+
+```bash
+FH_PROVIDERS='[{"id":"agnes","type":"openai-compatible","baseURL":"https://api.agnes-ai.cn/v1","apiKey":"<你的key>","model":"agnes-2.5-flash","tags":["code-gen"],"costPer1k":0.001}]'
+FH_MODEL_STRATEGY=cost
+FH_SHELL_ALLOW=git,npm,node,ls,cat
+FH_REQUIRE_APPROVAL=true
+```
+
+更多供应商（DeepSeek / 通义 / Ollama）见《配置参考》。
+
+---
+
+## 6. 最佳实践
+
+1. **先只读探查**：大改前先 `/grill src` 看风险、`/plan "..."` 看方案。
+2. **注意 cwd**：真实模式下 `cwd = 当前目录`，文件写入/命令执行都作用于此。建议从**干净目录**或**专用仓库**运行，避免误改。
+3. **并行用隔离**：多模块任务优先 `--parallel`，物理隔离最安全。
+4. **白名单最小化**：`FH_SHELL_ALLOW` 只放确实需要的命令。
+5. **离线先验证**：CI 或演示用 `FH_OFFLINE=true`，零成本且确定性强。
+6. **看日志**：每次运行生成 `~/.feihong-code/sessions/<runId>.jsonl`，排错首选。
+
+---
+
+## 7. 典型工作流
+
+```
+# 1) 评估现状（只读）
+fhcode /grill src
+fhcode /plan "重构配置模块并且补集成测试"
+
+# 2) 并行推进（隔离）
+fhcode --parallel "重构配置模块并且补集成测试"
+
+# 3) 单点精修（真实改码）
+fhcode "把配置校验抽到 config.ts 并补单测"
+
+# 4) 目标跟踪
+fhcode /goal "Q3 完成模块化与测试覆盖率 80%"
+```
+
+---
+
+© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹