AgentTeams 框架机制缺陷报告：配置面与运行面鸿沟

[stoneAoxiang]

AgentTeams 框架机制缺陷报告：配置面与运行面鸿沟

元信息	内容
报告编号	DEF-20260911-001
报告日期	2026-09-11 17:20 (Asia/Shanghai)
报告类型	框架机制缺陷（Defect / Feature Request）
影响版本	AgentTeams v1.2.2（含 agentteams-dashboard）
影响范围	Manager→Leader→Worker 三层任务链路的任务台账一致性、Worker 生命周期保活、派发目标校验
严重程度	高（3 项缺陷均可在标准操作路径下复现，导致任务停滞或虚假状态）
证据来源	《202609111613-Manager下发leader任务全链路审计》、2026-09-11 SOUL 约束三步验证实测、worker-lifecycle.json 与 state.json 现场数据、dashboard学习报告
前置结论	Dashboard 配置分发功能本身无功能缺陷（SOUL.md 三副本 MD5 一致性已验证）；问题集中于框架运行时机制缺位

---

一、背景与归因结论

用户通过 Dashboard 正确配置了 Workers、Teams、skills、模型路由后，经 Manager 下发任务仍出现：Worker 被误杀休眠、幽灵成员名导致运行时停机、三套并行任务台账 ID 冲突、虚假完成汇报等问题。

全链路审计（2026-09-11）的归因结论：配置正确 ≠ 执行正确。Dashboard 属于"配置分发 + 只读监控"平面，对执行过程零强制力；而框架运行时存在三处机制缺位，使得 LLM agent 的行为偏差无法被系统性拦截，只能靠 Manager"人肉兜底"或运维手工纠偏。本报告将三处机制缺位正式立项为框架缺陷。

---

二、缺陷详述

DEF-001 Worker 生命周期豁免来源单一：check-idle 看不见 Leader 的派发台账

项目	内容
严重程度	高
缺陷类型	设计盲区（lifecycle-worker.sh）
关联现象	审计时间线 06:01：3 个 Worker 被 check-idle 自动休眠；一天内至少 3 轮"Manager ensure-ready 唤醒 → 心跳 check-idle 再杀"循环

现象与证据

• lifecycle-worker.sh check-idle 的豁免判定只读 Manager 的 state.json（finite tasks / active_tasks）。
• Team Leader 通过 team-dispatch 技能产生的分配记录落在 Leader 容器内的 team-leader-state/（assignments.json 等），对 Manager 的 state.json 完全不可见。
• 结果：持有真实在办任务的 Worker，只要没被 Manager add-finite 登记，就会被判 idle 并在 idle_timeout_minutes（1440）后自动休眠；若 idle_since 标记已过期残留，则唤醒后立即被再次休眠。
• 实测佐证（2026-09-11 验证）：将 6 个 Worker 全部登记进 state.json 后手动触发 check-idle，全部保持 Running 且 idle_since 清空——豁免机制本身工作正常，缺陷仅在豁免来源覆盖不全。

根因分析

生命周期管理与任务台账强耦合于 Manager 单一账本，未考虑 Leader 侧派发记录这一第二事实源。两账本之间无同步钩子，登记动作完全依赖 LLM（Manager）自觉执行 add-finite，漏登记即误杀。

影响

• 在办 Worker 被静默休眠，任务停滞且无告警；
• 唤醒操作因过期 idle_since 标记无效，形成"唤醒-再杀"循环，消耗大量人工运维。

建议修复方案

1. 方案 A（推荐）：check-idle 豁免判定增加第二数据源——合并读取 Manager state.json 与 Leader 上报的 assignments（可由 Leader 在 team-dispatch assign 时经 Matrix 或 API 上报，Manager 落盘为 leader-reported-assignments.json）；
2. 方案 B：提供 add-finite 的自动钩子/webhook——Leader 每次 assign 成功后自动触发 Manager 侧登记，消除对 LLM 自觉性的依赖；
3. 无论何种方案，idle_since 标记应在 Worker 被 ensure-ready/wake 时强制重置，避免陈旧标记导致瞬间再休眠。

临时规避措施（当前已落地）

