本文档默认使用中文。类名、接口名、配置项、HTTP 字段、错误码和协议事件保留源码原名。
适用版本：
0.1.0-SNAPSHOT。发布状态：source-only pre-release，当前没有发布到 Maven Central 或 npm 公共仓库；本文中的 Maven 和 Browser 接入都以本仓库源码、本地 Maven Reactor 和 Starter 内置 Bundle 为前提。
文中的地址、账号、模型名、密钥和业务数据均为占位符。不要把占位符原样用于真实环境，也不要把任何真实凭据提交到仓库。
本文面向实际接入 PatchBridge Agent 的 Java、前端、平台安全和运维人员。阅读本文不要求先了解项目设计历史；当前实施状态以路线图为准，架构边界以架构总览和 ADR 为准，具体行为以当前源码和测试为准。
当前完成度、后续顺序与暂缓范围统一维护在《路线图与当前进度》。模块边界、六边形架构、显式状态机和设计模式的完整说明见《架构总览》与ADR 索引。
- 项目简介
- 快速开始：从零构建、启动 Demo、完成最短真实链路。
- 从源码构建：Java、Web 与 Starter 内置 Bundle 的完整构建步骤。
- 接入 Spring Boot 2 Starter：引入依赖、准备数据库、配置模型、声明 Tool、最小页面入口。
- 接入 Browser：Headless Controller 与默认 Widget 的接入方式。
- Demo 使用与验收：Demo 启动、入口、角色和逐项验收路径。
- Java Tool 开发：
@AiTool/@AiParam、Schema 边界、调用与重试。 - Java 后端模型调用：
ModelGateway单次调用文本、图片、异步、取消与宿主自行保存。 - 生产接入准备、身份权限与排障：
CurrentUserProvider、ToolAccessPolicy、owner 隔离、Admin 权限、安全上线检查、故障处理。
- 前端 Tool：页面注册 Browser Local Tool、Schema 校验和执行边界。
- WebMCP Adapter：接入
document.modelContext。 - Tools Inspector：只读查看当前 Tool 目录与执行快照。
- Call Trace：按 Execution 查看模型、Tool、确认、耗时与 token。
- 定制默认 Widget 样式：CSS Variables、
::part()、theme="none"。
- Global MCP 与 Admin：properties/JDBC 配置、凭据加密、管理台使用。
@patchbridge-agent/agent：Headless 浏览器核心。@patchbridge-agent/widget：默认参考 Web Component。
以下内容只作为历史背景保留，不代表当前行为：
下表是 v0.1 当前已完成并可通过 Demo 或底层验证观察的能力摘要：
| 能力 | 设计目的 | Demo 入口 |
|---|---|---|
| Global MCP 配置 | 让后端统一保管远程 MCP endpoint 与凭据，运行时热更新 Tool 路由 | /ai-admin/ 的 MCP 管理区（Demo 空库首启自动预置麦当劳 MCP 示例 mcd：无凭据、默认停用，在管理区编辑认证为 bearer 并填入令牌后启用） |
| 纯前端 Tool | 直接复用页面状态、前端 Service 或已有 HTTP API，不经过 /ai/tools/call |
首页注册的 frontend.device_search |
| WebMCP Adapter | 把浏览器 document.modelContext Tool 接到同一 Agent，而不污染核心包 |
首页 WebMCP 状态；支持时注册 page.open_tools_tab |
| Tools Inspector | 只读展示 Agent 当前真正可调用的全部 Tool | 首页“Tools 调试”页签 |
| Call Trace | 按 Execution 展示模型/Tool/确认调用细节、耗时与 token；显式开启 persistent 后在浏览器本地保留 | 首页“调用轨迹”页签（Demo 显式开启） |
| Widget 样式扩展 | 框架提供参考 View，但颜色、字体、尺寸和结构样式由宿主决定 | Demo 用 CSS Variables 与 ::part 覆盖默认主题 |
| 厂商中立 Runtime | 用 Message + ContentBlock、ModelState、结构化流和独立 Execution 承载可替换 Agent Loop，并以五项资源预算、唯一终态门和严格 Tool 批次预检限定执行 | 首页 Runtime 扩展状态、HITL、停止按钮、max-tokens 提示和会话恢复 |
| Java 后端单次模型调用 | 让宿主 Service 复用同一 Provider 发起一次模型请求，不引入后端 Agent Loop 或默认持久化 | /demo-api/model-invocations/text 与 /demo-api/model-invocations/image |