kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/zh/customization/hooks.md

@@ -1,10 +1,10 @@
 # Hooks
 
-Hooks（钩子）订阅引擎事件。声明式 v2 规则无需启动进程，就能附加指导文本或观察事件；legacy（旧协议）hooks 则执行本机 Shell 命令。典型的使用场景：
+Hooks 用来响应引擎事件。声明式（v2）规则不需要启动任何进程，就能附加指导文本或观察事件；legacy hook 则执行本机 Shell 命令。常见用途：
 
-- **安全拦截**：Agent 要执行 Shell 命令前，检查是否包含危险操作（如 `rm -rf`），包含则阻断执行
-- **桌面通知**：后台任务完成时，弹出系统通知提醒你回来查看结果
-- **自动检查**：每次用户提交消息时，自动在上下文里附加一些背景信息（如当前 Git 分支）
+- **拦截风险操作**：Shell 命令执行前检查是否包含 `rm -rf` 之类的危险操作并阻断
+- **桌面通知**：后台任务结束时弹出系统通知，提醒你回来看结果
+- **补充上下文**：把模型应该始终看到的信息（如当前 Git 分支）附加到每条提交的消息上
 
 ## 声明式规则（v2）
 
@@ -34,54 +34,47 @@ type = "inject"
 text = "继续前核对目标、已有证据和下一步。"
 ```
 
-一步指一次模型响应及其全部工具结果已落定并提交，不是一次工具调用或重试尝试。完成五步后，提醒在下一次模型请求前送达。第五步若恰好结束本轮，不会额外创建轮次，而是等待该模型的下一个请求。计数属于各 Agent 和模型配置的规范身份，因此 A → B → A 切换会保留 A 的计数；`counter_scope = "turn"` 则在新轮次清零。恢复、压缩和 undo 不倒拨计数，也不重放已投递提醒。修改 matcher 或节拍会开启从零计数的新语义 revision；只修改文本，会在下一个到期点使用新文本。
+一步指一次模型响应连同其全部工具结果已提交，不是一次工具调用。完成五步后，提醒会在下一次模型请求前注入；若第五步恰好结束了本轮，它会等该模型的下一个请求，不会为此新开一轮。计数按 Agent 和模型规范身份分别记录，A → B → A 仍保留 A 的计数，`counter_scope = "turn"` 则在新轮次清零。恢复、压缩和 undo 既不倒拨计数也不重放提醒；改 matcher 或节拍会从零开始新计数，只改文本则在下一个到期点用新文本。
 
-当前 v2 只接受 `inject` 和 `observe` 动作。`inject` 可用于 `step.before` 和 `prompt.submit`；`observe` 除这两个事件外，还支持 `step.after`、`tool.before`、`tool.after`、`turn.stopping`、`turn.after` 和 `session.start`。节拍仅适用于 step 事件。观察器只记录元数据，不改变原操作。v2 的 `command`、`block`、`gate` 和 `continue` 动作会在加载时被拒绝；脚本自动化仍使用下文的 legacy 协议。
+目前只有 `inject` 和 `observe` 两种动作。`inject` 用于 `step.before` 和 `prompt.submit`；`observe` 除这两个事件外还支持 `step.after`、`tool.before`、`tool.after`、`turn.stopping`、`turn.after` 和 `session.start`，只记录元数据。节拍仅适用于 step 事件。写 `command`、`block`、`gate` 或 `continue` 会在加载时被拒绝，它们属于下文的 legacy 协议。
 
 ### 来源与匹配
 
-用户配置、已信任项目的 `.kiki/hooks.toml` 和已启用插件 manifest 的规则组合执行，分别使用 `user/evidence-check`、`workspace/check`、`plugin/example/check` 等全限定 ID。`priority` 较小的先执行，同优先级按全限定 ID 排序；没有模型规则覆盖 profile 规则的优先链。同一命名空间的重复 ID 是错误，不同命名空间可使用相同短 ID。未信任项目的规则仍可查看，但不激活，纯文本规则也不例外。
+规则来自用户配置、已信任项目的 `.kiki/hooks.toml` 和已启用插件的 manifest，并各自带上 `user/evidence-check`、`workspace/check` 这样的全限定 id。`priority` 小的先执行，同优先级按全限定 id 排序。同一命名空间内 id 重复是错误，不同命名空间用相同短 id 没问题。未信任项目的规则仍可见但不激活，纯文本规则同样如此。
 
-`match.models`、`profiles`、`routes`、`executors` 和 `agent_roles` 使用精确值。不同字段必须同时命中，同一字段内的多个值是备选项，省略字段表示不限。模型别名在加载时解析，因此拼错别名会在首个请求前报告。工具名用 `match.tools`；工具结果状态用 `match.statuses`（`success`、`error`、`cancelled`、`denied`）。`prompt.submit` 默认仅匹配 `source = user`，其他来源需在 `match.sources` 中显式选择。无法提供 native step/tool 拦截的外部 executor 在检查视图中标为 unsupported，不会靠工具数量模拟步数。
+`match.models`、`profiles`、`routes`、`executors` 和 `agent_roles` 取精确值：你写了几个字段就必须同时命中，同一字段里的多个值是备选项，省略即不限。模型别名在加载时解析，拼错会在第一个请求前报出来。工具名写在 `match.tools`，工具结果写在 `match.statuses`（`success`、`error`、`cancelled`、`denied`）。`prompt.submit` 默认只匹配 `source = user`，其他来源要在 `match.sources` 里写明。无法原生拦截 step 或 tool 的外部 executor 会被标为不支持，而不是靠工具调用次数模拟。
 
-长文本可用 `text_file = "reminders/check.md"` 替代 `text`，二者互斥；`[hooks] files = ["hooks.toml"]` 可包含其他 v2 文档。路径相对于声明文件，经过 realpath（解析符号链接后的真实路径）检查后仍须留在该来源的作用域内。include 不能是 URL、不能循环或重复加载。缺文件、空文本、不支持的动作、无效节拍，以及超过 8 KiB UTF-8 字节预算的注入，都会形成加载期诊断。指导文本作为带来源标记的对话上下文投递，不替换系统提示词，也不能覆盖更高层指令。
+长文本可以用 `text_file = "reminders/check.md"` 代替 `text`（二者互斥），`[hooks] files = ["hooks.toml"]` 可以引入其他 v2 文档。路径相对于声明文件，解析后必须仍在其来源作用域内；include 不能是 URL、不能重复或形成循环。缺文件、空文本、不支持的动作、无效节拍以及超过 8 KiB 的注入都是加载期错误。注入的指导文本是带来源标记的对话上下文，不替换系统提示词，也无法覆盖更高优先级的指令。
 
-在规则上设 `enabled = false` 可停用该规则。用户 section 可用 `disabled = ["workspace/check"]` 停用任意来源的全限定 ID，或用 `enabled = false` 停用全部 v2 规则。项目和插件只能停用自身规则。变更在下一个安全事件边界生效，当前事件保留其配置快照。
+在规则上设 `enabled = false` 可停用。用户配置可以用 `disabled = ["workspace/check"]` 停用任意来源的规则，也可以用 `enabled = false` 关掉全部 v2 规则；项目和插件只能停用自己的。改动在下一个安全事件边界生效。
 
-### 查看有效规则
+### 查看生效规则
 
-引擎贡献命令 `hooks-inspect` 输出来源、激活或失败原因、执行顺序、绑定、语义 revision、已完成计数和下一次到期计数。可通过现有客户端命令 API 调用：
+`hooks-inspect` 命令会报告每条规则的来源、生效或失败原因、执行顺序、绑定、已计数和下一次到期计数：
 
 ```ts
 await klient.session(sessionId).agent("main").runCommand({ name: "hooks-inspect" });
 ```
 
-结果是 `hook.result` 诊断事件（`hookEvent = "hooks.inspect"`），不会附加到模型对话。在 GUI 中，展开会话 Agent 面板的 **Hooks**，可查看有效规则、来源路径、未激活原因和计步状态。此视图使用 `GET /api/sessions/{session_id}/agents/{agent_id}/hooks`；配置保存成功不代表规则已在该会话激活。
+结果是 `hook.result` 诊断事件（`hookEvent = "hooks.inspect"`），不会进入模型对话。GUI 里会话 Agent 面板的**自动规则**显示同样的信息，读取 `GET /api/sessions/{session_id}/agents/{agent_id}/hooks`——规则保存成功但在该会话未激活时，原因就显示在这里。没有配置任何规则、也没有需要修复的来源时，这个区块整个不出现。
 
-编辑用户配置时，打开**设置 → 能力 → 钩子**（`/settings/hooks`）。选中声明式规则或命令规则进行编辑，也可用 **高级：编辑 JSON** 编辑完整的 legacy 数组或 v2 对象。添加第一条声明式规则会显式切换到 v2，并把原命令保留在 `legacy` 中；打开或保存页面不会执行这些命令。**保存自动操作** 会校验完整的 hooks 值，并显示服务器保存后的值；保存失败时保留草稿。v2 总开关和停用 ID 仅影响声明式规则，不影响命令规则。
+在**设置 → 能力 → 钩子**（`/settings/hooks`）里编辑用户配置：选中规则直接编辑，或用 **高级：编辑 JSON** 处理整个 legacy 数组或 v2 对象。添加第一条声明式规则会把 legacy 数组切换为 v2，原命令保留在 `legacy` 下；打开或保存这个页面都不会执行它们。**保存自动操作** 校验完整的 hooks 值并显示服务器实际保存的内容，保存失败时你的草稿还在。v2 开关和停用 id 只影响声明式规则。
 
-TOML 不能在同一个 key 下同时声明 `[[hooks]]` 和 `[hooks]`。已有数组继续保持原义。需要在 v2 文档中保留 legacy 命令时，显式把旧条目移至 `[[hooks.legacy]]`，保持 `event`、`matcher`、`command` 和以秒计的 `timeout` 不变；它们仍使用 legacy runner 和输出协议，不会自动迁移或转换脚本协议。
+TOML 不能在同一个 key 下同时写 `[[hooks]]` 和 `[hooks]`，已有数组继续照常工作。要在 v2 文档里保留 legacy 命令，把它们显式移到 `[[hooks.legacy]]`，保留 `event`、`matcher`、`command` 和以秒计的 `timeout`；它们仍按 legacy runner 和输出协议执行。
 
-## Hooks 是怎么工作的
+## Legacy 命令 hook
 
-以下章节描述 legacy 命令协议，不是 v2 声明式规则。
+以下都是 legacy 协议：一条规则写明触发事件、要匹配的目标，以及要执行的 Shell 命令。
 
-配置一条 hook 规则，需要指定三件事：**在什么事件上触发**、**匹配哪些目标**、**运行哪个脚本**。
+命中时，CLI 把事件详情（触发原因、工具名、命令内容等）打包成 JSON，通过**标准输入**（stdin，程序运行时接收外部数据的通道）传给脚本，由脚本决定怎么做。**退出码**（exit code，程序结束时向系统报告的状态数字）决定放行还是阻断——`0` 放行，非零值在阻断类事件上阻止原操作，纯观察事件则继续；**标准输出**（stdout，`console.log` 打印的内容）可以附带说明。
 
-触发时，CLI 会把事件的详细信息（触发原因、工具名称、命令内容等）打包成 JSON（一种结构化文本格式），通过**标准输入**（stdin，程序运行时用来接收外部数据的通道）传给你的脚本。脚本读取这些信息后，决定怎么响应。
-
-脚本的响应结果由两样东西决定：
-
-- **退出码**（exit code，程序结束时向操作系统报告的状态数字）：`0` 表示放行；非零值在阻断类事件上阻止原操作，纯观察事件则继续。
-- **标准输出**（stdout，就是你用 `console.log` 或 `print` 打印出来的内容）：可以附带说明文字。
-
-阻断类事件在脚本失败或超时时采用 fail-closed（失败即拒绝）：尚未执行的操作停止，并提供原因。纯观察事件不打断主流程。[返回值表](#返回值)列出两类行为。
+阻断类事件在脚本失败或超时时按 fail-closed 处理：尚未执行的操作停止并给出原因。纯观察事件不打断主流程。[返回值表](#返回值)列出两类行为。
 
 ::: warning 注意
-Hooks 是权限系统的补充，不是操作系统沙箱，也不能代用户批准工具执行。高风险操作仍应保留权限检查和人工确认。
+Hook 是权限规则的补充，不是操作系统沙箱，也不能代你批准工具执行。高风险操作仍要保留权限检查和人工确认。
 :::
 
-## 快速上手：一个最简单的 hook
+## 一个最简单的 hook
 
 下面这条 hook 会在每次后台任务完成时，在终端标题栏闪一下通知（macOS 需要安装 `terminal-notifier`）：
 
@@ -95,9 +88,9 @@ command = "terminal-notifier -title Kimi -message 'Task done'"
 
 保存配置、重开会话，下次后台任务完成时就会弹出通知。
 
-## 配置
+## Legacy 规则字段
 
-所有 hook 规则写在 `~/.kiki/config.toml` 的 `[[hooks]]` 数组里，每一项是一条规则：
+每条 legacy 规则是 `~/.kiki/config.toml` 中 `[[hooks]]` 数组里的一项：
 
 | 字段 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
@@ -126,11 +119,11 @@ Hook 命令的工作目录是当前会话的项目目录。非 Windows 平台上
 }
 ```
 