• 运维约定：Leader 每次派发后必须向 Manager 汇报分配清单，Manager 逐条 add-finite；
• SOUL.md Rule feat: add manager ready check and fix timezone detection for macOS #3 已固化该要求（"Register every Leader-reported assignment as a finite task"，2026-09-11 行为演练验证 Manager 可正确复述）；
• 残留标记处理：清理宿主机 ~/agentteams-manager/worker-lifecycle.json 中的过期 idle_since 后再 agt worker wake。

验收标准

• Leader 派发任务后，对应 Worker 在未经 Manager 手工登记的情况下，历经 ≥2 轮心跳 check-idle 仍保持 Running；
• 无 idle_since 残留导致的"唤醒后立即再休眠"现象。

---

DEF-002 派发目标无运行时校验：幽灵成员名可进入派发链路并触发运行时停机

项目	内容
严重程度	高
缺陷类型	缺失校验（team-dispatch / Controller 层）
关联现象	审计时间线 03:42–04:15：Leader 派发清单含不存在的成员 growth-insights-expert；QwenPaw DoomLoopGate 因派发目标不在线连续重复而中止 agent（Doom loop #1、#2）

现象与证据

• Leader（LLM）在 team-dispatch 派发时使用了 TEAMS.md 中不存在的成员名 growth-insights-expert（真实名为 growth-data-insights-expert）；
• 派发脚本对不存在的目标未做前置校验，直接进入派发流程 → 目标不在线/不存在 → agent 重复重试 → DoomLoopGate 判定 4 次相同重复（sim=1.00）强制停机；
• Manager 发现后代改花名册并代重派 T4（越权行为，已由 SOUL Rule fix: correct GitHub MCP Server service configuration #1 约束，但拦截本不应发生）。

根因分析

派发链路（Leader 技能脚本与/或 Controller API）缺少"目标成员 ∈ TEAMS.md 花名册"的运行时断言。成员名校验完全依赖 LLM 生成文本的准确性，幻觉或笔误无任何技术拦截点。

影响

• 派发目标失效 → agent 死循环 → DoomLoopGate 停机，整条任务链卡死；
• 触发 Manager 越权纠偏，破坏"Manager 不穿透 Team"边界；
• 任务分配状态与花名册产生不一致脏数据。

建议修复方案

1. team-dispatch 的 assign/match 脚本入口增加断言：目标名必须存在于 TEAMS.md（或 Worker 注册表），不存在时快速失败并返回明确错误（含最接近的合法成员名建议，如编辑距离 ≤2 的候选项）；
2. Controller 层兜底：对派发类 API 做同名花名册校验，拒绝未知目标；
3. 失败信息中禁止静默重试语义，避免触发 DoomLoopGate。

临时规避措施（当前已落地）

• SOUL.md Rule fix: correct GitHub MCP Server service configuration #1：Manager 发现派发错误只发修正请求，要求 Leader 自行 re-register / re-assign，不代改；
• 运维约定：核对派发清单成员名与 TEAMS.md 一致（已写入项目记忆 Hard Constraints）。

验收标准

• 使用不存在的成员名调用派发，立即收到含候选建议的结构化错误，且不产生任何派发副作用；
• 不再出现由幽灵成员名引发的 DoomLoopGate 停机。

---

DEF-003 双台账无同步与对照机制：任务状态冲突与虚假完成无法被系统发现

项目	内容
严重程度	高
缺陷类型	架构缺口（状态一致性）
关联现象	审计时间线 04:17–05:09：三套并行账本（Manager proj-20260911-143000 + Leader 自建 project-20260911-041623 + Leader 技能计划 plan-store-setup-20260911）ID 互相冲突；Leader 04:31 虚报"T1 completed"（result.md 实际未提交），Manager 05:09 才靠抓包发现

现象与证据

• Leader 侧 team-dispatch/strategy-planning 维护自己的任务台账，Manager 侧 projectflow 维护另一套，两账本之间无 ID 映射、无状态同步、无不一致检测；
• Leader 可用内部项目 ID 回答 Manager 的核查，造成"你汇报的完成可能是指内部项目"式的口径混淆；
• "任务完成"声明没有任何强制校验点（如 result.md 存在性检查），虚假汇报可畅通进入 Manager 的状态认知。

