Agentswarm/docs/swarm/autonomous-task-generation.md

Agent 自主任务生成：提案协议（Issue #7）

状态：已接入实时 WS 主循环（去中心化重构 P3）。main.py: handle_task_proposal + WS task_proposal 分支：Agent 提案 → 审查（置信度/去重合并/每 run 预算 AGENT_PROPOSAL_BUDGET）→ ACCEPT 即入池为真实 PENDING 任务（带 lineage，source=agent_proposed，发标准 task.created）；提案生命周期存 run.metadata["proposals"]（内部遥测）。feature flag ENABLE_AGENT_TASK_PROPOSALS（构建期；cutover 转无条件）。集成测试 scripts/test-swarm-autonomous.py。本文是该机制的唯一入口。 实现：orchestrator/autonomous_tasks.py（纯模块，无 Redis / WS / FastAPI 依赖）。 测试：scripts/test-autonomous-tasks.py。 配套：任务模型见 orchestrator/task_queue.py；事件流 schema 见 ../integration/event-schema.md；派发回退对照 ../benchmark/decision-engine.md。

1. 问题与边界

Issue #7：执行单元（Agent）在工作中会发现当前共享状态缺失的工作（例如实现已落地但无测试、缺文档、需要补一个后续步骤），但运行时此前没有任何机制让 Agent 提出或补全任务。本机制补上「自底向上」的任务来源。

关键边界（务必先读）：

• 是 Agent 在提案，不是 Master 在生成任务。 Master/planner 的自顶向下分解路径已在去中心化重构中删除；本机制（自底向上提案）是蜂群唯一的分解路径。提案恒带 source="agent_proposed" 与 proposed_by_agent_id；assert_not_master_origin() 在运行时拒绝任何 proposer/trigger 名含 master/planner 的提案，防止 Master 借此路径「洗白」任务来源。
• 无条件接入（无开关）。 该机制是蜂群运行时的固有行为，无 ENABLE_* 开关（本仓即 swarm 运行时，模式选择在仓外）；main.py 的 WS task_proposal 分支与 handle_task_proposal 始终生效。
• Agent 只提案，编排器才决策。 Agent 给出自评置信度 proposal_confidence，但「收 / 拒 / 并」由编排器侧的策略函数 review_proposal 依据置信度阈值、提案预算、与现存任务去重来裁决——不调用任何模型。

2. 数据模型（orchestrator/autonomous_tasks.py）

2.1 TaskProposal

字段	说明
proposal_id	prop-<hex>，自动生成
proposed_by_agent_id	必填，提案的执行单元；为空抛错
source	恒为 "agent_proposed"（__post_init__ 硬锁，外部覆盖无效）
title / description / agent_role / required_capabilities / depends_on	拟建任务的规格
proposal_reason	Agent 为何提出（人/审计可读）
proposal_confidence	Agent 自评 0..1，构造时夹紧到 [0,1]
lineage	ProposalLineage：origin_task_id / trigger_event / shared_state_snapshot
status	ProposalStatus 枚举
merged_into_task_id	合并时记录并入的现存任务 id
decision_reason	review_proposal 写入的裁决理由

2.2 ProposalStatus（状态机）

proposed ──accept──▶ accepted ──ingest──▶ (新建 PENDING 任务)
   │
   ├──reject──▶ rejected
   ├──merge───▶ merged（并入现存任务，不新建）
   └──(超时/未处理)──▶ expired   # 枚举已定义，过期判定由集成方按预算/时限实现

ProposalLineage 三要素让被提案任务端到端可审计：来自哪个原始任务（origin_task_id）、被什么事件触发（trigger_event）、Agent 基于哪份共享状态快照推理（shared_state_snapshot，需脱敏）。

3. 策略与摄取

3.1 review_proposal(proposal, policy, existing_tasks) -> ReviewOutcome

纯函数，按序裁决，返回 ProposalDecision（accept/reject/merge）并就地更新 proposal.status 与 decision_reason：

1. 置信度下限：proposal_confidence < policy.min_confidence → REJECT。
2. 去重：与某个存活（pending/assigned/in_progress/blocked）现存任务描述相似度 ≥ dedup_similarity_threshold → MERGE 进该任务（不新建）。相似度用 description_similarity（词集 Jaccard，确定性、无模型调用、可复现）。已完成任务不作为去重目标——允许 Agent 提后续轮次。
3. 预算：policy.remaining_proposal_budget <= 0 → REJECT。
4. 否则 → ACCEPT。

ProposalPolicy 字段（min_confidence / auto_accept_confidence / remaining_proposal_budget / dedup_similarity_threshold）全部显式，集成方应从 run 的 orchestration_plan.budget 取值，不从模型读取。

3.2 ingest_accepted_proposal(proposal, *, swarm_id, root_task_id) -> dict

