koishi-plugin-hds-interlude 0.1.3-beta1 → 0.1.3

package/BEGINNER_GUIDE.md

@@ -1,6 +1,6 @@
 # HDS Interlude 新手引导
 
-适用版本：`0.1.3-beta1`
+适用版本：`0.1.3`
 
 HDS Interlude 是 Koishi 的持续叙事聊天插件。插件使用共享主剧本保存角色状态、关系分支、已发生事件、待处理计划和长期记忆。用户消息会进入当前活动场景；主模型在同一次请求中续写已经发生的生活，并决定是否发送、延迟发送或暂不发送消息。实时写作读取一条按时间排序的活动场景记录：最近剧本文字、真实用户消息和已经成功投递的角色消息在同一条线上。剧本引子、场景外近期事实和长期记忆负责更早的历史。
 
@@ -20,10 +20,11 @@ HDS Interlude 是 Koishi 的持续叙事聊天插件。插件使用共享主剧
 5. 保存配置后，在已授权私聊中执行：
 
 ```text
-interlude.init 主角名字
+interlude.doctor
+interlude.story.start
 ```
 
-Console 页面建议按以下顺序填写：`storyDefaults` → `model` → `onebot` → `sharedStory` → `runtime` → `agency` → `memory` → `alterSystem`。首次测试先完成模型、剧本起点和账号权限；网页观察、Embedding 和详细日志可以之后再开。
+Console 页面建议按以下顺序填写：`blindMode`（首次保持关闭）→ `storyDefaults` → `model` → `onebot` → `sharedStory` → `runtime` → `agency` → `memory` → `alterSystem`。首次测试先完成模型、剧本起点和账号权限；网页观察、Embedding、详细日志与失明模式可以之后再开。
 
 6. 发送一条普通消息，确认模型调用、日志和消息投递正常。
 
@@ -44,13 +45,11 @@ Console 页面建议按以下顺序填写：`storyDefaults` → `model` → `one
 ### 1. 模型与提示词
 
 ```yaml
-model.mode: openai-compatible
-model.mainModelId: 主叙事模型预设 ID
 model.mainTemperature: 0.7
-model.mainTopP: 0.9
-model.mainMaxTokens: 0
-model.mainTimeout: 0
-model.mainResponseFormat: prompt-only
+model.mainTopP: 1
+model.mainMaxTokens: 4096
+model.mainTimeout: 60000
+model.mainResponseFormat: json-object
 model.formatPrompt: ''
 model.fixedPrompt: ''
 model.failover.enabled: true
@@ -58,34 +57,29 @@ model.failover.strategy: priority
 model.failover.maxAttemptsPerProvider: 2
 model.failover.cooldownMinutes: 5
 model.embedding.enabled: false
-model.vision.enabled: true
+model.vision.enabled: false # 只有视觉模型才改为 true
 ```
 
 主叙事读取 `runtime.contextEntryLimit` 控制的近期原始条目，并受固定 12,000 字符预算保护；更早内容由 continuity、场景摘要和长期事实衔接。
 
 
-先在服务商列表填写连接信息，再在模型列表登记实际模型；后续各功能只需从模型预设下拉菜单选择即可：
+每条模型连接只配置一次；用用途开关决定它服务哪些任务：
 
 ```yaml
-model.providers[].id: primary
-model.providers[].label: Primary provider
+model.providers[].label: 主叙事模型
 model.providers[].enabled: true
 model.providers[].endpoint: https://你的服务商/v1/chat/completions
 model.providers[].apiKey: 你的 API Key
+model.providers[].model: 你的模型名称
+model.providers[].useForMain: true
+model.providers[].useForCompaction: true
+model.providers[].useForAlter: true
+model.providers[].useForEmbedding: false
 model.providers[].extraHeaders: ''
 model.providers[].extraBody: ''
