本地 API 服务器

Mindwtr 提供可选的本地 REST API 服务器，用于脚本和集成。在桌面端，它运行于应用二进制文件内部，并使用与应用相同的本地存储路径。仓库还包含一个 Bun 辅助程序，可用于开发和高级脚本编写。

桌面端开关

桌面端构建无需运行源代码即可启动本地 REST API：

打开设置 -> 高级。
启用本地 API 服务器。
保留默认端口 3456，或选择其他 localhost 端口。
从同一张设置卡片中复制生成的 bearer token。

应用仅绑定至 127.0.0.1，并要求每个请求都包含 Authorization: Bearer <token>。移动端二进制文件不公开本地 REST API 接口。

开发辅助程序

当你希望在桌面端应用之外运行 API，或令其指向明确指定的文件时，仍可使用仓库中的辅助程序。

快速开始

从桌面端应用启动：

text

Settings -> Advanced -> Enable local API server

默认 URL：

text

http://127.0.0.1:3456

从仓库根目录使用 Bun 启动：

bash

bun install
MINDWTR_API_TOKEN=replace-with-a-strong-token bun run mindwtr:api -- --port 4317 --host 127.0.0.1

选项

选项	默认值	说明
`--port <n>`	`4317`	服务器端口
`--host <host>`	`127.0.0.1`	绑定地址
`--data <path>`	平台默认值	覆盖 data.json 的位置
`--db <path>`	平台默认值	覆盖 mindwtr.db 的位置
`--dangerously-disable-auth`	关闭	完全不使用令牌运行——不安全，即便只监听回环地址对浏览器也不安全

环境变量

变量	说明
`MINDWTR_DATA`	覆盖 data.json 的位置（如果省略 `--data`）
`MINDWTR_DB_PATH`	覆盖 mindwtr.db 的位置（如果省略 `--db`）
`MINDWTR_API_TOKEN`	必需。辅助程序对每个请求都要求的 bearer token；未设置时将拒绝启动，除非传入 `--dangerously-disable-auth`
`MINDWTR_API_CORS_ORIGIN`	可选。允许调用该 API 的一个精确 http(s) 来源；未设置时不发送 CORS 响应头

默认情况下，API 会使用 Mindwtr 的平台路径解析 data.json 和 mindwtr.db（在 Linux 上优先使用 XDG 数据路径）。

认证

桌面端本地 API 请求始终需要设置 -> 高级中显示的 bearer token：

Authorization: Bearer <token>

Bun 辅助程序同样要求令牌：未设置 MINDWTR_API_TOKEN 时会立即退出，除非你显式传入 --dangerously-disable-auth（仅用于隔离环境下的兼容性测试）。

端点

方法	端点	说明
`GET`	`/health`	健康检查 → `{ ok: true }`
`GET`	`/tasks`	列出任务
`GET`	`/tasks?status=next`	按状态筛选
`GET`	`/tasks?query=@work`	搜索任务
`GET`	`/tasks?isFocusedToday=true`	桌面端：筛选加星任务，包括排队的未来开始任务
`GET`	`/tasks?all=1`	包含已完成/已归档任务
`GET`	`/tasks?deleted=1`	包含软删除任务
`POST`	`/tasks`	创建任务
`GET`	`/tasks/:id`	获取单个任务
`PATCH`	`/tasks/:id`	更新任务
`DELETE`	`/tasks/:id`	软删除任务
`POST`	`/tasks/:id/complete`	标记为已完成
`POST`	`/tasks/:id/archive`	标记为已归档
`POST`	`/tasks/:id/restore`	恢复软删除任务
`GET`	`/projects`	列出项目
`POST`	`/projects`	桌面端：创建项目
`GET`	`/projects/:id`	桌面端：获取单个项目
`PATCH`	`/projects/:id`	桌面端：更新项目
`DELETE`	`/projects/:id`	桌面端：软删除项目
`POST`	`/projects/:id/restore`	桌面端：恢复项目
`GET`	`/areas`	列出领域
`GET`	`/areas/:id`	桌面端：获取单个领域
`PATCH`	`/areas/:id`	桌面端：更新领域
`GET`	`/v1/areas`	领域端点的兼容别名
`GET`	`/sections`	辅助程序：列出分区，可加 `?projectId=`
`POST`	`/sections`	辅助程序：创建分区
`GET`	`/sections/:id`	辅助程序：获取单个分区
`PATCH`	`/sections/:id`	辅助程序：更新分区
`DELETE`	`/sections/:id`	辅助程序：删除分区
`GET`	`/search?query=...`	搜索任务和项目

