feihong-code 0.2.3 → 0.6.0

package/docs//345/270/270/350/247/201/351/227/256/351/242/230/344/270/216/346/225/205/351/232/234/346/216/222/346/237/245.md

@@ -1,130 +1,130 @@
-# 飞虹 Code 常见问题与故障排查（FAQ）
-
-> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-
----
-
-## Q1. 离线模式和真实模式如何切换？
-
-- 未配置 `FH_PROVIDERS`（或设为 `[]`/`FH_OFFLINE=true`）→ **离线**（内置 Mock 闭环，零成本）。
-- 配置非空 `FH_PROVIDERS` → **真实模型**。
-- 临时离线：`FH_OFFLINE=true fhcode "..."`。
-
----
-
-## Q2. 真实并行（`--parallel`）子任务失败，提示 HTTP 429？
-
-**原因**：`--parallel` 会**并发**调用 API。免费套餐（如 Agnes free tier）对并发请求有严格限流，触发 `429 Too Many Requests`。
-
-**解决**：
-1. 升级 API 套餐（Token Plan）提高并发额度；
-2. 改用单命令模式顺序执行大目标：`fhcode "实现A并且添加B"`（单命令串行，不易触发）；
-3. 用 `FH_OFFLINE=true fhcode --parallel "..."` 验证并行机制（不耗额度）。
-
-> 代码路径本身正确：真实 `ModelRouter` 已接入，worktree 创建/清理正常，限流被优雅捕获（不崩溃、清理照常）。
-
----
-
-## Q3. 没配 `FH_HOME` 会崩溃吗？
-
-不会。自 v0.1.0 起 `FH_HOME` 可缺省，默认 `~/.feihong-code`（Windows 为 `%USERPROFILE%/.feihong-code`）。仅当显式设置错误路径时才可能异常。
-
----
-
-## Q4. `git worktree` 残留 / 清理失败？
-
-正常结束后 worktree 会被强制清理（含 Windows 上 git 顺序移除缺陷的鲁棒兜底）。
-
-若发现残留：
-```bash
-git worktree list              # 查看
-git worktree prune            # 清理元数据
-# 手动删除遗留的临时目录（通常在 %TEMP%/fhcode-wt-*）
-```
-子代理产品本就不进入主仓库，残留目录可直接删除。
-
----
-
-## Q5. shell 命令被拒（"已拒绝执行（需审批）"）？
-
-- `run_shell` 要求命令首词命中 `FH_SHELL_ALLOW` 白名单。
-- 非交互 CLI 下，命中白名单自动通过；未命中则拒绝。
-- 检查 `.env` 的 `FH_SHELL_ALLOW` 是否包含你的命令（如 `git,npm,node,ls,cat`）。
-
----
-
-## Q6. 密钥会泄露吗？
-
-- `.env` 已被 `.gitignore` 排除，且 `package.json` 的 `files` 白名单确保 `npm publish` 不含 `.env`。
-- 日志中 `apikey/secret/token/...` 值一律 `[REDACTED]`。
-- 我（助手）全程不回显完整 API key。
-- 建议 `.env` 权限 `chmod 600 .env`。
-
----
-
-## Q7. 构建失败（tsc 报错）？
-
-```bash
-rm -rf dist node_modules
-npm install
-npm run typecheck     # 先看类型错误
-npm run build
-```
-确保 Node >= 18 且 `npm install` 已成功（需要联网拉取 zod/typescript）。
-
----
-
-## Q8. 模型不调用工具，直接给文字？
-
-- 编排器默认带 `['code-gen']` 标签筛选 provider，确认 `FH_PROVIDERS` 中模型 `tags` 含 `code-gen`。
-- 温度固定 `0`，模型仍可能选择不调用工具（取决于模型能力）。
-- 若需强制工具使用，可在需求中明确"请使用 list_dir / read_file 等工具"。
-
----
-
-## Q9. Node 版本要求？
-
-`engines.node >= 18`。低于 18 可能出现语法/API 不兼容（如 `structuredClone`、`fetch` 全局）。
-
----
-
-## Q10. REPL 无法交互（自动化环境）？
-
-REPL 依赖标准输入交互。在 CI / 自动化脚本中请使用**单命令模式**或**离线模式**，而非 REPL。
-
----
-
-## Q11. 真实模式会改我的文件吗？
-
-会。`cwd = 当前目录`，`write_file`/`edit_file` 会直接修改当前工作区文件（受沙箱限制在 cwd 内）。建议：
-- 从干净目录或专用仓库运行；
-- 大改前先用 `/plan`、`/grill` 只读评估；
-- 多模块任务用 `--parallel`（worktree 隔离，不污染主目录）。
-
----
-
-## Q12. 成本怎么算？会超额吗？
-
-每次调用按 `costPer1k` × tokens 估算，任务结束打印总成本。超过 `FH_BUDGET_USD` 仅**告警**不阻断。离线模式成本恒为 0。
-
----
-
-## Q13.（企业）任务启动即报 `QUOTA_EXCEEDED`，怎么回事？
-
-说明**租户当日成本已超预算**。触发链：任务启动前 `assertQuota()` 会按 `FH_TENANT_BUDGET_USD`（缺省取角色上限）统计当日已用成本，超限即 fail-fast 拒绝新任务（HTTP 429 语义）。可用 `fhcode whoami` 查看「已用/预算」，或调高 `FH_TENANT_BUDGET_USD` / 次日再跑。注意这是**硬上限**，不会静默放行。
-
-## Q14.（企业）`audit verify` 报链断裂（brokenAt），是日志被改了吗？
-
-哈希链校验规则：每条记录 `hash = sha256(prevHash | seq | ts | tenant | ... | resource | decision)`，且 `prevHash` 必须衔接上一条、`seq` 连续。若某条被增删改，`audit verify` 会定位首个断点 `brokenAt` 行号。常见原因：手工编辑了 `audit-YYYY-MM.jsonl`、文件被截断、或拷贝时丢了行。建议从该断点之后重建或归档受损月份日志。
-
-## Q15.（企业）多租户之间会串数据吗？
-
-不会。每个租户数据落在独立的物理目录 `<FH_HOME>/tenants/<tenantId>/{sessions,audit,goals}`，且 `FH_TENANT` 值受正则 `^[A-Za-z0-9._-]{1,64}$` 强校验，禁止 `../` 等穿越字符。未设 `FH_TENANT` 时走默认租户（兼容旧 `<FH_HOME>/sessions`）。CI 中 `beta` 租户断言读不到 `acme` 租户会话，即验证此隔离。
-
-## Q16.（企业）如何完全关闭企业能力（退回社区版）？
-
-设 `FH_ENTERPRISE=false`，则 RBAC / 审计 / 多租户隔离全部不注入，运行行为与 M3 社区版完全一致，零额外开销。这是单开关、向后兼容设计。
-
----
-
-© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+# 飞虹 Code 常见问题与故障排查（FAQ）
+
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+---
+
+## Q1. 离线模式和真实模式如何切换？
+
+- 未配置 `FH_PROVIDERS`（或设为 `[]`/`FH_OFFLINE=true`）→ **离线**（内置 Mock 闭环，零成本）。
+- 配置非空 `FH_PROVIDERS` → **真实模型**。
+- 临时离线：`FH_OFFLINE=true fhcode "..."`。
+
+---
+
+## Q2. 真实并行（`--parallel`）子任务失败，提示 HTTP 429？
+
+**原因**：`--parallel` 会**并发**调用 API。免费套餐（如 Agnes free tier）对并发请求有严格限流，触发 `429 Too Many Requests`。
+
+**解决**：
+1. 升级 API 套餐（Token Plan）提高并发额度；
+2. 改用单命令模式顺序执行大目标：`fhcode "实现A并且添加B"`（单命令串行，不易触发）；
+3. 用 `FH_OFFLINE=true fhcode --parallel "..."` 验证并行机制（不耗额度）。
+
+> 代码路径本身正确：真实 `ModelRouter` 已接入，worktree 创建/清理正常，限流被优雅捕获（不崩溃、清理照常）。
+
+---
+
+## Q3. 没配 `FH_HOME` 会崩溃吗？
+
+不会。自 v0.1.0 起 `FH_HOME` 可缺省，默认 `~/.feihong-code`（Windows 为 `%USERPROFILE%/.feihong-code`）。仅当显式设置错误路径时才可能异常。
+
+---
+
+## Q4. `git worktree` 残留 / 清理失败？
+
+正常结束后 worktree 会被强制清理（含 Windows 上 git 顺序移除缺陷的鲁棒兜底）。
+
+若发现残留：
+```bash
+git worktree list              # 查看
+git worktree prune            # 清理元数据
+# 手动删除遗留的临时目录（通常在 %TEMP%/fhcode-wt-*）
+```
+子代理产品本就不进入主仓库，残留目录可直接删除。
+
+---
+
+## Q5. shell 命令被拒（"已拒绝执行（需审批）"）？
+
+- `run_shell` 要求命令首词命中 `FH_SHELL_ALLOW` 白名单。
+- 非交互 CLI 下，命中白名单自动通过；未命中则拒绝。
+- 检查 `.env` 的 `FH_SHELL_ALLOW` 是否包含你的命令（如 `git,npm,node,ls,cat`）。
+
+---
+
+## Q6. 密钥会泄露吗？
+
+- `.env` 已被 `.gitignore` 排除，且 `package.json` 的 `files` 白名单确保 `npm publish` 不含 `.env`。
+- 日志中 `apikey/secret/token/...` 值一律 `[REDACTED]`。
+- 我（助手）全程不回显完整 API key。
+- 建议 `.env` 权限 `chmod 600 .env`。
+
+---
+
+## Q7. 构建失败（tsc 报错）？
+
+```bash
+rm -rf dist node_modules
+npm install
+npm run typecheck     # 先看类型错误
+npm run build
+```
+确保 Node >= 18 且 `npm install` 已成功（需要联网拉取 zod/typescript）。
+
+---
+
+## Q8. 模型不调用工具，直接给文字？
+
+- 编排器默认带 `['code-gen']` 标签筛选 provider，确认 `FH_PROVIDERS` 中模型 `tags` 含 `code-gen`。
+- 温度固定 `0`，模型仍可能选择不调用工具（取决于模型能力）。
+- 若需强制工具使用，可在需求中明确"请使用 list_dir / read_file 等工具"。
+
+---
+
+## Q9. Node 版本要求？
+
+`engines.node >= 18`。低于 18 可能出现语法/API 不兼容（如 `structuredClone`、`fetch` 全局）。
+
+---
+
+## Q10. REPL 无法交互（自动化环境）？
+
+REPL 依赖标准输入交互。在 CI / 自动化脚本中请使用**单命令模式**或**离线模式**，而非 REPL。
+
+---
+
+## Q11. 真实模式会改我的文件吗？
+
+会。`cwd = 当前目录`，`write_file`/`edit_file` 会直接修改当前工作区文件（受沙箱限制在 cwd 内）。建议：
+- 从干净目录或专用仓库运行；
+- 大改前先用 `/plan`、`/grill` 只读评估；
+- 多模块任务用 `--parallel`（worktree 隔离，不污染主目录）。
+
+---
+
+## Q12. 成本怎么算？会超额吗？
+
+每次调用按 `costPer1k` × tokens 估算，任务结束打印总成本。超过 `FH_BUDGET_USD` 仅**告警**不阻断。离线模式成本恒为 0。
+
+---
+
+## Q13.（企业）任务启动即报 `QUOTA_EXCEEDED`，怎么回事？
+
+说明**租户当日成本已超预算**。触发链：任务启动前 `assertQuota()` 会按 `FH_TENANT_BUDGET_USD`（缺省取角色上限）统计当日已用成本，超限即 fail-fast 拒绝新任务（HTTP 429 语义）。可用 `fhcode whoami` 查看「已用/预算」，或调高 `FH_TENANT_BUDGET_USD` / 次日再跑。注意这是**硬上限**，不会静默放行。
+
+## Q14.（企业）`audit verify` 报链断裂（brokenAt），是日志被改了吗？
+
+哈希链校验规则：每条记录 `hash = sha256(prevHash | seq | ts | tenant | ... | resource | decision)`，且 `prevHash` 必须衔接上一条、`seq` 连续。若某条被增删改，`audit verify` 会定位首个断点 `brokenAt` 行号。常见原因：手工编辑了 `audit-YYYY-MM.jsonl`、文件被截断、或拷贝时丢了行。建议从该断点之后重建或归档受损月份日志。
+
+## Q15.（企业）多租户之间会串数据吗？
+
+不会。每个租户数据落在独立的物理目录 `<FH_HOME>/tenants/<tenantId>/{sessions,audit,goals}`，且 `FH_TENANT` 值受正则 `^[A-Za-z0-9._-]{1,64}$` 强校验，禁止 `../` 等穿越字符。未设 `FH_TENANT` 时走默认租户（兼容旧 `<FH_HOME>/sessions`）。CI 中 `beta` 租户断言读不到 `acme` 租户会话，即验证此隔离。
+
+## Q16.（企业）如何完全关闭企业能力（退回社区版）？
+
+设 `FH_ENTERPRISE=false`，则 RBAC / 审计 / 多租户隔离全部不注入，运行行为与 M3 社区版完全一致，零额外开销。这是单开关、向后兼容设计。
+
+---
+
+© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