Agent-Squad/README.md

Agent-Squad

通用智能体小队编排底座：角色注册、意图/目标理解与任务拆解、动态编排执行、 黑板协同、Human-in-the-Loop（HITL）挂起与恢复。不含任何预设角色或任务模板， 一切角色/模板均通过配置文件、HTTP API、CLI 注册或由规划器现场派生。

设计参考 Multica 的 agent orchestration 理念与 Agent-System internal/squad 的成熟机制（黑板/沙箱工作区/顺序并行混合调度/动态调整），按"空表起步"通用化重写。

本仓库是该模块的源码位置。Go 模块路径为 agent-squad。依赖都在 deps/，由本仓 gitlink 固定，不随上游分支浮动：

路径	作用
deps/agent-native	智能体执行。replace agent-native => ./deps/agent-native
deps/error-code-system	HTTP 错误信封与规范码
deps/logging-system	组合根日志。trace_id 来自 X-Trace-Id，run_id 标识一次编排
deps/development-guidelines	开发规范，不参与编译

Agent-Native 自己的 deps/ 里还有一份错误码库、日志库和规范。本仓编译只使用本仓 go.mod 的 replace，嵌套目录里的 replace 不生效。scripts/submodule-consistency.sh 要求两侧 gitlink 相同，避免两份副本锁到不同提交。

克隆时带上子模块，否则无法编译。已有克隆若仍留着根目录 Agent-Native，先删掉该残留目录再初始化：

git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git
# 已克隆时：
git submodule sync --recursive
git submodule update --init --recursive

与周边仓库的关系

仓库/模块	关系
Agent-Native（本仓 submodule deps/agent-native）	智能体执行的唯一来源：角色执行经 agent-native adapters/native（自研内核 runtime 循环 + 工作区工具）或产品注册的其他 agent-native 后端（如 pi-agent）；LLM 规划器复用 runtime/llm 客户端做编排决策。本库不实现任何 Agent——只做编排与任务拆解。依赖方向 agent-squad → agent-native，反向无依赖
agent-system-multi/modules/squad（U4 产品小队暂存仓）	不在本仓，互不依赖。产品小队含医疗器械预设角色与任务键，属产品层；后续产品仓接入本底座时，预设角色/任务模板改为向本底座注册（独立一期）
主仓 internal/squad	机制语义（工作流驱动/黑板/子工作区/防篡改清单）的权威来源；本底座为通用化重写，不做逐行同步

分层

包	职责	依赖边界
squad	核心库：契约（模型/HITL）、角色注册表、蓝图注册表、规划器（rule/llm/mock）、执行引擎、黑板、沙箱工作区、事件	依赖 agent-native（exec + runtime/llm）；不依赖任何产品类型/DB
store	文件持久化：roles.d/.json、blueprints.d/.json	只依赖 squad 契约；无 DB
server	HTTP API（REST + SSE）	组合根之一，可独立 serve
cli	CLI：serve / role / blueprint / run / runs / demo	组合根之一
textextract	纯文本抽取（txt/md/json/docx + 页码锚点），纯标准库	无依赖
conformance	公开 API 全链路契约验收（含 HITL 挂起-回应）	只用公开 API

角色：创建与绑定智能体

RoleSpec 声明角色的全部设定；Backend 字段绑定执行该角色的智能体： 内置 stub（agent-native 离线桩，测试用）；真实执行用 agent-native （自研内核：多轮循环 + 读/写/编辑/检索工作区工具，经 RegisterAgentNative 注册工厂），产品也可注册 pi-agent 等外部智能体工厂。Model/ToolProfile/Skills 角色级注入——即每个角色可以用不同的智能体、不同的模型。

角色来源三种（RoleSource）：

