# AI 生成内容说明 / AI-Generated Content Disclosure

## 简体中文

### 一句话结论

**本项目的全部代码与文档由 AI 编程代理生成**，人类负责提出需求、做设计决策、审查结果并验收。
没有任何一行第三方项目的源码被复制进来。

### 生成方式

- 生成环境：[DeepSeek Harness](https://github.com/deepseek-ai)（DSH）上的 AI 编程代理，在移动端容器内运行。
- 生成过程：人类用自然语言提出需求与约束 → AI 编写代码与测试 → AI 在真实运行环境中执行测试并修复
  → 人类审查、否决不合适的方案、追加约束 → 迭代。
- 人类做出的关键决策（可由提交历史与文档佐证）：
  - 技术路线选择 **NapCat + OneBot 11**，而不是自造 QQ 协议；
  - 否决"用执行级硬闸锁死非拥有者"的初版方案，改为**入口路由 + 权限模型**；
  - 要求**指令必须整条严格匹配**（斜杠在首位、无多余内容），防止聊天内容夹带指令样内容被误执行；
  - 要求**动态授权不可跨群**、**只有拥有者能永久授权**；
  - 最终选定 `tools.guard`（一次注册 + 可变标志位）作为访客工具闸，理由是 0 额外 token 且不破坏对话一致性。

### 验证情况

- **自动化测试 123 项**，全部通过（`npm test`）：
  - 正向 WebSocket 适配器 19 项
  - 反向 WebSocket 适配器 12 项
  - Host 插件 25 项
  - 客户端设置页 31 项
  - 权限 / 群管理 / 访客工具闸 36 项
- 测试用的 QQ 侧对端是项目自带的**零依赖 OneBot 11 模拟器**（`test/mock-onebot.mjs`，手写 RFC 6455 帧编解码），
  因此**不需要真实 QQ 账号**即可回归。
- 上面"Host 插件"测试用**假 ctx**（自行实现 `subprocess` / `sessionController` / `timer` / `effect` / `tools`）
  加载**真正的 `lib/index.js`**，配真实适配器与真实模拟器，跑通完整链路。
- 曾以「动态 Cordis Package」形态在**真实运行的 DSH** 中验证过端到端：真实模型回复、会话落盘、
  适配器自动重启与重连、动态工具注册。
- 组合与打包已单独校验：`dsh --profile web --dump-config --patch …` 接受插件行；
  解包到 profile 位置后 `@deepseek-ai/dsh-tools` 可解析；客户端清单通过 `dsh.client` 校验规则。
- 客户端设置页**已由作者在真机（浏览器）上人工确认**：选项卡可见、字段渲染正常、读写与保存行为符合预期。
- 核对过的上游文档：[OneBot 11 鉴权规范](https://github.com/botuniverse/onebot-11)、
  [NapCat-Docker README](https://github.com/NapNeko/NapCat-Docker)（端口 3000/3001/6099、支持 arm64）、
  [AstrBot aiocqhttp 文档](https://docs.astrbot.app/platform/aiocqhttp.html)。

### 已知限制与**尚未验证**的部分（请务必阅读）

1. **没有用真实 QQ 账号测试过**。全部验证基于自带模拟器。真实 NapCat 的限流、风控、
   字段细节与边界情况均未验证。
2. **`lib/index.js` 作为已安装插件在真实 Cordis 宿主中的运行时行为，作者未直接观察到**。
   等价逻辑以动态 Package 形态跑通过；打包、清单、模块解析、组合预检是分别验证的。
   因此"装包 → 重启 → 实际可用"这一步请以你自己环境的实测为准。
3. **仅在 Linux（含 Android proot 容器）下验证过**，未测试 Windows / macOS。
4. **未实现自动治理**（关键词/刷屏自动撤回或禁言）。`notice` 事件目前只做透传与计数。
5. 回复段的处理只取了被引用消息的 id；合并转发、嵌套回复链未处理。
6. 群管理动作的实际效果（撤回是否成功、禁言时长是否被平台裁剪等）依赖具体 OneBot 实现，
   本项目只保证按协议发出请求并如实回报结果。

### 第三方与协议归属

特别感谢：

- [**NapCat**](https://napneko.github.io/) —— 提供灵感、OneBot v11 接口与文档。
- [**梁圣**](https://www.deepseek.com/) —— 忠！橙！


- **OneBot 11** 是开放协议标准，由社区（botuniverse）维护；本项目是对其的客户端实现，
  未复制其任何代码。
- **NapCat**、**AstrBot**、**LLOneBot**、**Lagrange** 等是各自独立的项目，本项目**不包含**它们的代码，
  仅在文档中作为可对接的实现被提及。
- **`@deepseek-ai/dsh-*`** 是 DSH 运行时，本项目以 **peerDependency** 方式使用，不打包、不分发。
- 本项目**运行时零 npm 依赖**：适配器只用 Node 22 内置的 `WebSocket` 与 `fetch`；
  唯一可选的 `@deepseek-ai/dsh-tools` 仅用于注册一个动态工具，缺失时功能会自动降级。

### 项目成本

由**一次连续会话**完成（2026-09-20）：

| 项 | 数值 |
| --- | --- |
| 时间 | 约 **5 小时 10 分**（06:26 → 11:37，含人工确认与等待）|
| Token | 约 **110M** |
| 费用 | 约 **¥7.2** |

说明：会话中途切换过多个模型；时间由文件系统时间戳推算，非精确计时。
也就是说，这个项目的全部代码、测试与文档，**成本大概是一杯咖啡，以及一个无聊的下午**。

### 维护状态：不承诺更新

**本项目到此封版，作者不做持续性维护**：不承诺修 bug、不适配上游破坏性变更、不接受功能请求。
功能是完整的、123 项测试是全绿的，但后续请自行负责。

遇到问题（包括 DSH 升级、NapCat 改字段、OneBot 实现换代、或者想加自动治理）——
**fork 下来自己改**。MIT 许可，随便改、随便发，不用打招呼。

为了让动手快一点，仓库里有 [ARCHITECTURE.md](ARCHITECTURE.md)：文件职责地图、一条消息的完整旅程、
每个设计决策的原因、以及「想加一条指令 / 一个工具 / 一个设置项」的分步指南。

### 安全与免责

- 群管理包含**破坏性操作**（禁言、踢人、撤回、改群名）。项目内置了授权链与演练模式，
  但**最终责任在使用者**：请先打开 `admin.dryRun` 确认行为，再正式启用。
- 非拥有者默认**不允许使用 DSH 内部工具**（读写文件、执行命令等），这是执行级拦截而非提示词约束；
  但任何自动化系统都不应被当作绝对安全边界，请自行评估风险。
- 本项目按 MIT 许可"按原样"提供，不附带任何形式的担保。

### 许可与作者

[MIT](LICENSE) · 作者 [@arrow1031](https://github.com/arrow1031) · 个人网站 <https://sputnikzaychik.icu> · QQ 群 [1091766276](https://qun.qq.com/universal-share/share?ac=1&authKey=z%2FlfWodgOvkDnUTzUZ3%2BNoYGInkfTKCyMfmxO8uyGa%2Bx%2BKmF4ILvUvzqSb6mEJoE&busi_data=eyJncm91cENvZGUiOiIxMDkxNzY2Mjc2IiwidG9rZW4iOiJuY0Z3eEkzeUJWUkROYUNwWnNhblY3VlQrWWh1NURVbDZlUDRZNHZKSFlGWEJnOFRhazB6VUVaV0ZoMzVZVjg2IiwidWluIjoiMzE5NTQzODg2In0%3D&data=qPi85PPH3R-8HaJ9_U2u0zi7KCjzwplsRb-xisY3XAiBsWzopanij924BvV0sfj_cspqyTWemKx0YnNIHTjjGQ&svctype=4&tempid=h5_group_info)

---

## English

**Every line of code and documentation in this project was generated by an AI coding agent.**
A human directed the requirements, made the design decisions, reviewed the output, and accepted the result.
No source code from third-party projects was copied into this repository.

- **Generated with:** an AI coding agent running on DeepSeek Harness (DSH), inside a mobile container.
- **Verification:** the browser-side settings page was **manually confirmed on a real device** (tab visible, fields render, read/write behaves).
  123 automated checks pass (`npm test`), covering the forward/reverse WebSocket adapter,
  the Host plugin (loaded with a fake `ctx` against a real adapter and a real mock OneBot peer),
  the browser-side settings page, and the permission/group-management subsystem.
  The QQ-side peer used throughout is a zero-dependency OneBot 11 simulator bundled in `test/`,
  so **no real QQ account is required** to reproduce the suite.
- **Upstream documentation consulted:** the OneBot 11 specification, the NapCat-Docker README,
  and the AstrBot aiocqhttp docs (links in the Chinese section above).

**Not verified — read before relying on this:**

1. Never tested against a **real QQ account**; all validation used the bundled simulator.
2. The packaged `lib/index.js` was **not observed running inside a real Cordis host by the author**.
   Equivalent logic was exercised as a dynamic Cordis package; packaging, manifest, module resolution
   and composition preflight were verified separately. Please validate install → restart → run in your
   own environment.
3. **Linux only** (including an Android proot container). Windows and macOS are untested.
5. **Automatic moderation is not implemented.** `notice` events are passed through and counted only.
6. Reply handling captures only the referenced message id; merged forwards and nested reply chains are not handled.

**Third-party attribution:** OneBot 11 is an open protocol standard (botuniverse) — this project is an
independent client implementation and copies none of its code. NapCat, AstrBot, LLOneBot and Lagrange are
separate projects and are **not** bundled. `@deepseek-ai/dsh-*` packages are consumed as peer dependencies
and are not redistributed. The project has **zero runtime npm dependencies**: the adapter uses only Node 22's
built-in `WebSocket` and `fetch`.

**Security:** group management includes destructive actions (mute, kick, recall, rename). Authorization
chains and a dry-run mode are built in, but **responsibility rests with the operator** — enable dry-run first.
This software is provided "as is" under the MIT license, without warranty of any kind.