Tasks.md 3.3.0 API 使用详解

目标：基于实测讲解 Tasks.md 3.3.0 内置 HTTP API 的全部接口（资源/标签/排序/图片/标题），覆盖请求方法、参数、真实响应与错误处理。Tasks.md 不提供命令行管理工具，所有自动化操作都通过该 API 完成。本文所有请求与响应均在 Ubuntu 22.04 + Tasks.md 3.3.0 环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• 组件版本：Tasks.md 3.3.0（后端 Koa，单进程 8080 端口）
• 部署方式：源码安装 + systemd 托管（见《Ubuntu 22.04 安装 Tasks.md 3.3.0 指南》）
• 测试工具：curl（Ubuntu 22.04 自带 7.81.0）
• 演示数据：TASKS_DIR=/opt/tasks-md-data/tasks 下已建「待办 / 进行中 / 已完成」三条泳道，「待办」下有一张「写周报.md」卡片

二、前置条件

1. Tasks.md 服务已启动并监听 8080 端口：

systemctl is-active tasks-md

实测回显：

active

2. 本机能访问服务端口（本文全部示例使用 http://localhost:8080，远程调用替换为服务器地址即可）。

3. ⚠️ 调用约定（实测得出的两条硬规则）：

   • URL 中的非 ASCII 路径段必须 percent-encode（如「待办」→ %E5%BE%85%E5%8A%9E），否则会出现乱码目录或 404（实测排障见七、常见问题 Q1）；
   • 请求体一律带 Content-Type: application/json（图片上传除外，用 multipart）。

三、API 总览

Tasks.md 后端把 API 统一挂载在 {BASE_PATH}/_api 之下（根路径部署时即 /_api）。接口一览（依据 backend/server.js 源码逐条实测）：

认证方式：Tasks.md 3.3.0 无任何认证机制，能访问端口即可调用全部接口。生产环境必须用防火墙或带认证的反向代理隔离（见《配置参数详解》篇安全提示）。

限流：无内置限流。

路径规则：<路径> 相对 TASKS_DIR；根项目用 /（即 /_api/resource/ 结尾带斜杠）。泳道 = 目录，卡片 = 以 .md 结尾的文件。

四、认证与首次调用

无需认证。用 GET /_api/title 做连通性检查——这是最简单的只读接口：

curl -s http://localhost:8080/_api/title

实测回显：

Tasks.md 生产看板

返回值为 TITLE 环境变量的原文（纯文本，非 JSON），能拿到该值即说明 API 可用。

五、各 API 域详解

5.1 资源接口（resource）：泳道与卡片的增删改查

列出根项目的全部泳道与卡片：

curl -s http://localhost:8080/_api/resource/

实测回显：

[{"name":"已完成","files":[]},{"name":"待办","files":[{"name":"写周报","content":"## 本周目标\n\n- [ ] 完成选型报告\n","lastUpdated":"2026-10-25T01:14:53.304Z","createdAt":"2026-10-25T01:14:53.304Z"}]},{"name":"进行中","files":[]}]

响应是泳道数组，每个泳道含 name 与 files；每张卡片含 name（不含 .md 后缀）、content（Markdown 全文）、lastUpdated/createdAt（文件 mtime/birthtime）。

新建泳道（路径不含 .md 后缀即建目录）：

curl -s -o /dev/null -w "%{http_code}\n" -X POST "http://localhost:8080/_api/resource/%E5%9B%9E%E9%A1%BE" -H "Content-Type: application/json" -d '{}'

实测回显（「回顾」泳道）：

201

新建卡片（路径以 .md 结尾 + 请求体 isFile: true）：

curl -s -o /dev/null -w "%{http_code}\n" -X POST "http://localhost:8080/_api/resource/%E5%BE%85%E5%8A%9E/%E5%86%99%E5%91%A8%E6%8A%A52.md" -H "Content-Type: application/json" -d '{"isFile":true,"content":"## 下周计划\n\n- [ ] 评审方案\n"}'

实测回显：

201

更新卡片内容（PATCH + content 字段）：

curl -s -o /dev/null -w "%{http_code}\n" -X PATCH "http://localhost:8080/_api/resource/%E5%BE%85%E5%8A%9E/%E5%86%99%E5%91%A8%E6%8A%A5.md" -H "Content-Type: application/json" -d '{"content":"## 本周目标\n\n- [x] 完成选型报告\n- [ ] 整理会议纪要\n"}'
cat /opt/tasks-md-data/tasks/待办/写周报.md

实测回显：

204
## 本周目标

- [x] 完成选型报告
- [ ] 整理会议纪要

204 表示成功；cat 回显证明 API 修改直接落到 Markdown 文件。

移动/重命名卡片（PATCH + newPath 字段）：把「待办/写周报2.md」移入「进行中」泳道：

curl -s -o /dev/null -w "%{http_code}\n" -X PATCH "http://localhost:8080/_api/resource/%E5%BE%85%E5%8A%9E/%E5%86%99%E5%91%A8%E6%8A%A52.md" -H "Content-Type: application/json" -d '{"newPath":"进行中/写周报2.md"}'

实测回显：

204

💡 说明：newPath 与源路径同目录时即为重命名；跨目录时即为移动（对应界面上拖拽卡片换泳道）。newPath 中的非法字符 <>:"/\|?*# 会被后端替换为空格。

删除泳道或卡片（DELETE，递归删除）：

curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://localhost:8080/_api/resource/%E5%9B%9E%E9%A1%BE"

