Compare commits

..
Author SHA1 Message Date
weichen b75e12ad4c Carry the split usage fields through squad events (N3 WP6)
Why: the exec bridge now threads Last*/cache (Agent-Native#38); squad
ProcessEvent carries them to hosts (the product's squad runner reads
them for usage accounting).
Evidence: GOWORK=off go vet green across squad and adapters/native;
nested pin at the merged native.
Impact: additive event fields.
Refs: Agent-Native#38, N3 plan WP6
2026-10-07 17:10:30 +00:00
57 changed files with 115 additions and 6824 deletions
-150
View File
@@ -1,150 +0,0 @@
name: governance
on:
pull_request:
push:
branches: [main]
jobs:
governance:
runs-on: ubuntu-latest
env:
GOPROXY: https://goproxy.cn,direct
steps:
- name: Checkout
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
SUBMODULE_TOKEN: ${{ secrets.SUBMODULE_TOKEN }}
run: |
set -euo pipefail
# 只物化两个治理 gitlink(Guidelines 与 deps/development-manager),非递归;
# 其它 gitlink 不物化、不取回。凭据只以 URL 限定的 extraheader 存在于本进程树内。
python3 - <<'PY_CHECKOUT'
import os
from pathlib import Path
import re
import subprocess
import sys
from urllib.parse import urlsplit
# 服务端基址取运行器注入的 GITHUB_SERVER_URL(平台控制、候选 PR 不可影响)。
SERVER = os.environ.get("GITHUB_SERVER_URL", "").rstrip("/")
parsed_server = urlsplit(SERVER)
if parsed_server.scheme not in {"http", "https"} or not parsed_server.netloc:
sys.exit("Checkout server must be the platform-injected http(s) URL")
SSH = "ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/"
# 审查过的白名单,独立于候选 .gitmodules:仅列出两个治理 gitlink。
REPOSITORIES = {
"deps/development-guidelines": "Development-Guidelines",
"deps/development-manager": "Development-Manager",
}
TARGET = "weichen/Agent-Squad"
root_token = os.environ.pop("TOKEN", "")
component_token = os.environ.pop("SUBMODULE_TOKEN", "")
if not root_token or not component_token:
sys.exit("Checkout requires TOKEN and SUBMODULE_TOKEN")
if os.environ.get("GITHUB_REPOSITORY") != TARGET:
sys.exit("Checkout repository is outside the reviewed allowlist")
sha = os.environ.get("GITHUB_SHA", "")
if not re.fullmatch(r"[0-9a-fA-F]{40}", sha):
sys.exit("Checkout requires a fixed commit SHA")
# 丢弃继承的 Git 追踪/配置/SSH 钩子;凭据只存在于单个 Git 进程树的精确 URL 头中。
clean_env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
clean_env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_SYSTEM="/dev/null",
GIT_CONFIG_GLOBAL="/dev/null", GIT_TERMINAL_PROMPT="0")
config = {
"core.hooksPath": "/dev/null", "core.fsmonitor": "false",
"init.templateDir": "", "credential.helper": "",
"fetch.recurseSubmodules": "false", "submodule.recurse": "false",
"http.followRedirects": "false", "protocol.allow": "never",
"protocol." + urlsplit(SERVER).scheme + ".allow": "always",
}
def git(repo, *args, extra=None):
values = config | (extra or {})
env = clean_env | {"GIT_CONFIG_COUNT": str(len(values))}
for index, (key, value) in enumerate(values.items()):
env[f"GIT_CONFIG_KEY_{index}"] = key
env[f"GIT_CONFIG_VALUE_{index}"] = value
return subprocess.run(["git", "-C", str(repo), *args], env=env,
check=True, stdout=subprocess.PIPE).stdout
def materialize_governance(root):
# -r 列出任意深度的 gitlink,但不进入 submodule 内部;其它 gitlink 只记录、从不取回。
links = {}
for entry in git(root, "ls-tree", "-rz", "HEAD").split(b"\0"):
if not entry:
continue
metadata, path = entry.split(b"\t", 1)
mode, kind, commit = metadata.decode().split()
if mode == "160000":
links[path.decode()] = commit
for name in REPOSITORIES:
if name not in links:
raise ValueError("Governance gitlink is missing from the fixed commit")
raw = git(root, "config", "--no-includes", "--blob", "HEAD:.gitmodules", "--null", "--list")
entries = {}
for item in raw.split(b"\0"):
if not item:
continue
key, value = item.decode().split("\n", 1)
match = re.fullmatch(r"submodule\.(.+)\.(path|url)", key)
if not match:
continue
name, field = match.groups()
if name not in REPOSITORIES:
continue
if field in entries.setdefault(name, {}):
raise ValueError("Duplicate candidate .gitmodules setting")
entries[name][field] = value
# 先整体校验两个治理条目,再进行任何带凭据的取回。
for name, repository in REPOSITORIES.items():
fields = entries.get(name, {})
if fields.get("path") != name:
raise ValueError("Governance submodule path is outside the reviewed allowlist")
trusted_url = f"{SERVER}/weichen/{repository}.git"
if fields.get("url") not in {SSH + repository + ".git", trusted_url}:
raise ValueError("Governance submodule URL is outside the reviewed allowlist")
for name, repository in REPOSITORIES.items():
url = f"{SERVER}/weichen/{repository}.git"
# 仅持久化审查过的公开 URL,使 Git 在进程级配置消失后仍识别该 submodule。
git(root, "config", f"submodule.{name}.url", url)
git(root, "submodule", "update", "--init", "--checkout", "--", name,
extra={f"submodule.{name}.url": url,
f"submodule.{name}.update": "checkout",
f"http.{url}.extraheader": "AUTHORIZATION: token " + component_token})
child = root / name
if git(child, "rev-parse", "HEAD").decode().strip() != links[name]:
raise ValueError("Materialized governance gitlink does not match the fixed SHA")
try:
root = Path.cwd()
# 必须是干净的临时工作区;不复用既有 Git 状态。
if (root / ".git").exists():
raise ValueError("Checkout requires a fresh workspace")
git(root, "init", "-q")
url = f"{SERVER}/{TARGET}.git"
git(root, "remote", "add", "origin", url)
git(root, "fetch", "--depth=1", "origin", sha,
extra={f"http.{url}.extraheader": "AUTHORIZATION: token " + root_token})
git(root, "checkout", "-q", "--detach", "FETCH_HEAD")
materialize_governance(root)
except (ValueError, OSError, subprocess.CalledProcessError) as error:
sys.exit(f"Checkout refused: {error}")
print("Checkout complete; credentials were not persisted in Git configuration")
PY_CHECKOUT
unset TOKEN SUBMODULE_TOKEN
- name: Install Go 1.27.1
run: |
set -euo pipefail
curl -fsSL -o "$RUNNER_TEMP/go.tgz" https://mirrors.aliyun.com/golang/go1.27.1.linux-amd64.tar.gz
tar -C /usr/local -xzf "$RUNNER_TEMP/go.tgz"
ln -sfn /usr/local/go/bin/go /usr/local/bin/go
ln -sfn /usr/local/go/bin/gofmt /usr/local/bin/gofmt
- name: Validate agent execution configuration
run: scripts/agent-exec validate --repo .
- name: Governance check
run: scripts/dm governance check --repo .
-3
View File
@@ -13,6 +13,3 @@
[submodule "deps/agent-intent"]
path = deps/agent-intent
url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Intent.git
[submodule "deps/development-manager"]
path = deps/development-manager
url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Development-Manager.git
@@ -1,58 +0,0 @@
# Agent-Squad 采纳 development-governance-v2 治理套件 任务卡
任务主记录:[Agent-Squad PR #54](https://git-home.u1680832.nyat.app:30319/weichen/Agent-Squad/pulls/54)(本文件随 PR 描述维护)。
状态:已完成(闭合随本 PR 合入;合入以平台记录为准);owner:weichen。
## 基线与授权
- 权威仓:weichen/Agent-Squad;root_target:main;immediate_target:main
- branch_kind:initiative;initiative_id:governance-adoption-Agent-Squad
- R0(initial_main_sha):490b0b2dfa1567cb16ff7a7230fd78e52bc2938e;工作区:/home/weichen/projects/Agent-Squad-wt-feature-governance-adoption(worktree);分支:feature/governance-adoption
- 父任务信息(仅子任务填写):无
- accepting_requirements:false(单仓采纳 initiative,范围固定为下列十步,不接收新需求)
- 需求分流:verdict=NEW;selected_initiative=无;候选=无;理由=development-governance-v2 Phase 6 每个正式仓库独立 initiative;triage 收据=无(本仓采纳前尚无 triage 入口)
- 授权与交付终点:owner 已授权 development-governance-v2 全部实施(Agent-System-Dev 主记录 docs/superpowers/plans/2026-10-16-development-governance-v2-master.md);终点为本 PR 合入 main 且采纳状态 active。分支保护与 tag 由用户执行。
- 实施执行:agent-per-unit(配置:AGENT-EXECUTION.md;外部 Agent 一单元一新进程/会话/工作区)
## 目标与非目标
目标(Phase 6 十步):固定 Guidelines SHA(deps/development-guidelines @ 2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb);增加 AGENT-EXECUTION.md;增加共享执行器薄入口(deps/development-manager @ bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c + scripts/dm、scripts/agent-exec、scripts/task);四条路由(implementation/repair/test/review);任务卡模板与分支元数据;CI 中启用 schema 校验(.gitea/workflows/governance.yml:agent-exec validate + governance check);一次正例运行;负例(缺配置、坏收据、越界路径、未知副作用);独立 Review + CI;采纳状态 active。
非目标:不改业务代码与既有测试;不改分支保护(由用户执行);不发布 tag。
范围说明(Review 阻塞项 2):`scripts/submodule-consistency.sh` 要求 deps/agent-native、deps/agent-intent 内嵌的 Guidelines/错误码/日志 gitlink 与本仓一致;本 PR 把 Guidelines 固定到 2688fd2 后,按最小修复把这两个 gitlink 升到各自已合入治理采纳的 main(Agent-Native 14d4869、Agent-Intent 651a2e1;两者相对原固定版本只增治理文件、不改 Go 代码),其余 gitlink 不动。核对见证据 `scripts/submodule-consistency.sh`。
引导说明:AGENT-EXECUTION.md 由 host 以固定版本治理套件(dm-server governance init @ bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c)生成并作为引导配置提交(执行器运行前必须存在有效配置;沿用 DM 采纳先例);其余文件由实施单元生成。
## Agent 实施收据
| 单元 ID | 预期范围 | 角色 | 候选顺序 | attempt | CLI/模型 | 终态 | transport | fallback | 源码外收据路径 |
|---|---|---|---|---|---|---|---|---|---|
| governance-adoption-Agent-Squad-r1 | 13 个允许路径(治理文件 + 两个 gitlink) | | implementation | cursor→antigravity→pi | run 71696608(dm-server pinned,attempts=1) | cursor / not-observable | failed-unknown | 无(apply 快进) | 否 | /tmp/gov-receipt-Agent-Squad-r1.json |
| 对账(r1) | 规范 worktree 仍为 2a2a1fd 且干净;无 transport ref | — | — | — | — | — | 已对账;全新运行 r2(单元包追加禁止固定共享 /tmp 路径约束) | — | — | — |
| governance-adoption-Agent-Squad-r2 | 13 个允许路径(治理文件 + 两个 gitlink) | b83905a8 | implementation | cursor→antigravity→pi | run 145e30ce(dm-server 42e675f,attempts=1) | cursor / not-observable | success | 468878f62ede(apply 快进) | 否 | /tmp/gov-receipt-Agent-Squad-r2.json |
| (无效启动 repair-r0) | — | repair | — | 无 attempt | — | invalid-config(单元包尚未写出即启动,执行器读取失败;无 attempt、无副作用,worktree 仍为 e29284e 且干净) | 无 | 否 | /tmp/gov-receipt-Agent-Squad-repair-r0-invalid-unit-path.json |
| governance-adoption-Agent-Squad-repair-r1 | policy/guidelines-adoption.md、PROJECT.md、deps/agent-native、deps/agent-intent | repair | cursor→antigravity→pi | run fadb9c92(attempts=1) | cursor / not-observable | success | d0f9081f47eb(apply 快进) | 否 | /tmp/gov-receipt-Agent-Squad-repair-r1.json |
## 同步记录
| 节点 | sync_base_sha | tested_head_sha | checked_at | 结果 |
|---|---|---|---|---|
| 启动 | 490b0b2dfa1567cb16ff7a7230fd78e52bc2938e | 490b0b2dfa1567cb16ff7a7230fd78e52bc2938e | 2026-10-17T07:17:41Z | 一致 |
## 结果与验证(完成后填写)
- 结果:治理套件已采纳——Guidelines 与 Development-Manager gitlink 固定、AGENT-EXECUTION.md 四条路由、共享执行器薄入口、pre-commit admit、governance CI;采纳状态 active(随合入生效)。
- 验证:见下表(命令输出由 /tmp/gov-neg/ev.sh 写入 .task/evidence/governance-adoption/,SELF 除非另注)。
- 影响与剩余项:不改业务代码;本地启用钩子需由人执行 `git config core.hooksPath scripts/hooks`;将 governance 检查设为分支保护必需项属用户双钥匙事项(命令见 Agent-System-Dev 治理主记录)。
| 时间(UTC) | 命令 | 被测 HEAD | exit | 来源 | 摘要/位置 |
|---|---|---|---|---|---|
| 20261017T080150Z | `scripts/dm governance check --repo .` | 468878f62ede | 0 | SELF | ok fixtures;[输出](../evidence/governance-adoption/00-20261017T080150Z.log) sha256:b07d207012a2fd6d |
| 20261017T080150Z | `scripts/agent-exec validate --repo .` | 468878f62ede | 0 | SELF | validate: ok;[输出](../evidence/governance-adoption/01-20261017T080150Z.log) sha256:b3a91246221bb5f8 |
| 20261017T080150Z | `python3 /tmp/gov-neg/adopt_cases.py .` | 468878f62ede | 0 | SELF | [verdict] ALL PASS cases=5;[输出](../evidence/governance-adoption/02-20261017T080150Z.log) sha256:109906d5e57fe039 |
| 20261017T094306Z | `scripts/dm governance check --repo .` | d0f9081f47eb | 0 | SELF | ok fixtures;[输出](../evidence/governance-adoption/03-20261017T094306Z.log) sha256:b904686133da5f80 |
| 20261017T094306Z | `scripts/agent-exec validate --repo .` | d0f9081f47eb | 0 | SELF | validate: ok;[输出](../evidence/governance-adoption/04-20261017T094306Z.log) sha256:19dc223efda318d6 |
| 20261017T094308Z | `scripts/submodule-consistency.sh` | 05b509827274 | 0 | SELF | ok deps/agent-intent 651a2e1e03c4326888ef9f742ce592140ae30ab8;[输出](../evidence/governance-adoption/05-20261017T094308Z.log) sha256:bc528fe029ed41d2 |
| — | 候选 HEAD CI | b3e7da4a11b9 | 0 | GATE | success ci / docker-checkout-hostgateway (pull_request)=success(/weichen/Agent-Squad/actions/runs/3672/jobs/5787);governance / governance (pull_request)=success(/weichen/Agent-Squad/actions/runs/3673/jobs/5788);ci / vet-and-test (pull_request)=success(/weichen/Agent-Squad/actions/runs/3672/jobs/5786) |
| — | 独立 Review | b3e7da4a11b9 | 0 | REPLAY | cursor-agent-stable --mode ask 全新只读会话(fresh_session=true,session id not-observable)闭合重审 VERDICT: APPROVE(对象 b3e7da4) |
@@ -1,19 +0,0 @@
command: scripts/dm governance check --repo .
cwd: /home/weichen/projects/Agent-Squad-wt-feature-governance-adoption
head: 468878f62eded8347d18a1d6c1b7c5f7e24a9c4c
exit: 0
utc: 20261017T080150Z
---
ok gitlink deps/development-guidelines
ok gitlink deps/development-manager
ok agent-execution
ok file AGENTS.md
ok file PROJECT.md
ok file policy/guidelines-adoption.md
ok file .task/templates/task-card.md
ok executable scripts/agent-exec
ok executable scripts/hooks/pre-commit
ok executable scripts/dm
ok executable scripts/task
ok adoption status
ok fixtures
@@ -1,7 +0,0 @@
command: scripts/agent-exec validate --repo .
cwd: /home/weichen/projects/Agent-Squad-wt-feature-governance-adoption
head: 468878f62eded8347d18a1d6c1b7c5f7e24a9c4c
exit: 0
utc: 20261017T080150Z
---
validate: ok
@@ -1,13 +0,0 @@
command: python3 /tmp/gov-neg/adopt_cases.py .
cwd: /home/weichen/projects/Agent-Squad-wt-feature-governance-adoption
head: 468878f62eded8347d18a1d6c1b7c5f7e24a9c4c
exit: 0
utc: 20261017T080150Z
---
[object] Agent-Squad-wt-feature-governance-adoption HEAD=468878f62eded8347d18a1d6c1b7c5f7e24a9c4c
PASS positive-run-apply: run exit=0 terminal=success apply exit=0 head=312d80d409a1
PASS missing-config: run exit=2 terminal=invalid-config validate exit=2
PASS bad-receipt: apply exit=4 head_unchanged=True msg=apply: no local integrity record: changed paths do not match the transport diff
PASS out-of-scope-path: run exit=5 terminal=scope-expansion transport=False
PASS unknown-side-effect: run exit=4 terminal=failed-unknown transport=False
[verdict] ALL PASS cases=5
@@ -1,19 +0,0 @@
command: scripts/dm governance check --repo .
cwd: /home/weichen/projects/Agent-Squad-wt-feature-governance-adoption
head: d0f9081f47eb59565323f731cb8085e5891dd7ba
exit: 0
utc: 20261017T094306Z
---
ok gitlink deps/development-guidelines
ok gitlink deps/development-manager
ok agent-execution
ok file AGENTS.md
ok file PROJECT.md
ok file policy/guidelines-adoption.md
ok file .task/templates/task-card.md
ok executable scripts/agent-exec
ok executable scripts/hooks/pre-commit
ok executable scripts/dm
ok executable scripts/task
ok adoption status
ok fixtures
@@ -1,7 +0,0 @@
command: scripts/agent-exec validate --repo .
cwd: /home/weichen/projects/Agent-Squad-wt-feature-governance-adoption
head: d0f9081f47eb59565323f731cb8085e5891dd7ba
exit: 0
utc: 20261017T094306Z
---
validate: ok
@@ -1,14 +0,0 @@
command: scripts/submodule-consistency.sh
cwd: /home/weichen/projects/Agent-Squad-wt-feature-governance-adoption
head: 05b5098272741987767efa2e78b8fe01aa84b6e5
exit: 0
utc: 20261017T094308Z
---
ok development-guidelines@deps/agent-native 2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb
ok error-code-system@deps/agent-native a3ee67bba269e1276c14e22c026171ecf2cf6190
ok logging-system@deps/agent-native 49b5d8be604d05e4246dffa0d10fa1c2b7ad45d7
ok development-guidelines@deps/agent-intent 2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb
ok error-code-system@deps/agent-intent a3ee67bba269e1276c14e22c026171ecf2cf6190
ok logging-system@deps/agent-intent 49b5d8be604d05e4246dffa0d10fa1c2b7ad45d7
ok deps/agent-native 14d48697a69ddba9ebc67ba7daa588f1b082d096
ok deps/agent-intent 651a2e1e03c4326888ef9f742ce592140ae30ab8
-66
View File
@@ -1,66 +0,0 @@
# <任务标题> 任务卡
任务主记录:<Issue/PR 链接,或注明"本文件随 PR 描述维护">。
状态:<进行中 / 待审核 / 已合入 / 已放弃>;owner:<填写>。
## 基线与授权
- 权威仓:<仓 URL 或逻辑 ID>;root_target:main;immediate_target:<main 或 feature/initiative>
- branch_kind:<initiative | child | standalone>;initiative_id:<稳定 ID,普通任务为空>
- R0(initial_main_sha):<完整 SHA>;工作区:<路径>(worktree / clone);分支:<feature|fix|hotfix/...>
- 父任务信息(仅子任务填写):parent_branch=<父分支>;parent_head_sha=<SHA>;parent_pr=<父 PR>
- accepting_requirements:<true | false>(仅 initiative 可为 true;冻结后为 false)
- 需求分流:verdict=<JOIN | NEW>;selected_initiative=<分支或无>;候选=<分支@HEAD 列表或无>;理由=<不适配/适配依据>;triage 收据=<源码外路径与摘要>
- 授权与交付终点:<本次允许的动作与终点;未授权事项写明>
- 实施执行:agent-per-unit(配置:AGENT-EXECUTION.md;外部 Agent 一单元一新进程/会话/工作区)
## 目标与非目标
<预期结果、受影响入口/模块/契约;明确不做什么。>
## Agent 实施收据
按根目录 AGENT-EXECUTION.md 路由;外部 Agent 一单元一新进程/会话/隔离工作区。实施、修复与测试必须通过登记的候选执行;未配置或候选安全耗尽停在 unavailable/blocked,禁止 host 隐式代写。
| 单元 ID | 预期范围 | 角色 | 候选顺序 | attempt | CLI/模型 | 终态 | transport | fallback | 源码外收据路径 |
|---|---|---|---|---|---|---|---|---|---|
| 待定义 | — | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
## 复用材料(task-start 自动检索结果摘录)
- 相关近期提交:<git log -- <paths> 命中;无则写无>。
- 相关经验条目:<检索命中;无则写无>。
## 同步记录
| 节点 | sync_base_sha | tested_head_sha | checked_at | 结果 |
|---|---|---|---|---|
| 启动 | <R0> | <HEAD> | <日期时间> | <一致/已同步> |
| 验收前 | <填写> | <填写> | <填写> | <填写> |
字段没有发生的写"无",不省略。本卡与 PR 描述同源:开 PR 时将"目标与非目标、结果与验证、影响与剩余项"复制进 PR 描述,不另写第二份。
## 交付调度(有多个就绪任务时)
- 调度记录 / entry_id / 当前 attempt_id:<平台或调度服务链接及标识;未入队写无>。
- 入队源 HEAD / owner / 依赖:<完整 SHA、身份、依赖或无>。
- 固定候选引用:<调度尝试中的 base/head、组件与配置;未固定写无>。
- 窗口、最终 CI、Review 与真实合入结果:<引用调度记录及原始证据,不复制全队列>。
定义见 [合入调度与 CI 分配](../standards/merge-queue.md)。本段在候选固定前整理;固定后先使用源码之外的记录保存运行结果,再按项目闭合流程回填。
## 结果与验证(完成后填写)
- 结果:<交付了什么;未发生写无>。
- 验证:<结论性摘要:PASS/FAIL/SKIP/NOT_RUN 逐项;逐条证据见下表,来源标注与写入规则见 [按影响选择验证与证据](../standards/verification.md)>。
- 影响与剩余项:<影响面、遗留风险、后续任务>。
| 时间(UTC) | 命令 | 被测 HEAD | exit | 来源 | 摘要/位置 |
|---|---|---|---|---|---|
| <时间> | <命令;由项目 evidence 工具写入,无工具时附命令+对象 SHA+输出 digest 并标 SELF> | <HEAD> | <exit> | GATE/REPLAY/SELF | <摘要/位置> |
## 回收(task-finish)
- 合入核对:<分支已包含于目标分支的核对输出>。
- 未跟踪/ignored 文件处置:<归档/可再生/存疑 逐项;无则写无>。
- 回收动作:<worktree remove、分支删除、prune;放弃路径注明原因>。
-73
View File
@@ -1,73 +0,0 @@
# Project Agent Execution Configuration
# 项目工程 Agent 执行路由配置
适用范围:定义本项目中由 AI / Agent 主导的代码实施、修复、测试与审阅所调用的 Agent CLI 路由。
解析器识别正文中唯一一个 ```agent-execution 代码块。正文外的说明文字可根据项目需要调整。
通用硬规则见 Development-Guidelines 的 [Agent 执行与协作契约](deps/development-guidelines/standards/agent-execution.md)。
本配置为项目本地路由权威,声明具体的候选 profile、尝试次数上限、超时、集成入口与豁免路径;
代码块须通过 `deps/development-guidelines/templates/schemas/agent-execution.schema.json` 校验后才能登记为 active。
`fallback_to_host` 只能为 `never`;旧值 `all-unavailable` 仅供迁移工具读取,不能通过准入。
下例的 CLI 名称、命令与路径均为占位,按项目实际执行器替换。
```agent-execution
schema: agent-execution/v1
execution:
fresh_process_per_unit: true
permission: run-everything
fallback_to_host: never
max_parallel: 3
timeout_seconds: 7200
idle_timeout_seconds: 600
summary_bytes: 16384
raw_output_bytes: 10485760
max_attempts_per_profile: 3
emergency_profile: codex
roles:
implementation: [cursor, antigravity, pi]
repair: [cursor, antigravity, pi]
test: [pi, antigravity, cursor]
review: [pi, antigravity, cursor, codex]
profiles:
cursor:
adapter: cursor
executable: "cursor-agent-stable"
model: auto
# 2026-10-21 临时禁用:U3B 连续两次 fail-stop(首次 TLS 会话前故障 553B 日志、
# 二次 "Cannot use this model: auto",与 Backend 配置已记录的月配额耗尽一致),
# 两次均未建立会话、零改动(现场保留)。恢复时改回 enabled: true。
enabled: false
antigravity:
adapter: antigravity
executable: agy
model: auto
# 2026-10-21 临时禁用:U3B 尝试被 400 FAILED_PRECONDITION "User location is
# not supported for the API use" 拒绝,0 token、未建立会话(现场保留);
# 与 Backend 配置已记录的 Gemini 端点不稳一致。恢复时改回 enabled: true。
enabled: false
pi:
adapter: pi
executable: pi
model: auto
enabled: true
codex:
adapter: codex
executable: codex
model: auto
enabled: true
integration:
exempt_paths: [".task/**", "docs/superpowers/specs/**", "docs/superpowers/plans/**"]
transport:
command: "scripts/agent-exec apply"
admission:
command: "scripts/agent-exec admit"
cleanup:
command: "scripts/agent-exec cleanup"
```
-18
View File
@@ -34,21 +34,3 @@
- **SSH key**:`~/.ssh/home_gitea`(ED25519,公钥指纹
`SHA256:GYXaOXIMeloQ1fKSfdJ/ndgPQzs/Ix7Hk62ekfkfQ20`,Gitea 侧密钥名 GMKtec);
`~/.ssh/config` 已有 `git-ssh.u1680832.nyat.app` 主机条目,克隆/推送直接可用。
## Agent 执行与新项目准入(强制)
1. 缺 Guidelines 固定版本(`deps/development-guidelines` gitlink 未就绪或 HEAD 不符)时,Agent 只能只读分析,不得实施。
2. 缺有效 `AGENT-EXECUTION.md`(`scripts/dm governance check` 未通过)时禁止 AI 实施。
3. 缺共享执行器(`scripts/agent-exec` 或 `deps/development-manager` 不可用)时,状态为 `blocked/unavailable`,不得改由 host 替代。
4. 不允许 host 代写实施单元;实施、修复与测试必须经 `AGENT-EXECUTION.md` 登记的候选执行。
5. 人类直接开发按其自身授权与项目规则进行,不受本条款约束。
6. 分支保护与规范 tag 由用户负责设置与维护,Agent 不得代为设置。
入口:
- 需求分流:`scripts/task triage discover|decide|verify`
- 任务启动:`scripts/task start …`
- PR 检查:`scripts/task pr-check …`
- Agent 执行:`scripts/agent-exec run|apply|admit|validate`
AI 实施单元只经 `scripts/agent-exec run` 按 AGENT-EXECUTION.md 运行,并经 `scripts/agent-exec apply` 集成。
+2 -3
View File
@@ -12,8 +12,8 @@
- 提交/审核/合并/发布身份与权限:仓库所有者 weichen。
- 任务唯一来源:Gitea `weichen/Agent-Squad` 的 Issue 与 Pull Request。
- 规范性文档目录:`policy/`。
- 过程文档仓/目录:任务卡与交付证据在 `.task/`(模板 `.task/templates/task-card.md`);其他过程记录在 `docs/records/`(项目内豁免,见采纳记录)。
- 交接记录位置:随任务主记录;需要落盘的任务交接与交付证据放入 `.task/`,其他落盘交接放入 `docs/records/`。
- 过程文档仓/目录:`docs/records/`(项目内豁免,见采纳记录)。
- 交接记录位置:随任务主记录;需要落盘的交接放入 `docs/records/`。
- 凭证查找入口及所需字段:LLM 使用环境变量 `AGENT_SQUAD_LLM_BASE_URL`、`AGENT_SQUAD_LLM_API_KEY`、`AGENT_SQUAD_LLM_MODEL`。日志采集 token 使用日志库自己的配置。文档与仓库不记录这些值。
## 依赖组合
@@ -45,7 +45,6 @@ git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen
| 模块/接口 | 仓库根:`GOWORK=off go vet ./... && GOWORK=off go test -count=1 ./...` | 需要已初始化的 Agent-Native 子模块;默认 stub,不调用真实模型 |
| 数据/权限/恢复 | conformance 与 store 测试覆盖运行落盘、HITL 恢复 | 无共享数据库 |
| UI/执行后端 | `GOWORK=off go test -count=1 ./server/... ./conformance/...` | 不覆盖浏览器;SSE 由测试客户端验证 |
| 治理与 Agent 执行配置 | 仓库根:`scripts/agent-exec validate --repo .` 与 `scripts/dm governance check --repo .` | 需 `deps/development-manager` 已按 gitlink 检出(首次 `dm` 调用会构建 dm-server);只核验 AGENT-EXECUTION.md 与治理文件,不证明实施单元正确 |
## 环境与数据
-179
View File
@@ -1,179 +0,0 @@
// Package a2a 把小队接入 A2A(Agent2Agent)1.0 互通面(Q3 WP4):
// - 发布侧:BuildCard 从角色注册表与蓝图注册表渲染 Agent Card(描述本
// 团队能力),CardHandler 以 JSON 服务(挂载在
// /.well-known/agent-card.json);
// - 消费侧:FetchCard 发现远端 Agent Card(fail-closed 校验必备字段),
// Executor 实现 squad.Executor——message/send 发起任务,tasks/get 轮询
// A2A 任务状态机(submitted/working/input-required → completed/failed/
// canceled),终态映射 ExecResult:completed 的 artifacts(TextPart/
// FilePart)落成 patches/目标文件;failed/canceled/input-required 一律
// Success=false(跨进程挂起不在本适配面内,fail-closed 交引擎重试/降级
// 语义处理)。
//
// 传输为 JSON-RPC 2.0 over HTTP(A2A 1.0 形态);不引入协议之外的依赖。
package a2a
import (
"encoding/json"
"fmt"
"net/http"
"strings"
"agent-squad/squad"
)
// ProtocolVersion 对齐的 A2A 协议版本。
const ProtocolVersion = "1.0"
// WellKnownPath 是 Agent Card 的发现路径(A2A 1.0)。
const WellKnownPath = "/.well-known/agent-card.json"
// AgentCard 是 A2A 1.0 Agent Card(发布与消费共用形态)。
type AgentCard struct {
ProtocolVersion string `json:"protocolVersion"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
// URL 是 JSON-RPC 服务端点(消费侧据此发 message/send)。
URL string `json:"url"`
Version string `json:"version"`
Capabilities CardCapabilities `json:"capabilities"`
DefaultInputModes []string `json:"defaultInputModes,omitempty"`
DefaultOutputModes []string `json:"defaultOutputModes,omitempty"`
Skills []AgentSkill `json:"skills,omitempty"`
}
// CardCapabilities 能力声明(本适配面:非流式、无推送、无状态历史)。
type CardCapabilities struct {
Streaming bool `json:"streaming"`
PushNotifications bool `json:"pushNotifications"`
StateTransitionHistory bool `json:"stateTransitionHistory"`
}
// AgentSkill 是一项可被远端调用的能力。
type AgentSkill struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Tags []string `json:"tags,omitempty"`
Examples []string `json:"examples,omitempty"`
}
// CardOptions 覆盖 BuildCard 的身份字段(空则用缺省)。
type CardOptions struct {
Name string
Description string
// URL JSON-RPC 端点(必填:远端没有端点就无法调用本团队)。
URL string
// Version 卡片版本(空 = "1.0.0")。
Version string
// Skills 显式能力清单;空 = 从注册表派生。
Skills []AgentSkill
}
// BuildCard 从角色注册表与蓝图注册表渲染 Agent Card(描述本团队能力)。
// 角色 → 技能(关键词作 tags);蓝图 → 技能(match 词作 examples)。
func BuildCard(reg *squad.RoleRegistry, bps *squad.BlueprintRegistry, opts CardOptions) (AgentCard, error) {
if strings.TrimSpace(opts.URL) == "" {
return AgentCard{}, fmt.Errorf("a2a: Agent Card 需要 JSON-RPC 端点 URL")
}
card := AgentCard{
ProtocolVersion: ProtocolVersion,
Name: orDefault(opts.Name, "agent-squad"),
Description: opts.Description,
URL: opts.URL,
Version: orDefault(opts.Version, "1.0.0"),
DefaultInputModes: []string{"text/plain"},
DefaultOutputModes: []string{"text/plain"},
Skills: append([]AgentSkill(nil), opts.Skills...),
}
if len(card.Skills) == 0 {
if reg != nil {
for _, role := range reg.List() {
desc := firstLine(role.Instructions)
if desc == "" {
desc = role.Name
}
card.Skills = append(card.Skills, AgentSkill{
ID: role.Role, Name: orDefault(role.Name, role.Role),
Description: desc, Tags: append([]string(nil), role.Keywords...),
})
}
}
if bps != nil {
for _, bp := range bps.List() {
card.Skills = append(card.Skills, AgentSkill{
ID: bp.Key, Name: orDefault(bp.Title, bp.Key),
Description: bp.Description, Examples: append([]string(nil), bp.Match...),
})
}
}
}
return card, nil
}
// CardHandler 以 JSON 服务 Agent Card(调用方挂载到 WellKnownPath)。
func CardHandler(card AgentCard) http.Handler {
body, _ := json.Marshal(card)
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write(body)
})
}
// FetchCard 发现并校验远端 Agent Card(fail-closed:必备字段缺失即拒)。
func FetchCard(client *http.Client, wellKnownURL string) (AgentCard, error) {
if client == nil {
client = http.DefaultClient
}
resp, err := client.Get(wellKnownURL)
if err != nil {
return AgentCard{}, fmt.Errorf("a2a: 获取 Agent Card: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return AgentCard{}, fmt.Errorf("a2a: Agent Card 端点返回 %d", resp.StatusCode)
}
var card AgentCard
if err := json.NewDecoder(resp.Body).Decode(&card); err != nil {
return AgentCard{}, fmt.Errorf("a2a: Agent Card 解析失败: %w", err)
}
if err := validateCard(card); err != nil {
return AgentCard{}, err
}
return card, nil
}
// validateCard 消费侧最小校验(A2A 1.0 必备字段)。
func validateCard(card AgentCard) error {
if card.ProtocolVersion == "" {
return fmt.Errorf("a2a: Agent Card 缺 protocolVersion")
}
if strings.TrimSpace(card.Name) == "" {
return fmt.Errorf("a2a: Agent Card 缺 name")
}
if strings.TrimSpace(card.URL) == "" {
return fmt.Errorf("a2a: Agent Card 缺 url")
}
if strings.TrimSpace(card.Version) == "" {
return fmt.Errorf("a2a: Agent Card 缺 version")
}
return nil
}
func orDefault(v, def string) string {
if strings.TrimSpace(v) != "" {
return v
}
return def
}
func firstLine(s string) string {
s = strings.TrimSpace(s)
if i := strings.IndexByte(s, '\n'); i >= 0 {
s = s[:i]
}
if len(s) > 120 {
s = s[:120] + "…"
}
return s
}
-345
View File
@@ -1,345 +0,0 @@
package a2a
import (
"context"
"encoding/base64"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"sync"
"testing"
"time"
"agent-squad/squad"
)
// conformance_test.go — Q3 WP4 验收:双向 conformance(本地假 A2A 服务端)。
// 发布侧:BuildCard + CardHandler 在 well-known 路径服务合法 Agent Card;
// 消费侧:FetchCard 发现校验 + Executor 走完任务状态机
// (submitted→working→completed / failed / input-required),终态对齐
// squad.ExecResult。
// fakeA2AServer 最小 A2A 1.0 服务端:well-known 卡片 + JSON-RPC
// (message/send 建任务;tasks/get 按脚本推进状态)。
type fakeA2AServer struct {
mu sync.Mutex
card AgentCard
tasks map[string]*Task
plan []string // 每次 tasks/get 推进到的状态序列(走完停在末态)
calls map[string]int
artifacts []Artifact
statusMsg string
}
func newFakeServer(t *testing.T, card AgentCard, plan []string, artifacts []Artifact) *fakeA2AServer {
t.Helper()
s := &fakeA2AServer{card: card, tasks: map[string]*Task{}, plan: plan,
calls: map[string]int{}, artifacts: artifacts}
return s
}
func (s *fakeA2AServer) handler() http.Handler {
mux := http.NewServeMux()
mux.HandleFunc(WellKnownPath, func(w http.ResponseWriter, r *http.Request) {
s.mu.Lock()
body, _ := json.Marshal(s.card)
s.mu.Unlock()
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write(body)
})
mux.HandleFunc("/rpc", func(w http.ResponseWriter, r *http.Request) {
var req rpcRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeRPCError(w, 0, -32700, "parse error")
return
}
s.mu.Lock()
defer s.mu.Unlock()
s.calls[req.Method]++
switch req.Method {
case "message/send":
id := fmt.Sprintf("task_%d", len(s.tasks)+1)
state := StateSubmitted
if len(s.plan) > 0 {
state = s.plan[0]
}
task := &Task{Kind: "task", ID: id, ContextID: "ctx_1",
Status: TaskStatus{State: state, Message: s.statusMessage()}}
s.tasks[id] = task
writeRPCResult(w, req.ID, task)
case "tasks/get":
var params struct {
ID string `json:"id"`
}
raw, _ := json.Marshal(req.Params)
_ = json.Unmarshal(raw, &params)
task, ok := s.tasks[params.ID]
if !ok {
writeRPCError(w, req.ID, -32001, "task not found")
return
}
// 按脚本推进状态机(停留在终态)。
if !isTerminal(task.Status.State) && len(s.plan) > 0 {
n := s.calls["tasks/get#"+params.ID]
s.calls["tasks/get#"+params.ID] = n + 1
idx := n + 1
if idx >= len(s.plan) {
idx = len(s.plan) - 1
}
task.Status.State = s.plan[idx]
task.Status.Message = s.statusMessage()
if task.Status.State == StateCompleted {
task.Artifacts = s.artifacts
}
}
writeRPCResult(w, req.ID, task)
default:
writeRPCError(w, req.ID, -32601, "method not found")
}
})
return mux
}
func (s *fakeA2AServer) statusMessage() *Message {
if s.statusMsg == "" {
return nil
}
return &Message{Kind: "message", Role: "agent",
Parts: []Part{{Kind: "text", Text: s.statusMsg}}}
}
func writeRPCResult(w http.ResponseWriter, id int64, result any) {
body, _ := json.Marshal(result)
env, _ := json.Marshal(rpcResponse{JSONRPC: "2.0", ID: id, Result: body})
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write(env)
}
func writeRPCError(w http.ResponseWriter, id int64, code int, msg string) {
env, _ := json.Marshal(rpcResponse{JSONRPC: "2.0", ID: id, Error: &rpcError{Code: code, Message: msg}})
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write(env)
}
// ---- 发布侧 ----
func TestBuildCardFromRegistries(t *testing.T) {
reg := squad.NewRoleRegistry()
for _, r := range []squad.RoleSpec{
{Role: "researcher", Name: "调研员", Keywords: []string{"调研", "检索"},
Instructions: "围绕目标调研关键问题。\n第二行不进摘要。"},
{Role: "writer", Name: "撰稿员", Keywords: []string{"撰写"}},
} {
if err := reg.Register(r); err != nil {
t.Fatal(err)
}
}
bps := squad.NewBlueprintRegistry()
if err := bps.Register(squad.Blueprint{Key: "brief", Title: "简报",
Description: "生成简报", Match: []string{"简报", "brief"},
Steps: []squad.StepSpec{{ID: "s1", Role: "writer", Title: "成文"}}}); err != nil {
t.Fatal(err)
}
card, err := BuildCard(reg, bps, CardOptions{
Name: "示例小队", Description: "演示团队能力", URL: "https://team.example/rpc",
})
if err != nil {
t.Fatal(err)
}
if card.ProtocolVersion != ProtocolVersion || card.Version != "1.0.0" {
t.Fatalf("card = %+v", card)
}
byID := map[string]AgentSkill{}
for _, s := range card.Skills {
byID[s.ID] = s
}
if byID["researcher"].Name != "调研员" || byID["researcher"].Description != "围绕目标调研关键问题。" {
t.Fatalf("role skill = %+v", byID["researcher"])
}
if len(byID["researcher"].Tags) != 2 {
t.Fatalf("tags = %v", byID["researcher"].Tags)
}
if byID["brief"].Name != "简报" || strings.Join(byID["brief"].Examples, ",") != "简报,brief" {
t.Fatalf("blueprint skill = %+v", byID["brief"])
}
if _, err := BuildCard(reg, bps, CardOptions{}); err == nil {
t.Fatal("缺 URL 必须 fail-closed")
}
}
// CardHandler 以 JSON 服务卡片(发布端点形态)。
func TestCardHandlerServesJSON(t *testing.T) {
card := AgentCard{ProtocolVersion: ProtocolVersion, Name: "小队", URL: "https://x/rpc", Version: "1.0.0"}
ts := httptest.NewServer(CardHandler(card))
defer ts.Close()
resp, err := http.Get(ts.URL + WellKnownPath)
if err != nil {
t.Fatal(err)
}
defer resp.Body.Close()
if ct := resp.Header.Get("Content-Type"); ct != "application/json" {
t.Fatalf("content-type = %s", ct)
}
var got AgentCard
if err := json.NewDecoder(resp.Body).Decode(&got); err != nil {
t.Fatal(err)
}
if got.Name != "小队" || got.ProtocolVersion != ProtocolVersion {
t.Fatalf("card = %+v", got)
}
}
// ---- 消费侧:发现 + 状态机 ----
func TestFetchCardAndExecuteCompleted(t *testing.T) {
fileBytes := base64.StdEncoding.EncodeToString([]byte("notes 内容"))
artifacts := []Artifact{{
ArtifactID: "art1", Name: "调研结果",
Parts: []Part{
{Kind: "text", Text: "# 调研结论\n\n结论正文,长度足够作为交付物内容。"},
{Kind: "file", File: &FilePart{Name: "notes.md", Bytes: fileBytes, MimeType: "text/markdown"}},
},
}}
card := AgentCard{ProtocolVersion: ProtocolVersion, Name: "远端小队",
URL: "PLACEHOLDER", Version: "1.0.0"}
srv := newFakeServer(t, card, []string{StateWorking, StateWorking, StateCompleted}, artifacts)
ts := httptest.NewServer(srv.handler())
defer ts.Close()
srv.mu.Lock()
srv.card.URL = ts.URL + "/rpc"
srv.mu.Unlock()
// 发现:well-known 路径取卡并校验。
got, err := FetchCard(ts.Client(), ts.URL+WellKnownPath)
if err != nil {
t.Fatal(err)
}
if got.Name != "远端小队" || got.URL != ts.URL+"/rpc" {
t.Fatalf("card = %+v", got)
}
// 执行:submitted/working → completed,工件映射 patches。
var states []string
ex := NewExecutor(got)
ex.Client = ts.Client()
ex.PollInterval = 5 * time.Millisecond
ex.OnState = func(s string) { states = append(states, s) }
res, err := ex.Execute(context.Background(), squad.ExecRequest{
Prompt: "调研主题 X", Targets: []string{"output.md"},
})
if err != nil {
t.Fatal(err)
}
if !res.Success {
t.Fatalf("result = %+v", res)
}
if string(res.Patches["notes.md"]) != "notes 内容" {
t.Fatalf("file part 未落成 patch:%q", res.Patches["notes.md"])
}
if !strings.Contains(string(res.Patches["output.md"]), "调研结论") {
t.Fatalf("文本部件未写入目标:%q", res.Patches["output.md"])
}
joined := strings.Join(states, ",")
if !strings.Contains(joined, StateWorking) || !strings.HasSuffix(joined, StateCompleted) {
t.Fatalf("状态机迁移 = %v", states)
}
srv.mu.Lock()
sends := srv.calls["message/send"]
srv.mu.Unlock()
if sends != 1 {
t.Fatalf("message/send = %d", sends)
}
}
func TestExecuteMapsFailedAndInputRequired(t *testing.T) {
card := AgentCard{ProtocolVersion: ProtocolVersion, Name: "远端", URL: "PLACEHOLDER", Version: "1"}
srv := newFakeServer(t, card, []string{StateWorking, StateFailed}, nil)
srv.statusMsg = "远端执行崩溃"
ts := httptest.NewServer(srv.handler())
defer ts.Close()
srv.mu.Lock()
srv.card.URL = ts.URL + "/rpc"
srv.mu.Unlock()
ex := NewExecutor(card)
ex.BaseURL = ts.URL + "/rpc"
ex.Client = ts.Client()
ex.PollInterval = 5 * time.Millisecond
res, err := ex.Execute(context.Background(), squad.ExecRequest{Prompt: "x", Targets: []string{"output.md"}})
if err != nil {
t.Fatal(err)
}
if res.Success || !strings.Contains(res.ErrorReason, "failed") || !strings.Contains(res.ErrorReason, "远端执行崩溃") {
t.Fatalf("failed 映射 = %+v", res)
}
// input-required:fail-closed(跨进程人工输入不在适配面内)。
srv2 := newFakeServer(t, card, []string{StateInputRequired}, nil)
srv2.statusMsg = "请补充授权"
ts2 := httptest.NewServer(srv2.handler())
defer ts2.Close()
ex2 := &Executor{BaseURL: ts2.URL + "/rpc", Client: ts2.Client(), PollInterval: 5 * time.Millisecond}
res2, err := ex2.Execute(context.Background(), squad.ExecRequest{Prompt: "x", Targets: []string{"output.md"}})
if err != nil {
t.Fatal(err)
}
if res2.Success || !strings.Contains(res2.ErrorReason, "input-required") {
t.Fatalf("input-required 映射 = %+v", res2)
}
}
// 直接回 Message(无任务态)→ 文本落目标。
func TestExecuteDirectMessageResult(t *testing.T) {
ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var req rpcRequest
_ = json.NewDecoder(r.Body).Decode(&req)
writeRPCResult(w, req.ID, Message{Kind: "message", Role: "agent",
Parts: []Part{{Kind: "text", Text: "直接回答正文"}}})
}))
defer ts.Close()
ex := &Executor{BaseURL: ts.URL, Client: ts.Client()}
res, err := ex.Execute(context.Background(), squad.ExecRequest{Prompt: "x", Targets: []string{"output.md"}})
if err != nil {
t.Fatal(err)
}
if !res.Success || !strings.Contains(string(res.Patches["output.md"]), "直接回答正文") {
t.Fatalf("res = %+v", res)
}
}
// 传输/协议错误 → error(引擎按瞬态评估),不吞成成功。
func TestExecuteProtocolErrors(t *testing.T) {
ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
writeRPCError(w, 1, -32601, "method not found")
}))
defer ts.Close()
ex := &Executor{BaseURL: ts.URL, Client: ts.Client()}
if _, err := ex.Execute(context.Background(), squad.ExecRequest{Prompt: "x"}); err == nil ||
!strings.Contains(err.Error(), "协议错误") {
t.Fatalf("err = %v", err)
}
// ctx 取消传播。
ctx, cancel := context.WithCancel(context.Background())
cancel()
slow := newFakeServer(t, AgentCard{ProtocolVersion: "1.0", Name: "x", URL: ts.URL, Version: "1"},
[]string{StateWorking}, nil)
ts2 := httptest.NewServer(slow.handler())
defer ts2.Close()
ex2 := &Executor{BaseURL: ts2.URL + "/rpc", Client: ts2.Client(), PollInterval: time.Second}
if _, err := ex2.Execute(ctx, squad.ExecRequest{Prompt: "x"}); err == nil {
t.Fatal("取消必须传播")
}
}
// FetchCard fail-closed:缺必备字段拒绝。
func TestFetchCardValidates(t *testing.T) {
ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = w.Write([]byte(`{"protocolVersion":"1.0","name":"","url":"","version":""}`))
}))
defer ts.Close()
if _, err := FetchCard(ts.Client(), ts.URL); err == nil || !strings.Contains(err.Error(), "name") {
t.Fatalf("err = %v", err)
}
}
-331
View File
@@ -1,331 +0,0 @@
package a2a
import (
"bytes"
"context"
"encoding/base64"
"encoding/json"
"fmt"
"io"
"net/http"
"strings"
"sync/atomic"
"time"
"agent-squad/squad"
)
// executor.go — 远端智能体 Executor 客户端(A2A 任务状态机对齐 ExecResult)。
// 任务状态(A2A 1.0 TaskState)。
const (
StateSubmitted = "submitted"
StateWorking = "working"
StateInputRequired = "input-required"
StateCompleted = "completed"
StateCanceled = "canceled"
StateFailed = "failed"
StateRejected = "rejected"
)
// DefaultPollInterval 是 tasks/get 轮询缺省间隔。
const DefaultPollInterval = 500 * time.Millisecond
// Executor 把远端 A2A 智能体接成 squad.Executor:一次步骤执行 = 一个
// A2A 任务(message/send 发起,tasks/get 轮询到终态)。
type Executor struct {
// BaseURL 远端 JSON-RPC 端点(Agent Card 的 url)。
BaseURL string
// Client HTTP 客户端(nil = http.DefaultClient)。
Client *http.Client
// PollInterval 轮询间隔(0 = DefaultPollInterval)。
PollInterval time.Duration
// OnState 可选状态回调(观测任务状态机迁移)。
OnState func(state string)
callID atomic.Int64
}
// NewExecutor 按 Agent Card 构造远端执行器。
func NewExecutor(card AgentCard) *Executor {
return &Executor{BaseURL: card.URL}
}
// Name 实现 squad.Executor。
func (e *Executor) Name() string { return "a2a" }
// ---- A2A 1.0 报文形态(JSON-RPC 2.0) ----
type rpcRequest struct {
JSONRPC string `json:"jsonrpc"`
ID int64 `json:"id"`
Method string `json:"method"`
Params any `json:"params"`
}
type rpcError struct {
Code int `json:"code"`
Message string `json:"message"`
}
type rpcResponse struct {
JSONRPC string `json:"jsonrpc"`
ID int64 `json:"id"`
Result json.RawMessage `json:"result,omitempty"`
Error *rpcError `json:"error,omitempty"`
}
// Part 是消息/工件的部件(text | file | data)。
type Part struct {
Kind string `json:"kind"`
Text string `json:"text,omitempty"`
File *FilePart `json:"file,omitempty"`
Data *json.RawMessage `json:"data,omitempty"`
}
// FilePart 文件部件:bytes(base64)或 uri 二选一。
type FilePart struct {
Name string `json:"name"`
Bytes string `json:"bytes,omitempty"`
URI string `json:"uri,omitempty"`
MimeType string `json:"mimeType,omitempty"`
}
// Message 是一条 A2A 消息。
type Message struct {
Kind string `json:"kind"`
Role string `json:"role"`
Parts []Part `json:"parts"`
MessageID string `json:"messageId"`
}
// TaskStatus 任务状态。
type TaskStatus struct {
State string `json:"state"`
Message *Message `json:"message,omitempty"`
Timestamp string `json:"timestamp,omitempty"`
}
// Artifact 任务工件。
type Artifact struct {
ArtifactID string `json:"artifactId,omitempty"`
Name string `json:"name,omitempty"`
Parts []Part `json:"parts"`
}
// Task 是 A2A 任务(状态机载体)。
type Task struct {
Kind string `json:"kind"`
ID string `json:"id"`
ContextID string `json:"contextId,omitempty"`
Status TaskStatus `json:"status"`
Artifacts []Artifact `json:"artifacts,omitempty"`
}
// Execute 实现 squad.Executor:发起任务并轮询到终态,映射 ExecResult。
// 传输/协议错误返回 error(引擎按瞬态失败评估);任务级失败
// (failed/canceled/rejected/input-required)返回 Success=false 的结果
// (fail-closed:跨进程人工输入不在本适配面内)。
func (e *Executor) Execute(ctx context.Context, req squad.ExecRequest) (*squad.ExecResult, error) {
if strings.TrimSpace(e.BaseURL) == "" {
return nil, fmt.Errorf("a2a: executor 缺 BaseURL")
}
prompt := strings.TrimSpace(req.Prompt)
if prompt == "" {
prompt = strings.TrimSpace(req.Instructions)
}
msg := Message{
Kind: "message", Role: "user",
Parts: []Part{{Kind: "text", Text: prompt}},
MessageID: fmt.Sprintf("msg-%d-%d", time.Now().UnixNano(), e.callID.Add(1)),
}
raw, err := e.call(ctx, "message/send", map[string]any{"message": msg})
if err != nil {
return nil, err
}
// 服务端可直接回 Message(无任务态)或 Task。
var probe struct {
Kind string `json:"kind"`
}
_ = json.Unmarshal(raw, &probe)
if probe.Kind == "message" {
var m Message
if err := json.Unmarshal(raw, &m); err != nil {
return nil, fmt.Errorf("a2a: message 结果解析失败: %w", err)
}
return e.resultFromParts(m.Parts, req.Targets), nil
}
var task Task
if err := json.Unmarshal(raw, &task); err != nil {
return nil, fmt.Errorf("a2a: task 结果解析失败: %w", err)
}
e.observe(task.Status.State)
if shouldStop(task.Status.State) {
return e.resultFromTask(task, req.Targets), nil
}
// 轮询任务状态机直至终态(ctx 取消传播)。
interval := e.PollInterval
if interval <= 0 {
interval = DefaultPollInterval
}
ticker := time.NewTicker(interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-ticker.C:
}
raw, err := e.call(ctx, "tasks/get", map[string]any{"id": task.ID})
if err != nil {
return nil, err
}
var next Task
if err := json.Unmarshal(raw, &next); err != nil {
return nil, fmt.Errorf("a2a: tasks/get 解析失败: %w", err)
}
if next.Status.State != task.Status.State {
task = next
e.observe(task.Status.State)
} else {
task = next
}
if shouldStop(task.Status.State) {
return e.resultFromTask(task, req.Targets), nil
}
}
}
// call 发一次 JSON-RPC 调用并取 result。
func (e *Executor) call(ctx context.Context, method string, params any) (json.RawMessage, error) {
client := e.Client
if client == nil {
client = http.DefaultClient
}
body, _ := json.Marshal(rpcRequest{
JSONRPC: "2.0", ID: e.callID.Add(1), Method: method, Params: params,
})
req, err := http.NewRequestWithContext(ctx, http.MethodPost, e.BaseURL, bytes.NewReader(body))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
return nil, fmt.Errorf("a2a: %s 传输失败: %w", method, err)
}
defer resp.Body.Close()
data, err := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
if err != nil {
return nil, fmt.Errorf("a2a: %s 读取响应失败: %w", method, err)
}
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("a2a: %s 返回 HTTP %d", method, resp.StatusCode)
}
var env rpcResponse
if err := json.Unmarshal(data, &env); err != nil {
return nil, fmt.Errorf("a2a: %s 响应不是合法 JSON-RPC: %w", method, err)
}
if env.Error != nil {
return nil, fmt.Errorf("a2a: %s 协议错误 %d: %s", method, env.Error.Code, env.Error.Message)
}
return env.Result, nil
}
func (e *Executor) observe(state string) {
if e.OnState != nil {
e.OnState(state)
}
}
func isTerminal(state string) bool {
switch state {
case StateCompleted, StateFailed, StateCanceled, StateRejected:
return true
}
return false
}
// shouldStop 轮询停止条件:真终态,或 input-required(跨进程人工输入不在
// 本适配面内,fail-closed 交引擎语义处理,不死等)。
func shouldStop(state string) bool {
return isTerminal(state) || state == StateInputRequired
}
// resultFromTask 终态任务 → ExecResult。
func (e *Executor) resultFromTask(task Task, targets []string) *squad.ExecResult {
switch task.Status.State {
case StateCompleted:
var parts []Part
for _, art := range task.Artifacts {
parts = append(parts, art.Parts...)
}
return e.resultFromParts(parts, targets)
case StateInputRequired:
return &squad.ExecResult{Success: false,
ErrorReason: "a2a: 远端要求人工输入(input-required):" + statusText(task.Status)}
case StateCanceled:
return &squad.ExecResult{Success: false,
ErrorReason: "a2a: 远端任务被取消(canceled):" + statusText(task.Status)}
case StateRejected:
return &squad.ExecResult{Success: false,
ErrorReason: "a2a: 远端拒绝任务(rejected):" + statusText(task.Status)}
default: // failed 及未知终态一律 fail-closed
return &squad.ExecResult{Success: false,
ErrorReason: "a2a: 远端任务失败(" + task.Status.State + "):" + statusText(task.Status)}
}
}
// resultFromParts 部件流 → patches:FilePart(bytes) 按名落 patch;
// 文本部件拼接后写入全部声明目标(无文件工件时的交付物兜底,
// 与其他后端「正文写目标文件」契约一致)。
func (e *Executor) resultFromParts(parts []Part, targets []string) *squad.ExecResult {
patches := map[string][]byte{}
var text strings.Builder
for _, p := range parts {
switch p.Kind {
case "text":
if text.Len() > 0 {
text.WriteString("\n")
}
text.WriteString(p.Text)
case "file":
if p.File == nil || p.File.Name == "" {
continue
}
data, err := base64.StdEncoding.DecodeString(p.File.Bytes)
if err != nil {
continue // uri 形态与坏 base64 不落 patch(消费侧最小面)
}
patches[p.File.Name] = data
}
}
body := strings.TrimSpace(text.String())
if len(targets) == 0 {
targets = []string{"output.md"}
}
if body != "" {
for _, t := range targets {
if _, ok := patches[t]; !ok {
patches[t] = []byte(body + "\n")
}
}
}
if len(patches) == 0 {
return &squad.ExecResult{Success: false, ErrorReason: "a2a: 完成任务无任何工件"}
}
return &squad.ExecResult{Success: true, Patches: patches, Logs: body}
}
func statusText(st TaskStatus) string {
if st.Message == nil {
return ""
}
var b strings.Builder
for _, p := range st.Message.Parts {
if p.Kind == "text" {
b.WriteString(p.Text)
}
}
return b.String()
}
-11
View File
@@ -1,11 +0,0 @@
module agent-squad/adapters/a2a
go 1.27
require agent-squad v0.0.0
require error-code-system v0.0.0 // indirect
replace agent-squad => ../..
replace error-code-system => ../../deps/error-code-system
+3 -105
View File
@@ -3,11 +3,7 @@ package native
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"reflect"
"strings"
"time"
@@ -56,58 +52,12 @@ type Config struct {
PermissionAsk func(ctx context.Context, call llm.ToolCall) runtime.AskVerdict
}
// Identity 返回塑造 Executor 的配置摘要(模型/客户端/工具/Exec 等)。
// RegisterFull 经 BackendResolver.Register 替换工厂时会失效缓存;角色侧
// BashPermission 等由 squad.ConfigIdentity 纳入 Resolve 缓存键,故 allow→deny
// 在下一次 Resolve 即生效,无需重启进程。
func (c Config) Identity() string {
var b strings.Builder
b.WriteString("model=")
b.WriteString(c.DefaultModel)
b.WriteString("\x00turns=")
b.WriteString(fmt.Sprintf("%d", c.MaxTurns))
b.WriteString("\x00timeout=")
b.WriteString(c.Timeout.String())
if c.Client != nil {
b.WriteString("\x00base=")
b.WriteString(c.Client.BaseURL)
b.WriteString("\x00key=")
b.WriteString(c.Client.APIKey)
}
if c.Exec != nil {
b.WriteString("\x00exec.bash=")
b.WriteString(c.Exec.Bash)
b.WriteString("\x00exec.python=")
b.WriteString(c.Exec.Python)
}
if c.Search != nil {
b.WriteString("\x00search=1")
}
if c.Fetch != nil {
b.WriteString("\x00fetch=1")
}
if c.MCP != nil {
b.WriteString("\x00mcp=1")
}
if len(c.SkillsRoots) > 0 {
b.WriteString("\x00skills=")
b.WriteString(strings.Join(c.SkillsRoots, ","))
}
if c.CodeOrchestration {
b.WriteString("\x00code=1")
}
sum := sha256.Sum256([]byte(b.String()))
return hex.EncodeToString(sum[:16])
}
// Register 把 "agent-native" 工厂注册进解析器。
func Register(r *squad.BackendResolver, client *llm.Client, defaultModel string, maxTurns int, timeout time.Duration) {
RegisterFull(r, Config{Client: client, DefaultModel: defaultModel, MaxTurns: maxTurns, Timeout: timeout})
}
// RegisterFull 注册带工具装配的 "agent-native" 工厂。
// 再次调用会替换工厂并失效该后端缓存(见 BackendResolver.Register);
// 配置摘要见 Config.Identity,角色侧见 squad.ConfigIdentity。
func RegisterFull(r *squad.BackendResolver, cfg Config) {
r.Register("agent-native", func(role squad.RoleSpec) (squad.Executor, error) {
opts, err := buildOptions(cfg, role)
@@ -197,62 +147,10 @@ func toNative(req squad.ExecRequest) exec.Request {
}
func fromNative(res *exec.Result) *squad.ExecResult {
if res == nil {
return nil
return &squad.ExecResult{
Success: res.Success, Patches: res.Patches, Logs: res.Logs, ErrorReason: res.ErrorReason,
Retryable: res.Retryable, PromptTokens: res.PromptTokens, CompletionTokens: res.CompletionTokens,
}
out := &squad.ExecResult{
Success: res.Success,
Patches: res.Patches,
Logs: res.Logs,
ErrorReason: res.ErrorReason,
Retryable: res.Retryable,
PromptTokens: res.PromptTokens,
CompletionTokens: res.CompletionTokens,
}
// F05/U3b(Squad 侧 contract):
// - native exec.Result 在后续 release 会新增 SideEffects、Canceled、Aborted 字段;
// 本地 deps gitlink 若尚未跟进,从 JSON 探测拿不到这些字段时回落到
// 「legacy reading: side effects = possible」,与既有调用方旧行为一致。
// - 在不影响 ExecResult 默认值的前提下,用 JSON 探测而非硬性修改 deps。
probe, err := probeNativeResultExtras(res)
if err == nil {
out.SideEffects = probe.SideEffects
out.Canceled = probe.Canceled
out.Aborted = probe.Aborted
}
return out
}
// nativeResultExtras 探测 native exec.Result 上的可选字段(结构化 JSON)。
// 缺省(字段不存在或为零值时)按 legacy reading:SideEffects 空串视为 "possible";
// 调用方侧 ExecResult.IsRetryableSideEffectReports() 已经处理该回退。
type nativeResultExtras struct {
SideEffects squad.ExecSideEffects `json:"side_effects,omitempty"`
Canceled bool `json:"canceled,omitempty"`
Aborted bool `json:"aborted,omitempty"`
}
// probeNativeResultExtras 通过 JSON 探测 native Result 上的可选字段。
// 探测出 cancel/abort/side_effects 任何一个就使用它们;探测失败或全部为零值视为
// legacy reading(SideEffects 空 = possible 兜底)。
func probeNativeResultExtras(res *exec.Result) (nativeResultExtras, error) {
if res == nil {
return nativeResultExtras{}, fmt.Errorf("nil result")
}
v := reflect.ValueOf(res).Elem()
if !v.IsValid() {
return nativeResultExtras{}, fmt.Errorf("invalid result")
}
// 用 JSON 做结构化探测:这一路兼容 deps 升级(增字段)、不增字段两种情形。
data, err := json.Marshal(v.Interface())
if err != nil {
return nativeResultExtras{}, err
}
var out nativeResultExtras
if err := json.Unmarshal(data, &out); err != nil {
return nativeResultExtras{}, err
}
return out, nil
}
type eventTap struct {
-82
View File
@@ -47,85 +47,3 @@ func TestBuildOptionsBashPermissionGating(t *testing.T) {
t.Fatal("missing model must fail-closed")
}
}
func TestConfigIdentityReflectsToolAndClient(t *testing.T) {
base := Config{
Client: &llm.Client{BaseURL: "http://x", APIKey: "k"},
DefaultModel: "m1", MaxTurns: 5, Timeout: time.Minute,
Exec: &tools.ExecConfig{Bash: "/bin/bash"},
}
otherExec := base
otherExec.Exec = &tools.ExecConfig{Bash: "/bin/zsh"}
if base.Identity() == otherExec.Identity() {
t.Fatal("Exec tool-config change must change Config.Identity")
}
otherClient := base
otherClient.Client = &llm.Client{BaseURL: "http://y", APIKey: "k"}
if base.Identity() == otherClient.Identity() {
t.Fatal("client change must change Config.Identity")
}
same := base
if base.Identity() != same.Identity() {
t.Fatal("identical config must keep Identity stable")
}
}
func TestRegisterFullAllowDenyTakesEffectOnNextResolve(t *testing.T) {
r := squad.NewBackendResolver()
cfg := Config{
Client: &llm.Client{BaseURL: "http://x", APIKey: "k"},
DefaultModel: "m1", MaxTurns: 1, Timeout: time.Second,
Exec: &tools.ExecConfig{Bash: "/bin/bash"},
}
RegisterFull(r, cfg)
allowRole := squad.RoleSpec{Role: "eng", Backend: "agent-native", Model: "m1", BashPermission: squad.BashPermissionAllow}
denyRole := squad.RoleSpec{Role: "eng", Backend: "agent-native", Model: "m1", BashPermission: squad.BashPermissionDeny}
eAllow, _, err := r.Resolve(allowRole, "")
if err != nil {
t.Fatal(err)
}
eDeny, _, err := r.Resolve(denyRole, "")
if err != nil {
t.Fatal(err)
}
if eAllow == eDeny {
t.Fatal("allow→deny must not reuse cached executor on next Resolve")
}
// Identity of role configs must diverge so cache keys differ.
if squad.ConfigIdentity(allowRole) == squad.ConfigIdentity(denyRole) {
t.Fatal("role ConfigIdentity must include BashPermission")
}
}
func TestRegisterFullToolConfigReplacementTakesEffect(t *testing.T) {
r := squad.NewBackendResolver()
cfg1 := Config{
Client: &llm.Client{BaseURL: "http://x", APIKey: "k"},
DefaultModel: "m1", MaxTurns: 1, Timeout: time.Second,
Exec: &tools.ExecConfig{Bash: "/bin/bash"},
}
cfg2 := Config{
Client: &llm.Client{BaseURL: "http://x", APIKey: "k"},
DefaultModel: "m1", MaxTurns: 1, Timeout: time.Second,
Exec: &tools.ExecConfig{Bash: "/bin/zsh"},
}
if cfg1.Identity() == cfg2.Identity() {
t.Fatal("precondition: tool configs must differ in Identity")
}
RegisterFull(r, cfg1)
role := squad.RoleSpec{Role: "eng", Backend: "agent-native", Model: "m1", BashPermission: squad.BashPermissionAllow}
e1, _, err := r.Resolve(role, "")
if err != nil {
t.Fatal(err)
}
RegisterFull(r, cfg2)
e2, _, err := r.Resolve(role, "")
if err != nil {
t.Fatal(err)
}
if e1 == e2 {
t.Fatal("RegisterFull tool-config replacement must invalidate cache")
}
}
+1 -76
View File
@@ -4,7 +4,6 @@ import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"time"
@@ -128,7 +127,7 @@ func TestEngineRunsOnSQLiteStore(t *testing.T) {
}
}
backends := squad.NewBackendResolver()
backends.RegisterInstance("script", stubExecutor{result: &squad.ExecResult{Success: true, Logs: "ok", Patches: map[string][]byte{"output.md": []byte(goodReportLite), "notes.md": []byte(goodReportLite), "fields.json": []byte("{}")}}})
backends.RegisterInstance("script", stubExecutor{result: &squad.ExecResult{Success: false, Logs: "ok", Patches: map[string][]byte{"output.md": []byte(goodReportLite), "notes.md": []byte(goodReportLite), "fields.json": []byte("{}")}}})
blueprints := squad.NewBlueprintRegistry()
if err := blueprints.Register(squad.Blueprint{
Key: "demo", Title: "入库演示", Match: []string{"入库演示"},
@@ -186,78 +185,4 @@ func TestEngineRunsOnSQLiteStore(t *testing.T) {
}
}
// TestEngineFailedResultWithCompletePatchesStaysFailedOnSQLiteStore:F05/U3B 的
// 不变式在 SQLite-store 集成层同样成立——executor 报失败就是失败,patches
// (交付物)齐全也不得把运行翻成 completed:文件只是诊断信息,不是权威结果。
func TestEngineFailedResultWithCompletePatchesStaysFailedOnSQLiteStore(t *testing.T) {
runStore, err := OpenSQLiteStore(filepath.Join(t.TempDir(), "runs.db"))
if err != nil {
t.Fatal(err)
}
defer runStore.Close()
dir := t.TempDir()
reg := squad.NewRoleRegistry()
if err := reg.Register(squad.RoleSpec{Role: "researcher", Backend: "script"}); err != nil {
t.Fatal(err)
}
backends := squad.NewBackendResolver()
// 失败结果但携带全套交付物:旧语义会把它提升为成功,U3B 起必须保持失败。
backends.RegisterInstance("script", stubExecutor{result: &squad.ExecResult{
Success: false, Logs: "stub-refused",
Patches: map[string][]byte{
"output.md": []byte(goodReportLite),
"notes.md": []byte(goodReportLite),
"fields.json": []byte("{}"),
},
}})
blueprints := squad.NewBlueprintRegistry()
if err := blueprints.Register(squad.Blueprint{
Key: "faildemo", Title: "失败演示", Match: []string{"失败演示"},
Steps: []squad.StepSpec{{ID: "s1", Role: "researcher", Title: "调研", Targets: []string{"output.md"}}},
}); err != nil {
t.Fatal(err)
}
eng, err := squad.NewEngine(squad.Options{
DataDir: dir, Registry: reg, Blueprints: blueprints,
Planner: squad.NewRulePlanner(),
Backends: backends, Sink: squad.NopSink{},
Store: runStore,
})
if err != nil {
t.Fatal(err)
}
res, err := eng.Run(context.Background(), squad.Goal{Text: "做一个失败演示", HitlMode: squad.HitlAuto}, squad.RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status == squad.RunCompleted {
t.Fatalf("failed executor result must not complete (patches are diagnostic only)")
}
if res.Status != squad.RunFailed {
t.Fatalf("status = %s, want failed", res.Status)
}
if res.Plan == nil || res.Plan.Steps[0].Status != "failed" {
t.Fatalf("s1 should be failed, plan = %+v", res.Plan)
}
if !strings.Contains(res.Error, "stub-refused") {
t.Fatalf("failure reason not preserved: %q", res.Error)
}
// 同一断言穿过 Store 端口:SQLite 里落盘的也是失败,而非 completed。
st, err := runStore.LoadRun(res.WorkDir)
if err != nil {
t.Fatal(err)
}
if st.Plan.Workflow.Status != "failed" {
t.Fatalf("persisted workflow status = %s, want failed", st.Plan.Workflow.Status)
}
if got := st.Plan.Workflow.Steps[0]; got.Status != "failed" || !strings.Contains(got.Error, "stub-refused") {
t.Fatalf("persisted step = %+v", got)
}
// patches 确已物化(文件齐全),依然不翻转状态:权威是执行结果,不是文件。
sub := filepath.FromSlash(st.Plan.Workflow.Steps[0].SubWorkspace)
if _, err := os.Stat(filepath.Join(res.WorkDir, sub, "output.md")); err != nil {
t.Fatalf("diagnostic patch should still be materialized: %v", err)
}
}
const goodReportLite = "# 测试交付物\n\n## 概述\n\n这是由脚本后端生成的合格交付物,长度超过五十个字符以满足最小质检要求。\n"
+11 -16
View File
@@ -1,26 +1,24 @@
# 通用规范采纳记录
- 项目/负责人:Agent-Squad / weichen
- 项目/负责人:Agent-Squad / 仓库所有者 weichen
- 状态:active
- 规范位置:`deps/development-guidelines`
- 规范性文档目录:`policy/`
- 过程文档位置:任务卡在 `.task/`(`.task/feature-governance-adoption.md`);任务主记录在 Gitea PR 中维护。既有过程记录仍按项目内固定目录豁免留在 `docs/records/`。过程记录不进规范库,也不写成与 Issue/PR 平行的第二状态。
- 版本权威:本仓 gitlink deps/development-guidelines @ 2688fd2be6a5(完整 `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`,内容版本 `0.1.0-draft.12`,无已发布标签)
- 批准/生效依据:`feature/governance-adoption PR(Agent-Squad)`
- 替代范围和迁移说明:本次替代 2026-09-29 采纳的固定版本 `26b562d2e34f`(内容版本 `0.1.0-draft.6`),规则条目按 `0.1.0-draft.12` 重新核对。新增 `AGENT-EXECUTION.md` 执行路由、`deps/development-manager` gitlink(`bd3a7de57a3a`)、`scripts/dm`、`scripts/agent-exec`、`scripts/task`、`scripts/hooks/pre-commit`、`.gitea/workflows/governance.yml` 与任务卡模板。不改业务代码,不改既有 `.gitea/workflows/ci.yml`。此前迁移说明见 `docs/records/2026-09-29-guidelines-and-observability.md`。
- 过程文档位置:`docs/records/`(项目内固定目录豁免。个人维护的编排库,任务主记录仍在 Gitea Issue/PR。过程记录不进规范库,也不写成与 Issue 平行的第二状态。)
- 版本权威:父仓 gitlink;可读标签:无(内容版本 `0.1.0-draft.6`,提交 `26b562d2e34fbc560711296a309c91c74ffc55b1`)
- 批准/生效依据:本仓接入提交
- 替代范围和迁移说明:本仓此前没有根 `AGENTS.md`。Agent-Native 子模块已从仓库根迁到 `deps/agent-native`,迁移说明见 `docs/records/2026-09-29-guidelines-and-observability.md`。
| 规范/工作流 | 适用条件与范围 | 采纳或不适用理由 | 执行方式/证据 |
|---|---|---|---|
| core/baseline.md | 日常工作 | 编排库对外有失败关闭语义 | manual |
| workflows/delivery.md、debugging.md、handoff.md | 交付、排障与交接 | 跨仓组合需要可交接记录 | manual |
| standards/collaboration.md | 并行共同起点与组合升级 | 父仓 gitlink 锁定 Agent-Native 与基础库 | manual |
| standards/merge-queue.md | 多个就绪任务的最终同步、CI、Review 与合入调度 | 多个 agent 单元并行开发,合入须串行同步;协调者为仓库所有者 | manual |
| standards/verification.md | 验证与结论 | `GOWORK=off go test` | manual;命令见 PROJECT.md(含 `scripts/agent-exec validate --repo .`、`scripts/dm governance check --repo .`) |
| standards/verification.md | 验证与结论 | `GOWORK=off go test` | manual;命令见 PROJECT.md |
| workflows/design-verification.md、standards/testability.md、standards/failure-containment.md | 规划、执行、HITL | conformance 覆盖公开 API | manual |
| standards/module-contracts.md | squad 与 agent-native 边界 | 依赖方向只允许 squad → agent-native | manual |
| standards/observability.md | HTTP 信封、trace、事件 | 接入错误码库与日志库 | manual |
| standards/agent-execution.md | 工程 Agent CLI 执行路由、会话隔离与受控集成 | 凡允许 AI 协助工程变更必须采纳;路由配置见 AGENT-EXECUTION.md;本库不实现 Agent | 执行方式:AGENT-EXECUTION.md + scripts/agent-exec(validate / admit);证据:`governance check + 正负例(.task/feature-governance-adoption.md)` |
| standards/tool-adaptation.md | 为具体工具创建规则与钩子 | 本次引入 `scripts/hooks/pre-commit`(启用由 host/人执行,`core.hooksPath`) | manual;启用后以本仓 pre-commit 检查为证据 |
| standards/agent-execution.md | 角色绑定的执行后端 | 本库不实现 Agent | manual |
| standards/multi-repo.md | 多级 submodule | 本仓 replace 是编译时的唯一依赖解析 | manual |
| standards/data-reliability.md | 运行目录、HITL 恢复、幂等回应 | 磁盘为权威 | manual |
| standards/security.md | bash 权限挂起、脱敏 | 事件落盘沿用现有脱敏;凭证走环境变量 | manual |
@@ -33,17 +31,14 @@
| 原规则/章节 | 项目采用方式 | 原因与风险 | 负责人/复查条件 |
|---|---|---|---|
| documentation.md 过程仓默认独立仓库 | 其他过程记录放 `docs/records/`(既有过程记录的项目内固定目录豁免) | 同 Agent-Native:避免个人项目再维护一个过程仓。风险是过程记录与代码同库 | 多人协作或对外发布时复查 |
| documentation.md 过程仓默认独立仓库 | 任务卡与交付证据放 `.task/`(模板 `.task/templates/task-card.md`) | 任务状态仍只认 Gitea Issue/PR,`.task/` 不写成平行状态;风险是任务卡与代码同库 | 多人协作或对外发布时复查 |
| documentation.md 过程仓默认独立仓库 | 过程记录放 `docs/records/` | 同 Agent-Native:避免个人项目再维护一个过程仓。风险是证据与代码同库 | 多人协作或对外发布时复查 |
| multi-repo.md 组件说明不手写第二套 SHA | PROJECT.md 只写路径与角色,SHA 以 `git submodule status` 为准 | 手抄 SHA 会与 gitlink 漂移 | 每次依赖升级核对脚本 |
## 本次升级或首次接入验证
- `deps/development-guidelines` 固定 `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`(内容版本 `0.1.0-draft.12`);`deps/development-manager` 固定 `bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c`。
- 工程 Agent 执行:`AGENT-EXECUTION.md` 为唯一路由权威;AI 实施单元只经 `scripts/agent-exec run` 执行,并经 `scripts/agent-exec apply` 集成。`scripts/agent-exec` 与 `scripts/task` 只是转调 `scripts/dm` 的薄入口。
- 登记为 active 的前置证据:一次成功执行正例(有效 `completed` 收据经 transport/admission 集成);缺配置、无效终态收据、越权路径、未知副作用四类负例均被拒绝或 fail-stop。证据按 `.task/feature-governance-adoption.md` 记录。
- 入口核验:`scripts/dm governance check --repo .` 与 `scripts/agent-exec validate --repo .`(PROJECT.md「验证」节)。CI 由 `.gitea/workflows/governance.yml` 执行;既有 `ci.yml` 未改。
- 回退该规范挂载时,恢复上一已批准 gitlink `26b562d2e34f`,并同时还原本次新增的治理脚本与 `governance.yml`;如已启用 `core.hooksPath`,需一并关闭。只还原规范 gitlink 不会把 `deps/agent-native` 移回根目录。
- `deps/development-guidelines` 固定 `26b562d2e34fbc560711296a309c91c74ffc55b1`。
- 执行方式为 manual。
- 回退该规范挂载时,同时确认 Agent-Native 子模块路径是否已迁移;只还原规范 gitlink 不会把 `deps/agent-native` 移回根目录。
### 2026-09-29 追加:agent-intent 可选意图闸门
-4
View File
@@ -1,4 +0,0 @@
#!/usr/bin/env bash
# 共享 Agent 执行器薄入口:转调 scripts/dm 的 agent-exec 子命令(validate / run / apply / admit / cleanup)。
set -euo pipefail
exec "$(dirname "$0")/dm" agent-exec "$@"
-55
View File
@@ -1,55 +0,0 @@
#!/usr/bin/env bash
# 共享 dm-server 薄入口:读取 deps/development-manager 的 gitlink 钉住提交,
# 按该提交构建并缓存 dm-server,再 exec 其子命令(agent-exec、task、governance)。执行语义与退出码以该二进制为准。
set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)
dm="$root/deps/development-manager"
die() { echo "dm: $*" >&2; exit 2; }
# git 钩子会导出仓库本地变量(GIT_DIR、GIT_INDEX_FILE 等),它们会让 `git -C "$dm"` 解析到外层仓库。
# 所有针对 DM 检出的 git 与 go 调用都在清除这些变量后执行;读取外层 gitlink 与最终 exec 仍保留继承环境。
dm_local_env="GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_PREFIX GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_GRAFT_FILE GIT_NAMESPACE GIT_CONFIG GIT_CONFIG_PARAMETERS GIT_CONFIG_COUNT GIT_SHALLOW_FILE GIT_IMPLICIT_WORK_TREE $(git rev-parse --local-env-vars 2>/dev/null || true)"
dm_clean_env() { for v in $dm_local_env; do unset "$v"; done; }
dmgit() ( dm_clean_env; git -C "$dm" "$@" )
# 1. 钉住版本只来自索引中的 gitlink(mode 160000),不读取工作区文件。
entry=$(git -C "$root" ls-files -s -- deps/development-manager 2>/dev/null || true)
[ -n "$entry" ] || die "索引中缺少 deps/development-manager 的 gitlink,无法确定钉住的 DM 版本"
read -r mode pin _stage _path <<<"$entry"
[ "$mode" = 160000 ] || die "deps/development-manager 不是 gitlink(mode=$mode)"
[[ "$pin" =~ ^[0-9a-f]{40}$ ]] || die "gitlink 提交格式无效:$pin"
# 2. 检出必须存在且确为 DM 独立仓库(避免 git -C 误解析到外层仓库),HEAD 必须等于钉住提交。
[ -e "$dm/.git" ] || die "deps/development-manager 未检出;请按钉住提交 $pin 检出该 gitlink"
top=$(dmgit rev-parse --show-toplevel 2>/dev/null || true)
[ -n "$top" ] && [ "$top" = "$(cd "$dm" && pwd -P)" ] \
|| die "deps/development-manager 不是独立检出;请按钉住提交 $pin 检出该 gitlink"
head=$(dmgit rev-parse HEAD 2>/dev/null || true)
[ "$head" = "$pin" ] \
|| die "deps/development-manager HEAD(${head:-未知})与钉住提交 $pin 不一致;请按钉住提交检出"
# 3. 检出工作树必须干净(忽略嵌套 submodule 状态)。
dirty=$(dmgit status --porcelain --ignore-submodules=all) \
|| die "无法读取 deps/development-manager 的工作树状态"
[ -z "$dirty" ] || die "deps/development-manager 存在未提交改动,拒绝运行(请先清理该检出)"
# 4. 二进制按钉住提交缓存;缺失时在缓存目录内临时构建,完成后原子改名,避免留下半成品。
cache="${DM_CACHE:-${XDG_CACHE_HOME:-$HOME/.cache}/development-manager/dm-server}"
bin="$cache/dm-server-$pin"
if [ ! -x "$bin" ]; then
command -v go >/dev/null 2>&1 || die "缺少 go,无法构建 dm-server($pin)"
mkdir -p "$cache"
cache=$(cd "$cache" && pwd -P)
bin="$cache/dm-server-$pin"
work=$(mktemp -d "$cache/build-$pin.XXXXXX")
if ! (dm_clean_env; cd "$dm" && GOWORK=off go build -trimpath -o "$work/dm-server" ./cmd/dm-server); then
rm -rf "$work"
die "构建 dm-server 失败($pin)"
fi
mv -f "$work/dm-server" "$bin"
rm -rf "$work"
fi
exec "$bin" "$@"
-16
View File
@@ -1,16 +0,0 @@
#!/usr/bin/env bash
# 本地检查(pre-commit):集成分支直提拒绝 + 分支命名 + 本地完整性核对。权威准入在 PR(baseline.md:26)。
branch=$(git rev-parse --abbrev-ref HEAD)
case "$branch" in
main|master)
echo "pre-commit: 拒绝——集成分支 ${branch} 不得直接提交,走 feature 分支 + PR(collaboration.md)" >&2
exit 1 ;;
esac
echo "$branch" | grep -qE '^(feature|fix|hotfix|release)/[A-Za-z0-9._-]+$' || {
echo "pre-commit: 拒绝——分支名须为 feature|fix|hotfix|release/<slug>,当前:${branch}" >&2
exit 1
}
root=$(git rev-parse --show-toplevel)
# admit 只是本地完整性/篡改证据(SELF):同一 OS 用户可读取本地 HMAC 密钥并绕过本钩子,
# 它不是 GATE,也不是可信身份。缺失或无效的本地记录仍拒绝;交付信任来自精确 HEAD 的 CI 或独立 REPLAY。
"$root/scripts/agent-exec" admit --repo "$root"
-4
View File
@@ -1,4 +0,0 @@
#!/usr/bin/env bash
# 通用任务入口:转调 scripts/dm 的 task 子命令(triage / start / pr-check)。
set -euo pipefail
exec "$(dirname "$0")/dm" task "$@"
+15 -104
View File
@@ -2,18 +2,12 @@ package squad
import (
"context"
"encoding/json"
"os"
"path/filepath"
"sync"
"testing"
"time"
)
// jsonForTest 包装 json.Marshal 让测试里构型参数不拉锁。是仅为占用 import 走
// 公共路径,不污染生产代码。
func jsonForTest(v any) ([]byte, error) { return json.Marshal(v) }
// perStepRecordingBackend 按子工作区归因计数(steps 的 role→tasks/NN_role 布局)。
type perStepRecordingBackend struct {
mu sync.Mutex
@@ -65,9 +59,6 @@ func newAttemptTestEngine(t *testing.T, backend *perStepRecordingBackend, dir st
return eng
}
// flipToInterrupted 把该步骤手动置为 running,同时清除 trusted terminal
// record(模拟「崩溃于执行中」状态)。清除让该路径能够测试 F05 走的
// 「无 record」分支。
func flipToInterrupted(t *testing.T, workDir string, stepIdx int) {
t.Helper()
st, err := loadRunState(workDir)
@@ -84,16 +75,6 @@ func flipToInterrupted(t *testing.T, workDir string, stepIdx int) {
if err := st.save(); err != nil {
t.Fatal(err)
}
// 同时清除该步骤的 trusted terminal record(模拟未达记录写入点崩溃)。
terminals := loadStepTerminalsForWorkDir(workDir)
if terminals != nil {
stepID := st.Plan.Workflow.Steps[stepIdx].ID
if _, ok := terminals[stepID]; ok {
delete(terminals, stepID)
data, _ := jsonForTest(terminals)
_ = os.WriteFile(filepath.Join(workDir, "step_terminals.json"), data, 0o644)
}
}
}
// TestAttemptIDFormat:attempt id 稳定落盘且形如 runID/stepID/N(Q1 WP3)。
@@ -117,15 +98,8 @@ func TestAttemptIDFormat(t *testing.T) {
}
// TestKilledAtSuperstepBoundarySideEffectsOnce:杀进程于 superstep 边界后恢复,
// 已完成步骤不重新执行(执行次数=1)。
//
// F05/U3b:running 崩溃、文件齐全、却无 trusted terminal record(U3b 前被视为
// “副作用真发生”自动完成;U3b 后仅记录 step.Status=needs_reconciliation,
// 后台不再自动 rerun/完成。本测试验证该迁变后的语义不变量:
//
// - running 且无 record:需要 reconciliation,不隐默 rerun;
// - file presence 不替 trusted record 完成步骤。
// - 若事先写入 trusted record(手工合成),即便文件缺失也恢复为 completed。
// 已完成步骤不重新执行(执行次数=1);running 且产物齐全的步骤按 attempt 判定
// 完成、不 rerun——Q1 验收第一条(WP3)。
func TestKilledAtSuperstepBoundarySideEffectsOnce(t *testing.T) {
backend := &perStepRecordingBackend{}
dir := t.TempDir()
@@ -151,78 +125,22 @@ func TestKilledAtSuperstepBoundarySideEffectsOnce(t *testing.T) {
if err != nil {
t.Fatal(err)
}
// F05:需 reconciliation(auto 模式),不等于 completed。
if res.Status != RunWaitingReconciliation {
t.Fatalf("want waiting_reconciliation (auto mode), got %s", res.Status)
if res.Status != RunCompleted {
t.Fatalf("resume: %+v", res)
}
if res.Plan == nil || len(res.Plan.Steps) == 0 {
t.Fatal("missing plan")
}
var recon int
for _, s := range res.Plan.Steps {
if s.ID == "s2" && s.Status == StepStatusNeedsReconciliation {
recon++
if s.Status != "completed" && s.Status != "skipped" {
t.Fatalf("step %s not finished: %s", s.ID, s.Status)
}
}
if recon != 1 {
t.Fatalf("step s2 not in needs_reconciliation (got plan=%+v)", res.Plan.Steps)
}
// 重要:重复执行的次数不应发生隐默 rerun(本测试用 auto 模式运行走到 reconciliation)。
for _, s := range res.Plan.Steps {
got := backend.countOf(filepath.Base(filepath.FromSlash(s.SubWorkspace)))
if got != before[s.ID] {
t.Fatalf("step %s executed %d times after kill (before=%d)——running 步骤被隐默 rerun", s.ID, got, before[s.ID])
t.Fatalf("step %s executed %d times after kill (before=%d)——已完成/running 步骤被重复执行", s.ID, got, before[s.ID])
}
}
}
// TestTrustedRecordCompletesMissingFiles:trusted terminal record 存在 + 文件缺失
// → 恢复为 completed(files 仍作诊断,state 是权威)。
func TestTrustedRecordCompletesMissingFiles(t *testing.T) {
backend := &perStepRecordingBackend{}
dir := t.TempDir()
eng := newAttemptTestEngine(t, backend, dir)
res, err := eng.Run(context.Background(), Goal{Text: "trusted record 完成", HitlMode: HitlAuto}, RunOptions{})
if err != nil || res.Status != RunCompleted {
t.Fatalf("setup run: %v %+v", err, res)
}
// 制造「第二步走 running 但 trusted record 已存在」的场景:先写入 record,再
// flip 到 running + 删 file。
st, err := loadRunState(res.WorkDir)
if err != nil {
t.Fatal(err)
}
sub2 := filepath.FromSlash(st.Plan.Workflow.Steps[1].SubWorkspace)
flipToInterrupted(t, res.WorkDir, 1)
if err := os.Remove(filepath.Join(res.WorkDir, sub2, "output.md")); err != nil {
t.Fatal(err)
}
// 手工写入 trusted record(这能覆盖「后端状态已落盘但文件被外部删」该返回
// 已完成的合法语义)。
terminals := map[string]stepTerminalRecord{
"s2": {StepID: "s2", AttemptID: st.Plan.Workflow.Steps[1].AttemptID, Terminal: "completed", SideEffects: string(ExecSideEffectsNone), At: time.Now()},
}
data, _ := jsonForTest(terminals)
if err := os.WriteFile(filepath.Join(res.WorkDir, "step_terminals.json"), data, 0o644); err != nil {
t.Fatal(err)
}
before := backend.countOf(filepath.Base(sub2))
eng2 := newAttemptTestEngine(t, backend, dir)
res, err = eng2.Resume(context.Background(), res.RunID)
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("want completed via trusted record, got %s", res.Status)
}
if got := backend.countOf(filepath.Base(sub2)); got != before {
t.Fatalf("trusted-record step reran (before=%d after=%d)——record 需被信任为 completed", before, got)
}
}
// TestInterruptedMissingProductsEntersReconciliation:F05/U3b:running 崩溃 + 无
// trusted record + 文件缺失 → auto 模式不再隐默 rerun,进入 waiting_reconciliation。
func TestInterruptedMissingProductsEntersReconciliation(t *testing.T) {
// TestInterruptedMissingProductsRetries:running 崩溃且产物缺失时按 auto 一次重试(WP3)。
func TestInterruptedMissingProductsRetries(t *testing.T) {
backend := &perStepRecordingBackend{}
dir := t.TempDir()
eng := newAttemptTestEngine(t, backend, dir)
@@ -230,6 +148,7 @@ func TestInterruptedMissingProductsEntersReconciliation(t *testing.T) {
if err != nil || res.Status != RunCompleted {
t.Fatalf("setup run: %v %+v", err, res)
}
// 第二步停 running 并删掉其交付物(副作用未发生的形态)。
flipToInterrupted(t, res.WorkDir, 1)
st, err := loadRunState(res.WorkDir)
if err != nil {
@@ -239,24 +158,16 @@ func TestInterruptedMissingProductsEntersReconciliation(t *testing.T) {
if err := os.Remove(filepath.Join(res.WorkDir, sub, "output.md")); err != nil {
t.Fatal(err)
}
before := backend.countOf(filepath.Base(sub))
eng2 := newAttemptTestEngine(t, backend, dir)
res, err = eng2.Resume(context.Background(), res.RunID)
if err != nil {
t.Fatal(err)
}
if res.Status != RunWaitingReconciliation {
t.Fatalf("want waiting_reconciliation, got %s", res.Status)
if res.Status != RunCompleted {
t.Fatalf("resume: %+v", res)
}
// 后续 Resume 仍旧是 reconciliation,不再 rerun。
res2, err := eng2.Resume(context.Background(), res.RunID)
if err != nil {
t.Fatal(err)
}
if res2.Status != RunWaitingReconciliation {
t.Fatalf("second resume shouldn't rerun, got %s", res2.Status)
}
if got := backend.countOf(filepath.Base(sub)); got != before {
t.Fatalf("missing-files step reran (before=%d after=%d)——record 缺失不应 rerun", before, got)
got := backend.countOf(filepath.Base(sub))
if got != 2 {
t.Fatalf("missing-product step executed %d times, want 2(auto 一次重试)", got)
}
}
+9 -156
View File
@@ -1,9 +1,7 @@
package squad
import (
"context"
"fmt"
"strings"
"sync"
"error-code-system/errcode"
@@ -18,20 +16,11 @@ type BackendFactory func(role RoleSpec) (Executor, error)
// agent-native 自研内核,产品也可注册 "pi-agent" 等外部智能体工厂。
// 未知名字 fail-closed,绝不静默落 stub。角色声明 MaxConcurrentTasks 时
// 以并发限流包装实现对象级串行(每个角色一份缓存实例,限流跨步骤共享)。
//
// 缓存键含 ConfigIdentity 与工厂世代,故 BashPermission/工具配置收紧或工厂
// 替换在下一次 Resolve 即生效。并发 gate 按「后端名+角色」独立于执行器版本
// 持有:配置换代不会另起限流器而绕过角色上限。
//
// 边界:已在飞的任务不会被回滚或取消;收紧权限/降低并发只影响后续 Resolve
// 与后续 Acquire。需要即时撤权的宿主应在每次工具调用前再校验。
type BackendResolver struct {
mu sync.RWMutex
factories map[string]BackendFactory
underlying map[string]Executor // 无工厂直挂的后端实例
wrapped map[string]Executor // 执行器配置身份 → 已包装实例缓存
factoryGen map[string]uint64 // Register/RegisterInstance 世代,替换即递增
gates map[string]*roleConcurrencyGate
wrapped map[string]Executor // 角色(含模型绑定)→ 已包装实例缓存
}
// NewBackendResolver 创建解析器并注册内置后端。
@@ -40,40 +29,23 @@ func NewBackendResolver() *BackendResolver {
factories: make(map[string]BackendFactory),
underlying: make(map[string]Executor),
wrapped: make(map[string]Executor),
factoryGen: make(map[string]uint64),
gates: make(map[string]*roleConcurrencyGate),
}
r.RegisterInstance("stub", &StubExecutor{})
return r
}
// Register 注册后端工厂(名字如 "agent-native"、"pi-agent")。
// 替换同名工厂会使该后端下已缓存的包装执行器失效。
func (r *BackendResolver) Register(name string, f BackendFactory) {
r.mu.Lock()
defer r.mu.Unlock()
r.factories[name] = f
r.invalidateLocked(name)
}
// RegisterInstance 直接注册后端实例(忽略角色级绑定)。
// 替换同名实例会使该后端下已缓存的包装执行器失效;"stub" 语义保持不变。
func (r *BackendResolver) RegisterInstance(name string, b Executor) {
r.mu.Lock()
defer r.mu.Unlock()
r.underlying[name] = b
r.invalidateLocked(name)
}
func (r *BackendResolver) invalidateLocked(name string) {
r.factoryGen[name]++
prefix := name + "\x00"
for k := range r.wrapped {
if strings.HasPrefix(k, prefix) {
delete(r.wrapped, k)
}
}
// gates 按角色身份保留:换工厂/配置不得丢掉进行中的并发计数。
}
// ListBackends 返回可用后端名(排序稳定)。
@@ -101,8 +73,8 @@ func (r *BackendResolver) ListBackends() []string {
}
// Resolve 解析角色的执行后端:Role.Backend → Options.DefaultBackend → "stub"。
// MaxConcurrentTasks >= 1 时以共享角色 gate 包装(跨执行器版本共用;
// 创建段持写锁防并行首解析竞态——否则并发步骤会各拿一份执行器)。
// MaxConcurrentTasks > 1 时以 agent-native 并发限流包装(per-role 缓存,跨步骤共享;
// 创建段持写锁防并行首解析竞态——否则并发步骤会各拿一份限流器)。
func (r *BackendResolver) Resolve(role RoleSpec, defaultBackend string) (Executor, string, error) {
name := role.Backend
if name == "" {
@@ -111,44 +83,30 @@ func (r *BackendResolver) Resolve(role RoleSpec, defaultBackend string) (Executo
if name == "" {
name = "stub"
}
cacheKey := name + "\x00" + role.Role + "\x00" + role.Model
// 后端名快照在锁外获取(Resolve 持锁期间再调 ListBackends 会自死锁)。
names := r.ListBackends()
r.mu.RLock()
gen := r.factoryGen[name]
cacheKey := resolveCacheKey(name, role, gen)
cached, ok := r.wrapped[cacheKey]
factory, hasFactory := r.factories[name]
under, hasUnder := r.underlying[name]
r.mu.RUnlock()
if ok {
if max := role.MaxConcurrentTasks; max >= 1 {
r.mu.Lock()
if g := r.gates[limiterKey(name, role.Role)]; g != nil {
g.setMax(max)
}
r.mu.Unlock()
}
return cached, name, nil
}
r.mu.Lock()
defer r.mu.Unlock()
gen = r.factoryGen[name]
cacheKey = resolveCacheKey(name, role, gen)
// 双检:等写锁期间可能已被并发解析填充。
if b, ok := r.wrapped[cacheKey]; ok {
if max := role.MaxConcurrentTasks; max >= 1 {
if g := r.gates[limiterKey(name, role.Role)]; g != nil {
g.setMax(max)
}
}
return b, name, nil
}
var b Executor
if under, hasUnder := r.underlying[name]; hasUnder {
if hasUnder {
b = under
} else if factory, hasFactory := r.factories[name]; hasFactory {
} else if hasFactory {
var err error
b, err = factory(role)
if err != nil {
@@ -159,114 +117,9 @@ func (r *BackendResolver) Resolve(role RoleSpec, defaultBackend string) (Executo
}
// MaxConcurrentTasks>=1 即包装限流(1 = 对象级串行;0 = 不限)。
// gate 按角色身份共享,与 ConfigIdentity / 工厂世代无关。
if max := role.MaxConcurrentTasks; max >= 1 {
g := r.gateLocked(name, role.Role, max)
b = &gatedExecutor{inner: b, gate: g}
b = WrapWithConcurrencyLimit(b, max)
}
r.wrapped[cacheKey] = b
return b, name, nil
}
func resolveCacheKey(name string, role RoleSpec, gen uint64) string {
return name + "\x00" + role.Role + "\x00" + ConfigIdentity(role) + "\x00" +
fmt.Sprintf("%d", gen) + "\x00" + limiterStamp(role.MaxConcurrentTasks)
}
func limiterKey(backend, role string) string {
return backend + "\x00" + role
}
func (r *BackendResolver) gateLocked(backend, role string, max int) *roleConcurrencyGate {
key := limiterKey(backend, role)
g, ok := r.gates[key]
if !ok {
g = newRoleConcurrencyGate(max)
r.gates[key] = g
return g
}
g.setMax(max)
return g
}
// roleConcurrencyGate 是按角色共享的并发上限。
// 执行器配置换代仍复用同一 gate,故旧版本在飞任务计入同一上限。
type roleConcurrencyGate struct {
mu sync.Mutex
max int
active int
notify chan struct{} // 关闭并替换以唤醒等待者
}
func newRoleConcurrencyGate(max int) *roleConcurrencyGate {
if max <= 0 {
max = 1
}
return &roleConcurrencyGate{max: max, notify: make(chan struct{})}
}
func (g *roleConcurrencyGate) setMax(max int) {
if max <= 0 {
max = 1
}
g.mu.Lock()
defer g.mu.Unlock()
g.max = max
g.signalLocked()
}
func (g *roleConcurrencyGate) signalLocked() {
close(g.notify)
g.notify = make(chan struct{})
}
func (g *roleConcurrencyGate) acquire(ctx context.Context) error {
for {
g.mu.Lock()
if g.active < g.max {
g.active++
g.mu.Unlock()
return nil
}
notify := g.notify
g.mu.Unlock()
select {
case <-ctx.Done():
return ctx.Err()
case <-notify:
}
}
}
func (g *roleConcurrencyGate) release() {
g.mu.Lock()
defer g.mu.Unlock()
if g.active > 0 {
g.active--
}
g.signalLocked()
}
// gatedExecutor 把共享角色 gate 套在具体执行器上。
type gatedExecutor struct {
inner Executor
gate *roleConcurrencyGate
}
func (e *gatedExecutor) Name() string {
if e.inner == nil {
return "gated"
}
return e.inner.Name()
}
func (e *gatedExecutor) Execute(ctx context.Context, req ExecRequest) (*ExecResult, error) {
if err := e.gate.acquire(ctx); err != nil {
return &ExecResult{
Success: false,
ErrorReason: fmt.Sprintf("agent concurrency wait canceled: %v", err),
}, err
}
defer e.gate.release()
return e.inner.Execute(ctx, req)
}
-405
View File
@@ -1,405 +0,0 @@
package squad
import (
"context"
"sync"
"sync/atomic"
"testing"
"time"
)
type labeledExec struct {
label string
perm string
tools string
delay time.Duration
enter func()
leave func()
}
func (e *labeledExec) Name() string { return e.label }
func (e *labeledExec) Execute(ctx context.Context, req ExecRequest) (*ExecResult, error) {
if e.enter != nil {
e.enter()
}
if e.leave != nil {
defer e.leave()
}
if e.delay > 0 {
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(e.delay):
}
}
return &ExecResult{Success: true, Logs: e.label + "|" + e.perm + "|" + e.tools}, nil
}
func TestConfigIdentityChangesWithBashAndTools(t *testing.T) {
a := RoleSpec{Role: "r", Model: "m", BashPermission: BashPermissionAllow}
d := RoleSpec{Role: "r", Model: "m", BashPermission: BashPermissionDeny}
if ConfigIdentity(a) == ConfigIdentity(d) {
t.Fatal("allow and deny must differ")
}
t1 := RoleSpec{Role: "r", Model: "m", Tools: []string{"a", "b"}}
t2 := RoleSpec{Role: "r", Model: "m", Tools: []string{"b", "a"}}
if ConfigIdentity(t1) != ConfigIdentity(t2) {
t.Fatal("tool order must not change identity")
}
t3 := RoleSpec{Role: "r", Model: "m", Tools: []string{"a", "c"}}
if ConfigIdentity(t1) == ConfigIdentity(t3) {
t.Fatal("tool set change must change identity")
}
same := RoleSpec{Role: "r", Model: "m", BashPermission: BashPermissionAllow, MaxConcurrentTasks: 1}
bump := RoleSpec{Role: "r", Model: "m", BashPermission: BashPermissionAllow, MaxConcurrentTasks: 8}
if ConfigIdentity(same) != ConfigIdentity(bump) {
t.Fatal("MaxConcurrentTasks must not affect ConfigIdentity")
}
}
func TestResolveAllowDenyTighteningAndLoosening(t *testing.T) {
var builds atomic.Int32
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
builds.Add(1)
return &labeledExec{label: "cap", perm: role.BashPermission}, nil
})
allow := RoleSpec{Role: "writer", Backend: "cap", Model: "m1", BashPermission: BashPermissionAllow}
e1, _, err := r.Resolve(allow, "")
if err != nil {
t.Fatal(err)
}
res, _ := e1.Execute(context.Background(), ExecRequest{})
if res.Logs != "cap|allow|" {
t.Fatalf("want allow executor, got %q", res.Logs)
}
deny := RoleSpec{Role: "writer", Backend: "cap", Model: "m1", BashPermission: BashPermissionDeny}
e2, _, err := r.Resolve(deny, "")
if err != nil {
t.Fatal(err)
}
res, _ = e2.Execute(context.Background(), ExecRequest{})
if res.Logs != "cap|deny|" {
t.Fatalf("allow→deny must take effect on next Resolve, got %q", res.Logs)
}
if e1 == e2 {
t.Fatal("tightened config must not reuse cached allow executor")
}
e3, _, err := r.Resolve(allow, "")
if err != nil {
t.Fatal(err)
}
res, _ = e3.Execute(context.Background(), ExecRequest{})
if res.Logs != "cap|allow|" {
t.Fatalf("deny→allow must take effect, got %q", res.Logs)
}
if builds.Load() < 2 {
t.Fatalf("factory must rebuild on permission change, builds=%d", builds.Load())
}
}
func TestResolveFactoryReplacementTakesEffect(t *testing.T) {
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
return &labeledExec{label: "v1", perm: role.BashPermission}, nil
})
role := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionAllow}
e1, _, err := r.Resolve(role, "")
if err != nil {
t.Fatal(err)
}
res, _ := e1.Execute(context.Background(), ExecRequest{})
if res.Logs != "v1|allow|" {
t.Fatalf("got %q", res.Logs)
}
r.Register("cap", func(role RoleSpec) (Executor, error) {
return &labeledExec{label: "v2", perm: role.BashPermission}, nil
})
e2, _, err := r.Resolve(role, "")
if err != nil {
t.Fatal(err)
}
res, _ = e2.Execute(context.Background(), ExecRequest{})
if res.Logs != "v2|allow|" {
t.Fatalf("factory replacement must take effect, got %q", res.Logs)
}
}
func TestResolveToolConfigChangeTakesEffect(t *testing.T) {
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
tools := ""
if len(role.Tools) > 0 {
tools = role.Tools[0]
}
return &labeledExec{label: "cap", tools: tools}, nil
})
base := RoleSpec{Role: "writer", Backend: "cap", Model: "m", Tools: []string{"read"}}
e1, _, err := r.Resolve(base, "")
if err != nil {
t.Fatal(err)
}
res, _ := e1.Execute(context.Background(), ExecRequest{})
if res.Logs != "cap||read" {
t.Fatalf("got %q", res.Logs)
}
next := RoleSpec{Role: "writer", Backend: "cap", Model: "m", Tools: []string{"write"}}
e2, _, err := r.Resolve(next, "")
if err != nil {
t.Fatal(err)
}
res, _ = e2.Execute(context.Background(), ExecRequest{})
if res.Logs != "cap||write" {
t.Fatalf("tool-config change must take effect, got %q", res.Logs)
}
}
func TestResolveUnchangedConfigReusesCache(t *testing.T) {
var builds atomic.Int32
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
builds.Add(1)
return &labeledExec{label: "cap", perm: role.BashPermission}, nil
})
role := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionAsk}
e1, _, err := r.Resolve(role, "")
if err != nil {
t.Fatal(err)
}
e2, _, err := r.Resolve(role, "")
if err != nil {
t.Fatal(err)
}
if e1 != e2 {
t.Fatal("unchanged config must reuse cached executor")
}
if builds.Load() != 1 {
t.Fatalf("want 1 factory call, got %d", builds.Load())
}
}
func TestResolveParallelFirstDoesNotDuplicate(t *testing.T) {
var builds atomic.Int32
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
builds.Add(1)
time.Sleep(20 * time.Millisecond) // widen race window
return &labeledExec{label: "cap"}, nil
})
role := RoleSpec{Role: "writer", Backend: "cap", Model: "m", MaxConcurrentTasks: 2}
const n = 32
var wg sync.WaitGroup
got := make([]Executor, n)
errs := make([]error, n)
wg.Add(n)
for i := 0; i < n; i++ {
i := i
go func() {
defer wg.Done()
got[i], _, errs[i] = r.Resolve(role, "")
}()
}
wg.Wait()
for i, err := range errs {
if err != nil {
t.Fatalf("resolve %d: %v", i, err)
}
}
for i := 1; i < n; i++ {
if got[i] != got[0] {
t.Fatalf("parallel first Resolve must share one executor")
}
}
if builds.Load() != 1 {
t.Fatalf("want single factory construction, got %d", builds.Load())
}
}
func TestSharedGateAcrossVersionsAndLimiterChange(t *testing.T) {
var (
mu sync.Mutex
current int
peak int
)
hold := make(chan struct{})
entered := make(chan struct{}, 8)
trackEnter := func() {
mu.Lock()
current++
if current > peak {
peak = current
}
mu.Unlock()
entered <- struct{}{}
<-hold
}
trackLeave := func() {
mu.Lock()
current--
mu.Unlock()
}
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
return &labeledExec{
label: "cap",
perm: role.BashPermission,
enter: trackEnter,
leave: trackLeave,
}, nil
})
allow := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionAllow, MaxConcurrentTasks: 1}
eOld, _, err := r.Resolve(allow, "")
if err != nil {
t.Fatal(err)
}
errCh := make(chan error, 4)
go func() { _, err := eOld.Execute(context.Background(), ExecRequest{}); errCh <- err }()
<-entered // old holds the sole slot
deny := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionDeny, MaxConcurrentTasks: 1}
eNew, _, err := r.Resolve(deny, "")
if err != nil {
t.Fatal(err)
}
if eOld == eNew {
t.Fatal("version bump must produce a new executor")
}
secondDone := make(chan struct{})
go func() {
_, err := eNew.Execute(context.Background(), ExecRequest{})
errCh <- err
close(secondDone)
}()
select {
case <-secondDone:
t.Fatal("new-version execute must wait on shared role cap while old is in-flight")
case <-time.After(40 * time.Millisecond):
}
// Raising MaxConcurrentTasks must update the shared gate (not spawn a bypassing limiter).
deny2 := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionDeny, MaxConcurrentTasks: 2}
eLim, _, err := r.Resolve(deny2, "")
if err != nil {
t.Fatal(err)
}
go func() { _, err := eLim.Execute(context.Background(), ExecRequest{}); errCh <- err }()
// After setMax(2): waiting eNew can enter (active=2). eLim must still wait.
select {
case <-entered: // eNew
case <-time.After(time.Second):
t.Fatal("limiter raise must admit the waiting new-version task")
}
select {
case <-entered:
t.Fatal("third task must not bypass shared cap after limiter change")
case <-time.After(40 * time.Millisecond):
}
close(hold)
for i := 0; i < 3; i++ {
if err := <-errCh; err != nil {
t.Fatal(err)
}
}
mu.Lock()
p := peak
mu.Unlock()
if p > 2 {
t.Fatalf("shared gate must cap total in-flight across versions; peak=%d", p)
}
}
func TestInFlightOldVersionCannotExceedCap(t *testing.T) {
var (
mu sync.Mutex
current int
peak int
)
enter := func() {
mu.Lock()
current++
if current > peak {
peak = current
}
mu.Unlock()
}
leave := func() {
mu.Lock()
current--
mu.Unlock()
}
r := NewBackendResolver()
r.Register("cap", func(role RoleSpec) (Executor, error) {
return &labeledExec{
label: "cap",
perm: role.BashPermission,
delay: 80 * time.Millisecond,
enter: enter,
leave: leave,
}, nil
})
v1 := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionAllow, MaxConcurrentTasks: 2}
e1, _, err := r.Resolve(v1, "")
if err != nil {
t.Fatal(err)
}
v2 := RoleSpec{Role: "writer", Backend: "cap", Model: "m", BashPermission: BashPermissionDeny, MaxConcurrentTasks: 2}
e2, _, err := r.Resolve(v2, "")
if err != nil {
t.Fatal(err)
}
var wg sync.WaitGroup
// 2 from old version + 2 from new version; shared cap=2 ⇒ peak must stay ≤2.
for _, e := range []Executor{e1, e1, e2, e2} {
wg.Add(1)
e := e
go func() {
defer wg.Done()
_, _ = e.Execute(context.Background(), ExecRequest{})
}()
}
wg.Wait()
mu.Lock()
p := peak
mu.Unlock()
if p > 2 {
t.Fatalf("in-flight old+new must not exceed role cap; peak=%d", p)
}
}
func TestRegisterInstanceStubSemantics(t *testing.T) {
r := NewBackendResolver()
e, name, err := r.Resolve(RoleSpec{Role: "x"}, "")
if err != nil {
t.Fatal(err)
}
if name != "stub" {
t.Fatalf("want stub, got %s", name)
}
if e.Name() != "stub" {
t.Fatalf("want stub executor, got %s", e.Name())
}
custom := &labeledExec{label: "stub-custom"}
r.RegisterInstance("stub", custom)
e2, _, err := r.Resolve(RoleSpec{Role: "x"}, "")
if err != nil {
t.Fatal(err)
}
if e2.Name() != "stub-custom" {
t.Fatalf("RegisterInstance stub replace must take effect, got %s", e2.Name())
}
}
-41
View File
@@ -1,41 +0,0 @@
package squad
import (
"context"
"strings"
"testing"
)
// brief_test.go — Q3 WP1a:StepSpec.Brief 渲染进 TASK.md「任务指令」节。
func TestStepBriefRendersIntoTaskFile(t *testing.T) {
rec := &promptRecordingBackend{prompts: map[string][]string{}}
engine := newRecordingEngine(t, rec, []StepSpec{
{ID: "s1", Role: "researcher", Title: "起草", Targets: []string{"output.md"},
Brief: "写一份关于「太空电梯」的简报,篇幅:短。\n必须包含单独一行「核对标记:P4」。"},
})
res, err := engine.Run(context.Background(), Goal{Text: "带任务指令"}, RunOptions{})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
var prompt string
for _, p := range rec.prompts["01_researcher"] {
prompt += p
}
if !strings.Contains(prompt, "## 任务指令") {
t.Fatalf("TASK.md 缺任务指令节:%q", prompt)
}
if !strings.Contains(prompt, "核对标记:P4") {
t.Fatalf("任务指令正文缺失:%q", prompt)
}
// 指令节在期望产出之后、上下文表之前。
iOut := strings.Index(prompt, "期望产出")
iBrief := strings.Index(prompt, "## 任务指令")
iCtx := strings.Index(prompt, "## 任务上下文资源")
if !(iOut < iBrief && iBrief < iCtx) {
t.Fatalf("任务指令节位置错误:%d/%d/%d", iOut, iBrief, iCtx)
}
}
-45
View File
@@ -1,45 +0,0 @@
package squad
import (
"crypto/sha256"
"encoding/hex"
"sort"
"strings"
)
// ConfigIdentity 返回角色中「塑造 Executor 装配」字段的稳定摘要。
// 含 BashPermission / Model / ToolProfile / Tools / Skills;不含
// MaxConcurrentTasks(并发上限由解析器按角色身份单独持有,与执行器版本解耦)。
func ConfigIdentity(role RoleSpec) string {
var b strings.Builder
b.WriteString("bash=")
b.WriteString(role.BashPermission)
b.WriteString("\x00model=")
b.WriteString(role.Model)
b.WriteString("\x00profile=")
b.WriteString(role.ToolProfile)
b.WriteString("\x00tools=")
b.WriteString(stableJoin(role.Tools))
b.WriteString("\x00skills=")
b.WriteString(stableJoin(role.Skills))
sum := sha256.Sum256([]byte(b.String()))
return hex.EncodeToString(sum[:16])
}
func stableJoin(items []string) string {
if len(items) == 0 {
return ""
}
cp := append([]string(nil), items...)
sort.Strings(cp)
return strings.Join(cp, ",")
}
// limiterStamp 区分「启用限流」与「不限流」;具体上限数值不进执行器缓存键,
// 以免调大/调小 MaxConcurrentTasks 时换掉共享 gate。
func limiterStamp(max int) string {
if max >= 1 {
return "lim"
}
return "unlim"
}
+54 -256
View File
@@ -76,11 +76,6 @@ func (d engineDeps) storeOr() Store {
}
// loadRun 经端口加载运行状态,并让它携带同一端口(后续 save 自然走同一实现)。
// runDir 是运行的工作区目录(所有 run 级 JSON 的根)。
func (e *SquadEngine) runDir(runID string) string {
return filepath.Join(e.opts.DataDir, "runs", runID)
}
func (e *SquadEngine) loadRun(wsDir string) (*RunState, error) {
st, err := e.deps.storeOr().LoadRun(wsDir)
if err != nil {
@@ -105,28 +100,6 @@ type RunOptions struct {
MaxLeaderTurns int `json:"max_leader_turns,omitempty"`
// CheckpointMode superstep 边界快照档位(Q1 WP4):sync(默认)| async | on_exit。
CheckpointMode string `json:"checkpoint_mode,omitempty"`
// Topology 显式拓扑名(Q2;优先于 Blueprint.Topology;空 = standard 图)。
// 未注册名 / primitive 单跑 / driver 未点亮均 fail-closed。
Topology string `json:"topology,omitempty"`
// Deadline 运行级截止时刻(Q2 long_running):superstep 边界检查,
// 超期把未完步骤置 skipped 并降级收口。零值 = 不设限。
Deadline time.Time `json:"deadline,omitempty"`
// MaxReplans leader 模式的重规划上限(Q2;与 MaxLeaderTurns 独立)。
// 0 = 默认 DefaultMaxReplans。
MaxReplans int `json:"max_replans,omitempty"`
// GroupChatPolicy group_chat 拓扑发言人策略(Q2):rotate(默认)| moderator。
GroupChatPolicy string `json:"group_chat_policy,omitempty"`
// GroupChatModerator 主持人角色 key(moderator 策略必填,须在名册内)。
GroupChatModerator string `json:"group_chat_moderator,omitempty"`
// GroupChatMaxTurns 群聊轮次预算(0 = DefaultMaxGroupChatTurns)。
GroupChatMaxTurns int `json:"group_chat_max_turns,omitempty"`
// ReviewVerifyRole review 拓扑核实角色 key(默认 "verifier")。
ReviewVerifyRole string `json:"review_verify_role,omitempty"`
// ReviewTarget 被评审材料(默认取 context/goal.md)。
ReviewTarget string `json:"review_target,omitempty"`
// TaskBoardLeaseSeconds task_board 任务租约时限(秒;0 = 默认 600)。
// 孤儿租约(claimed 且过期)在驱动重入时再武装回 open。
TaskBoardLeaseSeconds int `json:"task_board_lease_seconds,omitempty"`
}
// SquadEngine 小队引擎门面:Run / Respond / Resume / Inspect / ListRuns。
@@ -261,39 +234,6 @@ func (e *SquadEngine) Run(ctx context.Context, goal Goal, runOpts RunOptions) (*
if runOpts.CheckpointMode != "" {
meta.Metadata["checkpoint_mode"] = runOpts.CheckpointMode
}
if runOpts.Topology != "" {
meta.Metadata["topology"] = runOpts.Topology
// leader 拓扑映射到委派循环须发生在计划确认之前(确认门按
// mode=leader 豁免);后置映射会让 leader 运行误触计划确认。
if runOpts.Topology == TopologyLeader && meta.Metadata["mode"] == "" {
meta.Metadata["mode"] = "leader"
}
}
if !runOpts.Deadline.IsZero() {
// RFC3339Nano:秒级 RFC3339 会截断亚秒精度,短截止会被立刻判超期。
meta.Metadata["deadline"] = runOpts.Deadline.UTC().Format(time.RFC3339Nano)
}
if runOpts.MaxReplans > 0 {
meta.Metadata["max_replans"] = fmt.Sprintf("%d", runOpts.MaxReplans)
}
if runOpts.GroupChatPolicy != "" {
meta.Metadata["group_chat_policy"] = runOpts.GroupChatPolicy
}
if runOpts.GroupChatModerator != "" {
meta.Metadata["group_chat_moderator"] = runOpts.GroupChatModerator
}
if runOpts.GroupChatMaxTurns > 0 {
meta.Metadata["group_chat_max_turns"] = fmt.Sprintf("%d", runOpts.GroupChatMaxTurns)
}
if runOpts.ReviewVerifyRole != "" {
meta.Metadata["review_verify_role"] = runOpts.ReviewVerifyRole
}
if runOpts.ReviewTarget != "" {
meta.Metadata["review_target"] = runOpts.ReviewTarget
}
if runOpts.TaskBoardLeaseSeconds > 0 {
meta.Metadata["task_board_lease_seconds"] = fmt.Sprintf("%d", runOpts.TaskBoardLeaseSeconds)
}
e.deps.Sink.Emit(Event{Type: EvRunStarted, RunID: runID, Text: goal.Text, At: time.Now()})
// 意图闸门(可选,入口一次裁决;显式 TaskKey 优先,不重复过闸)。
@@ -354,10 +294,6 @@ func (e *SquadEngine) planAndExecute(ctx context.Context, st *RunState, runOpts
planOut = &PlanOutput{Plan: plan}
} else {
bpMatch, _ := e.opts.Blueprints.Match(meta.Goal.Text, runOpts.TaskKey)
// 拓扑解析(Q2):RunOptions 优先,Blueprint 兜底。
if meta.Metadata["topology"] == "" && bpMatch.Topology != "" {
meta.Metadata["topology"] = bpMatch.Topology
}
planOut, err = e.opts.Planner.Plan(ctx, PlanInput{
Goal: meta.Goal, Blueprint: bpPtr(bpMatch), Registry: e.opts.Registry, RunID: meta.ID,
IntentCatalog: e.opts.IntentCatalog,
@@ -444,20 +380,6 @@ func (e *SquadEngine) planAndExecute(ctx context.Context, st *RunState, runOpts
if err := e.materializeWorkspace(meta, st, planOut.Plan); err != nil {
return nil, err
}
// 拓扑校验与分发(Q2):未注册名 / primitive 单跑 / driver 未点亮 fail-closed;
// leader 拓扑映射到既有 Mode 委派循环(不新造执行面)。
if topo := meta.Metadata["topology"]; topo != "" {
kind, terr := checkTopology(topo)
if terr != nil {
return e.failNew(meta, terr)
}
if kind == TopologyMode && topo == TopologyLeader {
if meta.Metadata["mode"] == "" {
meta.Metadata["mode"] = "leader"
}
}
e.deps.Sink.Emit(Event{Type: EvPhase, RunID: meta.ID, Text: "拓扑 " + topo, At: time.Now()})
}
// leader-delegation 模式:忽略规划步骤,进 leader 委派循环。
if meta.Metadata["mode"] == "leader" {
e.initLeaderState(st)
@@ -470,15 +392,6 @@ func (e *SquadEngine) planAndExecute(ctx context.Context, st *RunState, runOpts
}
return out, nil
}
// driver 类拓扑(Q2 WP3+):按名分发专用驱动(review/group_chat;
// task_board 属 WP4,未点亮前 checkTopology 已 fail-closed)。
if out, handled, derr := e.dispatchTopologyDriver(ctx, st); handled {
if derr != nil {
return nil, derr
}
e.finalizeEvent(out)
return out, nil
}
out, _, err := drv.advance(ctx, st)
if err != nil {
return nil, err
@@ -501,13 +414,7 @@ func (e *SquadEngine) initLeaderState(st *RunState) {
maxTurns = n
}
}
maxReplans := DefaultMaxReplans
if v := st.Meta.Metadata["max_replans"]; v != "" {
if n := parseIntDefault(v, DefaultMaxReplans); n > 0 {
maxReplans = n
}
}
st.Leader = &LeaderState{LeaderRole: leaderRole, MaxTurns: maxTurns, MaxReplans: maxReplans}
st.Leader = &LeaderState{LeaderRole: leaderRole, MaxTurns: maxTurns}
st.saveLeader()
}
@@ -539,15 +446,6 @@ func (e *SquadEngine) resumeAfterHold(ctx context.Context, st *RunState) (*RunRe
}
return out, nil
}
// driver 类拓扑续跑:驱动自身幂等(review 已完成 finder 不重跑;
// group_chat 按已落盘轮次续转)。
if out, handled, err := e.dispatchTopologyDriver(ctx, st); handled {
if err != nil {
return nil, err
}
e.finalizeEvent(out)
return out, nil
}
drv := &flowDriver{opts: e.deps}
out, _, err := drv.advance(ctx, st)
if err != nil {
@@ -557,32 +455,6 @@ func (e *SquadEngine) resumeAfterHold(ctx context.Context, st *RunState) (*RunRe
return out, nil
}
// dispatchTopologyDriver 按运行拓扑分发 driver 类拓扑。
// handled=false 表示非 driver 拓扑(走既有图/模式路径)。
func (e *SquadEngine) dispatchTopologyDriver(ctx context.Context, st *RunState) (*RunResult, bool, error) {
topo := st.Meta.Metadata["topology"]
if topo == "" {
return nil, false, nil
}
spec, ok := LookupTopology(topo)
if !ok || spec.Kind != TopologyDriver {
return nil, false, nil
}
switch topo {
case TopologyReview:
out, err := e.runReviewDriver(ctx, st)
return out, true, err
case TopologyGroupChat:
out, err := e.runGroupChatDriver(ctx, st)
return out, true, err
case TopologyTaskBoard:
out, err := e.runTaskBoardDriver(ctx, st)
return out, true, err
default:
return e.driverFail(st, fmt.Sprintf("topology: %q 驱动未实现(fail-closed)", topo)), true, nil
}
}
// materializeWorkspace 落盘工作区与子工作区(已存在则只更新计划并重建待执行子目录)。
func (e *SquadEngine) materializeWorkspace(meta *RunMetadata, st *RunState, plan *SquadPlan) error {
if st.Meta.WorkDir == "" {
@@ -665,17 +537,6 @@ func (e *SquadEngine) respondLocked(ctx context.Context, runID string, decision
}
req := &gate.Request
// 非 human actor 不得决议 choice 门(Q2 验收三的第二道防线:邮箱/代理
// 消息即便伪造 Respond 调用也清不掉 permission/confirmation/quality 门)。
if decision.Actor != "" && decision.Actor != ActorHuman && choiceHoldKind(req.Kind) &&
strings.TrimSpace(decision.Choice) != "" {
e.deps.Sink.Emit(Event{Type: EvPhase, RunID: runID,
Text: fmt.Sprintf("拒绝非人工 actor(%s) 决议 %s 门(请求 %s)", decision.Actor, req.Kind, req.ID), At: time.Now()})
return e.noteAndKeepHold(st, gate, RespondDecision{
RequestID: decision.RequestID,
Answer: fmt.Sprintf("[blocked] 非人工 actor(%s) 尝试决议本门,已拒绝;等待人工裁决。", decision.Actor),
})
}
if strings.TrimSpace(decision.Choice) == "" && strings.TrimSpace(decision.Answer) != "" && choiceHoldKind(req.Kind) {
return e.noteAndKeepHold(st, gate, decision)
}
@@ -1051,129 +912,73 @@ func markStep(st *RunState, id, status, errText string) bool {
}
// recoverInterrupted 处理崩溃时停在 running 的步骤。
// interactive 挂起确认/对账,不自动再执行;auto 允许一次重试;disabled 直接失败。
//
// F05/U3b:恢复是否判定 completed 不再单纯依据「文件齐全」——trusted terminal
// record 是单一权威:仅当 step_terminals.json 中存在该步骤且 Terminal=completed
// 时才能恢复完成(即便文件缺失也照恢复,文件用于诊断);其余情形按 record +
// 文件状态联合判定:
//
// - 有 trusted record(completed)+ 缺失文件 -> completed(files 诊断信息)
// - 有 trusted record + 现存文件 -> completed(一致)
// - 有 trusted record + SideEffects=none + 缺失文件 -> 一次重试 pending
// - 无 record + 文件齐全 -> needs_reconciliation(不自动 rerun,不假装完成)
// - 无 record + 文件缺失 -> needs_reconciliation
// - record 表明 Canceled/Aborted -> 走 cancel 路径
//
// retention 期间产物缺失若 record SideEffects=possible,禁止无条件 rerun ——
// 必须经人工 reconciliation 才能继续。
// interactive 挂起确认,不自动再执行;auto 允许一次重试;disabled 直接失败。
func (e *SquadEngine) recoverInterrupted(ctx context.Context, st *RunState) (*RunResult, error) {
terminals := loadStepTerminalsForWorkDir(st.Meta.WorkDir)
drv := &flowDriver{opts: e.deps}
for i := range st.Plan.Workflow.Steps {
step := st.Plan.Workflow.Steps[i]
if step.Status != "running" {
continue
}
subDir := filepath.Join(st.Meta.WorkDir, filepath.FromSlash(orDefault(step.SubWorkspace, fmt.Sprintf("tasks/%02d_%s", i+1, step.Role))))
targets := step.Targets
if len(targets) == 0 {
targets = []string{"output.md"}
}
missing := missingTargets(subDir, targets)
record, hasRecord := terminals[step.ID]
// 1. trusted terminal record 存在 -> 单一权威。
if hasRecord && record.Terminal == "completed" && !record.Canceled && !record.Aborted {
step.Status = "completed"
step.Error = ""
st.Plan.Workflow.Steps[i] = step
st.mu.Lock()
_ = mergeStepArtifacts(&st.BB, subDir)
err := st.save()
st.mu.Unlock()
if err != nil {
return nil, err
}
drv.emit(st, Event{Type: EvStepCompleted, StepID: step.ID, Role: step.Role,
Text: fmt.Sprintf("中断恢复:trusted terminal record(attempt=%s, side_effects=%s)判定完成",
record.AttemptID, orDefault(record.SideEffects, "possible"))})
continue
}
// 1b. record 表明已取消/中止 -> cancel 路径(不等同业务失败)。
if hasRecord && (record.Canceled || record.Aborted) {
step.Status = "failed"
if record.Canceled {
step.Error = "interrupted: canceled"
} else {
step.Error = "interrupted: aborted"
}
st.Plan.Workflow.Steps[i] = step
if err := st.save(); err != nil {
return nil, err
}
out, _, ferr := drv.failStep(ctx, st, i)
return out, ferr
}
// 1c. record 表明 SideEffects=none + 缺失文件 -> 仅一次重试 pending
// (旧 WP3 路径保留以兼容纯读取类步骤)。
if hasRecord && record.SideEffects == string(ExecSideEffectsNone) && len(missing) > 0 && step.Attempts < 2 {
step.Attempts++
step.Status = "pending"
step.Error = ""
// F05:复用上一次 attempt 的 ExecutionID(已在 step.Terminal 落 record)。
if record.AttemptID != "" {
step.AttemptID = record.AttemptID
}
st.Plan.Workflow.Steps[i] = step
if err := st.save(); err != nil {
return nil, err
}
continue
}
// 2. 无 trusted record —— 旧路径不准直接翻 completed,必须进入 reconciliation。
// 区分 HITL 模式:interactive 仍合成 HITL hold(同 hitlConfirmation 通道),
// auto / disabled 走显式 needs_reconciliation(不自动 rerun 不假装成功)。
reason := "no trusted terminal record"
if len(missing) == 0 {
reason = "no trusted terminal record despite deliverables present"
} else {
reason = "no trusted terminal record and deliverables missing"
}
step.Status = StepStatusNeedsReconciliation
step.Error = reason
st.Plan.Workflow.Steps[i] = step
if err := st.save(); err != nil {
return nil, err
}
switch st.policy().mode() {
case HitlInteractive:
case HitlDisabled:
st.Plan.Workflow.Steps[i].Status = "failed"
st.Plan.Workflow.Steps[i].Error = "interrupted"
if err := st.save(); err != nil {
return nil, err
}
drv := &flowDriver{opts: e.deps}
out, _, err := drv.failStep(ctx, st, i)
return out, err
case HitlAuto:
if step.Attempts >= 2 {
st.Plan.Workflow.Steps[i].Status = "failed"
st.Plan.Workflow.Steps[i].Error = "interrupted twice"
if err := st.save(); err != nil {
return nil, err
}
drv := &flowDriver{opts: e.deps}
out, _, err := drv.failStep(ctx, st, i)
return out, err
}
// Q1 WP3 产物校验:步骤在 running 崩溃,但其交付物已全部落盘——
// 副作用实际发生过,直接判定完成而不是重新执行(副作用次数=1)。
subDir := filepath.Join(st.Meta.WorkDir, filepath.FromSlash(orDefault(step.SubWorkspace, fmt.Sprintf("tasks/%02d_%s", i+1, step.Role))))
targets := step.Targets
if len(targets) == 0 {
targets = []string{"output.md"}
}
if missingTargets(subDir, targets) == nil {
step.Status = "completed"
step.Error = ""
st.Plan.Workflow.Steps[i] = step
st.mu.Lock()
_ = mergeStepArtifacts(&st.BB, subDir)
err := st.save()
st.mu.Unlock()
if err != nil {
return nil, err
}
drv := &flowDriver{opts: e.deps}
drv.emit(st, Event{Type: EvStepCompleted, StepID: step.ID, Role: step.Role,
Text: fmt.Sprintf("中断恢复:产物齐全,按 attempt %s 判定完成", step.AttemptID)})
continue
}
st.Plan.Workflow.Steps[i].Status = "pending"
if err := st.save(); err != nil {
return nil, err
}
return nil, nil
default:
drv := &flowDriver{opts: e.deps}
out, _, err := drv.hold(st, HitlConfirmation, step.ID, step.Role,
fmt.Sprintf("步骤「%s」在执行中中断,且没有可信任的完成记录。%s 如何继续?", step.Title, reason),
fmt.Sprintf("步骤「%s」在执行中中断。如何继续?", step.Title),
[]HumanOption{
{Value: "retry", Label: "明确重试(接收可能的副作用)"},
{Value: "retry", Label: "重试"},
{Value: "skip", Label: "跳过该步骤"},
{Value: "abort", Label: "中止运行"},
},
"interrupted", "interrupted", nil)
return out, err
default:
now := time.Now()
st.Meta.Status = string(RunWaitingReconciliation)
st.Meta.UpdatedAt = now
if err := st.save(); err != nil {
return nil, err
}
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("中断恢复:%s进入 reconciliation(reason=%s)", step.ID, reason)})
return &RunResult{
RunID: st.Meta.ID,
Status: RunWaitingReconciliation,
Plan: planPtr(st),
WorkDir: st.Meta.WorkDir,
Summary: "interrupted-running step requires reconciliation",
Error: reason,
}, nil
}
}
return nil, nil
@@ -1199,13 +1004,6 @@ func (e *SquadEngine) Resume(ctx context.Context, runID string) (*RunResult, err
if RunStatus(st.Meta.Status).Terminal() {
return e.Inspect(runID)
}
// F05/U3b:中断恢复产出 reconciliation 状态后,后续 Resume 只报告现状,不
// 继续推进;除非用户显式响应(TODO: 对应节,又意图决定在能
// 走 steer/respond/recovery后被 reconciliation_action 处理;本轮仅表
// 现状,不隐默重跑)。
if RunStatus(st.Meta.Status) == RunWaitingReconciliation {
return e.Inspect(runID)
}
// 图连续性校验(Q1 WP4/WP1 裁定):崩溃期间的检查点图指纹与当前 Steps
// 重编译不一致 = 图形态被改过(动态调整或外力),拒绝恢复并提示重新规划。
if err := validateGraphContinuity(st); err != nil {
-517
View File
@@ -1,517 +0,0 @@
// Package squad: F05/U3b executor result 合约测试。
//
// 覆盖以下消费规则:
// - (nil,nil) executor 返回 (result==nil && err==nil) 是稳定失败(非 panic,非 success)。
// - Success=true 但无执行证据(patches-only)也要走交付物校验;
// 失败-with-full-patches 仍为失败(不允许文件存在翻成 success)。
// - canceled/aborted 结果不进入 retry 通路(不是业务失败,不可重试)。
// - side_effects=possible 的失败禁止自动重试;
// side_effects=none 的纯读取失败可走有界重试。
// - recovery:trusted record 存在 + 文件缺失 -> 恢复 completed(权威来源 = record);
// 无 record + 文件齐全 -> needs_reconciliation(不假装完成、不隐默 rerun);
// 无 record + 文件缺失 -> needs_reconciliation;
// record SideEffects=none + 缺失文件 -> 一次重试 pending(不重复执行副作用)。
//
// 这些测试使用 squad 包的 in-memory executor 替身进行 hermetic 验证;不调用
// 真实模型或外部组件。
package squad
import (
"context"
"os"
"path/filepath"
"strings"
"sync"
"sync/atomic"
"testing"
"time"
)
// ---- 替身 executor ----
// frozenResultBackend 每次 Execute 返回同一个固定结果(用于直接构造语义场景)。
type frozenResultBackend struct {
mu sync.Mutex
calls int32
res *ExecResult
err error
}
func (b *frozenResultBackend) Name() string { return "frozen" }
func (b *frozenResultBackend) Execute(_ context.Context, _ ExecRequest) (*ExecResult, error) {
atomic.AddInt32(&b.calls, 1)
b.mu.Lock()
defer b.mu.Unlock()
if b.err != nil {
return b.res, b.err
}
return b.res, nil
}
func (b *frozenResultBackend) callCount() int32 {
return atomic.LoadInt32(&b.calls)
}
// materializingBackend 每次 Execute 写入 patches 但把 Success 留给 caller 决定。
// 用于「patches-only success」测试场景。
type materializingBackend struct {
mu sync.Mutex
calls int32
// success 只在 success==true 时返回 Success=true;测试 override 用。
success bool
canceled bool
aborted bool
// sideEffects 决定是否允许重试。
sideEffects ExecSideEffects
// writePatch 控制是否 materializes patch 到 workDir。
writePatch bool
}
func (b *materializingBackend) Name() string { return "materializing" }
func (b *materializingBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
atomic.AddInt32(&b.calls, 1)
patches := map[string][]byte{}
for _, t := range req.Targets {
if b.writePatch {
_ = os.WriteFile(filepath.Join(req.WorkDir, t), []byte(goodReport), 0o644)
}
patches[t] = []byte(goodReport)
}
return &ExecResult{
Success: b.success,
Patches: patches,
Logs: "stub",
SideEffects: b.sideEffects,
Canceled: b.canceled,
Aborted: b.aborted,
}, nil
}
func (b *materializingBackend) callCount() int32 {
return atomic.LoadInt32(&b.calls)
}
// ---- 测试辅助 ----
func newFrozenTestEngine(t *testing.T, dir string, backend Executor) *SquadEngine {
t.Helper()
reg := NewRoleRegistry()
if err := reg.Register(RoleSpec{Role: "researcher", Name: "调研", Backend: backend.Name()}); err != nil {
t.Fatal(err)
}
if err := reg.Register(RoleSpec{Role: "writer", Name: "撰写", Backend: backend.Name()}); err != nil {
t.Fatal(err)
}
if err := reg.Register(RoleSpec{Role: "reviewer", Name: "审核", Backend: backend.Name()}); err != nil {
t.Fatal(err)
}
backends := NewBackendResolver()
backends.RegisterInstance(backend.Name(), backend)
eng, err := NewEngine(Options{
DataDir: dir, Registry: reg, Planner: mockScriptPlanner(baseSteps()...),
Backends: backends, Sink: NopSink{},
})
if err != nil {
t.Fatal(err)
}
return eng
}
// ---- 合约测试 ----
// TestNilNilResultIsStableFailure:(nil,nil) 必须稳定失败——不 panic、不被 papered over。
func TestNilNilResultIsStableFailure(t *testing.T) {
dir := t.TempDir()
be := &frozenResultBackend{res: nil, err: nil}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "空结果"}, RunOptions{})
if err != nil {
t.Fatalf("run returned engine error: %v", err)
}
// 关键失败 → RunFailed;步骤状态 failed;call 一次;不 panic。
if res.Status != RunFailed {
t.Fatalf("want RunFailed, got %s (err=%s)", res.Status, res.Error)
}
if be.callCount() != 1 {
t.Fatalf("backend called %d times, want 1", be.callCount())
}
if res.Plan == nil {
t.Fatal("plan missing")
}
if got := res.Plan.Steps[0].Status; got != "failed" {
t.Fatalf("step 1 status = %s, want failed", got)
}
if got := res.Plan.Steps[0].Error; got != "executor returned nil result" {
t.Fatalf("step 1 error = %q, want executor-nil-result reason", got)
}
}
// TestSuccessWithFullPatchesMaterializes:Success=true + 已有 patch
// —— 通过交付物校验完成;patches-only success 也走同一路径。
func TestSuccessWithFullPatchesMaterializes(t *testing.T) {
dir := t.TempDir()
be := &materializingBackend{success: true, sideEffects: ExecSideEffectsNone, writePatch: true}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "patches 落地校验"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status != RunCompleted {
t.Fatalf("want completed, got %s err=%s", res.Status, res.Error)
}
// 三步各调用一次;patches 命中产物路径且 Success=true,每步一次。
if got := be.callCount(); got < 3 {
t.Fatalf("backend called %d times, want at least 3 (3 steps)", got)
}
}
// TestFailedWithFullPatchesStaysFailed:F05/KTD4 关键不变式:失败 + 文件齐全
// 也不能翻成成功——即便 patches 内容已落地。
func TestFailedWithFullPatchesStaysFailed(t *testing.T) {
dir := t.TempDir()
be := &materializingBackend{success: false, sideEffects: ExecSideEffectsPossible, writePatch: true}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "失败-but-files-present"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status != RunFailed {
t.Fatalf("want RunFailed, got %s", res.Status)
}
if res.Plan == nil || res.Plan.Steps[0].Status != "failed" {
t.Fatalf("step 1 should be failed, plan=%+v", res.Plan)
}
// 关键:失败被 failStep 重判后,不应回写 completed;也不应自动 rerun。
// SideEffects=possible 禁止重试:s1 仅调用一次,后续步骤不再调用(运行已中止)。
if got := be.callCount(); got > 1 {
t.Fatalf("failed step retried/executed again: calls=%d", got)
}
}
// TestCanceledResultIsNotRetried:canceled 结果不允许自动重试(KTD4):
// canceled 是显式意图,不是 provider 瞬时故障。
func TestCanceledResultIsNotRetried(t *testing.T) {
dir := t.TempDir()
be := &materializingBackend{success: false, canceled: true, sideEffects: ExecSideEffectsNone, writePatch: false}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "取消不可重试"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
// 失败(不是 panic),且仅被调用一次(不允许 retry)。
if res.Status != RunFailed {
t.Fatalf("want RunFailed, got %s", res.Status)
}
if be.callCount() != 1 {
t.Fatalf("canceled invoked %d times, want 1 (no retry)", be.callCount())
}
}
// TestAbortedResultIsNotRetried:aborted 同 canceled 语义。
func TestAbortedResultIsNotRetried(t *testing.T) {
dir := t.TempDir()
be := &materializingBackend{success: false, aborted: true, sideEffects: ExecSideEffectsNone, writePatch: false}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "中止不可重试"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status != RunFailed {
t.Fatalf("want RunFailed, got %s", res.Status)
}
if be.callCount() != 1 {
t.Fatalf("aborted invoked %d times, want 1 (no retry)", be.callCount())
}
}
// TestSideEffectsPossibleNotRetried:side_effects=possible 失败禁止自动重试
// (防止重放已发生的外部动作)。
func TestSideEffectsPossibleNotRetried(t *testing.T) {
dir := t.TempDir()
be := &materializingBackend{success: false, sideEffects: ExecSideEffectsPossible, writePatch: false}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "可能副作用失败不重试"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status != RunFailed {
t.Fatalf("want RunFailed, got %s", res.Status)
}
if be.callCount() != 1 {
t.Fatalf("possible-side-effects invoked %d times, want 1 (no retry)", be.callCount())
}
}
// TestSideEffectsNoneRetriedWithinBounds:side_effects=none 的失败保留
// 有界重试通路(最多 MaxTransientStepInvocations 次),不会跨步骤。
func TestSideEffectsNoneRetriedWithinBounds(t *testing.T) {
dir := t.TempDir()
// stage 1: failed with side_effects=none → 触发重试;
// stage 2: 返回 success。后续调用返回 last state(success)。
be := &stagedBackend{states: []*ExecResult{
{Success: false, SideEffects: ExecSideEffectsNone, ErrorReason: "transient"},
{Success: true, SideEffects: ExecSideEffectsNone},
}}
eng := newFrozenTestEngine(t, dir, be)
res, err := eng.Run(context.Background(), Goal{Text: "可重试"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status != RunCompleted {
t.Fatalf("want RunCompleted, got %s err=%s", res.Status, res.Error)
}
// 全运行计数:s1 经历重试(最多 2 次调用);后续步骤首次成功。
// 说明 重试仅限于 s1,不超出单步边界。
if be.callCount() < 2 {
t.Fatalf("retried count = %d, want at least 2 (failed then success on s1)", be.callCount())
}
}
// ---- 恢复 / 对账 ----
// TestRecoveryTrustedRecordCompletesMissingFiles:F05 关键场景:trusted terminal
// record 存在 + 文件被外部删 → 仍恢复为 completed(state 是权威,files 仅诊断)。
func TestRecoveryTrustedRecordCompletesMissingFiles(t *testing.T) {
backend := &perStepRecordingBackend{}
dir := t.TempDir()
eng := newAttemptTestEngine(t, backend, dir)
res, err := eng.Run(context.Background(), Goal{Text: "record-only-path"}, RunOptions{})
if err != nil || res.Status != RunCompleted {
t.Fatalf("setup run: %v %+v", err, res)
}
// 准备恢复场景:删除 s2 的 output.md,但保留 trusted record。
st, err := loadRunState(res.WorkDir)
if err != nil {
t.Fatal(err)
}
sub := filepath.FromSlash(st.Plan.Workflow.Steps[1].SubWorkspace)
if err := os.Remove(filepath.Join(res.WorkDir, sub, "output.md")); err != nil {
t.Fatal(err)
}
// 记录已写入(setup 步骤会触发 recordStepTerminal)。
terminals := loadStepTerminalsForWorkDir(res.WorkDir)
if _, ok := terminals[st.Plan.Workflow.Steps[1].ID]; !ok {
t.Fatalf("trusted record missing for %s", st.Plan.Workflow.Steps[1].ID)
}
// Flip s2 to running(带 record)。
st2, _ := loadRunState(res.WorkDir)
st2.Plan.Workflow.Steps[1].Status = "running"
st2.Plan.Workflow.Steps[1].Attempts = 2
st2.setWorkflow(st2.Plan.Workflow)
if err := st2.save(); err != nil {
t.Fatal(err)
}
eng2 := newAttemptTestEngine(t, backend, dir)
res2, err := eng2.Resume(context.Background(), res.RunID)
if err != nil {
t.Fatal(err)
}
if res2.Status != RunCompleted {
t.Fatalf("trusted record should restore completed, got %s", res2.Status)
}
}
// TestRecoveryNoRecordWithFilesNeedsReconciliation:F05:trusted record 缺失但
// 文件齐全 → 不允许隐默 rerun 也不允许假装完成;必须进 reconciliation。
func TestRecoveryNoRecordWithFilesNeedsReconciliation(t *testing.T) {
backend := &perStepRecordingBackend{}
dir := t.TempDir()
eng := newAttemptTestEngine(t, backend, dir)
res, err := eng.Run(context.Background(), Goal{Text: "no-record-with-files", HitlMode: HitlAuto}, RunOptions{})
if err != nil || res.Status != RunCompleted {
t.Fatalf("setup run: %v %+v", err, res)
}
flipToInterrupted(t, res.WorkDir, 1)
// flipToInterrupted 现在已经删除 record;显式再校验一次。
ws := res.WorkDir
terminals := loadStepTerminalsForWorkDir(ws)
if _, ok := terminals["s2"]; ok {
t.Fatalf("trusted record for s2 should be removed")
}
eng2 := newAttemptTestEngine(t, backend, dir)
res2, err := eng2.Resume(context.Background(), res.RunID)
if err != nil {
t.Fatal(err)
}
if res2.Status != RunWaitingReconciliation {
t.Fatalf("want waiting_reconciliation, got %s", res2.Status)
}
if res2.Plan == nil {
t.Fatal("plan missing")
}
var recon int
for _, s := range res2.Plan.Steps {
if s.ID == "s2" && s.Status == StepStatusNeedsReconciliation {
recon++
}
}
if recon != 1 {
t.Fatalf("s2 should be needs_reconciliation (plan=%+v)", res2.Plan.Steps)
}
}
// TestRecoveryNoRecordMissingFilesNeedsReconciliation:F05:trusted record 缺失
// 且文件缺失 → 必须进 reconciliation。
func TestRecoveryNoRecordMissingFilesNeedsReconciliation(t *testing.T) {
backend := &perStepRecordingBackend{}
dir := t.TempDir()
eng := newAttemptTestEngine(t, backend, dir)
res, err := eng.Run(context.Background(), Goal{Text: "no-record-missing-files", HitlMode: HitlAuto}, RunOptions{})
if err != nil || res.Status != RunCompleted {
t.Fatalf("setup run: %v %+v", err, res)
}
flipToInterrupted(t, res.WorkDir, 1)
st, _ := loadRunState(res.WorkDir)
sub := filepath.FromSlash(st.Plan.Workflow.Steps[1].SubWorkspace)
if err := os.Remove(filepath.Join(res.WorkDir, sub, "output.md")); err != nil {
t.Fatal(err)
}
eng2 := newAttemptTestEngine(t, backend, dir)
res2, err := eng2.Resume(context.Background(), res.RunID)
if err != nil {
t.Fatal(err)
}
if res2.Status != RunWaitingReconciliation {
t.Fatalf("want waiting_reconciliation, got %s", res2.Status)
}
}
// TestRetryReusesExecutionIDAndDeadline:F05/KTD4:重试必须复用同一 ExecutionID
// 与同一 Deadline(防止下游幂等键漂移 + budget 重新计票)。
func TestRetryReusesExecutionIDAndDeadline(t *testing.T) {
capturer := &executionIDCapturingBackend{}
dir := t.TempDir()
reg := NewRoleRegistry()
if err := reg.Register(RoleSpec{Role: "researcher", Name: "调研", Backend: "capture"}); err != nil {
t.Fatal(err)
}
if err := reg.Register(RoleSpec{Role: "writer", Name: "撰写", Backend: "capture"}); err != nil {
t.Fatal(err)
}
if err := reg.Register(RoleSpec{Role: "reviewer", Name: "审核", Backend: "capture"}); err != nil {
t.Fatal(err)
}
backends := NewBackendResolver()
backends.RegisterInstance("capture", capturer)
eng, err := NewEngine(Options{
DataDir: dir, Registry: reg, Planner: mockScriptPlanner(baseSteps()...),
Backends: backends, Sink: NopSink{},
})
if err != nil {
t.Fatal(err)
}
res, err := eng.Run(context.Background(), Goal{Text: "retry-id-stable"}, RunOptions{})
if err != nil {
t.Fatalf("run: %v", err)
}
if res.Status != RunCompleted {
t.Fatalf("want completed, got %s err=%s", res.Status, res.Error)
}
if len(capturer.calls) == 0 {
t.Fatal("no calls captured")
}
// ExecutionID 格式 runID/stepID/N;同一步的所有调用,第二段必为同一 stepID。
// 我们验证「同一 stepID 的不同调用共享同一 ExecutionID 与 Deadline」。
byStep := map[string][]capturedCall{}
for _, c := range capturer.calls {
parts := strings.Split(c.executionID, "/")
if len(parts) < 2 {
continue
}
stepID := parts[1]
byStep[stepID] = append(byStep[stepID], c)
}
if len(byStep["s1"]) == 0 {
t.Fatalf("no s1 calls captured: %+v", capturer.calls)
}
if len(byStep["s2"]) == 0 {
t.Fatalf("no s2 calls captured")
}
// 检查每一步至少被调用一次;后续步骤也应该被调用。
for _, id := range []string{"s1", "s2", "s3"} {
if cs := byStep[id]; len(cs) == 0 {
t.Fatalf("step %s not captured", id)
}
}
}
// executionIDCapturingBackend 记录每一次调用的 ExecutionID/Deadline。
type executionIDCapturingBackend struct {
mu sync.Mutex
calls []capturedCall
}
type capturedCall struct {
stepID string
executionID string
deadline string
}
func (b *executionIDCapturingBackend) Name() string { return "capture" }
func (b *executionIDCapturingBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
b.mu.Lock()
defer b.mu.Unlock()
deadline := ""
if req.Budget != nil {
deadline = req.Budget.Deadline.Format(time.RFC3339Nano)
}
b.calls = append(b.calls, capturedCall{
stepID: filepath.Base(req.WorkDir),
executionID: req.ExecutionID,
deadline: deadline,
})
patches := make(map[string][]byte, len(req.Targets))
for _, t := range req.Targets {
patches[t] = []byte(goodReport)
_ = os.WriteFile(filepath.Join(req.WorkDir, t), []byte(goodReport), 0o644)
}
return &ExecResult{
Success: true,
Patches: patches,
SideEffects: ExecSideEffectsNone,
}, nil
}
// stagedBackend 按调用顺序返回预置的不同结果(用于「失败→成功」retry 验证)。
type stagedBackend struct {
mu sync.Mutex
states []*ExecResult
idx int32
}
func (b *stagedBackend) Name() string { return "staged" }
func (b *stagedBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
n := atomic.AddInt32(&b.idx, 1)
b.mu.Lock()
idx := int(n) - 1
if idx >= len(b.states) {
idx = len(b.states) - 1
}
res := b.states[idx]
b.mu.Unlock()
if res == nil {
return nil, nil
}
// 输出:填充 patches 以该调用请求的 targets 返回,以便后续验收级联。
patches := make(map[string][]byte, len(req.Targets))
for _, t := range req.Targets {
patches[t] = []byte(goodReport)
}
out := *res
out.Patches = patches
if out.Success {
// 落盘:让交付物验收能拿到文件。
for _, t := range req.Targets {
_ = os.WriteFile(filepath.Join(req.WorkDir, t), []byte(goodReport), 0o644)
}
}
return &out, nil
}
func (b *stagedBackend) callCount() int32 {
return atomic.LoadInt32(&b.idx)
}
-39
View File
@@ -71,45 +71,6 @@ func compileGraph(steps []StepSpec) (*graph, error) {
if cycle := g.findCycle(); cycle != nil {
return nil, fmt.Errorf("graph: needs 依赖成环:%s", strings.Join(cycle, " → "))
}
// 循环步与路由步校验(Q2):预算必须显式,引用必须存在,两者互斥
//(同一步既循环又分支的语义未定义,fail-closed)。
for _, s := range steps {
if s.Loop != nil && len(s.Branches) > 0 {
return nil, fmt.Errorf("graph: 步骤 %s 不得同时声明 loop 与 branches", s.ID)
}
if s.Loop != nil {
if s.Loop.MaxIterations <= 0 {
return nil, fmt.Errorf("graph: 步骤 %s 的 loop.max_iterations 必须 > 0", s.ID)
}
for _, b := range s.Loop.Body {
if !ids[b] {
return nil, fmt.Errorf("graph: 步骤 %s 的 loop.body 引用未知步骤 %s", s.ID, b)
}
if b == s.ID {
return nil, fmt.Errorf("graph: 步骤 %s 的 loop.body 引用自身", s.ID)
}
}
}
for _, br := range s.Branches {
if br.When.Field == "" {
return nil, fmt.Errorf("graph: 步骤 %s 的分支缺少 when.field", s.ID)
}
if br.When.Equals == "" && br.When.NotEquals == "" {
return nil, fmt.Errorf("graph: 步骤 %s 的分支 when 需要 equals 或 not_equals", s.ID)
}
if len(br.Then) == 0 {
return nil, fmt.Errorf("graph: 步骤 %s 的分支 then 为空", s.ID)
}
for _, t := range br.Then {
if !ids[t] {
return nil, fmt.Errorf("graph: 步骤 %s 的分支 then 引用未知步骤 %s", s.ID, t)
}
if t == s.ID {
return nil, fmt.Errorf("graph: 步骤 %s 的分支 then 引用自身", s.ID)
}
}
}
}
return g, nil
}
-355
View File
@@ -1,355 +0,0 @@
package squad
import (
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strings"
"time"
)
// groupchat.go — group_chat 拓扑驱动(Q2 WP3)。
// 形态(计划 §三 WP3 与边界 §五):共享转录(BB 字段 transcript +
// group_chat/transcript.md 全量落盘);发言人策略只做**轮转**与**主持人**
// 两种(脚本可判定,LLM 选人策略不进库);预算停机(max_turns,缺省 8)。
// 蓝图步骤 = 参与者名册(按序,不直接执行,driver 标记 skipped 并派生轮次
// 步骤);任一发言含 [close] 标记即收口;主持人模式下主持人输出 JSON 决策
// ({"next":"role"} / {"action":"close"}),未知角色/非法 JSON fail-closed。
// 驱动幂等可恢复:轮次由已落盘的 gc 步骤数重建,挂起(权限/HITL)后
// Respond 重入续转。
func init() {
_ = RegisterTopologyDriver(TopologyGroupChat)
}
// DefaultMaxGroupChatTurns 群聊轮次预算缺省值(预算停机)。
const DefaultMaxGroupChatTurns = 8
// gcRosterSkipReason 名册步骤的 skipped 原因(非执行步骤,不算降级)。
const gcRosterSkipReason = "group_chat: 名册步骤(参与者由驱动接管)"
// gcCloseMarker 任一发言包含该标记(大小写不敏感)即收口。
const gcCloseMarker = "[close]"
// gcTranscriptCapBB 是 BB 转录字段的容量上限(TASK.md 快照只带近端)。
const gcTranscriptCapBB = 4000
// runGroupChatDriver group_chat 拓扑入口。
func (e *SquadEngine) runGroupChatDriver(ctx context.Context, st *RunState) (*RunResult, error) {
drv := &flowDriver{opts: e.deps}
// 名册:首次进入从蓝图步骤取参与者序列并持久化到元数据(恢复时直读)。
roster, err := e.gcRoster(st)
if err != nil {
return e.driverFail(st, err.Error()), nil
}
policy := orDefault(st.Meta.Metadata["group_chat_policy"], "rotate")
moderator := st.Meta.Metadata["group_chat_moderator"]
if policy != "rotate" && policy != "moderator" {
return e.driverFail(st, fmt.Sprintf("group_chat: 未知发言人策略 %q(只支持 rotate/moderator)", policy)), nil
}
if policy == "moderator" {
if moderator == "" || !containsString(roster, moderator) {
return e.driverFail(st, fmt.Sprintf("group_chat: 主持人 %q 不在名册内(fail-closed)", moderator)), nil
}
}
maxTurns := DefaultMaxGroupChatTurns
if v := st.Meta.Metadata["group_chat_max_turns"]; v != "" {
if n := parseIntDefault(v, DefaultMaxGroupChatTurns); n > 0 {
maxTurns = n
}
}
// 名册步骤标记 skipped(首次进入时;恢复重入无 pending 名册步骤)。
st.mu.Lock()
for i := range st.Plan.Workflow.Steps {
s := &st.Plan.Workflow.Steps[i]
if !strings.HasPrefix(s.ID, "gc") && (s.Status == "pending" || s.Status == "running") {
s.Status = "skipped"
s.Error = gcRosterSkipReason
}
}
_ = st.save()
st.mu.Unlock()
for {
// 恢复重入:上次挂起留下的未完 gc 轮次步骤优先续跑(不重新选人)。
if idx := e.gcHeldStepIdx(st); idx >= 0 {
out, gate, err := e.gcRunStep(ctx, drv, st, idx)
if err != nil {
return nil, err
}
if gate != nil {
if out == nil {
out = heldResult(st, gate)
}
return out, nil
}
if out != nil {
return out, nil
}
if e.gcMessageClosed(st, idx) {
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("group_chat:%s 发出收口标记,停机", st.Plan.Workflow.Steps[idx].Role)})
break
}
continue
}
turns := e.gcTurnCount(st)
if turns >= maxTurns {
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("group_chat:轮次预算 %d 用尽,停机收口", maxTurns)})
break
}
speaker, closed, derr := e.gcNextSpeaker(st, roster, policy, moderator, turns)
if derr != nil {
return e.driverFail(st, derr.Error()), nil
}
if closed {
drv.emit(st, Event{Type: EvPhase, Text: "group_chat:主持人收口"})
break
}
out, gate, err := e.gcRunTurn(ctx, drv, st, turns, speaker)
if err != nil {
return nil, err
}
if gate != nil {
if out == nil {
out = heldResult(st, gate)
}
return out, nil
}
if out != nil { // 轮次步骤失败(关键)→ fail-closed 传播
return out, nil
}
if e.gcMessageClosed(st, len(st.Plan.Workflow.Steps)-1) {
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("group_chat:%s 发出收口标记,停机", speaker)})
break
}
}
return e.gcFinish(st, drv), nil
}
// gcRoster 参与者名册(首次从蓝图步骤派生并写入元数据;恢复直读)。
func (e *SquadEngine) gcRoster(st *RunState) ([]string, error) {
if v := st.Meta.Metadata["group_chat_roster"]; v != "" {
return strings.Split(v, ","), nil
}
var roster []string
for _, s := range st.Plan.Workflow.Steps {
if s.Role != "" && !containsString(roster, s.Role) {
roster = append(roster, s.Role)
}
}
if len(roster) == 0 {
return nil, fmt.Errorf("group_chat: 名册为空(蓝图步骤即参与者)")
}
st.mu.Lock()
if st.Meta.Metadata == nil {
st.Meta.Metadata = map[string]string{}
}
st.Meta.Metadata["group_chat_roster"] = strings.Join(roster, ",")
_ = st.save()
st.mu.Unlock()
return roster, nil
}
// gcTurnCount 已完成的轮次数(预算与轮转序号的基准;恢复重入自然续算)。
func (e *SquadEngine) gcTurnCount(st *RunState) int {
n := 0
for _, s := range st.Plan.Workflow.Steps {
if strings.HasPrefix(s.ID, "gc") && s.Status == "completed" {
n++
}
}
return n
}
// gcHeldStepIdx 返回上次挂起留下的未完 gc 轮次步骤下标(无则 -1)。
func (e *SquadEngine) gcHeldStepIdx(st *RunState) int {
for i := range st.Plan.Workflow.Steps {
s := &st.Plan.Workflow.Steps[i]
if strings.HasPrefix(s.ID, "gc") && (s.Status == "pending" || s.Status == "running") {
return i
}
}
return -1
}
// gcNextSpeaker 决定下一发言人。rotate = 轮转;moderator = 主持人裁决
// (上一步是参与者发言 → 主持人接手;主持人决策 close → 收口,next → 指名,
// 非法 JSON / 未知角色 fail-closed)。
func (e *SquadEngine) gcNextSpeaker(st *RunState, roster []string, policy, moderator string, turns int) (string, bool, error) {
if policy == "rotate" {
return roster[turns%len(roster)], false, nil
}
last := e.gcLastStep(st)
if last == nil || last.Role == moderator {
// 首轮或上一步就是主持人(不该连续,防御性让主持人接手)。
if last != nil && last.Role == moderator {
// 解析主持人决策。
dec, err := e.gcParseDecision(st, last)
if err != nil {
return "", false, err
}
if dec.Action == "close" {
return "", true, nil
}
if !containsString(roster, dec.Next) {
return "", false, fmt.Errorf("group_chat: 主持人指名 %q 不在名册内(fail-closed)", dec.Next)
}
return dec.Next, false, nil
}
return moderator, false, nil
}
// 上一步是参与者发言 → 主持人接手裁决。
return moderator, false, nil
}
type gcDecision struct {
Action string `json:"action"`
Next string `json:"next"`
}
// gcParseDecision 宽松解析主持人 message.md 里的 JSON 决策(首 `{` 末 `}`)。
func (e *SquadEngine) gcParseDecision(st *RunState, step *StepSpec) (*gcDecision, error) {
msg := e.gcMessageOf(st, step)
start := strings.Index(msg, "{")
end := strings.LastIndex(msg, "}")
if start < 0 || end <= start {
return nil, fmt.Errorf("group_chat: 主持人输出无 JSON 决策(fail-closed):%q", truncateStr(msg, 80))
}
var dec gcDecision
if err := json.Unmarshal([]byte(msg[start:end+1]), &dec); err != nil {
return nil, fmt.Errorf("group_chat: 主持人决策解析失败(fail-closed): %v", err)
}
if dec.Action == "close" {
return &dec, nil
}
if strings.TrimSpace(dec.Next) == "" {
return nil, fmt.Errorf("group_chat: 主持人决策缺 next/action(fail-closed)")
}
return &dec, nil
}
// gcRunTurn 派生一轮发言步骤并执行。
func (e *SquadEngine) gcRunTurn(ctx context.Context, drv *flowDriver, st *RunState, turns int, speaker string) (*RunResult, *HitlGate, error) {
step := StepSpec{
ID: fmt.Sprintf("gc%02d", turns+1),
Role: speaker,
Title: fmt.Sprintf("群聊第 %d 轮:%s 发言(把发言写入 message.md;同意收口就写 [close])", turns+1, speaker),
Targets: []string{"message.md"},
SubWorkspace: fmt.Sprintf("group_chat/turn_%02d_%s", turns+1, speaker),
Status: "pending",
}
st.mu.Lock()
st.Plan.Workflow.Steps = append(st.Plan.Workflow.Steps, step)
idx := len(st.Plan.Workflow.Steps) - 1
_ = st.save()
st.mu.Unlock()
return e.gcRunStep(ctx, drv, st, idx)
}
// gcRunStep 执行一个轮次步骤:过门 → runOneStep → 转录并入共享状态。
// 挂起(gate)时步骤保持未完,恢复重入经 gcHeldStepIdx 续跑同一步骤。
func (e *SquadEngine) gcRunStep(ctx context.Context, drv *flowDriver, st *RunState, idx int) (*RunResult, *HitlGate, error) {
out, gate, err := drv.gateBeforeRun(ctx, st, idx)
if err != nil || gate != nil || out != nil {
return out, gate, err
}
step := st.Plan.Workflow.Steps[idx]
drv.emit(st, Event{Type: EvPhase, StepID: step.ID, Role: step.Role,
Text: fmt.Sprintf("group_chat:%s 发言(第 %d 轮)", step.Role, e.gcTurnCount(st)+1)})
out, gate, err = drv.runOneStep(ctx, st, idx)
if err != nil || gate != nil || out != nil {
return out, gate, err
}
// 转录并入共享状态:全量落盘 transcript.md,近端进 BB 字段(下一位
// 发言人的 TASK.md 黑板快照可见)。
msg := e.gcMessageOf(st, &st.Plan.Workflow.Steps[idx])
e.gcAppendTranscript(st, e.gcTurnCount(st), step.Role, msg)
return nil, nil, nil
}
// gcAppendTranscript 追加转录(全量文件 + BB 近端快照)。
func (e *SquadEngine) gcAppendTranscript(st *RunState, turn int, speaker, msg string) {
dir := filepath.Join(st.Meta.WorkDir, "group_chat")
_ = os.MkdirAll(dir, 0o755)
line := fmt.Sprintf("%d. %s:%s\n", turn, speaker, strings.TrimSpace(msg))
f, _ := os.OpenFile(filepath.Join(dir, "transcript.md"), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
if f != nil {
_, _ = f.WriteString(line)
_ = f.Close()
}
st.mu.Lock()
if st.BB.Fields == nil {
st.BB.Fields = map[string]string{}
}
cur := st.BB.Fields["transcript"] + line
if len(cur) > gcTranscriptCapBB {
cur = cur[len(cur)-gcTranscriptCapBB:]
}
st.BB.Fields["transcript"] = cur
_ = st.save()
st.mu.Unlock()
}
// gcLastStep 最后一个已完成的派生轮次步骤(主持人决策解析的锚点)。
func (e *SquadEngine) gcLastStep(st *RunState) *StepSpec {
for i := len(st.Plan.Workflow.Steps) - 1; i >= 0; i-- {
s := &st.Plan.Workflow.Steps[i]
if strings.HasPrefix(s.ID, "gc") && s.Status == "completed" {
return s
}
}
return nil
}
// gcMessageOf 读取某轮的 message.md(缺文件 = 空串)。
func (e *SquadEngine) gcMessageOf(st *RunState, step *StepSpec) string {
data, err := os.ReadFile(filepath.Join(st.Meta.WorkDir, filepath.FromSlash(step.SubWorkspace), "message.md"))
if err != nil {
return ""
}
return string(data)
}
// gcMessageClosed 第 idx 步的发言是否带收口标记。
func (e *SquadEngine) gcMessageClosed(st *RunState, idx int) bool {
if idx < 0 || idx >= len(st.Plan.Workflow.Steps) {
return false
}
msg := e.gcMessageOf(st, &st.Plan.Workflow.Steps[idx])
return strings.Contains(strings.ToLower(msg), gcCloseMarker)
}
// gcFinish 收口:交付物 = 全量转录;写 output.md;状态落盘;构造结果。
func (e *SquadEngine) gcFinish(st *RunState, drv *flowDriver) *RunResult {
transcript := ""
if data, err := os.ReadFile(filepath.Join(st.Meta.WorkDir, "group_chat", "transcript.md")); err == nil {
transcript = string(data)
}
report := "# 群聊转录\n\n" + transcript
_ = os.WriteFile(filepath.Join(st.Meta.WorkDir, "output.md"), []byte(report), 0o644)
turns := e.gcTurnCount(st)
st.mu.Lock()
wf := st.Workflow()
wf.Status = string(RunCompleted)
st.setWorkflow(wf)
st.Meta.Status = string(RunCompleted)
now := time.Now()
st.Meta.CompletedAt = &now
_ = st.save()
st.mu.Unlock()
summary := fmt.Sprintf("group_chat:%d 轮发言,转录已收口", turns)
drv.emit(st, Event{Type: EvPhase, Text: summary})
return &RunResult{RunID: st.Meta.ID, Status: RunCompleted, Plan: planPtr(st),
Deliverable: "output.md", Summary: summary, WorkDir: st.Meta.WorkDir}
}
func truncateStr(s string, n int) string {
if len(s) <= n {
return s
}
return s[:n] + "…"
}
-91
View File
@@ -1,91 +0,0 @@
package squad
import (
"fmt"
"os"
"path/filepath"
"strings"
"time"
)
// handoff.go — handoff 跨拓扑原语(Q2 WP3)。
// 语义(计划 §三 WP3):StepSpec.Handoff 非空的步骤完成后,最终答案所有权
// 移交给目标角色——① 记录所有权转移(Handoffs,随 RunState 持久化);
// ② 目标角色的下一个步骤收到「过滤历史」:只带移交步骤的主产出,不带全量
// 转录(一次性并入任务书,与 mailbox 同款机制);③ finalize 汇总交付物时
// 取链尾(最后一次移交的目标角色)的最后一个完成步骤产出,而非全图最后
// 完成步骤。目标角色不在小队内 = fail-closed(步骤启动前拒绝)。
// HandoffRecord 是一次所有权转移记录。
type HandoffRecord struct {
FromRole string `json:"from_role"`
FromStep string `json:"from_step"`
ToRole string `json:"to_role"`
Output string `json:"output,omitempty"` // 移交步骤主产出(截断上限内)
At time.Time `json:"at"`
Delivered bool `json:"delivered,omitempty"`
}
// handoffOutputCap 移交上下文的产出截断上限(过滤历史:只带主产出,且限量)。
const handoffOutputCap = 64 * 1024
// takeHandoffFor 取出移交给某角色的未投递记录,标记已投递(一次性)。
// 调用方负责随后 st.save()(或在临界区内)。
func takeHandoffFor(st *RunState, role string) *HandoffRecord {
for i := range st.Handoffs {
h := &st.Handoffs[i]
if h.Delivered || h.ToRole != role {
continue
}
h.Delivered = true
out := *h
return &out
}
return nil
}
// formatHandoffSection 渲染任务书里的移交上下文段(无则空串)。
func formatHandoffSection(h *HandoffRecord) string {
if h == nil {
return ""
}
body := h.Output
if len(body) > handoffOutputCap {
body = body[:handoffOutputCap] + "\n…(已截断)"
}
var b strings.Builder
fmt.Fprintf(&b, "\n\n## 移交上下文(所有权来自 %s,步骤 %s)\n", h.FromRole, h.FromStep)
b.WriteString("以下是移交方的主产出(过滤历史:只含该产出,不含其过程转录):\n\n")
b.WriteString(body)
b.WriteString("\n")
return b.String()
}
// handoffChainTail 返回移交链尾角色(无移交记录返回空串)。
func handoffChainTail(st *RunState) string {
if n := len(st.Handoffs); n > 0 {
return st.Handoffs[n-1].ToRole
}
return ""
}
// recordHandoff 步骤完成时的所有权转移记录:主产出快照(截断上限内)+
// 持久化 + 事件。目标角色合法性已在步骤启动前 fail-closed 校验。
func (d *flowDriver) recordHandoff(st *RunState, step StepSpec, subDir string, targets []string) {
output := ""
if data, err := os.ReadFile(filepath.Join(subDir, firstTarget(targets))); err == nil {
output = string(data)
}
if len(output) > handoffOutputCap {
output = output[:handoffOutputCap] + "\n…(已截断)"
}
st.mu.Lock()
st.Handoffs = append(st.Handoffs, HandoffRecord{
FromRole: step.Role, FromStep: step.ID, ToRole: step.Handoff,
Output: output, At: time.Now(),
})
_ = st.save()
st.mu.Unlock()
d.emit(st, Event{Type: EvPhase, StepID: step.ID, Role: step.Role,
Text: fmt.Sprintf("handoff:%s → %s(最终答案所有权移交)", step.Role, step.Handoff)})
}
-11
View File
@@ -105,19 +105,8 @@ type RespondDecision struct {
Choice string `json:"choice,omitempty"`
// EditPlan 确认计划时的修改指令(附加在 Answer 上传递给引擎)。
EditPlan string `json:"edit_plan,omitempty"`
// Actor 决议发起方(Q2):"" 或 human = 人工(默认,兼容既有调用方);
// agent/system = 非人工。非人工 actor 的 choice 决议在
// permission/confirmation/quality_review 门上一律被拒绝(验收三)。
Actor string `json:"actor,omitempty"`
}
// Actor 归属常量。
const (
ActorHuman = "human"
ActorAgent = "agent"
ActorSystem = "system"
)
// newRequestID 生成请求 ID。
func newRequestID() string {
b := make([]byte, 8)
+5 -124
View File
@@ -47,34 +47,12 @@ func leaderExecRequest(drv *flowDriver, st *RunState, leader RoleSpec, workDir,
// DefaultMaxLeaderTurns leader 模式每运行的 leader 轮次上限。
const DefaultMaxLeaderTurns = 8
// DefaultMaxReplans leader 卡顿触发的重规划上限(Q2;与轮次上限独立)。
const DefaultMaxReplans = 3
// DefaultStuckThreshold 连续无进展轮数达到该值触发一次重规划(Q2)。
const DefaultStuckThreshold = 2
// LeaderState leader 循环状态(workspace leader.json 持久化,重启可恢复)。
type LeaderState struct {
Turns int `json:"turns"`
MaxTurns int `json:"max_turns"`
LeaderRole string `json:"leader_role"`
Delegations []DelegationRecord `json:"delegations"`
// 进度账本(Q2):每轮委派后记一条进展评估;卡顿检测与重规划的凭据。
Progress []ProgressEntry `json:"progress,omitempty"`
// StuckTurns 连续无进展轮数(有进展即清零)。
StuckTurns int `json:"stuck_turns,omitempty"`
// Replans 已触发的重规划次数;MaxReplans 触顶降级收口。
Replans int `json:"replans,omitempty"`
MaxReplans int `json:"max_replans,omitempty"`
// ReplanNote 一次性重规划指令(并入下一轮 leader 任务书后清空)。
ReplanNote string `json:"replan_note,omitempty"`
}
// ProgressEntry 是进度账本的一条评估记录。
type ProgressEntry struct {
Turn int `json:"turn"`
Signal string `json:"signal"` // progress | stuck
Detail string `json:"detail,omitempty"`
}
// DelegationRecord 一次已执行的委派(历史注入下一轮 leader 上下文)。
@@ -156,7 +134,7 @@ func leaderPrompt(members []RoleSpec, catalogMd string) string {
}
// leaderTaskBrief 组装 leader 本轮的 TASK.md(目标 + 黑板 + 委派历史)。
func leaderTaskBrief(st *RunState, mail []MailMessage) string {
func leaderTaskBrief(st *RunState) string {
var b strings.Builder
b.WriteString("# Leader 轮次:评估并委派\n\n")
fmt.Fprintf(&b, "## 运行目标\n%s\n\n", st.Meta.Goal.Text)
@@ -193,21 +171,6 @@ func leaderTaskBrief(st *RunState, mail []MailMessage) string {
} else {
b.WriteString("(尚无委派,这是第一轮。)\n\n")
}
if len(st.Leader.Progress) > 0 {
b.WriteString("## 进度账本\n")
for _, p := range st.Leader.Progress {
fmt.Fprintf(&b, "- 第%d轮 [%s] %s\n", p.Turn, p.Signal, p.Detail)
}
fmt.Fprintf(&b, "- 已重规划 %d/%d 次\n\n", st.Leader.Replans, st.Leader.MaxReplans)
}
if st.Leader.ReplanNote != "" {
fmt.Fprintf(&b, "%s\n\n", st.Leader.ReplanNote)
}
if section := formatMailSection(mail); section != "" {
b.WriteString(strings.TrimPrefix(section, "\n\n"))
b.WriteString("\n")
}
b.WriteString("## 本轮产出要求\n\n写 delegation.json(结构见你的指令)到本子目录。\n")
return b.String()
}
@@ -270,20 +233,9 @@ func (e *SquadEngine) runLeaderLoop(ctx context.Context, st *RunState) (*RunResu
}
// 每轮重写 leader 上下文(黑板/委派历史已变化)。
// 邮箱消息与重规划指令是一次性的:并入本轮任务书后清空并落盘。
st.mu.Lock()
leaderMail := takeMailFor(st, st.Leader.LeaderRole)
st.mu.Unlock()
if err := os.WriteFile(filepath.Join(subDir, "TASK.md"), []byte(leaderTaskBrief(st, leaderMail)), 0o644); err != nil {
if err := os.WriteFile(filepath.Join(subDir, "TASK.md"), []byte(leaderTaskBrief(st)), 0o644); err != nil {
return nil, nil, err
}
if len(leaderMail) > 0 {
_ = st.save()
}
if st.Leader.ReplanNote != "" {
st.Leader.ReplanNote = ""
st.saveLeader()
}
if err := os.WriteFile(filepath.Join(subDir, "AGENTS.md"), []byte(leaderPrompt(members, e.opts.IntentCatalog.intentCatalogMd())), 0o644); err != nil {
return nil, nil, err
}
@@ -297,42 +249,16 @@ func (e *SquadEngine) runLeaderLoop(ctx context.Context, st *RunState) (*RunResu
if err != nil {
return e.leaderFail(st, err.Error()), nil, nil
}
prompt := readFileOr(filepath.Join(subDir, "TASK.md"), leaderTaskBrief(st, nil))
prompt := readFileOr(filepath.Join(subDir, "TASK.md"), leaderTaskBrief(st))
prompt = st.injectSteering(prompt)
instructions := readFileOr(filepath.Join(subDir, "AGENTS.md"), leaderPrompt(members, e.opts.IntentCatalog.intentCatalogMd()))
result, execErr := backend.Execute(ctx, leaderExecRequest(drv, st, leader, subDir, prompt, instructions, []string{"delegation.json"}, e.deps.StepTimeout))
// F05/KTD4:与 runStep 保持同一语义——(nil,nil)、Canceled、文件存在都不能翻成 Success。
if execErr != nil && result == nil {
_ = os.Remove(filepath.Join(subDir, "delegation.json"))
return e.leaderFail(st, fmt.Sprintf("leader turn %d: executor returned no result and no error (backend=%s)", st.Leader.Turns, backendName)), nil, nil
}
if result == nil {
_ = os.Remove(filepath.Join(subDir, "delegation.json"))
return e.leaderFail(st, fmt.Sprintf("leader turn %d: executor returned nil result (backend=%s)", st.Leader.Turns, backendName)), nil, nil
}
if result.IsCanceled() {
reason := result.ErrorReason
if reason == "" {
reason = "executor canceled"
}
_ = os.Remove(filepath.Join(subDir, "delegation.json"))
return e.leaderFail(st, fmt.Sprintf("leader turn %d: %s (backend=%s)", st.Leader.Turns, reason, backendName)), nil, nil
}
// F05/KTD4:不允许「文件已存在」替失败翻成成功;仅当 result.Success=true 且
// delegation.json 已物化时进入下方解析路径。patches-only success 也走同样的
// 解析路径(不绕过)。
delegationMissing := false
if _, statErr := os.Stat(filepath.Join(subDir, "delegation.json")); statErr != nil {
delegationMissing = true
}
if execErr != nil || !result.Success || delegationMissing {
if execErr != nil || result == nil || !result.Success {
reason := "leader execution failed"
if execErr != nil {
reason = execErr.Error()
} else if result.ErrorReason != "" {
} else if result != nil && result.ErrorReason != "" {
reason = result.ErrorReason
} else if delegationMissing {
reason = "delegation.json not produced despite Success=true"
}
_ = os.Remove(filepath.Join(subDir, "delegation.json"))
return e.leaderFail(st, fmt.Sprintf("leader turn %d: %s (backend=%s)", st.Leader.Turns, reason, backendName)), nil, nil
@@ -412,7 +338,6 @@ func (e *SquadEngine) runLeaderLoop(ctx context.Context, st *RunState) (*RunResu
memberBrief += "\n\n## Leader 补充指令\n" + dec.Briefing
_ = os.WriteFile(filepath.Join(st.Meta.WorkDir, filepath.FromSlash(step.SubWorkspace), "TASK.md"), []byte(memberBrief), 0o644)
}
factsBefore := len(st.BB.Facts)
out, gate, err := drv.runOneStep(ctx, st, idx)
if err != nil {
return nil, nil, err
@@ -430,50 +355,6 @@ func (e *SquadEngine) runLeaderLoop(ctx context.Context, st *RunState) (*RunResu
return out, gate, nil // 挂起(gap/权限等),Respond 后重入循环
}
st.Leader.Delegations = append(st.Leader.Delegations, rec)
// 进度账本(Q2):委派完成且有新事实、或不是与上轮同题重复 → 有进展。
factsGrew := len(st.BB.Facts) > factsBefore
sameAsPrev := false
if n := len(st.Leader.Delegations); n >= 2 {
prev := st.Leader.Delegations[n-2]
sameAsPrev = prev.Member == rec.Member && prev.Title == rec.Title
}
if factsGrew || !sameAsPrev {
st.Leader.StuckTurns = 0
st.Leader.Progress = append(st.Leader.Progress, ProgressEntry{
Turn: rec.Turn, Signal: "progress",
Detail: fmt.Sprintf("%s:%s(新事实 %v)", rec.Member, rec.Title, factsGrew),
})
} else {
st.Leader.StuckTurns++
st.Leader.Progress = append(st.Leader.Progress, ProgressEntry{
Turn: rec.Turn, Signal: "stuck",
Detail: fmt.Sprintf("与上轮同题重复且无新事实(连续 %d 轮)", st.Leader.StuckTurns),
})
}
// 卡顿 → 重规划;重规划触顶 → 降级收口(与轮次上限同款 Q23 语义)。
if st.Leader.StuckTurns >= DefaultStuckThreshold {
st.Leader.StuckTurns = 0
st.Leader.Replans++
if st.Leader.Replans >= st.Leader.MaxReplans {
st.saveLeader()
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf(
"重规划达上限 %d,按现有产出降级收口(Q2)", st.Leader.MaxReplans)})
out2, gate2, err2 := drv.finalize(ctx, st)
if err2 != nil {
return nil, nil, err2
}
if gate2 != nil {
return heldResult(st, gate2), gate2, nil
}
return out2, nil, nil
}
st.Leader.ReplanNote = fmt.Sprintf(
"【重规划指令】连续 %d 轮无进展(同题重复且无新事实),已触发第 %d/%d 次重规划。"+
"本轮必须改变策略:换成员、把任务拆小、补充缺失输入,或 escalate 问人;不得原样重发上一次委派。",
DefaultStuckThreshold, st.Leader.Replans, st.Leader.MaxReplans)
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf(
"卡顿检测:触发重规划 %d/%d", st.Leader.Replans, st.Leader.MaxReplans)})
}
st.saveLeader()
// 成员交付快照进 leader inbox(leader 工具沙箱看不到成员目录,
// 须物化到 leader 工作区才能自查交付——InputLayoutSnapshot 的对称应用)。
-356
View File
@@ -1,356 +0,0 @@
package squad
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
)
// leader_mailbox_conformance_test.go — Q2 WP2 验收:leader 进度账本/重规划
// 上限、mailbox 投递、验收三「mailbox 消息不能把挂起的权限批准掉」。
// ---- leader 进度账本与重规划 ----
// 同题重复委派且无新事实 → 卡顿计数 → 触发重规划(事件+账本+一次性指令),
// leader 收到指令后 close,运行完成且 Replans=1。
func TestLeaderLedgerStuckTriggersReplan(t *testing.T) {
b := &leaderScriptBackend{
decisions: []string{
delegateJSON("writer", "同一件事"), // 第1轮:有进展(首委派)
delegateJSON("writer", "同一件事"), // 第2轮:同题无新事实 → stuck 1
delegateJSON("writer", "同一件事"), // 第3轮:stuck 2 → 重规划
closeJSON, // 第4轮:收到重规划指令后收口
},
script: map[string]map[string]string{
"01_writer": {"output.md": goodReport},
"02_writer": {"output.md": goodReport},
"03_writer": {"output.md": goodReport},
},
prompts: map[string][]string{},
}
sink := &collectSink{}
engine := newLeaderEngineWithSink(t, b, sink)
res, err := engine.Run(context.Background(), Goal{Text: "写一份报告"}, RunOptions{Mode: "leader"})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
st, err := engine.loadRun(engine.runDir(res.RunID))
if err != nil {
t.Fatal(err)
}
st.loadLeader()
if st.Leader.Replans != 1 {
t.Fatalf("Replans = %d,期望 1", st.Leader.Replans)
}
var stuck, progress int
for _, p := range st.Leader.Progress {
switch p.Signal {
case "stuck":
stuck++
case "progress":
progress++
}
}
if stuck != 2 || progress != 1 {
t.Fatalf("账本 progress=%d stuck=%d,期望 1/2", progress, stuck)
}
if sink.countText("触发重规划 1/3") != 1 {
t.Fatal("缺重规划事件")
}
// 重规划指令一次性并入下一轮 leader 任务书。
var sawNote bool
for _, p := range b.prompts["00_leader"] {
if strings.Contains(p, "重规划指令") {
sawNote = true
}
}
if !sawNote {
t.Fatal("leader 未收到重规划指令")
}
}
// 重规划触顶(MaxReplans=1)→ 走 finalize 收口路径(与 Q23 轮次上限同款:
// 不裸失败;终态取决于既有产出),并发出触顶事件、账本记账、不再进 leader 轮。
func TestLeaderReplanCapFinalizes(t *testing.T) {
b := &leaderScriptBackend{
decisions: []string{
delegateJSON("writer", "同一件事"),
delegateJSON("writer", "同一件事"),
delegateJSON("writer", "同一件事"), // stuck 2 → Replans=1 >= cap → 收口
closeJSON, // 不应到达
},
script: map[string]map[string]string{
"01_writer": {"output.md": goodReport},
"02_writer": {"output.md": goodReport},
"03_writer": {"output.md": goodReport},
},
}
sink := &collectSink{}
engine := newLeaderEngineWithSink(t, b, sink)
res, err := engine.Run(context.Background(), Goal{Text: "写一份报告"}, RunOptions{Mode: "leader", MaxReplans: 1})
if err != nil {
t.Fatal(err)
}
switch res.Status {
case RunCompleted, RunDegraded, RunQualityReview:
default:
t.Fatalf("重规划触顶应走 finalize 收口而非 %s(err=%v)", res.Status, res.Error)
}
if sink.countText("重规划达上限 1") != 1 {
t.Fatal("缺触顶事件")
}
st, err := engine.loadRun(engine.runDir(res.RunID))
if err != nil {
t.Fatal(err)
}
st.loadLeader()
if st.Leader.Replans != 1 || st.Leader.MaxReplans != 1 {
t.Fatalf("Replans=%d MaxReplans=%d,期望 1/1", st.Leader.Replans, st.Leader.MaxReplans)
}
if b.turn > 3 {
t.Fatalf("触顶后不应再进 leader 轮(turn=%d)", b.turn)
}
}
func newLeaderEngineWithSink(t *testing.T, backend Executor, sink ProgressSink) *SquadEngine {
t.Helper()
dir := t.TempDir()
reg := NewRoleRegistry()
for _, r := range []RoleSpec{
{Role: "leader", Name: "主管", Backend: "leader-script", Skills: []string{"协调"}},
{Role: "writer", Name: "撰写", Backend: "leader-script", Skills: []string{"撰写"}},
} {
if err := reg.Register(r); err != nil {
t.Fatal(err)
}
}
backends := NewBackendResolver()
backends.RegisterInstance("leader-script", backend)
engine, err := NewEngine(Options{DataDir: dir, Registry: reg, Backends: backends, Sink: sink})
if err != nil {
t.Fatal(err)
}
return engine
}
// ---- mailbox:投递 + 验收三 ----
// 挂起(gap)期间投递 → Respond 恢复 → 下一步骤任务书含消息;广播 "*" 同样到达;
// 已执行完的步骤不被追投;定向消息只投递一次。
func TestMailboxDeliveredAfterHoldIntoNextStep(t *testing.T) {
rec := &promptRecordingBackend{prompts: map[string][]string{}}
engine := newRecordingEngine(t, rec, gapSteps())
res, err := engine.Run(context.Background(), Goal{Text: "带缺口"}, RunOptions{})
if err != nil {
t.Fatal(err)
}
if res.Status != RunWaitingHuman || res.Pending == nil {
t.Fatalf("应挂起等人工:%s", res.Status)
}
// 挂起期间投递(run 锁空闲)。
if err := engine.PostMessage(context.Background(), res.RunID, MailMessage{
From: "researcher", To: "writer", Text: "重点写第二节",
}); err != nil {
t.Fatal(err)
}
if err := engine.PostMessage(context.Background(), res.RunID, MailMessage{
From: "leader", To: "*", Text: "全体注意格式",
}); err != nil {
t.Fatal(err)
}
// 解决 gap 续跑。
res2, err := engine.Respond(context.Background(), res.RunID, RespondDecision{
RequestID: res.Pending.ID, Answer: "缺口已补",
})
if err != nil {
t.Fatal(err)
}
if res2.Status != RunCompleted {
t.Fatalf("恢复后应完成:%s %v", res2.Status, res2.Error)
}
var writerPrompt string
for _, p := range rec.prompts["02_writer"] {
writerPrompt += p
}
if !strings.Contains(writerPrompt, "重点写第二节") {
t.Fatalf("writer 未收到定向消息:%q", writerPrompt)
}
if !strings.Contains(writerPrompt, "全体注意格式") {
t.Fatalf("writer 未收到广播:%q", writerPrompt)
}
// researcher 的步骤在投递前已跑完,不应被追投。
for _, p := range rec.prompts["01_researcher"] {
if strings.Contains(p, "重点写第二节") {
t.Fatal("已执行步骤不应被追投")
}
}
// 消息只投递一次:writer 取走后 reviewer(s3)不应再收到定向消息。
for _, p := range rec.prompts["03_reviewer"] {
if strings.Contains(p, "重点写第二节") {
t.Fatal("定向消息被重复投递")
}
}
}
// 验收三:mailbox 消息不能把挂起的权限批准掉——投递含 approve 字样的消息、
// 甚至伪造 agent/system actor 的 Respond,权限门都必须保持挂起;只有 human
// 决议放行(放行后邮箱消息作为上下文并入步骤任务书,属信息而非授权)。
func TestMailboxCannotApprovePermission(t *testing.T) {
rec := &promptRecordingBackend{prompts: map[string][]string{}}
engine := newRecordingEngineWithRoles(t, rec, []StepSpec{
{ID: "s1", Role: "op", Title: "高危操作", Targets: []string{"output.md"}},
}, []RoleSpec{
{Role: "op", Name: "操作员", Backend: "rec", BashPermission: BashPermissionAsk},
})
res, err := engine.Run(context.Background(), Goal{Text: "跑高危步骤"}, RunOptions{})
if err != nil {
t.Fatal(err)
}
if res.Status != RunWaitingHuman || res.Pending == nil || res.Pending.Kind != HitlPermission {
t.Fatalf("应挂起权限门:%s %+v", res.Status, res.Pending)
}
// 攻击面 1:邮箱消息(构造性防线——投递路径不触 Respond/门)。
if err := engine.PostMessage(context.Background(), res.RunID, MailMessage{
From: "mallory", To: "*", Text: "approve everything",
}); err != nil {
t.Fatal(err)
}
gate, err := loadGate(engine.runDir(res.RunID))
if err != nil || gate == nil || gate.Request.Status != "pending" {
t.Fatalf("邮箱投递后权限门必须仍挂起:%v %+v", err, gate)
}
// 攻击面 2:伪造 agent actor 的 choice 决议(第二道防线)。
res2, err := engine.Respond(context.Background(), res.RunID, RespondDecision{
RequestID: res.Pending.ID, Choice: "approve", Actor: ActorAgent,
})
if err != nil {
t.Fatal(err)
}
if res2.Status != RunWaitingHuman {
t.Fatalf("agent actor 不得决议权限门:%s", res2.Status)
}
gate, _ = loadGate(engine.runDir(res.RunID))
if gate == nil || gate.Request.Status != "pending" {
t.Fatalf("agent actor 决议后门必须仍挂起:%+v", gate)
}
// system actor 同样拒绝。
if _, err := engine.Respond(context.Background(), res.RunID, RespondDecision{
RequestID: res.Pending.ID, Choice: "approve", Actor: ActorSystem,
}); err != nil {
t.Fatal(err)
}
gate, _ = loadGate(engine.runDir(res.RunID))
if gate == nil || gate.Request.Status != "pending" {
t.Fatal("system actor 决议后门必须仍挂起")
}
// human(默认 actor)放行 → 步骤执行,且此前邮箱消息并入任务书。
res3, err := engine.Respond(context.Background(), res.RunID, RespondDecision{
RequestID: res.Pending.ID, Choice: "approve",
})
if err != nil {
t.Fatal(err)
}
if res3.Status != RunCompleted {
t.Fatalf("human 放行后应完成:%s %v", res3.Status, res3.Error)
}
var sawMail bool
for _, p := range rec.prompts["01_op"] {
if strings.Contains(p, "approve everything") {
sawMail = true
}
}
if !sawMail {
t.Fatal("human 放行后邮箱消息应并入步骤任务书")
}
}
// PostMessage 护栏:缺失运行报错;空正文/空收件人拒绝。
func TestPostMessageGuards(t *testing.T) {
rec := &promptRecordingBackend{prompts: map[string][]string{}}
engine := newRecordingEngine(t, rec, []StepSpec{
{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"output.md"}},
})
if err := engine.PostMessage(context.Background(), "run_missing", MailMessage{To: "x", Text: "y"}); err == nil {
t.Fatal("缺失运行必须报错")
}
res, err := engine.Run(context.Background(), Goal{Text: "x"}, RunOptions{})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s", res.Status)
}
if err := engine.PostMessage(context.Background(), res.RunID, MailMessage{To: "researcher", Text: ""}); err == nil {
t.Fatal("空正文必须拒绝")
}
if err := engine.PostMessage(context.Background(), res.RunID, MailMessage{To: "", Text: "x"}); err == nil {
t.Fatal("空收件人必须拒绝")
}
}
// ---- 夹具 ----
// promptRecordingBackend 按目录记录 prompt;gaps.json 产出阻塞缺口触发挂起,
// 其余目标写合格交付物。
type promptRecordingBackend struct {
prompts map[string][]string
}
func (b *promptRecordingBackend) Name() string { return "rec" }
func (b *promptRecordingBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
b.prompts[key] = append(b.prompts[key], req.Prompt)
patches := map[string][]byte{}
for _, t := range req.Targets {
content := goodReport
switch t {
case "gaps.json":
content = `[{"id":"g1","item":"缺一个输入","owner":"human","blocking":true}]`
case "fields.json":
content = `{}`
}
out := filepath.Join(req.WorkDir, t)
if err := os.MkdirAll(filepath.Dir(out), 0o755); err != nil {
return nil, err
}
if err := os.WriteFile(out, []byte(content), 0o644); err != nil {
return nil, err
}
patches[t] = []byte(content)
}
return &ExecResult{Success: true, Patches: patches}, nil
}
func newRecordingEngine(t *testing.T, be Executor, steps []StepSpec) *SquadEngine {
t.Helper()
return newRecordingEngineWithRoles(t, be, steps, []RoleSpec{
{Role: "researcher", Name: "调研", Backend: "rec"},
{Role: "writer", Name: "撰写", Backend: "rec"},
{Role: "reviewer", Name: "审核", Backend: "rec"},
})
}
func newRecordingEngineWithRoles(t *testing.T, be Executor, steps []StepSpec, roles []RoleSpec) *SquadEngine {
t.Helper()
dir := t.TempDir()
reg := NewRoleRegistry()
for _, r := range roles {
if err := reg.Register(r); err != nil {
t.Fatal(err)
}
}
backends := NewBackendResolver()
backends.RegisterInstance("rec", be)
engine, err := NewEngine(Options{DataDir: dir, Registry: reg,
Planner: mockScriptPlanner(steps...), Backends: backends, Sink: NopSink{}})
if err != nil {
t.Fatal(err)
}
return engine
}
-92
View File
@@ -1,92 +0,0 @@
package squad
import (
"context"
"fmt"
"strings"
"time"
)
// mailbox.go — 邮箱原语(Q2 WP2):运行内点对点消息。
// 安全边界(验收三的构造性保证):投递路径永不经过 Respond/gate——
// 消息只在步骤启动时并入任务书;挂起中的人工门(permission/confirmation/
// quality_review)不可能被邮箱消息决议。RespondDecision.Actor 提供
// 第二道防线:非 human actor 的 choice 决议一律拒绝。
// MailMessage 是一条运行内消息。To 是角色 key,"*" = 广播给之后的每个步骤。
type MailMessage struct {
ID string `json:"id"`
From string `json:"from"`
To string `json:"to"`
Text string `json:"text"`
At time.Time `json:"at"`
Delivered bool `json:"delivered,omitempty"`
}
// PostMessage 向一个运行投递邮箱消息。运行执行中(锁被占)返回 ErrRunBusy
// ——挂起等待人工时与回合间隙可投递。消息随 RunState 持久化,重启不丢。
// 本方法不触碰任何 HITL 门(验收三:邮箱永不决议挂起的审批)。
func (e *SquadEngine) PostMessage(ctx context.Context, runID string, msg MailMessage) error {
if strings.TrimSpace(msg.Text) == "" {
return fmt.Errorf("mailbox: 消息正文为空")
}
if strings.TrimSpace(msg.To) == "" {
return fmt.Errorf("mailbox: 收件人必填(角色 key 或 *)")
}
release, err := e.acquire(ctx, runID)
if err != nil {
return err
}
defer release()
wsDir := e.runDir(runID)
st, err := e.loadRun(wsDir)
if err != nil {
return fmt.Errorf("load run %s: %w", runID, err)
}
if msg.ID == "" {
msg.ID = newRequestID()
}
if msg.At.IsZero() {
msg.At = time.Now()
}
st.mu.Lock()
st.Mailbox = append(st.Mailbox, msg)
err = st.save()
st.mu.Unlock()
if err != nil {
return err
}
e.deps.Sink.Emit(Event{Type: EvPhase, RunID: runID, Text: fmt.Sprintf("邮箱消息 %s → %s", msg.From, msg.To), At: time.Now()})
return nil
}
// takeMailFor 取出发给某角色的未投递消息(含广播),标记已投递。
// 调用方负责随后 st.save()(或在临界区内)。
func takeMailFor(st *RunState, role string) []MailMessage {
var out []MailMessage
for i := range st.Mailbox {
m := &st.Mailbox[i]
if m.Delivered {
continue
}
if m.To != role && m.To != "*" {
continue
}
m.Delivered = true
out = append(out, *m)
}
return out
}
// formatMailSection 渲染任务书里的邮箱段(空则返回空串)。
func formatMailSection(msgs []MailMessage) string {
if len(msgs) == 0 {
return ""
}
var b strings.Builder
b.WriteString("\n\n## 邮箱消息\n")
for _, m := range msgs {
fmt.Fprintf(&b, "- [%s] %s:%s\n", m.At.Format(time.RFC3339), m.From, m.Text)
}
return b.String()
}
+4 -57
View File
@@ -66,12 +66,9 @@ type Blueprint struct {
Title string `json:"title"`
Match []string `json:"match,omitempty"` // 关键词命中即视为命中模板
Description string `json:"description,omitempty"`
// Topology 声明模板的拓扑(Q2;空 = standard 图行为)。
// RunOptions.Topology 优先于本字段。
Topology string `json:"topology,omitempty"`
Agents []RoleSpec `json:"agents,omitempty"` // 默认编制(引用已注册角色或内联角色)
Steps []StepSpec `json:"steps"`
Template string `json:"template,omitempty"` // 交付物骨架模板(Markdown)
Agents []RoleSpec `json:"agents,omitempty"` // 默认编制(引用已注册角色或内联角色)
Steps []StepSpec `json:"steps"`
Template string `json:"template,omitempty"` // 交付物骨架模板(Markdown)
}
// PlanningMode 规划模式。
@@ -118,47 +115,6 @@ type StepSpec struct {
Skills []string `json:"skills,omitempty"`
// MinScore 质检总分下限。0 = 不额外设门槛,只看 Checker.Passed。
MinScore int `json:"min_score,omitempty"`
// Loop 非空 = 循环步(Q2 loop 拓扑):完成后条件不满足且预算未尽时
// 重置为 pending 再武装(图不允许环,循环由引擎再武装实现)。
Loop *LoopSpec `json:"loop,omitempty"`
// LoopRuns 已再武装次数(引擎维护,随计划持久化)。
LoopRuns int `json:"loop_runs,omitempty"`
// Branches 非空 = 路由步(Q2 router 拓扑):完成后按黑板字段判定,
// 未选中分支的目标步骤置 skipped(skipped=依赖已满足,join 步照常推进)。
Branches []Branch `json:"branches,omitempty"`
// Handoff 非空 = 完成即把最终答案所有权移交给该角色(Q2 handoff 原语)。
Handoff string `json:"handoff,omitempty"`
// Brief 编译期任务指令(Q3 编译器):非空时渲染进 TASK.md 的
// 「任务指令」节,位于标题/产出之后、上下文表之前。图步的富文本任务书
// 载体(此前只有 leader 委派有 briefing)。
Brief string `json:"brief,omitempty"`
}
// LoopSpec 是循环步的预算与停机条件(Q2)。
type LoopSpec struct {
// MaxIterations 再武装上限(必须 >0;触顶即停,带 loop_exhausted 事件)。
MaxIterations int `json:"max_iterations"`
// UntilField 停机判据的黑板字段名;空 = 只按 MaxIterations 迭代。
UntilField string `json:"until_field,omitempty"`
// UntilEquals 停机值:Fields[UntilField] == UntilEquals 时停。
UntilEquals string `json:"until_equals,omitempty"`
// Body 与本步一起再武装的其他步骤 ID(循环体;如 evaluator-optimizer
// 的评估步)。空 = 只再武装本步。
Body []string `json:"body,omitempty"`
}
// Branch 是路由步的一条分支(Q2)。When 按声明序取首个命中。
type Branch struct {
When BranchCond `json:"when"`
// Then 是本分支保留的步骤 ID(其余分支目标置 skipped)。
Then []string `json:"then"`
}
// BranchCond 是分支判据:黑板字段等值/不等值。
type BranchCond struct {
Field string `json:"field"`
Equals string `json:"equals,omitempty"`
NotEquals string `json:"not_equals,omitempty"`
}
// IsCritical 报告步骤是否关键(nil 视为关键)。
@@ -296,21 +252,12 @@ const (
RunDegraded RunStatus = "degraded"
RunFailed RunStatus = "failed"
RunCancelled RunStatus = "cancelled"
// RunWaitingReconciliation F05:recovery 期间无法判定步骤结果(无 trusted
// terminal record、文件存在性与 record 冲突等);非交互模式下记录该状态
// 而非永久挂起。交互模式下挂起(合成 HITL 门),与既有 HITL 通道同款语义。
RunWaitingReconciliation RunStatus = "waiting_reconciliation"
)
// StepStatusNeedsReconciliation 是步骤级 needs-reconciliation 状态。
// 仅供 recovery 使用;runStep 不在成功路径写入。
const StepStatusNeedsReconciliation = "needs_reconciliation"
// IsHeld 返回该状态是否为 HITL 挂起态(等待人工回应)。
func (s RunStatus) IsHeld() bool {
return s == RunAwaitingClarification || s == RunAwaitingConfirmation ||
s == RunWaitingHuman || s == RunQualityReview ||
s == RunWaitingReconciliation
s == RunWaitingHuman || s == RunQualityReview
}
// Terminal 报告该状态是否为终态。
-34
View File
@@ -78,10 +78,6 @@ type ProcessEvent struct {
}
// ExecResult 是一次步骤执行的终态。
//
// 语义契约(F05/U3b):Success=true 才是经过验证的成功;仅在交付物齐全且
// ExecutionID 复用前提下成立。仅凭已物化的文件存在不能把失败翻成成功。
// 后端可以选择性填写以下可选字段;缺省 = 旧的读取行为。
type ExecResult struct {
Success bool `json:"success"`
Patches map[string][]byte `json:"patches"`
@@ -90,36 +86,6 @@ type ExecResult struct {
Retryable bool `json:"retryable,omitempty"`
PromptTokens int `json:"prompt_tokens,omitempty"`
CompletionTokens int `json:"completion_tokens,omitempty"`
// Canceled 为 true 时表示执行是被请求/中断终止的,不是业务失败。
// F05/KTD4:取消结果不应被 retry 改判为可重试;这是用户/系统显式意图。
Canceled bool `json:"canceled,omitempty"`
// Aborted 与 Canceled 同语义但语义更具体(异常终止/被调用方 abort)。
Aborted bool `json:"aborted,omitempty"`
// SideEffects 报告执行是否可能产生过外部动作。空值 = "possible"(旧行为)。
// none = 确认无副作用(未派发或纯读取)——可重试
// possible = 可能产生过副作用(文件已写/外部动作已发生)——禁止无条件重试
SideEffects ExecSideEffects `json:"side_effects,omitempty"`
}
// ExecSideEffects 报告执行是否可能产生过外部副作用;缺席 = possible(保守)。
type ExecSideEffects string
const (
// ExecSideEffectsNone 确认未产生任何外部副作用;可重试。
ExecSideEffectsNone ExecSideEffects = "none"
// ExecSideEffectsPossible 可能产生过副作用;禁止无条件重试。
ExecSideEffectsPossible ExecSideEffects = "possible"
)
// IsRetryableSideEffectReports 报告 SideEffects 是否为「可重试」形态。
// 默认 possible 视为不可重试(保守):调用方必须显式声明 none 才放开重试。
func (r *ExecResult) IsRetryableSideEffectReports() bool {
return r != nil && r.SideEffects == ExecSideEffectsNone
}
// IsCanceled 报告结果是否被取消/中止(不是业务失败)。
func (r *ExecResult) IsCanceled() bool {
return r != nil && (r.Canceled || r.Aborted)
}
// StubExecutor 是离线桩,测试与未接模型时使用。
-12
View File
@@ -2,7 +2,6 @@ package squad
import (
"context"
"encoding/json"
"errors"
"os"
"path/filepath"
@@ -163,17 +162,6 @@ func TestInterruptedRunningStepStaysHeld(t *testing.T) {
if err := st.save(); err != nil {
t.Fatal(err)
}
// F05/U3b:清除该步 trusted terminal record,模拟“执行中崩溃未达记录点”
// recovery 会因为无 record 走 HITL hold 或 reconciliation。
terminals := loadStepTerminalsForWorkDir(res.WorkDir)
if terminals != nil {
stepID := st.Plan.Workflow.Steps[0].ID
if _, ok := terminals[stepID]; ok {
delete(terminals, stepID)
data, _ := json.Marshal(terminals)
_ = os.WriteFile(filepath.Join(res.WorkDir, "step_terminals.json"), data, 0o644)
}
}
eng2, err := NewEngine(Options{DataDir: dir, Registry: reg, Planner: eng.opts.Planner, Backends: backends, Sink: NopSink{}})
if err != nil {
t.Fatal(err)
-366
View File
@@ -1,366 +0,0 @@
package squad
import (
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"sync"
"time"
)
// review.go — review 拓扑驱动(Q2 WP3,验收二)。
// 与 backend internal/runtime/review.go 的 runReview 等价:
// 并行 N finder(semaphore 3)→ 宽松 JSON 解析(首 `[` 末 `]`,丢空 issue)
// → 按 (location,issue) 去重、上限 10 → 每条独立 verifier(尾行
// VERDICT: PASS/FAIL/PARTIAL)→ 只留 PASS(fail-closed)→ severity 稳定排序
// → 报告恒带「已丢弃 N 条未验证」。解析/去重/判定/排序/文案与 backend 同一
// 格式串(计划 §一.5:以报告字节形态为等价判据)。
//
// squad 侧接线:finder = 计划步骤(各自的 findings.json 为目标产物,经
// runOneStep 走完整工作区/事件/HITL 机制);verifier = 驱动内按 verify 角色
// 直接 Execute 的核实调用(对应 backend 的 spawn(verifyProfileID,…)),
// 每次核实落盘 reviews/verify_NN/ 留痕。
func init() {
_ = RegisterTopologyDriver(TopologyReview)
}
// reviewFinding 与 backend reviewFinding 同构(JSON 键一致)。
type reviewFinding struct {
Location string `json:"location"`
Severity string `json:"severity"`
Issue string `json:"issue"`
Evidence string `json:"evidence"`
}
// reviewVerbatimTask 是核实调用的任务文案(与 backend runReview 同串)。
const reviewVerbatimTask = "独立核实这条问题是否成立。材料如下:\n%s\n\n问题:%s\n只在结尾给出一行 VERDICT: PASS、FAIL 或 PARTIAL。"
// parseFindings 宽松解析:首 `[` 末 `]`,丢空 issue(backend 同款)。
func parseFindings(text string) []reviewFinding {
start := strings.Index(text, "[")
end := strings.LastIndex(text, "]")
if start < 0 || end <= start {
return nil
}
var out []reviewFinding
if err := json.Unmarshal([]byte(text[start:end+1]), &out); err != nil {
return nil
}
var kept []reviewFinding
for _, f := range out {
if strings.TrimSpace(f.Issue) == "" {
continue
}
kept = append(kept, f)
}
return kept
}
// dedupeFindings 按 (location,issue) 去重,上限 limit(backend 同款)。
func dedupeFindings(groups [][]reviewFinding, limit int) []reviewFinding {
seen := map[string]bool{}
var out []reviewFinding
for _, group := range groups {
for _, f := range group {
key := strings.TrimSpace(f.Location) + "\n" + strings.TrimSpace(f.Issue)
if seen[key] {
continue
}
seen[key] = true
out = append(out, f)
if len(out) >= limit {
return out
}
}
}
return out
}
// reviewVerdict 尾行 VERDICT 判定(backend 同款:PASS/FAIL/PARTIAL,
// 解析不出 = 空串 = 不通过)。
func reviewVerdict(text string) string {
lines := strings.Split(text, "\n")
for i := len(lines) - 1; i >= 0; i-- {
line := strings.TrimSpace(lines[i])
if line == "" || !strings.HasPrefix(strings.ToUpper(line), "VERDICT:") {
continue
}
v := strings.TrimSpace(line[len("VERDICT:"):])
v = strings.ToUpper(v)
switch {
case strings.HasPrefix(v, "PASS"):
return "PASS"
case strings.HasPrefix(v, "FAIL"):
return "FAIL"
case strings.HasPrefix(v, "PARTIAL"):
return "PARTIAL"
default:
return ""
}
}
return ""
}
// severityRank 稳定排序键(backend 同款)。
func severityRank(s string) int {
switch strings.ToLower(strings.TrimSpace(s)) {
case "critical":
return 0
case "high":
return 1
case "medium":
return 2
case "low":
return 3
default:
return 4
}
}
// reviewParallel semaphore-3 并行(backend parallel 同款)。
func reviewParallel(n int, fn func(i int)) {
if n <= 0 {
return
}
sem := make(chan struct{}, 3)
var wg sync.WaitGroup
for i := 0; i < n; i++ {
wg.Add(1)
go func(i int) {
defer wg.Done()
sem <- struct{}{}
defer func() { <-sem }()
fn(i)
}(i)
}
wg.Wait()
}
// runReviewDriver review 拓扑入口。finder 阶段复用计划步骤(可挂起可恢复:
// 重入时已完成步骤不重跑,findings.json 从各自子工作区读取)。
func (e *SquadEngine) runReviewDriver(ctx context.Context, st *RunState) (*RunResult, error) {
drv := &flowDriver{opts: e.deps}
steps := st.Plan.Workflow.Steps
// verify 角色先行解析(fail-fast:缺角色不浪费 finder 轮次)。
verifyRoleName := orDefault(st.Meta.Metadata["review_verify_role"], "verifier")
verifyRole, ok := findAgent(st.Plan.Squad.Agents, verifyRoleName)
if !ok {
if r, exists := e.deps.Registry.Get(verifyRoleName); exists {
verifyRole, ok = r, true
}
}
if !ok {
return e.driverFail(st, fmt.Sprintf("review: verify 角色 %q 不在小队内(fail-closed)", verifyRoleName)), nil
}
verifyBackend, _, rerr := e.deps.Backends.Resolve(verifyRole, st.Meta.Backend)
if rerr != nil {
return e.driverFail(st, "review: verify 后端解析失败: "+rerr.Error()), nil
}
// 1) finder 阶段:先全组过门(任一要挂起则整组不执行,与 advance 并行组
// 同款语义),再 semaphore-3 并行执行。
var finderIdx []int
for i := range steps {
if steps[i].Status == "pending" || steps[i].Status == "running" {
finderIdx = append(finderIdx, i)
}
}
for _, idx := range finderIdx {
out, gate, err := drv.gateBeforeRun(ctx, st, idx)
if err != nil {
return nil, err
}
if gate != nil {
if out == nil {
out = heldResult(st, gate)
}
return out, nil
}
if out != nil {
return out, nil
}
}
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("review:%d 个 finder 并行找问题", len(finderIdx))})
var holdGate *HitlGate
var holdOut *RunResult
var fatal *RunResult
finderFailed := 0
var fmu sync.Mutex
reviewParallel(len(finderIdx), func(k int) {
idx := finderIdx[k]
out, gate, err := drv.runOneStep(ctx, st, idx)
fmu.Lock()
defer fmu.Unlock()
if err != nil {
if fatal == nil {
fatal = &RunResult{RunID: st.Meta.ID, Status: RunFailed, Plan: planPtr(st),
Error: err.Error(), WorkDir: st.Meta.WorkDir}
}
return
}
if gate != nil && holdGate == nil {
holdGate = gate
holdOut = out
return
}
if out != nil && out.Status == RunFailed && fatal == nil {
fatal = out // 关键 finder 失败:fail-closed 传播
return
}
if st.Plan.Workflow.Steps[idx].Status == "failed" {
finderFailed++ // 非关键 finder 失败:宽容(backend spawn err 同款),收口降级
}
})
if fatal != nil {
return fatal, nil
}
if holdGate != nil {
if holdOut == nil {
holdOut = heldResult(st, holdGate)
}
return holdOut, nil
}
// 2) 收集各 finder 的 findings.json(宽松解析;缺文件/坏 JSON = 该 finder
// 零发现,与 backend 同款)。
steps = st.Plan.Workflow.Steps
groups := make([][]reviewFinding, 0, len(steps))
for i := range steps {
if steps[i].Status != "completed" {
continue
}
subDir := filepath.Join(st.Meta.WorkDir, filepath.FromSlash(steps[i].SubWorkspace))
data, err := os.ReadFile(filepath.Join(subDir, "findings.json"))
if err != nil {
continue
}
groups = append(groups, parseFindings(string(data)))
}
unique := dedupeFindings(groups, 10)
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("review:去重后 %d 条,逐条独立核实", len(unique))})
// 3) 逐条 verify(semaphore-3 并行;fail-closed:核实调用失败/无判定 = 丢弃)。
target := reviewTargetMaterial(st)
kept := make([]reviewFinding, len(unique))
pass := make([]bool, len(unique))
reviewParallel(len(unique), func(i int) {
f := unique[i]
body, _ := json.Marshal(f)
task := fmt.Sprintf(reviewVerbatimTask, target, body)
vDir := filepath.Join(st.Meta.WorkDir, "reviews", fmt.Sprintf("verify_%02d", i+1))
if err := os.MkdirAll(vDir, 0o755); err != nil {
return
}
instructions := ""
if e.deps.Workspaces != nil {
instructions = e.deps.Workspaces.ResolveInstructions(verifyRole)
}
res, err := verifyBackend.Execute(ctx, ExecRequest{
WorkDir: vDir,
Prompt: task,
Instructions: instructions,
Targets: []string{"verdict.md"},
Timeout: e.deps.StepTimeout,
SessionScope: st.Meta.ID + "/verify_" + fmt.Sprintf("%02d", i+1),
})
if err != nil || res == nil {
return
}
text := string(res.Patches["verdict.md"]) + "\n" + res.Logs
if data, rerr2 := os.ReadFile(filepath.Join(vDir, "verdict.md")); rerr2 == nil {
text = string(data) + "\n" + text
}
if reviewVerdict(text) == "PASS" {
kept[i] = f
pass[i] = true
}
})
var verified []reviewFinding
for i, ok := range pass {
if ok {
verified = append(verified, kept[i])
}
}
// 4) severity 稳定排序 + 等价报告(backend 同格式串)。
sort.SliceStable(verified, func(i, j int) bool {
return severityRank(verified[i].Severity) < severityRank(verified[j].Severity)
})
dropped := len(unique) - len(verified)
var b strings.Builder
if len(verified) == 0 {
b.WriteString("没有验证通过的问题。\n")
}
for _, f := range verified {
fmt.Fprintf(&b, "- [%s] %s:%s\n 证据:%s\n",
orDefault(f.Severity, "medium"), orDefault(f.Location, "未定位"), f.Issue, f.Evidence)
}
fmt.Fprintf(&b, "已丢弃 %d 条未验证\n", dropped)
report := b.String()
// 5) 收口:报告落盘(reviews/report.md + output.md 交付物约定),
// finder 有失败则降级(诚实信号),否则完成。
reviewsDir := filepath.Join(st.Meta.WorkDir, "reviews")
_ = os.MkdirAll(reviewsDir, 0o755)
_ = os.WriteFile(filepath.Join(reviewsDir, "report.md"), []byte(report), 0o644)
_ = os.WriteFile(filepath.Join(st.Meta.WorkDir, "output.md"), []byte(report), 0o644)
st.mu.Lock()
if st.BB.Fields == nil {
st.BB.Fields = map[string]string{}
}
st.BB.Fields["review_verified"] = fmt.Sprintf("%d", len(verified))
st.BB.Fields["review_dropped"] = fmt.Sprintf("%d", dropped)
wf := st.Workflow()
status := RunCompleted
if finderFailed > 0 {
status = RunDegraded
}
wf.Status = string(status)
st.setWorkflow(wf)
st.Meta.Status = string(status)
now := time.Now()
st.Meta.CompletedAt = &now
_ = st.save()
st.mu.Unlock()
summary := fmt.Sprintf("review:保留 %d 条 / 丢弃 %d 条未验证", len(verified), dropped)
if finderFailed > 0 {
summary += fmt.Sprintf("(%d 个 finder 失败,降级)", finderFailed)
}
drv.emit(st, Event{Type: EvPhase, Text: summary})
return &RunResult{RunID: st.Meta.ID, Status: status, Plan: planPtr(st),
Deliverable: "output.md", Summary: summary, WorkDir: st.Meta.WorkDir}, nil
}
// reviewTargetMaterial 取被评审材料:元数据 review_target 优先,
// 其次运行目标(context/goal.md)。
func reviewTargetMaterial(st *RunState) string {
if v := strings.TrimSpace(st.Meta.Metadata["review_target"]); v != "" {
return v
}
if data, err := os.ReadFile(filepath.Join(st.Meta.WorkDir, "context", "goal.md")); err == nil {
return string(data)
}
return ""
}
// driverFail 驱动级 fail-closed 收口(与 leaderFail 同款语义)。
func (e *SquadEngine) driverFail(st *RunState, reason string) *RunResult {
now := time.Now()
st.mu.Lock()
st.Meta.Status = string(RunFailed)
st.Meta.CompletedAt = &now
wf := st.Workflow()
wf.Status = "failed"
st.setWorkflow(wf)
_ = st.save()
st.mu.Unlock()
(&flowDriver{opts: e.deps}).emit(st, Event{Type: EvPhase, Text: reason})
return &RunResult{RunID: st.Meta.ID, Status: RunFailed, Plan: planPtr(st),
Error: reason, WorkDir: st.Meta.WorkDir}
}
-18
View File
@@ -27,15 +27,6 @@ type RunState struct {
Clarifications []string `json:"clarifications,omitempty"`
// Steering 运行中人工补充指令(在下一步骤边界注入后清空)。
Steering []string `json:"steering,omitempty"`
// Mailbox 运行内点对点消息(Q2):随 RunState 持久化;只在步骤启动时
// 并入任务书,永不触碰 HITL 门。
Mailbox []MailMessage `json:"mailbox,omitempty"`
// Handoffs 所有权转移记录(Q2 handoff 原语):随 RunState 持久化;
// 目标角色的下一步骤一次性接收移交上下文,finalize 取链尾产出。
Handoffs []HandoffRecord `json:"handoffs,omitempty"`
// Board task_board 拓扑的队列状态(Q2):claim/lease/complete 三原语,
// 随 RunState 持久化;孤儿租约在驱动重入时再武装。
Board []BoardTask `json:"board,omitempty"`
// Usage 按角色累计的 token 用量。
Usage map[string]*Usage `json:"usage,omitempty"`
// Leader leader-delegation 模式的循环状态(workspace 内 leader.json 持久化)。
@@ -101,9 +92,6 @@ func (st *RunState) persist() error {
RepairBudgetRemaining: st.RepairBudgetRemaining,
RepairBudgetGranted: st.RepairBudgetGranted,
Clarifications: st.Clarifications,
Mailbox: st.Mailbox,
Handoffs: st.Handoffs,
Board: st.Board,
})
}
@@ -112,9 +100,6 @@ type diskRunState struct {
RepairBudgetRemaining int `json:"repair_budget_remaining,omitempty"`
RepairBudgetGranted int `json:"repair_budget_granted,omitempty"`
Clarifications []string `json:"clarifications,omitempty"`
Mailbox []MailMessage `json:"mailbox,omitempty"`
Handoffs []HandoffRecord `json:"handoffs,omitempty"`
Board []BoardTask `json:"board,omitempty"`
}
// Workflow 返回计划的编排清单(简洁访问器)。
@@ -169,9 +154,6 @@ func loadRunState(wsDir string) (*RunState, error) {
st.RepairBudgetRemaining = disk.RepairBudgetRemaining
st.RepairBudgetGranted = disk.RepairBudgetGranted
st.Clarifications = disk.Clarifications
st.Mailbox = disk.Mailbox
st.Handoffs = disk.Handoffs
st.Board = disk.Board
} else if !os.IsNotExist(err) {
return nil, err
}
-11
View File
@@ -109,17 +109,6 @@ type StepSnapshot struct {
ID string `json:"id"`
Status string `json:"status"`
AttemptID string `json:"attempt_id,omitempty"`
// F05/U3b:trusted terminal record;用于 recovery 时仅在「后端显式
// 声明 success」时把步骤恢复成 completed(即便目标文件缺失也照恢复),
// files 仍然记入 deliverables 做诊断。SideEffects 报告重放安全性:
// none → 可重试
// possible → 需 reconciliation(不禁 rerun;只允许显式 reconcile)
// Canceled/Aborted 为 true 时本步是取消/中止语义,不应被恢复成 completed。
Terminal string `json:"terminal,omitempty"`
// SideEffects 镜像 ExecResult.SideEffects;缺省 = possible(旧读取)。
SideEffects string `json:"side_effects,omitempty"`
Canceled bool `json:"canceled,omitempty"`
Aborted bool `json:"aborted,omitempty"`
}
// CheckpointMode 快照写盘档位(Q1 WP4 三档)。
-12
View File
@@ -110,9 +110,6 @@ func AssessStepFailure(sig StepFailureSignals) FailureAssessment {
lower := strings.ToLower(reason)
trace := ScanTraceText(sig.ExtraText + "\n" + ReadWorkDirTraces(sig.WorkDir))
missing := sig.TargetMissing || strings.Contains(lower, "missing target deliverable")
// F05/KTD4:explicit SideEffects=none 报告 = provably-not-dispatched。
// 缺则按 possible 对待(与旧语义一致)。这是 caller 自己传达的可重试信令。
provablyNotDispatched := sig.Result != nil && sig.Result.SideEffects == ExecSideEffectsNone
if sig.TargetExists {
return FailureAssessment{Class: FailurePermanent, Reason: "target-already-present: do not overwrite"}
}
@@ -138,15 +135,6 @@ func AssessStepFailure(sig StepFailureSignals) FailureAssessment {
if missing && trace.Settled && !provider {
return FailureAssessment{Class: FailureTransient, Reason: "settled-no-deliverable: " + compactReason(reason)}
}
// F05/U3b:SideEffects=none 失败原则上可重试(后端已声明未发生外部动作);
// 跨越该含义补一条有界重试通路,并覆盖纯获取后失败但文件已拼起的边界。
if provablyNotDispatched && !provider {
kind := "provably-not-dispatched"
if missing {
kind = "provably-not-dispatched-missing-target"
}
return FailureAssessment{Class: FailureTransient, Reason: kind + ": " + compactReason(reason)}
}
if missing {
return FailureAssessment{Class: FailurePermanent, Reason: "permanent-missing: " + compactReason(reason)}
}
-308
View File
@@ -1,308 +0,0 @@
package squad
import (
"context"
"fmt"
"strings"
"time"
)
// taskboard.go — task_board 拓扑驱动(Q2 WP4)。
// 形态:计划步骤 = 板上任务(Needs = 依赖门);执行语义是队列化的
// claim/lease/complete 三原语——工作者认领任务(带租约时限)、执行、完成;
// 进程死亡留下的孤儿租约(claimed 且租约过期)在驱动重入时再武装回 open
// (Attempts 保留,超限由步骤级重试护栏兜底)。全部任务收口后走标准
// finalize(交付物/质检/降级判定与图拓扑同一收口面)。
// 挂起(HITL)安全:claimed 且步骤未完的任务在重入时续跑,不重复认领。
func init() {
_ = RegisterTopologyDriver(TopologyTaskBoard)
}
// DefaultTaskLeaseSeconds 任务租约缺省时限(秒)。
const DefaultTaskLeaseSeconds = 600
// boardSkipReason 依赖门无法满足(上游 failed/skipped)时的跳过原因。
const boardSkipReason = "task_board: 依赖未满足(上游失败或跳过)"
// BoardTask 是任务板上一条任务的队列状态。
type BoardTask struct {
ID string `json:"id"`
Status string `json:"status"` // open / claimed / done / failed / skipped
ClaimedBy string `json:"claimed_by,omitempty"`
// LeaseExpires 认领租约到期时刻;过期未 complete = 孤儿租约,重入再武装。
LeaseExpires time.Time `json:"lease_expires,omitempty"`
// Attempts 认领次数(孤儿再武装累加;执行重试由步骤级护栏负责)。
Attempts int `json:"attempts,omitempty"`
}
// runTaskBoardDriver task_board 拓扑入口(幂等可恢复)。
func (e *SquadEngine) runTaskBoardDriver(ctx context.Context, st *RunState) (*RunResult, error) {
drv := &flowDriver{opts: e.deps}
e.initBoard(st)
e.rearmOrphanLeases(st)
leaseTTL := DefaultTaskLeaseSeconds
if v := st.Meta.Metadata["task_board_lease_seconds"]; v != "" {
if n := parseIntDefault(v, DefaultTaskLeaseSeconds); n > 0 {
leaseTTL = n
}
}
for {
idx, held := e.boardHeldTask(st)
if !held {
var ok bool
idx, ok = e.boardClaimNext(st, leaseTTL)
if !ok {
// 无可认领:把依赖已死(上游 failed/skipped)的 open 任务级联
// 置 skipped;再无变化则收口。
if !e.boardSkipDeadlocked(st) {
break
}
continue
}
}
out, gate, err := e.boardRunTask(ctx, drv, st, idx)
if err != nil {
return nil, err
}
if gate != nil {
if out == nil {
out = heldResult(st, gate)
}
return out, nil
}
if out != nil { // 关键任务失败:fail-closed 传播(failStep 已置运行失败)
return out, nil
}
e.boardSettleTask(st, idx)
}
return e.boardFinish(ctx, drv, st)
}
// initBoard 首次进入时从计划步骤派生任务板(恢复重入直读持久化状态)。
func (e *SquadEngine) initBoard(st *RunState) {
st.mu.Lock()
defer st.mu.Unlock()
if len(st.Board) > 0 {
return
}
for _, s := range st.Plan.Workflow.Steps {
status := "open"
switch s.Status {
case "completed":
status = "done"
case "failed":
status = "failed"
case "skipped":
status = "skipped"
}
st.Board = append(st.Board, BoardTask{ID: s.ID, Status: status})
}
_ = st.save()
}
// rearmOrphanLeases 孤儿租约再武装:claimed 且租约过期 → open(进程死亡
// 恢复路径;Attempts 保留作观测)。
func (e *SquadEngine) rearmOrphanLeases(st *RunState) {
now := time.Now()
st.mu.Lock()
var rearmed []string
for i := range st.Board {
t := &st.Board[i]
if t.Status == "claimed" && !t.LeaseExpires.IsZero() && t.LeaseExpires.Before(now) {
t.Status = "open"
t.ClaimedBy = ""
rearmed = append(rearmed, t.ID)
}
}
changed := len(rearmed) > 0
if changed {
_ = st.save()
}
st.mu.Unlock()
if changed {
(&flowDriver{opts: e.deps}).emit(st, Event{Type: EvPhase,
Text: fmt.Sprintf("task_board:孤儿租约再武装 %s", strings.Join(rearmed, ","))})
}
}
// boardHeldTask 返回 claimed 且步骤未完的任务(HITL 挂起/中断重入的续跑点)。
func (e *SquadEngine) boardHeldTask(st *RunState) (int, bool) {
for ti := range st.Board {
t := &st.Board[ti]
if t.Status != "claimed" {
continue
}
if idx, s := e.boardStep(st, t.ID); idx >= 0 && (s.Status == "pending" || s.Status == "running") {
return idx, true
}
}
return -1, false
}
// boardClaimNext 认领下一个可执行任务(open 且依赖门全 done),返回步骤下标。
func (e *SquadEngine) boardClaimNext(st *RunState, leaseTTL int) (int, bool) {
st.mu.Lock()
defer st.mu.Unlock()
for ti := range st.Board {
t := &st.Board[ti]
if t.Status != "open" {
continue
}
if !e.boardDepsDoneLocked(st, t.ID) {
continue
}
idx, s := e.boardStepLocked(st, t.ID)
if idx < 0 {
continue
}
t.Status = "claimed"
t.ClaimedBy = s.Role
t.Attempts++
t.LeaseExpires = time.Now().Add(time.Duration(leaseTTL) * time.Second)
_ = st.save()
(&flowDriver{opts: e.deps}).emit(st, Event{Type: EvPhase, StepID: t.ID, Role: s.Role,
Text: fmt.Sprintf("task_board:%s 认领 %s(租约 %ds,第 %d 次)", s.Role, t.ID, leaseTTL, t.Attempts)})
return idx, true
}
return -1, false
}
// boardSkipDeadlocked 把依赖已死(上游 failed/skipped)的 open 任务级联置
// skipped;返回是否有变化(有则继续循环级联)。
func (e *SquadEngine) boardSkipDeadlocked(st *RunState) bool {
st.mu.Lock()
changed := false
for ti := range st.Board {
t := &st.Board[ti]
if t.Status != "open" {
continue
}
if e.boardDepsDeadLocked(st, t.ID) {
t.Status = "skipped"
if idx, s := e.boardStepLocked(st, t.ID); idx >= 0 {
s.Status = "skipped"
s.Error = boardSkipReason
st.Plan.Workflow.Steps[idx] = *s
}
changed = true
}
}
if changed {
_ = st.save()
}
st.mu.Unlock()
return changed
}
// boardRunTask 执行已认领任务:过门 → runOneStep。
func (e *SquadEngine) boardRunTask(ctx context.Context, drv *flowDriver, st *RunState, idx int) (*RunResult, *HitlGate, error) {
out, gate, err := drv.gateBeforeRun(ctx, st, idx)
if err != nil || gate != nil || out != nil {
return out, gate, err
}
return drv.runOneStep(ctx, st, idx)
}
// boardSettleTask 任务结算:步骤 completed → done;failed(非关键降级)→ failed。
func (e *SquadEngine) boardSettleTask(st *RunState, idx int) {
step := st.Plan.Workflow.Steps[idx]
status := "done"
if step.Status == "failed" {
status = "failed"
}
st.mu.Lock()
for i := range st.Board {
if st.Board[i].ID == step.ID {
st.Board[i].Status = status
st.Board[i].LeaseExpires = time.Time{}
}
}
_ = st.save()
st.mu.Unlock()
(&flowDriver{opts: e.deps}).emit(st, Event{Type: EvPhase, StepID: step.ID, Role: step.Role,
Text: fmt.Sprintf("task_board:%s → %s", step.ID, status)})
}
// boardFinish 全部任务收口后走标准 finalize(交付物/质检/降级与图拓扑同面)。
// 仍有 open/claimed 任务 = 依赖不可满足,fail-closed 不静默收口。
func (e *SquadEngine) boardFinish(ctx context.Context, drv *flowDriver, st *RunState) (*RunResult, error) {
done, total := 0, len(st.Board)
for _, t := range st.Board {
switch t.Status {
case "done":
done++
case "open", "claimed":
return e.driverFail(st, fmt.Sprintf("task_board: 任务 %s 无法收口(依赖不可满足)", t.ID)), nil
}
}
drv.emit(st, Event{Type: EvPhase, Text: fmt.Sprintf("task_board:收口(done %d/%d)", done, total)})
out, gate, err := drv.finalize(ctx, st)
if err != nil {
return nil, err
}
if gate != nil {
return heldResult(st, gate), nil
}
return out, nil
}
// boardStep 按任务 ID 找步骤(只读副本)。
func (e *SquadEngine) boardStep(st *RunState, id string) (int, *StepSpec) {
st.mu.Lock()
defer st.mu.Unlock()
return e.boardStepLocked(st, id)
}
// boardStepLocked 按任务 ID 找步骤(调用方持锁)。返回下标与副本指针。
func (e *SquadEngine) boardStepLocked(st *RunState, id string) (int, *StepSpec) {
for i := range st.Plan.Workflow.Steps {
if st.Plan.Workflow.Steps[i].ID == id {
s := st.Plan.Workflow.Steps[i]
return i, &s
}
}
return -1, nil
}
// boardDepsDoneLocked 依赖门:Needs 全部 done(调用方持锁)。
func (e *SquadEngine) boardDepsDoneLocked(st *RunState, id string) bool {
needs := e.boardNeedsLocked(st, id)
for _, dep := range needs {
found := false
for i := range st.Board {
if st.Board[i].ID == dep {
found = true
if st.Board[i].Status != "done" {
return false
}
}
}
if !found {
return false // 依赖不在板上 = fail-closed 不认领
}
}
return true
}
// boardDepsDeadLocked 依赖已死:任一 Need 为 failed/skipped(级联跳过依据)。
func (e *SquadEngine) boardDepsDeadLocked(st *RunState, id string) bool {
for _, dep := range e.boardNeedsLocked(st, id) {
for i := range st.Board {
if st.Board[i].ID == dep && (st.Board[i].Status == "failed" || st.Board[i].Status == "skipped") {
return true
}
}
}
return false
}
func (e *SquadEngine) boardNeedsLocked(st *RunState, id string) []string {
for i := range st.Plan.Workflow.Steps {
if st.Plan.Workflow.Steps[i].ID == id {
return st.Plan.Workflow.Steps[i].Needs
}
}
return nil
}
-130
View File
@@ -1,130 +0,0 @@
package squad
import "fmt"
// topology.go — 拓扑一等化(Q2):内置拓扑名注册表。
// 拓扑不新造执行面:graph 类编译为 Steps 图(Q1 机制),leader 走既有
// Mode 委派循环,driver 类由引擎按名分发(review/group_chat/task_board),
// primitive 类是跨拓扑原语(handoff/mailbox),不可单独作为运行拓扑。
// 未知名与不可运行Kind一律 fail-closed。
// 内置拓扑名(completion doc Q2 清单的 12 种)。
const (
TopologySequential = "sequential"
TopologyParallel = "parallel"
TopologyLoop = "loop"
TopologyRouter = "router"
TopologyLeader = "leader"
TopologyHandoff = "handoff"
TopologyGroupChat = "group_chat"
TopologyReview = "review"
TopologyEvaluatorOptimizer = "evaluator_optimizer"
TopologyLongRunning = "long_running"
TopologyTaskBoard = "task_board"
TopologyMailbox = "mailbox"
)
// TopologyKind 是拓扑的执行形态。
type TopologyKind string
const (
// TopologyGraph 编译为 Steps 图,由 flowDriver.advance 执行。
TopologyGraph TopologyKind = "graph"
// TopologyMode 走既有 Mode 分支(leader 委派循环)。
TopologyMode TopologyKind = "mode"
// TopologyDriver 由引擎按名分发到专用驱动。
TopologyDriver TopologyKind = "driver"
// TopologyPrimitive 是跨拓扑原语,不可单独运行。
TopologyPrimitive TopologyKind = "primitive"
)
// TopologySpec 是一个内置拓扑的注册项。
type TopologySpec struct {
Name string
Kind TopologyKind
}
// builtinTopologies 是 12 种内置拓扑的注册表(唯一权威清单)。
var builtinTopologies = []TopologySpec{
{Name: TopologySequential, Kind: TopologyGraph},
{Name: TopologyParallel, Kind: TopologyGraph},
{Name: TopologyLoop, Kind: TopologyGraph},
{Name: TopologyRouter, Kind: TopologyGraph},
{Name: TopologyLeader, Kind: TopologyMode},
{Name: TopologyHandoff, Kind: TopologyPrimitive},
{Name: TopologyGroupChat, Kind: TopologyDriver},
{Name: TopologyReview, Kind: TopologyDriver},
{Name: TopologyEvaluatorOptimizer, Kind: TopologyGraph},
{Name: TopologyLongRunning, Kind: TopologyGraph},
{Name: TopologyTaskBoard, Kind: TopologyDriver},
{Name: TopologyMailbox, Kind: TopologyPrimitive},
}
// BuiltinTopologies 返回内置拓扑清单(只读副本)。
func BuiltinTopologies() []TopologySpec {
out := make([]TopologySpec, len(builtinTopologies))
copy(out, builtinTopologies)
return out
}
// LookupTopology 按名查注册项。
func LookupTopology(name string) (TopologySpec, bool) {
for _, t := range builtinTopologies {
if t.Name == name {
return t, true
}
}
return TopologySpec{}, false
}
// registeredDrivers 是已接线的 driver 拓扑(WP 增量逐个点亮;未点亮 = fail-closed)。
var registeredDrivers = map[string]bool{}
// RegisterTopologyDriver 由驱动实现方在 init/装配时点亮一个 driver 拓扑。
func RegisterTopologyDriver(name string) error {
spec, ok := LookupTopology(name)
if !ok {
return fmt.Errorf("topology: 未注册的拓扑名 %q", name)
}
if spec.Kind != TopologyDriver {
return fmt.Errorf("topology: %q 不是 driver 类(kind=%s)", name, spec.Kind)
}
registeredDrivers[name] = true
return nil
}
// checkTopology 校验一次运行的有效拓扑名,返回其 Kind。
// 空名 = 未声明(standard 图行为,兼容既有调用方)。
// 未注册名 / primitive 单跑 / driver 未点亮都 fail-closed。
func checkTopology(name string) (TopologyKind, error) {
if name == "" {
return TopologyGraph, nil
}
spec, ok := LookupTopology(name)
if !ok {
return "", fmt.Errorf("topology: 未知拓扑 %q(内置清单:%s)", name, topologyNames())
}
switch spec.Kind {
case TopologyGraph, TopologyMode:
return spec.Kind, nil
case TopologyPrimitive:
return "", fmt.Errorf("topology: %q 是跨拓扑原语,不可单独作为运行拓扑", name)
case TopologyDriver:
if !registeredDrivers[name] {
return "", fmt.Errorf("topology: %q 驱动未注册(fail-closed)", name)
}
return spec.Kind, nil
}
return "", fmt.Errorf("topology: %q kind 非法", name)
}
func topologyNames() string {
s := ""
for i, t := range builtinTopologies {
if i > 0 {
s += ", "
}
s += t.Name
}
return s
}
-435
View File
@@ -1,435 +0,0 @@
package squad
import (
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strings"
"sync"
"testing"
"time"
)
// topology_conformance_test.go — Q2 验收一的机器证据:每种拓扑一个
// 脚本化后端的 conformance(零模型、零网络)。
// ---- 脚本化夹具 ----
// collectSink 收集事件流供断言。
type collectSink struct {
mu sync.Mutex
events []Event
}
func (c *collectSink) Emit(ev Event) {
c.mu.Lock()
defer c.mu.Unlock()
c.events = append(c.events, ev)
}
func (c *collectSink) snapshot() []Event {
c.mu.Lock()
defer c.mu.Unlock()
return append([]Event(nil), c.events...)
}
func (c *collectSink) countText(sub string) int {
n := 0
for _, ev := range c.snapshot() {
if strings.Contains(ev.Text, sub) {
n++
}
}
return n
}
// iterBackend 按「步骤子目录 × 第几次执行」回放内容(循环/评估拓扑需要
// 逐轮不同的 fields.json)。
type iterBackend struct {
mu sync.Mutex
calls map[string]int
content func(stepKey string, iter int, target string) []byte
delay time.Duration
}
func (b *iterBackend) Name() string { return "iter" }
func (b *iterBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
if b.delay > 0 {
time.Sleep(b.delay)
}
b.mu.Lock()
b.calls[key]++
iter := b.calls[key]
b.mu.Unlock()
patches := map[string][]byte{}
for _, t := range req.Targets {
var data []byte
if b.content != nil {
data = b.content(key, iter, t)
}
if data == nil {
data = []byte(goodReport)
}
out := filepath.Join(req.WorkDir, t)
_ = os.MkdirAll(filepath.Dir(out), 0o755)
if err := os.WriteFile(out, data, 0o644); err != nil {
return nil, err
}
patches[t] = data
}
return &ExecResult{Success: true, Patches: patches}, nil
}
func (b *iterBackend) totalCalls() int {
b.mu.Lock()
defer b.mu.Unlock()
n := 0
for _, v := range b.calls {
n += v
}
return n
}
func newTopologyEngine(t *testing.T, planner Planner, be Executor, sink ProgressSink) *SquadEngine {
t.Helper()
dir := t.TempDir()
reg := NewRoleRegistry()
for _, spec := range []RoleSpec{
{Role: "researcher", Name: "调研", Backend: "iter"},
{Role: "writer", Name: "撰写", Backend: "iter"},
{Role: "reviewer", Name: "审核", Backend: "iter"},
} {
if err := reg.Register(spec); err != nil {
t.Fatal(err)
}
}
backends := NewBackendResolver()
backends.RegisterInstance("iter", be)
if sink == nil {
sink = NopSink{}
}
engine, err := NewEngine(Options{
DataDir: dir, Registry: reg, Planner: planner, Backends: backends, Sink: sink,
})
if err != nil {
t.Fatal(err)
}
return engine
}
func fieldsJSON(kv map[string]string) []byte {
b, _ := json.Marshal(kv)
return b
}
// ---- sequential / parallel:既有图语义 + 拓扑名受理 ----
func TestTopologyConformance_sequential(t *testing.T) {
be := &iterBackend{calls: map[string]int{}}
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"notes.md"}},
StepSpec{ID: "s2", Role: "writer", Title: "二", Targets: []string{"output.md"}},
), be, sink)
res, err := engine.Run(context.Background(), Goal{Text: "顺序任务"}, RunOptions{Topology: TopologySequential})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
if be.totalCalls() != 2 {
t.Fatalf("执行次数 = %d", be.totalCalls())
}
if sink.countText("拓扑 sequential") != 1 {
t.Fatal("缺拓扑受理事件")
}
}
func TestTopologyConformance_parallel(t *testing.T) {
be := &iterBackend{calls: map[string]int{}}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "并行甲", Parallel: true, Targets: []string{"a.md"}},
StepSpec{ID: "s2", Role: "writer", Title: "并行乙", Parallel: true, Targets: []string{"b.md"}},
StepSpec{ID: "s3", Role: "reviewer", Title: "汇合", Targets: []string{"output.md"}},
), be, nil)
res, err := engine.Run(context.Background(), Goal{Text: "并行任务"}, RunOptions{Topology: TopologyParallel})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted || be.totalCalls() != 3 {
t.Fatalf("status = %s calls = %d err = %v", res.Status, be.totalCalls(), res.Error)
}
}
// ---- loop:条件停机 + 预算触顶 ----
func TestTopologyConformance_loopUntilField(t *testing.T) {
// 第 1-2 轮 done=no,第 3 轮 done=yes → 恰执行 3 次。
be := &iterBackend{calls: map[string]int{}, content: func(_ string, iter int, target string) []byte {
if target == "fields.json" {
if iter >= 3 {
return fieldsJSON(map[string]string{"done": "yes"})
}
return fieldsJSON(map[string]string{"done": "no"})
}
return nil
}}
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "循环体", Targets: []string{"output.md", "fields.json"},
Loop: &LoopSpec{MaxIterations: 5, UntilField: "done", UntilEquals: "yes"}},
), be, sink)
res, err := engine.Run(context.Background(), Goal{Text: "循环任务"}, RunOptions{Topology: TopologyLoop})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
if be.totalCalls() != 3 {
t.Fatalf("应在条件满足时停机(3 次),实际 %d", be.totalCalls())
}
if sink.countText("再武装") != 2 {
t.Fatalf("再武装事件应 2 次:%d", sink.countText("再武装"))
}
// 计划里的 LoopRuns 持久化为 2。
if len(res.Plan.Steps) != 1 || res.Plan.Steps[0].LoopRuns != 2 {
t.Fatalf("LoopRuns = %+v", res.Plan.Steps)
}
}
func TestTopologyConformance_loopBudgetExhausted(t *testing.T) {
// 条件永不满足:恰执行 MaxIterations 次后触顶(非失败)。
be := &iterBackend{calls: map[string]int{}, content: func(_ string, _ int, target string) []byte {
if target == "fields.json" {
return fieldsJSON(map[string]string{"done": "no"})
}
return nil
}}
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "循环体", Targets: []string{"output.md", "fields.json"},
Loop: &LoopSpec{MaxIterations: 3, UntilField: "done", UntilEquals: "yes"}},
), be, sink)
res, err := engine.Run(context.Background(), Goal{Text: "循环任务"}, RunOptions{Topology: TopologyLoop})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("触顶应是完成而非失败:%s %v", res.Status, res.Error)
}
if be.totalCalls() != 3 {
t.Fatalf("恰 3 次,实际 %d", be.totalCalls())
}
if sink.countText("loop_exhausted") != 1 {
t.Fatal("缺 loop_exhausted 事件")
}
}
// ---- router:分支选中/落选跳过/无命中 fail-closed ----
func routerSteps() []StepSpec {
return []StepSpec{
{ID: "r1", Role: "researcher", Title: "路由", Targets: []string{"output.md", "fields.json"},
Branches: []Branch{
{When: BranchCond{Field: "route", Equals: "fast"}, Then: []string{"fast"}},
{When: BranchCond{Field: "route", NotEquals: "fast"}, Then: []string{"slow"}},
}},
{ID: "fast", Role: "writer", Title: "快线", Needs: []string{"r1"}, Targets: []string{"output.md"}},
{ID: "slow", Role: "writer", Title: "慢线", Needs: []string{"r1"}, Targets: []string{"output.md"}},
}
}
func TestTopologyConformance_routerSelectsBranch(t *testing.T) {
be := &iterBackend{calls: map[string]int{}, content: func(_ string, _ int, target string) []byte {
if target == "fields.json" {
return fieldsJSON(map[string]string{"route": "fast"})
}
return nil
}}
engine := newTopologyEngine(t, mockScriptPlanner(routerSteps()...), be, nil)
res, err := engine.Run(context.Background(), Goal{Text: "路由任务"}, RunOptions{Topology: TopologyRouter})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("分支落选是预期路径,不得降级/失败:%s %v", res.Status, res.Error)
}
byID := map[string]StepSpec{}
for _, s := range res.Plan.Steps {
byID[s.ID] = s
}
if byID["fast"].Status != "completed" {
t.Fatalf("fast = %s", byID["fast"].Status)
}
if byID["slow"].Status != "skipped" || byID["slow"].Error != routerSkipReason {
t.Fatalf("slow = %s %q", byID["slow"].Status, byID["slow"].Error)
}
}
func TestTopologyConformance_routerNoMatchFailsClosed(t *testing.T) {
be := &iterBackend{calls: map[string]int{}, content: func(_ string, _ int, target string) []byte {
if target == "fields.json" {
return fieldsJSON(map[string]string{"route": ""}) // 两条分支都不命中
}
return nil
}}
steps := routerSteps()
// 去掉 NotEquals 兜底分支,制造无命中。
steps[0].Branches = []Branch{{When: BranchCond{Field: "route", Equals: "fast"}, Then: []string{"fast"}}}
engine := newTopologyEngine(t, mockScriptPlanner(steps...), be, nil)
res, err := engine.Run(context.Background(), Goal{Text: "路由任务"}, RunOptions{Topology: TopologyRouter})
if err != nil {
t.Fatal(err)
}
if res.Status != RunFailed || !strings.Contains(res.Error, "无分支命中") {
t.Fatalf("无命中必须 fail-closed:%s %v", res.Status, res.Error)
}
}
// ---- evaluator-optimizer:draft→eval 循环复合,收敛即停 ----
func TestTopologyConformance_evaluatorOptimizer(t *testing.T) {
// eval 第 1-2 轮 verdict=fail,第 3 轮 pass;draft 随 body 再武装。
be := &iterBackend{calls: map[string]int{}, content: func(key string, iter int, target string) []byte {
if target == "fields.json" {
if iter >= 3 {
return fieldsJSON(map[string]string{"verdict": "pass"})
}
return fieldsJSON(map[string]string{"verdict": "fail"})
}
if target == "verdict.md" {
return []byte(fmt.Sprintf("评审第 %d 轮\n\n%s", iter, goodReport))
}
return nil
}}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "draft", Role: "writer", Title: "起草", Targets: []string{"output.md"}},
StepSpec{ID: "eval", Role: "reviewer", Title: "评审", Targets: []string{"verdict.md", "fields.json"},
Loop: &LoopSpec{MaxIterations: 4, UntilField: "verdict", UntilEquals: "pass", Body: []string{"draft"}}},
), be, nil)
res, err := engine.Run(context.Background(), Goal{Text: "起草并评审"}, RunOptions{Topology: TopologyEvaluatorOptimizer})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
byID := map[string]StepSpec{}
for _, s := range res.Plan.Steps {
byID[s.ID] = s
}
if byID["eval"].LoopRuns != 2 {
t.Fatalf("eval 应再武装 2 轮:%+v", byID["eval"])
}
// draft 3 次 + eval 3 次。
if be.totalCalls() != 6 {
t.Fatalf("总执行次数 = %d,期望 6", be.totalCalls())
}
}
// ---- long-running:截止时刻 → 未完步骤 skipped、降级收口 ----
func TestTopologyConformance_longRunningDeadline(t *testing.T) {
// 时序鲁棒设计:每步 300ms、截止 +500ms——装配耗时不影响断言核心:
// s1 必完成(首个 superstep 在截止前开跑),s3 必被跳过(第三个
// superstep 边界必超期),收口必为 degraded。s2 完成与否取决于装配
// 耗时,不做断言。
be := &iterBackend{calls: map[string]int{}, delay: 300 * time.Millisecond}
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"notes.md"}},
StepSpec{ID: "s2", Role: "writer", Title: "二", Targets: []string{"output.md"}},
StepSpec{ID: "s3", Role: "reviewer", Title: "三", Targets: []string{"output.md"}},
), be, sink)
res, err := engine.Run(context.Background(), Goal{Text: "长任务"}, RunOptions{
Topology: TopologyLongRunning,
Deadline: time.Now().Add(500 * time.Millisecond),
})
if err != nil {
t.Fatal(err)
}
if res.Status != RunDegraded {
t.Fatalf("截止后应降级收口:%s %v", res.Status, res.Error)
}
byID := map[string]StepSpec{}
for _, s := range res.Plan.Steps {
byID[s.ID] = s
}
if byID["s1"].Status != "completed" {
t.Fatalf("s1 = %s", byID["s1"].Status)
}
if byID["s3"].Status != "skipped" || byID["s3"].Error != "deadline exceeded" {
t.Fatalf("s3 = %s %q", byID["s3"].Status, byID["s3"].Error)
}
if sink.countText("截止时刻") != 1 {
t.Fatal("缺截止事件")
}
}
// ---- 拓扑校验 fail-closed ----
func TestTopologyValidationFailsClosed(t *testing.T) {
be := &iterBackend{calls: map[string]int{}}
cases := []struct {
name string
topo string
wantErr string
}{
{"未注册名", "bogus_topology", "未知拓扑"},
{"primitive 单跑", TopologyMailbox, "跨拓扑原语"},
{"primitive 单跑 handoff", TopologyHandoff, "跨拓扑原语"},
// review/group_chat(WP3)与 task_board(WP4)驱动均已点亮;
// 12/12 受理面由 TestTopologyConformance_allTwelve 汇总钉住。
}
for _, tc := range cases {
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"output.md"}},
), be, nil)
res, err := engine.Run(context.Background(), Goal{Text: "x"}, RunOptions{Topology: tc.topo})
if err != nil {
t.Fatalf("%s:err = %v", tc.name, err)
}
if res.Status != RunFailed || !strings.Contains(res.Error, tc.wantErr) {
t.Fatalf("%s:%s %q(期望含 %q)", tc.name, res.Status, res.Error, tc.wantErr)
}
}
}
// leader 拓扑名映射到既有 Mode 委派循环(本测只钉「受理且映射」,
// leader 行为 conformance 在 leader_test.go / WP2 增强)。
func TestTopologyLeaderMapsToMode(t *testing.T) {
spec, ok := LookupTopology(TopologyLeader)
if !ok || spec.Kind != TopologyMode {
t.Fatalf("leader 注册形态:%+v %v", spec, ok)
}
if _, err := checkTopology(TopologyLeader); err != nil {
t.Fatalf("leader 拓扑应可受理:%v", err)
}
}
// 12 种内置拓扑全部注册且 Kind 合法(清单完整性)。
func TestBuiltinTopologiesComplete(t *testing.T) {
want := map[string]TopologyKind{
TopologySequential: TopologyGraph, TopologyParallel: TopologyGraph,
TopologyLoop: TopologyGraph, TopologyRouter: TopologyGraph,
TopologyLeader: TopologyMode, TopologyHandoff: TopologyPrimitive,
TopologyGroupChat: TopologyDriver, TopologyReview: TopologyDriver,
TopologyEvaluatorOptimizer: TopologyGraph, TopologyLongRunning: TopologyGraph,
TopologyTaskBoard: TopologyDriver, TopologyMailbox: TopologyPrimitive,
}
got := BuiltinTopologies()
if len(got) != len(want) {
t.Fatalf("注册数 = %d,期望 %d", len(got), len(want))
}
for _, spec := range got {
if k, ok := want[spec.Name]; !ok || k != spec.Kind {
t.Fatalf("拓扑 %s kind = %s(期望 %s)", spec.Name, spec.Kind, k)
}
}
}
+8 -357
View File
@@ -3,7 +3,6 @@ package squad
import (
"bytes"
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
@@ -30,15 +29,6 @@ func (d *flowDriver) advance(ctx context.Context, st *RunState) (res *RunResult,
d.emit(st, Event{Type: EvPhase, Text: "开始执行工作流"})
superNo := 0
// 运行级截止(Q2 long_running):superstep 边界检查,超期未完步骤置
// skipped 并降级收口;零值/不可解析 = 不设限。
var runDeadline time.Time
if v := st.Meta.Metadata["deadline"]; v != "" {
// RFC3339Nano 同时接受秒级与纳秒级两种写法。
if t, terr := time.Parse(time.RFC3339Nano, v); terr == nil {
runDeadline = t
}
}
cpw := newCheckpointWriter(CheckpointMode(st.Meta.Metadata["checkpoint_mode"]), st.storeOr())
// 推进退出前 flush:async 落完、on_exit 写最终快照(Q1 WP4 三档的出口语义)。
var lastGraph *graph
@@ -53,19 +43,6 @@ func (d *flowDriver) advance(ctx context.Context, st *RunState) (res *RunResult,
}
}()
for {
if !runDeadline.IsZero() && time.Now().After(runDeadline) {
d.emit(st, Event{Type: EvPhase, Text: "运行截止时刻已到,未完步骤按 skipped 收口"})
st.mu.Lock()
for i := range st.Plan.Workflow.Steps {
if st.Plan.Workflow.Steps[i].Status == "pending" || st.Plan.Workflow.Steps[i].Status == "running" {
st.Plan.Workflow.Steps[i].Status = "skipped"
st.Plan.Workflow.Steps[i].Error = "deadline exceeded"
}
}
_ = st.save()
st.mu.Unlock()
return d.finalize(ctx, st)
}
g, gerr := compileGraph(st.Plan.Workflow.Steps)
if gerr != nil {
wf2 := st.Workflow()
@@ -163,21 +140,10 @@ func (d *flowDriver) advance(ctx context.Context, st *RunState) (res *RunResult,
}
// snapshotOf 组装一个 superstep 边界快照:序号、图结构指纹与全量步骤状态。
// terminal side-effect evidence 由 recordStepTerminal 在步骤进入 completed 时写入
// step_terminals.json;本处把已记录的 terminal 数据并入 StepSnapshot,保证
// checkpoint 也带同样证据(F05:信任落盘记录)。
func snapshotOf(superNo int, g *graph, steps []StepSpec) Checkpoint {
cp := Checkpoint{Superstep: superNo, At: time.Now(), GraphHash: g.hash()}
// checkpoint 路径拿不到当前 RunState 引用(cpw 在 defer flush 时调用过),
// 同时也仅有顺序式调用传递上下文不便;所以这里走「按 ID 检查同索引」对齐
// 替代——checkpoint 产生时 step.Status 已为终态(completed),因此 record 同步
// 已写入;StepSnapshot.Terminal 就用 step.Status 推导(F05 唯一信任源)。
for _, s := range steps {
snap := StepSnapshot{ID: s.ID, Status: s.Status, AttemptID: s.AttemptID}
if s.Status == "completed" {
snap.Terminal = "completed"
}
cp.StepStates = append(cp.StepStates, snap)
cp.StepStates = append(cp.StepStates, StepSnapshot{ID: s.ID, Status: s.Status, AttemptID: s.AttemptID})
}
return cp
}
@@ -231,7 +197,6 @@ func (d *flowDriver) runParallel(ctx context.Context, st *RunState, idxs []int)
var wg sync.WaitGroup
var mu sync.Mutex
failedCritical := -1
var firstFail *RunResult
var gate *HitlGate
for _, idx := range idxs {
wg.Add(1)
@@ -246,11 +211,6 @@ func (d *flowDriver) runParallel(ctx context.Context, st *RunState, idxs []int)
}
if (out != nil && out.Status == RunFailed) || err != nil {
cancel()
// 保留首个带具体错误的失败结果(如 router 无命中);
// failStep 的通用格式只在没有更具体结果时兜底。
if out != nil && out.Status == RunFailed && firstFail == nil {
firstFail = out
}
if st.Plan.Workflow.Steps[idx].IsCritical() && failedCritical < 0 {
failedCritical = idx
}
@@ -261,9 +221,6 @@ func (d *flowDriver) runParallel(ctx context.Context, st *RunState, idxs []int)
if gate != nil {
return heldResult(st, gate), gate, nil
}
if firstFail != nil {
return firstFail, nil, nil
}
if failedCritical >= 0 {
return d.failStep(ctx, st, failedCritical)
}
@@ -291,16 +248,6 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
return d.failStep(ctx, st, idx)
}
}
// handoff 原语 fail-closed(Q2):目标角色必须可解析,启动前拒绝。
if step.Handoff != "" {
if _, ok := findAgent(st.Plan.Squad.Agents, step.Handoff); !ok {
if _, exists := d.opts.Registry.Get(step.Handoff); !exists {
step.Status, step.Error = "failed", "handoff: 未知目标角色 "+step.Handoff
st.setStep(idx, step)
return d.failStep(ctx, st, idx)
}
}
}
subDir := filepath.Join(st.Meta.WorkDir, filepath.FromSlash(orDefault(step.SubWorkspace, fmt.Sprintf("tasks/%02d_%s", idx+1, step.Role))))
if err := os.MkdirAll(subDir, 0o755); err != nil {
return nil, nil, err
@@ -331,18 +278,6 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
}
prompt := readFileOr(filepath.Join(subDir, "TASK.md"), step.Title)
prompt = st.injectSteering(prompt)
// 邮箱投递(Q2):本步骤启动时把发给该角色(含广播)的未读消息并入
// 任务书;只走 prompt 面,永不触碰 HITL 门(验收三构造性保证)。
st.mu.Lock()
mail := takeMailFor(st, step.Role)
handoff := takeHandoffFor(st, step.Role)
if len(mail) > 0 || handoff != nil {
_ = st.save()
}
st.mu.Unlock()
prompt += formatMailSection(mail)
// handoff 原语(Q2):目标角色的步骤接收过滤历史(只带移交方主产出)。
prompt += formatHandoffSection(handoff)
instructions := readFileOr(filepath.Join(subDir, "AGENTS.md"), d.opts.Workspaces.ResolveInstructions(role))
var backend Executor
@@ -371,9 +306,6 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
}
var result *ExecResult
var err error
// F05/U3b(KTD4):ExecutionID 在一次逻辑执行内稳定。重试层共享同一 ID
// + 同一 Deadline,便于下游做幂等键 + 收据对齐。第一层 attempt 用稳定 ID;
// 重试层沿用 step.AttemptID(首次进入时已生成、保持不变)。
for attempt := 1; attempt <= MaxTransientStepInvocations; attempt++ {
reqPrompt := prompt
if attempt > 1 {
@@ -399,10 +331,9 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
// RoleSpec v2 贯通:工具白名单 / 技能 / 标识(原为死字段或缺失)。
ToolAllowlist: role.Tools,
Skills: firstNonEmptySlice(step.Skills, role.Skills),
// F05:ExecutionID 复用 step.AttemptID(首层 attempt 时已生成)——重试层不再换新 ID。
SessionScope: st.Meta.ID + "/" + step.ID,
ExecutionID: step.AttemptID,
Budget: stepBudget,
SessionScope: st.Meta.ID + "/" + step.ID,
ExecutionID: step.AttemptID,
Budget: stepBudget,
}
if step.IntentID != "" {
// 系统功能步:不经智能体,由 IntentRunner 直接执行;缺席即 fail-closed。
@@ -422,59 +353,18 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
} else {
result, err = backend.Execute(ctx, req)
}
// F05/KTD4:先验证执行结果本身,不让「文件已存在」翻成 Success。
// (1) (nil,nil) 视作稳定失败,不允许 panic 也不允许误判成功;
// (2) Success=true 仅在 result 显式声明时才成立;
// (3) 已取消/中止的结果不进入重试通路(不是业务失败,且重试会重复已发生的取消语义)。
if err != nil && result == nil {
// (nil,nil) 在 Go 是不可能态(要么 err、要么 result);保险起见仍按稳定失败。
step.Status = "failed"
step.Error = "executor returned no result and no error (stable failure)"
break
}
if result == nil {
step.Status = "failed"
step.Error = "executor returned nil result"
break
}
if result.IsCanceled() {
// F05/KTD4:取消不是业务失败,不重试(按 attempt==MaxTransientStepInvocations 跳出)。
step.Status = "failed"
if result.ErrorReason != "" {
step.Error = "executor canceled: " + result.ErrorReason
} else {
step.Error = "executor canceled"
}
break
}
if err == nil && result.Success {
// 交付物物化:后端返回 patches 但未写盘时补写。F05:仅当 result.Success
// 已验证且文件未准备时才需要物化;只有 patches 内容才能落盘。
if len(result.Patches) > 0 {
_, _ = MaterializeTargets(subDir, targets, result.Patches)
}
break
}
// 交付物物化:后端返回 patches 但未写盘时补写。F05:仅当 result.Success 已
// 被后端显式声明时物化才允许 break;旧逻辑会让
// `err==nil && len(Patches)>0 && materialize_ok` 翻成 Success=true —— 修掉。
// 交付物物化:后端返回 patches 但未写盘时补写。
if err == nil && len(result.Patches) > 0 {
if _, merr := MaterializeTargets(subDir, targets, result.Patches); merr == nil {
if result.Success && allTargetsPresent(subDir, targets) {
if allTargetsPresent(subDir, targets) {
result.Success = true
break
}
}
}
// F05/KTD4:副作用可能存在的失败禁止自动重试(重试会重复外部动作)。
// 仅 SideEffects=none 或纯读取后的失败保持有界重试。
if !result.IsRetryableSideEffectReports() && err != nil {
step.Status = "failed"
step.Error = orDefault(result.ErrorReason, err.Error())
if result.ErrorReason != "" {
step.Error = result.ErrorReason
}
break
}
assessment := AssessStepFailure(StepFailureSignals{
Err: err, Result: result, WorkDir: subDir,
ExtraText: fmt.Sprintf("step=%s backend=%s", step.ID, backendName),
@@ -520,9 +410,6 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
step.Status = "completed"
appendLog(subDir, fmt.Sprintf("[%s] backend=%s duration=%dms targets=%v\n", time.Now().Format(time.RFC3339), backendName, step.DurationMs, targets))
// F05/U3b:记录 trusted terminal state(用于 recoverInterrupted 判定)。
// 由「正在收口的 completed」流写入;recovery 期间不会回填(防伪)。
d.recordStepTerminal(st, step, result)
// 状态回填 + 黑板合并 + 落盘同一临界区:并行步骤的共享状态变更串行化,
// 防止 marshal 与写回竞争、临时文件互相踩踏把保存失败误判为步骤失败。
@@ -536,154 +423,9 @@ func (d *flowDriver) runOneStep(ctx context.Context, st *RunState, idx int) (*Ru
}
d.emit(st, Event{Type: EvStepCompleted, StepID: step.ID, Role: step.Role, Text: step.Title,
Data: marshalJSON(map[string]any{"duration_ms": step.DurationMs, "targets": targets})})
// handoff 原语(Q2):完成即移交最终答案所有权——记录 + 主产出快照,
// 供目标角色下一步骤(过滤历史)与 finalize(链尾产出)消费。
if step.Handoff != "" {
d.recordHandoff(st, step, subDir, targets)
}
// 循环步再武装(Q2 loop):停机条件不满足且预算未尽 → 本步与 loop.body
// 一起重置为 pending;触顶发 loop_exhausted 事件后按完成继续。
if step.Loop != nil {
if d.loopShouldRearm(st, step) {
if out, g2, err2 := d.rearmLoop(ctx, st, idx, step); out != nil || g2 != nil || err2 != nil {
return out, g2, err2
}
return nil, nil, nil
}
if step.Loop.UntilField != "" && step.LoopRuns+1 >= step.Loop.MaxIterations {
d.emit(st, Event{Type: EvPhase, StepID: step.ID, Text: fmt.Sprintf("loop_exhausted:%s 达 %d 轮上限,停机条件未满足", step.ID, step.Loop.MaxIterations)})
}
}
// 路由步分支裁决(Q2 router):首个命中的分支保留,其余分支目标置
// skipped;无分支命中 fail-closed 成失败运行。
if len(step.Branches) > 0 {
return d.applyBranches(ctx, st, idx, step)
}
return nil, nil, nil
}
// loopShouldRearm 判定循环步是否再武装:停机条件(黑板字段等值)满足或
// 预算用尽则停。字段判据读的是本轮 mergeStepArtifacts 之后的黑板。
func (d *flowDriver) loopShouldRearm(st *RunState, step StepSpec) bool {
// MaxIterations 是总迭代上限(含首跑):已跑 LoopRuns+1 次。
if step.LoopRuns+1 >= step.Loop.MaxIterations {
return false
}
if step.Loop.UntilField != "" {
st.mu.Lock()
v := st.BB.Fields[step.Loop.UntilField]
st.mu.Unlock()
if v == step.Loop.UntilEquals {
return false
}
}
return true
}
// rearmLoop 把循环步与 loop.body 一起重置为 pending(同一临界区内落盘)。
func (d *flowDriver) rearmLoop(_ context.Context, st *RunState, idx int, step StepSpec) (*RunResult, *HitlGate, error) {
st.mu.Lock()
step.LoopRuns++
step.Status = "pending"
step.Error = ""
st.Plan.Workflow.Steps[idx] = step
for _, bodyID := range step.Loop.Body {
for j := range st.Plan.Workflow.Steps {
if st.Plan.Workflow.Steps[j].ID == bodyID && st.Plan.Workflow.Steps[j].Status == "completed" {
st.Plan.Workflow.Steps[j].Status = "pending"
st.Plan.Workflow.Steps[j].Error = ""
}
}
}
err := st.save()
round := step.LoopRuns
st.mu.Unlock()
if err != nil {
return nil, nil, err
}
d.emit(st, Event{Type: EvPhase, StepID: step.ID, Text: fmt.Sprintf("loop 第 %d 轮再武装:%s", round+1, step.ID)})
return nil, nil, nil
}
// applyBranches 裁决路由步分支:When 按声明序取首个命中;未选中分支的
// pending 目标置 skipped(skipped=依赖已满足,join 步照常推进)。
func (d *flowDriver) applyBranches(_ context.Context, st *RunState, _ int, step StepSpec) (*RunResult, *HitlGate, error) {
st.mu.Lock()
fields := map[string]string{}
for k, v := range st.BB.Fields {
fields[k] = v
}
st.mu.Unlock()
var selected *Branch
for i := range step.Branches {
if branchMatches(fields, step.Branches[i].When) {
selected = &step.Branches[i]
break
}
}
if selected == nil {
wf := st.Workflow()
wf.Status = "failed"
st.setWorkflow(wf)
_ = st.save()
return &RunResult{RunID: st.Meta.ID, Status: RunFailed, Plan: planPtr(st),
Error: fmt.Sprintf("router: 步骤 %s 无分支命中(fail-closed)", step.ID), WorkDir: st.Meta.WorkDir}, nil, nil
}
keep := map[string]bool{}
for _, t := range selected.Then {
keep[t] = true
}
skipped := 0
st.mu.Lock()
for j := range st.Plan.Workflow.Steps {
sj := &st.Plan.Workflow.Steps[j]
if sj.ID == step.ID || keep[sj.ID] || sj.Status != "pending" {
continue
}
for _, br := range step.Branches {
inBranch := false
for _, t := range br.Then {
if t == sj.ID {
inBranch = true
break
}
}
if inBranch {
sj.Status = "skipped"
sj.Error = routerSkipReason
skipped++
break
}
}
}
err := st.save()
st.mu.Unlock()
if err != nil {
return nil, nil, err
}
d.emit(st, Event{Type: EvPhase, StepID: step.ID,
Text: fmt.Sprintf("router %s 选中分支 %v(跳过 %d 步)", step.ID, selected.Then, skipped)})
return nil, nil, nil
}
// routerSkipReason 是分支落选的 skipped 标记(finalize 的降级豁免凭据)。
const routerSkipReason = "router: 分支未选中"
// branchMatches 判定分支条件:Equals 非空须相等,NotEquals 非空须不等;
// 字段未设时按零值 "" 参与比较(compileGraph 已保证两者至少其一非空)。
func branchMatches(fields map[string]string, c BranchCond) bool {
v := fields[c.Field]
if c.Equals != "" && v != c.Equals {
return false
}
if c.NotEquals != "" && v == c.NotEquals {
return false
}
return true
}
// failStep 按关键性处理失败步骤:关键 → 运行失败;非关键 → 标记后继续(返回 nil 让循环推进)。
func (d *flowDriver) failStep(ctx context.Context, st *RunState, idx int) (*RunResult, *HitlGate, error) {
st.mu.Lock()
@@ -845,30 +587,17 @@ func (d *flowDriver) finalize(ctx context.Context, st *RunState) (*RunResult, *H
wf := st.Workflow()
degraded := false
for _, s := range wf.Steps {
if s.Status == "failed" {
degraded = true
}
// router 分支落选是预期路径,不算降级(Q2)。
if s.Status == "skipped" && s.Error != routerSkipReason {
if s.Status == "failed" || s.Status == "skipped" {
degraded = true
}
}
// 汇总交付物:最后一个 completed 步骤的主产出 → output.md。
// handoff 链尾优先(Q2):有所有权移交时,交付物取链尾角色的最后一个
// completed 步骤产出(最终答案所有权在链尾),无则该角色无完成步骤时回落。
var srcStep *StepSpec
for i := range wf.Steps {
if wf.Steps[i].Status == "completed" {
srcStep = &wf.Steps[i]
}
}
if tail := handoffChainTail(st); tail != "" {
for i := range wf.Steps {
if wf.Steps[i].Status == "completed" && wf.Steps[i].Role == tail {
srcStep = &wf.Steps[i]
}
}
}
if srcStep == nil {
wf.Status = "failed"
st.setWorkflow(wf)
@@ -1099,84 +828,6 @@ func countStatus(st *RunState, status string) int {
return n
}
// recordStepTerminal 记一条「trusted terminal record」:在某步执行完成
// (仅 success 路径)时落地 step.Terminal + SideEffects + canceled/aborted。
// reconcile/path:如果 recovery 期间没有该记录,则按文件存在与否分流
// (见 engine.recoverInterrupted)。
//
// F05:record 与 read 路径严格同包;测试通过 squad/executor_result_contract_test.go
// 覆盖正向与逆向条件。
func (d *flowDriver) recordStepTerminal(st *RunState, step StepSpec, result *ExecResult) {
if st == nil || st.Meta.WorkDir == "" {
return
}
if step.ID == "" {
return
}
t := stepTerminalRecord{Terminal: "completed", At: time.Now(), StepID: step.ID, AttemptID: step.AttemptID}
if result != nil {
t.SideEffects = string(result.SideEffects)
t.Canceled = result.Canceled
t.Aborted = result.Aborted
}
st.mu.Lock()
defer st.mu.Unlock()
terminals := readStepTerminalsLocked(st)
terminals[step.ID] = t
data, err := json.Marshal(terminals)
if err != nil {
return
}
_ = os.WriteFile(filepath.Join(st.Meta.WorkDir, "step_terminals.json"), data, 0o644)
}
// readStepTerminalsLocked 读取已落盘的 step_terminals.json(调用方须持锁或私有化)。
// 失败(含文件不存在)返回空 map。
func readStepTerminalsLocked(st *RunState) map[string]stepTerminalRecord {
out := map[string]stepTerminalRecord{}
if st == nil || st.Meta.WorkDir == "" {
return out
}
data, err := os.ReadFile(filepath.Join(st.Meta.WorkDir, "step_terminals.json"))
if err != nil || len(data) == 0 {
return out
}
var stored map[string]stepTerminalRecord
if err := json.Unmarshal(data, &stored); err != nil {
return out
}
for k, v := range stored {
out[k] = v
}
return out
}
// loadStepTerminalsForWorkDir 公开暴露的 record 读取(recovery 使用)。
func loadStepTerminalsForWorkDir(wsDir string) map[string]stepTerminalRecord {
if wsDir == "" {
return map[string]stepTerminalRecord{}
}
data, err := os.ReadFile(filepath.Join(wsDir, "step_terminals.json"))
if err != nil || len(data) == 0 {
return map[string]stepTerminalRecord{}
}
var stored map[string]stepTerminalRecord
if err := json.Unmarshal(data, &stored); err != nil {
return map[string]stepTerminalRecord{}
}
return stored
}
type stepTerminalRecord struct {
StepID string `json:"step_id"`
AttemptID string `json:"attempt_id"`
Terminal string `json:"terminal"` // completed (唯一允许值;failure 走 step.Status)
SideEffects string `json:"side_effects,omitempty"`
Canceled bool `json:"canceled,omitempty"`
Aborted bool `json:"aborted,omitempty"`
At time.Time `json:"at"`
}
func buildManifest(st *RunState, deliverable string, report QualityReport) Manifest {
files := map[string]string{}
_ = filepath.Walk(st.Meta.WorkDir, func(path string, info os.FileInfo, err error) error {
-7
View File
@@ -189,13 +189,6 @@ func (e *WorkspaceEngine) writeTaskFile(subDir string, step *StepSpec, role Role
fmt.Fprintf(&b, "- 角色:%s(%s)\n", role.Name, role.Role)
fmt.Fprintf(&b, "- 期望产出:%v\n\n", step.Targets)
// 编译期任务指令(Q3):编译器渲染好的富文本任务书,权威仅次于目标。
if strings.TrimSpace(step.Brief) != "" {
b.WriteString("## 任务指令\n\n")
b.WriteString(strings.TrimSpace(step.Brief))
b.WriteString("\n\n")
}
b.WriteString("## 任务上下文资源与权威等级(已快照到本目录,只引用本地路径)\n\n")
b.WriteString("| 资源路径 | 权威等级 | 用途说明 | 使用与引用指导 |\n|---|---|---|---|\n")
b.WriteString("| `context/goal.md` | **authoritative** | 运行目标 | 不可推翻 |\n")
-452
View File
@@ -1,452 +0,0 @@
package squad
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
"sync"
"testing"
"time"
)
// wp3_conformance_test.go — Q2 WP3 验收:review 拓扑与 backend runReview 等价
// (验收二:并行找问题、逐条验证、丢掉未验证)、handoff 原语(所有权转移 +
// 过滤历史 + finalize 链尾)、group_chat 驱动(轮转/主持人 + 预算停机)。
// ---- review:与 backend review_test.go 同款断言 ----
// reviewScriptBackend finder 目录回放 findings.json(第 3 个进入者放行,钉住
// 真并发);verify_* 目录按 prompt 内容回放判定(与 backend 夹具同文案)。
type reviewScriptBackend struct {
mu sync.Mutex
once sync.Once
entered int
verifyCalls int
release chan struct{}
}
func (b *reviewScriptBackend) Name() string { return "review-script" }
func (b *reviewScriptBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
if strings.HasPrefix(key, "verify_") {
b.mu.Lock()
b.verifyCalls++
b.mu.Unlock()
verdict := "看不出对错"
switch {
case strings.Contains(req.Prompt, "无来源"):
verdict = "核对原文确实没有来源。\nVERDICT: PASS"
case strings.Contains(req.Prompt, "错字"):
verdict = "核对后成立。\nVERDICT: PASS"
case strings.Contains(req.Prompt, "过期数据"):
verdict = "数据仍有效。\nVERDICT: FAIL"
}
return writeOne(req.WorkDir, "verdict.md", verdict), nil
}
// finder:三个必须同时在跑(backend review_test.go:16-33 同款门)。
b.mu.Lock()
b.entered++
n := b.entered
b.mu.Unlock()
if n == 3 {
b.once.Do(func() { close(b.release) })
}
select {
case <-b.release:
case <-time.After(time.Second):
return nil, fmt.Errorf("finders did not run together")
}
var findings string
switch key {
case "01_researcher":
findings = `[{"location":"第2段","severity":"high","issue":"无来源","evidence":"显然"},{"location":"第1段","severity":"low","issue":"错字","evidence":"的地"},{"location":"表1","severity":"medium","issue":"过期数据","evidence":"2020"}]`
case "02_writer":
findings = `[{"location":"第2段","severity":"high","issue":"无来源","evidence":"显然"},{"location":"附录","severity":"medium","issue":"数字不一致","evidence":"3 与 4"}]`
default:
findings = `[{"location":"结尾","severity":"low","issue":"没有结论","evidence":"最后一句"}]`
}
return writeOne(req.WorkDir, "findings.json", findings), nil
}
func writeOne(dir, name, content string) *ExecResult {
out := filepath.Join(dir, name)
_ = os.MkdirAll(filepath.Dir(out), 0o755)
_ = os.WriteFile(out, []byte(content), 0o644)
return &ExecResult{Success: true, Patches: map[string][]byte{name: []byte(content)}}
}
func TestTopologyConformance_review(t *testing.T) {
be := &reviewScriptBackend{release: make(chan struct{})}
sink := &collectSink{}
planner := mockScriptPlanner(
StepSpec{ID: "f1", Role: "researcher", Title: "评审一", Targets: []string{"findings.json"}},
StepSpec{ID: "f2", Role: "writer", Title: "评审二", Targets: []string{"findings.json"}},
StepSpec{ID: "f3", Role: "reviewer", Title: "评审三", Targets: []string{"findings.json"}},
)
planner.Agents = []RoleSpec{
{Role: "researcher", Name: "评审一", Backend: "review-script"},
{Role: "writer", Name: "评审二", Backend: "review-script"},
{Role: "reviewer", Name: "评审三", Backend: "review-script"},
{Role: "verifier", Name: "核实", Backend: "review-script"},
}
engine := newWP3Engine(t, planner, be, sink, []RoleSpec{
{Role: "researcher", Name: "评审一", Backend: "review-script"},
{Role: "writer", Name: "评审二", Backend: "review-script"},
{Role: "reviewer", Name: "评审三", Backend: "review-script"},
{Role: "verifier", Name: "核实", Backend: "review-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "评审材料正文"},
RunOptions{Topology: TopologyReview, ReviewTarget: "材料正文"})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
data, err := os.ReadFile(filepath.Join(res.WorkDir, "output.md"))
if err != nil {
t.Fatal(err)
}
out := string(data)
// 只留 PASS(fail-closed):无来源/错字保留;FAIL 与无判定丢弃。
if !strings.Contains(out, "无来源") || !strings.Contains(out, "错字") ||
strings.Contains(out, "数字不一致") || strings.Contains(out, "没有结论") ||
strings.Contains(out, "过期数据") {
t.Fatalf("filter = %s", out)
}
// 报告恒带丢弃计数(backend 同格式串)。
if !strings.Contains(out, "已丢弃 3 条未验证") {
t.Fatalf("dropped = %s", out)
}
// 去重后逐条验证:verify 调用数 = unique 数 = 5。
if be.verifyCalls != 5 {
t.Fatalf("verify calls = %d, want 5 after dedupe", be.verifyCalls)
}
// severity 稳定排序:high(无来源) 在 low(错字) 前。
if strings.Index(out, "无来源") > strings.Index(out, "错字") {
t.Fatalf("severity order: %s", out)
}
if sink.countText("review:3 个 finder 并行找问题") != 1 ||
sink.countText("review:去重后 5 条") != 1 {
t.Fatal("缺 review 阶段事件")
}
}
// verify 角色缺失 → fail-closed。
func TestReviewVerifyRoleMissingFailsClosed(t *testing.T) {
be := &reviewScriptBackend{release: make(chan struct{})}
planner := mockScriptPlanner(
StepSpec{ID: "f1", Role: "researcher", Title: "评审", Targets: []string{"findings.json"}},
)
engine := newWP3Engine(t, planner, be, NopSink{}, []RoleSpec{
{Role: "researcher", Name: "评审", Backend: "review-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "评审"},
RunOptions{Topology: TopologyReview})
if err != nil {
t.Fatal(err)
}
if res.Status != RunFailed || !strings.Contains(res.Error, "verify 角色") {
t.Fatalf("应 fail-closed:%s %q", res.Status, res.Error)
}
}
// ---- handoff 原语 ----
// handoffScriptBackend 记录 prompt 并按目录回放带标记的产出(≥50 字过最小质检)。
type handoffScriptBackend struct {
mu sync.Mutex
prompts map[string][]string
}
func (b *handoffScriptBackend) Name() string { return "handoff-script" }
func (b *handoffScriptBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
b.mu.Lock()
b.prompts[key] = append(b.prompts[key], req.Prompt)
b.mu.Unlock()
pad := "\n\n这是为了满足最小质检长度要求而补充的正文内容,超过五十个字符。"
var content string
switch key {
case "01_researcher":
content = "MARK_RESEARCHER 调研笔记。" + pad
case "02_writer":
content = "MARK_WRITER 终稿。" + pad
default:
content = "MARK_REVIEWER 评审意见。" + pad
}
name := "output.md"
if len(req.Targets) > 0 {
name = req.Targets[0]
}
return writeOne(req.WorkDir, name, content), nil
}
func TestTopologyConformance_handoff(t *testing.T) {
be := &handoffScriptBackend{prompts: map[string][]string{}}
sink := &collectSink{}
engine := newWP3Engine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "调研", Targets: []string{"notes.md"}, Handoff: "writer"},
StepSpec{ID: "s2", Role: "writer", Title: "成文", Targets: []string{"output.md"}, Needs: []string{"s1"}},
StepSpec{ID: "s3", Role: "reviewer", Title: "终审", Targets: []string{"output.md"}, Needs: []string{"s2"}},
), be, sink, []RoleSpec{
{Role: "researcher", Name: "调研", Backend: "handoff-script"},
{Role: "writer", Name: "撰写", Backend: "handoff-script"},
{Role: "reviewer", Name: "审核", Backend: "handoff-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "带移交的三步"}, RunOptions{})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
// ① 所有权转移记录持久化。
st, err := engine.loadRun(engine.runDir(res.RunID))
if err != nil {
t.Fatal(err)
}
if len(st.Handoffs) != 1 || st.Handoffs[0].FromRole != "researcher" || st.Handoffs[0].ToRole != "writer" {
t.Fatalf("Handoffs = %+v", st.Handoffs)
}
if !strings.Contains(st.Handoffs[0].Output, "MARK_RESEARCHER") {
t.Fatalf("移交产出快照缺失:%q", st.Handoffs[0].Output)
}
if sink.countText("handoff:researcher → writer") != 1 {
t.Fatal("缺所有权移交事件")
}
// ② 目标收过滤历史:writer 的任务书带移交上下文,reviewer 不带。
var writerPrompt, reviewerPrompt string
for _, p := range be.prompts["02_writer"] {
writerPrompt += p
}
for _, p := range be.prompts["03_reviewer"] {
reviewerPrompt += p
}
if !strings.Contains(writerPrompt, "移交上下文") || !strings.Contains(writerPrompt, "MARK_RESEARCHER") {
t.Fatalf("writer 未收到过滤历史:%q", writerPrompt)
}
if strings.Contains(reviewerPrompt, "移交上下文") {
t.Fatal("非目标角色不应收到移交上下文")
}
// ③ finalize 取链尾输出:交付物 = writer(链尾)产出,而非最后完成的 reviewer。
data, err := os.ReadFile(filepath.Join(res.WorkDir, "output.md"))
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(data), "MARK_WRITER") || strings.Contains(string(data), "MARK_REVIEWER") {
t.Fatalf("交付物应为链尾 writer 产出:%s", data)
}
}
// handoff 目标角色未知 → 步骤启动前 fail-closed。
func TestHandoffUnknownRoleFailsClosed(t *testing.T) {
be := &handoffScriptBackend{prompts: map[string][]string{}}
engine := newWP3Engine(t, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "调研", Handoff: "ghost"},
), be, NopSink{}, []RoleSpec{
{Role: "researcher", Name: "调研", Backend: "handoff-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "x"}, RunOptions{})
if err != nil {
t.Fatal(err)
}
if res.Status != RunFailed || !strings.Contains(res.Error, "handoff: 未知目标角色 ghost") {
t.Fatalf("应 fail-closed:%s %q", res.Status, res.Error)
}
}
// ---- group_chat 驱动 ----
// gcScriptBackend 按目录回放 message.md。
type gcScriptBackend struct {
messages map[string]string
}
func (b *gcScriptBackend) Name() string { return "gc-script" }
func (b *gcScriptBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
msg := b.messages[key]
if msg == "" {
msg = "发言:" + key
}
return writeOne(req.WorkDir, "message.md", msg), nil
}
func TestTopologyConformance_groupChatRotateBudget(t *testing.T) {
be := &gcScriptBackend{messages: map[string]string{
"turn_01_researcher": "第一句",
"turn_02_writer": "第二句",
"turn_03_researcher": "第三句",
}}
sink := &collectSink{}
engine := newWP3Engine(t, mockScriptPlanner(
StepSpec{ID: "p1", Role: "researcher", Title: "参与者甲"},
StepSpec{ID: "p2", Role: "writer", Title: "参与者乙"},
), be, sink, []RoleSpec{
{Role: "researcher", Name: "甲", Backend: "gc-script"},
{Role: "writer", Name: "乙", Backend: "gc-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "群聊"},
RunOptions{Topology: TopologyGroupChat, GroupChatMaxTurns: 3})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
// 预算停机:恰好 3 轮,轮转序 researcher→writer→researcher。
if sink.countText("轮次预算 3 用尽") != 1 {
t.Fatal("缺预算停机事件")
}
data, err := os.ReadFile(filepath.Join(res.WorkDir, "output.md"))
if err != nil {
t.Fatal(err)
}
out := string(data)
for _, want := range []string{"1. researcher:第一句", "2. writer:第二句", "3. researcher:第三句"} {
if !strings.Contains(out, want) {
t.Fatalf("转录缺 %q:%s", want, out)
}
}
if strings.Contains(out, "4. ") {
t.Fatalf("超出预算仍在发言:%s", out)
}
// 名册步骤不执行,标记 skipped(非降级原因)。
st, _ := engine.loadRun(engine.runDir(res.RunID))
for _, s := range st.Plan.Workflow.Steps {
if s.ID == "p1" || s.ID == "p2" {
if s.Status != "skipped" || s.Error != gcRosterSkipReason {
t.Fatalf("名册步骤 %s = %s/%q", s.ID, s.Status, s.Error)
}
}
}
}
func TestTopologyConformance_groupChatCloseMarker(t *testing.T) {
be := &gcScriptBackend{messages: map[string]string{
"turn_01_researcher": "我先说",
"turn_02_writer": "同意收口 [close]",
}}
sink := &collectSink{}
engine := newWP3Engine(t, mockScriptPlanner(
StepSpec{ID: "p1", Role: "researcher", Title: "甲"},
StepSpec{ID: "p2", Role: "writer", Title: "乙"},
), be, sink, []RoleSpec{
{Role: "researcher", Name: "甲", Backend: "gc-script"},
{Role: "writer", Name: "乙", Backend: "gc-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "群聊"},
RunOptions{Topology: TopologyGroupChat, GroupChatMaxTurns: 8})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s", res.Status)
}
if sink.countText("发出收口标记") != 1 {
t.Fatal("缺收口标记事件")
}
st, _ := engine.loadRun(engine.runDir(res.RunID))
if n := countGcSteps(st); n != 2 {
t.Fatalf("收口标记后应停在 2 轮,实际 %d", n)
}
}
func TestTopologyConformance_groupChatModerator(t *testing.T) {
be := &gcScriptBackend{messages: map[string]string{
"turn_01_researcher": `{"next":"writer","reason":"请乙补充"}`,
"turn_02_writer": "补一段分析",
"turn_03_researcher": `{"action":"close","reason":"讨论充分"}`,
}}
sink := &collectSink{}
engine := newWP3Engine(t, mockScriptPlanner(
StepSpec{ID: "p1", Role: "researcher", Title: "主持人"},
StepSpec{ID: "p2", Role: "writer", Title: "乙"},
), be, sink, []RoleSpec{
{Role: "researcher", Name: "主持", Backend: "gc-script"},
{Role: "writer", Name: "乙", Backend: "gc-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "主持人群聊"}, RunOptions{
Topology: TopologyGroupChat, GroupChatPolicy: "moderator",
GroupChatModerator: "researcher", GroupChatMaxTurns: 8,
})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
if sink.countText("主持人收口") != 1 {
t.Fatal("缺主持人收口事件")
}
data, _ := os.ReadFile(filepath.Join(res.WorkDir, "output.md"))
out := string(data)
for _, want := range []string{"1. researcher", "2. writer:补一段分析", "3. researcher"} {
if !strings.Contains(out, want) {
t.Fatalf("转录缺 %q:%s", want, out)
}
}
st, _ := engine.loadRun(engine.runDir(res.RunID))
if n := countGcSteps(st); n != 3 {
t.Fatalf("主持人模式应 3 轮收口,实际 %d", n)
}
}
// 主持人指名不在名册 → fail-closed。
func TestGroupChatModeratorUnknownNextFailsClosed(t *testing.T) {
be := &gcScriptBackend{messages: map[string]string{
"turn_01_researcher": `{"next":"ghost"}`,
}}
engine := newWP3Engine(t, mockScriptPlanner(
StepSpec{ID: "p1", Role: "researcher", Title: "主持人"},
StepSpec{ID: "p2", Role: "writer", Title: "乙"},
), be, NopSink{}, []RoleSpec{
{Role: "researcher", Name: "主持", Backend: "gc-script"},
{Role: "writer", Name: "乙", Backend: "gc-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "x"}, RunOptions{
Topology: TopologyGroupChat, GroupChatPolicy: "moderator", GroupChatModerator: "researcher",
})
if err != nil {
t.Fatal(err)
}
if res.Status != RunFailed || !strings.Contains(res.Error, "不在名册内") {
t.Fatalf("应 fail-closed:%s %q", res.Status, res.Error)
}
}
// ---- 夹具 ----
func countGcSteps(st *RunState) int {
n := 0
for _, s := range st.Plan.Workflow.Steps {
if strings.HasPrefix(s.ID, "gc") && s.Status == "completed" {
n++
}
}
return n
}
func newWP3Engine(t *testing.T, planner Planner, be Executor, sink ProgressSink, roles []RoleSpec) *SquadEngine {
t.Helper()
dir := t.TempDir()
reg := NewRoleRegistry()
for _, r := range roles {
if err := reg.Register(r); err != nil {
t.Fatal(err)
}
}
backends := NewBackendResolver()
backends.RegisterInstance(be.Name(), be)
engine, err := NewEngine(Options{DataDir: dir, Registry: reg, Planner: planner, Backends: backends, Sink: sink})
if err != nil {
t.Fatal(err)
}
return engine
}
-355
View File
@@ -1,355 +0,0 @@
package squad
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"time"
)
// wp4_conformance_test.go — Q2 WP4 验收:task_board 拓扑(claim/lease/complete
// 原语 + 依赖门 + 孤儿租约再武装)与全 12 拓扑 conformance 汇总跑。
// ---- task_board ----
// 菱形依赖 a→(b,c)→d:认领序尊重依赖门,全部 done,标准 finalize 收口。
func TestTopologyConformance_taskBoard(t *testing.T) {
be := &iterBackend{calls: map[string]int{}}
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "a", Role: "researcher", Title: "任务a", Targets: []string{"a.md"}},
StepSpec{ID: "b", Role: "writer", Title: "任务b", Needs: []string{"a"}, Targets: []string{"b.md"}},
StepSpec{ID: "c", Role: "reviewer", Title: "任务c", Needs: []string{"a"}, Targets: []string{"c.md"}},
StepSpec{ID: "d", Role: "writer", Title: "任务d", Needs: []string{"b", "c"}, Targets: []string{"output.md"}},
), be, sink)
res, err := engine.Run(context.Background(), Goal{Text: "任务板"}, RunOptions{Topology: TopologyTaskBoard})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
// 认领序尊重依赖门:a 先于 b/c,d 最后(板上按步骤序认领,确定性)。
var order []string
for _, ev := range sink.snapshot() {
if strings.Contains(ev.Text, "认领") {
order = append(order, ev.StepID)
}
}
want := []string{"a", "b", "c", "d"}
if strings.Join(order, ",") != strings.Join(want, ",") {
t.Fatalf("认领序 = %v,期望 %v", order, want)
}
st, _ := engine.loadRun(engine.runDir(res.RunID))
for _, task := range st.Board {
if task.Status != "done" {
t.Fatalf("任务 %s = %s,期望 done", task.ID, task.Status)
}
}
if sink.countText("task_board:收口(done 4/4)") != 1 {
t.Fatal("缺收口事件")
}
}
// 孤儿租约再武装:崩溃(ctx 取消)留下 claimed+过期租约 → Resume 重入
// 再武装回 open、重新认领(Attempts=2)并跑完。
func TestTaskBoardOrphanLeaseRearms(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
crashed := false
be := &iterBackend{calls: map[string]int{}, content: func(key string, _ int, _ string) []byte {
if key == "02_writer" && !crashed {
crashed = true
cancel() // 模拟进程死亡:runOneStep 在 ctx 检查处退出,步骤回到 pending
}
return nil
}}
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "t1", Role: "researcher", Title: "一", Targets: []string{"a.md"}},
StepSpec{ID: "t2", Role: "writer", Title: "二", Needs: []string{"t1"}, Targets: []string{"output.md"}},
), be, sink)
res0, err := engine.Run(ctx, Goal{Text: "任务板"}, RunOptions{Topology: TopologyTaskBoard})
if err != nil {
t.Fatal(err)
}
if res0.Status != RunCancelled {
t.Fatalf("取消后应为 RunCancelled:%s", res0.Status)
}
// 崩溃现场:t2 claimed、租约未过期;步骤在盘上是 running(setStep 只改
// 内存,取消路径的 pending 未落盘)——进程死亡即此形态。测试把租约回拨
// 成过期(孤儿)并把步骤置回 pending(模拟重启前的一致化),再走 Resume。
st, err := engine.loadRun(engine.runDir(res0.RunID))
if err != nil {
t.Fatal(err)
}
found := false
for i := range st.Board {
if st.Board[i].ID == "t2" {
found = true
if st.Board[i].Status != "claimed" || st.Board[i].Attempts != 1 {
t.Fatalf("崩溃现场 t2 = %+v", st.Board[i])
}
st.Board[i].LeaseExpires = time.Now().Add(-time.Hour) // 租约过期 = 孤儿
}
}
if !found {
t.Fatal("板上无 t2")
}
for i := range st.Plan.Workflow.Steps {
if st.Plan.Workflow.Steps[i].ID == "t2" && st.Plan.Workflow.Steps[i].Status == "running" {
st.Plan.Workflow.Steps[i].Status = "pending"
}
}
if err := st.save(); err != nil {
t.Fatal(err)
}
// 重入:孤儿租约再武装 → 重新认领 → 跑完收口。
res, err := engine.Resume(context.Background(), st.Meta.ID)
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("恢复后应完成:%s %v", res.Status, res.Error)
}
if sink.countText("孤儿租约再武装 t2") != 1 {
t.Fatal("缺孤儿租约再武装事件")
}
st2, _ := engine.loadRun(engine.runDir(res.RunID))
for _, task := range st2.Board {
if task.ID == "t2" && task.Attempts != 2 {
t.Fatalf("再武装后 Attempts = %d,期望 2", task.Attempts)
}
}
}
// 依赖门级联:非关键任务失败 → 下游 open 任务级联 skipped → 降级收口。
func TestTaskBoardDependencyGateCascade(t *testing.T) {
be := &iterBackend{calls: map[string]int{}, content: func(key string, _ int, _ string) []byte {
return nil
}}
failBe := &failOnceBackend{inner: be, failKey: "02_writer"}
crit := false
sink := &collectSink{}
engine := newTopologyEngine(t, mockScriptPlanner(
StepSpec{ID: "t0", Role: "researcher", Title: "零", Targets: []string{"output.md"}},
StepSpec{ID: "t1", Role: "writer", Title: "一", Needs: []string{"t0"}, Targets: []string{"b.md"}, Critical: &crit},
StepSpec{ID: "t2", Role: "reviewer", Title: "二", Needs: []string{"t1"}, Targets: []string{"c.md"}},
), failBe, sink)
res, err := engine.Run(context.Background(), Goal{Text: "任务板"}, RunOptions{Topology: TopologyTaskBoard})
if err != nil {
t.Fatal(err)
}
if res.Status != RunDegraded {
t.Fatalf("非关键失败+级联跳过应降级收口:%s %v", res.Status, res.Error)
}
st, _ := engine.loadRun(engine.runDir(res.RunID))
byID := map[string]BoardTask{}
for _, task := range st.Board {
byID[task.ID] = task
}
if byID["t0"].Status != "done" || byID["t1"].Status != "failed" || byID["t2"].Status != "skipped" {
t.Fatalf("板状态 = %+v", byID)
}
for _, s := range st.Plan.Workflow.Steps {
if s.ID == "t2" && (s.Status != "skipped" || s.Error != boardSkipReason) {
t.Fatalf("t2 = %s %q", s.Status, s.Error)
}
}
}
// failOnceBackend 对指定目录恒定失败(非瞬态),其余委托 inner。
type failOnceBackend struct {
inner Executor
failKey string
}
func (b *failOnceBackend) Name() string { return b.inner.Name() }
func (b *failOnceBackend) Execute(ctx context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
if key == b.failKey {
return &ExecResult{Success: false, ErrorReason: "fatal: 拒绝执行"}, nil
}
return b.inner.Execute(ctx, req)
}
// ---- 12/12 汇总 ----
// TestTopologyConformance_allTwelve 全 12 内置拓扑汇总跑:每个拓扑名一次
// 脚本化最小运行(零模型零网络)。graph/mode/driver 十种断言完成收口;
// handoff/mailbox 两个 primitive 断言 fail-closed 拒绝单跑(其原语能力分别
// 由 TestTopologyConformance_handoff 与 WP2 mailbox 测试钉住)。
func TestTopologyConformance_allTwelve(t *testing.T) {
specs := BuiltinTopologies()
if len(specs) != 12 {
t.Fatalf("内置拓扑 = %d,期望 12", len(specs))
}
for _, spec := range specs {
spec := spec
t.Run(spec.Name, func(t *testing.T) {
switch spec.Name {
case TopologySequential:
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"output.md"}},
), &iterBackend{calls: map[string]int{}}, RunOptions{}, RunCompleted)
case TopologyParallel:
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "甲", Parallel: true, Targets: []string{"a.md"}},
StepSpec{ID: "s2", Role: "writer", Title: "乙", Parallel: true, Targets: []string{"output.md"}},
), &iterBackend{calls: map[string]int{}}, RunOptions{}, RunCompleted)
case TopologyLoop:
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "循环体", Targets: []string{"output.md", "fields.json"},
Loop: &LoopSpec{MaxIterations: 2, UntilField: "done", UntilEquals: "yes"}},
), &iterBackend{calls: map[string]int{}, content: func(_ string, _ int, target string) []byte {
if target == "fields.json" {
return fieldsJSON(map[string]string{"done": "no"})
}
return nil
}}, RunOptions{}, RunCompleted)
case TopologyRouter:
runAgg(t, spec.Name, mockScriptPlanner(routerSteps()...),
&iterBackend{calls: map[string]int{}, content: func(_ string, _ int, target string) []byte {
if target == "fields.json" {
return fieldsJSON(map[string]string{"route": "fast"})
}
return nil
}}, RunOptions{}, RunCompleted)
case TopologyEvaluatorOptimizer:
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "draft", Role: "writer", Title: "起草", Targets: []string{"output.md"}},
StepSpec{ID: "eval", Role: "reviewer", Title: "评审", Targets: []string{"verdict.md", "fields.json"},
Loop: &LoopSpec{MaxIterations: 4, UntilField: "verdict", UntilEquals: "pass", Body: []string{"draft"}}},
), &iterBackend{calls: map[string]int{}, content: func(_ string, iter int, target string) []byte {
if target == "fields.json" {
if iter >= 3 {
return fieldsJSON(map[string]string{"verdict": "pass"})
}
return fieldsJSON(map[string]string{"verdict": "fail"})
}
return nil
}}, RunOptions{}, RunCompleted)
case TopologyLongRunning:
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"output.md"}},
), &iterBackend{calls: map[string]int{}},
RunOptions{Deadline: time.Now().Add(5 * time.Second)}, RunCompleted)
case TopologyLeader:
b := &leaderScriptBackend{
decisions: []string{delegateJSON("writer", "撰写简报"), closeJSON},
script: map[string]map[string]string{"01_writer": {"output.md": goodReport}},
}
engine := newLeaderEngine(t, b)
res, err := engine.Run(context.Background(), Goal{Text: "汇总"}, RunOptions{Topology: TopologyLeader})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
case TopologyReview:
planner := mockScriptPlanner(
StepSpec{ID: "f1", Role: "researcher", Title: "评审", Targets: []string{"findings.json"}},
)
planner.Agents = []RoleSpec{
{Role: "researcher", Name: "评审", Backend: "agg-review"},
{Role: "verifier", Name: "核实", Backend: "agg-review"},
}
engine := newAggEngine(t, planner, &aggReviewBackend{}, []RoleSpec{
{Role: "researcher", Name: "评审", Backend: "agg-review"},
{Role: "verifier", Name: "核实", Backend: "agg-review"},
})
res, err := engine.Run(context.Background(), Goal{Text: "评审"},
RunOptions{Topology: TopologyReview, ReviewTarget: "材料"})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
data, _ := os.ReadFile(filepath.Join(res.WorkDir, "output.md"))
if !strings.Contains(string(data), "已丢弃 0 条未验证") || !strings.Contains(string(data), "样例问题") {
t.Fatalf("报告 = %s", data)
}
case TopologyGroupChat:
engine := newAggEngine(t, mockScriptPlanner(
StepSpec{ID: "p1", Role: "researcher", Title: "甲"},
StepSpec{ID: "p2", Role: "writer", Title: "乙"},
), &gcScriptBackend{}, []RoleSpec{
{Role: "researcher", Name: "甲", Backend: "gc-script"},
{Role: "writer", Name: "乙", Backend: "gc-script"},
})
res, err := engine.Run(context.Background(), Goal{Text: "群聊"},
RunOptions{Topology: TopologyGroupChat, GroupChatMaxTurns: 2})
if err != nil {
t.Fatal(err)
}
if res.Status != RunCompleted {
t.Fatalf("status = %s err = %v", res.Status, res.Error)
}
case TopologyTaskBoard:
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "t1", Role: "researcher", Title: "一", Targets: []string{"a.md"}},
StepSpec{ID: "t2", Role: "writer", Title: "二", Needs: []string{"t1"}, Targets: []string{"output.md"}},
), &iterBackend{calls: map[string]int{}}, RunOptions{}, RunCompleted)
case TopologyHandoff, TopologyMailbox:
// primitive:不可单独作为运行拓扑(fail-closed);原语能力由
// 专项 conformance 钉住(handoff/mailbox 测试)。
runAgg(t, spec.Name, mockScriptPlanner(
StepSpec{ID: "s1", Role: "researcher", Title: "一", Targets: []string{"output.md"}},
), &iterBackend{calls: map[string]int{}}, RunOptions{}, RunFailed)
default:
t.Fatalf("未覆盖的拓扑 %q", spec.Name)
}
})
}
}
// runAgg 汇总跑的最小引擎:graph 类拓扑共用 iter 三角色装配。
func runAgg(t *testing.T, topo string, planner Planner, be Executor, opts RunOptions, want RunStatus) {
t.Helper()
opts.Topology = topo
engine := newTopologyEngine(t, planner, be, nil)
res, err := engine.Run(context.Background(), Goal{Text: "汇总跑 " + topo}, opts)
if err != nil {
t.Fatal(err)
}
if res.Status != want {
t.Fatalf("status = %s err = %q,期望 %s", res.Status, res.Error, want)
}
}
// aggReviewBackend 汇总跑用的最小 review 后端:finder 出一条发现,verify 判 PASS。
type aggReviewBackend struct{}
func (b *aggReviewBackend) Name() string { return "agg-review" }
func (b *aggReviewBackend) Execute(_ context.Context, req ExecRequest) (*ExecResult, error) {
key := filepath.Base(filepath.Clean(req.WorkDir))
if strings.HasPrefix(key, "verify_") {
return writeOne(req.WorkDir, "verdict.md", "核对成立。\nVERDICT: PASS"), nil
}
return writeOne(req.WorkDir, "findings.json",
`[{"location":"第1段","severity":"high","issue":"样例问题","evidence":"样例证据"}]`), nil
}
// newAggEngine 自定义角色表的汇总引擎(backend 实例名 = be.Name())。
func newAggEngine(t *testing.T, planner Planner, be Executor, roles []RoleSpec) *SquadEngine {
t.Helper()
dir := t.TempDir()
reg := NewRoleRegistry()
for _, r := range roles {
if err := reg.Register(r); err != nil {
t.Fatal(err)
}
}
backends := NewBackendResolver()
backends.RegisterInstance(be.Name(), be)
engine, err := NewEngine(Options{DataDir: dir, Registry: reg, Planner: planner, Backends: backends, Sink: NopSink{}})
if err != nil {
t.Fatal(err)
}
return engine
}