@tachu/extensions 1.0.0-beta.1 → 1.0.0-rc.1

package/README_ZH.md

@@ -1,39 +1,81 @@
 # Tachu
 
-**生产级 Agentic 引擎——将任何 LLM 变为可靠、可观测、生产就绪 Agent 的 Harness。**
+**正在积极开发中的 Agentic 引擎——目标是成为将任何 LLM 变为可靠、可观测 Agent 的 *Harness*。**
 
 [![npm version](https://img.shields.io/npm/v/@tachu/core?label=%40tachu%2Fcore)](https://www.npmjs.com/package/@tachu/core)
+[![status: rc](https://img.shields.io/badge/status-rc-blue)](#项目状态project-status)
 [![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](#许可证license)
 [![bun](https://img.shields.io/badge/runtime-bun-orange)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org)
 
+> **项目状态 —— Release Candidate。** 9 阶段主干、Registry、Prompt 组装、CLI、OpenAI / Anthropic / Qwen / Gemini Adapter、MCP Adapter、向量存储与可观测性 Emitter 已完成接线并有测试覆盖。Phase 3（意图分析）是真实 LLM 调用，Phase 5 会把复杂且具备可见工具的请求路由到内置 `tool-use` loop，Phase 8 运行 deterministic 验证规则并支持可选 semantic judge。Runtime provider fallback 与 semantic judge 生产级策略属于 rc 后续加固。请使用 `@rc` dist-tag 安装。
+
 ---
 
 ## 什么是 Tachu？
 
 **太初有道，万物之始。以声明式描述符创造 Agent 万物。**
 
-Tachu 是一个**生产级 Agentic 引擎**——不是 Demo 玩具，不是 API 薄封装。它是等式 **Agent = Model + Harness** 中的 *Harness*：提供结构骨架（协议、生命周期、安全、记忆、编排），让任何 LLM 都能成为可靠、可观测、可生产部署的 Agent。
+Tachu 的目标是成为一个**你可以基于它做真实产品的 Agentic 引擎**——不是 Demo 玩具，不是 API 薄封装。它是等式 **Agent = Model + Harness** 中的 *Harness*：提供结构骨架（协议、生命周期、安全、记忆、编排），让任何 LLM 都能成为可靠、可观测的 Agent。
 
-引擎本身刻意**不感知业务领域**——它不知道你的业务逻辑、用户身份或领域词汇。取而代之的是，它定义了一套极简的核心抽象（Rules、Skills、Tools、Agents），业务通过这些抽象注入所有智能。Tachu 处理那些真正困难的部分：9 阶段执行主干、双平面语义匹配、上下文窗口管理、精确 Token 计数的 Prompt 组装、结构化重试/降级、取消传播，以及端到端可观测性。
+引擎本身刻意**不感知业务领域**——它不知道你的业务逻辑、用户身份或领域词汇。取而代之的是，它定义了一套极简的核心抽象（Rules、Skills、Tools、Agents），业务通过这些抽象注入所有智能。Tachu 被设计来处理那些真正困难的部分：9 阶段执行主干、双平面语义匹配、上下文窗口管理、精确 Token 计数的 Prompt 组装、结构化重试/降级、取消传播，以及端到端可观测性。
 
-Tachu 以 Bun 原生 TypeScript Monorepo 形式发布，包含三个包：零依赖引擎核心（`@tachu/core`）、生产级官方扩展库（`@tachu/extensions`），以及完整功能的 CLI 程序（`@tachu/cli`）——后者同时也是参考实现。
+Tachu 以 Bun 原生 TypeScript Monorepo 形式发布，包含三个已发布包：零依赖引擎核心（`@tachu/core`）、官方扩展库（`@tachu/extensions`），以及完整功能的 CLI 程序（`@tachu/cli`，同时也是参考实现）；另外有 `@tachu/host-defaults` 供 CLI 与嵌入式 host 共享默认装配，以及一个可选的私有 sidecar 包（`@tachu/web-fetch-server`），用于远端浏览器抓取类工具。
+
+---
+
+## 项目状态（Project Status）
+
+**当前发布版本：** `1.0.0-rc.0`（`rc` dist-tag）
+
+**版本术语：** 当前产品线为 **Tachu v1**。Release candidate 是 `1.0.0` 的稳定化构建，不是新的框架代际；`/v1/extract` 等仅为 HTTP API 版本。详见 [详细设计 · 版本与发布术语](docs/detailed-design.md#版本与发布术语必读)。
+
+这是一次**架构骨架**发布——核心基础设施基本就绪，但 Result Validation 与若干生产化闭环仍未完成。下表仅为**可读性索引**；运行时行为、默认值与边界情况以所引用的源码与测试为准，不在此重复展开。
+
+| 能力 | 状态 | 说明 |
+|-----|------|-----|
+| 9 阶段主干骨架（类型、编排器、状态机、Hook 链路） | ✅ 已实现 | `packages/core/src/engine` |
+| Descriptor Registry（Rules / Skills / Tools / Agents） | ✅ 已实现 | Markdown + YAML frontmatter 加载、语义索引、启动校验 |
+| Prompt 组装器（tiktoken、KV Cache 友好顺序） | ✅ 已实现 | `packages/core/src/prompt` |
+| 任务调度器、DAG 校验、turn/task 重试簿记 | ✅ 已实现 | `packages/core/src/engine/scheduler.ts`；**LLM 失败时的 runtime provider fallback 未接线**（见 [LLM Provider](./docs/guides/providers-and-integrations.md)） |
+| Session / Memory / Runtime-state / Safety / Model-router / Provider / Observability / Hooks 八大模块 | ✅ 已实现 | `packages/core/src/modules` |
+| OpenAI / Anthropic / Qwen / Mock Provider Adapter | ✅ 已实现 | CLI 经 `@tachu/host-defaults` 自动装配；流式、函数调用、工具 Schema |
+| Gemini Provider Adapter | ✅ 已实现（需手动接线） | `@tachu/extensions` 提供 `GeminiProviderAdapter` 与单测；**不会**被 CLI 默认 `buildProviderAdapter` 注册 —— 需 `createEngine(..., { providers: [new GeminiProviderAdapter(...)] })` 显式注入（见 [LLM Provider](./docs/guides/providers-and-integrations.md)） |
+| `apiKey` / `baseURL` / `organization` / `timeoutMs` 配置（env var / `tachu.config.ts` / CLI flags） | ✅ 已实现 | 支持 Azure OpenAI / LiteLLM / OpenRouter / 自建网关 |
+| 22 个内置 Tools + Terminal / File / Web Backend | ✅ 已实现 | `packages/extensions/src/tools/index.ts` |
+| MCP stdio + SSE Adapter | ✅ 已实现 | `packages/extensions/src/mcp` |
+| `LocalFsVectorIndexAdapter`（文件持久化）+ `QdrantVectorIndexAdapter`（REST） | ✅ 已实现 | |
+| OTel / JSONL Emitter | ✅ 已实现 | |
+| `tachu init` / `tachu run` / `tachu chat` CLI、流式渲染、Session 持久化、Ctrl+C 语义 | ✅ 已实现 | |
+| **CLI 终端 Markdown 渲染** | ✅ **已实现** | 基于 `marked` + `marked-terminal` + `cli-highlight` 栈。作用于 `tachu chat` / `tachu run --output text` 的最终回复：TTY 环境自动开启，`NO_COLOR` / 非 TTY / `--no-color` 下自动关闭；`tachu run` 支持通过 `--markdown` / `--no-markdown` 显式开关。专用封装 `renderMarkdownToAnsi`（`packages/cli/src/renderer/markdown.ts`），附 12 个单测（`markdown.test.ts`）。 |
+| **Phase 3 意图分析（LLM 调用，纯分类）** | ✅ **已实现** | 仅做分类（`IntentResult`）；面向用户的最终答复由 Phase 7 `direct-answer` 负责。**实现：** `packages/core/src/engine/phases/intent.ts`（`INTENT_SYSTEM_PROMPT_BASE`、快速路径、JSON 解析、启发式兜底）；测试：`intent.test.ts`。宿主可 **`config.intent.systemPromptBase`** 完整替换 base；可选追加 few-shot：`config.intent.fewShotExamples`（Agent Context / explicit selections 仍由 core 追加）。 |
+| **Phase 5 任务规划（planning router）** | ✅ **已实现** | 强制 `plans[0].tasks.length >= 1`。规则：(1) `simple` 意图 → 单步 `direct-answer` 子流程任务；(2) `complex` + 有可见工具 → 单步 `tool-use` 子流程任务；(3) `complex` + 无可见工具 → 单步 `direct-answer` 子流程任务（携带 `warn: true`）；(4) 后置守护：上游回归导致 `tasks` 为空时自动兜底。多步行为由 `tool-use` 内部承担；未来可以继续演进 Plan Preview / Human Review，但主路径不存在单独的默认 LLM 预规划器。 |
+| **`direct-answer` 内置子流程（Phase 7）** | ✅ **已实现** | `packages/core/src/engine/subflows/direct-answer.ts`。解析 `capabilityMapping.intent`（未命中时回退到 `fast-cheap`），组合 system + ≤10 条历史 + 用户 prompt，以合并后的 AbortSignal 调用 `ProviderAdapter.chat()`，单次超时 60s。System Prompt 强制**自然语言 + Markdown**、禁止 JSON 壳 / `"已识别请求：…"` 模板 / 4 空格缩进式代码块；`warn: true` 时子流程会坦诚说明"当前无匹配工具"。observability 事件统一以 `phase: "direct-answer"` 发出（`llm_call_start` / `llm_call_end`）。保留名机制：`DescriptorRegistry` 会把 `direct-answer` 列入保留名，业务侧注册 / 注销同名描述符将抛 `RegistryError.reservedName`。 |
+| **Phase 8 结果验证 Outcome** | 🟡 **部分接线** | `ValidationOutcome` 联合类型 + `ValidationRuleRegistry`（**5 条 deterministic rules**，见 `buildDefaultValidationRuleRegistry()`，`packages/core/src/engine/phases/validation/index.ts`）。可选 `ProviderSemanticJudgeAdapter` / `BudgetedSemanticJudgeAdapter`。Engine 消费 `retry`（turn 循环，`decideTurnRetry`）、`degrade` / `handoff`（退出到 Output）。缺口：无独立 `ExecutionPolicy` 类型；runtime provider fallback 未实现，semantic judge 尚非 production-complete。 |
+| **Phase 9 输出装配** | ✅ **已实现** | 内容选择顺序：`taskResults['task-direct-answer']` → 结构化 `{intent, taskResults}` JSON（工具链成功路径；语义层面的润色仍依赖真实 Phase 8）→ 中文诚实回退文案（validation 未通过）。内部 state JSON 不会再外泄到用户侧。专项测试见 `output.test.ts`。 |
+| 真实环境端到端烟测（OpenAI / Anthropic / Azure 等） | 🟡 **已手工验证；可选脚本化** | CI 内 Adapter 以 Mock 单测为主；维护者已 **手工跑通** 真实 LLM 路径（含自建网关）。仓库提供 **可选** 脚本化 e2e —— 预先配置 `TACHU_REAL_E2E=1` 与 `TACHU_E2E_API_KEY` / `TACHU_E2E_API_BASE` / `TACHU_E2E_PROVIDER`（见[贡献指南](./CONTRIBUTING.md)）—— 但默认 CI 不发布签署记录。 |
+| 生产加固（SLO、错误预算、故障注入、签名 provenance） | 🔴 未开展 | `1.0.0`（Tachu v1）目标。 |
+
+图例：✅ 已实现并有测试 · 🟡 骨架存在、真实实现进行中 · 🔴 未开工。
 
 ---
 
 ## 核心亮点（Key Features）
 
-- **9 阶段执行主干** — 会话管理 → 安全准入 → 意图分析 → 前置校验 → 任务规划 → DAG 校验 → 子任务执行 → 结果验证 → 输出规范；每个阶段类型安全、可挂钩
+- **9 阶段执行主干** — 会话管理 → 安全准入 → 意图分析（纯分类）→ 前置校验 → planning router → DAG 校验 → 子任务执行 → 结果验证 outcome → 输出规范；每个阶段类型安全、可挂钩，且每个请求（simple 或 complex）都会完整穿过 9 个阶段，Rules / Hooks / Observability / 预算熔断统一生效
+- **任务计划 + 工具循环（Task Planning + Tool-use Loop）** — Phase 5 不预先生成完整的排序多步计划，而是把 `simple` 请求路由到 `direct-answer`，把 `complex + 可见工具` 路由进内置 `tool-use` Agentic Loop，由循环内部完成 LLM 工具选择 → 受控工具执行 → 工具结果回灌 → 最终答复。
+- **`direct-answer` 内置子流程** — 对 simple 请求（以及 complex 但无匹配工具的请求），最终答复由一个引擎内置的一等公民子流程在 Phase 7 产出，不再由意图分析阶段捎带。
 - **双平面匹配（Dual-Plane Matching）** — 语义发现（向量相似度）+ 确定性执行闸门（Scopes、白名单、审批），作用于所有 Rules、Skills、Tools 和 Agents
 - **四大核心抽象** — 以 Markdown + YAML frontmatter 描述符声明 Rules、Skills、Tools、Agents；引擎自动解析、激活并编排
-- **双 Provider 支持** — 生产级 OpenAI 与 Anthropic Adapter；可配置 Provider 降级顺序，实现零停机 Provider 切换
+- **OpenAI 与 Anthropic Adapter** — 流式、函数调用、`baseURL` / `organization` / `timeoutMs` 可配置；可对接 Azure OpenAI / LiteLLM / OpenRouter / 任意自建网关
 - **MCP 集成** — 通过 `McpToolAdapter` 接入任意 MCP 服务端（stdio 或 SSE）；MCP Tools 成为引擎一等公民
 - **精确 Token 计数** — 基于 tiktoken 的精确 Token 统计；KV Cache 友好的 Prompt 布局；自动上下文压缩（Head-Middle-Tail 策略）
 - **结构化记忆（Memory System）** — 会话上下文窗口（含可配置上限）；压缩前强制归档；长期向量记忆召回
 - **OpenTelemetry 可观测性** — 每个阶段进入/退出、LLM 调用、Tool 调用、重试和降级都产出结构化 `EngineEvent`；内置 OTel 与 JSONL Emitter
-- **生产级 CLI** — `tachu chat` / `tachu run` / `tachu init`，完整参数体系、流式渲染、Session 持久化、Ctrl+C 取消传播
+- **交互式 CLI** — `tachu chat` / `tachu run` / `tachu init`，完整参数体系、流式渲染、Session 持久化、Ctrl+C 取消传播
+- **终端 Markdown 渲染** —— 最终回复由 `marked` + `marked-terminal` + `cli-highlight` 渲染；支持标题、粗体 / 斜体、列表、块引用、链接、表格、带代码高亮的 fenced code block。`NO_COLOR` / 非 TTY / `--no-color` 下自动关闭；`tachu run` 可通过 `--markdown` / `--no-markdown` 显式控制。
 - **Fail-Closed 安全基线** — 循环防护、预算熔断、基础输入校验硬编码于引擎核心，不可关闭
-- **Qdrant 与 LocalFs 向量存储** — 生产环境接入 Qdrant，开发阶段使用内置内存实现
+- **Qdrant 与 LocalFs 向量存储** — 多进程部署使用 Qdrant，本地/单进程使用文件持久化
 
 ---
 
@@ -53,117 +95,17 @@ Tachu 基于三个核心信念：
 
 ## 核心抽象（Core Abstractions）
 
-Tachu 的四大核心抽象**平级独立、相互正交**——各自独立注册、独立激活，可在所有引擎阶段组合使用。
-
-| 抽象 | 本质 | 激活闸门 | 作用 |
-|------|------|----------|------|
-| **Rules** | 约束与指导 | 语义发现 → 直接激活 | 注入各阶段 LLM System Prompt |
-| **Skills** | 知识与指令 | 语义发现 → 直接激活 | 激活后注入 LLM 上下文 |
-| **Tools** | 原子可执行操作 | 语义发现 → **必须过闸**（Scopes → 白名单 → 审批） | 带完整副作用追踪的执行 |
-| **Agents** | 自然语言驱动的执行单元 | 语义发现 → 可激活 | 递归使用引擎能力；所有 Tool 调用仍走 Tool 闸门 |
-
-所有四类抽象共享统一的**描述符格式**（Markdown + YAML frontmatter）：
+Rule、Skill、Tool、Agent 以 Markdown + YAML 描述符声明。语义发现给出候选，确定性闸门（尤其 Tool）决定是否执行。
 
-```yaml
-name: unique-name             # 必填，同类型内唯一
-description: ...              # 自然语言描述（用于语义发现）
-tags: [tag1, tag2]            # 标签，用于过滤和分类
-trigger: { type: always }     # 激活条件
-requires:
-  - { kind: tool, name: read-file }  # 显式依赖引用
-```
-
-### 双平面匹配模型（Dual-Plane Matching）
-
-每个核心抽象的激活都经历两个阶段：
-
-```mermaid
-graph LR
-    Input[上下文输入] --> Discovery[语义发现面]
-    Discovery --> Index[(向量索引)]
-    Index --> Candidates[候选集]
-    Candidates --> Gate[确定性执行闸门]
-    Gate -- Scopes / 白名单 / 审批 --> Execution[执行面]
-```
-
-- **语义发现面**：描述符的 `description` 在注册时向量化写入索引；运行时以当前上下文匹配索引，产出候选集
-- **确定性执行闸门**：最终激活需通过确定性校验（显式引用、白名单/黑名单、权限 Scopes、审批检查）
-
-Rules 和 Skills 无闸门直接激活（无副作用）。Tools 必须经过完整闸门。Agents 自由激活，但其内部调用的 Tools 仍需过 Tool 闸门。
+详见 [概要设计 · 四大核心抽象](./docs/overview-design.md#三四大核心抽象) · [双平面匹配](./docs/overview-design.md#共享特性)。
 
 ---
 
-## 架构总览（Architecture Overview）
-
-### 三层发布结构
-
-```mermaid
-graph TD
-    subgraph "业务层（Business Layer）"
-        A[业务 Rules / 领域 Tools / 自定义 Adapter / 领域 Skills / Agents / Plan 模板]
-    end
-    subgraph "引擎扩展库 — @tachu/extensions"
-        B[OpenAI & Anthropic Adapter / 7 个常用 Tools / Terminal+File+Web Backend / Qdrant+LocalFs VectorStore / MCP Adapter / OTel+JSONL Emitter / 4 个通用 Rules]
-    end
-    subgraph "引擎核心 — @tachu/core"
-        C[协议定义 / 9 阶段主干 / 生命周期钩子 / Session / 记忆 / 安全 / 模型路由 / 运行状态]
-    end
-    A --> B
-    B --> C
-```
+## 架构概览（摘要）
 
-| 层级 | 包 | 职责 |
-|------|----|----|
-| 引擎核心 | `@tachu/core` | 协议接口、9 阶段主干骨架、8 个核心模块、Registry、Prompt 组装器、VectorStore 接口 + 内置轻量实现 |
-| 扩展库 | `@tachu/extensions` | 官方具体实现：Provider Adapter、Tools、Backend、VectorStore Adapter、OTel/JSONL Emitter、通用 Rules |
-| 业务/CLI | `@tachu/cli` 或业务代码 | 组装 core + extensions 为可工作的 Agent；提供领域 Rules/Skills/Tools/Agents |
-
-### 9 阶段执行主干
-
-每个请求都经历完整的 9 个阶段：
-
-```mermaid
-graph TD
-    Start([业务请求]) --> S1[阶段 1：会话管理]
-    S1 --> S2[阶段 2：最小安全准入]
-    S2 --> S3[阶段 3：意图分析 — LLM]
-    S3 -- 简单 --> S9[阶段 9：输出规范]
-    S3 -- 复杂 --> S4[阶段 4：前置校验]
-    S4 --> S5[阶段 5：任务拆分]
-    S5 -- Plan 模式 --> PlanLoop{规划审阅循环}
-    S5 -- 模板匹配 --> S6
-    S5 -- 动态拆分 --> S6[阶段 6：依赖图校验]
-    PlanLoop -- 确认 --> S6
-    S6 --> S7[阶段 7：子任务执行]
-    S7 --> S8[阶段 8：结果验证 — LLM]
-    S8 -- 通过 --> S9
-    S8 -- 不通过 --> Retry{重试 / 重规划}
-    Retry -- 未达上限 --> S5
-    Retry -- 耗尽 --> S9
-    S9 --> End([输出])
-
-    style S2 fill:#ffeaa7,stroke:#fdcb6e
-    style S7 fill:#dfe6e9,stroke:#b2bec3
-```
+请求经 **9 阶段主干**；复杂工具任务在 Phase 7 进入内置 `tool-use` Agentic Loop。
 
-| # | 阶段 | LLM 调用 | 关键输出 |
-|---|------|----------|---------|
-| 1 | 会话管理（Session Management） | 否 | 会话上下文加载 |
-| 2 | 最小安全准入（Minimum Safety Check） | 否 | 通过 / 拒绝 |
-| 3 | 意图分析（Intent Analysis） | **是** | `IntentResult`（简单/复杂，上下文相关性） |
-| 4 | 前置校验（Pre-Check） | 否 | 资源可用性、深度安全校验 |
-| 5 | 任务拆分（Task Planning） | **是** | `PlanningResult`（带排名的方案 + DAG） |
-| 6 | 依赖图校验（DAG Validation） | 否 | 环检测、节点完整性（确定性） |
-| 7 | 子任务执行（Sub-task Execution） | 视子任务 | `TaskResult[]`（可并行） |
-| 8 | 结果验证（Result Validation） | **是** | `ValidationResult`（通过 / 执行问题 / 拆分问题） |
-| 9 | 输出规范（Output Normalization） | 否 | `EngineOutput`（含步骤状态、元信息、附件） |
-
-**主干关键特性：**
-
-- **全路径安全准入** — 阶段 2 对所有请求路径执行，包括简单问题的快速通道
-- **上下文门卫** — 阶段 3 判断会话历史是否与本轮相关；无关历史不向下传递
-- **事不过三** — 任务级重试最多 3 次（可配置）；系统级重试最多 2 次
-- **取消传播（Last-message-wins）** — 同一 Session 收到新消息时，通过 `AbortController` 取消当前执行
+详见 [Pipeline 阶段详解](./docs/architecture/pipeline-phases.md) · [概要设计](./docs/overview-design.md)。
 
 ---
 
@@ -171,21 +113,23 @@ graph TD
 
 Tachu 需要 [Bun](https://bun.sh) 作为运行时。
 
+> **请使用 `@rc` dist-tag 安装**（或固定到具体版本），直至 Tachu 进入稳定版。
+
 ```bash
 # 安装引擎核心
-bun add @tachu/core
+bun add @tachu/core@rc
 
 # 安装扩展库（Provider、Tools、Backend、向量存储）
-bun add @tachu/extensions
+bun add @tachu/extensions@rc
 
 # 全局安装 CLI
-bun add -g @tachu/cli
+bun add -g @tachu/cli@rc
 ```
 
 安装完成后验证：
 
 ```bash
-tachu --version
+tachu --version   # 预期输出 1.0.0-rc.0 或更新
 ```
 
 ---
@@ -211,599 +155,41 @@ tachu chat
 tachu chat --resume
 ```
 
-### 编程式（Programmatic — TypeScript）
-
-```typescript
-import { Engine } from '@tachu/core';
-import { OpenAIProviderAdapter } from '@tachu/extensions/providers';
-import type { EngineConfig, InputEnvelope, ExecutionContext } from '@tachu/core';
-
-const config: EngineConfig = {
-  retry: { taskMaxRetries: 3, systemMaxRetries: 2 },
-  planning: { planCount: 1, enableValidation: true },
-  agent: { maxNestingDepth: 1 },
-  context: { maxTokens: 8000, compressionThreshold: 0.8 },
-  execution: { defaultTimeout: 120_000 },
-  models: {
-    capabilityMapping: {
-      'high-reasoning': 'gpt-4o',
-      'fast-cheap': 'gpt-4o-mini',
-    },
-    providerFallbackOrder: ['openai'],
-  },
-  safety: { maxInputSize: 1_000_000, maxRecursionDepth: 10 },
-  hooks: { writeHookTimeout: 5000, failureBehavior: 'continue' },
-  storage: {},
-};
-
-const engine = new Engine(config);
-engine.useProvider(new OpenAIProviderAdapter({ apiKey: process.env.OPENAI_API_KEY! }));
-
-const input: InputEnvelope = {
-  content: '写一个 TypeScript 函数，对异步操作做防抖处理',
-  metadata: { modality: 'text' },
-};
-
-const context: ExecutionContext = {
-  requestId: crypto.randomUUID(),
-  sessionId: 'session-001',
-  traceId: crypto.randomUUID(),
-  principal: { userId: 'user-001' },
-  budget: { maxTokens: 20_000, maxDurationMs: 60_000 },
-  scopes: ['read', 'write'],
-};
-
-for await (const chunk of engine.runStream(input, context)) {
-  if (chunk.type === 'delta') process.stdout.write(chunk.content);
-  if (chunk.type === 'done') console.log('\n\n完成，状态：', chunk.output.status);
-}
-```
-
----
-
-## 包结构（Package Layout）
-
-### 三包说明
-
-| 包 | 说明 | 主要导出 |
-|----|------|---------|
-| `@tachu/core` | 零依赖引擎核心 | `Engine`、`Registry`、`PromptAssembler`、所有接口与类型 |
-| `@tachu/extensions` | 官方具体实现 | `OpenAIProviderAdapter`、`AnthropicProviderAdapter`、`McpToolAdapter`、`QdrantVectorStore`、`OtelEmitter`、Backend、Tools、Rules |
-| `@tachu/cli` | 生产级 CLI 程序 | `tachu chat`、`tachu run`、`tachu init` |
-
-### 依赖关系（Dependency Relationship）
-
-```mermaid
-graph LR
-    cli["@tachu/cli"]
-    extensions["@tachu/extensions"]
-    core["@tachu/core"]
-
-    cli --> extensions
-    cli --> core
-    extensions --> core
-
-    style core fill:#74b9ff,stroke:#0984e3
-    style extensions fill:#a29bfe,stroke:#6c5ce7
-    style cli fill:#fd79a8,stroke:#e84393
-```
-
-### core 包内部结构
-
-```
-@tachu/core / src/
-├── types/          # 所有 TypeScript 接口：描述符、上下文、I/O、配置
-├── engine/         # Engine 入口类、各阶段处理器、编排控制面、依赖调度器
-├── registry/       # Registry：注册/查询/启动校验（四类抽象统一管理）
-├── modules/        # 8 个核心模块（会话、记忆、运行状态、模型路由、
-│                   #   Provider、安全、可观测性、Hooks）
-├── prompt/         # PromptAssembler：Token 预算分配、KV Cache 友好排列
-└── vector/         # VectorStore 接口 + 内置轻量实现
-```
-
----
-
-## Provider 与集成（Providers & Integrations）
-
-### LLM Provider
-
-| Provider | 包 | 流式输出 | Function Calling | 备注 |
-|----------|----|----|------|------|
-| OpenAI | `@tachu/extensions/providers` | ✅ | ✅ | GPT-4o、GPT-4o-mini 及所有可枚举模型 |
-| Anthropic | `@tachu/extensions/providers` | ✅ | ✅ | Claude 3.5 Sonnet 及所有可枚举模型 |
-| Mock | `@tachu/extensions/providers` | ✅ | ✅ | 测试专用；可配置响应内容 |
-
-通过 `models.providerFallbackOrder` 配置降级顺序。系统级错误（超时、API 报错）时，引擎自动按顺序切换 Provider，无需重新规划。
-
-### MCP（Model Context Protocol）
-
-```typescript
-import { McpToolAdapter } from '@tachu/extensions/mcp';
-
-const adapter = new McpToolAdapter();
-
-// 通过 stdio 连接本地进程
-await adapter.connect('stdio://path/to/mcp-server');
-
-// 通过 SSE 连接远程服务
-await adapter.connect('http://localhost:3000/sse');
-
-// MCP Tools 自动注册到引擎 Registry
-const tools = await adapter.listTools(); // 返回 ToolDescriptor[]
-engine.registry.registerAll(tools);
-```
-
-`McpToolAdapter` 负责 MCP Session 生命周期管理、能力协商，并将引擎取消信号传播到 MCP 服务端。
-
-### 向量存储（Vector Stores）
-
-| Adapter | 包 | 适用场景 |
-|---------|----|----|
-| `InMemoryVectorStore` | `@tachu/core` | 开发/测试；零依赖内置实现 |
-| `LocalFsVectorStore` | `@tachu/extensions/vector` | 单进程生产；文件持久化 |
-| `QdrantVectorStore` | `@tachu/extensions/vector` | 多进程生产；完整 Qdrant REST API |
-
-```typescript
-import { QdrantVectorStore } from '@tachu/extensions/vector';
-
-const vectorStore = new QdrantVectorStore({
-  url: 'http://localhost:6333',
-  collectionName: 'tachu-descriptors',
-});
-engine.useVectorStore(vectorStore);
-```
-
-### 可观测性 Emitter
-
-| Emitter | 包 | 输出目标 |
-|---------|----|----|
-| `OtelEmitter` | `@tachu/extensions/emitters` | OpenTelemetry Span（via `@opentelemetry/api`） |
-| `JsonlEmitter` | `@tachu/extensions/emitters` | 追加写入 JSONL 文件 |
-| `ConsoleEmitter` | `@tachu/extensions/emitters` | 结构化控制台输出（开发用） |
-
-### 执行 Backend
-
-| Backend | 包 | 说明 |
-|---------|----|----|
-| `TerminalBackend` | `@tachu/extensions/backends` | 沙箱终端内的 Shell 命令执行 |
-| `FileBackend` | `@tachu/extensions/backends` | 文件系统读写 |
-| `WebBackend` | `@tachu/extensions/backends` | HTTP 请求至外部 API / Web 资源 |
-
----
-
-## 设计原则（Design Principles）
-
-Tachu 基于七条核心工程原则：
-
-1. **双平面匹配** — 所有四类核心抽象通过语义方式发现（向量相似度），但通过确定性方式激活（Scopes、白名单、审批）。语义发现是参考；执行闸门是权威。
-
-2. **全路径安全准入** — 最小安全检查（阶段 2）对*所有*请求路径执行，包括简单问题的快速通道。安全性绝不为性能让步。
-
-3. **事不过三** — 任务级重试循环和系统级重试循环都有严格上限。不允许无限重试。耗尽上限后，引擎输出步骤级完成状态而非笼统失败。
-
-4. **KV Cache 友好的 Prompt 组装** — System Prompt 按稳定顺序组装（硬约束 Rules → 软偏好 Rules → Skills → Tool 定义），使跨轮次的前缀保持不变，最大化 KV Cache 复用，降低 LLM 成本。
-
-5. **取消传播（Last-message-wins）** — 同一 Session 收到新消息时，通过 `AbortController` 取消当前执行，在已有上下文基础上处理新输入。保证上下文连贯，避免无效工作。
-
-6. **引擎不感知业务权限** — 引擎只在 Tool 执行闸门处校验执行上下文中的粗粒度 `scopes`。细粒度业务授权由 Tool 实现本身或专用的授权 Tool 负责。
-
-7. **Fail-Closed 安全基线** — 循环防护、预算熔断、基础输入校验硬编码于引擎核心，*不可*通过配置禁用。即使业务配置完全为空，引擎也不会失控运行。
-
----
-
-## 配置（Configuration）
-
-引擎通过项目根目录的 `tachu.config.ts` 文件配置（由 `tachu init` 自动生成）：
-
-```typescript
-import type { EngineConfig } from '@tachu/core';
-
-const config: EngineConfig = {
-  // 描述符注册中心
-  registry: {
-    descriptorRoot: '.tachu',          // Rules/Skills/Tools/Agents 根目录
-  },
-
-  // 运行时行为
-  runtime: {
-    planMode: false,                   // 是否默认开启 Plan 模式
-    maxConcurrency: 4,                 // 最大并行子任务数
-  },
-
-  // 上下文窗口与记忆
-  memory: {
-    maxTokens: 8000,                   // 上下文窗口 Token 上限
-    compressionThreshold: 0.8,         // 达到 80% 容量时触发压缩
-    archivePath: '.tachu/archive.jsonl',
-    vectorIndexLimit: 10000,           // 内置向量索引最大条目数
-  },
-
-  // 预算约束
-  budget: {
-    maxTokens: 50000,                  // 单次执行总 Token 预算
-    maxToolCalls: 50,                  // 单次执行最大 Tool 调用次数
-    maxWallTimeMs: 300000,             // 5 分钟墙钟时间上限
-  },
-
-  // 安全基线（硬编码最小集；业务策略通过 Hooks 追加）
-  safety: {
-    maxInputSize: 1_000_000,           // 字节
-    maxRecursionDepth: 10,
-    enablePromptInjectionCheck: true,
-  },
-
-  // 模型路由
-  models: {
-    capabilityMapping: {
-      'high-reasoning': { provider: 'openai', model: 'gpt-4o' },
-      'fast-cheap':     { provider: 'openai', model: 'gpt-4o-mini' },
-      'vision':         { provider: 'openai', model: 'gpt-4o' },
-    },
-    providerFallbackOrder: ['openai', 'anthropic'],
-  },
-
-  // 可观测性
-  observability: {
-    emitter: 'jsonl',
-    jsonlPath: '.tachu/events.jsonl',
-  },
-};
-
-export default config;
-```
-
-所有字段均有合理默认值。`tachu init` 会根据你选择的 Provider 预填生成此文件。
-
----
-
-## CLI 参考（CLI Reference）
-
-### `tachu init`
-
-初始化 Tachu 项目工作空间。
-
-```
-tachu init [options]
-
-选项：
-  --template <name>    脚手架模板：minimal | full  （默认：minimal）
-  --force              已存在时强制覆盖（不询问）
-  --path <dir>         目标目录                   （默认：当前目录）
-  --provider <name>    写入 config 的默认 Provider：openai | anthropic | mock  （默认：mock）
-  --no-examples        跳过生成示例 Rule / Tool 描述符
-  -h, --help           显示帮助
-```
-
-生成 `.tachu/` 目录骨架 + `tachu.config.ts` + `.gitignore` 追加条目。
-
----
-
-### `tachu run <prompt>`
 
-单次执行 Prompt，将结果流式输出到 stdout。
-
-```
-tachu run <prompt> [options]
-
-参数：
-  <prompt>             Prompt 文本（或通过 stdin 管道传入）
-
-选项：
-  --session <id>       指定 Session ID
-  --resume             恢复最近一次 Session
-  --model <name>       覆盖 high-reasoning 模型
-  --provider <name>    覆盖默认 Provider
-  --input <file>       从文件读取 Prompt
-  --json               将 Prompt 解析为 JSON（结构化输入）
-  --output <fmt>       输出格式：text | json | markdown  （默认：text）
-  --no-validation      跳过阶段 8 结果验证
-  --plan-mode          启用 Plan 模式（阶段 5 后暂停等待审批）
-  --verbose, -v        详细日志（阶段切换、LLM 调用详情）
-  --no-color           禁用 ANSI 彩色输出（同 NO_COLOR 环境变量）
-  --timeout <ms>       墙钟时间上限（覆盖 budget.maxWallTimeMs）
-  -h, --help           显示帮助
-```
+编程式接入见 [配置](./docs/guides/configuration.md) 与 `@tachu/host-defaults`。
 
 ---
 
-### `tachu chat`
-
-进入多轮交互式对话 Session。
-
-```
-tachu chat [options]
-
-选项：
-  --session <id>       指定 Session ID
-  --resume             恢复最近一次 Session
-  --history            列出所有 Session 后退出（不进入交互）
-  --export <file>      将指定 Session 导出为 Markdown 后退出
-  --model <name>       覆盖 high-reasoning 模型
-  --provider <name>    覆盖默认 Provider
-  --plan-mode          启用 Plan 模式
-  --verbose, -v        详细日志
-  --no-color           禁用彩色输出
-  -h, --help           显示帮助
-```
-
-**交互内置命令**（输入时以 `/` 开头）：
+## 文档（Documentation）
 
-| 命令 | 说明 |
+| 文档 | 说明 |
 |------|------|
-| `/exit` | 保存 Session 并退出 |
-| `/reset` | 清空当前 Session 的 Memory |
-| `/new` | 开启新 Session |
-| `/list` | 列出所有已保存的 Session |
-| `/load <id>` | 切换到指定 Session |
-| `/save` | 手动持久化当前 Session |
-| `/export <path>` | 将当前 Session 导出为 Markdown 文件 |
-| `/history` | 显示本 Session 的消息历史 |
-| `/stats` | 显示 Token 用量、Tool 调用次数、剩余预算 |
-| `/help` | 显示所有命令 |
-
-**Ctrl+C 行为：**
-- 第一次：取消当前 LLM/Tool 调用（回到提示符，Session 不丢失）
-- 1 秒内第二次：保存 Session 并正常退出
-- 第三次：强制退出
-
----
-
-## 扩展指南（Extension Guide）
-
-Tachu 通过在 `.tachu/` 目录下创建 Markdown 描述符文件来扩展。Rules、Skills 和 Tools 无需任何代码变更——只有 Agent 的执行函数需要在代码中单独注册。
-
-### 自定义 Rule
-
-```markdown
-<!-- .tachu/rules/no-external-calls.md -->
----
-name: no-external-calls
-description: 禁止 Agent 在未获明确审批前发起外部网络调用
-type: rule
-scope: [execution]
-tags: [security, network]
----
-
-除非被调用 Tool 的 requiresApproval 为 true 且用户已确认，
-否则不得发起 HTTP 请求、DNS 查询或任何其他外部网络调用。
-```
-
-### 自定义 Skill
-
-```markdown
-<!-- .tachu/skills/git-workflow/SKILL.md -->
----
-name: git-workflow
-description: 本仓库 Git 分支策略、Commit 规范与 PR 工作流知识
-tags: [development, git]
-requires:
-  - { kind: tool, name: run-command }
----
-
-## Git 工作流
-
-本仓库采用基于主干的开发模式（trunk-based development），配合短生命周期特性分支。
-
-### 分支命名
-- 功能分支：`feat/<ticket>-<short-desc>`
-- 修复分支：`fix/<ticket>-<short-desc>`
-
-### Commit 规范
-使用 Conventional Commits：`type(scope): subject`
-...
-```
-
-### 自定义 Tool
-
-```markdown
-<!-- .tachu/tools/query-db.md -->
----
-name: query-db
-description: 对应用数据库执行只读 SQL 查询
-sideEffect: readonly
-idempotent: true
-requiresApproval: false
-timeout: 10000
-inputSchema:
-  type: object
-  properties:
-    sql:   { type: string, description: "SQL SELECT 语句" }
-    limit: { type: number, description: "最大返回行数", default: 100 }
-  required: [sql]
-execute: queryDatabase
----
-
-执行参数化只读 SQL 查询，结果以 JSON 数组形式返回。
-```
-
-在 `engine-factory.ts` 中注册执行函数：
-
-```typescript
-engine.registry.registerExecutor('queryDatabase', async (input, ctx) => {
-  const { sql, limit = 100 } = input as { sql: string; limit?: number };
-  return db.query(sql).limit(limit).execute();
-});
-```
-
-### 自定义 Agent
-
-```markdown
-<!-- .tachu/agents/code-reviewer.md -->
----
-name: code-reviewer
-description: 审查 Pull Request diff，产出结构化代码审查意见
-sideEffect: readonly
-idempotent: true
-requiresApproval: false
-timeout: 180000
-maxDepth: 1
-availableTools: [read-file, search-code, run-command]
----
-
-你是一名严谨的代码审查者。接到 diff 或文件集后：
-1. 理解变更意图
-2. 从正确性、清晰度、安全性和性能角度逐项审查
-3. 输出带有严重程度分级的结构化审查意见：critical / major / minor / nit
-```
+| [概要设计](./docs/overview-design.md) | 愿景、分层、抽象、主干流程 |
+| [详细设计](./docs/detailed-design.md) | 类型、模块、配置 Schema |
+| [技术设计](./docs/technical-design.md) | 工程结构与实现指南 |
+| [Pipeline 阶段详解](./docs/architecture/pipeline-phases.md) | 9 阶段与 tool-use 循环 |
+| [包结构](./docs/architecture/package-layout.md) | Monorepo 包与依赖 |
+| [设计原则](./docs/architecture/design-principles.md) | 核心工程原则 |
+| [CLI 参考](./docs/guides/cli.md) | 命令与参数 |
+| [配置](./docs/guides/configuration.md) | `tachu.config.ts` |
+| [Provider 与集成](./docs/guides/providers-and-integrations.md) | LLM、MCP、向量库 |
+| [扩展指南](./docs/guides/extension-guide.md) | Rule / Skill / Tool / Agent |
+| [可观测性与安全](./docs/guides/observability-and-safety.md) | 事件、OTel、安全 |
+| [CONTEXT.md](./CONTEXT.md) | 产品术语 |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | 开发流程 |
+| [Web Fetch Server](./packages/web-fetch-server/README.md) | 可选 sidecar |
 
 ---
 
-## 可观测性与安全（Observability & Safety）
+## Web Fetch Server（可选）
 
-### OpenTelemetry 集成
-
-每个引擎事件映射为一条 OTel Span，实现完整的分布式追踪：
-
-```typescript
-import { OtelEmitter } from '@tachu/extensions/emitters';
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
-import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-
-const provider = new NodeTracerProvider();
-provider.addSpanProcessor(
-  new SimpleSpanProcessor(new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }))
-);
-provider.register();
-
-engine.useEmitter(new OtelEmitter());
-```
-
-**每次请求产出的事件类型：**
-
-| 事件类型 | 时机 |
-|---------|------|
-| `phase_enter` / `phase_exit` | 每个流程阶段进入/退出 |
-| `llm_call_start` / `llm_call_end` | 每次 LLM 调用 |
-| `tool_call_start` / `tool_call_end` | 每次 Tool 执行 |
-| `retry` | 任务级或系统级重试触发 |
-| `provider_fallback` | Provider 降级启动 |
-| `budget_warning` | 预算已用到上限的 80% |
-| `budget_exhausted` | 预算熔断激活 |
-| `error` | 任何 `EngineError` 子类 |
-
-### 安全模块（Safety Module）
-
-安全模块分两层独立运行：
-
-**引擎固有基线（不可禁用）：**
-- 输入大小上限（`maxInputSize` 字节）
-- 递归深度限制（`maxRecursionDepth`）
-- 预算熔断（Token/时间预算耗尽时立即终止）
-
-**业务可注入策略**（通过 Hooks 或配置）：
-- Prompt 注入检测（`enablePromptInjectionCheck: true`）
-- 敏感操作拦截（通过 `engine.registerSafetyPolicy()` 注册）
-- 输出内容合规检查
-
-```typescript
-// 注册自定义安全策略
-engine.registerSafetyPolicy(async (input, ctx) => {
-  if (containsPersonalData(input.content)) {
-    return { passed: false, violations: [{ type: 'pii', message: '输入中检测到个人隐私数据' }] };
-  }
-  return { passed: true, violations: [] };
-});
-```
-
----
-
-## 发展路线（Roadmap）
-
-### v1.0.0 — 已交付
-
-- [x] `@tachu/core`：Engine、9 阶段主干、8 个核心模块、Registry、PromptAssembler、InMemoryVectorStore、完整错误分类体系
-- [x] `@tachu/extensions`：OpenAI + Anthropic Provider、7 个 Tools、Terminal/File/Web Backend、LocalFs + Qdrant VectorStore、MCP stdio+SSE Adapter、OTel+JSONL Emitter、4 个通用 Rules
-- [x] `@tachu/cli`：`tachu init` / `tachu run` / `tachu chat`，完整参数体系、Session 持久化、流式渲染
-- [x] 测试套件（行覆盖率 ≥80%）和性能基准
-- [x] 中英文 README
-
-### v1.x — 规划中
-
-- 更多 VectorStore Adapter（Pinecone、pgvector）
-- 更多 Provider Adapter（Google Gemini、Mistral）
-- 更多 MCP Tool 集成
-- 更多内置压缩策略
-- 结构化 Plan 模板库
-
-### v2 — 愿景
-
-- 多 Agent 协作（Agent 间通信协议）
-- 跨部署重启的长期记忆持久化
-- 子任务粒度的精细预算分配
-
----
-
-## 贡献指南（Contributing）
-
-### 环境要求
-
-- [Bun](https://bun.sh) >= 1.1.0
-- TypeScript 5.x（通过 devDependencies 提供）
-
-### 开发工作流
+浏览器渲染的 `web-fetch` / `web-search` 需可选 sidecar，见 [packages/web-fetch-server/README.md](./packages/web-fetch-server/README.md)。
 
 ```bash
-# 克隆并安装
-git clone https://github.com/dangaogit/tachu
-cd tachu
-bun install
-
-# 运行所有测试
-bun test
-
-# 类型检查
-bun run typecheck
-
-# 构建所有包
-bun run build
-
-# 运行指定包的测试
-bun test --filter packages/core
+bun run dev:server:install-browser
+bun run dev:server
 ```
 
-### 项目规范
-
-- 文件名：`kebab-case`
-- 类名/类型名：`PascalCase`
-- 函数/变量名：`camelCase`
-- 常量名：`SCREAMING_SNAKE_CASE`
-- 所有公开 API 必须有 TSDoc 注释（`@param`、`@returns`、`@throws`、`@example`）
-- 测试文件与源码同目录，命名 `*.test.ts`
-- 集成测试放 `__tests__/`
-
-Pull Request 要求：
-- 所有测试通过（`bun test`）
-- TypeScript 零错误（`bun run typecheck`）
-- 覆盖率达标（行 ≥80%，分支 ≥70%）
-- 新增公开 API 有完整 TSDoc
-
-详见 `CONTRIBUTING.md`。
-
----
-
-## 基准测试（Benchmarks）
-
-性能基准位于 `packages/core/benchmarks/`，通过 `bun test` 执行：
-
-| 基准 | 度量指标 | 基线数据 |
-|------|---------|---------|
-| `scheduler.bench.ts` — 100 个并行任务 | 调度吞吐量 | *由 verifier 阶段填充* |
-| `vector-store.bench.ts` — 10,000 条索引，topK=10 | 搜索 QPS | *由 verifier 阶段填充* |
-| `prompt-assembler.bench.ts` — 4K Token 窗口组装 | 组装延迟（p99） | *由 verifier 阶段填充* |
-
-基准测试提供回归检测基线；v1 不设定最低性能指标要求。
-
----
-
-## 文档（Documentation）
-
-| 文档 | 说明 |
-|------|------|
-| [架构设计（Architecture Design）](./docs/adr/architecture-design.md) | 愿景、三层结构、四大核心抽象、9 阶段主干设计 |
-| [详细设计（Detailed Design）](./docs/adr/detailed-design.md) | TypeScript 接口、模块规格、配置 Schema |
-| [技术设计（Technical Design）](./docs/adr/technical-design.md) | 技术选型、工程结构、实现指南 |
-
 ---
 
 ## 许可证（License）