shad0wca7-vikunja-kanban

通过 API 管理 Vikunja 看板，支持任务创建、移动与 heartbeat 集成。

## 概述（中文）

通过 API 管理 Vikunja 看板，支持任务创建、移动与 heartbeat 集成。

## 技能正文

# Vikunja Kanban Skill

通过 API 管理 Vikunja 看板。读取状态、创建/移动/完成任务，并与 heartbeat 和 triage 定时任务集成。

## 配置

凭据存储在 `secrets/vikunja.env` 中：
```
VIKUNJA_URL=https://your-vikunja-instance
VIKUNJA_TOKEN=${VIKUNJA_TOKEN}
VIKUNJA_PROJECT_ID=1
VIKUNJA_VIEW_ID=4
```

## 认证

所有脚本使用**长期有效的 API 令牌**（2030-01-01 过期）。无需 JWT 登录。
- 权限：tasks（read_all、update、create、delete）、projects（read_all、update、create）
- `secrets/vikunja.env` 中保留 JWT 登录凭据仅供参考

## 桶 ID

| ID | Name | Purpose |
|----|------|---------|
| 1 | 🔴 Urgent | 需要立即关注 |
| 2 | ⏳ Waiting On | 已发送/已请求，等待回复 |
| 7 | ⚠️ System Issues | 基础设施/系统问题 |
| 8 | 🚧 Active Projects | 进行中 |
| 9 | 📅 Upcoming | 已排期/未来 |
| 10 | 📥 Inbox | 新项目，未分类 |
| 3 | ✅ Done | 已完成 |

## 脚本

所有脚本位于 skill 的 `scripts/` 目录中。从 skill 根目录运行。

### 读取看板
```bash
bash scripts/vikunja-status.sh              # All buckets
bash scripts/vikunja-status.sh "Urgent"     # Filter by bucket name
```

### 添加任务
```bash
bash scripts/vikunja-add-task.sh "Title" "Description" BUCKET_ID [PRIORITY]
# Priority: 0=unset, 1=low, 2=medium, 3=high, 4=urgent
# Example: bash scripts/vikunja-add-task.sh "Fix DNS" "Check records" 1 4
```

### 在桶之间移动任务
```bash
bash scripts/vikunja-move-task.sh TASK_ID BUCKET_ID
# Example: bash scripts/vikunja-move-task.sh 15 3  # Move to Done
```

### 完成任务
```bash
bash scripts/vikunja-complete-task.sh TASK_ID
```

## Heartbeat 集成

heartbeat 定时任务从 Vikunja 读取：
```bash
bash scripts/vikunja-status.sh
```
- 检查 🔴 Urgent 中存在超过 1 小时的项目
- 如果 Vikunja 不可达，回退到 `scripts/nc-status-board.sh read`

## 邮件分类集成

邮件分类将 Action Required 项目添加到 Inbox 桶：
```bash
bash scripts/vikunja-add-task.sh "Email subject" "Brief description" 10 3
```

## API 参考

- **Base URL:** https://your-vikunja-instance/api/v1
- **Auth:** POST /login，使用用户名/密码 → JWT 令牌（短期有效）
- **Tasks:** PUT /projects/{id}/tasks（创建），POST /tasks/{id}（更新）
- **Buckets:** POST /projects/{id}/views/{view}/buckets/{bucket}/tasks（移动任务）
- **Views:** GET /projects/{id}/views/{view}/tasks（按桶列出任务）
- **Projects:** POST /projects/{id}（更新标题/设置），GET /projects（列出全部）
- **Sharing:** PUT /projects/{id}/users `{"username":"...", "right":N}`（添加用户）
- **Users:** GET /users?s=query（搜索），POST /user/password（自助修改密码）

## 已知 API 缺陷与坑

### 创建时共享权限被忽略
`PUT /projects/{id}/users` 会忽略 `right` 字段 —— 始终以 permission=0（只读）创建。
**变通方案：** 直接在 PostgreSQL 中设置权限：
```sql
UPDATE users_projects SET permission = 2 WHERE user_id = X AND project_id = Y;
```
权限值：0=只读，1=读+写，2=管理员

### 默认 Inbox 项目无法删除
每个新用户都会获得一个自动创建的 "Inbox" 项目。`DELETE /projects/{id}` 返回错误 3012。
**变通方案：** 重命名它：`POST /projects/{id}`，使用 `{"title":"New Name"}`

### 密码修改仅限自助
没有用于修改其他用户密码的管理员端点。必须以目标用户身份登录：
`POST /api/v1/user/password`，使用 `{"old_password":"...", "new_password":"..."}`

### API 令牌创建需要同时具备 tasks 和 projects 权限
仅具有 `tasks` 权限的令牌无法读取看板视图（返回 401）。
必须包含：`"permissions":{"tasks":["read_all","update","create","delete"],"projects":["read_all","update","create"]}`

### 令牌创建端点
`PUT /api/v1/tokens` 创建，`GET /api/v1/tokens` 列出，`DELETE /api/v1/tokens/{id}` 移除。
必需字段：`title`、`expires_at`（ISO-8601）、`permissions`（含权限组的对象）。

## 说明

- 使用**长期有效的 API 令牌**（2030 过期）—— 无 JWT 登录开销
- Vikunja 使用 PUT 创建、POST 更新（不寻常）
- 桶 ID 特定于看板视图（view_id=4）
- 项目名称："Kit Operations"（从默认的 "Inbox" 重命名）
- 项目共享给：Kit（id:1，管理员/所有者）、Alex（id:2，通过数据库修复获得管理员权限）
- 令牌具有 tasks + projects 权限；覆盖所有看板操作
- 每个用户都会获得一个无法删除的默认项目 —— 重命名以避免混淆