-具体事件还会附带额外字段（如工具名称、命令内容），见下方事件一览。所有字段名使用下划线命名（snake_case）。
+具体事件会附带各自的字段（工具名、命令内容等），见下方事件一览。所有字段名使用下划线命名（snake_case）。
 
 ## 返回值
 
-脚本结束后，CLI 根据退出码判断 hook 的意图：
+脚本结束后，CLI 按退出码判断它的意图：
 
 | 退出码 | 含义 | CLI 怎么处理 |
 | --- | --- | --- |
@@ -141,11 +134,11 @@ Hook 命令的工作目录是当前会话的项目目录。非 Windows 平台上
 
 ### JSON 协议判定
 
-退出码为 `0` 时，CLI 按以下规则判断标准输出：
+退出码为 `0` 时，CLI 这样判断标准输出：
 
-- **有效 JSON**：CLI 会递归检查对象和数组。如果任意深度的对象自身含有 `message` 或 `hookSpecificOutput` 键，该输出就属于协议尝试，且顶层值必须符合严格的 hook 响应对象格式。顶层形态不同或协议字段非法时，阻断类事件会被阻断。完全不含这两个键的 JSON 仍视为非结构化输出并放行。
-- **畸形对象文本**：只有呈对象形态、且含有可识别的精确 `message` 或 `hookSpecificOutput` 键时，文本才属于协议尝试。以 `[` 开头的文本只有在第一个非空白字符是 JSON 值起始符时才视为数组形态，因此 `[INFO]` 和 `[DEBUG]` 日志仍是非结构化输出。键识别能覆盖单引号、缺少分隔符、键和值之间漏冒号等常见错误，同时不会把 `messageCount` 这类前缀当成协议键。已识别的畸形协议尝试会阻断阻断类事件。
-- **残余歧义文本**：如果畸形文本中没有可识别的精确协议键，CLI 无法可靠地将其与普通日志区分，因此仍按非结构化输出放行。这包括 `[INFO] response contains "message": metadata` 这类日志。
+- **有效 JSON** 会被递归检查。任意深度的对象里出现 `message` 或 `hookSpecificOutput` 键，就认为这是协议输出，顶层必须符合严格的 hook 响应对象格式；顶层形态不同或协议字段非法时阻断该操作。两个键都没有的 JSON 仍是非结构化输出，放行。
+- **畸形的对象文本** 只有在含有可识别的精确 `message` 或 `hookSpecificOutput` 键时才算协议尝试。以 `[` 开头时，只有第一个非空白字符能作为 JSON 值开头才按数组处理，因此 `[INFO]`、`[DEBUG]` 这类日志保持非结构化。单引号、缺少分隔符、键值之间漏冒号都能识别，而 `messageCount` 这样的前缀不算协议键。识别出的畸形协议输出会阻断该操作。
+- **其余内容** —— 没有可识别协议键的畸形文本，例如引用了 "message" 字样的日志行 —— 无法与普通日志区分，保持非结构化并放行。
 
 也可以通过标准输出返回一段 JSON 来阻断：
 
