FlowOS（软件研发全流程协同操作系统）的可执行概念验证切片：在真实 AgentTeams 运行时上，用 4 个职能 Agent 跑通「缺陷定位 → 修复生成 → 质量门禁 → 人工审批」端到端闭环，并把每次交接沉淀为可校验的链式证据。
A runnable proof-of-concept for FlowOS, a software-engineering full-lifecycle collaboration OS. Four role-specialized agents on a real AgentTeams runtime complete a defect closed loop (localize → fix → gate → human approval), with every handoff recorded in a verifiable SHA-256 evidence chain.
软件研发的痛点不在单个环节，而在环节之间的接缝：缺陷定位结论靠"人肉转述"交给修复者、修复提案没有测试范围约束、门禁裁决依赖人工经验、复盘结论进不了下一次开发。本仓库把一条接缝（M3↔M4 缺陷流）做成一个可运行、可复核、可复现的最小闭环：
defect-tracer（N14 缺陷定位）→ fix-engineer（N15 修复生成）
→ quality-gate（M4 质量门禁）→ human-approver（L2 人工审批，fail-closed）
四个职能 Agent 在 AgentTeams Embedded v1.2.2（Matrix 房间 + Kubernetes 风格 CRD）真实运行时上协作，两次独立缺陷闭环已在真实环境跑通（DF-0001 订单支付失败 27 条消息 / DF-0002 连接泄漏 14 条消息 NEEDS_REVIEW 转人工）。
| 机制 | 落点 | 关键设计 |
|---|---|---|
| 交接契约 | contracts/ |
3 份 JSON Schema（结论包/修复提案/门禁报告）+ 准入校验，evidence_refs 前缀正则防编造 |
| 链式证据链 | src/agentteams_poc/evidence.py |
append-only + SHA-256 链式哈希 + seal 封口，篡改/截断可检出 |
| 确定性门禁 | src/agentteams_poc/gates.py |
5 条确定性规则，LLM 只提议、系统只确认；fail-closed |
| LLM 降级 | src/agentteams_poc/llm.py |
坏输出 → 兜底结论 → 转人工，失败不隐藏（llm-degraded 留痕） |
| 主数据 | src/agentteams_poc/registry.py |
defect_id/trace_id 单写多读签发 + 血缘 |
| 任务状态机 | src/agentteams_poc/statemachine.py |
六态迁移表 + 真实房间消息回放驱动，乱序/重复 fail-closed |
| 审计一键导出 | src/agentteams_poc/audit_export.py |
按 trace_id 装配完整审计报告，篡改检出 |
pip install jsonschema pytest
export PYTHONPATH=$PWD/src
bash scripts/run-demo.sh # mock 端到端（确定性输出，无需 LLM Key）
python -m pytest tests/ -q # 58 passed
python -m agentteams_poc verify evidence/run-golden.jsonl # 证据链校验接入真实 LLM（OpenAI 兼容）：
export LLM_BASE_URL=https://api.deepseek.com/v1
export LLM_API_KEY=sk-xxxx
export LLM_MODEL=deepseek-chat
export LLM_MOCK=0
bash scripts/run-demo.sh --mock 0未配置 Key 时自动确定性降级（不崩溃、不放行）：兜底结论 → 门禁 NEEDS_REVIEW → 审批默认拒绝（退出码 3），降级事件写入证据链。
evidence/agentteams-runtime/ 收录 AgentTeams Embedded v1.2.2 上的两次真实闭环原始数据：
- 房间时间线 JSONL（27 + 14 条消息，含 origin_server_ts 真实时间戳）
- 资源快照（workers/teams/humans/managers，
agt get实测） - 状态机轨迹（两次闭环各 6 次合法迁移走完六态）
- 交接时延指标卡（10 个真实样本：审批→归档 p50=8.3s）
- 权限运行时验证（L3 隔离、Worker 跨 Team 唯一 HTTP 400）
部署复现见 docs/run-evidence.md。
在落地过程中发现并修复 AgentTeams 真实 bug，已提交上游：
- PR #1171：
openai-compat使用 IP Base URL 时 LLM 503cluster_not_found的修复（字节码级根因定位） - 复发机制分析（已作为评论发布）：controller 重启即复发——启动路径硬编码覆盖 provider 配置，附 4 条根治建议
- Issue #1057 证据评论
详见 docs/upstream/。
├── contracts/ 交接契约 JSON Schema + 准入执行引擎
├── src/agentteams_poc/ 证据链 / 主数据 / 门禁 / LLM 降级 / 状态机 / 审计导出 / 流水线
├── manifests/ AgentTeams 声明式资源（4 Worker + Team + Human，agentteams.io/v1beta1）
├── skills/ 3 份 SKILL.md（9 要素：名称/用途/IO/调用条件/依赖/失败处理/安全边界/复用/协同关系）
├── scenarios/ 样例输入（order-pay-fail / conn-leak）
├── tests/ 58 个测试（模块→集成→E2E→回归→状态机→审计导出）
├── evidence/ 黄金样本 + 审计导出样例 + 真实运行时证据
├── scripts/ 一键演示 / 证据采集 / 部署脚本
└── docs/ 工具契约 / 架构 / 运行证据 / 上游分析
Apache-2.0。基于 AgentTeams（Apache-2.0）生态设计。
本仓库源自 GOAI 世界人工智能开源大赛 Agent Infra 赛道的参赛实践，独立开源、可自由复用。