agent-workbench/references/operations.md

运行接入

配置与部署

服务由 python3 -m agent_control.server --config <私有JSON> 启动。先构建 assets/dashboard/，生产静态根默认是其 dist/；web_root 可指向本轮明确的构建产物。

scripts/setup.py 在指定的当前账号家目录内建立私有运行根、配置与随机令牌，支持可选的自有 systemd 用户服务。不使用 sudo，不修改其他服务、网络、认证或防火墙。令牌文件权限600，运行根700，SQLite位于本地盘；不放入NFS、仓库或前端代码。

examples/control.example.json 展示配置字段。bind 必须明确为内网/回环IPv4，allowed_hosts 包含确实使用的域名与端口；title 为当前项目名称，primary_session_id 指定人类沟通会话。保留来源校验，不关闭TLS或主机身份验证来解决连接问题。

HTTP服务适合受控局域网或受保护隧道。跨不可信网络使用经过授权的TLS反向代理；公开代码仓库不意味着允许公开运行端口。服务使用单一操作员令牌，不是多租户权限系统；source标签不能证明人类批准。

API与状态

读写API使用 Authorization: Bearer <令牌>；写操作还需 X-CSRF-Token: 1。浏览器令牌只放内存，退出清理。静态资源不包含运行数据。

接口	用途
GET /api/state	任务、会话连接、事件、指标缓存、默认会话与项目标题
POST /api/sessions	注册真实会话映射；id/wp/name/role/worktree/thread_id
POST /api/session-requests	保存新会话请求，不声称已经创建
POST /api/tasks、PATCH /api/tasks/<id>	任务状态、阶段、ETA范围/依据和待决策
POST /api/messages	session_id/text/source/idempotency_key，定向消息
GET /api/messages?session_id=<id>	当前会话最近500条消息及投递状态
POST /api/worker/claim	串行领取，返回有限租期及领取身份
POST /api/worker/start、renew	记录可能产生副作用的执行开始与续租
POST /api/worker/submission	在发送前登记完整输入哈希，随后持久保存真实排队回执与观察到的turn
POST /api/worker/complete、uncertain	幂等回执或结果未知；未知停止该会话自动领取
POST /api/messages/reconcile	人工核查后显式重试/失败，须记录依据
POST /api/mirror	绑定thread的可见历史导入、更新、关联原输入/最终回复
POST /api/events	工作包汇报、方案、决策、队列回执等事件

任务状态：queued/running/blocked/waiting/completed/failed/cancelled。阶段：planning/implementation/validation/integration/done。完成任务须为done阶段。ETA包含最小值、最大值和依据；没有可靠估计时为空。

源代码与行为测试维护精确校验规则。接口没有任意命令执行能力，采集不在HTTP请求中同步运行。

GET /api/messages 的原输入行包含submission元数据。镜像只有在完整实际输入的服务端哈希、目标thread及已知turn都与登记记录一致时才能关联原消息；旧版本已投递但没有submission的消息须人工核查，不能伪造回执或重发来补登记。活跃领取中的最终回复可返回deferred，镜像不推进该项checkpoint，后续重试关联。正常输入上限32000字符；完整镜像正文及回复上限262144字符，对应请求体上限4MiB，超出明确拒绝而不截断或自动重执行。

当前会话与桥接

加载skill时默认绑定当前真实会话；用户明确要求专门入口才另建，并将其设为默认。用宿主受支持工具确认真实ID，建立项目归属与看板映射。不要把内部执行器thread和桌面会话混为一谈。

执行器使用既有模型登录。集群未认证时让本机运行worker和mirror，服务/指标留在集群；模型凭据不离开本机。远程API可用 control.transport="ssh"：配置入口账号、独立私钥、remote_client 与 remote_config。客户端使用严格主机校验，在服务端内存读取服务令牌；不把令牌或模型认证拷进前端。

desktop_queue模式向原thread使用官方codex queue发送。保存外部回执、输入哈希和观察到的turn，精确匹配完整输入，不把用户正文引用的标记当作回执。队列回执与历史的clientId并无已验证的一对一保证，不能擅自假定相等。独立exec resume遇到桌面writer锁时不得抢占；可用性必须按本机版本验收。

镜像通过官方App Server分页历史读取用户、助手可见正文和明确的跨会话汇报；排除推理与工具日志。保留外部thread/turn/item ID、来源和修订；checkpoint绑定服务端点、会话和协议版本，换目标须显式处理旧状态。网页输入与最终回复关联原队列消息，去重且能补回超时后的真实最终结果。

