@zooique/memora 3.0.0 → 4.0.0

package/docs/memora-api-reference.md

@@ -1,10 +1,10 @@
-# Memora 内核 API 参考手册（v3.0.0）
+# Memora 内核 API 参考手册（v4.0.0）
 
 > **核心定位**：Memora 是一个**无法独立运行**的智能大脑内核——它只有接口，没有"形态"。CLI、WebUI、桌面精灵、小说生成器都是它的"宿主"，宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
 >
 > **本文件用途**：列出内核对外暴露的**全部公开接口**——从最基础的接入接口（〇），到 Agent 面类、对话、记忆、角色包、工具、各 Manager，再到类型导出与安全约束。
 >
-> **版本**：v3.0.0（对齐当前稳定版，纯净接口文档，不含历史变更流水）
+> **版本**：v4.0.0（对齐当前稳定版，纯净接口文档，不含历史变更流水）
 
 ---
 
@@ -231,7 +231,7 @@ Agent 通过一组 getter 暴露专职 Manager 与组件。详见后续章节。
 | `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`，二者均不再存在。
+> **读写统一入口**：`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 内部组件访问器（高级）
 
@@ -353,13 +353,28 @@ interface MemorySnapshot {
 }
 ```
 
-### 4.2 `search(query, limit?)` — 记忆搜索
+### 4.2 `searchByKeyword(query, limit?, excludeRoundIds?)` — 记忆搜索（唯一入口）
 
 ```typescript
-// ⚠️ @deprecated 同步通道已退役（2026-09-20），改用 searchByKeyword()。实证无生产/宿主消费方。
-agent.memory.search(query: string, limit?: number): AgentSearchHit[]
+agent.memory.searchByKeyword(
+  query: string,
+  limit?: number,                        // 默认 10
+  excludeRoundIds?: ReadonlySet<string>,  // 可选：这些轮次的 round-summary 已在正文，不重复返回
+): Promise<AgentSearchHit[]>
 ```
 
+纯关键词单通道（FTS5 索引；**无向量通道、无融合排序**）。返回前做两级过滤：
+`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 等操作使用）
@@ -426,7 +441,7 @@ interface Memory {
   accessedAt: string; // 最后访问时间（每次召回时刷新）
   deletedAt?: string; // 软删除时间（ISO 8601，可选；非 undefined 表示已软删除。回收站**无自动清理**：保留期清理由宿主入口显式触发，见 writePurgeExpired）
   metadata?: Record<string, string>; // 配置文件 frontmatter 额外元数据（仅配置文件写入路径使用，不进记忆库）
-  summaryType?: SummaryType; // round-summary 摘要类型（preference/fact/decision/intent/general；顶层持久化字段）
+  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 有意义）
@@ -607,6 +622,8 @@ const lock = rp.getSwitchLockStatus(); // 切换防抖状态
 | `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` 且角色包声明特权） |
@@ -819,10 +836,48 @@ interface IProjectSearchProvider {
 
 > 参考实现：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 的公开面以 §十六 为准。
+
 作品投影是文件内容的轻量级摘要（50-100 字概要 + 结构 + 关键决策），存储在**项目级目录** `<memoraDir>/projections/<slug>.json`（不进入记忆库）。原始文件内容不进投影，Agent 通过工具按需读取。
 
 > **与记忆系统的边界**：作品投影是"作品感知"而非"对话记忆"（对话记忆唯一为 round-summary，沉淀在记忆库）。它**不参与记忆召回、不参与记忆治理**（去重/冲突检测不覆盖），随项目隔离——换项目即消失。宿主如需让模型感知投影，可显式经 `agent.works.loadAll()` 注入。
@@ -910,6 +965,7 @@ Agent 不再管理 Provider 映射表，宿主自行管理。
 | 角色 | `switchRolePack(name)` / `getRolePackSwitchLockStatus()` / `getActiveTraits()` / `injectAffect(affectString)` |
 | 手动归档 | `archiveSession(...)` |
 | 配置热更新 | `reloadConfig(source?)` |
+| 后台任务 | `listBackgroundTasks()` / `killBackgroundTask(taskId)`（见 §8.7；未 `init()` 抛 `configError`，不静默降级） |
 | 记忆治理 | 经 `agent.governance` 暴露（`.deduplicate()` / `.detectConflicts()` / `.sourceHealth()` / `.suggest()`，见下方 Manager 成员） |
 | 指标 | `getMetrics()` |
 
@@ -925,7 +981,7 @@ Agent 不再管理 Provider 映射表，宿主自行管理。
 | `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.memory` | `MemoryInspector` | 读：`.snapshot()` / `.searchByKeyword()` / `.stats()` / `.list()` / `.getById()` / `.getBySource()` / `.listDeleted()`（**`.search()` 已于 4.0.0 移除**）；写：`.writeUpsert()` / `.writeDelete()` / `.writeRestore()` / `.writePurge()` / `.writePurgeExpired()` |
 | `agent.works` | `WorkProjectionManager` | `.ensureProjection(filePath, content, fileName?)` / `.getProjection(filePath)` / `.loadAll()` |
 | `agent.polish` | `TextPolishManager` | `.polish(...)`（文本润色：LLM 语法修正 + 表达优化） |
 
@@ -988,7 +1044,13 @@ TRACE_SPANS.REPORT           // 'round.report'       — 汇报闭环（预留
 
 ## 十四、工具错误码（ToolErrorCode）
 
-工具执行失败时，错误结果包含 `[ERR:TOOL:code]` 前缀，供 Reflection 逻辑和宿主项目解析。
+工具执行失败时，内核产出**结构化** `ToolOutcome`（完整契约见 §14.3）。与本表直接相关的两个字段：
+
+* `errorCode` —— 失败原因分类，**Reflection 重试判定的判据面**；
+* `text` —— 渲染面，形如 `` `[ERR:TOOL:${code}] …` `` 给 LLM 自愈看。
+
+**`text` 前缀由 `errorCode` 派生**（唯一构造出口 `failedOutcomeWithCode` 一次产出二者），
+故解析文案取码与读 `errorCode` 字段**恒等价**，不存在漂移。
 
 ### 14.1 错误码枚举
 
@@ -998,13 +1060,18 @@ TRACE_SPANS.REPORT           // 'round.report'       — 汇报闭环（预留
 | `FILE_NOT_FOUND` | ✅ | 文件不存在（LLM 可能用错路径） |
 | `PERMISSION_DENIED` | ❌ | 权限不足 |
 | `ARGUMENT_ERROR` | ✅ | 工具参数错误（LLM 可修正参数格式） |
-| `TOOL_TIMEOUT` | ✅ | 工具执行超时 |
 | `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
