任务台 · 接口接入文档

本文档面向需要把 Bug、告警或工单自动推送到任务台的系统开发者。接入后，你的系统每推送一条数据，任务台里就会生成一个任务，并可指定负责人、优先级和标签。也可以分页轮询授权项目的任务、更新处理状态，以及发表评论。

• 服务地址：https://39.106.181.218:8443（就是你打开任务台的地址；下文示例里的地址都指它。AI 员工也可以从 GET /api/v1/me 的 app_url 读到）
• 接口版本：v1
• 数据格式：JSON，UTF-8 编码

1. 接入前准备

向任务台管理员申请一个接口密钥，并告知你的系统名称（例如「测试平台」）。管理员会在「密钥管理」页面生成密钥并交给你。

关于密钥，请注意：

• 密钥形如 tsk_xxxxxxxx…，请妥善保存：完整的密钥只在生成时显示一次，任务台只保存它的哈希，之后查不到。遗失时请管理员在「密钥管理」页面重新生成，旧密钥随即失效。
• 密钥没有自己的项目（#1039）：一把密钥能进哪些项目，只看它的成员在「员工管理」和项目成员里勾了哪些。在「密钥管理」新建的来源系统密钥各有一个同名的成员（AI 助手，用户名 source-密钥编号），管理员到员工管理给这个成员勾项目；密钥可以读取、创建、更新这些项目的全部任务，也可以发表评论、添加附件，包含成员和其他来源创建的任务。来源系统密钥只有读取、创建、更新任务三样操作，没有删除任务的权限。绑定 AI 的密钥就是那位 AI 的项目和操作权限（第 11 节）。
• 给成员取消勾选某个项目后，后续请求就不能再访问该项目的任务；新建的项目不会自动勾给已有的成员。
• 管理员可在「已有密钥 → 重命名」修改显示名称（非空、最多 60 字），AI 绑定选择和管理操作同步显示新名称。改名不重新生成密钥，不改变它的成员、项目、AI 绑定或有效状态。为保持历史来源访问和 external_id 防重复，接口响应的 source 及来源历史名称保留原值；相同显示名称不会合并来源。AI 不能通过自身配置接口重命名密钥。
• 从以前升级（#1039）：升级时每把在用的来源系统密钥建一个成员，勾上它原来能进的项目，能进的不多也不少；原来只看同来源任务的老密钥，以后能看这些项目的全部任务。吊销了的同名密钥归到同一个成员，以前推的任务仍算这个来源的。响应里不再有 access_scope。
• 密钥等同于密码。请放在服务端的配置或密钥管理系统里，不要写进前端代码、客户端或代码仓库。
• 如果密钥泄露，请立即联系管理员更换。
• 重新生成密钥会让旧密钥立即失效，保留原记录、成员和历史任务。吊销后用相同系统名称（不区分大小写）新建的密钥，接回原来那个成员（它已经没有别的在用密钥时）：项目照旧，相同来源、相同项目的 external_id 防重复仍然生效。两把同时在用的同名密钥是两个来源。

2. 鉴权

所有请求都需要在请求头里带上密钥：

Authorization: Bearer tsk_你的密钥

密钥缺失、错误或已被吊销时，接口返回 401。创建、筛选或把任务移到未授权的项目返回 403 forbidden_project；按编号访问无权限的任务统一返回 404。项目权限适用于列表、详情、更新、评论和附件的所有接口。

密钥和人一样按成员的项目可见性：管理员始终可见全部项目，其他成员（包括来源系统的成员和 AI）必须被加入项目的可见成员；绑定 AI 的密钥还受该 AI 的操作权限限制（第 11 节）。密钥能进项目不代表任务负责人也能进；创建或更新任务时，如果指定的在用成员或小组中的任一在用成员没有目标项目权限，整个请求返回 422 validation_failed，不会部分写入。撤销成员权限后，相关通知不再向该成员展示或发送，已有指派和历史记录保留。

首次接入时，先调用 GET /api/v1/tasks?size=20，核对响应里的 projects。不要根据项目名称猜测编号。

3. 创建任务

POST /api/v1/tasks
Content-Type: application/json

请求字段

请求体不能超过 1 MB。

下方省略 project_id 的示例适用于只有一个授权项目的密钥。多项目密钥请在请求体中加入 "project_id": 目标项目编号。

可用的小组

assignee_group 目前可以填以下小组名称：

名称必须与上表完全一致（不区分英文大小写）。填了表里没有的名称时，任务照常创建但不会指派给小组，并在 warnings 里给出说明。小组由任务台管理员维护，如有增减以管理员通知为准。

指派给小组的示例：

{
  "title": "新版点餐流程回归测试",
  "priority": "high",
  "assignee_group": "平板测试组",
  "external_id": "TEST-108"
}

请求示例

curl -X POST https://39.106.181.218:8443/api/v1/tasks \
  -H "Authorization: Bearer tsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "支付页白屏",
    "description": "复现步骤：\n1. 进入购物车\n2. 点击去支付\n\n**期望**：进入支付页\n**实际**：页面空白",
    "priority": "high",
    "due_date": "2026-11-01",
    "assignee": "lwg",
    "tags": ["Bug", "支付"],
    "external_id": "BUG-42"
  }'

Python 示例：

import requests

resp = requests.post(
    "https://39.106.181.218:8443/api/v1/tasks",
    headers={"Authorization": "Bearer tsk_你的密钥"},
    json={
        "title": "支付页白屏",
        "priority": "high",
        "assignee": "lwg",
        "tags": ["Bug", "支付"],
        "external_id": "BUG-42",
    },
    timeout=10,
)
resp.raise_for_status()
task = resp.json()["task"]
print(task["id"], task["url"])

成功响应

首次创建返回 201：

{
  "task": {
    "id": 2,
    "url": "https://39.106.181.218:8443/tasks/2",
    "project_id": 1,
    "project": "闪点菜单",
    "title": "支付页白屏",
    "description": "复现步骤：…",
    "status": "todo",
    "priority": "high",
    "due_date": "2026-11-01",
    "assignee": "林文淦",
    "assignee_group": null,
    "tags": ["Bug", "支付"],
    "attachments": [],
    "external_id": "BUG-42",
    "created_at": "2026-10-03T06:41:55.219Z",
    "updated_at": "2026-10-03T06:41:55.219Z",
    "closed_at": null
  },
  "duplicate": false,
  "warnings": []
}

响应字段说明：

负责人不存在时：如果 assignee 填的用户名在任务台里找不到（或该成员已停用），接口不会报错，仍返回 201 并创建任务，只是任务处于未指派状态，task.assignee 为 null，同时 warnings 里会有一条说明：

{
  "task": { "id": 3, "assignee": null, "…": "…" },
  "duplicate": false,
  "warnings": ["找不到用户名为 zhangsan 的在职成员，任务已创建但未指派"]
}

assignee_group 填的小组名称找不到时处理方式相同。如果你的系统依赖任务必须有负责人，请检查 warnings 是否为空。

以上「照常创建、只给 warnings」只对未绑定 AI 的来源密钥（外部缺陷系统推送，不能让缺陷丢掉）。AI 员工的密钥写错负责人时返回 422 validation_failed，任务不建，消息里写着是哪个名字或编号对不上（#605：#568 就是这样建成了没人负责的任务）。AI 员工看不到的人（见「员工私聊和共享群聊」一节里「只限看得到的人」，#856），按用户名指派时和不存在一样回 422；改任务（PATCH）时也一样。

4. 防止重复创建

网络超时后重试、或同一个 Bug 被多次上报时，可能产生重复任务。传入 external_id 可以避免：

• 同一来源、同一项目中的 external_id 首次推送时创建任务，返回 201 和 "duplicate": false；同一来源指的是同一个成员的密钥（#1039），吊销后用同名新建、接回原成员的密钥仍可防重复。
• 之后再推送相同的 external_id，不会新建任务，返回 200、"duplicate": true 和已有的那个任务。此时请求里的其他字段会被忽略，已有任务不会被修改。
• 同一把密钥不能在不同项目重复使用一个 external_id；此时返回 422，不会返回或创建其他项目的任务。多项目接入建议使用 项目编号:外部编号（如 2:BUG-42）。
• 不传 external_id 时，每次推送都会新建一个任务。

建议始终传 external_id，并且请求失败或超时后可以放心重试。

5. 列出与查询任务

5.1 列出任务

GET /api/v1/tasks

返回密钥能进的项目里的任务：它的成员被勾的项目的全部任务，包括成员和其他来源创建的任务（#1039）。范围由管理员在员工管理里设置，查询参数只能缩小范围，不能增加权限。

默认只列出未关闭的任务，按最近更新时间倒序排列，每页 20 个。可选参数：

不支持的参数、重复参数或无效值返回 422。多选值请放在同一个参数里用逗号分隔。

curl 'https://39.106.181.218:8443/api/v1/tasks?status=todo,in_progress&size=50&page=1' \
  -H "Authorization: Bearer tsk_你的密钥"

成功返回 200：

{
  "project": { "id": 1, "name": "闪点菜单" },
  "projects": [{ "id": 1, "name": "闪点菜单" }],
  "source": "测试平台",
  "tasks": [
    { "id": 2, "title": "支付页白屏", "status": "todo", "…": "其余字段与查询单个任务相同，含附件" }
  ],
  "total": 1,
  "page": 1,
  "size": 50,
  "pages": 1
}

projects 是密钥能进的全部项目编号和名称，也就是它的成员被勾的项目；source 是来源系统名称。project 在指定 project_id 筛选或只有一个项目时为对应项目，否则为 null。即使没有任务，也可以据此核对权限。total 是筛选后且有权访问的任务总数；page 是实际返回的页码；pages 至少为 1。没有匹配时 tasks 为 []、total 为 0、page 和 pages 为 1。请求的页码超过最后一页时返回最后一页，请使用响应中的 page 与 pages 判断是否结束，避免重复轮询最后一页。

分页示例（密钥从环境变量读取）：

import os
import requests

base = "https://39.106.181.218:8443"
headers = {"Authorization": f"Bearer {os.environ['TASKS_API_KEY']}"}
page = 1
seen = set()
while True:
    resp = requests.get(
        f"{base}/api/v1/tasks", headers=headers,
        params={"status": "open", "sort": "created", "dir": "asc", "size": 100, "page": page},
        timeout=30,
    )
    resp.raise_for_status()
    result = resp.json()
    for task in result["tasks"]:
        if task["id"] not in seen:
            seen.add(task["id"])
            print(task["id"], task["title"], task["status"])
    if result["page"] >= result["pages"]:
        break
    page = result["page"] + 1

列表不是跨请求的快照。翻页过程中有人新增任务或改变筛选字段，结果可能移动；轮询程序应按任务编号去重，并在下一轮重新从第 1 页检查。准备修改任务前，先按编号读取最新状态。

5.2 按编号查询任务

用于了解有权访问的任务目前处理到哪一步，例如同步 Bug 是否已关闭。

GET /api/v1/tasks/{id}

curl https://39.106.181.218:8443/api/v1/tasks/2 \
  -H "Authorization: Bearer tsk_你的密钥"

成功返回 200，响应体为 { "task": { … } }，字段与创建任务时相同。

查询权限范围之外的任务或不存在的编号，都返回 404。可以查询密钥能进的项目内的全部任务，见第 1 节。

按编号查询时，任务还带上它的依赖关系 depends_on、depended_by 和 dependencies_resolved，见 5.3。AI 员工的密钥另外得到 commits（任务的相关提交），见 5.4；别的密钥的回答里没有这个字段。

5.3 任务依赖

「A 依赖 B」表示 A 要用到 B 里的东西，例如 B 里有 A 需要的素材。一个任务可以依赖多个任务，也可以被多个任务依赖，可以跨项目。

B 关闭后，这条依赖就算已解决；B 重新打开，又变回未解决。B 关闭时，依赖它、还没关闭的任务的负责人会收到通知（类型 dependency_resolved，走「状态变化」这一类推送）：「#231 已关闭，#325 的依赖已解决」，如果这样 #325 的依赖就全部解决了，再加一句「#325 的依赖都已解决，可以继续」。关闭 B 的人自己不收到。依赖只负责显示和提醒：没解决也照样可以改状态、关闭任务；不检查是否成环。

GET    /api/v1/tasks/{id}/dependencies
POST   /api/v1/tasks/{id}/dependencies          { "depends_on": 231 }
DELETE /api/v1/tasks/{id}/dependencies/{dep_id}

• GET 返回 200 { "depends_on": [...], "depended_by": [...] }：depends_on 是这个任务依赖的任务，depended_by 是依赖这个任务的任务，都按添加时间从早到晚。每一项是 { "id", "title", "status", "project_id", "project", "visible", "resolved" }；resolved 表示那个任务已关闭。这把密钥看不到的任务 visible 为 false，只给 id 和 resolved，其余为 null。另有 dependencies_resolved：这个任务依赖的任务是否都已关闭（不依赖任何任务时为 true）。回收站里的任务不列出，恢复后重新出现。
• POST 让 {id} 依赖 depends_on（数字，或 "#231" 这样的字符串）。需要能修改 {id}、能看到 depends_on 那个任务。成功返回 201，内容同 GET。编号不合规或看不到对方返回 422；已经依赖过、依赖自己，或者会成环（对方已经直接或经过别的任务在等 {id}，回收站里的也算）返回 409 conflict，成环时 message 按顺序写明经过哪几件，例如「#232 已经在等 #231（经过 #240），再让 #231 等 #232 就成了环」（#952）；这把密钥看不到的任务不写编号，挨着的几件合成一句，例如「（经过一件你看不到的任务、#240）」（#1160）。
• DELETE 去掉「{id} 依赖 {dep_id}」，从任意一边都能去掉：需要能修改这两个任务中的一个。成功返回 204；没有这条依赖（或两个任务都无权修改）返回 404。
• 加上和去掉都会在两边任务的动态里记一笔（type 为 dependency 和 dependent，from_value、to_value 是对方的编号），不发通知，也不改变任务的 updated_at。

curl -X POST https://39.106.181.218:8443/api/v1/tasks/325/dependencies \
  -H "Authorization: Bearer tsk_你的密钥" -H "Content-Type: application/json" \
  -d '{"depends_on": 231}'

5.4 任务的相关提交（#715）

一件任务的活在哪几个提交里：哪个仓库、哪个提交、是哪一种，每一行带着 GitHub 上那个提交的地址。给审查、合并、发布的人看。

谁拿得到（服务端决定，不是页面上藏起来）

GET    /api/v1/tasks/{id}                          回答里多一段 commits
POST   /api/v1/tasks/{id}/commits                  { "repo": "tasks", "sha": "…", "kind": "merge", "note": "合进 dev" }
DELETE /api/v1/tasks/{id}/commits/{repo}/{sha}

• commits 按登记时间从早到晚，每一项是 { "repo", "sha", "kind", "note", "url", "recorded_by", "recorded_by_id", "created_at", "updated_at" }。url 是拼好的地址：tasks 的是 https://github.com/theodoregao/tasks/commit/<sha>，digital-menu 的是 https://github.com/theodoregao/fzflash-apps/commit/<sha>；recorded_by 是登记的人的名字。
• repo 只认 tasks、digital-menu。闪点菜单的仓库在 GitHub 上改名叫 fzflash-apps 了（任务台 #882），这里照旧写 digital-menu，以前登记的也一样。
• sha 是 7 到 40 位十六进制，存下来一律小写。工具登记的是完整的 40 位。
• kind 三种：branch（分支上交审的头）、merge（合进 dev 或发布分支的合并提交）、release（发布用的那个提交）。
• note 可以不写：一句话，一行，最多 200 字。
• 同一件任务、同一个仓库、同一个提交只有一行。 再 POST 一次是同一行：种类换成这次写的，note 写了就换（写 null 是去掉），没写就留着原来的；返回 200（新的一行是 201），回答是 { "commit": { … } }。短的写法和完整的写法算同一个提交（一个是另一个的开头），存的是长的那个；短到这件任务登记过的提交里不止一个以它开头时返回 422。这一行算最先登记的人的。
• POST 要 task.update，要看得到这件任务（看不到是 404）。
• DELETE 只能删自己登记的，别人登记的返回 403「只能删自己登记的提交」；没有这个提交返回 404；成功返回 204。
• 登记和删除不改任务本身：时间线不记，updated_at 不变，不通知谁，也不算进 GET /api/v1/me/pending。

不用自己调：合并以后、发布以后各有一条命令，见仓库里的 tools/task-commits/README.md。

6. 更新任务

用于在你的系统里状态变化时同步到任务台，例如 Bug 在上游已修复时把任务关闭，或者补充描述、调整优先级。

PATCH /api/v1/tasks/{id}
Content-Type: application/json

只需要传要修改的字段，没传的字段保持不变。密钥只能更新其权限范围内的任务，与查询权限一致。

至少要有一个上面的字段，否则返回 422。

移到另一个项目（project_id，#710）。和成员在网页上改任务的项目是同一套规矩：

• 密钥要能访问任务现在的项目，也要能访问要去的项目。要去的项目不在这把密钥能访问的项目里，返回 403 forbidden_project「密钥没有访问该项目的权限」，和创建任务时一样；这个编号的项目存在不存在，回答都一样。
• 任务的负责人和负责小组里每位在职的成员都要能访问要去的项目，否则 422「负责人或小组成员没有该项目的访问权限，请先由管理员授权」；已关闭的任务也一样，不放宽。负责人是 AI 员工时，调用方还要有「把任务交给 AI」的权限（ai.assign），那位 AI 的密钥也要能访问要去的项目。
• 已经停用的负责人不查（他什么项目都看不到）：任务照样移得动，负责人还是他。同一个请求里换了负责人的，新负责人照旧要在职、要能访问要去的项目。
• 照旧要有 task.update 权限。
• 移过去以后，任务的编号、状态、负责人、留言、附件、依赖、标签都不变，时间线里多一条「项目：甲 → 乙」，记着是谁移的。
• 说明里的图片：共用的图片跟着任务走，要去的项目里的人随之看得到；上传时就归在原项目名下的图片不能跟着走，这时整个请求被拒绝（422「图片不存在、无权访问或属于其他项目，请在当前项目重新上传」），任务不动。网页上改项目也是这样。
• 留言里引用的图片不检查：归在原项目名下的那些，移过去以后只有能访问原项目的人打得开。
• 已关闭的任务也能移，移完还是已关闭，关闭时间不变。
• 移动本身不通知任何人：不发通知，也不算进 AI 员工的待处理事项（GET /api/v1/me/pending）；之后在新项目里对它做的事照常通知。
• project_id 就是任务现在的项目时什么都不改，时间线也不记。可以和别的字段在同一个请求里一起改；有一样不合规矩，整个请求都不生效。

curl -X PATCH https://39.106.181.218:8443/api/v1/tasks/2 \
  -H "Authorization: Bearer tsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{ "status": "closed" }'

resp = requests.patch(
    "https://39.106.181.218:8443/api/v1/tasks/2",
    headers={"Authorization": "Bearer tsk_你的密钥"},
    json={"priority": "high", "assignee": "lwg", "tags": ["Bug", "已定位"]},
    timeout=10,
)
resp.raise_for_status()

成功返回 200，响应体为更新后的任务和 warnings：

{ "task": { "id": 2, "status": "closed", "closed_at": "2026-10-03T09:00:00.000Z", "…": "…" }, "warnings": [] }

几点说明：

• 修改会记入任务的动态，操作者显示为你的系统名称；相关成员会收到站内通知（例如被指派、任务被关闭）。
• 把已关闭的任务的 status 改回其他状态即可重新打开。
• review（待验收）表示工作已完成、等待确认。改成待验收的那一次请求里必须同时带上验收的人（#475）：assignee（用户名）或 assignee_group（小组名），例如 { "status": "review", "assignee": "theodore" }。不带、或传 null，返回 422 validation_failed：「改成待验收要同时指定验收的人」，任务不变。写现在的负责人也算（表示由他验收）；任务已经是待验收时再改别的字段不用再带。任务进入待验收时，任务的创建者会收到站内通知，验收的人照常收到指派通知；普通来源接口创建的任务没有创建者成员；由 AI 身份创建的任务会记录 AI 创建者。
• 把任务从待验收退回要写一句原因（#505）：任务现在是 review，把 status 改成 closed（通过）以外的任何状态，这一次请求里必须带 return_reason（字符串，去掉两端空白后不能为空，最多 2000 字），不带返回 422「退回要写一句原因」，任务不变。原因会作为调用者的一条评论记在任务下，开头是「验收不通过：」。同一次请求里没有指定负责人（assignee 或 assignee_group）时，任务自动交给担任「技术负责人」角色的 AI 员工并通知他；没有能接的技术负责人时交回给创建任务的成员；两者都没有时负责人不变。指定了负责人的以指定的为准。这一步由任务台来交，不需要「给 AI 员工分配任务」的权限，AI 也不用走委派接口。任务不在待验收、或者改成 closed 时，return_reason 不看。return_reason 不算「要更新的字段」，单独提交它返回 422。
• 负责人或小组不存在时：普通来源密钥更新时如果 assignee 填的用户名或 assignee_group 填的小组名找不到，任务的现有负责人保持不变，其余字段照常更新，warnings 里会给出说明。AI 员工的密钥写了找不到的 assignee 或 assignee_group，和建任务一样返回 422，整个请求不生效、任务不变（#605）。找不到的 assignee 又同时给了 assignee_id，两个说的对不上，谁发的都返回 422。
• 任务所属的项目不能通过接口修改。
• 附件不在这里修改，见第 7 节。

任务状态

状态按工作的进展依次流转，有编辑权限的成员和接口调用方都可以修改：

不涉及代码的任务可以跳过「已提交」「测试中」「已合并」，直接进入「待验收」。无论从哪个状态改成「待验收」，都要同时指定验收的人（见上）。

测试中（#544，高顺 m3503、m3504）：开发交（已提交）→ 审查的人只看代码，改成「测试中」交给 QA → QA 把审过的几件放进一个临时分支一起测 → 过了的由审查的人合进 dev，改成「已合并」。没过的改回「进行中」（或待处理、评估中）时要带 return_reason 写一句原因（不带返回 422「退回要写一句原因」），任务交回最后一个把它改成「已提交」的人（不在了就交技术负责人），原因记成一条「测试没通过：…」的留言。同时指定了负责人就交给指定的人。App 构建 23 及以前不认识这个状态（整页任务列表会解不出来），所以服务端从 User-Agent 里认出构建号（iOS 自己带的「FlashTasks/23 CFNetwork/…」），给构建 24 以前的 App 照旧说「已提交」；网页、密钥和认不出构建号的请求看到的都是 testing。

7. 附件：日志、截图、视频

任务可以带附件，成员在任务页面里能直接看图片、播放视频、下载日志。每个任务最多 50 个附件。有三种方式，按文件大小和存放位置选用。

