SpringAgentOps

Project console: open http://127.0.0.1:8080/projects/project-alpha/overview. Local mode maps the local user to Project OWNER without OIDC. All Dataset, Evaluation, Baseline, Quality Gate, GitHub, API Key, security policy, retention, and audit screens use authorized backend APIs. Raw managed API Keys are displayed once and are never stored by the browser. See the Project console guide.

SpringAgentOps 不负责编排 Agent。它聚焦 Agent 上线后的工程问题：还原模型、工具和检索调用链路， 用固定数据集重复评测，比较 Baseline 与 Candidate，并将可解释的质量门接入 Pull Request。

• Trace 可观测性：采集 Agent、模型、工具和检索 Span，通过执行树、时间瀑布、 Token 与费用信息定位失败和性能瓶颈。
• 安全采集：模型与工具内容默认不采集；显式开启后，在入队和持久化前执行不可逆脱敏。
• 可重复评测：用不可变 Dataset Version、持久化 Evaluation Run 和九类确定性 Evaluator 建立可复现的评测流程。
• Baseline 与质量门：比较成功率、评分、成本、延迟、覆盖率和逐 Case 变化，输出 PASSED、FAILED 或 NOT_EVALUATED。
• GitHub 回归检查：验签并幂等处理 GitHub App webhook，将可信事件转换为评测、 Comparison 和 Check Run。
• 契约优先：用 OpenAPI 3.1、JSON Schema、测试向量和追踪矩阵约束 SDK、后端与前端的一致性。

本地体验使用确定性的 mock Agent，不需要模型账号或付费云服务。

• Git 2.43+
• Docker Engine 26+ 与 Docker Compose v2
• Python 3.12+
• 至少 4 GB 可用内存和 5 GB 可用磁盘

git clone https://github.com/HangChi/SpringAgentOps.git
cd SpringAgentOps
python tools/quickstart/init_env.py
docker compose up --build --detach
docker compose --profile mock run --rm mock-agent

看到 MODEL trace verified: ... 后，打开 http://127.0.0.1:8080/projects/project-alpha/traces。列表中应出现 quickstart-agent； MySQL、后端和 ContentStore 只在 Compose 网络内运行，宿主机仅暴露 127.0.0.1:8080。

停止服务但保留 Trace 数据：

docker compose down

Starter 尚未发布到公共 Maven 仓库。先在当前仓库构建并安装本地快照：

./mvnw -pl sdk/spring-agentops-spring-boot-starter -am install

然后在 Spring Boot 应用中添加依赖：

<dependency>
  <groupId>io.springagentops</groupId>
  <artifactId>spring-agentops-spring-boot-starter</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

Starter 默认关闭，且默认不采集模型和工具内容：

springagentops:
  enabled: true
  endpoint: http://127.0.0.1:8080/api/v1/ingestion/traces:batch
  api-key: ${SPRINGAGENTOPS_API_KEY}
  environment: development
  service-name: ${spring.application.name}
  capture:
    content: false

flowchart LR
    App["Spring AI application"] --> Starter["SpringAgentOps Starter"]
    Starter --> Queue["Bounded telemetry queue"]
    Queue --> Ingestion["Trace Ingestion API"]
    Ingestion --> Store["MySQL + ContentStore"]
    Store --> Query["Trace Query API"]
    Query --> Console["React Trace Console"]

    Dataset["Immutable dataset versions"] --> Runner["Evaluation Runner"]
    Runner --> Evaluators["Built-in evaluators"]
    Evaluators --> Comparison["Baseline comparison"]
    Comparison --> Gate["Versioned quality gate"]

    GitHub["GitHub App webhooks"] --> Inbox["Verified inbox / outbox"]
    Inbox --> Runner
    Gate --> Check["GitHub Check Run"]

后端按 feature package 划分，禁止跨模块直接访问内部 Repository。大型内容通过可替换的 ContentStore 管理，Trace 写入使用事务与 Outbox 协调。设计细节见 平台架构和 ADR 索引。

功能实现以 specs/001 至 specs/015 的规格、契约和追踪矩阵为事实来源。

backend/       Trace、Dataset、Evaluation、GitHub 与安全模块
sdk/           Java SDK、Spring AI 适配和 Spring Boot Starter
frontend/      React Trace Console
specs/         平台与 Feature 规格、契约、任务和追踪矩阵
tools/         契约、文档、安全和发布校验工具
adr/           架构决策记录
docs/          使用、运维、参考与项目治理文档

Java、契约、文档和前端的常用验证命令：

./mvnw --batch-mode --no-transfer-progress test
python tools/contract-validation/validate_contracts.py
python -m unittest tools/docs/test_documentation_delivery.py
cd frontend
pnpm install --frozen-lockfile
pnpm test
pnpm build

涉及 MySQL 的 *IntegrationTest 需要 Docker。完整开发约束、按模块测试方式和 PR 要求见 贡献指南与贡献者开发路径。

一般问题请查阅支持渠道；安全漏洞必须按安全策略私密报告。