• registered：配置文件（roles.d/*.json）/ HTTP API / CLI 手动注册；
• derived：规划器或用户按 base_role 基线现场派生（领域特化专员）；
• 运行期 minimal 引导：空注册表澄清时人工选择"最小编制"，自动注册 4 个通用角色。

未知智能体名 fail-closed（运行失败并留痕），绝不静默回落 stub。

规划：理解目标 → 拆解任务 → 分配角色

Planner 接口可插拔，内置三种实现：

规划器	机制
rule（默认，零模型依赖）	命中蓝图→基线步骤；未命中→通用四阶段骨架（梳理→专项→成文→终审），角色按 Keywords/职责推荐，缺位现场派生（派生计划需人工确认）
llm	结构化 JSON 输出：复用/派生角色清单 + 步骤 + 并行分组 + 高风险标记；解析失败重试一次后 fail-closed；信息不足时输出澄清请求而非猜测计划（直接用 agent-native runtime/llm 客户端做一次编排决策调用，不是智能体执行）
mock	脚本化，离线演示/测试

蓝图（Blueprint）= 可选的任务模板（关键词匹配或显式 task key 命中）， 提供基线步骤/默认编制/交付物骨架，注册表同样空表起步。

Leader-Delegation 编排模式（机制参考 Multica Squad Leader，原创实现）

除标准模式（一次性计划顺序执行）外，支持事件驱动的增量委派循环 （--mode leader --leader-role <role>）：leader 是注册表中的普通角色，每轮被 引擎激活——读目标/黑板/委派历史，产出结构化决策 delegation.json：

• delegate：委派一名成员（按 skills 挑人），引擎执行成员步骤、把交付快照进 leader 工作区 inbox/<步骤id>/（leader 沙箱看不到成员目录，须物化核实）、 黑板合并，然后唤醒 leader 再评估；
• escalate：升级问人（HITL kind=escalation，人工回答落黑板事实后 leader 继续）；
• close：收口（走统一质检/清单）；failed：如实报告无法达成。

防失控：每运行 leader 轮次上限（默认 8，--max-leader-turns）。leader 协议 核心：只协调不实现、按能力委派、一轮一任务、委派不了就升级、严禁假装完成。

借鉴 Multica 的增强（重写实现，非代码复制）

能力	说明
HITL 等待条件	缺口可声明 wait_run_id/wait_field——等目标运行终态/黑板字段出现时自动唤醒续跑（唤醒报告事实非业务完成）；护栏：单请求自动唤醒上限（MaxWakeupFires=5）后自动中止；serve 每 15s sweep
何时问人总则	planner 与默认角色指令内置："信息若实质改变结果/路径/权限/安全才问人，否则自行决定并说明；严禁假装完成"
运行级 steering	POST /v1/runs/{id}/steer（CLI runs steer）：运行中人工补充指令在下一次步骤边界注入当前运行（不中断进行中步骤，单次消费）
角色级并发上限	RoleSpec.MaxConcurrentTasks（1=对象级串行）；per-role 缓存 + 双检锁防并行首解析竞态
用量记账	每步骤 token 用量按角色累计（usage.json + RunResult.Usage/Manifest）
事件落盘+脱敏	FileEventSink：事件按 seq 追加 runs/<id>/events.jsonl，落盘前脱敏（sk-key/Bearer/JWT/api_key/password 形状），转发 SSE
HITL severity	请求带 action_required/attention 分级（inbox 降噪语义）
会话毒化轮转	agent-native adapters/native：resume-unsafe 失败（context overflow/迭代上限等）后自动归档旧会话换新会话，网络类失败保留会话续跑

HITL：六个挂起点 + 恢复

挂起点	触发	恢复
clarification	规划器判定目标信息不足	回答并入 Goal 重新规划
confirmation	高风险计划/派生编制/requires_approval 步骤	approve/abort（approve 后执行）
gap	角色写 gaps.json 声明 blocking 缺口	回答落黑板 Fact 并 resolve；skip/abort 可选
adjustment	评估器建议加步/跳步且命中审批策略	approve/reject/abort
permission	角色 bash_permission=ask	approve（本运行内授权）/reject/abort
quality_review	质检失败且自动修复预算用尽	人工放行（记录 ManualPass）/再修复/判失败

挂起 = 状态与 pending.json 落盘后返回；Respond 按请求 ID 幂等应用决策并续跑， 进程重启后可恢复（磁盘即权威）。策略三级（全局→角色→Goal 覆盖）： interactive（默认）| auto（无值守：缺口记 fallback 假设继续，高风险决策 fail-closed） | disabled（挂起点直接失败）。

执行引擎与工作区

顺序/并行混合调度（相邻 parallel=true 步骤成组并发）；顺序步骤后可接 StepEvaluator（可插拔，默认 no-op）做动态调整；非关键步骤（critical=false） 失败降级继续（终态 degraded）。步骤级瞬态重试复用 agent-native AssessStepFailure（上限 2 次），交付物物化带符号链接防护。

任务级沙箱工作区（与产品 squad 布局兼容）：

<data>/runs/<run_id>/
  workspace.json squad.json workflow.json blackboard.json template.md
  context/{goal.md, materials/, materials_text/, index.json}
  tasks/<NN>_<role>/{TASK.md, AGENTS.md, output…, fields.json?, gaps.json?, execution.log}
  output.md manifest.json   # 交付物 + 防篡改清单（sha256 + 质检报告）

黑板（Facts/Gaps/Assumptions/Fields）由步骤产出 fields.json/gaps.json 合并， 人工回答记录为 Source=human 的事实。

HTTP API（serve）

方法/路径	说明
GET /v1/health	健康检查
GET/POST /v1/roles、PUT/DELETE /v1/roles/{key}	角色注册管理
POST /v1/roles/derive	派生角色
GET /v1/roles/recommend?q=	角色推荐
GET/POST /v1/blueprints、DELETE /v1/blueprints/{key}	任务模板管理
POST /v1/runs	发起运行（goal/task_key/backend），同步推进至挂起或终态
GET /v1/runs、GET /v1/runs/{id}	运行列表/详情
GET /v1/runs/{id}/pending	当前挂起的人工请求
POST /v1/runs/{id}/respond	应用人工决策（answer/choice）并续跑
POST /v1/runs/{id}/steer	运行中追加人工指令（下一步骤边界注入）
POST /v1/runs/{id}/blackboard	写入黑板字段（可满足 field_set 等待条件）
POST /v1/wakeups/sweep	手动触发等待条件扫描（serve 内置 15s 周期）
POST /v1/runs/{id}/resume	重启恢复入口
GET /v1/runs/{id}/blackboard	黑板
GET /v1/runs/{id}/events?cursor=N	SSE 事件流（human_input_required/步骤事件/终态），支持断线重放

事件名：run_started/phase/step_started/step_completed/step_failed/step_skipped/ detail/deliverable/human_input_required/human_responded/run_completed/run_failed/run_cancelled。

CLI

agent-squad serve --addr :8090 [--planner rule|llm] [--model M]
agent-squad role list|add(-f file 或 --role/--backend/--model/--keywords…)|rm|recommend|derive
agent-squad blueprint list|add <file.json>|rm <key>
agent-squad run "目标文本" [--task-key K] [--backend B] [--materials DIR] [--hitl-mode interactive|auto|disabled]
agent-squad runs list|inspect|pending|respond|blackboard
agent-squad demo          # 离线全链路演示（含一次 HITL 挂起-回应）

run 在终端交互式处理 HITL：挂起时打印问题/选项/上下文，读 stdin 回应后自动续跑。 LLM 配置走环境变量：AGENT_SQUAD_LLM_BASE_URL / AGENT_SQUAD_LLM_API_KEY / AGENT_SQUAD_LLM_MODEL（OpenAI 兼容端点；配置后自动注册 agent-native 后端工厂与 llm 规划器，角色用 --backend agent-native 执行真实智能体）。

快速开始

在仓库根目录（需已初始化 deps/ 下的子模块）：

go build -o agent-squad .
./agent-squad demo                     # ① 离线全链路演示
./agent-squad role add --role researcher --backend stub --keywords "调研,市场"
./agent-squad run "调研 X 并产出报告"   # ② 终端交互式 HITL（stub 后端）
./agent-squad serve --addr :8090       # ③ HTTP API（REST + SSE）

CodeGraph

codegraph init 的索引写在 .codegraph/。仓库只跟踪 .codegraph/.gitignore。SQLite 数据库、WAL、pid、socket 和日志留在本机；根目录 .gitignore 与该文件双重忽略，避免索引被提交。

验证

GOWORK=off go vet ./... && GOWORK=off go test -count=1 ./...
./scripts/submodule-consistency.sh

当前全绿（conformance 全链路 + HITL 各挂起点 + server + store + textextract）。