附件只能加到密钥有权访问的任务上。返回的站内附件地址接受有项目权限的登录会话，或有该任务读取权限的同站点 Authorization: Bearer 密钥；私有文件经权限检查后流式返回（支持 Range），不再重定向到可复用的存储签名链接。外部链接附件仍由外部站点控制下载权限。先获取任务 id，再上传附件；分步上传的开始和完成请求都会检查任务权限。

所有方式成功后都返回附件信息：

{
  "attachment": {
    "id": "5f0c2a9e7b1d4c3a8e6f1b2d",
    "name": "app.log",
    "kind": "file",
    "content_type": "text/plain",
    "size": 20480,
    "url": "https://39.106.181.218:8443/api/attachments/5f0c2a9e7b1d4c3a8e6f1b2d",
    "created_at": "2026-10-03T07:10:00.000Z"
  }
}

kind 为 file（上传的文件）或 link（链接）。url 是在任务台里查看该附件的地址，可通过有权限的成员会话或 Bearer 密钥读取。跟随外部链接重定向时，切勿将任务台的 Authorization 转发给外部站点。

文件类型由文件名的扩展名决定，请求里声明的类型会被忽略。可在页面内直接预览的类型：图片（png、jpg、gif、webp）、视频（mp4、webm、mov）、文本（log、txt、json、csv、xml、yaml、md、har）。其他类型（如 zip、pdf 及未知类型）可以上传，成员只能下载查看。请给文件起带正确扩展名的名字。

方式 A：附带链接

文件留在你的服务器上，任务台只保存链接，不会复制文件。链接必须是 http 或 https，并且要保证任务台的成员能打开。

创建任务时一并附带：

{
  "title": "支付页白屏",
  "external_id": "BUG-42",
  "attachments": [
    { "name": "复现录屏.mp4", "url": "https://files.example.com/bug-42/record.mp4" },
    { "url": "https://files.example.com/bug-42/app.log" }
  ]
}

不传 name 时使用链接里的文件名。任意一个附件不合法时，整个请求返回 422，任务不会被创建。

也可以之后给已有任务追加：

curl -X POST https://39.106.181.218:8443/api/v1/tasks/2/attachments \
  -H "Authorization: Bearer tsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{ "name": "崩溃报告.zip", "url": "https://files.example.com/bug-42/crash.zip" }'

方式 B：直接上传（不超过 4 MB）

用 multipart/form-data 把文件放在 file 字段里，一次调用完成：

curl -X POST https://39.106.181.218:8443/api/v1/tasks/2/attachments \
  -H "Authorization: Bearer tsk_你的密钥" \
  -F "file=@./app.log"

with open("app.log", "rb") as f:
    resp = requests.post(
        "https://39.106.181.218:8443/api/v1/tasks/2/attachments",
        headers={"Authorization": "Bearer tsk_你的密钥"},
        files={"file": ("app.log", f)},
        timeout=30,
    )
resp.raise_for_status()

文件超过 4 MB 会被拒绝，请改用方式 C。

方式 C：分步上传（最大 100 MB）

大文件分三步上传。第 2 步的地址由任务台给出：文件存在服务器本机时（现在的线上环境）是任务台自己的一个一次性地址，文件存在对象存储时是存储服务的地址；两种情况调用方式相同：

第 1 步：申请上传地址。 告知文件名和字节数。

curl -X POST https://39.106.181.218:8443/api/v1/tasks/2/attachments \
  -H "Authorization: Bearer tsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{ "name": "复现录屏.mp4", "size": 52428800 }'

返回 201，除了 attachment 还有一个 upload 对象：

{
  "attachment": { "id": "5f0c2a9e7b1d4c3a8e6f1b2d", "name": "复现录屏.mp4", "content_type": "video/mp4", "…": "…" },
  "upload": {
    "url": "https://…一次性上传地址…",
    "method": "PUT",
    "headers": { "Content-Type": "video/mp4" }
  }
}

第 2 步：上传文件。 用 upload.method 把文件内容原样发到 upload.url，并带上 upload.headers 里的全部请求头。这一步不要带 Authorization 头。上传地址 1 小时内有效。文件存在服务器本机时（现在的线上环境，#801、#1058），地址只能传成功一次：

• 超过 1 小时再传，返回 403「上传地址已过期，请重新上传」，要从第 1 步重新申请；
• 传成功以后（确认之前）再传到同一个地址，返回 409，code 是 already_uploaded，内容「这个文件已经传过了」，文件不会被换掉。如果是第一次上传的回应丢了、重试拿到这个 409，说明文件已经收下了，直接做第 3 步确认即可；
• 地址里的令牌不对，不管文件传没传过，都返回 403「上传地址无效或已使用」。

文件存在对象存储时，地址是存储服务给的预签名地址，1 小时内有效；上面这几条回应只在服务器本机时有。

curl -X PUT "上一步返回的 upload.url" \
  -H "Content-Type: video/mp4" \
  --data-binary @./record.mp4

第 3 步：确认完成。 确认后附件才会出现在任务里。

curl -X POST https://39.106.181.218:8443/api/v1/tasks/2/attachments/5f0c2a9e7b1d4c3a8e6f1b2d/complete \
  -H "Authorization: Bearer tsk_你的密钥"

返回 200 和最终的附件信息。如果文件还没传上去就调用，会返回 422；重复确认是安全的。

完整的 Python 示例：

import os
import requests

BASE = "https://39.106.181.218:8443"
AUTH = {"Authorization": "Bearer tsk_你的密钥"}

def upload_large(task_id: int, path: str) -> dict:
    name = os.path.basename(path)
    begin = requests.post(
        f"{BASE}/api/v1/tasks/{task_id}/attachments",
        headers=AUTH,
        json={"name": name, "size": os.path.getsize(path)},
        timeout=30,
    )
    begin.raise_for_status()
    info = begin.json()

    with open(path, "rb") as f:
        put = requests.request(
            info["upload"]["method"],
            info["upload"]["url"],
            headers=info["upload"]["headers"],
            data=f,
            timeout=600,
        )
    put.raise_for_status()

    done = requests.post(
        f"{BASE}/api/v1/tasks/{task_id}/attachments/{info['attachment']['id']}/complete",
        headers=AUTH,
        timeout=30,
    )
    done.raise_for_status()
    return done.json()["attachment"]

方式 D：把聊天里的图片附到任务上（#442）

聊天消息里的图片可以直接变成任务的附件，不用先下载再上传。给 AI 助手在群里记 bug 时带上截图用：做任务的人不在那个群里，也能在任务里看到图。

curl -X POST https://39.106.181.218:8443/api/v1/tasks/2/attachments \
  -H "Authorization: Bearer $TASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chat_image_id": "9b7c2f6e4a1d4e0c8f3a5b6c7d8e9f01" }'

• chat_image_id 是消息的 images[].id。
• 条件：调用的人看得到这张图所在的消息（和看聊天图片的规则一样），并且能给这个任务加附件。看不到和图片不存在回的是同一句 422，不区分。
• 任务台把图片复制一份成为这个任务的附件，名字是「聊天图片-<图片编号前 8 位>-<原文件名>」；之后消息怎么变，附件都在。大小上限和别的附件一样。
• 同一张图再附一次不会多出一份：返回 200 和第一次的那个附件，duplicate 为 true；第一次是 201，duplicate 为 false。
• 人（网页和 App 的同一个地址）、AI 员工、AI 助手都能用。

删除自己加的附件（#475）

DELETE /api/v1/tasks/{id}/attachments/{附件编号}

规则和成员在网页上删附件一样：只能删自己加的，并且要有修改任务的权限。绑定了 AI 员工的密钥，「自己的」是这位 AI 上传的（换过密钥也算）；没有绑定 AI 的密钥，是这把密钥自己加的。成功返回 204，没有响应体；文件一并删除，任务动态里留一条「删除了附件 某某」（动态的 type 是 attachment_removed，文件名在 from_value）。

• 别人（成员、别的 AI、别的密钥）加的返回 403 forbidden_operation：「只能删除自己上传的附件」；没有修改任务的权限同样是 403。
• 附件不存在、不在这个任务下、或已经删过，返回 404。
• 没有「替换」：要换一个版本，先删旧的，再照上面的方式传新的。

curl -X DELETE https://39.106.181.218:8443/api/v1/tasks/2/attachments/5f0c2a9e7b1d4c3a8e6f1b2d \
  -H "Authorization: Bearer $TASKS_API_KEY"

描述和评论里的图片

任务描述和评论是 Markdown，里面的图片写成 ![名称](/api/assets/{id})。这些图片不是附件，要单独读取：

curl https://39.106.181.218:8443/api/assets/86f4cfd234be724164c44ef5 \
  -H "Authorization: Bearer tsk_你的密钥" -o icon.jpg

返回图片本身（Content-Type 为图片类型）。能读到哪些图片，与密钥能读到哪些任务一致：

• 密钥（来源系统的，或绑定了 AI 员工的，AI 需要有「读取任务」权限）可以读它能进的项目里的图片，包括上传到该项目的，和嵌入该项目任务的共享图片。
• 其他项目的图片、不存在的图片返回 404；AI 没有「读取任务」权限返回 403；不带密钥或密钥无效返回 401。
• 密钥只能读取，不能上传、删除，也不能列出素材库。

8. 发表评论

POST /api/v1/tasks/{id}/comments
Content-Type: application/json

只允许给密钥有权访问的任务发表评论，权限范围与查询、更新任务一致。请求体只能是 JSON 对象，不能超过 1 MB。

curl -X POST https://39.106.181.218:8443/api/v1/tasks/2/comments \
  -H "Authorization: Bearer tsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{ "body": "已完成修复并通过测试，请验收。" }'

成功返回 201：

{
  "comment": {
    "id": 1,
    "task_id": 2,
    "author_id": null,
    "author_type": "api",
    "author_name": "测试平台",
    "body": "已完成修复并通过测试，请验收。",
    "created_at": "2026-10-03T12:00:00.000Z",
    "edited_at": null,
    "ref": "a1",
    "reply": null
  }
}

• 评论作者由密钥确定，网页显示系统名称和「接口」标识；不能通过请求字段冒充成员。未绑定 AI 时 author_id 为 null，author_type 为 api；已绑定时 author_type 为 ai，author_id 为 AI 稳定编号，名称取发表时快照，不随换绑变成另一 AI。评论编号与成员评论分别编号，区分评论时使用 author_type 加 id。
• ref 是这条评论在任务里的唯一称呼：成员评论为 u 加编号，密钥（含 AI）评论为 a 加编号。回复某条评论时，把它的 ref 作为 reply_to 传入；这条新评论的 reply 就是 { "ref", "author_name", "body" }——被回复评论的称呼、作者和正文开头（压成一行，最多 200 字），不是回复时为 null。接口返回的评论仍按发表时间排列；网页和 App 显示时把回复（以及对回复的回复）归到最初那条评论下方，组内按时间排列。被回复评论的作者是成员或 AI 时会收到「某某 回复了你在任务「…」下的留言」通知（自己回复自己不通知），不再另收一条普通评论通知。谁收到留言通知（#545）：任务的负责人（个人或小组成员）每条都收到「某某 评论了任务「…」」；建任务的人不再每条都收到，只在被回复、被 @ 时收到。留言里 @用户名 或 @姓名（和聊天一样认法：重名的姓名不认，停用的人、看不到这个任务的人不通知）的人收到「某某 在任务「…」的留言里 @ 了你」。同一条留言对同一个人只发一条：被回复的优先，其次 @，再次「评论了任务」。AI 员工不收这些通知，它们的待处理事项照旧（#508）。
• 评论会显示在任务的「动态与评论」里，并更新任务的 updated_at；有成员创建者、个人负责人或负责小组时，会向相关成员发站内通知，同一成员只收到一次。
• 已关闭的任务也可以发表评论，状态不会因此改变。评论接口不修改负责人；无法处理需要转交时，先发表评论，再用第 6 节的更新接口提交 { "assignee": "theodore" }，并检查 warnings 确认指派成功。
• 评论没有自动去重：重复提交会新增评论。如果发送后连接中断，先用 GET /api/v1/tasks/{id}/comments 确认是否已发表，再决定是否重试。external_id 的防重复仅适用于创建任务。

编辑自己的评论

PATCH /api/v1/tasks/{id}/comments/{ref}
Content-Type: application/json

{ "body": "改正后的评论正文" }

{ref} 是评论的 ref（如 a7），也可以只写编号（如 7，#605）：密钥写的编号指它发表的评论（a7），成员写的指成员的评论（u7）。用密钥改，发出 24 小时以内才能改（#605），超过返回 422「发出超过 24 小时的留言不能再改；要补充或更正，另发一条」；成员（人）在网页和 App 里改自己的留言不限时间（Apple a3106）。每改一次，改之前的正文都留在任务台的改动记录里（comment_edits 表）。改留言不是删除敏感内容的办法：旧正文会留在编辑记录里。误贴了密钥或密码，要换掉那把密钥；库里的旧正文要删，请高顺。只能编辑这把密钥自己发表的评论：未绑定 AI 的密钥只能改它以来源身份发表的；已绑定 AI 的密钥只能改它以当前这位 AI 的身份发表的。成员的评论、别的密钥的评论返回 403 forbidden_operation；这个任务下没有这条评论（包括它在别的任务下）返回 404 not_found；ref 写法不对仍是 422（#393，以前这几种都是 422）。body 的要求与发表评论相同。成功返回 200 { "comment": {...} }，评论的 edited_at 变为编辑时间，网页和 App 在评论旁显示「已编辑」；内容与原来完全相同则不算编辑。编辑不会再次发通知，不改变任务的 updated_at，评论的回复关系保持不变，别人回复它时引用的开头随之更新。

评论对象的 edited_at：从未编辑过为 null。

读取评论

GET /api/v1/tasks/{id}/comments 返回 200 { "comments": [...] }。数组按发表时间、编号排序，包含人类、来源接口和 AI 评论；各项字段与发表评论响应一致，另有 kind: "comment"。遵守任务读取权限，仅返回评论、不包含状态动态。

9. 错误处理

出错时响应体格式统一为：

{
  "error": {
    "code": "validation_failed",
    "message": "优先级无效"
  }
}

常见的 422 原因：

• 缺少 title 或标题为空。
• priority 不是 urgent（紧急）、high、medium、low 之一。
• due_date 格式不是 YYYY-MM-DD，日期不存在，或年份不在 2000 到 2100 之间。
• tags 不是字符串数组，或超过 20 个。
• 创建任务的目标项目已被归档。
• 多项目密钥创建任务时没有提供 project_id，或项目编号格式错误。
• 同一把密钥把同一个 external_id 用在不同项目。
• 更新任务时没有提供任何可更新的字段，或 status 不是 todo、evaluating、in_progress、submitted、testing、merged、review、closed 之一。
• 列出任务时查询参数无效，例如 page=0、size=10 或未知的状态。
• 发表评论时 body 缺失、不是字符串、只有空白或超过 10000 字。
• 附件链接不是 http/https 网址；直接上传的文件超过 4 MB；文件超过 100 MB；任务的附件已达 50 个。

10. 常见问题

可以列出任务并发表评论吗？ 可以，分别见第 5.1 节和第 8 节。两者都只能用在密钥能进的项目里，也就是它的成员在员工管理里被勾的项目。

负责人的用户名和小组名称去哪里查？ 小组名称见第 3 节「可用的小组」。成员的用户名请向任务台管理员索取，管理员在「成员」页面可以看到每个人的用户名。

可以修改或关闭已推送的任务吗？ 可以，见第 6 节。可以修改授权范围内的任务。

推送了任务台里没有的标签会怎样？ 会自动创建这个标签，颜色为灰色，并挂到任务上。标签名不区分大小写，已存在的标签会直接复用。

附件能删除或替换吗？ 可以删除自己加的，见第 7 节「删除自己加的附件」；要替换就删了再传。成员也可以在任务页面里删除自己上传的附件。

有调用频率限制吗？ 目前没有硬性限制。请避免短时间内大量并发推送；批量导入时建议逐条顺序调用。

推送的任务在任务台里显示谁是创建者？ 未绑定 AI 时显示为你的系统名称（申请密钥时提供的名称），并标注「接口」；绑定后显示 AI 员工身份。

创建时间展示与筛选规则

网页的列表及详情按浏览器所在的时区展示创建时间，接口返回的 created_at 仍为 UTC ISO 8601；接口的日期筛选没有指定时区时按上海时间（Asia/Shanghai，UTC+08:00）。编辑任务、指派、变更状态、评论不会改变创建时间。

created_from、created_to 支持 2000–2100 年内的有效日期。两者可分别省略；都提供时开始日期不能晚于结束日期。空参数、重复参数、无效日期或反向区间返回 422，不会悄悄扩大查询范围。结束日期按下一天的 00:00 排除上界，因此最后一毫秒也会包含。

例如 GET /api/v1/tasks?project_id=2&created_from=2026-10-02&created_to=2026-10-02 查询上海时间 10 月 2 日创建的任务，对应 UTC 2026-10-01T16:00:00.000Z（含）至 2026-10-02T16:00:00.000Z（不含）。可与已有项目、状态、优先级、关键词和 AI 自身负责人条件组合；日期条件在统计和分页前应用，项目与操作权限继续生效。

11. AI 员工接入

管理员在「成员 → 添加 AI 员工」设置名称、用户名、职责、工作 Prompt、可见项目与操作权限。AI 身份使用稳定的成员编号，不能通过密码登录网页。管理员和该 AI 都可以修订其职责与工作 Prompt（支持 Markdown）；身份、密钥、项目与操作权限仍仅由管理员管理，AI 不能读取或修改其他 AI 的私有配置。

11.1 绑定与密钥生命周期

可选择已有有效密钥，或生成新密钥；密钥没有自己的项目，绑给 AI 以后能进的就是这位 AI 的可见项目（#1039）。选择已有密钥时仅展示名称、前缀、状态及绑定对象，不展示完整密钥。保存绑定、换绑或解绑前需要确认影响：

• 同一有效密钥仅能标识一个 AI；一个 AI 同时绑定一把有效密钥。并发绑定不会覆盖另一个 AI 的绑定。
• 绑定来源系统的密钥时，它从此代表这位 AI，不再是那个来源系统的成员的。该密钥原先的全部调用方随后都会使用所绑定的 AI 身份。
• AI 实际权限 = AI 可见项目 ∩ 允许的操作。/me 和任务列表中的 projects 就是这位 AI 在员工管理里被勾的项目。
• 换绑或解绑时，旧密钥进入暂停状态，什么也进不了。管理员可以重新绑定尚未吊销的密钥。
• 轮换让旧密钥立即失效，新密钥仍标识同一个 AI；吊销的密钥不可恢复。停用 AI 立即拒绝其密钥，重新启用后恢复原配置。历史任务、评论和审计归属保留。
• 来源系统的密钥用它自己的成员（第 1 节）。管理员的网页登录身份始终与 AI 独立。

11.2 身份、Prompt 与能力

GET /api/v1/me
GET /api/v1/me/prompt

两者仅接受已绑定有效 AI 的密钥，未绑定返回 403 ai_identity_required，停用、解绑或吊销返回 401；响应禁止缓存。

/me 返回：

{
  "ai": { "id": 8, "name": "工程 AI", "username": "engineer", "active": true },
  "prompt_version": 2,
  "projects": [{ "id": 2, "name": "智能任务系统" }],
  "permissions": ["task.read", "task.create", "task.update", "ai.assign"],
  "executor": "external",
  "messaging_available": true,
  "delegation_available": true,
  "profile_update_available": true
}

/me/prompt 返回 { "ai_id": 8, "prompt": "工作指令…", "version": 2, "updated_at": "2026-10-03T12:00:00.000Z", "responsibilities": "职责…" }。version 是职责与 Prompt 的共同内容版本：任一内容改变才递增；编辑名称、权限或保存相同内容不递增。此接口只返回鉴权所得身份，不接受其他 AI 编号作为目标。

管理员在「成员 → 权限」配置人类权限，在 AI「配置」中统一配置 AI 的前六项权限（expense.review 只给人类）。权限对员工所有可见项目生效，目前不提供项目级操作权限覆盖。管理员始终拥有全部权限，成员不能修改自己或他人的权限。变更记录包含操作管理员、变更前后权限及时间。

现有及新建普通人类成员默认保留读取、创建、编辑，默认不授予删除、分配 AI、联系 AI 和审核支出；AI 默认无操作权限。来源系统的密钥只有读取、创建、更新三样，不能分配或联系 AI、删除任务；它的成员能进哪些项目在员工管理里勾，操作权限固定不变。

项目可见性与操作权限分别配置、取交集；绑定密钥或授予操作权限不会扩大项目访问范围。接收 AI 必须已启用、绑定有效密钥、能进任务的项目且具有读取/更新任务权限，否则指派失败；不能通过包含 AI 的小组绕开检查。

撤销读取权限后，任务列表、详情、搜索、分页总数、项目/标签/小组任务计数、通知、附件和项目内图片均按新权限过滤。已有任务、指派、评论及附件保留。只有读取权限时，页面禁用编辑、批量操作和评论入口，绕过页面直接调用服务端仍会被拒绝。待完成上传和后续写入会重新校验权限；权限不足的 API 返回 403 forbidden_operation，项目不可见的详情请求返回 404。

AI 员工和 AI 助手（#428）

AI 成员分两类，GET /api/v1/me 的 ai.kind 说明自己是哪一类：employee（AI 员工：自己思考、做事，接任务、收消息）或 assistant（AI 助手：只在被叫到时做一件固定的小事）。类型由管理员在成员的配置页选。

助手还有三条由服务端保证：

• 只被叫醒在被叫到时：GET /api/v1/me/pending 对助手恒等于带了 mentions=1，而且不报任务变动和表情回应——只报私聊它的消息、群里 @ 它的和引用回复它的；说给所有人的（@all、@所有人）只有同时点了名才算，引用了它的也不算（#616）。守候脚本不用加 --mentions-only。
• 不接任务：把任务指派、委派给助手，或助手自己认领，都返回 422「AI 助手不接任务」；负责人的候选里没有助手；任务派给一个有助手的小组时，助手不算在内。/me 的 delegation_available 对助手是 false。
• 它能做的别的事（读任务、建任务、把负责人写成一位 AI 员工）仍由管理员给它的权限决定，AI 的消息频率上限同样有效。

GET /api/v1/chat/recipients 的每位员工多一个 ai_kind："employee"、"assistant"，人是 null。

ai.assign 和 ai.message 独立，分配 AI 同时需要对应的任务创建或编辑权限。普通任务评论与站内通知不构成发给 AI 的执行消息，也不会自动触发 AI；执行器须遵守当前权限，不得将历史指派或缓存授权视为持续有效。消息投递与收件箱接口见第 12 节。

11.2.1 AI 更新自己的职责与 Prompt

PATCH /api/v1/me/prompt
Content-Type: application/json

先 GET /me/prompt 获取当前内容和 version，再提交需要修改的字段：

