mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-20 08:58:03 +00:00
docs(example): 为每个插件补 README
此前 example/ 下 21 个插件里，13 个完全没有 README，另 4 个是 `hmapdev init` 生成的脚手架样板（`# <name>` + `plugin build` + `Install` 三行， 等于从没被写过）。只有 deepsearch / vikunja / plugindev / luademo 是真实文档。 本次为 **17 个**插件写了真文档（13 个缺失 + 4 个样板），现在 21 个全部有内容。 ## 写法 每个 README 覆盖：能力一句话 → 为什么需要 → 工具表 → 配置项表 → 通道与钩子（有才写）→ 构建 → 已知边界。 **事实全部从源码读出来，不推测**： - 工具名核对到注册点（含 `tp+"x"` / `p.name+"_x"` 前缀拼接，展开成最终名） - 配置键与默认值取自 `RegisterDef` / getStr 默认值 - 通道名、钩子名、依赖命令逐条 grep 确认 - 版本号与已部署实例交叉核对，17 个里 16 个一致 ## 几处按源码写、与直觉不同的点 - **rss**：订阅时会把抓到的历史条目一次性标为 seen，所以订阅一个源 **不会**把历史文章全推一遍 —— 这是避免刷屏的关键，写进了文档。 - **files**：路径校验是**两道**（规范化后判断 + 解析符号链接后再判断）， 只做前者的话沙箱里的软链接就能逃逸。两种情况报错文案不同。 - **qq**：身份必须**绑帧**而非存插件全局，源码注释记录了由此产生的两个真实故障 （中断抢占恢复后权限门整体失效、运行中到达的消息改写正在跑那一轮的身份）。 多来源合并时权限取**交集**。硬私有工具按前缀一律拒绝。这些是安全关键， 单独成节写清楚。 - **memo**：待办与备忘录**刻意分两类**（一提醒一不提醒），提醒注入带 NoMemory。 - **sanitizer**：不注册任何工具，只挂三个阶段钩子；依赖 ABI v2 的 stage 写回能力。 - **editdoc**：本目录是 v1.0.0（单工具），而线上跑 v2.0.0（全能版，源码未公开）—— 在文档开头显式标注，**不按 v2 描述**，避免读者以为这里就是线上那份。 ## 验证 - 21/21 文件非空且非样板（最小 913B，最大 6845B） - 逐个核对 README 中出现的工具名能在源码找到依据；5 处报警经复核**全是误报** （`ai_image_generate`/`music_*` 前缀来自 metadata 的 name，`on_input` 等是钩子不是工具） - README 版本号 vs 线上 plugin.json：16/17 一致，editdoc 的差异已显式说明 注：本仓既有未提交改动（example/qq/plugin.go、sdk/plugin.go）**未纳入本次提交**。
This commit is contained in:
JianFeeeee
167
example/qq/README.md
Normal file
167
example/qq/README.md
Normal file
@ -0,0 +1,167 @@
|
||||
# qq · QQ 消息桥接
|
||||
|
||||
通过 [NapCat](https://github.com/NapNeko/NapCatQQ) 把 QQ 接成 HomeAgent 的一个 IO 通道：
|
||||
让 agent 收发 QQ 消息、读群/好友信息、传文件。
|
||||
|
||||
> ⚠️ 这是**安全敏感**插件：它让外部 QQ 用户能触达 agent 的工具。
|
||||
> 本文档的「权限模型」一节请务必读完。
|
||||
|
||||
## 通道与钩子
|
||||
|
||||
| 类型 | 名称 | 说明 |
|
||||
|---|---|---|
|
||||
| 出站 | `qq` | `CapText` + `CapFile` + `CapImage` + `CapAudio`；发消息/文件给 QQ |
|
||||
| 入站 | `qq` | `NoMemory: true` + `Cleaner` + `RecallPolicy: None` |
|
||||
|
||||
四个阶段钩子（全部 `StageScopeGlobal`）：
|
||||
|
||||
| 钩子 | 作用 |
|
||||
|---|---|
|
||||
| `on_input` | 把本轮 QQ 身份**绑到帧上** |
|
||||
| `before_toolcall` | 权限门：逐个工具判断是否放行 |
|
||||
| `post_action` | 清掉被拒绝时模型已经吐出的废话 |
|
||||
| `after_output` | 收尾时清理插件全局身份 |
|
||||
|
||||
## 工具（20 个）
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `qq_get_message` | 按 `message_id` 取消息正文、发送者、附件 |
|
||||
| `qq_get_history` | 取群/私聊最近历史消息 |
|
||||
| `qq_list_chats` | 会话列表（按最新消息排序，带未读数与摘要） |
|
||||
| `qq_mark_read` | 把某会话未读数清零 |
|
||||
| `qq_send_file` | 发文件/图片（私聊或群聊） |
|
||||
| `qq_get_groups` | 群列表，可按关键词搜 |
|
||||
| `qq_get_friends` | 好友列表，可按昵称/备注搜 |
|
||||
| `qq_get_recent_contacts` | 最近有消息的联系人与群 |
|
||||
| `qq_resolve_name` / `qq_resolve_nickname` | 名字 ↔ QQ 号互查 |
|
||||
| `qq_get_group_member_info` | 群成员信息 |
|
||||
| `qq_group_manage` | 群综合管理（见下） |
|
||||
| `qq_friend_action` | 好友操作 |
|
||||
| `qq_get_group_files` | 群文件列表 |
|
||||
| `qq_download_file` / `qq_upload_group_file` / `qq_get_download_tasks` | 文件传输与任务 |
|
||||
| `qq_read_document` | 读 QQ 传来的文档 |
|
||||
| `qq_video_download` | 下载视频 |
|
||||
| `qq_send_like` | 点赞 |
|
||||
|
||||
`qq_group_manage` 一个工具承载多种操作（`command` 参数）：
|
||||
`leave` 退群、`kick` 踢人、`ban`/`unban` 禁言解禁、`rename` 改名、`mute-all` 全员禁言、
|
||||
`set-card` 设名片、`set-admin` 设管理、`set-title` 设头衔、`member-list`、`group-info`、
|
||||
`msg-history`、`recall` 撤回、`pin-msg` 精华、`list-files`、`pending-requests`、`folder-create` 等。
|
||||
|
||||
**破坏性操作**（`leave`/`kick`/`ban`/`unban`/`rename`/`mute-all`/`set-card`/`set-admin`/
|
||||
`set-title`/`recall`/`pin-msg`/`folder-create`）**必须显式传 `confirm: true`**。
|
||||
|
||||
## 权限模型
|
||||
|
||||
这是本插件最重要的部分。
|
||||
|
||||
### 身份分级
|
||||
|
||||
| 身份 | 权限 |
|
||||
|---|---|
|
||||
| **owner**（Bot 所有者） | 私聊或群聊均**完整放行** |
|
||||
| **普通 QQ 用户** | 只放行白名单内的工具 |
|
||||
|
||||
### 身份必须「绑帧」，不能只存插件全局
|
||||
|
||||
源码注释记录了两个真实故障，这就是绑帧的原因：
|
||||
|
||||
1. **中断抢占后身份丢失**：中断会抢占当前轮、把现场压栈。中断轮收尾时
|
||||
`after_output` 会清空插件**全局**身份；随后外层被恢复（`resumeTask` 复用同一帧、
|
||||
**不重跑 `on_input`**）。若身份只存全局，恢复后的外层就是"无身份"，
|
||||
`before_toolcall` 在 `!auth.active` 处直接返回 —— **整个权限门失效**。
|
||||
2. **运行中到达的消息改写身份**：新消息会调 `activateAuthContext` 改写全局身份，
|
||||
把**正在跑的那一轮**换成另一方的身份（换高=越权，换低=误拒）。
|
||||
|
||||
帧上的 `Extra` 随帧一起压栈/恢复，正好是"这一轮的身份"。
|
||||
|
||||
### 合并取最小权限
|
||||
|
||||
多来源被内核合并到同一推理时，权限**取交集**而非并集：
|
||||
|
||||
```go
|
||||
p.auth.owner = p.auth.owner && next.owner
|
||||
```
|
||||
|
||||
防的是"非所有者请求 + 随后所有者消息"意外把前一个请求提权。
|
||||
|
||||
### 硬私有工具
|
||||
|
||||
非所有者**一律拒绝**（不看白名单），按前缀拦截：
|
||||
`calendar_`、`email_`、`mail_`、`agentmail_`、`memory_`、`knowledge_`、`device_`、
|
||||
`devicectl_`、`terminal_`、`shell_`、`command_`、`exec_`、`filesystem_`、`agentfs_`、
|
||||
`config_`、`settings_`、`plugin_`、`plugins_`，
|
||||
外加 `read_file`、`write_file`、`edit_file`、`delete_file`、`list_files`、`run_command`、
|
||||
`homeagent_config`、`homeagent_restart`、`output_send__email`、`output_send__mail`。
|
||||
|
||||
### 参数与会话一致性校验
|
||||
|
||||
光看工具名不够，还要检查**参数指向的会话与当前身份一致**，否则可以拿别人的
|
||||
`message_id` 去读别处内容：
|
||||
|
||||
- 带 `message_id` 的工具：该 ID 必须属于当前 QQ 会话（`lookupMsgRef` 校验 peer 与群/私聊类型）。
|
||||
- `get_group_member_info` / `get_group_files`：`group_id` 必须是**当前群**。
|
||||
|
||||
### 频率与重复控制
|
||||
|
||||
| 键 | 作用 |
|
||||
|---|---|
|
||||
| `max_qq_tool_calls` | 单轮工具调用上限 |
|
||||
| `max_qq_output_calls` | 单轮输出调用上限 |
|
||||
| `max_duplicate_qq_send` | 重复发送上限，防刷屏 |
|
||||
| `batch_window_ms` / `batch_max_ms` | 消息合批窗口 |
|
||||
|
||||
被拒时只允许**发一次权鉴说明**，之后锁止本轮剩余工具调用
|
||||
（`clearDeniedResponse` 再把模型已写出的内容清掉，避免输出里带一堆"我不能…"）。
|
||||
|
||||
## 配置项
|
||||
|
||||
### 连接
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `napcat_url` | — | NapCat 服务地址 |
|
||||
| `listen` | — | 本插件 HTTP 监听地址 |
|
||||
| `webhook_token` | — | webhook 校验令牌 |
|
||||
|
||||
### 身份与准入
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `owner` | 空 | Bot 所有者 QQ 列表（逗号分隔），拥有完整权限 |
|
||||
| `admin` | 空 | **旧配置名**，`owner` 为空时作为所有者列表（兼容用） |
|
||||
| `dm_policy` | `open` | 私聊策略：`open` / `allowlist` / `disabled` |
|
||||
| `allow_from` | 空 | 私聊白名单（QQ 号，逗号分隔） |
|
||||
| `group_policy` | `open` | 群聊策略：`open` / `allowlist` / `disabled` |
|
||||
| `group_allow_from` | 空 | 群白名单 |
|
||||
| `private_tool_allowlist` | 空 | 私聊下非所有者可用的工具 |
|
||||
| `group_tool_allowlists` | 空 | 按群配置的工具白名单 |
|
||||
|
||||
### 文件与转发
|
||||
|
||||
| 键 | 说明 |
|
||||
|---|---|
|
||||
| `files_dir` | 本地文件目录 |
|
||||
| `remote_dir` | 供 NapCat 容器访问的目录（发文件前先复制到这里） |
|
||||
| `agentfs_dir` | agent 文件系统目录 |
|
||||
| `forward_rules` | JSON 数组，每项 `{group_id,host,port,password,template}`：匹配的群消息经 **RCON** 转发到 Minecraft；`template` 支持 `{nickname}` / `{message}` 占位 |
|
||||
|
||||
## 部署前提
|
||||
|
||||
需要**自行部署 NapCat**（本插件不含 QQ 协议实现，只是 NapCat 的客户端）。
|
||||
发文件前会先把文件复制到 `remote_dir`，因为 NapCat 通常在容器里，看不到宿主任意路径。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
go test -count=1 -race ./...
|
||||
```
|
||||
|
||||
含权限门与绑帧的回归测试。改动权限相关代码后务必跑 `-race`。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
Reference in New Issue
Block a user