@fg-lab/amadeus-qq 0.0.0-stage → 1.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jeskoky-pixel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# Amadeus QQ
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/market-icon.png" width="80" alt="Amadeus qq logo">
+
+[简体中文](README.zh-CN.md) · [Detailed configuration](REFERENCE.md) · [Issues](https://github.com/jeskoky-pixel/amadeus-qq/issues)
+
+QQ conversations with persistent DSH Sessions and explicit Scene permissions.
+
+Target package: **`@fg-lab/amadeus-qq@1.2.1`**. Tested runtime baseline: official DSH Desktop **0.2.1-rc.3**. MIT licensed.
+
+## Release status
+
+**1.2.1 is published:** [GitHub Release](https://github.com/jeskoky-pixel/amadeus-qq/releases/tag/v1.2.1) · [npm](https://www.npmjs.com/package/@fg-lab/amadeus-qq). Install the pinned version and verify the release checksum. Later main changes do not change this immutable archive. See [publishing policy](docs/PUBLISHING.md).
+
+## What you can do
+
+- Connect an existing local NapCat instance to authorized groups and private chats, each with a persistent DSH Session in your Workspace.
+- Continue a current conversation using read, wait, mark-read and guarded sends; deduplicate delivery attempts and preserve Session history across ordinary configuration edits.
+- Handle supported text, mentions, replies and media through capability-specific checks. Provider-dependent features remain conditional.
+- Choose Observe, Safe Chat, Enhanced or Autonomous Social presets; trusted administrator private chats may use Owner Agent. Global denials and QQ platform permissions always apply.
+- Manage account/profile operations and optional QQ Space capabilities on their separate account page. Availability depends on the actual provider and configured grants.
+- Pause NapCat listening for handoff to another application. QQ owns current conversations; optional Life owns long-term wake scheduling.
+
+Example: authorize a test group in Observe, inspect inbound status, then select Safe Chat when ready to allow replies. Use the Web Console to inspect effective permissions instead of assuming that a preset grants every tool.
+
+NapCat is not bundled: this plugin does not install, log in to or host NapCat. An unconfigured installation sends nothing. Dangerous tools are not enabled by default. Memory, Life, State and Persona are optional; QQ does not grant access to their private data merely by receiving a message.
+
+## Install and configure
+
+Install the prebuilt `.tgz` with the official DSH plugin manager into your selected Profile. No local source build is required. Follow [installation instructions](docs/INSTALL_V1_2.md); do not copy configuration into a running Profile by hand.
+
+Connect NapCat, choose a Workspace, set the Owner QQ number and authorize individual Scenes. Start with Observe.
+
+The other Amadeus plugins are optional. Install only the integrations you need.
+
+## Interface
+
+![Amadeus Qq interface](docs/screenshots/product-release-20261031.png)
+
+This is a recorded interface screenshot, not evidence that every real platform capability passed the current release gate. See the detailed reference and verification reports for limitations.
+
+## Upgrade and recovery
+
+Back up user data before upgrading. Code, persistent user data and recovery backups are separate. Disable stops functionality; uninstall is intended to retain external data. Restoring old code alone does not reverse a database migration.
+
+- [Upgrade policy](docs/UPGRADE_POLICY.md)
+- [Data migration and recovery](docs/DATA_MIGRATION.md)
+- [Release checklist](docs/RELEASE_CHECKLIST.md)
+- [Full configuration and limitations](REFERENCE.md)
+
+## Ecosystem and license
+
+[Amadeus project](https://github.com/jeskoky-pixel/Amadeus-dsh) · [MIT license](LICENSE)
+
+The 2026-11-06 development increment adds conservative recovery of a persisted scene binding only when the official Host confirms its Session is missing. See [current verification](docs/FULL_CYCLE_2026-11-06.md); lookup errors and Workspace mismatches never trigger an identity rebuild.

package/README.zh-CN.md

@@ -0,0 +1,51 @@
+# Amadeus QQ
+
+<img src="assets/market-icon.png" width="80" alt="Amadeus qq logo">
+
+[English](README.md) · [详细配置参考](REFERENCE.md)
+
+通过持久 DSH 会话与明确的场景权限连接 QQ。
+
+目标发行包：**`@fg-lab/amadeus-qq@1.2.1`**。已验证的官方 DSH Desktop 基线：**0.2.1-rc.3**。许可证：MIT。
+
+## 当前发行状态
+
+已发布 **1.2.1**：[GitHub Release](https://github.com/jeskoky-pixel/amadeus-qq/releases/tag/v1.2.1) · [npm](https://www.npmjs.com/package/@fg-lab/amadeus-qq)。请安装固定版本；发行包校验值见 Release。后续源码修改不代表该版本安装包发生变化。
+
+## 能帮你做什么
+
+- 将已登录的本地 NapCat 接入获授权的群聊与私聊，每个场景在指定工作区拥有独立持久 DSH 会话。
+- 用读取、等待补充、标记已读和受权限约束的发送维持当前交流；去重投递，普通配置修改保留会话历史。
+- 支持代码已实现的文字、@、引用及媒体能力，逐项检查权限；依赖 Provider 的功能以实际可用状态为准。
+- 选择仅观察、安全聊天、增强对话或自主群友；仅可信管理员私聊可选择 Owner Agent。全局拒绝与 QQ 平台权限始终有效。
+- 在独立账号页管理资料及可选 QQ 空间能力；是否可用取决于实际 Provider 与授权。
+- 暂停监听以交接给其他应用。QQ 负责当前交流，可选 Life 负责长期自主唤醒。
+
+示例：先把测试群加入仅观察模式，确认入站正常，再切换安全聊天允许回复。通过控制台查看有效权限，不要把选择预设理解为开放全部工具。
+
+插件不包含 NapCat，不负责其安装、登录或托管。未配置时不会外发，危险工具不默认开放。Memory、Life、State、Persona 均为可选联动，收到 QQ 消息不代表获得其他插件的私有数据权限。
+
+## 安装与首次配置
+
+使用官方 DSH 插件管理器将预构建 `.tgz` 安装到所需 Profile，无需手工构建源码。按[安装说明](docs/INSTALL_V1_2.md)操作，不要手工改写正在运行的 Profile。
+
+配置 NapCat、选择工作区、填写管理员 QQ 号并逐项授权场景。建议先选择仅观察。
+
+其他 Amadeus 插件均为可选联动，按需要分别安装。
+
+## 界面
+
+![Amadeus Qq 界面](docs/screenshots/product-release-20261031.png)
+
+截图展示已有界面，不表示本轮所有真实平台能力均已通过。具体限制请阅读配置参考和验收报告。
+
+## 升级与回滚
+
+升级前备份用户数据。程序、持久数据和恢复备份分开保存。禁用停止功能；卸载默认保留外部数据。回退旧程序不能自动撤销数据库迁移。
+
+- [升级政策](docs/UPGRADE_POLICY.md)
+- [数据迁移与恢复](docs/DATA_MIGRATION.md)
+- [发行检查清单](docs/RELEASE_CHECKLIST.md)
+- [完整配置与限制](REFERENCE.md)
+
+[项目主页](https://github.com/jeskoky-pixel/Amadeus-dsh) · [MIT 许可证](LICENSE)

package/REFERENCE.md

@@ -0,0 +1,49 @@
+# Amadeus QQ 1.2.1（发行候选）
+
+此候选版提供预构建 DSH Bundle，可从隔离的 DSH 插件管理器安装 `.tgz`。已在官方 DSH Desktop `0.2.1-rc.3` 附带的运行时验证；公开 npm 与市场收录尚未执行。安装、升级、卸载和数据保留见 [v1.2 安装说明](docs/INSTALL_V1_2.md)、[升级政策](docs/UPGRADE_POLICY.md) 与 [数据迁移](docs/DATA_MIGRATION.md)。此前 1.1.1 的验收记录保留在下文。
+
+Amadeus QQ 是独立的 DeepSeek Harness 插件，通过本机 NapCat/OneBot 连接 QQ。每个授权群聊或好友私聊使用一个持久 DSH Session；消息读取、模型工具外发、媒体、回执与权限检查均留在插件内。Memory、Life、State 是可选联动，QQ 单独安装也能处理当前对话。
+
+## 首次使用
+
+1. 在 DSH Desktop 的插件管理器安装 `@fg-lab/amadeus-qq` 包。打开插件设置页，进入受 DSH Owner 鉴权保护的 Web Console。
+2. 在“全局设置”选择已有 DSH Workspace，填写 Bot QQ 号、唯一 Owner QQ 号、本机 NapCat HTTP/WebSocket 地址及需要的 Access Token。Token 保存后不回显。
+3. 添加授权群号或好友 QQ 号；Owner 私聊自动加入白名单。保存并应用，按页面提示连接 NapCat。
+4. 到“会话管理”选择预设，查看每项**实际生效**的权限，保存。授权 Scene 会在所选 Workspace 中建立独立 Session；可暂停、恢复或移出白名单。
+5. 到“运行与诊断”检查连接、授权和 Session 状态。账号资料与 QQ 空间的授权位于独立的“账号与 QQ 空间”页。
+
+默认的普通预设不授予群管理写权限。手工修改权限或行为参数会显示“自定义”；重新选择预设会覆盖该 Scene 的整套预设。“全局设置”可管理对所有 Scene 生效的全局拒绝。可信 Owner、Scene 白名单和 QQ 平台权限始终优先。模型只能通过受控 QQ 工具发送消息，普通文本输出不会自动外发。
+
+## 与本地 AstrBot 轮流使用同一个 QQ
+
+只运行一个登录该 QQ 号的本机 NapCat。Amadeus QQ 与 AstrBot 可以配置同一 NapCat 的本机 OneBot 地址和各自所需的 Token；同一时间只让一方接管消息。在 Amadeus QQ Web Console 的“全局设置 → QQ 接管”点击“暂停 Amadeus，交给 AstrBot”，确认页面显示“已暂停”后再启动 AstrBot。切回时先停用 AstrBot，再点击“恢复由 Amadeus 接管”。开关仅由 DSH Owner 操作，状态保存在 DSH 配置中，重启后仍有效。
+
+暂停会断开 Amadeus 的 WebSocket 接收并拒绝新的 OneBot HTTP 操作、QQ 模型工具外发和 Life 经 QQ 的发送授权；已有 Scene、DSH Session 与历史消息保留。交接前已提交给 NapCat 的请求可能已经执行，无法撤回，结果不确定的动作不会自动重发。AstrBot 接管期间的消息不会自动补入 Amadeus；交接时尚未发起的旧 QQ 唤醒也不会在恢复后延迟回复。
+
+## 页面与架构
+
+Web Console 有总览、会话管理、功能中心、账号与 QQ 空间、全局设置、运行与诊断六页，支持浅色和深色主题。原生 DSH 设置页仅提供状态与入口。短消息可在有上限的静默窗口内合批；Agent 可等待补充、分条发送或保持沉默。QQ 不拥有长期自主唤醒或冷场定时调度，长期活动由可选的 Life 插件负责。
+
+功能中心区分源码接线、Provider 配置与实际平台可用性；显示“源码已接线”并不代表已在所有 NapCat 版本实机验证。QQ 空间依赖单独 Provider。
+
+## 验证与当前边界
+
+`npm run build` 和 `npm test` 可检查安装包及回归测试。v1.1.1 完整回归为 **303 项：298 通过、0 失败、5 跳过**。隔离 DSH Desktop 已验证 GUI 首次设置、Owner 鉴权、Workspace 内的双 Scene Session、权限编辑、暂停和重启恢复。新交接开关尚未在重装后的真实 NapCat 与 AstrBot 上完成实机切换；[v1.0 真实 QQ 验收](docs/verification/V1_REAL_NAPCAT_2026-10-27.md)只能作为既有能力的历史证据。此次合并仅作为个人电脑实机测试基线，不代表生产部署许可。
+
+- [v1.1 测试报告](docs/v1.1/TEST_REPORT.md)
+- [1.1.1 本地 AstrBot 交接验收](docs/verification/QQ_ASTRBOT_HANDOFF_2026-10-29.md)
+- [四插件联合验收与未完成项目](docs/verification/FOUR_PLUGIN_V11_JOINT_2026-10-28.md)
+- [权限预设矩阵](docs/v1.1/PRESET_MATRIX.md)
+- [升级说明](docs/v1.1/UPGRADE.md)
+- [原型差异](docs/v1.1/PROTOTYPE_DIFF.md)
+- [发行说明](docs/RELEASE_NOTES.md)与[兼容性](docs/COMPATIBILITY.md)
+
+## 开发与隐私
+
+仅在隔离 Profile 和授权测试 QQ 场景验收。不要将生产 DSH Profile、NapCat、QQ Bridge、Memory/Life/State 数据或真实 Token 加入仓库。`npm pack` 生成本地安装包；此仓库不自动发布或部署。项目总览见 [Amadeus-dsh](https://github.com/jeskoky-pixel/Amadeus-dsh)。
+
+Persona 等可信 Host 插件可使用只读的 [已授权 Scene 发现契约](docs/PERSONA_SCENE_CONTRACT.md) 在首条消息前配置场景；QQ 白名单与发送权限仍由 QQ 插件管理。
+
+## 许可证与发行
+
+本仓库采用 [MIT 许可证](LICENSE)。v1.2 发行包已配置为公开 npm 包；GitHub Release、npm 实际发布及 DSH Market 收录状态以发行验收报告为准。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Real OneBot connectivity is disabled until an administrator configures it.
+- insert:
+    - id: amadeus-qq
+      name: '@fg-lab/amadeus-qq'
+      config:
+        enabled: false

package/docs/COMPATIBILITY.md

@@ -0,0 +1,17 @@
+# Amadeus QQ 1.1.1 开发基线兼容性
+
+| 对象 | 本轮基线 | 契约 |
+| --- | --- | --- |
+| DSH Desktop | 隔离实测 `0.2.1-rc.3` | 使用官方 Session、工具、Settings、Plugin Manager、Config Editor 与 Workspace 服务；其他 DSH 版本需隔离复验。 |
+| Node.js | `>=22.13.0` | 遵循 `package.json` 的 `engines`。 |
+| 本机 NapCat | 现有 OneBot 11 接口 | 首次 GUI 配置本机 HTTP/WS、Token 与授权 Scene；v1.1 候选未重新完成真实入站/外发验收。 |
+| Life | 可选，1.1.0 | 只消费受控 Wake 所在 DSH Session；Life opt-in 不取代 QQ 执行期权限。交接暂停时 QQ 外发授权会拒绝。 |
+| Memory | 可选，1.0.1 | 普通 QQ Scene 的三个 `memory_*` reader 依赖 [可信 Scene ACL 契约](contracts/qq-memory-scene-acl-v1.md)，缺失时安全拒绝。 |
+| State | 可选，1.1.0 | QQ 无硬依赖；State 不提供 QQ 权限或独立 Persona。 |
+| Persona | 可选，0.1.0 | 通过可信 QQ Scene 映射选择表达风格；暂停交接时没有新的 QQ 消息唤醒。 |
+
+插件包名为 `@fg-lab/amadeus-qq`，Bundle ID 为 `amadeus-qq`。五个插件各自保留独立安装、状态和回滚路径；不共享 SQLite 文件。QQ 不创建第二个主 Agent 或人格。
+
+1.0 状态文件可沿用；新 Workspace 绑定会撤销旧 Session 并建立新绑定。先备份独立 QQ 状态与 DSH Profile，再按[升级说明](v1.1/UPGRADE.md)操作。
+
+1.1.1 的 QQ 接管开关沿用现有 `connect` 配置；仅切换连接不更改 Workspace、Scene 白名单或 Session 安全指纹。真实 NapCat 与 AstrBot 轮流接管尚待本机验收。

package/docs/DATA_MIGRATION.md

@@ -0,0 +1,26 @@
+# QQ 数据迁移契约
+
+## 当前格式
+
+1.2.1 只修复 Session ID 兼容性，延续 1.2.0 数据结构；以下历史迁移路径继续适用。
+
+- 发行包：`@fg-lab/amadeus-qq@1.2.1`
+- 持久 Schema Version：JSON schemaVersion 1 (`src/storage.js`)
+- 数据范围：DSH Profile 中的 Bot/Owner/连接配置、显式绝对路径 `statePath` 中的 Scene、Session 绑定、消息和投递账本；DSH 自身 Session 日志；配置的媒体目录。
+- 本轮迁移：1.1.1 → 1.2.0 不改变状态 schema。未知 `schemaVersion` 会拒绝加载，不能把旧状态重建为空对象。
+
+## 未来迁移流程
+
+读取并验证当前版本、完整性和关键关联。未知或未来版本拒绝写入，并给出可读的迁移路径提示。现有数据先创建一致性备份；备份失败即停止。每一步迁移使用事务或原子文件替换，幂等且可重试；内容和引用复核通过后才标记新版本。不能通过删除数据库、清空配置或重新建立 Session 来“修复”错误。
+
+备份必须位于独立用户数据目录，记录时间、原 Schema Version、目标版本和校验值，不能进入发行包或 Git。恢复时区分：只回滚代码、只恢复配置、完整恢复数据库和 Profile。任何不可逆转换都必须保留升级前快照；旧程序如不支持新格式，必须连同旧数据快照恢复。
+
+## v1.2.0 验证清单
+
+- 使用 `1.1.1` 的合成数据，核对升级前后字段内容、关联和权限，而不只比较条数。
+- 停用/启用和硬重启后重新读取。
+- 令备份或迁移失败，确认旧数据仍完整且错误可见。
+- 使用与上一版本匹配的备份演练回滚；不把新版本数据库直接交给旧程序。
+- 验证：Scene 权限、Session ID、Owner/白名单、可靠投递与 `unknown` 状态、重启后绑定、连续对话和 NapCat 断开默认值。
+
+未在真实 DSH Desktop/Market 运行的项目不得在发行报告里记作通过。

package/docs/INSTALL_V1_2.md

@@ -0,0 +1,22 @@
+# Amadeus QQ v1.2.1 安装与升级
+
+当前为内部发行候选。可从本仓库 PR 的 CI artifact 获取预构建 `fg-lab-amadeus-qq-1.2.1.tgz`；公开 npm、GitHub Release 与外部市场收录尚未执行。隔离测试使用官方 DSH Desktop `0.2.1-rc.3` 附带的 DSH 运行时；Desktop 图形安装仍待验收。普通用户不需要 Node、源码构建或 Codex。
+
+## 首次安装
+
+1. 在 DSH Desktop 打开目标 Profile 的插件管理器，选择安装本地预构建包；正式发布后也可选择 `@fg-lab/amadeus-qq@1.2.1` 的 npm 源或固定版本 GitHub Release。
+2. 选择 `fg-lab-amadeus-qq-1.2.1.tgz`，确认已安装插件列表显示 `@fg-lab/amadeus-qq@1.2.1`，并打开其设置页。
+3. 在设置中选择 Workspace、填写 Bot/Owner 与 NapCat，添加授权 Scene；未配置或未启用时不会连接或外发。
+4. 按宿主提示重载或重启，回到设置页检查健康状态。安装失败时不要修改数据目录；保留错误信息与原安装包，然后恢复备份的 Profile。
+
+## 升级
+
+旧版升级前先导出 DSH Profile，停止插件写入，并对用户数据做一致性备份：`statePath` 指向的 Scene JSON、DSH Profile 中的 Bot/Owner/白名单及 DSH Session 日志。使用同一 Profile 安装 v1.2.1 包，不更换 Workspace、插件 ID 和数据路径。重启后检查内容与关键关联；仅在确认新版本正常后清理旧安装包。详细迁移和回滚规则见 [升级政策](UPGRADE_POLICY.md) 与 [数据迁移](DATA_MIGRATION.md)。
+
+## 禁用、卸载与恢复
+
+禁用只停止功能，保留数据。卸载默认只移除代码；用户数据位于安装包之外。插件管理器对 Profile 中配置条目的保留行为取决于宿主，卸载前必须导出 Profile。重新安装同一版本并恢复原配置路径可重新读取数据。彻底删除数据是独立、明确的人工操作，不能由安装脚本自动执行。
+
+## 发行边界
+
+当前本地预构建包已通过隔离官方 `dsh plugin` 安装；尚未通过公开 Market 下载源，也未验证生产 QQ/NapCat 或个人 Profile。不要把内部候选包当作已公开发布版本。

package/docs/PUBLISHING.md

@@ -0,0 +1,28 @@
+# Publishing @fg-lab/amadeus-qq 1.2.1
+
+Publication is an explicit operation after release acceptance, not a side effect of a main-branch push. The `npm-publish.yml` workflow is manual and only accepts a version tag whose commit is contained in main. It uses GitHub OIDC (`id-token: write`) and npm provenance, not a repository npm token.
+
+## Account setup
+
+The npm package must exist and the maintainer must have publication rights in `@fg-lab`. Configure npm Trusted Publishing for owner `jeskoky-pixel`, repository `amadeus-qq`, workflow file `npm-publish.yml`, environment `npm-release`. Never put an npm token or recovery code in an issue, commit or screenshot. Initial package creation may require an authenticated, 2FA-approved publish; OIDC configuration is not assumed to exist before the package does.
+
+## Release gates
+
+1. Review the final commit, tests, prebuilt assets, license, package inventory and sensitive-file scan.
+2. Complete the current real-runtime and platform gates. CI alone is insufficient.
+3. Test install, upgrade, disable, uninstall/reinstall and recovery using the candidate archive. Retain the package hash and report.
+4. Verify main protection, required checks and protected `v*` tags. Tags cannot be updated or deleted.
+5. Create a tag from the final tested main HEAD. Never reuse a version or move a published tag.
+6. Dispatch the workflow with the exact commit SHA. Its `npm-release` environment must be configured for the same Trusted Publisher identity. Review generated package contents before authorizing any account-side publish.
+7. Download the published npm and GitHub Release archives; compare SHA-256 and npm integrity with the actual published bytes, inspect metadata and install from the public source. If builds differ, do not claim byte identity or silently replace artifacts.
+8. Publish checksums, source commit, tested Desktop version, schema compatibility, upgrade/rollback instructions and known limitations with the release.
+
+## Recovery
+
+Do not overwrite a published npm version. Investigate and publish a new patch when necessary. Data rollback may require restoring the matching backup, not only old code. Preserve historical archives and checksums. Market directory inclusion is not a security audit; external Market PR submission remains a separate action.
+
+## 当前状态
+
+2026-10-31：npm 与 GitHub Release 已发布，固定版本和 SHA-256 见 Release。初始 npm 版本由所有者通过浏览器认证发布，不带 npm OIDC provenance；不得将 SHA 校验等同于该证明。
+
+五包的 npm Trusted Publisher 已通过 CLI 配置并读取验证，限定为各自仓库、`npm-publish.yml` 和 `npm-release` 环境。后续 OIDC 工作流尚未用新版本执行，不声称首发带有该证明。普通 push 不发布。发布过的版本不可覆盖；后续改动必须使用新版本。

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,23 @@
+# QQ 固定发行检查单
+
+本页是每次发布的质量门禁。v1.2.0 的公开 npm 与 GitHub Release 已获 Owner 授权；第三方市场投稿仍需独立核查。
+
+## 源码与包
+
+- [ ] 从最新 `main` 创建开发分支；记录源码 Commit SHA、上一个稳定 Tag 和 PR。
+- [ ] 核对包名 `@fg-lab/amadeus-qq`、运行 ID `amadeus-qq`、版本、`dsh.bundle`、`dsh.client`、`engines.dsh`、入口及 `cordis.patch.yml`。
+- [ ] `npm ci --ignore-scripts`、`npm run build`、`npm test`、`npm run verify:release` 通过；额外运行必要的跨插件契约测试。
+- [ ] 用 `npm pack --ignore-scripts` 产生 `.tgz`，检查内容、SHA-256 与预构建 Client/Console/翻译/图标，确认没有凭据、数据库、日志和个人资料。
+- [ ] 在目标官方 DSH Desktop 隔离 Profile 实测单独安装、五插件联合安装、禁用/启用、重启、旧版升级、卸载和恢复。只声明实测过的 DSH 版本。
+
+## 数据与兼容
+
+- [ ] 按 `UPGRADE_POLICY.md` 和 `DATA_MIGRATION.md` 备份并运行上一稳定版 → 当前版的合成升级回归；验证关键内容、关系、权限、绑定、功能及失败恢复。
+- [ ] 确认数据路径不位于包目录；升级和卸载不删除用户数据；旧版代码回滚与数据库恢复分别演练。
+- [ ] 核对 QQ Scene、Memory、Life、State、Persona 的公开 Host 契约版本与兼容矩阵，避免重复注册、重复注入和双实例。
+
+## 发行授权
+
+- [ ] 核实包内 MIT `LICENSE` 与 `package.json` 一致；确认 `@fg-lab` 发布权限、`publishConfig.access=public`、npm 登录和 2FA 人工流程。
+- [ ] 准备不可变的 `v1.2.0` Tag、GitHub Release 说明、可下载 `.tgz`、SHA-256、Schema Version、升级/回滚说明；正式创建前完成全部质量门禁，并确认 Tag、源码和 tarball 一致。
+- [ ] `awesome-dsh-plugin` 只增加本仓库对应的 `data/plugins/*.yml`；不编辑生成 README。市场展示、下载源和安装行为实际验证后再提交外部收录 PR。

package/docs/RELEASE_NOTES.md

@@ -0,0 +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 原生工具没有同等级实机证据；不将这些作为已验证能力宣称。

package/docs/UPGRADE_POLICY.md

@@ -0,0 +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 契约不兼容时应先适配或限制组合版本。小版本不得无说明删除既有能力；弃用需标记、替代方案和兼容周期。

package/docs/V1_SCOPE.md

@@ -0,0 +1,33 @@
+# Amadeus QQ v1.0 收缩后任务清单
+
+更新：2026-10-27。`1.0.0` 已完成限定功能、隔离 DSH Host、真实 NapCat/QQ 与四插件同 Profile 的验收；以下仍区分各项证据来源。
+
+| 领域 | 状态 | 剩余边界 |
+| --- | --- | --- |
+| M1 连续交流、去重、权限 | 隔离 DSH 模型调用、重启去重和撤权通过；真实私聊收发及重启后相同 actionId 去重通过 | 大规模长时间运行、QQ 平台风控与跨网络故障未测 |
+| Owner Agent | 可信 Owner 私聊中的 DSH 原生 `pwsh`、`read`、`web_fetch` 实际由模型调用；已注册 Life 工具可由 Owner 调用，撤权后旧 Session 在真实 Host 被拒 | 隔离 Host 未安装 GitHub 工具，不能声称已验证 GitHub 调用；实际可用性取决于 Host 工具注册 |
+| 日常消息 | 真实收取文字、图片、语音；向指定测试私聊发送文字、图片、MP3 语音并通过 `get_msg` 读回 | 长时间顺序性、平台风控与跨网络故障未测 |
+| 群聊发送与附件 | 在仅含 Owner 与测试 Bot 的授权群，真实隔离模型调用 @+face、回复、回应、戳一戳和群附件工具，均返回 delivered；`get_msg` 复核到 @、face、reply 段；群文件根目录确认一个上传文件 | 群内批量/并发、其他消息类型和长时间顺序性未测 |
+| 群附件回执 | 最终包与隔离 Desktop 重启后，新群附件返回 delivered，平台恰有一个匹配文件，经 `get_group_file_url` 解析回执；NapCat 列表会轮换 `file_id`，代码以稳定元数据/计数核对，歧义保留 unknown | 旧的 unknown 上传未被重试，也未确认其平台事实；未知结果仍靠人工对账 |
+| QQ 原生 ASR | 本机 NapCat `fetch_ptt_text` 实际返回文本；隔离 DSH 模型工具得到原消息、发送者及私聊 Scene 绑定的转写，重启后保留 | 第一次平台调用暂时失败，重试成功；不能保证所有语音都可转写 |
+| 外部 TTS 交接 | 受控目录 MP3 经 QQ 插件发送真实 QQ 语音；无内建 TTS 依赖 | 未与具体第三方 TTS 插件联测 |
+| 账号资料 | 测试号头像和签名真实修改、读回并恢复 | QQ 头像恢复后视觉一致，平台重编码导致字节哈希不同；其他资料字段不作为门槛 |
+| QQ 空间 | `qq_qzone` 统一入口；真实测试号的仅自己可见文字/图片说说发布得到 tid，并调用平台删除 | 点赞、评论等已有 Provider 动作仅单元/模拟；其他可见范围未实测 |
+| Memory | 同一隔离官方 DSH Host 中，使用合成标记和真实绑定的群/私聊 Session：精确查询命中私聊标记，未观察到跨 Scene 注入 | 初始宽泛私聊查询未召回该标记；不宣称通用检索完备，长期生产流量未验证 |
+| Life | 同一隔离 Host 的只读联动通过；受控外发 opt-in 已独立验证：intent 持久化 `life-tool:session:` provenance，管理员对同一 allowlist Owner Session 与授权 QQ 私聊开启 `externalMessageSessionIds` 后 wake 执行，模型恰好一次 `qq_send_message`，QQ 返回 delivered，NapCat `get_msg` 与指定 Owner 好友历史确认私有文字；关闭 opt-in 后新 intent 的 wake 为零 QQ 发送 | 首次尝试因错误 provenance 检查未发送，Life 源码已改为读取持久 intent；opt-in 只改变提示指导，不是 Life 级硬闸门，QQ Scene 权限仍是权威；长期自治与任意 QQ 目标未验证 |
+| State | 可选降级，QQ 无硬依赖 | State 1.0.0 已合并；四插件同 Host 联合验收另行记录 |
+| 管理与交付 | 原生 Settings、Admin API 和 Web Console；最终包隔离 Desktop 的 HTTP 路由、匿名拒绝、CSP、禁连状态和真实浏览器中的 Scene 图节点点击/筛选/重置已验收；停用 Memory Bundle 时同一 UI 仍加载并显示授权 Scene 拓扑，确认无 Memory 运行时依赖；权限编辑器保留 | 窄屏由横向滚动/列表回退处理，未做移动端视觉回归；Memory 自身实体 UI 是独立 Mneme 视图，本轮隔离库为空，未绘制新的语义图数据；安装包与 PR 交付见最终报告 |
+
+## 已移出 v1.0 门槛
+
+消息转发与合并转发、独立历史同步、好友和入群申请审核、群文件管理、大量群设置、内建 TTS、独立 ASR 服务、内建视频/文件理解、QQ 空间全部底层接口重写、复杂跨平台自主规划和大型 Web 仪表盘。已有能力保留。
+
+## 验收纪律
+
+真实外发只对用户授权的测试私聊和仅含 Owner 与测试 Bot 的授权群执行；群发送/附件证据来自该群。账号资料与空间操作只在测试号进行并已恢复或清理。隔离 NapCat 的 QQ 客户端媒体缓存仍共用系统 `Documents/Tencent Files`，因此本轮不宣称 QQ 客户端级完全隔离。生产 DSH Profile、SnowLuma Bot、QQ Bridge、Memory 与 Life 数据不应直接用作迁移或破坏性测试。
+
+当前 `npm test`：281 通过、0 失败、4 跳过；四个跳过项均因本机 Windows 无法创建符号链接。`npm run build` 与 `git diff --check` 通过；`1.0.0` 最终包已在全新隔离 Desktop 与另外三个插件共同安装、加载和停用恢复，详见[联合报告](https://github.com/jeskoky-pixel/Amadeus-dsh/blob/main/docs/verification/AMADEUS_V1_FOUR_PLUGIN_ACCEPTANCE.md)。
+
+## 部署与回滚建议
+
+先在独立 QQ 状态文件和 `connect:false` 下核对 bot/owner/Scene 白名单、NapCat Token、媒体根与权限上限，再对授权私聊/小群灰度；观察 unknown 投递并人工对账，不自动重发。回滚时停用 QQ Bundle、恢复上一安装包与隔离备份状态，不改动生产 QQ、Memory 或 Life 数据。Life 受控外发只在管理员 opt-in、授权 QQ Scene 与明确目标下使用；该 opt-in 改变提示指导，不是硬性禁止层，QQ 执行权限仍是权威。

package/docs/v1.1/PRESET_MATRIX.md

@@ -0,0 +1,28 @@
+# v1.1 权限预设对照
+
+下表是默认继承权限。Scene 内显式 `allow/deny`、全局拒绝、可信 Owner 身份、Provider 状态和 QQ 平台权限会继续决定实际结果；Web Console 显示最终生效值与原因。
+
+| 能力 | 仅观察 | 安全聊天 | 增强对话 | 自主群友 | Owner Agent |
+| --- | --- | --- | --- | --- | --- |
+| 读取已授权 Scene | 是 | 是 | 是 | 是 | 是 |
+| 发送普通消息 | 否 | 是 | 是 | 是 | 是 |
+| DSH 搜索与媒体读取 | 否 | 否 | 是 | 是 | 是 |
+| 回应、戳一戳、撤回 | 否 | 否 | 是 | 是 | 是 |
+| 未被 @ 的群消息触发参与判断 | 否 | 否 | 否 | 是 | 不适用 |
+| 群管理写入 | 否 | 否 | 否 | 否 | 不适用 |
+| 账号资料与 QQ 空间 | 否 | 否 | 否 | 否 | 需账号页显式授权 |
+| Owner 文件/Host 工具 | 否 | 否 | 否 | 否 | 仍需单项授权与 Host Guard |
+
+Owner Agent 只能用于已配置的可信 Owner 私聊。群管理需要对对应 Scene 手动允许，并由 NapCat/QQ 平台再次拒绝无权操作。`custom` 只是界面编辑状态，不是后端权限模式。手动调整后保留其他字段；重新选择命名预设会重置原有覆盖与行为参数。
+
+行为参数默认值：
+
+| 预设 | 合批静默窗口 | 续聊等待上限 | 自主接话冷却 | 近期上下文上限 |
+| --- | ---: | ---: | ---: | ---: |
+| 仅观察 | 0 秒 | 0 秒 | 0 秒 | 20 条 |
+| 安全聊天 | 5 秒 | 30 秒 | 0 秒 | 20 条 |
+| 增强对话 | 10 秒 | 30 秒 | 0 秒 | 20 条 |
+| 自主群友 | 12 秒 | 30 秒 | 15 秒 | 20 条 |
+| Owner Agent | 10 秒 | 30 秒 | 0 秒 | 20 条 |
+
+“参与活跃度”随请求传给当前对话模型作为判断提示；它不创建定时主动发言。静默窗口有最长等待上限，续聊等待及上下文上限在 QQ 执行路径约束。

package/docs/v1.1/PROTOTYPE_DIFF.md

@@ -0,0 +1,15 @@
+# HTML 原型与实际 Web Console 对照
+
+设计参考来自用户提供的 `amadeus_qq_v1_1_console_handoff.zip`。原型是静态交互稿；产品页面由插件自身静态资源及受 DSH Owner 鉴权的 Admin API 驱动。
+
+| 原型 | v1.1 实现与差异 |
+| --- | --- |
+| 六类导航、卡片布局、浅色/深色主题 | 已在真实 Web Console 实现。图标与细节并非逐像素复制，以当前插件状态为准。 |
+| 首次设置、Scene 管理 | 真实 Workspace、Bot/Owner、NapCat、白名单与全局拒绝配置；Session ID 来自 DSH。没有硬编码演示数据。 |
+| 预设与自定义 | 改动任一权限/行为参数立即显示自定义；保存使用修订号冲突检查；实际生效权限由后端返回。 |
+| 功能中心 | 显示源码已接线、Provider 条件与待平台确认状态，不把 NapCat 动作目录当作已验证能力。 |
+| 账号/空间 | Owner 授权与 QZone Provider 分开保存；账号级能力不放在普通 Scene 编辑器。 |
+| 诊断 | 展示连接、Workspace、Scene 与 Session 绑定。原型中的演示指标、模拟日志或安全测试按钮未照搬为假数据。 |
+| 窄屏布局 | 保留响应式 CSS；真实窄屏浏览器视觉证据仍待补充。 |
+
+界面当前不内置 NapCat 安装器或二维码登录器。用户可在 DSH GUI 完成 QQ 插件配置，但 NapCat 本体仍需按其官方方式安装和登录。v1.1 的真实平台闭环待隔离 NapCat 可用后复验。

package/docs/v1.1/TEST_REPORT.md

@@ -0,0 +1,20 @@
+# v1.1 候选测试与验收记录
+
+## 本次已验证
+
+- `npm run build` 通过；`npm test` 共 **291 项，286 通过、0 失败、5 跳过**。跳过项含 4 项 Windows 符号链接环境能力及 1 项本地 Life 源码缺失条件。
+- 回归覆盖首次配置校验与修订冲突、Owner 同源鉴权、预设/自定义、群管理默认拒绝、Scene 暂停/撤权、不同 Scene Session、Workspace 迁移、短消息合批和重启回放、可选插件缺失降级。
+- 在隔离 DSH Desktop Profile 的真实 Web Console 操作首次设置、预设选择、自定义参数、撤销与保存、账号授权和深色主题。最终包还实测了全局拒绝勾选、保存、页面刷新后保持，以及另一项未保存修改的撤销。未登录的设置请求返回 401。配置持久化后重启，两个授权 Scene 的 Session ID 与 Workspace 归属保持一致；最终包复验见本报告的收尾记录。
+- 真实浏览器截图：[总览](../screenshots/overview-desktop.png)、[全局设置](../screenshots/global-desktop.png)；[账号页](../screenshots/account-browser.png)与[深色主题](../screenshots/account-dark-browser.png)是合成数据布局检查，不能作为真实配置或 QQ 外发证据。公开截图已遮蔽真实测试号码与本机路径。
+
+## 尚未验证
+
+- 本次 v1.1 连接到真实 NapCat 的入站、模型工具外发、连续群聊自然结束、动态撤权和 Life 同时唤醒尚未完成。独立测试 NapCat 进程未能在当前已有桌面实例同时运行，隔离端口未监听。未停止或更改已有实例。v1.0 的[真实 QQ 验收](../verification/V1_REAL_NAPCAT_2026-10-27.md)只能证明当时的版本和场景。
+- 窄屏响应式布局有 CSS 断点与原型参考；本次没有可复核的窄屏真实浏览器截图。其他 DSH/NapCat 版本、长期平台稳定性和日常生产账号未验收。
+- “参与活跃度”是当前模型提示参数，真实模型在不同值下的参与率未测量。不能将它解释为平台级硬概率控制。
+
+## 收尾记录
+
+最终 `1.1.0` 包通过本地 `npm pack` 构建并重新安装到隔离 DSH Profile；已核对安装后的 `src/core.js`、`src/setup.js` 和 Web Console 脚本与工作树内容哈希一致。重新启动后，Owner 鉴权的设置/Scene/Console API 均返回 200，两个原 Scene 在 DSH Session 列表中仍保持原 Session ID 和相同 Workspace 归属，全局拒绝也写入隔离 Profile 并在重启后保留。未登录设置请求返回 401。
+
+候选代码保持独立 QQ 仓库和隔离 DSH Profile。测试 QQ 目标均为事先授权的私聊/小群；此次没有向 QQ 群聊或私聊发送新的测试内容。未修改 DSH 核心、NapCat 本体或 Memory、Life、State 仓库；未合并和发布。

package/docs/v1.1/UPGRADE.md

@@ -0,0 +1,10 @@
+# 从 1.0.0 升级到 1.1.0
+
+1. 先备份 QQ 独立状态文件和 DSH Profile；在隔离 Profile 用 `npm pack` 生成的包升级并检查 Web Console。
+2. 在“全局设置”选择现有 DSH Workspace。既有绝对 `sessionCwd` 仍用于旧配置兼容；选择 Workspace 后新建 Scene Session 归入该 Workspace。
+3. 核对 Bot、唯一 Owner、NapCat 地址与 Scene 白名单。旧版已有的 Scene 权限及消息/投递状态沿用，不自动清除。
+4. 逐 Scene 查看“实际生效”权限。1.1 普通预设不再默认允许群管理；如果确有需要，明确开启单项权限并确认 QQ 平台角色。
+5. 检查账号资料和 QQ 空间页的独立授权。保存后按诊断页提示检查 Provider 和连接。
+6. 重启 DSH Desktop，确认 Session 仍位于所选 Workspace，消息与投递账本连续。旧 Workspace 绑定切换时旧 Session 会撤权，新 Session 会建立。
+
+回滚：停用 QQ 插件，恢复 1.0.0 安装包及升级前的独立 QQ 状态/Profile 备份；不要让 1.0 与 1.1 同时连接同一 Bot。当前 PR 未发布到插件市场，也未用于生产部署。

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 和两次真实调用仍需复测。
+