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

package/BEGINNER_GUIDE.md

@@ -1,6 +1,6 @@
 # HDS Interlude 新手引导
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.4-beta1`
 
 HDS Interlude 是 Koishi 的持续叙事聊天插件。插件使用共享主剧本保存角色状态、关系分支、已发生事件、待处理计划和长期记忆。用户消息会进入当前活动场景；主模型在同一次请求中续写已经发生的生活，并决定是否发送、延迟发送或暂不发送消息。实时写作读取一条按时间排序的活动场景记录：最近剧本文字、真实用户消息和已经成功投递的角色消息在同一条线上。剧本引子、场景外近期事实和长期记忆负责更早的历史。
 
@@ -45,13 +45,11 @@ Console 页面建议按以下顺序填写：`blindMode`（首次保持关闭）
 ### 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
@@ -59,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 可以直接在该行配置。
 
 主叙事提示词：
 
@@ -103,7 +96,7 @@ model.stylePrompt:
 
 从主角此刻手头正在做的事情继续写。让时间通过具体行动向前移动：拿起或放下的物品、进行到哪一步的任务、身体产生的需要、环境中的变化、临时出现的安排，以及周围人物正在做出的选择。细节应参与行动和因果，使读者能够感到这一段生活确实发生过。
 
-根据真实经过的时间选择合适的叙事密度。短暂间隔聚焦一个新动作、注意力变化或对话进展；较长间隔选择几个有连接的生活时刻，表现任务、地点、身体状态、陪伴者和计划怎样逐步变化。
+按当前阶段和已经经过的生活连续书写：用户消息、对话后续、到期意图与自动推进各自提供明确事件边界；调度间隔只决定何时唤醒写作，不预设叙事密度。
 
 让主角同时拥有眼前事务、当天安排、个人兴趣、现实压力和未解决的小事。每次选择当前最能自然推进的部分，并让偶然变化从既有处境中生长，例如计划调整、物品带来的麻烦、配角提出的新安排、环境变化或意外发现。
 
@@ -120,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

package/CONFIGURATION_GUIDE.md

@@ -1,6 +1,6 @@
 # HDS Interlude 配置指南
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.4-beta1`
 
 第一次安装先看 `BEGINNER_GUIDE.md`。本文件严格按照 Koishi Console 的显示顺序说明当前字段；旧版本已经移除或隐藏的字段集中列在末尾，不再混入正常配置流程。
 
@@ -34,7 +34,7 @@
 | --- | --- |
 | `characterName` | 主角名称。 |
 | `characterProfile` | 主角身份、性格、作息、习惯、压力和行为边界。 |
-| `perspective` | 主角个体价值观 / 看待世界的方式。它是独立于 Canon 的外壳人格层：只在相关事件中自然影响判断，不是剧情主题、道德说教或逐话题审查。长期剧情可形成 `perspective` overlay。 |
+| `perspective` | 主角个体价值观 / 看待世界的方式。它作为独立于 Canon 的外壳人格层，在相关事件中自然影响判断；长期剧情可形成 `perspective` overlay。 |
 | `userProfile` | 没有账号专属资料时使用的默认用户背景。 |
 | `relationship` | 新参与者与主角的默认初始关系。 |
 | `world` | 时间、地点、社会与现实规则。 |
@@ -54,39 +54,61 @@
 ### 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` 不调用远程模型，只适合验证插件、数据库和命令是否安装成功。
 
+### 智谱官方提供商模式
+
+在任意一行 `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 对象。 |
 
-### 3.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`：主叙事唯一的输出格式设置
 
 ### 3.4 failover 与提示词
 
@@ -101,9 +123,9 @@
 
 ### 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`。非标准网关应填写完整地址。
 
@@ -130,9 +152,12 @@ Embedding 地址留空时，插件会尝试从标准 `/chat/completions` 地址
 | `contextLimit` | 主叙事读取的最近群消息数。 |
 | `debounceSeconds` | 合并连续群消息的等待时间。 |
 | `cooldownSeconds` | 主角群发言后的最短冷却。 |
+| `willingness` | 可选的纯算法群聊意愿：积累、半衰减、阈值概率与成功发言成本。 |
 
 群聊不再调用独立快速筛选模型。满足入口规则的消息在合并后直接交给主叙事，由主叙事决定是否输出 `groupReply`。
 
