CST-agent/docs/workers.md

多模型 worker 与编排模式

主 agent 使用强模型进行设计与验收，子 agent 按角色绑定较便宜的模型。 用户配置目录的 workers.json 可设置所有项目的默认配置；存在工作区 .agent/workers.json 时，以工作区的完整配置为准，不合并两份配置。 在工作区创建 .agent/workers.json，或者通过 TUI /agents config <JSON>、 WebUI 扩展面板的「模型与 worker 配置」保存同样的配置：

{
  "orchestrate": true,
  "max_steps": 20,
  "max_tasks": 8,
  "max_requests": 100,
  "profiles": {
    "worker": {
      "provider": "deepseek",
      "model": "deepseek-flash",
      "effort": "low"
    }
  },
  "roles": {
    "general": "worker",
    "explore": "worker",
    "plan": "worker"
  }
}

provider 必须已注册，使用其独立保存的凭据或 provider 的环境变量。 档案支持 temperature、top_p、max_tokens。不要在此文件中保存 API Key。 自定义角色 Markdown frontmatter 也可指定 profile: worker；JSON 中的角色绑定优先。 未绑定的角色继承主 agent；旧 model frontmatter 仍在原 provider 下生效。

CLI --orchestrate / --no-orchestrate 可以覆盖工作区设置。开启后主 agent 优先委派适合拆分的任务，但保留获授权的写文件和 shell 工具；简单操作可以直接执行。 规划模式和只读限制继续约束子 agent。旧 task 的只读调用可并行，可写调用串行。

V2：任务控制与异步执行

默认工具配置增加 worker_start：kind=read 路由到 explore 角色； kind=edit 路由到 general，必须提供 files 路径数组，在独立 Git worktree 中编辑； kind=external 使用受保护的串行资源。模型仍由上述 profiles/roles 配置决定， 例如 explore 绑定 DS Flash、general 绑定 DS Pro，主 agent 使用 Kimi Code。 旧 task、worker 续接和预算配置继续兼容。

异步调用返回 job_id。job_read 查看状态，job_wait 最多等待 30 秒； 主循环在未完成的作业上等待，不通过反复请求模型轮询。 主 agent 的默认 run_shell 在 250ms 内未结束时也返回作业状态。 effect=workspace 表示允许安全中断的工作区命令；未声明的外部命令默认受保护， 涉及 fastboot/adb/flash 的命令始终按受保护作业处理。这是调度约定，不是安全认证。

新消息在执行中发送时会作为纠正指令：任务版本递增，旧版本后续工具调用被拒绝， 可中断作业收到取消请求；已完成的副作用不会回滚。受保护外部操作不因普通取消被杀死， 只有用户明确强制停止或程序关闭时才强制中断。不要把强制停止用于正在刷写的设备。 状态明确记录取消来源，不能把 instruction_changed/user 等同于 timeout。 纠正后只等待当前任务版本的作业；旧版本受保护作业仍在后台时，任务报告 partial， 不把新指令卡在旧操作上，也不谎报旧操作已完成。

TUI：/task state、/task readonly、/task write、/task direct（禁止委派）、 /task auto、/task pause、/task resume、/task cancel JOB_ID、/task force JOB_ID。 暂停/恢复是权限控制，不会重放操作；恢复后发送下一条指令继续。 WebUI /task 打开任务面板；Qt 桌面/Android 共用 Tasks 面板。 面板可查看作业输出、切换约束、取消作业、预览和集成编辑结果；Qt 还提供 worker JSON 配置。 HTTP 对应 GET/POST /api/task、POST /api/jobs/cancel、POST /api/worktree。

编辑 worker 的 worker_diff 预览增量，worker_integrate 执行三方合并。 基线包含用户已有 tracked 修改及显式作用域内的 untracked 输入，使用私有 index， 不会暂存、提交或重置用户分支。集成冲突时原文件和用户 index 不变，worktree/补丁保留。 非 Git 根目录使用直接执行或兼容 task。worktree 不是恶意 shell 的完整安全边界； 可用时编辑 shell 使用系统 sandbox，集成时再检查 tracked 修改范围。