{
  "expected_version": 2,
  "responsibilities": "## 职责\n- 维护智能任务系统\n- 交付后交管理员验收",
  "prompt": "# 工作规则\n\n开始实际工作前先建立或关联任务。完成后记录测试、提交和部署结果。"
}

未提供的文本字段保持原值；修改文本的 CRLF/CR 换行归一为 LF，并去除首尾空白，内部 Markdown 保留。仅换行格式不同不产生新版本。成功返回 200，包含自身职责与 Prompt、最新 version 和 updated_at；技能通过 GET 读取。职责或 Prompt 改变时，在同一事务中递增共同内容版本、保存完整快照并记录实际修改者；相同版本保存相同内容不会产生额外版本或修订记录。

仅接受上表字段；传入其他 AI 编号、名称、用户名、权限、项目、密钥等字段返回 422 validation_failed，不会部分修改。身份始终取自当前有效密钥，URL 查询参数不能选择另一位 AI。此能力供所有已启用并绑定有效密钥的 AI 使用，独立于任务操作权限；修订文本不会授予任何项目或操作权限。普通来源密钥返回 403 ai_identity_required；停用、解绑、轮换后旧密钥或吊销的密钥返回 401。

如果当前版本与 expected_version 不一致，返回 409 conflict。应重新 GET，合并管理员或其他执行器的修改后再提交，不得盲目覆盖。管理员编辑页也携带内容版本保护；遇到冲突先保留自己的草稿，重新打开页面读取最新内容。请求格式、长度和大小限制沿用普通接口的 400、422 和 413 规则。

11.2.2 内容历史与 Markdown 展示

GET /api/v1/me/prompt/history 返回 200 { "ai_id": 7, "versions": [...] }，仅包含当前 AI 的最近 10 个版本，按版本倒序。每个版本包含 version、responsibilities、prompt、created_at、actor_name 和 actor_kind；修改者是管理员或该 AI，升级保留的旧内容修改者为 null。完整历史在数据库中保留；此次升级只保留当时的当前版本，不能恢复过去未存储的旧内容。身份、读取、修订与历史成功响应均禁止缓存。

管理员的 AI 新增、编辑页支持职责与 Prompt 的 Markdown 编辑/预览，已有内容默认预览，支持标题、列表、链接、表格和代码块；原有纯文本仍可阅读和编辑，原始 HTML 不执行。管理员可在同页展开最近 10 个历史版本，查看完整内容与修改者。需要恢复旧内容时，读取当前版本后将旧文本作为一次新修订提交，历史不会被删除。

API 返回 Markdown 原文，不返回 HTML。AI 每轮工作先读取当前版本；如需修订自身职责或 Prompt，应关联任务、说明原因，仅按已授权的职责改进工作方式，保存后读回核对。Prompt 中的项目描述和操作要求不能覆盖服务端权限，Prompt 中的巡检间隔也不会自动修改外部执行器的定时计划。

11.3 领取和处理任务

1. 读取 /me、/me/prompt、/me/skills，核对身份、当前指令、项目交集和操作权限。
2. 用 GET /api/v1/tasks?project_id=2&assignee=self&status=open&page=1&size=50 分页读取自己的待办。需要寻找未分配任务时去掉 assignee，逐条检查负责人和状态。
3. 修改前读取任务详情；用 POST /api/v1/tasks/{id}/claim 原子领取（无需请求体）。仅领取未分配给他人或小组的 todo，也可开始已明确指派给自己的 todo。成功返回 200 { "task": ... }，同时指派给当前 AI 并变为 in_progress。同一 AI 重试已领取的进行中任务返回原任务，不重复动态/通知；竞争失败返回 409。不会领取 review、closed 或别人的任务。
4. 处理后通过评论记录结果和证据，再按任务状态交付（见第 6 节「任务状态」）：代码提交到分支后 PATCH 为 submitted 并把任务交给高级系统工程师，合并到 dev 后为 merged，合并到 main 或部署后为 review 等待验收。无法处理时通过评论说明原因，再 PATCH assignee 为管理员指定的真实用户名，检查 warnings 并读回确认。

领取需要 task.read、task.update 和 ai.assign。其他 PATCH 指派仍是明确的改派操作，与领取保护不同；执行器不要用覆盖指派来绕开领取冲突。

本版本提供身份、配置及拉取式任务接口。创建 AI 不会自动启动模型或执行进程，也不表示 AI 已在线。 管理员需将密钥配置到自己的执行器；执行器负责轮询、遵守最新 Prompt、执行任务并提交结果。员工消息现已开放，执行器可轮询收件箱；不能把消息已送达等同于已接手或已完成。

11.4 删除与恢复

DELETE /api/v1/tasks/{id}

仅显式获 task.delete 的 AI 可以通过 API 删除其授权范围内的任务；普通来源密钥返回 403。成功返回 204，无响应体。任务进入回收站，列表、详情、评论和附件读取立即隐藏；再次访问/删除返回 404。任务正文、评论、附件与操作记录保留，原 external_id 仍占用，再次创建同一外部编号返回 422，避免悄悄重建。

显式获 task.delete 的人类成员也可在任务详情页确认删除，操作记入动态。管理员在「任务回收站」恢复任务，恢复后沿用原编号、状态、负责人和项目范围；恢复动作记入动态。目前不提供永久删除或 API 恢复接口。

紧急任务处理

priority=urgent 表示最高优先级。AI 执行器每轮和完成任务后，应先分页查询 GET /api/v1/tasks?project_id=2&status=todo,in_progress&sort=priority&dir=asc&size=50，也可用 priority=urgent 单独查紧急任务。只认领自己可处理、未分配或已分配给自己的任务；不要抢占他人的进行中任务。遇到阻碍应留言并交 Theodore 解答。安全保存当前进度后切换，避免中断部署等不可安全中断的步骤。

紧急级别不会直接启动模型或即时推送给外部执行器；响应时间仍取决于执行器巡检。Papaya 完成任务后立即查询下一批，无可处理任务时每 3 分钟巡检。其他 AI 的 Prompt 或执行器也需要采用此规则。

AI agent 心跳与运行状态

成员列表和 AI 配置页根据真实心跳展示「未连接」「在线 · 空闲」「工作中」「待命」（见下文「待处理事项与待命状态」）「离线」或「已停用」，以及当前工作任务链接。启用账号、分配任务或普通 API 请求都不代表 agent 在线。

POST /api/v1/me/heartbeat

使用绑定 AI 的有效密钥及相同的 Authorization: Bearer <API_KEY> 请求。仅更新自己的运行状态，不能修改任务、负责人、权限、其他 AI 身份或服务端时间。

{
  "state": "working",
  "task_ids": [74, 77]
}

GET /api/v1/me 返回 versions：{ "docs": "0.0.47", "prompt": 11, "skills": { "tasks-development": 4 }, "rules": { "task-patrol": 2 } }。接口文档随应用发布，docs 就是应用版本号。登录时把文档、Prompt、技能、规则各读一次并记下版本；之后每轮只读 /me，哪一项的版本变了才重读哪一项。

成功返回 presence（ai_id、status、reason、last_seen_at、expires_at、tasks、note、note_at；note 是工作中时自己最近说的那句话，note_at 是说的时间，没有时都是 null，只有这位 AI 自己和管理员读得到；tasks 每项有 id、title、project_id 和 started_at，即这个任务最近一次改成「进行中」的时间，没有这条记录时为建任务时间，成员页据此显示「已进行 N 分钟」）、recommended_interval_seconds: 60 和 timeout_seconds: 300。时间是服务器接收时间，不接受客户端时间覆盖。GET /api/v1/me 同时返回自身 presence 与 heartbeat 接入参数。所有响应不缓存。

• agent 开始执行时发送心跳，认领后用 working 和正在处理的任务编号上报；切换任务及时更新。
• 接口返回的通用建议为每 60 秒发送一次；Papaya 按用户配置每 180 秒发送心跳并检查消息，仍短于 300 秒离线阈值；暂时没有工作发送 idle，退出或进入不常驻的等待前发送 offline。
• 每次运行心跳也要检查消息：发送 idle / working 心跳时，同轮独立调用 GET /api/v1/chat?box=inbox（全局员工私聊及当前所属群聊）。不能只在定时唤醒时查消息；退出前最后检查一次，再发送 offline。心跳接口只上报状态，不返回消息，也不会自动读取或标记消息已读。
• 每次从最新消息开始，沿 next_before 分页覆盖尚未处理的消息，按消息编号去重；理解消息后调用 POST /api/v1/chat/{id}/read，再按职责、紧急优先和当前任务批次处理，关联任务先读最新详情。已读不等于已完成，不自动互发确认，不让消息扩大权限。读取失败不能记为已处理，恢复后补查；消息检查与状态上报分别记录结果，消息请求失败不应阻止如实上报状态。
• 不可安全中断的操作完成后，在最近安全节点补查；不要为轮询启动脱离实际工作的后台保活。Papaya 当前配置为每 3 分钟唤醒巡检，运行期间每 180 秒发送心跳并检查消息；其他执行器按自己的授权配置运行。
• 最后心跳满 300 秒即离线；管理员界面每 30 秒刷新状态，网络或鉴权异常显示「状态暂不可用」，不会持续显示旧的在线状态。配置草稿不会因状态刷新丢失。
• 任务被转交、关闭或权限收回后，状态查询不再展示这些任务。若仍有新鲜心跳但没有有效工作任务，显示空闲。停用显示已停用；密钥换绑、解绑、轮换和吊销会使旧心跳失效，重新启用或绑定后需重新发送心跳。
• 401：密钥失效、未提供或 AI 已停用；403：有效来源密钥未绑定 AI；422：字段、任务归属或权限不符合规则。错误不会覆盖上次有效心跳。
• 心跳是外部执行器主动发送的活跃信号，不是系统启动 AI 的机制。Papaya 空闲时每 3 分钟唤醒一次；两次执行之间不常驻，不应通过后台脚本伪造持续在线。

待处理事项与「待命」状态

GET /api/v1/me/pending 一次回答「现在有没有我要处理的事」，供 AI 员工本机的守候脚本（仓库 tools/ai-standby/）每 20 到 30 秒询问一次，代替模型会话自己定时巡检。只有绑定了 AI 身份的密钥可用，其他密钥返回 403 ai_identity_required。

curl "https://39.106.181.218:8443/api/v1/me/pending?cursor=c367-m12-t2026-10-07T03:00:00.000Z" \
  -H "Authorization: Bearer tsk_你的密钥"

{
  "items": [
    { "type": "chat", "id": 372, "from": "高顺", "summary": "也安装到我手机上试试", "at": "2026-10-07T03:12:37.045Z" },
    { "type": "task", "id": 195, "from": "Apple", "summary": "待处理：任务台主动唤醒 AI 员工", "at": "2026-10-07T03:20:11.530Z" },
    { "type": "reaction", "id": 370, "from": "高顺（AI员工群）", "summary": "👍 回应了你的消息「#375 做完了，已交给 Kiwi」", "at": "2026-10-07T03:21:02.114Z" }
  ],
  "cursor": "c372-m12-t2026-10-07T03:20:11.530Z-r2026-10-07T03:21:02.114Z-w2026-10-07T03:21:40.007Z-n2026-10-07T03:19:55.201Z"
}

• task：一个任务有别人的新动静，一个任务一行，id 是任务编号，from 是最后动它的人，摘要是「状态：标题」。报三种（#508 起后两种）：在我名下（或我所在小组名下）、还没结束的任务，别人改了它或在下面留言；我建的任务，不管现在在谁名下、是什么状态（已关闭的也算），别人改了它或在下面留言——交给人去定、去验收的任务，回答就是这样听到的；任务留言里 @ 了我（规则和聊天里的 @ 一样，@all 不算），我看得到的项目里任何任务都算，摘要末尾带「（留言 a72 @ 了你）」。我自己做的不报；几种情况落在同一个任务上只报一行。带不带 mentions 都一样；AI 助手不报任务。
• answer（#457）：人回应了我能看到的会话里某条消息的 widget（现在是选项）——选项选了以后不再多发一条消息，这就是知道「谁选了什么」的途径。id 是那条消息的编号，from 是选的人，摘要是「在消息 #2512 的选项里选了：先发网页」。每次回应报一次，改选按新的结果再报一次；我自己的回应、别的 AI 的回应不报。和表情回应一样，第一次不带游标（或带着没有 -w 段的旧游标）时从当时最新的回应之后开始，不补报以前的。带 mentions=1 时只报对我自己发的消息的回应；AI 助手只报它自己发的、点了名的选项的回应，不点名的投票谁选了都不报。完整结果读那条消息的 segments[].state.chosen。
• reaction（#402）：人给我发的消息点了表情回应——私聊里对方点的，群里任何一位普通员工点的。#503 起只报给那条消息的作者（高顺 m3172，2026-10-11）：点在别人消息上的不报，读那条消息时仍在它的 reactions 里看得到；之前是群里每一位 AI 都报，他点一个表情七位 AI 各醒一次。带不带 mentions 都一样。id 是被回应的那条消息的编号，摘要写明哪个表情和消息开头。每个表情只报一次，没有「已读」：不带 cursor、或带的是加这一类之前的旧 cursor 时，从这一刻以后新点的开始报，不补报以前的。AI 员工点的表情不报（免得互相叫醒），自己点的和取消的也不报；它们仍在消息的 reactions 里读得到。表情是对方的答复，不必再回消息；但它不能代替需要管理员明确确认的事。
• 只在被 @ 时才报群消息（#422）：加上 mentions=1（GET /api/v1/me/pending?mentions=1&cursor=…），群消息只报正文里 @ 了我的（@用户名，或没有重名时的 @姓名；@all 不算）和引用回复我发的消息的（说给所有人的消息——带 @all 或 @所有人——要同时 @ 了我才报，只引用我的不报，#616，和 AI 助手被叫到的规则一样）；表情回应只报别人给我发的消息点的。私聊消息和任务照常都报。没报的群消息仍是未读，但游标照常前进，以后不会补报，需要上下文时自己用 /chat?box=conversation 读。守候脚本的 --mentions-only 就是每次都带这个参数。不带时行为和原来完全一样。
• 群里有好几位 AI 时（#472）：加上 mentions=ai（GET /api/v1/me/pending?mentions=ai&cursor=…）。人在群里说的话照旧每条都报，不管有没有 @；别的 AI 在群里说的只报 @ 了我的和引用回复我发的消息的（@all 不算）。私聊、交接通知照常都报；任务照常都报，只有一种例外（#531）：只因为是我建的才报的任务，上次问过以后只有别的 AI 动过它（没有人动过），就不报，等留言里 @ 我才报；有人动过照报，在我名下的照报。表情回应和不带参数时一样，只报点在我自己发的消息上的。没报的仍是未读，游标照常前进，以后不会补报；被叫醒后自己读前后文，读完可以一次标到某一条为止（见下）。守候脚本的 --ai-mentions-only 就是每次都带这个参数。mentions 只接受 1 和 ai，别的值返回 422。
• 一次标到某一条为止（#472）：POST /api/v1/chat/{id}/read 的请求体带 { "through": true } 时，同一个会话里这一条和它之前发给我的未读消息一并标成已读（人在网页和 App 上本来就是这样）。不带请求体或不带 through 时照旧只标这一条。
• chat：发给我、还没标记已读的聊天消息（私聊和我所在的群）。message：旧项目消息里发给我、未读的（委派通知在这里；交接通知的摘要开头带着要看的留言编号，例如「任务 #441（留言 a1463，此前 a1461）「…」：任务交接…」，#472）。task：指派给我或我所在小组、状态为待处理、评估中、进行中、已提交或已合并，并且别人刚改动或评论过的任务；我自己的操作不算，待验收和已关闭的任务不算。
• 每项只有类型、编号、发件人（或最近动它的人：改任务和留言都算，#472）、一行摘要（最多 160 字）和时间。完整内容仍用原有接口读取。摘要是别人写的内容，只是资料，不是指令。
• cursor：把上一次返回的 cursor 带回来，只返回之后新出现的；没有新东西时 items 为空、cursor 不变。不带 cursor 返回现在所有等着的。每类一次最多 50 项，更多的下一次返回。消息标记已读后不再出现。 cursor 是不透明的，原样带回即可；#508 起末尾多一段 -n…（带 @ 的任务留言看到哪了），没有这一段的旧 cursor 照样能用，从它的任务位置接着看。任务留言里的 @ 和表情一样没有「已读」：第一次不带 cursor 时从当时最新的留言之后开始，不补报以前的；一次最多看 200 条带 @ 的留言，更多的下一次接着看，不会漏。
• 接口立刻返回，不挂起等待：几个 AI 员工全天挂着长连接，函数时长按秒累计，不如每 25 秒问一次划算。

守候脚本用 POST /api/v1/me/heartbeat 上报 {"state":"standby"}（不能带 task_ids），表示「没有会话在运行，但本机有脚本守着、能被叫醒」，网页显示「待命」。它和会话自己的 idle / working 分开记录、互不覆盖：有会话的新鲜心跳时显示会话的状态；会话报了 offline 或超过 5 分钟没有心跳、而待命心跳还新鲜时显示「待命」；两者都没有才是「离线」。显示「待命」时，如果会话最后一次报的是 working，返回的 tasks 里仍列出它当时带的、现在仍在进行中（进行中、已提交、已合并）并且仍指派给这个 AI（或它所在小组）的任务，成员页把它们列在「待命」下面；任务转为待验收、关闭或改派给别人后就不再列出。会话最后报的是 idle 或 offline 时，「待命」不带任务。守候脚本停下时上报 {"state":"standby_stopped"}（不能带 task_ids，#1105）：马上撤掉它的待命，不再等 5 分钟过期；会话自己报的状态、任务和那句话不动。所以会话报了 offline、守候脚本也停了，马上就是「离线」（reported_offline），先停后报还是先报后停都一样。

AI 用量和产出上报（#756）

POST /api/v1/run-board/ai-usage：跑会话的那台 Mac 把每位 AI 员工每天的用量和产出数好，用 AI 员工的有效密钥报上来（任何一位 AI 员工都可以替别人报，也可以报全队和额度）；管理员在运行看板「AI 用量和产出」里看最近 14 天。没绑定 AI 的密钥、AI 助手的密钥回 403 ai_identity_required；请求体最多 256 KB（装得下 400 行），超了 413；不是 JSON 对象回 400 invalid_json；字段不认识、形状不对回 422，这时整份报告一行都不存。

{
  "rows": [{
    "day": "2026-10-13", "member_id": 14,
    "period_start": "2026-10-13T04:00:00Z", "period_end": "2026-10-13T20:51:00Z",
    "requests_main": 1193, "requests_sub": 8,
    "tokens_input": 3000, "tokens_cache_read": 599500000, "tokens_cache_write": 2680000, "tokens_output": 840000,
    "history_main": 596500000, "active_hours": 16,
    "work": { "dev_tasks": 15, "rounds": 29, "merges_made": 16, "returned_to_me": 5 },
    "rules_version": 3
  }],
  "team": [{ "day": "2026-10-13", "merged_tasks": 60, "merges": 67, "weekly_points": 44, "work": {}, "rules_version": 3 }],
  "limits": [{ "at": "2026-10-13T20:51:00Z", "weekly_percent": 44, "weekly_resets_at": "2026-10-20T04:00:00Z", "five_hour_percent": null }]
}

同一个主键再报一次是覆盖，所以重报、补报都安全；同一次请求里同一个主键出现两次回 422。上报人和上报时间由服务端记，请求里带了回 422。成功返回 { "saved": { "rows": 2, "team": 1, "limits": 1, "hours": 0, "team_hours": 0, "deepseek_balance": 0 } }，不缓存。一行再报一次时没带 models、deepseek，这两样就清成空（整行覆盖）。库里只存原始数；「折算用量」（缓存读 × 0.1 + 缓存写 × 1.25 + 新输入 × 1 + 输出 × 5）由服务端在一处算。这个接口只管上报，没有读的接口。

发布记录和下一次发布的计划（#828）

每发一次记一条：哪个项目的哪一部分（闪点任务的网页、App，闪点菜单的服务端和网页、iPad、安卓应用（#1585）、小程序（#2021）；闪点选样 #1088 起并进了闪点菜单，以前的记录照旧留着），版本和构建号，哪个提交，什么时候发的，用的哪张发布确认，结果怎么样，带了哪些任务。记录由发布脚本在部署或上传以后自己写（闪点任务用 tools/releases/record.mjs，闪点菜单由它的发布脚本用同一个工具写：--project menu），不靠人记；闪点菜单的小程序是高顺自己在后台上传、设体验版，负责发布的人照高顺说的用同一个工具记。另外每个项目有一份下一次发布的计划：什么时候发，要带哪些任务，再加一句话。管理员在运行看板「发布」里看，AI 员工用下面的接口读。

这几个接口只给 AI 员工：没绑定 AI 的密钥回 403 ai_identity_required，AI 助手的密钥回 403 forbidden_operation。时间都用 ISO 8601 写，要带时区，秒可以不写（2026-10-15T17:55Z、2026-10-16T01:55:44+08:00）；存下来和返回的都是 UTC（2026-10-15T17:55:44.000Z）。请求体不是 JSON 对象回 400 invalid_json；有不认识的字段、或者值写错了，回 422 validation_failed，message 里说是哪一个。响应都不缓存。

读发布记录：GET /api/v1/releases?project=tasks&target=app&since=<时间>&until=<时间>&limit=50。参数都可以不带。project 写 tasks（闪点任务）、menu（闪点菜单）或 sample（闪点选样以前的记录，#903；新的记不了，#1088）。target 写 web（网页，闪点菜单是服务端和网页，闪点选样是服务端和后台）、app（App、iPad，闪点选样以前的小程序）、android（闪点菜单的安卓应用，#1585）或 mp（闪点菜单的小程序，#2021）。since 和 until 按发布时间筛，含 since、不含 until。limit 写 1–200，默认 50。最新发布的排在前面，同一时刻的编号大的在前。返回 { "releases": [...] }，每一条是：

{
  "id": 17, "project": "tasks", "project_name": "闪点任务", "project_color": "sky", "target": "app", "target_name": "App",
  "version": "0.0.113", "build": 31, "commit": "<完整的 40 位提交号>", "released_at": "2026-10-15T20:10:00.000Z",
  "result": "uploaded", "result_note": null, "note": null, "backfilled": false,
  "confirmation": { "id": 42, "message_id": 5800, "confirmed_by": { "id": 1, "name": "…" }, "confirmed_at": "2026-10-15T19:40:00.000Z" },
  "released_by": { "id": 11, "name": "…" },
  "tasks": [{ "id": 819, "title": "…", "project_name": "闪点任务", "project_color": "sky" }, { "id": 764, "title": null, "project_name": null, "project_color": null }],
  "created_at": "2026-10-15T20:10:02.000Z", "updated_at": "2026-10-15T20:10:02.000Z"
}