如果完成一个有开始日期、无截止日期的固定周期任务需要跳过已错过的重复日期，桌面本地 API 会返回 409（recurrence_requires_app）。任务保持不变，请在应用中完成它。如果下一次重复仍在当前日期或未来，只有开始日期的任务仍受支持。

标注桌面端的行只存在于桌面应用的本地 API。标注辅助程序的行只存在于 Bun 辅助程序，它同时也在 /v1/ 前缀下响应这些请求（/v1/sections）。

桌面端本地 API 接受 isFocusedToday=true/1 和 isFocusedToday=false/0。true 或 1 返回加星任务，包括排队等待进入专注的未来开始任务；false 或 0 返回未标记的任务，包括没有该字段的旧记录。省略该参数时，API 不按此字段筛选。其他值会返回 400。

这里的 query 是纯文本匹配：该值会转为小写，并作为子串与任务的标题、描述、状态、标签、上下文、项目与领域 ID 以及支持备注进行比较。它不是操作符语言。status:、context:、tag:、due:<=7d、引号短语和 -取反 属于应用内的搜索框、CLI 的 --query 以及 MCP 服务器的任务列表；在这里发送时会按字面字符匹配，通常什么也返回不了。

响应结构

任务（部分字段）

json

{
  "id": "uuid",
  "title": "Task title",
  "status": "inbox",
  "projectId": "uuid",
  "dueDate": "2026-01-25T12:00:00.000Z",
  "tags": ["#work"],
  "contexts": ["@email"],
  "createdAt": "2026-01-25T10:00:00.000Z",
  "updatedAt": "2026-01-25T10:00:00.000Z",
  "deletedAt": null
}

项目（部分字段）

json

{
  "id": "uuid",
  "title": "Project name",
  "status": "active",
  "color": "#94a3b8",
  "createdAt": "2026-01-25T10:00:00.000Z",
  "updatedAt": "2026-01-25T10:00:00.000Z",
  "deletedAt": null
}

领域

json

{
  "id": "uuid",
  "name": "Area name",
  "color": "#94a3b8",
  "icon": "briefcase",
  "order": 0,
  "createdAt": "2026-01-25T10:00:00.000Z",
  "updatedAt": "2026-01-25T10:00:00.000Z"
}

创建任务的请求体

json

{
  "input": "Call Alice",
  "title": "Alternative title",
  "props": {
    "status": "next",
    "contexts": ["@phone"],
    "tags": ["#errands"]
  }
}

桌面端会在存在 title 时使用它，否则使用 input，并应用明确指定的 props。Bun 辅助程序还会对 input 运行 parseQuickAdd。

桌面端项目写入

桌面应用内置 API 支持创建、获取、更新、软删除和恢复项目。创建项目时必须提供 title；areaId、color、status、isSequential 和 order 为可选字段。更新时可使用相同的可编辑字段。创建、获取、更新和恢复都以 { "project": { ... } } 返回已保存的项目；删除返回 { "ok": true }。

创建选项放在 props 中，例如 { "title": "Plan the move", "props": { "isSequential": true } }；PATCH 字段直接放在请求体中。sequentialScope 支持 project 或 section，项目 status 支持 active、someday、waiting 或 archived。将 areaId 设为 null 可移除领域。项目归档和重新激活遵循应用中对子任务和分区的处理规则。对于 PATCH，项目不存在时返回 404，已删除或已永久删除时返回 409。

GET /projects/:id 也会返回仍存储的软删除项目，便于脚本在恢复前检查。DELETE /projects/:id 会软删除项目及其活动分区，并解除活动任务的项目关联，而不会删除任务或更改任务状态。POST /projects/:id/restore 会恢复项目以及由同一次旧版级联删除的子项，但不会重新关联当前删除操作已解除关联的任务。重复删除或恢复是安全的，不会改变当前状态。对已永久删除项目执行生命周期变更会返回 409。

创建顺序项目:

bash

curl -s -X POST "http://127.0.0.1:3456/projects" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Plan the move","props":{"isSequential":true}}' | jq .

将现有项目改为并行:

bash

curl -s -X PATCH "http://127.0.0.1:3456/projects/$PROJECT_ID" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"isSequential":false}' | jq .

在桌面端编辑领域

GET /areas/:id 和 PATCH /areas/:id 返回 { "area": { ... } }。未知或已删除的领域均返回 404。这些端点属于桌面应用内置 API，不属于 Bun 辅助服务。

PATCH 接受仅包含 name、color、icon 和 order 的非空对象。name 必须是非空白字符串，首尾空白会被移除。color 和 icon 接受字符串，也可设为 null 以清除字段。order 必须是有限数值，允许小数和负数。未知字段、无效类型、空白名称及空对象均返回 400。

