mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 06:17:25 +00:00
feat(sdk): 22 个示例插件配齐 skill + 三态启动声明 + 打包期校验
## 用户的三条要求 1. 「所有插件都默认自启会占启动时间，还在 llms 上下文塞大量工具」 ⇒ 纯工具型改为按需加载，靠 skill 让 agent 知道要先拉起。 2. 「会向 agent 注入输入的部分插件不能这样做」 ⇒ 9 个必须常驻，其余 13 个按需。 3. 「sdk 是不是没有暴露插件声明自身行为的方案」 ⇒ 对：auto_start 只在 internal/plugin/manifest.go 有，SDK 零命中。 ## 定级依据（代码证据，不是猜描述） 注入 / 钩子 ⇒ 必须常驻（9 个）： qq HTTP 监听 NapCat 推送，消息到达要立刻注入 rss 轮询订阅源，新文章主动推送 calendar 30s ticker 检查提醒 memo 5min ticker 检查待办到期 a2a TCP 监听外部 Agent 请求 acp TCP 监听 ACP 客户端 browser ticker + 长命令完成回调 sanitizer 注册 stage 钩子（无工具，要每轮生效） luademo 注册 stage 钩子做示范 纯工具型 ⇒ 按需（13 个）： weather ocr music bili ai_image files editdoc deepsearch plugindev recoverydiag vanblog vikunja commondev ★ commondev 值得单独说：它虽然有 6 处 Inject 调用，但**注入源是自己的 sidecar 完成回投**，而 sidecar 只在 commondev_agent_up 时才拉起 （Start() 里不启 sidecar，通道也在 agent_up 时才注册）。所以没有 agent 调用它时，它不需要做任何事 —— 可以按需。44 个工具 ≈726 tokens 省下来可观。 ## 改动 · 22 个插件各配一个 skill，写明：何时用、先 plugin_start、 工具清单、**用 plugin_stop 而不是 plugin_disable** · 13 个 plg.json 加 `auto_start: false` · `sdk/autostart.go`：把三态语义与"按需插件必须有 skill"的理由写进公开 SDK · hmapdev 打包期校验：`auto_start=false` 但无 skill/ 目录 ⇒ 直接 exit 1 （理由：缺 skill 的按需插件**等价于没装**，比没装更糟 —— 占着磁盘让人以为可用） · 修 Lua 打包路径：它**完全不走** rawfile/skill 收集，luademo 的 skill 永远打不进去 · 修 build-examples.sh：原来 `[ ! -x ]` 判"二进制在不在"，改了 hmapdev 源码后 重新打包**仍用旧工具链**（实测：luademo 的 skill 一直是 0） · 补 mocksdk.ToolDef.Timeout（上一轮加 ToolDef.Timeout 时漏了镜像） ## 判据 · TestHasSkillDirRequiresRealSkillMd（空目录/.gitkeep/无 SKILL.md 都不算） · TestBuildRejectsOnDemandWithoutSkill（打包期必须真拦住 + exit 1） · TestLuaPackagingCollectsSkillAndRawfiles（**验代码行**，不验注释 —— 第一版 只查符号存在，把 createHmapWithRaw 换回 createHmap 判据照样通过） ## 踩过的坑 · Lua 分支的结束边界原是 `// Resolve build config`，但那个注释在文件里 **出现多次**（Go 路径里也有），用它截取会把 Go 分支一起包进来 ⇒ 变异测不出。改成截到 Lua 分支自己的 `return` + `}`。
This commit is contained in:
JianFeeeee
45
example/a2a/skill/a2a-tools/SKILL.md
Normal file
45
example/a2a/skill/a2a-tools/SKILL.md
Normal file
@ -0,0 +1,45 @@
|
||||
---
|
||||
name: a2a-tools
|
||||
description: Agent-to-Agent 协议通信（TCP 服务端 + 客户端）。本插件**常驻自启**：它在监听外部 Agent 请求。
|
||||
---
|
||||
|
||||
# A2A 通信
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
a2a 插件在 **TCP 端口上监听**其他 Agent 发来的 Tasks/Send 请求，收到后注入给本 agent 处理。
|
||||
|
||||
改成按需加载 ⇒ 端口不监听 ⇒ **外部 Agent 的请求无人应答**，
|
||||
对方只会看到连接失败或超时，而本机**毫无记录**。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `a2a_query` | 向其他 Agent 发请求 |
|
||||
| `a2a_discover` | 发现可用的对端 |
|
||||
| `a2a_configure` | 配置对端地址 |
|
||||
| `a2a_restart` | 重启监听 |
|
||||
| `a2a_status` | 查监听状态与已知对端 |
|
||||
|
||||
## 注意
|
||||
|
||||
- 监听地址/端口在插件配置里。端口冲突时 `a2a_status` 会明确报错。
|
||||
- 出站 `a2a_query` 需要能连上对端，网络不通时明确报错，不要重试到超时。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
43
example/acp/skill/acp-tools/SKILL.md
Normal file
43
example/acp/skill/acp-tools/SKILL.md
Normal file
@ -0,0 +1,43 @@
|
||||
---
|
||||
name: acp-tools
|
||||
description: Agent Client Protocol 通信（服务端 + 客户端）。本插件**常驻自启**：它在监听外部 ACP 请求。
|
||||
---
|
||||
|
||||
# ACP 通信
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
acp 插件在 **TCP 端口上监听** ACP 客户端的 session/new 等请求。
|
||||
|
||||
改成按需加载 ⇒ 端口不监听 ⇒ 外部调用方（如编辑器、其他 agent 框架）
|
||||
连不上，而本机无任何记录。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `acp_query` | 以 ACP 客户端身份向对端发起请求 |
|
||||
| `acp_configure` | 配置对端 |
|
||||
| `acp_status` | 查监听与对端状态 |
|
||||
|
||||
## 注意
|
||||
|
||||
与 a2a 的区别：A2A 是 Agent 对 Agent 的任务协议，ACP 是
|
||||
"客户端驱动 agent 会话"的协议（更像 IDE 集成）。两者可能同时在跑。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -16,5 +16,6 @@
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
}
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
50
example/ai_image/skill/ai-image-tools/SKILL.md
Normal file
50
example/ai_image/skill/ai-image-tools/SKILL.md
Normal file
@ -0,0 +1,50 @@
|
||||
---
|
||||
name: ai-image-tools
|
||||
description: AI 图像生成（DALL·E / Stable Diffusion）。按需工具：先 plugin_start ai_image，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# AI 画图
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户要求**生成图片**（画一张、生成插画、做个配图）时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=ai_image
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `ai_image_generate` | 按提示词生成图片 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=ai_image
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 需要配置**上游服务**（DALL·E 或 SD）与各自的密钥；没配时会明确报错，
|
||||
不要重试或猜一个 URL。
|
||||
- 生图有成本（按张计费）。一次不满意就调整提示词，不要连续盲试。
|
||||
- 提示词用**画面描述**（主体/风格/构图/光线），不是命令式句子。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -15,5 +15,6 @@
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
}
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
49
example/bili/skill/bili-tools/SKILL.md
Normal file
49
example/bili/skill/bili-tools/SKILL.md
Normal file
@ -0,0 +1,49 @@
|
||||
---
|
||||
name: bili-tools
|
||||
description: B站视频清晰度查询与下载（yt-dlp）。按需工具：先 plugin_start bili，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# B站视频
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户要**下载 B站视频**，或想知道某个视频有哪些清晰度可选时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=bili
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `bili_video` | 查清晰度列表 / 按指定格式下载 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=bili
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 依赖 **yt-dlp**，未安装时会明确报错。
|
||||
- 下载目录由插件配置决定，不要假设是当前工作目录。
|
||||
- 先查清晰度列表再下载，不要盲目选最高（可能体积很大）。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
55
example/browser/skill/browser-tools/SKILL.md
Normal file
55
example/browser/skill/browser-tools/SKILL.md
Normal file
@ -0,0 +1,55 @@
|
||||
---
|
||||
name: browser-tools
|
||||
description: 统一浏览器能力（搜索/HTTP 抓取/无头渲染/CDP 交互）。本插件**常驻自启**：它有 ticker 与长命令回调，会主动注入。
|
||||
---
|
||||
|
||||
# 浏览器
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
browser 插件有两处**主动注入**：
|
||||
|
||||
1. **30 秒 ticker** —— 检查长任务（渲染、下载）的进度
|
||||
2. **长时间命令的完成回调** —— 命令跑完后把结果注入回来
|
||||
|
||||
改成按需加载 ⇒ 长任务还在跑、插件却被卸载 ⇒ 结果无人接收，
|
||||
或者在跑的任务变成孤儿进程。
|
||||
|
||||
## 工具
|
||||
|
||||
| 组 | 工具 |
|
||||
|---|---|
|
||||
| 轻量 | `search` `fetch`（HTTP 抓取，快） |
|
||||
| 渲染 | `render` `html`（无头浏览器，慢） |
|
||||
| 交互 | `start` `navigate` `screenshot` `click` `type` `scroll` `close` |
|
||||
| 环境 | `install`（装浏览器依赖） |
|
||||
|
||||
## 选哪个
|
||||
|
||||
| 需求 | 用 |
|
||||
|---|---|
|
||||
| 只要页面文字 | `fetch`（最快，不执行 JS） |
|
||||
| 页面靠 JS 渲染 | `render` |
|
||||
| 要点击/填表/截图 | `start` → `navigate` → 交互 → `close` |
|
||||
|
||||
## 注意
|
||||
|
||||
- 交互式会话**用完必须 `close`**，否则浏览器进程一直占内存。
|
||||
- `install` 只在缺依赖时用，不要每次都跑。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
47
example/calendar/skill/calendar-tools/SKILL.md
Normal file
47
example/calendar/skill/calendar-tools/SKILL.md
Normal file
@ -0,0 +1,47 @@
|
||||
---
|
||||
name: calendar-tools
|
||||
description: 日历事件与提醒。本插件**常驻自启**：它定时检查提醒并主动通知。
|
||||
---
|
||||
|
||||
# 日历
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
日历插件有一个 **30 秒的提醒 ticker**。到点的事件会主动注入给 agent，
|
||||
让 agent 提醒用户。
|
||||
|
||||
改成按需加载 ⇒ 没有 ticker ⇒ **提醒永远不会响**。而"提醒不响"比"没有提醒功能"
|
||||
更糟：用户以为设了闹钟，实际上什么都没发生。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `calendar_event_add` | 新建事件（可带提醒） |
|
||||
| `calendar_event_list` | 列出事件 |
|
||||
| `calendar_event_update` | 修改事件 |
|
||||
| `calendar_event_delete` | 删除事件 |
|
||||
| `calendar_today` / `week` / `month` | 按范围查看 |
|
||||
| `calendar_search` | 搜索事件 |
|
||||
|
||||
## 注意
|
||||
|
||||
- 时间必须确认**时区**。用户说"明天三点"时，先确认是本地时间。
|
||||
- 重复事件要明确是每天/每周/每月。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -6,7 +6,13 @@
|
||||
"description": "主管式多仓库开发流水线：登记项目、开工程对话、为每条线拉起内置 pi 并注册一对通道，投递任务给 pi 并在同一会话内续投。",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["commondev", "git", "agent", "develop"],
|
||||
"tags": [
|
||||
"commondev",
|
||||
"git",
|
||||
"agent",
|
||||
"develop"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"rawfiles": []
|
||||
"rawfiles": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
@ -7,6 +7,43 @@ author: HomeAgent
|
||||
|
||||
# commondev 纪律（主管模式 · 工程对话 · 平台操作）
|
||||
|
||||
## ★ 本插件默认不自启：先拉起再用
|
||||
|
||||
commondev 的 44 个工具占约 726 tokens，是本组最大的。因此它**默认不自启**
|
||||
（`auto_start: false`），不在初始工具清单里。
|
||||
|
||||
需要开工程线/派活时：
|
||||
|
||||
```
|
||||
plugin_start name=commondev
|
||||
```
|
||||
|
||||
**用完必须关掉**（44 个工具常驻会持续吃上下文）：
|
||||
|
||||
```
|
||||
plugin_stop name=commondev
|
||||
```
|
||||
|
||||
### 什么时候可以关
|
||||
|
||||
安全关闭的判据是"**没有在跑的工程线**"：
|
||||
|
||||
1. 先查有没有活着的 sidecar：`commondev_agent_state`（看 `agent_alive`）
|
||||
2. 有在跑的线，先停：`commondev_agent_down`（暂停）或
|
||||
`commondev_agent_interrupt`（只停当前这一轮，保留会话）
|
||||
3. 确认都不在跑，再 `plugin_stop`
|
||||
|
||||
★ **不要在有 sidecar 在跑时直接 disable** —— 进程会变成孤儿。
|
||||
插件 `Stop()` 里有幂等全清（sidecar / pi 进程一个不留），但那是兜底，
|
||||
不是正常路径。
|
||||
|
||||
### 关闭不影响已做的活
|
||||
|
||||
台账（`ledger.json`）、工作目录、分支状态、凭据全部**持久化在磁盘**。
|
||||
下次 `plugin_start` 后 `commondev_project_list` / `commondev_branch_status`
|
||||
能看到之前的一切，`commondev_agent_up` 能接着用原来的 session 续投。
|
||||
|
||||
|
||||
本技能三部分，**都可能与你的任务直接相关**：
|
||||
|
||||
- **第一部分：使用者纪律** —— 怎么开工程、怎么派活。
|
||||
@ -853,3 +890,20 @@ pi 进程、sidecar、ssh 会话、workdir（含凭据残留检查）一个不
|
||||
6. **改了内置插件源码只重启服务** —— 必须重编 homed。
|
||||
7. **手改生成的文档**（`docs/api/*.md` 首行写着「请勿手改」）—— 改 `sdk/*.go` 注释再重新生成。
|
||||
8. **为了让插件生效去改 homed 的源码** —— 先确认它是不是内置插件。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
|
||||
@ -13,5 +13,6 @@
|
||||
"retrieval",
|
||||
"news"
|
||||
],
|
||||
"targets": "linux/amd64"
|
||||
}
|
||||
"targets": "linux/amd64",
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
58
example/deepsearch/skill/deepsearch-tools/SKILL.md
Normal file
58
example/deepsearch/skill/deepsearch-tools/SKILL.md
Normal file
@ -0,0 +1,58 @@
|
||||
---
|
||||
name: deepsearch-tools
|
||||
description: 真正的联网检索（本地 SearXNG 聚合多引擎）。按需工具：先 plugin_start deepsearch，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# 联网检索
|
||||
|
||||
## 什么时候用
|
||||
|
||||
需要**当前**信息（新闻、价格、版本号、事件进展），
|
||||
而你的训练数据可能过期时。
|
||||
|
||||
★ 判断标准：答案是"昨天的"就会出错的问题，就用它。
|
||||
常识性、不变的知识不用搜。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=deepsearch
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `deepsearch_search` | 通用检索（标题/URL/摘要/时间） |
|
||||
| `deepsearch_news` | 新闻检索 |
|
||||
| `deepsearch_fetch` | 抓取指定 URL 正文 |
|
||||
| `deepsearch_deep` | 深度检索（多轮、更全） |
|
||||
| `deepsearch_status` | 查后端服务是否可用 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=deepsearch
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 后端是**本地 SearXNG**。服务没起时 `deepsearch_status` 会明确报错，
|
||||
不要编造检索结果。
|
||||
- 引用检索结果时**带上 URL 和日期**，让用户能自己核对。
|
||||
- 摘要可能不准，关键事实要 `deepsearch_fetch` 打开原文确认。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -18,5 +18,6 @@
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
}
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
54
example/editdoc/skill/office-tools/SKILL.md
Normal file
54
example/editdoc/skill/office-tools/SKILL.md
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
name: office-tools
|
||||
description: 办公文档读写转换（docx/xlsx/pptx/md/csv/txt，基于 python-docx 等）。按需工具：先 plugin_start editdoc，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# 办公文档
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户要**新建/读取/编辑/转换** Word、Excel、PPT、Markdown、CSV 文件时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=editdoc
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `read_document` | 读文档内容与结构 |
|
||||
| `create_document` | 新建文档 |
|
||||
| `create_from_template` | 用模板新建 |
|
||||
| `edit_document` | 编辑现有文档 |
|
||||
| `convert_document` | 格式转换（如 docx→md） |
|
||||
| `office_check` | 检查依赖是否齐全 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=editdoc
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 依赖 **Python 库**（python-docx / openpyxl / python-pptx）。
|
||||
先跑 `office_check` 确认，缺库时工具会明确报错。
|
||||
- 改文档前先 `read_document` 看清结构，避免覆盖掉原有格式与内容。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -6,10 +6,14 @@
|
||||
"description": "文件系统操作工具集（读取/写入/编辑/列表），提供沙箱化文件访问，支持配置工作目录。",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["files", "filesystem"],
|
||||
"tags": [
|
||||
"files",
|
||||
"filesystem"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
54
example/files/skill/file-tools/SKILL.md
Normal file
54
example/files/skill/file-tools/SKILL.md
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
name: file-tools
|
||||
description: 沙箱内文件读写（read/write/edit/ls）。按需工具：先 plugin_start files，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# 文件操作
|
||||
|
||||
## 什么时候用
|
||||
|
||||
需要在**插件配置的工作目录**内读写文件时。
|
||||
|
||||
★ 如果你已经有 run_shell / bash 之类的能力，优先用那个 —— 它更直接。
|
||||
本插件适合**没有 shell 权限**或需要走沙箱路径限制的场景。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=files
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `files_read` | 读文件内容 |
|
||||
| `files_write` | 写文件（覆盖） |
|
||||
| `files_edit` | 局部替换编辑 |
|
||||
| `files_ls` | 列目录 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=files
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 只能访问**配置的工作目录**内。走出沙箱会明确报错，不要试图绕。
|
||||
- 写/改之前先读一遍，确认不是要保留的内容。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
47
example/luademo/skill/luademo-tools/SKILL.md
Normal file
47
example/luademo/skill/luademo-tools/SKILL.md
Normal file
@ -0,0 +1,47 @@
|
||||
---
|
||||
name: luademo-tools
|
||||
description: Lua 插件全功能示例（工具 + 阶段钩子 + 通道 + 数据 API）。本插件**常驻自启**：它注册 stage 钩子做示范。
|
||||
---
|
||||
|
||||
# Lua 插件示例（luademo）
|
||||
|
||||
## 这个插件是什么
|
||||
|
||||
**示例工程**，不是实用工具。它演示 Lua 插件能做的四件事：
|
||||
|
||||
1. 注册工具（`no_memory` / `cleaner` 两种形态）
|
||||
2. 注册阶段钩子
|
||||
3. 注册通道
|
||||
4. 使用数据类 API
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
它注册了 stage 钩子（与 sanitizer 同理，钩子要每轮生效）。
|
||||
若只是想看代码示例，可以关掉；若在**验证 Lua 适配层**，必须让它常驻跑着。
|
||||
|
||||
```
|
||||
plugin_stop name=luademo # 仅看代码时
|
||||
plugin_start name=luademo # 验证 Lua VM / 钩子时
|
||||
```
|
||||
|
||||
## 开发者看这里
|
||||
|
||||
读 `example/luademo/` 的源码 + 本文件即可上手写自己的 Lua 插件。
|
||||
Lua 侧能力边界由内核 `FacilityLua`（Lua 协议适配 VM）决定。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
45
example/memo/skill/memo-tools/SKILL.md
Normal file
45
example/memo/skill/memo-tools/SKILL.md
Normal file
@ -0,0 +1,45 @@
|
||||
---
|
||||
name: memo-tools
|
||||
description: 待办与备忘录（到期主动提醒）。本插件**常驻自启**：它定时检查待办到期。
|
||||
---
|
||||
|
||||
# 待办与备忘录
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
memo 插件有一个 **5 分钟的 ticker**，检查有没有到期的待办，到点主动提醒。
|
||||
|
||||
改成按需加载 ⇒ 没有 ticker ⇒ **待办到期不提醒**，
|
||||
而用户设待办就是为了被提醒。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `memo_todo_add` | 加待办（可带截止时间） |
|
||||
| `memo_todo_complete` | 完成待办 |
|
||||
| `memo_todo_list` | 列出待办 |
|
||||
| `memo_todo_delete` | 删除待办 |
|
||||
| `memo_create` / `memo_list` / `memo_delete` | 备忘录增删查 |
|
||||
|
||||
## 注意
|
||||
|
||||
待办 vs 备忘录的区别：**待办**有完成状态、会提醒；**备忘录**只是记着。
|
||||
用户说"提醒我"时用待办，说"记一下"时用备忘录。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -6,10 +6,16 @@
|
||||
"description": "音乐搜索插件，支持搜索歌曲和查看歌词（基于网易云音乐）",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["music", "song", "lyrics", "网易云"],
|
||||
"tags": [
|
||||
"music",
|
||||
"song",
|
||||
"lyrics",
|
||||
"网易云"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
48
example/music/skill/music-tools/SKILL.md
Normal file
48
example/music/skill/music-tools/SKILL.md
Normal file
@ -0,0 +1,48 @@
|
||||
---
|
||||
name: music-tools
|
||||
description: 搜索歌曲与查看歌词（网易云音乐）。按需工具：先 plugin_start music，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# 音乐搜索
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户问某首歌、某个歌手、想找歌词时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=music
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `music_search` | 按歌名/歌手搜索 |
|
||||
| `music_lyrics` | 查指定歌曲的歌词 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=music
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
只返回**曲目信息与歌词文本**，不下载音频文件。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -6,10 +6,15 @@
|
||||
"description": "图片文字识别工具，基于 Tesseract OCR 引擎。支持从 URL 或 base64 图片中提取文字内容。",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["ocr", "image", "text"],
|
||||
"tags": [
|
||||
"ocr",
|
||||
"image",
|
||||
"text"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
51
example/ocr/skill/ocr-tools/SKILL.md
Normal file
51
example/ocr/skill/ocr-tools/SKILL.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
name: ocr-tools
|
||||
description: 从图片中提取文字（Tesseract OCR）。按需工具：先 plugin_start ocr，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# 图片文字识别
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户给了**图片里带文字**（截图、照片、扫描件），需要把文字读出来时。
|
||||
|
||||
★ 如果图片是**给模型看内容**（风景、人物、界面布局），不需要 OCR ——
|
||||
直接用 see_image 看就行。只有"要文字"才用本插件。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=ocr
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `ocr_ocr_image` | 从 URL 或 base64 图片提取文字 |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=ocr
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 依赖本机 **Tesseract** 引擎；未安装时工具会明确报错，不要当成"图片里没字"。
|
||||
- 识别结果可能含错字（尤其手写/低分辨率）。引用原文时提示这一点。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -15,5 +15,6 @@
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
55
example/plugindev/skill/plugindev-tools/SKILL.md
Normal file
55
example/plugindev/skill/plugindev-tools/SKILL.md
Normal file
@ -0,0 +1,55 @@
|
||||
---
|
||||
name: plugindev-tools
|
||||
description: 插件开发工具链（脚手架/构建 .hmap/SDK 管理）。按需工具：先 plugin_start plugindev。
|
||||
---
|
||||
|
||||
# 插件开发
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户要**写一个新插件**、构建 `.hmap`、或管理 SDK 版本时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=plugindev
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `plugindev_status` | 查工具链与 SDK 状态 |
|
||||
| `plugindev_init` | 生成插件工程脚手架 |
|
||||
| `plugindev_build` | 构建打包 `.hmap` |
|
||||
| `plugindev_sdk` | SDK 版本安装/切换 |
|
||||
| `plugindev_projects` | 列已有插件工程 |
|
||||
|
||||
## 开发完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=plugindev
|
||||
```
|
||||
|
||||
## 关键纪律
|
||||
|
||||
- 构建产物（`.hmap`）**必须用 `plugin_install` 安装**，
|
||||
不要手工解包替换 `plugin.bin` —— 那会绕过整包校验、备份回滚、
|
||||
rawfile 全量解包。
|
||||
- 声明 `auto_start=false`（按需加载）的插件**必须**配 `skill/`，
|
||||
否则 agent 不知道它存在，等价于没装。打包时会被拦下。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
48
example/qq/skill/qq-tools/SKILL.md
Normal file
48
example/qq/skill/qq-tools/SKILL.md
Normal file
@ -0,0 +1,48 @@
|
||||
---
|
||||
name: qq-tools
|
||||
description: QQ 消息收发（NapCat 协议桥接）。本插件**常驻自启**：它在监听外部消息，不能按需加载。
|
||||
---
|
||||
|
||||
# QQ 消息
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
QQ 插件在 **HTTP 端口上监听 NapCat 推送**。用户发来的 QQ 消息**随时可能到达**，
|
||||
到达后它立刻注入给 agent。
|
||||
|
||||
如果把本插件改成按需加载：
|
||||
|
||||
- 内核启动时它不会被拉起
|
||||
- **没有人会去拉起它** —— 因为没有人知道有消息在等着
|
||||
- 结果：QQ 消息**静默丢失**，用户以为 agent 不理他
|
||||
|
||||
所以 `auto_start` 必须保持默认（true）。这不是性能取舍，是**功能正确性**。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `qq_send`（及消息类工具） | 主动发消息 |
|
||||
|
||||
## 注意
|
||||
|
||||
- 依赖 **NapCat** 服务在运行且已登录。
|
||||
- 消息可能过期（NapCat 侧有时效），发送失败时会明确报错。
|
||||
- **不要在群里 @全体成员**、不要连续刷屏。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -17,5 +17,6 @@
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
}
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
53
example/recoverydiag/skill/recovery-tools/SKILL.md
Normal file
53
example/recoverydiag/skill/recovery-tools/SKILL.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
name: recovery-tools
|
||||
description: 崩溃取证与自检（退出码/信号/config.db 完整性/日志扫描）。按需工具：先 plugin_start recoverydiag。
|
||||
---
|
||||
|
||||
# 故障取证
|
||||
|
||||
## 什么时候用
|
||||
|
||||
服务**起不来、反复重启、行为异常**，需要查清原因时。
|
||||
正常运行时不需要它。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=recoverydiag
|
||||
```
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `diag_triage` | 退出码/信号/存活状态粗分 |
|
||||
| `diag_db` | config.db 完整性检查 |
|
||||
| `diag_log_scan` | 扫描日志找错误模式 |
|
||||
| `diag_delta` | 对比两次快照的差异 |
|
||||
| `diag_loc` | 定位日志/配置位置 |
|
||||
|
||||
## 排查完可释放
|
||||
|
||||
```
|
||||
plugin_stop name=recoverydiag
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
这些工具**只读**诊断，不修改任何状态。
|
||||
要修复请明确告知用户具体动作，不要自行修改系统配置。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
44
example/rss/skill/rss-tools/SKILL.md
Normal file
44
example/rss/skill/rss-tools/SKILL.md
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
name: rss-tools
|
||||
description: RSS/Atom 订阅与更新推送。本插件**常驻自启**：它定时轮询订阅源，新内容要主动推送。
|
||||
---
|
||||
|
||||
# RSS 订阅
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
RSS 插件每 **N 分钟轮询**所有订阅源。发现新文章后**主动注入**给 agent，
|
||||
由 agent 决定要不要告诉用户。
|
||||
|
||||
改成按需加载 ⇒ 没人轮询 ⇒ **新文章永远不会被发现**，而且不报错。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `rss_subscribe` | 订阅一个源 |
|
||||
| `rss_unsubscribe` | 取消订阅 |
|
||||
| `rss_list` | 列出所有订阅 |
|
||||
| `rss_check_now` | 立刻检查一次（不等下一次轮询） |
|
||||
|
||||
## 注意
|
||||
|
||||
- 轮询间隔可在插件配置里调（默认 30 分钟）。
|
||||
- 订阅源失效会记日志但不会删订阅，需要时用 `rss_list` 看状态。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
38
example/sanitizer/skill/sanitizer-tools/SKILL.md
Normal file
38
example/sanitizer/skill/sanitizer-tools/SKILL.md
Normal file
@ -0,0 +1,38 @@
|
||||
---
|
||||
name: sanitizer-tools
|
||||
description: 清洗 LLM 输出里的工具调用残留（思维泄漏）。本插件**常驻自启**：它注册的是 stage 钩子，不解包任何工具。
|
||||
---
|
||||
|
||||
# 输出清洗
|
||||
|
||||
## 本插件为什么常驻
|
||||
|
||||
sanitizer **没有工具**，它注册三个 stage 钩子：
|
||||
|
||||
| 钩子 | 时机 | 作用 |
|
||||
|---|---|---|
|
||||
| `StageOnInput` | 输入时 | 清理输入里的协议残留 |
|
||||
| `StageAfterToolcall` | 工具调用后 | 去掉工具结果的格式噪声 |
|
||||
| `StagePostAction` | 动作后 | 清洗即将发出去的回复 |
|
||||
|
||||
stage 钩子**必须在每一轮**都生效。停掉它不影响"能不能用"，
|
||||
但会让脏输出漏给用户（模型把内部工具调用语法当正文吐出来）。
|
||||
|
||||
所以它属于"基础设施型"插件：既不占工具槽位，也不能按需加载。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -6,6 +6,11 @@
|
||||
"description": "管理 VanBlog 开源博客系统：文章的增删改查、分类标签管理、草稿发布、备份导出等",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["blog", "vanblog", "cms"],
|
||||
"targets": "linux/amd64"
|
||||
}
|
||||
"tags": [
|
||||
"blog",
|
||||
"vanblog",
|
||||
"cms"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
60
example/vanblog/skill/vanblog-tools/SKILL.md
Normal file
60
example/vanblog/skill/vanblog-tools/SKILL.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
name: vanblog-tools
|
||||
description: 管理 VanBlog 博客（文章/分类/标签/草稿/备份等，28 个工具）。按需工具：先 plugin_start vanblog，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# VanBlog 博客管理
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户要**写/改文章、管分类标签、发布草稿、备份**他们的 VanBlog 站点时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=vanblog
|
||||
```
|
||||
|
||||
工具按用途分组（都带 `vanblog_` 前缀）：
|
||||
|
||||
| 组 | 工具 |
|
||||
|---|---|
|
||||
| 文章 | `list_articles` `get_article` `create_article` `update_article` `delete_article` `search_articles` |
|
||||
| 草稿 | `manage_drafts` |
|
||||
| 分类/标签 | `manage_categories` `manage_tags` |
|
||||
| 媒体/链接 | `manage_images` `manage_links` |
|
||||
| 站点配置 | `manage_settings` `manage_site` `manage_menu` `manage_about` `manage_social` `manage_rewards` |
|
||||
| 页面 | `manage_pages` |
|
||||
| 运维 | `get_analysis` `get_logs` `manage_backup` `manage_caddy` `manage_isr` `manage_pipelines` |
|
||||
| 协作 | `manage_collaborators` `manage_tokens` `auth` `get_meta` |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
28 个工具占约 454 tokens，是本组里第二大的。写完博客就关掉：
|
||||
|
||||
```
|
||||
plugin_stop name=vanblog
|
||||
```
|
||||
|
||||
## 关键纪律
|
||||
|
||||
- **删除类操作**（`delete_article` 等）不可逆。执行前必须向用户确认是哪一篇。
|
||||
- 改文章前先 `get_article` 读原文，不要用新内容整篇覆盖。
|
||||
- 需要 API key 与站点地址；没配时工具会明确报错，不要猜。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -13,5 +13,6 @@
|
||||
"gtd",
|
||||
"productivity"
|
||||
],
|
||||
"targets": "linux/amd64"
|
||||
}
|
||||
"targets": "linux/amd64",
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
58
example/vikunja/skill/vikunja-tools/SKILL.md
Normal file
58
example/vikunja/skill/vikunja-tools/SKILL.md
Normal file
@ -0,0 +1,58 @@
|
||||
---
|
||||
name: vikunja-tools
|
||||
description: 管理 Vikunja 任务/项目/看板（28 个工具）。按需工具：先 plugin_start vikunja，用完可 plugin_stop。
|
||||
---
|
||||
|
||||
# Vikunja 任务管理
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户要**建/改任务、管项目看板、打标签、看通知**他们的 Vikunja 时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
```
|
||||
plugin_start name=vikunja
|
||||
```
|
||||
|
||||
工具按用途分组（都带 `vikunja_` 前缀）：
|
||||
|
||||
| 组 | 工具 |
|
||||
|---|---|
|
||||
| 任务 | `tasks` `task_get` `task_create` `task_update` `task_done` `task_delete` `task_bulk` |
|
||||
| 任务细节 | `task_assignees` `task_labels` `task_comments` `task_relations` `task_attachments` |
|
||||
| 项目/视图 | `projects` `project_views` |
|
||||
| 组织 | `labels` `filters` `teams` `sharing` |
|
||||
| 协作 | `notifications` `subscriptions` `webhooks` `reactions` |
|
||||
| 其他 | `time_entries` `migrate` `user` `admin` `api` `status` |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
28 个工具占约 365 tokens。做完任务管理就关掉：
|
||||
|
||||
```
|
||||
plugin_stop name=vikunja
|
||||
```
|
||||
|
||||
## 关键纪律
|
||||
|
||||
- **`task_delete` 与 `admin` 不可逆**。执行前向用户确认具体对象。
|
||||
- `task_bulk` 会一次改多条，先说明影响范围。
|
||||
- 需要 API token 与实例地址；没配时明确报错，不要猜。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
@ -6,11 +6,15 @@
|
||||
"description": "天气查询插件（基于 wttr.in），支持实时天气和未来预报",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["weather", "forecast", "wttr"],
|
||||
"tags": [
|
||||
"weather",
|
||||
"forecast",
|
||||
"wttr"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
"source_dirs": [],
|
||||
"auto_start": false
|
||||
}
|
||||
|
||||
|
||||
58
example/weather/skill/weather-tools/SKILL.md
Normal file
58
example/weather/skill/weather-tools/SKILL.md
Normal file
@ -0,0 +1,58 @@
|
||||
---
|
||||
name: weather-tools
|
||||
description: 查询实时天气与未来预报。按需工具：用到时先 plugin_start weather 拉起，用完可 plugin_stop 释放。
|
||||
---
|
||||
|
||||
# 天气查询
|
||||
|
||||
## 什么时候用
|
||||
|
||||
用户问**天气**、气温、是否下雨、要不要带伞、未来几天怎么样时。
|
||||
|
||||
## 先拉起插件
|
||||
|
||||
本插件默认**不自启**（不在初始工具清单里）。调用前先启用：
|
||||
|
||||
```
|
||||
plugin_start name=weather
|
||||
```
|
||||
|
||||
启用后可用工具：
|
||||
|
||||
| 工具 | 用途 |
|
||||
|---|---|
|
||||
| `weather_current` | 当前实时天气（温度/湿度/风力/天气现象） |
|
||||
| `weather_forecast` | 未来若干天预报 |
|
||||
| `weather_set_location` | 设置默认城市（避免每次都说地名） |
|
||||
|
||||
## 用完可释放
|
||||
|
||||
天气是一次性查询，问完不再需要。连续问同一类问题时保持启用即可；
|
||||
换了别的话题、且较长时间不会再查天气，可以关掉以释放上下文：
|
||||
|
||||
```
|
||||
plugin_stop name=weather
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 数据源是 wttr.in，**不需要 API key**。
|
||||
- 用户没给城市时，先看有没有设置过默认位置；没有就问一句，不要瞎猜。
|
||||
- 查的是**真实天气**，不要把训练数据里的气温当答案。
|
||||
|
||||
## ★ 用 plugin_stop / plugin_start，不要用 plugin_disable / plugin_enable
|
||||
|
||||
四个工具看着像同义词，语义差别很大：
|
||||
|
||||
| 工具 | 作用 | 跨重启 |
|
||||
|---|---|---|
|
||||
| `plugin_stop` | **运行态**关闭，现在停掉 | **不影响**，重启照常加载 |
|
||||
| `plugin_start` | **运行态**拉起，现在开回来 | 不影响 |
|
||||
| `plugin_disable` | **持久**禁用 | **会记下来**，开机也不自启 |
|
||||
| `plugin_enable` | 解除持久禁用 | 会记下来 |
|
||||
|
||||
**释放上下文用 `plugin_stop`。** 用 `plugin_disable` 会顺手把"开机自启"
|
||||
永久关掉 —— 用户下次开机发现插件没了，得再手动开回来。
|
||||
|
||||
（本插件声明 `auto_start: false`，所以它本来就不自启；但 `plugin_disable`
|
||||
仍会写进持久禁用清单，让 `plugin_start` 拒绝拉起，只能再用 `plugin_enable` 解。）
|
||||
Reference in New Issue
Block a user