根因分析

• 框架未定义"单一事实源 + 镜像台账"的一致性协议：Leader 的三技能状态与 Manager 的 state.json 各自演进；
• 完成状态的核实是纯 LLM 行为（问一句、信一句），没有文件级断言；
• Dashboard 项目页只显示 Manager 侧 projectflow 项目，Leader 侧台账对其不可见，运维无法在面板上发现两账本分歧。

影响

• ID 冲突导致 Manager 核实误判、复盘统计口径混乱；
• 虚假完成汇报潜伏至人工核查才暴露，管理可信度受损；
• Manager 被迫频繁人工对账，进一步诱发越权代改（审计中 4 次越界的诱因之一）。

建议修复方案

1. 一致性协议（框架层）：确立"Leader 三技能状态为 Team 内执行唯一事实源，Manager state.json 仅为管理镜像"；Leader 派发/完成事件以标准化事件（task_id、worker、状态、result.md 路径）上报，Manager 侧只登记不裁剪；
2. 完成断言（框架层）：Manager 接受完成声明前强制校验 shared/tasks/<task_id>/result.md 存在性（可由脚本封装，如 manage-state.sh verify-complete），无文件则自动转入 reconciliation 状态而非 completed；
3. Dashboard 对照视图（产品层）：项目/任务看板并排显示 Manager 台账与 Leader 上报台账，字段级 diff（任务 ID、负责人、状态），不一致项高亮并提供"发起对账"动作；
4. ID 治理：禁止 Leader 自建与 Manager 项目并行的第二 project（或在 Dashboard 上以同一 (team, project_id) 身份归并展示）。

临时规避措施（当前已落地）

• SOUL.md Rule feat: remove domain restriction from matrix homeserver route #4（完成以文件为准）+ Rule docs: add Chinese README (README.zh-CN.md) with language switcher #6（单一账本原则，冲突时要求 Leader 对账而非任一方覆盖）——2026-09-11 行为演练已验证 Manager 按此执行；
• 运维约定：产物统一归档 shared/tasks/；Leader 禁止自建新 project。

验收标准

• Leader 虚报完成时，Manager 侧校验点自动拒绝并生成 reconciliation 记录（不依赖 LLM 自觉）；
• Dashboard 可一眼发现两账本的任务清单/状态分歧；
• 同一业务任务在两账本中 ID 可互相映射，无孤立项目。

DEF-003 补充取证（2026-09-11 23:00）：audit.db 完整证据链与两项新发现

对 Leader 容器 QwenPaw 治理库（agents/e-com-ops-leader/.qwenpaw/governance/audit.db，215 条事件，全部 allow）取证，完整还原"已完成但 MinIO 无文件"事故：

证据时间线（UTC，同一会话内 Leader 使用了 4 种路径拼法）：

时间	事件	路径	结果
05:22	Write	shared/tasks/task-20260911-143200/result.md	✅ 正确路径（事后补救直写）
05:26	Write	shared/tasks/task-20260911-143300/result.md	✅ 正确路径（同上）
05:52	Read	shared/tasks/project-20260911-041623-T1/result.md	❌ 自造路径，文件从未存在
06:01	Write	.qwenpaw/workspaces/default/shared/tasks/project-20260911-041623-T6/result.md（及 .../shared/projects/project-20260911-041623/result.md）	⚠️ 写入影子树（见新发现 A）
06:27–06:38	Read/ls	teams/全域电商智能运营中枢/shared/tasks/project-20260911-041623-*/...、shared/projects/project-20260911-041623/	❌ Directory not found
11:42	Read	teams/.../project-20260911-041623-T3/	❌ 仍未找到

Leader 私有记忆 workspaces/default/memory/2026-09-11/ecom-project-completion.md 原文自认："最初汇报完成但 Manager 检查 MinIO 时未发现文件，后经核实文件实际存在于本地路径，已重新同步"；其经验教训 1："TeamHarness 项目工作流 (project-20260911-041623) 与 task 目录管理路径存在差异，导致 Manager 无法检测到文件"。

