kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/zh/reference/tools.md

@@ -64,11 +64,17 @@ MCP 和插件工具会以名称和简短说明公告。需要调用时，先用
 
 在服务端的 transcript 回退检索中，`sort: "newest"` 和 `"oldest"` 按时间戳排列命中文本，跨页用稳定来源 ID 处理同时间命中；缺失的时间戳按零排序。导航先构建到固定来源水位，确认当前可见性，因此冷态大会话可能先返回空的 `navigation_building` 准备页，再返回命中。用 `next_cursor` 继续；投影准备和原文读取共享每次调用的预算。导航就绪后，最新优先检索会直接读取近期文本片段，不再从 wire 开头扫起。
 
-默认的 `sort: "relevance"` 只在当前有界页收集到的命中之间按词法得分排序：完整查询命中和更多词组命中提高分值，再以较新时间戳和稳定 ID 打破平分。跨页按最新时间优先扫描，并非全局相关度排序；后续页可能有更相关的命中。部分页会在 coverage 中披露 `page_local_relevance`。新版扫描 cursor 绑定查询、来源指纹和导航 generation；来源追加、undo、clear 或改写都会使其失效，失效后应重新发起查询。旧版扫描 cursor 仍能按来源顺序续扫，但会提示重新查询以使用排序导航。
+默认的 `sort: "relevance"` 只在当前有界页收集到的命中之间按词法得分排序：完整查询命中和更多词组命中提高分值，再以较新时间戳和稳定 ID 打破平分。跨页按最新时间优先扫描，并非全局相关度排序；后续页可能有更相关的命中。部分页会在 coverage 中披露 `page_local_relevance`。
+
+新版扫描 cursor 固定本次查询在开始时的历史范围；来源正常追加后仍可翻页，但新增内容不在本次结果里，要查看它们需重新查询。已固定的来源内容改变、查询条件改变，或共享导航已推进到本次范围之后时，按返回提示重新发起查询。旧版扫描 cursor 仍按原兼容规则续读。
+
+`HistorySearch` 在读取过程中发现来源发生变化时返回 `source_changed`，等写入方稳定后重新发起查询即可。这与你确实带了 cursor、而它与来源或查询不再匹配是不同的情况，那种情况提示去掉 cursor 重新发起。
 
 省略新版的 scope 和 mode 参数时，会按当前 session 和 `auto` 模式处理。不要假定旧版默认值，请读取响应中的 `scope_used` 和 `mode_used`；如果结果范围太窄，按 `expand_hint.next_call` 的建议改用 `scope: "workspace"` 重试。
 