移除首尾空白并忽略大小写后，若名称与另一个未删除领域相同，则返回 409，不作任何更改。API 不会隐式合并领域。重命名和颜色更改会保留应用对关联项目元数据的处理行为，并一并保存。清除领域颜色也会将关联项目重置为默认颜色（#94a3b8）。设置 order 只更新此领域的数值排序位置，并非批量重排操作。不包含领域创建和删除。

bash

curl -s -X PATCH "http://127.0.0.1:3456/areas/$AREA_ID" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Work","color":"#94a3b8","order":2}' | jq .

桌面端任务分类

使用带有 status 的 PATCH /tasks/:id，可将活动任务在 inbox、next、waiting、someday 和 reference 之间移动。完成、归档和恢复仍使用对应的 /complete、/archive 和 /restore 操作。PATCH 不接受终结状态。

PATCH 无法重新打开已完成或已归档的任务（返回 409）；请先在应用中重新打开。已删除任务需先通过 /restore 恢复，再进行分类。已永久删除的任务无法分类。

将已归档项目中的任务改为 inbox、next、waiting 或 someday 会返回 409。请先通过 PATCH /projects/:id 和 {"status":"active"} 重新激活项目，或在同一次任务 PATCH 中将任务移出该项目。

将收集箱任务移至下一步行动:

bash

curl -s -X PATCH "http://127.0.0.1:3456/tasks/$TASK_ID" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"status":"next"}' | jq .

示例

列出下一步行动：

bash

curl -s 'http://127.0.0.1:3456/tasks?status=next' \
  -H 'Authorization: Bearer <token>' | jq .

使用明确指定的 props 创建任务：

bash

curl -s -X POST 'http://127.0.0.1:3456/tasks' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Call Alice","props":{"status":"next","contexts":["@phone"],"tags":["#errands"]}}' | jq .

完成任务：

bash

curl -s -X POST "http://127.0.0.1:3456/tasks/$TASK_ID/complete" \
  -H 'Authorization: Bearer <token>' | jq .

CLI 工具

还可以使用一个更简单的命令行界面：

bash

# Add a task
bun mindwtr:cli -- add "Call mom @phone #family"

# List active tasks
bun mindwtr:cli -- list

# List with filters
bun mindwtr:cli -- list --status next --query "due:<=7d"

# Read or update a task
bun mindwtr:cli -- get <taskId>
bun mindwtr:cli -- update <taskId> '{"status":"next"}'

# Complete a task
bun mindwtr:cli -- complete <taskId>

# Archive, delete, or restore
bun mindwtr:cli -- archive <taskId>
bun mindwtr:cli -- delete <taskId>
bun mindwtr:cli -- restore <taskId>

# Search
bun mindwtr:cli -- search "@work"

# List projects
bun mindwtr:cli -- projects

CLI 参考

命令	示例	说明
`add`	`mindwtr:cli -- add "Call mom @phone"`	使用快速添加解析
`list`	`mindwtr:cli -- list --status next`	支持 `--all`、`--deleted`、`--query`
`get`	`mindwtr:cli -- get <taskId>`	输出完整任务 JSON
`update`	`mindwtr:cli -- update <taskId> '{"status":"next"}'`	应用 JSON patch
`search`	`mindwtr:cli -- search "@work due:<=7d"`	搜索任务/项目
`complete`	`mindwtr:cli -- complete <taskId>`	将任务标记为已完成
`archive`	`mindwtr:cli -- archive <taskId>`	将任务标记为已归档
`delete`	`mindwtr:cli -- delete <taskId>`	软删除任务
`restore`	`mindwtr:cli -- restore <taskId>`	恢复已删除任务
`projects`	`mindwtr:cli -- projects`	列出现存项目

安全说明

服务器适合在 127.0.0.1（localhost）上运行。除非你了解相关风险，否则不要将其公开。
桌面端 API 访问需要“设置”中生成的 bearer token。请妥善保管该令牌。
如果需要远程访问 Bun 辅助程序，请设置 MINDWTR_API_TOKEN，并将服务器置于经过认证的反向代理之后。

本地 API 服务器 ​

桌面端开关 ​

开发辅助程序 ​

快速开始 ​

选项 ​

环境变量 ​

认证 ​

端点 ​

响应结构 ​

创建任务的请求体 ​

桌面端项目写入 ​

在桌面端编辑领域 ​

桌面端任务分类 ​

示例 ​

CLI 工具 ​

CLI 参考 ​

安全说明 ​

另请参阅 ​

本地 API 服务器

桌面端开关

开发辅助程序

快速开始

选项

环境变量

认证

端点

响应结构

创建任务的请求体

桌面端项目写入

在桌面端编辑领域

桌面端任务分类

示例

CLI 工具

CLI 参考

安全说明

另请参阅