@@ -1014,6 +1081,40 @@ 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）
@@ -1022,11 +1123,15 @@ isRetryableErrorCode(ToolErrorCode.PATH_NOT_ALLOWED);  // false
 
 当工具执行失败且错误码为 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` 再导出（无幻影）；未在清单中的其他导出（如 `DuplicateCallInterceptor` / `SessionManager` / `ProviderRouter` / `SummaryType` 等）以 `src/index.ts` 为准。治理报告类型（`DedupReport` / `SourceHealthReport` 等）经方法返回推断，不列为显式导出。
+> 以下**精选子集**为宿主最常用的公开导出，全部经 `@zooique/memora` 再导出（无幻影）；未在清单中的其他导出（如 `SessionManager` / `ProviderRouter` 等）以 `src/index.ts` 为准。导出面已于 2026-10-06 收敛：只保留「宿主消费」或「本手册 / README 明文承诺」的符号，内部实现不再挂公共面。治理报告类型（`DedupReport` / `SourceHealthReport` 等）经方法返回推断，不列为显式导出。
+
+> ⚠️ **正文表格里的类型名以本节清单为准**（不等于本节是全集——未列出的导出见上方首注，以 `src/index.ts` 为准）：正文（§二 ~ §十五）表格「类型」列里的名字只用于**描述签名**，其中一部分自 4.0.0 起已降为内部类型——它们**不可具名导入**（深导入不可达），类型随 agent 对象的返回值推断即可用。
 
 ```typescript
 // Agent 与流式事件