+对 `responseMode=always` 的活跃群，可开启 `willingness`。它完全在本地按算法运行：普通群消息累积意愿、按半衰期自然衰减、接近上限时增益递减、超过阈值后按概率决定是否进入主模型；主角成功群发言后会扣除意愿。关键词与引用机器人消息可增加意愿，@ 机器人始终绕过概率。它默认关闭，只作用于这个群，不影响私聊、Alter、Agency、自动推进或主提示词，也不产生额外模型调用。
+
 ### 4.3 voiceTranscription：SnowLuma 私聊语音转写
 
 | 字段 | 默认值 | 说明 |
@@ -222,7 +247,7 @@ Agency Window 包含 `activityLoad`、`privacy` 和 `deviceAccess`。自动生
 
 ### 8.2 事实排序
 
-`factImportanceWeight`、`factConfidenceWeight`、`factRecencyWeight`、`semanticWeight` 和 `unresolvedWeight` 共同决定旧事实进入主提示词的顺序。没有可用 Embedding 时语义分数自动退化为零。
+`factImportanceWeight`、`factConfidenceWeight`、`factRecencyWeight`、`semanticWeight` 和 `unresolvedWeight` 共同决定旧事实进入主提示词的顺序。Embedding 可用时，语义分数参与排序；否则语义分数为零。
 
 ### 8.3 剧情余波
 
@@ -231,7 +256,7 @@ Agency Window 包含 `activityLoad`、`privacy` 和 `deviceAccess`。自动生
 - `activeConsequenceMaxDays`
 - `activeConsequenceDefaultStrength`
 
-余波保存已经发生事件的短期影响，不是永久人格标签，也不会自行触发额外写作。
+余波保存已经发生事件的短期影响，保持具体、短期，并由后续事件自然收束。
 
 ### 8.4 Overlay 演化与压缩
 