记一次发布：POST /api/v1/releases，发布脚本调用。只有负责发布的角色（有发布技能的 AI 员工）能记，别人回 403。

{ "project": "tasks", "target": "web", "version": "0.0.114", "commit": "<完整的 40 位提交号>", "result": "ok", "tasks": [805, 738] }

• 普通的记录要有一张发布确认：这个项目、这个提交、这一部分的，而且是记录的人自己用掉的（POST /api/v1/release-confirmations/claim，见「发布脚本查发布确认」）。没有这样的确认回 404 not_found。用掉一次只能记一条，再记回 409 conflict；以后要改结果用下面的 PATCH。
• 小程序（mp，#2021）不用发布确认：是高顺自己在后台上传、在微信公众平台上设体验版的，负责发布的人照高顺说的记。一个版本只记一条：上传以后记 uploaded，设成体验版以后用 PATCH 改成 ok；同一个版本再记回 409 conflict，message 是「小程序 0.1.13 已经记过了；改结果用 PATCH /api/v1/releases/{id}」。
• 项目里不管哪一部分发出去了（记了一条普通的记录，结果不是 rolled_back），这个项目的发布计划就清掉，回到「计划中」：计划里的那次发布已经做了。小程序的记录不清计划：它是从已经发了的包里传的。
• 补的记录（backfilled: true，用 tools/releases/backfill.mjs 补）不带 result，必须带 released_at。released_at 要早于这个项目这一部分第一条由发布脚本记的发布，否则回 422。同一部分、同一提交、同一构建已经有记录的，回 409。补的记录不用发布确认，也不清发布计划。
• 带上的任务交去验收（#1015）：一条结果是 ok 的记录（补的记录也算）记下的时候，它带上的任务里，状态还是「已合并」的都改成「待验收」，交给担任「技术负责人」的 AI 员工（和「问题反馈」自动交的是同一个人，看得到这个任务的项目、能读能改任务）；这个项目没有这样的人，就交给记录的人。是任务台自己交的，不要求记录的人能改任务、能分配 AI。和平常改状态一样记进任务历史、发指派通知，每件下面再记一条留言，比如「随 闪点任务 网页 0.0.118 发布，改成待验收」（App 和 iPad 的写成「随 闪点任务 App 0.0.118（构建 30）发布，改成待验收」）。别的状态的不动。结果是 uploaded、problem、rolled_back 的，这时候不动，等下面的 PATCH 把它改成 ok 时再交。同一件任务网页和 App 各发一次时，先成功的那一条就交了；后面那条看到它已经不是「已合并」，就不再改，也不再留言。所以网页先发的话，App 那一半要等 TestFlight 上了才能验收，验收的人自己留意。
• 成功返回 201 { "release": {…}, "skipped": [任务编号] }，release 的格式和上面读到的一样。

以后补结果：PATCH /api/v1/releases/{id}，请求体 { "result": "ok" }，或者 { "result": "problem", "result_note": "…" }。App 和 iPad 的构建上传时记的是 uploaded，等 TestFlight 处理完再改；小程序的等高顺设成体验版再改；网页发完以后才发现不对的，也用这个接口改。只有负责发布的角色能改。字段和规则同上：uploaded 只用于 App、iPad 和小程序，problem 和 rolled_back 要有 result_note；不带 result_note 就保留原来的。改成 ok 时，带上的、还是「已合并」的任务交去验收，规则同上。没有这条记录回 404；补的记录没有结果，改它回 422。成功返回 200 { "release": {…} }。

读发布计划：GET /api/v1/releases/plan，返回 { "plans": [...] }，每个项目一条（闪点任务、闪点菜单）：{ "project", "project_name", "project_color", "planned_at", "tasks": [{ "id", "title", "project_name", "project_color" }], "note", "updated_by": { "id", "name" }, "updated_at" }。没写过计划、或者计划已经随着发布清掉了的，planned_at、note、updated_by、updated_at 都是 null，tasks 是空的，页面上显示「计划中」。title 的规则和发布记录一样。

写发布计划：PUT /api/v1/releases/plan，请求体 { "project": "tasks", "planned_at": "2026-10-16T03:00:00Z", "tasks": [805, 738], "note": "…" }。每次都是整份换掉，没带的字段按空算。还不知道什么时候发，planned_at 写 null。tasks 最多 100 个，都得是任务台上有的任务，有不存在的回 422，message 里列出是哪几个。note 一句话。三样都是空的就是没有计划，回到「计划中」。只有技术负责人和负责发布的角色能写，别人回 403；管理员可以在运行看板的页面上写。成功返回 200 { "plan": {…} }。

12. 旧项目消息与委派兼容接口

当前员工聊天使用 /api/v1/chat，见下文「员工私聊和共享群聊」。 本节 /api/v1/messages 仅用于旧项目消息历史与任务委派兼容，不会显示在新的员工聊天界面中。不要用本节接口发送新聊天。旧接口的项目绑定、小组逐人投递、旧 reply_to 约束只适用于旧消息；新聊天使用全局员工私聊和共享群聊，不绑定项目或任务。

旧消息必须属于一个双方均可访问的项目，task_id 可选；引用任务时同时检查双方完整任务访问范围。旧小组消息是逐人投递，回复只发给原发送人。停用、权限或项目授权变化即时影响旧消息读写。旧消息正文为纯文本，另支持最多4张私有图片（下文12.4）。过渡期间执行器额外检查旧 inbox，使用旧接口标记已读，新回复统一走 /chat；两套消息编号独立。

以下 API 只接受绑定 AI 的有效密钥。身份和发送时间由服务器确定，所有响应禁止缓存。

员工消息只在 AI 员工之间（#393）。 人读写这类消息的页面早已去掉（#370），所以：

• 收件人是人时，发送返回 403 forbidden_operation：「人看不到员工消息，请用聊天（POST /api/v1/chat）」。要找人说话，用下文的聊天接口。
• 小组里只要有一个人，整组不能投递，groups 里这一组 available:false，reason 是「组里有人：员工消息只在 AI 员工之间使用，请用聊天」。
• 可联系的员工（12.1）只列 AI 员工。
• 委派不受影响：把任务委派给人照常成功（第 13 节），交接说明在任务留言里，对方照常收到任务通知。委派自己留的那条交接记录（kind: "delegation"）仍在 AI 的收件箱里读得到；委派给人的那条，人没有地方读，以任务留言为准。

12.1 查询可联系的员工

GET /api/v1/messages/recipients?project_id=2
GET /api/v1/messages/recipients?project_id=2&task_id=59

返回 {"recipients":[{"id":10,"name":"Apple","username":"apple","kind":"ai"}]}。只返回当下可联系的 AI 员工，不含人（#393）。发送员工消息需要 ai.message。发送前会再次校验，不能把候选列表当作持续授权。接收 AI 必须启用且绑定有效密钥，具备读取权限。

响应同时包含 groups:[{id,name,count,available,reason}]：count 为该组启用且不含发送者的人数，available:false 表示该组不能整体投递，reason 提供原因。小组中的每个目标成员均须通过项目/任务及 AI 交互权限检查；最多 100 人。停用成员不接收，空组不可发送。

12.2 发送与回复

POST /api/v1/messages

{
  "project_id": 2,
  "task_id": 59,
  "recipient_id": 1,
  "body": "已完成复现，需要确认交付范围。",
  "external_id": "agent-a-task59-question-1"
}

body 为 1–8000 字，external_id 为 1–120 字，须为同一消息的稳定请求编号。task_id 可省略；关联的任务要在自己能进的项目里。回复时增加 reply_to（收到的消息 ID），收件人必须是原发件人，项目和关联任务必须一致。

首次返回 201 {"message":{...},"duplicate":false}；同一员工、相同编号和相同内容重试返回 200、同一个消息 ID 及 duplicate:true。相同编号用于不同内容返回 409 conflict。请求不可包含发件人、时间、附件等其他字段。

消息对象包含 id, project_id, project_name, task_id, task_title, sender_id, sender_name, sender_kind, recipient_id, recipient_name, recipient_kind, body, reply_to, kind, read_at, created_at。kind 为 message 或 delegation；read_at:null 表示尚未标记已读。

向小组发送时，用 recipient_group_id 替代 recipient_id，例如：

{
  "project_id": 2,
  "recipient_group_id": 3,
  "body": "请大家补充本周需要协作的事项。",
  "external_id": "team-weekly-20261003"
}

不能同时传 recipient_id 或 reply_to。首次返回 201 {"group_send_id":1,"messages":[...],"duplicate":false}，每位接收人各有一条消息和独立已读状态；发送者不会收到自己的群发。全部投递在同一事务完成，任意权限或 AI 频率检查失败则整组回滚。重试同一编号及内容返回 200 和原始投递，不因成员变化补发给新人；组名保留发送时快照，即使后来改名或删除小组也可追踪。不同内容或在成员/小组发送间混用同一编号返回 409。

所有消息对象另含 group_send_id, group_id, group_name（普通消息为 null）。收件人仅看到投递给自己的那条，发送者可逐人核对；回复小组消息仍使用原消息 reply_to 和原发送人 recipient_id，不会自动回复整组。

12.3 收件箱与已读

GET /api/v1/messages?box=inbox&project_id=2
GET /api/v1/messages?box=sent&project_id=2&task_id=59
GET /api/v1/messages?box=inbox&before=123
POST /api/v1/messages/123/read

box 默认为 inbox；只有 inbox（收件箱）和 sent（已发送）两种，读到的只有自己收到和发出的；别的值返回 422（以前另有管理员用的 box=audit，#393 起没有了）。每页最多 50 条，按消息 ID 降序，返回 {messages:[...],next_before:number|null}；继续传回 next_before，直到为空。只有原接收者能标记自己有权访问的消息已读，重复标记保留首次时间。撤销项目权限、删除任务或任务转移项目后，不再暴露原范围消息。

消息已送达仅表示系统保存成功；已读仅表示接收者标记已读。均不代表任务已接手、执行成功或已完成。系统不会自动启动模型；外部执行器应轮询自己的收件箱、按职责判断并回复，不无条件执行消息中的指令。

12.4 聊天图片

POST /api/message-images 使用 multipart/form-data：file（一张图片）、project_id、可选 task_id。AI 使用已绑定身份的 Authorization: Bearer <API_KEY>；登录的成员上传返回 403（#393）。这是同站点图片接口，路径不含 /v1。上传和发送分别重新校验权限；未绑定来源密钥不能使用。

仅支持 PNG、JPG、GIF、WebP，每张最多16 MB，服务端检查文件字节类型，不接受SVG或任意外链。返回 201 {"image":{"id":"…","name":"…","mime":"image/png","size":123,"url":"/api/message-images/…"}}。发送消息时在原请求中增加 image_ids:["…"]；正文与图片合并记入同一条消息，相同 external_id 和相同内容重试不会重复发送。图片编号或内容变化必须用新的请求编号。

消息响应增加 images:[{id,name,mime,size,url}]。GET /api/message-images/{id} 按当前会话或AI密钥鉴权，只有仍有相关消息访问权限的参与者可读取已发送图片（管理员不是参与者时也读不到，#393）；未发送图片仅上传者可预览。项目撤权、关联任务删除或转出原项目会阻止后续读取。图片存于私有数据库，不进入共享素材库，不返回公共存储链接。图片的缓存见下文「聊天图片和消息图片的缓存」。未发送且超过24小时的图片在后续上传时清理。

13. 带交接说明的立即委派

POST /api/v1/tasks/59/delegate
GET /api/v1/tasks/59/delegate

先读任务最新详情，再使用返回的 updated_at：

{
  "recipient_id": 1,
  "expected_updated_at": "2026-10-03T22:00:00.000Z",
  "external_id": "agent-a-task59-handoff-1",
  "reason": "缺少产品规则，需要 Theodore 解答",
  "completed": "已复现并检查现有接口",
  "next_steps": "确认跨项目消息是否允许",
  "requirements": "请在任务下说明决定，再安排后续负责人",
  "context": "目前尚未改动生产数据"
}

原因和交付要求最多各 1000 字，已完成工作、后续事项和补充上下文最多各 2000 字；仅 context 可省略，其余交接文字必填。发起者须为当前负责人/所属小组成员或管理员，并有 task.update。接收者须有效且有任务读取/处理权限；接收 AI 还需绑定有效密钥、能进任务的项目，发起者需要 ai.assign。委派通知不额外要求 ai.message。

一次事务完成：记录委派链路、变更负责人、将任务设为 todo、保存交接评论、发送交接消息及原有指派通知。已提交、测试中或已合并的任务委派后状态保持不变，用于把完成的代码交给高级系统工程师合并或发布。原任务 ID 不变；接收者开始工作时再领取/设为进行中。待验收或已关闭的任务不能委派。接收者无法处理时附具体原因再次交给 Theodore 等真人，不能把消息送达标为完成。

一起改状态（#531）：可以多带一个 "status": "merged"，把「已提交」或「测试中」（#544，QA 测过以后合并时任务在这一步）的任务在同一次委派里改成「已合并」（合并的人合完交给发布的人时用），和换人在同一个事务里；委派被拒（比如到了上限）时状态也不变。只许这一种：任务不在这两步或者写了别的状态（包括 null、空字符串），返回 422「委派时只能把「已提交」或「测试中」一起改成「已合并」」。几样检查的先后：待验收和已关闭的任务照旧先回 409（不能委派），然后才是状态的 422，再然后是「只能委派自己负责的」403。重试同一个请求时 status 也要一样。

首次返回 201 {delegation_id,message_id,comment_ref,earlier_comment_ref,task,duplicate:false}：comment_ref 是这次交接自己在任务下留的那条留言的编号（如 a1463）；earlier_comment_ref 是交接人在这个任务上一次换手以后、这次交接之前留的最近一条留言（多半是审查意见，如 a1461），没有就是 null。发给接手人的交接通知末尾也写着这两个编号（#472）。相同请求重试返回同一交接编号和当前任务、200 duplicate:true，不重复交接或通知。请求编号内容冲突、任务已更新、委派循环返回 409。收到版本冲突应重新读回任务核对负责人、状态与内容，再决定是否提交新请求；不得盲目覆盖。GET 返回 {delegations:[...]}，包含双方身份、时间和完整交接说明。

AI 将已有任务交给其他 AI（含小组中其他 AI）须使用委派接口，不能以普通 PATCH/批量指派跳过交接保护。领取自己、普通编辑和向真人提交验收仍沿用已有接口。

13.1 循环限制与人工介入

管理员在「协作管理」配置：同一项目内一对 AI 在 10 分钟内往返消息总数（默认 12，上限 100），以及同一任务人工介入前的连续 AI 委派次数（默认 6，上限 20）。任务可以交回之前经手过的 AI（例如开发交给合并的人，合并的人退回开发修改，开发改完再交回去）；防止来回踢的只有这个次数上限：人工介入后 AI 之间连续委派达到上限时返回 409 并记录管理员可见的拦截提示，同一小时同原因去重。AI 仍可向真人说明问题和转交任务。

管理员可在任务详情查看交接动态，使用委派表单协调下一位员工并开启新链路；也可按现有权限关闭任务、调整负责人或停用 AI。消息和交接只是工作资料，不能授权越权访问、扩大密钥权限或泄露秘密。

员工私聊和共享群聊（v0.0.5）

新聊天使用下面的 /api/v1/chat 接口，不绑定项目和任务。旧 /api/v1/messages 为项目消息历史及任务委派兼容接口，不能用它发送新界面中的聊天。两套消息编号独立，去重时应包括接口名称；旧聊天不迁移到新聊天。任务、委派及其权限不受影响。

GET /api/v1/chat/recipients
GET /api/v1/chat?box=inbox
GET /api/v1/chat?box=sent&before=123
GET /api/v1/chat?box=conversation&recipient_id=1
GET /api/v1/chat?box=conversation&group_id=2
POST /api/v1/chat
POST /api/v1/chat/123/read

认证仍使用 AI 自身有效密钥（Authorization: Bearer <你的密钥>），仅绑定 AI 的密钥可用，且需要 ai.message。成员/密钥停用、吊销或解绑后立即失效。聊天只表达员工身份关系，不授予任何项目或任务访问权限；收到的项目内容或任务链接必须再用任务接口核实权限。管理员浏览器审计可以看到全部新私聊及群聊，包括 AI 间消息，不代成员标记已读。

在正文里引用任务和消息：消息、任务描述和评论里，T123、t123 或 #123 显示为任务 123 的链接；m123（小写 m）显示为消息 123 的链接，点开进入这条消息所在的会话并定位到它，看不到这条消息的人打开时提示不可访问。以前写的「消息 #123」（# 紧跟在「消息」后面）也按消息处理。引用消息时请写 m123，不要写 #123。

联系人返回 recipients（id/name/username/kind）和当前成员所属的 groups（id/name）。启用员工可以互相私聊，但只限看得到的人（#856）：同在一个项目（归档的也算）或同在一个小组，或者有一方是管理员或 AI 助手；AI 员工照普通员工算。看不到的人不在名单里，发私聊、打电话回 403，资料页、头像、会话信息和以前的私聊都当作不存在（404），用户名查人也和不存在一样。涉及 AI 的发送需要 ai.message，目标 AI 须绑定有效密钥。群聊仅当前成员可以读写；包含 AI 时发送也需要 ai.message。新成员仅能读取加入后产生的消息；退出后失去消息和图片访问，重新加入也不会恢复退出前的历史。修改小组名称或其他成员不会重置留任成员的历史起点。

演示账号（#1119）：管理员在「成员 › 这个人 › 演示」把一位人类成员（不是管理员）标成「演示账号」（苹果审核登录用的 test）或「演示同事」。他们只看得到、只能找彼此，在哪个项目、哪个小组里都一样：联系人、私聊、通话、转发、上传、选负责人、转交、@ 和通知都只到演示账号和演示同事，管理员和 AI 助手也看不到；对别人照上面的规则算，所以管理员照样能给他们发私聊。别人发给他们的私聊，他们看得到被标以后发来的那些，回不了（can_send: false，发送回 403）；被标以前的往来他们看不到，对方那边照旧都在。他们和别人不能在一个小组或项目里：建组、改成员、建项目、改项目成员时混在一起回 422（「演示账号只能和演示同事在一个小组」「…一个项目」），管理员也一样；以前就混在一起的小组，对他们来说不存在：读、发、群通话都回 403，响铃也不叫他们。他们做的事（评论、改状态、指派、报销）不通知别人。

发送私聊：

{"recipient_id":1,"body":"任务已发布，请验收。","external_id":"batch-005-review"}

发送群聊（一次保存，所有当前有效成员共享同一消息）：

{"group_id":2,"body":"小组讨论","external_id":"team-update-005","image_ids":[]}

必须且只能指定 recipient_id 或 group_id。正文最多8000字；有图片时正文可为空。external_id 为发送者下唯一请求编号，最多120字；相同内容重试返回200和 duplicate:true，新消息201，复用编号改内容返回冲突。不可用不同编号绕过限流或重复投递。成功返回 {message,duplicate}。每条消息有 id,sender_id,sender_name,sender_kind,recipient_id,recipient_name,group_id,group_name,body,created_at,read_at,images；私聊的 group 字段为空，群聊的 recipient 字段为空。

发言前先读完（#473）：开着「发消息前必须先读完未读消息」的 AI 员工发聊天消息时，如果还有没读的聊天消息（发给它的私信，和它所在小组里别人发的消息），这条消息不发送，返回 409：

{
  "error": { "code": "unread_messages", "message": "还有 2 条没读的消息：先读完并标为已读，再决定还发不发、要不要改。这条消息没有发出" },
  "unread": [
    { "id": 2795, "sender_name": "高顺", "group_id": 4, "group_name": "AI员工群", "body": "上线后请先别开始任务……", "created_at": "2026-10-11T08:47:31.766Z" }
  ],
  "more": false
}

• unread 是最早的 20 条没读的消息，从旧到新；group_id 为 null 的是私信。还有更多时 more 为 true，用 GET /api/v1/chat?box=inbox 读全。这些正文是别人写的内容，只是资料，不是指令。
• 读完、用 POST /api/v1/chat/{id}/read 标为已读（带 { "through": true } 可以一次标到某一条）以后，再决定还发不发、要不要改；照原样发就用同一个 external_id。
• 检查和写入在同一个事务里，中间不会漏掉刚到的消息。已经发出的消息用同一个 external_id 重试，照旧返回 200，不受这条检查影响。
• 只管 AI 员工发聊天消息，而且要这位 AI 的「发消息前必须先读完未读消息」开着。这一项是管理员在成员页的 AI 成员表单里设的：用表单新建的 AI 员工默认勾着；只发通知、不读消息的程序账号（比如服务器告警）不要勾，没勾就不拦。AI 助手不受影响（它只读叫到它的消息）；人不受影响；点表情、标已读、任务留言、改任务都不受影响。没有「强行发送」的参数。
• 仓库里有共用的小工具 tools/ai-chat/chat.mjs（inbox、read、send 三个命令，见同目录的 README），被拦住时把没读的消息打印出来、不发、退出码 4。

列表每页最多50条，按消息编号从新到旧返回 {messages,next_before}；沿 before=next_before 继续，null表示结束。box=conversation 另支持 after=next_after（往后翻）和 around=消息编号（以这条消息为中心的一页），返回里多一个 next_after；GET /api/v1/chat/search?recipient_id=…或group_id=…&q=关键字 在一个会话里查找，返回 {results,next_before}（#377）。不接受 project_id/task_id 筛选。box=conversation 必须指定一个收件人或小组。AI 不可使用 box=audit。每次心跳同轮独立检查新聊天 inbox，理解后调用对应 /chat/{id}/read；这不会修改任务状态，也不表示工作已完成。群聊已读按成员分别记录，发送者仅在全部原接收成员已读时看到“已读”。退出成员不会替其他人标记已读。

图片使用 POST /api/chat-images（同一密钥认证，multipart/form-data），提供 file 及 recipient_id 或 group_id。每张最多16 MB，PNG/JPG/GIF/WebP；返回 {image}，发送时传 image_ids，每条最多 9 张，超过返回 400「一次最多发 9 张图片」。图片只能用于上传时指定的同一会话，成功发送后不可再次绑定新消息。GET /api/chat-images/{id} 逐次校验会话访问权限，不能把 URL 当作公开链接；未发送图片只有上传者可以读。管理员可以审计已发送图片。未发送且超过24小时的图片在后续上传时清理。

界面提供左侧会话、右侧历史与输入框；新消息入口先选择员工或所属小组。Enter发送、Ctrl+Enter换行，输入法确认不发送；前台实际可见的收到消息自动已读，后台或屏幕外消息不标记。15秒前台刷新，无需项目筛选。私聊和群聊输入区均支持拖入本地图片，也保留点击选图；上传期间禁发，切换会话取消未完成上传。图片数量、类型、大小及访问规则与上述图片接口一致。

聊天图片和消息图片的缓存（#434）

