@zooique/memora 2.0.3 → 3.0.0

package/docs/memora-/346/216/245/345/205/245/346/214/207/345/215/227.md

@@ -1,808 +1,843 @@
-# Memora · 接入指南 v2.0.3
-
-> 帮助宿主项目开发者快速理解 Memora 的设计理念和接入方法。
->
-> **版本**：v2.0.3（最后更新：2026-08-01）
->
-> **1.0.0 之前：核心能力演进**（原内部里程碑 v3.0–v3.3，于 npm 0.2.0 前后完成）：
-> - **Agent God Object 拆分（原 v3.0）**：记忆查询、规则注入、工具注册等方法迁移到专职 Manager，通过 `agent.<manager>.xxx()` 访问。详见 [API 参考手册](./memora-api-reference.md)。
-> - **可观测性与护栏（原 v3.1）**：新增可观测性（ITracer）、内容护栏（Guardrails）、工具错误反思（Reflection）、评估体系（Eval）支持。
-> - **关系图谱与画像（原 v3.2）**：新增 ADR-014 记忆关系图谱（IMemoryRelationStore 侧车接口）、UserProfile 用户画像管理、WorkProjectionManager 作品投影、AutoConfigRefiner 自进化配置建议。
-> - **npm 正式包与基础工具（原 v3.3）**：内核发布 v0.2.0（npm 正式包），精灵切换至 npm alias 依赖。Phase 1-4 全部核心完成。新增 EmbeddingProvider、安全定时器（safeSetTimeout/safeSetInterval）、Frontmatter 工具、事件系统（TypedEventEmitter）、记忆关系常量（RELATION_TYPES/RELATION_WEIGHTS）、审计类型（AuditEvent 等）、评估框架（EvalScenario/collectAgentChunks/evaluateResult）。
->
-> **v1.0.0 变更**：1.0 正式发布。P0 阻塞修复全量收敛：DEFAULT_CONFIG 由 `config/loader.ts` 常量声明单一真理源（不再维护独立 schema）、IVectorStore 接口提取（JsonVectorStore 内置实现）、AbortSignal 合并工具、Logger 懒初始化（移除模块顶层副作用）、评估框架结构化信号（guardrailBlocked 替代文案匹配）、文档全量对齐（包名 @zooique/memora）。
->
-> **v2.0.0 变更**：版本号提升（维护性质，无破坏性 API 变更）。
->
-> **v2.0.1 变更**：文档版本号对齐（v1.0.2 → v2.0.1）。无 API 破坏性变更，仅同步文档与版本戳。
+# Memora · 接入指南 v3.0.0
+
+> 帮助宿主项目开发者快速理解 Memora 的设计理念和接入方法。
 >
-> **v2.0.2 变更**：万物皆记忆 v2（双轨模型——设定记忆 + 对话记忆）。Persona/Skill 从 SQLite 索引解耦，改为纯文件 + 内存缓存。Skill 匹配改为当轮实时注入。详见 [CHANGELOG](../CHANGELOG.md)。
+> **当前稳定版**：v3.0.0。各版完整变更见 [CHANGELOG](../CHANGELOG.md)。
 >