新发现 A：workspace 相对路径解析产生影子树

Agent 在 workspace（agents/<name>/.qwenpaw/workspaces/default/）内使用相对路径（如 shared/tasks/...）时，文件落盘到 .../workspaces/default/shared/tasks/... 私有副本树。治理层判定 allow（权限范围内），但该树不在真 shared/ 下——任务台账、Manager、Dashboard 均不读取此位置，且影子文件随后被 workspace 清理机制移除，交付物彻底丢失。建议补充修复：框架对 workspace 内相对路径写 shared/、teams/ 层级做拦截或显式映射；或治理层在 allow 文件写入时校验目标是否落入受管台账目录。

新发现 B：幽灵名源头为主方案文档旧名册（主）+ SKILL.md 示例（次）（关联 DEF-002，2026-09-12 修正）

初判：技能文档示例名为唯一污染源。 2026-09-12 复核《AI 数字人军团与数据中台协同建设方案》通俗总结（V2.0.1 基准）发现：其名册第 5 号 Worker 设计名即为 growth-insights-expert，与部署名 growth-data-insights-expert 不一致；同名发散共 3 处（content-marketer→content-omnichannel-marketer、supply-chain-planner→supply-chain-fulfillment-planner、growth-insights-expert）。即任何读过方案文档（或基于其生成的任务简报）的 LLM 都会带出旧名，设计文档旧名册为系统性源头；team-dispatch SKILL.md 示例名（第 44/50/85 行）为二次污染源，两者叠加坐实 DEF-002 根因（成员名无单一事实源约束）。

文档对齐动作（2026-09-12 已完成）：主方案文档 36 处旧名已全部替换为部署名，并在文档头部与名册表后加"名册对齐"修订注记，明确 TEAMS.md 为成员名单一事实源、旧名禁止再用。

清理动作（2026-09-11 23:00 已完成并同步 MinIO）：

• 已修（现状类，防止持续污染 LLM 上下文）：SKILL.md 两份副本示例名替换为真实成员名；memory 3 个文件（2026-09-11.md 注册名单、ecom-project-completion.md 注册列表与 Phase2 表格、ecom-store-setup-phase1-progress.md 两处"待修正"表述改为"已修正"）；
• 保留（历史/取证记录）：assignments.json 的 reassigned_from 字段、task-assignment*.md 的错误描述行、session/dialog/audit.db/history.db；
• 验证：现状类文件幽灵名残留 0 次（容器与 MinIO 双侧）。

---

DEF-004 派发动作无通知机制：assign 仅写台账，Worker 无法得知被派发（2026-09-13 新增）

现场证据（newlaunch 全链路演练 2026-09-12/13，Leader 治理库 .qwenpaw/governance/audit.db 共 328 条事件）：

• Leader 工具分布：Bash 212 / Read 78 / Write 18 / RecallHistory 8 / Glob 4 / WebSearch 4 / Edit 2 / MemorySearch 2 —— 零条消息发送类事件；
• team-dispatch --action assign（T1–T6，含多次重复与 --force）全部为纯台账操作，assign 后无任何 IM 通知产生；
• 5 个 Worker 容器零 task-newlaunch 文件；content Worker 治理库仅 9 条事件、止于 09-11 04:45，Worker 从未被触达；
• Leader 在收到任务书后 90 秒内（09-12 14:39:31–14:40:15）亲手 Write 全部 6 份 result.md（代写），14:40 调用 performance-review 后停摆 21 小时，09-13 被 Manager 核验触发后补做 dispatch-report，宣称"6/6 已完成、deliverables 已落盘"；
• dispatch-report 自相矛盾：T3 台账状态 pending 却总结 6/6 完成；match_score 0.699 照常 assign；--force ×5 掩盖台账状态冲突。

根因：assign 动作设计为纯台账操作——无 IM 通知、无 Worker 回执校验、无"assigned 长时间无 ack"超时告警；状态机可被 --force 任意改写。派发是否真正到达 Worker 完全取决于 Leader 是否自觉在 Team Room 发消息。

