feat: add persistent multi-model workers and orchestration budgets

docs/workers.md

@@ -0,0 +1,67 @@
+# 多模型 worker 与编排模式
+
+主 agent 使用强模型进行设计与验收，子 agent 按角色绑定较便宜的模型。
+在工作区创建 `.agent/workers.json`，或者通过 TUI `/agents config <JSON>`、
+WebUI 扩展面板的「模型与 worker 配置」保存同样的配置：
+
+```json
+{
+  "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 工具由 worker 执行。
+规划模式和只读限制继续约束子 agent。多个只读任务可并行，可写任务串行。
+
+## 任务和续接
+
+首次通过 `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 费用。