-
-model.models[].id: narrative
-model.models[].label: 主叙事模型
-model.models[].enabled: true
-model.models[].providerId: primary
-model.models[].model: 你的模型名称
-model.models[].maxTokens: 4096
-model.models[].timeout: 60000
-model.models[].responseFormat: prompt-only
 ```
 
-保存后，在 `model.mainModelId` 填写 `narrative`。若还要配置压缩、Alter 分析或 Embedding，也是在 `model.models` 增加对应预设，再将相同的预设 ID 填到各功能的 `modelId` 字段；服务商地址和 API Key 不需要重复填写。
+无需填写或记忆任何 `providerId`、`modelId`、`mainModelId`。若压缩或 Alter 要用更便宜的模型，新增一行模型连接，只勾选对应用途即可；服务商地址和 API Key 可以直接在该行配置。
 
 主叙事提示词：
 
@@ -102,7 +96,7 @@ model.stylePrompt:
 
 从主角此刻手头正在做的事情继续写。让时间通过具体行动向前移动：拿起或放下的物品、进行到哪一步的任务、身体产生的需要、环境中的变化、临时出现的安排，以及周围人物正在做出的选择。细节应参与行动和因果，使读者能够感到这一段生活确实发生过。
 
-根据真实经过的时间选择合适的叙事密度。短暂间隔聚焦一个新动作、注意力变化或对话进展；较长间隔选择几个有连接的生活时刻，表现任务、地点、身体状态、陪伴者和计划怎样逐步变化。
+按当前阶段和已经经过的生活连续书写：用户消息、对话后续、到期意图与自动推进各自提供明确事件边界；调度间隔只决定何时唤醒写作，不预设叙事密度。
 
 让主角同时拥有眼前事务、当天安排、个人兴趣、现实压力和未解决的小事。每次选择当前最能自然推进的部分，并让偶然变化从既有处境中生长，例如计划调整、物品带来的麻烦、配角提出的新安排、环境变化或意外发现。
 
@@ -119,8 +113,6 @@ model.stylePrompt:
 
 ```yaml
 model.compaction.enabled: true
-model.compaction.providerId: 留空表示自动选择
-model.compaction.model: 低成本模型名称
 model.compaction.temperature: 0.3
 model.compaction.topP: 1
 model.compaction.maxTokens: 2048
@@ -172,6 +164,7 @@ sharedStory.participantContextLimit: 6
 ```yaml
 runtime.captureDirectMessages: true
 runtime.autoCreate: true
+onebot.voiceTranscription.enabled: false # 使用 SnowLuma 私聊语音转写时改为 true
 runtime.ignoreCommandMessages: true
 runtime.userMessageDebounceSeconds: 2
 runtime.cancelDelayedRepliesOnUserMessage: true
@@ -216,8 +209,8 @@ runtime.restWindows[].maxIntervalMinutes: 240
 
 ```yaml
 memory.enabled: true
-memory.sceneEntryThreshold: 12
-memory.sceneCharacterThreshold: 8000
+memory.sceneEntryThreshold: 16
+memory.sceneCharacterThreshold: 10000
 memory.factLimit: 20
 memory.activeConsequencesEnabled: true
 memory.activeConsequencePromptLimit: 6

package/CONFIGURATION_GUIDE.md

@@ -1,25 +1,32 @@
 # HDS Interlude 配置指南
 
-适用版本：`0.1.3-beta1`
+适用版本：`0.1.3`
 
 第一次安装先看 `BEGINNER_GUIDE.md`。本文件严格按照 Koishi Console 的显示顺序说明当前字段；旧版本已经移除或隐藏的字段集中列在末尾，不再混入正常配置流程。
 
 ## Console 顺序
 
-1. `storyDefaults`：剧本起点
-2. `model`：模型与服务商
-3. `onebot`：OneBot / NapCat 权限
-4. `sharedStory`：共享剧本
-5. `runtime`：对话与时间
-6. `agency`：主体行动窗口
-7. `memory`：连续性与记忆
-8. `alterSystem`：临时氛围偏移
-9. `browser`：只读网页观察
-10. `logging`：日志与隐私
+1. `blindMode`：失明模式
+2. `storyDefaults`：剧本起点
+3. `model`：模型与服务商
+4. `onebot`：OneBot / NapCat 权限
+5. `sharedStory`：共享剧本
+6. `runtime`：对话与时间
+7. `agency`：主体行动窗口
+8. `memory`：连续性与记忆
+9. `alterSystem`：临时氛围偏移
+10. `browser`：只读网页观察
+11. `logging`：日志与隐私
 
