@zooique/memora 4.0.0 → 5.1.0

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

@@ -1,12 +1,14 @@
-# Memora · 接入指南 v4.0.0
+# Memora · 接入指南 v5.1.0
 
 > 帮助宿主项目开发者快速理解 Memora 的设计理念和接入方法。
 >
-> **当前稳定版**：v4.0.0。各版完整变更见 [CHANGELOG](../CHANGELOG.md)。
+> **当前内核版本**：v5.1.0（对齐当前内核包版本 `package.json`）。各版完整变更见 [CHANGELOG](../CHANGELOG.md)。
+>
+> **最新已发布版本**：以 npm registry 为准（`npm view @zooique/memora dist-tags.latest`），不在包内复述。
 >
 > **对接入者有影响的迁移结论**（不含历史流水，细节见 [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` 布尔标记）。
+> - 已移除：`SqliteStorage`（**原 better-sqlite3 实现**移出内核，由宿主实现 `IMemoryStorage`——注意这是 native 实现出内核，**不等于**内核不再提供任何 SQLite 实现；5.0.0 起内核另有基于 `node:*` 内建模块的 `createNodeSqliteStorage`）、洞察层（`insight.*`）、AutoConfigRefiner / ConfigManager、记忆关系图谱与用户画像层（偏好收敛为 round-summary，冲突改用 `supersededBy` 布尔标记）。
 >
 ---
 
@@ -32,13 +34,13 @@
 
 **摘要即记忆（memory-as-summary）。** Memora 的记忆只有单一轨道——**对话记忆**（round-summary 摘要，宿主持久化 + **纯关键词召回**，带 `summaryType` 语义标签）；**设定**（角色包 persona/rules/skills）是 Agent 的骨骼，.md 文件 + 内存缓存，唯一归角色包、确定性注入不经过召回，不属记忆库（ADR-025）。二者边界一刀切：记忆系统只承载对话摘要、角色包承载设定；偏好类信息沉淀为摘要记忆，不设独立"用户画像"记忆层。
 
-**单 Agent 模型。** 一个 Agent 实例的对话与记忆由**同一组存储实例**承载（`storage` / `sessionStore` 均在构造时注入、实例级），**`switchProject()` 切换项目时复用同一实例，不重建、不丢记忆**。要按工作区彼此隔离，就各自 `new Agent`——隔离粒度由宿主决定，内核不规定。
+**单 Agent 模型（一个项目一个 Agent）。** 一个 Agent 实例的对话与记忆由**同一组存储实例**承载（`storage` / `sessionStore` 均在构造时注入、实例级），**切会话不换存储、不丢记忆**。要按项目彼此隔离，就各自 `new Agent`——**隔离粒度由宿主决定，内核不规定**（形态与取舍见 [§8](#8-多项目一个项目一个-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` 等）。
+**Manager 委托模式。** Agent 面类只做编排，领域操作委托给专职 Manager：`agent.rolePack`（角色包）/ `agent.tools`（工具）/ `agent.skills`（技能）/ `agent.memory`（记忆查询+写入）/ `agent.works`（作品投影）/ `agent.polish`（文本润色）共 6 个业务 Manager（另有 `projects` / `security` / `sessionManager` 等）。
 
 ```
 ┌────────────────────────────────────────────────────────────┐
@@ -51,7 +53,7 @@
 │  ┌──────────────────────────────────────────┐               │
 │  │  Memora 内核（Agent）                    │               │
 │  │  - chat(input) → 流式响应                │               │
-│  │  - 7 个业务 Manager getter（rolePack/tools/skills/memory/governance/works/polish，委托模式）      │               │
+│  │  - 6 个业务 Manager getter（rolePack/tools/skills/memory/works/polish，委托模式）            │               │
 │  │  ⚠️ 不包含：UI / LLM 配置 / 用户配置模板 │               │
 │  └──────────────────────────────────────────┘               │
 └────────────────────────────────────────────────────────────┘
@@ -71,11 +73,13 @@
 ```
 小说项目/
 ├── .memora/           ← 项目级配置（rules + skills）+ 内核写入的 .lock
-└── .memora-data/      ← dataDir 指向此处（记住：内核只往这里写 projects.json 注册表）
-    ├── projects.json  ← 内核写入：项目注册表
+└── .memora-data/      ← dataDir 指向此处（Agent 级资源目录；宿主注入 storage 时内核不在此落文件）
     └── <记忆库>        ← 由宿主的 storage 决定形态与文件名
 ```
 
+> **多项目怎么办**：一个 Agent 绑定一个项目，不做项目切换；多项目请为每个项目各创建一个
+> Agent 实例。完整形态、取舍与代码示例见 [§8 多项目：一个项目一个 Agent](#8-多项目一个项目一个-agent形态定案)。
+
 ---
 
 ## 三、最小接入步骤
@@ -109,7 +113,8 @@ const backgroundProvider = createProviderFromConfig('background', {
   model: 'deepseek-chat', // 可用更便宜的模型
 });
 
-// 可选：注入存储层（不传则使用 InMemoryStorage）。后端由宿主自选，二选一即可：
+// 可选：注入存储层（不传则用内核内置内存实现，仅内存不落盘；该类不挂公共面——PUB-API-PRUNE-2 收面）。
+//         后端由宿主自选，二选一即可：
 const storage: IMemoryStorage = new MySqliteStorage('/path/to/memora.db'); // SQLite（同步实现天然对齐）
 // const storage: IMemoryStorage = new MyJsonStorage('/path/to/memories.json'); // JSON 文件（第一宿主 memora-vscode 的选法）
 
@@ -123,7 +128,7 @@ const agent = new Agent({
   backgroundProvider,    // 后台 Provider（可选）
   configDir: '/path/to/agent-config',
   dataDir: '/path/to/novel-project/.memora-data',  // 必填；相对路径会以进程 cwd 为基准，建议传绝对路径
-  maxContextTokens: 120000,
+  maxContextTokens: 120000, // 示例值——缺省时以内核 AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS 为真源，数字以该常量为准
   activeRolePack: '作家',
   permission: 'owner',
   allowedPaths: ['.'],
@@ -161,7 +166,7 @@ Agent 向宿主广播对话外事件（记忆变更、角色切换、会话分
 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('rolePackSwitched', (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} 个问答闭环`));
 
