@zooique/memora 3.0.1 → 5.0.0

package/docs/memora-api-reference.md

@@ -1,1175 +1,1349 @@
-# Memora 内核 API 参考手册（v3.0.0）
-
-> **核心定位**：Memora 是一个**无法独立运行**的智能大脑内核——它只有接口，没有"形态"。CLI、WebUI、桌面精灵、小说生成器都是它的"宿主"，宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
->
-> **本文件用途**：列出内核对外暴露的**全部公开接口**——从最基础的接入接口（〇），到 Agent 面类、对话、记忆、角色包、工具、各 Manager，再到类型导出与安全约束。
->
-> **版本**：v3.0.0（对齐当前稳定版，纯净接口文档，不含历史变更流水）
-
----
-
-## 〇、接入基础接口
-
-> **定位**：一个新宿主接入 memora 的**最小接入面**。其余各章是 `Agent` 初始化后暴露的运行时能力；本章回答"接入前必须提供什么"。
->
-> **一句话总结**：必做三件事——① 实现 `IMemoryStorage` + `ISessionStore` + `LlmProvider`；② 准备 `configDir`（含 `config.json` 模型表 + `role-packs/` + `skills/`）；③ 传 `projectPath` / `dataDir` / `configDir` 构造 `Agent`。其余接口按需注入，缺省都有降级兜底。
-
-### 〇.1 宿主实现的接口（注入）
-
-| 接口 | 必选 | 声明位置 | 用途 |
-|------|------|---------|------|
-| `LlmProvider` | ✅ 必选 | `src/llm/provider.ts` | 前台 LLM 流式对话（`stream()`），宿主创建 |
-| `IMemoryStorage` | ✅ 必选* | `src/memory/storageInterface.ts` | 记忆持久化，15 方法，同步语义（对齐 better-sqlite3）；**后端由宿主自选** |
-| `ISessionStore` | ✅ 必选* | `src/memory/sessionStore.ts` | 会话消息持久化，3 必需 + 6 可选方法 |
-| `ITracer` | 可选 | `src/agent/tracer.ts` | 可观测性，不传用 `NoopTracer` |
-| `IWebSearchProvider` | 可选 | `src/web-search/types.ts` | 网络搜索，不注入则不启用 |
-| `IFetchProvider` | 可选 | `src/web-fetch/types.ts` | 网页抓取（搜索→抓取闭环第二段），不注入则不启用 |
-| `ICodeExecutionProvider` | 可选 | `src/code-exec/types.ts` | 通用代码执行（沙箱由宿主提供），不注入则不启用 |
-| `IProjectSearchProvider` | 可选 | `src/project-search/types.ts` | 项目内搜索（等价 IDE 全局搜索），不注入则不暴露 `search_project`（见 §8.6） |
-| `ILogger` | 可选 | `src/logging/loggerInterface.ts` | 日志，默认内置 |
-| `backgroundProvider` (`LlmProvider`) | 可选 | AgentOptions | 后台通道（归档/投影），不配复用前台 |
-
-\* 不传则内核自动用 `InMemoryStorage` / 内存会话（仅内存不落盘）；做产品必须实现。
-
-### 〇.2 宿主提供的配置资源（`configDir` 下）
-
-`configDir` 是唯一的配置目录入口（含角色包 / 全局技能 / 配置文件）：
-
-```
-configDir/
-├── config.json              ← ★ LLM 配置真理源：providers + active + background + taskRouter
-├── role-packs/              ← 角色包目录（每个包一个文件夹，含 manifest.json）
-│   └── 工程师/
-│       ├── manifest.json    ← 必填：元数据 + strategy + capabilities
-│       ├── persona.md       ← 约定名，可省（身份设定）
-│       ├── rules.md         ← 约定名，可省（安全契约）
-│       └── skills/          ← 角色包内嵌技能（目录动态扫描，可选）
-│           └── ...          ← 形式与全局技能池一致（见下）
-├── skills/                  ← 全局技能池（所有角色共享，可选）
-│   ├── search.md            ← 单文件形式
-│   └── code-review/         ← 文件夹形式（统一大众公认的 Agent Skills 格式）
-│       ├── SKILL.md         ← 技能正文（frontmatter 声明 name/description）
-│       ├── resources/       ← L3 参考资源（参考材料/规范）
-│       ├── scripts/         ← L3 可执行脚本（运行时按需执行）
-│       ├── references/      ← 技能内参考资料
-│       └── assets/          ← 技能内资源（模板/图片/示例）
-```
-
-> **skills 两种形式（两级技能共用统一格式）**：全局技能池（`configDir/skills/`）与角色包内嵌技能（`role-packs/<名>/skills/`）采用**同一套**技能格式，仅激活条件不同（全局始终激活，角色包技能随角色激活）。每个技能为单文件 `*.md` **或** 文件夹 `SKILL.md` 两种形式之一；`references/` / `assets/` 属于**技能内部**的资源目录（文件夹形式的组成部分），非 configDir 或角色包顶层目录。渐进披露：L1 元数据常驻 / L2 `read_skill` 按需读正文 / L3 `read_resource` + `run_skill_script`。
-```
-
-**config.json 大模型列表**（不是独立目录，是配置文件中的映射表）：
-
-```jsonc
-{
-  "llm": {
-    "providers": { "deepseek": { "baseUrl": "...", "model": "...", "apiKey": "" },
-                   "openai":   { "baseUrl": "...", "model": "...", "apiKey": "" } },
-    "active": "deepseek",        // 激活别名，不配取第一个 key
-    "background": { ... },       // 可选后台通道，节省成本
-    "taskRouter": { "simple": "deepseek", "reasoning": "openai" }
-  }
-}
-```
-
-- API Key **不写文件**，从环境变量读取。
-- memora 内核仅内置 `mock` Provider（无 API Key 的测试/降级），其余厂商需宿主在 config.json 显式配置。
-
-### 〇.3 `dataDir` vs `storage` 的区别
-
-两个易混淆的参数：**`storage` 管"如何存取"（接口实例），`dataDir` 管"存到哪个目录"（路径字符串）**。
-
-| | `storage`（IMemoryStorage） | `dataDir` |
-|---|---|---|
-| 本质 | 接口实例（宿主写的类） | 文件系统目录路径（字符串） |
-| 内核怎么用它 | 调方法：`upsert` / `getById` / `search` / `getAllSources`… | 用它定位项目注册表（`projects.json`）；记忆库落哪、叫什么名，由宿主自定，内核不参与 |
-| 管什么 | "怎么存取记忆"（逻辑），内核不关心内部是 SQLite 还是内存 | "记忆库与项目注册表放哪个目录"（物理位置） |
-| 谁实现 | 宿主实现（如 SqliteMemoryStorage） | 宿主传路径 |
-| 关系 | `dataDir` 指向目录；宿主按自己的持久化形态构造 storage（JSON 文件 / SQLite 皆可） | 内核用 `dataDir` 推导注册表路径；**项目锁文件不由 `dataDir` 推导**，它固定落 `<projectPath>/.memora/.lock` |
-| 缺省 | 不传 → `InMemoryStorage`（仅内存） | **必填，无默认值**（目录位置与层级语义是宿主的产品决策，内核不假设） |
-
-一句话：`storage` 是宿主**怎么**存取的实现，`dataDir` 是存取内容**落在哪个目录**的配置——一个管"如何"，一个管"何处"。
-
-> **`config.json` 里的 `memory.dataDir` 内核不读**：它只是「宿主约定的载体」——宿主可自行从配置取出后传给
-> `new Agent({ dataDir })`。内核不消费它，也没有任何默认值；`config.example.json` 里写 `~/.memora` 只是一个示例值，
-> 不等于内核的缺省行为。
-
-### 〇.4 多来源双路径编排（内置 + 用户）
-
-内核**刻意保持"单 `configDir` 输入"**——`SkillManager`/`RolePackManager` 只扫 `<configDir>/skills/`、`<configDir>/role-packs/`，无"多来源"概念。宿主若想开放"内置（随插件打包）+ 用户自定义"双路径，由宿主在传入内核**之前**自行编排归一，两种形态：
-
-| 形态 | 做法 | 适用 |
-|------|------|------|
-| **A. 宿主文件层汇总（推荐，零内核改动）** | 宿主在文件系统层把"内置目录 + 用户目录"合并/软链到**一个 `configDir`** 再传内核 | 角色包、全局技能均可；内容本质同构、希望同池匹配 |
-| **B. 宿主多 Manager 实例聚合** | 宿主建多个 `RolePackManager(configDirA/B)` 各管一个来源，聚合 `listMeta()` 在 UI 层分组展示，激活仍逐个调用 | 来源语义需要区分（UI 分组、只读标记） |
-
-选择依据：内容**不必区分来源**走 A（合并到同一 configDir）；**必须区分来源**（只读/可编辑、分组）走 B（多实例聚合展示）。内核两种都支持。
-
-### 〇.5 构造 `Agent` 的参数
-
-```ts
-new Agent({
-  projectPath,            // ✅ 必选：工作区
-  provider,               // ✅ 必选：前台 LLM
-  // 常用可选项
-  configDir,              // 配置根目录（role-packs / skills；缺省用内置默认）
-  dataDir,                // ✅ 必选：记忆数据落地目录（内核不提供默认值）
-  backgroundProvider,     // 后台 LLM
-  storage,                // IMemoryStorage 实现（缺省 InMemoryStorage）
-  sessionStore,           // ISessionStore 实现（缺省仅内存保存）
-  webSearchProvider,      // 网络搜索
-  tracer,                 // 可观测
-  maxContextTokens,       // 默认 120000
-  permission, allowedPaths, confirmWrites,   // 安全
-  activeRolePack,         // 启动激活的角色包
-})
-```
-
----
-
-## 一、设计哲学
-
-```
-┌────────────────────────────────────────────────────────────┐
-│  宿主程序（CLI / 桌面精灵 / 小说生成器 / WebUI）           │
-│  ┌─────────────────┐    ┌──────────────────┐               │
-│  │ LLM Provider 实例 │◄───│ API Key / baseUrl │  ← 宿主职责  │
-│  └────────┬────────┘    └──────────────────┘               │
-│           │ 注入                                            │
-│           ▼                                                 │
-│  ┌──────────────────────────────────────────┐               │
-│  │  Memora 内核（Agent）                    │               │
-│  │  ┌──────────────────────────────────────┐│               │
-│  │  │  Agent 面类（编排层）                 ││               │
-│  │  │  - init/close · chat · switchProject ││               │
-│  │  │  - .rolePack / .tools / .skills      ││               │
-│  │  │  - .governance / .memory             ││               │
-│  │  └──────────┬───────────────────────────┘│               │
-│  │             │ 委托                         │               │
-│  │  ┌──────────┼───────────────────────────┐│               │
-│  │  │ RolePackManager / SkillManager       ││               │
-│  │  │ ToolExecutor / MemoryInspector       ││               │
-│  │  │ MemoryGovernance                     ││               │
-│  │  └──────────────────────────────────────┘│               │
-│  │  ⚠️ 不包含：UI / LLM 配置 / 用户配置模板 │               │
-│  └──────────────────────────────────────────┘               │
-└────────────────────────────────────────────────────────────┘
-```
-
-**设计原则**：
-- **零运行时依赖**（核心层零 npm 运行时依赖、**零运行时模块解析**；日志默认内置 console fallback，宿主经 `setLogger()` 注入自定义实现；持久化由宿主通过 `IMemoryStorage` 接口注入）
-- **内核模块不直接调用 `console.*`**（唯一日志出口是 `logging/` 单例 `logger`；默认实现为内置 console fallback，写 stderr）
-- **零写用户文件**（配置文件是真理源，Agent 只读）
-- **零 LLM 配置加载**（Agent 不知道 `apiKey`，宿主传入 `LlmProvider` 实例）
-- **Manager 委托模式**：Agent 面类只做编排，领域操作委托给专职 Manager
-
----
-
-## 二、构造与生命周期
-
-### 2.1 构造选项 `AgentOptions`
-
-| 字段 | 类型 | 必须 | 说明 |
-|------|------|------|------|
-| `projectPath` | `string` | ✅ | 项目路径（必须） |
-| `provider` | `LlmProvider` | ✅ | 前台 LLM Provider（必须） |
-| `backgroundProvider` | `LlmProvider` | ❌ | 后台 Provider（投影等后台操作） |
-| `providerRouter` | `ProviderRouter` | ❌ | 按任务类型返回 Provider 的路由器（不配时全部使用同一 Provider，向后兼容） |
-| `configDir` | `string` | ❌ | 配置目录（role-packs / skills，设定记忆唯一归角色包） |
-| `dataDir` | `string` | ✅ | 记忆数据目录（必填，内核不提供默认值；传项目级还是用户级目录由宿主决定） |
-| `registryDir` | `string` | ❌ | 项目注册表目录（缺省与 dataDir 相同）。注册表用于**跨项目按名解析**，仅当多项目共用一份时才成立 |
-| `maxContextTokens` | `number` | ❌ | 上下文窗口上限（默认 120000） |
-| `activeRolePack` | `string` | ❌ | 启动激活的角色包名（缺失/不存在回退默认激活首个） |
-| `permission` | `'owner' \| 'guest'` | ❌ | 安全权限（默认 'owner'） |
-| `allowedPaths` | `string[]` | ❌ | 路径白名单（默认 [] = 全部允许） |
-| `confirmWrites` | `boolean` | ❌ | 写入确认（默认 false） |
-| `storage` | `IMemoryStorage` | ❌ | 存储层注入（默认 InMemoryStorage） |
-| ~~`vectorStore`~~ | ~~`IVectorStore`~~ | — | **已删除（2026-09-18 B0 收编）**：向量语义召回通道此前**写端缺失、从未在生产生效**（`upsert` 零调用 → 库恒空 → 语义分支永不触发 = 僵尸能力）。经主流 agent 调研（Anthropic Memory/Claude Code/Librarian Pattern 实证「LLM 消费者 + 小语料」纯关键词足用）拍板收编：`IVectorStore` 接口、`JsonVectorStore`、`EmbeddingProvider` 及 `config.embedding` 段全链删除；`search_memories` 走纯关键词，未命中提示 LLM 换词重试 |
-| ~~`recallExcludeSources`~~ | ~~`string[]`~~ | — | **已删除（2026-09-11）**：该配置随召回编排 `recall()` 退役后成为零消费者死配置，全链（AgentOptions → AgentConfig → AssembleInput → ContextPreparerDeps）物理删除。关联推荐的实际排除走 `Agent.governance.suggest(query, { excludeSources })` 显式参数 |
-| `sessionStore` | `ISessionStore` | ❌ | 会话存储注入 |
-| `tracer` | `ITracer` | ❌ | 可观测性 Tracer 注入（不传则使用 NoopTracer 静默丢弃所有 span） |
-| `messages` | `UIMessages` | ❌ | 宿主可覆盖的 UI 消息文本（默认英文，宿主覆盖为中文等） |
-| `enableContextSummary` | `boolean` | ❌ | 上下文超限时是否自动生成摘要（默认 true，开启后首次截断时增加 ~1-2s 延迟） |
-| `archiveMode` | `ArchiveMode` | ❌ | 归档模式（ADR-015，默认 `'full'`）。`'full'`：会话内容在会话切换前自动归档；`'manual'`：全部需手动触发（2026-08-14 洞察层移除后三态收敛为二态，原 `'insights-only'` 已移除） |
-| `webSearchProvider` | `IWebSearchProvider` | ❌ | 网络搜索提供者注入（提供时自动暴露 `web_search` 工具给 LLM，不传则不暴露） |
-| `fetchProvider` | `IFetchProvider` | ❌ | 网页抓取提供者注入（提供时自动暴露 `web_fetch` 工具给 LLM，与 `webSearchProvider` 成对构成「搜索→抓取」闭环，不传则不暴露） |
-| `codeExecutionProvider` | `ICodeExecutionProvider` | ❌ | 代码执行提供者注入（提供时自动暴露 `run_code` 工具给 LLM，沙箱执行能力完全由宿主 provider 决定，内核零运行时依赖，不传则不暴露） |
-| `fileConsistencyCheck` | `FileConsistencyCheck` | ❌ | 文件层前置条件断言回调（可选，未注入则完全降级为现状） |
-| `preExecutionCheck` | `(name, args) => PreExecutionResult` | ❌ | 工具执行前检查回调（宿主审批/审计/参数改写通道；装配时与内部幂等检查组合为单点入口） |
-
-> **Logger 注入方式**：v1.0 起 `AgentOptions` 不再含 `logger` 字段。日志通过全局 `setLogger(customLogger)` 注入（详见 §十七 类型导出）；未注入时使用内核内置 console fallback（写 stderr，级别由 `MEMORA_LOG_LEVEL` 控制），内核不做任何运行时模块解析。注入即内核唯一日志出口，对**所有内核模块（含 utils 层）**生效。
-
-### 2.2 生命周期方法
-
-| 方法 | 用途 |
-|------|------|
-| `new Agent(opts)` | 构造函数（无副作用，不连接 LLM） |
-| `init(projectPathOverride?)` → `Promise<ProjectContext>` | 初始化：建立存储、加载配置、组装组件 |
-| `close()` → `Promise<void>` | 关闭：释放项目锁、关闭数据库 |
-
-### 2.3 Agent 只读访问器
-
-| 访问器 | 类型 | 说明 |
-|--------|------|------|
-| `agent.initialized` | `boolean` | 是否已初始化 |
-| `agent.context` | `AgentContext \| null` | 当前项目上下文 |
-| `agent.provider` | `LlmProvider` | 当前前台 Provider |
-| `agent.isBusy` | `boolean` | 是否正在对话中 |
-| `agent.lastInteractionAt` | `Date \| null` | 最近一次 `chat()` 调用时间 |
-
-### 2.4 Manager 访问器（委托模式）
-
-Agent 通过一组 getter 暴露专职 Manager 与组件。详见后续章节。
-
-| 访问器 | 类型 | 职责 |
-|--------|------|------|
-| `agent.rolePack` | `RolePackManager \| null` | 角色包管理 |
-| `agent.tools` | `ToolExecutor \| null` | 工具注册与执行 |
-| `agent.skills` | `SkillManager \| null` | 技能匹配与注入 |
-| `agent.governance` | `MemoryGovernance \| null` | 记忆治理（去重/冲突检测/建议） |
-| `agent.memory` | `MemoryInspector \| null` | 记忆查询 + 写入（`writeXxx` 前缀） |
-| `agent.works` | `WorkProjectionManager \| null` | 作品投影（工作内容摘要） |
-| `agent.polish` | `TextPolishManager \| null` | 文本润色（LLM 语法修正 + 表达优化） |
-
-> **读写统一入口**：`agent.memory`（MemoryInspector）同时负责记忆的查询与写入——只读方法（snapshot/search/searchByKeyword/stats/list/getById/getBySource/listDeleted 等）与写方法（`writeXxx` 前缀：writeUpsert/writeDelete/writeRestore/writePurge/writePurgeExpired。`writeBoost` 已随 score 字段退役删除，2026-09-09）。旧的 `memoryMutator`/`MemoryMutator` 拆分已在后续迭代中合并回 `MemoryInspector`，二者均不再存在。
-
-### 2.5 内部组件访问器（高级）
-
-| 访问器 | 类型 | 说明 |
-|--------|------|------|
-| `agent.agentLoop` | `AgentLoop \| null` | Agent 循环体（`getMessages()` / `getRecentHistory()`） |
-| `agent.agentHistory` | `MessageHistory \| null` | 消息历史（`listAllSessions()` 等） |
-
-### 2.6 `ProjectContext` 字段（`init()` 返回值）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `projectPath` | `string` | 项目根目录的绝对路径 |
-| `projectName` | `string` | 项目名称（从注册表读取，或取目录名） |
-| `memoraDir` | `string` | `.memora/` 目录的绝对路径 |
-| `index` | `IMemoryStorage` | 记忆存储接口 |
-| `security` | `SecurityGuard` | 安全守卫 |
-| `bootstrapMemories` | `Memory[]` | 启动时加载的必召记忆 |
-
-### 2.7 事件订阅（`agent.on()` / `agent.off()` / `agent.once()`）
-
-Agent 继承 `TypedEventEmitter<AgentEventMap>`，向宿主项目广播对话外事件。
-
-```typescript
-agent.on<K extends AgentEventName>(event: K, handler: (payload: AgentEventMap[K]) => void): void
-agent.off<K extends AgentEventName>(event: K, handler: (payload: AgentEventMap[K]) => void): void
-agent.once<K extends AgentEventName>(event: K, handler: (payload: AgentEventMap[K]) => void): void
-```
-
-| 事件名 | 载荷 | 触发时机 |
-|--------|------|----------|
-| `memoryAdded` | `{ id, source, name }` | 记忆被写入存储（round-summary 沉淀等） |
-| `personaSwitched` | `{ from: string \| null, to }` | 角色被切换（手动指定） |
-| `memoryRecalled` | `{ count, query }` | 记忆被召回（用于 UI 展示） |
-| `sessionForked` | `{ from, to, messageCount }` | 会话被分叉（创建新分支） |
-| `projectSwitched` | `{ from: string \| null, to: string, projectName: string }` | 项目切换（宿主 UI 可据此刷新项目相关界面） |
-| `skillMatched` | `{ skill: string, score: number }` | 技能被匹配（宿主 UI 可据此展示当前激活技能） |
-| `archiveFailed` | `{ stage: 'content'; message: string }` | 归档操作失败（仅 content 阶段，fire-and-forget catch 分支发射，宿主可通知用户） |
-
-```typescript
-// 使用示例
-agent.on('memoryAdded', (e) => console.log(`新记忆: ${e.source}:${e.name}`));
-```
-
-> `close()` 自动移除所有事件监听器。
-
-**状态机**：
-```
-[构造] --init()--> [已初始化] --chat()/其他方法...--> [已初始化]
-                              --close()--> [已关闭]
-```
-
-未初始化时调用任何方法**抛 `configError`**。Manager 访问器在 `init()` 前返回 `null`。
-
----
-
-## 三、对话 API
-
-### 3.1 `chat(input, signal?)` — 流式对话（唯一入口）
-
-```typescript
-async *chat(input: string, signal?: AbortSignal): AsyncGenerator<AgentChunk, void, unknown>
-```
-
-流式返回 `AgentChunk` 事件，可选传入 `signal` 支持取消。
-
-```typescript
-type AgentChunk =
-  | { type: 'thinking'; phase: ThinkingPhase }             // 推理阶段
-  | { type: 'text'; content: string }  // LLM 文本片段（流式输出内容）
-  | { type: 'thought'; content: string; stepIndex?: number }  // 模型思考增量（不进正文/记忆）；stepIndex = 所属 step 轮内序号（loop 打标）
-  | { type: 'tool_start'; toolCallId: string; name: string; args?: string; stepIndex?: number }   // 工具调用开始（stepIndex 同 thought；tool_result 经 toolCallId 归属，不重复携带）
-  | { type: 'tool_result'; toolCallId: string; name: string; ok: boolean; summary?: string }  // 工具调用结果
-  | { type: 'aborted'; reason: string }                    // 对话被取消
-  | { type: 'error'; message: string }                     // 流式过程中发生错误（LLM 超时/连接断开）
-  | { type: 'retry'; attempt: number; maxRetries: number; delayMs: number; error: string }  // 指数退避重试
-  | { type: 'done' };                                      // 结束标记
-```
-
-> 上表为核心事件子集（含边界/提问等更多成员的 `AgentChunk` 全集以 [types.ts](../src/agent/types.ts) 为唯一真理源）。
-
-> **记忆召回展示链已退役（2026-09-10）**：`recall` chunk 分支与 `RecalledMemorySummary` 类型已随自动注入退役**物理删除**。记忆纯工具化后，「召回了什么」由 `search_memories` 工具的 `tool_start` / `tool_result` 过程事件天然展示；检索命中含 `accessedAt` / 溯源字段（`sessionId`/`roundId`）。
-
-`ThinkingPhase` 取值：`'recalling' | 'processing' | 'archiving'`
-
-### 3.2 `chatSync(input, signal?)` — 同步版（仅供测试用）
-
-```typescript
-async chatSync(input: string, signal?: AbortSignal): Promise<string>
-```
-
-收集所有 `text` 事件拼接成完整字符串返回。
-
----
-
-## 四、记忆查询与写入（`agent.memory` · MemoryInspector）
-
-> Manager 访问路径：`agent.memory.xxx()`。`init()` 前返回 `null`。
-
-### 4.1 `snapshot()` — 3 层记忆快照
-
-```typescript
-agent.memory.snapshot(): MemorySnapshot
-```
-
-同步返回当前 3 层记忆快照（纯只读、无副作用）：
-
-| 层 | 键 | 内容 |
-|----|-----|------|
-| 第 1 层 | `snapshot.working` | `WorkingMemorySnapshot` — 当前 AgentLoop 消息（最近 5 条预览 + 总数） |
-| 第 2 层 | `snapshot.bootstrap` | `BootstrapSnapshot` — 规则记忆（名称 + 来源 + 权重，Persona/Skill 已解耦为设定记忆，不进 bootstrap） |
-| 第 3 层 | `snapshot.archive` | `ArchiveSnapshot` — 归档记忆计数（round-summary）+ 当前会话信息 |
-
-```typescript
-interface MemorySnapshot {
-  working: WorkingMemorySnapshot;
-  bootstrap: BootstrapSnapshot;
-  archive: ArchiveSnapshot;
-}
-```
-
-### 4.2 `search(query, limit?)` — 记忆搜索
-
-```typescript
-// ⚠️ @deprecated 同步通道已退役（2026-09-20），改用 searchByKeyword()。实证无生产/宿主消费方。
-agent.memory.search(query: string, limit?: number): AgentSearchHit[]
-```
-
-```typescript
-interface AgentSearchHit {
-  id: string;             // 记忆唯一标识（source:name 格式，供 showMemory/deleteMemory 等操作使用）
-  name: string;           // 记忆名称
-  source: string;         // 来源标签
-  contentPreview: string; // 内容预览（截断到 120 字符）
-  createdAt?: string;     // 创建时间（ISO 8601，供 UI 层时间筛选/排序使用）
-}
-```
-
-### 4.3 `stats()` — 记忆库统计
-
-```typescript
-agent.memory.stats(): AgentStats
-```
-
-```typescript
-interface AgentStats {
-  bySource: Record<string, number>; // 按来源标签分组的记忆数量
-  total: number;                    // 记忆总数
-}
-```
-
-### 4.4 `agent.agentLoop.getMessages()` — 工作记忆原始消息
-
-```typescript
-agent.agentLoop.getMessages(): readonly Message[]
-```
-
-### 4.5 写入方法
-
-记忆的写入统一收口在 `agent.memory`，写方法以 `writeXxx` 前缀命名（同步返回、不调 LLM、不触发异步 IO）：
-
-```typescript
-// ─── 写入（writeXxx 前缀） ───
-agent.memory.writeUpsert(memory: Memory): void;                 // 插入或更新记忆
-agent.memory.writeDelete(id: string): void;                    // 软删除（写入 deletedAt）
-agent.memory.writeRestore(id: string): void;                   // 恢复软删除
-agent.memory.writePurge(id: string): void;                     // 物理删除（不可恢复）
-agent.memory.writePurgeExpired(before: Date): number;          // 清理过期回收站
-
-// ─── 只读扩展查询 ───
-agent.memory.list(limit?: number): Memory[];                   // 列出所有记忆（按 accessedAt 降序；score 已随 2026-09-09 退役）
-agent.memory.getById(id: string): Memory | null;               // 按 ID 获取活跃记忆
-agent.memory.getBySource(source: string): Memory[];            // 按 source 获取
-agent.memory.listDeleted(limit?: number): Memory[];            // 回收站（软删除记忆）
-agent.memory.getDeletedById(id: string): Memory | null;
-agent.memory.searchByKeyword(query: string, limit?: number): Promise<AgentSearchHit[]>; // 纯关键词通道
-```
-
-> **注意**：`suggest()` / `sourceHealth()` 经 `agent.governance` 暴露（`.suggest()` / `.sourceHealth()`），不挂在 `agent.memory` 下，避免经 MemoryInspector 转发产生多余代理层。
-
----
-
-## 五、Memory 模型（基元驱动）
-
-```typescript
-interface Memory {
-  id: string;         // 唯一标识（source:name 格式，如 'rule:core'）
-  content: string;    // 记忆内容（Markdown 文本）
-  source: string;     // 来源标签（开放字符串，非枚举）
-  name: string;       // 可读名称
-  createdAt: string;  // 创建时间（ISO 8601）
-  accessedAt: string; // 最后访问时间（每次召回时刷新）
-  deletedAt?: string; // 软删除时间（ISO 8601，可选；非 undefined 表示已软删除。回收站**无自动清理**：保留期清理由宿主入口显式触发，见 writePurgeExpired）
-  metadata?: Record<string, string>; // 配置文件 frontmatter 额外元数据（仅配置文件写入路径使用，不进记忆库）
-  summaryType?: SummaryType; // round-summary 摘要类型（preference/fact/decision/intent/general；顶层持久化字段）
-  sessionName?: string;  // round-summary 归属会话标识（顶层持久化字段，仅 round-summary 有意义）
-  roundId?: string;      // round-summary 归属轮次标识（顶层持久化字段，仅 round-summary 有意义）
-  isModified?: boolean;  // 摘要是否已被人工修改（仅 round-summary 有意义）
-  supersededBy?: string; // 写路径取代标记：非 undefined 表示已被更新的摘要覆盖，召回时确定性过滤
-}
-```
-
-> **字段基线**（score 已退役）：`score` 字段已随 2026-09-09 阶段3 物理删除（无持久化排序分字段，使用轨迹唯一事实源为 `accessedAt`）；向量语义通道已随 2026-09-18 B0 收编（检索为纯关键词单通道）。round-summary 溯源/分类字段（summaryType/sessionName/roundId）已提升为顶层持久化字段（metadata 不进记忆库）。所有查询方法（getById/getBySource/search/count/countBySource/getAllSources）自动过滤 `deletedAt != undefined` 的记忆。详见 ADR-004 GAP-6 + ADR-002 §IMemoryStorage。
-
-**常用 source 标签（`SOURCE_LABELS` 常量）：**
-
-| 常量 | 值 | 用途 |
-|------|----|------|
-| `SOURCE_LABELS.PERSONA` | `'persona'` | 角色人格（残留兼容标签，已随 ADR-025 归角色包、不进记忆库） |
-| `SOURCE_LABELS.RULE` | `'rule'` | 创作规则（残留兼容标签，已随 ADR-025 归角色包、不进记忆库） |
-| `SOURCE_LABELS.SKILL` | `'skill'` | 技能定义（残留兼容标签，已随 ADR-025 归角色包、不进记忆库） |
-| `SOURCE_LABELS.WORK_PROJECTION` | `'work-projection'` | 作品投影（已移出记忆库，2026-08-20 落项目目录 projections/） |
-| `SOURCE_LABELS.ROUND_SUMMARY` | `'round-summary'` | 轮次摘要（当前实际写入记忆库的主要 source） |
-| `SOURCE_LABELS.UNKNOWN` | `'unknown'` | 未知来源（未被已知标签覆盖时的兜底值） |
-
-> source 是开放字符串，宿主可自定义新标签。`validateSource()` 可检测常见 typo（基于 Levenshtein 距离）。PERSONA/RULE/SKILL/WORK_PROJECTION 四标签**仅作历史兼容与 typo 检测**保留，已不进入治理范围（`GOVERNANCE_SOURCES`）——当前写入记忆库的主要 source 为 `round-summary`。
-
-### 5.2 `IMemoryStorage` 接口
-
-宿主实现此接口注入 Agent，替代默认的 `InMemoryStorage`。共 **15 方法**（14 必需 + 可选 `close`），所有方法同步（与 better-sqlite3 API 对齐，`await` 同步值安全）。所有查询方法自动过滤已软删除的记忆（`deletedAt != undefined`）。
-
-```typescript
-interface IMemoryStorage {
-  // ─── 基础 CRUD（6 方法） ───
-  upsert(memory: Memory): void;
-  getById(id: string): Memory | null;
-  getBySource(source: string): Memory[];
-  search(query: string, limit?: number): Memory[];
-  count(): number;
-  countBySource(source: string): number;
-
-  // ─── 软删除 / 回收站（6 方法，ADR-004 GAP-6 扩展） ───
-  delete(id: string): void;           // 软删除（写入 deletedAt，不物理移除；对已软删除的 no-op）
-  restore(id: string): void;          // 恢复软删除记忆（清除 deletedAt；对活跃记忆 no-op）
-  purge(id: string): void;            // 物理删除（不可恢复，用于回收站"彻底删除"）
-  listDeleted(limit?: number): Memory[];        // 列出回收站（按 deletedAt 降序；limit 缺省/≤0 = 全部，正整数 = 最近 N 条）
-  getDeletedById(id: string): Memory | null;    // 按 ID 获取单条软删除记忆（restore/purge 前存在性校验）
-  purgeExpired(before: Date): number;           // 清理过期回收站（物理删除 deletedAt 早于 before 的，返回清理数量）
-
-  // ─── 统计与维护（2 方法） ───
-  touch(id: string, now: string): boolean;  // 刷新 accessedAt（score 退役后唯一写位；不写 score、无 clamp 语义）
-  getAllSources(): Map<string, number>;     // 获取所有 source 标签及其活跃记忆数量
-
-  // ─── 可选（1 方法） ───
-  close?(): void;
-}
-```
-
-> 宿主实现应使用 `COUNT(*)` / `UPDATE ... WHERE` 等数据库原生操作，避免全量加载数据。`getAllSources` 是性能优化方法，避免逐条遍历。详见 ADR-002 §IMemoryStorage 接口方法。
-
-### 5.3 `ISessionStore` 接口
-
-宿主实现此接口提供会话消息的持久化能力。
-
-```typescript
-interface ISessionStore {
-  appendMessage(date: string, session: string, message: SessionMessage): void;
-  loadMessages(date: string, session: string): SessionMessage[];
-  listSessions(): string[];
-}
-```
-
----
-
-## 六、项目 / 会话管理
-
-> **方法归属**：项目相关方法在 `agent.projects`（ProjectManager），会话相关方法在 `agent.sessionManager`（SessionManager），仅 `switchProject` / `rebuildComponents` / `forkSession` 保留在 Agent 面类作为常用入口。
-
-> **switch* 返回值约定**：各 switch 操作返回与其操作语义最匹配的值 ——
-> `switchSession` 返回新会话名（string）、`switchProject` 返回完整项目上下文（AgentContext，含 bootstrap 记忆等）、
-> `agent.switchRolePack` 返回布尔值（是否切换成功）。这是设计性差异，非 bug。
-
-### 6.1 Agent 面类方法（项目/会话入口）
-
-| 方法 | 用途 |
-|------|------|
-| `switchProject(nameOrPath)` → `Promise<AgentContext>` | 切换到指定项目（保留 Agent 级记忆，自动 rebuild） |
-| `rebuildComponents()` → `Promise<void>` | 重建 history / loop（通常不需要手动调用，switchProject 已自动执行） |
-| `forkSession(targetSession?)` → `AgentForkResult` | 分叉当前会话（同步，复制完整消息历史到新分支） |
-
-### 6.2 `agent.projects` — ProjectManager
-
-| 方法 | 用途 |
-|------|------|
-| `projects.list` | 所有已注册项目（getter） |
-| `projects.listProjects()` → `ProjectEntry[]` | 列出所有已注册项目 |
-
-### 6.3 `agent.sessionManager` — SessionManager
-
-| 方法 | 用途 |
-|------|------|
-| `sessionManager.switchSession(newName)` → `string` | 切换到指定会话（chatBusy 时抛 configError） |
-| `sessionManager.forkSession(targetSession?)` → `AgentForkResult` | 分叉当前会话 |
-| `sessionManager.loadSessionMessages(date, session)` → `Promise<SessionMessage[]>` | 加载指定日期/会话的消息（含时间戳） |
-| `sessionManager.restoreMostRecentSession()` → `Promise<number>` | 恢复最近活跃会话（SSOT：listSessionMetas[0]，updatedAt 降序；绝不隐式创建——新建会话唯一入口为宿主手动按钮） |
-| `sessionManager.restoreSession(date, session)` → `Promise<number>` | 恢复指定日期/会话 |
-| `sessionManager.createCheckpoint(mainGoal?)` → `SessionCheckpoint \| null` | 创建当前会话检查点（含热记忆、目标、计划、状态机快照），首次调用返回完整检查点，后续调用合并增量。**同进程内存态**（2026-09-10 减法后不落盘） |
-| `sessionManager.getCheckpoint()` → `SessionCheckpoint \| null` | 获取当前检查点（只读，不修改状态） |
-| `sessionManager.discardCheckpoint()` → `boolean` | **Phase 4 新增**：放弃当前暂停检查点（对称 pause 创建，宿主 handleStop paused 态调之；停定时器 + 清内存 + resetToRunning；无检查点返回 false） |
-
-```typescript
-// 项目列表
-const projects = agent.projects.list;
-
-// 会话分叉示例（Agent 面类入口，等价于 agent.sessionManager.forkSession()）
-const forkResult = agent.forkSession();
-console.log(`分叉到 ${forkResult.newSession}，复制了 ${forkResult.messageCount} 条消息`);
-
-// 自定义分支名
-const customFork = agent.forkSession('experiment');
-
-// listAllSessions 通过 agentHistory 访问
-const sessions = await agent.agentHistory?.listAllSessions();
-```
-
-### `AgentForkResult` / `ForkResult` 类型
-
-```typescript
-// Agent.forkSession() / sessionManager.forkSession() 返回值
-interface AgentForkResult {
-  newSession: string;
-  messageCount: number;
-}
-
-// MessageHistory.forkSession() 内部类型（从 memora 导出）
-export interface ForkResult {
-  date: string;
-  newSession: string;
-  messages: SessionMessage[];
-}
-```
-
----
-
-## 七、角色包管理（`agent.rolePack` · RolePackManager）
-
-> Manager 访问路径：`agent.rolePack`（RolePackManager，`init()` 前返回 `null`）。角色包是「设定记忆唯一载体」（persona/rules/skills 归属角色包，见 memory-role-pack-boundary 纪律）。
-
-| 成员 | 类型 | 说明 |
-|------|------|------|
-| `rolePack.listMeta()` | `RolePackMeta[]` | 所有角色包元数据（name / displayName / description / version / ...） |
-| `rolePack.activeName` | `string \| null`（getter） | 当前激活的角色包名（null = 未激活） |
-| `rolePack.getActive()` | `RolePackAssembly \| null` | 当前激活的完整角色包对象（含合并后策略） |
-| `rolePack.getActiveRules()` | `string[]` | 当前激活角色包的规则列表 |
-| `rolePack.getActiveTraits()` | `Record<string, number> \| undefined` | 当前激活角色包的 traits（clamp 0-1） |
-| `rolePack.activate(name)` | 方法 → `boolean` | 手动切换到指定角色包（30s 内超 5 次切换后锁 2 分钟防抖） |
-| `rolePack.getSwitchLockStatus()` | 方法 → `{ locked, unlockAt }` | 切换防抖锁定状态 |
-| `rolePack.onRolePackActivated(handler)` | 方法 | 注册激活变更回调（`(from, to)`） |
-
-```typescript
-// 使用示例
-const rp = agent.rolePack;
-if (!rp) throw new Error('rolePack 未就绪');
-const metas = rp.listMeta();           // 列出所有角色包
-rp.activate('作家');                    // 切换角色包
-console.log(rp.activeName);            // 当前角色包名
-const lock = rp.getSwitchLockStatus(); // 切换防抖状态
-```
-
----
-
-## 八、工具注册（`agent.tools` · ToolExecutor）
-
-> 工具注册/执行走 `agent.tools.xxx()`。
-
-### 8.1 内置工具（核心摘要：默认常驻 + 条件暴露，非全集）
-
-| 工具名 | 用途 | 参数 | 暴露条件 |
-|--------|------|------|------|
-| `read_file` | 读取项目内文件内容（**按行分段返回**：单次输出 token 数 ≤ `LOOP_CONSTANTS.SINGLE_TOOL_RESULT_MAX_TOKENS`＝6000；未读到末尾时附「[read_file 分段]」脚注，给出已显示行号区间、总行数与续读 offset） | `path`, `offset?`, `limit?` | 默认常驻 |
-| `write_file` | 写入/创建文件（支持 overwrite/append/insert/replace 四种模式） | `path`, `content`, `mode?`, `insert_line?`, `old_string?` | 默认常驻 |
-| `list_dir` | 列出目录内容（递归深度 ≤ 3） | `path?`, `recursive?`, `maxDepth?` | 默认常驻 |
-| `search_memories` | 在记忆索引中搜索（支持 match/near 两种模式） | `query`, `limit?`, `mode?` | 默认常驻 |
-| `run_project_script` | 运行**项目内既有**脚本（内核子进程，cwd=项目根；路径白名单越界拒绝；扩展名推断 node/python/shell；超时 30s 上限 120s） | `script_path`, `args?` | 默认常驻（零注入） |
-| `run_skill_script` | 执行技能目录下的脚本（渐进披露 L3） | `skill_name`, `script_path`, `args?` | 默认常驻（来源=技能作者） |
-| `web_search` | 搜索互联网 | `query`, `limit?` | 条件暴露（注入 `IWebSearchProvider`） |
-| `web_fetch` | 抓取网页正文（与 `web_search` 成对闭环） | `url`, `limit?` | 条件暴露（注入 `IFetchProvider`） |
-| `run_code` | LLM 现写代码执行（特权：`code:execute` 声明 + 宿主沙箱注入） | `language`, `code` 或 `script_path` | 条件暴露（注入 `ICodeExecutionProvider` 且角色包声明特权） |
-
-### 8.2 `agent.tools` — ToolExecutor
-
-| 方法 | 用途 |
-|------|------|
-| `tools.registerTool(definition, handler)` | 注册自定义工具（会话级） |
-| `tools.list` | 所有工具定义（getter，`ToolDefinition[]`） |
-| `tools.execute(name, argsJson, extensions?)` → `Promise<string>` | 执行工具调用 |
-
-```typescript
-// 工具定义
-interface ToolDefinition {
-  name: string;
-  description: string;
-  parameters: {
-    type: 'object';
-    properties: Record<string, { type: string; description: string }>;
-    required: string[];        // 必填参数列表（不可省略）
-  };
-}
-
-// 宿主注册领域工具示例
-agent.tools.registerTool(
-  {
-    name: 'web_search',
-    description: '搜索互联网，返回结构化结果',
-    parameters: {
-      type: 'object',
-      properties: {
-        query: { type: 'string', description: '搜索关键词' },
-        limit: { type: 'number', description: '最大返回条数', default: 5 },
-      },
-      required: ['query'],
-    },
-  },
-  async (args) => {
-    const res = await fetch(`https://api.example.com/search?q=${encodeURIComponent(args.query)}`);
-    return await res.json();
-  },
-);
-```
-
-### 8.3 `IWebSearchProvider` — 网络搜索注入接口
-
-> 宿主实现此接口并注入 `AgentOptions.webSearchProvider`，即可让 Agent 拥有网络搜索能力。
-> 未注入时，Agent 不会暴露 `web_search` 工具给 LLM，LLM 被告知搜索不可用。
-> 内核提供 `FetchWebSearchProvider` 作为零依赖默认实现（`buildSearchEndpoints` 构建内置 Bing/DuckDuckGo 等预设降级链）。
-> **主推宿主自建 `SearchEndpoint` 注入**（自带 URL+解析），内核预设仅作零配置保底。
-
-```typescript
-// 搜索结果
-interface SearchResult {
-  title: string;
-  url: string;
-  snippet: string;
-  endpoint?: string;  // 实际后端名（降级打标用，自定义实现可省略）
-}
-
-// 搜索选项
-interface WebSearchOptions {
-  limit?: number;  // 返回结果数量上限（默认 5）
-}
-
-// 搜索端点契约：宿主可自建（自带 URL+解析）覆盖内核预设
-interface SearchEndpoint {
-  name: string;                       // 端点名（降级打标 / 结果透出）
-  buildUrl(query: string): string;    // 由查询构造请求 URL
-  parse(html: string, limit: number): SearchResult[];  // 解析结果页
-}
-
-// 网络搜索提供者接口
-interface IWebSearchProvider {
-  search(query: string, options?: WebSearchOptions): Promise<SearchResult[]>;
-}
-
-// 注入方式
-const agent = new Agent({
-  // ... 其他选项
-  // 方案 1（保底）：内置默认实现（Bing→DuckDuckGo 零配置开箱即用）
-  webSearchProvider: new FetchWebSearchProvider(),
-  // 方案 2（主推）：宿主自建端点注入，URL/解析完全由宿主掌控
-  // webSearchProvider: new FetchWebSearchProvider([
-  //   { name: 'MyEngine', buildUrl: (q) => `https://my.engine/s?q=${q}`, parse: myParse },
-  // ]),
-});
-
-// buildSearchEndpoints：预设名与自定义端点混排，内核预设仅作保底
-// buildSearchEndpoints(['bing', myEndpoint])  // 自定义端点优先，未知名忽略
-```
-
-### 8.4 `IFetchProvider` — 网页抓取注入接口（搜索→抓取闭环第二段）
-
-> 宿主实现此接口并注入 `AgentOptions.fetchProvider`，即可让 Agent 读取 `web_search` 找到的候选链接正文。
-> 未注入时，Agent 不会暴露 `web_fetch` 工具给 LLM。
-> 内核提供 `FetchWebFetchProvider` 作为基于内置 `fetch` + 正则清洗 HTML 的零依赖默认实现；`safeFetch` 为带 30s 超时保护的包装（抓取失败/超时降级返回友好提示，不中断主流程）。
-
-```typescript
-// 抓取结果
-interface FetchedPage {
-  url: string;
-  title: string;
-  content: string;
-  contentType?: string;
-}
-
-// 抓取选项
-interface FetchOptions {
-  maxChars?: number;  // 正文截断字符数上限
-}
-
-// 网页抓取提供者接口
-interface IFetchProvider {
-  fetch(url: string, options?: FetchOptions): Promise<FetchedPage>;
-}
-
-// 注入方式
-const agent = new Agent({
-  // ... 其他选项
-  fetchProvider: new FetchWebFetchProvider(), // 使用内置默认实现
-});
-```
-
-### 8.5 `ICodeExecutionProvider` — 代码执行注入接口
-
-> 宿主实现此接口并注入 `AgentOptions.codeExecutionProvider`，即可让 Agent 拥有通用代码执行能力（计算 / 数据处理 / 验证）。
-> 未注入时，Agent 不会暴露 `run_code` 工具给 LLM。
-> **内核零运行时依赖**：沙箱执行（语言白名单 / 资源限制 / 网络隔离）完全由宿主 provider 决定；`safeExecuteCode` 为带 120s 超时保护的包装（执行失败/超时降级返回错误结果，不中断主流程）。
-
-```typescript
-// 执行结果
-interface CodeExecutionResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  timedOut: boolean;
-}
-
-// 执行选项
-interface CodeExecutionOptions {
-  timeoutMs?: number;  // 单次执行超时上限
-}
-
-// 代码执行提供者接口
-interface ICodeExecutionProvider {
-  execute(code: string, language: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
-}
-
-// 注入方式（沙箱实现由宿主提供）
-const agent = new Agent({
-  // ... 其他选项
-  codeExecutionProvider: mySandboxProvider,
-});
-```
-
-### 8.6 `IProjectSearchProvider` — 项目内搜索注入接口
-
-> 宿主实现此接口并注入 `AgentOptions.projectSearchProvider`，即可让 Agent 具备「在当前项目（工作区）中搜索」能力（等价 IDE 全局搜索 `Ctrl+Shift+F`）。
-> 未注入时，Agent 不会暴露 `search_project` 工具给 LLM。
-> **内核零依赖**：目录遍历 / 忽略规则 / 扫描与结果上限全由宿主决定；内核提供 `safeSearchProjectFiles` / `safeSearchProjectText` 两个带 30s 超时保护的包装，并内置由分词 SSOT 产出的**放宽词表**（`buildSearchTerms`）。
-
-```typescript
-// 文件名命中
-interface ProjectFileMatch {
-  path: string;            // 相对项目根的 posix 路径
-}
-
-// 内容命中
-interface ProjectTextMatch {
-  path: string;
-  line?: number;           // 命中行号（1 起）
-  preview?: string;        // 命中行预览（去控制字符 + 限长，防上下文注入）
-}
-
-// 内容搜索的**结果对象**（含本次检索的元信息）
-interface ProjectTextSearchResult {
-  matches: ProjectTextMatch[];
-  truncated: boolean;                        // 检索被截断（零命中时也须如实回报）
-  truncatedBy?: 'results' | 'files';         // 截断主因：结果达上限 / 扫描达文件上限
-  scannedFiles?: number;                     // 实际参与匹配的文件数（宿主上报的数据）
-  partialReadFiles?: number;                 // 只检索了前一部分（过大）的文件数（**参与了**检索，非跳过）
-  unreadableSkipped?: number;                // 读取失败（权限/被删/悬空链接）完全未参与检索的文件数
-  perFileCapped?: boolean;                   // 有文件的命中被单文件上限截断
-  failed?: boolean;                          // 检索自身失败（超时/抛错）≠ 真零命中
-  relaxed?: boolean;                         // 已放宽为分词匹配 → 结果**非精确**命中
-  termsUsed?: string[];                      // 放宽时实际使用的词（文案的唯一取值来源）
-}
-
-interface ProjectTextSearchOptions extends ProjectFileSearchOptions {
-  pattern: string;         // 内容关键词（**字面量**语义，宿主自行转义，内核不假定正则）
-  terms?: string[];        // 内核下发的放宽词表；宿主**仅在整串零命中时**才启用
-}
-
-interface IProjectSearchProvider {
-  searchFiles(options?: ProjectFileSearchOptions): Promise<ProjectFileMatch[]>;
-  searchText(options: ProjectTextSearchOptions): Promise<ProjectTextSearchResult>;
-}
-```
-
-**实现约定（宿主侧，三条都是契约而非建议）**：
-
-1. **精确优先 + 零命中回退**：先按 `pattern` 整串字面量匹配；整串零命中**且** `terms` 非空时，才用 `terms` 做一次 OR 放宽，并置 `relaxed` + 回填 `termsUsed`（多词无需拆开传，**任一分词命中即算**，不是"全部包含"）。整串已命中时不得放宽——否则精确命中会退化成"可能不是精确命中"。
-2. **三态必须可区分**：`failed`（没搜完/搜坏了）/ `truncated`（没搜全）/ 真零命中，三者不得再压成同一个空数组——`[]` 承载不了任何元信息，会把"没搜到"与"没搜完"变成逐字同形。失败**不要**返回工具错误（"no results is not an error"），如实回报 `failed` 即可，由内核分流文案。
-3. **预算量以数据上报，不提升为内核常量**：`scannedFiles` / `partialReadFiles` / `unreadableSkipped` / `perFileCapped` 是宿主内部预算（扫描文件数 / 单文件字节 / 单文件命中数）与**读取结果**的事实；内核从不扫描，因此不持有这些常量，只把它们写进给 LLM 的文案。同理，`truncatedBy` 由宿主判定（只有宿主知道自己是因何停下）。
-   ⚠️ `partialReadFiles`（看了但没看全）与 `unreadableSkipped`（根本没看上）**必须分开上报**：两者都是「零命中 ≠ 不存在」的依据，但补救动作不同——前者换更具体的关键词或 `read_file` 精读，后者可重试。
-
-**放宽词表（内核侧）**：`buildSearchTerms(query)` 采用「显式片段优先」——空白分隔的片段是一等公民，不含 CJK 的片段原样保留（`Next.js` 不会被切成 `next` + `js`），含 CJK 的片段交给分词 SSOT。调用方（内核 `ToolExecutor`）会剔除与整串等价的词，因此单段查询通常不会触发放宽轮。
-
-> 参考实现：VS Code 宿主 `hosts/memora-vscode/src/extension/host/projectSearchProvider.ts`（`mode=name` 走 `workspace.findFiles`；`mode=content` 走受限 fs 递归扫描，忽略 `IGNORED_DIR_NAMES`）。
-
----
-
-## 九、作品投影（`agent.works` · WorkProjectionManager）
-
-作品投影是文件内容的轻量级摘要（50-100 字概要 + 结构 + 关键决策），存储在**项目级目录** `<memoraDir>/projections/<slug>.json`（不进入记忆库）。原始文件内容不进投影，Agent 通过工具按需读取。
-
-> **与记忆系统的边界**：作品投影是"作品感知"而非"对话记忆"（对话记忆唯一为 round-summary，沉淀在记忆库）。它**不参与记忆召回、不参与记忆治理**（去重/冲突检测不覆盖），随项目隔离——换项目即消失。宿主如需让模型感知投影，可显式经 `agent.works.loadAll()` 注入。
-
-### 类型定义
-
-```typescript
-interface WorkProjectionEntry {
-  id: string;            // 唯一 ID（work-proj-<slug>）
-  sourcePath: string;    // 文件路径
-  fileHash: string;      // 文件 hash（SHA-256，用于变更检测）
-  summary: string;       // 概要（50-100 字）
-  structure: string[];   // 结构（章节/模块列表，2-8 个）
-  keyDecisions: string[];// 关键决策（1-3 个）
-  updatedAt: string;     // 最后更新时间
-}
-```
-
-### `agent.works` 公开方法
-
-| 方法 | 用途 |
-|------|------|
-| `agent.works.ensureProjection(filePath, content, fileName?)` | 检查并更新作品投影（核心方法）。计算 hash → 查询已有投影 → 无则生成 / hash 变则重新生成 / hash 同则跳过。同文件并发调用时复用 in-flight Promise，避免重复 LLM 调用 |
-| `agent.works.getProjection(filePath)` | 获取已有的作品投影（不触发生成） |
-| `agent.works.loadAll()` | 加载所有作品投影（扫描项目目录 `<memoraDir>/projections/`，非记忆召回） |
-
-> **注意**：`agent.works` 在 `init()` 前返回 `null`。`ensureProjection` 依赖后台 LLM Provider 生成摘要，未注入 `backgroundProvider` 时使用前台 Provider。
-
-### 宿主接入示例
-
-```typescript
-// 宿主工具读取文件后，调用 ensureProjection 生成/更新投影
-agent.tools.registerTool(
-  {
-    name: 'read_file',
-    description: '读取文件内容',
-    parameters: { /* ... */ },
-  },
-  async (args) => {
-    const content = await fs.readFile(args.path, 'utf-8');
-    // 异步生成投影（fire-and-forget，不阻塞工具返回）
-    void agent.works?.ensureProjection(args.path, content);
-    return content;
-  },
-);
-```
-
----
-
-## 十、Provider 管理
-
-| 方法 | 用途 |
-|------|------|
-| `setProvider(provider)` | 运行时切换前台 Provider |
-| `setBackgroundProvider(provider)` | 运行时切换后台 Provider |
-
-Agent 不再管理 Provider 映射表，宿主自行管理。
-
----
-
-## 十一、内部调试
-
-> v1.0 起已移除 `getBuildCtx()` 和 `inspect()` 方法。宿主项目可通过以下渠道观察内核状态：
->
-> - **事件系统**（§2.7）：订阅 `memoryAdded` / `memoryRecalled` / `skillMatched` 等事件获取运行时动态
-> - **可观测性 Tracer**（§十四）：注入 `ITracer` 实现获取 AgentLoop 关键 span（RECALL / LLM_CALL / TOOL_EXEC / RESPONSE）
-> - **`agent.memory.snapshot()`**（§4.1）：获取 3 层记忆快照（working / bootstrap / archive）
-> - **`agent.agentLoop.getMessages()`**（§4.4）：获取工作记忆原始消息列表
-
----
-
-## 十二、完整 API 一览
-
-### Agent 面类直接方法
-
-| 分组 | 方法 |
-|------|------|
-| 生命周期 | `init(projectPathOverride?)` / `close()` |
-| 对话 | `chat(input, signal?)` / `chatSync(input, signal?)` / `processEvent(event)` / `resumeExecution()` / `forceReleaseChatLock()` |
-| 事件 | `on()` / `off()` / `once()`（继承自 TypedEventEmitter） |
-| 暂停/继续 | `pause(reason, source?, lowRisk?)` / `resume()` / `requestPause(reason, source?)` / `cancelPauseRequest()` / `isPausePending()` / `interject(content)` / `removePendingInterject(index)` / `clearPendingInterjections()` / `getPendingInterjections()` / `discardCurrentCheckpoint()` / `canContinueWithoutInput()` |
-| 项目 / 会话 | `switchProject(nameOrPath)` / `rebuildComponents()` / `forkSession(targetSession?)` / `createCheckpoint(mainGoal?, role?, standard?)` / `getCheckpoint()` |
-| Provider | `setProvider(provider)` / `setBackgroundProvider(provider)` |
-| 归档模式 | `setArchiveMode(mode)` / `getArchiveMode()` |
-| 角色 | `switchRolePack(name)` / `getRolePackSwitchLockStatus()` / `getActiveTraits()` / `injectAffect(affectString)` |
-| 手动归档 | `archiveSession(...)` |
-| 配置热更新 | `reloadConfig(source?)` |
-| 记忆治理 | 经 `agent.governance` 暴露（`.deduplicate()` / `.detectConflicts()` / `.sourceHealth()` / `.suggest()`，见下方 Manager 成员） |
-| 指标 | `getMetrics()` |
-
-### Agent 面类只读访问器
-
-`initialized` / `context` / `provider` / `isBusy` / `lastInteractionAt` / `agentLoop` / `agentHistory` / `projects` / `security` / `sessionManager` / `rolePack` / `tools` / `skills` / `governance` / `memory` / `works` / `polish`
-
-### 各 Manager / 组件公开成员
-
-| 访问器 | 类型 | 公开成员 |
-|---------|---------|---------|
-| `agent.rolePack` | `RolePackManager` | `.listMeta()` / `.activeName` / `.getActive()` / `.getActiveRules()` / `.activate()` / `.getSwitchLockStatus()` / `.getActiveTraits()` |
-| `agent.tools` | `ToolExecutor` | `.list` / `.registerTool()` / `.execute()` |
-| `agent.skills` | `SkillManager` | `.list` / `.match()` / `.register()` / `.buildSystemPrompt()` |
-| `agent.governance` | `MemoryGovernance` | `.deduplicate()` / `.detectConflicts()` / `.sourceHealth()` / `.suggest()` |
-| `agent.memory` | `MemoryInspector` | 读：`.snapshot()` / `.search()` / `.searchByKeyword()` / `.stats()` / `.list()` / `.getById()` / `.getBySource()` / `.listDeleted()`；写：`.writeUpsert()` / `.writeDelete()` / `.writeRestore()` / `.writePurge()` / `.writePurgeExpired()` |
-| `agent.works` | `WorkProjectionManager` | `.ensureProjection(filePath, content, fileName?)` / `.getProjection(filePath)` / `.loadAll()` |
-| `agent.polish` | `TextPolishManager` | `.polish(...)`（文本润色：LLM 语法修正 + 表达优化） |
-
-> **说明**：`suggest()` / `sourceHealth()` 经 `agent.governance` 暴露，不挂在 `agent.memory` 下。旧的 `memoryMutator` 访问器与 `MemoryMutator` 类已合并回 `MemoryInspector`，请勿再使用。
-
----
-
-## 十三、可观测性（ITracer / ISpan）
-
-Memora 内置轻量 Span/Trace 抽象，宿主注入实现后可观测 AgentLoop 行为。
-
-### 13.1 ITracer 接口
-
-```typescript
-interface ITracer {
-  startSpan(name: string, attributes?: Record<string, string | number | boolean>): ISpan;
-}
-```
-
-### 13.2 ISpan 接口
-
-```typescript
-interface ISpan {
-  setAttribute(key: string, value: string | number | boolean): void;
-  end(): void;
-  recordException(error: Error): void;
-}
-```
-
-### 13.3 NoopTracer（默认实现）
-
-```typescript
-import { NOOP_TRACER } from '@zooique/memora';
-
-// 不注入 tracer 时自动使用 NOOP_TRACER，零运行时开销
-// NOOP_TRACER.startSpan() 返回共享的 NoopSpan 单例，所有方法为空操作
-```
-
-### 13.4 TRACE_SPANS 常量
-
-```typescript
-import { TRACE_SPANS } from '@zooique/memora';
-
-TRACE_SPANS.LLM_CALL         // 'llm.call'           — LLM API 调用
-TRACE_SPANS.TOOL_EXEC        // 'tool.execute'       — 工具执行
-TRACE_SPANS.RESPONSE         // 'response.generate'  — 整轮响应
-TRACE_SPANS.CONTEXT_SUMMARY  // 'context.summary'    — 上下文摘要生成（消息超窗触发截断时）
-TRACE_SPANS.POST_PROCESS     // 'archive.postProcess' — 每轮 chat() 后的归档处理
-TRACE_SPANS.DIFFICULTY       // 'round.difficulty'   — 难度分级（预留名）
-TRACE_SPANS.REPORT           // 'round.report'       — 汇报闭环（预留名）
-```
-
-> 共 **7** 个常量（数量由 `src/agent/__tests__/tracer.test.ts` 锁定）。
->
-> **预留名**：`DIFFICULTY` / `REPORT` 内核当前**零 emit 点**——宿主按名建监控面板暂时收不到这两个 span 的数据，不要据此判定链路异常。
->
-> **已删除**：`TRACE_SPANS.RECALL`（`'recall.recall'`）与 `TRACE_SPANS.RECALL_ACTUAL`（`'recall.actual'`）已于 **2026-09-11 物理删除**（自动记忆召回退役后无 emit 点，不留幽灵契约）；现行记忆检索耗时看 `TOOL_EXEC`（`search_memories` 工具）。
-
----
-
-## 十四、工具错误码（ToolErrorCode）
-
-工具执行失败时，错误结果包含 `[ERR:TOOL:code]` 前缀，供 Reflection 逻辑和宿主项目解析。
-
-### 14.1 错误码枚举
-
-| 错误码 | 可重试 | 说明 |
-|--------|--------|------|
-| `PATH_NOT_ALLOWED` | ❌ | 路径不在白名单内 |
-| `FILE_NOT_FOUND` | ✅ | 文件不存在（LLM 可能用错路径） |
-| `PERMISSION_DENIED` | ❌ | 权限不足 |
-| `ARGUMENT_ERROR` | ✅ | 工具参数错误（LLM 可修正参数格式） |
-| `TOOL_TIMEOUT` | ✅ | 工具执行超时 |
-| `WRITE_REJECTED` | ❌ | 用户拒绝写入 |
-| `DIR_NOT_FOUND` | ✅ | 目录不存在 |
-| `UNKNOWN_TOOL` | ❌ | 未知工具 |
-| `CUSTOM_TOOL_FAILED` | ✅ | 自定义工具执行失败 |
-| `UNKNOWN` | ❌ | 通用错误 |
-
-### 14.2 isRetryableErrorCode()
-
-```typescript
-import { ToolErrorCode, isRetryableErrorCode } from '@zooique/memora';
-
-isRetryableErrorCode(ToolErrorCode.FILE_NOT_FOUND);   // true
-isRetryableErrorCode(ToolErrorCode.PATH_NOT_ALLOWED);  // false
-```
-
----
-
-## 十五、工具错误反思（Reflection）
-
-> 注：原「内容护栏（Guardrails）」章节已移除——guardrail 是「零规则、无扫描映射、无消费者」的空转链，已随内核摘除（2026-08-17，见 memory-role-pack-boundary.md §4.4）。本章仅保留原 15.3 的有效内容。
-
-当工具执行失败且错误码为 retryable 时，AgentLoop 自动注入 `[REFLECTION_HINT]` 系统消息，引导 LLM 修正参数后重试。默认最多重试 2 次（`maxReflectionRetries`）。
-
----
-
-## 十六、类型导出
-
-> 以下**精选子集**为宿主最常用的公开导出，全部经 `@zooique/memora` 再导出（无幻影）；未在清单中的其他导出（如 `DuplicateCallInterceptor` / `SessionManager` / `ProviderRouter` / `SummaryType` 等）以 `src/index.ts` 为准。治理报告类型（`DedupReport` / `SourceHealthReport` 等）经方法返回推断，不列为显式导出。
-
-```typescript
-// Agent 与流式事件
-export { Agent } from '@zooique/memora';
-export type {
-  AgentChunk,
-  ThinkingPhase,
-  UIMessages,
-  ArchiveMode,
-} from '@zooique/memora';
-export type {
-  AgentOptions,
-  AgentContext,
-  AgentProjectEntry,
-} from '@zooique/memora';
-export { type AgentForkResult } from '@zooique/memora';
-export type { SessionCheckpoint } from '@zooique/memora';
-
-// 记忆快照与搜索（MemoryInspector）
-export type {
-  MemorySnapshot,
-  WorkingMemorySnapshot,
-  BootstrapSnapshot,
-  ArchiveSnapshot,
-  AgentSearchHit,
-  AgentStats,
-} from '@zooique/memora';
-// 记忆治理统一门面（治理 / 健康度报告类型经方法返回推断，未列为公开显式导出）
-export { MemoryGovernance } from '@zooique/memora';
-// 文本润色
-export type { PolishResult } from '@zooique/memora';
-export { AGENT_CONSTANTS, LOOP_CONSTANTS } from '@zooique/memora';
-
-// 工具
-export type { ToolDefinition, ToolHandler, ToolContext, WriteExtensions } from '@zooique/memora';
-// 网页抓取（搜索→抓取闭环第二段）
-export type { IFetchProvider, FetchedPage, FetchOptions } from '@zooique/memora';
-export { FetchWebFetchProvider, safeFetch } from '@zooique/memora';
-// 代码执行（通用计算底座）
-export type { ICodeExecutionProvider, CodeExecutionResult, CodeExecutionOptions } from '@zooique/memora';
-export { safeExecuteCode } from '@zooique/memora';
-
-// 作品投影
-export type { WorkProjectionEntry } from '@zooique/memora';
-
-// 记忆
-export { SOURCE_LABELS } from '@zooique/memora';
-export type { Memory } from '@zooique/memora';
-export { escapeLike, escapeLikeSnippet, validateSource } from '@zooique/memora';
-export type { SourceValidationSeverity } from '@zooique/memora';
-export type { IMemoryStorage } from '@zooique/memora';
-export { InMemoryStorage } from '@zooique/memora';
-// 治理共享常量（提升/上限/下限）
-export { BOOST_INCREMENT, SCORE_CEILING, SCORE_FLOOR } from '@zooique/memora';
-export type { ISessionStore, SessionMessage } from '@zooique/memora';
-export type { ForkResult } from '@zooique/memora';
-
-// 项目注册表 + 锁文件管理
-export { ProjectRegistry } from '@zooique/memora';
-export type { ProjectEntry } from '@zooique/memora';
-export { LockManager } from '@zooique/memora';
-
-// 事件系统
-export { TypedEventEmitter } from '@zooique/memora';
-export type { AgentEventMap, AgentEventName, AgentEventHandler } from '@zooique/memora';
-
-// 可观测性
-export type { ITracer, ISpan, AgentMetrics } from '@zooique/memora';
-export { NOOP_TRACER, TRACE_SPANS } from '@zooique/memora';
-
-// 错误码
-export { MemoraError, ToolErrorCode, isRetryableErrorCode } from '@zooique/memora';
-export { toError } from '@zooique/memora';
-export type { ToolErrorCodeValue } from '@zooique/memora';
-
-// 日志
-export type { ILogger } from '@zooique/memora';
-export { setLogger, logger } from '@zooique/memora';
-
-// 召回（2026-09-10 减法：`recall()` 召回编排 + `RecallOptions` 已退役——
-// 唯一消费者是跨重启恢复链的 warmRecall，随之整体下线；记忆检索走 `search_memories` 工具 → `searchByKeyword`）
-export { extractKeywords } from '@zooique/memora';
-
-// 网络搜索
-export type { IWebSearchProvider, SearchResult, WebSearchOptions, SearchEndpoint } from '@zooique/memora';
-export { FetchWebSearchProvider } from '@zooique/memora';
-
-// 角色包
-export type { RolePackMeta } from '@zooique/memora';
-
-// 技能
-export type { SkillEntry, SkillMatch } from '@zooique/memora';
-
-// LLM
-export { createLlmProvider, createProviderFromConfig } from '@zooique/memora';
-export type { ProviderConfig } from '@zooique/memora';
-export type { LlmProvider, ChatOptions } from '@zooique/memora';
-export type { LlmChunk } from '@zooique/memora';
-
-// 配置
-export { loadConfig } from '@zooique/memora';
-export type { Config } from '@zooique/memora';
-
-// 工具函数
-export { segmentText, segmentLower } from '@zooique/memora';
-export { parseFrontmatter, serializeFrontmatter } from '@zooique/memora';
-export { safeSetTimeout, safeSetInterval, clearSafeTimeout, clearSafeInterval } from '@zooique/memora';
-export { isPlainObject } from '@zooique/memora';
-export { truncate } from '@zooique/memora';
-export { formatDateKey, todayDate } from '@zooique/memora';
-
-// 安全
-export type {
-  AuditEvent,
-  AuditListener,
-  Permission,
-  WriteDecision,
-  WriteConfirmationInfo,
-  WriteConfirmationRequest,
-} from '@zooique/memora';
-```
-
----
-
-## 十七、安全与约束
-
-### 核心库零越界
-
-| 检查项 | 结论 |
-|--------|------|
-| 核心库 `console.*` 调用 | 0 处 |
-| 核心库 `process.stdin/stdout` | 0 处 |
-| 核心库写配置文件 | 0 处 |
-| 核心库 `readFileSync/writeFileSync` 写宿主业务文件 | 0 处 |
-
-### 内部数据写入（不越界）
-
-Agent 内部只维护两个状态文件，路径全部由宿主传入的路径推导，内核不假设 `~/.memora/` 一类的用户级默认位置：
-
-- `projects.json`（项目注册表）——落 `dataDir` 内；若显式传了 `registryDir` 则落那里
-- `.lock`（项目锁）——固定落 `<projectPath>/.memora/.lock`，**不由 `dataDir` 推导**
-
----
-
-**版本**：v3.0.0
-**配套文档**：[memora-接入指南.md](./memora-接入指南.md)（步骤式教程）
+# Memora 内核 API 参考手册（v5.0.0）
+
+> **核心定位**：Memora 是一个**无法独立运行**的智能大脑内核——它只有接口，没有"形态"。CLI、WebUI、桌面精灵、小说生成器都是它的"宿主"，宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
+>
+> **本文件用途**：列出内核对外暴露的**全部公开接口**——从最基础的接入接口（〇），到 Agent 面类、对话、记忆、角色包、工具、各 Manager，再到类型导出与安全约束。
+>
+> **版本**：v5.0.0（对齐当前内核包版本 `package.json`；npm 已发布最新为 v4.0.0、v5.0.0 待发布。纯净接口文档，不含历史变更流水）
+
+---
+
+## 〇、接入基础接口
+
+> **定位**：一个新宿主接入 memora 的**最小接入面**。其余各章是 `Agent` 初始化后暴露的运行时能力；本章回答"接入前必须提供什么"。
+>
+> **一句话总结**：必做三件事——① 实现 `IMemoryStorage` + `ISessionStore` + `LlmProvider`；② 准备 `configDir`（含 `config.json` 模型表 + `role-packs/` + `skills/`）；③ 传 `projectPath` / `dataDir` / `configDir` 构造 `Agent`。其余接口按需注入，缺省都有降级兜底。
+
+### 〇.1 宿主实现的接口（注入）
+
+| 接口 | 必选 | 声明位置 | 用途 |
+|------|------|---------|------|
+| `LlmProvider` | ✅ 必选 | `src/llm/provider.ts` | 前台 LLM 流式对话（`stream()`），宿主创建 |
+| `IMemoryStorage` | ✅ 必选* | `src/memory/storageInterface.ts` | 记忆持久化，15 方法，同步语义（对齐 better-sqlite3）；**后端由宿主自选** |
+| `ISessionStore` | ✅ 必选* | `src/memory/sessionStore.ts` | 会话消息持久化，3 必需 + 6 可选方法 |
+| `ITracer` | 可选 | `src/agent/tracer.ts` | 可观测性，不传用 `NoopTracer` |
+| `IWebSearchProvider` | 可选 | `src/web-search/types.ts` | 网络搜索，不注入则不启用 |
+| `IFetchProvider` | 可选 | `src/web-fetch/types.ts` | 网页抓取（搜索→抓取闭环第二段），不注入则不启用 |
+| `ICodeExecutionProvider` | 可选 | `src/code-exec/types.ts` | 通用代码执行（沙箱由宿主提供），不注入则不启用 |
+| `IProjectSearchProvider` | 可选 | `src/project-search/types.ts` | 项目内搜索（等价 IDE 全局搜索），不注入则不暴露 `search_project`（见 §8.6） |
+| `ILogger` | 可选 | `src/logging/loggerInterface.ts` | 日志，默认内置 |
+| `backgroundProvider` (`LlmProvider`) | 可选 | AgentOptions | 后台通道（归档/投影），不配复用前台 |
+
+\* 不传则内核自动用内置内存实现 / 内存会话（仅内存不落盘；内存实现类为内部机制，不挂公共面——PUB-API-PRUNE-2 收面）；做产品必须实现。
+
+### 〇.2 宿主提供的配置资源（`configDir` 下）
+
+`configDir` 是唯一的配置目录入口（含角色包 / 全局技能 / 配置文件）：
+
+```
+configDir/
+├── config.json              ← ★ LLM 配置真理源：providers + active + background + taskRouter
+├── role-packs/              ← 角色包目录（每个包一个文件夹，含 manifest.json）
+│   └── 工程师/
+│       ├── manifest.json    ← 必填：元数据 + strategy + capabilities
+│       ├── persona.md       ← 约定名，可省（身份设定）
+│       ├── rules.md         ← 约定名，可省（安全契约）
+│       └── skills/          ← 角色包内嵌技能（目录动态扫描，可选）
+│           └── ...          ← 形式与全局技能池一致（见下）
+├── skills/                  ← 全局技能池（所有角色共享，可选）
+│   ├── search.md            ← 单文件形式
+│   └── code-review/         ← 文件夹形式（统一大众公认的 Agent Skills 格式）
+│       ├── SKILL.md         ← 技能正文（frontmatter 声明 name/description）
+│       ├── resources/       ← L3 参考资源（参考材料/规范）
+│       ├── scripts/         ← L3 可执行脚本（运行时按需执行）
+│       ├── references/      ← 技能内参考资料
+│       └── assets/          ← 技能内资源（模板/图片/示例）
+```
+
+> **skills 两种形式（两级技能共用统一格式）**：全局技能池（`configDir/skills/`）与角色包内嵌技能（`role-packs/<名>/skills/`）采用**同一套**技能格式，仅激活条件不同（全局始终激活，角色包技能随角色激活）。每个技能为单文件 `*.md` **或** 文件夹 `SKILL.md` 两种形式之一；`references/` / `assets/` 属于**技能内部**的资源目录（文件夹形式的组成部分），非 configDir 或角色包顶层目录。渐进披露：L1 元数据常驻 / L2 `read_skill` 按需读正文 / L3 `read_resource` + `run_skill_script`。
+```
+
+**config.json 大模型列表**（不是独立目录，是配置文件中的映射表）：
+
+```jsonc
+{
+  "llm": {
+    "providers": { "deepseek": { "baseUrl": "...", "model": "...", "apiKey": "" },
+                   "openai":   { "baseUrl": "...", "model": "...", "apiKey": "" } },
+    "active": "deepseek",        // 激活别名，不配取第一个 key
+    "background": { ... },       // 可选后台通道，节省成本
+    "taskRouter": { "simple": "deepseek", "reasoning": "openai" }
+  }
+}
+```
+
+- API Key **不写文件**，从环境变量读取。
+- memora 内核仅内置 `mock` Provider（无 API Key 的测试/降级），其余厂商需宿主在 config.json 显式配置。
+
+### 〇.3 `dataDir` vs `storage` 的区别
+
+两个易混淆的参数：**`storage` 管"如何存取"（接口实例），`dataDir` 管"存到哪个目录"（路径字符串）**。
+
+| | `storage`（IMemoryStorage） | `dataDir` |
+|---|---|---|
+| 本质 | 接口实例（宿主写的类） | 文件系统目录路径（字符串） |
+| 内核怎么用它 | 调方法：`upsert` / `getById` / `search` / `getAllSources`… | 记忆库落哪、叫什么名，由宿主自定，内核不参与（`dataDir` 只是 Agent 级资源目录，内核不假设其下文件形态） |
+| 管什么 | "怎么存取记忆"（逻辑），内核不关心内部是 SQLite 还是内存 | "记忆库与项目注册表放哪个目录"（物理位置） |
+| 谁实现 | 宿主实现（如 SqliteMemoryStorage） | 宿主传路径 |
+| 关系 | `dataDir` 指向目录；宿主按自己的持久化形态构造 storage（JSON 文件 / SQLite 皆可） | 内核用 `dataDir` 推导注册表路径；**项目锁文件不由 `dataDir` 推导**，它固定落 `<projectPath>/.memora/.lock` |
+| 缺省 | 不传 → 内置内存实现（仅内存，不挂公共面） | **必填，无默认值**（目录位置与层级语义是宿主的产品决策，内核不假设） |
+
+一句话：`storage` 是宿主**怎么**存取的实现，`dataDir` 是存取内容**落在哪个目录**的配置——一个管"如何"，一个管"何处"。
+
+> **`config.json` 里的 `memory.dataDir` 内核不读**：它只是「宿主约定的载体」——宿主可自行从配置取出后传给
+> `new Agent({ dataDir })`。内核不消费它，也没有任何默认值；`config.example.json` 里写 `~/.memora` 只是一个示例值，
+> 不等于内核的缺省行为。
+
+### 〇.4 多来源双路径编排（内置 + 用户）
+
+内核**刻意保持"单 `configDir` 输入"**——`SkillManager`/`RolePackManager` 只扫 `<configDir>/skills/`、`<configDir>/role-packs/`，无"多来源"概念。宿主若想开放"内置（随插件打包）+ 用户自定义"双路径，由宿主在传入内核**之前**自行编排归一，两种形态：
+
+| 形态 | 做法 | 适用 |
+|------|------|------|
+| **A. 宿主文件层汇总（推荐，零内核改动）** | 宿主在文件系统层把"内置目录 + 用户目录"合并/软链到**一个 `configDir`** 再传内核 | 角色包、全局技能均可；内容本质同构、希望同池匹配 |
+| **B. 宿主多 Manager 实例聚合** | 宿主建多个 `RolePackManager(configDirA/B)` 各管一个来源，聚合 `listMeta()` 在 UI 层分组展示，激活仍逐个调用 | 来源语义需要区分（UI 分组、只读标记） |
+
+选择依据：内容**不必区分来源**走 A（合并到同一 configDir）；**必须区分来源**（只读/可编辑、分组）走 B（多实例聚合展示）。内核两种都支持。
+
+### 〇.5 构造 `Agent` 的参数
+
+```ts
+new Agent({
+  projectPath,            // ✅ 必选：工作区
+  provider,               // ✅ 必选：前台 LLM
+  // 常用可选项
+  configDir,              // 配置根目录（role-packs / skills；缺省用内置默认）
+  dataDir,                // ✅ 必选：记忆数据落地目录（内核不提供默认值）
+  backgroundProvider,     // 后台 LLM
+  storage,                // IMemoryStorage 实现（缺省内置内存实现，不挂公共面）
+  sessionStore,           // ISessionStore 实现（缺省仅内存保存）
+  webSearchProvider,      // 网络搜索
+  tracer,                 // 可观测
+  maxContextTokens,       // 默认见 AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS（数字以该常量为真源，此处不落账）
+  permission, allowedPaths, confirmWrites,   // 安全
+  activeRolePack,         // 启动激活的角色包
+})
+```
+
+---
+
+## 一、设计哲学
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  宿主程序（CLI / 桌面精灵 / 小说生成器 / WebUI）           │
+│  ┌─────────────────┐    ┌──────────────────┐               │
+│  │ LLM Provider 实例 │◄───│ API Key / baseUrl │  ← 宿主职责  │
+│  └────────┬────────┘    └──────────────────┘               │
+│           │ 注入                                            │
+│           ▼                                                 │
+│  ┌──────────────────────────────────────────┐               │
+│  │  Memora 内核（Agent）                    │               │
+│  │  ┌──────────────────────────────────────┐│               │
+│  │  │  Agent 面类（编排层）                 ││               │
+│  │  │  - init/close · chat · forkSession  ││               │
+│  │  │  - .rolePack / .tools / .skills      ││               │
+│  │  │  - .memory / .works / .polish        ││               │
+│  │  └──────────┬───────────────────────────┘│               │
+│  │             │ 委托                         │               │
+│  │  ┌──────────┼───────────────────────────┐│               │
+│  │  │ RolePackManager / SkillManager       ││               │
+│  │  │ ToolExecutor / MemoryInspector       ││               │
+│  │  └──────────────────────────────────────┘│               │
+│  │  ⚠️ 不包含：UI / LLM 配置 / 用户配置模板 │               │
+│  └──────────────────────────────────────────┘               │
+└────────────────────────────────────────────────────────────┘
+```
+
+**设计原则**：
+- **零运行时依赖**（核心层零 npm 运行时依赖、**零运行时模块解析**；日志默认内置 console fallback，宿主经 `setLogger()` 注入自定义实现；持久化由宿主通过 `IMemoryStorage` 接口注入）
+- **内核模块不直接调用 `console.*`**（唯一日志出口是 `logging/` 单例 `logger`；默认实现为内置 console fallback，写 stderr）
+- **零写用户文件**（配置文件是真理源，Agent 只读）
+- **零 LLM 配置加载**（Agent 不知道 `apiKey`，宿主传入 `LlmProvider` 实例）
+- **Manager 委托模式**：Agent 面类只做编排，领域操作委托给专职 Manager
+
+---
+
+## 二、构造与生命周期
+
+### 2.1 构造选项 `AgentOptions`
+
+| 字段 | 类型 | 必须 | 说明 |
+|------|------|------|------|
+| `projectPath` | `string` | ✅ | 项目路径（必须） |
+| `provider` | `LlmProvider` | ✅ | 前台 LLM Provider（必须） |
+| `backgroundProvider` | `LlmProvider` | ❌ | 后台 Provider（投影等后台操作） |
+| `providerRouter` | `ProviderRouter` | ❌ | 按任务类型返回 Provider 的路由器（不配时全部使用同一 Provider，向后兼容） |
+| `configDir` | `string` | ❌ | 配置目录（role-packs / skills，设定记忆唯一归角色包） |
+| `dataDir` | `string` | ✅ | 记忆数据目录（必填，内核不提供默认值；传项目级还是用户级目录由宿主决定） |
+| `maxContextTokens` | `number` | ❌ | 上下文窗口上限（缺省 = 内核 `AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS`，数字以该常量为真源，此处不落账） |
+| `maxTokens` | `number` | ❌ | per-LLM 输出预算（token；宿主配置面板「输出上限」透传，undefined = 回服务端默认）。与角色包策略 `act.outputLimit` **取更小值**，`buildChatOptions` 单点裁决，宿主经 `agent.getEffectiveMaxTokens()` 读生效值 |
+| `confirmScripts` | `boolean` | ❌ | 脚本/代码执行确认（独立于写入确认；true 时 `run_code` / `run_project_script` 执行前弹窗，默认 false 不弹窗） |
+| `activeRolePack` | `string` | ❌ | 启动激活的角色包名（缺失/不存在回退默认激活首个） |
+| `rolePackTeams` | `RolePackTeam[]` | ❌ | 组（宿主装配级）：组长角色包 + 组员名单（会议名单容器；组长唯一、组员可跨组引用，仅用于小组会议，不用于日常） |
+| `builtinFallbackRole` | `string` | ❌ | 程序级内置兜底角色（覆盖内核常量 `BUILTIN_FALLBACK_PACK`；覆盖值须指向存在的包，否则回退内核常量） |
+| `strategyOverride` | `Partial<BehaviorStrategy>` | ❌ | 宿主装配级策略覆盖：经 `resolveActiveStrategy` 压过角色包声明（只影响 override 声明过的键），表达宿主产品能力边界 |
+| `permission` | `'owner' \| 'guest'` | ❌ | 安全权限（默认 'owner'） |
+| `allowedPaths` | `string[]` | ❌ | 路径白名单（默认 [] = 全部允许） |
+| `confirmWrites` | `boolean` | ❌ | 写入确认（默认 false） |
+| `storage` | `IMemoryStorage` | ❌ | 存储层注入（默认内置内存实现，不挂公共面） |
+| ~~`vectorStore`~~ | ~~`IVectorStore`~~ | — | **已删除（2026-09-18 B0 收编）**：向量语义召回通道此前**写端缺失、从未在生产生效**（`upsert` 零调用 → 库恒空 → 语义分支永不触发 = 僵尸能力）。经主流 agent 调研（Anthropic Memory/Claude Code/Librarian Pattern 实证「LLM 消费者 + 小语料」纯关键词足用）拍板收编：`IVectorStore` 接口、`JsonVectorStore`、`EmbeddingProvider` 及 `config.embedding` 段全链删除；`search_memories` 走纯关键词，未命中提示 LLM 换词重试 |
+| ~~`recallExcludeSources`~~ | ~~`string[]`~~ | — | **已删除（2026-09-11）**：该配置随召回编排 `recall()` 退役后成为零消费者死配置，全链（AgentOptions → AgentConfig → AssembleInput → ContextPreparerDeps）物理删除。**原消费者已彻底消失**：它当时服务的关联推荐通道 `Agent.governance.suggest(query, { excludeSources })` 于 2026-10-18 随治理链整链退役（见 §四 注记），无替代通道 |
+| `sessionStore` | `ISessionStore` | ❌ | 会话存储注入 |
+| `roundStore` | `IRoundStore` | ❌ | 问答闭环独立存储注入（round-based 落盘真源；未注入则消息仅内存保存，与 `sessionStore` 配套） |
+| `tracer` | `ITracer` | ❌ | 可观测性 Tracer 注入（不传则使用 NoopTracer 静默丢弃所有 span） |
+| `messages` | `UIMessages` | ❌ | 宿主可覆盖的 UI 消息文本（默认英文，宿主覆盖为中文等） |
+| `enableContextSummary` | `boolean` | ❌ | 上下文超限时是否自动生成摘要（默认 true，开启后首次截断时增加 ~1-2s 延迟） |
+| `archiveMode` | `ArchiveMode` | ❌ | 归档模式（ADR-015，默认 `'full'`）。`'full'`：会话内容在会话切换前自动归档；`'manual'`：全部需手动触发（2026-08-14 洞察层移除后三态收敛为二态，原 `'insights-only'` 已移除） |
+| `webSearchProvider` | `IWebSearchProvider` | ❌ | 网络搜索提供者注入（提供时自动暴露 `web_search` 工具给 LLM，不传则不暴露） |
+| `fetchProvider` | `IFetchProvider` | ❌ | 网页抓取提供者注入（提供时自动暴露 `web_fetch` 工具给 LLM，与 `webSearchProvider` 成对构成「搜索→抓取」闭环，不传则不暴露） |
+| `codeExecutionProvider` | `ICodeExecutionProvider` | ❌ | 代码执行提供者注入（提供时自动暴露 `run_code` 工具给 LLM，沙箱执行能力完全由宿主 provider 决定，内核零运行时依赖，不传则不暴露） |
+| `projectSearchProvider` | `IProjectSearchProvider` | ❌ | 项目内搜索提供者注入（提供时 LLM 获项目文件检索能力，不传则不暴露） |
+| `environmentProvider` | `IEnvironmentProvider` | ❌ | 宿主环境提供者（不配则 system prompt 不注入环境段）：宿主上报运行环境事实（OS / shell / 可用运行时），内核零解释转发 |
+| `scriptNodePath` | `string` | ❌ | node 可执行文件路径：宿主注入真实 node 路径给 L3 脚本执行器（`run_skill_script` / `run_project_script` 的 node 分支）；缺省走 `'node'`（PATH 查找），宿主机无独立 node 时注入可避免 ENOENT |
+| `disabledSkills` | `string[]` | ❌ | 禁用的技能名清单：命中的技能从 L1 清单消失、L2/L3 访问不可用（对 LLM 语义 = 技能不存在，宿主 UI 据同名设置标「已禁用」徽章） |
+| `preExecutionCheck` | `(name, args) => PreExecutionResult` | ❌ | 工具执行前检查回调（宿主审批/审计/参数改写通道；装配时与内部幂等检查组合为单点入口） |
+
+> **Logger 注入方式**：v1.0 起 `AgentOptions` 不再含 `logger` 字段。日志通过全局 `setLogger(customLogger)` 注入（详见 §十七 类型导出）；未注入时使用内核内置 console fallback（写 stderr，级别由 `MEMORA_LOG_LEVEL` 控制），内核不做任何运行时模块解析。注入即内核唯一日志出口，对**所有内核模块（含 utils 层）**生效。
+
+### 2.2 生命周期方法
+
+| 方法 | 用途 |
+|------|------|
+| `new Agent(opts)` | 构造函数（无副作用，不连接 LLM） |
+| `init()` → `Promise<ProjectContext>` | 初始化：建立存储、加载配置、组装组件。**项目在构造时钉死**（`AgentOptions.projectPath`）——换项目请新建一个 Agent 实例，单实例内不可改绑 |
+| `close()` → `Promise<void>` | 关闭：释放项目锁、关闭数据库 |
+
+### 2.3 Agent 只读访问器
+
+| 访问器 | 类型 | 说明 |
+|--------|------|------|
+| `agent.initialized` | `boolean` | 是否已初始化 |
+| `agent.context` | `AgentContext \| null` | 当前项目上下文 |
+| `agent.provider` | `LlmProvider` | 当前前台 Provider |
+| `agent.isBusy` | `boolean` | 是否正在对话中 |
+| `agent.lastInteractionAt` | `Date \| null` | 最近一次 `chat()` 调用时间 |
+
+### 2.4 Manager 访问器（委托模式）
+
+Agent 通过一组 getter 暴露专职 Manager 与组件。详见后续章节。
+
+| 访问器 | 类型 | 职责 |
+|--------|------|------|
+| `agent.rolePack` | `RolePackManager \| null` | 角色包管理 |
+| `agent.tools` | `ToolExecutor \| null` | 工具注册与执行 |
+| `agent.skills` | `SkillManager \| null` | 技能匹配与注入 |
+| `agent.memory` | `MemoryInspector \| null` | 记忆查询 + 写入（`writeXxx` 前缀） |
+| `agent.works` | `WorkProjectionManager \| null` | 作品投影（项目文件指针索引） |
+| `agent.polish` | `TextPolishManager \| null` | 文本润色（LLM 语法修正 + 表达优化） |
+
+> **历史留痕（2026-10-18 · 5.0.0）**：本表原有 `agent.governance` 一行（类型 `MemoryGovernance | null`，职责「记忆治理：去重/冲突检测/建议」），已随治理链**整链退役**删除——
+> 理由为**结构性恒空**（非「暂时没人用」）：`deduplicate()` / `detectConflicts()` / `suggest()` 逐 `GOVERNANCE_SOURCES` 取样，而该常量是字面量空数组、非注入项，代码路径上永远拿不到输入。
+> 唯一有效的 `sourceHealth()` 已有等价替代 `agent.memory.stats().bySource`。连带删除 `MemoryAdvisor` / `DedupManager` / `llmJudgeHelper` / `recallDefaults` 与 `dedupCompleted` 事件。详见 §四 注记。
+
+> **读写统一入口**：`agent.memory`（MemoryInspector）同时负责记忆的查询与写入——只读方法（snapshot/searchByKeyword/stats/list/getById/getBySource/listDeleted 等；**`search()` 已于 4.0.0 移除**，见 §4.2）与写方法（`writeXxx` 前缀：writeUpsert/writeDelete/writeRestore/writePurge/writePurgeExpired。`writeBoost` 已随 score 字段退役删除，2026-09-09）。旧的 `memoryMutator`/`MemoryMutator` 拆分已在后续迭代中合并回 `MemoryInspector`，二者均不再存在。
+
+### 2.5 内部组件访问器（高级）
+
+| 访问器 | 类型 | 说明 |
+|--------|------|------|
+| `agent.agentLoop` | `AgentLoop \| null` | Agent 循环体（`getMessages()` / `getRecentHistory()`） |
+| `agent.agentHistory` | `MessageHistory \| null` | 消息历史（`listAllSessions()` 等） |
+
+### 2.6 `ProjectContext` 字段（`init()` 返回值）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `projectPath` | `string` | 项目根目录的绝对路径（构造时钉死，不可改绑） |
+| `projectName` | `string` | 项目名称（显式传入优先，否则取目录名；内核不读任何注册表） |
+| `memoraDir` | `string` | `.memora/` 目录的绝对路径 |
+| `index` | `IMemoryStorage` | 记忆存储接口 |
+| `security` | `SecurityGuard \| null` | 安全守卫（未注入 `createSecurityGuard` 工厂时为 `null`） |
+| `bootstrapMemories` | `Memory[]` | 启动必召记忆——**恒为空数组**（设定记忆归角色包内容层，ADR-025） |
+
+### 2.7 事件订阅（`agent.on()` / `agent.off()` / `agent.once()`）
+
+Agent 继承 `TypedEventEmitter<AgentEventMap>`，向宿主项目广播对话外事件。
+
+```typescript
+agent.on<K extends AgentEventName>(event: K, handler: (payload: AgentEventMap[K]) => void): void
+agent.off<K extends AgentEventName>(event: K, handler: (payload: AgentEventMap[K]) => void): void
+agent.once<K extends AgentEventName>(event: K, handler: (payload: AgentEventMap[K]) => void): void
+```
+
+| 事件名 | 载荷 | 触发时机 |
+|--------|------|----------|
+| `memoryAdded` | `{ id, source, name, content? }` | 记忆被写入存储（round-summary 沉淀等）；`content` = 记忆正文（5.0.0 起可选携带，UI 提示按内容显示） |
+| `rolePackSwitched` | `{ from: string \| null, to }` | 角色包被切换（自动匹配 / 手动切换共用唯一切换入口） |
+| `memoryRecalled` | `{ count, query, hits?, toolCallId? }` | LLM 经 `search_memories` 命中记忆（`hits` = 命中明细 `{ id, name, source, contentPreview? }`，4.1.0 起可选、`contentPreview` 5.0.0 起携带；`toolCallId` = 本次调用的配对键，4.1.x 起可选，宿主据此把明细挂回对应工具行，缺省回退轮次级落位） |
+| `sessionForked` | `{ from, to, roundCount }` | 会话被分叉（`roundCount` = 新会话 Round 数） |
+| `sessionSwitched` | `{ date, session, fromSessionId, toSessionId }` | 会话身份切换完成（载荷指向被切走的旧会话；内核自消费，宿主零消费为刻意设计） |
+| `archiveFailed` | `{ stage: 'session', message }` | 归档异常（fire-and-forget catch 分支发射，宿主可通知用户） |
+| `sessionArchived` | `{ sessionId, updatedFields }` | 会话归档写入成功（宿主据此重拉会话列表刷新摘要） |
+| `contextTruncated` | `{ skippedCount, keptCount }` | 内核自动截断上下文 |
+| `contextCompressed` | `{ target, replacedCount, summaryLength }` | LLM 主动压缩完成（第二级压缩） |
+| `configReloaded` | `{ source }` | 配置重载 |
+| `archiveModeChanged` | `{ from, to }` | 归档模式切换 |
+| `rolePackSwitchLocked` | `{ reason, lockedSeconds }` | 角色包切换被锁定（如切换冷却期） |
+| `workProjectionGenerated` | `{ sourcePath, summary }` | 作品投影生成完成 |
+| ~~`dedupCompleted`~~ | ~~`{ deduplicatedCount, demotedIds }`~~ | **已移除（2026-10-18 · 5.0.0）**：随治理链整链退役，`AGENT_EVENTS` 与 `AgentEventMap` 两处同删。宿主侧的订阅与 `suggestions` 渲染通道一并拆除，勿加回 |
+| `sessionPauseTimedOut` | `{ sessionId, pauseDuration, date?, session? }` | 暂停超时（达到 `PAUSE_TIMEOUT_MS` 自动归档） |
+| `sessionResumeBlocked` | `{ sessionId, reason }` | 恢复被拒绝（如锁冲突） |
+| `sessionResumeFailed` | `{ sessionId?, reason }` | 恢复失败（宿主据此 toast 提示） |
+| `inputTooLarge` | `{ inputLength, remainingTokens, hint }` | 装配前判负：触发输入过大，剩余预算不足一轮正文 |
+| `questionPending` | `AskQuestion[]` | LLM 调 `ask_user` 主动提问（Agent 暂停等待回答） |
+| `sessionPaused` | `{ reason, source, sessionId? }` | 会话进入暂停态 |
+| `sessionResumed` | `{ sessionId? }` | 会话恢复运行 |
+| `sessionError` | `{ cause, sessionId? }` | 会话进入异常态 |
+| `sessionRecovered` | `{ sessionId? }` | 会话从异常态恢复 |
+| `sessionTitleUpdated` | `{ sessionId, title }` | LLM 自动更新会话标题（宿主据此刷新 UI） |
+| `roundSummaryGenerated` | `{ roundId, success }` | 轮次摘要生成收口（宿主据此解锁删除/分叉按钮，防孤儿摘要） |
+| `backgroundTaskSettled` | `{ taskId, command, status }` | 后台任务自然终态（自行跑完 / 超时强杀；主动 kill 刻意不发） |
+
+```typescript
+// 使用示例
+agent.on('memoryAdded', (e) => console.log(`新记忆: ${e.source}:${e.name}`));
+```
+
+> `close()` 自动移除所有事件监听器。
+
+**状态机**：
+```
+[构造] --init()--> [已初始化] --chat()/其他方法...--> [已初始化]
+                              --close()--> [已关闭]
+```
+
+未初始化时调用任何方法**抛 `configError`**。Manager 访问器在 `init()` 前返回 `null`。
+
+---
+
+## 三、对话 API
+
+### 3.1 `chat(input, signal?)` — 流式对话（唯一入口）
+
+```typescript
+async *chat(input: string, signal?: AbortSignal): AsyncGenerator<AgentChunk, void, unknown>
+```
+
+流式返回 `AgentChunk` 事件，可选传入 `signal` 支持取消。
+
+```typescript
+type AgentChunk =
+  | { type: 'thinking'; phase: ThinkingPhase }             // 推理阶段
+  | { type: 'text'; content: string }  // LLM 文本片段（流式输出内容）
+  | { type: 'thought'; content: string; stepIndex?: number }  // 模型思考增量（不进正文/记忆）；stepIndex = 所属 step 轮内序号（loop 打标）
+  | { type: 'tool_start'; toolCallId: string; name: string; args?: string; stepIndex?: number }   // 工具调用开始（stepIndex 同 thought；tool_result 经 toolCallId 归属，不重复携带）
+  | { type: 'tool_result'; toolCallId: string; name: string; ok: boolean; summary?: string }  // 工具调用结果
+  | { type: 'aborted'; reason: string }                    // 对话被取消
+  | { type: 'error'; message: string }                     // 流式过程中发生错误（LLM 超时/连接断开）
+  | { type: 'retry'; attempt: number; maxRetries: number; delayMs: number; error: string }  // 指数退避重试
+  | { type: 'done' };                                      // 结束标记
+```
+
+> 上表为核心事件子集（含边界/提问等更多成员的 `AgentChunk` 全集以 [types.ts](../src/agent/types.ts) 为唯一真理源）。
+
+> **记忆召回展示链已退役（2026-09-10）**：`recall` chunk 分支与 `RecalledMemorySummary` 类型已随自动注入退役**物理删除**。记忆纯工具化后，「召回了什么」由 `search_memories` 工具的 `tool_start` / `tool_result` 过程事件天然展示；检索命中含 `accessedAt` / 溯源字段（`sessionId`/`roundId`）。
+
+`ThinkingPhase` 取值：`'recalling' | 'processing' | 'archiving'`
+
+### 3.2 `chatSync(input, signal?)` — 同步版（聚合完整回复）
+
+```typescript
+async chatSync(input: string, signal?: AbortSignal): Promise<string>
+```
+
+收集所有 `text` 事件拼接成完整字符串返回。适合 CLI / 脚本宿主等不需要流式处理的场景；
+需要中间过程可观测或长任务可中断时用流式 `chat()`。
+
+---
+
+## 四、记忆查询与写入（`agent.memory` · MemoryInspector）
+
+> Manager 访问路径：`agent.memory.xxx()`。`init()` 前返回 `null`。
+
+### 4.1 `snapshot()` — 3 层记忆快照
+
+```typescript
+agent.memory.snapshot(): MemorySnapshot
+```
+
+同步返回当前 3 层记忆快照（纯只读、无副作用）：
+
+| 层 | 键 | 内容 |
+|----|-----|------|
+| 第 1 层 | `snapshot.working` | `WorkingMemorySnapshot` — 当前 AgentLoop 消息（最近 5 条预览 + 总数） |
+| 第 2 层 | `snapshot.bootstrap` | `BootstrapSnapshot` — 规则记忆（名称 + 来源 + 权重，Persona/Skill 已解耦为设定记忆，不进 bootstrap） |
+| 第 3 层 | `snapshot.archive` | `ArchiveSnapshot` — 归档记忆计数（round-summary）+ 当前会话信息 |
+
+```typescript
+interface MemorySnapshot {
+  working: WorkingMemorySnapshot;
+  bootstrap: BootstrapSnapshot;
+  archive: ArchiveSnapshot;
+}
+```
+
+### 4.2 `searchByKeyword(query, limit?, excludeRoundIds?)` — 记忆搜索（唯一入口）
+
+```typescript
+agent.memory.searchByKeyword(
+  query: string,
+  limit?: number,                        // 默认 10
+  excludeRoundIds?: ReadonlySet<string>,  // 可选：这些轮次的 round-summary 已在正文，不重复返回
+): Promise<AgentSearchHit[]>
+```
+
+纯关键词单通道（分词后任一词对 `content`/`name` 子串命中；**无向量通道、无融合排序、无 FTS 索引**）。
+返回顺序 = **`accessedAt` 倒序**（最近写入 / 最近被想起者靠前；`memory-tool-recall-design.md` §5.2 2026-10-19 改定案），
+**不按相关度排序**。返回前做两级过滤：
+`superseded` 过滤（被 `supersededBy` 取代的摘要不作为当前事实返回，仍可经 `trace_summary`
+回溯原文）与 `excludeRoundIds` 互斥（工具召回与装配期正文不重复）。
+
+> ⚠️ **4.0.0 已移除 `search()`**：原同步方法 `search(query, limit?)` **已删除**——
+> 此前它只标了 `@deprecated`，却仍作为正常方法列在随包文档里（退役不彻底的僵尸出口）。
+> 其能力由 `searchByKeyword()` 完全覆盖（后者还多出 superseded 过滤 / `excludeRoundIds`
+> 互斥 / accessedAt 刷新 + 溯源揭示），且移除前已实测**零生产消费、零宿主消费**。
+> **一律改用 `searchByKeyword()`。**
+
+返回值 `AgentSearchHit`：
+
+```typescript
+interface AgentSearchHit {
+  id: string;             // 记忆唯一标识（source:name 格式，供 showMemory/deleteMemory 等操作使用）
+  name: string;           // 记忆名称
+  source: string;         // 来源标签
+  contentPreview: string; // 内容预览（截断到 120 字符）
+  createdAt?: string;     // 创建时间（ISO 8601，供 UI 层时间筛选/排序使用）
+  accessedAt?: string;    // 最近使用时间（命中即刷新；LLM 按此判断「最近使用优先」）
+  sessionId?: string;     // 溯源（round-summary 命中项）：会话标识，trace_summary 参数直通
+  roundId?: string;       // 溯源（round-summary 命中项）：轮次 ID，LLM 零解析直用
+}
+```
+
+### 4.3 `stats()` — 记忆库统计
+
+```typescript
+agent.memory.stats(): AgentStats
+```
+
+```typescript
+interface AgentStats {
+  bySource: Record<string, number>; // 按来源标签分组的记忆数量
+  total: number;                    // 记忆总数
+}
+```
+
+### 4.4 `agent.agentLoop.getMessages()` — 工作记忆原始消息
+
+```typescript
+agent.agentLoop.getMessages(): readonly Message[]
+```
+
+### 4.5 写入方法
+
+记忆的写入统一收口在 `agent.memory`，写方法以 `writeXxx` 前缀命名（同步返回、不调 LLM、不触发异步 IO）：
+
+```typescript
+// ─── 写入（writeXxx 前缀） ───
+agent.memory.writeUpsert(memory: Memory): void;                 // 插入或更新记忆
+agent.memory.writeDelete(id: string): void;                    // 软删除（写入 deletedAt）
+agent.memory.writeRestore(id: string): void;                   // 恢复软删除
+agent.memory.writePurge(id: string): void;                     // 物理删除（不可恢复）
+agent.memory.writePurgeExpired(before: Date): number;          // 清理过期回收站
+
+// ─── 只读扩展查询 ───
+agent.memory.list(limit?: number): Memory[];                   // 列出所有记忆（按 accessedAt 降序；score 已随 2026-09-09 退役）
+agent.memory.getById(id: string): Memory | null;               // 按 ID 获取活跃记忆
+agent.memory.getBySource(source: string): Memory[];            // 按 source 获取
+agent.memory.listDeleted(limit?: number): Memory[];            // 回收站（软删除记忆）
+agent.memory.getDeletedById(id: string): Memory | null;
+agent.memory.searchByKeyword(query: string, limit?: number): Promise<AgentSearchHit[]>; // 纯关键词通道
+```
+
+> **历史留痕 · 治理门面整链退役（2026-10-18 · 5.0.0）**：`agent.governance` 曾暴露 `deduplicate()` / `detectConflicts()` / `sourceHealth()` / `suggest()`。
+> 其中前三者逐 `GOVERNANCE_SOURCES`（`src/memory/governance.ts`）取样，而该常量是**字面量空数组、非注入项** ⇒ 三者**结构性恒空**（不是「暂时没人用」，是代码路径上永远拿不到输入）。
+> 唯一有效的 `sourceHealth()` 已有等价替代：`agent.memory.stats().bySource`（宿主 `memora.memoryStats` 命令即消费此字段）。
+> 故按「结构性恒空」判据整链退役——**这是能力退回，不是 API 兼容性妥协**：原有的去重/冲突检测/建议三条能力，从 5.0.0 起**不存在**，不会「偶发不生效」。
+> 写时治理由 `supersede`（写时取代）承担，不经本门面。退役决策与代价见 `tasks/待完成任务.md` `GOVERNANCE-SRC-1`，删后注记见 `src/agent/agent.ts`。
+
+---
+
+## 五、Memory 模型（基元驱动）
+
+```typescript
+interface Memory {
+  id: string;         // 唯一标识（source:name 格式，如 'rule:core'）
+  content: string;    // 记忆内容（Markdown 文本）
+  source: string;     // 来源标签（开放字符串，非枚举）
+  name: string;       // 可读名称
+  createdAt: string;  // 创建时间（ISO 8601）
+  accessedAt: string; // 最后访问时间（每次召回时刷新）
+  deletedAt?: string; // 软删除时间（ISO 8601，可选；非 undefined 表示已软删除。回收站**无自动清理**：保留期清理由宿主入口显式触发，见 writePurgeExpired）
+  metadata?: Record<string, string>; // 配置文件 frontmatter 额外元数据（仅配置文件写入路径使用，不进记忆库）
+  summaryType?: 'preference' | 'fact' | 'decision' | 'intent' | 'general'; // round-summary 摘要类型（顶层持久化字段；类型随 Memory 签名推断，不单独导出）
+  sessionName?: string;  // round-summary 归属会话标识（顶层持久化字段，仅 round-summary 有意义）
+  roundId?: string;      // round-summary 归属轮次标识（顶层持久化字段，仅 round-summary 有意义）
+  isModified?: boolean;  // 摘要是否已被人工修改（仅 round-summary 有意义）
+  supersededBy?: string; // 写路径取代标记：非 undefined 表示已被更新的摘要覆盖，召回时确定性过滤
+  materialFingerprint?: string; // 摘要原料指纹（sha256(原文+分隔符+回复)），写路径前置精确去重：原料全等则跳过生成、不调 LLM。仅 round-summary 有意义，存量条目无此字段
+}
+```
+
+> **字段基线**（score 已退役）：`score` 字段已随 2026-09-09 阶段3 物理删除（无持久化排序分字段，使用轨迹唯一事实源为 `accessedAt`）；向量语义通道已随 2026-09-18 B0 收编（检索为纯关键词单通道）。round-summary 溯源/分类字段（summaryType/sessionName/roundId）已提升为顶层持久化字段（metadata 不进记忆库）。所有查询方法（getById/getBySource/search/count/countBySource/getAllSources）自动过滤 `deletedAt != undefined` 的记忆。详见 ADR-004 GAP-6 + ADR-002 §IMemoryStorage。
+
+**常用 source 标签（`SOURCE_LABELS` 常量）：**
+
+| 常量 | 值 | 用途 |
+|------|----|------|
+| `SOURCE_LABELS.PERSONA` | `'persona'` | 角色人格（残留兼容标签，已随 ADR-025 归角色包、不进记忆库） |
+| `SOURCE_LABELS.RULE` | `'rule'` | 创作规则（残留兼容标签，已随 ADR-025 归角色包、不进记忆库） |
+| `SOURCE_LABELS.SKILL` | `'skill'` | 技能定义（残留兼容标签，已随 ADR-025 归角色包、不进记忆库） |
+| `SOURCE_LABELS.WORK_PROJECTION` | `'work-projection'` | 作品投影（**残留兼容标签**：对应内容不归记忆库管理；现行投影为项目级 `work-projections.json` 指针索引，见 §九） |
+| `SOURCE_LABELS.ROUND_SUMMARY` | `'round-summary'` | 轮次摘要（当前实际写入记忆库的主要 source） |
+| `SOURCE_LABELS.UNKNOWN` | `'unknown'` | 未知来源（未被已知标签覆盖时的兜底值） |
+
+> source 是开放字符串，宿主可自定义新标签。`validateSource()` 可检测常见 typo（基于 Levenshtein 距离）。PERSONA/RULE/SKILL/WORK_PROJECTION 四标签**仅作历史兼容与 typo 检测**保留，已不进入治理范围——圈定该范围的 `GOVERNANCE_SOURCES` 常量已随 5.0.0 事后治理链**整链退役**删除（见上文「历史留痕」注记）；当前写入记忆库的主要 source 为 `round-summary`。
+
+### 5.2 `IMemoryStorage` 接口
+
+宿主实现此接口注入 Agent，替代内核内置的内存默认实现（内部类，不挂公共面——PUB-API-PRUNE-2 收面）。共 **15 方法**（14 必需 + 可选 `close`），所有方法同步（与 better-sqlite3 API 对齐，`await` 同步值安全）。所有查询方法自动过滤已软删除的记忆（`deletedAt != undefined`）。
+
+```typescript
+interface IMemoryStorage {
+  // ─── 基础 CRUD（6 方法） ───
+  upsert(memory: Memory): void;
+  getById(id: string): Memory | null;
+  getBySource(source: string): Memory[];
+  search(query: string, limit?: number): Memory[];
+  count(): number;
+  countBySource(source: string): number;
+
+  // ─── 软删除 / 回收站（6 方法，ADR-004 GAP-6 扩展） ───
+  delete(id: string): void;           // 软删除（写入 deletedAt，不物理移除；对已软删除的 no-op）
+  restore(id: string): void;          // 恢复软删除记忆（清除 deletedAt；对活跃记忆 no-op）
+  purge(id: string): void;            // 物理删除（不可恢复，用于回收站"彻底删除"）
+  listDeleted(limit?: number): Memory[];        // 列出回收站（按 deletedAt 降序；limit 缺省/≤0 = 全部，正整数 = 最近 N 条）
+  getDeletedById(id: string): Memory | null;    // 按 ID 获取单条软删除记忆（restore/purge 前存在性校验）
+  purgeExpired(before: Date): number;           // 清理过期回收站（物理删除 deletedAt 早于 before 的，返回清理数量）
+
+  // ─── 统计与维护（2 方法） ───
+  touch(id: string, now: string): boolean;  // 刷新 accessedAt（score 退役后唯一写位；不写 score、无 clamp 语义）
+  getAllSources(): Map<string, number>;     // 获取所有 source 标签及其活跃记忆数量
+
+  // ─── 可选（1 方法） ───
+  close?(): void;
+}
+```
+
+> 宿主实现应使用 `COUNT(*)` / `UPDATE ... WHERE` 等数据库原生操作，避免全量加载数据。`getAllSources` 是性能优化方法，避免逐条遍历。详见 ADR-002 §IMemoryStorage 接口方法。
+
+### 5.3 `ISessionStore` 接口
+
+宿主实现此接口提供会话消息的持久化能力。共 **12 方法**（11 必需 + 可选 `setSessionTitle`），
+按职责分三组：会话消息读写 / 元数据 / round-based 引用。**方法签名以本节为准，勿按旧版（含
+`appendMessage` 的 3 方法版）实现**——那是 round-based 改造前的历史形态，已被删除。
+
+```typescript
+interface ISessionStore {
+  // ─── 会话消息读写（1 方法） ───
+  /**
+   * 加载指定会话的完整消息列表（从 roundIds → RoundStore 展开），不存在返回空数组。
+   * **只返回 `user` / `assistant` 两种角色**：tool 结果属执行中间态，不落会话消息。
+   * 这不是实现自由，而是接口契约——上下文中 tool 消息的唯一来源是 Loop 的入口落盘。
+   */
+  loadMessages(date: string, session: string): SessionMessage[];
+
+  // ─── 元数据（5 方法，1 可选） ───
+  /** 列出所有会话标识（YYYY-MM-DD-session） */
+  listSessions(): string[];
+  /** 读取会话标题元数据，不存在返回 undefined */
+  getSessionMeta(sessionId: string): SessionMeta | undefined;
+  /** 设置用户可修改的显示名（displayName）；首轮自动命名走 updateSessionMeta 写 autoName */
+  setSessionTitle?(sessionId: string, title: string): void;
+  /** 更新元数据（autoName/keyTopics/summary/createdAt 等） */
+  updateSessionMeta(sessionId: string, meta: Partial<SessionMeta>): void;
+  /** 列出全部会话标题元数据，**必须按 updatedAt 降序**（最近活跃在前） */
+  listSessionMetas(): SessionMeta[];
+
+  // ─── round-based 引用（4 方法） ───
+  appendRoundId(sessionId: string, roundId: string): void;
+  appendRoundIds(sessionId: string, roundIds: string[]): void;
+  getRoundIds(sessionId: string): string[];
+  setRoundIds(sessionId: string, roundIds: string[]): void;
+
+  // ─── 会话生命周期（2 方法） ───
+  createSession(meta: SessionMeta): void;
+  /** 删除会话（同时清理 Round ID 引用） */
+  deleteSession(sessionId: string): void;
+}
+```
+
+> **`listSessionMetas` 排序方向是契约的一部分**：宿主视 `[0]` 为「最近活跃会话」的唯一真理源
+> （打开面板时定位初始会话）；升序实现会让初始定位落到最旧会话。
+
+---
+
+## 六、项目 / 会话管理
+
+> **方法归属**：会话相关方法在 `agent.sessionManager`（SessionManager）；`forkSession` 保留在
+> Agent 面类作为常用入口。**项目既无切换入口、也无重建入口**——多项目由宿主创建多个 Agent
+> 实例（一个 Agent 绑定一个项目），见 §6.2。
+
+> **switch* 返回值约定**：各 switch 操作返回与其操作语义最匹配的值 ——
+> `switchSession` 返回新会话名（string）、`agent.switchRolePack` 返回布尔值（是否切换成功）。
+> 这是设计性差异，非 bug。（原 `switchProject` 随 PR-SWITCH-1 删除，不再有项目切换入口。）
+
+### 6.1 Agent 面类方法（项目/会话入口）
+
+| 方法 | 用途 |
+|------|------|
+| `forkSession(targetSession?)` → `AgentForkResult` | 分叉当前会话（同步，复制完整消息历史到新分支） |
+
+### 6.2 多项目怎么办（形态定案）
+
+**一个 Agent 绑定一个项目**——内核不提供项目切换，也不维护跨项目名单。多项目的正确做法是
+**宿主为每个项目各创建一个 Agent 实例**（项目数据本就隔离在项目自己的 `.memora/` 下：
+`dataDir = <projectPath>/.memora`，记忆 / 会话 / round 三家 store 同目录）。
+
+需要「最近项目列表」时由宿主自持（VS Code 用 `recent folders`、扫 `.memora` 等），比内核管
+项目名单更合边界——内核不假设多项目目录的位置与形态。
+
+> 历史留痕：5.0.0 前曾有 `agent.projects`（项目管理器）与 `switchProject` / `projectSwitched`
+> 事件 / `registryDir` / `ProjectEntry` / `projects.json` 跨项目注册表整链，已于 PR-SWITCH-1
+> 一并删除（形态定案后整链落空：注册表随项目级 `dataDir` 各一份、按名切换永不命中，且注入
+> 存储不随切换重建 ⇒ 用了会错）。
+
+### 6.3 `agent.sessionManager` — SessionManager
+
+| 方法 | 用途 |
+|------|------|
+| `sessionManager.switchSession(newName)` → `string` | 切换到指定会话（chatBusy 时抛 configError） |
+| `sessionManager.forkSession(targetSession?)` → `AgentForkResult` | 分叉当前会话 |
+| `sessionManager.createCheckpoint()` → `SessionCheckpoint` | 创建当前会话检查点（含计划、状态机快照），首次调用返回完整检查点，后续调用合并增量。**同进程内存态**（2026-09-10 减法后不落盘）。返回值恒非空（agent 层与 sessionManager 层皆然；未 `init()` 时抛 `configError` 而非返回 `null`）。会返回 `null` 的是下一行 `getCheckpoint()`（首个检查点尚未创建时），勿混 |
+| `sessionManager.getCheckpoint()` → `SessionCheckpoint \| null` | 获取当前检查点（只读，不修改状态） |
+| `sessionManager.discardCheckpoint()` → `boolean` | **Phase 4 新增**：放弃当前暂停检查点（对称 pause 创建，宿主 handleStop paused 态调之；停定时器 + 清内存 + resetToRunning；无检查点返回 false） |
+
+```typescript
+// 会话分叉示例（Agent 面类入口，等价于 agent.sessionManager.forkSession()）
+const forkResult = agent.forkSession();
+console.log(`分叉到 ${forkResult.newSession}，含 ${forkResult.roundCount} 个 Round（roundId 指针）`);
+
+// 自定义分支名
+const customFork = agent.forkSession('experiment');
+
+// listAllSessions 通过 agentHistory 访问
+const sessions = await agent.agentHistory?.listAllSessions();
+```
+
+### `AgentForkResult` / `ForkResult` 类型
+
+```typescript
+// Agent.forkSession() / sessionManager.forkSession() 返回值
+interface AgentForkResult extends ForkResult {
+  roundCount: number; // 新会话获得的 Round ID 数量（源码 = ForkResult & { roundCount }）
+}
+
+// MessageHistory.forkSession() 内部类型（从 memora 导出）
+export interface ForkResult {
+  date: string;
+  newSession: string;
+  roundIds: string[]; // 已复制到新会话的 Round ID 指针列表
+}
+```
+
+---
+
+## 七、角色包管理（`agent.rolePack` · RolePackManager）
+
+> Manager 访问路径：`agent.rolePack`（RolePackManager，`init()` 前返回 `null`）。角色包是「设定记忆唯一载体」（persona/rules/skills 归属角色包，见 memory-role-pack-boundary 纪律）。
+
+| 成员 | 类型 | 说明 |
+|------|------|------|
+| `rolePack.listMeta()` | `RolePackMeta[]` | 所有角色包元数据（name / displayName / description / version / ...） |
+| `rolePack.activeName` | `string \| null`（getter） | 当前激活的角色包名（null = 未激活） |
+| `rolePack.getActive()` | `RolePackAssembly \| null` | 当前激活的完整角色包对象（含合并后策略） |
+| `rolePack.getActiveRules()` | `string[]` | 当前激活角色包的规则列表 |
+| `rolePack.getActiveTraits()` | `Record<string, number> \| undefined` | 当前激活角色包的 traits（clamp 0-1） |
+| `rolePack.activate(name)` | 方法 → `boolean` | 手动切换到指定角色包（30s 内超 5 次切换后锁 2 分钟防抖） |
+| `rolePack.getSwitchLockStatus()` | 方法 → `{ locked, unlockAt }` | 切换防抖锁定状态 |
+| `rolePack.onRolePackActivated(handler)` | 方法 | 注册激活变更回调（`(from, to)`） |
+
+```typescript
+// 使用示例
+const rp = agent.rolePack;
+if (!rp) throw new Error('rolePack 未就绪');
+const metas = rp.listMeta();           // 列出所有角色包
+rp.activate('作家');                    // 切换角色包
+console.log(rp.activeName);            // 当前角色包名
+const lock = rp.getSwitchLockStatus(); // 切换防抖状态
+```
+
+---
+
+## 八、工具注册（`agent.tools` · ToolExecutor）
+
+> 工具注册/执行走 `agent.tools.xxx()`。
+
+### 8.1 内置工具（核心摘要：默认常驻 + 条件暴露，非全集）
+
+| 工具名 | 用途 | 参数 | 暴露条件 |
+|--------|------|------|------|
+| `read_file` | 读取项目内文件内容（**按行分段返回**：单次输出 token 数 ≤ `LOOP_CONSTANTS.SINGLE_TOOL_RESULT_MAX_TOKENS`＝6000；未读到末尾时附「[read_file 分段]」脚注，给出已显示行号区间、总行数与续读 offset） | `path`, `offset?`, `limit?` | 默认常驻 |
+| `write_file` | 写入/创建文件（支持 overwrite/append/insert/replace 四种模式） | `path`, `content`, `mode?`, `insert_line?`, `old_string?` | 默认常驻 |
+| `list_dir` | 列出目录内容（递归深度 ≤ 3） | `path?`, `recursive?`, `maxDepth?` | 默认常驻 |
+| `search_memories` | 在记忆索引中搜索（支持 match/near 两种模式） | `query`, `limit?`, `mode?` | 默认常驻 |
+| `run_project_script` | 运行**项目内既有**脚本（内核子进程，cwd=项目根；路径白名单越界拒绝；扩展名推断 node/python/shell；超时 30s 上限 120s） | `script_path`, `args?` | 默认常驻（零注入） |
+| `run_skill_script` | 执行技能目录下的脚本（渐进披露 L3） | `skill_name`, `script_path`, `args?` | 默认常驻（来源=技能作者） |
+| `run_command` | 执行 shell 命令（裁决链：deny 恒拦 → 确认档位 → allow 白名单；`background: true` 转后台立即返回 taskId，结果经回流通知注入，详见 §8.7） | `command`, `cwd?`, `background?`, `timeoutMs?` | 默认常驻 |
+| `kill_command` | 终止后台命令任务并取回截至当时的输出（仅可杀本 agent 实例起的任务，§8.7） | `taskId` | 默认常驻 |
+| `web_search` | 搜索互联网 | `query`, `limit?` | 条件暴露（注入 `IWebSearchProvider`） |
+| `web_fetch` | 抓取网页正文（与 `web_search` 成对闭环） | `url`, `limit?` | 条件暴露（注入 `IFetchProvider`） |
+| `run_code` | LLM 现写代码执行（特权：`code:execute` 声明 + 宿主沙箱注入） | `language`, `code` 或 `script_path` | 条件暴露（注入 `ICodeExecutionProvider` 且角色包声明特权） |
+
+### 8.2 `agent.tools` — ToolExecutor
+
+| 方法 | 用途 |
+|------|------|
+| `tools.registerTool(definition, handler)` | 注册自定义工具（会话级） |
+| `tools.list` | 所有工具定义（getter，`ToolDefinition[]`） |
+| `tools.execute(name, argsJson, extensions?)` → `Promise<string>` | 执行工具调用 |
+
+```typescript
+// 工具定义
+interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, { type: string; description: string }>;
+    required: string[];        // 必填参数列表（不可省略）
+  };
+  readonly?: boolean;          // 只读工具标记：true = readonly 模式下保留；缺省 false = 写操作，readonly 模式被阻止
+  diskWrite?: 'path' | 'opaque'; // 改盘声明（与 readonly 正交）：'path' 按 args.path 定位目标做写串行；'opaque' 与一切写互斥；缺省 = 不改盘
+}
+
+// 宿主注册领域工具示例
+agent.tools.registerTool(
+  {
+    name: 'web_search',
+    description: '搜索互联网，返回结构化结果',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: '搜索关键词' },
+        limit: { type: 'number', description: '最大返回条数', default: 5 },
+      },
+      required: ['query'],
+    },
+  },
+  async (args) => {
+    const res = await fetch(`https://api.example.com/search?q=${encodeURIComponent(args.query)}`);
+    return await res.json();
+  },
+);
+```
+
+### 8.3 `IWebSearchProvider` — 网络搜索注入接口
+
+> 宿主实现此接口并注入 `AgentOptions.webSearchProvider`，即可让 Agent 拥有网络搜索能力。
+> 未注入时，Agent 不会暴露 `web_search` 工具给 LLM，LLM 被告知搜索不可用。
+> 内核提供 `FetchWebSearchProvider` 作为零依赖默认实现（`buildSearchEndpoints` 构建内置 Bing/DuckDuckGo 等预设降级链）。
+> **主推宿主自建 `SearchEndpoint` 注入**（自带 URL+解析），内核预设仅作零配置保底。
+
+```typescript
+// 搜索结果
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+  endpoint?: string;  // 实际后端名（降级打标用，自定义实现可省略）
+}
+
+// 搜索选项
+interface WebSearchOptions {
+  limit?: number;  // 返回结果数量上限（默认 5）
+}
+
+// 搜索端点契约：宿主可自建（自带 URL+解析）覆盖内核预设
+interface SearchEndpoint {
+  name: string;                       // 端点名（降级打标 / 结果透出）
+  buildUrl(query: string): string;    // 由查询构造请求 URL
+  parse(html: string, limit: number): SearchResult[];  // 解析结果页
+}
+
+// 网络搜索提供者接口
+interface IWebSearchProvider {
+  search(query: string, options?: WebSearchOptions): Promise<SearchResult[]>;
+}
+
+// 注入方式
+const agent = new Agent({
+  // ... 其他选项
+  // 方案 1（保底）：内置默认实现（Bing→DuckDuckGo 零配置开箱即用）
+  webSearchProvider: new FetchWebSearchProvider(),
+  // 方案 2（主推）：宿主自建端点注入，URL/解析完全由宿主掌控
+  // webSearchProvider: new FetchWebSearchProvider([
+  //   { name: 'MyEngine', buildUrl: (q) => `https://my.engine/s?q=${q}`, parse: myParse },
+  // ]),
+});
+
+// buildSearchEndpoints：预设名与自定义端点混排，内核预设仅作保底
+// buildSearchEndpoints(['bing', myEndpoint])  // 自定义端点优先，未知名忽略
+```
+
+### 8.4 `IFetchProvider` — 网页抓取注入接口（搜索→抓取闭环第二段）
+
+> 宿主实现此接口并注入 `AgentOptions.fetchProvider`，即可让 Agent 读取 `web_search` 找到的候选链接正文。
+> 未注入时，Agent 不会暴露 `web_fetch` 工具给 LLM。
+> 内核提供 `FetchWebFetchProvider` 作为基于内置 `fetch` + 正则清洗 HTML 的零依赖默认实现。抓取调用由内核 `toolExecutor` 经内部超时包装执行（30s；抓取失败/超时降级返回友好提示，不中断主流程）——该包装为**内部机制，不挂公共面**（PUB-API-PRUNE-2 收面，4.x 的 `safeFetch` 导出已删）。
+
+```typescript
+// 抓取结果
+interface FetchedPage {
+  url: string;
+  title: string;
+  content: string;
+  contentType?: string;
+  fetchFailed?: true;  // 抓取失败降级页标记（safeFetch 专有，值恒 true）；消费方据此区分「失败降级」与「成功但内容为空」
+}
+
+// 抓取选项
+interface FetchOptions {
+  maxChars?: number;  // 正文截断字符数上限
+}
+
+// 网页抓取提供者接口
+interface IFetchProvider {
+  fetch(url: string, options?: FetchOptions): Promise<FetchedPage>;
+}
+
+// 注入方式
+const agent = new Agent({
+  // ... 其他选项
+  fetchProvider: new FetchWebFetchProvider(), // 使用内置默认实现
+});
+```
+
+### 8.5 `ICodeExecutionProvider` — 代码执行注入接口
+
+> 宿主实现此接口并注入 `AgentOptions.codeExecutionProvider`，即可让 Agent 拥有通用代码执行能力（计算 / 数据处理 / 验证）。
+> 未注入时，Agent 不会暴露 `run_code` 工具给 LLM。
+> **内核零运行时依赖**：沙箱执行（语言白名单 / 资源限制 / 网络隔离）完全由宿主 provider 决定。执行调用由内核 `toolExecutor` 经内部超时包装执行（120s；执行失败/超时降级返回错误结果，不中断主流程）——该包装为**内部机制，不挂公共面**（PUB-API-PRUNE-2 收面，4.x 的 `safeExecuteCode` 导出已删）。
+
+```typescript
+// 执行结果
+interface CodeExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+}
+
+// 执行选项
+interface CodeExecutionOptions {
+  timeoutMs?: number;  // 单次执行超时上限（毫秒，默认 30000，最大 120000）
+  cwd?: string;        // 工作目录（可选，未传由执行器决定）
+}
+
+// 代码执行提供者接口
+interface ICodeExecutionProvider {
+  readonly supportedLanguages?: readonly string[]; // 支持的语言别名（如 ['javascript','js','node']）；声明后 run_code 工具描述按实际生成「支持：…」，缺省则退化为去承诺文案
+  execute(code: string, language: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
+}
+
+// 注入方式（沙箱实现由宿主提供）
+const agent = new Agent({
+  // ... 其他选项
+  codeExecutionProvider: mySandboxProvider,
+});
+```
+
+### 8.6 `IProjectSearchProvider` — 项目内搜索注入接口
+
+> 宿主实现此接口并注入 `AgentOptions.projectSearchProvider`，即可让 Agent 具备「在当前项目（工作区）中搜索」能力（等价 IDE 全局搜索 `Ctrl+Shift+F`）。
+> 未注入时，Agent 不会暴露 `search_project` 工具给 LLM。
+> **内核零依赖**：目录遍历 / 忽略规则 / 扫描与结果上限全由宿主决定。搜索调用由内核 `toolExecutor` 经内部超时包装执行（30s），并内置由分词 SSOT 产出的**放宽词表**（`buildSearchTerms`）——包装为**内部机制，不挂公共面**（PUB-API-PRUNE-2 收面，4.x 的 `safeSearchProjectFiles` / `safeSearchProjectText` 导出已删）。
+
+```typescript
+// 文件名命中
+interface ProjectFileMatch {
+  path: string;            // 相对项目根的 posix 路径
+}
+
+// 内容命中
+interface ProjectTextMatch {
+  path: string;
+  line?: number;           // 命中行号（1 起）
+  preview?: string;        // 命中行预览（去控制字符 + 限长，防上下文注入）
+}
+
+// 内容搜索的**结果对象**（含本次检索的元信息）
+interface ProjectTextSearchResult {
+  matches: ProjectTextMatch[];
+  truncated: boolean;                        // 检索被截断（零命中时也须如实回报）
+  truncatedBy?: 'results' | 'files';         // 截断主因：结果达上限 / 扫描达文件上限
+  scannedFiles?: number;                     // 实际参与匹配的文件数（宿主上报的数据）
+  partialReadFiles?: number;                 // 只检索了前一部分（过大）的文件数（**参与了**检索，非跳过）
+  unreadableSkipped?: number;                // 读取失败（权限/被删/悬空链接）完全未参与检索的文件数
+  perFileCapped?: boolean;                   // 有文件的命中被单文件上限截断
+  failed?: boolean;                          // 检索自身失败（超时/抛错）≠ 真零命中
+  relaxed?: boolean;                         // 已放宽为分词匹配 → 结果**非精确**命中
+  termsUsed?: string[];                      // 放宽时实际使用的词（文案的唯一取值来源）
+}
+
+interface ProjectTextSearchOptions extends ProjectFileSearchOptions {
+  pattern: string;         // 内容关键词（**字面量**语义，宿主自行转义，内核不假定正则）
+  terms?: string[];        // 内核下发的放宽词表；宿主**仅在整串零命中时**才启用
+}
+
+interface IProjectSearchProvider {
+  searchFiles(options?: ProjectFileSearchOptions): Promise<ProjectFileMatch[]>;
+  searchText(options: ProjectTextSearchOptions): Promise<ProjectTextSearchResult>;
+}
+```
+
+**实现约定（宿主侧，三条都是契约而非建议）**：
+
+1. **精确优先 + 零命中回退**：先按 `pattern` 整串字面量匹配；整串零命中**且** `terms` 非空时，才用 `terms` 做一次 OR 放宽，并置 `relaxed` + 回填 `termsUsed`（多词无需拆开传，**任一分词命中即算**，不是"全部包含"）。整串已命中时不得放宽——否则精确命中会退化成"可能不是精确命中"。
+2. **三态必须可区分**：`failed`（没搜完/搜坏了）/ `truncated`（没搜全）/ 真零命中，三者不得再压成同一个空数组——`[]` 承载不了任何元信息，会把"没搜到"与"没搜完"变成逐字同形。失败**不要**返回工具错误（"no results is not an error"），如实回报 `failed` 即可，由内核分流文案。
+3. **预算量以数据上报，不提升为内核常量**：`scannedFiles` / `partialReadFiles` / `unreadableSkipped` / `perFileCapped` 是宿主内部预算（扫描文件数 / 单文件字节 / 单文件命中数）与**读取结果**的事实；内核从不扫描，因此不持有这些常量，只把它们写进给 LLM 的文案。同理，`truncatedBy` 由宿主判定（只有宿主知道自己是因何停下）。
+   ⚠️ `partialReadFiles`（看了但没看全）与 `unreadableSkipped`（根本没看上）**必须分开上报**：两者都是「零命中 ≠ 不存在」的依据，但补救动作不同——前者换更具体的关键词或 `read_file` 精读，后者可重试。
+
+**放宽词表（内核侧）**：`buildSearchTerms(query)` 采用「显式片段优先」——空白分隔的片段是一等公民，不含 CJK 的片段原样保留（`Next.js` 不会被切成 `next` + `js`），含 CJK 的片段交给分词 SSOT。调用方（内核 `ToolExecutor`）会剔除与整串等价的词，因此单段查询通常不会触发放宽轮。
+
+> 参考实现：VS Code 宿主 `hosts/memora-vscode/src/extension/host/projectSearchProvider.ts`（`mode=name` 走 `workspace.findFiles`；`mode=content` 走受限 fs 递归扫描，忽略 `IGNORED_DIR_NAMES`）。
+
+### 8.7 后台命令任务（`run_command` background 模式）
+
+`run_command` 以 `background: true` 启动时**不阻塞本轮**：立即返回 `taskId`，进程在本轮对话之外继续跑。宿主经 Agent 门面查看 / 终止这些任务（注册表按 **Agent 实例隔离**，不跨会话互杀）。
+
+```typescript
+// 只读快照：供宿主 UI 渲染任务列表（只读投影，不含进程句柄）
+agent.listBackgroundTasks(): readonly BackgroundTask[]
+
+// 终止：先取已捕获输出快照再杀树，返回终态投影；taskId 不存在 → null
+agent.killBackgroundTask(taskId: string): BackgroundTask | null
+```
+
+> ⚠️ 两者**未 `init()` 时抛 `configError`**（`assertInitialized` 门面统一契约），
+> **不静默降级**——静默返回空会把「未初始化」伪装成「没有后台任务」。
+
+```typescript
+interface BackgroundTask {
+  taskId: string;                                   // 寻址用（kill_command 传入它取回输出）
+  command: string;
+  startedAt: number;                                // 启动时间戳（ms）
+  status: 'running' | 'completed' | 'timedOut' | 'killed';
+  result?: ScriptExecutionResult;                   // 进入终态后才有
+}
+```
+
+**寿命与可见性边界（务必转达用户）**：
+
+* 结果**不会自动进入上下文**——需模型调 `kill_command` 传入该 `taskId`，取回截至当时的输出并终止；
+* 不取则一直跑到自己结束（未传 `timeoutMs` 时**没有超时上限**）；
+* 正常退出 VS Code 时随扩展一并终止（扩展崩溃或被强制结束时不保证清理）。
+
+> 注册表类 `BackgroundTaskRegistry` **不进公共导出面**（内核内部模块）：导出它会让宿主
+> 跨会话 kill，与「仅可杀本 agent 起的后台任务」定案冲突——故**只出方法、不出类**；
+> 类型 `BackgroundTask` 与状态词表 `BACKGROUND_TASK_STATUS_LABELS`（宿主 UI 渲染状态
+> 文案的唯一真源，禁自建第二套）经 `@zooique/memora` 导出。
+
+---
+
+## 九、作品投影（`agent.works` · WorkProjectionManager）
+
+> 注：`WorkProjectionManager` 自 4.0.0 起为**内部类型**（不可具名 import），此处仅作 `agent.works` 的签名描述；可具名 import 的公开面以 §十六 为准。
+
+作品投影是**项目文件的「极简指针索引」**：一张清单，记录项目关键文件的 `name`（文件名）+ `description`（一句话说明）+ `source`（源文件路径），存储在**项目级文件** `<memoraDir>/work-projections.json`（JSON 数组，不进入记忆库）。**只存指针不存内容**——AI 按 `description` 自主判断相关性，再按需 `read_file` 读取 `source` 原文（设计详述见 [architecture/work-projection.md](architecture/work-projection.md)）。
+
+> **与记忆系统的边界**：作品投影是"作品感知"而非"对话记忆"（对话记忆唯一为 round-summary，沉淀在记忆库）。它**不参与记忆召回、不参与记忆治理**（去重/冲突检测不覆盖），随项目隔离——换项目即消失。装配链已在系统提示词自动注入投影块（`contextBlock()`），宿主无需手动注入。
+
+### 类型定义
+
+```typescript
+interface WorkProjectionEntry {
+  name: string;        // 作品名（默认取源文件名去扩展名）
+  description: string; // 一句话说明（告诉 AI 这个文件是干什么的）
+  source: string;      // 源文件路径（相对项目根，指向真实文件）
+}
+```
+
+### `agent.works` 公开方法
+
+| 方法 | 用途 |
+|------|------|
+| `agent.works.registerWork(sourcePath, description)` | 登记作品索引（`register_work` 工具数据源）：同 `source` 覆盖、否则追加；写入为「读盘 refresh → 追加 → 原子写盘」。预存文件格式异常（非顶层 JSON 数组）时**拒绝写入**防覆盖原索引（fail-safe） |
+| `agent.works.refresh()` | 从磁盘重新同步条目缓存，返回当前条目 |
+| `agent.works.listWorks()` | 列出全部投影条目（读盘同步后返回） |
+| `agent.works.contextBlock()` | 生成系统提示词注入块（`【项目索引】` 段；无条目返回空串） |
+| `agent.works.loadAndGetContextBlock()` | `refresh()` + `contextBlock()` 的组合 |
+
+> **注意**：`agent.works` 在 `init()` 前返回 `null`。内核侧**零 LLM 依赖**（纯读写、无后台任务）；`description` 可由宿主生成后传入（vscode 命令即先经 LLM 生成一句话描述、失败时用文件名兜底）。并发：当前为单 Agent 单进程场景，`registerWork` 无文件锁。
+
+### 宿主接入示例
+
+```typescript
+// vscode 宿主命令（memora.registerWork）：把工作区文件登记为作品索引
+const relativePath = vscode.workspace.asRelativePath(targetUri);
+// 宿主可选：先自行生成一句话描述（LLM 或用户输入）——内核只负责落盘
+const result = await agent.works?.registerWork(relativePath, description);
+// result: WorkProjectionEntry | null（null = 路径越界或索引文件格式异常被拒写）
+```
+
+---
+
+## 十、Provider 管理
+
+| 方法 | 用途 |
+|------|------|
+| `setProvider(provider)` | 运行时切换前台 Provider |
+| `setBackgroundProvider(provider)` | 运行时切换后台 Provider |
+
+Agent 不再管理 Provider 映射表，宿主自行管理。
+
+---
+
+## 十一、内部调试
+
+> v1.0 起已移除 `getBuildCtx()` 和 `inspect()` 方法。宿主项目可通过以下渠道观察内核状态：
+>
+> - **事件系统**（§2.7）：订阅 `memoryAdded` / `memoryRecalled` / `sessionArchived` 等事件获取运行时动态
+> - **可观测性 Tracer**（§十三）：注入 `ITracer` 实现获取 AgentLoop 关键 span（LLM_CALL / TOOL_EXEC / RESPONSE——`RECALL` 已随自动召回退役、内核零发射点）
+> - **`agent.memory.snapshot()`**（§4.1）：获取 3 层记忆快照（working / bootstrap / archive）
+> - **`agent.agentLoop.getMessages()`**（§4.4）：获取工作记忆原始消息列表
+
+---
+
+## 十二、完整 API 一览
+
+### Agent 面类直接方法
+
+| 分组 | 方法 |
+|------|------|
+| 生命周期 | `init()` / `close()` |
+| 对话 | `chat(input, signal?)` / `chatSync(input, signal?)` / `resumeExecution()` |
+| 事件 | `on()` / `off()` / `once()`（继承自 TypedEventEmitter） |
+| 暂停/继续 | `pause(reason, source?)` / `resume()` / `requestPause(reason, source?)` / `cancelPauseRequest()` / `isPausePending()` / `interject(content)` / `removePendingInterject(index)` / `clearPendingInterjections()` / `getPendingInterjections()` / `discardCurrentCheckpoint()` |
+| 会话 | `forkSession(targetSession?)` / `createCheckpoint()` / `getCheckpoint()` |
+| Provider | `setProvider(provider)` / `setBackgroundProvider(provider)` |
+| 归档模式 | `setArchiveMode(mode)` / `getArchiveMode()` |
+| 角色 | `switchRolePack(name)` / `getRolePackSwitchLockStatus()` / `getActiveTraits()` / `injectAffect(affectString)` |
+| 手动归档 | `archiveSession(...)` |
+| 配置热更新 | `reloadConfig(source?)` |
+| 后台任务 | `listBackgroundTasks()` / `killBackgroundTask(taskId)`（见 §8.7；未 `init()` 抛 `configError`，不静默降级） |
+| 记忆治理 | ~~经治理门面暴露~~ **该组方法已于 2026-10-18（5.0.0）整链退役**，理由为结构性恒空；`sourceHealth()` 的等价替代 = `agent.memory.stats().bySource`（见 §四 注记） |
+| 指标 | `getMetrics()` |
+
+> **手动归档触发选项**（`archiveSession(date, session, options?)`，2026-10-19 起）：
+> `options.autoTriggered`（系统自动触发；受 `archiveMode` 门控）+ `options.skipIfUnchanged`
+> （防重：距上次**实际完成归档**消息数未变则跳过 LLM。**缺省随 `autoTriggered`**——自动=防重、
+> 手动=无条件；显式传 `true` = 便捷手势也防重；显式 `false` = 强制重归档）。判据本体在
+> `SessionArchiver`（单点），协调器只转发意图。防重快照跨进程存活（内存态 + `SessionMeta.
+> archivedMessageCount` 落盘副本双源），宿主重启后不会重复烧 LLM；又聊过（消息数增）则一定
+> 重新归档。
+>
+> ⚠️ **该选项类型未具名导出**（`ArchiveTriggerOptions` 不在包导出面内）：调用方传**结构字面量**
+> 即可（`archiveSession(d, s, { skipIfUnchanged: true })`），TS 随 `archiveSession` 签名推导类型。
+> 刻意不导出——公开面登记门槛守卫（`PUBLIC-API-SURFACE-1`）要求新增导出必须有真实具名消费或
+> 文档承诺，本类型两者皆无（宿主只按字面量用），导出即纯增面。
+
+### Agent 面类只读访问器
+
+`initialized` / `context` / `provider` / `isBusy` / `lastInteractionAt` / `agentLoop` / `agentHistory` / `projects` / `security` / `sessionManager` / `rolePack` / `tools` / `skills` / `memory` / `works` / `polish`
+
+### 各 Manager / 组件公开成员
+
+| 访问器 | 类型 | 公开成员 |
+|---------|---------|---------|
+| `agent.rolePack` | `RolePackManager` | `.listMeta()` / `.activeName` / `.getActive()` / `.getActiveRules()` / `.activate()` / `.getSwitchLockStatus()` / `.getActiveTraits()` |
+| `agent.tools` | `ToolExecutor` | `.list` / `.registerTool()` / `.execute()` |
+| `agent.skills` | `SkillManager` | `.list` / `.match()` / `.register()` / `.buildSystemPrompt()` |
+| ~~记忆治理门面~~ | ~~`MemoryGovernance`~~ | **已移除（2026-10-18 · 5.0.0）**：整链退役，无成员可调；健康度需求改走 `agent.memory.stats().bySource`（见 §四 注记） |
+| `agent.memory` | `MemoryInspector` | 读：`.snapshot()` / `.searchByKeyword()` / `.stats()` / `.list()` / `.getById()` / `.getBySource()` / `.listDeleted()`（**`.search()` 已于 4.0.0 移除**）；写：`.writeUpsert()` / `.writeDelete()` / `.writeRestore()` / `.writePurge()` / `.writePurgeExpired()` |
+| `agent.works` | `WorkProjectionManager` | `.registerWork(sourcePath, description)` / `.refresh()` / `.listWorks()` / `.contextBlock()` / `.loadAndGetContextBlock()` |
+| `agent.polish` | `TextPolishManager` | `.polish(...)`（文本润色：LLM 语法修正 + 表达优化） |
+
+> **说明**：记忆查询与写入**只有** `agent.memory`（`MemoryInspector`）一个入口。历史访问器 memoryMutator 与 MemoryMutator 类（4.0.0 前）已合并回 `MemoryInspector`；治理门面已于 5.0.0 整链退役（§四 注记）——三个旧名都不在源码中，读旧文档时勿按其名查找。
+
+---
+
+## 十三、可观测性（ITracer / ISpan）
+
+Memora 内置轻量 Span/Trace 抽象，宿主注入实现后可观测 AgentLoop 行为。
+
+### 13.1 ITracer 接口
+
+```typescript
+interface ITracer {
+  startSpan(name: string, attributes?: Record<string, string | number | boolean>): ISpan;
+}
+```
+
+### 13.2 ISpan 接口
+
+```typescript
+interface ISpan {
+  setAttribute(key: string, value: string | number | boolean): void;
+  end(): void;
+  recordException(error: Error): void;
+}
+```
+
+### 13.3 NoopTracer（内核内部默认实现，**不挂公共面**）
+
+**不注入 `tracer` 即零运行时开销**——内核自动降级为内部 Noop 实现，所有 span 方法为空操作。
+宿主无需、也不应引用任何 Noop 实现类；要「关闭追踪」就是不传 `tracer`。
+
+### 13.4 TRACE_SPANS 常量
+
+```typescript
+import { TRACE_SPANS } from '@zooique/memora';
+
+TRACE_SPANS.LLM_CALL         // 'llm.call'           — LLM API 调用
+TRACE_SPANS.TOOL_EXEC        // 'tool.execute'       — 工具执行
+TRACE_SPANS.RESPONSE         // 'response.generate'  — 整轮响应
+TRACE_SPANS.CONTEXT_SUMMARY  // 'context.summary'    — 上下文摘要生成（消息超窗触发截断时）
+TRACE_SPANS.POST_PROCESS     // 'archive.postProcess' — 每轮 chat() 后的归档处理
+TRACE_SPANS.DIFFICULTY       // 'round.difficulty'   — 难度分级（预留名）
+TRACE_SPANS.REPORT           // 'round.report'       — 汇报闭环（预留名）
+```
+
+> 共 **7** 个常量（数量由 `src/agent/__tests__/tracer.test.ts` 锁定）。
+>
+> **预留名**：`DIFFICULTY` / `REPORT` 内核当前**零 emit 点**——宿主按名建监控面板暂时收不到这两个 span 的数据，不要据此判定链路异常。
+>
+> **已删除**：`TRACE_SPANS.RECALL`（`'recall.recall'`）与 `TRACE_SPANS.RECALL_ACTUAL`（`'recall.actual'`）已于 **2026-09-11 物理删除**（自动记忆召回退役后无 emit 点，不留幽灵契约）；现行记忆检索耗时看 `TOOL_EXEC`（`search_memories` 工具）。
+
+---
+
+## 十四、工具错误码（ToolErrorCode）
+
+工具执行失败时，内核产出**结构化** `ToolOutcome`（完整契约见 §14.3）。与本表直接相关的两个字段：
+
+* `errorCode` —— 失败原因分类，**Reflection 重试判定的判据面**；
+* `text` —— 渲染面，形如 `` `[ERR:TOOL:${code}] …` `` 给 LLM 自愈看。
+
+**`text` 前缀由 `errorCode` 派生**（唯一构造出口 `failedOutcomeWithCode` 一次产出二者），
+故解析文案取码与读 `errorCode` 字段**恒等价**，不存在漂移。
+
+### 14.1 错误码枚举
+
+| 错误码 | 可重试 | 说明 |
+|--------|--------|------|
+| `PATH_NOT_ALLOWED` | ❌ | 路径不在白名单内 |
+| `FILE_NOT_FOUND` | ✅ | 文件不存在（LLM 可能用错路径） |
+| `PERMISSION_DENIED` | ❌ | 权限不足 |
+| `ARGUMENT_ERROR` | ✅ | 工具参数错误（LLM 可修正参数格式） |
+| `WRITE_REJECTED` | ❌ | 用户拒绝写入 |
+| `DIR_NOT_FOUND` | ✅ | 目录不存在 |
+| `UNKNOWN_TOOL` | ❌ | 未知工具 |
+| `CUSTOM_TOOL_FAILED` | ✅ | 自定义工具执行失败 |
+| `NOT_AVAILABLE` | ❌ | 能力未装配 / 未注入回调（provider 或技能回调缺失）——重试无意义 |
+| `UNKNOWN` | ❌ | 通用错误 |
+
+> ⚠️ **订正（对齐 `src/utils/errors.ts` 实际枚举）**：旧版此表列有 `TOOL_TIMEOUT`（★可重试），
+> 该值**已从枚举删除**（删除后 retryable 由 5 → 4），属文档死条目，已移除。
+> 另：结果文本里会出现 `[ERR:TOOL:ABORTED]`，但 `ABORTED` **故意不入本枚举**
+> （中断不触发 Reflection，见 `toolRunner`），勿按本表去找它。
+
+### 14.2 isRetryableErrorCode()
+
+```typescript
+import { ToolErrorCode, isRetryableErrorCode } from '@zooique/memora';
+
+isRetryableErrorCode(ToolErrorCode.FILE_NOT_FOUND);   // true
+isRetryableErrorCode(ToolErrorCode.PATH_NOT_ALLOWED);  // false
+```
+
+### 14.3 `ToolOutcome` — 工具结果契约（status 三值 + errorCode）
+
+工具结果在内核内部与可观测面共用同一形状（`agent/managers/toolCallHelpers`）：
+
+> **可观测性说明（勿踩空）**：`ToolOutcome` 是**内核内部**形状，
+> **未从 `@zooique/memora` 导出**（`src/index.ts` 无此导出），**不要尝试 import 它**。
+> 宿主是**间接**观察它的：`tool_result` chunk 的 `ok` / `blocked` 字段即由 `status` 派生
+> （`ok` ⇔ `status==='ok'`，`blocked` ⇔ `status==='blocked'`），计数经 `getMetrics()` 暴露。
+> 本节列出它是为了说清三值语义与计数口径，不是新增可导入类型。
+
+```typescript
+interface ToolOutcome {
+  readonly status: ToolStatus;              // 'ok' | 'failed' | 'blocked' —— 判据面唯一真源
+  readonly text: string;                    // 渲染面（原样回给 LLM 自愈）
+  readonly blockedReason?: BlockedReason;   // 仅 blocked：为什么没成功（与 status 正交）
+  readonly hasRealFailure?: boolean;        // 仅 blocked：背后是否藏真失败
+  readonly errorCode?: ToolErrorCodeValue;  // 仅 failed：失败原因分类（见 §14.1）
+}
+```
+
+| `status` | 语义 | 计入 `toolFailureCount`？ |
+|-----------|------|---------------------------|
+| `ok` | 工具正常执行完成（**含"成功但无输出"**：`exitCode 0` + 空输出仍是成功） | ❌ |
+| `failed` | 工具真的跑了但失败（非零退出 / 超时 / 抛异常 / 参数非法 / 资源不存在） | ✅ |
+| `blocked` | **我们主动挡下的**（护栏拦截 / 只读拒绝 / 幂等跳过 / fail-closed 拒绝） | ❌（改计 `toolBlockedCount`） |
+
+**纪律（勿回改）**：
+
+1. `blocked` 既非成功也非失败——「主动挡下的 ≠ 工具跑失败的」，三值穷尽，不加第四值；
+2. 消费者判成败**一律读 `status` 字段**，不得解析 `text`（B4/B5 后内核零文本判据，
+   `isToolFailure` 文本判据桥已物理删除）；
+3. `blockedReason` 与 `status` 正交——前者只回答「为什么没成功」，不新增 status 值；
+4. `errorCode` 与 `text` 前缀在 `failedOutcomeWithCode` **同源产出一次**，改一处即两处同步。
+
+---
+
+## 十五、工具错误反思（Reflection）
+
+> 注：原「内容护栏（Guardrails）」章节已移除——guardrail 是「零规则、无扫描映射、无消费者」的空转链，已随内核摘除（2026-08-17，见 memory-role-pack-boundary.md §4.4）。本章仅保留原 15.3 的有效内容。
+
+当工具执行失败且错误码为 retryable 时，AgentLoop 自动注入 `[REFLECTION_HINT]` 系统消息，引导 LLM 修正参数后重试。默认最多重试 2 次（`maxReflectionRetries`）。
+
+> ⚠️ **执行类失败不进自动 Reflection（设计口径，非回归）**：`run_command` / `run_code` / `run_project_script` / `run_skill_script` 四条执行链路失败时返回**不带 `errorCode`** 的失败结果，不满足上述「retryable 错误码」触发条件，AgentLoop 因此不注入 `[REFLECTION_HINT]`。结局事实（超时 / 非零退出码 / 许可拒绝等）已完整呈现在返回文本里，LLM 读到后自行决定是否调整重试；自动重试机制只服务于带 retryable 错误码的工具失败（错误码全集见 §十四）。
+
+---
+
+## 十六、类型导出
+
+> 以下**精选子集**为宿主最常用的公开导出，全部经 `@zooique/memora` 再导出（无幻影）；未在清单中的其他导出（如 `SessionManager` / `ProviderRouter` 等）以 `src/index.ts` 为准。导出面已于 2026-10-06 收敛：只保留「宿主消费」或「本手册 / README 明文承诺」的符号，内部实现不再挂公共面。治理报告类型（`DedupReport` / `SourceHealthReport` 等）经方法返回推断，不列为显式导出。
+
+> ⚠️ **正文表格里的类型名以本节清单为准**（不等于本节是全集——未列出的导出见上方首注，以 `src/index.ts` 为准）：正文（§二 ~ §十五）表格「类型」列里的名字只用于**描述签名**，其中一部分自 4.0.0 起已降为内部类型——它们**不可具名导入**（深导入不可达），类型随 agent 对象的返回值推断即可用。
+
+```typescript
+// Agent 与流式事件
+export { Agent } from '@zooique/memora';
+export type {
+  AgentChunk,
+  ThinkingPhase,
+  UIMessages,
+  ArchiveMode,
+} from '@zooique/memora';
+export type {
+  AgentOptions,
+  AgentContext,
+} from '@zooique/memora';
+export { type AgentForkResult } from '@zooique/memora';
+export type { SessionCheckpoint } from '@zooique/memora';
+
+// 记忆快照与搜索（MemoryInspector）
+export type {
+  MemorySnapshot,
+  WorkingMemorySnapshot,
+  BootstrapSnapshot,
+  ArchiveSnapshot,
+  AgentSearchHit,
+  AgentStats,
+} from '@zooique/memora';
+// 记忆治理门面已于 5.0.0（2026-10-18）整链退役，健康度替代通道见 §四 注记
+// 文本润色
+export type { PolishResult } from '@zooique/memora';
+export { AGENT_CONSTANTS, LOOP_CONSTANTS } from '@zooique/memora';
+
+// 工具
+export type { ToolDefinition, ToolHandler, ToolContext, WriteExtensions } from '@zooique/memora';
+// 网页抓取（搜索→抓取闭环第二段）
+export type { IFetchProvider, FetchedPage, FetchOptions } from '@zooique/memora';
+export { FetchWebFetchProvider } from '@zooique/memora';
+// 代码执行（通用计算底座）
+export type { ICodeExecutionProvider, CodeExecutionResult, CodeExecutionOptions } from '@zooique/memora';
+
+// 作品投影
+export type { WorkProjectionEntry } from '@zooique/memora';
+
+// 记忆
+export { SOURCE_LABELS, SUMMARY_TYPES } from '@zooique/memora';
+export type { Memory } from '@zooique/memora';
+export { validateSource } from '@zooique/memora';
+export type { SourceValidationSeverity } from '@zooique/memora';
+export type { IMemoryStorage } from '@zooique/memora';
+// 记忆存储落盘实现（工厂 + 只读视图）
+export { createNodeSqliteStorage } from '@zooique/memora';
+export type { ReadOnlyMemoryStorage } from '@zooique/memora';
+export type { ISessionStore, SessionMessage } from '@zooique/memora';
+export type { ForkResult } from '@zooique/memora';
+
+// 事件系统
+export { TypedEventEmitter } from '@zooique/memora';
+export type { AgentEventMap, AgentEventName, AgentEventHandler } from '@zooique/memora';
+
+// 可观测性
+export type { ITracer, ISpan, AgentMetrics } from '@zooique/memora';
+export { TRACE_SPANS } from '@zooique/memora';
+
+// 错误码
+export { MemoraError, ToolErrorCode, isRetryableErrorCode } from '@zooique/memora';
+export type { ToolErrorCodeValue } from '@zooique/memora';
+
+// 日志
+export type { ILogger } from '@zooique/memora';
+export { setLogger, logger } from '@zooique/memora';
+
+// 网络搜索
+export type { IWebSearchProvider, SearchResult, WebSearchOptions, SearchEndpoint } from '@zooique/memora';
+export { FetchWebSearchProvider } from '@zooique/memora';
+
+// 角色包
+export type { RolePackMeta } from '@zooique/memora';
+
+// 技能
+export type { SkillEntry } from '@zooique/memora';
+
+// LLM
+export { createProviderFromConfig } from '@zooique/memora';
+export type { ProviderConfig } from '@zooique/memora';
+export type { LlmProvider, ChatOptions } from '@zooique/memora';
+export type { LlmChunk } from '@zooique/memora';
+
+// 配置
+export { loadConfig } from '@zooique/memora';
+export type { Config } from '@zooique/memora';
+
+// 工具函数
+export { segmentLower } from '@zooique/memora';
+export { parseFrontmatter } from '@zooique/memora';
+export { formatDateKey, todayDate } from '@zooique/memora';
+
+// 安全
+export type {
+  AuditEvent,
+  AuditListener,
+  Permission,
+  WriteDecision,
+  WriteConfirmationInfo,
+  WriteConfirmationRequest,
+} from '@zooique/memora';
+```
+
+> **记忆存储落盘实现（2026-10-16 新增，内核切片）**：`createNodeSqliteStorage`（**同步工厂**，收数据库文件全长路径，
+> 返回 `IMemoryStorage`）与 `ReadOnlyMemoryStorage`（**只读视图类型**，即 `IMemoryStorage` 的读方法子集）。
+> 契约要点：① **只出工厂不出实现类**——实现类不挂公共面，须经工厂创建；② **可用性判据唯一来源 = 调用工厂的结果**
+> （模块不可用时抛专属错误，其错误码为 `ToolErrorCode.NOT_AVAILABLE`）；宿主**不得**自行解析 Node 版本号推断；
+> ③ **只读视图**：工厂第二参数为只读开关，返回对象**结构上不含写方法**（供只读宿主零并列复用同一实现），
+> 只读连接不建库、不迁移；④ 文件路径语义留在宿主侧（内核不拼目录、不定义文件名）；⑤ 实现仅依赖 Node 内建模块，
+> 不引入第三方运行时依赖。稳定性：随 `5.0.0` 起提供，语义受契约对拍测试（与内核内置内存实现逐位一致）约束。
+
+---
+
+## 十七、安全与约束
+
+### 核心库零越界
+
+| 检查项 | 结论 |
+|--------|------|
+| 核心库 `console.*` 调用 | 0 处 |
+| 核心库 `process.stdin/stdout` | 0 处 |
+| 核心库写配置文件 | 0 处 |
+| 核心库 `readFileSync/writeFileSync` 写宿主业务文件 | 0 处 |
+
+### 内部数据写入（不越界）
+
+Agent 内部只维护一个状态文件，路径全部由宿主传入的路径推导，内核不假设 `~/.memora/` 一类的用户级默认位置：
+
+- `.lock`（项目锁）——固定落 `<projectPath>/.memora/.lock`，**不由 `dataDir` 推导**
+
+`dataDir` 仅作 Agent 级资源目录（确保存在）；宿主注入 `IMemoryStorage` 时内核**不**在该目录下
+落任何文件。（PR-SWITCH-1 前内核曾在此写 `projects.json` 跨项目注册表，随多项目形态定案删除。）
+
+---
+
+**版本**：v5.0.0
+**配套文档**：[memora-接入指南.md](./memora-接入指南.md)（步骤式教程）