# Agent-Squad

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

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

本仓库是该模块的源码位置。Go 模块路径为 `agent-squad`。智能体执行依赖子模块 [Agent-Native](./Agent-Native)（`replace agent-native => ./Agent-Native`），钉在固定提交，不随 Agent-Native 分支浮动。

克隆时带上子模块，否则无法编译：

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

## 与周边仓库的关系

| 仓库/模块 | 关系 |
|---|---|
| Agent-Native（本仓 submodule `./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

```bash
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` 执行真实智能体）。

## 快速开始

在仓库根目录（需已初始化 `Agent-Native` 子模块）：

```bash
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）
```

## 验证

```bash
go vet ./... && go test -count=1 ./...
```

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