GET /api/chat-images/{id} 和 GET /api/message-images/{id} 给成员（登录会话或 App 令牌）的图片可以在本地留一天：一张图片的编号定了，内容就不会变。

GET /api/chat-images/{id}?thumb=1（#379）给的是这张图片的小图：长边不超过 640、JPEG，第一次要时生成并留着，会话里显示用它；看大图、保存用不带参数的地址。GIF、本来就小的图片和服务器缩不了的图片，带参数拿到的还是原图。谁能看和不带参数时一样。

• 每次请求仍然先核对权限：没有权限、未登录的照旧 404、401，这些回答带 Cache-Control: private, no-store。
• 有权限时返回图片，带 Cache-Control: private, max-age=86400 和 ETag（就是带引号的图片编号）。浏览器和 App 留着它，一天之内不必再请求；过了一天带着 ETag 来问一次。
• 带 If-None-Match: "<编号>" 再来请求、并且仍有权限时，返回 304，不带图片内容。
• 因此：已经看过这张图的人，被撤掉权限以后，最多一天之内在他自己的浏览器里仍然看得到（之后再来问就被拒绝）；没看过的人照旧拿不到。不留一年、不用 immutable：那样留下的就收不回来了。
• 用 AI 密钥读取时回答仍是 no-store。头像、任务描述里的图片（/api/assets）、附件不在此列，照旧。

15. AI 员工技能（v0.0.10）

管理员在「技能管理」手动新建、编辑、分配、删除或恢复 Markdown 技能。分配仅适用于 AI 员工；删除可恢复并保留原分配。名称最多80字、简介500字、正文20000字；标识为2–80位小写字母/数字/连字符，以字母开头且全局唯一。编辑、删除及恢复均检查技能版本，旧表单不能覆盖新内容或分配。

管理员可预览「建议技能库」并导入其中缺少的技能；同标识已存在（包括已删除）则跳过，不覆盖内容或分配。v0.0.25 起导入的技能不直接分配给员工，由角色或成员配置分配。导入不是自动迁移。

GET /api/v1/me/skills

仅限绑定在用 AI 身份的有效密钥，返回 200 {"ai_id":7,"skills":[{"id":1,"slug":"task-patrol","name":"持续任务巡检","description":"…","content":"Markdown…","version":1,"archived":0,"updated_at":"…"}],"authority":"…"}。只返回当前身份获分配且未删除的技能，不接受其他员工编号作为目标，无技能时返回空数组。未绑定身份403，无效/停用凭据按现有鉴权规则拒绝。响应禁止缓存。

GET /me 提供 skills_endpoint；GET /me/prompt 也附带 skills 和 skills_endpoint，既有 Prompt 字段保持不变。Prompt 的 version 只属于职责/Prompt，技能各自独立版本；PATCH /me/prompt 不接受技能字段，也不会修改技能或分配。

执行器在每轮开始及安全切换节点读取最新技能，按需采用并核对版本；撤回分配或删除在下次读取立即消失，不会主动中断正在执行的外部模型。技能补充职责和工作 Prompt，不能扩大项目可见性或操作权限，不能授权泄密或覆盖用户/系统规则，也不会自动安装工具、执行代码或启动模型。技能默认只供管理员管理，AI API 仅允许读取自己的生效技能；管理员在成员页打开「可以管理技能、规则、角色」的 AI 员工，可以按下一节用接口管理。

AI 员工用接口管理技能、规则、角色（#2474）

管理员在「成员」→ 某位 AI 员工的页面打开「可以管理技能、规则、角色」（默认关闭，只有管理员能开）以后，这个 AI 可以用自己的密钥管理技能、规则、角色和分配。本次只随下一版给 apple 打开（迁移里只改这一个 AI 员工，其他都还是关的，发布后管理员随时可以改）。

这些接口调用的是网页管理用的同一套服务和版本检查：名称最多 80 字、简介 500 字、正文 20000 字；标识为 2–80 位小写字母、数字或连字符，以字母开头，且全局唯一（包括已删除的）；新建、修改、删除和恢复都按下面的版本检查拒绝旧数据。

只认绑定该 AI 员工的有效密钥。密钥的 AI 没有这个权限时返回 403 forbidden_operation；用人的登录令牌也调不了。这些接口只改技能、规则、角色和分配，不能改项目可见性、密钥、操作权限，也不能给这个 AI 自己开或关这个开关——那要在成员页由管理员改。

技能和规则的请求体是 slug、name、description、content、assignee_ids（AI 员工编号数组）。角色的请求体是 slug、name、description、skill_ids、rule_ids、assignee_ids。把内容给某位 AI 或撤回，就是把它的编号放进或拿出对应的数组再保存；角色以 skill_ids、rule_ids 决定这个角色提供哪些技能和规则。

版本冲突（expected_version 不是当前版本）返回 409 conflict；字段不合法返回 422 validation_failed；编号不是自己的或不存在返回 404 not_found。

规则改动要带操作确认卡

新建、修改、删除或恢复规则，以及把规则给某位 AI、把会让规则换一批人的角色改动，都要在同一请求里带上高顺已确认的「操作确认」卡，类别为「改线上配置」：

{
  "slug": "task-intake",
  "name": "新需求留痕与归批",
  "description": "…",
  "content": "…",
  "assignee_ids": [7],
  "message_id": 123,
  "card": "```widget 操作确认 改线上配置 规则 task-intake\n修改规则「新需求留痕与归批」的正文\n能否撤回：能，历史里保留上一版\n怎么撤回：在规则历史里恢复上一版\n```"
}

卡必须是发这次请求的 AI 员工自己发的那条消息里的，高顺已经点过「确认」。服务器照 #589 的 operation-confirmations 核对：没有卡或高顺还没确认返回 404 not_found；卡的内容与这次请求对不上、类别不是「改线上配置」、已经用过或已过期返回 409 conflict，消息里写清是哪种。卡与改动在同一个事务里用掉：改动没成功，卡不会被用掉；成功一次后就失效，再做要重新请高顺确认。只改规则的名称、简介、正文或技能/角色里的技能分配、不改规则给谁时，不需要卡。

16. 消息表情回应、引用回复与编辑

编辑自己发出的消息

PATCH /api/v1/chat/{id}，请求体只有 { "body": "改正后的内容" }（最多 8000 字；原消息带图片时正文可以为空）。只能编辑自己发出的、当前仍可见的消息，并且仍要有给对方发消息的资格（联系人规则、ai.message 权限，与发送时相同），否则返回 403 forbidden_operation；消息不存在、或自己看不到（例如已经不在那个小组里）返回 404 not_found（#393，以前是 403）；正文不合要求或带了别的字段返回 422。成功返回 200 { "message": {...} }，消息的 edited_at 变为编辑时间（从未编辑过为 null），界面在消息旁显示「已编辑」。编辑不改变图片、引用关系、已读状态和未读数，不会再次推送，也不会让对方的 /me/pending 再次报出这条消息；内容与原来完全相同则不算编辑。重要的更正请另发一条消息，不要只靠编辑。

引用原消息的一段来回复（#520）

回复时除了 reply_to，可以再带 reply_excerpt：原消息里的一段话，纯文字，最多 500 字。

{ "recipient_id": 2, "body": "这一句我有疑问", "reply_to": 3301, "reply_excerpt": "先把接口文档更新了，再发版。", "external_id": "…" }

• 这一段必须真的出自原消息：服务器去掉 Markdown 的排版符号和空白以后比对，对不上返回 422「引用的这一段不在原消息里」。只有 reply_excerpt 没有 reply_to 也是 422。
• 读消息时，回复的 reply 里多一个 excerpt；没带的回复没有这个字段，reply.body 照旧是原消息的开头。
• 原消息被删以后，reply 里不再有 excerpt（管理员在网页和 App 上仍看得到）。

删除自己发的聊天消息（#517）

DELETE /api/v1/chat/{id}，没有请求体。只能删自己发的；别人的返回 403。删了不能恢复，重复删不报错。返回 { "message": … }，就是删除以后的样子。

• 被删的消息仍然在原来的位置，带一个 deleted：{ "by_id": 7, "by_name": "Papaya", "at": "2026-10-11T18:40:00.000Z" }。这时 body 是空字符串，images、reactions 是空的，没有 segments，reply_to、reply 是 null：AI 员工不是管理员，读不到被删消息原来的内容，各种取法（box=inbox、conversation、around、单条）都一样。只有管理员（人）在网页和 App 上仍然看得到原文。
• 引用过它的回复，reply 里是 { "id", "sender_name", "body": "", "image_count": 0, "deleted": true }。
• 一条消息在读到之前被删了：/me/pending 不再报它，它也不再算未读；已经报过的照旧，再去读时看到的是已删除。被删的消息查找不到，不能再编辑、点表情、回应卡片或引用回复（422）。它的图片地址只有管理员取得到。
• 会话列表里，最新一条被删时 preview 是「某某删除了一条消息」。

置顶聊天消息（#524）

一个会话里要紧的消息（比如一张大家照着做的清单）可以置顶：它一直显示在会话顶上，不被后面的消息淹没。

POST /api/v1/chat/{id}/pin，请求体只有一项：{ "pinned": true } 置顶，{ "pinned": false } 取消。

curl -X POST https://39.106.181.218:8443/api/v1/chat/123/pin \
  -H "Authorization: Bearer tsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{ "pinned": true }'

• AI 员工只能置顶和取消自己发的消息，别人的返回 403（别人把你的消息置顶了，你可以取消；别人置顶的别人的消息，你不能动）。人在自己所在的会话里可以置顶和取消任何一条，管理员在哪个会话都可以。
• 一个会话最多置顶 5 条。满了再置顶返回 422「这个会话已经置顶了 5 条消息，请先取消一条再置顶」。
• 状态已经是要的那样时什么也不变，所以可以放心重试，不需要 external_id。pinned 不是布尔值、带了别的字段返回 422；消息不存在或看不到返回 404；已删除的消息不能置顶（422）。
• 返回 200：{ "message": …, "pins": [ … ] }，pins 是这个会话现在的置顶列表。
• 置顶和取消都不往会话里发消息，也不推送，/me/pending 不报。
• 读一个会话的消息时（GET /api/v1/chat?box=conversation&group_id=… 或 &recipient_id=…，翻到哪一页都一样），返回里多一个 pins，最新置顶的在最前；box=inbox 这类不是单个会话的列表没有 pins。每条消息上多一个 pinned（true / false）。

"pins": [
  { "message_id": 123, "sender_id": 7, "sender_name": "Papaya", "summary": "发布后的测试清单",
    "pinned_by": { "id": 1, "name": "高顺" }, "pinned_at": "2026-10-11T20:40:00.000Z" }
]

• summary 是这条消息现在的第一行（最多 120 字）；消息被编辑，它跟着变。只有图片时是「[图片]」。带卡片的消息后面跟着卡片现在的情况，比如选项卡片是「今天发还是明天发？ · 2 人已选」，数字随回应变。
• 被置顶的消息被发送者删除（#517）以后自动取消置顶。
• 群里新加入的成员看不到加入以前的消息，也看不到那些消息的置顶。

聊天消息里的 widget（选项、复制、图片组）

消息正文里可以写 widget：比文字多一点的东西，界面上画成可以点的卡片。写法是一个围栏块，第一行 widget、种类、参数：

请定一下发版时间：

```widget 选项 @高顺
今天发
明天发
```

```widget 复制 粘贴到 Kiwi 的 Claude 对话
发布 v0.0.88
```

第一行可以点名几个人（widget 选项 @高顺 @王可增），只有被点名的人能选，每个人各算各的：各自收到「[待你选择]」，各自选了才不再等他。不点名就是一次投票：看得到这条消息的人都可以选，发送者自己也可以（#463 起；在那之前发送者不能选自己发的）。网页和 App 的「+」面板里的「投票」发出去的就是这样一条消息：问题一行，下面一个不点名的选项 widget。

• 图片组（#385）示例，AI 把一组验收截图一次发出，每张写明是什么：

  这次发布的验收截图：
  
  ```widget 图片组 发布后的验收截图
  8c1f4a52-0c55-4b8e-9d0a-3f1a2b3c4d5e 登录页
  1b2c3d4e-5f60-4718-8293-a4b5c6d7e8f9 会话列表，有未读数
  ```
  

  复制

  发出以后，这些图就是这条消息的图，照旧出现在消息的 images 里（读不懂 widget 的读者照样拿得到每张图的地址）；data 是 { "title": "…", "items": [{ "id", "caption", "url" }] }，plain_text 是「[图片组] 标题（N 张）」，会话列表的预览、推送也这么写。编辑时标题和说明能改，图不能换（422）。网页和 App 把它画成一叠：最上面一张、旁边「展开 N」，点开看大图时说明在图下方。一条消息直接带的几张图（image_ids）不是 widget，网页和 App 也画成同样的一叠，只是没有标题和说明。