@@ -262,7 +287,7 @@ 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`。
 

package/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,220 @@
+# HDS Interlude 部署教程
+
+> 写给第一次把 HDSI 接到 QQ 上、并希望角色能长期生活下去的人。
+
+（必看）准备工作：
+
+硬件：一台能长时间稳定运行的电脑；普通 i5 级别处理器、8 GB 以上内存和稳定网络通常足够。模型调用依赖网络，自动推进与长对话更需要避免频繁休眠、断网或强制关机。
+
+软件：Koishi Desktop、Node.js（加入 PATH，能使用 `npm`）、最新版电脑 QQ（QQNT 内核）、NapCatQQ。若准备查看数据库，建议安装 VS Code 与 SQLite Viewer 扩展。
+
+准备好以后，现在让我们开始吧！
+
+## 一、安装 Koishi 与 NapCat
+
+Koishi 官网：[https://koishi.chat/](https://koishi.chat/)
+
+一般 Windows 用户在官网选择“用于搭建机器人服务”→“Windows”→ 安装包（`.msi`）。网络不稳定时，也可从 Koishi Desktop 的 GitHub Releases 下载对应安装包：
+
+[https://github.com/koishijs/koishi-desktop/releases](https://github.com/koishijs/koishi-desktop/releases)
+
+接下来下载 NapCatQQ：
+
+[https://github.com/NapNeko/NapCatQQ/releases](https://github.com/NapNeko/NapCatQQ/releases)
+
+Windows 用户在 Assets 中选择 `NapCat.Shell.zip`，解压后按默认方式安装即可。
+
+> **配图位置 1：** Koishi Desktop 下载页中“用于搭建机器人服务 / Windows / 安装包”的选择界面。
+>
+> **配图位置 2：** NapCat Releases 页面中 `NapCat.Shell.zip` 的位置。
+
+## 二、启动 Koishi，安装必要插件
+
+Koishi 第一次启动会准备运行环境，耐心等待即可。
+
+> **配图位置 3：** Koishi Desktop 的主界面。
+
+进入插件市场，确认下列插件可用：
+
+- `hds-interlude`：HDSI 本体；
+- `adapter-onebot`：Koishi 与 NapCat 的连接；
+- SQLite 数据库插件：通常由 Desktop 默认安装，确认其已启用；
+- `puppeteer`：推荐但非必需。需要网页观察、动态图片代表帧时再启用，默认参数即可。
+
+如果市场加载缓慢，可重试刷新。HDSI 尚未发布到你使用的市场源时，可以安装本地发布包：
+
+```powershell
+cd C:\Users\你的用户名\AppData\Roaming\Koishi\Desktop\data\instances\default
+npm install C:\路径\koishi-plugin-hds-interlude-0.1.3.tgz
+```
+
+安装完成后回到 Koishi Console，添加或启用 `hds-interlude`。
+
+每次完成重要配置，都要点击右上角的“保存配置”或“重载配置”。
+
+## 三、配置 NapCat，并连接 OneBot Adapter
+
+运行 NapCat 目录中的 launcher 批处理文件。出现二维码后，用手机 QQ 扫码登录你准备作为机器人的 QQ 账号。
+
+登录成功后，在浏览器进入 NapCat WebUI：
+
+```text
+http://127.0.0.1:6099/webui/
+```
+
+默认密码请以 NapCat 当前界面提示为准；登录后建议立刻修改。
+
+> **配图位置 4：** NapCat WebUI 首页。
+
+进入“网络配置”，新建 WebSocket 服务器。监听地址、端口与 Token 需要和 Koishi 的 OneBot Adapter 完全一致。Token 可以自行设置，但请妥善保存，不要发到聊天记录、截图或公开配置中。
+
+> **配图位置 5：** NapCat 的“新建 WebSocket 服务器”配置页面；图中应标出地址、端口、Token 三处。
+
+回到 Koishi 的 `adapter-onebot` 配置：
+
+- `selfId` 填机器人 QQ 号；
+- WebSocket 地址填刚才创建的服务器地址；
+- Token 与 NapCat 中保持一致；
+- 保存并启动插件。
+
+日志出现连接成功提示、Koishi 右下角状态变绿后，QQ 与 Koishi 的通信就正常了。
+
+> **配图位置 6：** OneBot Adapter 的配置页面。
+>
+> **配图位置 7：** Koishi 右下角绿色连接状态或成功日志。
+
+## 四、配置 HDSI 的模型中心
+
+进入 `hds-interlude` 插件配置。HDSI 的模型配置只需要记住一件事：**一行模型连接，就是一个实际可调用的模型；在这一行勾选它承担什么用途。**
+
+在 `model.providers` 添加模型连接。只要存在一条启用、且模型名与连接信息完整的模型行，HDSI 就会自动启用远程主叙事；不需要再设置全局模型模式。
+
+### 普通 OpenAI-compatible 提供商
+
+该行的 `mode` 选择 `openai-compatible`。保存并重载后，填写：
+
+- 显示名称；
+- Endpoint；
+- API Key；
+- 实际模型名；
+- 主叙事 / 压缩 / Alter / Embedding 用途开关。
+
+例如，一个只负责主叙事的模型就只勾选“用作主叙事模型”。一个低成本模型可以只勾选“用作后台压缩模型”。Embedding 模型必须确实支持 `/embeddings`，不要把普通聊天模型误勾为 Embedding。
+
+常用官方模式还包括 `openai-official`、`deepseek-official`、`moonshot-official`、`dashscope-official`、`siliconflow-official`、`openrouter` 与 `gemini-openai`。每一种在提供商行选中后都会固定其官方 endpoint，只显示 API Key、模型名和必要的地域选项；它们可以和智谱、普通中转站行同时存在。
+
+### 智谱官方 GLM 提供商
+
+如果使用智谱官方 API，在该行的 `mode` 选择 `zhipu-official`，保存并重载。该行会只显示：
+
+- 智谱 API Key；
+- 模型名，例如 `glm-5.3-flash`；
+- 推理强度：`low`、`high` 或 `max`。
+
+智谱官方 endpoint 会自动填写，不能与同一行的普通 endpoint 混用。GLM‑5.3‑Flash 会走 SSE 流式接收：首个可见文本最长等待 45 秒，收到首字后不设置总等待上限。它仍在完整 JSON 解析成功后才向 QQ 投递，保证剧本与消息记录一致。
+
+视觉模型才开启 `model.vision.enabled`。普通文本模型保持关闭；使用 GLM‑5.3‑Flash 时可在确认官方模式可用后再测试图片。
+
+> **配图位置 8：** HDSI 模型中心全貌：提供商行中的 `mode` 下拉，以及四个用途开关。
+>
+> **配图位置 9：** 同一提供商行切换为 `zhipu-official` 后，只显示 API Key、模型名、推理强度的界面。
+
+主叙事下方的温度、top-p、最大输出、超时和 JSON / prompt 输出格式，只影响主叙事。压缩、Alter、Embedding 在各自区域拥有独立的任务参数；模型本身已经在上方的用途开关决定，不需要再填写任何 `providerId`、`modelId` 或 `mainModelId`。
+
+首次测试建议：
+
+- 只启用一条主叙事模型；
+- 关闭 `model.vision.enabled`、Embedding 与主动消息；
+- `mainResponseFormat` 选择 `json-object`；
+- 先确认一次普通私聊能正常完成。
+
+## 五、创建角色与 QQ 白名单
+
+HDSI 的人设不放在某个隐藏的 Markdown 文件夹，而是直接写进 Console 的故事档案。
+
+进入 `storyDefaults`，填写：
+
+- 主角名称；
+- 角色资料：身份、习惯、作息、语言与现实边界；
+- Perspective：主角看待人和世界的稳定方式；
+- 默认用户资料与初始关系；
+- 世界、地点、重要配角、叙事风格与时区。
+
+然后进入 `onebot`：
+
+- 在 `botAccounts` 填机器人 QQ；
+- 在 `userAccounts` 填允许私聊测试的 QQ；
+- 为每位用户填写主角对其的称呼、资料与初始关系；
+- 第一次部署建议只放一位测试用户。
+
+> **配图位置 10：** `storyDefaults` 的角色、人设、Perspective、世界和时区区域。
+>
+> **配图位置 11：** `onebot.botAccounts` 与 `onebot.userAccounts` 白名单表。
+
+首次部署保持 `blindMode.enabled=false`。失明模式会屏蔽命令与 HDSI 详细日志，适合模型、账号和故事档案完全稳定之后再开启。
+
+保存配置后，在已授权的私聊中执行：
+
+```text
+interlude.doctor
+interlude.story.start
+```
+
+`interlude.doctor` 会检查模型、白名单、时区和故事档案；`interlude.story.start` 会确认创建第一份主剧本。
+
+## 六、第一次对话与自动生活
+
+先发一条普通 QQ 消息。正常情况下，你会看到：收到用户消息、模型调用、剧本写入、角色消息投递。
+
+确认普通私聊稳定后，再逐项开启：
+
+1. 自动推进与对话后续；
+2. Alter System；
+3. Agency Window 与主动联系；
+4. Embedding、网页观察、群聊与视觉能力；
+5. 最后才考虑失明模式。
+
+HDSI 的角色不需要手工维护一堆提示词文件。角色的 Canon、Perspective、世界、关系和文风都在 Console；长期发生的剧情会由剧本、场景摘要、事实、Overlay 与意图共同保存。
+
+> **配图位置 12：** 一次成功私聊的 HDSI 分层日志：收到消息 → 模型调用 → 完成 → 消息投递。
+
+## 七、数据库、备份与调试
+
+HDSI 的故事数据保存在：
+
+```text
+C:\Users\你的用户名\AppData\Roaming\Koishi\Desktop\data\instances\default\data\koishi.db
+```
+
+它包含 HDSI 的故事、参与者、剧本条目、长期事实、意图、场景、Overlay 等表。使用 VS Code 的 SQLite Viewer 可以只读查看和排查问题。
+
+但请注意：
+
+- 先关闭 Koishi 或复制数据库备份，再进行任何人工修改；
+- 不建议直接删除或篡改表记录，优先使用 `interlude.overlay.clear`、`interlude.memory.add`、`interlude.memory.forget` 等管理指令；
+- 数据库保存的是 HDSI 的剧本与状态，不等于模型的原始隐藏推理过程；
+- API Key、NapCat Token、日志和数据库都不要公开。
+
+## 八、常见问题
+
+### 模型一直请求中、超时或 429
+
+先确认只有正确的聊天模型勾选了“用作主叙事模型”。Embedding 模型不要参加主叙事用途。GLM‑5.3‑Flash 建议使用提供商行的 `zhipu-official` 模式；它会使用官方 endpoint 与流式首字超时策略。
+
+### 图片一发就 Bad Request
+
+确认当前主叙事模型支持视觉，再开启 `model.vision.enabled`。普通文本模型必须关闭视觉。智谱官方模式会使用兼容的 `image_url.url` 字段；普通 OpenAI-compatible 网关是否支持图片，仍取决于该网关和模型。
+
+### 看不到机器人回复
+
+依次检查：NapCat 是否在线、OneBot Adapter 是否连接、机器人 QQ 是否在 `botAccounts`、你的 QQ 是否在 `userAccounts`、`blindMode` 是否关闭，以及模型连接是否勾选了“用作主叙事模型”。
+
+### 重载后无法用指令
+
+先确认 `blindMode.enabled=false`。失明模式开启时，HDSI 管理指令与当前 Koishi 实例中已识别的命令都会被静默屏蔽。
+
+夜深了。确认一切正常后，去和她/他聊第一句话吧；从那一刻起，HDSI 的故事才真正开始。
+
+---
+
+HDS Interlude 部署教程，基于 HDSI 当前 Console 与 OneBot/NapCat 流程整理。需要更新截图时，优先替换文中标注的十二个“配图位置”。

package/README.md

@@ -4,11 +4,12 @@
 
 HDS Interlude 是一个面向 Koishi 一对一与多参与者场景的持续叙事聊天框架。它让用户消息、角色的沉默、延迟回复、主动联系和自动推进，都成为同一段生活剧本中自然可见的部分，并由一次主叙事写作连贯地决定。
 
-当前版本：`0.1.3-beta4`（沉浸式失明模式与结构化投递一致性增强预发布版）。如需生产环境，建议先在独立 Koishi 实例中验证后再升级。
+当前版本：`0.1.4-beta1`（测试版）。提供持续生活剧本、结构化投递、群聊意愿、多提供商模型连接与可选聊天动作。
 
 ## 文档导航
 
 - 第一次安装和测试：[BEGINNER_GUIDE.md](BEGINNER_GUIDE.md)
+- 从零部署 QQ 角色：[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)
 - 逐项配置说明：[CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md)
 - 管理员命令：[command.md](command.md)
 - 当前架构：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
@@ -201,7 +202,7 @@ Alter System 是一个动态氛围响应机制，用于解决长期对话中角
 | maxIntensity | 2.0 | 最大强度上限，防止过度极端 |
 | densityFactor | 0.3 | 对话密度影响因子，密集对话时降低阈值 |
 
-侧端分析模型还可配置 `modelId`、兼容的 `providerId/model`、温度、输出长度、超时和附加提示词。侧模型遇到失败时，系统会保留累计轨迹并在后续条件合适时重试。
+侧端分析模型由模型中心中勾选“用作 Alter 侧端分析模型”的连接提供；温度、输出长度、超时和附加提示词在 Alter 设置内单独调整。侧模型遇到失败时，系统会保留累计轨迹并在后续条件合适时重试。
 
 ### 使用建议
 
@@ -223,6 +224,8 @@ OneBot 模式采用显式白名单：启用后，绑定的机器人 QQ 账号和
 
 群聊与私聊分开配置。群聊需要单独列入群白名单并填写群用途、主角在群中的身份和发言模式；符合白名单和调度条件的群聊消息直接进入主叙事模型，不再额外调用快速判断模型。
 
+对 `responseMode=always` 的活跃群，可按群开启纯算法 `willingness`：本地意愿分数会随消息、关键词和引用累积，按半衰期衰减，并在超过阈值后以概率决定是否值得调用主模型。@ 机器人始终可以立即通过，主角成功发言后会消耗意愿。这个层只减少不必要的群聊主模型调用，不参与私聊、Alter 或 Agency。
+
 ## 图片与网页观察
 
 ### 原生视觉
@@ -256,13 +259,13 @@ npm install koishi-plugin-hds-interlude@beta
 使用本地预发布包时，可在 Koishi 实例目录执行：
 
 ```bash