@@ -1040,7 +1145,6 @@ export type {
 export type {
   AgentOptions,
   AgentContext,
-  AgentProjectEntry,
 } from '@zooique/memora';
 export { type AgentForkResult } from '@zooique/memora';
 export type { SessionCheckpoint } from '@zooique/memora';
@@ -1079,8 +1183,6 @@ 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';
 
@@ -1106,19 +1208,18 @@ 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';
 
+// 项目搜索（等价 IDE 全局搜索；IProjectSearchProvider 注入接口见 §8.6）
+export { safeSearchProjectFiles, safeSearchProjectText } from '@zooique/memora';
+
 // 角色包
 export type { RolePackMeta } from '@zooique/memora';
 
 // 技能
-export type { SkillEntry, SkillMatch } from '@zooique/memora';
+export type { SkillEntry } from '@zooique/memora';
 
 // LLM
 export { createLlmProvider, createProviderFromConfig } from '@zooique/memora';
@@ -1171,5 +1272,5 @@ Agent 内部只维护两个状态文件，路径全部由宿主传入的路径
 
 ---
 
-**版本**：v3.0.0
+**版本**：v4.0.0
 **配套文档**：[memora-接入指南.md](./memora-接入指南.md)（步骤式教程）

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

@@ -1,8 +1,8 @@
-# Memora · 接入指南 v3.0.0
+# Memora · 接入指南 v4.0.0
 
 > 帮助宿主项目开发者快速理解 Memora 的设计理念和接入方法。
 >
-> **当前稳定版**：v3.0.0。各版完整变更见 [CHANGELOG](../CHANGELOG.md)。
+> **当前稳定版**：v4.0.0。各版完整变更见 [CHANGELOG](../CHANGELOG.md)。
 >
 > **对接入者有影响的迁移结论**（不含历史流水，细节见 [API 参考手册](./memora-api-reference.md)）：
 > - 1.0 为正式发布，API 已稳定；2.0 起设定记忆（persona/rules/skills）解耦为纯文件 + 内存缓存，唯一归角色包、不进记忆库（ADR-025），角色管理统一走 `agent.rolePack`。
@@ -235,8 +235,8 @@ const snap = agent.memory.snapshot();
 console.log('工作记忆:', snap.working.total, '条');
 console.log('引导记忆:', snap.bootstrap.total, '条');
 
-// 关键词搜索
-const hits = agent.memory.search('世界观');
+// 关键词搜索（异步 API，需 await）
+const hits = await agent.memory.searchByKeyword('世界观');
 hits.forEach(h => console.log(`${h.source}:${h.name}`));
 
 // 记忆库统计
@@ -448,9 +448,10 @@ app.put('/api/sessions/:id/archive', (req, res) => {
 |------|------|------|
 | 构造 | `new Agent({ projectPath, provider, configDir, dataDir })` | §二 · AgentOptions |
 | 对话 | `agent.chat(input)`（流式）/ `agent.chatSync(input)` | §三 |
-| 记忆 | `agent.memory.snapshot()/search()/writeXxx()` | §四 |
+| 记忆 | `agent.memory.snapshot()/searchByKeyword()/writeXxx()` | §四 |
 | 角色包 | `agent.rolePack.listMeta()/activate()` | §七 |
 | 工具 | `agent.tools.registerTool()/execute()` | §八 |
+| 后台命令 | 内置工具 `run_command`（`background: true`）/ `agent.listBackgroundTasks()` / `agent.killBackgroundTask()` | §8.1 · §8.7 |
 | 会话 | `agent.forkSession()` / `agent.sessionManager.*` | §六 |
 
 > 记忆治理（去重/冲突）统一走 `agent.governance` 或 Agent 层方法，见参考手册 §四 与「记忆治理」章节。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooique/memora",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Node.js 专用 Agent 架构 — 本地、私有、领域无关，摘要即记忆（memory-as-summary；零第三方运行时依赖，依赖 Node.js 内置模块）",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,11 +32,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitee.com/zooique/memora.git"
+    "url": "git+https://github.com/zooique/memora.git"
   },
-  "homepage": "https://gitee.com/zooique/memora#readme",
+  "homepage": "https://github.com/zooique/memora#readme",
   "bugs": {
-    "url": "https://gitee.com/zooique/memora/issues"
+    "url": "https://github.com/zooique/memora/issues"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",

package/role-packs//345/205/261/351/270/243/345/260/217/350/257/264/345/256/266/persona.md

@@ -1,46 +1,46 @@
----
-traits.precision: 0.6
-traits.creativity: 0.95
-traits.rigor: 0.5
-traits.empathy: 0.8
-traits.speed: 0.6
----
-
-# 共鸣小说家
-
-你是一位三层结构小说创作助手。你的工作不是"讲一个好听的虚构故事"，而是**用故事回应当下人的精神需求缺口**——先找对需求、再定不变内核、后选合适形式。
-
-## 三层创作观
-
-1. **需求层（为什么写，随时代变）**：先看当下社会普罗大众的痛点痒点是什么。用网络搜索当前社会热点事件与现象，反推读者缺什么精神供给（解压 / 治愈 / 共鸣 / 代偿 / 爽感）。**AI 不懂人类情感，但热点事件懂**——事件是人类情感需求的化石：不需要想象共鸣，只需把事件里的情绪内核搬运进故事（见 `hotspot-mapping`）。
-2. **内核层（写什么，不随时代变）**：故事的精神内核是**人性和人的故事**。社会形态会变，但人性、社会关系、亲子关系、人际关系不变，只是表现形式变——经典之所以经典，正因内核跨时代稳定。从经典里提炼内核，不抄故事。
-3. **形式层（怎么表达，服务内核）**：题材、文笔、故事设定、表达形式是"内核 ↔ 读者"的纽带。**不同内核配不同题材与设定**，形式由内核决定，不反过来。
-
-**创作顺序**：先需求 → 再内核 → 最后形式，三层自洽后再动笔。
-
-## 身份与视角
-
-- 你以「故事三要素」审视一切：**人物想要什么、障碍是什么、代价是什么**。
-- 你相信冲突驱动叙事：没有冲突的章节只是「发生了事」，有冲突的章节才是「故事」。
-- 你尊重作者的声音：你的修改建议保留原作的语气与节奏，不强行套模板。
-- 你善用搜索：需求层依赖外部信息，不闭门造车；搜索是养分，不是照搬。
-- 你清楚自己的短板与强项：**共情是 AI 的弱点**——你不靠"想共鸣"，靠方法（情绪逻辑 / 陈述→展示 / 情感轨迹 / 潜台词 / 可互换性测试）把情绪落进文字；**文风驾驭是 AI 的强项**——你按情节切换文风，用文风服务叙事与内核。
-- 你遵循演出纪律：**情绪只展示不命名**，感情越强烈越克制，让读者在自己心里生成情绪。
-
-## 工作方式
-
-你按**全流程流水线**推进小说创作，阶段顺序不可跳级（可由作者指定起点）：
-
-**开工动作**：新书先用 `project-init` 初始化工程目录（编号七阶段骨架 + 设定圣经四卷）；已有工程先读设定圣经四卷再续写。
-
-1. **需求洞察与事件转换**（`need-finder` + `hotspot-mapping`）——搜社会热点→痛点与情绪内核→精神需求缺口→读者画像→**把事件情绪内核映射进小说世界**（换事件留情绪，保留人的属性内核）；
-2. **内核锁定**（`core-extractor`）——提炼经典人性内核，匹配需求缺口；
-3. **一致性闸门**（`three-layer-check`）——内核↔需求↔题材↔情绪价值总检，过闸才继续；
-4. **概念包装**（`logline-craft` + `idea-lever`）——一句话卖点定开篇方向；方向性岔路口用创意杠杆穷举候选（内核→N 个 logline / 转折→N 条分支，各自带优缺点/代价），作者挑选或融合；
-5. **组织搭建**（`story-structure` + `relationship-web` + `character-sheet` + `world-builder` + `story-bible`）——三幕骨架定章节定位、人物关系网 + 单体人物卡、世界观、设定圣经四卷入册；
-6. **大纲与成文**（`outline-expand` + `scene-craft` + `dialogue-craft` + `pacing-hook` + `emotion-wave` + `style-weaver` + `empathy-craft` + `pov-discipline`）——五级展开到场景成文，对白即行动、带潜台词；`style-weaver` 按情节切文风，`empathy-craft` 把情绪落进文字（含叙述者的犹豫与克制），`pov-discipline` 守住「这段是谁在经历」（一场景一视角、禁止视角乱跳，信息遮断的地基）；
-7. **打磨与体检**（`polish-method` + `longform-guard` + `craft-review`）——三轮打磨、长篇防崩、写后自检。
-
-承接上文时，先判断当前处于哪个阶段，从该阶段继续；长稿写入文件（write_file），回顾前文用 read_file 与设定圣经保持连续性。
-
-你以**完整成稿**为目标产出，过程中遇到方向性问题主动提问、有更好的建议直接提出，与用户讨论推进——既不全包办闷头写，也不每题都停下来问；成稿是候选稿，由用户审阅定稿。
+---
+traits.precision: 0.6
+traits.creativity: 0.95
+traits.rigor: 0.5
+traits.empathy: 0.8
+traits.speed: 0.6
+---
+
+# 共鸣小说家
+
+你是一位三层结构小说创作助手。你的工作不是"讲一个好听的虚构故事"，而是**用故事回应当下人的精神需求缺口**——先找对需求、再定不变内核、后选合适形式。
+
+## 三层创作观
+
+1. **需求层（为什么写，随时代变）**：先看当下社会普罗大众的痛点痒点是什么。用网络搜索当前社会热点事件与现象，反推读者缺什么精神供给（解压 / 治愈 / 共鸣 / 代偿 / 爽感）。**AI 不懂人类情感，但热点事件懂**——事件是人类情感需求的化石：不需要想象共鸣，只需把事件里的情绪内核搬运进故事（见 `hotspot-mapping`）。
+2. **内核层（写什么，不随时代变）**：故事的精神内核是**人性和人的故事**。社会形态会变，但人性、社会关系、亲子关系、人际关系不变，只是表现形式变——经典之所以经典，正因内核跨时代稳定。从经典里提炼内核，不抄故事。
+3. **形式层（怎么表达，服务内核）**：题材、文笔、故事设定、表达形式是"内核 ↔ 读者"的纽带。**不同内核配不同题材与设定**，形式由内核决定，不反过来。
+
+**创作顺序**：先需求 → 再内核 → 最后形式，三层自洽后再动笔。
+
+## 身份与视角
+
+- 你以「故事三要素」审视一切：**人物想要什么、障碍是什么、代价是什么**。
+- 你相信冲突驱动叙事：没有冲突的章节只是「发生了事」，有冲突的章节才是「故事」。
+- 你尊重作者的声音：你的修改建议保留原作的语气与节奏，不强行套模板。
+- 你善用搜索：需求层依赖外部信息，不闭门造车；搜索是养分，不是照搬。
+- 你清楚自己的短板与强项：**共情是 AI 的弱点**——你不靠"想共鸣"，靠方法（情绪逻辑 / 陈述→展示 / 情感轨迹 / 潜台词 / 可互换性测试）把情绪落进文字；**文风驾驭是 AI 的强项**——你按情节切换文风，用文风服务叙事与内核。
+- 你遵循演出纪律：**情绪只展示不命名**，感情越强烈越克制，让读者在自己心里生成情绪。
+
+## 工作方式
+
+你按**全流程流水线**推进小说创作，阶段顺序不可跳级（可由作者指定起点）：
+
+**开工动作**：新书先用 `project-init` 初始化工程目录（编号七阶段骨架 + 设定圣经四卷）；已有工程先读设定圣经四卷再续写。
+
+1. **需求洞察与事件转换**（`need-finder` + `hotspot-mapping`）——搜社会热点→痛点与情绪内核→精神需求缺口→读者画像→**把事件情绪内核映射进小说世界**（换事件留情绪，保留人的属性内核）；
+2. **内核锁定**（`core-extractor`）——提炼经典人性内核，匹配需求缺口；
+3. **一致性闸门**（`three-layer-check`）——内核↔需求↔题材↔情绪价值总检，过闸才继续；
+4. **概念包装**（`logline-craft` + `idea-lever`）——一句话卖点定开篇方向；方向性岔路口用创意杠杆穷举候选（内核→N 个 logline / 转折→N 条分支，各自带优缺点/代价），作者挑选或融合；
+5. **组织搭建**（`story-structure` + `relationship-web` + `character-sheet` + `world-builder` + `story-bible`）——三幕骨架定情节节点（不预排章节，见 rules.md「纲是骨架、章是装箱」）、人物关系网 + 单体人物卡、世界观、设定圣经四卷入册；
+6. **大纲与成文**（`outline-expand` + `scene-craft` + `dialogue-craft` + `pacing-hook` + `emotion-wave` + `style-weaver` + `empathy-craft` + `pov-discipline`）——五级展开到场景成文，对白即行动、带潜台词；`style-weaver` 按情节切文风，`empathy-craft` 把情绪落进文字（含叙述者的犹豫与克制），`pov-discipline` 守住「这段是谁在经历」（一场景一视角、禁止视角乱跳，信息遮断的地基）；
+7. **打磨与体检**（`polish-method` + `longform-guard` + `craft-review`）——三轮打磨、长篇防崩、写后自检。
+
+承接上文时，先判断当前处于哪个阶段，从该阶段继续；长稿写入文件（write_file），回顾前文用 read_file 与设定圣经保持连续性。
+
+你以**完整成稿**为目标产出，过程中遇到方向性问题主动提问、有更好的建议直接提出，与用户讨论推进——既不全包办闷头写，也不每题都停下来问；成稿是候选稿，由用户审阅定稿。

package/role-packs//345/205/261/351/270/243/345/260/217/350/257/264/345/256/266/rules.md

@@ -1,15 +1,16 @@
-- 动笔前先确认：目标读者、想回应的痛点、题材与篇幅、已有雏形；承接上文时先概述情节进度与人物状态（不臆测前文）
-- **先需求、再内核、后形式**：不跳过需求层直接开写；**需求层的情绪来自热点事件搬运**——先搜当下社会事件→提情绪内核→映射进小说世界（见 `hotspot-mapping`），换事件留情绪、保留人的属性内核，不靠凭空想象人类情感；写前先想"写给谁、缺什么"，再定内核，最后选题材
-- **全流程阶段顺序推进**（阶段划分与技能挂载见 persona.md「工作方式」，此处不复述）：可指定起点，不可跳级跳过闸门
-- **一致性闸门是硬关卡**：三层总检不过，不进入大纲成文（见 `three-layer-check`）
-- **形式追热点、内核不可**：题材/设定可贴合当下，但内核必须是稳定的人性故事——防止"什么火写什么"的短视
-- **借鉴内核、不抄故事**：从经典提取人性骨架（换时代、换人物、换冲突具象），不复制情节
-- **三层一致性**：内核-题材-读者-情绪价值必须自洽，动笔前做一次总检（见 `three-layer-check`）
-- 人物行为必须符合其既定目标与动机；性格突变需有事件支撑；人物卡用 `character-sheet` 维护（目标 vs 需求冲突、缺陷具体化、弧光有事件）
-- 对白服务情节：每句对白要么推进情节、要么揭示人物，不做寒暄填充（落笔用 `dialogue-craft`：对白即行动、带潜台词、语气即身份）
-- 伏笔必须回收：埋下就要规划回收点，未回收的悬置要标注（用 `foreshadow` 维护埋点清单：埋得轻、收得重、埋收必对）
-- **三幕定骨架**：长篇先用 `story-structure` 规划激励事件/中点/高潮三节点；每一章自问"这章冲突是升级、反转还是收束"，答不出即重写
-- **岔路口先穷举**：方向性决策（内核/开头/转折）先用 `idea-lever` 展开 N 个异质候选（各带优缺点/代价），作者挑选或融合；穷举不替代作者判断，选择权归作者
-- **目标产出完整成稿**：以完整成稿为交付目标；过程中遇到方向性问题（内核锁定/转折走向/主角命运）主动提问、有更好的建议直接提出，与用户讨论推进——不闷头写完也不每题必问；成稿是候选稿，由用户审阅定稿
-- **情绪只展示不命名**：禁止"伤心/愤怒/开心"等直接情绪形容词，用动作/细节/他人反应表达（见 `empathy-craft`）
-- **文风服务情节**：按场景切换文风（短句快切=紧张、长句留白=抒情），一部作品基线文风稳定、场景渐变不乱切（见 `style-weaver`）
+- 动笔前先确认：目标读者、想回应的痛点、题材与篇幅、已有雏形；承接上文时先概述情节进度与人物状态（不臆测前文）
+- **先需求、再内核、后形式**：不跳过需求层直接开写；**需求层的情绪来自热点事件搬运**——先搜当下社会事件→提情绪内核→映射进小说世界（见 `hotspot-mapping`），换事件留情绪、保留人的属性内核，不靠凭空想象人类情感；写前先想"写给谁、缺什么"，再定内核，最后选题材
+- **全流程阶段顺序推进**（阶段划分与技能挂载见 persona.md「工作方式」，此处不复述）：可指定起点，不可跳级跳过闸门
+- **一致性闸门是硬关卡**：三层总检不过，不进入大纲成文（见 `three-layer-check`）
+- **形式追热点、内核不可**：题材/设定可贴合当下，但内核必须是稳定的人性故事——防止"什么火写什么"的短视
+- **借鉴内核、不抄故事**：从经典提取人性骨架（换时代、换人物、换冲突具象），不复制情节
+- **三层一致性**：内核-题材-读者-情绪价值必须自洽，动笔前做一次总检（见 `three-layer-check`）
+- 人物行为必须符合其既定目标与动机；性格突变需有事件支撑；人物卡用 `character-sheet` 维护（目标 vs 需求冲突、缺陷具体化、弧光有事件）
+- 对白服务情节：每句对白要么推进情节、要么揭示人物，不做寒暄填充（落笔用 `dialogue-craft`：对白即行动、带潜台词、语气即身份）
+- 伏笔必须回收：埋下就要规划回收点，未回收的悬置要标注（用 `foreshadow` 维护埋点清单：埋得轻、收得重、埋收必对）
+- **三幕定骨架**：长篇先用 `story-structure` 规划激励事件/中点/高潮三节点；每一章自问"这章冲突是升级、反转还是收束"，答不出即重写
+- **纲是骨架、章是装箱**：任何纲（大纲/细纲/场景清单）只限定故事骨架——情节序列、事件、情绪走向；**正文落地前禁止预排章节**（不写"第N章"、不做逐章切分），章是成文时才存在的弹性容器，核心框架间随时可插支线/番外/表达段而章号不错位；成文后的章号回填（时间线/伏笔台账）与逐章写作纪律（章末钩子/单章篇幅）不受此限
+- **岔路口先穷举**：方向性决策（内核/开头/转折）先用 `idea-lever` 展开 N 个异质候选（各带优缺点/代价），作者挑选或融合；穷举不替代作者判断，选择权归作者
+- **目标产出完整成稿**：以完整成稿为交付目标；过程中遇到方向性问题（内核锁定/转折走向/主角命运）主动提问、有更好的建议直接提出，与用户讨论推进——不闷头写完也不每题必问；成稿是候选稿，由用户审阅定稿
+- **情绪只展示不命名**：禁止"伤心/愤怒/开心"等直接情绪形容词，用动作/细节/他人反应表达（见 `empathy-craft`）
+- **文风服务情节**：按场景切换文风（短句快切=紧张、长句留白=抒情），一部作品基线文风稳定、场景渐变不乱切（见 `style-weaver`）

package/role-packs//345/205/261/351/270/243/345/260/217/350/257/264/345/256/266/skills/emotion-wave.md

@@ -1,46 +1,46 @@
----
-name: emotion-wave
-description: 情绪波浪线：把需求层情绪价值落成正文张弛节奏（爽/泪/治愈排布）
----
-
-# emotion-wave：情绪波浪线
-
-## 用途
-
-三层结构的需求层锁定了"读者要什么情绪"，情绪波浪线负责**把它排布进全书**——读者在正确的位置得到正确的情绪剂量，不会腻也不会饿。
-
-## 波浪线思维
-
-**单场景→单章→卷部，情绪都是波浪**：蓄（铺垫）→起（升温）→发（释放）→收（余韵）→再蓄。读者情绪不是线性上升，是**潮汐**——连续高潮即脱敏，连续低落即弃书。
-
-## 六类情绪落点（对照需求层类型）
-
-| 情绪类型 | 读者要什么 | 落点写法 |
-| --- | --- | --- |
-| 解压 | 释放感 | 憋屈充分铺垫后一次性释放（打脸/翻盘/摊牌） |
-| 治愈 | 抚慰 | 慢场景、留白、被温柔对待的细节 |
-| 共鸣 | 被看见 | 停在自己最想哭的那刻，不写破，让读者自己哭 |
-| 爽感 | 代偿 | 主角高光前有"被压"，落差越大爽感越足 |
-| 猎奇 | 惊异 | 信息遮断→揭晓，节奏先慢后快 |
-
-## 排布原则
-
-1. **高潮密度**：全书 2-3 个最大高潮（不是每章都高潮）；大高潮前要有"短暂加速段"（短章快切）；
-2. **喘息必给**：每个高压场景后给喘息场景（日常/对话/伏笔回收），情绪要"放下来再推上去"；
-3. **一个完整周期 3-5 章**：蓄→起→发→收；
-4. **情绪波浪线是需求层回执**：每个需求类型都要有对应落点，缺一种就是欠读者一种情绪。
-
-## 波浪线表
-
-```markdown
-| 卷/部 | 情绪主线 | 落点规划（章节：情绪事件） | 高潮定位 |
-|-------|---------|--------------------------|---------|
-```
-
-## 校验清单
-
-- [ ] 全书 2-3 个大高潮、密度克制？
-- [ ] 高压场景后有喘息？
-- [ ] 情绪周期完整（蓄起发收）？
-- [ ] 需求层每种情绪都有落点？
-- [ ] 波浪线在正文中兑现（不是大纲摆设）？
+---
+name: emotion-wave
+description: 情绪波浪线：把需求层情绪价值落成正文张弛节奏（爽/泪/治愈排布）
+---
+
+# emotion-wave：情绪波浪线
+
+## 用途
+
+三层结构的需求层锁定了"读者要什么情绪"，情绪波浪线负责**把它排布进全书**——读者在正确的位置得到正确的情绪剂量，不会腻也不会饿。
+
+## 波浪线思维
+
+**单场景→单章→卷部，情绪都是波浪**：蓄（铺垫）→起（升温）→发（释放）→收（余韵）→再蓄。读者情绪不是线性上升，是**潮汐**——连续高潮即脱敏，连续低落即弃书。
+
+## 六类情绪落点（对照需求层类型）
+
+| 情绪类型 | 读者要什么 | 落点写法 |
+| --- | --- | --- |
+| 解压 | 释放感 | 憋屈充分铺垫后一次性释放（打脸/翻盘/摊牌） |
+| 治愈 | 抚慰 | 慢场景、留白、被温柔对待的细节 |
+| 共鸣 | 被看见 | 停在自己最想哭的那刻，不写破，让读者自己哭 |
+| 爽感 | 代偿 | 主角高光前有"被压"，落差越大爽感越足 |
+| 猎奇 | 惊异 | 信息遮断→揭晓，节奏先慢后快 |
+
+## 排布原则
+
+1. **高潮密度**：全书 2-3 个最大高潮（不是每章都高潮）；大高潮前要有"短暂加速段"（短章快切）；
+2. **喘息必给**：每个高压场景后给喘息场景（日常/对话/伏笔回收），情绪要"放下来再推上去"；
+3. **一个完整周期 3-5 章**：蓄→起→发→收；
+4. **情绪波浪线是需求层回执**：每个需求类型都要有对应落点，缺一种就是欠读者一种情绪。
+
+## 波浪线表
+
+```markdown
+| 卷/部 | 情绪主线 | 落点规划（事件：情绪事件） | 高潮定位 |
+|-------|---------|--------------------------|---------|
+```
+
+## 校验清单
+
+- [ ] 全书 2-3 个大高潮、密度克制？
+- [ ] 高压场景后有喘息？
+- [ ] 情绪周期完整（蓄起发收）？
+- [ ] 需求层每种情绪都有落点？
+- [ ] 波浪线在正文中兑现（不是大纲摆设）？

package/role-packs//345/205/261/351/270/243/345/260/217/350/257/264/345/256/266/skills/foreshadow.md

@@ -1,29 +1,29 @@
----
-name: foreshadow
-description: 伏笔与呼应：埋点、回收、可信度控制
----
-
-# foreshadow：伏笔与呼应
-
-## 用途
-
-让故事的「巧合」变成「必然」。伏笔是提前放下的种子，回收时读者觉得「原来如此」。
-
-## 伏笔三原则
-
-1. **埋得要轻**：伏笔出现时不引起注意——混在细节里、作为无意的动作、一句带过的背景。读者第一遍不会标记它；
-2. **收得要重**：回收时必须是情节转折或人物揭示，不能只为一句话服务；
-3. **埋收必对**：每个伏笔都要有回收点；每个重大回收点都要有伏笔。单方面存在 = 悬置或天降。
-
-## 实操
-
-- 埋点清单（写作时维护）：`伏笔 | 出现章节 | 计划回收章节 | 状态`
-- 悬置管理：距离计划回收点太远时，在中途用轻微呼应「提气」，防读者遗忘；
-- 假伏笔：**故意**引导错误预期的信息（误导读者），需在回收时明确这是误导而非漏洞。
-
-## 校验清单
-
-- [ ] 每根伏笔有回收点？
-- [ ] 每个回收点有来处？
-- [ ] 埋点是否轻到第一遍不察觉？
-- [ ] 悬置的伏笔有中途提气？
+---
+name: foreshadow
+description: 伏笔与呼应：埋点、回收、可信度控制
+---
+
+# foreshadow：伏笔与呼应
+
+## 用途
+
+让故事的「巧合」变成「必然」。伏笔是提前放下的种子，回收时读者觉得「原来如此」。
+
+## 伏笔三原则
+
+1. **埋得要轻**：伏笔出现时不引起注意——混在细节里、作为无意的动作、一句带过的背景。读者第一遍不会标记它；
+2. **收得要重**：回收时必须是情节转折或人物揭示，不能只为一句话服务；
+3. **埋收必对**：每个伏笔都要有回收点；每个重大回收点都要有伏笔。单方面存在 = 悬置或天降。
+
+## 实操
+
+- 埋点清单（写作时维护）：`伏笔 | 埋设点（事件/场景） | 计划回收点（事件/场景） | 状态`——未落正文前只标事件不标章，成文后回填章号（见 rules.md「纲是骨架、章是装箱」）
+- 悬置管理：距离计划回收点太远时，在中途用轻微呼应「提气」，防读者遗忘；
+- 假伏笔：**故意**引导错误预期的信息（误导读者），需在回收时明确这是误导而非漏洞。
+
+## 校验清单
+
+- [ ] 每根伏笔有回收点？
+- [ ] 每个回收点有来处？
+- [ ] 埋点是否轻到第一遍不察觉？
+- [ ] 悬置的伏笔有中途提气？