dsh-qqchat 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coffeiz
+
+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.en.md

@@ -0,0 +1,276 @@
+<div align="center">
+
+# dsh-qqchat
+
+### Bring QQ group and direct chats to DeepSeek Harness
+
+<p>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/DSH-Plugin-6f42c1.svg" alt="DSH Plugin">
+  <img src="https://img.shields.io/badge/TypeScript-5.x-3178c6.svg" alt="TypeScript">
+</p>
+
+<p>
+  <a href="./README.md">中文</a> ·
+  <a href="./docs/ARCHITECTURE.en.md">Architecture</a>
+</p>
+
+<p><em>Chat in QQ, then view the complete Session, memory and tool activity in DSH Web.</em></p>
+
+`dsh-qqchat` is an official QQ Bot plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). It maps QQ groups and direct chats to ordinary DSH Sessions and uses DSH's native Conversation, Agent, command and tool surfaces.
+
+> This is a Vibe Coding project, so code quality and engineering completeness may need improvement. If you find a problem or have a better implementation idea, please open an [Issue](https://github.com/Coffeiz/dsh-qqchat/issues) or submit a [Pull Request](https://github.com/Coffeiz/dsh-qqchat/pulls).
+
+> This uses official QQ Bot authorization. It is not QR login for a personal QQ account.
+
+</div>
+
+## Features
+
+| Feature | What it does | Notes |
+| --- | --- | --- |
+| QQ group and direct chat | Receives group and C2C messages | One isolated DSH Session per group or direct peer |
+| QR connection | Binds an official QQ Bot from **Settings -> QQ Chat** | Cancel the binding and scan again when needed |
+| Group receive modes | Auto reply, Mention only or Silent record | Silent record stores messages without waking the Agent |
+| Message formats | Smart, Markdown or Plain compatibility | Group and direct-chat formats are configured separately; groups default to Plain compatibility |
+| Direct-chat streaming | Optionally uses QQ's official streaming message API for private chats | Private chats only; Plain compatibility disables it automatically; some clients may not display streaming |
+| Quotes and mentions | Preserves quoted messages and resolves QQ mentions to display names | Stable IDs remain in metadata |
+| Memory system | Stores group, member and direct-user memory | Can be disabled; disabling does not delete existing memory |
+| Memory reflection | Converts recent daily notes into long-term memory | Runs asynchronously after idle or batch thresholds |
+| Media and file permissions | Separately controls receiving media, reading attachments, and regular tools | Owner and direct chats are unrestricted by default |
+| Tool permissions | Separately controls whether group members may use regular Agent tools | Owner is matched by stable user ID |
+| Native DSH commands | Runs `/compact`, `/goal`, `/plan`, `/qqmodel`, `/qqstatus` and more directly from QQ | Commands do not go through the model; `/qqhelp` lists the full set |
+| Native DSH UI | Uses the normal Session list, Conversation surface and composer styling | QQ Sessions remain ungrouped in DSH |
+| Diagnostics | Shows plugin logs in Settings | Useful for connection and delivery troubleshooting |
+
+## How to use
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/扫码链接.jpg" width="100%" alt="QQ Chat QR connection">
+      <h3>Scan to connect</h3>
+      <p>Open <strong>Settings -> QQ Chat</strong> in DSH Web and scan the generated QR code with QQ to authorize an official Bot. Connection status, QR regeneration and cancellation are all available on the same page.</p>
+    </td>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/设置界面.jpg" width="100%" alt="QQ Chat settings page">
+      <h3>Settings and permissions</h3>
+      <p>Use the settings page to configure group receive mode, message formats, memory, media and file access, tool permissions and the Owner account.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/群聊界面.jpg" width="100%" alt="QQ group chat in DSH Web">
+      <h3>Group and direct chat</h3>
+      <p>QQ groups and direct chats connect to the DSH Agent and appear as separate Sessions. Groups support auto reply, mention-only reply and silent recording, as well as quoted messages, username display and mention conversion.</p>
+    </td>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/记忆系统.jpg" width="100%" alt="QQ Chat memory system">
+      <h3>Memory system</h3>
+      <p>The plugin maintains separate memory for groups, members and direct users. Member memory supports profiles, group nicknames, historical nicknames, behavior patterns and long-term notes; recent messages are organized asynchronously. Memory is refreshed as Session context when needed, and can be disabled without deleting stored data.</p>
+    </td>
+  </tr>
+</table>
+
+### Scan to connect
+
+1. Start DSH.
+2. Open **Settings -> QQ Chat**.
+3. Choose **Scan to connect** and scan the QR code with QQ.
+4. Authorize the desired official Bot.
+5. The Gateway starts automatically. Use **Cancel connection** before scanning again if you need to bind another Bot.
+
+The Host decrypts and stores the AppSecret in the local plugin database. The temporary QR AES key never travels through the browser Client RPC.
+
+### Chat in QQ
+
+QQ groups and direct chats appear as normal DSH Sessions. Group messages can be handled automatically, only when the Bot is mentioned, or recorded silently. Quotes are preserved, and `@` mentions are displayed with the resolved username whenever QQ provides one.
+
+### Use the memory system
+
+The plugin keeps separate memory for groups, members and direct users. Member profiles support typed facts, group nicknames, historical nicknames, patterns, summaries and long-term notes. Daily records use one `## YYYY-MM-DD` heading per day and are asynchronously reflected into long-term memory.
+
+Memory is injected through DSH's official runtime-context snapshot mechanism, so a new snapshot replaces the previous one instead of accumulating duplicate full contexts. Memory is enabled by default and can be switched off under **Settings -> QQ Chat -> Memory system**. The setting warns that memory may reduce context-cache hit rate and increase input tokens; disabling it stops injection and background reflection without deleting stored data.
+
+## Install
+
+### New `qqchat` profile
+
+Install the official DSH Web bundle together with the plugin:
+
+```bash
+npx @deepseek-ai/dsh plugin --profile qqchat add @deepseek-ai/dsh-web-app dsh-qqchat
+npx @deepseek-ai/dsh --profile qqchat
+```
+
+### Existing Web profile
+
+```bash
+npx @deepseek-ai/dsh plugin --profile web add dsh-qqchat
+npx @deepseek-ai/dsh --profile web
+```
+
+### Development branch
+
+Before npm publication, install the branch directly from GitHub:
+
+```bash
+npx @deepseek-ai/dsh plugin --profile qqchat add @deepseek-ai/dsh-web-app "git+ssh://git@github.com/Coffeiz/dsh-qqchat.git#agent/typescript-migration"
+npx @deepseek-ai/dsh --profile qqchat
+```
+
+Git installs build TypeScript through `prepare`. For local development:
+
+```bash
+git clone git@github.com:Coffeiz/dsh-qqchat.git
+cd dsh-qqchat
+npm install
+npm run check
+```
+
+## Group receive modes
+
+Configure **Settings -> QQ Chat -> Message reception**:
+
+| Mode | Behavior |
+| --- | --- |
+| Auto reply | Every group message can trigger the Agent |
+| Mention only | All messages are stored, but only messages mentioning the Bot trigger a reply |
+| Silent record | Stores messages and memory without actively replying |
+
+Groups default to Plain compatibility format. Group and direct-chat formats can be selected independently. Plain compatibility for direct chats automatically disables streaming.
+
+## Commands
+
+Messages beginning with `/` are handled directly by the command system and are not sent to the model. Native DSH commands keep their original names; QQChat commands use the `qq` prefix. In a group, write `@Bot /help` or `@Bot /qqhelp`.
+
+| Command | Purpose |
+| --- | --- |
+| `/qqhelp`, `/qqcommands` | List QQChat and DSH commands |
+| `/qqnew`, `/qqreset`, `/qqclear` | Keep the old Session and start a new one on the next message |
+| `/compact` | Compact older conversation history |
+| `/qqmodel [provider/]model` | Show or switch the current Session model |
+| `/qqstop` | Stop the current generation |
+| `/qqstatus` | Show Session, model and generation status |
+| `/qqping` | Check QQChat connectivity |
+| `/qqversion` | Show the plugin version |
+| `/goal` | Manage a DSH Goal |
+| `/plan` | Enter or leave Plan mode |
+| `/feedback` | Submit feedback |
+| `/permission` | View or switch tool permission presets |
+
+### Where `/feedback` goes
+
+`/feedback` uses DSH's native feedback mechanism. It does not create a GitHub Issue or send feedback directly to the QQChat authors. By default, feedback is written only to the current DSH Session's local log and does not leave the machine.
+
+It is uploaded to a configured OTLP service only when DSH session telemetry is explicitly enabled:
+
+| DSH telemetry mode | Destination |
+| --- | --- |
+| `DISABLED` (default) | Local DSH Session only |
+| `FEEDBACK_ONLY` | The current Session log suffix is sent to the configured OTLP service when `/feedback` is recorded |
+| `FULL` | Session events are sent to the configured OTLP service in real time; `/feedback` also records a feedback event |
+
+Feedback may include the current Session's conversation, tool arguments, tool results and workspace path. Check your DSH telemetry settings before submitting sensitive information.
+
+`/export` is a browser-only DSH Web command and is not available from QQ. Model changes apply independently to each group or direct Session while preserving the existing conversation.
+
+## Memory content
+
+QQ Chat stores:
+
+- Group memory: important events, agreements, topics and relationships.
+- Member memory: profile facts, group nicknames, historical nicknames, behavior patterns and long-term information.
+- Direct-chat memory: long-term information about a direct QQ user.
+
+Reflection runs asynchronously after the chat is idle or enough messages have accumulated. The **QQ Memory** action at the top of a QQ Session shows group and member memory. Memory snapshots refresh when a Session starts, the memory context expires, or the Session is compacted; continuous conversation does not repeatedly write the full memory. Enabled memory may reduce context-cache hit rate or increase input tokens, and can be disabled under **Settings -> QQ Chat -> Memory system** without deleting stored data.
+
+## Tool permissions
+
+When **Group members can use tools** is enabled, group-triggered Agent turns may use the tools exposed by the current preset. When disabled, only the configured Owner stable ID may execute tools; other group members can still chat normally.
+
+Owner matching uses a stable QQ user ID, not a nickname.
+
+## Message display
+
+QQ conversations use DSH's default Conversation UI:
+
+- Sender usernames are displayed without exposing stable IDs in the bubble.
+- Own and other people's messages use the native DSH bubble alignment.
+- Quoted messages are displayed.
+- QQ `@` mentions are converted to usernames when available.
+- The DSH Session composer can proactively send messages to QQ.
+
+## Notes
+
+- An official QQ Bot is required; personal QQ account login is not supported.
+- `0.2.0` is still being refined; test with a dedicated Bot and group first.
+- Rich media, full QQ emoji handling and some complex message formats may require compatibility mode.
+- Uninstalling the plugin does not automatically delete saved chat or memory data.
+
+## Settings
+
+The Settings page contains configuration only:
+
+```text
+QR authorization and connection
+Group receive mode
+Group and direct-chat reply formats
+Memory system [on/off]
+Media and file permissions and regular tool permissions are independent settings:
+
+- **Receive group-member media/files** controls whether images, files, audio, and video are downloaded, stored, and shown in the session.
+- **Allow group members to read media/files** controls whether their Agent turns may call QQChat media tools for the current attachment.
+- **Group members can use tools** controls access to regular Agent tools.
+Owner stable ID
+Diagnostics and logs
+```
+
+The Settings page does not contain chat lists, transcripts or memory browsing. Those remain in the normal DSH Session and Conversation surfaces.
+
+## Persistence and memory scopes
+
+The SQLite database is stored at:
+
+```text
+$DSH_HOME/plugins/dsh-qqchat/qqchat.sqlite
+```
+
+SQLite is the source of truth for real QQ history, identities, settings, memory documents and the proactive-message outbox. DSH Sessions store the Agent turns, model output, tools, titles and visible transcript events.
+
+Memory scopes are isolated as follows:
+
+- **Group:** profile, summary, daily and long-term memory for one QQ group.
+- **Member:** typed profile, pattern, summary, daily and long-term memory for one stable sender.
+- **Direct chat:** uses the member scope for that QQ user.
+
+The same stable sender may retain member memory across groups under the same Bot. Group relationships and group-specific facts never cross group scopes. Reflection runs after roughly 120 seconds of inactivity or 20 unreflected messages, and can also compress older daily records after the configured thresholds.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run check
+```
+
+The source layout follows feature boundaries:
+
+```text
+src/config.ts             runtime configuration
+src/gateway/              QQ API, authorization, Gateway and normalization
+src/session/              Agent bridge and QQ runtime
+src/storage/              SQLite and memory engine
+src/transport/            Client RPC
+src/commands/             QQ command dispatch
+src/shared/               shared augmentations and logging
+client-src/               DSH Web Client factory and settings UI
+tests/                    automated tests
+```
+
+See [docs/ARCHITECTURE.en.md](./docs/ARCHITECTURE.en.md) for the detailed boundaries and data flow.
+
+## License
+
+This project is released under the [MIT License](./LICENSE).

package/README.md

@@ -0,0 +1,211 @@
+<div align="center">
+
+# dsh-qqchat
+
+### 让 QQ 群聊与私聊接入 DeepSeek Harness
+
+<p>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/DSH-Plugin-6f42c1.svg" alt="DSH Plugin">
+  <img src="https://img.shields.io/badge/TypeScript-5.x-3178c6.svg" alt="TypeScript">
+</p>
+
+<p>
+  <a href="./README.en.md">English</a> ·
+  <a href="./docs/DEVELOPMENT.md">开发文档</a> ·
+  <a href="./docs/ARCHITECTURE.md">架构说明</a>
+</p>
+
+<p><em>dsh-qqchat 是 DeepSeek Harness（DSH）的 QQ 官方 Bot 插件，支持 QQ 群聊、私聊、会话隔离、记忆系统和 DSH 原生命令。</em></p>
+
+> 本项目是一个 Vibe Coding 项目，代码质量和工程完整性可能需要改进。如果你发现问题或有更好的实现建议，欢迎提交 [Issue](https://github.com/Coffeiz/dsh-qqchat/issues) 或 [Pull Request](https://github.com/Coffeiz/dsh-qqchat/pulls)。
+
+</div>
+
+## 主要功能
+
+| 功能 | 说明 | 备注 |
+| --- | --- | --- |
+| QQ 群聊与私聊 | 接收 QQ 官方 Bot 的群聊和私聊消息 | 每个群、每个私聊对象对应独立 DSH 会话 |
+| 扫码连接 | 在 **设置 → QQ Chat** 中扫码绑定 QQ Bot | 支持取消连接后重新绑定 |
+| 断线重连 | QQ Gateway 断线后自动恢复连接 | 无需重复扫码 |
+| 群聊回复模式 | 自动回应、@回复、静默记录 | 可在设置页随时切换 |
+| 消息格式兼容 | 智能兼容、Markdown、纯文本兼容 | 群聊和私聊可分别设置；群聊默认纯文本兼容 |
+| 私聊流式回复 | 私聊可选用 QQ 官方流式消息接口逐步更新回复 | 仅适用于私聊；纯文本兼容模式自动关闭；部分客户端可能不可见 |
+| 消息引用与 @ | 支持引用消息和 QQ @消息 | @用户优先显示用户名 |
+| 会话隔离 | QQ 群聊和私聊分别使用独立会话 | 不同群、不同用户的上下文互相隔离 |
+| 记忆系统 | 保存群聊、群成员和私聊用户的独立记忆 | 设置中可关闭；关闭不会删除已有记忆 |
+| 记忆整理 | 自动将近期记录整理为长期记忆 | 后台执行，不阻塞正常回复 |
+| 媒体与文件权限 | 分别控制群成员媒体接收、媒体读取和普通工具使用 | Owner 与私聊默认不受限制 |
+| 工具权限 | 单独控制群成员是否可以使用普通 Agent 工具 | 可指定 Owner，按稳定用户 ID 判断 |
+| DSH / QQChat 命令 | QQ 中直接执行 `/compact`、`/goal`、`/plan`、`/qqmodel`、`/qqstatus` 等命令 | 命令不经过模型；发送 `/qqhelp` 查看完整列表 |
+| DSH 原生界面 | 使用 DSH 默认会话、聊天区和输入框 | 支持从 DSH 主动向 QQ 发送消息 |
+| 日志查看 | 在设置页查看 QQ Chat 运行日志 | 方便排查连接和消息问题 |
+
+## 如何使用
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/扫码链接.jpg" width="100%" alt="QQ Chat 扫码连接">
+      <h3>扫码连接</h3>
+      <p>在 DSH Web 的 <strong>设置 → QQ Chat</strong> 中生成二维码，使用手机 QQ 扫描即可完成官方 Bot 授权。连接状态、重新生成二维码和取消绑定都可以在同一页面完成。</p>
+    </td>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/设置界面.jpg" width="100%" alt="QQ Chat 设置页面">
+      <h3>设置与权限</h3>
+      <p>在设置页面配置群聊接收方式、消息格式、记忆系统、媒体与文件权限、工具权限以及 Owner。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/群聊界面.jpg" width="100%" alt="QQ 群聊在 DSH Web 中的显示">
+      <h3>群聊与私聊</h3>
+      <p>QQ 群聊和私聊都会接入 DSH Agent，并在 DSH Web 中以独立 Session 展示。群聊支持自动回应、@回复和静默记录，也支持引用消息、用户名显示和 @用户转换。</p>
+    </td>
+    <td width="50%" valign="top">
+      <img src="./docs/assets/记忆系统.jpg" width="100%" alt="QQ Chat 群聊记忆系统">
+      <h3>记忆系统</h3>
+      <p>插件会分别维护群聊、群成员和私聊用户的记忆。成员记忆支持资料、群内称呼、历史昵称、行为模式和长期信息；近期消息会在空闲或达到阈值后自动整理。记忆会作为 Session 上下文按需刷新，设置中可以关闭，关闭后不会删除已有数据。</p>
+    </td>
+  </tr>
+</table>
+
+## 安装
+
+### 新建一个 QQ Chat profile
+
+```bash
+npx @deepseek-ai/dsh plugin --profile qqchat add @deepseek-ai/dsh-web-app dsh-qqchat
+npx @deepseek-ai/dsh --profile qqchat
+```
+
+### 安装到已有的 Web profile
+
+```bash
+npx @deepseek-ai/dsh plugin --profile web add dsh-qqchat
+npx @deepseek-ai/dsh --profile web
+```
+
+当前开发分支也可以直接从 GitHub 安装：
+
+```bash
+npx @deepseek-ai/dsh plugin --profile qqchat add @deepseek-ai/dsh-web-app "git+ssh://git@github.com/Coffeiz/dsh-qqchat.git#agent/typescript-migration"
+npx @deepseek-ai/dsh --profile qqchat
+```
+
+## 第一次连接 QQ
+
+1. 启动 DSH Web。
+2. 打开 **设置 → QQ Chat**。
+3. 点击 **扫码连接**。
+4. 使用手机 QQ 扫描二维码，并选择要授权的官方 Bot。
+5. 授权完成后，QQ Gateway 会自动连接。
+
+连接成功后，QQ Chat 的设置和对话会出现在 DSH 中。
+
+## 群聊接收方式
+
+在 **设置 → QQ Chat → 消息接收** 中可以选择：
+
+| 模式 | 行为 |
+| --- | --- |
+| 自动回应 | 每条群消息都会交给 Agent，Agent 可以自动回复 |
+| @回复 | 所有消息都会记录，但只有 @Bot 的消息会触发回复 |
+| 静默记录 | 只保存消息和记忆，不主动回复 |
+
+群聊默认使用纯文本兼容格式，适合不同 QQ 客户端。私聊和群聊可以分别选择智能兼容、Markdown 或纯文本兼容。私聊使用纯文本兼容时会自动关闭流式传输。
+
+## 命令
+
+QQ 中以 `/` 开头的消息会交给命令系统处理，不会作为普通消息发送给模型。DSH 原生命令保持原名；QQChat 自有命令使用 `qq` 前缀。群聊中可以发送 `@Bot /help` 或 `@Bot /qqhelp`。
+
+| 命令 | 用途 |
+| --- | --- |
+| `/qqhelp`、`/qqcommands` | 查看 QQChat 和 DSH 命令 |
+| `/qqnew`、`/qqreset`、`/qqclear` | 保留旧 Session，下一条消息开始新的 QQ Session |
+| `/compact` | 手动压缩较早的会话历史 |
+| `/qqmodel [provider/]model` | 查看或切换当前群聊/私聊的模型 |
+| `/qqstop` | 中止当前生成 |
+| `/qqstatus` | 查看当前 Session、模型和生成状态 |
+| `/qqping` | 测试 QQChat 连通性 |
+| `/qqversion` | 查看 QQChat 版本 |
+| `/goal` | 查看、创建、编辑、暂停、恢复或清除 Goal |
+| `/plan` | 进入或退出 Plan 模式 |
+| `/feedback` | 提交反馈 |
+| `/permission` | 查看或切换工具权限预设 |
+
+### `/feedback` 反馈去向
+
+`/feedback` 使用 DSH 原生反馈机制，不会自动创建 GitHub Issue，也不会直接发送给 QQChat 作者。默认情况下，反馈只写入当前 DSH Session 的本地日志，不会离开本机。
+
+只有在 DSH 显式配置会话遥测时才会上传到配置的 OTLP 服务：
+
+| DSH 遥测模式 | 反馈去向 |
+| --- | --- |
+| `DISABLED`（默认） | 仅保存在本地 Session |
+| `FEEDBACK_ONLY` | 执行 `/feedback` 时，将当前 Session 日志后缀发送到配置的 OTLP 服务 |
+| `FULL` | Session 事件按配置实时发送到 OTLP 服务；`/feedback` 另外记录反馈事件 |
+
+反馈可能包含当前 Session 的对话、工具参数、工具结果和工作区路径。提交前请确认 DSH 遥测配置符合你的隐私要求。
+
+`/export` 是 DSH Web 的浏览器下载命令，QQ 中会提示暂不支持。模型切换按群聊/私聊分别生效，并保留已有对话上下文。
+
+## 记忆内容
+
+QQ Chat 会分别保存：
+
+- 群聊记忆：群里的重要事件、约定、话题和关系
+- 群成员记忆：成员的资料、群内称呼、历史昵称、行为特点和长期信息
+- 私聊记忆：与某个 QQ 用户的长期对话信息
+
+记忆会在聊天空闲或积累到一定数量后异步整理，不会阻塞正常回复。可以从 QQ Session 顶部的 **QQ 记忆** 入口查看群和成员记忆。记忆内容会按需进入 Agent 上下文，启用后可能降低上下文缓存命中率并增加输入 token；可在 **设置 → QQ Chat → 记忆系统** 中关闭。
+
+记忆快照会在新 Session、记忆上下文过期或 Session 压缩后刷新，连续对话不会重复写入完整记忆。群级记忆和当前群员记忆分别管理，群持续活跃不会替潜水成员刷新成员记忆。
+
+## 工具权限
+
+在设置中，媒体与文件权限和普通工具权限分别控制：
+
+- **接收群成员媒体/文件**：控制是否下载、存储并在会话中显示群成员发送的图片、文件、音频和视频。
+- **允许群成员读取媒体/文件**：控制群成员触发的 Agent 是否可以调用 QQChat 媒体工具读取当前消息附件。
+- **群成员可用工具**：控制群成员是否可以使用当前 preset 的普通 Agent 工具。
+
+关闭媒体接收不会影响普通文字消息；关闭普通工具或媒体读取也不会影响群友正常聊天和获得回复。
+
+Owner 使用 QQ 的稳定用户 ID 判断，不根据昵称判断身份。
+
+## 消息显示
+
+QQ 对话会使用 DSH 的默认聊天界面显示：
+
+- 显示发送人用户名
+- 区分自己发送和他人发送的消息
+- 支持消息引用显示
+- 支持 QQ @消息转换为用户名
+- 支持从 DSH 会话输入框主动发送 QQ 消息
+
+## 注意事项
+
+- 需要 QQ 官方 Bot，不支持个人 QQ 账号登录。
+- `0.2.0` 仍在持续完善，建议先在测试 Bot 和测试群中使用。
+- 富媒体、完整 QQ 表情和部分复杂消息格式可能需要使用兼容模式。
+- 卸载插件不会自动删除已经保存的聊天和记忆数据。
+
+## 本地开发
+
+```bash
+npm install
+npm run check
+```
+
+更多开发约定和内部说明见：
+
+- [开发说明](./docs/DEVELOPMENT.md)
+- [记忆规则](./docs/MEMORY.md)
+- [安全边界](./docs/SECURITY.md)
+- [架构说明](./docs/ARCHITECTURE.md)
+
+## License
+
+本项目使用 [MIT License](./LICENSE)。

package/client-src/plugin.cts

@@ -0,0 +1,15 @@
+import { installStyles, setQQRpc } from './shared.cjs'
+import type { Ctx } from './shared.cjs'
+import { QQSettings } from './settings.cjs'
+import { QQSessionUtility, QQTranscriptNode, createQQMessageDefinition } from './workspace.cjs'
+
+exports.inject = ['slots', 'connection', 'conversationEvents'] as const
+exports.apply = function apply(ctx: Ctx) {
+  setQQRpc(ctx.connection.rpc)
+  ctx.effect(installStyles, 'dsh-qqchat: client styles')
+  ctx.conversationEvents.register(createQQMessageDefinition())
+
+  ctx.slots.inject('settings.section', () => ctx.slots.register({ name: 'settings.section', id: 'qqchat', order: 35, label: () => 'QQ Chat', inject: () => ({ rpc: ctx.connection.rpc }) }, QQSettings))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({ name: 'conversation.chat.node', key: 'qqchat-message' }, QQTranscriptNode))
+  ctx.slots.inject('conversation.session.header.utilities', () => ctx.slots.register({ name: 'conversation.session.header.utilities', id: 'qqchat-memory', order: 30, inject: () => ({ rpc: ctx.connection.rpc }) }, QQSessionUtility))
+}