-首次测试只需要完成前五组。Embedding、网页观察、主动联系和内容日志应在基础私聊稳定后逐项开启。
+首次测试先完成 `storyDefaults`、`model`、`onebot`、`sharedStory` 和 `runtime`；`blindMode` 保持关闭。Embedding、网页观察、主动联系和内容日志应在基础私聊稳定后逐项开启。
 
-## 1. storyDefaults：剧本起点
+## 1. blindMode：失明模式
+
+开启 `blindMode.enabled` 后，HDSI 不注册自己的管理指令，并静默拦截当前 Koishi 实例中所有已经识别的指令；普通聊天仍会进入叙事。HDSI 的普通运行日志、错误详情和消息预览都会隐藏，只按 `healthReportMinutes` 输出一次不含故事或账户内容的运行状态心跳；其它插件仍遵循各自的日志配置。
+
+它适合追求高度沉浸感，并且模型、账号白名单和故事档案已经稳定正常的环境。关闭此模式需要在 Console 修改配置并重载插件；失明模式开启期间无法通过聊天指令恢复管理能力。旧 `blackBox` 配置仍可兼容读取，但 Console 只显示 `blindMode`。
+
+## 2. storyDefaults：剧本起点
 
 这些字段只在创建新主剧本时写入 Canon。修改 Console 不会自动重写已经存在的故事。
 
@@ -27,6 +34,7 @@
 | --- | --- |
 | `characterName` | 主角名称。 |
 | `characterProfile` | 主角身份、性格、作息、习惯、压力和行为边界。 |
+| `perspective` | 主角个体价值观 / 看待世界的方式。它作为独立于 Canon 的外壳人格层，在相关事件中自然影响判断；长期剧情可形成 `perspective` overlay。 |
 | `userProfile` | 没有账号专属资料时使用的默认用户背景。 |
 | `relationship` | 新参与者与主角的默认初始关系。 |
 | `world` | 时间、地点、社会与现实规则。 |
@@ -35,50 +43,74 @@
 | `style` | 当前故事文风，优先级高于全局 `model.stylePrompt`。 |
 | `timezone` | IANA 时区，例如 `Asia/Shanghai`。主模型以该时区生成权威 `nowLocal`、当前时段和日照预期。 |
 
-小幅补充无需维护。若大幅改变角色、关系或世界前提，保存后执行对应的 `interlude.overlay.clear character|relationship|world`，避免旧 Overlay 与新 Canon 冲突。
+小幅补充无需维护。若大幅改变角色、Perspective、关系或世界前提，保存后执行对应的 `interlude.overlay.clear character|perspective|relationship|world`，避免旧 Overlay 与当前设定冲突。
+
+`perspective` 是独立于 Canon 的主角外壳人格层，不会重写 `characterProfile`。Console 的 `storyDefaults.perspective` 会写入新主剧本；已有故事可通过 `interlude.setup {"perspective":"..."}` 一次性设置基础 Perspective，再让长期剧情形成其 overlay。
 
 重载和长间隔不会沿用旧剧本中的钟点描述：当前 `nowLocal` 始终优先。时区无效时运行时回退到 UTC，因此发现上午/下午错误时应先检查这里是否为有效 IANA 名称。
 
-## 2. model：模型与服务商
+## 3. model：模型与服务商
 
-### 2.1 连接顺序
+### 3.1 连接顺序
 
 1. 将 `mode` 设为 `openai-compatible`。
-2. 在 `providers` 添加服务商和 API Key。
-3. 在 `models` 登记可复用模型预设。
-4. 将预设 ID 填入 `mainModelId`、`compaction.modelId`、`embedding.modelId` 或 `alterSystem.modelId`。
+2. 先确认 `vision.enabled`：纯文本模型保持关闭；视觉模型才开启。
+3. 在 `providers` 的每一行一次填完连接地址、API Key 和实际模型名。
+4. 勾选这行模型要承担的用途：主叙事、压缩、Alter 或 Embedding；每种用途保持一条即可。
+5. 在下方按任务分别调整温度、token、超时、提示词和 Embedding 参数。
 
 `fallback` 不调用远程模型，只适合验证插件、数据库和命令是否安装成功。
 
