A CLI-first Agent Runtime and EvalOps platform for building auditable, validated, and reproducibly evaluated agent workflows.
这个项目解决的不是“再写一个 prompt demo”，而是 Agent 在路由、工具执行、状态更新、 验证、受限修复和评测中的工程边界问题。CloudOps RCA、GUI Automation 和 Issue-to-Patch 三条 workflow 共用同一套 Runtime，并产出可检查的 trace、state 和 artifact。
| Capability | What it proves |
|---|---|
| Runtime composition | App package、service、provider、profile 和 scope 有清晰装配边界 |
| Auditable execution | Tool record、trace、final state 和 artifact 可检查 |
| Validation and repair | commit 前 validator 与预算受限 reflection/repair |
| EvalOps | manifest/case 驱动、deterministic rerun 和 failure taxonomy |
flowchart LR
CLI["CLI / Task Input"] --> Router["Registry-aware Router"]
Router --> Runtime["AgentRuntime + LangGraph"]
Runtime --> Apps["Registered App Workflows"]
Runtime --> Services["Scoped Runtime Services"]
Apps --> Tools["Tools + Validators + Reflection"]
Services --> Providers["Replaceable Providers"]
Runtime --> Evidence["Trace + State + Artifacts"]
Evidence --> Eval["EvalRunner + Reports"]
core 持有执行合同和通用服务，apps 持有业务 workflow 与策略，extensions 提供 可替换 provider/adapter；CLI 只负责装配和展示，不复制 Runtime。
Problem: 从受控 incident fixtures 中汇集多源证据，输出可验证的根因分析，而不是让 LLM 凭直觉下结论。
incident -> metrics/logs/traces/events -> EvidenceGraph
-> hypothesis ranking -> validator -> bounded repair
-> RCA report + trace + final state
展示 read-only tool policy、RAG、证据引用、validator、reflection 和 case memory。
uv run python scripts/run_cloudops_demo.py \
--case cloudops_001 \
--llm-mode deterministic \
--show tools,evidence,validators,report,artifacts产物：artifacts/runs/cloudops_demo_cloudops_001/
Problem: 在可重复的 mock-admin 环境中执行后台操作，并用环境状态而非模型自报判断成功。
task -> DOM observation -> bounded action plan -> browser tools
-> environment validator -> repair/replay -> snapshots + trace
展示受控 browser adapter、action schema、side-effect policy、replay 和状态验证。
uv run python scripts/run_gui_demo.py \
--case gui_001 \
--llm-mode deterministic \
--show actions,observations,validators,replay产物：artifacts/runs/workspace_gui_gui_001/
Problem: 在隔离的 mock workspace 中完成搜索、补丁、测试与回退，不修改用户真实工作树。
issue -> search/read -> bounded patch -> tests -> semantic validators
-> repair or revert -> final diff + test log + trace
展示文件范围治理、patch schema、测试门禁、bounded repair 和失败回退。
uv run python scripts/run_coding_demo.py \
--case code_001 \
--llm-mode deterministic \
--show search,patch,tests,validators,diff产物：artifacts/runs/workspace_coding_code_001/
需要 Python 3.12 和 uv。
uv sync --frozen
uv run python scripts/run_cloudops_demo.py \
--case cloudops_001 \
--llm-mode deterministic \
--show tools,evidence,validators,report,artifacts成功运行的精简输出如下；完整 JSON/JSONL 只写入被 Git 忽略的 artifact 目录：
run_id: cloudops_demo_cloudops_001
agent_id: cloudops_rca_agent
workflow_id: cloudops_rca_v1
status: success
root_cause: mysql_connection_pool_exhausted
confidence: 0.9
validation.ok: true
failed_checks: []
artifact: cloudops_evidence_graph.json
artifact: rca_report.md
artifact: final_output.json
artifact: final_state.json
artifact: trace.jsonl
以下数字来自 2026-07-12 在当前提交上的 deterministic 本地运行，不代表线上准确率、 真实 provider SLA 或生产规模验证。
Tests: 312 passed
Eval: 47/47 passed
Validated on: 2026-07-12
Commands: uv run pytest -q; uv run python scripts/run_evals.py --suite all --llm-mode deterministic
全量评测覆盖 CloudOps、Workspace GUI、Workspace Coding 和 Router；报告写入 artifacts/evals/<eval_run_id>/。case 定义和 scorer 说明见 Evaluation。
| Path | Role |
|---|---|
| src/agent_platform/core | Runtime、state、tools、validation、trace、memory、eval contracts |
| src/agent_platform/apps | CloudOps 与 Workspace 的业务 package/workflow/policy |
| src/agent_platform/extensions | LLM、embedding、RAG、memory 和 scorer providers |
| evals | Agent Runtime manifest-driven case suite |
| scripts | Demo、eval 与 trace/artifact inspection CLI |
| docs | 当前架构、工作流、评测和设计决策 |
- 项目是 CLI-first 的架构验证与 Agent 工程实践，不是完整 Web/SaaS 产品。
- deterministic 模式用于稳定 demo 和 regression eval，不等同于真实线上效果。
- provider 模式必须显式配置，并受 schema、validator、fallback、cache 和调用预算约束。
- CloudOps 数据来自仓库内合成 fixtures，不直连生产监控系统。
- GUI/Coding 使用受控 mock adapter；它们不会任意操作真实浏览器、shell 或用户仓库。
- docker-compose.yml 只提供可选的 Postgres、Redis、Qdrant 基础设施，没有应用 API。
uv sync --frozen
uv run ruff check .
uv run mypy src
uv run pytest -q
uv run python scripts/run_evals.py --suite all --llm-mode deterministic运行产物、数据库、cache、.env 和完整 prompt payload 不进入版本控制。真实 provider 调用还要求显式传入 --allow-external-provider-calls；默认命令不会访问付费服务。
本项目采用 Apache License 2.0。公开问题与联系请使用 GitHub Issues 或仓库所有者的 GitHub Profile。