@@ -158,8 +151,8 @@ Hook 命令的工作目录是当前会话的项目目录。非 Windows 平台上
 }
 ```
 
-::: info 哪些事件支持阻断？
-只有**可阻断事件**（`PreToolUse`、`Stop`、`UserPromptSubmit`）的返回值会影响主流程。其余事件属于**观察型事件**——触发后即发即忘，不管脚本返回什么，主流程都不会改变。
+::: info 哪些事件可以阻断？
+只有 `PreToolUse`、`Stop` 和 `UserPromptSubmit` 的返回值会影响主流程。其余都是观察型事件，触发后不管脚本返回什么都不改变主流程。
 :::
 
 ## 事件一览
@@ -217,13 +210,13 @@ process.stdin.on('end', () => {
 });
 ```
 
-阻断后，Kiki 会把阻断原因写回上下文，模型可以据此选择更安全的替代方案。
+阻断后，Kiki 会把原因写回上下文，模型可以据此选择更安全的做法。
 
 ::: warning 注意
-此示例仅演示阻断机制，不是生产级的安全解析器。真实场景更适合用白名单，或用专门的 Shell 解析器处理引号、变量展开和多段命令。
+这个示例只演示阻断机制，按子串匹配不是安全解析器。真正要做防护，请用白名单列出允许的命令，或使用能处理引号、变量展开和命令串联的 Shell 解析器。
 :::
 
 ## 下一步
 