-npm install /absolute/path/to/koishi-plugin-hds-interlude-0.1.3-beta4.tgz
+npm install /absolute/path/to/koishi-plugin-hds-interlude-0.1.4-beta1.tgz
 ```
 
 Windows 示例：
 
 ```powershell
-npm install C:\dev\HDS-Interlude\plugins\hds-interlude\release\koishi-plugin-hds-interlude-0.1.3-beta4.tgz
+npm install C:\dev\HDS-Interlude\plugins\hds-interlude\release\koishi-plugin-hds-interlude-0.1.4-beta1.tgz
 ```
 
 安装后重新加载 Koishi，再在 Console 启用插件。
@@ -285,7 +288,9 @@ OneBot / NapCat 未启动时可能出现 `ECONNREFUSED`，表示适配器正在
 
 1. **失明模式**：首次配置保持关闭；稳定运行后可开启以获得无命令、极少 HDSI 日志的沉浸式对话。
 2. **基础设定**：主角、世界、配角、叙事风格、默认关系。
-3. **模型中心**：先添加服务提供商，再添加可复用模型预设；主叙事、压缩、Embedding 和 Alter 分析按需选择模型预设。
+3. **模型中心**：先确认图片理解开关；每个模型连接只填一次地址、密钥和模型名，再勾选它承担主叙事、压缩、Alter 或 Embedding 的用途；下方分别调整各任务的采样与输出。
+
+使用 GLM‑5.3‑Flash 时，可在对应模型连接行选择 `mode=zhipu-official`：仅填写智谱 API Key、模型名与推理强度，插件会使用官方 endpoint 和流式请求策略；同一配置内的其它模型行仍可使用普通 OpenAI-compatible 模式。
 4. **平台控制**：启用 OneBot 后填写机器人 QQ、私聊用户白名单；如需群聊，再添加群白名单。
 5. **剧情节奏**：连续消息合并、自动推进、休息时段、延迟消息和主动联系意愿阈值。
 6. **Agency Window**：日程负荷、隐私、设备和主动联系重查边界。

package/command.md

@@ -1,6 +1,6 @@
 # HDS Interlude 管理员指令
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.3`
 ## 使用前先看这里
 
 - 新手安装和首次测试：`BEGINNER_GUIDE.md`