-### 2.2 providers
+### 智谱官方提供商模式
+
+在任意一行 `providers` 中将该行 `mode` 设为 `zhipu-official`，保存并重载后，Console 会切换为智谱专属字段：只需填写智谱 API Key、模型代码和推理强度。该行固定使用 `https://open.bigmodel.cn/api/paas/v4/chat/completions`，不会显示 endpoint、额外请求头或额外请求体；其它提供商行仍可保持 `openai-compatible`。
+
+智谱行的 GLM‑5.3‑Flash 强制使用 SSE：首个可见文本等待上限为 45 秒，首字到达后不设置总等待上限。推理强度可选 `low`、`high`、`max`，默认 `high`；GLM‑5.3‑Flash 不支持关闭思考。图片请求会使用智谱接受的 `image_url.url` 形式，不附带 OpenAI 的 `detail` 字段。
+
+### 其它官方提供商模式
+
+每一行 `providers.mode` 都可以独立选择，保存并重载后显示该模式的字段。以下预设固定官方 Chat Completions endpoint，只需填写 API Key 与模型名：
+
+| 模式 | 服务商 | 默认模型 | 说明 |
+| --- | --- | --- | --- |
+| `openai-official` | OpenAI | `gpt-5-mini` | OpenAI 官方 Chat Completions。 |
+| `deepseek-official` | DeepSeek | `deepseek-chat` | DeepSeek 官方 Chat Completions。 |
+| `moonshot-official` | Kimi / Moonshot | `kimi-k2.5` | Kimi 官方 OpenAI-compatible 接口。 |
+| `dashscope-official` | 阿里云百炼 | `qwen-plus` | 可选择北京、新加坡或美国共享服务地域；工作空间专属地址使用自定义模式。 |
+| `siliconflow-official` | 硅基流动 | `Qwen/Qwen3-8B` | 官方 OpenAI-compatible 接口。 |
+| `openrouter` | OpenRouter | `openai/gpt-5-mini` | 使用 OpenRouter 模型 slug，例如 `anthropic/...` 或 `google/...`。 |
+| `gemini-openai` | Google Gemini | `gemini-2.5-flash` | Gemini 官方 OpenAI 兼容端点。 |
+
+`openai-compatible` 始终保留给第三方中转站、工作空间专属域名和自定义网关。Anthropic 官方 Messages API 与 HDSI 当前 Chat Completions 请求结构不同，因此不作为“官方兼容预设”显示；可通过 OpenRouter，或使用支持 Chat Completions 的中转服务。
+
+### 3.2 providers
 
 | 字段 | 说明 |
 | --- | --- |
-| `id` | 服务商唯一标识，供模型预设引用。 |
-| `label` | Console 备注。 |
-| `enabled` | 是否参与候选选择。 |
+| `label` | 模型连接的显示名称，例如 GLM 4.7 Flash。 |
+| `enabled` | 是否启用这条模型连接。 |
 | `endpoint` | 完整 Chat Completions 地址。 |
 | `apiKey` | 密钥；按密码处理，不要进入截图和日志。 |
-| `model` | 未使用模型预设时的兼容默认模型。 |
-| `temperature` / `topP` | 默认采样参数。 |
-| `maxTokens` / `timeout` | 默认输出上限和请求超时。 |
-| `responseFormat` | 支持 JSON mode 时使用 `json-object`；否则用 `prompt-only`。 |
+| `model` | 服务商实际模型名；只在这行填写一次。 |
+| `useForMain` | 用作主叙事模型。 |
+| `useForCompaction` | 用作后台压缩模型。 |
+| `useForAlter` | 用作 Alter 侧端分析模型。 |
+| `useForEmbedding` | 用作 Embedding 模型；仅支持 `/embeddings` 的模型可勾选。 |
 | `extraHeaders` / `extraBody` | 服务商明确要求时填写 JSON 对象。 |
 
-### 2.3 models 与主叙事
+模型行既是连接配置，也是用途分配中心。无需填写或记忆 `providerId`、`modelId`、`mainModelId`；旧配置中的这些字段仍可兼容读取。
 
-`models` 的每一行包含 `id`、`label`、`enabled`、`providerId`、真实模型名、最大输出、超时和响应格式。专项功能填写的是预设 `id`，不是展示名称。
+### 3.3 主叙事调优
 