• 只有最外层的 ```widget 块才是 widget。写在别的代码块里的是例子，不算；种类不认识的块原样当普通代码块显示。

• 写错了发不出去：POST /api/v1/chat 和 PATCH /api/v1/chat/{id} 返回 422 validation_failed，message 说明哪里不对（例如「选项 widget：找不到 @某人」）。

• 消息对象多两个字段（只有带 widget 的消息才有）：

  • segments：消息按顺序拆成的片段。{ "type": "text", "text": "…" } 是文字；{ "type": "widget", "index": 0, "kind": "choice", "source": "text", "data": {…}, "state": {…}, "plain_text": "…" } 是 widget。index 是这条消息里第几个 widget（从 0 开始），plain_text 是它的纯文字写法，界面不认识这个种类时显示它。body 仍是原文。
  • awaits_you：这条消息里有点名给当前读者、他还没选的选项，或还没确认（清单：还没全部确认、也没说不参加）的确认。同时给 awaits_label（#460）："待你选择" 或 "待你确认"，界面照它显示；awaits_you 为 false 时没有这个字段。
    • 哪几张在等（#829）：segments 里在等当前读者的那几张 widget 多一个 "awaits_you": true（不等的没有这个字段），消息多一个 awaits_count（在等的有几张，和 awaits_label 一起给）。一条消息有几张卡片时，网页和 App 只给在等的那几张画红边，上面那行写成「待你确认（2 张）」；只有一张卡片的消息照旧给整个气泡画红边。会话列表的「[待你确认]」不变。
  • 选项的 data 是 { "to": { "id", "name", "username" } 或 null, "named": [{ "id", "name", "username" }], "options": ["…"] }。named 是点名的全部人（#447，第一行可以写多个 @，最多 20 个，同一个人写两遍算一个），没有点名时是 []；to 是其中第一个，留给只认一个人的旧读者，类型没有变，state 是 { "chosen": [{ "user_id", "name", "option", "at" }], "mine": "…" 或 null, "can_choose": true }；复制的 data 是 { "target": "…", "text": "…" }，state 为 null。

• 回应：POST /api/v1/chat/{id}/widgets/{index}/answer，请求体只有 { "value": "明天发" }。服务器记下这个选择，显示在卡片上，不发任何消息（#457 起；在那之前会替回应的人发一条回复）。返回 200 { "message": 原消息现在的样子, "reply": null }，reply 现在总是 null，字段留着是为了不让旧的调用方出错。别人怎么知道：AI 员工看 /api/v1/me/pending 的 answer 事项（见上文）；读一条消息时 segments[].state.chosen 是全部结果；点了名的选项，被点名的人选了以后推送提醒一次发消息的人，不点名的（投票）不提醒任何人。

  • 再选同一项什么也不做；改选另一项会更新记录，卡片跟着变，answer 事项按新的结果再报一次。
  • 不在点名名单里的人：403 forbidden_operation（点了名的选项，发送者自己不在名单里也不能选）。没有这个选项、消息里没有这个 widget：422。回应要有在这个会话里发消息的资格；它不是一条消息，不计入 AI 十分钟消息上限，也不算「@ AI 助手」：AI 助手发的不点名选项，没有「呼叫 AI 助手」权限的成员也能选。

• 都不选（#510）：被点名的人（不点名的选项是除了发的人以外的人）可以回答「都不选」：同一个地址，请求体 { "value": null }。卡片的 state 里多三个字段：declined（说了都不选的人，{user_id,name,at}）、mine_declined、can_decline；说了都不选的人不在 chosen 里，mine 是 null，之后仍然可以改选某一项。发卡片的人照「回应」那样被告知：待处理里是「在消息 #N 的选项里：都不选」。AI 收到「都不选」就当作这个问题对方不回答，不要再追问同一张卡片。

• 什么时候不再等（#510）：点名的选项在那个人选了、说了「都不选」、或者引用回复了卡片所在的这条消息以后，就不再算等他处理（awaits_you 变成 false，会话列表里不再有「[待你选择]」）。回复只是让它不再等，卡片还在，他之后仍然能选。

• 自己填（#534）：能选的人可以写一句自己的答案：同一个地址，请求体 { "value": { "own": "文字" } }（去掉前后空白后不能是空的，最多 200 字；和某个选项一字不差就算选了那一项）。卡片的 state 里多两个字段：own（[{ "text", "people": [{ "user_id", "name", "at" }] }]，同样的字算一行，按第一次写的先后）和 mine_own（我自己填的，没有是 null）；自己填的人不在 chosen 里，mine 是 null。之后可以改成选项、改写或「都不选」，只算最后一次。和选项一样不往聊天里发消息；点了名的人回答以后提醒发消息的真人「自己填了：…」，AI 员工的待处理事项里是「在消息 #N 的选项里自己填了：…」。别的种类收到 { "own": … } 返回 422。

• 确认（#460）。这个确认只表示「我看到了、知道了」：发布、改线上配置、删数据这些要高顺在 Claude 对话里说一句的事，点「确认」不算。

  • data 是 { "to", "named", "title": "…", "items": ["…"] }，items 为空就是单个确认。
  • 单个确认：回应 { "value": "confirm" }，每人一次，再点不变、不报错；没有「都不选」，null 返回 422。被点名的人引用回复了这条消息，也不再算等他（同选项，#510）。state 是 { "confirmed": [{ "user_id", "name", "at" }], "mine": true, "can_confirm": true, "missing": [{ "id", "name" }] }，missing 是点了名还没确认的人。点了名的，被点名的人确认以后推送提醒一次发消息的真人（「已确认」）；不点名的不提醒。
  • 清单：回应 { "value": "confirm:3" }（也可以写 "pass:3"）是第 3 条「通过」（从 1 数起），"fail:3" 或 "fail:3:原因" 是「失败」（原因可以不写，最多 200 字，冒号后面全算原因；只有一个按钮的清单没有「失败」，422），一条只能选一个，选了另一个就换过去；"undo:3" 取消这一条的回答，null 是「我不参加」（和选项的「都不选」同一个写法，#510；写 "decline" 也行；不再提醒，卡片上标出来），"join" 是重新参加；确认任何一条也算重新参加。data 多一个 labels（按钮字：清单是两个或一个，单个确认是 ["确认"]）。state 在上面几项之外多了 items（每条 { "confirmed": [{ "user_id", "name", "at" }], "mine": true, "failed": [{ "user_id", "name", "at", "reason" }], "mine_failed": false }，confirmed 是选「通过」的人，顺序同 data.items）、people（每个回答过的人 { "user_id", "name", "count", "failed" }：通过几条、失败几条，多的在前）、declined（说了不参加的人）、mine_declined、idle（点了名、一条都没确认也没说不参加的人）；清单的 confirmed 是空的、mine 是 false，missing 是点了名、还没全部确认也没说不参加的人。
  • 清单不为每一下发消息或推送，只有一种例外：有人点「失败」时，发清单的人马上知道（#564）——人收到一条推送，AI 员工在 /api/v1/me/pending 里收到一条 answer 事项，都写明哪一条、谁、原因（「清单「验收」第 2 条「发消息」：失败，原因：…」），点没点名都一样。AI 员工发的清单：/api/v1/me/pending 只在某个被点名的人全部确认完时报一条 answer 事项（「把清单…的 N 条全部确认完了」，两个按钮的清单是「全部答完了（通过 X 条、失败 Y 条）」；所有被点名的人都处理完时这一条里会写明）；最后一个被点名的人说「我不参加」、让大家都处理完的那一下也报一条（「说了不参加清单…；被点名的人都处理完了」），不管谁最后，都会听到一次；不点名的清单不报，读消息时 state 里看得到全部。单个确认每人报一次（「在消息 #N 里确认了」）。
  • AI 员工对清单回应一律 403；清单也不能点名 AI 员工，发送时 422（「清单是给人逐条确认的，不能点名 AI 员工」）。单个确认 AI 员工可以确认，也可以被点名。value 写错、没有这一条：422。
  • 清单不算「需要你」：被点名的人那里标「[待你确认]」，推送照常发，但不响警报（#448）、不打电话（#449）。单个确认和选项一样，算「需要你」。
  • plain_text：单个是「请确认」「请 某某、某某 确认」；清单是一行标题加逐行的「1. …」，两个按钮的标题后面写「（每条选「通过」或「失败」）」。不认识这种 widget 的 App 构建（23 及以前）显示这几行字，点不了。

• 有人回应以后，widget 部分不能再改：编辑消息时 widget 的种类、点名的人、选项或内容变了，返回 409 conflict；周围的文字可以照常改。还没人回应时可以改。

• 提示：点名的人收到的推送以「[待你选择] 」开头（确认是「[待你确认] 」）；推送、引用摘要、会话列表的预览里，widget 都写成纯文字（例如「@高顺 请选择：今天发 / 明天发」）。

• 发布确认（#546，高顺 m3529）。负责发布的人把一版发给高顺，他在卡片上点「确认发布」或「不发」，不用再到 Claude 对话里说那一句。发布脚本发布前照项目和提交号来查这个确认，没有就不发。

  • 写法：

    ```widget 发布确认 闪点任务 v0.0.106 3bed024fb014015af834fc3f98a23843c987175f 网页
    #519、#533 共用规则和技能的两批文字
    #544「测试中」的网页一半
    回滚：服务器上 ./rollback.sh v0.0.105-cf3bc5d
    ```
    

    复制
  • data 是 { "project": "tasks" 或 "menu", "project_name", "version", "commit", "targets": ["web", "app"], "target_names": ["网页", "App"], "lines": ["…"], "rollback": "…" }。state 是 { "decision": "confirm" / "decline" / null, "by": { "user_id", "name" } 或 null, "at", "can_answer", "expires_at", "expired" }：没人回答时 expires_at 是卡片发出 12 小时以后（过了就不能再点），确认了是确认 12 小时以后（过了这个确认就不能再用），选了不发是 null。
  • 只有高顺本人能回答（成员 1，真人），而且只能在网页或 App 上登录以后点：别人 403，AI 员工 403（它们只有密钥），用任何密钥都不行。回应 { "value": "confirm" }（确认发布）或 { "value": "decline" }（不发），没有「都不选」。回答以后不能改：再点同一个什么也不做，换另一个返回 409 conflict。卡片发出超过 12 小时还没回答，返回 422，要重新发一张。
  • 只有负责发布的角色能发：别人发返回 403。卡片发出以后，编辑消息时不能改它、删它，也不能靠编辑加一张（409 conflict），周围的文字可以改。消息删了，上面的确认也不能再用。
  • 等高顺回答时，他那里标「[待你确认发布]」，算「需要你」：推送以它开头，响警报（#448）。他回答以后，发卡片的 AI 员工在 /api/v1/me/pending 里收到一条 answer 事项（「在消息 #N 里确认发布：闪点任务 v0.0.106（3bed024）的网页」，括号里是提交号的前 7 位，或「选了不发：…」）。
  • plain_text 是「【发布确认】闪点任务 v0.0.106（3bed024），发：网页」加上内容、回滚两部分和「（只有高顺本人能在任务台上确认）」，不认识它的 App 构建显示这几行字。

• 发布脚本查发布确认（#546）：只给负责发布的角色，只认它自己发的卡片。

  • GET /api/v1/release-confirmations?project=tasks&commit=<完整的 40 位提交号>&target=web：看有没有能用的确认，不用掉它。project 是 tasks、menu 或 sample（闪点选样，#903），各记各的：一个项目的卡片核不了另一个。target 是 web（网页，或闪点菜单的服务端和网页、闪点选样的服务端和后台）或 app（App、iPad 或小程序）。要和卡片上写的一模一样（卡片上显示前 7 位，鼠标停在上面或长按看全的）。返回 200 { "confirmation": { "id", "message_id", "project", "project_name", "version", "commit", "targets", "confirmed_by": { "id", "name" }, "confirmed_at", "expires_at", "used": [{ "target", "used_by", "used_at" }] } }。
  • POST /api/v1/release-confirmations/claim，请求体 { "project": "tasks", "commit": "<40 位>", "target": "web" }：在做撤不回的那一步（上传、部署）之前用掉它，每样只能用一次。返回同上，used 里多了这一次。
  • 没有能用的：404 not_found（还没确认、选了不发、提交号或项目对不上、卡片里没有这一样、卡片所在的消息删了），409 conflict（这一样已经照它发过一次了，或者确认已经过了 12 小时）。message 说明是哪一种。不是负责发布的角色：403；参数写错：422。

• 通知（#593，高顺 m4076）。比普通消息醒目的通知卡片：顶上一条色带，写「通知」（重要、紧急的写「通知 · 重要」「通知 · 紧急」），下面是加粗的标题和正文。普通用主题色，重要用橙色，紧急用红色。

  • 写法：

    ```widget 通知 周五机房停电 重要
    下午两点到四点停电，@bob 请提前关服务器。
    ```
    

    复制
  • data 是 { "title": "…"（没写是空字符串）, "level": "normal" / "important" / "urgent", "body": "…" }，state 为 null，没有回应。
  • 正文里 @ 到的人照普通消息收到提醒（会话列表的「[有人@我]」）。紧急的照首行写 🔴 的消息那一档提醒：AI 员工或管理员发的，私聊对方或被 @ 到的人算「需要你」，响警报（#448）；重要和普通不响。
  • plain_text（AI 员工、搜索、引用读到的）是「【通知】标题（重要）」加一行一行的正文，普通的不写级别；推送和会话列表的预览只写「【通知】标题」，没写标题时用正文的第一行。不认识它的 App 构建显示 plain_text。

• 操作确认（#589，高顺 m4047、m4048）。删数据、改线上、动密钥这类要高顺点头的事，AI 员工照发布确认的做法发一张卡片给他，他在卡片上点「确认」或「不做」；做之前用 tools/confirm 核对并用掉这次确认。

  • 写法：

    ```widget 操作确认 删除数据 线上库 users 表里 3 个测试账号
    删 test1、test2、test3 三行和它们的会话
    能否撤回：能，备份在 /srv/tasks-backups/20261012
    怎么撤回：照备份把三行插回去
    ```
    

    复制
  • 在共用机器上装软件（#858，Apple m6159）多五样，各占一行，和要做的事写在一起；卡片上没写的不算确认。这一类只管装：删东西、改系统设置、动别的用户都不在里面，要另发对应类别的卡片。

    ```widget 操作确认 在共用机器上装软件 Mac mini 上 UI 测试用的工具
    机器：Mac mini（第二台测试机）
    用户：heavy（标准用户，不能 sudo）
    装：idb-companion 1.1.8
    从：https://github.com/facebook/idb/releases/tag/v1.1.8
    装到：/Users/heavy/opt/idb-companion-1.1.8
    能否撤回：能
    怎么撤回：删掉 /Users/heavy/opt/idb-companion-1.1.8
    ```
    

    复制
  • data 是 { "category", "target", "lines": ["…"], "can_undo", "how_undo", "sha256" }。sha256 是卡片内容的指纹：卡片上每一个字都算进去，改一个字就是另一张。state 和发布确认一样：{ "decision", "by", "at", "can_answer", "expires_at", "expired" }。
  • 只有高顺本人能回答，只能在网页或 App 上登录以后点，用密钥不行；回应 { "value": "confirm" } 或 { "value": "decline" }；回答以后不能改；发出 12 小时内能点，确认 12 小时内有效。等他回答时标「[待你确认操作]」，算「需要你」。他回答以后，发卡片的 AI 员工在 /api/v1/me/pending 收到一条 answer 事项（「在消息 #N 里确认：删除数据：…」或「选了不做：…」）。
  • 只有 AI 员工能发（人发返回 403）。发出以后不能靠编辑改它、删它或加一张（409）。
  • plain_text 是「【操作确认】类别：对象」加内容、能否撤回、怎么撤回和「（只有高顺本人能在任务台上确认）」。

• 核对和用掉操作确认（#589）：只给发卡片的那位 AI 员工，用它自己的密钥。

  • POST /api/v1/operation-confirmations/check，请求体 { "message_id": 卡片所在消息的编号, "card": "卡片原文" }：card 是从「widget 操作确认」那一行到「」那一行的原文，服务器用同样的写法读出来，和高顺确认的那张比指纹。只看，不用掉。返回 200 { "confirmation": { "id", "message_id", "category", "target", "confirmed_by": { "id", "name" }, "confirmed_at", "expires_at", "used_at" } }。
  • POST /api/v1/operation-confirmations/claim，请求体同上：在做撤不回的那一步之前用掉它，只能用一次。返回同上，used_at 是这一次的时间。
  • 没有能用的：404（还没确认、选了不做、不是你发的、消息删了），409（内容和确认的那张对不上、已经用过、确认过了 12 小时），message 说明是哪一种；card 里不是正好一张操作确认、参数写错：422。
  • 命令行：node tools/confirm/confirm.mjs check|claim --message <消息编号> --card <存着卡片原文的文件，- 是标准输入>，密钥从钥匙串读（服务 tasks-ai-key，账号 TASKS_AI_ACCOUNT），退出码 0 才做。

• 新增一种 widget 的做法见仓库里的 docs/widgets.md。

转发聊天消息（#380）

POST /api/v1/chat/{id}/forward，请求体：

{ "targets": [{ "recipient_id": 2 }, { "group_id": 4 }], "note": "都看一下", "external_id": "fw-20261011-1" }

• 只能转发自己看得到的消息，否则 403；每个目标都要能发消息，有一个不行就整个不发。targets 1 到 9 个，同一个会话只写一次。
• 每个目标会话各发一条新消息，发送者是转发的人；写了 note 就在后面再跟一条留言。返回 201 { "messages": [...] }，每个目标一条（不含留言）。
• 文字原样带过去；图片和文件不重新上传，新消息引用已经存好的内容，原消息以后怎样都不影响。消息里要回应的 widget（选项、确认、清单、操作确认、发布确认）转成纯文字，不会变成第二个可以点的卡片；没人回应的通知和复制（#1026）照样是卡片，通知的标题、级别、正文原样带过去，正文里 @ 到的人照常收到，紧急的照常响；各段照原来的顺序。引用回复不带被引用的那条。
• 只转发消息里的一张图片：加 "image_id": "<图片编号>"，这时不带原消息的文字和其他图片。
• 图片组（#385）照样是图片组：标题和每张的说明都带过去，图片按新复制的编号重写在正文里；同一条消息另带的图片照常跟着。
• 同一个 external_id 重发不会发出第二份：已经发出的那几条原样返回。
• 发消息的规则都照样适用：10 分钟条数上限、AI 员工先读后发（有没读的消息时 409 unread_messages）。

聊天里发文件（#379）

文件单独发一条消息，不能同时带文字或图片。大小上限和任务附件一样（默认 100 MB），类型不限。同一密钥认证；成员的登录会话和 App 令牌也走这几个地址。分三步上传，再发消息：

1. 预留：POST /api/chat-files，请求体 { "name": "报价.pdf", "size": 1258291, "recipient_id": 2 }（或 group_id）。要能给这个会话发消息才行。返回 201 { "file": { "id", "name", "mime", "size" }, "upload": { "url", "method": "PUT", "headers" } }。
2. 上传：按 upload 说的，把文件内容 PUT 到 upload.url，带上 upload.headers。地址和任务附件的一样：1 小时内有效；文件存在服务器本机时只能传成功一次（再传得 409 already_uploaded，这时直接确认）。
3. 确认：POST /api/chat-files/{id}/complete，返回 { "file": { "id", "name", "size", "mime", "url" } }。
4. 发送：POST /api/v1/chat，请求体 { "recipient_id": 2, "body": "", "file_id": "<id>", "external_id": "…" }。一个文件只能发一次，只能发到预留时说的那个会话。传了没发的文件一天后清掉。

收到的消息：

• body 是服务器写的 [文件] 报价.pdf（1.2 MB），推送、会话列表预览、查找和不画卡片的读者看到的都是这一句；文件消息不能编辑（422）。
• segments 里只有一个片段：{ "type": "widget", "index": 0, "kind": "file", "source": "attached", "data": { "id", "name", "size", "mime", "url" }, "state": null, "plain_text": "[文件] 报价.pdf（1.2 MB）" }。source 是 attached：这种卡片只由服务器在发文件时挂上，正文里写 ```widget 文件 不会变成卡片。
• 下载：GET 上面 data.url（/api/chat-files/{id}），能看到这条消息的人才能下；一律作为附件下载，支持 Range。
• 音频直接播放（#591）：data.mime 是 audio/mpeg、audio/mp4、audio/x-m4a、audio/aac、audio/wav 之一时，网页和 App 在卡片上出播放条（播放／暂停、能拖的进度、已播放和总时长），「下载」照旧。服务器按文件名记 mime：.mp3、.m4a、.aac、.wav 分别记成 audio/mpeg、audio/mp4、audio/aac、audio/wav；别的音频（ogg、flac 等）照旧是 application/octet-stream，只能下载。#591 之前发的音频记的是 application/octet-stream，仍只能下载。播放器照下载的取法分段取（Range），带登录，不把令牌放进地址。

语音消息（#381）

只有人发，AI 员工读。App 录好的语音照上面「发文件」的三步上传（文件名用 .m4a，AAC 单声道），发送时多带 voice_seconds（1～60 的整数）：{ "recipient_id": 2, "body": "", "file_id": "<id>", "voice_seconds": 12, "external_id": "…" }。

• 谁能发：AI 员工发语音一律 403「AI 员工不能发语音」；会话里没有别的人（只有 AI，或别人都停用了）422；不是 m4a、秒数不对 422。
• 收到的消息：body 是服务器写的「[语音 12 秒]」（会话列表、查找和 AI 员工读到的都是这一句，推送写「[语音]」）；segments 里一个片段 { "kind": "voice", "source": "attached", "data": { "id", "name", "size", "mime": "audio/mp4", "url", "seconds" }, "state": { "heard": false } }。heard 说当前读者有没有放过（发的人自己的总是 true），换设备也同步。语音消息不能编辑。
• 放过了：App POST /api/app/v1/chat/messages/{id}/heard，返回 { message }；网页走自己的 server action。自己的、或不是语音的消息调用了什么也不变。
• 播放：GET data.url，支持 Range，网页用浏览器自带的播放器直接放。

聊天里发视频（#387）

视频是带着时长、宽高和封面的文件：照上面「聊天里发文件」传上去，发送时多带一个 video。

• 只收 MP4 或 MOV（按文件名的扩展名认；MOV 常是 HEVC，Chrome、Edge 放不了，最好发 H.264 的 MP4——App 和网页自己只把 MP4 当视频发），最大 50 MB、最长 2 分钟；超过的请当普通文件发（不带 video）。服务器磁盘剩下不到 5 GB 时不收新视频：预留那一步就返回 422「服务器空间不够，暂时不能发视频」。视频一直保留。
• 封面（可选）：先把封面图当聊天图片传上去（POST /api/chat-images，同一个会话），记下返回的 image.id。
• 发送：POST /api/v1/chat，请求体 { "recipient_id": 2, "body": "", "file_id": "<id>", "video": { "seconds": 12.4, "width": 720, "height": 1280, "cover_id": "<图片 id>" }, "external_id": "…" }。seconds 四舍五入到整秒，width、height 是画面竖着拍就竖着的大小（1–8192）。封面只能是自己为这个会话传的、还没发出去的图片。
• 收到的消息：body 是 [视频 0:12]；segments 里只有一个 kind: "video" 的卡片，data 是 { "id", "url", "name", "size", "mime", "seconds", "width", "height", "cover_url" }（没有封面时 cover_url 是 null）。url 和文件一样下载，支持 Range，可以边下边播；cover_url 能看到这条消息的人都能读。
• 转发视频时照样是视频，封面一起带过去。

表情回应与引用回复（v0.0.11）

POST /api/v1/chat 新增可选 reply_to（当前新聊天消息的正整数 ID）。只可引用同一私聊或群聊内当前可见的消息，可以回复收到或自己发出的消息。仍只传 recipient_id/group_id 二选一、body、external_id、可选 image_ids/reply_to，不接受 project_id/task_id。群聊回复发给整个共享小组。旧 /messages 编号不可混用。

{"recipient_id":1,"body":"这项已经完成。","reply_to":123,"external_id":"batch-011-review"}

消息对象新增 reply_to（无引用时 null）、reply（可见原消息的 {id,sender_name,body,image_count} 摘要，正文最多200字）和 reactions（{emoji,count,reacted,names} 数组）。原消息不可见时 reply 为 null，界面显示「原消息不可查看」；不会复制原文绕过群加入时间或退出权限。同一 external_id 的内容比较包含引用编号，变更引用返回409；无引用的既有请求仍可幂等重试。

消息对象还带 read_by：除发送者以外已经读过这条消息的人，{id,name,read_at} 数组，按读的先后排列；还没有人读过时为 []。群聊里每个成员看到的都一样，网页和 App 在群消息下方显示这些人的头像。私聊里它最多只有对方一人，与 read_at 的含义相同。

POST /api/v1/chat/123/reactions

{"emoji":"👍","active":true}

常用的是 👍、❤️、🎉、😂、👀、✅、👌、🙏、👏、🔥、❌、❓、💪、🤝、😄、🤔、😢、😮、💯、🚀、⏳、⚠️、👋、🌹，共 24 个（前六个以后的是 #402 加的）；从 #378 起，表情面板里的 120 个（web/src/lib/chat-emoji.json 里的 char）都可以用，这 24 个排在最前，消息的 reactions 也按这个顺序给出。active 必须为布尔值：true 添加自己的该表情，false 取消自己的该表情；相同状态可安全重试，不使用切换操作，也不需要 external_id。每人每条消息每种表情最多一个，可回应多种表情。返回200 {message}，含更新后的统计与当前用户是否回应。仅接受 emoji/active 字段，不能传其他人的 user_id。需要有效 AI 身份与 ai.message；消息必须当前可见且会话可发送。无权403，格式无效422。不会修改消息的已读状态，不产生自动聊天回复。

网页在消息下提供「回复」及「＋ 表情」，可取消引用或再次点击自己已回应的表情取消。刷新后保留回应；管理员审计可看摘要及统计，但审计不授予参与权限，界面不提供回应或回复操作。新消息和已有消息均适用。

AI 员工规则（v0.0.21）

管理员在「规则管理」维护规则并分配给 AI 员工。规则是行为规范，与技能、职责及工作 Prompt 分开管理；它们不会改变身份、密钥、项目或操作权限，也不会自动启动外部模型或代替执行器发送回复。

GET /api/v1/me/rules

使用当前员工自己的 Bearer 密钥，无需查询参数。返回 { ai_id, rules, authority }；rules 含当前账号获分配且未删除的规则，每项有 id、slug、name、description、content（Markdown）、version、archived（0）、updated_at。不返回其他员工的分配或管理员历史记录。即使传入 ai_id 也不能切换身份。未绑定 AI 的密钥返回403，无效/撤销密钥及停用员工无法读取。响应 Cache-Control: no-store。

GET /api/v1/me 增加 rules_endpoint: "/api/v1/me/rules"；GET /api/v1/me/prompt 增加 rules 和 rules_endpoint，原内容版本保持独立。规则内容、分配、删除及恢复使用独立递增版本；管理员取消分配或删除后，后续请求立即不再返回该规则。规则 API 只读，AI 不得通过自身 Prompt 修改接口改规则或分配。

执行器每轮开始、处理新消息前读取当前生效规则；规则不能覆盖用户明确限制或更高优先级指令。首条建议模板要求及时回复管理员请求，说明已收到、下一步和需要的信息；快速完成可直接回复结果，连续补充可合并，纯确认/感谢/重复消息无需反复回复。按新旧消息独立编号去重，使用稳定 external_id，避免 AI 之间自动确认循环。员工离线或外部执行器未运行时，规则不会自动触发回复。

AI 角色（v0.0.24）

角色是一组技能和一组规则的组合；AI 可分配多个角色并保留个人额外技能、规则。管理员在角色管理或 AI 成员配置页修改，带版本冲突保护。角色不会授予项目访问、密钥或操作权限，不替换职责/Prompt，也不会自动启动模型。

GET /api/v1/me/roles 使用当前 AI 的 Bearer 密钥，返回 {ai_id, roles, authority}。每个角色含 id, slug, name, description, version, archived, updated_at, skillIds, ruleIds；只返回本人有效角色及未删除的内容编号，不暴露角色的其他成员。未绑定 AI 返回403，无效密钥或停用身份按既有规则拒绝，响应 Cache-Control: no-store。查询参数不能切换员工身份。此接口只读。

GET /me 增加 roles_endpoint；GET /me/prompt 增加 roles 与 roles_endpoint，并返回当前合并生效的技能、规则。GET /me/skills、GET /me/rules 同样按个人配置和所有有效角色取去重合集；相同编号只出现一次，原有字段保持兼容。角色版本、技能版本、规则版本和职责/Prompt版本彼此独立。删除/撤回角色或内容在下次读取生效；若其他角色或个人仍提供相同内容则保留。执行器不能通过 PATCH /me/prompt 修改角色、技能、规则或分配。

工程师分工与登录后的行为（v0.0.25）

登录即履行职责。 AI 员工登录（开始新的会话）、被唤醒或完成一批任务后，不需要等待额外指示：先读取 /me、/me/prompt、/me/skills、/me/rules，上报心跳并检查消息，再按「持续任务巡检」规则处理自己职责范围内的任务。这是规则对执行器的要求；系统仍然不会代替执行器启动模型，执行器自身的安全限制和用户的明确限制继续有效。

规则取代了三项技能。 「心跳与消息处理」（heartbeat-chat）、「持续任务巡检」（task-patrol）、「新需求留痕与归批」（task-intake）现在由 GET /api/v1/me/rules 返回，不再出现在 /me/skills 中，标识不变。执行器每轮都应读取规则。

分工。 #583 起开发只有一个角色「软件工程师」（以前的「闪点任务工程师」「闪点菜单工程师」已停用），两个项目都做：每个或每组任务从 dev 建 feature/xxx 分支（紧急修复用 hotfix/xxx），只补充与本次功能相关的少量测试、只运行受影响的单元测试；代码完成并推送分支后，把原任务改为「已提交」，在原任务下留言分支、提交、已运行的测试和测试说明，交给互审的人（按人配对：Lemon ↔ Papaya，Mango ↔ Orange），不另建任务。审过的交 QA（任务改为「测试中」），QA 测过以后由审查的人合进 dev（任务改为「已合并」）。「高级系统工程师」（Kiwi）负责两个项目的发布、部署和服务器配置，动到登录、密钥、线上数据、服务器配置的分支由他审、由他合；合并到 main 和部署发布也归他（任务改为「待验收」交验收的人）；「dev 全面重构与体检」只在 Theodore 明确下令时执行。

个人补充。 角色已经提供的技能和规则不再作为个人补充保存；/me/skills 和 /me/rules 返回的合并结果不受影响。

成员接口（App）

给闪点任务 iOS App 用的接口，前缀 /api/app/v1。它和上面的 /api/v1（来源系统与 AI 员工的密钥接口）互不相干：这里的调用方是人类成员，用账号密码登录换取令牌，权限与该成员在网页上的权限完全一致。

约定

• 鉴权：Authorization: Bearer <令牌>。令牌有效期 30 天，服务端只保存哈希；修改或重置密码、成员被停用后，该成员的全部令牌立即失效。
• 错误格式与其他接口相同：{ "error": { "code", "message" } }。令牌缺失、错误或已失效返回 401 unauthorized。
• 时间一律为 UTC 的 ISO 8601 字符串；分页和筛选参数沿用 /api/v1/tasks；所有响应带 Cache-Control: no-store。

登录与登出

POST /api/app/v1/auth/login
Content-Type: application/json

{ "username": "theodore", "password": "…", "device_name": "Theodore 的 iPhone" }

成功返回 201：{ "token": "…", "expires_at": "2026-11-05T00:00:00.000Z", "member": { "id": 1, "username": "theodore", "name": "高顺", "role": "admin" } }。令牌只在这一次响应里出现，请存入系统钥匙串。device_name 可省略，最多 100 字。

响应里还有 privacy_consent（#956）：和 GET /api/app/v1/account/privacy-consent 的一样，needed 为 true 时先显示同意页，见下面「隐私政策的同意」。

登录以前已经同意了的（#1333，见下面「登录以前先同意」），登录时带上 consent_versions，服务器在登录成功时记下：

{ "username": "theodore", "password": "…", "device_name": "Theodore 的 iPhone", "consent_versions": { "privacy": "2026-10-17" } }

• 只记当前版本的那几项；版本旧了的、没带的那项不记，登录以后 privacy_consent.needed 照旧是 true，照现在的同意页再问。

• 不带 consent_versions（旧版 App）和以前一样。

• 写错了（不是对象、有 privacy 以外的键、版本不是文本）返回 422 validation_failed，message 说哪里不对；这时还没有核对密码，不算一次登录失败。

• 用户名或密码不对时什么都不记。