-不知道关键词时，用 `HistoryList` 浏览短轮次摘录或旧会话的 Agent 目录。轮次条目的 `ref` 传给 `HistoryRead` 会按来源 block 读取整轮；也可用 `turn` 或 `step_id` 选择有界的轮次、步骤 block。导航目录尚在构建时，coverage 会披露已扫描范围。已知步骤可用 `HistoryRead({"step_id":"t42.3"})`。Search 命中文本块时，`HistoryRead({"ref":"<hit.ref>"})` 从命中附近开始读。每个 block 返回自己的 `ref` 和 UTF-16 `range`；用 `cursor` 续读，若 cursor 失效，可用 block 的 `ref` 加上一次的 `range.end` 作为 `start_char` 重开。来源撤销或失效会明确报错，不会跳到同号的新轮次。已有的 v1 Read cursor 仍按旧 JSON 形式续页；用 ref、turn 或 step_id 重新发起可切换到 blocks。
+不知道关键词时，用 `HistoryList` 浏览短轮次摘录或旧会话的 Agent 目录。轮次条目的 `ref` 传给 `HistoryRead` 会按来源 block 读取整轮；也可用 `turn` 或 `step_id` 选择有界的轮次、步骤 block。导航目录尚在构建时，返回的是 `partial` 准备页，会披露已扫描范围并带上 cursor——用它继续，而不是把当前列表当成完整结果。已知步骤可用 `HistoryRead({"step_id":"t42.3"})`。Search 命中文本块时，`HistoryRead({"ref":"<hit.ref>"})` 从命中附近开始读。每个 block 返回自己的 `ref` 和 UTF-16 `range`；用 `cursor` 续读，若 cursor 失效，可用 block 的 `ref` 加上一次的 `range.end` 作为 `start_char` 重开。来源撤销或失效会明确报错，不会跳到同号的新轮次。已有的 v1 Read cursor 仍按旧 JSON 形式续页；用 ref、turn 或 step_id 重新发起可切换到 blocks。
+
+`HistoryRead` 正常返回 `partial` 时，会带上已扫描到的 block 和续读 cursor。`no_match` 表示扫描已完成、这个定位没有内容。`source_pending` 表示持久化转录末尾是一条未写完的记录，还无法判断该定位是否命中，等写入方稳定后重试。导航目录仍在准备时同样是 `partial`，但带的是准备 cursor 和进度；此时的空 block 列表表示「还没扫到」而不是「没有」，先用该 cursor 续读再判断。若该 Agent 的持久化转录整体不可用，错误会指向 `HistoryList` 的 `kind: "agents"` 去核对 agent id。来源已变化时返回错误，不会读到另一轮内容。
 
 只检索跨线程消息时，使用 `HistorySearch({"query":"交接","scope":"peer"})`。它搜索当前工作区内的双向往来，也可指定经批准访问的 `workspace_id`；可选 `session_id` 限定一个会话。Peer 检索复用既有词法匹配模式，但始终按最新时间优先排列：省略 `sort` 或使用 `"newest"`。它排除子 Agent 和普通用户输入，不接受 `source: "transcript"`；指定 Agent 时只接受 `agent_id: "main"`。结果来源为 `source: "mailbox"`，命中带有 `communication` 元数据，包含消息身份、两端和投递状态，不会编造会话轮次号或 HistoryRead ref。完整正文和导航身份见[沟通记录 REST 读取](../server/rest-api.md#沟通记录)。部分页或空页应使用 `next_cursor` 继续读取；此视图覆盖邮箱仍保留的记录，不包含旧版本已淘汰的更早消息。
 
@@ -76,7 +82,7 @@ MCP 和插件工具会以名称和简短说明公告。需要调用时，先用
 
 ## 网络类
 
-两个工具都由 Kiki 内置的搜索与抓取模块支撑，随产品一起安装，不需要额外的安装步骤。免密钥的仓库搜索 lane 和 URL 抓取链无需配置即可使用；通用网页搜索需选择其他 lane。配置入口见 [`nb_search`](../configuration/config-files.md#nb-search)。
+两个工具都由 Kiki 内置的搜索与抓取模块支撑，随产品一起安装，不需要额外的安装步骤。通用网页搜索和 URL 抓取无需配置或 API 密钥即可使用。配置入口见 [`nb_search`](../configuration/config-files.md#nb-search)。
 
 | 工具 | 默认审批 | 说明 |
 | --- | --- | --- |
@@ -87,7 +93,7 @@ MCP 和插件工具会以名称和简短说明公告。需要调用时，先用
 
 通过 Kiki 内置的 `nb-search` 模块进行搜索。最小调用为 `{ "query": "搜索词" }`，对应 `action: "run"`，其余字段沿用 `[nb_search]` 默认值。`query` 可以是单个字符串或字符串数组。
 
-零配置下，默认使用 `github.repositories`，只检索 GitHub 仓库，而非全网。查阅库文档请显式选择 `context7.docs`（返回 typed 结果）；免密钥通用网页检索可显式选择 `duckduckgo.search`，但公共 HTML 端点可能触发 CAPTCHA。需要可靠的通用检索时，建议配置 `exa.search` 等提供商。若显式删除默认 lane，且调用时未指定 `lane`、`lanes` 或 `preset`，工具仍会拒绝运行；显式选择会覆盖默认值，选择无效或不可用时也不会悄悄换成其他 provider。
+零配置下，默认使用 `duckduckgo.search` 检索通用网页，无需注册、API 密钥或手选 lane。公共 HTML 端点可能触发验证或限流；等待后再试，或显式选择其他已配置的来源。这些失败会报告错误，不会伪装为空结果。仓库检索和库文档可显式选择 `github.repositories`、`context7.docs`（后者返回 typed 结果）。若显式删除默认 lane，且调用时未指定 `lane`、`lanes` 或 `preset`，工具仍会拒绝运行；显式选择会覆盖默认值，选择无效或不可用时也不会悄悄换成其他 provider。
 
 `run` 接受以下几组真正影响行为的参数：
 
@@ -206,7 +212,43 @@ Plan 模式下，`Write` 与 `Edit` 只能修改当前计划文件。`BoardWrite
 
 当一条修改或归档提议留待审阅时，原条目在决定之前保持原有内容并继续生效。接受提议才会对原条目执行相应的修改或归档；丢弃只移除这条提议，原条目不受影响。如果原条目在提议之后已经变化，该决定会被拒绝，提议仍会保留，并提示你重新读取该条目。
 
-三个范围的模型、审批收件箱、可撤销的改动历史和 `/memory` 页，见[记忆](../guides/memory.md)。
+### 写入一条条目
+
+`MemoryWrite` 每次调用只做一个 `action`：
+
+- **`create`**——真正的新主体。需要 `type`、`title`、`body` 和 `reason`，不传 `id` 与 `expected_revision`。不显式指定 `scope` 时落到当前绑定的角色，没有角色则落到工作区。
+- **`update`**——在原条目上修订，保留它的 id 和仍然成立的条件。`body` 是完整的新正文，不是补丁。
+- **`supersede`**——写出一条有自己 id 的替代条目，等替代条目生效后才让前驱退出。规则真的变了时用它，两版内容都留得住。
+- **`archive`**——让条目退出，保留已存正文。只传目标和 `reason`；`type`、`title`、`body` 会被忽略。
+
+`update`、`supersede` 和 `archive` 必须同时给 `id` **和** `expected_revision`——取自读取结果、搜索条目或此前的回执。缺它时调用会被拒绝，而不是套用到一个你没看过的版本上。同一个 id 可能同时存在于多个可见范围：显式 `scope` 会限定查找，省略时必须唯一命中，否则调用会列出候选，而不是替你挑一个。
+
+两个可选字段记录内容依据什么，两者都是「省略或保留」而不是「给默认值」：
+
+- **`basis`**——`{ kind, note, refs? }`，`kind` 为 `human`、`observed`、`derived` 或 `unknown`。它记录内容的证据，与系统自动记录的最后写入者相互独立；恰好在你的轮次里运行的写入不会自动算成你亲口说的。`update` 时省略它，只有在 type、title、body 都没变的情况下才保留原依据；改了其中任何一项却没有给出新依据，这条记忆会降为 `{ kind: 'unknown' }` 并附 `content changed without refreshed attribution` 警告，让过期的依据不会比它描述过的正文留得更久。
+- **`validity`**——`{ check, until? }`，用于会变的内容。`update` 时省略表示保留原值，显式传 `null` 才是清除。没有 `validity` 并不意味着内容永远成立。
+
+`covered_by` 只用于 `archive`，取同一范围中保留条目的 `{ id, expected_revision }`，该条目需处于生效状态且内容完整覆盖目标。真正执行归档时会在写锁内重新核验这个依赖，所以对着已经变了的替代条目归档会失败并返回 `covered_target_changed`，而不是丢掉那条规则。
+
+成功调用会连同完整条目（已存的或待审的）一起返回一个 `outcome`：
+
+| outcome | 含义 |
+| --- | --- |
+| `applied` | 写入已生效。返回的条目就是当前内容——不必为了确认再读一次。 |
+| `pending` | 写入是一条待你决定的提议。它指向的原条目未变，仍然生效。 |
+| `unchanged` | 这次提交的内容与已存下来的没有任何差异。没有产生新版本，也没有可撤销的操作。 |
+
+`unchanged` 以及重复提交的同一待审提议，`operation_id` 都为 `null`——这正是重复提议被识别出来、而不是越堆越多的原因。
+
+失败以结构化错误返回，带 `code`、说明和恢复指引：`missing_revision`、`revision_conflict`、`not_found`、`ambiguous_target`、`scope_mismatch`、`covered_target_changed`、`duplicate_title` 等。正确的应对是按 recovery 处理、必要时重新读取、然后做一次修正后的尝试；这些 code 存在的意义就是阻止「写不进去就另建一条」绕开问题。你看不到的目标会被报成不可用，而不是被别人代写。
+
+### 搜索与读取
+
+`MemorySearch` 可以用 `mode: "search"`（默认，需要 `query`）或 `mode: "list"`（不带 query，浏览清单）。`page_size` 取 1–20，search 默认 8、list 默认 20；翻页只带 `cursor`，改动任何过滤条件都会让它失效。每一项都带完整标题、type、status、revision、所属范围、可直接复制进 `MemoryWrite` 的 `target`、`basis_kind`，以及 `expired` / `recheck` / `unrecorded` 三态的 `applicability`。响应里的 `coverage` 说明实际查了哪些范围和状态、有没有跳过什么。只要 `exhausted` 为 false，空准备页也要接续；扫描预算不会截掉剩余源内容。搜索相关性排序针对每个有界源片段。search 额外给最多 200 字符的 `snippet` 和 `score`，list 两者都没有。片段会省略条件，所以要依赖、合并或替换一条记忆前先完整读出来。
+
+`MemoryRead` 在 `id` 和 `ids`（最多 10 个）中恰好取一个，默认读取生效、已归档和被替代的条目，只有显式传 `include_pending: true` 才包含待审提议。结果是完整条目而不是摘要，并带所属范围、target 字段和适用性，所以一次读取可以直接作为 `update` 的来源。
+
+三个范围的模型、审批收件箱、可撤销的改动历史和 `/memory` 页，见[记忆](../guides/memory.md)。同一份数据的 HTTP 入口见[服务端 API](../server/rest-api.md#记忆)。
 
 ## 协作类
 
@@ -227,7 +269,7 @@ Plan 模式下，`Write` 与 `Edit` 只能修改当前计划文件。`BoardWrite
 
 Kiki 桌面端和 `kiki` CLI/TUI 会给主 `agent` profile 始终提供 `AgentRun`、`AgentList` 和 `AgentSend`。这些工具只管理调用方的直属子 Agent——用 `AgentRun` 里可选的 `name`，或用 agent id。它们不需要实验开关。内置的 [`coder` 与 `explore` profile](../customization/agents.md) 没有这组工具。
 
-`AgentList` 返回这些直属子 Agent，不会列出孙级。`AgentSend` 的投递语义是尽早送达：子 Agent 正在运行时，消息会在下一个 step 边界被 steer 进其活跃 turn；子 Agent 空闲（或竞态恰逢 turn 结束）时保持排队，到下一步开始时才读这条消息。
+`AgentList` 返回这些直属子 Agent，不会列出孙级。`AgentSend` 把消息排进某个直属子 Agent 的邮箱，之后发生什么取决于该子 Agent 的状态——细节见本页下方 `AgentSend` 条目。
 协作类工具负责 Agent 间协作、用户交互和 Skill 调用。
 
 | 工具 | 默认审批 | 说明 |
@@ -238,7 +280,30 @@ Kiki 桌面端和 `kiki` CLI/TUI 会给主 `agent` profile 始终提供 `AgentRu
 | `AskUserQuestion` | 自动放行 | 向用户提问以获取结构化输入 |
 | `Skill` | 自动放行 | 调用已注册的 inline Skill |
 
-**`AgentRun`** 将子任务委托给子 Agent。必填参数为 `prompt` 和 `description`（3–5 个词的短任务描述，用于界面展示）。可选启动参数包括 `profile`（省略时由显式配置的 `[subagent].default_profile` 选择对应 profile；该配置键不存在时使用内建通用 subagent 提示词；显式留空时必须指定目标）、`profile_file`（显式 role Markdown 文件，绝对路径或工作区相对路径；它是 role 定义而非共享提示词模板，与 `profile`、`route`、`resume` 互斥）、`background`（省略时 main 默认后台、subagent 默认前台；显式 `false` 同步等待）、`name`（会话内唯一的句柄，只含小写字母、数字和下划线，`root` 保留）、`route`、`model_alias`、`effort`，以及在 `resume` 时显式修改模型用的 `allow_model_change`。另有两个可选参数按这一次绑定覆盖子 Agent 的工具：`tools` 替换已解析出的工具选择（只写 `*`，或写 `["*", ThreadRead]`，会保留普通工具并额外加入该 opt-in；有限名单仍然有限），`disallowed_tools` 增加一层调用级 deny。两者都省略时，新建子 Agent 使用配置默认，`resume` 保留已保存的覆盖；显式传值替换该层，`disallowed_tools: []` 只清掉调用级 deny，不会清除 profile、祖先或 route 的 deny。两者都要求原生 executor：不支持的外部 executor 会在子 Agent 启动前报错。新派生项按此顺序选模型：具体 `model_alias` 参数 → 生效 profile / route / caller lease pin → 显式配置的 `[subagent].default_model`。这些来源都不存在时以 `model.not_configured` 失败，不会创建子 Agent。调用方模型与主 Agent 的 `default_model` 均不是静默回退来源。`AgentRun` 拒绝 `model_alias: "inherit"`：请写具体的已配置模型名，或省略参数以使用目标默认模型。在 subagent profile、route、caller lease 中写 `model_alias: inherit`，仍会绑定调用方当前已解析的模型与有效思考强度；工具显式 `effort`，或 profile、route、lease、匹配的 `model_profiles` 条目上适用的 effort pin 优先。其他情况下，effort 按工具 `effort` → 匹配的 `model_profiles` 档位 → 所绑定模型与 profile pin 匹配时的 `thinking_effort` → 所绑定模型自身的默认档位解析。显式传入未知的具体 `model_alias` 会报错；main agent 没有调用方，其 profile 不可使用 `inherit`。`resume` 按名称或 agent id 继续已有直属子 Agent，与 `name`、`profile`、`profile_file` 和 `route` 互斥。同时省略 `model_alias` 和 `effort` 会保留已保存的绑定，也可以传入 `effort` 让下一次空闲运行使用。`AgentRun` 恢复时同样拒绝 `model_alias: "inherit"`；显式换模请写具体模型名。省略 `model_alias` 会保留已保存的模型；切换到不同规范模型必须传 `allow_model_change: true`，而解析到同一规范模型则不产生模型变化。`preferred_models`、`discouraged_models`、`preferred_efforts` 与 route / caller lease pin，对满足硬域且可执行的绑定产生 advisory。`allowed_models`、`deny_models`、`allowed_efforts` 在 profile、lease、树策略与匹配 model-profile 中为硬规则；绑定、人工切换与恢复均拒绝违规。机器级 deny、不可用能力、换模确认与 executor / thread 限制也仍是硬错误。外部 executor 不支持修改恢复的 thread 绑定时会报错，不会重建 thread 或 executor。Agent 任务默认 2 小时超时，通过 `[subagent] timeout_ms` 或 `KIKI_SUBAGENT_TIMEOUT_MS` 配置全局限制（`0` 表示禁用），print 模式默认无超时；不提供单次调用 timeout 或任意供应商参数透传。前台模式下父 Agent 等待结果；后台模式立即返回任务 ID，结果会通过之后的合成 User 消息自动送达。TUI 会把同一步中的多个前台调用合并展示，并显示状态与耗时。完整 profile 与生命周期契约见 [Agent 与子 Agent](../customization/agents.md)。
+**`AgentRun`** 将子任务委托给子 Agent。必填参数为 `prompt` 和 `description`（3–5 个词的短任务描述，用于界面展示）。
+
+| 参数 | 作用 |
+| --- | --- |
+| `profile` | 执行子任务的 agent profile。省略时由显式配置的 `[subagent].default_profile` 选择；该配置键不存在时使用内建通用 subagent 提示词；显式留空则必须指定目标 |
+| `profile_file` | role Markdown 文件，绝对路径或工作区相对路径。它是 role 定义而不是共享提示词模板，与 `profile`、`route`、`resume` 互斥 |
+| `background` | 省略时 main 默认后台、subagent 默认前台；显式 `false` 同步等待 |
+| `name` | 会话内唯一的句柄，只含小写字母、数字和下划线，`root` 保留 |
+| `route` | 用 profile route 代替具名 profile |
+| `model_alias` | 子 Agent 使用的模型，完整解析顺序见[模型选择](./model-vocabulary.md#绑定规则) |
+| `effort` | 该子 Agent 的思考强度 |
+| `allow_model_change` | 在 `resume` 时把已有子 Agent 换到另一个模型需要显式传它 |
+| `tools` | 替换本次绑定已解析出的工具选择。只写 `*`，或写 `["*", ThreadRead]`，会保留普通工具并额外加入该 opt-in；有限名单仍然有限 |
+| `disallowed_tools` | 增加一层调用级 deny。传 `[]` 只清掉这一层，不会清除 profile、祖先或 route 的 deny |
+
+`tools` 和 `disallowed_tools` 都省略时，新建子 Agent 使用配置默认，`resume` 保留已保存的覆盖。两者都要求原生 executor；不支持它们的外部 executor 会在子 Agent 启动前报错。
+
+**模型与档位。** 新派生项按此顺序选模型：`model_alias` 参数 → 生效 profile、route 或 caller lease 上的 pin → 显式配置的 `[subagent].default_model`。这些来源都不存在时以 `model.not_configured` 失败，不会创建子 Agent——调用方模型与主 Agent 的 `default_model` 都不是静默回退来源。`AgentRun` 拒绝 `model_alias: "inherit"`，请写具体的已配置模型名或省略该参数；subagent profile、route、caller lease 里仍可写 `model_alias: inherit` 跟随调用方。其他情况下，思考强度按工具 `effort` → route 上锁定的 effort（route 未锁定时改用 caller lease 的）→ 匹配的 `model_profiles` 档位 → 所绑定模型与 profile pin 匹配时的 `thinking_effort` → 所绑定模型自身的默认档位解析。未声明档位时，能力明确不支持思考的模型使用 `off`；思考模型没有可解析默认档位时仍需显式选择。未知能力不视为 `off`。完整规则见[绑定解析](../customization/agents.md#具名-profile-route-实验功能)。
+
+`preferred_models`、`discouraged_models`、`preferred_efforts` 是建议，选到列表之外的模型仍然能跑。`allowed_models`、`deny_models`、`allowed_efforts` 是硬限制：绑定、人工切换与恢复都会拒绝违规，机器级 deny 与不可用能力同样如此。
+
+**恢复。** `resume` 按名称或 agent id 继续已有直属子 Agent，与 `name`、`profile`、`profile_file`、`route` 互斥。同时省略 `model_alias` 和 `effort` 会保留已保存的绑定，也可以传 `effort` 让下一次空闲运行使用。恢复时同样拒绝 `model_alias: "inherit"`——显式换模请写具体模型名，解析到不同模型时再加 `allow_model_change: true`。外部 executor 无法修改已恢复 thread 的绑定时会报错，不会重建 thread。
+
+**超时与模式。** Agent 任务默认 2 小时超时，通过 `[subagent] timeout_ms` 或 `KIKI_SUBAGENT_TIMEOUT_MS` 配置全局限制（`0` 表示禁用），print 模式默认无超时；不提供单次调用 timeout。前台模式下父 Agent 等待结果；后台模式立即返回任务 ID，结果会通过之后的合成 User 消息送达。TUI 会把同一步中的多个前台调用合并展示，并显示状态与耗时。完整 profile 与生命周期契约见 [Agent 与子 Agent](../customization/agents.md)。
 
 `AgentRun` 的默认值按调用方的运行时身份决定，不取决于目标 profile；每次 `resume` 重新应用同一规则，goal mode 也不改变默认值。Main 省略 `background` 或显式传 `true` 时，要求 `TaskList`、`TaskOutput`、`TaskStop` 可用；不可用则在启动前报错，提示启用这些工具或显式用 `background:false` 同步重试，不会静默回退到前台。Main 前台调用遇到 steer / Send now 时，等待会转入后台而不停止子 Agent；下一安全步骤读取新输入，子 Agent 完成后仍自动通知。普通排队消息不会触发转后台。停止当前 main 轮次不等于停止已脱离等待的子 Agent；需要停止某个跟踪任务时，显式调用 `TaskStop`。
 
@@ -248,9 +313,9 @@ Kiki 桌面端和 `kiki` CLI/TUI 会给主 `agent` profile 始终提供 `AgentRu
 
 **`AgentList`** 列出当前 Agent 的直属子 Agent。可选参数 `include_finished` 默认为 false。实例正在启动、运行或取消时，即使之前的后台任务已完成或超时，也会以 `running` 保持可见。执行器处于故障状态时显示 `errored`；其他情况采用最近一次后台任务状态，没有任务记录则为 `untracked`。传 `true` 才会额外包含已结束或出错的子 Agent。最多返回 50 条，运行中的排在前面；装不下的数量记在 `omitted`。每条记录含 `agent_id`、可选的 `name` 与 `profile`，以及 `status`。`running` 不代表一定有跟踪中的后台任务或之后的完成通知；用 `TaskList` 查看跟踪中的工作。
 
-**`AgentSend`** 把非空的 `message` 排进直属子 Agent 的邮箱。`target` 可以是 `AgentRun` 当时传入的 `name`，也可以是 agent id。子 Agent 正在运行时，消息会在下一个 step 边界被 steer 进其活跃 turn，尽早送达；空闲且可恢复的子 Agent 会以该消息启动一次新的运行，该次运行完成时父 Agent 照常收到完成通知。匹配到多个直属子 Agent、或一个都匹配不到时调用失败——先用 `AgentList` 再换成不含糊的值重试。邮箱满了说明未读排队消息太多，等子 Agent 消化一些再发。
+**`AgentSend`** 把非空的 `message` 排进直属子 Agent 的邮箱。`target` 可以是 `AgentRun` 当时传入的 `name`，也可以是 agent id。子 Agent 以 native 方式运行时，消息会在下一个 step 边界被 steer 进其活跃 turn；跑在外部执行器上的子 Agent 无法被 steer，消息会等到它下一次运行开始时才被取走；空闲且可恢复的子 Agent 则以该消息启动一次新的运行，该次运行完成时父 Agent 照常收到完成通知。匹配到多个直属子 Agent、或一个都匹配不到时调用失败——先用 `AgentList` 再换成不含糊的值重试。邮箱满了说明未读排队消息太多，等子 Agent 消化一些再发。
 
-返回结果包含 `message_id` 和 `queued` 或 `delivered` 状态。`queued` 表示邮箱已接收，但消息尚未加入收件方上下文。收件方上下文持久化且邮箱确认投递后，发送者的 transcript 会记录投递回执，GUI 的「待送达」标记随之清除，即使没有打开子 Agent 的 transcript。回执在页面重载和历史回放后仍然有效；它只确认送达，不代表子 Agent 已按消息采取行动。
+返回结果包含 `message_id` 和 `queued` 或 `delivered` 状态。`queued` 表示邮箱已受理；投递可以并发完成，所以它并不说明这条消息此刻一定还没进上下文。`delivered` 只表示消息已送达收件方上下文，不代表子 Agent 已按它采取行动。`resumed: true` 表示确实观测到一次新运行启动；没有观测到运行启动时该字段会被省略，所以看不到它并不等于否定答案。收件方上下文持久化且邮箱确认投递后，发送者的 transcript 会记录投递回执，GUI 的「待送达」标记随之清除，即使没有打开子 Agent 的 transcript。回执在页面重载和历史回放后仍然有效。
 
 **`AskUserQuestion`** 以结构化多选题的形式向用户提问，适用于需要消歧或选择方案的场景。`questions` 参数接受 1–4 道题，每道题需提供 `question`（以 `?` 结尾）、`options`（2–4 个选项，每项含 `label` 和 `description`）以及可选的 `header`（最多 12 字符）和 `multi_select`（默认 false）。系统自动附加"其他"选项。`background` 为 true 时启动后台问题任务并立即返回任务 ID。宿主未实现交互式提问能力时返回失败提示，Agent 应改为在文本回复中直接提问。
 

package/dist/docs/zh/release-notes/changelog.md

@@ -6,7 +6,7 @@ outline: 2
 
 本页记录 Kiki 每个版本的变更内容。
 
-::: info 说明
+::: tip 说明
 本页早期版本的条目来自上游 Kimi Code 项目，其中出现的命令与变量名反映当时命名。命令的现行名是 `kiki`；环境变量以 [环境变量](../configuration/env-vars.md) 页列出的确切名称为准。
 :::
 
@@ -15,7 +15,6 @@ outline: 2
 ### 优化
 
 - web: 设置页新增 「实验室」标签页，上线「多标签侧边栏开关」功能；开启后侧边栏显示 Open / Done / Workspaces 标签页。
-- 做了若干细节优化和内部改进。更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。
 
 ## 0.37.1（2026-08-18）
 
@@ -47,7 +46,6 @@ outline: 2
 - web: 修复 macOS 上输入框中 Ctrl+K 误打开会话搜索的问题，会话搜索现仅响应 Cmd+K。
 - web: 修复 Background Agent 面板显示数量和状态不对的问题。
 - web: 修复把复制的文件夹粘贴进输入框会导致上传报连接错误的问题，现在文件夹会被直接跳过。
-- 修复了一些已知问题，并做了若干细节优化。更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。
 
 ## 0.36.1（2026-08-14）
 
@@ -59,10 +57,6 @@ outline: 2
 
 - web: 优化输入框的 Plan、Goal、Swarm 开关，现收进了输入框旁的 + 号菜单。
 
-### 修复
-
-- 修复了一些已知问题，并做了若干细节优化。更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。
-
 ## 0.36.0（2026-08-13）
 
 ### 新功能
@@ -93,7 +87,6 @@ outline: 2
 - 修复未信任工作区可在信任确认前植入同名 `fd`/`stty` 可执行文件的风险；信任提示现在展示项目 MCP 的启动目标，并默认拒绝信任。
 - 修复在严格的 OpenAI 兼容供应商（如 DeepSeek）下，模型思考阶段打断轮次后，后续每轮请求都报 400 错误的问题。
 - 修复 API 请求失败自动重试期间按 Ctrl+C 无反应的问题。
-- 修复了一些已知问题，并做了若干细节优化。更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。
 
 ## 0.35.0（2026-08-12）
 
@@ -107,7 +100,6 @@ outline: 2
 - 修复 coder 子 Agent 默认可继续派生子 Agent 的问题。
 - 修复压缩后 token 数显示偏低的问题，现在与会话中看到的数字一致。
 - 修复 Windows 上的两处二进制植入风险。
-- 修复了一些已知问题，并做了若干细节优化。更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。
 
 ## 0.34.0（2026-08-06）
 

package/dist/docs/zh/server/acp.md

@@ -28,7 +28,7 @@ kiki acp
 
 ## ACP 方法覆盖
 
-规范把方法分为**稳定**面和仍在演化的**不稳定**面。两部分稳定性保证完全不同——稳定面是任何生产 ACP 客户端都会用到的方法，不稳定面覆盖实验性扩展（inline-edit 预测、document 缓冲区同步、provider 管理、elicitation 等），因此分开列出。任何正常 agent 流程所需的方法（initialize → auth → new/load/resume → prompt → cancel + 文件 I/O + 工具审批）都已实现。
+规范把方法分为**稳定**面和仍在演化的**不稳定**面，因此分开列出。任何正常 agent 流程所需的方法——initialize → auth → new/load/resume → prompt → cancel，加上文件 I/O 与工具审批——都已实现。
 
 ### 稳定面 agent-side — IDE → agent
 

package/dist/docs/zh/server/ide.md

@@ -92,7 +92,7 @@ Paseo 的通用 ACP 适配层不会帮你走登录流程，所以请先完成终
 
 - **会话立刻被中断 / IDE 提示 "agent exited"**：通常是 `command` 路径不对或 kiki 没登录。先在终端跑一次 `kiki acp` 验证：如果阻塞等待标准输入则说明 CLI 本身没问题，问题在 IDE 配置；如果立刻报错则按报错提示处理（多数是没 `/login`）。
 - **IDE 显示 "auth required"**：表示 CLI 没有可用的鉴权令牌。退出 IDE，在终端执行 `kiki` 完成登录后再启动 IDE 即可。
-- **MCP 工具看不到**：参考 [`kiki acp`](./acp.md) 中的能力表确认 IDE 配的 MCP 传输类型是否被支持。当前 Kiki 的 ACP 适配层支持 `http`、`stdio` 与 `sse` 三种传输方式；`acp` 传输的 MCP server 会被静默丢弃并在日志中给出 warn。
+- **MCP 工具看不到**：`kiki acp` 适配层接受 `http` 与 `sse` 传输；`stdio` 只有在 IDE 用 `--allow-client-stdio-mcp` 启动时才接受。`acp` 传输的 server 会被丢弃，并在日志里给出 warn。详见 [MCP 转发](./acp.md#mcp-转发)。
 
 ## 下一步
 

package/dist/docs/zh/server/local-server.md

@@ -18,7 +18,7 @@ kiki serve --ensure --workspace . --json
 kiki serve --stop
 ```
 
-不带模式时，`serve` 在前台运行 daemon；`--query --json` 只检查当前实例；`--ensure` 连接已有健康实例或启动新实例；`--stop` 停止所选 home 下当前可达的实例。活跃实例身份无法验证时，须先停止或升级它，Kiki 才会启动其他实例。`--idle-exit` 默认是 `30m`；活跃客户端 lease（租约：定期续期，表示客户端仍在使用 daemon）和运行中的派遣会让服务保持运行。显式 `--idle-exit 0ms` 让新启动的 daemon 持续到显式停止。工作区信任后，TUI 自动执行同样的连接或启动逻辑。
+不带模式时，`serve` 在前台运行 daemon；`--query --json` 只检查当前实例；`--ensure` 连接已有健康实例或启动新实例；`--stop` 停止所选 home 下当前可达的实例。活跃实例身份无法验证时，须先停止或升级它，Kiki 才会启动其他实例。`--idle-exit` 默认是 `30m`；活跃客户端 lease（定期续期，表示客户端仍在使用 daemon）和运行中的派遣会让服务保持运行。显式 `--idle-exit 0ms` 让新启动的 daemon 一直运行到你手动停止。工作区信任后，TUI 自动执行同样的连接或启动逻辑。
 
 ## 运行兼容性的前台服务
 
@@ -50,14 +50,14 @@ Stop:    Ctrl+C
 
 - **REST**：请求头 `Authorization: Bearer <token>`。
 - **Kiki GUI**：启动横幅里的地址自带 `#token=` 片段，浏览器打开后自动完成登录；该片段不会发送到服务端。
-- **WebSocket**：能自定义请求头的客户端用 `Authorization: Bearer`；浏览器等不能自定义头的客户端改用子协议（WebSocket 握手时声明的协议名）`kimi-code.bearer.<token>`（历史协议名，沿用自上游 Kimi Code 时代，为兼容保留）。
+- **WebSocket**：能自定义请求头的客户端用 `Authorization: Bearer`；浏览器等不能自定义头的客户端，把 token 放进握手子协议 `kimi-code.bearer.<token>`。
 
-远端 owner token 泄露时运行 `kiki web rotate-token`：它替换 `server.token`，使旧远端凭据失效，并停止受影响的 peer 流，无需重启。这不会轮换 `server.local-owner`；该本地管理凭据泄露意味着本地访问已受损，不能靠远端 token 轮换补救。
+远端 owner token 泄露时运行 `kiki web rotate-token`：它替换 `server.token`，使旧远端凭据失效，并停止受影响的 peer 流，无需重启。它不会轮换 `server.local-owner`，所以该文件泄露要按本地访问已失守处理。
 
 桌面 GUI 先查实例注册表，用 local-owner 凭据连接已有服务；找不到时才启动自己的 sidecar。因此同一 home 下受支持的本地客户端共享同一批会话，与具体哪个启动器启动服务无关。
 
 ::: warning 注意
-这条警告针对彼此独立预配、互不信任的运行时（例如分属不同 host 身份、各自拥有权限域的两个服务）：不要让这样的两个运行时共享同一个可写 home 目录，不要在它们的 home 之间复制会话目录，也不要复制 `device_id` 让两个 home 冒充同一台 host——会话索引、thread 归属与权限边界都依赖 home 身份的唯一性。同一 home 下的共享 daemon、TUI、桌面 GUI 与并存的服务实例是受支持的协作方式，不在此列。
+两个彼此独立预配、互不信任的运行时——分属不同 host 身份、各自拥有权限域的两个服务——不要共享同一个可写 `KIKI_HOME`，不要在它们的 home 之间复制会话目录，也不要复制 `device_id` 让两个 home 冒充同一台 host。会话索引、thread 归属与权限边界都依赖 home 身份的唯一性。同一 home 下的共享 daemon、TUI、桌面 GUI 与并存的服务实例是受支持的协作方式，不在此列。
 :::
 
 绑定非本机地址（`--host`，包括裸 `--host`，即 `0.0.0.0`）需要服务前面有终结 TLS 的反向代理，或加 `--insecure-no-tls`；两者都没有时服务拒绝启动。服务在非本机地址上运行之后，可设置 `KIKI_PASSWORD` 作为另一种 owner 凭据；它不能替代 local-owner 或逐源 grant。服务端会对鉴权失败自动限流。
@@ -84,7 +84,7 @@ kiki web --insecure-no-tls      # 允许明文 LAN HTTP（见下方警告）
 
 TUI 里对应的是 `/web temporary|persistent|status|off|link|revoke [id]`，可搭配 `--host`、`--port`、`--public-url`、`--insecure-no-tls`、`--no-open`。
 
-每次开启会打印一个一次性链接，用于让浏览器登录。Kiki 用它换取一个由浏览器自己保管的 session cookie（HttpOnly、`SameSite=Strict`、host-only，HTTPS 下带 `Secure`）；JavaScript、`localStorage` 和 URL 查询参数里都不会留下 session 或根 token。链接只显示一次——服务端只保留摘要，丢失后需要重新生成，而不是找回同一个。已经授权的浏览器可以跨服务重启继续使用；新设备需要新链接。
+每次开启会打印一个一次性链接，用于让浏览器登录。Kiki 用它换取一个由浏览器自己保管的 session cookie（HttpOnly、`SameSite=Strict`、host-only，HTTPS 下带 `Secure`）；JavaScript、`localStorage` 和 URL 查询参数里都不会留下 session 或根 token。服务端只保留摘要，链接丢失后需要重新生成，而不是找回同一个。已经授权的浏览器可以跨服务重启继续使用；新设备需要新链接。
 
 关闭 Web 访问会撤销全部链接和浏览器会话，并关闭已打开的连接流；它不会停止 daemon、桌面应用或 TUI，也不会取消已经开始的任务。`kiki serve` 和桌面应用都不受影响。
 

package/dist/docs/zh/server/mcp.md

@@ -2,7 +2,7 @@
 
 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 是一个开放协议，让模型可以安全地调用外部进程或服务暴露的工具——例如读取 GitHub issues、查询数据库、操作本地文件系统。Kiki 作为 MCP client 接入这些外部工具，并把它们与内置工具（`Read`、`Bash`、`Grep` 等）一起暴露给 Agent 使用，行为上没有差异。
 
-MCP 工具结果可以携带内嵌媒体。当当前模型无法接收某张内嵌图片——格式不被接受，或该 part 超过单 part 体积上限——结果会同时保留文本提示，并把原件存入会话媒体存储，不会丢失字节。提示中带有已保存文件的绝对路径和 `kimi-file://` 引用；把该路径传给 `Read` 或 `ReadMediaFile` 即可查看原件。Kiki 不直接交付的 resource blob 也会以同样方式保留。当累积的附件清单会挤占工具输出时，清单会写入一个文本文件，输出中只保留指向它的简短指针。
+MCP 工具结果可以携带内嵌媒体。当当前模型无法接收某张内嵌图片——格式不被接受，或该 part 超过单 part 体积上限——Kiki 会同时保留文本提示，并把原件存入会话媒体存储，不会丢失字节。提示中带有已保存文件的绝对路径和 `kimi-file://` 引用；把该路径传给 `Read` 或 `ReadMediaFile` 即可查看原件。Kiki 不直接交付的 resource blob 也会以同样方式保留。当附件清单会挤占工具输出时，清单会写入一个文本文件，输出中只保留指向它的简短指针。
 
 ## 接入方式
 
@@ -67,7 +67,7 @@ MCP server 配置写在 `mcp.json` 中，分两层：
 
 连接超时和单次工具调用超时的默认值都不必逐个 server 设置：`config.toml` 的 `[mcp] startup_timeout_ms` / `[mcp] tool_timeout_ms` 或环境变量 `KIKI_MCP_STARTUP_TIMEOUT_MS` / `KIKI_MCP_TOOL_TIMEOUT_MS` 可以调整全局默认值，优先级为 server 字段 > 环境变量 > `config.toml` > 内置默认。详见 [配置文件](../configuration/config-files.md#mcp)。
 
-HTTP 与 SSE server 支持通过 `headers` 或 `bearerTokenEnvVar` 提供静态凭证。需要 OAuth 时，运行 `/kiki-ops 帮我登录 MCP <server-name>` 完成浏览器授权。
+HTTP 与 SSE server 支持通过 `headers` 或 `bearerTokenEnvVar` 提供静态凭证。需要 OAuth 时，运行 `/kiki-ops 帮我登录 MCP <server-name>` 完成浏览器授权。如果该 server 的授权元数据声明支持 `offline_access`，Kiki 会在登录时一并请求这个 scope，以便之后能续期而不必重新登录；否则按你原本的 scope 授权。声明支持该 scope 的 server 仍可能多显示一次同意页，也不保证一定签发 refresh token。已经登录过的 server 保留现有授权并继续用它续期——新增 scope 不会把你登出。
 
 Plugins 也可以在 manifest 中声明 MCP servers。Plugin 声明的 servers 默认启用，可以在 `/plugins` 中禁用或重新启用：禁用或移除后，已打开会话中的工具调用会失败并返回移除提示；重新启用则会让该 server 立即重连到已打开的会话并恢复工具——前提是会话创建时这个 server 已存在（包括重新启用 `mcp.json` 中 `enabled: false` 的条目）。全新出现的 server 仍遵循上一段的规则：只加入之后创建的会话。详见 [Plugins](../customization/plugins.md#plugin-中的-mcp-servers)。
 

package/dist/docs/zh/server/rest-api.md

@@ -118,6 +118,13 @@ HTTP 状态码几乎总是 200，业务结果以 `code` 为准。例外情况：
 | `POST /api/oauth/logout` | 登出托管供应商 |
 | `GET /api/oauth/usage` | 查询套餐用量与限额 |
 | `GET /api/oauth/userinfo` | 查询账号资料 |
+| `POST /api/usage-export/destinations/{id}/auth/begin` | 为某个目的地发起 VibeCafe 登录 |
+| `POST /api/usage-export/auth/{id}/poll` | 轮询该次登录 |
+| `POST /api/usage-export/auth/{id}/cancel` | 取消该次登录 |
+
+`vibecafe.ai` 目的地的登录方式与 VibeCafe 自己一致，而且只有官方服务提供这一种。`POST /api/usage-export/destinations/{id}/auth/begin` 只接收凭据的存放方式（`keyring` 或 `private-file`）——没有地址、client id 或密钥要填，服务地址固定为 `https://vibecafe.ai`。返回里带 `flow_id`、`state`、`user_code`、`verification_uri`、`expires_at` 和 `poll_after_ms`；按它给的间隔用 `POST /api/usage-export/auth/{id}/poll` 轮询，用 `POST /api/usage-export/auth/{id}/cancel` 取消。`state` 从 `pending` 变成 `connected`、`cancelled`、`denied`、`expired` 或 `error`，不是 `connected` 时由 `error_category` 说明原因。
+
+登录完成只是把凭据存下来，并不会自动开始外送。目的地仍保持 `disabled`，要等你预览过内容再启用，和手动配置的用途地一样。指向自定义地址的目的地、或者你自己提供密钥的那种，走的是手动路径；在那里发起这种登录会得到 `vibe-auth-official-only`，表示此方式不可用。
 
 ### 配置
 
@@ -182,6 +189,28 @@ Claude ACP、Codex ACP 与 Codex app-server 提供独立的本机历史目录。
 
 要自动分配工作区，可向 `POST /api/sessions` 发送 `{}`。服务端会在 `$KIKI_HOME/workspaces/` 下为该会话新建独立目录并注册工作区；响应中的 `workspace_id` 和 `metadata.cwd` 是新工作区的信息。显式提供已有 `workspace_id` 或 `metadata.cwd` 时仍按原方式定位，未知 `workspace_id` 仍会被拒绝。
 
+创建时设置 `agent_config.execution`，即可独立于 profile 选择 harness：
+
+```json
+{ "agent_config": { "execution": { "executor": "claude-acp" } } }
+```
+
+选择对象为 `{ executor, profile?, overrides? }`。省略 `profile` 表示外部直连；显式选择的 profile 必须使用同一执行器。`overrides` 接受 `model`、`thinking`、`permission_mode`、`kiki_context`、`allow_kiki_subagents`。执行器与 profile 相同时，省略覆盖字段保留该会话已有覆盖；`null` 删除覆盖并恢复 [下层默认值](../configuration/config-files.md#外部-harness-默认设置)，`[]` 与 `false` 则明确关闭对应能力。旧的顶层 model/profile/thinking 请求仍可使用。
+
+读取会话时，已提交的 `agent_config.execution` 绑定为 `{ version: 1, selection, effective, sources, generation }`。来源取 `session`、`profile`、`harness-settings`、`harness-default`；有效模型或档位未设置表示 Kiki 没有指定，而不是 harness 没有使用模型。厂商报告的模型是观测值，不会变成新的覆盖。空闲时也可通过 `POST /api/sessions/{session_id}/profile` 的 `agent_config.execution` 修改；运行中请随下一条提示词提交选择。
+
+#### `POST /api/sessions/{session_id}:compact`
+
+请求体可以省略。它接受 `instruction`（要保留什么）和 `strategy`，取值为服务端实现的两种续上下文策略 `summarize` 或 `relay`。请求到达时会话空闲就直接开始压缩；仍有模型响应或工具结果正在落进历史时则先排队，等那部分工作结束后的下一个 step 边界处理，不用等整个轮次。
+
+```json
+{ "accepted": true, "status": "queued", "source": "manual" }
+```
+
+`accepted: true` 表示请求已被受理，**不表示**历史已经压缩完。`status` 描述当时的阶段，取 `queued` 或 `running`；是否完成要看终态的 [`compaction.*` 事件](#事件)，而不是这个响应。已有手动压缩处于排队或执行中时再次请求会返回 `accepted: false`，不会产生第二次；只有收到终态事件、且上一次确实失败时才需要重发。
+
+受理也不保证压缩成功。执行时如果找不到可安全截取的更早历史，会以带 `reason` 的 `compaction.cancelled` 收尾，而不是悄悄放着历史不动；排队的手动请求也不会被随后完成的自动压缩清掉。旧版服务端可能返回空的 `data`，示例中的每个字段缺失都应按可选处理。
+
 ### 消息与转录
 
 | 方法与路径 | 说明 |
@@ -205,7 +234,9 @@ Claude ACP、Codex ACP 与 Codex app-server 提供独立的本机历史目录。
 | `POST /api/sessions/{session_id}/prompts/{prompt_id}:abort` | 中止指定的排队中、启动中、运行中或已追加的提示词 |
 | `POST /api/sessions/{session_id}/prompts/{prompt_id}:steer` | 立即发送单个排队提示词 |
 
-立即发送会把选中的提示词追加到活跃轮次；没有活跃轮次时，则按队列顺序分别启动新轮次。重启后，此操作只让选中项绕过恢复确认，其他恢复的提示词仍等待确认。中止已追加的提示词会取消它所加入的轮次，不会取消后续轮次。中止不存在或已经结束的提示词会返回 `40402`。
+提示词可在顶层 `execution` 携带同一份 [execution 选择](#会话)。选择随该提示词保存，到启动时才应用，而不是入队就生效；当前轮次保持已提交的绑定。execution 代际变化时新建远端会话，不恢复或 fork 旧远端，也不发送旧 Kiki 对话的交接文本；Kiki 中可见的历史仍保留。冷恢复继续使用已提交的代际及其自身保存的远端引用。
+
+立即发送会把普通选中提示词追加到活跃轮次；没有活跃轮次时，则按队列顺序分别启动新轮次。带有 execution 选择的提示词必须独立启动，不能把新绑定追加进当前轮次。重启后，此操作只让选中项绕过恢复确认，其他恢复的提示词仍等待确认。中止已追加的提示词会取消它所加入的轮次，不会取消后续轮次。中止不存在或已经结束的提示词会返回 `40402`。
 
 ### 审批与提问
 
@@ -311,6 +342,41 @@ PTY 终端接口，仅 loopback 绑定时挂载。
 | `POST /api/workspaces/{workspace_id}/trust` | 授予信任 |
 | `POST /api/workspaces/{workspace_id}/untrust` | 撤销信任 |
 
+### 记忆
+
+`{scope}` 取 `global`、`workspace`、`persona` 或 `persona_workspace`。三个非全局范围需要在查询串里带归属：工作区带 `workspace_id`，角色带 `persona_id`，角色的单工作区笔记两个都要。未知 `workspace_id` 会被拒绝。
+
+| 方法与路径 | 说明 |
+| --- | --- |
+| `GET /api/memory/settings` | 读取记忆配置，含 `effective_enabled` |
+| `PATCH /api/memory/settings` | 修改 `enabled`、`approval` 或 `budget` |
+| `GET /api/memory/workspaces/{workspace_id}/settings` | 读取某个工作区的开关 |
+| `PATCH /api/memory/workspaces/{workspace_id}/settings` | 设为 `true` / `false`，或 `null` 表示跟随全局 |
+| `GET /api/memory/{scope}` | 搜索或列出条目，过滤与分页见下文 |
+| `GET /api/memory/{scope}/{id}` | 读取单条，带 `target`、`applicability` 和 `complete` |
+| `PUT /api/memory/{scope}/{id}` | 写入条目；`{id}` 传 `new` 表示新建 |
+| `DELETE /api/memory/{scope}/{id}` | 删除条目（`expected_revision` 放查询串） |
+| `GET /api/memory/{scope}/inbox` | 列出待审提议 |
+| `GET /api/memory/{scope}/journal` | 改动历史，可用 `id` 收窄到单条 |
+| `POST /api/memory/{scope}/undo` | 按 `operation_id` 撤销一次操作 |
+
+`GET /api/memory/{scope}` 返回有界分页的 `{ items, mode, next_cursor, coverage }`，不带分页参数时也一样。没有 `query` 时 `mode` 默认 `list`，有 `query` 时默认 `search`；`page_size` 取 1–20。没有显式 `statuses` 时，list 查 `active` 和 `pending`，search 查 `active`，`include_inactive=true` 把两者都放宽到四种。`statuses` 是 `active`、`pending`、`superseded`、`archived` 的逗号串。既有客户端必须消费 `next_cursor`，不能把第一页当成整个命名空间。
+
+持续接续，直到 `next_cursor` 为 null 且 `coverage.exhausted` 为 true。带 cursor 的空准备页不代表命名空间为空。`coverage.complete` 和 `warnings` 说明不可读、非法或过大的记录；这些记录不会隐藏其余可读条目。扫描预算限制单次调用，不永久限制清单大小；搜索相关性排序与列表标题排序针对每个有界源片段。
+
+续读保持同一个 `{scope}` 路径和归属的 `workspace_id` / `persona_id`，只传 `cursor`，不要再带原过滤条件或页大小，混传会返回 `40944`。源内容变化或 store 重启会让 cursor 失效；重新查询并按范围加 ID 对账。`GET /api/memory/{scope}/inbox` 为 `pending` 返回同样的分页形状，接受 `page_size` 或 pending 列表的 `cursor`；其他状态或 search 模式的 cursor 会被拒绝。
+
+`PUT /api/memory/{scope}/{id}` 使用与 [`MemoryWrite`](../reference/tools.md#写入一条条目)相同的动作词表：`action`（`create`、`update`、`supersede`、`archive`）、`type`、`title`、`body`、`reason`、`expected_revision` 和 `pinned`。经 REST 的写入一律记录为来自你，无论 Agent 本会用哪个 `source`。响应是 `{ entry, operationId, outcome, warnings? }`，`outcome` 取 `applied`、`pending` 或 `unchanged`；`unchanged` 以及与已在等待的提议完全相同的重复提交，`operationId` 为 `null`，这两种情况都没有可撤销的操作。`update`、`supersede` 和 `archive` 必须带 `expected_revision`——基于过期版本的 `PUT` 会被拒绝，而不是覆盖掉更新的那一版。
+
+两个元数据字段可选，且「省略」的含义不同：
+
+- **`basis`**——`{ kind, note, refs? }`，`kind` 取 `human`、`observed`、`derived`、`unknown`。它是对象或缺省，永远不是 `null`。`update` 时省略它，只有在 `type`、`title`、`body` 都没变的情况下才保留原依据；改了其中任何一项却没给新依据，这条记忆会降为 `{ kind: 'unknown' }`，并在 `warnings` 里说明依据没有刷新。
+- **`validity`**——`{ check, until? }`，`null` 是有意义的：它清除已记录的核对项。`update` 时省略整个 key 表示保留原值，新建条目省略则表示没有记录。没有记录有效性的条目不等于永远有效。
+
+`covered_by` 只在 `archive` 时接受，填同一范围内保留的生效条目的 `{ id, expected_revision }`。存下来的条目以 `{ id, revision }` 记录同一依赖——就是你发过去的那个 revision——并且在真正执行归档时会重新核验，所以对着已经变了的替代条目归档会失败，而不是丢掉仍然需要的规则。
+
+`GET /api/memory/{scope}/{id}` 返回完整条目，外加 `scope`、取 `{ scope, id, expected_revision }` 的 `target`、取 `expired` / `recheck` / `unrecorded` 的 `applicability`，以及 `complete: true`。`target` 是用来定位的对象，不是请求体：`scope` 和 `id` 放路径上，归属的工作区或角色放查询串上，`PUT` 请求体里只有 `expected_revision` 这一个字段取自它，其余是你这次要写的 `action`、`type`、`title`、`body` 和 `reason`。写之前先读：`expected_revision` 对不上的 `PUT` 会返回 `40944`，响应的 `details` 带着 domain 自己的 `code` 与 `recovery`，而信封里的数值 code 仍是既有客户端已在处理的那一个。
+
 ### 会话租约与 peer thread
 
 会话租约（lease）是客户端持有的、需定期续期的「在线凭证」：`POST /api/leases` 创建或续期一条租约（默认有效期 60 秒），响应返回 `lease_id` 与 `expires_at`。持有租约可以挂住需要清理的资源（如 PTY 终端与文件监听），并让共享 daemon 在空闲退出判定时保持运行，见 [`kiki serve`](../reference/command.md#kiki-serve) 的 `--idle-exit`。
@@ -530,6 +596,8 @@ Klient 提供 `rest.rooms.listItems()` 和 `global.rooms.listItems()`。`klient.
 | 后台 | `task.started` / `terminated`、`shell.started` / `output` / `completed` |
 | 其他 | `compaction.*`、`skill.activated`、`goal.updated`、`prompt.*`、`error`、`warning` |
 
+`compaction.*` 这一族把「谁发起的」和「发生了什么」分开。`compaction.started` 带 `trigger`，取 `manual` 或 `auto`，并可能带 `phase`，取 `queued` 或 `running`；没有 `phase` 即表示 running。`compaction.completed` 带可选的 `trigger` 和一个 `result`；`compaction.cancelled` 带可选的 `trigger`，失败时带 `reason`，没有 `reason` 就是被取消。请依据这些事件判断完成情况，而不是[压缩请求](#post-api-sessions-session-id-compact)的 HTTP 响应——`trigger` 缺省应视为未知，不要据此认定一次手动压缩已完成。排队中的手动请求也不会因为某次自动压缩完成而被结算。
+
 事件另分持久与易失两种：持久事件带严格递增的 `seq`，落盘并可回放；易失事件（各 `*.delta`、`tool.progress`、`shell.*` 等）标 `volatile: true`，不回放。消费易失文本流时用 `offset`（该轮次内的累计字符偏移）与本地已累积文本比对：小于本地长度说明是重复帧，大于说明有缺漏、需走快照恢复。
 
 ### 断线恢复

package/dist/docs/zh/server/sdk.md

@@ -1,6 +1,6 @@
 # Node.js SDK
 
-Kiki 目前没有发布到公共 npm registry 的 SDK。要把 Kiki 集成进自己的应用，使用以下受支持的协议入口：
+Kiki 没有发布到 npm 的 SDK。要把 Kiki 集成进自己的应用，使用以下协议入口：
 
 | 集成方式 | 适用场景 | 参考 |
 | --- | --- | --- |
@@ -8,4 +8,4 @@ Kiki 目前没有发布到公共 npm registry 的 SDK。要把 Kiki 集成进自
 | MCP | 让外部工具与 Agent 调用 Kiki | [Model Context Protocol](./mcp.md) |
 | ACP | 编辑器与 IDE 客户端 | [ACP](./acp.md) |
 
-Kiki 仓库内还有一个 TypeScript 客户端（`@kiki/klient`，标记为 `private` 的包），供在 monorepo 内开发与贡献时使用；它形成公共发行契约后，本页会更新为完整的 SDK 文档。
+仓库里还有一个 TypeScript 客户端（`@kiki/klient`），Kiki 自己的测试和工具链在用。它没有发布，不要在你自己代码里依赖它。