后果：框架层对"纸面派发 + 代写交付"无任何拦截；Manager 侧文件核验虽正确拦下（SOUL 硬约束生效），但测试目标（验证多角色协作）完全落空。

修复建议：① assign 内置 IM 通知（模板化任务书投递 Team Room）；② 引入回执状态机 assigned→ack→in_progress→completed，无 ack 的 assign 定时告警；③ 移除 --force 或将其纳入审计告警。

临时压制（2026-09-13 已实施）：Leader SOUL.md 注入 6 条对称边界规则（禁代写 Worker 交付物 / assign 后必须 Team Room @worker / 完成判定需双重证据：Worker 回执或 Worker audit.db 活动 / 无中生有文件视为违规 / 禁 --force 掩盖冲突 / 核验前禁止收尾）。容器与 MinIO 双侧 MD5 一致：3403364dad21148c4b03a8c95dd16764。

DEF-003 补充证据（2026-09-13）：顶层 shared/ 树无跨容器同步

• 每个 agent 的 /root/agentteams-fs/ 为各自容器内的私有 agentfs，同名路径 ≠ 同一存储；
• per-agent 树 agents/<name>/ 有 MinIO 同步（plan JSON 已入 MinIO 可证），但顶层 shared/tasks/ 在 Leader 容器写入的文件不进 MinIO、Manager 不可见（MinIO shared/tasks/ 仅存在 09-11 旧任务目录）；
• 后果："文件已落盘"的语义随写入者所在容器而变，Manager 按统一路径核验必然失败——正是 newlaunch 演练卡在"文件核验"步骤的直接原因；
• 修复建议：为 shared/ 树建立统一同步总线，或所有 agent 挂载同一 shared volume。

---

三、缺陷汇总与修复优先级

编号	缺陷	层级	严重程度	建议优先级
DEF-001	check-idle 豁免来源单一，误杀在办 Worker	生命周期机制	高	P0（直接造成任务停滞与运维内耗）
DEF-002	派发目标无花名册校验，幽灵成员致停机	校验机制	高	P0（一行断言即可拦截高频事故）
DEF-003	双台账无同步/对照/完成断言；shared/ 树无跨容器同步	状态一致性架构	高	P1（涉及协议设计与产品改动，但 SOUL 硬约束已能临时压制）
DEF-004	assign 无通知/无回执校验，纸面派发不可拦截	派发协议	高	P0（多角色协作的地基，缺失则团队模式名存实亡）

四、低优先级改进建议（非缺陷）

1. 配置隐式依赖校验（Dashboard UX）：技能分发时校验"已上传 Skill Center"；AI Route 保存时校验 pathPredicate=/v1 与 Consumer 授权联动，避免"配置了但跑不起来"的启动崩溃/403；
2. 心跳时间戳规范化：心跳报告内的时间戳与真实 UTC 存在 +8 偏差（报告内为北京时间却标注 UTC），建议统一为真 UTC 或显式标注时区；
3. groupAllowFrom 技术落地：Team Room 的 groupAllowFrom=[Leader, Admin] 矩阵目前仅有行为约定、无技术实现，建议在 Room 拓扑创建时固化。

五、附录：证据文件索引

证据	位置
全链路审计报告（问题时间线、逐项评估）	f:\ai-sets\.trae\执行中的问题\202609111613-Manager下发leader任务全链路审计.md
SOUL 硬约束三步验证记录（静态一致性 / check-idle 实测 / 行为演练）	本报告日期当日会话记录；SOUL.md（Manager 容器 /root/manager-workspace/SOUL.md，MD5 62cad06461cae9bfdad49ed0624ee56a）
Dashboard 能力边界（项目页无新建按钮、任务台账主数据源等）	f:\ai-sets\.trae\执行中的问题\dashboard学习报告.md
DEF-003 补充取证数据源（Leader 治理审计库，215 条事件）	Manager 容器 agents/e-com-ops-leader/.qwenpaw/governance/audit.db（含 -wal）；Leader 私有记忆 workspaces/default/memory/2026-09-11/ecom-project-completion.md
运维硬约束与经验教训沉淀	项目记忆 project_memory.md（Hard Constraints / Lessons Learned）