17 KiB
17 KiB
任务内标记工具（marker tools）
适用基线：main d129f7b 上的 feat-marker-tools 分支（本地提交，未推、
未建 PR、未部署）。本批只做四类标记工具，不要把本文档读成
“所有 Codex app 线程工具都已实现”：handoff、worktree 创建状态、
PR 检查诊断、automation、clock-sleep 都不在本批；MCP 真工具路
（同轮函数返回）也不在本批。
一句话原理
agent 不用联网、不用凭证。agent 在回合输出里写标记块，本地与 Docker 执行器都经 sandbox 的结果解析提取标记块（与 task-message 同款两处解析），可信的 worker 在 completed 轮次后执行。
异步语义（必须先讲清，否则会被当成函数调用）：
- 写块 → 回合结束 → worker 执行 → 报告拼成一条后续消息、 下一轮才回到父任务。不是同轮函数返回。
- 轮询与等待在 worker 执行期间循环查库、占 worker 槽位（与 协调员等齐同款代价）；超时或父任务被取消时中止。
- 只有 completed 轮次的块被执行；失败 / 超时 / 取消 / 配额中断 的轮次不执行；父任务执行期间被取消时也不执行。
- 拒绝只记报告与审计、不炸任务、不改目标状态。
边界：谁能用、谁不能用
- 能用：普通任务。普通任务当项目经理、自己派生员工、轮询员工、 等一批员工、取消或重试员工，走的就是这批工具。
- 不能用：goal 任务与协调员任务不解析这些标记块（只收不发）。 协调员任务本身不跑模型回合，等齐循环也不会在中途排空后续 消息做判断，所以协调员 PM 不能因此获得任务内工具。
- 容易混淆的一点：协调员的子任务本身是普通任务（不是协调员 任务），它写标记块会被解析；它的派生代数从 0 计（见“派生护栏”）。
四个工具的标记格式
task-create：新建平级主线任务
```task-create
{"name": "test-xxx", "prompt": "...", "model": null,
"effort": null, "executor": "docker"}
- 新任务是平级主线，不是子代理、不是 fork；不继承父任务历史；
环境基线继承父任务的 environment_id，但 worker 给它独立的
tenant/worktree，不动父任务的 cwd；父任务未提交的改动不会
自动带过去。
- prompt 必填、1-20000 字；name 可选、1-100 字（仅用于派生报告，
tasks 表没有 name 列，不落库、不改 prompt）；model 不做白名单；
effort 只能是 low / medium / high / xhigh / max；executor 只能是
local / docker / cloud，未指定时继承父任务。
- 只建普通任务：不通过标记建协调员任务与 goal 任务。
- 每轮最多 5 块，多余的忽略；非法 JSON、prompt 缺失/空串/超长、
name 超长、effort/executor 非法时整块跳过；正文里的行首围栏
会把块截断成非法 JSON 而被跳过（与 task-message 同款非贪婪匹配）。
### task-poll / task-read：按任务 id 轮询阅读
```text
```task-poll
{"task_id": "<目标任务 id>", "interval_seconds": 5,
"timeout_seconds": 300, "chars": 2000}
{"task_id": "<目标任务 id>", "wait_seconds": 30}
- task-read 是 task-poll 的别名；read-thread / read_thread 也是
同款别名。不传 wait_seconds 时立即读一次快照；传了则等这么久
再读一次（等价于 interval = timeout = wait_seconds）。
- interval 钳制 1-60 秒，timeout 钳制 0-3600 秒（0 = 立即快照），
chars 钳制 200-8000 字；各类块合计每轮最多 5 块。
- 轮询目标不存在、跨项目、轮询自己时，报告里写清拒绝原因，
不改任何状态。轮询目标是只读的，goal 任务也可以被轮询。
### wait-threads：一次等多个目标任务
```text
```wait-threads
{"task_ids": ["B", "C"], "interval_seconds": 5,
"timeout_seconds": 300, "chars": 2000}
- wait_threads 是同款写法；task_ids 也接受 thread_ids / threads
两个别名；去重保序。
- 每块最多 8 个目标，每轮最多 2 块。8 这个数是刻意与服务端
POST /tasks/{id}/wait 的“一次最多 8 个线程”对齐的；spawn
分支原先的每块 10 个在本批收紧到 8 个，不要再用 10。
- 并行查库：每轮查一次全部目标，不是逐个串行等超时相加；
全部终态或超时后把每目标快照一起排回父任务。
- 缺失、跨项目、等待自己的目标当场记为已处理（写清原因），
不让它们把整批拖到超时；其余目标继续等到终态或超时。
- 超时口径与服务端 /wait 不同，且是故意的：服务端 /wait 是给
外部调用方持 HTTP 连接等的，上限 120 秒；标记 wait 是 worker
在回合后直连库循环查，不持 HTTP 连接，超时钳制与 task-poll
同款（0-3600 秒），占的是 worker 槽位而不是 HTTP 连接。
两者不要混用、不要互抄上限。
### task-cancel / task-retry：取消 / 重试已存在的任务
```text
```task-cancel
{"task_id": "<目标任务 id>"}
{"task_id": "<目标任务 id>"}
- task_cancel / task_retry 是同款写法；task_id 也接受 to /
to_task_id / thread_id 别名；每种每轮最多 5 块。
- 取消复用 worker 现有的取消路径语义：取消后状态为 interrupted，
正在跑的进程组 / 容器按现有取消路径真杀，不只改库状态。
- 重试与服务端 POST /tasks/{id}/retry 对齐：仅 failed /
interrupted / merge-failed 可重试，重试时清空上一轮
result_text / error_text / actual_model、状态回 queued、
prompt 与模型等原样保留、记审计。重试本身不花模型钱，
重试后的新一轮照常计费。
- 执行顺序：创建 → 取消 → 重试 → 轮询 → 等待。创建在前让同一轮
刚创建的任务立刻能被轮询；控制操作在快照之前让轮询/等待读到
取消或重试后的新状态。
## 门禁（task-cancel / task-retry，缺一不可）
纯函数层（cloud/marker_tools.py check_control_gate）与 worker
权限层（worker.py _deliver_marker_tools）两道，拒绝时只记报告
与审计、不改目标状态：
1. 目标存在；同项目；不是自己。
2. 非 goal 任务（verify_command 非空或 goal_mode 为真都算 goal）。
3. 取消要求目标非终态；重试要求目标仅为 failed / interrupted /
merge-failed。已合并（merged）两者都拒绝；merge-failed 本身
是终态，所以取消拒绝、重试接受。
4. 关系二选一：目标在发送方派生链上（沿 parent_task_id 链最多
32 步能追溯到发送方），或目标 created_by 与发送方 created_by
相同。“同项目猜到 id 就能取消任何人的任务”在此被挡住。
5. 权限层：取消要求发送方创建人有项目 create_task 权限（与
服务端取消口径同款），重试要求有 approve_merge 权限（与
服务端重试口径同款）。权限检查本身抛异常时收紧到仅派生链内
可用，同创建人-only 的目标一律拒绝，并把原因写进报告。
## 派生护栏与费用
- 派生深度上限 3 代（父任务本身是派生任务时逐代计；协调员子任务
的代数从 0 计，见“边界”）；单个父任务直接派生上限 20 个
（不含协调员子任务）；超限的块跳过。
- 派生任务是独立主线：父任务完成或取消都不自动杀派生任务；
想停派生任务，用 task-cancel 或控制台 / API 显式取消它。
协调员孤儿收口只扫 coordinator_part 非空的协调员子任务，
不扫派生任务。
- 费用与配额：派生任务 created_by 跟父任务走，认领时照常过
key 门与配额门；创建时 worker 先查一次父任务配额，超限时
整轮创建跳过（排队本身不花钱，但不让超限方再批量排队）。
## 诚实边界（与服务端口径不一致处，逐条列出）
- 重试的 goal 拒绝比服务端严：服务端 POST /tasks/{id}/retry
没有单独的 goal 检查，标记重试为了不破坏 goal 循环语义，
明确拒绝 goal 目标。这是标记口径比服务端口径严，不是遗漏。
- 取消的 goal 拒绝同理：服务端取消也没有单独的 goal 检查，
标记取消同样拒绝 goal 目标。
- 服务端重试是双人门（触发人与原任务创建人任一超限即拦，
且触发人须有 approve_merge 权限）；标记重试的触发方是发送
方任务本身，其 created_by 与派生任务的 created_by 天然相同
（派生时跟父任务走），所以 worker 侧只查发送方创建人这一道
approve_merge，效果与双人门在派生链内等价；同创建人-only
的目标同样只查这一道，权限查不到时则收紧到仅派生链内。
- wait 的超时口径与服务端 /wait 不同（见上文），数量口径已
对齐到 8 个；不要把标记 wait 的 3600 秒上限套到 HTTP /wait 上。
- 本批没有 MCP 真工具：标记工具永远是异步的（下一轮才拿到
报告），做不到同轮函数返回；想做同轮返回要另搭任务级鉴权的
MCP 服务器，不在本批。
- 签名门残留：worker 的 _code_signature 只签 worker / sandbox /
coordinator / cost / server / host 共 6 个文件，新模块
marker_tools.py 不在签名候选里。本批部署时 worker.py 与
sandbox.py 本身都变了，签名门照常生效；但将来只改
marker_tools.py 的补丁不会单独触发签名门，届时要么把
marker_tools.py 加进签名候选并同步改单测的 6 个断言，要么
接受这一处缺口——本批不顺手改签名，避免动无关安全测试的
预期。
- spawn 分支的未提交半成品没有原样合并进来：本批只移植了
已提交的 task-create / task-poll / task-read 实现与未提交的
wait 解析（收紧到 8 个后接通执行），handoff / worktree /
PR 检查 / automation / clock-sleep 的解析与 send-message-to-thread
别名均未移植；spawn 工作区本身未动。
## 关键实现位置
- cloud/marker_tools.py：纯逻辑（解析、校验、快照格式化、
门禁、派生代数与直接上限计数），单测不需要 worker/server。
- cloud/sandbox.py：本地 _result_from_runner 与 Docker
_parse_host_result 两处提取标记块，worker 侧按结果
dict 里的 task_creates / task_polls / wait_threads /
task_cancels / task_retries / todo_lists / todo_creates /
todo_updates 执行。
- cloud/worker.py：_deliver_marker_tools（5 处投递点，与
_deliver_peer_messages 同款位置）、_poll_task_snapshot、
_wait_task_targets、_queue_self_followup、_marker_auth。
- cloud/tests/test_marker_tools.py：解析上限与钳制、非法块跳过、
跨项目拒绝、自操作拒绝、已终态拒绝、goal / 已合并拒绝、
重试仅三态且清空旧结果、wait 多目标终态与超时快照、派生
深度与直接上限、权限检查失败收紧。
## 待办标记工具（todo-list / todo-create / todo-update）
与上面四类同款异步语义：写块 → 回合结束 → worker 执行 →
报告拼成后续消息、下一轮才回到父任务。goal 任务与协调员
任务不解析（只收不发），所以首轮待办注入也跳过 goal 任务，
避免模型写出永远不会执行的 todo-update 块。
### todo-list：查本项目待办
```text
```todo-list
{"status": "pending", "q": "文档"}
- 不传 status 时只返回未完成项（pending / in_progress /
blocked），查已完成项须显式传 status；q 是标题/描述子串。
- 每轮最多 5 块；status 非法、q 非字符串或超长时整块跳过。
- 读权限：发送方创建人须有项目 read 权限，否则报告里写清
拒绝；报告最多列 20 条，超出写明还有几条。
### todo-create：新建待办
```text
```todo-create
{"title": "写接口文档", "priority": "high"}
- title 必填 1-500 字；description 可选 <=20000 字；
status / priority 只能是枚举值；due_at 是 epoch 秒，
>=1e11 按毫秒除 1000；task_id 关联的任务必须在本项目内，
否则整块拒绝；sort_order 整数可选。
- 每轮最多 5 块；写权限：发送方创建人须有 create_task
权限，否则拒绝。
### todo-update：改待办（最常用是改状态）
```text
```todo-update
{"id": "<待办 id>", "status": "completed"}
- id 必填，至少改一个字段；各字段校验与 todo-create 同款，
未知字段忽略；行不存在或属于别的项目时按“不存在”拒绝，
不改任何状态；completed 记 completed_at，离开 completed
清掉（复用 todos 模块状态机）。
- 每轮最多 5 块；删除不走标记块（硬删除只在控制台 /
REST DELETE 里做，避免模型误删整条）。
### 首轮注入（worker _apply_todo_injection）
- 普通任务被认领的首轮，worker 在内存副本的 prompt 前贴
一份本项目未完成待办（最多 20 条、标题截断 100 字），附
三行 todo-update 示例；原 prompt 不落库，续跑与断点续跑
不重复贴，协调员与 goal 任务跳过，无未完成待办时不贴空
章节，注入查询失败时静默跳过、不炸认领。
- 注入贴的是数据，不是完整工具指南；完整格式只在本文件里。
## 任务列表标记（task-list）与项目注入
### task-list：查本项目任务
```text
```task-list
{"status": "failed", "q": "登录", "limit": 20}
- 不传 status 时查全部状态（与 todo-list 默认只查未完成
不同——分诊首先要看到失败与运行中的任务），报告附各状态
计数；q 是 prompt 子串；limit 钳制 1-50（默认 20），
超出写明还有几条；列表按新建倒序。
- 每轮最多 5 块；status 非法、q 非字符串或超长、limit 非
整数时整块跳过；只读，发送方创建人须有项目 read 权限，
否则报告里写清拒绝；跨项目任务不出现。
- 只读不改状态：捡到失败任务后改状态走 task-retry /
task-cancel，合并与审批仍由人操作。
### 首轮项目注入（worker _apply_project_injection）
- 普通任务与 goal 任务被认领的首轮，worker 在内存副本前
贴三行项目上下文：项目名、仓库（未绑定时明写未绑定，
不编地址）、环境（有 environment_id 时写环境名/分支/
状态，否则写无）；再加一行 task-list 格式示例。
- goal 任务同时改内存里的 goal（执行器取 goal 优先于
prompt，只改 prompt 的话 goal 任务看不到）；原 prompt /
goal 不落库，协调员、续跑与断点续跑跳过，项目行查不到
或查询失败时原样返回、不贴半截上下文、不炸认领。
- 贴的是数据加一行格式示例，不是完整工具指南；完整格式
只在本文件里。注入顺序：项目上下文在最前，其次待办、
记忆，最后是原 prompt。
## 成本、配额与文件标记（task-cost / quota-status / task-files）
### task-cost：查单个任务成本（只读）
```text
```task-cost
{"task_id": "<目标任务 id>"}
- 报告：美元数（只计有价行）、总 token（actual / estimated
分列）、轮次；无价 actual token 单独列，不会被静默算成
0 美元（与 CostStore._report 同款口径）。
- 门禁比服务端只要求 read 更严：目标须在本项目内，且在
派生链内或与发送方同创建人（自己也算同创建人），防止在
项目内猜 id 看别人的花费；每轮最多 5 块。
### quota-status：查发送方创建人当月配额（只读）
```text
```quota-status
{}
- 块体必须是 JSON 对象，不接受任何参数：配额永远按发送方
任务的创建人算（创建人缺失时回查父任务，仍查不到时拒绝），
块里写别人 id 也无效。报告：总额、已用、剩余、无价
actual token；显式不限额时明写不限额，不编一个数字。
- 每轮最多 5 块；发送方创建人须有项目 read 权限，否则拒绝。
### task-files：读派生链内或同创建人任务的文件（只读）
```text
```task-files
{"task_id": "<目标任务 id>", "path": "out.txt"}
- 不传 path（或空串）时列顶层（只列前 50 项，目录名带 /）；
传相对路径读文件，上限 20000 字，超出写明截断。
- 门禁：目标须在本项目内且在派生链内或同创建人；cloud
任务与 worktree 在别机的任务拒绝（文件不在本机）；目标
没有本地 worktree 时按“没有本地 worktree”报告，不编内容。
- 路径安全：绝对路径、.. 逃逸、符号链接逃逸一律拒绝并在
报告里写清；二进制文件（解码失败或含 NUL 字节）拒绝；
worktree 解析只接受已存在的任务级目录（租户路径或
host.py 同级 work/host-worktrees），绝不把共享挂载点本身
当成目标任务的目录。
- 每轮最多 5 块；删除、写文件不走标记块（模型改文件走它
自己的执行器工作区，不是读别人 worktree 的路）。