capstead

# Capstead **一款适用于 Spring Boot 的能力平台 — 适用于业务能力的注册、治理、版本控制和可观察性。** Capstead **不是**另一个 AI 框架。它是围绕您的 AI（Spring AI、LangChain4j 或其他）的一层治理层。您继续编写普通的 Spring Boot 方法；Capstead 将它们转换为**受管辖、可发现、可观察、版本化的业务能力** — 具有每个能力成本跟踪和预算 — 只需一个注解。 > Spring AI 告诉您一个模型调用。Capstead 告诉您**业务能力**：它运行的频率，使用了哪个模型，消耗了多少令牌，成本是多少，是否成功，以及执行了哪个版本。 📖 **[阅读研究：Spring Boot 中的 AI 能力治理 →](https://capstead.ai/research)** --- ## 为什么 现代应用程序在许多服务和团队中暴露 AI 能力，但没有人能回答：**存在哪些能力，谁拥有它们，哪个版本正在运行，成本是多少？** 像 Spring AI 和 LangChain4j 这样的框架在**执行**方面表现出色。Capstead 解决了**执行**之外的所有问题： | | Spring AI / LangChain4j | Capstead | |---|---|---| | 提供者抽象、结构化输出、工具调用 | ✅ | *重用它们* | | 能力注册 + 元数据 + **版本控制** | ❌ | ✅ | | `/actuator/capabilities` 发现 | ❌ | ✅ | | 一流的执行记录 + **成本/记分卡** | ❌（仅限每个模型调用） | ✅ | | 每个模型的**调用** + 父子执行**树** | ❌ | ✅ | | **持久**执行历史（JDBC）+ `/actuator/capabilityexecutions` | ❌ | ✅ | | **每日预算** 和治理 | ❌ | ✅ | | 强制提供者隐藏 | ❌ | ✅ | | 将能力导出为**受管辖的 MCP 工具** | ❌ | ✅ | --- ## 安装 ```xml <dependency> <groupId>io.capstead</groupId> <artifactId>capstead-starter</artifactId> <version>0.3.3</version> </dependency> ``` 就这样。自动配置连接了所有内容；除了注解方法外，无需进行代码更改。 --- ## 快速入门 注解任何 Spring Bean 方法： ```java @Service class LessonService { @Capability( name = "生成课程", domain = "EngineerPrep", owner = "内容团队", version = "2", tags = {"课程", "Java"} ) @DailyBudget("$25") public Lesson generateLesson(String topic) { // 您的普通逻辑 — 调用 Spring AI、LangChain4j 或其他 return chatClient.prompt().user(topic).call().entity(Lesson.class); } } ``` 现在访问执行器： ``` GET /actuator/capabilities # 目录：名称、领域、所有者、版本、标签 GET /actuator/capabilityscorecard # 调用次数、成功率、延迟、令牌、成本 GET /actuator/capabilityexecutions # 执行历史：ID、父级、每个模型的调用 GET /actuator/capabilitymetrics # Micrometer 支持的统计数据（Prometheus 就绪） ``` …and 打开仪表盘： ``` http://localhost:8080/capstead/ ``` 在 `application.yml` 中公开端点： ```yaml management: endpoints: web: exposure: include: capabilities,capabilityscorecard,capabilitymetrics,capabilityexecutions ``` --- ## 三种声明能力的方式 Capstead 支持**所有三种**样式 — 在同一个应用程序中混合和匹配。 **1. 注解** — 在方法上添加 `@Capability`（如上所示）。最适合您拥有代码并希望在代码旁边声明。 **2. 配置（YAML）** — 在**不触及 Bean** 的情况下声明能力，适用于第三方或通用命名的方法（`generate` / `ask` / `review`），或者您希望避免在领域代码中使用注解： ```yaml capstead: capabilities: - name: "生成课程" bean: lessonService # Spring Bean 名称 method: generate # 要治理的方法 domain: 学习 owner: 内容团队 version: "2" tags: [课程] # parameter-types: [java.lang.String] # 仅用于消除重载方法的歧义 ``` **3. 声明式** — **不编写任何代码**。注解一个**接口**方法与 `@Capability` + `@Prompt`，Capstead 生成实现（渲染提示、路由模型、调用 Spring AI、绑定结果）— 然后像其他能力一样对其进行治理： ```java @CapabilityClient @ModelProfile("reasoning") public interface LessonCapability { @Capability(name = "生成课程", domain = "学习") @Prompt("为 {{topic}} 生成 Java 课程") Lesson execute(String topic); // 没有正文 — Capstead 编写 } ``` 模型路由通过配置文件驱动，因此能力代码永远不会命名模型： ```yaml capstead: ai: profiles: reasoning: { model: us.anthropic.claude-sonnet-4-6, temperature: 0.2 } ``` **与任何模型后端配合使用 — 不需要 Spring AI**。Capstead 调用一个单独的 `CapabilityModelInvoker` Bean；您提供它（LangChain4j、提供者 SDK、普通 HTTP 客户端），或添加 `capstead-spring-ai` 以获取默认 Spring AI `ChatClient` 实现： ```java @Bean CapabilityModelInvoker modelInvoker(MyLlmClient llm) { return req -> llm.complete(req.model(), req.systemPrompt(), req.userPrompt()); } ``` 完整指南： [`docs/DECLARATIVE-CAPABILITIES.md`](docs/DECLARATIVE-CAPABILITIES.md). 如果一个方法被声明**超过一次**，则**注解优先**。还有一个基于规则的 `capstead.scan` 可以一次通过包 + 名称模式提升许多方法。参见使用每种样式的可运行示例 [`samples/`](samples/). --- ## 自动成本跟踪 Capstead **不** 自己测量令牌 — 它将 Spring AI 现有的令牌/模型数据**归因**于业务能力。添加桥接： ```xml <dependency> <groupId>io.capstead</groupId> <artifactId>capstead-spring-ai</artifactId> <version>0.5.0</version> </dependency> ``` 配置每个模型的定价（每百万令牌的价格）： ```yaml capstead: cost: models: claude-sonnet: input-per-million-tokens: 3.00 output-per-million-tokens: 15.00 ``` 现在，每个能力的记分卡显示实际的令牌计数和估计成本 — **您的代码中没有**。一旦达到能力的 `@DailyBudget`，进一步的调用将被 `CapabilityBudgetException` 阻止，直到第二天。 > 不使用 Spring AI？增强缝隙是开放的：调用 > `CapabilityExecutionContext.recordModelInvocation(model, inputTokens, outputTokens, cost)` > 每次模型调用，从您进行调用的任何地方 — Capstead 将每个调用归因于线程上正在执行的**能力**。 --- ## 持久执行记录器 每个 `@Capability` 调用成为一个具有唯一 ID 的一流 `CapabilityExecution` — 记分卡、预算和仪表盘构建的原子。在 `0.3.3` 中，记录器变得**持久且结构化**: - **每个模型的调用**。一个能力可能调用模型多次（重试、多步骤、扇出）。每次调用都捕获为一个 `ModelInvocation`（模型、令牌、成本、时间戳），因此成本**按模型**归因 — 而不仅仅是按能力。令牌/成本总数在调用之间求和。 - **执行树**。当一个 `@Capability` 调用另一个时，嵌套执行会自动链接到其父级（`parentExecutionId`）— 一个执行树，无需工作流引擎。 - **历史端点**。 ``` GET /actuator/capabilityexecutions # 最近的执行：ID、父级、时间、结果、调用 GET /actuator/capabilityexecutions/{id} # 一个执行 + 其嵌套能力调用 ``` - **记录模式**。`capstead.executions.recording-mode: best-effort`（默认 — 记录永远不会失败您的业务调用）` | 同步 | 异步`. - **默认隐私**。输入/输出**不**存储，除非您选择加入（`capstead.executions.capture-input` / `capture-output`），并且 `CapabilityDataRedactor` Bean 允许您剥离秘密/PII。执行归因于调用者与 `CapabilityPrincipalProvider`. ### 持久性（在重启期间存活，跨实例聚合） 内存存储有界且实例特定。添加 `capstead-jdbc` 以将每个执行（及其模型调用）持久存储到 Capstead 拥有的表中： ```xml <dependency> <groupId>io.capstead</groupId> <artifactId>capstead-jdbc</artifactId> <version>0.3.3</version> </dependency> ``` ```yaml capstead: jdbc: enabled: true retention-days: 90 # 0 = 永久保存 ``` Capstead 在启动时创建自己的架构（可在 PostgreSQL 和 H2 之间移植），以原子方式写入每个执行及其调用，然后在每日扫描时修剪旧行 — 因此记分卡和执行树在重启期间存活并跨每个实例聚合。 --- ## 将能力导出为 MCP 工具 Capstead 可以将您的受管辖能力发布为 [Model Context Protocol](https://modelcontextprotocol.io) （MCP）工具 — 因此 MCP 客户端（或 LLM）可以发现和调用它们，同时它们保持**版本化、所有者和预算强制执行**。普通的 MCP 工具没有这种治理；Capstead 将其贯彻到底。 ### 传输无关的工具模型 + 执行器 ```xml <dependency> <groupId>io.capstead</groupId> <artifactId>capstead-mcp</artifactId> <version>0.3.3</version> </dependency> ``` 每个 `@Capability` 成为一个 MCP 工具：一个稳定的 `name@version` 派生的工具 ID，一个从方法签名派生的 JSON 输入模式，以及一个 `governance` 块（所有者、领域、版本、标签）。添加两个执行器表面： ``` GET /actuator/capabilitymcp # 工具/列表 — 每个能力作为 MCP 工具 GET /actuator/capabilitymcp/{name} # 单个工具定义 POST /actuator/capabilitymcp/{name} # 工具/调用 — 正文 {"arguments": { ... }} ``` 调用通过能力的治理代理路由，因此 `@DailyBudget` 和执行记录适用于直接调用的确切方式。 ### 在实时 MCP 服务器上提供服务 要通过真正的 MCP 传输（STDIO、SSE、Streamable-HTTP）公开工具，请添加桥接器以及任何 Spring AI MCP 服务器启动器： ```xml <dependency> <groupId>io.capstead</groupId> <artifactId>capstead-mcp-server</artifactId> <version>0.3.3</version> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server</artifactId> </dependency> ``` `capstead-mcp-server` 注册了一个 Spring AI `ToolCallbackProvider`，由您的能力构建；MCP 服务器启动器发现它并自动提供每个能力： --- ## 生产中使用 Capstead 在 **[engineerprep.io](https://engineerprep.io)** 的生产环境中经过测试 — 一个 AI 驱动的技术面试准备平台，基于 Spring Boot。它管理大约十几个 AI 能力，跨两个领域 — **EngineerPrep** （课程、叙述、辅导）和 **Academy** （场景和可视化规划、主题和问题生成、审查、目录和 GitHub 仓库生成） — 并根据 **Anthropic Claude** 和 **Amazon Nova（Bedrock）** 的令牌成本分配成本，每个都可见于 `/capstead` 仪表盘、`/actuator/capabilityscorecard` 和 `/actuator/capabilityexecutions`。 大多数这些是从配置中声明的**无需触及 Bean 源** — Capstead 可以将现有的方法（甚至是通用命名的 `generate` / `ask` / `review`）提升为受管辖的能力： ```yaml capstead: capabilities: - { name: "生成叙述", bean: lessonNarrationGenerator, method: generate, domain: EngineerPrep, owner: 内容团队, tags: [课程, 叙述] } - { name: "课程辅导", bean: lessonTutorService, method: ask, domain: EngineerPrep, owner: 内容团队, tags: [辅导] } - { name: "问题审查", bean: questionReviewer, method: review, domain: Academy, owner: 内容团队, tags: [审查] } ``` 没有注解，没有代码编辑 — 每个方法成为一个受管辖、记分、预算强制执行的 capaiblity。（更喜欢注解？`@Capability` 和基于配置的声明共存；注解在冲突时获胜。） --- ## 架构 Capstead 用一个 Spring AOP 顾问包装每个能力，将每个调用转换为一个一流的、受管辖的 `CapabilityExecution` — 然后将其扩展到记录器并通过执行器、仪表盘和 MCP 暴露它。Capstead 自己永远不会执行模型；模型调用（您的或 Capstead 为声明式能力生成的模型）用模型、令牌和成本丰富正在进行的执行；嵌套调用形成一棵树。 ```mermaid flowchart TB subgraph App["您的 Spring Boot 应用程序"] direction LR Cap["@Capability 方法<br/>(您调用模型)"] Client["@CapabilityClient 接口<br/>(Capstead 调用模型)"] end subgraph Capstead["Capstead — 自动配置"] Advisor["能力 AOP 顾问<br/>(拦截器)"] Ctx["执行上下文<br/>(线程局部丰富)"] Registry["能力注册表<br/>(目录)"] Publisher["执行发布者"] end Model["模型调用<br/>Spring AI ChatClient · CapabilityModelInvoker · 您自己的客户端"] subgraph Recorders["记录器"] InMem["内存存储"] Micrometer["Micrometer 指标"] Jdbc["JDBC — 持久的,<br/>跨实例"] end subgraph Surfaces["治理表面"] Actuator["/actuator/capabilities<br/>/capabilityscorecard<br/>/capabilityexecutions"] Dashboard["/capstead 仪表盘"] Mcp["MCP 工具"] end Cap -->|调用| Advisor Client -->|代理| Advisor Advisor -->|包装/调用| Model Model -.->|模型 · 令牌 · 成本| Ctx Advisor --> Ctx Advisor -->|发布执行| Publisher Publisher --> InMem & Micrometer & Jdbc Registry --> Actuator InMem --> Actuator Jdbc --> Actuator Actuator --> Dashboard Registry --> Mcp ``` - **声明** 能力有三种方式 — 方法上的 `@Capability` 、配置（YAML）或无正文的 `@CapabilityClient` 接口。所有流都经过同一个顾问。 - **治理** — 顾问强制执行 `@DailyBudget`、计时调用并打开 `CapabilityExecution`。 - **丰富** — 调用模型（Spring AI 的观察桥接器、`CapabilityModelInvoker` 或您的客户端）将模型、令牌和成本记录到正在进行的执行中；嵌套调用形成树。 - **记录** — 执行分支到内存存储、Micrometer 和（可选）持久的 JDBC。 - **公开** — 注册表和记录器支持执行器端点、`/capstead` 仪表盘和 MCP 工具导出。 --- ## 模块 | 模块 | 目的 | |---|---| | `capstead-annotations` | `@Capability` 、 `@DailyBudget` — 依赖无关 | | `capstead-core` | 公共模型：`CapabilityMetadata` 、 `CapabilityExecution` 、 `CapabilityScorecard` | | `capstead-runtime` | 注册表、发现、执行捕获、成本、预算 | | `capstead-starter` | Spring Boot 自动配置 + 执行器端点 + 仪表盘 + **声明式能力** (`@CapabilityClient` ，提供者中立) | | `capstead-spring-ai` | 可选：来自 Spring AI 观察的令牌/模型归因 + 默认 Spring AI `ChatClient` 模型调用器，用于声明式能力 | | `capstead-mcp` | 可选：将能力导出为 MCP 工具 + `/actuator/capabilitymcp` | | `capstead-mcp-server` | 可选：通过 Spring AI `ToolCallbackProvider` 将能力服务于实时 MCP 服务器 | | `capstead-jdbc` | 可选：持久的、跨实例的执行 + 模型调用持久性，保留 | --- ## 设计原则 1. **提供者无关** — Capstead 从未在能力 API 中公开 `ChatClient` 、模型名称或令牌。启动器拒绝任何 `@Capability` ，其签名泄漏提供者类型。 2. **基于业务** — 您思考 *生成课程* 、 *批准付款* ，不是 *提示* 和 *温度* 。 3. **约定优于配置** — 一个注解公开受管辖的能力。 4. **Spring Boot 原生** — 自动配置、依赖注入、执行器、Micrometer。 --- ## 状态 `0.5.0`。开源核心已完成并测试：注册表、元数据、版本发现、一流的执行 **每个模型的调用和父子执行树** 、成本估算、每日预算、执行历史、执行器端点（目录、记分卡、指标、 **执行历史**）、仪表盘、Spring AI 桥接器、**提供者中立的声明式能力**（ `@CapabilityClient` — 与任何模型后端配合使用，通过 `CapabilityModelInvoker`）、MCP 导出（工具模型、执行器和 Spring AI MCP 服务器桥接器）和可选的 **JDBC 记录器** 用于持久的、跨实例的历史记录与保留。 ## 许可证 Apache License 2.0.