@fg-lab/amadeus-qq 1.2.1 → 1.2.2

package/docs/RELEASE_NOTES.md

@@ -1,38 +1,38 @@
-## 1.2.1 compatibility candidate (2026-10-31)
-
-Real official Host integration exposed reserved QQ Session IDs without the usual `session-` prefix. QQ now reserves standard `session-UUID` IDs. Life also accepts the exact legacy UUID shape for existing trusted Sessions, including its bounded wake query and configuration UI. Workspace membership, trusted Host identity, permissions and wake authorization remain mandatory. Existing IDs and history are preserved; no schema change, Session recreation or production data migration. Public distribution is pending explicit release approval.
-
-# Amadeus QQ 发行说明
-
-## 1.2.0 内部发行候选（未公开发布）
-
-- 统一 `@fg-lab/amadeus-qq@1.2.0`，保留 Bundle ID `amadeus-qq`、Scene/Session 绑定、权限配置和可靠投递数据；本轮聚焦发行包与升级兼容。
-- 预构建 Client、Bundle Manifest、市场图标和迁移说明已纳入候选包。隔离 DSH Desktop `0.2.1-rc.3` 所附 CLI 完成 1.1.1 → 1.2.0 的合成数据升级、重启和恢复演练。
-- 本仓库经所有者确认采用 MIT；本轮发行源为公开 npm 包和固定版本 GitHub Release 包；实际发布须以最终验收结果为准。
-- Desktop 图形安装、公开 Market 下载及真实 NapCat/模型联合运行仍待验收；公开发行需要单独确认。
-
-## 1.1.1 本地交接补丁（未公开发布）
-
-- Owner Web Console 增加“QQ 接管”开关：将同一 NapCat 登录在 Amadeus QQ 与本地 AstrBot 之间手动交接。开关经 DSH 配置服务保存并在重启后恢复，Scene 和 DSH Session 绑定不因切换而重建。
-- 暂停时停止 OneBot WebSocket 接收、拒绝新的 HTTP 操作和 QQ 外发授权，并在配置重载前等待已中断操作的本地记账完成。尚未提交的旧唤醒不在恢复后重放，结果不确定的外发不自动重试。
-- 控制台和 DSH 原生状态使用中文显示交接结果。真实 NapCat 与 AstrBot 的双客户端交接需在用户重装后的隔离环境实机验证。
-
-## 1.1.0 开发基线（未公开发布）
-
-- 六页 Owner 鉴权 Web Console 与简化的 DSH 原生设置入口。首次设置可在 GUI 选择 Workspace、NapCat、Bot、唯一 Owner、Scene 白名单和全局拒绝；Token 不回显。
-- 每个授权 Scene 在选定 Workspace 中建立独立持久 Session；支持暂停、恢复、撤权和重启恢复。
-- 五个权限预设及界面“自定义”状态；普通预设不再继承群管理写权限。权限保存使用修订号冲突检查，执行时继续由可信 Scene Guard 裁决。
-- 当前对话可短时合批、等待补充、按权限发送或沉默；合批静默窗口从最后一条消息计时且有最长等待上限。Life 保持长期自主唤醒职责。
-- 账号资料与 QQ 空间配置分离；功能中心标明源码接线、Provider 与平台验收边界。
-- 本候选尚未完成 v1.1 真实 NapCat 入站/外发与 Life 并发实机验收。详见 [v1.1 测试报告](v1.1/TEST_REPORT.md)。PR #2 已合并 main；尚未公开发布或部署。
-
-## 1.0.0
-
-- 包版本与收缩后的 v1.0 功能范围对齐；保留包名 `@amadeus/qq` 和 Bundle ID `amadeus-qq`。本次版本收口不新增 QQ 能力。
-- 持续 Scene Session、Owner Agent、五级权限和执行期 Guard、消息与附件回执、本机 NapCat 媒体/ASR、外部音频交接、账号头像与签名、QQ 空间文字/图片说说、原生 Settings 与独立 Web Console 均沿用已审查实现。
-- 普通 QQ Scene 的 Memory reader 仅在 Memory 提供可信 Scene ACL 读契约时可见并执行；缺失或撤销时立即拒绝。Life 的 `externalMessageSessionIds` 只提供唤醒提示，QQ Scene Guard 负责外发授权。
-- 隔离 Desktop、NapCat 与 QQ 的既有实机覆盖见 [验收记录](verification/V1_REAL_NAPCAT_2026-10-27.md)；最终包与四插件同 Profile 验收见[联合报告](https://github.com/jeskoky-pixel/Amadeus-dsh/blob/main/docs/verification/AMADEUS_V1_FOUR_PLUGIN_ACCEPTANCE.md)。未部署生产，也未公开发布。
-
-## 范围和限制
-
-交付范围以 [V1_SCOPE.md](V1_SCOPE.md) 为准。长期平台稳定性、任意目标外发、所有低频 QQ API、移动端视觉细节和未安装的 Host 原生工具没有同等级实机证据；不将这些作为已验证能力宣称。
+## 1.2.1 compatibility candidate (2026-10-31)
+
+Real official Host integration exposed reserved QQ Session IDs without the usual `session-` prefix. QQ now reserves standard `session-UUID` IDs. Life also accepts the exact legacy UUID shape for existing trusted Sessions, including its bounded wake query and configuration UI. Workspace membership, trusted Host identity, permissions and wake authorization remain mandatory. Existing IDs and history are preserved; no schema change, Session recreation or production data migration. Public distribution is pending explicit release approval.
+
+# Amadeus QQ 发行说明
+
+## 1.2.0 内部发行候选（未公开发布）
+
+- 统一 `@fg-lab/amadeus-qq@1.2.0`，保留 Bundle ID `amadeus-qq`、Scene/Session 绑定、权限配置和可靠投递数据；本轮聚焦发行包与升级兼容。
+- 预构建 Client、Bundle Manifest、市场图标和迁移说明已纳入候选包。隔离 DSH Desktop `0.2.1-rc.3` 所附 CLI 完成 1.1.1 → 1.2.0 的合成数据升级、重启和恢复演练。
+- 本仓库经所有者确认采用 MIT；本轮发行源为公开 npm 包和固定版本 GitHub Release 包；实际发布须以最终验收结果为准。
+- Desktop 图形安装、公开 Market 下载及真实 NapCat/模型联合运行仍待验收；公开发行需要单独确认。
+
+## 1.1.1 本地交接补丁（未公开发布）
+
+- Owner Web Console 增加“QQ 接管”开关：将同一 NapCat 登录在 Amadeus QQ 与本地 AstrBot 之间手动交接。开关经 DSH 配置服务保存并在重启后恢复，Scene 和 DSH Session 绑定不因切换而重建。
+- 暂停时停止 OneBot WebSocket 接收、拒绝新的 HTTP 操作和 QQ 外发授权，并在配置重载前等待已中断操作的本地记账完成。尚未提交的旧唤醒不在恢复后重放，结果不确定的外发不自动重试。
+- 控制台和 DSH 原生状态使用中文显示交接结果。真实 NapCat 与 AstrBot 的双客户端交接需在用户重装后的隔离环境实机验证。
+
+## 1.1.0 开发基线（未公开发布）
+
+- 六页 Owner 鉴权 Web Console 与简化的 DSH 原生设置入口。首次设置可在 GUI 选择 Workspace、NapCat、Bot、唯一 Owner、Scene 白名单和全局拒绝；Token 不回显。
+- 每个授权 Scene 在选定 Workspace 中建立独立持久 Session；支持暂停、恢复、撤权和重启恢复。
+- 五个权限预设及界面“自定义”状态；普通预设不再继承群管理写权限。权限保存使用修订号冲突检查，执行时继续由可信 Scene Guard 裁决。
+- 当前对话可短时合批、等待补充、按权限发送或沉默；合批静默窗口从最后一条消息计时且有最长等待上限。Life 保持长期自主唤醒职责。
+- 账号资料与 QQ 空间配置分离；功能中心标明源码接线、Provider 与平台验收边界。
+- 本候选尚未完成 v1.1 真实 NapCat 入站/外发与 Life 并发实机验收。详见 [v1.1 测试报告](v1.1/TEST_REPORT.md)。PR #2 已合并 main；尚未公开发布或部署。
+
+## 1.0.0
+
+- 包版本与收缩后的 v1.0 功能范围对齐；保留包名 `@amadeus/qq` 和 Bundle ID `amadeus-qq`。本次版本收口不新增 QQ 能力。
+- 持续 Scene Session、Owner Agent、五级权限和执行期 Guard、消息与附件回执、本机 NapCat 媒体/ASR、外部音频交接、账号头像与签名、QQ 空间文字/图片说说、原生 Settings 与独立 Web Console 均沿用已审查实现。
+- 普通 QQ Scene 的 Memory reader 仅在 Memory 提供可信 Scene ACL 读契约时可见并执行；缺失或撤销时立即拒绝。Life 的 `externalMessageSessionIds` 只提供唤醒提示，QQ Scene Guard 负责外发授权。
+- 隔离 Desktop、NapCat 与 QQ 的既有实机覆盖见 [验收记录](verification/V1_REAL_NAPCAT_2026-10-27.md)；最终包与四插件同 Profile 验收见[联合报告](https://github.com/jeskoky-pixel/Amadeus-dsh/blob/main/docs/verification/AMADEUS_V1_FOUR_PLUGIN_ACCEPTANCE.md)。未部署生产，也未公开发布。
+
+## 范围和限制
+
+交付范围以 [V1_SCOPE.md](V1_SCOPE.md) 为准。长期平台稳定性、任意目标外发、所有低频 QQ API、移动端视觉细节和未安装的 Host 原生工具没有同等级实机证据；不将这些作为已验证能力宣称。

package/docs/UPGRADE_POLICY.md

@@ -1,26 +1,26 @@
-# QQ 升级与数据保留政策
-
-适用包：`@fg-lab/amadeus-qq`；运行时插件 ID：`amadeus-qq`。v1.2.0 从 `1.1.1` 升级。本政策从 v1.2.0 起用于后续 v1.2.1、v1.3.0 和主版本发布。
-
-## 代码、配置与数据
-
-安装包只放程序及资源，可在升级时替换。用户数据位于插件包之外：DSH Profile 中的 Bot/Owner/连接配置、显式绝对路径 `statePath` 中的 Scene、Session 绑定、消息和投递账本；DSH 自身 Session 日志；配置的媒体目录。 不能把唯一副本放进 `node_modules`、插件包或可被 Market 清理的安装目录。升级时记录并沿用原 Profile、Bundle ID 和数据路径；若升级后看似空白，先核对路径和 Workspace，不能初始化覆盖。
-
-## 四种操作
-
-| 操作 | 约定 |
-| --- | --- |
-| 安装 | 创建缺失的结构；发现既有数据时先校验，绝不以空默认值覆盖。 |
-| 升级 | 只替换代码；保留 Profile 配置和外部数据。支持的迁移先备份、校验、执行、复核，失败即停止启用。 |
-| 禁用 | 停止监听、定时器和写入，数据仍留在原目录。 |
-| 卸载 | 插件自身不删除用户数据；DSH Market/Plugin Manager 对 Profile 配置的实际保留行为须在目标 Desktop 版本实测，卸载前导出 Profile。彻底清除数据是独立人工操作。 |
-
-## 固定升级步骤
-
-1. 记录旧包版本/ SHA-256、DSH 版本、数据路径、Schema Version 与跨插件组合；保留旧 `.tgz`。
-2. 停止 QQ 连接和写入，备份 DSH Profile、`statePath` 文件及配置的媒体目录。投递状态为 `unknown` 时先与平台人工对账，不自动重发。
-3. 在隔离 Profile 用官方 Plugin Manager 或已验收的 Market 更新入口安装候选包，不执行用户侧构建脚本。
-4. 重启并检查原有内容、关系、权限、Session/Workspace 绑定、配置及关键功能；重点：Scene 权限、Session ID、Owner/白名单、可靠投递与 `unknown` 状态、重启后绑定、连续对话和 NapCat 断开默认值。
-5. 通过后再在目标 Profile 分批升级。若失败，先禁用，保存故障现场，按 `DATA_MIGRATION.md` 恢复兼容数据库和旧包；不能假设旧代码一定能读已迁移的新数据。
-
-每个新版本的 CI 必须从上一稳定版的合成真实格式数据升级到当前版，测试关键字段、关联、权限、重启和失败恢复。跨插件 Host 契约不兼容时应先适配或限制组合版本。小版本不得无说明删除既有能力；弃用需标记、替代方案和兼容周期。
+# QQ 升级与数据保留政策
+
+适用包：`@fg-lab/amadeus-qq`；运行时插件 ID：`amadeus-qq`。v1.2.0 从 `1.1.1` 升级。本政策从 v1.2.0 起用于后续 v1.2.1、v1.3.0 和主版本发布。
+
+## 代码、配置与数据
+
+安装包只放程序及资源，可在升级时替换。用户数据位于插件包之外：DSH Profile 中的 Bot/Owner/连接配置、显式绝对路径 `statePath` 中的 Scene、Session 绑定、消息和投递账本；DSH 自身 Session 日志；配置的媒体目录。 不能把唯一副本放进 `node_modules`、插件包或可被 Market 清理的安装目录。升级时记录并沿用原 Profile、Bundle ID 和数据路径；若升级后看似空白，先核对路径和 Workspace，不能初始化覆盖。
+
+## 四种操作
+
+| 操作 | 约定 |
+| --- | --- |
+| 安装 | 创建缺失的结构；发现既有数据时先校验，绝不以空默认值覆盖。 |
+| 升级 | 只替换代码；保留 Profile 配置和外部数据。支持的迁移先备份、校验、执行、复核，失败即停止启用。 |
+| 禁用 | 停止监听、定时器和写入，数据仍留在原目录。 |
+| 卸载 | 插件自身不删除用户数据；DSH Market/Plugin Manager 对 Profile 配置的实际保留行为须在目标 Desktop 版本实测，卸载前导出 Profile。彻底清除数据是独立人工操作。 |
+
+## 固定升级步骤
+
+1. 记录旧包版本/ SHA-256、DSH 版本、数据路径、Schema Version 与跨插件组合；保留旧 `.tgz`。
+2. 停止 QQ 连接和写入，备份 DSH Profile、`statePath` 文件及配置的媒体目录。投递状态为 `unknown` 时先与平台人工对账，不自动重发。
+3. 在隔离 Profile 用官方 Plugin Manager 或已验收的 Market 更新入口安装候选包，不执行用户侧构建脚本。
+4. 重启并检查原有内容、关系、权限、Session/Workspace 绑定、配置及关键功能；重点：Scene 权限、Session ID、Owner/白名单、可靠投递与 `unknown` 状态、重启后绑定、连续对话和 NapCat 断开默认值。
+5. 通过后再在目标 Profile 分批升级。若失败，先禁用，保存故障现场，按 `DATA_MIGRATION.md` 恢复兼容数据库和旧包；不能假设旧代码一定能读已迁移的新数据。
+
+每个新版本的 CI 必须从上一稳定版的合成真实格式数据升级到当前版，测试关键字段、关联、权限、重启和失败恢复。跨插件 Host 契约不兼容时应先适配或限制组合版本。小版本不得无说明删除既有能力；弃用需标记、替代方案和兼容周期。

package/docs/verification/IMAGE_READ_FIX_2026-11-07.md

@@ -0,0 +1,22 @@
+# QQ 图片读取修复（2026-11-07）
+
+## 根因
+
+生产 Profile 已声明 `mediaRoot`，但 NapCat 的 `get_image` 返回的是其自己的 provider cache 路径，通常不在 QQ 插件私有目录内。旧实现把这个安全的、由绑定消息句柄返回的路径当成越界路径拒绝；首次运行时目录缺失也会导致同样的失败。
+
+## 修复
+
+- QQ 插件启动时创建已配置的绝对 `mediaRoot`，避免新安装因目录缺失直接失败。
+- `qq_read_message_image` 仍优先使用配置的 `mediaRoot`。当 OneBot 返回 provider cache 文件时，只有在显式配置的 `providerCacheRoot` 之内才允许读取，并使用 canonical regular-file、完整路径符号链接拒绝、5 MiB 上限和图片签名检查。这个路径只来自绑定消息的 `get_image` 回读，不接受模型输入的路径。
+- 内联 base64 不读取 URL。mediaRoot 缺失时仍要求 providerCacheRoot 有效，无法建立可信 provider 根时明确失败。Host 权限在平台调用前后各复核一次。
+
+## 验证
+
+- 定向图片与 Host 边界测试：27 通过、1 个 Windows 符号链接权限跳过、0 失败。
+- 回归覆盖：声明的 provider cache 在 mediaRoot 外可读、未声明 provider 根被拒绝、provider 根外路径被拒绝、canonical 内联 PNG 可保存为 Host attachment。
+- 现有生产 `mediaRoot`：`C:\Users\Jesko\.dsh\profiles\desktop\data\amadeus-qq\media`；修复部署前已创建该目录。
+- 旧安装目录实际仍加载了未包含 provider-cache 回退的 QQ 包，因此真实图片请求报 `QQ_MEDIA_PATH_OUTSIDE_ROOT`。工作树修复已重新打包并安装到主 DSH。
+- 当前包 SHA-256：`E383FE0DEAFA4445A6F6CF1092F03A826BE10F143643A288FA5836C5B152B3A8`；安装目录 `src/media.js` SHA-256：`279FBF61C9FB41A45A2ED597DBA00A78ED2A961645318E2C284F353757674F9C`，与工作树一致。
+- 新 TIM 图片事件 `messageId=2009581422` 的原始 OneBot 句柄为 `565D42CED7DA9903A72A4E50388AF672.jpg`。NapCat `get_image(file=该句柄)` 返回可信 provider cache 路径 `...\\Pic\\2026-11\\Ori\\565d42ced7da9903a72a4e50388af672.jpg`，文件大小 `263144` 字节、JPEG 签名有效。使用当前包的真实 OneBot transport 和主 QQ state 回读，已成功生成 Host attachment `sha256:test-real`。
+- 这条图片在旧包运行期间进入，随后 DSH 才重启并换成新 Session，因此没有形成新的模型回合。当前 DSH 已监听 `127.0.0.1:3081`，要取得“图片进入实际 Provider 请求并由模型回答”的证据，需要在重启后的连接窗口再发送一条新图片。
+

package/docs/verification/LIFE_QQ_BOUNDARY_2026-11-07.md

@@ -0,0 +1,20 @@
+# QQ Life 工具边界（2026-11-07）
+
+## 契约
+
+`amadeus.life.read` 是 QQ Scene 的显式只读 grant。它不改变 `safe-chat` 默认权限，也不授予 QQ 外发、Life 管理、Owner 或文件系统能力。
+
+有该 grant 的 Scene 创建带 Life 读取能力的受限 preset。没有该 grant 的 Scene 使用原有 preset，工具不会进入其可见工具集合。Life 读取工具在执行函数内再次验证真实 QQ Session、当前 Scene、Workspace、权限 revision 和显式 grant。
+
+`life_shared_read` 调用 Core 提供的 `life.getSharedLifeView`，`life_health` 调用 Core 提供的 `life.getScopedHealth`。QQ 不读取 Life 数据库，也不创建第二套调度器。
+
+## 版本
+
+本次修改由 QQ 仓库提交 `97fdb39` 之后的工作树产生。最终提交和构建哈希在安装记录中补充。
+
+## 当前证据
+
+- 本地 QQ 回归测试通过。
+- 未授权 Session 的执行 guard 继续拒绝 `amadeus.life.read`。
+- 真实 TIM 在桥接版本重新安装后的工具 schema 和两次真实调用仍需复测。
+