实测回显：

204

⚠️ 注意：DELETE 对目录是递归的（recursive: true），删除泳道会连其下全部卡片一起删除且不可恢复，调用前请确认。

错误响应：操作不存在的资源时返回 404（实测 PATCH 不存在的卡片返回 Not Found）；路径编码错误时返回 500（详见七、常见问题）。

5.2 标签接口（tags）

标签颜色按「项目路径 → 标签名 → 颜色」存储在 CONFIG_DIR/tags.json。

读取根项目标签（未设置时返回空对象）：

curl -s "http://localhost:8080/_api/tags/"

实测回显：

{}

设置标签颜色：

curl -s -o /dev/null -w "%{http_code}\n" -X PATCH "http://localhost:8080/_api/tags/" -H "Content-Type: application/json" -d '{"bug":"var(--color-alt-1)","需求":"var(--color-alt-2)"}'
curl -s "http://localhost:8080/_api/tags/"

实测回显：

204
{"bug":"var(--color-alt-1)","需求":"var(--color-alt-2)"}

颜色值推荐使用主题预置变量 var(--color-alt-1) ~ var(--color-alt-7)（见《配置参数详解》篇颜色变量表），也可直接写 CSS 颜色（如 #e01b24）。

5.3 排序接口（sort）

保存泳道内卡片的排列顺序，数据写入 CONFIG_DIR/sort.json。

保存「待办」泳道的卡片顺序：

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "http://localhost:8080/_api/sort/" -H "Content-Type: application/json" -d '{"待办":["写周报"]}'
curl -s "http://localhost:8080/_api/sort/"

实测回显：

200
{"待办":["写周报"]}

PUT 为合并写入：只更新请求体中给出的泳道键，其他泳道的排序保持不变。

5.4 图片接口（image）

上传图片（multipart 表单，字段名固定为 file）：

curl -s -X POST http://localhost:8080/_api/image -F "file=@/tmp/t.png"

实测回显：

ecb83ad8-ffda-4ca7-8385-e6fd45d64bc9.png

返回值为服务端生成的 UUID 文件名，图片保存在 CONFIG_DIR/images/ 下。

在卡片中引用：Markdown 正文写 ![描述](_api/image/ecb83ad8-ffda-4ca7-8385-e6fd45d64bc9.png)。

读取图片：

curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8080/_api/image/ecb83ad8-ffda-4ca7-8385-e6fd45d64bc9.png"

实测回显：

200

⚠️ 注意：只有正文中以 _api/image/<文件名> 形式引用的图片才会被自动清理任务判定为「使用中」，其余会被周期清理（见《配置参数详解》篇 5.4 节）。

六、分页、过滤与排序约定

• 分页：无分页参数。GET /_api/resource/ 一次返回指定项目下全部泳道与卡片（含卡片完整内容），数据量大时注意响应体体积。
• 过滤：无服务端过滤参数；卡片名以 . 开头的文件、目录名以 . 开头的泳道会被后端自动忽略（隐藏文件语义）。
• 排序：卡片顺序由 /_api/sort/ 接口维护，不由查询参数控制。

七、常见问题

Q1：直接发中文 URL（未 percent-encode）会怎样？ 实测（2026-10-25，3.3.0）两类异常：

• POST 未编码中文路径返回 201，但落盘目录名是乱码（如「待办」变成 待办），页面里也出现乱码泳道；
• PATCH 未编码中文路径返回 404 Not Found，后端日志可见 ENOENT ... rename（源路径乱码找不到文件）。 正确做法：每个路径段都做 percent-encode。curl 中可用 --data-urlencode 处理请求体，但 URL 路径需自行编码，例如 bash 中：

python3 -c "from urllib.parse import quote; print(quote('待办'))"
# %E5%BE%85%E5%8A%9E

Q2：在中文名子项目下创建泳道返回 500？ 实测对「多段且含编码中文」的路径（如 /_api/resource/%E9%A1%B9%E7%9B%AE%A/%E5%BE%85%E5%8A%9E），后端抛 URIError: URI malformed（server.js 的 decodeURIComponent 处）并返回 500 Internal Server Error；纯 ASCII 多段路径（如 /_api/resource/projA/lane1）工作正常。属 3.3.0 的已知行为边界；界面操作子项目不受此影响。若必须用 API 操作中文子项目，可先用界面或文件系统建好汉化目录，再对单段编码路径操作。

Q3：PATCH 返回 204 但内容没变？ 检查请求体是否带 Content-Type: application/json 头。后端用 koa-bodyparser 解析 JSON，缺该头时 ctx.request.body 为空，content/newPath 都取不到，表现为「成功但不生效」。

Q4：API 有认证/Token 吗？ 3.3.0 没有。任何能访问端口的客户端都可读写全部数据，切勿直接暴露公网。

Q5：能用 API 批量迁移旧任务吗？ 可以。任务即 Markdown 文件，最简单的方式是直接往 TASKS_DIR/<泳道>/ 下写 .md 文件（文件名即卡片名），无需调 API；API 更适合与 CI/IM 机器人做轻量联动。

八、参考链接

• Tasks.md 后端路由源码（接口定义唯一权威）：https://github.com/BaldissaraMatheus/Tasks.md/blob/main/backend/server.js
• Tasks.md 官方 README：https://github.com/BaldissaraMatheus/Tasks.md/blob/main/README.md
• Koa 框架：https://koajs.com/