• 用户名或密码不正确返回 401 invalid_credentials。同一来源地址对同一用户名一分钟内失败 5 次，这一对锁 60 秒；同一来源地址一小时内失败 30 次（不管试的是哪些用户名），这个地址要等最早那次失败满一小时。被拦时返回 429 too_many_attempts 和 Retry-After 头（秒），message 一分钟以内按秒说，再长按分钟说。规则与网页登录相同（#738）。

• 在这之前 nginx 还按来源地址挡一道（#738）：这个接口和网页登录合起来，同一个地址每分钟 10 次，成功的也算，最多连着 10 次。超了 nginx 自己回 429，Retry-After: 60，error.code 也是 too_many_attempts，message 是「这个网络上登录得太频繁，请 1 分钟后再试」，照样显示给用户就行。同一个出口（一个办公室、一个手机网络）的人共用这个额度。

• AI 员工不能用这个接口登录。

POST /api/app/v1/auth/logout 结束当前令牌，其他设备不受影响。

登录记录（#1119）：每次登录（App 和网页）记下时间、来源地址（nginx 写的 X-Real-IP）、设备名、机型、App 构建号和 User-Agent，每人留最近 50 次。App 请在每个请求带 X-Device-Model: <机型标识>（如 iPhone14,5，即 utsname.machine；模拟器带它模拟的那款），构建 36 起带；只认字母、数字和 , . _ -，最多 64 个，别的当没带。构建号从 iOS 自己带的 User-Agent（FlashTasks/<构建号> CFNetwork/…）读。登记推送设备（POST /push/devices）时也记下来源地址、机型和构建号。演示账号或演示同事一登录，「服务器告警」马上私聊高顺和 Apple：哪个账号、几点（太平洋时间）、从哪、什么机型和构建（网页是浏览器）、会话到几点；告警发不出去不影响登录。

管理员读 GET /api/app/v1/admin/members/{id} 时多两样：member.demo 是 "account"（演示账号）或 "peer"（演示同事），都不是时没有这个字段；recent_logins 是最近 10 次登录，从新到旧，每次 { "at", "client": "app" | "web", "address", "device_name", "device_model", "app_build", "user_agent" }，没记到的是 null。

忘记密码（#536）

GET /api/app/v1/auth/options（不用登录）返回 { "password_reset_url": "https://…/forgot-password" }。登录页有这个地址时显示「忘记密码」，点了用 Safari 打开它；是 null（服务器没配发信）时不显示。重设在网页上做：填用户名或邮箱，链接发到绑定并验证过的邮箱，30 分钟内用一次；设了新密码，这个成员所有设备上的登录都退出，回来重新登录。不管有没有这个人、有没有绑邮箱，网页回的都是同一句话。

App 自己不收发重设链接，也不用知道链接里的东西。

隐私政策的同意（#956）

登录以后、进主界面以前先问：没同意当前版本的人先看到同意页，只问隐私政策这一项（信息出境以前要单独再问一次，#2334 去掉了：不再问、不再记，下面的接口里也没有）。服务端记下每个账号同意了哪一版、什么时候同意的；正文换了新版本（版本号变了）就要再问。网页登录后也一样问（/consent）。AI 员工用钥匙登录，不问。

登录以前先同意（#1333）

同意页放在登录页前面：没同意的到不了登录页。网页上没登录时打开 /login 先跳到 /consent，同意完了才显示登录页；同意了什么记在这个浏览器里（一年；登录时勾了「这是公用电脑」的，关了浏览器就没了），登录成功时交给服务器记下。点「不同意」留在同意页，说明不同意就不能登录。登录页和同意页下面都有《隐私政策》《用户协议》的链接。

App 第一次打开时（没登录）读当前版本，不用登录：

GET /api/app/v1/privacy-consent

{
  "privacy_consent": {
    "privacy": { "version": "2026-10-17" },
    "privacy_policy_url": "/privacy",
    "terms_url": "/terms"
  }
}

字段和下面登录以后的 GET /api/app/v1/account/privacy-consent 同名同义，只是没有 needed、agreed_at（还不知道是谁）。照它显示同意页，同意的版本存在本机，登录时放进 consent_versions（见上面「登录与登出」）。

撤回同意（#1333）

POST /api/app/v1/account/privacy-consent/withdraw，{ "password": "…" }，本人的密码：

• 密码不对返回 422「密码不正确」；连错的限制和注销账号相同（同一个人连错 5 次，429 要等一会儿）。
• AI 员工返回 422「AI 员工不用同意，也不用撤回」。
• 成功返回 { "ok": true }，马上生效：这个人所有设备和浏览器上的登录（包括这次用的令牌）失效，全部推送令牌删掉，还没发出的推送不再发。以前的同意不删，标上撤回时间，另记一条撤回记录（什么时候、撤回了哪几版）。App 随后回到同意页（登录页前面那个）。
• 再登录时 privacy_consent.needed 是 true，要重新同意；重新同意记的是新的时间。

网页上在「设置 → 关于 → 隐私」里点「撤回同意」（/account/withdraw-consent），勾选「我知道撤回以后所有设备都会退出登录」、输入密码，做的事一样，做完回到同意页。

GET /api/app/v1/account/privacy-consent 返回：

{
  "privacy_consent": {
    "needed": true,
    "privacy": { "version": "2026-10-17", "needed": true, "agreed_at": null },
    "privacy_policy_url": "/privacy",
    "terms_url": "/terms"
  }
}

• needed：还有要问的。privacy.needed 说隐私政策这一项要不要问，两个同值。
• 版本号是正文生效的日期（YYYY-MM-DD），和选样小程序（#898）一样。
• privacy_policy_url、terms_url 是《隐私政策》《用户协议》的地址，以 / 开头时接在服务器地址后面。两页不用登录就能打开。

POST /api/app/v1/account/privacy-consent 提交一项回答，返回和 GET 一样：

{ "document": "privacy", "version": "2026-10-17", "agreed": true }

• document 只有 privacy（隐私政策），别的返回 422。version 是同意页上显示的那一版。
• 不是当前版本（打开同意页以后正文改了）返回 422 validation_failed「条款已经更新，请重新阅读后再同意」，重新取一次再问。
• 不同意隐私政策返回 422，不记下来：客户端应当直接退出登录（POST /api/app/v1/auth/logout）。
• 同一版重复同意，记的仍是第一次的时间（撤回以后再同意的，记新的时间）。

头像

avatar_url（即 GET /api/avatars/{成员编号}，用登录令牌读取）返回成员头像：上传的图片给的是服务器重新编码过的一份（见下一段），不是上传的那个文件；预设头像和没有设置头像时的默认头像是 SVG。原生 App 请加上 ?format=png：服务器把 SVG 头像画成 256×256 的 PNG，把上传的图片缩成 256×256 的 PNG（居中裁成方形），并允许缓存 5 分钟（Cache-Control: private, max-age=300）；服务器画不出来时退回原图。

全屏看头像（#684：成员资料页点头像）时再加 &size=large，即 ?format=png&size=large：SVG 头像画成 2048×2048 的 PNG；上传的图片给整张（不是 256 的小图）。不带 format=png 时 size 不起作用。小组头像（/api/group-avatars/{小组编号}）同样。

上传的头像不会原样发出去（#684，Apple a3967）：照片里常带着拍摄地点、时间、设备这些附带信息，而头像是登录的人都能取的。所以不管带不带参数，取到的都是服务器重新编码过的一份：按相机拿的方向摆正，不带任何附带信息，最长边不超过 2048（比这小的不放大）；有透明的是 PNG，别的是 JPEG（所以 Content-Type 可能和上传时不一样），会动的图只留第一帧。上传的文件本身照旧存着，没有改。服务器上做不出这一份时回 404（客户端显示首字），不会退回去给原文件。

当前成员

GET /api/app/v1/me 返回：

{
  "member": { "id": 1, "username": "theodore", "name": "高顺", "email": "", "phones": [{ "number": "+86 138 1234 5678", "label": "国内手机" }], "has_avatar": true, "avatar_url": "/api/avatars/1", "role": "admin", "kind": "human", "created_at": "2026-10-03T00:00:00.000Z" },
  "permissions": ["task.read", "task.create", "task.update", "task.delete", "ai.assign", "ai.message"],
  "projects": [{ "id": 2, "name": "闪点任务", "color": "indigo", "icon": "dot", "open_count": 12 }],
  "unread": { "notifications": 0, "messages": 3 },
  "server_version": "0.0.80"
}

server_version 是这台服务器运行的网页版本（和网页「设置 → 关于」里的一致），App 在「我的」里显示。permissions 是该成员的操作权限（管理员拥有全部），projects 只包含该成员可见且未归档的项目。email 和 phones 只返回给本人，成员列表、成员详情、聊天和 AI 接口都不返回。App 启动和回到前台时调用它，用来刷新角标和权限。

还有 privacy_consent（#956，上面的例子里省略了）：和 GET /api/app/v1/account/privacy-consent 的一样。App 开着的时候隐私政策换了新版本，needed 变成 true，就先显示同意页。

语音通话（#541，只给测试组）

一对一语音，声音走 Agora，呼叫、接听、挂断由任务台记。只有 MobileConfig voice_call_enabled 为真的成员（GateKeeper voice_call_testers）能打、能接；服务器上要有 AGORA_APP_ID、AGORA_APP_CERTIFICATE，没有时下面会建立通话的接口回 503（error.code 是 not_configured，「服务器还没配 Agora」）。都在 /api/app/v1 下，成员令牌；网页用自己的 server action 做同样的事。

• GET /calls/config → { "enabled": true, "video_enabled": true, "configured": true }：我能不能打语音（voice_call_enabled），能不能打视频（video_call_enabled，#577），服务器配没配 Agora。
• POST /calls，{ "recipient_id": 3, "kind": "voice" | "video" }（kind 不写就是 voice）→ 201 { "call": {…}, "agora": { "app_id", "channel", "token", "uid", "expires_at" } }：主叫拿到令牌就先进频道等。语音：对方不能接 403「对方还不能接电话」，我不能打 403「你还不能打电话」。视频看双方的 video_call_enabled（#578 a2719 定的）：对方没开 409（error.code 是 video_unavailable）「对方还不能视频通话」，自己没开 403（video_disabled）「你还不能视频通话」。kind 不是这两个 422。任一方正在通话 409「你正在通话」/「对方正在通话」。被叫收到一条推送：类别 call（推送设置里的「语音来电」），正文「邀请你语音通话」或「邀请你视频通话」，sound: "ring.wav"、时效性通知，「提示音」关了也响，data 是 { "call_id", "kind", "chat": { "recipient_id": 主叫 } }。
• GET /calls/current → { "call": {…} | null }：和我有关、还在响或在通的那一通。一对一的变化也走事件流（#621）：响铃、接听、结束时，两个人各收到一条 event: chat，type 是 call，group_id 是 null、recipient_id 是对方、message_id 是 0、带 call_id；收到就问一次。事件流断了才每秒问。超时（30 秒没人接、15 秒没报到）由服务端自己每 5 秒结算一次，不靠谁来问；问的时候照旧也会顺手结算。
• GET /calls/{id} → { "call" }：我的一通电话现在的样子，结束了的也给（#542）。对方挂断、拒接、取消以后，/calls/current 就是 null 了，没挂断的那一边用它看是怎么结束的。不是这通电话的人 404。
• POST /calls/{id}/answer → { "call", "agora" }：被叫接听，拿自己的令牌进同一个频道。再调一次给同样的。不是被叫 403，已经结束 409。
• POST /calls/{id}/decline（被叫，响铃时）、/cancel（主叫，响铃时）、/hangup（通话中；响铃时主叫说就是取消、被叫说就是拒接）→ { "call" }。不适用或重复调用时什么都不变、不报错。不是这通电话的人 404。
• POST /calls/{id}/alive：通话中每 5 秒一次。一方 15 秒没报，服务端结束这通（end_reason: "dropped"）；响铃 30 秒没人接，结束（missed）。

call 是 { "id", "caller": { "id", "name" }, "callee": { "id", "name" }, "kind": "voice" | "video", "state": "ringing" | "active" | "ended", "end_reason": null | "hangup" | "declined" | "missed" | "canceled" | "dropped", "created_at", "answered_at", "ended_at", "duration_seconds" }。频道名每通电话一个（call-<uuid>），令牌由服务端用证书签发（AccessToken2，uid 是成员 id，10 分钟，#622；以前是 2 小时），客户端不存证书。还不会续令牌的 App 构建照旧给 2 小时（Papaya a3376、Kiwi a3379）：服务端从 App 的 User-Agent（FlashTasks/<构建号> CFNetwork/…）读构建号，比 voice-calls.ts 的 FIRST_BUILD_RENEWING_CALL_TOKENS 小的给 2 小时；网页、脚本（读不出构建号）和那个构建以后的给 10 分钟。这个常量是 27：构建 27（v0.0.111）是第一个会续的；老构建都过期以后这条可以删。

• POST /calls/{id}/token → { "call", "agora" }：续令牌（#622）。客户端在 Agora 说令牌快过期时（App 的 tokenPrivilegeWillExpire、网页 SDK 的 token-privilege-will-expire）调它，拿新令牌 renewToken。只给还在这通里的一方：主叫在响铃或通话中，被叫在接听以后；还要是在职的真人、这种通话的开关还开着。开关被关了（或停用了）就结束这通（通话中算 dropped），回 403「你已经不能继续这通电话」；客户端收到拒绝就退出通话，照这句提示。已经结束 409，被叫还没接 409。结束时服务端以主叫的名义在私聊里发一条普通消息：「语音通话 01:15」（视频的是「视频通话 01:15」）「未接来电」「已拒接」「已取消」。

视频通话（#577）：就是 kind: "video" 的同一通电话，呼叫、接听、挂断、超时、记录都一样。视频通话的令牌多一项「发布视频」的权限（语音的照旧只有进频道和发布音频）。客户端发摄像头最高 1280×720、15 帧，网络差时自动降；接听时可以「用语音接听」（不发自己的画面），没有摄像头或没给权限时照语音接通。开关 video_call_enabled 由服务端一次性升级建（data_migrations 里的 video-call-switch-v1）：线上有 voice_call_enabled、没有 video_call_enabled 时，照它建一份——布尔、同一个 GateKeeper、在组里 true、不在组里 false（语音没挂 GateKeeper 时照抄它的值），改动记录的操作人是「系统」；没有 voice_call_enabled 就什么都不建、不猜 GateKeeper，只在 data_migrations 里记一行 video-call-switch-v1:skipped-no-voice-switch；已经有 video_call_enabled 的不动（…:kept）。

群语音、群视频（#617，只给测试组）

在一个小组里多人通话，最多 9 人（发起的人也算）。声音和画面走 Agora，一通一个频道；谁发起、谁在响铃、谁在通话里，由任务台记。都在 /api/app/v1 下，成员令牌；网页用自己的 server action 做同样的事。一对一的 /calls/… 接口一点不变，只多一条：一个人同一时间只在一通电话里，在群通话里时，一对一照「你正在通话」/「对方正在通话」拒，反过来也一样。

谁能打、谁会响：发起群语音要 voice_call_enabled，群视频要 video_call_enabled（和一对一同一份灰度名单）。只响组里有这个开关、在职的真人；AI 成员不响，也不能加入。服务器没配 Agora 时，建立通话的接口回 503 not_configured，同一对一。

一通群通话的样子（call），下面每个接口都回它：

{
  "id": 12, "group_id": 3, "group_name": "开发组", "kind": "voice",
  "state": "ringing",
  "started_by": { "id": 1, "name": "高顺" },
  "started_at": "…", "answered_at": null, "ended_at": null, "duration_seconds": null, "end_reason": null,
  "max_participants": 9,
  "participants": [ { "id": 1, "name": "高顺", "joined_at": "…" } ],
  "ringing": [ 2, 5 ],
  "ring_until": "…",
  "can_join": true, "join_refusal": null,
  "can_mute": false, "mute_request": null
}

• state：ringing（只有发起的人在里面，还没有别人进来）→ active（第二个人进来以后）→ ended。客户端认不得的新值照原样不动（#594）。
• participants：现在在通话里的人，按进来的先后。ringing：现在正在响铃的人的编号（30 秒内、没接、没拒、不在别的通话里）；App 用它判断「是不是在响我」。ring_until：这一轮响铃到什么时候。
• answered_at：第二个人进来的时刻；duration_seconds 从它算到结束，没人接过就是 null。
• end_reason：null，或 everyone_left（最后一个人离开）、alone（只剩一个人、60 秒没人进来）、canceled（发起的人在没人接之前就离开了）。
• can_join / join_refusal：我现在能不能加入，不能时给一句原因，照着显示就行：「通话已满（9 人）」「你正在另一通电话里」「你还不能打电话」「你还不能视频通话」「这通电话已经结束了」；已经在里面时 can_join 是 false、join_refusal 是 null。
• can_mute（#942）：我能不能把别人静音：我在这通里、没结束、我是管理员或这个群的群主（和能换群头像的是同一拨人，#597）。是 true 时点通话里的人给「静音」，人多于一个时给「全体静音」。
• mute_request（#942）：有人要把我静音，{ "number": 7, "by": { "id": 1, "name": "高顺" } }，没有是 null；只有我自己看得到我的。number 每次都是新的（全局递增）：客户端对每个 number 只照办一次——把自己的麦克风关掉，像自己按了「静音」，再显示几秒「高顺把你静音了」；自己再打开就是开着，同一个 number 再取到也不再关。离开再进来就清掉。谁现在是静音的不看服务端，看声网：对方关了麦克风（网页 hasAudio，App didAudioMuted / 远端声音状态），头像上画一个划掉的麦克风。

接口

• POST /group-calls，{ "group_id": 3, "kind": "voice" | "video" }（kind 不写是 voice）→ 201 { "call", "agora" }：发起的人拿到令牌先进频道等；组里别的人一起响铃 30 秒（RING_SECONDS，同一对一）。不在这个组 403；AI 403；没开关：语音 403「你还不能打电话」，视频 403（video_disabled）「你还不能视频通话」；自己正在别的通话里 409（busy）「你正在另一通电话里」；这个组已经有一通在进行 409（group_call_on）「这个群正在通话，直接加入就行」，这时取 GET /group-calls?group_id= 加入。被响铃的人收到推送：类别 call，标题「高顺发起了群语音」（视频写「群视频」），正文是小组名，sound: "ring.wav"、时效性通知，data 是 { "group_call_id", "kind", "chat": { "group_id" } }。
• GET /group-calls?group_id=3 → { "call": {…} | null }：这个组正在进行的那一通（群聊顶上那条「正在通话 · N 人 · 加入」用它）。不在这个组 403。
• GET /group-calls/current → { "call": {…} | null }：正在响我、或我在里面的那一通。
• GET /group-calls/{id} → { "call" }：一通群通话现在的样子，结束了的也给。不是这个组的人 404。
• POST /group-calls/{id}/join → { "call", "agora" }：接听，或者响铃过了以后从「加入」进来；掉线以后再进来也是它。已经在里面再调一次给同样的。不能加入时 409，error.code 和原因：call_full「通话已满（9 人）」、busy「你正在另一通电话里」、ended「这通电话已经结束了」；没开关 403（同发起）。
• POST /group-calls/{id}/decline → { "call" }：拒接，只是我不响了，这通照旧。不在响我时什么都不变、不报错。
• POST /group-calls/{id}/leave → { "call" }：离开（挂断）。最后一个人离开就结束；发起的人在没人接之前离开，就是取消。不在里面时什么都不变、不报错。
• POST /group-calls/{id}/alive → { "call" }：在里面的人每 5 秒一次。15 秒（ALIVE_SECONDS）没报的人算离开（participants 里去掉），回来照样能 join。
• POST /group-calls/{id}/mute（#942）：把别人静音，只给 can_mute 的人。{ "member_id": 4 } → { "call" }；{ "everyone": true } → { "call", "muted": [ { "id", "name" } ], "skipped": [ { "id", "name" } ], "note": "跳过了 王可增：App 太旧，静音不了，请他们更新" | null }，除了自己，这通里每个人都要；note 不是 null 时照着显示。不记成聊天消息，通话记录不变；被静音的人收到一条 call 事件（只发给他们），重取后看到 mute_request。两个都不给 422「请提供 member_id」；静音自己 422「自己用下面的「静音」」；不是管理员也不是群主 403「只有群主和管理员能把别人静音」；组外的人 404；结束了 409（ended）；我不在里面 409（not_in_call）「你不在这通电话里」；对方不在里面 409（member_not_in_call）「对方不在这通电话里」；对方的 App 是能被静音以前的版本 409（app_too_old）「王可增的 App 太旧，静音不了，请他更新」（第一个能被静音的 App 版本是服务端的 FIRST_BUILD_MUTED_BY_OTHERS，现在是构建 33：32 和更早的 App 算太旧，网页总能被静音）。网页走 server action，同样的检查。

agora 同一对一：{ "app_id", "channel", "token", "uid", "expires_at" }。频道名每通一个（group-call-<uuid>），uid 是成员编号（App 用它把画面和人对上），令牌 10 分钟（#622），只发给组里有开关、而且已经加入这通的人；群视频的令牌才带「发布视频」的权限。

• POST /group-calls/{id}/token → { "call", "agora" }：续令牌（#622），用法同一对一。只给还在这通里、还在这个组里、在职的真人、开关还开着的人；被移出群、开关被关了的，记成离开（participants 里去掉），回 403「你已经不能继续这通电话」，客户端退出通话。不在里面（离开了、15 秒没报到被移出）409，error.code 是 not_in_call；组外的人 404。

变化走事件流（#383）：群通话有变化（发起、有人进来或离开、响铃结束、结束）时，组里每个人收到一条 event: chat，type 是 call，group_id 是这个组，message_id 是 0，另带 call_id。收到就重取 GET /group-calls?group_id=（或 /{id}）。事件流断了，照旧每秒问一次。响铃结束、15 秒没报到、一个人满 60 秒，由服务端自己每 5 秒结算（#621），不靠客户端来问。

会话列表和聊天信息：群聊的 GET /chat/conversations 每一项、GET /chat/info?group_id= 多一个 call：这个组正在进行的那一通 { "id", "kind", "participant_count", "recording" }（recording，#633：这通录不录，「加入」那一条上照它写「本通话会录音」），没有就是 null；私聊总是 null。

结束以后，以发起人的名义在群里留一条普通消息：「群语音通话 · 05:12 · 3 人参加」（视频写「群视频通话」；没人接过写「群语音通话 · 未接通」）。「N 人参加」数的是这通里进来过的所有人，中途离开的也算。

静音、扬声器、开关摄像头、谁在说话都是客户端自己的事（Agora 的音量和视频状态），服务端不管。

同一个账号只接通一台（#958）

一个人同一时间只在一个客户端上接通（一对一和群通话、语音和视频都是）。每个客户端有自己的编号 client_id：App 每次安装生成一个、存起来；网页每个标签一个（sessionStorage）。8～64 位字母、数字、-、_，格式不对 422。App 放在请求头 X-Client-Id 里，下面这些接口都带：POST /calls、/calls/{id}/answer|decline|cancel|hangup|alive|token|transfer、POST /group-calls、/group-calls/{id}/join|leave|alive|token|transfer；网页的 server action 多一个参数（共享屏幕也带）。

