Vikunja Task Manager#

Vikunja 是一个轻量开源任务管理工具，部署于 http://localhost:3456，REST API v1。

凭证（多 Agent 支持）#

Token 支持两种读取方式（按优先级）：

1. 环境变量 VIKUNJA_TOKEN（推荐，适合 agent 运行时注入）
2. Token 文件 $AGENT_WORKSPACE/config/.vikunja-token（每个 agent 有自己独立的 token 文件）

获取 Token：

bash

RESP=$(curl -s -X POST http://localhost:3456/api/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"your-user","password":"your-pass"}')
TOKEN=$(echo "$RESP" | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
echo "$TOKEN"

存入 token 文件（每个 agent 不同路径）：

bash

mkdir -p "$AGENT_WORKSPACE/config"
echo "$TOKEN" > "$AGENT_WORKSPACE/config/.vikunja-token"
chmod 600 "$AGENT_WORKSPACE/config/.vikunja-token"

读取 Token：

bash

get_token() {
  [ -n "$VIKUNJA_TOKEN" ] && { echo "$VIKUNJA_TOKEN"; return; }
  [ -f "$AGENT_WORKSPACE/config/.vikunja-token" ] && cat "$AGENT_WORKSPACE/config/.vikunja-token"
}
TOKEN=$(get_token)

多 Agent 场景：每个 agent 独立 login，token 互不干扰。Vikunja 本身 token 无过期时间，可长期使用。

项目（Projects）#

bash

# 列出项目
curl -s http://localhost:3456/api/v1/projects -H "Authorization: Bearer $TOKEN"

# 创建项目（PUT /projects）
curl -s -X PUT http://localhost:3456/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"项目名","description":""}'

# 获取项目
curl -s http://localhost:3456/api/v1/projects/{id} -H "Authorization: Bearer $TOKEN"

# 更新项目（POST）
curl -s -X POST http://localhost:3456/api/v1/projects/{id} \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"新标题"}'

# 删除项目
curl -s -X DELETE http://localhost:3456/api/v1/projects/{id} -H "Authorization: Bearer $TOKEN"

任务（Tasks）#

⚠️ 创建用 PUT /projects/{id}/tasks，更新用 POST /tasks/{id}

bash

# 在项目里创建任务（PUT，不是 POST）
curl -s -X PUT http://localhost:3456/api/v1/projects/{project_id}/tasks \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"任务标题","description":"描述","priority":2}'

# 更新任务（POST，不是 PUT）
curl -s -X POST http://localhost:3456/api/v1/tasks/{task_id} \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"done":true,"priority":3}'

# 列出所有任务
curl -s http://localhost:3456/api/v1/tasks -H "Authorization: Bearer $TOKEN"

# 搜索标题
curl -s "http://localhost:3456/api/v1/tasks?s=关键词" -H "Authorization: Bearer $TOKEN"

# 过滤（done=false 只显示未完成）
curl -s "http://localhost:3456/api/v1/tasks?filter=done%20%3D%20false" \
  -H "Authorization: Bearer $TOKEN"

# 列出某项目任务
curl -s http://localhost:3456/api/v1/projects/{project_id}/tasks \
  -H "Authorization: Bearer $TOKEN"

# 删除任务
curl -s -X DELETE http://localhost:3456/api/v1/tasks/{id} -H "Authorization: Bearer $TOKEN"

评论（Comments）#

bash

# 添加评论（字段名是 comment，不是 text）
curl -s -X PUT http://localhost:3456/api/v1/tasks/{task_id}/comments \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"comment":"评论内容"}'

# 获取评论
curl -s http://localhost:3456/api/v1/tasks/{task_id}/comments \
  -H "Authorization: Bearer $TOKEN"

标签（Labels）#

bash

# 创建标签
curl -s -X PUT http://localhost:3456/api/v1/labels \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"in-progress","color":"#ff9900"}'

# 给任务打标签
curl -s -X PUT http://localhost:3456/api/v1/tasks/{task_id}/labels \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"labels": [{"id": 1}]}'

负责人（Assignees）#

bash

# 分配负责人
curl -s -X PUT http://localhost:3456/api/v1/tasks/{task_id}/assignees \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"user_id": 2}'

# 获取负责人
curl -s http://localhost:3456/api/v1/tasks/{task_id}/assignees \
  -H "Authorization: Bearer $TOKEN"

信息查询#

bash

# 服务信息（版本、功能开关）
curl -s http://localhost:3456/api/v1/info -H "Authorization: Bearer $TOKEN"

Python 模板#

python

import requests, os

BASE = "http://localhost:3456/api/v1"
TOKEN_FILE = os.path.join(os.getenv("AGENT_WORKSPACE", "."), "config", ".vikunja-token")

def get_token():
    if os.getenv("VIKUNJA_TOKEN"):
        return os.getenv("VIKUNJA_TOKEN")
    with open(TOKEN_FILE) as f:
        return f.read().strip()

def headers():
    return {"Authorization": f"Bearer {get_token()}", "Content-Type": "application/json"}

def create_task(project_id, title, **kw):
    return requests.put(f"{BASE}/projects/{project_id}/tasks",
                        json={"title": title, **kw}, headers=headers()).json()

def update_task(task_id, **kw):
    return requests.post(f"{BASE}/tasks/{task_id}", json=kw, headers=headers()).json()

def search_tasks(q):
    return requests.get(f"{BASE}/tasks", params={"s": q}, headers=headers()).json()

已知坑#

1. 创建任务用 PUT /projects/{id}/tasks，不是 POST
2. 更新任务用 POST /tasks/{id}，不是 PUT（PUT 报 405）
3. 评论字段是 comment，不是 text
4. 批量创建 POST /tasks/bulk 文档有但实测不通，循环单条操作代替

Agent Rules#

• 先尝试从 VIKUNJA_TOKEN 环境变量读取 token；无则读 $AGENT_WORKSPACE/config/.vikunja-token
• Token 不硬编码，运行时从磁盘或环境变量读取
• 日志只含 metadata（操作类型、数量），无 token 值
• Token 文件权限 600
• Token 泄露后：重新 login 获取新 token 存入文件