-- [配置](#配置) — `[[hooks]]` 在 `config.toml` 中的完整字段声明
-- [Agent 与 subagent](./agents.md) — 利用 `SubagentStop` 事件在 subagent 完成后触发通知
+- [Legacy 规则字段](#legacy-规则字段) — `[[hooks]]` 的完整字段说明
+- [Agent 与 subagent](./agents.md) — 用 `SubagentStop` 事件在 subagent 完成后触发通知

package/dist/docs/zh/customization/personas.md

@@ -1,8 +1,6 @@
 # 角色、Bot 与房间
 
-**角色（persona）**让一个身份及其记忆延续到不同会话，并给它一个随时可以回去的固定地址；[profile](./agent-profiles.md) 仍然负责工具、权限、模型和执行方式。**Bot** 是角色背后的常驻对话——定时提示词、另一个角色或房间通过它找到这个角色——**房间**则让多个角色在各自独立的成员会话里讨论同一主题。
-
-角色是长期身份，profile 是执行配置。它们回答的是不同的问题——它是谁、记得什么，对应它能调用哪些工具、用哪个模型和思考档位、从哪份提示词起步。角色卡会写明它挂在哪个 profile 上，你也可以换掉这个绑定而不丢掉身份，但两者不是同一个东西的两种叫法。
+**角色（persona）**是一个跨会话保留记忆的身份，并有一个随时可以回去的固定地址；它的 [profile](./agent-profiles.md) 负责工具、权限、模型和执行方式。角色回答「它是谁、记得什么」，profile 回答「它能调用什么、怎么运行」，换掉 profile 绑定不会丢掉身份。**Bot** 是角色背后的常驻对话，定时提示词、另一个角色或房间都通过它找到这个角色；**房间**让多个角色在各自独立的成员会话里讨论同一主题。
 
 ## 从角色开始
 
@@ -21,7 +19,7 @@ memory:
 你负责协调发布准备工作。主动询问缺失的证据，区分已确认事实与待解决问题。
 ```
 
-目录名就是稳定 ID：使用小写字母、数字，以单个连字符分隔单词。Markdown 正文定义身份。可选的 `model_alias` 和 `thinking_effort` 指定已配置模型及思考档位，但不授予权限。`tools` 等字段会被拒绝，因为权限属于 profile。
+目录名就是稳定 ID：使用小写字母、数字，以单个连字符分隔单词。Markdown 正文定义身份。可选的 `model_alias` 和 `thinking_effort` 指定已配置模型及思考档位，但不授予权限；`tools` 等字段会被拒绝，因为权限属于 profile。
 
 在 GUI 新建会话时选择角色，或从终端启动：
 
@@ -29,25 +27,25 @@ memory:
 kiki --persona release-guide
 ```
 
-每个角色还有一个固定的日常对话入口：侧栏那一行、切换器、会话顶栏和角色页指向的都是它。点角色的名字，落进的就是那一个对话，所以「找这个角色」每次都是同一件事。同一角色可以同时有多段对话，你从它的对话列表里切换，于是一个身份就能跨项目干活。终端里的对应操作是 `/persona switch release-guide`，它会打开一个**新会话**，旧会话仍然保留。
+每个角色都有一段固定的**日常对话**，侧栏那一行、切换器、会话顶栏和角色页打开的都是它，所以「找这个角色」每次都是同一段对话。一个角色可以同时持有多段，在它的对话列表里切换即可。终端里用 `/persona switch release-guide` 会打开**新会话**，旧会话保持原样；`/persona list` 列出全部角色。
 
-TUI 中，`/persona list` 列出角色。显式选择的模型优先于角色模型；否则先使用角色模型，再考虑 profile 或默认模型。显式选择其他 profile 会覆盖角色预设的 profile，但不会丢掉角色身份。
+显式选择的模型优先于角色模型；否则先看角色模型，再看 profile 或默认模型。显式选择其他 profile 会替换角色预设的 profile，但不会丢掉角色身份。
 
-每个会话都会冻结自己的角色快照。编辑角色卡不会悄悄修改正在进行的会话的系统提示词；新建会话或重建上下文后才会应用修改。开场白在你明确回复之前只是本地展示，单纯打开会话不会把它加入模型历史。
+每个会话都会冻结自己的角色快照，编辑角色卡不会影响进行中的会话——新建会话或重建上下文后才会生效。开场白在你明确回复之前只是本地展示，打开会话不会把它写进模型历史。
 
 ## 记忆与角色卡
 
-角色记忆跟随角色，不随 profile 或模型切换而丢失。角色专属条目与其他角色隔离；默认也能读取公共 global 和 workspace 记忆。设置 `memory.shared: []` 可排除这些公共记忆。记忆页提供角色范围；这一页的选择、审批收件箱和可撤销的改动历史见[记忆](../guides/memory.md)。删除角色也会删除其角色记忆；如果清理记忆失败，删除操作会报告错误并保留角色卡，便于重试。
+角色记忆跟随角色，不随 profile 或模型切换而丢失。角色专属条目与其他角色隔离，默认也能读取公共 global 和 workspace 记忆，设置 `memory.shared: []` 可排除。记忆页提供角色范围；模型、审批收件箱和可撤销的改动历史见[记忆](../guides/memory.md)。删除角色会一并删除其记忆，清理失败时删除操作会报错并保留角色卡，方便重试。
 
-角色页支持 Character Card V3 的 JSON、PNG、CHARX 导入导出。保存前先查看导入预览：卡片的 lorebook（背景知识条目）可转换为角色记忆，影响后续模型请求。未知扩展字段会在导出时保留；如果卡片含有头像之外的二进制素材，请保留原卡，因为这些素材尚不能完整保留。头像选择器接受不超过 20 MB 的 PNG、JPEG、WebP 原图，裁剪后上传 256 像素的图片。可以选择圆形或方形边框，重载后仍保留已保存的形状。「移除头像」恢复首字母头像，不删除角色或其记忆。直接调用 API 上传时仍限制为 2 MiB。复制会创建新身份，不复制会话状态或私有记忆；归档会隐藏常规选择列表中的角色，但不抹除数据。
+角色页支持 Character Card V3 的 JSON、PNG、CHARX 导入导出，保存前先看导入预览：lorebook 条目会转成角色记忆并影响后续模型请求。未知扩展字段在导出时保留，但头像之外的二进制素材无法完整保留，这类卡片请留好原件。头像选择器接受不超过 20 MB 的 PNG、JPEG、WebP，裁剪后上传 256 像素的圆形或方形图，重载后保留。**移除头像**只恢复首字母，不删除角色或记忆。直接调 API 上传仍限制 2 MiB。**复制**创建新身份，不带会话状态和私有记忆；**归档**把角色从常规选择列表隐藏，但保留数据。
 
-保存后的 `persona.md` 上限为 1 MiB，示例和扩展文件各为 256 KiB，均按 UTF-8 字节计算。保存或导入超限内容会在修改角色卡及其记忆之前失败；缩短内容后可重试。旧版无效或超限角色卡仍可通过 `PUT /api/personas/{id}` 替换，或通过 `DELETE /api/personas/{id}` 删除；删除时仍先清理该角色的记忆。
+保存后的 `persona.md` 上限 1 MiB，示例和扩展各 256 KiB，按 UTF-8 字节计算。超限内容会在改动角色卡和记忆之前失败，缩短后重试即可。旧版无效或超限的角色卡仍可用 `PUT /api/personas/{id}` 替换，或用 `DELETE /api/personas/{id}` 删除，后者会先清理该角色的记忆。
 
 ## 常驻对话
 
 角色无论你有没有跟它说过话，都有一个稳定的地址。它的**日常对话**就是这个地址：侧栏那一行、切换器、会话顶栏和角色页打开的都是同一个；角色页还会列出该角色的其它对话，你可以把日常入口换成其中另一段。第一次打开时会创建它。
 
-定时提示词、来自另一个角色的消息、房间里的席位，访问的都是这同一个对话——不需要再另外配置一份角色。角色为它保留自己的工作目录，默认是 `$KIKI_HOME/bots/<id>`，也可以由角色卡用 `home_workspace` 指定。相关限制在 `config.toml` 里配置：
+定时提示词、来自另一个角色的消息、房间里的席位访问的都是这同一个对话，不需要另外配置角色。它有独立的工作目录，默认 `$KIKI_HOME/bots/<id>`，也可以由角色卡用 `home_workspace` 指定。相关限制在 `config.toml` 里配置：
 
 ```toml
 [bot]
@@ -62,21 +60,21 @@ room_budget = 12
 
 ## 在房间中讨论
 
-创建房间时选择两到六个成员、归类工作区和主持人。角色成员获得独立的消息模式会话；API 也接受现有线程（`kind: "thread"`），直接沿用原会话、工作区和权限，要求 `[thread_communication] enabled = true`，且不能是子智能体。GUI 里可以在侧栏按住 Ctrl/⌘ 多选线程后右键「拉进新房间」，在线程菜单用「加入房间…」，在房间「添加成员」的「线程」页签搜索会话，或在线程链接上右键「和这些线程开房间」。调度只有三条规则：
+创建房间时选择两到六个成员、归类工作区和主持人。角色成员获得独立的消息模式会话；API 也接受现有线程（`kind: "thread"`），沿用其原会话、工作区和权限，要求 `[thread_communication] enabled = true`，且不能是 subagent。GUI 里可以在侧栏按住 Ctrl/⌘ 多选线程后选「拉进新房间」，在线程菜单用「加入房间…」，在房间「添加成员」的「线程」页签里加入，或在线程链接上选「和这些线程开房间」。谁会被唤醒由三条规则决定：
 
 1. 用户 @ 谁就唤醒谁；`@everyone` 或 `@所有人` 选择全部成员。
 2. 用户没有 @ 任何人时交给主持人，主持人不论是角色还是线程。
-3. 角色消息只唤醒它 @ 到的成员。没有 @ 的发言不会继续触发讨论。
+3. 角色或线程的房间消息只唤醒它 @ 到的成员。没有 @ 的发言会记入房间，但不会唤醒任何人。
 
-成员依次运行，后发言者能收到前一位的结果。静音成员不会被角色提及和主持兜底唤醒，但用户显式 @ 它时仍会唤醒。成员收到自上次唤醒以来的消息，不重复加入自己已经记录过的发言。
+角色成员依次运行，已有线程则各有自己的队列。静音成员不会被 Agent 提及和主持兜底唤醒，但用户显式 @ 它时仍会唤醒。成员收到自上次成功完成汇总以来的消息，不含自己已记录的发言。成功批次已经覆盖的通知不会再单独开启轮次；失败或取消的轮次不会确认该批消息已处理。
 
-预算限制每条用户消息之后的成员发言数，默认 12 条。用尽后讨论暂停，「继续」会重置预算并恢复保留的任务。「暂停」取消排队唤醒，允许当前轮次结束；「停止所有」只会中断角色成员的活动轮次，不会中断原线程任务，也不回滚已完成的动作。纯角色房间保留用户插话机制，混合房间则保留排队任务。同一时刻房间只展示一张问题卡，后续问题排队。
+预算限制每条用户消息之后的成员发言数，默认 12 条。用尽后讨论暂停，「继续」重置预算并恢复保留的任务。「暂停」取消排队唤醒但让当前轮次跑完；「停止所有」还会中断角色成员的活动轮次，但不会中断原线程任务，也不回滚已完成的动作。纯角色房间保留用户插话，混合房间保留排队任务。同一时刻只展示一张问题卡，后续排队。
 
-线程成员默认 `queueWhenBusy: true`：房间输入等待当前轮次结束，不会 steer。冷线程在自己的工作区恢复；除主持人以外的成员，未点名的消息在下次唤醒时按 since 汇总，不单独产生模型调用。线程必须使用 `ThreadSend({room, content, mentions?})` 发言，普通 Assistant 文本不会进入房间。
+线程成员默认 `queueWhenBusy: true`：房间输入等当前轮次结束，不会 steer。冷线程在自己的工作区恢复；没有选中某成员的消息会在该成员下次唤醒时汇总，不单独产生模型调用。线程必须用 `ThreadSend({room, content, mentions?})` 发言，普通 Assistant 文本不会进入房间。`mentions` 使用准确的成员 ID（线程用 `sessionId`，角色用 `personaId`），不用显示名。不带 mentions 的发送不会唤醒主持人；主持人兜底只适用于用户消息。
 
-改名、换主持人、静音和更换归类工作区不会重写成员系统提示词或权限。移除线程会在其会话留下系统记录，房间日志保留，原线程不会归档。创建时要求两到六个成员，离开后可少于两个。
+改名、换主持人、静音和更换归类工作区都不会重写成员的系统提示词或权限。移除线程会在其会话留下系统记录、保留房间日志，不归档原线程。创建时要求两到六个成员，离开后可以少于两个。
 
-成员无法唤醒时，房间会显示失败原因和恢复操作，不再承诺自动重试。模型未登录时，请到「设置 → 模型与提供商 → 连接服务」登录，或打开该成员的会话选择可用模型。已有成员会话保留绑定的模型，修改角色卡片不会改变它。修复后再发一条房间消息；失败成员不是主持人时，请 @ 它。「继续」用于恢复暂停的房间，不会重试尚未暂停的失败唤醒。
+成员无法唤醒时，房间会显示失败原因和恢复办法。模型未登录时，到「设置 → 模型与提供商 → 连接服务」登录，或打开该成员的会话选择一个可用模型——已有成员会话保留绑定的模型，改角色卡不会改变它。修好后再发一条房间消息，失败成员不是主持人时请 @ 它。「继续」恢复的是暂停的房间，不会重试尚未暂停的失败唤醒。
 
 ## API 入口