-主叙事覆盖字段：
+主叙事模型由上方 `useForMain` 自动选择。这里仅调整它的生成行为：
 
-- `mainModelId`
 - `mainTemperature`
 - `mainTopP`
-- `mainMaxTokens`：`0` 使用预设或服务商值
-- `mainTimeout`：`0` 使用预设或服务商值
-- `mainResponseFormat`
+- `mainMaxTokens`
+- `mainTimeout`
+- `mainResponseFormat`：主叙事唯一的输出格式设置
 
-### 2.4 failover 与提示词
+### 3.4 failover 与提示词
 
 `failover.enabled` 控制失败切换；`strategy` 可选按顺序或轮询；`maxAttemptsPerProvider` 控制单服务尝试次数；`cooldownMinutes` 控制失败后的临时跳过。
 
@@ -89,19 +121,19 @@
 - `fixedPrompt`：所有故事通用的长期约束。
 - `stylePrompt`：全局文风。
 
-### 2.5 vision、compaction、embedding
+### 3.5 vision、compaction、embedding
 
-- `vision.enabled`：把当前私聊图片作为原生多模态输入；模型必须支持视觉。
-- `compaction`：后台整理已发生剧本、事实和状态提案。可独立选择模型，并配置温度、top-p、输出、超时、响应格式和压缩提示词。
-- `embedding`：长期事实语义检索。`liveQuery=false` 可避免每次实时回复多一次向量请求；`backfillBatchSize` 控制后台补齐旧事实的速度。
+- `vision.enabled`：位于模型区最前面；开启后把当前私聊图片作为原生多模态输入，纯文本模型必须保持关闭。
+- `compaction`：后台整理已发生剧本、事实和状态提案。模型由 `useForCompaction` 选择；这里配置温度、top-p、输出、超时、响应格式和压缩提示词。
+- `embedding`：长期事实语义检索。模型由 `useForEmbedding` 选择；`liveQuery=false` 可避免每次实时回复多一次向量请求，`backfillBatchSize` 控制后台补齐旧事实的速度。
 
 Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址推导 `/embeddings`。非标准网关应填写完整地址。
 
-## 3. onebot：OneBot / NapCat 权限
+## 4. onebot：OneBot / NapCat 权限
 
 `onebot.enabled=true` 后采用显式白名单：`botAccounts` 或 `userAccounts` 为空都会拒绝对应账号。
 
-### 3.1 botAccounts 与 userAccounts
+### 4.1 botAccounts 与 userAccounts
 
 - `botAccounts`：机器人 QQ、备注、启用状态。
 - `userAccounts`：用户 QQ、主角称呼、稳定人物 ID、人物资料、初始关系、启用状态。
@@ -109,7 +141,7 @@ Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址
 
 同一现实人物的多个账号可复用 `personId`。不同人物必须分别填写资料和关系，不能把所有 QQ 当作同一关系分支。
 
-### 3.2 groupChats
+### 4.2 groupChats
 
 | 字段 | 说明 |
 | --- | --- |
@@ -120,10 +152,22 @@ Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址
 | `contextLimit` | 主叙事读取的最近群消息数。 |
 | `debounceSeconds` | 合并连续群消息的等待时间。 |
 | `cooldownSeconds` | 主角群发言后的最短冷却。 |
+| `willingness` | 可选的纯算法群聊意愿：积累、半衰减、阈值概率与成功发言成本。 |
 
 群聊不再调用独立快速筛选模型。满足入口规则的消息在合并后直接交给主叙事，由主叙事决定是否输出 `groupReply`。
 