package/docs/AGENCY_WINDOW.md

@@ -1,6 +1,6 @@
 # Agency Window
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.3`
 
 ## 定位
 

package/docs/ALTER_SYSTEM.md

@@ -1,6 +1,6 @@
 # Alter System
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.3`
 
 ## 定位
 
@@ -46,7 +46,7 @@ Alter System 追踪一部持续生活剧本的临时氛围惯性。它只向主
 
 成功后保存新 offset、权重设为 1、记录方向并清零累计值。失败时不清零、不伪造 offset，并至少等待五分钟再尝试。
 
-Alter 分析复用模型预设、Provider、OpenAI-compatible 协议、超时和 failover，但不是普通 compactor 请求。
+Alter 分析复用模型预设、Provider、OpenAI-compatible 协议、超时和 failover，并作为独立的低频分析请求运行。
 
 ## 主模型注入
 

package/docs/ARCHITECTURE.md

@@ -1,12 +1,12 @@
 # 当前架构
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.3`
 
 ## 核心原则
 
 HDS Interlude 使用 `0.1.1-beta6` 验证过的自然语言连续性路线：近期上下文以原始剧本为主，低频 continuitySnapshot 和长期事实负责跨时间衔接。已回滚的 sceneTrace、sceneState、storyHook、logicalTurn 和 relationshipMoment 不属于当前架构。
 
-用户消息是进入主角生活的真实外部事件。主模型在一个回合内补写从故事游标到现在已经发生的生活，并决定看见、沉默、立即回复、延迟回复或产生其它受限行动。自动推进没有当前用户事件，不能伪造新消息。
+用户消息是进入主角生活的真实外部事件。主模型在一个回合内补写从故事游标到现在已经发生的生活，并决定看见、沉默、立即回复、延迟回复或产生其它受限行动。自动推进围绕主角已在进行的生活展开。
 
 ## 模块职责
 
@@ -32,6 +32,8 @@ HDS Interlude 使用 `0.1.1-beta6` 验证过的自然语言连续性路线：近
 5. 服务规范化所有模型字段，保存剧本和状态，再执行受权限和时间约束的消息投递。
 6. 后台扫描处理自动生活推进、到期意图、记忆压缩、Overlay 压缩、网页观察和旧事实向量补齐。
 
+群聊可选的 willingness 层位于群消息缓冲与主叙事之间：它只维护每个群的内存分数，以半衰减、边际递减、阈值概率和成功发言成本决定普通 `always` 群消息是否值得进入主模型。它不写数据库、不调用模型、不影响私聊、Alter 或 Agency；@ 机器人绕过该概率门。
+
 Alter 达到阈值时，本轮只保存累计状态并安排后台分析。当前可见回复不会等待侧端模型；分析任务仍进入同一故事队列，避免与下一次状态写入竞争。
 
 ## 连续性分层
@@ -53,7 +55,7 @@ Alter 达到阈值时，本轮只保存累计状态并安排后台分析。当
 
 主动联系使用现有 intent 表形成闭环：生活剧本产生真实理由，Agency Window 判断立即联系、`proactive-check` 稍后重查或自然放下。重查时重新读取当前生活，不保存预写消息。关系身份会在后台以受控摘要提供，但原始私聊仍按共享开关隔离。
 
-场景压缩可顺带更新最多八项在场状态，每项必须引用本次压缩中的真实剧本条目；没有证据的告别、抵达或重逢会被拒绝。自动投递摘要最多保留六项，并且只在 `advance` 与 `conversation-follow-up` 回合进入提示词；用户实时回合和普通到期意图不读取它。
+场景压缩可顺带更新最多八项在场状态，每项引用本次压缩中的真实剧本条目。自动投递摘要最多保留六项，并且只在 `advance` 与 `conversation-follow-up` 回合进入提示词。
 
 承诺回访最多保留每位参与者两项待处理内容。它只在创建承诺的用户回合、用户后续消息和该承诺到期时进入提示词，携带事项、类型、时间和来源；普通自动推进不读取它。到期回合没有可见结果时，原 intent 会保留并延后，而不会静默完成。
 

package/docs/CHANGELOG.md

@@ -1,11 +1,34 @@
 # 版本记录
 
-## 0.1.3-beta4
+## 0.1.4-beta1
+
+- 新增轻量聊天动作能力层，默认关闭；仅当 Console 开关、当前平台和适配器能力同时满足时，相关字段才进入主提示词。
+- QQ/OneBot 群聊支持指定消息回复与单条消息表情回应；模型只读取 `msg-*` 安全引用，HDSI 在本地映射真实 OneBot 消息 ID。
+- 群聊消息记录补充可操作消息 ID；成功表情回应写入轻量动作回执，并复用群聊意愿成本与冷却，避免绕过防刷屏约束。
+- Console 可选择 QQ、微信或同时选择作为聊天动作目标平台；当前内置执行器为 QQ/OneBot，未注册的微信连接器不会向模型暴露动作字段。
+- 入站指定回复现在读取 Koishi `session.quote`，将被引用消息的作者与正文作为本轮独立引用上下文交给主模型；无引用时不增加提示字段。
+- 新增默认关闭的本地表情包库：每五分钟扫描新增或变更的 PNG/JPEG/WebP/GIF 素材，按分组与单素材描述建立本地索引。
+- 模型连接行新增 `useForStickers`；只有勾选并完整配置的视觉模型才会为新表情包生成描述。主模型仅在库中存在已描述素材且当前 OneBot 回合可投递媒体时读取受限目录。
+- 主模型可精确选择描述最匹配的本地表情包；HDSI 验证素材 ID 后发送原始文件，并把实际发送描述写入动作回执。GIF 描述使用代表帧，投递保持原动图。
+- 修复旧式“引用：原句”被当普通文本发送：现在会映射近期可引用的真实 OneBot 消息 ID 并发送 QQ 引用；无映射目标时阻止伪引用文本。
+- 修复模型将 `[表情]`、`[图片]`、`[动图]` 等占位词作为普通消息发送；引用内容与旧剧本进一步标记为已发生历史，避免被误写成刚刚发生的新事件。
+- 加入动作引用范围、表情白名单、提示词条件注入和隐私边界的回归测试。
+
+## 0.1.3
 
 - 新增 Console 首位的 `blindMode` 失明模式：HDSI 不注册管理指令，并在执行前静默拦截当前 Koishi 实例中已解析的命令；普通聊天仍进入叙事。旧 `blackBox` 配置保留兼容读取。
 - 失明模式隐藏 HDSI 运行、错误、消息预览与模型侧调试记录，仅按可配置间隔输出无故事内容的健康心跳；其它插件日志保持各自配置。
 - 对话后续阶段的已发送私聊现在要求与 `interaction.reply` 使用同一段文本，避免剧本写到投递动作而结构化回复仍为 `none`。
 - README 改以“固定阶段、连续生活”说明写作机制：调度间隔只决定唤醒时机，不再定义不同的写作尺度。
+- 重排模型 Console：视觉开关前置，服务商行仅保留连接信息，实际模型名只在预设填写一次，主叙事只保留一份采样和输出格式；单一启用预设可自动复用为主叙事、压缩与 Alter 模型。
+- 进一步合并模型配置中心：模型连接行直接分配主叙事、压缩、Alter、Embedding 四类用途，Console 不再要求填写 `providerId`、`modelId` 或 `mainModelId`；旧配置引用继续兼容读取。
+- 新增每提供商独立的 `zhipu-official` 模式：智谱行固定官方 endpoint，配置仅保留 API Key、模型与推理强度；GLM‑5.3‑Flash 主叙事改用 SSE，首字等待上限 45 秒、首字后无总时限，并使用智谱兼容的图片字段。普通 OpenAI-compatible 提供商可与智谱行混用。
+- 新增 OpenAI、DeepSeek、Kimi/Moonshot、阿里云百炼、硅基流动、OpenRouter 与 Gemini 的每提供商官方预设；各行固定其官方 Chat Completions endpoint，仍可与自定义 OpenAI-compatible 网关混用。
+- 移除冗余的全局 `model.mode` Console 字段；是否启用远程模型由启用且完整的提供商行自动判断，旧字段仅保留读取兼容。
+- 新增群聊专用的纯算法 willingness：按群本地累积、半衰减、边际递减、阈值概率和成功发言成本筛选 `responseMode=always` 的普通消息；@ 机器人绕过概率，默认关闭且不影响私聊或其它系统。
+- 群聊投递兼容 `groupReply` 与即时 `interaction.reply`，并在结构化可见回复缺失时丢弃未落库剧本、带恢复指令重写一次。
+- SnowLuma STT 保持默认关闭；Console 收束模型连接、失明模式、群聊意愿与语音转写的提示文案。
+- 群聊意愿判断前置到冷却查询之前，减少未触发群的数据库读取。
 
 ## 0.1.3-beta3
 

package/docs/SECURITY.md

@@ -1,6 +1,6 @@
 # 安全与依赖说明
 
-适用版本：`0.1.3-beta4`
+适用版本：`0.1.3`
 
 ## 发布包边界
 

package/lib/database.d.ts

@@ -1,5 +1,5 @@
 import { Context } from 'koishi';
-import { InterludeArc, InterludeParticipant, InterludeScene, InterludeStory, NarrativeFact, NarrativeIntent, NarrativeMemory, OverlaySnapshot, ScriptEntry, StatePatchProposal, WebObservation } from './types';
+import { InterludeArc, InterludeParticipant, InterludeScene, InterludeStory, NarrativeFact, NarrativeIntent, NarrativeMemory, OverlaySnapshot, ScriptEntry, StatePatchProposal, StickerAsset, WebObservation } from './types';
 declare module 'koishi' {
     interface Tables {
         interlude_story: InterludeStory;
@@ -12,6 +12,7 @@ declare module 'koishi' {
         interlude_fact: NarrativeFact;
         interlude_state_patch: StatePatchProposal;
         interlude_overlay_snapshot: OverlaySnapshot;
+        interlude_sticker: StickerAsset;
         interlude_web_observation: WebObservation;
     }
 }