-> **v2.0.3 变更**：npm 发布配置修复与质量加固。新增 `publishConfig.access = "public"`、`exports` 增加 `default` 回退条件、`keywords` 扩充至 18 个。无 API 破坏性变更。
-
----
-
-## 目录
-
-- [一、核心理念](#一核心理念)
-- [二、三重数据存续路径](#二三重数据存续路径)
-- [三、最小接入步骤](#三最小接入步骤)
-- [四、会话持久化](#四会话持久化)
-- [五、API 速查](#五api-速查)
-- [六、宿主工具函数](#六宿主工具函数)
-- [七、可观测性接入（ITracer）](#七可观测性接入itracer)
-- [八、内容护栏（Guardrails）](#八内容护栏guardrails)
-- [九、评估体系（Eval）](#九评估体系eval)
-- [十、多步骤编排](#十多步骤编排)
-- [十一、关键约束](#十一关键约束)
-
----
-
-## 一、核心理念
-
-**Memora 是一个无法独立运行的智能大脑内核。** 它只有接口，没有"形态"——宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
-
-**万物皆记忆 v2。** Memora 有两类记忆：**设定记忆**（Persona/Skill/Rule —— Agent 的骨骼，.md 文件 + 内存缓存，确定性注入不经过召回）和**对话记忆**（Conversation/Insight/UserProfile —— Agent 的血肉，SQLite + VectorStore，语义召回）。二者通过 `autoConfigRefiner` 连接——对话洞察可生长为设定文件。
-
-**单 Agent 模型。** 所有对话、所有记忆存在同一个数据库中，**切换子项目不会丢失记忆**。
-
-**配置文件是真理源，对话记忆走 SQLite 索引。** Persona/Skill 为纯文件 + 内存缓存；Rule 文件写入 SQLite 供 bootstrap 读取；对话记忆（insight/profile）走 SQLite + 语义召回。
-
-**内核零越界。** 核心库不调用 `console.*`、不读 `process.stdin`、不管理 API Key、不写用户配置文件。
-
-**Manager 委托模式（1.0.0）。** Agent 面类只做编排，领域操作委托给 9 个专职 Manager：`agent.persona` / `agent.tools` / `agent.skills` / `agent.config` / `agent.insight` / `agent.memory` / `agent.userProfile` / `agent.works` / `agent.polish`（文本润色）。
-
-```
-┌────────────────────────────────────────────────────────────┐
-│  宿主程序                                                   │
-│  ┌─────────────────┐    ┌──────────────────┐               │
-│  │ LLM Provider 实例 │◄───│ API Key / baseUrl │  ← 宿主职责  │
-│  └────────┬────────┘    └──────────────────┘               │
-│           │ 注入                                            │
-│           ▼                                                 │
-│  ┌──────────────────────────────────────────┐               │
-│  │  Memora 内核（Agent）                    │               │
-│  │  - chat(input) → 流式响应                │               │
-│  │  - 9 个 Manager getter（委托模式，含文本润色）      │               │
-│  │  ⚠️ 不包含：UI / LLM 配置 / 用户配置模板 │               │
-│  └──────────────────────────────────────────┘               │
-└────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 二、三重数据存续路径
-
-| 路径 | 用途 | 示例 |
-|------|------|------|
-| `AgentOptions.configDir` | Agent 级配置（personas/rules/skills） | 嵌入宿主程序 |
-| `AgentOptions.dataDir` | 记忆数据（memora.db + sessions/） | 跟作品走 |
-| `projectPath/.memora/` | 项目级配置（rules/skills） | 跟作品走 |
-
-**小说生成器推荐布局：**
-```
-小说项目/
-├── .memora/           ← 项目级配置（rules + skills）
-└── .memora-data/      ← 项目级记忆（dataDir 指向此处）
-    ├── memora.db
-    └── sessions/
-```
-
----
-
-## 三、最小接入步骤
-
-### 1. 安装
-
-```bash
-npm install @zooique/memora
-```
-
-### 2. 创建 Provider + Agent
-
-```typescript
-import { Agent, createLlmProvider, JsonVectorStore, setLogger } from '@zooique/memora';
-import type { IMemoryStorage, ILogger, EmbeddingService } from '@zooique/memora';
-
-// 宿主职责：创建 LLM Provider（Agent 不关心 API Key）
-const provider = createLlmProvider({
-  provider: 'openaiCompatible',
-  apiKey: process.env.LLM_API_KEY!,
-  baseUrl: 'https://api.deepseek.com/v1',
-  model: 'deepseek-chat',
-});
-
-// 可选：后台 Provider（投影等后台操作）
-const backgroundProvider = createLlmProvider({
-  provider: 'openaiCompatible',
-  apiKey: process.env.LLM_API_KEY!,
-  baseUrl: 'https://api.deepseek.com/v1',
-  model: 'deepseek-chat', // 可用更便宜的模型
-});
-
-// 可选：注入存储层（不传则使用 InMemoryStorage）
-const storage: IMemoryStorage = new MySqliteStorage('/path/to/memora.db');
-
-// 可选：全局替换日志实现（不调用则使用内置 console logger；pino 为可选 peer 依赖，动态 import 懒加载）
-setLogger(myCustomLogger);
-
-// 可选：向量存储（提供后启用语义搜索召回）
-const embeddingService: EmbeddingService = myEmbeddingService;
-const vectorStore = new JsonVectorStore('/path/to/vectors.json', embeddingService);
-
-// 创建 Agent
-const agent = new Agent({
-  projectPath: '/path/to/novel-project',
-  provider,              // 前台 Provider（必须）
-  backgroundProvider,    // 后台 Provider（可选）
-  configDir: '/path/to/agent-config',
-  dataDir: '.memora',
-  maxContextTokens: 120000,
-  persona: '作家',
-  permission: 'owner',
-  allowedPaths: ['.'],
-  confirmWrites: false,
-  storage,               // 存储层注入（可选）
-  vectorStore,           // 向量存储（可选，启用语义搜索）
-  tracer: myOtelTracer,  // 可观测性 Tracer（可选，不传则静默丢弃所有 span）
-});
-
-await agent.init();
-```
-
-### 3. 对话
-
-```typescript
-// 流式对话（生产推荐）
-for await (const chunk of agent.chat('帮我写一段玄幻小说开头')) {
-  switch (chunk.type) {
-    case 'text':       ui.appendText(chunk.content); break;
-    case 'thinking':   ui.showThinking(chunk.phase); break;
-    case 'tool_start': ui.showToolStart(chunk.name); break;
-    case 'tool_result':ui.showToolResult(chunk.ok); break;
-    case 'aborted':    ui.showCancelled(chunk.reason); break;
-  }
-}
-
-// 同步对话（测试用）
-const reply = await agent.chatSync('你好');
-```
-
-### 3.5 事件订阅（可选）
-
-Agent 向宿主广播对话外事件（记忆变更、角色切换、衰减完成、会话分叉等）。
-
-```typescript
-import type { AgentEventMap } from '@zooique/memora';
-
-agent.on('memoryAdded', (e) => console.log(`新记忆: ${e.source}:${e.name}`));
-agent.on('personaSwitched', (e) => console.log(`角色: ${e.from} → ${e.to}`));
-agent.on('decayCompleted', (e) => console.log(`衰减 ${e.decayedCount} 条记忆`));
-agent.on('memoryRecalled', (e) => console.log(`想起 ${e.count} 条记忆`));
-agent.on('sessionForked', (e) => console.log(`分叉: ${e.from} → ${e.to}，${e.messageCount} 条消息`));
-
-// close() 自动移除所有监听器
-```
-
-### 4. 注册领域工具
-
-> 1.0.0：工具注册走 `agent.tools.xxx()`。
-
-```typescript
-agent.tools.registerTool(
-  {
-    name: 'create_chapter',
-    description: '创建一个新章节',
-    parameters: {
-      type: 'object',
-      properties: { title: { type: 'string', description: '章节标题' } },
-      required: ['title'],
-    },
-  },
-  async (args) => {
-    const chapter = await myNovel.createChapter(args.title);
-    return `章节 "${args.title}" 已创建`;
-  },
-);
-```
-
-### 5. 注入写入扩展 + 记忆关键词
-
-> 1.0.0：写入扩展和关键词走 `agent.insight.xxx()`。
-
-```typescript
-// 写入前 diff 确认回调
-agent.insight.setWriteExtensions({
-  onBeforeWrite: async (path, before, after) => {
-    showDiff(path, before, after);
-    return await userConfirm(`确认写入 ${path}？`);
-  },
-});
-
-// 记忆关键词（领域 + 用户专属）
-agent.insight.setKeywords({
-  domain: ['主角', '角色', '情节', '设定'],
-  personal: ['我', '我的', '记住', '帮我'],
-});
-```
-
-### 6. 注入项目规则
-
-> 1.0.0：规则注入走 `agent.config.xxx()`。
-
-```typescript
-await agent.config.addSimpleRule(
-  '世界观规则',
-  '这是一个东方玄幻世界，修真等级分为炼气、筑基、金丹……',
-);
-```
-
-### 7. 查询记忆
-
-> 1.0.0：记忆查询走 `agent.memory.xxx()`。
-
-```typescript
-// 3 层记忆快照
-const snap = agent.memory.snapshot();
-console.log('工作记忆:', snap.working.total, '条');
-console.log('引导记忆:', snap.bootstrap.total, '条');
-
-// 关键词搜索
-const hits = agent.memory.search('世界观');
-hits.forEach(h => console.log(`${h.source}:${h.name} (${h.score})`));
-
-// 记忆库统计
-const stats = agent.memory.stats();
-console.log('记忆总数:', stats.total);
-```
-
-### 8. 管理角色
-
-> 1.0.0：角色管理走 `agent.persona.xxx`。
-
-```typescript
-// 列出所有角色
-const names = agent.persona.list.map(p => p.name);
-
-// 手动切换（返回新角色的 system prompt，可用于 UI 展示）
-const personaPrompt = agent.persona.switchPersona('作家');
-
-// 锁定手动模式（禁止自动匹配）
-agent.persona.setMode('manual');
-
-// 查询当前状态
-console.log(agent.persona.activeName);   // '作家'
-console.log(agent.persona.currentMode);  // 'manual'
-```
-
-### 9. 切换项目
-
-```typescript
-// switchProject() 自动 rebuild，无需手动调用 rebuildComponents()
-const ctx = await agent.switchProject('another-novel');
-console.log(`已切换到：${ctx.projectName}`);
-```
-
-### 10. 关闭
-
-```typescript
-await agent.close(); // 释放项目锁 + 关闭数据库
-```
-
----
-
-## 四、会话持久化（ISessionStore）
-
-Memora 通过 `ISessionStore` 接口支持会话消息的持久化。宿主实现此接口，注入到 Agent。
-
-```typescript
-import type { ISessionStore, SessionMessage } from '@zooique/memora';
-
-// 宿主实现接口
-class FileSessionStore implements ISessionStore {
-  appendMessage(date: string, session: string, message: SessionMessage): void {
-    // 写入文件或数据库
-  }
-  loadMessages(date: string, session: string): SessionMessage[] {
-    // 从文件或数据库读取
-    return [];
-  }
-  listSessions(): string[] {
-    // 返回所有会话列表
-    return [];
-  }
-}
-
-// 注入到 Agent
-const agent = new Agent({
-  // ...其他配置
-  sessionStore: new FileSessionStore('./sessions'),
-});
-```
-
-**会话持久化特性：**
-- 日期使用 `todayDate()` 动态获取，确保跨日后消息写入当天目录
-- `appendUser()` / `appendAssistant()` 自动调用 `appendMessage()`
-- `loadSessionMessages()` 自动调用 `loadMessages()`
-- `SessionMessage.role` 支持 `'user' | 'assistant' | 'system'`，宿主直接调用 `appendMessage()` 时可传入任意角色
-
----
-
-## 四.5、会话分叉（Fork Session）
-
-Memora 支持会话分叉功能，允许用户从当前对话创建独立分支，继承完整消息历史后各自独立发展。
-
-**使用场景**：
-- 用户在对话中建立了丰富的上下文后，可以分叉到多个并行任务
-- 每个分支继承已建立的共识，避免从零开始
-- 分支完全独立，互不干扰
-
-```typescript
-// 自动生成分支名（main-b1, main-b2, ...）
-const result = agent.forkSession();
-console.log(`已分叉到: ${result.newSession}，复制了 ${result.messageCount} 条消息`);
-
-// 自定义分支名
-const result2 = agent.forkSession('experiment');
-```
-
-**命名规则**：
-- 自动生成：`{原始会话名}-b{序号}`（如 `main-b1`、`main-b2`）
-- 支持分叉的分叉：`main-b1-b1`
-- 自定义名称：直接传入目标名称
-
-**记忆处理策略**：
-- 已有记忆：全局共享（记忆是全局知识库，不属于单个会话）
-- 分叉后的 Insight：各自独立（不同分支探索不同方向）
-- 用户画像：全局共享（UserProfile 是全局的）
-
-**事件监听**：
-```typescript
-agent.on('sessionForked', (event) => {
-  console.log(`从 ${event.from} 分叉到 ${event.to}`);
-  console.log(`复制了 ${event.messageCount} 条消息`);
-});
-```
-
-**边界情况**：
-- 当前会话无消息时抛出错误
-- `ISessionStore` 未注入时抛出错误
-- 对话正在进行中（`chatBusy`）时抛出错误
-- 自定义名称已存在时抛出错误
-
----
-
-## 五、API 速查
-
-> 完整定义见 [memora-api-reference.md](./memora-api-reference.md)。
-
-### 构造选项 `AgentOptions`
-
-| 选项 | 类型 | 必须 | 说明 |
-|------|------|------|------|
-| `projectPath` | `string` | ✅ | 项目路径 |
-| `provider` | `LlmProvider` | ✅ | 前台 LLM Provider |
-| `backgroundProvider` | `LlmProvider` | ❌ | 后台 Provider（投影） |
-| `configDir` | `string` | ❌ | 配置目录（personas/rules/skills） |
-| `dataDir` | `string` | ❌ | 记忆数据目录（默认 ~/.memora） |
-| `registryDir` | `string` | ❌ | 项目注册表目录（默认与 dataDir 相同） |
-| `maxContextTokens` | `number` | ❌ | 上下文窗口上限（默认 120000） |
-| `persona` | `string` | ❌ | 默认角色名 |
-| `permission` | `'owner' \| 'guest'` | ❌ | 安全权限（默认 'owner'） |
-| `allowedPaths` | `string[]` | ❌ | 路径白名单（默认 [] = 全部允许） |
-| `confirmWrites` | `boolean` | ❌ | 写入确认（默认 false） |
-| `storage` | `IMemoryStorage` | ❌ | 存储层注入 |
-| `relationStore` | `IMemoryRelationStore` | ❌ | 记忆关系存储（ADR-014 侧车，不传则跳过关系构建） |
-| `vectorStore` | `IVectorStore` | ❌ | 向量存储接口（提供时启用语义搜索；内置实现 `JsonVectorStore`） |
-| `recallExcludeSources` | `string[]` | ❌ | 召回时排除的 source 标签（默认 `['persona', 'rule', 'skill']`） |
-| `sessionStore` | `ISessionStore` | ❌ | 会话存储注入 |
-| `tracer` | `ITracer` | ❌ | 可观测性 Tracer 注入（不传则使用 NoopTracer 静默丢弃所有 span） |
-| `messages` | `UIMessages` | ❌ | 宿主可覆盖的 UI 消息文本（默认英文，宿主覆盖为中文等） |
-| `enableContextSummary` | `boolean` | ❌ | 上下文超限时是否自动生成摘要（默认 true，开启后首次截断时增加 ~1-2s 延迟） |
-
-### Agent 生命周期与状态
-
-| 成员 | 说明 |
-|------|------|
-| `agent.init()` | 初始化（创建存储、加载配置、组装组件），返回 `AgentContext` |
-| `agent.close()` | 安全关闭（释放锁 + 关闭数据库） |
-| `agent.initialized` | 只读 getter，`boolean` |
-| `agent.isBusy` | 只读 getter，`boolean`（是否正在对话中） |
-| `agent.lastInteractionAt` | 只读 getter，`Date \| null`，最近一次对话时间 |
-| `agent.context` | 只读 getter，`AgentContext \| null`，当前项目上下文 |
-
-### 对话
-
-| 方法 | 说明 |
-|------|------|
-| `agent.chat(input, signal?)` | 流式对话，返回 `AsyncGenerator<AgentChunk>` |
-| `agent.chatSync(input, signal?)` | 同步对话（测试用） |
-
-### 项目 / 会话
-
-| 方法 | 说明 |
-|------|------|
-| `agent.projects.listProjects()` / `agent.projects.list` | 列出已注册的子项目 |
-| `agent.switchProject(name)` | 切换到其他子项目 |
-| `agent.rebuildComponents()` | 通常不需要手动调用（`switchProject` 已自动执行），仅在强制刷新配置时使用 |
-| `agent.switchSession(name)` | 切换当前会话（同步，返回新会话名） |
-| `agent.forkSession(name?)` | 分叉当前会话（复制完整消息历史到新分支） |
-| `agent.loadSessionMessages(date, session)` | 加载指定日期/会话的消息 |
-| `agent.restoreSession(date, session)` | 恢复指定日期/会话 |
-| `agent.restoreMostRecentSession()` | 启动时恢复最近一次会话 |
-| `agent.agentHistory.listAllSessions()` | 列出所有会话文件名 |
-
-### Manager 速查表
-
-| 路径 | Manager | 主要成员 |
-|------|---------|---------|
-| `agent.memory.xxx()` | MemoryInspector | 读：`snapshot()` / `search(q, n)` / `searchHybrid(q, n)` / `stats()` / `list()` / `getById(id)` / `listDeleted()` / 关系查询；写：`writeUpsert()` / `writeDelete()` / `writeRestore()` / `writePurge()` / `writeAddRelation()` 等（`writeXxx` 前缀）。`suggest()` / `sourceHealth()` 已上移至 `agent.suggest()` / `agent.sourceHealth()` |
-| `agent.config.xxx()` | ConfigManager | `addRule(m)` / `addSimpleRule(n, c)` / `addSkill(m)` / `addSimpleSkill(n, c, k?)` / `onSuggestion(h)` / `confirm(s)` |
-| `agent.tools.xxx()` | ToolExecutor | `registerTool(d, h)` / `getToolDefinitions()` / `execute(n, a)` / `list` |
-| `agent.insight.xxx()` | InsightExtractor | `setWriteExtensions(e)` / `setKeywords(k)` / `classify(i)` |
-| `agent.persona.xxx` | PersonaManager | `.list` / `.activeName` / `.currentMode` / `.switchPersona(n)` / `.setMode(m)` |
-| `agent.skills.xxx` | SkillManager | `.list` / `.match(i)` / `.register(skill)` / `.buildSystemPrompt()` |
-| `agent.userProfile.xxx()` | UserProfile | `load()` / `archiveFacts(f)` / `getConfirmed()` / `getPending()` / `buildSystemPrompt()` / `confirm(id)` / `reject(id)` |
-| `agent.works.xxx()` | WorkProjectionManager | `ensureProjection(path, content)` / `getProjection(path)` / `loadAll()` |
-| `agent.on()` / `agent.off()` / `agent.once()` | TypedEventEmitter | `memoryAdded` / `personaSwitched` / `decayCompleted` / `memoryRecalled` / `sessionForked` / `insightExtracted` / `conflictDetected` / `projectSwitched` / `skillMatched` / `archiveFailed` |
-
-### Provider 管理
-
-| 方法 | 说明 |
-|------|------|
-| `agent.setProvider(provider)` | 运行时切换前台 Provider |
-| `agent.setBackgroundProvider(provider)` | 运行时切换后台 Provider |
-
----
-
-## 六、宿主工具函数
-
-```typescript
-import {
-  createLlmProvider,
-  createProviderFromConfig,
-  loadConfig,
-  InMemoryStorage,
-  InMemoryRelationStore,
-  JsonVectorStore,
-  EmbeddingProvider,
-  setLogger,
-  logger,
-  segmentText,
-  parseFrontmatter,
-  serializeFrontmatter,
-  safeSetTimeout,
-  safeSetInterval,
-  clearSafeTimeout,
-  clearSafeInterval,
-  recall,
-  extractKeywords,
-  SOURCE_LABELS,
-  RELATION_TYPES,
-  RELATION_WEIGHTS,
-  inferSource,
-  escapeLike,
-  validateSource,
-  MemoraError,
-  toError,
-  NOOP_TRACER,
-  TRACE_SPANS,
-  ToolErrorCode,
-  isRetryableErrorCode,
-  TypedEventEmitter,
-  collectAgentChunks,
-  evaluateResult,
-} from '@zooique/memora';
-import type {
-  ProviderConfig,
-  Config,
-  IMemoryStorage,
-  IMemoryRelationStore,
-  MemoryRelation,
-  RelationDirection,
-  ILogger,
-  ISessionStore,
-  SessionMessage,
-  Memory,
-  SourceValidationSeverity,
-  LlmProvider,
-  LlmChunk,
-  ChatOptions,
-  AgentChunk,
-  ThinkingPhase,
-  UIMessages,
-  ArchiveMode,
-  AgentOptions,
-  AgentContext,
-  AgentProjectEntry,
-  AgentForkResult,
-  ToolDefinition,
-  ToolHandler,
-  ToolContext,
-  WriteExtensions,
-  MemoryKeywords,
-  MemorySnapshot,
-  WorkingMemorySnapshot,
-  BootstrapSnapshot,
-  ArchiveSnapshot,
-  AgentSearchHit,
-  AgentStats,
-  SuggestOptions,
-  SuggestHit,
-  SourceHealthStatus,
-  SourceHealthEntry,
-  SourceHealthReport,
-  ConfigSuggestion,
-  ConfigSuggestionHandler,
-  AutoConfigRefinerOptions,
-  SessionArchiveResult,
-  WorkProjectionEntry,
-  UserProfileEntry,
-  ProfileCategory,
-  ExtractedFact,
-  PersonaMode,
-  Persona,
-  SkillEntry,
-  SkillMatch,
-  RecallOptions,
-  EmbeddingService,
-  EmbeddingConfig,
-  EmbeddingResult,
-  AgentEventMap,
-  AgentEventName,
-  AgentEventHandler,
-  ForkResult,
-  ITracer,
-  ISpan,
-  AgentMetrics,
-  ToolErrorCodeValue,
-  EvalScenario,
-  EvalExpectation,
-  EvalResult,
-  AuditEvent,
-  AuditListener,
-  Permission,
-  WriteDecision,
-  WriteConfirmationInfo,
-  WriteConfirmationRequest,
-  OpenAICompatibleProvider,
-  OpenAICompatibleConfig,
-} from '@zooique/memora';
-```
-
-| 函数/类型 | 用途 |
-|-----------|------|
-| `createLlmProvider(config)` | 从扁平配置创建 LlmProvider 实例 |
-| `createProviderFromConfig(name, config)` | 从命名配置创建 LlmProvider 实例 |
-| `loadConfig(path?)` | 加载 memora.json 配置文件 |
-| `InMemoryStorage` | IMemoryStorage 的纯内存实现（测试用） |
-| `InMemoryRelationStore` | IMemoryRelationStore 的纯内存实现（测试用） |
-| `JsonVectorStore` | 向量存储内置实现（实现 IVectorStore 接口，宿主注入 EmbeddingService 后创建，启用语义搜索） |
-| `EmbeddingProvider` | OpenAI 兼容 Embedding 端点实现（满足 EmbeddingService 接口） |
-| `setLogger(logger)` | 替换全局日志实现 |
-| `logger` | 全局日志实例 |
-| `segmentText(text)` | 中文分词工具 |
-| `parseFrontmatter(text)` | 解析 Markdown frontmatter |
-| `serializeFrontmatter(fm, body)` | 序列化 frontmatter + body 为 Markdown |
-| `safeSetTimeout(fn, ms)` | 安全定时器（可跟踪清理） |
-| `safeSetInterval(fn, ms)` | 安全间隔器（可跟踪清理） |
-| `clearSafeTimeout(id)` | 清除安全定时器 |
-| `clearSafeInterval(id)` | 清除安全间隔器 |
-| `recall(storage, query, options?)` | 记忆召回（async，双通道：语义 + 关键词） |
-| `extractKeywords(text)` | 提取关键词 |
-| `SOURCE_LABELS` | source 标签常量（PERSONA / RULE / SKILL / INSIGHT / PROFILE / WORK_PROJECTION / GUARDRAIL） |
-| `RELATION_TYPES` | 记忆关系类型常量（CONTRADICTS / SUPPORTS / FOLLOWS / REFINES / CAUSED / RELATED） |
-| `RELATION_WEIGHTS` | 关系强度常量（NONE / WEAK / UNDEFINED / STRONG / CERTAIN） |
-| `inferSource(content)` | 从内容推断 source 标签 |
-| `escapeLike(query)` | 转义 SQLite LIKE 通配符 |
-| `validateSource(source)` | 校验 source 标签是否为已知标签（返回 warning，不阻止写入） |
-| `MemoraError` | 统一错误类型（结构化错误码 + 上下文） |
-| `toError(err)` | 将任意值转为 Error（浏览器端安全，不引入 pino） |
-| `NOOP_TRACER` | ITracer 的空实现（静默丢弃所有 span，零开销） |
-| `TRACE_SPANS` | AgentLoop 预定义 Span 名称常量（RECALL / LLM_CALL / TOOL_EXEC / RESPONSE） |
-| `ToolErrorCode` | 工具错误码枚举（10 种，含 PATH_NOT_ALLOWED / FILE_NOT_FOUND 等） |
-| `isRetryableErrorCode(code)` | 判断错误码是否可重试（5 种 retryable） |
-| `TypedEventEmitter` | 类型安全的事件发射器（Agent 继承此类） |
-| `collectAgentChunks(gen)` | 从 AgentChunk 流收集行为数据（Mock Eval 用） |
-| `evaluateResult(name, collected, expected)` | 比对期望与结果（Mock Eval 用） |
-
-**注意**：`SqliteStorage` 已移出到宿主项目，不再从 memora 导出。宿主需自行实现 `IMemoryStorage` 接口。
-
-`IMemoryStorage` 接口要求实现 `count()` 和 `countBySource(source)` 方法，用于高效统计记忆数量（避免全量加载数据）。详见 [API 参考手册](./memora-api-reference.md)。
-
----
-
-## 七、可观测性接入（ITracer）
-
-Memora 内置了轻量的 Span/Trace 抽象，宿主可注入 OpenTelemetry 等实现来观测 AgentLoop 行为。
-
-### 接口定义
-
-```typescript
-interface ITracer {
-  startSpan(name: string, attributes?: Record<string, string | number | boolean>): ISpan;
-}
-
-interface ISpan {
-  setAttribute(key: string, value: string | number | boolean): void;
-  end(): void;
-  recordException(error: Error): void;
-}
-```
-
-### AgentLoop 预定义 Span
-
-| Span 名称 | 常量 | 触发时机 | 关键属性 |
-|-----------|------|---------|---------|
-| `recall.recall` | `TRACE_SPANS.RECALL` | 记忆召回阶段 | `recallCount` |
-| `llm.call` | `TRACE_SPANS.LLM_CALL` | LLM API 调用 | `model`, `messageCount`, `iteration` |
-| `tool.execute` | `TRACE_SPANS.TOOL_EXEC` | 工具执行 | `toolName` |
-| `response.generate` | `TRACE_SPANS.RESPONSE` | 整轮响应 | `inputLength` |
-
-### 宿主接入示例（OpenTelemetry）
-
-```typescript
-import { trace } from '@opentelemetry/api';
-import type { ITracer, ISpan } from '@zooique/memora';
-
-// 宿主实现 ITracer 接口（桥接 OpenTelemetry）
-class OtelTracer implements ITracer {
-  private tracer = trace.getTracer('memora-agent');
-
-  startSpan(name: string, attributes?: Record<string, string | number | boolean>): ISpan {
-    const otelSpan = this.tracer.startSpan(name, { attributes });
-    return {
-      setAttribute: (key, value) => otelSpan.setAttribute(key, value),
-      end: () => otelSpan.end(),
-      recordException: (error) => otelSpan.recordException(error),
-    };
-  }
-}
-
-// 注入到 Agent
-const agent = new Agent({
-  // ...其他配置
-  tracer: new OtelTracer(),
-});
-```
-
-> **不注入时**：默认使用 `NOOP_TRACER`（静默丢弃所有 span，零运行时开销）。
-
----
-
-## 八、内容护栏（Guardrails）
-
-Memora 支持基于正则的内容护栏，在对话输入和 LLM 输出阶段分别检查，防止恶意输入和敏感信息泄露。
-
-### 护栏规则格式
-
-护栏规则以 `source: "guardrail"` 记忆形式存储，放在 `configDir/rules/guardrails/` 目录下：
-
-```markdown
----
-name: 禁止执行代码
-source: guardrail
----
-
-pattern: /执行|运行|eval|exec/
-action: block
-```
-
-- `pattern`：正则表达式（可选加 `/` 定界符）
-- `action`：`block`（阻断对话）或 `warn`（仅警告）
-
-### 护栏行为
-
-| 阶段 | 命中 block | 命中 warn | 规则异常 |
-|------|-----------|----------|---------|
-| 输入 | 阻断对话，返回阻止消息 | 追加警告文本，继续对话 | 降级放行 + 记日志 |
-| 输出 | 阻断输出，返回阻止消息 | 追加警告文本，继续输出 | 降级放行 + 记日志 |
-
-> **降级优先**：护栏自身异常（如正则编译失败）永远不阻断用户对话。
-
-### 工具错误反思（Reflection）
-
-当工具执行失败时，错误结果包含 `[ERR:TOOL:code]` 前缀。如果错误码标记为 retryable（如 `FILE_NOT_FOUND`、`ARGUMENT_ERROR`），AgentLoop 会自动注入 `[REFLECTION_HINT]` 系统消息，引导 LLM 修正参数后重试。
-
-```typescript
-import { ToolErrorCode, isRetryableErrorCode } from '@zooique/memora';
-
-// 判断错误码是否可重试
-isRetryableErrorCode(ToolErrorCode.FILE_NOT_FOUND);  // true
-isRetryableErrorCode(ToolErrorCode.PATH_NOT_ALLOWED); // false
-```
-
-Reflection 默认最多重试 2 次（`maxReflectionRetries`），防止无限循环。
-
----
-
-## 九、评估体系（Eval）
-
-Memora 提供了 Mock Eval 框架，用于 Agent 行为回归测试（不发起真实 LLM 调用）。
-
-### 类型定义
-
-```typescript
-import type { EvalScenario, EvalExpectation, EvalResult } from '@zooique/memora';
-// Eval 类型已从 memora 主包导出，宿主项目可直接 import
-```
-
-### 评估场景示例
-
-```typescript
-const scenario: EvalScenario = {
-  name: '只读查询不应调用 write_file',
-  description: '用户只查询信息时，Agent 不应写入文件',
-  input: '帮我看看第一章写了什么',
-  expect: {
-    toolsCalled: ['read_file'],       // 期望调用 read_file
-    toolsNotCalled: ['write_file'],   // 不应调用 write_file
-  },
-};
-```
-
-### 评估工具函数
-
-```typescript
-import { collectAgentChunks, evaluateResult } from '@zooique/memora';
-
-// 从 AgentChunk 流中收集行为数据
-const collected = await collectAgentChunks(agent.chat('帮我看看第一章'));
-
-// 比对期望
-const result = evaluateResult(scenario.name, collected, scenario.expect);
-console.log(result.passed ? '✅ 通过' : `❌ 失败: ${result.failures.join('; ')}`);
-```
-
-### 两种评估层次
-
-| 层次 | 工具 | LLM 调用 | 用途 |
-|------|------|---------|------|
-| Mock Eval | `collectAgentChunks` + `evaluateResult` | 不调用（MSW Mock） | 行为回归（工具调用、护栏、召回） |
-| 真实 LLM Eval | 宿主自建 | 真实调用 | 回复质量、指令遵循度 |
-
-> Mock Eval 在 CI 中运行，真实 LLM Eval 由宿主项目手动触发。
-
----
-
-## 十、多步骤编排
-
-Memora 是单 Agent 模型（ADR-011），不内置多 Agent 编排。宿主项目可通过多次调用 `agent.chat()` 实现复杂工作流：
-
-```typescript
-// 示例：分析项目 → 生成大纲 → 逐章写作
-const analysis = await agent.chatSync('分析这个项目的风格和主题');
-const outline = await agent.chatSync('基于分析结果，生成章节大纲');
-for (const chapter of chapters) {
-  const content = await agent.chatSync(`根据大纲，写第${chapter.num}章：${chapter.title}`);
-  // 写入文件...
-}
-```
-
-**编排要点**：
-- 每次 `chat()` 共享同一个 AgentLoop 上下文（记忆、角色、技能）
-- 宿主负责流程控制（条件分支、并行、错误处理）
-- 如需隔离上下文，使用 `agent.switchSession()` 或 `agent.forkSession()`
-
----
-
-## 十一、关键约束
-
-1. **`provider` 是必填项** — Agent 无法独立运行
-2. **configDir** 指向 Agent 级配置目录，所有子项目共享
-3. **项目级 `.memora/`** 只放 `rules/`、`skills/` 和 `guardrails/`
-4. **角色由关键词自动触发**
-5. **对话历史跨子项目持久化**
-6. **Manager 访问器在 `init()` 前返回 `null`** — 所有 `agent.config.xxx()` / `agent.memory.xxx()` 等调用必须在 `init()` 之后
-7. **作品原始内容不进 SQLite**，Agent 通过工具按需读取
-8. **配置文件是真理源**，`agent-config/` 下的配置由 MemoryLoader 启动时扫描加载
-9. **禁止**为每个子项目创建独立的 memora.db
-10. **禁止**项目切换时关闭/重建数据库
-11. **禁止**将配置直接写入 SQLite 作为持久化存储
-12. **项目切换** `switchProject()` 已自动 rebuild，通常无需手动调用 `rebuildComponents()`
-13. **护栏规则**以 `source: "guardrail"` 记忆形式存储，不创建独立子系统
-14. **Tracer 未注入时**自动降级为 NoopTracer，零运行时开销
-
----
-
-> 更多细节参见 [memora-api-reference.md](./memora-api-reference.md)（完整 API 参考）
+> **对接入者有影响的迁移结论**（不含历史流水，细节见 [API 参考手册](./memora-api-reference.md)）：
+> - 1.0 为正式发布，API 已稳定；2.0 起设定记忆（persona/rules/skills）解耦为纯文件 + 内存缓存，唯一归角色包、不进记忆库（ADR-025），角色管理统一走 `agent.rolePack`。
+> - 已移除：`SqliteStorage`（移出内核，由宿主实现 `IMemoryStorage`）、洞察层（`insight.*`）、AutoConfigRefiner / ConfigManager、记忆关系图谱与用户画像层（偏好收敛为 round-summary，冲突改用 `supersededBy` 布尔标记）。
+>
+---
+
+## 目录
+
+- [一、核心理念](#一核心理念)
+- [二、三重数据存续路径](#二三重数据存续路径)
+- [三、最小接入步骤](#三最小接入步骤)
+- [四、会话持久化](#四会话持久化)
+- [五、API 速查](#五api-速查)
+- [六、宿主工具函数](#六宿主工具函数)
+- [七、可观测性接入（ITracer）](#七可观测性接入itracer)
+- [八、工具错误反思（Reflection）](#八工具错误反思reflection)
+- [九、多步骤编排](#九多步骤编排)
+- [十、关键约束](#十关键约束)
+- [十一、用户档案实现指南（宿主扩展）](#十一用户档案实现指南宿主扩展)
+
+---
+
+## 一、核心理念
+
+**Memora 是一个无法独立运行的智能大脑内核。** 它只有接口，没有"形态"——宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
+
+**摘要即记忆（memory-as-summary）。** Memora 的记忆只有单一轨道——**对话记忆**（round-summary 摘要，宿主持久化 + **纯关键词召回**，带 `summaryType` 语义标签）；**设定**（角色包 persona/rules/skills）是 Agent 的骨骼，.md 文件 + 内存缓存，唯一归角色包、确定性注入不经过召回，不属记忆库（ADR-025）。二者边界一刀切：记忆系统只承载对话摘要、角色包承载设定；偏好类信息沉淀为摘要记忆，不设独立"用户画像"记忆层。
+
+**单 Agent 模型。** 一个 Agent 实例的对话与记忆由**同一组存储实例**承载（`storage` / `sessionStore` 均在构造时注入、实例级），**`switchProject()` 切换项目时复用同一实例，不重建、不丢记忆**。要按工作区彼此隔离，就各自 `new Agent`——隔离粒度由宿主决定，内核不规定。
+
+**配置文件是真理源，对话记忆由宿主持久化。** 角色包（persona/rules/skills）为纯文件 + 内存缓存，设定记忆唯一归角色包、不进记忆库（ADR-025）；对话记忆（round-summary 摘要记忆，带 `summaryType` 标签）经宿主注入的 `IMemoryStorage` 持久化——**后端由宿主自选**（SQLite / JSON 文件 / 内存皆可），检索为 **纯关键词召回**（向量语义通道已随 2026-09-18 B0 收编移除，见 [API 参考手册](./memora-api-reference.md) §〇.5 构造参数表）。
+
+**内核零越界。** 核心库模块不直接调用 `console.*`（唯一日志出口为 `logging/` 单例，默认实现写 stderr）、不读 `process.stdin`、不管理 API Key、不写用户配置文件。
+
+**Manager 委托模式。** Agent 面类只做编排，领域操作委托给专职 Manager：`agent.rolePack`（角色包）/ `agent.tools`（工具）/ `agent.skills`（技能）/ `agent.memory`（记忆查询+写入）/ `agent.governance`（记忆治理）/ `agent.works`（作品投影）/ `agent.polish`（文本润色）共 7 个业务 Manager（另有 `projects` / `security` / `sessionManager` 等）。
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  宿主程序                                                   │
+│  ┌─────────────────┐    ┌──────────────────┐               │
+│  │ LLM Provider 实例 │◄───│ API Key / baseUrl │  ← 宿主职责  │
+│  └────────┬────────┘    └──────────────────┘               │
+│           │ 注入                                            │
+│           ▼                                                 │
+│  ┌──────────────────────────────────────────┐               │
+│  │  Memora 内核（Agent）                    │               │
+│  │  - chat(input) → 流式响应                │               │
+│  │  - 7 个业务 Manager getter（rolePack/tools/skills/memory/governance/works/polish，委托模式）      │               │
+│  │  ⚠️ 不包含：UI / LLM 配置 / 用户配置模板 │               │
+│  └──────────────────────────────────────────┘               │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、三重数据存续路径
+
+| 路径 | 用途 | 示例 |
+|------|------|------|
+| `AgentOptions.configDir` | 配置根目录（role-packs / skills） | 嵌入宿主程序 |
+| `AgentOptions.dataDir` | 记忆数据目录（**必填**；记忆库形态由宿主的 `storage` 实现决定） | 宿主自定 |
+| `projectPath/.memora/` | 项目级配置（rules/skills）+ 项目锁文件 `.lock` | 跟作品走 |
+
+**小说生成器推荐布局：**
+```
+小说项目/
+├── .memora/           ← 项目级配置（rules + skills）+ 内核写入的 .lock
+└── .memora-data/      ← dataDir 指向此处（记住：内核只往这里写 projects.json 注册表）
+    ├── projects.json  ← 内核写入：项目注册表
+    └── <记忆库>        ← 由宿主的 storage 决定形态与文件名
+```
+
+---
+
+## 三、最小接入步骤
+
+### 1. 安装
+
+```bash
+npm install @zooique/memora
+```
+
+### 2. 创建 Provider + Agent
+
+```typescript
+import { Agent, createProviderFromConfig, setLogger } from '@zooique/memora';
+import type { IMemoryStorage, ILogger } from '@zooique/memora';
+
+// 宿主职责：创建 LLM Provider（Agent 不关心 API Key）
+// createProviderFromConfig 是"单个 provider"入口；多 provider + active 随 loadConfig 路由见 api-reference §十 Provider 管理
+const provider = createProviderFromConfig('primary', {
+  provider: 'openaiCompatible',
+  apiKey: process.env.LLM_API_KEY!,
+  baseUrl: 'https://api.xiaomimimo.com/v1',
+  model: 'deepseek-chat',
+});
+
+// 可选：后台 Provider（投影等后台操作）
+const backgroundProvider = createProviderFromConfig('background', {
+  provider: 'openaiCompatible',
+  apiKey: process.env.LLM_API_KEY!,
+  baseUrl: 'https://api.xiaomimimo.com/v1',
+  model: 'deepseek-chat', // 可用更便宜的模型
+});
+
+// 可选：注入存储层（不传则使用 InMemoryStorage）。后端由宿主自选，二选一即可：
+const storage: IMemoryStorage = new MySqliteStorage('/path/to/memora.db'); // SQLite（同步实现天然对齐）
+// const storage: IMemoryStorage = new MyJsonStorage('/path/to/memories.json'); // JSON 文件（第一宿主 memora-vscode 的选法）
+
+// 可选：全局替换日志实现（不调用则使用内核内置 console fallback，写 stderr；宿主可注入任意 ILogger 实现）
+setLogger(myCustomLogger);
+
+// 创建 Agent
+const agent = new Agent({
+  projectPath: '/path/to/novel-project',
+  provider,              // 前台 Provider（必须）
+  backgroundProvider,    // 后台 Provider（可选）
+  configDir: '/path/to/agent-config',
+  dataDir: '/path/to/novel-project/.memora-data',  // 必填；相对路径会以进程 cwd 为基准，建议传绝对路径
+  maxContextTokens: 120000,
+  activeRolePack: '作家',
+  permission: 'owner',
+  allowedPaths: ['.'],
+  confirmWrites: false,
+  storage,               // 存储层注入（可选）
+  tracer: myOtelTracer,  // 可观测性 Tracer（可选，不传则静默丢弃所有 span）
+});
+
+await agent.init();
+```
+
+### 3. 对话
+
+```typescript
+// 流式对话（生产推荐）
+for await (const chunk of agent.chat('帮我写一段玄幻小说开头')) {
+  switch (chunk.type) {
+    case 'text':       ui.appendText(chunk.content); break;
+    case 'thinking':   ui.showThinking(chunk.phase); break;
+    case 'tool_start': ui.showToolStart(chunk.name); break;
+    case 'tool_result':ui.showToolResult(chunk.ok); break;
+    case 'aborted':    ui.showCancelled(chunk.reason); break;
+  }
+}
+
+// 同步对话（测试用）
+const reply = await agent.chatSync('你好');
+```
+
+### 3.5 事件订阅（可选）
+
+Agent 向宿主广播对话外事件（记忆变更、角色切换、会话分叉等）。
+
+```typescript
+import type { AgentEventMap } from '@zooique/memora';
+
+agent.on('memoryAdded', (e) => console.log(`新记忆: ${e.source}:${e.name}`));
+agent.on('personaSwitched', (e) => console.log(`角色: ${e.from} → ${e.to}`));
+agent.on('memoryRecalled', (e) => console.log(`想起 ${e.count} 条记忆`));
+agent.on('sessionForked', (e) => console.log(`分叉: ${e.from} → ${e.to}，${e.roundCount} 个问答闭环`));
+
+// close() 自动移除所有监听器
+```
+
+### 4. 注册领域工具
+
+> 1.0.0：工具注册走 `agent.tools.xxx()`。
+
+```typescript
+agent.tools.registerTool(
+  {
+    name: 'create_chapter',
+    description: '创建一个新章节',
+    parameters: {
+      type: 'object',
+      properties: { title: { type: 'string', description: '章节标题' } },
+      required: ['title'],
+    },
+  },
+  async (args) => {
+    const chapter = await myNovel.createChapter(args.title);
+    return `章节 "${args.title}" 已创建`;
+  },
+);
+```
+
+### 4.5 外部世界工具注入（可选，条件性暴露）
+
+> 三个「连接外部世界」的条件工具——`web_search` / `web_fetch` / `run_code`——**宿主注入对应 provider 才暴露，未注入则不进入 LLM 工具面**，内核保持零运行时依赖。各工具的用途、参数与单工具注入方式见 [API 参考手册](./memora-api-reference.md) §8；此处演示三者**一起**注入的组合写法。
+
+```typescript
+import { Agent, FetchWebFetchProvider } from '@zooique/memora';
+import type { ICodeExecutionProvider } from '@zooique/memora';
+
+// ① 网页抓取（搜索→抓取闭环：web_search 找链接，web_fetch 读正文）
+const fetchProvider = new FetchWebFetchProvider(); // 内置零依赖默认实现
+
+// ② 代码执行（沙箱完全由宿主提供——语言白名单/资源限制/网络隔离）
+const codeExecutionProvider: ICodeExecutionProvider = {
+  async execute(code, language, options) {
+    // 例：经宿主沙箱执行，返回 stdout/stderr/exitCode/timedOut
+    return { stdout: '42', stderr: '', exitCode: 0, timedOut: false };
+  },
+};
+
+const agent = new Agent({
+  projectPath: '/path/to/novel-project',
+  dataDir: '/path/to/novel-project/.memora-data',  // 必填
+  provider,
+  // webSearchProvider: new FetchWebSearchProvider(),  // 搜索（web_search，参见参考手册 §8.3）
+  fetchProvider,            // 可选：暴露 web_fetch
+  codeExecutionProvider,    // 可选：暴露 run_code
+});
+```
+
+> **注意**：`run_code` 是通用执行能力（源码不进上下文，仅结果返回），执行隔离等级完全由宿主 provider 决定；接入前务必评估沙箱安全边界（参见参考手册 §8.5）。
+
+### 5. 记忆关键词与写入扩展（已移除）
+
+> 写入扩展与记忆关键词（`agent.insight.xxx()`）已于 2026-08-14 随洞察层移除，不再提供。记忆统一以 round-summary 沉淀，经 `agent.memory.writeUpsert()` 等 `writeXxx` 方法写入。
+
+### 6. 查询记忆
+
+> 1.0.0：记忆查询走 `agent.memory.xxx()`。
+
+```typescript
+// 3 层记忆快照
+const snap = agent.memory.snapshot();
+console.log('工作记忆:', snap.working.total, '条');
+console.log('引导记忆:', snap.bootstrap.total, '条');
+
+// 关键词搜索
+const hits = agent.memory.search('世界观');
+hits.forEach(h => console.log(`${h.source}:${h.name}`));
+
+// 记忆库统计
+const stats = agent.memory.stats();
+console.log('记忆总数:', stats.total);
+```
+
+### 7. 管理角色包
+
+> 统一走 `agent.rolePack.xxx`（RolePackManager）。
+
+```typescript
+const rp = agent.rolePack;
+if (rp) {
+  // 列出所有角色包元数据
+  const metas = rp.listMeta();
+
+  // 手动切换角色包
+  rp.activate('作家');
+
+  // 查询当前状态
+  console.log(rp.activeName);    // '作家'
+  console.log(rp.getActiveTraits());
+}
+```
+
+### 8. 切换项目
+
+```typescript
+// 按路径切换（最稳）：传项目根目录的绝对路径，无需预先注册
+const ctx = await agent.switchProject('/path/to/another-novel');
+console.log(`已切换到：${ctx.projectName}`);
+
+// 按名切换：依赖项目注册表命中，须先注册
+// 注册表缺省落在 dataDir 内 —— 只有多项目共用同一 dataDir（或显式指定共同的 registryDir）时，
+// 按名切换才成立；若 dataDir 是项目级目录，注册表会随之落进各项目、只含自身条目，按名切换不成立。
+agent.projects.registerProject('/path/to/another-novel', 'another-novel');
+const ctx2 = await agent.switchProject('another-novel');
+```
+
+> 未命中注册表且传入的又不是绝对路径时，`switchProject` 直接抛错（相对路径会以进程 cwd 为基准，
+> 可能静默创建出非预期的项目目录并占用其锁）。
+
+### 9. 关闭
+
+```typescript
+await agent.close(); // 释放项目锁 + 关闭注入的存储实例
+```
+
+---
+
+## 四、会话持久化（ISessionStore）
+
+Memora 通过 `ISessionStore` 接口支持会话消息的持久化。宿主实现此接口，注入到 Agent。
+
+> **⚠ 现行契约以类型定义为准（导出类型 `ISessionStore`，以随包 `.d.ts` 为准）**：下方示例仅示意最小形态。当前接口为 **round-based 单一模式**（`appendRoundId` / `getRoundIds` / `setRoundIds` / `createSession` / `deleteSession` + 标题元数据 `getSessionMeta` / `updateSessionMeta` / `listSessionMetas`）——消息内容只存 RoundStore，`ISessionStore` 只持 Round 指针。
+> **检查点持久化已退役（2026-09-10 减法）**：`saveCheckpoint` / `loadCheckpoint` / `deleteCheckpoint` 已从接口删除；跨重启恢复链整体下线，中止/断电一律把未完成 turn 补全为完整 turn 身份并在下次会话按历史加载，运行时暂停是同 turn 内续跑（内存态）。
+
+```typescript
+import type { ISessionStore, SessionMessage } from '@zooique/memora';
+
+// 宿主实现接口
+class FileSessionStore implements ISessionStore {
+  appendMessage(date: string, session: string, message: SessionMessage): void {
+    // 写入文件或数据库
+  }
+  loadMessages(date: string, session: string): SessionMessage[] {
+    // 从文件或数据库读取
+    return [];
+  }
+  listSessions(): string[] {
+    // 返回所有会话列表
+    return [];
+  }
+}
+
+// 注入到 Agent
+const agent = new Agent({
+  // ...其他配置
+  sessionStore: new FileSessionStore('./sessions'),
+});
+```
+
+**会话持久化特性：**
+- 日期使用 `todayDate()` 动态获取，确保跨日后消息写入当天目录
+- `appendUser()` / `appendAssistant()` 自动调用 `appendMessage()`
+- `loadSessionMessages()` 自动调用 `loadMessages()`
+- `SessionMessage.role` 支持 `'user' | 'assistant' | 'system'`，宿主直接调用 `appendMessage()` 时可传入任意角色
+
+---
+
+## 四.5、会话分叉（Fork Session）
+
+Memora 支持从任意问答闭环（Round）位置创建会话分叉。分叉后，新会话只包含分叉点及之前的问答闭环，后续的问答闭环在原会话中保持不变。
+
+**使用场景**：
+- 用户在对话中决定从某个关键点分叉探索不同方向
+- 每个分支只继承到分叉点为止的上下文，避免无关历史干扰
+- 分支完全独立，互不干扰
+
+```typescript
+// 从指定 Round 位置分叉（唯一分叉方式，roundId 可选）
+const result = agent.forkSession(roundId);
+console.log(`已分叉到: ${result.newSession}，复制了 ${result.roundCount} 个问答闭环`);
+
+// 不传 roundId → 默认使用最后一个 Round（等效全量分叉）
+const fullResult = agent.forkSession();
+
+// 自定义分支名
+const result2 = agent.forkSession(roundId, 'experiment');
+```
+
+**命名规则**：
+- 自动生成：平等普通会话名（与手动创建的会话一致，无 `main-b1` 等分叉标记）
+- 自定义名称：直接传入目标名称作为第二参数
+
+**记忆处理策略**：
+- 已有记忆：全局共享（记忆是全局知识库，不属于单个会话）
+- 分叉后的 round-summary：各自独立（不同分支探索不同方向）
+
+**事件监听**：
+```typescript
+agent.on('sessionForked', (event) => {
+  console.log(`从 ${event.from} 分叉到 ${event.to}`);
+  console.log(`复制了 ${event.roundCount} 个问答闭环`);
+});
+```
+
+**边界情况**：
+- 当前会话无问答闭环时抛出错误
+- 传入的 `roundId` 不存在于当前会话时抛出错误
+- `ISessionStore` 未注入时抛出错误
+- 对话正在进行中（`chatBusy`）时抛出错误
+- 自定义名称已存在时抛出错误
+
+---
+
+## 四.6、会话归档（Archive Session）—— 宿主独立实现
+
+Memora 内核聚焦于“对话与记忆”引擎，不负责管理用户的视觉焦点和会话列表的展示层级。**会话归档（将会话从活跃列表移至历史列表）是一个纯粹的 UI/UX 行为，应由宿主项目独立实现，无需修改 Memora 内核。**
+
+### 设计理念
+
+- **内核职责**：确保对话内容（消息记录、记忆卡片）的持久化和可召回性。会话一旦创建，其内容在生命周期内始终可用。
+- **宿主职责**：管理“活跃会话”与“已归档会话”的视图分离，为用户提供整洁的交互界面。
+
+### 实现方案
+
+宿主项目应在自身的数据模型中扩展会话管理功能：
+
+#### 1. 数据库调整
+
+在宿主的会话数据表中增加一个状态字段，例如 `is_archived`（布尔值或枚举），用于区分会话的展示状态。
+
+```sql
+-- 示例：宿主数据库表结构
+ALTER TABLE sessions ADD COLUMN is_archived BOOLEAN DEFAULT 0;
+```
+
+#### 2. 前端交互实现
+
+- **归档按钮**：在会话列表项中提供“归档”操作按钮。点击时，**不调用** Memora Agent 的任何 API，而是调用宿主自身的后端接口（如 `PUT /api/sessions/{id}/archive`）。
+- **列表分离**：宿主前端应维护两个视图：
+  - **活跃列表**：查询 `is_archived = false` 的会话。
+  - **历史列表**：查询 `is_archived = true` 的会话。
+- **数据同步**：宿主的后端接口负责更新数据库中的 `is_archived` 字段，并通过 WebSocket 或轮询通知前端刷新列表。
+
+### 流程示例
+
+```typescript
+// 宿主前端代码
+async function archiveSession(sessionId: string) {
+  // 1. 调用宿主后端 API
+  const response = await fetch(`/api/sessions/${sessionId}/archive`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' }
+  });
+  
+  if (response.ok) {
+    // 2. 从活跃列表移除该会话
+    removeSessionFromList(sessionId);
+    // 3. 可选：提示用户已归档
+    showToast('会话已归档至历史记录');
+  }
+}
+
+// 宿主后端路由（伪代码）
+app.put('/api/sessions/:id/archive', (req, res) => {
+  const { id } = req.params;
+  // 4. 更新数据库状态
+  db.updateSessionStatus(id, { is_archived: true });
+  res.json({ success: true });
+});
+```
+
+### 核心优势
+
+- **解耦**：Memora 内核无需感知“归档”这一视图行为，保持纯粹的业务逻辑。
+- **灵活**：宿主可自由扩展“归档”的变体，如“收藏夹”、“置顶”、“多级分类”等，均可在宿主侧独立完成。
+- **稳定**：内核代码零风险，记忆召回逻辑完全不受归档行为影响，确保所有对话内容（无论归档与否）都能被准确回忆。
+
+---
+
+## 五、API 速查
+
+> 构造选项、生命周期、对话、项目/会话、各 Manager、事件、Provider 管理等**完整条目与类型定义**详见 [memora-api-reference.md](./memora-api-reference.md)。此处只列接入期最常用的几个入口：
+
+| 操作 | 入口 | 详见参考手册 |
+|------|------|------|
+| 构造 | `new Agent({ projectPath, provider, configDir, dataDir })` | §二 · AgentOptions |
+| 对话 | `agent.chat(input)`（流式）/ `agent.chatSync(input)` | §三 |
+| 记忆 | `agent.memory.snapshot()/search()/writeXxx()` | §四 |
+| 角色包 | `agent.rolePack.listMeta()/activate()` | §七 |
+| 工具 | `agent.tools.registerTool()/execute()` | §八 |
+| 会话 | `agent.forkSession()` / `agent.sessionManager.*` | §六 |
+
+> 记忆治理（去重/冲突）统一走 `agent.governance` 或 Agent 层方法，见参考手册 §四 与「记忆治理」章节。
+
+---
+
+## 六、宿主工具函数
+
+> 所有可导入工具函数/类型的**完整 import 清单与导出声明**见 [memora-api-reference.md](./memora-api-reference.md) §十六。下表列出常用函数与其用途：
+
+| 函数/类型 | 用途 |
+|-----------|------|
+| `createLlmProvider(config)` | 从完整 Config（`llm.providers` + `active`）创建激活 Provider（配合 `loadConfig`） |
+| `createProviderFromConfig(name, config)` | 从命名配置创建单个 Provider 实例（扁平参数） |
+| `loadConfig(path?)` | 加载 `.memora/config.json` 项目级配置文件（或传入显式 configPath） |
+| `InMemoryStorage` | IMemoryStorage 的纯内存实现（测试用） |
+| `setLogger(logger)` | 替换全局日志实现 |
+| `logger` | 全局日志实例 |
+| `segmentText(text)` | 中文分词工具 |
+| `parseFrontmatter(text)` | 解析 Markdown frontmatter |
+| `serializeFrontmatter(fm, body)` | 序列化 frontmatter + body 为 Markdown |
+| `safeSetTimeout(fn, ms)` | 安全定时器（可跟踪清理） |
+| `safeSetInterval(fn, ms)` | 安全间隔器（可跟踪清理） |
+| `clearSafeTimeout(id)` | 清除安全定时器 |
+| `clearSafeInterval(id)` | 清除安全间隔器 |
+| `extractKeywords(text)` | 提取关键词 |
+| `SOURCE_LABELS` | source 标签常量（PERSONA / RULE / SKILL / WORK_PROJECTION / ROUND_SUMMARY / UNKNOWN） |
+| `escapeLike(query)` | 转义 SQLite LIKE 通配符（`%` / `_` → `\%` / `\_`）。**SQL 必须写成 `LIKE ? ESCAPE '\'`**——不写 ESCAPE 子句则反斜杠被视为普通字符，转义后的模式匹配不到任何字面值，查询**静默返回空** |
+| `escapeLikeSnippet(text, maxLen?)` | 截断至 maxLen（默认 50）后转义 LIKE 通配符——搜索输入防超长解析 + 防通配符被当模式符（SQL 后端检索的配套动作，同样须配 `ESCAPE '\'`） |
+| `validateSource(source)` | 校验 source 标签是否为已知标签（返回 warning，不阻止写入） |
+| `MemoraError` | 统一错误类型（结构化错误码 + 上下文） |
+| `toError(err)` | 将任意值转为 Error（浏览器端安全，不引入 `logging/` 模块） |
+| `NOOP_TRACER` | ITracer 的空实现（静默丢弃所有 span，零开销） |
+| `TRACE_SPANS` | AgentLoop 预定义 Span 名称常量（RECALL / LLM_CALL / TOOL_EXEC / RESPONSE） |
+| `ToolErrorCode` | 工具错误码枚举（10 种，含 PATH_NOT_ALLOWED / FILE_NOT_FOUND 等） |
+| `isRetryableErrorCode(code)` | 判断错误码是否可重试（5 种 retryable） |
+| `TypedEventEmitter` | 类型安全的事件发射器（Agent 继承此类） |
+
+**注意**：`SqliteStorage` 已移出到宿主项目，不再从 memora 导出。宿主需自行实现 `IMemoryStorage` 接口。
+
+`IMemoryStorage` 接口要求实现 `count()` 和 `countBySource(source)` 方法，用于高效统计记忆数量（避免全量加载数据）。详见 [API 参考手册](./memora-api-reference.md)。
+
+---
+
+## 七、可观测性接入（ITracer）
+
+Memora 内置了轻量的 Span/Trace 抽象，宿主可注入 OpenTelemetry 等实现来观测 AgentLoop 行为。
+
+### 接口定义
+
+```typescript
+interface ITracer {
+  startSpan(name: string, attributes?: Record<string, string | number | boolean>): ISpan;
+}
+
+interface ISpan {
+  setAttribute(key: string, value: string | number | boolean): void;
+  end(): void;
+  recordException(error: Error): void;
+}
+```
+
+### AgentLoop 预定义 Span
+
+| Span 名称 | 常量 | 触发时机 | 关键属性 |
+|-----------|------|---------|---------|
+| `llm.call` | `TRACE_SPANS.LLM_CALL` | LLM API 调用（含重试循环） | `model`, `messageCount`, `iteration`，另写 `inputTokens` |
+| `tool.execute` | `TRACE_SPANS.TOOL_EXEC` | 工具执行（并发时多个 span 时间重叠） | `toolName`，另写 `args`（被拒时 `denied`） |
+| `response.generate` | `TRACE_SPANS.RESPONSE` | 整轮响应 | `inputLength`（任务级指标随流结束统一补写） |
+| `context.summary` | `TRACE_SPANS.CONTEXT_SUMMARY` | 消息超 `maxContextTokens` 触发截断、生成"遗忘补偿"摘要 | `messageCount`, `summarizingMessages` |
+| `archive.postProcess` | `TRACE_SPANS.POST_PROCESS` | 每轮 `chat()` 后归档（round-summary、角色/技能匹配） | `archiveMode` |
+| `round.difficulty` | `TRACE_SPANS.DIFFICULTY` | **预留名，内核当前零 emit 点** | — |
+| `round.report` | `TRACE_SPANS.REPORT` | **预留名，内核当前零 emit 点** | — |
+
+> 共 **7** 个常量。`TRACE_SPANS.RECALL` / `TRACE_SPANS.RECALL_ACTUAL`（`recall.recall` / `recall.actual`）已于 **2026-09-11 物理删除**（自动记忆召回退役后无 emit 点）——宿主无需为其编写 span 处理逻辑；记忆检索耗时看 `tool.execute`（`search_memories` 工具）。
+
+### 宿主接入示例（OpenTelemetry）
+
+```typescript
+import { trace } from '@opentelemetry/api';
+import type { ITracer, ISpan } from '@zooique/memora';
+
+// 宿主实现 ITracer 接口（桥接 OpenTelemetry）
+class OtelTracer implements ITracer {
+  private tracer = trace.getTracer('memora-agent');
+
+  startSpan(name: string, attributes?: Record<string, string | number | boolean>): ISpan {
+    const otelSpan = this.tracer.startSpan(name, { attributes });
+    return {
+      setAttribute: (key, value) => otelSpan.setAttribute(key, value),
+      end: () => otelSpan.end(),
+      recordException: (error) => otelSpan.recordException(error),
+    };
+  }
+}
+
+// 注入到 Agent
+const agent = new Agent({
+  // ...其他配置
+  tracer: new OtelTracer(),
+});
+```
+
+> **不注入时**：默认使用 `NOOP_TRACER`（静默丢弃所有 span，零运行时开销）。
+
+---
+
+## 八、工具错误反思（Reflection）
+
+> 注：原「内容护栏（Guardrails）」章节已移除——guardrail 是「零规则、无扫描映射、无消费者」的空转链，已随内核摘除（2026-08-17，见 memory-role-pack-boundary.md §4.4）。
+
+当工具执行失败时，错误结果包含 `[ERR:TOOL:code]` 前缀。如果错误码标记为 retryable（如 `FILE_NOT_FOUND`、`ARGUMENT_ERROR`），AgentLoop 会自动注入 `[REFLECTION_HINT]` 系统消息，引导 LLM 修正参数后重试。
+
+```typescript
+import { ToolErrorCode, isRetryableErrorCode } from '@zooique/memora';
+
+// 判断错误码是否可重试
+isRetryableErrorCode(ToolErrorCode.FILE_NOT_FOUND);  // true
+isRetryableErrorCode(ToolErrorCode.PATH_NOT_ALLOWED); // false
+```
+
+Reflection 默认最多重试 2 次（`maxReflectionRetries`），防止无限循环。
+
+---
+
+## 九、多步骤编排
+
+Memora 是单 Agent 模型（ADR-011），不内置多 Agent 编排。宿主项目可通过多次调用 `agent.chat()` 实现复杂工作流：
+
+```typescript
+// 示例：分析项目 → 生成大纲 → 逐章写作
+const analysis = await agent.chatSync('分析这个项目的风格和主题');
+const outline = await agent.chatSync('基于分析结果，生成章节大纲');
+for (const chapter of chapters) {
+  const content = await agent.chatSync(`根据大纲，写第${chapter.num}章：${chapter.title}`);
+  // 写入文件...
+}
+```
+
+**编排要点**：
+- 每次 `chat()` 共享同一个 AgentLoop 上下文（记忆、角色、技能）
+- 宿主负责流程控制（条件分支、并行、错误处理）
+- 如需隔离上下文，使用 `agent.sessionManager.switchSession()` 或 `agent.forkSession()`
+
+---
+
+## 十、关键约束
+
+**前提：存储方案由宿主自选，内核只定契约。** 内核只定义 `IMemoryStorage` / `ISessionStore` 接口，**不规定后端**——SQLite（better-sqlite3）、JSON 文件、内存实现一视同仁，任何后端都不得被写进内核逻辑。接口方法为**同步语义**（对齐 better-sqlite3），异步后端需另行扩展接口；JSON 落地实现在同步路径上做全量重写，记忆量增长时由宿主自行评估更优后端（阈值与权衡见 `storageInterface.ts` 头注释）。第一宿主 memora-vscode 当前用 JSON 文件，换成 SQLite **不需要改内核**。
+
+1. **`provider` 是必填项** — Agent 无法独立运行
+2. **configDir** 指向 Agent 级配置目录，所有项目共享
+3. **项目级 `.memora/`** 放项目级配置（`rules/`、`skills/`）与内核写入的项目锁 `.lock`；`dataDir` 若指向此处（第一宿主 memora-vscode 即如此），记忆库与会话也落在这里
+4. **角色包只能手动切换**（`agent.switchRolePack(name)` / `agent.rolePack.activate(name)`）——无输入自动匹配、无粘性锁存、无互斥触发；已激活的角色包在当前会话内保持固定（v0.13 已移除自动匹配全链）
+5. **对话历史随 Agent 持久化** — `sessionStore` 是实例级注入的，`switchProject()` 不换存储；未注入则仅内存保存
+6. **Manager 访问器在 `init()` 前返回 `null`** — 所有 `agent.rolePack.xxx()` / `agent.memory.xxx()` 等调用必须在 `init()` 之后
+7. **作品原始内容不进记忆库**，Agent 通过工具按需读取（大文本走 `read_file` 分段，提炼后只留情报，不全量入库 / 入上下文）
+8. **配置文件是真理源**，`<configDir>/role-packs/` 下的角色包由 RolePackManager 启动时扫描加载
+9. **一个 Agent = 一份记忆库** — `storage` 与 `dataDir` 都是 **Agent 实例级**的：`switchProject()` 复用同一实例，不按项目 / 子项目分裂。**要按工作区彼此隔离，就各自 `new Agent`**——隔离粒度归宿主决定，内核不规定
+10. **项目切换不重建、不关闭存储** — `switchProject()` 复用已注入的实例，只在 `close()` 时关闭（`ProjectManager` 在 Agent 生命周期内缓存）
+11. **禁止把配置放进记忆库** — 配置（角色包 / persona / rules / skills）的真理源是文件（`configDir` / 角色包），设定记忆归角色包内容层、不进记忆库（ADR-025 / `memory-role-pack-boundary`）
+12. **项目切换** `switchProject()` 已自动 rebuild，通常无需手动调用 `rebuildComponents()`
+13. **Tracer 未注入时**自动降级为 NoopTracer，零运行时开销
+
+---
+
+## 十.5、执行前检查决策（preExecutionCheck）⚠️ 安全基线
+
+`preExecutionCheck` 是工具执行前的统一闸门（内核 `ToolExecutor` 单点聚合检查：只读 → 审批 → 执行三态）。宿主经 `AgentOptions.preExecutionCheck` 注入，返回 `allow` / `skip` / `confirm` 三态。
+
+### 单用户桌面场景（可恒放行）
+
+本地运行的单用户宿主（VS Code 插件 / 桌面应用）可注入恒放行：
+
+```ts
+preExecutionCheck: () => ({ skip: false }),  // 放行，等价于 allow
+```
+
+**理由**（宿主装配注入点见仓库内参考实现 `hosts/memora-vscode/src/extension/host/assemble.ts`，**非随包产物**）：
+1. 宿主运行在用户本地，天然信任模型；
+2. 工具审计已由 `tool_start` / `tool_result` chunk + `tool.execute` span 承担，不重复记录。
+
+### 多用户 / 服务端部署（必须替换）⚠️
+
+**恒放行仅限单用户本地场景。** 一旦接入多用户或服务端部署，必须替换为真实审批策略，否则任意用户可经工具读写任意文件 / 执行任意命令。最小实现要点：
+
+- **审批在宿主侧实现**：内核 3.0.0 已删内核审批键（`toolApproval`，理由见下 §十.7 补记），多用户场景须由宿主在 `preExecutionCheck` 实现真实审批（返回 `denied` 拒绝），高危操作（写文件 / 执行命令）默认拒绝而非放行；
+- **路径守卫**：结合内核 `SecurityGuard` 的 `allowedPaths` 白名单 + 28 类禁止规则做硬性拦截，返回 `skip` 阻断越权调用；
+- **只读策略**：角色包 `toolReadonly: 'readonly'` 时，preExecutionCheck 须拒绝一切写操作。
+
+> 本决策同时受 `tasks/待完成任务.md` 设计纪律 **D5** 约束：恒放行属单用户场景可接受，但必须显式标注，未来多用户/服务端再接入真实策略。
+
+---
+
+## 十.6、存储单例约束（sessionStore / roundStore）⚠️ 契约基线
+
+`sessionStore`（会话元数据）与 `roundStore`（问答闭环 / round 落盘）**必须全局唯一单例，且 UI 面板与 Agent 装配共享同一实例**。
+
+### 为什么是硬约束（双实例覆盖写）
+
+会话与 round 落盘的最终载体是同一份磁盘文件（`*.memora/sessions.json` + 各 round 文件）。若 UI 面板与 Agent 各自 `new` 一份 store：
+
+- 两侧各自 `load()` 后内存状态分叉；
+- 任一侧 `save()` 都只写自己内存视角，**后写覆盖先写** → 另一侧已追加的会话 / 消息丢失；
+- 典型症状：重启后"会话记录加载不全"、跨面板操作互相吞掉对方写入。
+
+这是数据正确性 bug，**不是性能或风格问题**，任何宿主对接都会踩。
+
+### 规范模式（VS Code 宿主实证）
+
+在 `activate()` 中创建一次，注入两侧（见仓库内参考实现 `hosts/memora-vscode/src/extension/extension.ts`，**非随包产物**：`activate()` 内 `new WorkspaceRoundStore(...)` 与 `new WorkspaceSessionStore(workspacePath, roundStore)` 各建一次；面板侧经 `new MemoraChatViewProvider(..., sessionStore, ...)` 与 `settingsProvider.setAgentFactory(...)`，Agent 侧经 `getOrCreateAgent(..., sessionStore, roundStore, ...)` → `assembleAgent(...)`）：
+
+```ts
+// 单例：activate 中创建一次
+const sessionStore = new WorkspaceSessionStore(workspacePath, roundStore);
+sessionStore.load();
+
+// 注入 UI 面板：面板经 setAgentFactory 复用同一 agentPromise → 同一份 store
+chatProvider.setAgentFactory((projectPath) =>
+  getOrCreateAgent(projectPath, providerStore, sessionStore, roundStore, /* ... */));
+
+// 注入 Agent 装配：assembleAgent 透传同一 sessionStore / roundStore 进内核
+```
+
+`sessionStore` 经 `getOrCreateAgent` → `assembleAgent` 透传进内核；UI 面板经 `chatProvider.setAgentFactory` 复用同一 `agentPromise`，从而共用同一份 store。**两侧的 store 引用必须指向同一对象**，禁止各建各的。
+
+### 单例 / 原子写各防什么（边界辨析）
+
+- **单例**防**同进程内**两个代码路径各 `new` 一份 store → 内存分叉 → 互相覆盖写。VS Code 单宿主下，单例已彻底封死这条路。
+- **原子写**（`atomicWriteFileSync`：先写 `.tmp` 再 `renameSync`）防**写一半进程崩了**导致文件损坏——落盘要么旧内容、要么完整新内容，不会半截。memora 已实现，且**内核与宿主各有一份**：内核 `src/utils/atomicWrite.ts` 的 `atomicWriteFile`（异步，当前生产消费者为 `WorkProjectionManager`）；宿主 `hosts/memora-vscode/src/extension/host/atomicWriteSync.ts` 的 `atomicWriteFileSync`（同步，供 `WorkspaceSessionStore` / `WorkspaceRoundStore` / `WorkspaceStorage` 等宿主存储消费，**非随包产物**）。
+- **两者都不防"跨进程双开"**：同工作区开两个窗口 / 两个宿主进程 = 两个 `sessionStore` 单例 = 两个进程各原子写同一 `*.memora/sessions.json`。原子写保"不损坏"但不保"不丢更新"（后 rename 覆盖先 rename）。此场景须靠**进程锁 / 单实例守卫**兜底（参考 grida 对 `sessions.db` 加进程锁、重复启动直接拒绝）。
+
+### 新宿主接入检查清单
+
+- [ ] `sessionStore` / `roundStore` 在宿主生命周期内只 `new` 一次；
+- [ ] UI 面板（对话视图 / 会话树 / 设置）与 Agent 装配引用**同一个** store 实例；
+- [ ] 落盘走**原子写**（`tmp` + `rename`），禁止裸 `writeFile` 覆盖（防崩溃损坏）；
+- [ ] **跨进程 / 多窗口宿主须加文件锁或单实例守卫**：单例只防同进程双实例，不防同工作区双开各自写同一 `sessions.json`；原子写保证不损坏但不保证不丢更新，须进程锁兜底；
+- [ ] 测试覆盖：模拟"面板先写、Agent 后写"或反之，断言最终落盘含两侧写入（防回归双实例覆盖写）。
+
+> 本约束原仅存于宿主实现注释（`extension.ts` 的"杜绝双实例覆盖写"；仓库内参考实现，**非随包产物**），现提升为宿主接入契约基线，避免新宿主对接踩坑。原子写实锤已具备（`atomicWriteFileSync`），单例 + 原子写已对齐主流硬化做法（grida / Chatbox 同款 tmp+rename）；唯一真实残留为跨进程锁，已列入检查清单第 4 项。
+
+## 十.7、策略键消费矩阵（16 键 SSOT 落点）📌 参考
+
+> 逐键矩阵（16 键 × 内核消费位置 × UI 侧消费）为仓库内开发文档（SSOT：`src/role-pack/strategyKeys.ts`），**不随包发布**；宿主对接所需的键语义见 [role-pack-authoring-guide.md](./architecture/role-pack-authoring-guide.md) §三。此处只给新宿主对接必知的结论与边界。
+
+- **16 键全部被内核真实消费、零 `[草案]`**（prepare 1 / act 7 / reflect 3 / global 5）。解析层 `rolePackManager` + `strategyResolver` 84 项测试守护，消费层跨 `contextPreparer` / `loop` / `agent` / `managers/llmCaller` / `toolRunner` / `orchestrator` / `prepare` 多文件覆盖。
+- **三类流向，单一收口无镜像**：
+  1. act 5 键（`toolMode`/`toolStepLimit`/`providerRouting`/`multiStepReasoning`/`toolReadonly`）+ `selfReview` + global 4 键（`errorHandling`/`contextLimit`/`stepBudget`/`askLimit`），统一经 `resolveL2Strategy()` 聚合注入 `L2RuntimeStrategy`，loop 经 `this.strategy.<field>` 读取；`act.temperature`/`outputLimit` 由 `agent.ts` 直映射 `ChatOptions`（不经聚合）；
+  2. prepare 键经 `resolveActiveStrategy()` 单一真理源流入 `contextPreparer` / `roundSummaryGenerator`；
+  3. persona 指令类（`userFollowup`/`askOn`/`askLimit`）由 `assembleRolePack()` 单收口注入。
+- **⚠️ 边界纠正：`toolReadonly` 内核已执行，非「无宿主执行方」**。`toolRunner.ts` 只剩两层闸：闸①（只读闸 `toolReadonly==='readonly'`）**由内核执行**；闸③（宿主 `preExecutionCheck` 注入点）当前 VS Code 宿主恒放行（`assemble.ts` 恒返回 `() => ({ skip: false })`）只是单用户信任模型下的显式让行（关联 十.5 / 设计纪律 D5），未来多用户/服务端须替换真实审批。原闸② `toolApproval` 审批链已随 3.0.0 删键（2026-09-11，故代码注释 ①/③ 编号保留）：单用户本地无真实审批场景，原"通知宿主 + UI 需审批 chip"是展示性假承诺——整键删除，新宿主切勿再期待 `onToolApproval` 回调或 `toolApproval==='confirm'` 语义，审批须自行在 `preExecutionCheck` 实现。
+- **UI 侧 6 键有呈现**：宿主角色列表视图渲染策略 chip 5 键（`toolReadonly` / `summaryFocus` / `outputLimit` / `temperature` / `multiStepReasoning`）+ `toolMode` 经对话视图 capability badge 渲染（'纯 LLM' / '全部工具'）。能力名映射与策略键无关，**勿混淆**。（上述 UI 实现均为仓库内宿主参考实现，**非随包产物**。）
+
+---
+
+## 十一、用户档案实现指南（宿主扩展）
+
+> **为什么内核没有独立的用户档案模块？**
+
+### 设计哲学：偏好涌现 vs 配置驱动
+
+Memora 的记忆系统通过 `round-summary` 的 `type=preference` 类型承载"偏好涌现"的核心需求。用户在对话中的偏好（如"喜欢简洁回答"、"偏好中文沟通"）会自然沉淀为摘要记忆，并在后续对话中随召回注入上下文。
+
+这种"涌现驱动"的设计与传统"配置驱动"的用户档案方案有本质区别：
+
+| 维度 | WorkBuddy 类方案（配置驱动） | Memora 方案（涌现驱动） |
+|------|---------------------------|----------------------|
+| 更新方式 | 手动编辑档案文档 | 对话自然沉淀 |
+| 结构化程度 | 强（schema 约束） | 弱（LLM 理解） |
+| 内核侵入性 | 高（需新模块） | 低（复用现有机制） |
+
+**Memora 选择"涌现驱动"的核心理由**：
+1. **单一真理源**：偏好从对话中涌现，而非外部注入，避免双写冲突
+2. **自然生长**：不预埋用户画像结构，符合"种子决定长势、土壤决定养分"哲学
+3. **零新增模块**：复用现有记忆/召回机制
+
+### 宿主实现方案
+
+如果宿主确实需要"预配置用户身份"的场景（如"我叫张三、后端工程师、偏好 Go 语言"），可以通过以下两种方式扩展，**内核零改动**。
+
+#### 方案一：工具注册（LLM 按需查询）
+
+适合场景：用户身份信息在对话中被 LLM 按需查询。
+
+```typescript
+// 宿主实现用户档案读取逻辑
+async function loadUserProfile(): Promise<Record<string, unknown>> {
+  // 从文件、数据库或环境变量读取
+  return {
+    name: '张三',
+    role: '后端工程师',
+    preferredLanguage: 'zh-CN',
+    codingLanguage: 'Go',
+    // ...其他用户信息
+  };
+}
+
+// 注册为工具，LLM 需要时主动调用
+agent.tools.registerTool(
+  {
+    name: 'read_user_profile',
+    description: '读取当前用户的档案信息（姓名、角色、偏好等）',
+    parameters: {
+      type: 'object',
+      properties: {}, // 无参数
+    },
+  },
+  async () => {
+    const profile = await loadUserProfile();
+    return `用户档案：姓名=${profile.name}，角色=${profile.role}，偏好语言=${profile.preferredLanguage}`;
+  },
+);
+```
+
+#### 方案二：复用 `agent.injectAffect()` 固定注入（设计定案）
+
+适合场景：用户身份 / 基础设定需要**始终在上下文中**，且与角色包解耦（切换角色不丢失）。
+
+内核公开 API `agent.injectAffect(text)`（见 [API 参考手册](./memora-api-reference.md) §十二 完整 API 一览·角色条目）是「宿主可控的 system prompt 固定文本槽」：文本原样插在**角色包 prompt 与 bootstrap 记忆之间**，角色切换不清除、实时重建，传空串清除。名字虽沿用"情感基调"，机制即通用文本注入，正适合承载用户基础设定。
+
+```typescript
+// 宿主启动装配、agent.init() 完成后调用一次（内存态——每次启动从宿主自有存储读取后注入）
+async function loadUserProfile(): Promise<{
+  name: string;
+  role?: string;
+  background?: string;
+  preferences?: string[];
+} | null> {
+  // 宿主实现：文件 / SQLite / 环境变量均可
+}
+
+const profile = await loadUserProfile();
+if (profile) {
+  agent.injectAffect(
+    [
+      '【用户基础设定】',
+      `姓名：${profile.name}`,
+      `角色：${profile.role ?? '未指定'}`,
+      `背景：${profile.background ?? '未指定'}`,
+      `偏好：${profile.preferences?.join('、') ?? '无'}`,
+    ].join('\n'),
+  );
+}
+// 需要清除时：agent.injectAffect('');
+```
+
+### 两种方案对比
+
+| 维度 | 方案一：工具注册 | 方案二：injectAffect 固定注入 |
+|------|---------------|-------------------|
+| 触发方式 | LLM 按需调用 | 装配时注入一次，始终在上下文 |
+| Token 效率 | 高（仅需要时消耗） | 低-中（每轮随 system prompt 携带） |
+| 实现复杂度 | 低 | 低 |
+| 适用场景 | 身份信息偶尔被查询 | 身份信息必须始终可见、且与角色解耦 |
+
+### 用户档案文件格式示例
+
+宿主可以使用任意格式存储用户档案，推荐 JSON 或 Markdown：
+
+**`user-profile.json`**
+```json
+{
+  "name": "张三",
+  "role": "后端工程师",
+  "background": "5 年 Go 开发经验，熟悉微服务架构",
+  "preferences": ["简洁回答", "中文沟通", "代码优先"]
+}
+```
+
+**`user-profile.md`**
+```markdown
+# 用户档案
+
+- **姓名**：张三
+- **角色**：后端工程师
+- **背景**：5 年 Go 开发经验，熟悉微服务架构
+- **偏好**：简洁回答、中文沟通、代码优先
+```
+
+### 核心约束
+
+1. **用户档案完全由宿主管理**：存储、更新、版本管理
+2. **内核零新增**：不新增存储、不新增 API——方案二复用现有公开方法 `agent.injectAffect()`，仅以文本形式注入，内核不感知"档案"语义
+3. **不注入时零影响**：未实现用户档案的宿主，Agent 行为不变
+4. **偏好记忆仍走涌现路径**：对话中涌现的偏好（如"用户喜欢简洁回答"）仍通过 `preference` 摘要沉淀，用户档案仅承载**静态/半静态身份信息**
+
+---
+
+> 更多细节参见 [memora-api-reference.md](./memora-api-reference.md)（完整 API 参考）