-## 4. sharedStory：共享剧本
+对 `responseMode=always` 的活跃群，可开启 `willingness`。它完全在本地按算法运行：普通群消息累积意愿、按半衰期自然衰减、接近上限时增益递减、超过阈值后按概率决定是否进入主模型；主角成功群发言后会扣除意愿。关键词与引用机器人消息可增加意愿，@ 机器人始终绕过概率。它默认关闭，只作用于这个群，不影响私聊、Alter、Agency、自动推进或主提示词，也不产生额外模型调用。
+
+### 4.3 voiceTranscription：SnowLuma 私聊语音转写
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `false` | 启用 SnowLuma `fetch_ptt_text`。仅处理当前私聊中的 QQ `record` 语音。 |
+| `timeoutMs` | `20000` | 转写最大等待时间；超时后仍保留语音事实并继续本轮。 |
+
+转写成功后，主模型收到的用户事件会带有 `[用户语音转写]` 标记，并和当前文本、图片一起构成同一个回合。该功能需要 SnowLuma 支持原始 OneBot `fetch_ptt_text` 动作；NapCat 或其它实现不支持时会安全降级。它不把音频文件或 base64 写入 HDSI 数据库。
+
+## 5. sharedStory：共享剧本
 
 当前运行时固定为“同一机器人账号一个活动主剧本”，因此不再显示旧版 `enabled` 开关。
 
@@ -136,14 +180,14 @@ Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址
 | `participantContextLimit` | 单次请求携带的其它参与者摘要数量。 |
 | `managerAccounts` | 有权执行全局管理命令的 QQ；空表表示所有已授权用户。 |
 
-## 5. runtime：对话与时间
+## 6. runtime：对话与时间
 
-### 5.1 消息合并、回复和失败恢复
+### 6.1 消息合并、回复和失败恢复
 
 | 字段 | 说明 |
 | --- | --- |
 | `captureDirectMessages` | 是否接管私聊。 |
-| `autoCreate` | 没有故事时是否自动创建；关闭时先执行 `interlude.init`。 |
+| `autoCreate` | 没有故事时是否从当前 Console 档案自动启动；关闭时先执行 `interlude.doctor`，再由管理员执行 `interlude.story.start`。 |
 | `ignoreCommandMessages` | 防止管理命令进入剧本。 |
 | `userMessageDebounceSeconds` | 合并连续私聊的静默等待时间，默认 2 秒。 |
 | `narrativeRetryDelaySeconds` / `narrativeRetryMaxAttempts` | 叙事服务失败后的重试节奏。 |
@@ -151,13 +195,13 @@ Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址
 | `minimumDelayedReplySeconds` / `maximumDelayedReplyMinutes` | 模型允许计划的延迟范围。 |
 | `maxScriptCharacters` / `maxMessageCharacters` | 单回合剧本和单条可见消息的字符上限。 |
 
-### 5.2 分段消息
+### 6.2 分段消息
 
 `splitReplyMessages` 开启后，模型可以用 `messageSeparator`（默认 `<sep/>`）拆分聊天气泡。`typingBaseDelaySeconds`、`typingCharactersPerSecond` 和 `typingMaxDelaySeconds` 控制后续气泡的模拟输入时间。
 
 主模型尚未提交第一条回复时，新消息会废弃旧请求，并把旧、新消息合并后重新写作，不再受固定秒数窗口限制。第一条回复已经提交后，新消息会取消剩余分段；未发送文字以 `interruptedOutgoingDrafts` 进入替代提示词，表示主角想发送但被新消息打断，不能视为已送达内容。
 
-### 5.3 自动生活和主动联系
+### 6.3 自动生活和主动联系
 
 | 字段 | 说明 |
 | --- | --- |
@@ -171,7 +215,7 @@ Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址
 | `proactiveWillingnessThreshold` | 主模型主动联系意愿门槛。 |
 | `contextEntryLimit` / `memoryLimit` | 主叙事携带的近期条目和长期事实数量。 |
 
-## 6. agency：主体行动窗口
+## 7. agency：主体行动窗口
 
 Agency Window 只描述角色能否采取外部联系行动的现实条件，不描述情绪、关系阶段或联系风格。
 
@@ -186,9 +230,9 @@ Agency Window 包含 `activityLoad`、`privacy` 和 `deviceAccess`。自动生
 
 `runtime.allowProactiveMessages=false` 时 Agency 不产生可见联系。`proactiveWillingnessThreshold`、白名单和单回合动作上限仍然是最终安全边界。Agency 不读取 Alter 数值，也不会影响文风。
 
-## 7. memory：连续性与记忆
+## 8. memory：连续性与记忆
 
-### 7.1 整理触发和预算
+### 8.1 整理触发和预算
 
 - `enabled`
 - `backgroundIntervalMinutes`