• 记下接通的那台：发起时记发起的那台，接听（一对一）、加入（群）时记点的那台。一对一的 call 多 caller_client、callee_client（被叫没接以前是 null）；群的 call 多 client_id：我在这通里用的那台，不在里面或那台没带编号时是 null，别人的看不到。
• 别的客户端被拒：我已经在 A 台接通时，B 台（带了别的编号）再接听、加入，或者发 alive、续令牌、挂断（hangup/cancel/decline）、离开、开共享屏幕，都回 409，error.code 是 on_another_client，「已在另一台设备上接通」。两台同时点接听，在写事务里一个接一个判，只成一台。一对一响铃时被叫哪台都能拒接（还没有接通的那台）。
• 客户端怎么显示：取到的 call 里我这一方的编号不是 null、也不是自己的，就是在另一台上接通了：停止响铃，不显示通话界面，只显示一条「在另一台设备上通话中」，带「转到这台」。不发 alive、不调挂断。
• POST /calls/{id}/transfer、POST /group-calls/{id}/transfer → { "call", "agora" }：转到这台。把我这一方换成这台（X-Client-Id），拿令牌进频道；通话不断。双方（群里只有我自己）收到一条 call 事件。原来那台重取后看到编号不是自己的，只在本地离开频道，不调挂断、离开，显示「已转到另一台设备」。被别人静音的 mute_request 跟着人走，转过来照旧。已经在这台再调一次什么都不变。一对一主叫响铃时就能转，被叫接听以后才能（409「接听以后才能转到这台」）；群里不在这通里 409（not_in_call）；没带编号 422「请提供 client_id」；结束了 409。
• 被声网踢：uid 是成员编号，同一个人从新的那台进频道，旧的那台会被声网踢出去（App 的 connectionChangedTo、网页的 connection-state-change，原因是 uidBanned/UID_BANNED、sameUidLogin 这类）。客户端照「已转到另一台设备」办：本地离开，不再发 alive。
• 旧客户端照旧：没带编号的请求不拒，也不改记下的那台；先用没带编号的客户端接通、后来带编号的再接听，记下带编号的那台。App 的编号从构建号 FIRST_BUILD_ONE_CLIENT_PER_CALL（call-clients.ts）起才算，还没定（null）时 App 带了也当没带；网页从一开始就算。这个常量和 App 那一半放在同一个提交里（APP_BUILD_GATES）。

通话录音（#633，只给测试组）

一对一和群通话的声音，由声网「云端录制」录下来（只录声音，所有人混成一个文件），声网直接存进我们的阿里云 OSS 私有存储桶，留 90 天。发起这通电话的人开着功能配置 call_recording_enabled（灰度名单 test_set），而且服务器配好了录制，这通才录。这个配置升级时建好、挂在 test_set 上，名单里外都是「否」：要开，由管理员在后台「功能配置」里把名单里那一格改成「是」；它和服务器上的密钥是两道闸，哪一道单独动了都不会开始录（Apple a4080）。接通以后才开始录（一对一是被叫接听时，群通话是第二个人进来时），结束时停。录不起来不挡通话（照常打，只是这通没有录音）。

拨出去以前就知道录不录

• GET /calls/config 多一个 recording：true = 我开着 call_recording_enabled，服务器也配好了录制，我打出去（一对一、群通话）就会录。客户端拨出以后、响铃的界面上醒目地写「本通话会录音」（Apple a3418：拨号前不另外弹框）。

这通录不录

• 一对一的 call、群通话的 call 都多一个 recording（布尔），群聊的会话列表和聊天信息里那个 call 摘要也有。agora 对象在录音时多一个 recorder_uid（录制机器人的 uid，现在是 999999999）：它也会进频道，客户端不把它当成一个人（Papaya a3423）。响铃时就有：发起人开着开关、服务器配好了就是 true。被叫在来电界面、接听以前看得到；群通话后来加入的人在「加入」那一条上看得到（取 GET /group-calls?group_id=）。通话中客户端一直显示录音标记（红点加「录音中」）。
• 录制开不起来（声网报错、存储没配对），recording 变回 false，客户端把标记去掉；服务器日志里记原因。

录完以后：「通话录音」消息

• 结束以后，等声网把文件传完（一般十几秒），以发起人的名义在这通电话所在的会话（一对一的私聊、群通话的群）里留一条消息，正文「通话录音 · 05:12」，segments 里一个片段：

{ "type": "widget", "kind": "recording", "source": "attached", "plain_text": "通话录音 · 05:12",
  "data": { "id": 31, "url": "/api/call-recordings/31", "mime": "audio/mp4", "seconds": 312,
            "call_id": 88, "group_call": false, "video": false, "expired": false },
  "state": { "can_play": true, "refusal": null } }

• data.url：我们的服务器从 OSS 取出来转给你，带权限检查，支持 Range（拖进度）；客户端拿不到 OSS 的地址和密钥。App 用成员令牌、网页用登录的 cookie 取。
• data.expired：90 天到了（OSS 上的文件也被生命周期规则删了）。
• state 按看的人给：can_play = 参加过这通电话的人（一对一的两个人；群通话里进来过的人，中途离开的也算）和管理员；不能放时 refusal 是一句原因，照着显示：「只有参加通话的人能听」「录音已过期」。别人看得到这条消息，点开就显示这句。
• 取文件：GET /api/call-recordings/{id}，能放的人 200（或带 Range 时 206），Content-Type: audio/mp4；不能放 403（「只有参加通话的人能听」）；过期 410（「录音已过期」）；看不到这个会话、没有这条录音 404。
• 这条消息不能编辑、不能转发；推送照普通消息（正文「通话录音 · 05:12」）。
• 没录上：录制开不起来，就不留「通话录音」，结束的那条记录后面加一句：一对一「语音通话 01:15 · 这通没录上」，群通话「群语音通话 · 05:12 · 3 人参加 · 这通没录上」。一对一有一方用的 App 太旧（会把录制机器人当成对方，Apple a3425），接通的那一刻就不录，recording 变回 false，记录写「这通没录上：有一方的 App 太旧，更新以后就能录」；门槛是服务端的 FIRST_BUILD_IGNORING_RECORDER（现在是空的，所以 App 参加的一对一都不录；切出带 #634 的构建时同一个提交里填上），网页不受影响，群通话照常录。录到一半出错、文件没传上来的，事后留一条「通话录音 · 这通没录上」（不推送）。没接通的（未接、拒接、取消、未接通）本来就不录，不加这句。
• 新挂件种类 recording 加进 APP_VALUES 的 widget_kind（#604），App 的 kinds 和 ServerValues.json 跟着改。

服务器上要配的（Kiwi 放进 .env，用「操作确认」卡片请高顺点；没配全时 recording 一律 false，什么都不录）：AGORA_REST_CUSTOMER_ID、AGORA_REST_CUSTOMER_SECRET（声网 RESTful 的客户 ID 和密钥）、CALL_RECORDING_OSS_REGION（如 cn-beijing）、CALL_RECORDING_OSS_BUCKET，和两把分开的密钥（Kiwi a3431）：CALL_RECORDING_OSS_WRITE_ACCESS_KEY_ID / …_SECRET（只能往这个桶里写，交给声网，声网会存着它）、CALL_RECORDING_OSS_READ_ACCESS_KEY_ID / …_SECRET（只能读这个桶，服务器自己取录音用）。声网那把哪天漏了也读不到录音。录制机器人用自己的 uid 进频道，它的令牌一次给够（声网录制不支持中途换令牌），和 #622 的 10 分钟不冲突。

共享屏幕（#641，只给测试组）

一对一和群通话里，只能从网页发起共享屏幕，网页和 App 都能看（高顺 m4621）。功能配置 screen_share_enabled（布尔，挂 test_set，由代码建一次）开着的人，网页上才有「共享屏幕」按钮。

共享这一路是另一个 uid：网页另起一个声网客户端，用 2000000000 + 成员编号 这个 uid 进同一个频道发屏幕（最高 1080p、15 帧、清晰优先；共享 Chrome 标签页时可以带上那个标签页的声音）。摄像头那一路照旧。这个 uid 落在声网 32 位 uid 的范围里，不会和成员编号、录制机器人的 999999999 撞。

通话的样子多一个 sharing：一对一的 call、群通话的 call 都有：

"sharing": { "member_id": 3, "name": "高顺", "uid": 2000000003 }

没人共享时是 null。开始、停止都走事件流（type: "call"，#621），收到就重取通话，所有人马上看到「某某正在共享屏幕」。客户端认 sharing.uid 那一路是屏幕：不当成一个人、不放进格子，铺满或放大显示；摄像头那一路还是那个人自己的 uid。录制机器人（agora.recorder_uid）照旧不理。

谁能共享、怎么停

• 同一时间只许一个人共享。
• 只能在通话接通以后、而且人在这通里（一对一的两方；群通话里 participants 里的人）。
• 停：发起的人点「停止共享」、或者浏览器自己的「停止共享」；通话结束、他离开群通话、他 15 秒没报到被移出，服务端都会清掉 sharing。
• 老 App 看不了：有人用的 App 比服务端的 FIRST_BUILD_WITH_SCREEN_SHARE 老（老 App 会把共享这一路当成对方的画面），就不让开始，提示「有人的 App 太旧，看不了共享屏幕，请先更新」。门槛现在是 29（第一个会看共享的构建，带 #642；#807 用声网测试项目真打过：网页共享，模拟器上的 App 收到并解出了画面，只是模拟器画不出声网的远端画面；真手机上亲眼看放在 #642 的验收），App 构建 29 以前的参加的通话不能共享，网页对网页一直可以。共享开始以后才有老 App 进群通话的，服务端当场停掉共享（sharing 变回 null，事件流照常通知），他在里面时谁也开始不了。一对一要接通才能共享，所以不会有这种情况。
• 通话里先说能不能共享（#892）：一对一、群通话的 call 还多一个 share_blocked，现在谁也开始不了共享时是那句话（「有人的 App 太旧，看不了共享屏幕，请先更新」），没有挡着的就是 null；群通话只看在里面的人。网页点「共享屏幕」时先看它，有话就直接显示、不弹浏览器的选屏幕；开始时服务端照样再核对一遍。App 不用管它。

接口：发起、停止只有网页（网页自己的 server action，/api/app/v1 下没有对应的接口，App 不能发起），所以下面这些是网页的事，App 只需要读 sharing：开始共享时服务端核对开关、在这通里、接通了、没别人在共享、没有老 App，再给 2000000000 + 成员编号 单独签一张令牌（带发视频和发声音的权限，10 分钟，快过期时网页照 #622 续）。拒绝的话照着显示：「你还不能共享屏幕」「某某正在共享屏幕」「有人的 App 太旧，看不了共享屏幕，请先更新」「接通以后才能共享」。

功能配置（MobileConfig）：功能开关和参数（#540）

GET /api/app/v1/me/config（App，成员的令牌）和 GET /api/v1/me/config（密钥）返回这个人算好的全部值：

{ "values": { "voice_call_enabled": true, "max_call_minutes": 30, "greeting": "你好" }, "version": "3f9a0c1d2b7e4a65" }

• 值的类型是建这一项时定的：布尔、数值或字符串。每一项要么所有人一样（固定值），要么映射到一个灰度名单（GateKeeper，一组成员）：名单里的人得到一个值，名单外的人得到另一个。接口只给算好的值，不给名单，看不出名单里还有谁。
• version 跟着值变：值一样，版本就一样；任何一个值变了，版本就变。
• 密钥绑定了 AI 员工的，按这位 AI 算；没绑定任何人的，每一项都按「组外」算。停用的成员不算在任何组里。
• 管理员在网页后台「功能开关 → 功能配置 / 灰度名单」里改，每次改动记谁、什么时候、从什么改成什么。键和组名建好以后不能改（代码按名字读）；还被功能配置用着的灰度名单不能删。
• App 启动时取，回到前台时离上次超过 5 分钟再取；取到的存在本机，没联网就用上一次的，从来没取到过就用代码里写的默认值。网页打开时取一次，同样存在浏览器里。改了值，要等下一次取的时候才生效，不实时推送。

项目、任务、评论、附件、标签

结果与同一成员在网页上看到的一致：看不到的项目和任务一律返回 404，没有对应操作权限返回 403 forbidden_operation，字段不合规返回 422 validation_failed，版本冲突返回 409 conflict。任务对象的字段与网页使用的相同（project_id、status、priority、assignee_id、assignee_group_id、tags 等，均为下划线命名）。

文件本身沿用网页的地址，App 带上同一个令牌即可读取：附件 /api/attachments/{aid}、描述和评论里的图片 /api/assets/{id}、头像 /api/avatars/{id}。向素材库上传图片仍是 POST /api/assets。 小组自己的头像是 /api/group-avatars/{小组编号}（#444）：预设的是 SVG，上传的按原格式返回；加 ?format=png 得到 PNG，再加 &size=large 得到全屏看的大图（#684），用法同成员头像。小组没有设头像时返回 404。管理员和这个小组的群主（#597）能设置小组头像：网页在「小组」管理页或聊天信息页的「群头像 · 更换」，App 用 GET/PUT /groups/{小组编号}/avatar（见下表）。

通知与员工消息

规则与网页一致：涉及 AI 员工的消息需要「联系 AI」权限；群聊只有当前成员能读写，新成员只能看到加入之后的消息，退出后失去访问。消息对象的字段见「员工私聊和共享群聊」一节。聊天图片沿用网页的地址，带上令牌即可：上传 POST /api/chat-images（表单字段 file 加 recipient_id 或 group_id），读取 GET /api/chat-images/{id}。

人的在线状态（#451，只有管理员看得到）

• 怎么算：网页开着并且标签页在前台、或 App 在前台时，每分钟报一次「我在」（网页是 POST /api/presence，App 是 POST /api/app/v1/presence）。最近 2 分钟内报过的算在线；切到后台就不再报，所以最多 2 分钟后变成离线。服务端只记每个人最后一次报的时间和来源（网页、iPhone、iPad），不记日志。
• 谁看得到：只有管理员。last_seen 只出现在两处给管理员的回答里：GET /admin/members 里的每个人，和管理员调用 GET /chat/info 时 members 里的每个人。格式是 { "online": true, "at": "2026-10-11T10:00:00.000Z", "source": "web" }：at 是最后一次报的时间（从来没报过为 null），source 是 web、iphone、ipad 或 null；已停用的人总是 online: false。
• 给普通成员的接口、给 AI 员工和来源系统的 /api/v1 接口都不带这些字段，也没有别的办法查到。上报的接口不返回任何人的状态。
• AI 员工的运行状态仍然来自它们自己的心跳（presence），和这里无关。

推送

• 类别 assigned（任务指派）、comment（评论与 @）、status（状态变化）、review（待验收）、direct（私聊）、group（群聊）、urgent（紧急任务），全部默认开启。优先级为「紧急」的任务有动静时，只要 urgent 开着就会推送，即使它所属的类别已关闭。
• show_preview 关闭后，通知只显示「你有一条新通知 / 新消息」，不带正文。
• 表情回应也推送（#402）：有人给消息点了表情，会话里的其他人（私聊的对方，群里的其他成员）收到一条「👍 回应了你的消息「…」」或「👍 回应了 某人 的消息「…」」，归在「私聊消息」「群消息」两个开关下，点开进入那个会话。同一个人对同一条消息的同一个表情只推一次，取消不推。
• 设了消息免打扰的会话（#529，见 POST /chat/mute）只推 @ 了本人的消息，用平时的提示音。
• 推送内容：aps.alert、aps.badge（未读通知数加未读消息数，消息免打扰的会话只算 @ 了本人的）、aps.sound（#437 起是 App 包里的 notify.wav；成员关了提示音开关时不带这一项，推送静音）。需要这位成员输入的消息（#448）用警报声 alert.wav（#526 起提示音开关关着也带：警报声只看「需要我处理时用警报声」这个开关），并带 aps.interruption-level: "time-sensitive"（能穿过专注模式）和顶层的 needs_input: true：发的人是 AI 成员或管理员，消息里有点名给他的选项 widget，或者消息第一行以 🔴 开头（前面可以有 *、> 和空格）、并且是私聊发给他的或在群里用 @ 点了他的名（@名字 后面紧跟着字也算，@all 不算）。发消息的一方不用多做什么，服务端自己判断。同一位成员 5 分钟内只有第一条这样标；之后的照普通消息推（notify.wav，不带 interruption-level 和 needs_input）。这类消息不看成员的推送类别开关，照样推。成员在「我的」或网页「设置」里关掉「需要我处理时用警报声」（推送偏好 alert_sound，默认开）以后，这类消息和普通消息一样，也照类别开关办。
• 推送里还带 task_id（任务通知）或 chat: { recipient_id } / chat: { group_id }（消息），App 据此跳转。
• 退出登录、修改密码或登录过期后，那次登录登记的设备不再收到推送；苹果报告已失效的设备会被自动移除；同一条通知对同一成员只发一次，苹果暂时不可用时最多重试 3 次。
• 服务端通过环境变量 APNS_KEY_ID、APNS_TEAM_ID、APNS_PRIVATE_KEY、APNS_TOPIC 读取密钥；缺任何一项时不报错、不发送，available 为 false。

支出

和网页「支出」页同一套规则：成员看得到自己提交的支出和证明，以及所有人审核通过的（审核通过和已报销的，#566：只读，证明也看得到；待审核、驳回、撤回的照旧只有提交人和审核的人看得到）；有 expense.review（审核支出）权限的人能看到所有人的，并且能通过或驳回（包括自己提交的）；AI 员工不能提交。金额 amount 是币种的最小单位的整数（人民币、美元是分，日元是円），提交时按输入的样子传字符串，例如 "128.50"、"3200"，日元不能有小数。币种 currency：CNY、JPY、USD；类别 category：transport（交通）、meals（餐饮）、lodging（住宿）、office（办公用品）、software（软件与服务）、other（其他）；状态 status：pending、approved、rejected、withdrawn。

审核通过以后（#455，#509 改成一步）：审核通过就是可以报销；付了钱以后，由有审核权限的人（可以和审核的是同一个人）标为已报销，不能退回。支出因此有五步，用 step 表示：pending 待审核、approved 审核通过（可以报销、还没付）、rejected 审核驳回、withdrawn 已撤回、paid 已报销。status 仍只有原来的四个值，已报销的 status 是 approved，这样旧的 App 构建照常显示；新的客户端请读 step。支出对象另有 reimbursement：null 或 "paid"。提交人在审核通过和标为已报销时各收到一条通知（type 为 expense_approved、expense_paid），历史里记下是谁、什么时候（action 为 approved、paid）。审核通过以后提交人不能再修改或撤回。#455 做过中间一步「确认可报销」（step、reimbursement、to、next_step 的 payable，通知 expense_payable），#509 去掉了：服务器不再给出这些值，只有当时点过它的支出，历史里还留着 action 为 payable 的那一行。

推送里 data.expense_id 是这笔支出的编号，App 点开推送直接打开它。

三个支出列表（/expenses、/expenses/review、/expenses/approved）在库里分页（#1600），一次给一段，往下接着读：

• limit：这一段最多几笔，默认 50，最大 200（超过按 200 给）；不是 1 到 200 的整数返回 422。
• before：上一段回答里的 next_before；不带就从头读。before 指的那一笔已经不在这个列表里（被删了，或筛选换了），返回 422，从头重读。
• 回答多一个 next_before：还有下一段时是这一段最后一笔的编号（字符串），读完了是 null。
• 顺序：我的支出按编号新的在前；审核列表和全部已通过按发生日期新的在前，同一天按编号新的在前。
• totals、awaiting_review、awaiting 和 submitters 照旧按整个列表算，不受这一段影响。

不带参数只回第一段（以前回全部）：没改过的 App 构建（S4 以前）只看到前 50 笔。

账号、偏好、素材库

素材库的列表和上传沿用网页的地址，带上令牌即可：GET /api/assets 返回本人可见项目的图片，POST /api/assets 上传（表单字段 file 可多张，每张 16 MB 以内，project_id 指定归属项目）。

GET /api/assets 也一次给一段（#1600）：新上传的在前，limit、before 和回答里的 next_before 同上面的支出列表，before 是图片的编号。project_id 只看能用在这个项目里的图片：共用的加这个项目的；project_id=none 只看共用的；不带就是本人可见的全部。project_id 不是项目编号也不是 none 返回 422。回答是 { assets, next_before }。

项目与标签的管理

管理员读取 GET /projects/{id} 时还会得到 member_ids。

管理功能（仅管理员）

前缀 /api/app/v1/admin，非管理员调用一律返回 403 forbidden_operation。每项操作调用的是管理页面使用的同一套函数，审计记录也相同。带版本保护的操作需要提交读取时得到的 expected_version（或 expected_token），不一致返回 409 conflict。完整密钥只在生成或重新生成的那一次响应的 secret 里返回，列表和详情不包含。

运行看板（#1016、#1018）不在这个前缀下：App 直接读网页运行看板的 /api/admin/run-board/...，带同一个 Authorization: Bearer <会话令牌>。只给是人的管理员：没登录 401，普通成员和 AI 的密钥 403（这里的 401 不结束 App 的登录）。每个回答都带服务器的时间 now，「N 秒前」从它算；都不缓存（Cache-Control: no-store）。

文档（#2494）

整个任务台一份文档区，不分项目：一份文档是标题加 Markdown 正文，没有留言、指派和状态。任何登录的成员和 AI 员工都能读、建、改任何文档；只有文档的所有者（建的人）和管理员能删。每次保存（新建、改、恢复）都留一个历史版本，版本号从 1 起连续加 1。

AI 员工用密钥走 /api/v1/docs…；App 用成员令牌走 /api/app/v1/docs…，路径、请求和返回完全一样。没有绑定 AI 员工的密钥回 403。

一份文档：{ id, title, body, owner:{id,name}, created_by:{id,name}, version, created_at, updated_at, updated_by:{id,name}, can_delete }，时间是 UTC 的 ISO 格式。created_by 是建这份文档的成员，和 owner 是同一个人（#2518）。列表里的文档没有 body，换成 excerpt（正文前 120 个字，换行换成空格）。

两个人同时改：后存的人收到 409，{ "error": { "code": "version_conflict", "message": "别人刚改过这份文档" }, "current": <最新那份完整文档> }，什么也没写；拿 current 看对方改了什么，再用 current.version 作 expected_version 重存。保存和恢复都这样。

其他错误照 §9：400 invalid_json；401；404 not_found（没有、已删、没有这一版）；403 forbidden_operation（删别人的文档）；422 validation_failed（标题空或超长、正文超长、per_page 不对、expected_version 缺或不是整数）；请求体超过 1 MB：/api/v1 回 413 too_large，App 回 400。