@tachu/extensions 1.0.0-beta.1

package/README_ZH.md

@@ -0,0 +1,815 @@
+# Tachu
+
+**生产级 Agentic 引擎——将任何 LLM 变为可靠、可观测、生产就绪 Agent 的 Harness。**
+
+[![npm version](https://img.shields.io/npm/v/@tachu/core?label=%40tachu%2Fcore)](https://www.npmjs.com/package/@tachu/core)
+[![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)
+
+---
+
+## 什么是 Tachu？
+
+**太初有道，万物之始。以声明式描述符创造 Agent 万物。**
+
+Tachu 是一个**生产级 Agentic 引擎**——不是 Demo 玩具，不是 API 薄封装。它是等式 **Agent = Model + Harness** 中的 *Harness*：提供结构骨架（协议、生命周期、安全、记忆、编排），让任何 LLM 都能成为可靠、可观测、可生产部署的 Agent。
+
+引擎本身刻意**不感知业务领域**——它不知道你的业务逻辑、用户身份或领域词汇。取而代之的是，它定义了一套极简的核心抽象（Rules、Skills、Tools、Agents），业务通过这些抽象注入所有智能。Tachu 处理那些真正困难的部分：9 阶段执行主干、双平面语义匹配、上下文窗口管理、精确 Token 计数的 Prompt 组装、结构化重试/降级、取消传播，以及端到端可观测性。
+
+Tachu 以 Bun 原生 TypeScript Monorepo 形式发布，包含三个包：零依赖引擎核心（`@tachu/core`）、生产级官方扩展库（`@tachu/extensions`），以及完整功能的 CLI 程序（`@tachu/cli`）——后者同时也是参考实现。
+
+---
+
+## 核心亮点（Key Features）
+
+- **9 阶段执行主干** — 会话管理 → 安全准入 → 意图分析 → 前置校验 → 任务规划 → DAG 校验 → 子任务执行 → 结果验证 → 输出规范；每个阶段类型安全、可挂钩
+- **双平面匹配（Dual-Plane Matching）** — 语义发现（向量相似度）+ 确定性执行闸门（Scopes、白名单、审批），作用于所有 Rules、Skills、Tools 和 Agents
+- **四大核心抽象** — 以 Markdown + YAML frontmatter 描述符声明 Rules、Skills、Tools、Agents；引擎自动解析、激活并编排
+- **双 Provider 支持** — 生产级 OpenAI 与 Anthropic Adapter；可配置 Provider 降级顺序，实现零停机 Provider 切换
+- **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 取消传播
+- **Fail-Closed 安全基线** — 循环防护、预算熔断、基础输入校验硬编码于引擎核心，不可关闭
+- **Qdrant 与 LocalFs 向量存储** — 生产环境接入 Qdrant，开发阶段使用内置内存实现
+
+---
+
+## 愿景（Vision）
+
+> 太初有道，万物之始。以声明式描述符创造 Agent 万物。
+
+Tachu 的长期愿景是成为**通用 Agent 框架**：**引擎提供骨架，业务填充血肉**——任何组织都能基于稳定、可观测、可审计的基础设施构建生产级 Agentic 系统，而无需每次从头解决安全、上下文管理、重试逻辑和多 Provider 编排等困难问题。
+
+Tachu 基于三个核心信念：
+
+1. **Harness 才是难点。** 模型智能已经商品化；可靠的编排机制尚未。Tachu 深度投资引擎基础设施，让应用开发者专注领域逻辑。
+2. **声明优于实现（Declaration over implementation）。** Rules、Skills、Tools、Agents 均以普通 Markdown 文件声明。引擎负责解析。无框架样板代码。
+3. **默认可观测。** 每个内部事件都是结构化且可发出的。生产系统需要完整 Trace——Tachu 无需额外埋点即可提供。
+
+---
+
+## 核心抽象（Core Abstractions）
+
+Tachu 的四大核心抽象**平级独立、相互正交**——各自独立注册、独立激活，可在所有引擎阶段组合使用。
+
+| 抽象 | 本质 | 激活闸门 | 作用 |
+|------|------|----------|------|
+| **Rules** | 约束与指导 | 语义发现 → 直接激活 | 注入各阶段 LLM System Prompt |
+| **Skills** | 知识与指令 | 语义发现 → 直接激活 | 激活后注入 LLM 上下文 |
+| **Tools** | 原子可执行操作 | 语义发现 → **必须过闸**（Scopes → 白名单 → 审批） | 带完整副作用追踪的执行 |
+| **Agents** | 自然语言驱动的执行单元 | 语义发现 → 可激活 | 递归使用引擎能力；所有 Tool 调用仍走 Tool 闸门 |
+
+所有四类抽象共享统一的**描述符格式**（Markdown + YAML frontmatter）：
+
+```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 闸门。
+
+---
+
+## 架构总览（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
+```
+
+| # | 阶段 | 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` 取消当前执行
+
+---
+
+## 安装（Installation）
+
+Tachu 需要 [Bun](https://bun.sh) 作为运行时。
+
+```bash
+# 安装引擎核心
+bun add @tachu/core
+
+# 安装扩展库（Provider、Tools、Backend、向量存储）
+bun add @tachu/extensions
+
+# 全局安装 CLI
+bun add -g @tachu/cli
+```
+
+安装完成后验证：
+
+```bash
+tachu --version
+```
+
+---
+
+## 快速开始（Quick Start）
+
+### CLI 方式
+
+```bash
+# 1. 初始化项目工作空间
+tachu init --template minimal --provider openai
+
+# 2. 设置 API Key
+export OPENAI_API_KEY=sk-...
+
+# 3. 单次执行 Prompt
+tachu run "帮我总结最近 5 条 git commit 的内容"
+
+# 4. 进入交互式对话
+tachu chat
+
+# 恢复最近一次 Session
+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           显示帮助
+```
+
+---
+
+### `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           显示帮助
+```
+
+**交互内置命令**（输入时以 `/` 开头）：
+
+| 命令 | 说明 |
+|------|------|
+| `/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
+```
+
+---
+
+## 可观测性与安全（Observability & Safety）
+
+### 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 提供）
+
+### 开发工作流
+
+```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
+```
+
+### 项目规范
+
+- 文件名：`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）
+
+[Apache License 2.0](./LICENSE) © 2026 Tachu Contributors
+
+本项目采用 Apache License 2.0 许可证发布。许可证全文见 [LICENSE](./LICENSE) 文件，也可在 <http://www.apache.org/licenses/LICENSE-2.0> 获取。
+
+除非适用法律要求或书面同意，按照本许可证分发的软件是按"原样"分发的，不附带任何明示或暗示的担保或条件。请参阅许可证以了解特定语言的管理权限和限制。