feihong-code 0.2.1

package/docs//344/272/247/345/223/201/345/274/200/345/217/221/346/226/207/346/241/243.md

@@ -0,0 +1,614 @@
+# 飞虹 Code（Muse Code 参照复刻）产品开发文档
+
+> 项目代号：**飞虹 Code / FeiHong Code**
+> 文档类型：完整产品开发文档（定位 + 架构 + 模块 + 接口 + 数据模型 + 里程碑 + 落地计划）
+> 版本：v0.1.0-draft
+> 日期：2026-08-10
+> 状态：实现中（M0、M1、M2、B 真实模型联调、部署就绪、M3 恢复与审计 已完成并通过验证；M4 待推进）
+
+---
+
+## 0. 署名与版权
+
+| 项 | 内容 |
+|----|------|
+| 公司 | 晋江市飞虹智科技企业管理有限公司 |
+| 中心 | 飞扬企源研发中心 |
+| 负责人 | 吴赐虹 |
+| 用途 | 版权声明、README、关于页、源码注释头部统一署名 |
+
+---
+
+## 1. 产品概述
+
+### 1.1 产品定位（一句话）
+
+**飞虹 Code 是一款运行在终端的 AI 编程智能体：用户用自然语言描述需求，它自主完成「规划 → 写码 → 执行 → 验证」的完整软件工程任务，并通过多子代理并行与长时任务恢复机制，在大型代码库中稳定交付。**
+
+### 1.2 背景与动机
+
+- Meta 于 2026-08 发布 **Muse Code**（终端 AI 编程 Agent，基于 Muse Spark 1.2），对标 Claude Code / OpenAI Codex，主打多智能体并行、长时任务、仓库级代码变更，并采用低价按量付费策略（贡献者套餐便宜逾 10 倍，但需授权数据留存）。
+- 该形态验证了「终端 Agent 自主完成完整软件工程任务」的市场价值，但**闭源、依赖 Meta 模型、数据留存策略对国内企业不友好**。
+- 飞虹 Code 的目标：**参照其能力范式，复刻一套自主可控、模型可切换、数据不出域、可私有化部署的终端编程智能体**，复用本团队 TS/Node 工程能力与飞扬企源企业管理方法学。
+
+### 1.3 参照对象能力拆解（Muse Code）
+
+| 能力维度 | Muse Code 实现 | 我们是否复刻 | 我们的差异点 |
+|----------|----------------|--------------|--------------|
+| 安装方式 | 单命令 `curl … | bash` | ✅ | 增加 `npm i -g` / 国内镜像源 |
+| 多智能体并行 | 主代理 + 多个持久化子代理，隔离 worktree 并行 | ✅ | 子代理角色可配置（规划/编码/审查） |
+| 长时任务与崩溃恢复 | 本地事件日志作为单一可信源，可精确回放 | ✅ | 事件日志可导出/审计，支持断点续跑 |
+| 内置技能 | `/plan`、`/grill`、`/goal` 等 | ✅ | 扩展为可插拔技能市场（本地+团队共享） |
+| 多模态输入 | 视频/文档 → 完整应用 | 🔲 P2 | 先支持图片/文档，视频后置 |
+| 模型绑定 | 绑定 Muse Spark | ❌ | **多模型路由层**，不绑定单一厂商 |
+| 数据策略 | 低价套餐需授权数据留存 | ❌ | 默认本地/私有部署，数据不出域 |
+| 透明度 | 完全可审计 | ✅ | 增加变更 diff 可视化与回滚 |
+
+### 1.4 目标用户
+
+1. **专业软件工程师 / 架构师**：处理大型代码库重构、跨模块迁移。
+2. **技术团队负责人**：把重复性编程任务自动化。
+3. **AI 研究人员 / 独立开发者**：需要长时迭代优化（如 GPU 内核调优）。
+4. （远期）**非技术业务人员**：通过自然语言生成内部工具/页面。
+
+### 1.5 核心价值主张
+
+- **自主可控**：模型、数据、部署全链路可私有化，不绑定任何云厂商。
+- **成本最优**：多模型路由按任务/成本/能力自动选优，避免为简单任务付高价。
+- **稳交付**：长时任务事件日志 + 崩溃恢复 + 隔离 worktree，大型任务不中断。
+- **可审计**：每一次模型调用、工具执行、文件变更可追溯、可回滚。
+
+### 1.6 与参照的差异总结
+
+> 不追「模型最强」，而追「架构最稳、可控性最高、成本最优、最贴合国内企业私有化诉求」。
+
+---
+
+## 2. 功能规划
+
+### 2.1 功能全景图
+
+```
+飞虹 Code
+├── 交互层（终端 REPL / 单条命令）
+│   ├── 自然语言需求输入
+│   ├── /plan 规划  /grill 压力测试  /goal 目标达成
+│   └── 审批确认（危险操作时）
+├── 编排层（Agent Orchestrator）
+│   ├── 任务分解 → 子代理派发
+│   ├── 子代理并行（隔离 worktree）
+│   └── 结果汇总与冲突协调
+├── 工具层（Tool System）
+│   ├── 文件：read / write / edit / list / grep
+│   ├── 执行：run_shell（沙箱+审批）
+│   ├── 检索：codebase_search / web_fetch
+│   └── 验证：test_run / build_check
+├── 模型层（Multi-Model Router）
+│   ├── OpenAI 兼容 API（DeepSeek/通义/OpenRouter…）
+│   ├── 本地模型（Ollama）
+│   └── 路由策略：能力/成本/延迟
+├── 运行时（Runtime）
+│   ├── 事件日志（单一可信源）
+│   ├── 会话/子代理状态
+│   └── 崩溃恢复 / 断点续跑
+└── 技能层（Skill System）
+    ├── 内置技能
+    └── 可插拔技能（本地 + 团队共享）
+```
+
+### 2.2 优先级
+
+| 等级 | 功能 | 说明 |
+|------|------|------|
+| **P0（MVP）** | 终端 REPL、自然语言→代码、文件读写编辑、shell 执行（带审批）、基础规划、模型路由（单/多供应商切换）、事件日志、结构化错误/日志 | 能完成「描述需求→生成并验证代码」的最小闭环 |
+| **P1** | 多子代理并行 + 隔离 worktree、长时任务崩溃恢复、技能系统（/plan /grill /goal）、成本计量、diff 可视化与回滚 | 对标 Muse Code 核心差异化能力 |
+| **P2** | 多模态输入（图片/文档→应用）、技能市场、团队共享配置、Web 管理面板（可选）、自动 PR 提交 | 增强与生态 |
+
+### 2.3 核心用户故事
+
+- **US-1（开发者）**：`fhcode "把 src/utils 里的 date 格式化抽成独立模块并补单测"` → 自动规划、改码、跑测试、汇报结果。
+- **US-2（长时任务）**：`fhcode "对 CUDA 内核做 24h 迭代优化"` → 事件日志持久化，进程崩溃后 `fhcode resume` 从断点续跑。
+- **US-3（并行）**：`fhcode "同时给登录/支付/报表三个模块加审计日志"` → 派发 3 个子代理，各自隔离 worktree 并行，合并无冲突。
+
+---
+
+## 3. 技术架构
+
+### 3.1 总体架构（分层）
+
+```
+┌─────────────────────────────────────────────┐
+│  CLI 入口 (src/cli)                          │  argparse / REPL / 单命令
+├─────────────────────────────────────────────┤
+│  Agent 编排层 (src/agent)                     │  Orchestrator / Planner / SubAgent
+├──────────────┬──────────────┬───────────────┤
+│ 工具层        │ 技能层        │ 模型路由层     │  ToolSystem / SkillSystem / ModelRouter
+│ (src/tools)  │ (src/skills) │ (src/models)  │
+├──────────────┴──────┬───────┴───────────────┤
+│  运行时 / 存储层 (src/runtime)               │  事件日志 / 会话状态 / 恢复
+├─────────────────────────────────────────────┤
+│  基础设施 (src/shared)                        │  config / errors / logger / types
+└─────────────────────────────────────────────┘
+```
+
+### 3.2 分层职责（铁律）
+
+| 层 | 职责 | ❌ 禁止 |
+|----|------|---------|
+| CLI | 解析参数、启动 REPL、渲染输出、收集审批 | 写业务/模型逻辑 |
+| Agent | 任务分解、调度子代理、汇总 | 直接调用模型 HTTP / 直接碰文件系统 |
+| Tool | 单条能力的纯实现（带 schema + 沙箱） | 跨工具编排 |
+| Model | 统一 chat/stream 接口 + 路由 + 成本计量 | 感知业务语义 |
+| Runtime | 事件日志、状态、恢复 | 业务逻辑 |
+| Shared | config/errors/logger/types | 业务代码 |
+
+### 3.3 多模型路由层设计
+
+**目标**：不绑定任何厂商，按「能力 / 成本 / 延迟 / 任务类型」动态选模型。
+
+```
+ModelRouter
+  ├─ registerProvider(OpenAICompatibleProvider)   // DeepSeek / 通义 / OpenRouter
+  ├─ registerProvider(LocalOllamaProvider)
+  └─ route(task: ModelTask): Provider
+       策略：
+         - capability: code-gen | reasoning | long-context | vision | cheap
+         - cost-ceiling: 本次任务预算上限
+         - fallback: 主选失败自动切次选
+```
+
+- `ModelTask` 携带 `capabilityTags`、`maxCost`、`requireStream`、`contextWindow` 等元数据。
+- 每次调用记录 `tokenUsage` 与 `cost` 进事件日志，支持成本计量与告警。
+- 配置化供应商清单，密钥仅存于环境变量（`.env`，不入库）。
+
+### 3.4 工具系统（Tool System）
+
+每个工具实现统一契约：
+
+```typescript
+interface Tool {
+  name: string;                 // 唯一名，如 "edit_file"
+  description: string;          // 给模型看的用途说明
+  inputSchema: JSONSchema;      // 输入校验（Zod/JSON Schema）
+  risk: 'safe' | 'shell' | 'destructive';
+  execute(input: unknown, ctx: ToolContext): Promise<ToolResult>;
+}
+```
+
+| 工具 | 风险级 | 说明 |
+|------|--------|------|
+| read_file / list_files / grep | safe | 只读，免审批 |
+| write_file / edit_file | safe* | 写文件，记录 diff 可回滚 |
+| run_shell | shell | 默认需审批/沙箱，危险命令拦截 |
+| web_fetch | safe | 联网检索，受白名单限制 |
+| test_run / build_check | shell | 触发验证，结果回流 |
+
+### 3.5 运行时事件日志（单一可信源）
+
+- **Append-only** 事件流，是长时任务可回放/恢复的基础。
+- 事件类型：`session_start` / `model_call` / `tool_call` / `approval` / `file_edit` / `error` / `subagent_spawn` / `session_end`。
+- 存储于本地 `~/.feihong-code/sessions/<id>.log`（JSONL）。
+- `fhcode resume <id>` 重放事件重建状态，从最后未完成的步骤续跑。
+
+### 3.6 子代理隔离与并行
+
+- 主代理分解任务 → 派发 N 个 `SubAgent`，每个在独立 `git worktree` 工作（互不污染工作副本）。
+- 角色可配：`planner`（规划）/ `coder`（实现）/ `reviewer`（审查）。
+- 合并阶段由 Orchestrator 协调冲突（基于文件归属/变更区间）。
+
+### 3.7 技能系统
+
+- 技能 = 预置 prompt 模板 + 工具组合 + 触发词。
+- 内置：`/plan`、`/grill`、`/goal`；远期支持本地目录 + 团队共享插件。
+
+---
+
+## 4. 工程结构（Feature-first）
+
+```
+feihong-code/
+├── package.json
+├── .env.example
+├── tsconfig.json
+├── src/
+│   ├── cli/                 # 入口、REPL、参数解析
+│   │   ├── index.ts
+│   │   ├── repl.ts
+│   │   └── commands.ts
+│   ├── agent/               # 编排层
+│   │   ├── orchestrator.ts
+│   │   ├── planner.ts
+│   │   ├── subagent.ts
+│   │   └── agent.dto.ts
+│   ├── tools/               # 工具层（feature-first）
+│   │   ├── file/
+│   │   │   ├── read-file.tool.ts
+│   │   │   ├── write-file.tool.ts
+│   │   │   └── edit-file.tool.ts
+│   │   ├── shell/
+│   │   │   └── run-shell.tool.ts
+│   │   ├── search/
+│   │   │   └── grep.tool.ts
+│   │   ├── verify/
+│   │   │   ├── test-run.tool.ts
+│   │   │   └── build-check.tool.ts
+│   │   ├── tool.interface.ts
+│   │   └── tool.registry.ts
+│   ├── models/              # 多模型路由层
+│   │   ├── model-router.ts
+│   │   ├── model.interface.ts
+│   │   ├── providers/
+│   │   │   ├── openai-compatible.provider.ts
+│   │   │   └── ollama.provider.ts
+│   │   └── model.dto.ts
+│   ├── skills/              # 技能层
+│   │   ├── skill.interface.ts
+│   │   ├── plan.skill.ts
+│   │   ├── grill.skill.ts
+│   │   └── goal.skill.ts
+│   ├── runtime/             # 运行时/存储
+│   │   ├── event-log.ts
+│   │   ├── session-store.ts
+│   │   └── recovery.ts
+│   └── shared/              # 基础设施
+│       ├── config.ts        # 集中配置，启动校验，fail-fast
+│       ├── errors.ts        # 类型化错误层级
+│       ├── logger.ts        # 结构化 JSON 日志 + requestId
+│       └── types.ts
+├── tests/
+│   ├── unit/
+│   └── integration/
+└── docs/
+    └── 产品开发文档.md
+```
+
+---
+
+## 5. 核心模块设计
+
+### 5.1 配置中心（集中、类型化、fail-fast）
+
+```typescript
+// src/shared/config.ts
+import 'dotenv/config';
+
+function required(name: string): string {
+  const v = process.env[name];
+  if (!v) throw new Error(`缺少必需环境变量: ${name}`); // fail-fast
+  return v;
+}
+
+export const config = {
+  app: { name: 'feihong-code', version: '0.1.0', homeDir: required('FH_HOME') },
+  models: {
+    providers: JSON.parse(process.env.FH_PROVIDERS || '[]'), // 供应商清单（含 endpoint/key/标签）
+    defaultStrategy: process.env.FH_MODEL_STRATEGY || 'cost',  // cost|capability|latency
+    budgetPerTaskUsd: Number(process.env.FH_BUDGET_USD || '0.5'),
+  },
+  runtime: { logDir: process.env.FH_LOG_DIR || '~/.feihong-code/sessions', maxRetries: 3 },
+  security: { shellAllowlist: (process.env.FH_SHELL_ALLOW || '').split(','), requireApproval: true },
+} as const;
+```
+
+### 5.2 类型化错误层级
+
+```typescript
+// src/shared/errors.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly status: number,
+    public readonly isOperational = true,
+  ) { super(message); }
+}
+export class ConfigError extends AppError {
+  constructor(key: string) { super(`配置缺失: ${key}`, 'CONFIG_ERROR', 500); }
+}
+export class ModelError extends AppError {
+  constructor(msg: string, public readonly provider: string) {
+    super(`模型调用失败[${provider}]: ${msg}`, 'MODEL_ERROR', 502);
+  }
+}
+export class ToolError extends AppError {
+  constructor(tool: string, msg: string) { super(`工具[${tool}]失败: ${msg}`, 'TOOL_ERROR', 400); }
+}
+export class ApprovalRequiredError extends AppError {
+  constructor(action: string) { super(`需人工审批: ${action}`, 'APPROVAL_REQUIRED', 401); }
+}
+```
+
+### 5.3 结构化日志
+
+```typescript
+// src/shared/logger.ts
+import { randomUUID } from 'crypto';
+const reqId = randomUUID();
+export const logger = {
+  info: (msg: string, meta = {}) => console.log(JSON.stringify({ level: 'info', msg, reqId, ...meta })),
+  error: (msg: string, meta = {}) => console.error(JSON.stringify({ level: 'error', msg, reqId, ...meta })),
+};
+// ❌ 禁止 console.log 散落业务代码；禁止记录密钥/PII
+```
+
+### 5.4 Agent 编排器（节选）
+
+```typescript
+// src/agent/orchestrator.ts
+export class Orchestrator {
+  constructor(
+    private readonly router: ModelRouter,
+    private readonly tools: ToolRegistry,
+    private readonly runtime: EventLog,
+  ) {}
+
+  async run(task: string): Promise<AgentResult> {
+    this.runtime.append({ type: 'session_start', task });
+    const plan = await this.planner.plan(task, this.router);
+    const results = await Promise.all(
+      plan.steps.map((s) => this.dispatchSubAgent(s)),  // 隔离 worktree 并行
+    );
+    return this.aggregate(results);
+  }
+}
+```
+
+### 5.5 模型路由（节选）
+
+```typescript
+// src/models/model-router.ts
+export class ModelRouter {
+  private providers: ModelProvider[] = [];
+  register(p: ModelProvider) { this.providers.push(p); }
+  async route(task: ModelTask): Promise<ModelProvider> {
+    const scored = this.providers
+      .filter((p) => task.capabilityTags.every((t) => p.tags.includes(t)))
+      .sort((a, b) => this.score(a, task) - this.score(b, task)); // 按策略打分
+    const pick = scored[0];
+    if (!pick) throw new ModelError('无可用模型', 'router');
+    return pick;
+  }
+}
+```
+
+### 5.6 工具实现示例（edit_file）
+
+```typescript
+// src/tools/file/edit-file.tool.ts
+export const editFileTool: Tool = {
+  name: 'edit_file',
+  description: '按 old_string→new_string 精确替换文件内容',
+  risk: 'safe',
+  inputSchema: { type: 'object', properties: { path: { type: 'string' }, old_string: { type: 'string' }, new_string: { type: 'string' } }, required: ['path','old_string','new_string'] },
+  async execute(input, ctx) {
+    const before = await fs.readFile(input.path, 'utf8');
+    if (!before.includes(input.old_string)) throw new ToolError('edit_file', 'old_string 未匹配');
+    const after = before.replace(input.old_string, input.new_string);
+    await fs.writeFile(input.path, after);
+    ctx.runtime.recordDiff(input.path, before, after); // 可回滚
+    return { ok: true, path: input.path };
+  },
+};
+```
+
+### 5.7 运行时事件日志
+
+```typescript
+// src/runtime/event-log.ts
+export class EventLog {
+  constructor(private readonly file: string) {}
+  append(event: AgentEvent) {
+    appendFileSync(this.file, JSON.stringify({ ts: Date.now(), ...event }) + '\n');
+  }
+  replay(): AgentEvent[] { return readFileSync(this.file,'utf8').trim().split('\n').map(JSON.parse); }
+}
+```
+
+### 5.8 技能系统
+
+```typescript
+// src/skills/skill.interface.ts
+export interface Skill {
+  name: string;            // /plan
+  description: string;
+  trigger: RegExp;
+  run(ctx: SkillContext): Promise<void>;
+}
+```
+
+---
+
+## 6. 关键接口契约（TypeScript）
+
+```typescript
+// 模型层
+interface ModelProvider {
+  id: string;
+  tags: CapabilityTag[];           // 'code-gen' | 'reasoning' | 'long-context' | 'vision' | 'cheap'
+  chat(req: ChatRequest): Promise<ChatResponse>;
+  stream(req: ChatRequest): AsyncIterable<ChatChunk>;
+}
+interface ChatRequest { messages: ChatMessage[]; temperature?: number; maxTokens?: number; }
+interface ChatResponse { content: string; usage: TokenUsage; }
+interface TokenUsage { promptTokens: number; completionTokens: number; costUsd: number; }
+
+// 工具层
+interface ToolContext { runtime: EventLog; cwd: string; askApproval(action: string): Promise<boolean>; }
+interface ToolResult { ok: boolean; data?: unknown; error?: string; }
+
+// Agent 层
+interface AgentPlan { steps: PlanStep[]; }
+interface PlanStep { id: string; goal: string; role: 'planner'|'coder'|'reviewer'; worktree: string; }
+interface AgentResult { changes: FileChange[]; summary: string; costUsd: number; }
+```
+
+---
+
+## 7. 数据模型
+
+### 7.1 事件日志（JSONL，append-only）
+
+```json
+{ "ts": 1754790000000, "type": "model_call", "provider": "deepseek", "usage": {"promptTokens":120,"completionTokens":300,"costUsd":0.0009} }
+{ "ts": 1754790001000, "type": "tool_call", "tool": "edit_file", "input": {"path":"src/a.ts"}, "risk": "safe" }
+{ "ts": 1754790002000, "type": "approval", "action": "run_shell: npm test", "decision": "granted" }
+```
+
+### 7.2 会话状态
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | string | 会话 UUID |
+| task | string | 原始需求 |
+| status | enum | planning / running / paused / done / failed |
+| subagents | SubAgent[] | 派发的子代理 |
+| costUsd | number | 累计成本 |
+| createdAt | number | 时间戳 |
+
+### 7.3 子代理
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | string | 子代理 UUID |
+| role | enum | planner / coder / reviewer |
+| worktree | string | 隔离工作树路径 |
+| status | enum | idle / busy / done |
+
+---
+
+## 8. 配置管理（.env.example）
+
+```bash
+# 应用
+FH_HOME=~/.feihong-code
+FH_LOG_DIR=~/.feihong-code/sessions
+
+# 模型路由（多供应商，JSON 数组）
+# 每个 provider: { id, type:"openai-compatible"|"ollama", baseURL, apiKey, tags:[], costPer1k }
+FH_PROVIDERS='[
+  {"id":"deepseek","type":"openai-compatible","baseURL":"https://api.deepseek.com/v1","apiKey":"","tags":["code-gen","cheap"],"costPer1k":0.0001},
+  {"id":"qwen","type":"openai-compatible","baseURL":"https://dashscope.aliyuncs.com/compatible-mode/v1","apiKey":"","tags":["code-gen","long-context"],"costPer1k":0.0002},
+  {"id":"ollama","type":"ollama","baseURL":"http://localhost:11434","apiKey":"","tags":["code-gen","local"],"costPer1k":0}
+]'
+FH_MODEL_STRATEGY=cost          # cost | capability | latency
+FH_BUDGET_USD=0.5               # 单任务预算上限
+
+# 安全
+FH_SHELL_ALLOW=git,npm,pnpm,node,ls,cat   # shell 白名单（逗号分隔）
+FH_REQUIRE_APPROVAL=true
+```
+
+---
+
+## 9. 安全与合规
+
+遵循飞扬企源「管理给方案，技术给步骤，安全守底线」原则：
+
+1. **命令沙箱**：`run_shell` 仅允许白名单命令；危险命令（rm -rf、:(){、curl|sh 等）强制拦截并需显式审批。
+2. **数据不出域**：默认本地/私有部署；供应商密钥仅存于环境变量，绝不入库、不打印、不写日志。
+3. **操作留痕**：所有模型调用、工具执行、文件变更进事件日志，可审计、可回滚。
+4. **敏感信息脱敏**：日志自动遮蔽密钥/PII；客户信息、合同、财务等内部机密绝不进入 Agent 上下文。
+5. **权限分级**：危险操作（删除、推送远端、修改系统配置）必须人工审批。
+6. **绝不越权**：不修改薪酬/股权/制度、不承诺效果、不伪造身份。
+7. **企业权限（M4）**：四角色 RBAC + deny 优先矩阵，危险命令/敏感路径在角色判定前即拦截（含 admin）；策略覆盖只能加严不能放宽。
+8. **防篡改审计（M4）**：工具执行前由守卫统一留痕，审计日志按月切分并以 sha256 哈希链串联，任意篡改均可被 `audit verify` 定位断点。
+9. **多租户与成本治理（M4）**：租户物理目录隔离、ID 正则防穿越；单任务成本上限 + 租户日预算双重熔断，超限直接拒绝。
+
+---
+
+## 10. 开发里程碑
+
+| 里程碑 | 周期(估) | 交付物 | 退出标准 |
+|--------|----------|--------|----------|
+| **M0 脚手架** | 3d | feature-first 工程结构、config/errors/logger、CLI 入口 | `fhcode --version` 可运行，构建通过 ✅(2026-08-10) |
+| **M1 P0 闭环** | 10d | 模型路由（≥2 供应商）、文件/编辑/shell 工具、REPL、事件日志 | 能完成 US-1：`描述需求→改码→跑测试` ✅(2026-08-10 离线闭环验证通过) |
+| **M2 编排升级** | 10d | 多子代理并行 + 隔离 worktree、规划/技能、成本计量 | 能完成 US-3 并行三模块 ✅(2026-08-10 离线 worktree 隔离并行端到端验证通过) |
+| **B 真实模型联调** | 2d | 接入 OpenAI 兼容真实模型（Agnes 网关）、ReAct 闭环验证、.env 加载器 | 单命令问答 + list 工具调用真实跑通 ✅(2026-08-10 Agnes 网关联调通过；成本计量/事件日志正常) |
+| **M3 恢复与审计** | 7d | `sessions`/`resume` 断点续跑、`diff`/`rollback` 会话作用域变更管理、交互式审批流 | 能完成 US-2 长时任务中断续跑 ✅(2026-08-10 离线端到端验证：sessions 列表/resume 续跑/diff/rollback 全绿，交互式与白名单审批 6 项断言通过) |
+| **M4 打磨发布** | 5d | README/署名、安装脚本、冒烟测试、**企业级（RBAC/防篡改审计/多租户/三流水线 CI）**、v0.1.0 打包 | 端到端冒烟通过，可 `npm i -g` 安装；企业断言 41/41 通过 ✅(2026-08-10) |
+
+---
+
+## 11. 任务拆解（落地计划）
+
+```
+M0:
+  [x] 初始化 npm/ts 工程、tsconfig、目录骨架
+  [x] shared/config、errors、logger、types
+  [x] cli/index + 参数解析 + --version
+M1:
+  [x] models: interface + openai-compatible + ollama + router（含 cost 计量、zod 校验）
+  [x] tools: read/write/edit/list/grep + run_shell(沙箱) + test/build（含路径安全、白名单+审批）
+  [x] agent: orchestrator(ReAct 循环) + planner 最小版
+  [x] runtime: event-log(JSONL 单一可信源) + session-store
+  [x] REPL 交互 + 单命令模式（离线 Mock 驱动闭环）
+M2:
+  [x] subagent + git worktree 隔离（git worktree add/remove 隔离工作区；离线 Mock 驱动子代理）
+  [x] /plan（只读目标分解，按 并且/以及/同时 等连词切分）/grill（红队式安全审查，误报已收敛）/goal（目标持久化到 ~/.feihong-code/goals）
+  [x] 并行编排器 runParallel：分解→建 worktree→Promise.allSettled 并行子代理→清理（已修复 Windows 上多 worktree 顺序移除连带清掉 .git/worktrees 的已知缺陷，改用 尽力移除+强制清目录+prune 鲁棒策略）
+  [x] 成本计量接入事件日志（每轮迭代累计 costUsd，落检查点 + 事件日志）
+M3:
+  [x] sessions 列出历史会话 / resume 从检查点续跑（Orchestrator.run(goal, resume?) 重建对话继续 ReAct）
+  [x] diff 展示会话作用域变更 / rollback 回滚（git 辅助，touchedFiles 作用域，--yes 确认，非 git 仓库拒绝）
+  [x] 审批流：TTY 交互式 y/n 确认 + 非 TTY 白名单兜底（interactiveApprover / defaultApproverFor）
+M4:
+  [x] 安装脚本 install.sh + npm 包（files 白名单防 .env 泄露、prepublishOnly 自动构建）
+  [x] README、署名、LICENSE（全部带晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹）
+  [x] 企业级四能力（src/enterprise/）：
+      - tenant.ts 多租户物理目录隔离 + ID 正则防穿越 + 默认租户兼容
+      - policy.ts RBAC 四角色 + deny 优先 + 危险命令(23)/敏感路径(11)黑名单 + 策略覆盖加严
+      - audit.ts sha256 哈希链防篡改 + 按月切分 + redact 脱敏 + verifyAudit
+      - quota.ts 租户日预算 FH_TENANT_BUDGET_USD + 单任务 maxCostUsd 熔断
+      - guard.ts 唯一权威闸门（策略判定→审批→留痕一次性完成）
+      - index.ts 装配 isEnterpriseEnabled/assertQuota/renderWhoami
+  [x] CLI 企业命令：whoami / policy / audit [--limit N] / audit verify / tenants
+  [x] 三流水线 CI（build 多 Node 矩阵 / enterprise 41 项离线断言 / security 发布白名单+密钥扫描）
+  [x] 冒烟测试脚本 scripts/verify-m4.mjs（41 项全离线断言，7 节） + npm run verify:m4 / verify
+  [x] 文档：README §4.8 企业能力、用户手册 §2.7+安全模型、配置参考 M4 变量、架构与API §8、部署指南 §5 三流水线、常见问题 Q13-Q16、本文件 §9/§10/§11
+```
+
+---
+
+## 12. 风险与对策
+
+| 风险 | 影响 | 对策 |
+|------|------|------|
+| 模型厂商接口变动 | 调用失败 | 供应商抽象层 + fallback 路由 |
+| 长时任务进程崩溃 | 进度丢失 | 事件日志 append-only + resume |
+| 并行 worktree 冲突 | 合并失败 | 文件归属/变更区间协调 + reviewer |
+| shell 误执行危险命令 | 数据损失 | 白名单 + 危险拦截 + 审批 |
+| 成本失控 | 超支 | 单任务预算上限 + 实时计量告警 |
+| 数据合规 | 泄露 | 默认私有部署、密钥不入库、日志脱敏 |
+
+---
+
+## 13. 附录
+
+### 13.1 命令参考（草案）
+
+| 命令 | 说明 |
+|------|------|
+| `fhcode "<需求>"` | 单命令模式：直接执行一条需求 |
+| `fhcode` | 进入交互 REPL |
+| `fhcode /plan <需求>` | 仅规划，不执行 |
+| `fhcode /grill <计划>` | 对计划做压力测试/找漏洞 |
+| `fhcode /goal <目标>` | 目标达成模式，循环推进 |
+| `fhcode resume <id>` | 从断点恢复长时任务 |
+| `fhcode log <id>` | 查看事件日志 |
+| `fhcode diff <id>` | 查看变更 diff / 回滚 |
+
+### 13.2 命名约定
+
+- 包名：`feihong-code`；命令：`fhcode`；配置前缀：`FH_`。
+- 文件夹小写下划线/连字符；类型/接口 PascalCase；函数 camelCase。
+- 所有源码文件头部注明署名（公司/中心/负责人）。
+
+### 13.3 与团队其他项目的关系
+
+- **geo-saa**：本项目的成本计量/会话管理可借鉴其 Spring Boot 后端（远期 Web 面板复用）。
+- **FyqyClaw**：若后续做桌面版 GUI，直接复用其 Electron + Vite 工程化经验。
+- 统一署名规范、安全底线、冒烟测试方法论三项目一致。
+
+---
+
+> 本文档为持续演进稿。M0/M1/M2/B 真实联调/M3/M4 已实现并附验证。最近更新：2026-08-10 完成 **M4 企业级**——新增 `src/enterprise/`（tenant 多租户隔离 / policy RBAC+deny 优先 / audit 防篡改哈希链 / quota 日预算熔断 / guard 唯一权威闸门 / index 装配），CLI 加 `whoami`/`policy`/`audit`/`audit verify`/`tenants` 五条企业命令；`scripts/verify-m4.mjs` 提供 41 项全离线断言（7 节），`npm run verify` 串联 typecheck+build+verify:m4，CI 升级为 build/enterprise/security 三流水线（零 Secrets 全离线）。验证结果：typecheck ✅ / build ✅ / verify-m4 **41/41** ✅；CLI 实测 whoami/policy/audit/tenants 正确，viewer 写文件被拒（audit DENY），租户 acme/beta 隔离互不串台，配额超限 `QUOTA_EXCEEDED` 正确触发。文档同步更新 README（§4.8 企业能力）、用户手册（§2.7+安全模型）、配置参考（M4 变量+安全建议）、架构与API（第 8 节企业级架构）、部署指南（§5 三流水线+合规建议）、常见问题（Q13-Q16）、本文件（§9/§10/§11）。M4 里程碑标记 ✅，可进入发布（v0.1.0）与 GitHub 推送准备。