任务结果使用 completed/partial/blocked/cancelled，存在运行作业、最近动作失败或缺少 必要工具证据时不接受 completed，并最多要求一次模型修正；这不是语义正确性的证明。 长输出写入证据文件，evidence_read 按 ID、字节偏移和长度检索，避免重跑命令。 默认活跃上下文预算上限为主 agent 48k、worker 24k，保留稳定系统/工具前缀。 会话旁的 .task-v2.json 保存状态和有限事件历史，重启只展示历史，不重启外部操作。 当前每个运行时最多保留 64 个热作业槽；已结束的槽可复用，旧状态和输出保留为文件， 可继续按 job ID 查询。达到 64 个未结束作业时明确拒绝新作业。

本地验证：tests/test_runtime 覆盖版本失效、只读/委派控制、完成证据、异步等待、 保护取消、恢复配置、私有 index 与三方集成冲突；tests/test_subagent 验证模型路由和预算。 真实 API 的费用、延迟、缓存命中提升需要运行下面的付费评测，不从模拟测试推导。

单机默认

默认协作模式是 solo / legacy_workers（未设 CST_COLLABORATION 且无 open parliament meta）。本机可直接使用本节全部工具；密码 Realm 不会自动关掉它们。 仅当显式 collaboration=parliament（或已有 open parliament）时，这些工具被隐藏， 改走 parliament_note。详见 docs/parliament.md「单机默认」。

作业终态会入队完成事件：TUI 推送一行系统消息，下一模型回合注入 [cst] job … 笔记，减少盲轮询 job_wait。

任务和续接

首次通过 task 指定 agent、description 和完整 prompt，结果包含 worker_id。 再次调用 task 时传 worker_id 和新任务即可续接；历史、模型绑定与角色指令保存于 主会话目录中，重启恢复主会话后仍可使用。模型配置变化适用于新 worker。 运行中断不会自动重放工具；先检查当前文件状态再续接。

max_steps 可降低本次请求上限，不得提高角色或工作区上限。 默认每次委派最多 20 个实际模型请求，主回合最多 8 次委派、100 个子 agent 请求。 续接也算委派，重试、压缩、总结和缓存命中的请求都计数。达到上限后不再发请求， 任务返回最后可用结果与失败原因，不额外调用模型总结。下一主回合重置共享预算。

TUI /agents 查看角色和运行记录，/agents config 查看配置， /agents budget 查看当前回合总量，/agents cancel sub-1 请求取消指定 worker。 WebUI 显示 worker 模型、请求数、缓存 token 和续接/取消入口。 每次委派的使用记录追加到 sub-N.runs.jsonl；最新状态在 sub-N.json。

缓存与验证

复用 worker 保留其历史前缀。角色指令位于环境信息前，任务差异作为新消息追加。 支持缓存路由的平台使用包含工作区、模型、角色、系统提示和工具 schema 的稳定标识， 相同配置的新 worker 也可利用公共前缀。其它平台仍使用自身隐式缓存或已有缓存断点。 缓存数据未返回时显示未知，不把未知视为零命中；实际命中率取决于平台。

使用 tests/test_subagent 验证跨平台路由、持久化续接、预算、并行与取消。 真实模型验收应固定模型版本、参数和任务，对比完成率、越界操作、无效调用、请求数及缓存。 可运行 bash scripts/eval_workers.sh --provider kimi-code --model k3；设置 WORKER_EVAL_CONFIG 为配置文件路径可对比编排方案。脚本在临时目录测试限定文件修改与 长文件定位，保留输出、会话和 worker 使用记录，不删除评测材料。 建议任务包含：限定单文件修复、读取截断输出、工具失败恢复、验证结果报告和主 agent 分派验收。 不要在真实模型评测中使用生产密钥以外的敏感数据；评测会产生 API 费用。