已开始的执行失联后不自动重跑。重启发现inflight或待对账时，先查保存的回执、原会话、现有进程和产物；不能因一个本机进程结束就认为远端操作没发生。确认原操作已完成则收敛回执，只有明确核查和批准后才重试。

对已accepted/unknown的旧投递，不在同一message下更换输入哈希重试。核查并结束旧投递后，确需再次执行时建立带新幂等键的新消息，保留旧记录与人工依据；不要通过清空数据库恢复执行。

Windows下桌面队列命令受系统命令行长度限制；过长消息与上下文明确失败，不截断用户正文后静默提交。可缩小上下文或按用户意图拆成多条消息。

指标与扩展

默认配置仅本机只读指标。远程主机必须在本地可信配置中明确列出并加入白名单，使用获准入口与身份。NFS只读挂载统计，不递归扫描工程。调度器wrapper路径由站点配置，wrapper仅接收固定采集参数。

LSF主机/队列RUN计数可能是槽位数，不能等同作业记录数量。Slurm与LSF分别显示节点状态、队列/作业汇总、错误和时间；缺命令、缺配置与无权限不补零。新指标实现受控采集器和解析回归，不能让网页提交shell文本。

定期汇报与验收

面向用户默认事件驱动，仅重大里程碑、关键结果、阻塞、关键失败、重大风险与待决策触发；普通进展合并，无变化不打扰。总控可使用正式heartbeat每10分钟进行内部巡检与会话汇总，记录真实计划ID/目标；内部巡检不固定向用户播报。项目结束且无待处理事件后暂停计划。

真实验收分别记录：认证和来源保护、消息隔离/幂等、租期/失联恢复、同一真实会话往返、原会话汇报镜像、五分页及返回刷新、窄屏、真实采集、局域网直连。模拟通过不能替代真实模型/集群测试。原业务项目仍执行其自己的测试和原生工具验收。

故障钩子

POST /api/hooks 只收认证结构事件：event_id/source、severity(info/warning/critical)、status(firing/resolved)、summary，以及可选task_id/session_id、impact、evidence字符串数组、action、next_step。来源与ID各最多128字符；摘要1000、其他说明2000、证据最多8项各1000。引用的任务或会话必须存在。正文不执行任何命令，也不能指定通知目标。

source+event_id+status持久幂等，相同故障重复不打扰；恢复必须对应原故障并保留原严重性。每次新故障使用新ID。所有事件进入总控outbox，critical额外进入人类入口。GET /api/hook-notifications读pending通知，POST /api/hooks/ack以notification_id幂等确认。GET /api/state的hooks字段显示待投递数、活动故障和最近事件；通知确认仅代表进入目标会话队列，不代表修复成功。

在桥接私有配置增加 notification_targets: {"control":"<总控真实UUID>","human":"<入口真实UUID>"}、notification_state_file（仓库外私有状态）。bridge_service同时运行notifier，保存队列回执，进程异常退出自动发关键故障，功能健康且持续成功30秒后发恢复，不把进程存活等同功能恢复。bridge-faults.json和通知状态中的health显示钩子自身失败；同一通知不因ack失败而重发，未知结果只对账。后台执行主机离线时无法保证立即通知，内部巡检负责发现失联。

显式开发检查可用 python3 scripts/hooks.py --config <私有配置> --source build --event-id <本次故障ID> --severity critical --summary "开发检查失败" --evidence "本地检查日志位置" -- <已授权程序与参数>。不使用shell，不上传原始日志或命令参数，保留原程序退出码。恢复时同ID使用 --status resolved，或运行成功的修复验证命令；包装器在私有配置旁持久保存检查生命周期；首次检查成功直接返回0，不上报不存在的恢复。钩子投递失败自身返回失败并提示核查，不隐瞒。

这是通用接入机制。集群其他服务、CI、调度作业的故障需在各自受授权检查入口接入；不自动修改站点Runner或业务服务配置。事件文字只作事实资料，不扩大修复权限。 恢复通知发送失败后组件又失去健康时，保存 uncertain_recovery/needs_reconciliation，不继续宣布恢复。先核对服务事件与原会话，再人工收敛记录；不能盲重发或复用旧故障ID启动新周期。