mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-20 08:58:03 +00:00
4482235312
线上真调用暴露：vikunja_task_create 把 project_id 当字符串发出 →
422 validation failed: expected integer at body.project_id。同类的还有指派，
而且 v2 的 assignees **根本不接受 username 字段**（422 unexpected property），
两个分支都是坏的。单测没盖到，因为从未发过真实请求体。
实测（vikunja v2.6.0，2026-09-12）：
{"project_id":"1"} → 422 expected integer
{"user_id":"1"} → 422 expected integer
{"username":"jianf"} → 422 unexpected property
{"user_id":1} → 201 ✓
{"label_id":1} → 201 ✓（插件本来就 Atoi，无需改）
修法：
- taskBody：project_id 走 parseID（数字）
- 新增 resolveUserID：用户名 → 数字 id，查 GET /users?q=（v1 用 ?s=）；
**只认精确匹配**，不做「只有一条就用它」的模糊兜底 —— 指派是写别人任务的动作，猜错人更贵
- assigneeBody：v2 只发 {"user_id":N}，不再带 username
- task_assignees remove：路径也用解析后的数字 id
新增 5 项回归测试钉住请求体形状（数字 project_id / user_id、无 username 字段、
数字 ID 不查用户表、移除走数字路径、未知用户给可读错误）。
版本 1.0.0 → 1.0.1。线上复验：create(project_id=1, assignees=jianf) 不再报错、
add→list 显示 jianf、标签 add/remove 正常，测试数据已清理（任务/标签残留 0）。
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 同步。