@@ -263,22 +268,50 @@ if (rp) {
 }
 ```
 
-### 8. 切换项目
+### 8. 多项目：一个项目一个 Agent（形态定案）
+
+**一个 Agent 绑定一个项目**，内核不做项目切换。多项目请为**每个项目各创建一个 Agent 实例**：
 
 ```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');
+// 项目 A
+const agentA = new Agent({
+  projectPath: '/repo/app-a',
+  dataDir: '/repo/app-a/.memora',
+  storage: makeStorage('/repo/app-a'), // 宿主实现的 IMemoryStorage
+  sessionStore: makeSessionStore('/repo/app-a'),
+  provider, configDir,
+});
+await agentA.init();
+
+// 项目 B：独立实例，与 A 并行运行、互不干扰
+const agentB = new Agent({
+  projectPath: '/repo/app-b',
+  dataDir: '/repo/app-b/.memora',
+  storage: makeStorage('/repo/app-b'),
+  sessionStore: makeSessionStore('/repo/app-b'),
+  provider, configDir,
+});
+await agentB.init();
 ```
 
-> 未命中注册表且传入的又不是绝对路径时，`switchProject` 直接抛错（相对路径会以进程 cwd 为基准，
-> 可能静默创建出非预期的项目目录并占用其锁）。
+每个实例各自持有：记忆库（宿主注入的 storage）、会话存储、项目锁、安全守卫、角色包管理器。
+项目数据天然隔离在项目自己的 `.memora/` 下。
+
+| 维度 | 形态 |
+|------|------|
+| 并行度 | **按项目计** —— N 个项目 = N 个会话同时跑 |
+| 项目内多会话 | 可拥有 N 个会话（`switchSession` / `switchToSession` / `forkSession`），**同一时刻只跑一个** |
+| 项目内多会话的记忆 | **共享同一个记忆库**（`searchByKeyword` 无 sessionId 过滤）⇒ 经验跨会话连续 |
+
+**取舍（明写，勿反复重议）**：本形态**不对标主流「一个会话 = 一个 Agent 实例」**。代价是
+**同一项目内不能并行跑两个会话**（主流开两个终端各推各的任务即可）——已知并接受，登记
+`MULTI-SESS-1`（观察，不修）。**理由**：记忆库归**项目**所有，会话只是项目内的对话线程；
+把身份边界画在项目而非会话，才能让同一项目的经验跨会话连续。仅当出现「同一仓库要并行
+两个任务」的真实需求时才重议形态。
+
+> 历史留痕：5.0.0 前曾有 `agent.switchProject()` / `agent.projects.*` / `AgentOptions.registryDir`
+> / `projects.json` 跨项目注册表整链，随形态定案一并删除（PR-SWITCH-1）。**勿按旧文档找回**——
+> 内核既不切换项目，也不维护跨项目名单。
 
 ### 9. 关闭
 
@@ -323,7 +356,7 @@ const agent = new Agent({
 **会话持久化特性：**
 - 日期使用 `todayDate()` 动态获取，确保跨日后消息写入当天目录
 - `appendUser()` / `appendAssistant()` 自动调用 `appendMessage()`
-- `loadSessionMessages()` 自动调用 `loadMessages()`
+- `loadSessionMessages()`（内部方法，非公开 API）自动调用 `loadMessages()`
 - `SessionMessage.role` 支持 `'user' | 'assistant' | 'system'`，宿主直接调用 `appendMessage()` 时可传入任意角色
 
 ---
@@ -454,7 +487,8 @@ app.put('/api/sessions/:id/archive', (req, res) => {
 | 后台命令 | 内置工具 `run_command`（`background: true`）/ `agent.listBackgroundTasks()` / `agent.killBackgroundTask()` | §8.1 · §8.7 |
 | 会话 | `agent.forkSession()` / `agent.sessionManager.*` | §六 |
 
-> 记忆治理（去重/冲突）统一走 `agent.governance` 或 Agent 层方法，见参考手册 §四 与「记忆治理」章节。
+> 记忆**写入期**治理由 `supersede`（写时取代）承担，无需宿主调用；写入入口统一是 `agent.memory.writeXxx()`。
+> 订阅式事后治理（去重 / 冲突检测 / 关联推荐）已于 5.0.0 整链退役，`agent.governance` 不再存在——见参考手册 §四 注记。
 
 ---
 
@@ -464,33 +498,39 @@ app.put('/api/sessions/:id/archive', (req, res) => {
 
 | 函数/类型 | 用途 |
 |-----------|------|
-| `createLlmProvider(config)` | 从完整 Config（`llm.providers` + `active`）创建激活 Provider（配合 `loadConfig`） |
 | `createProviderFromConfig(name, config)` | 从命名配置创建单个 Provider 实例（扁平参数） |
 | `loadConfig(path?)` | 加载 `.memora/config.json` 项目级配置文件（或传入显式 configPath） |
-| `InMemoryStorage` | IMemoryStorage 的纯内存实现（测试用） |
+| `createNodeSqliteStorage(dbPath[, options])` | 内核提供的 SQLite 落盘实现**工厂**（基于 `node:*` 内建模块，零第三方依赖）。不可用时抛专属错误（错误码 `NOT_AVAILABLE`）——「当前环境能否用 SQLite」的**唯一判据**（勿自行解析版本号）。第二参数 `{ readOnly: true }` 返回只读视图 |
+| `ReadOnlyMemoryStorage` | 只读存储视图**类型**（`IMemoryStorage` 的读方法子集，结构上无写方法）。供只读宿主（如 MCP）复用同一实现，避免自写第二份 SQLite 语义 |
 | `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，零开销） |