@@ -199,22 +243,22 @@ Agency Window 包含 `activityLoad`、`privacy` 和 `deviceAccess`。自动生
 - `factContentCharacters`
 - `maxFactsPerStory` / `maxStoriesPerCompactionRun`
 
-近期使用原始剧本；更早内容通过场景、剧情弧线和长期事实压缩。压缩只处理已经发生的内容，不会制造未来事件。
+近期使用原始剧本；更早内容通过场景、剧情弧线和长期事实压缩。默认在 16 条未压缩条目或 10000 个字符达到其一时整理，短对话会保留更宽的连续回合缓冲。压缩只处理已经发生的内容，不会制造未来事件。
 
-### 7.2 事实排序
+### 8.2 事实排序
 
-`factImportanceWeight`、`factConfidenceWeight`、`factRecencyWeight`、`semanticWeight` 和 `unresolvedWeight` 共同决定旧事实进入主提示词的顺序。没有可用 Embedding 时语义分数自动退化为零。
+`factImportanceWeight`、`factConfidenceWeight`、`factRecencyWeight`、`semanticWeight` 和 `unresolvedWeight` 共同决定旧事实进入主提示词的顺序。Embedding 可用时，语义分数参与排序；否则语义分数为零。
 
-### 7.3 剧情余波
+### 8.3 剧情余波
 
 - `activeConsequencesEnabled`
 - `activeConsequencePromptLimit`
 - `activeConsequenceMaxDays`
 - `activeConsequenceDefaultStrength`
 
-余波保存已经发生事件的短期影响，不是永久人格标签，也不会自行触发额外写作。
+余波保存已经发生事件的短期影响，保持具体、短期，并由后续事件自然收束。
 
-### 7.4 Overlay 演化与压缩
+### 8.4 Overlay 演化与压缩
 
 普通状态提案需满足置信度、至少三个独立剧本回合、至少两个日期以及同路径冷却。相关字段包括：
 
@@ -229,7 +273,7 @@ Agency Window 包含 `activityLoad`、`privacy` 和 `deviceAccess`。自动生
 
 Overlay 压缩字段包括 `overlayCompressionEnabled`、近期保留天数、周/月窗口和摘要字符上限。管理员可使用 `interlude.overlay.status`、`interlude.overlay.compact` 和 `interlude.overlay.clear` 检查或维护。
 
-## 8. alterSystem：临时氛围偏移
+## 9. alterSystem：临时氛围偏移
 
 Alter 只衡量本轮新事件对整体氛围造成的净变化：正数偏严肃，负数偏轻松，范围 `-5..5`。
 
@@ -243,11 +287,11 @@ Alter 只衡量本轮新事件对整体氛围造成的净变化：正数偏严
 | `minWeight` | `0.2` | 低于此值清除旧 offset。 |
 | `maxIntensity` | `2` | 新 offset 强度上限。 |
 
-`modelId` 优先选择集中模型预设；`providerId` / `model` 是兼容回退。`temperature`、`topP`、`maxTokens`、`timeout` 和 `prompt` 控制低频分析请求。
+Alter 模型由上方 `useForAlter` 选择。`temperature`、`topP`、`maxTokens`、`timeout` 和 `prompt` 只控制这项低频分析任务。
 
 达到阈值后，本轮先完成剧本、状态和可见消息；侧端分析在同一故事队列中后台运行，不阻塞当前回复。失败时保留累计值并进入五分钟冷却。完整算法见 `docs/ALTER_SYSTEM.md`。
 
-## 9. browser：只读网页观察
+## 10. browser：只读网页观察
 
 需要同时启用 Koishi Puppeteer。插件只允许搜索或访问公开 HTTP(S) 页面，不登录、不填表、不下载、不发布内容，并拒绝 localhost、私网和不安全协议。
 
@@ -266,7 +310,7 @@ Alter 只衡量本轮新事件对整体氛围造成的净变化：正数偏严
 
 `allow-immediate` 会为少数私聊额外执行一次观察并重新请求主叙事，因此延迟和费用都更高。首次测试使用 `deferred-only`。
 
-## 10. logging：日志与隐私
+## 11. logging：日志与隐私
 
 | 字段 | 说明 |
 | --- | --- |