仅接受 ACCEPTED 提案（否则抛错），再次校验 assert_not_master_origin，产出与 task_queue.create_task 对齐的 kwargs 形 spec：description / agent_role / required_capabilities / depends_on / parent_task_id / root_task_id / source="agent_proposed" / context。完整 lineage 写入 context["proposal"]（提案人、理由、置信度、origin/trigger、快照），新任务由 create_task 落为 PENDING。默认以 origin_task_id 为 parent_task_id，将新任务挂入原 run。

本函数只产出 spec，由集成方调用 task_queue.create_task(**spec) 入队——模块本身不碰 Redis/队列，以保持纯净与可测。

3.3 生命周期事件

build_proposal_event(event_type, proposal, **extra) 与 build_lifecycle_events_for_outcome(proposal, outcome) 产出扁平 payload：恒先 task.proposal_submitted（提案这一动作本身可审计），再按裁决追加 task.proposal_accepted / task.proposal_rejected / task.proposal_merged（合并事件带 merge_target_task_id）。

事件类型常量：EVENT_SUBMITTED / EVENT_ACCEPTED / EVENT_REJECTED / EVENT_MERGED。

4. 接入现状（已无条件接入）

已落地于 orchestrator/main.py（去中心化重构，无开关）：WS task_proposal 分支 → handle_task_proposal：构造 TaskProposal → review_proposal（置信度/去重合并/每 run 预算 AGENT_PROPOSAL_BUDGET）→ ACCEPT 即 task_queue.create_task 入队为真实 PENDING 任务（带 lineage、source=agent_proposed、发标准 task.created）；提案生命周期存 run.metadata["proposals"]（内部遥测，非 Manager 事件）。这是蜂群唯一的分解路径。集成测试 scripts/test-swarm-autonomous.py。

模块本身（autonomous_tasks.py）仍是纯策略/数据层（无 Redis/WS/模型）：TaskProposal/lineage/状态枚举、review_proposal 三路裁决、ingest_accepted_proposal 映射、生命周期事件、assert_not_master_origin 守卫。

仍为后续：expired 过期判定仅定义枚举未实现；Task/SwarmRun 未加持久化提案字段（提案存于 run.metadata）；真实 Agent 执行器基于 LLM 决定「提哪些子任务」为后续（scripts/stub_agent.py 已演示种子→提案）。

5. Agent 端发送（agent/main.py）

新增一个方法（与 request_handoff 同风格），由执行器在发现缺口时调用：

async def propose_task(self, *, description, reason, confidence, origin_task_id,
                       trigger_event, shared_state_snapshot, agent_role="general",
                       required_capabilities=None, depends_on=None, title=None):
    await self.safe_send({
        "type": "task_proposal", "agent_id": self.agent_id,
        "title": title, "description": description, "proposal_reason": reason,
        "proposal_confidence": confidence, "agent_role": agent_role,
        "required_capabilities": required_capabilities or [], "depends_on": depends_on or [],
        "origin_task_id": origin_task_id, "trigger_event": trigger_event,
        "shared_state_snapshot": shared_state_snapshot, "timestamp": time.time(),
    })

并在 handle_message 的控制消息集合中加入 task_proposal_ack。

5.3 新增 Task 字段（orchestrator/task_queue.py，可选增强）

去重与审计已可由 source="agent_proposed" + context["proposal"] 承载，无需新增 Task 字段即可工作。如需一等公民查询，可选增（默认不破坏现有契约）：

• Task.proposal_id: Optional[str] = None
• Task.proposed_by_agent_id: Optional[str] = None

5.4 新增 SwarmRun 字段（orchestrator/swarm_runtime.py）

提案预算与提案台账建议落到 run 上（与 collaboration / decisions 同为内部遥测，非 Manager 事件）：

# 已提案任务台账（内部遥测，不入 HM 事件注册表）。
proposals: List[Dict[str, Any]] = Field(default_factory=list)

预算可暂存于既有 metadata["proposal_budget"]（如 §5.1 所示），无需新增字段；若要显式化可加 proposal_budget: int = 3。配套可加 record_proposal(run, proposal_dict) 方法（仿 record_decision）。

5.5 影响范围声明（PR 模板用）

• Client：否（除非同时落 §5.2 Agent 端）。
• Manager：接口不变；提案事件为内部遥测，未改 HM 事件注册表 / 回调 / 审批链 / 计费 / 审计字段语义。
• agent_swarm：是（新增 WS task_proposal 分支、派发入队、SwarmRun 遥测字段）。
• 密钥 / 计费 / 审计 / 发布链路：不涉及。

6. 测试

pip install -r orchestrator/requirements.txt -r agent/requirements.txt
..\.venv\Scripts\python.exe scripts/test-autonomous-tasks.py

模块级、无需 Redis / WS / 模型密钥：模拟 Agent 基于共享状态快照提案 → 策略 accept/reject/merge → ACCEPTED 提案产出带完整 lineage 的新 PENDING 任务 spec + 状态机转移 + 生命周期事件。当前 47 项断言全部通过。