+| （无 Noop 导出） | 不注入 `tracer` 即自动降级为内核内部 Noop 实现（静默丢弃所有 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` 接口。
+**注意**：基于 **better-sqlite3** 的 `SqliteStorage` 仍已移出到宿主项目（native 编译模块不入内核），宿主可继续自行实现 `IMemoryStorage`。**但自 5.0.0 起，内核另提供可选的 SQLite 实现**：`createNodeSqliteStorage(dbPath)`——基于 `node:*` 内建模块（不引入第三方/native 依赖），宿主**无需自写**即可接入 SQLite；也可选择不接（继续 JSON / 内存实现）。用法：
+
+```typescript
+import { createNodeSqliteStorage, type IMemoryStorage } from '@zooique/memora';
+
+// 读写：文件不存在则建库（路径由宿主决定，内核不拼目录）
+let storage: IMemoryStorage;
+try {
+  storage = createNodeSqliteStorage(join(dataDir, 'memory.db'));
+} catch (err) {
+  // 唯一判据：工厂抛出的专属错误（errorCode = ToolErrorCode.NOT_AVAILABLE）→ 降级到 JSON/内存实现
+  storage = new MyJsonStorage(join(dataDir, 'memories.json'));
+}
+// 只读宿主：返回对象结构上不含写方法
+// const readOnly = createNodeSqliteStorage(join(dataDir, 'memory.db'), { readOnly: true });
+```
 
 `IMemoryStorage` 接口要求实现 `count()` 和 `countBySource(source)` 方法，用于高效统计记忆数量（避免全量加载数据）。详见 [API 参考手册](./memora-api-reference.md)。
 
@@ -555,7 +595,7 @@ const agent = new Agent({
 });
 ```
 
-> **不注入时**：默认使用 `NOOP_TRACER`（静默丢弃所有 span，零运行时开销）。
+> **不注入时**：内核自动降级为内部 Noop 实现（静默丢弃所有 span，零运行时开销）——无需引用任何实现类。
 
 ---
 
