mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 06:17:25 +00:00
74e2c654ed
## 用户的三条要求 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` + `}`。
Vikunja 插件（HomeAgent）
把 Vikunja 待办/任务管理接入 HomeAgent：用自然语言查任务、建任务、改期、完成、看板拖动、指派、评论、时间跟踪、导入数据等。
配置项（全部可在插件配置界面修改）
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
url |
string | https://vikunja.jianfgit.xyz |
站点根地址，不带 /api |
token |
password(secret) | 空 | 必填。Vikunja → 设置 → API Tokens 生成（tk_ 开头）。令牌的权限范围决定本插件能力上限：勾全范围即为完整能力 |
api_version |
select | v2 |
v2（推荐，标准 REST，含时间跟踪等新能力）或 v1（用于 v2 暂未提供的端点） |
default_project_id |
string | 空 | 新建任务未指定项目时落到这里；留空则必须显式指定 |
max_items |
int | 25 |
列表类工具的默认条数，控制上下文体积 |
compact_output |
bool | true |
任务/项目/标签列表只返回关键字段；关闭则返回 Vikunja 完整对象 |
timeout_seconds |
int | 20 |
单次 HTTP 超时 |
verify_tls |
bool | true |
自签证书站点可关闭（不建议） |
配置在每次工具调用前重新读取，因此换了 token 不必重启插件。
工具
| 工具 | 能力 |
|---|---|
vikunja_status |
连接/配置自检：地址、token 对应的用户、API 版本、服务器能力、CalDAV 地址 |
vikunja_tasks |
列任务：按项目、完成状态、截止（today/this_week/overdue/no_due）、关键词、原生 filter 表达式 |
vikunja_task_get / task_create / task_update / task_done / task_delete |
任务增删改查（task_update 只传要改的字段） |
vikunja_task_bulk |
批量改完成状态/项目/优先级/截止/标签 |
vikunja_task_assignees / task_labels / task_comments / task_relations / task_attachments |
指派、标签、评论、关联（子任务/依赖/相关）、附件（支持上传本地文件） |
vikunja_projects / project_views |
项目增删改查、归档；视图与看板桶（把任务移入桶＝看板拖动） |
vikunja_labels / filters |
标签、保存的筛选器（Saved Filter） |
vikunja_teams / sharing |
团队与成员；项目分享（用户/团队授权、链接分享含密码） |
vikunja_notifications / subscriptions / webhooks |
通知、订阅、Webhook 管理 |
vikunja_time_entries |
时间跟踪（仅 v2）：补录/修改/删除、开始与停止计时器 |
vikunja_migrate |
从 TickTick/WeKan/CSV/Planka/Vikunja 文件（v2）与 Todoist/Trello/微软待办（v1）导入 |
vikunja_user / vikunja_admin |
当前账号（设置、登录会话、API Token）与实例管理（用户增删/提权/停用/改密、项目归属转移，需实例管理员） |
vikunja_reactions |
任务/评论的表情回应 |
vikunja_api |
通用直通：调任意端点，未封装的能力走这里（可强制指定 v1/v2），保证能力无死角 |
v1 / v2 差异（已按实例自带规范逐条核对）
插件默认 v2，并自动处理下列差异：
| 操作 | v1 | v2 |
|---|---|---|
| 建任务 | PUT /projects/{id}/tasks |
POST /projects/{id}/tasks |
| 改任务 | POST /tasks/{id}（必须整对象 → 插件自动取回-合并-提交） |
PATCH /tasks/{id}（merge-patch，只发变更字段；被拒则回落取回-合并-PUT） |
| 搜索参数 | ?s= |
?q= |
| 加标签 | PUT（Label 对象） |
POST（{"label_id":N}） |
| 批量改 | POST /tasks/bulk |
PUT /tasks/bulk |
| 时间跟踪 | 不支持 | /time-entries（end_time 为 null 即计时中；停止用 /time-entries/timer/stop） |
| 导入 | Todoist / Trello / 微软待办 | TickTick / WeKan / CSV / Planka / Vikunja 文件 |
官方路线：v1 仍支持但新端点只进 v2，3.0 弃用、4.0 移除。除“导入”外建议一律用 v2。
开发与构建
cd third_party/homeagent-sdk/example/vikunja
go test -count=1 -race ./... # 16 项测试（httptest 打桩，不需要真 token）
hmapdev build # 产出 dist/vikunja_bundle.hmap
go.mod 里的 replace 把 SDK 指向仓库内的 third_party/homeagent-sdk，因此无需联网拉私有模块。
部署到运行实例
.hmap 包内是 plugin.json + plugin.bin.<os>.<arch>，安装时按运行平台重命名入口文件：
unzip -o dist/vikunja_bundle.hmap -d /home/newqqagent/plugins/vikunja
cd /home/newqqagent/plugins/vikunja && mv plugin.bin.linux.amd64 plugin.bin
# 然后重载插件（或重启 homeagent.service）
已知边界
- 附件下载未单独封装：
task_attachments支持列出/上传/删除，下载请用vikunja_api访问附件 URL。 - 链接分享的字段（
right/password）按 Vikunja 版本语义透传；如遇 4xx，可直接用raw参数传完整 JSON。 - 批量改标签的
fields结构以BulkTask为准，未在真实实例上验证过（缺少可用 token），如有偏差请用vikunja_api直通。 - CalDAV 是客户端协议，插件只提供地址（
vikunja_status里的caldav_url），不做 CalDAV 同步。