s17 自治智能体：Autonomous Agents - Harness Engineering - 后端

# 三行速读

自治不是 “放飞”，而是 “按规则自动认领与续跑”。
空闲轮询、角色过滤、认领日志是自治三件套。
可观测与可刹车能力决定自治是否可上线。

# 先修知识

已理解 s16 的协议与状态治理。
已掌握 s12 任务图与 owner 概念。

# 读完后你应该能做到（可检验清单）

让队友自动认领符合角色的任务。
通过 claim 事件回放一次认领链路。
设计一个自治暂停 / 恢复开关流程。

# 本篇要解决什么

s15、s16 的团队依然偏 “被动分派”。s17 让队友可以在空闲时自己找活、自己认领、自己续跑。

核心目标：自治推进，但仍受规则约束。

# 用一个类比先理解

像仓库拣货员：

空闲时查看待拣清单；
按岗位规则领单；
领单后更新系统状态；
按身份完成任务。

自治不是随便抢单，而是按流程自动运行。

# 为什么这一步必须现在做

当任务量上来后，完全依赖主控逐条分派会成为瓶颈。自治机制能提高吞吐，但必须保证可追踪与可控。

# 关键代码怎么读

# 1) 自治轮询节奏

1
2
3

POLL_INTERVAL = 5
IDLE_TIMEOUT = 60
CLAIM_EVENTS_PATH = TASKS_DIR / "claim_events.jsonl"

轮询频率与空闲超时决定了自治灵敏度与资源消耗。

# 2) 可认领判定

1 2	def _task_allows_role(task: dict, role: str \| None) -> bool: ... def is_claimable_task(task: dict, role: str \| None = None) -> bool: ...

这里在做 “有边界自治”：先看任务状态，再看角色匹配。

# 3) 扫描与认领

1 2	def scan_unclaimed_tasks(role: str \| None = None) -> list: ... def claim_task(...): ...

扫描可做任务，认领后更新状态，形成自动推进闭环。

# 4) 身份上下文续接

1 2	def make_identity_block(name: str, role: str, team_name: str) -> dict: ... def ensure_identity_context(messages: list, name: str, role: str, team_name: str): ...

确保队友每次续跑都带上正确身份，不会行为漂移。

# 你可以怎么复现

准备多条可认领任务并标注角色。
启动自治队友，观察自动认领流程。
检查 claim_events 日志是否完整记录。

# 常见误区

误区 1：把自治等同于无限权限。
误区 2：没有认领日志，后续无法排查争抢。
误区 3：忽略身份恢复，导致续跑行为不一致。

# 一句话总结

s17 把 “主动推进” 能力做成受控机制，自治从概念变成可工程化流程。

# 补充解读：自治机制的 “可控性设计”

# A. `_append_claim_event` 是责任追踪点

认领事件落到 claim_events.jsonl 后，后续每次冲突都能回放 “谁何时认领了哪项任务”。

# B. `scan_unclaimed_tasks` 的过滤逻辑

它通常会过滤：已完成、已认领、角色不匹配、状态不可执行任务。过滤顺序决定了自治效率。

# C. `ensure_identity_context` 不是可选项

自治队友如果丢身份，容易在后续轮里变成 “泛化助手”，导致角色边界失效。

# D. idle 轮询不是越快越好

POLL_INTERVAL 太小会增大系统噪音，太大又降低响应速度，需要按任务密度调参。

# 进阶练习

引入 “任务抢占优先级” 策略。
给自治扫描加指标：命中率、认领率、放弃率。
增加 “认领失败重试冷却时间”。

# 再补一层：自治系统上线前的安全清单

# A. 先做 “只扫描不执行” 灰度

第一阶段只让自治队友扫描并打印将认领的任务，不真实执行。这样能先校验认领规则是否正确。

# B. 认领冲突必须可检测

即使有 claim 事件，也建议在认领前后做一次 “当前 owner 二次确认”，减少并发竞争窗口。

# C. 角色过滤建议可配置化

把角色匹配规则写死在代码里，后续迭代会很痛苦。建议逐步外置到配置层。

# D. 自治也要能 “人工刹车”

必须保留全局暂停开关，出现异常时能一键停止自治认领，防止错误扩散。

# 统一术语口径（本章）

Self-Claim ：队友按规则自主认领可执行任务。
Role Filter ：按角色能力过滤可认领任务。
Claim Event ：记录认领行为的可追踪事件日志。

# 章节衔接（从易到难）

本章解决 “自治推进能力”。
下一章 s18 进入 “并行执行目录隔离与收尾治理”。

Harness Engineering