@@ -600,20 +640,20 @@ for (const chapter of chapters) {
 
 ## 十、关键约束
 
-**前提：存储方案由宿主自选，内核只定契约。** 内核只定义 `IMemoryStorage` / `ISessionStore` 接口，**不规定后端**——SQLite（better-sqlite3）、JSON 文件、内存实现一视同仁，任何后端都不得被写进内核逻辑。接口方法为**同步语义**（对齐 better-sqlite3），异步后端需另行扩展接口；JSON 落地实现在同步路径上做全量重写，记忆量增长时由宿主自行评估更优后端（阈值与权衡见 `storageInterface.ts` 头注释）。第一宿主 memora-vscode 当前用 JSON 文件，换成 SQLite **不需要改内核**。
+**前提：存储方案由宿主自选，内核只定契约。** 内核只定义 `IMemoryStorage` / `ISessionStore` 接口，**不规定后端**——SQLite、JSON 文件、内存实现一视同仁，任何后端都不得被写进内核逻辑（5.0.0 起内核**提供**可选的 SQLite 实现 `createNodeSqliteStorage`，但那是「多一个可选实现」，**不是**把后端写进逻辑——选哪个仍归宿主，`Agent` 构造契约不变）。接口方法为**同步语义**（对齐 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()` 不换存储；未注入则仅内存保存
+5. **对话历史随 Agent 持久化** — `sessionStore` 是实例级注入的，**切会话不换存储**；未注入则仅内存保存
 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 生命周期内缓存）
+9. **一个 Agent = 一份记忆库** — `storage` 与 `dataDir` 都是 **Agent 实例级**的：切会话复用同一实例，不按会话 / 子项目分裂。**要按项目彼此隔离，就各自 `new Agent`**——隔离粒度归宿主决定，内核不规定（见 [§8](#8-多项目一个项目一个-agent形态定案)）
+10. **切会话不重建、不关闭存储** — 会话切换只换身份（`sessionId`），复用已注入的实例；只在 `close()` 时关闭（`ProjectManager` 在 Agent 生命周期内缓存）
 11. **禁止把配置放进记忆库** — 配置（角色包 / persona / rules / skills）的真理源是文件（`configDir` / 角色包），设定记忆归角色包内容层、不进记忆库（ADR-025 / `memory-role-pack-boundary`）
-12. **项目切换** `switchProject()` 已自动 rebuild，通常无需手动调用 `rebuildComponents()`
+12. **组件重装配** 由内核在 `init()` / `reloadConfig()` 内部完成，无公开重建入口，宿主无需也无法手动触发
 13. **Tracer 未注入时**自动降级为 NoopTracer，零运行时开销
 
 ---
@@ -694,15 +734,15 @@ chatProvider.setAgentFactory((projectPath) =>
 
 > 本约束原仅存于宿主实现注释（`extension.ts` 的"杜绝双实例覆盖写"；仓库内参考实现，**非随包产物**），现提升为宿主接入契约基线，避免新宿主对接踩坑。原子写实锤已具备（`atomicWriteFileSync`），单例 + 原子写已对齐主流硬化做法（grida / Chatbox 同款 tmp+rename）；唯一真实残留为跨进程锁，已列入检查清单第 4 项。
 
-## 十.7、策略键消费矩阵（16 键 SSOT 落点）📌 参考
+## 十.7、策略键消费矩阵（17 键 SSOT 落点）📌 参考
 
-> 逐键矩阵（16 键 × 内核消费位置 × UI 侧消费）为仓库内开发文档（SSOT：`src/role-pack/strategyKeys.ts`），**不随包发布**；宿主对接所需的键语义见 [role-pack-authoring-guide.md](./architecture/role-pack-authoring-guide.md) §三。此处只给新宿主对接必知的结论与边界。
+> 逐键矩阵（17 键 × 内核消费位置 × 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` 多文件覆盖。
+- **17 键全部被内核真实消费、零 `[草案]`**（prepare 1 / act 7 / reflect 3 / global 6）。解析层 `rolePackManager` + `strategyResolver` 测试守护，消费层跨 `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`（不经聚合）；
+  1. act 5 键（`toolMode`/`toolStepLimit`/`providerRouting`/`multiStepReasoning`/`toolReadonly`）+ `selfReview` + **global 键中经聚合的 5 键**（`errorHandling`/`contextLimit`/`stepBudget`/`askLimit`/`webSearchLimit`）——此「5 键」是「**经 `resolveL2Strategy()` 聚合这一层**」的子集，global 第 6 键 `askOn` 不走聚合（归第 3 类）；上列各键统一经 `resolveL2Strategy()` 聚合注入 `L2RuntimeStrategy`，loop 经 `this.strategy.<field>` 读取；`act.temperature`/`outputLimit` 由 `agent.ts` 直映射 `ChatOptions`（不经聚合）；
   2. prepare 键经 `resolveActiveStrategy()` 单一真理源流入 `contextPreparer` / `roundSummaryGenerator`；
-  3. persona 指令类（`userFollowup`/`askOn`/`askLimit`）由 `assembleRolePack()` 单收口注入。
+  3. persona 指令类（`userFollowup`/`askOn`/`askLimit`）由 `assembleRolePack()` 单收口注入——**`askLimit` 是双面键**：既在第 1 类经聚合进 `L2RuntimeStrategy` 供 loop 硬护栏消费，又在此处随 persona prompt 注入，两处各占一面、**非重复计数**。
 - **⚠️ 边界纠正：`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 实现均为仓库内宿主参考实现，**非随包产物**。）
 

package/docs/role-pack-/345/274/200/346/224/276/351/224/256/346/214/207/345/215/227.md

@@ -1,148 +1,148 @@
-# 角色包开放键使用指南（发布包版）
-
-> **面向对象**：安装 `@zooique/memora` 后，编写 / 理解角色包（role pack）的开发者——既包括**宿主接入者**（要把角色包能力接进自己的产品），也包括**角色包作者**（要填写 `manifest.json`）。
-> **定位**：本指南回答「manifest.json 里的开放键填什么、**被谁消费**、有什么上限」。它是 memora 发布包内的角色包使用入口。
-> **相关文档**：
-> - 中立规范（跨所有 Agent 实现的契约，随包发布）：[role-pack-spec.md](./architecture/role-pack-spec.md)
-> - 详细填写手册（含全部区间 / 错误修正 / 键的落实状态，随包发布）：[role-pack-authoring-guide.md](./architecture/role-pack-authoring-guide.md)
-> - 示例角色包（结构参考，随包发布、不参与宿主运行时装载）：[role-packs/](../role-packs/README.md)
-
----
-
-## 一、角色包是什么
-
-角色包 = 一个文件夹 + `manifest.json`（唯一核心控制文件）+ 内容文件：
-
-```
-角色包名/
-├── manifest.json        # ★ 元数据 + strategy 策略 + capabilities + skills 白名单
-├── persona.md           # 角色身份设定（约定文件名，可缺省）
-├── rules.md             # 确定性规则（约定文件名，逐行解析）
-└── skills/              # 技能目录（动态扫描，新增技能只写文件即可）
-```
-
-把角色包文件夹放进 `configDir/role-packs/` 即可装载。`manifest.json` 里的字段统称**开放键**——它们是内核、宿主、UI 三方协作的契约，本文档回答「谁在用它们」。
-
----
-
-## 二、三层消费方逻辑（先理解"键被谁用"）
-
-所有开放键的消费方分三层，**不是所有键都是给宿主接入的**：
-
-| 层 | 消费方 | 键 | 用途 |
-|----|--------|-----|------|
-| **① 内核直接消费** | memora 内核 | `skills` / `strategy` | 技能扫描、行为策略 |
-| **② 中立接口（宿主接入点）** | 宿主 / 其他实现 | `capabilities` / `handoffPrompt` | 能力映射、接手话术 |
-| **③ 元数据（UI 展示）** | 宿主 UI | `name` / `displayName` / `description` / `author` | 标识与展示 |
-
-### 2.1 ① 内核直接消费层（memora 实现细节）
-
-这些键由 memora 内核自己跑逻辑，**宿主不需要处理**：
-
-- `skills`：内嵌技能白名单（目录动态扫描，声明项仅作白名单过滤；不声明则全量扫描 `skills/`）。
-- `strategy`：L2 行为策略（`prepare` / `act` / `reflect` / `global` 四组），控制工具暴露、摘要视角、自审查、预算与提问等行为偏好。
-
-> 这些键的**上限由内核统一守门**（见 §2.4），因为解析入口在内核。
-
-### 2.2 ② 中立接口层（宿主接入点）
-
-这一层是**为宿主 / 跨实现接入预留的中立契约**——角色包不绑具体实现，由各实现自己消费：
-
-- **`capabilities`（能力声明）**：以**中立能力命名空间**声明（`域:动作`，如 `file:write` / `web:search`），不绑具体工具。**各实现（memora 是 reference implementation）自行映射到自有工具**：
-  - **特权声明模型（2026-09-08 定，2026-09-16 扩）**：memora 侧映射表在 `src/role-pack/capabilityMap.ts`（SSOT）——仅 `web:search` / `web:fetch` / `code:execute` 映射为**特权工具白名单**；`file:*` / `memory:recall` / **`task:plan`（对应任务表）** 属**默认常驻工具**（`toolExecutor.DEFAULT_EXPOSED_TOOLS`），声明与否都不影响可见性、不再映射。任务表系内核多步任务必要基建（2026-09-16 用户拍板），非角色包可选的领域深度能力；
-  - **宿主可以有自己的映射表**：例如 `code:execute` 需宿主注入 `ICodeExecutionProvider` 才真正暴露；
-  - 未知能力（不在映射表）跳过，不阻塞装载。
-  - 角色包声明 `capabilities` 后，工具暴露面 = 常驻豁免集 + 能力白名单内的特权工具（换角色 → 特权工具集切换）。
-- **`handoffPrompt`（接手话术）**：该角色包**被宿主带入对话（激活 + 聚焦）时**预填输入框的特色衔接话术——作者为「这个角色接手任务时怎么说」定制的提示词，缺省由宿主回退通用话术。**宿主消费**（如 memora-vscode 在 `roles_handoff` 处理中读取 `listMeta().handoffPrompt` 预填）；内核仅透传 + 校验（非字符串 warning 不阻塞装载）。
-
-### 2.3 ③ 元数据层（UI 展示）
-
-- `name`（唯一标识，缺失用文件夹名兜底）、`displayName`（UI 展示名，缺省回退 `name`）、`description`、`author`。
-- 内核仅作标识/校验；真正消费是宿主的角色包清单 / UI 展示。
-
-### 2.4 为什么上限由内核统一守门
-
-**无论最终消费方是谁，`manifest.json` 的解析入口都在 memora 内核**（`validator.ts` 校验 + `rolePackManager.ts` 装载）。内核作为装载器在入口守门——对所有开放字段统一限长：
-
-- 对**内核字段**：防资源失控（匹配词列表膨胀拖慢匹配、巨型内容占内存/上下文）；
-- 对**宿主字段**：防巨型数据透传给宿主（宿主收到的是已被内核约束过的安全数据）。
-
-这正是「零依赖内核」哲学：**内核做守门，宿主做消费**。所以上表中所有字段的上限，全部由内核入口统一控制（见 §三），不区分消费方。
-
----
-
-## 三、开放键速查表（消费方 + 上限）
-
-> 详细区间 / 错误修正 / 键的落实状态见 [role-pack-authoring-guide.md](./architecture/role-pack-authoring-guide.md)（仓库内文档）。下表是发布包内的精简速查。
-> **上限 SSOT**：`src/role-pack/validator.ts`（非策略键）与 `src/role-pack/strategyKeys.ts`（策略键数值区间）。
-
-### 3.1 元数据层
-
-| 键 | 类型 | 消费方 | 上限 | 说明 |
-|----|------|--------|------|------|
-| `name` | string | ③ UI / 内核标识 | ≤200 字符 | 唯一标识（缺失用文件夹名兜底） |
-| `formatVersion` | string | ① 内核校验（可选，缺省 `1.0.0`） | semver（x.y.z） | 格式版本，绑定固定 schema URL，发布后不变；建议声明 |
-| `displayName` | string | ③ UI | ≤200 字符 | UI 展示名，缺省回退 `name` |
-| `description` | string | ③ UI | ≤200 字符 | 角色包描述 |
-| `author` | string | ③ UI | ≤200 字符 | 作者/来源 |
-| `version` | string | ③ 分发 | semver（x.y.z） | 角色包自身版本（可选） |
-
-### 3.2 中立接口层（宿主接入）
-
-| 键 | 类型 | 消费方 | 上限 | 说明 |
-|----|------|--------|------|------|
-| `capabilities` | 对象数组 | ② 宿主 / 各实现映射 | ≤50 项 | `{ capability: "域:动作", description? }`；映射到各实现自有工具 |
-| `handoffPrompt` | string | ② 宿主预填 | ≤2000 字符 | 被带入对话时预填的接手话术 |
-
-### 3.3 内核消费层
-
-| 键 | 类型 | 消费方 | 上限 | 说明 |
-|----|------|--------|------|------|
-| `skills` | 对象数组 | ① 内核扫描 | ≤50 项 | 技能白名单（`{ file, name?, description? }`） |
-| `strategy` | 嵌套对象 | ① 内核行为 | 各数值键有上下限（见 authoring-guide §四） | L2 行为策略（prepare/act/reflect/global） |
-
-### 3.4 合规 / 分档层
-
-| 键 | 类型 | 消费方 | 上限 | 说明 |
-|----|------|--------|------|------|
-| `interactionType` | string 枚举 | ① 内核合规 | `tool_assistant` / `companion`（缺省 `tool_assistant`） | 交互类型：工具型（豁免区间）vs 拟人化陪伴（完整合规校验） |
-| `aiIdentityDisclosure` | boolean | ① 内核合规 | `true`（缺省） | 是否向用户明确标注 AI 身份（companion 必须显式 true） |
-| `minorProtection` | string 枚举 | ① 内核合规 | `required`（缺省） | 未成年人保护模式（当前仅支持 required） |
-
-> **越界行为统一**：开发期 `validator` 校验报 error（拒绝装载提示）；运行时按上限截断 / 回退默认（宽容容错）。
-
----
-
-## 四、内容文件约定（零声明）
-
-`persona.md` / `rules.md` / `skills/` 全部**约定俗成**——manifest **不注册内容路径**（防路径写错静默丢内容）：
-
-| 文件 | 约定 | 说明 |
-|------|------|------|
-| `persona.md` | 约定名 | 角色身份设定（frontmatter 可声明 `traits.*` 数值 trait，clamp 0-1） |
-| `rules.md` | 约定名 | 确定性规则（逐行解析 `- ` / `* ` / `n. ` 列表） |
-| `skills/` | 目录动态扫描 | 新增技能只写文件即可，frontmatter 声明 `name` / `description`（渐进披露 L1） |
-
----
-
-## 五、最小示例
-
-```json
-{
-  "name": "plain-designer",
-  "displayName": "白话方案设计师",
-  "description": "白话方案设计角色包",
-  "formatVersion": "1.0.0",
-  "interactionType": "tool_assistant",
-  "strategy": {
-    "prepare": { "summaryFocus": "以方案设计视角提炼要点" },
-    "act": { "toolMode": "allow", "temperature": 0.3 },
-    "global": { "contextLimit": 0 }
-  },
-  "capabilities": [
-    { "capability": "file:write", "description": "写文件" },
-    { "capability": "web:search", "description": "搜索" }
-  ],
-  "handoffPrompt": "你好，我是白话方案设计师，请告诉我你想解决什么模糊想法或痛点。"
-}
-```
+# 角色包开放键使用指南（发布包版）
+
+> **面向对象**：安装 `@zooique/memora` 后，编写 / 理解角色包（role pack）的开发者——既包括**宿主接入者**（要把角色包能力接进自己的产品），也包括**角色包作者**（要填写 `manifest.json`）。
+> **定位**：本指南回答「manifest.json 里的开放键填什么、**被谁消费**、有什么上限」。它是 memora 发布包内的角色包使用入口。
+> **相关文档**：
+> - 中立规范（跨所有 Agent 实现的契约，随包发布）：[role-pack-spec.md](./architecture/role-pack-spec.md)
+> - 详细填写手册（含全部区间 / 错误修正 / 键的落实状态，随包发布）：[role-pack-authoring-guide.md](./architecture/role-pack-authoring-guide.md)
+> - 示例角色包（结构参考，随包发布、不参与宿主运行时装载）：[role-packs/](../role-packs/README.md)
+
+---
+
+## 一、角色包是什么
+
+角色包 = 一个文件夹 + `manifest.json`（唯一核心控制文件）+ 内容文件：
+
+```
+角色包名/
+├── manifest.json        # ★ 元数据 + strategy 策略 + capabilities + skills 白名单
+├── persona.md           # 角色身份设定（约定文件名，可缺省）
+├── rules.md             # 确定性规则（约定文件名，逐行解析）
+└── skills/              # 技能目录（动态扫描，新增技能只写文件即可）
+```
+
+把角色包文件夹放进 `configDir/role-packs/` 即可装载。`manifest.json` 里的字段统称**开放键**——它们是内核、宿主、UI 三方协作的契约，本文档回答「谁在用它们」。
+
+---
+
+## 二、三层消费方逻辑（先理解"键被谁用"）
+
+所有开放键的消费方分三层，**不是所有键都是给宿主接入的**：
+
+| 层 | 消费方 | 键 | 用途 |
+|----|--------|-----|------|
+| **① 内核直接消费** | memora 内核 | `skills` / `strategy` | 技能扫描、行为策略 |
+| **② 中立接口（宿主接入点）** | 宿主 / 其他实现 | `capabilities` / `handoffPrompt` | 能力映射、接手话术 |
+| **③ 元数据（UI 展示）** | 宿主 UI | `name` / `displayName` / `description` / `author` | 标识与展示 |
+
+### 2.1 ① 内核直接消费层（memora 实现细节）
+
+这些键由 memora 内核自己跑逻辑，**宿主不需要处理**：
+
+- `skills`：内嵌技能白名单（目录动态扫描，声明项仅作白名单过滤；不声明则全量扫描 `skills/`）。
+- `strategy`：L2 行为策略（`prepare` / `act` / `reflect` / `global` 四组），控制工具暴露、摘要视角、自审查、预算与提问等行为偏好。
+
+> 这些键的**上限由内核统一守门**（见 §2.4），因为解析入口在内核。
+
+### 2.2 ② 中立接口层（宿主接入点）
+
+这一层是**为宿主 / 跨实现接入预留的中立契约**——角色包不绑具体实现，由各实现自己消费：
+
+- **`capabilities`（能力声明）**：以**中立能力命名空间**声明（`域:动作`，如 `file:write` / `web:search`），不绑具体工具。**各实现（memora 是 reference implementation）自行映射到自有工具**：
+  - **特权声明模型（2026-09-08 定，2026-09-16 扩）**：memora 侧映射表在 `src/role-pack/capabilityMap.ts`（SSOT）——仅 `web:search` / `web:fetch` / `code:execute` 映射为**特权工具白名单**；`file:*` / `memory:recall` / **`task:plan`（对应任务表）** 属**默认常驻工具**（`toolExecutor.DEFAULT_EXPOSED_TOOLS`），声明与否都不影响可见性、不再映射。任务表系内核多步任务必要基建（2026-09-16 用户拍板），非角色包可选的领域深度能力；
+  - **宿主可以有自己的映射表**：例如 `code:execute` 需宿主注入 `ICodeExecutionProvider` 才真正暴露；
+  - 未知能力（不在映射表）跳过，不阻塞装载。
+  - 角色包声明 `capabilities` 后，工具暴露面 = 常驻豁免集 + 能力白名单内的特权工具（换角色 → 特权工具集切换）。
+- **`handoffPrompt`（接手话术）**：该角色包**被宿主带入对话（激活 + 聚焦）时**预填输入框的特色衔接话术——作者为「这个角色接手任务时怎么说」定制的提示词，缺省由宿主回退通用话术。**宿主消费**（如 memora-vscode 在 `roles_handoff` 处理中读取 `listMeta().handoffPrompt` 预填）；内核仅透传 + 校验（非字符串 warning 不阻塞装载）。
+
+### 2.3 ③ 元数据层（UI 展示）
+
+- `name`（唯一标识，缺失用文件夹名兜底）、`displayName`（UI 展示名，缺省回退 `name`）、`description`、`author`。
+- 内核仅作标识/校验；真正消费是宿主的角色包清单 / UI 展示。
+
+### 2.4 为什么上限由内核统一守门
+
+**无论最终消费方是谁，`manifest.json` 的解析入口都在 memora 内核**（`validator.ts` 校验 + `rolePackManager.ts` 装载）。内核作为装载器在入口守门——对所有开放字段统一限长：
+
+- 对**内核字段**：防资源失控（匹配词列表膨胀拖慢匹配、巨型内容占内存/上下文）；
+- 对**宿主字段**：防巨型数据透传给宿主（宿主收到的是已被内核约束过的安全数据）。
+
+这正是「零依赖内核」哲学：**内核做守门，宿主做消费**。所以上表中所有字段的上限，全部由内核入口统一控制（见 §三），不区分消费方。
+
+---
+
+## 三、开放键速查表（消费方 + 上限）
+
+> 详细区间 / 错误修正 / 键的落实状态见 [role-pack-authoring-guide.md](./architecture/role-pack-authoring-guide.md)（仓库内文档）。下表是发布包内的精简速查。
+> **上限 SSOT**：`src/role-pack/validator.ts`（非策略键）与 `src/role-pack/strategyKeys.ts`（策略键数值区间）。
+
+### 3.1 元数据层
+
+| 键 | 类型 | 消费方 | 上限 | 说明 |
+|----|------|--------|------|------|
+| `name` | string | ③ UI / 内核标识 | ≤200 字符 | 唯一标识（缺失用文件夹名兜底） |
+| `formatVersion` | string | ① 内核校验（可选，缺省 `1.0.0`） | semver（x.y.z） | 格式版本，绑定固定 schema URL，发布后不变；建议声明 |
+| `displayName` | string | ③ UI | ≤200 字符 | UI 展示名，缺省回退 `name` |
+| `description` | string | ③ UI | ≤200 字符 | 角色包描述 |
+| `author` | string | ③ UI | ≤200 字符 | 作者/来源 |
+| `version` | string | ③ 分发 | semver（x.y.z） | 角色包自身版本（可选） |
+
+### 3.2 中立接口层（宿主接入）
+
+| 键 | 类型 | 消费方 | 上限 | 说明 |
+|----|------|--------|------|------|
+| `capabilities` | 对象数组 | ② 宿主 / 各实现映射 | ≤50 项 | `{ capability: "域:动作", description? }`；映射到各实现自有工具 |
+| `handoffPrompt` | string | ② 宿主预填 | ≤2000 字符 | 被带入对话时预填的接手话术 |
+
+### 3.3 内核消费层
+
+| 键 | 类型 | 消费方 | 上限 | 说明 |
+|----|------|--------|------|------|
+| `skills` | 对象数组 | ① 内核扫描 | ≤50 项 | 技能白名单（`{ file, name?, description? }`） |
+| `strategy` | 嵌套对象 | ① 内核行为 | 各数值键有上下限（见 authoring-guide §四） | L2 行为策略（prepare/act/reflect/global） |
+
+### 3.4 合规 / 分档层
+
+| 键 | 类型 | 消费方 | 上限 | 说明 |
+|----|------|--------|------|------|
+| `interactionType` | string 枚举 | ① 内核合规 | `tool_assistant` / `companion`（缺省 `tool_assistant`） | 交互类型：工具型（豁免区间）vs 拟人化陪伴（完整合规校验） |
+| `aiIdentityDisclosure` | boolean | ① 内核合规 | `true`（缺省） | 是否向用户明确标注 AI 身份（companion 必须显式 true） |
+| `minorProtection` | string 枚举 | ① 内核合规 | `required`（缺省） | 未成年人保护模式（当前仅支持 required） |
+
+> **越界行为统一**：开发期 `validator` 校验报 error（拒绝装载提示）；运行时按上限截断 / 回退默认（宽容容错）。
+
+---
+
+## 四、内容文件约定（零声明）
+
+`persona.md` / `rules.md` / `skills/` 全部**约定俗成**——manifest **不注册内容路径**（防路径写错静默丢内容）：
+
+| 文件 | 约定 | 说明 |
+|------|------|------|
+| `persona.md` | 约定名 | 角色身份设定（frontmatter 可声明 `traits.*` 数值 trait，clamp 0-1） |
+| `rules.md` | 约定名 | 确定性规则（逐行解析 `- ` / `* ` / `n. ` 列表） |
+| `skills/` | 目录动态扫描 | 新增技能只写文件即可，frontmatter 声明 `name` / `description`（渐进披露 L1） |
+
+---
+
+## 五、最小示例
+
+```json
+{
+  "name": "plain-designer",
+  "displayName": "白话方案设计师",
+  "description": "白话方案设计角色包",
+  "formatVersion": "1.0.0",
+  "interactionType": "tool_assistant",
+  "strategy": {
+    "prepare": { "summaryFocus": "以方案设计视角提炼要点" },
+    "act": { "toolMode": "allow", "temperature": 0.3 },
+    "global": { "contextLimit": 0 }
+  },
+  "capabilities": [
+    { "capability": "file:write", "description": "写文件" },
+    { "capability": "web:search", "description": "搜索" }
+  ],
+  "handoffPrompt": "你好，我是白话方案设计师，请告诉我你想解决什么模糊想法或痛点。"
+}
+```