diff --git a/openspec/a2a.md b/openspec/a2a.md index 53d6bfdde..e16470aa3 100644 --- a/openspec/a2a.md +++ b/openspec/a2a.md @@ -9,6 +9,16 @@ A2A 得到了超过 50 家技术合作伙伴（如 Atlassian, Box, Cohere, Langc A2A 专注于"互联互通"，与 ACP（Agent Communication Protocol）形成互补关系。 +## 实现状态 + +| 组件 | 状态 | 说明 | +|------|------|------| +| A2A Client | ❌ 不计划 | 作为参考协议，不做实现 | +| A2A Server | ❌ 不计划 | 参考文档 | +| AgentCard 发现 | ❌ 不计划 | - | + +> 相关协议: [ACP](acp.md)（本地 Agent 通信）, [agent-message](agent-message.md)（消息处理框架） + ## 与 ACP 的互补关系 | 维度 | A2A | ACP | diff --git a/openspec/abp.md b/openspec/abp.md index 8506f4d4d..566c91ec4 100644 --- a/openspec/abp.md +++ b/openspec/abp.md @@ -10,6 +10,22 @@ ABP 采用**插件作为独立服务**的设计，插件通过配置加载，可 - **数据目录由主进程分配**：插件的数据存储目录由主进程在握手时告知 - **零侵入性**：插件无需了解 AstrBot 内部结构 +> **⚠️ 实现说明**：ABP 协议的核心实现（握手、消息路由、生命周期管理）在 Rust 核心运行时中。 +> 插件本身可使用任意语言实现，只需遵循 ABP 协议即可。 +> 进程内插件（`load_mode: in_process`）示例使用 Python，但核心逻辑由 Rust 承担。 + +## 实现状态 + +| 组件 | 状态 | 说明 | +|------|------|------| +| ABP 握手协议 | ⚠️ 待实现 | Rust 核心尚未提交源码 | +| out_of_process 插件加载 | ⚠️ 待实现 | stdio/Unix Socket/HTTP 传输 | +| in_process 插件接口 | ⚠️ 待实现 | Python 插件示例待迁移到 Rust | +| 配置 Schema 生成 | ⚠️ 待实现 | UI 配置表单生成 | +| 插件生命周期管理 | ⚠️ 待实现 | start/stop/reload | + +> 相关协议: [MCP](mcp.md)（工具/数据源连接）, [agent-message](agent-message.md)（消息处理框架） + ## 与 MCP 的关系 | 维度 | ABP | MCP | diff --git a/openspec/acp.md b/openspec/acp.md index e408b13bc..7730af862 100644 --- a/openspec/acp.md +++ b/openspec/acp.md @@ -8,6 +8,17 @@ AstrBot 将 ACP 实现为**客户端**，连接到暴露智能体能力的 ACP **参考**: 受 [Google A2A](https://google-a2a.10140099 .io/) (Agent-to-Agent Protocol) 启发 +## 实现状态 + +| 组件 | 状态 | 说明 | +|------|------|------| +| ACP 客户端 | ⚠️ 待实现 | 尚未在 Rust 核心中实现，Python 层无 ACP 客户端 | +| JSON-RPC 2.0 编解码 | ⚠️ 待实现 | - | +| 连接池管理 | ⚠️ 待实现 | - | +| 流式响应 | ⚠️ 待实现 | - | + +> 相关协议: [A2A](a2a.md)（Google 发起，定位互补）, [agent-message](agent-message.md)（消息处理框架） + ## 架构 ``` diff --git a/openspec/agent-message.md b/openspec/agent-message.md index 287015a9a..8bea0b1db 100644 --- a/openspec/agent-message.md +++ b/openspec/agent-message.md @@ -10,6 +10,24 @@ AstrBot Agent 采用**双缓冲区 + 流控**的消息处理模型，实现消 - **流控引擎**：根据 API 限制自动调节消费速率 - **安全层**：防注入、防泄密、防误触 +> **⚠️ 实现说明**：本文档中的所有 Rust 代码块（```rust）是 Rust 核心运行时的**实现规范**， +> 实际代码位于 `astrbot/rust/`（尚未提交源码）。 +> Python 胶水层通过 FFI 调用 Rust 核心，不得在 Python 层重复实现核心逻辑。 + +## 实现状态 + +| 组件 | 状态 | 说明 | +|------|------|------| +| 双缓冲区模型 | ⚠️ 待实现 | 输入/输出缓冲区尚未 Rust 实现 | +| 流控引擎 | ⚠️ 待实现 | 限流策略未迁移到 Rust | +| 安全层 | ⚠️ 待实现 | 防注入/泄密未 Rust 实现 | +| ToolRouter | ⚠️ 待实现 | Internal/MCP/Skills 路由未 Rust 实现 | +| ACPAgentClient | ⚠️ 待实现 | ACP 调用未 Rust 实现 | +| SkillExecutor | ⚠️ 待实现 | Skill 执行未 Rust 实现 | +| Agent Loop | ⚠️ 待实现 | LLM Loop 未 Rust 实现 | + +> 相关: [ABP](abp.md)（插件协议）, [ACP](acp.md)（Agent 通信）, [MCP](mcp.md)（工具协议） + ## 架构图 ``` diff --git a/openspec/api.md b/openspec/api.md index b9cb2e4b5..bc2f206ad 100644 --- a/openspec/api.md +++ b/openspec/api.md @@ -10,6 +10,29 @@ AstrBot 提供 HTTP API 服务器，用于第三方应用集成。支持 API Key - 文件上传/下载 - 主动消息推送 +> ⚠️ **实现说明**：实际 HTTP 服务器使用 **Quart + Hypercorn**（ASGI），非 FastAPI。 +> API 路由位于 `astrbot/dashboard/routes/open_api.py`。 +> api.md 描述的是**目标规范**，当前实现可能存在偏差，需逐步对齐。 + +## 实现状态 + +| 端点 | 状态 | 实际路径 | +|------|------|----------| +| `GET /api/v1/im/bots` | ✅ 已实现 | `open_api.py` | +| `POST /api/v1/file` | ✅ 已实现 | `open_api.py` | +| `GET /api/v1/file` | ✅ 已实现 | `open_api.py` | +| `POST /api/v1/chat` | ✅ 已实现 | `open_api.py` | +| `GET /api/v1/chat/sessions` | ✅ 已实现 | `open_api.py` | +| `POST /api/v1/im/message` | ✅ 已实现 | `open_api.py` | +| `GET /api/v1/configs` | ✅ 已实现 | `open_api.py` | +| SSE 流式响应 | ✅ 已实现 | `open_api.py` | +| Webhook 回调 | ⚠️ 待实现 | - | +| API Key 权限体系 | ⚠️ 部分实现 | 仅基础校验 | +| SSL/TLS | ⚠️ 待实现 | - | +| 速率限制 | ⚠️ 待实现 | - | + +> 相关: [path.md](path.md)（路径规范）, [env.md](env.md)（环境变量）, [config.md](config.md)（配置规范） + ## 服务器配置 ### 启动参数 diff --git a/openspec/config.md b/openspec/config.md index b49c50f5a..4c3a8add0 100644 --- a/openspec/config.md +++ b/openspec/config.md @@ -11,7 +11,7 @@ AstrBot 配置系统遵循以下原则： | **环境变量优先** | 密钥通过环境变量注入，不写入配置文件 | | **分层配置** | 系统配置 → 平台配置 → 插件配置 | -## 配置分类 +> 相关: [env.md](env.md)（环境变量）, [path.md](path.md)（路径规范）, [api.md](api.md)（HTTP API） ### 配置域 diff --git a/openspec/config.yaml b/openspec/config.yaml index 57735b05b..a57c0d301 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,10 +1,31 @@ schema: spec-driven +# 项目版本 +version: "4.16.0" + +# 规范实现状态 + +| 规范 | 文件 | 状态 | +|------|------|------| +| Rust 核心运行时 | `astrbot/rust/` | ⚠️ 仅编译产物，无源码 | +| ABP 插件协议 | `abp.md` | ⚠️ 纯规范，待实现 | +| ACP Agent 通信 | `acp.md` | ⚠️ 纯规范，待实现 | +| MCP 客户端 | `mcp.md` | ⚠️ Python 层有简单封装 | +| LSP 协议 | `lsp.md` | ❌ 参考文档，不做实现 | +| A2A 协议 | `a2a.md` | ❌ 参考文档，不做实现 | +| HTTP API | `api.md` | ⚠️ 部分实现，使用 Quart 非 FastAPI | +| agent-message 消息模型 | `agent-message.md` | ⚠️ 纯规范，待 Rust 实现 | +| XDG 路径 | `path.md` | ⚠️ 部分实现，需对齐 | +| 环境变量 | `env.md` | ⚠️ 部分实现，需对齐 | +| 配置分层 | `config.md` | ⚠️ 规范存在，需落地 | + +状态说明: ✅ 已实现 | ⚠️ 部分实现/待实现 | ❌ 不计划 + # 项目上下文 context: | - 技术栈: Python 3.12, anyio (异步), ~~FastAPI~~, pytest, ruff, uv , rust + 技术栈: Python 3.12 (胶水层), **Rust (核心运行时)**, anyio (Python 异步), pytest, ruff, uv 领域: 多平台 LLM 聊天机器人框架 (QQ, Telegram, Discord 等) - 架构: 基于协议的系统 (LSP, MCP, ACP, ABP) + 架构: **Rust 核心 + Python 胶水层**，基于协议的系统 (LSP, MCP, ACP, ABP) # artifact 规则 rules: @@ -16,29 +37,81 @@ rules: - 使用绝对导入，前缀 `astrbot.` - 必须有类型标注（尽量避免 Any） - 注释使用英文 + - Rust 核心代码遵循 `cargo fmt` 和 `cargo clippy` + - FFI 函数签名必须与 rust-ffi.md 保持一致，不得擅自添加 commits: - 使用 conventional commits (feat:, fix:, docs:, refactor:, test:, chore:) # 项目最高旨意 directives: architecture: | + **核心运行时（Core Runtime）由 Rust 实现**，编译为 `astrbot/rust/_core.so`。 + Rust 核心职责：消息缓冲、限流、工具路由、Agent 协调、协议栈、进程管理。 + Python 负责：胶水层（胶水层调用 Rust 核心）、平台适配器、Stars 插件、WebUI、CLI。 新架构放在 _internal 包中，避免分支冲突。 - 协议系统: LSP (客户端), MCP (客户端+服务端), ACP (客户端+服务端), ABP (客户端+服务端)。 - Runtime 协调协议，Gateway 提供 FastAPI 后端。 - Stars 是插件 - Galaxy 是加载插件的中间层。 + 协议系统: LSP (客户端), MCP (客户端+服务端), ACP (客户端，仅调用远程 Agent), ABP (客户端+服务端)。 + Runtime 协调协议，Gateway 提供 HTTP API 后端（见 api.md）。 + FFI 接口规范见 rust-ffi.md。 async_library: | - 使用 anyio 作为异步库（不是 asyncio）。 + Python 胶水层使用 anyio 作为异步库。 + Rust 核心内部使用 tokio 异步运行时。 coverage: | 必须提高覆盖率测试。 type_checking: | - 代码必须通过 `uvx ty check` (astral 的 pyright)。 + Python 代码必须通过 `uvx ty check` (astral 的 pyright)。 避免使用 Any 和 cast。 code_style: | - 代码必须通过 `ruff check .` 和 `ruff format .`。 + Python 代码必须通过 `ruff check .` 和 `ruff format .`。 + Rust 代码必须通过 `cargo check` 和 `cargo fmt`。 execution: | 运行 Python 脚本必须使用 `uv run`，不要用裸 python。 + rust_core: | + Rust 源码目标路径 `astrbot/rust/src/`，由 Cargo.toml 管理依赖（尚未提交源码）。 + 当前仅有编译产物 `astrbot/rust/_core.so`（._core.pyi 提供类型注解）。 + Rust 核心通过 FFI 暴露接口给 Python 胶水层调用（详见 rust-ffi.md）。 + 源码提交时应包含: `src/lib.rs`、`src/orchestrator.rs`、`Cargo.toml`、`Cargo.lock`。 + internal_package: | + 新架构放在 `astrbot/_internal/` 包中，避免分支冲突。 + _internal/ 结构（目标）： + ``` + astrbot/_internal/ + ├── __init__.py + ├── abc/ # 抽象基类（Protocol） + ├── protocols/ # 协议实现（LSP/MCP/ACP/ABP） + │ ├── lsp/ + │ ├── mcp/ + │ ├── acp/ + │ └── abp/ + └── runtime/ # 运行时核心 + ├── orchestrator.py # 主协调器（胶水层） + └── ... + ``` + _internal/ 是新协议实现的 Python 胶水层，不含核心逻辑。 + 核心逻辑在 Rust，胶水层只做 FFI 调用和类型转换。 + terminology: | + | 术语 | 含义 | + |------|------| + | Star | Legacy 插件系统（`astrbot/builtin_stars/`），已被 ABP 取代 | + | ABP Plugin | 基于 ABP 协议的插件（见 abp.md），可跨语言 | + | Galaxy | 概念层，负责加载和管理 Stars/ABP 插件（尚未实现） | + | Gateway | HTTP API 网关（Quart + Hypercorn，见 api.md） | + | Tool | LLM 可调用的函数，分 Internal/MCP/Skills 三类 | + | Skill | 预构建的 Agent 执行流程模板 | + | Platform | 平台适配器（QQ/Telegram/Discord 等） | goal: | - 最终目标：实现 ABP 协议 + 最终目标：实现 ABP 协议（见 abp.md） 代码美观 类型标注完美 - 将现有功能迁移到新架构 + 将现有功能迁移到 Rust 核心 + Python 胶水层尽量轻薄，核心逻辑不过渡到 Python + + 依赖实现顺序（ Roadmap）： + 1. Rust FFI 接口规范化 → rust-ffi.md + 2. Rust 核心基础设施（错误码、日志、线程安全） + 3. ABP 协议核心（握手、生命周期、消息路由） + 4. ABP 传输层（Stdio → Unix Socket → HTTP/SSE） + 5. 工具路由（Internal Tool → MCP Client → Skills） + 6. 双缓冲区消息模型（输入缓冲 → 输出缓冲 → 流控） + 7. Agent 协调（LLM Loop → Tool Executor → Subagent Orchestrator） + 8. ABP 插件加载器（InProcess → OutOfProcess） + 9. Stars → ABP 插件迁移 diff --git a/openspec/env.md b/openspec/env.md index 574c7b9c0..c04f1f1c7 100644 --- a/openspec/env.md +++ b/openspec/env.md @@ -4,7 +4,7 @@ 本文档定义 AstrBot 环境变量的规范，所有环境变量以 `ASTRBOT_` 为前缀。 -## 变量分类 +> 相关: [config.md](config.md)（配置规范）, [path.md](path.md)（路径规范） | 分类 | 前缀 | 说明 | |------|------|------| diff --git a/openspec/lsp.md b/openspec/lsp.md index 22f323664..803703a21 100644 --- a/openspec/lsp.md +++ b/openspec/lsp.md @@ -8,6 +8,16 @@ LSP（Language Server Protocol）是由 Microsoft 制定的开放协议，用于 **解决方案**：语言服务器在其自己的进程中运行，编辑器通过标准协议与之通信。只需实现一次语言服务器，即可集成到任何支持 LSP 的工具中。 +## 实现状态 + +| 组件 | 状态 | 说明 | +|------|------|------| +| LSP Client | ❌ 不计划 | AstrBot 不作为 LSP 客户端使用（用于 IDE 集成） | +| LSP Server | ❌ 不计划 | 作为 AI 编程助手，暂无语言服务器需求 | +| 参考文档 | ✅ 完成 | 本文档为 LSP 协议参考，不做实现 | + +> 相关协议: [A2A](a2a.md)（Agent 间通信）, [agent-message](agent-message.md)（消息处理框架） + **参考**：[Language Server Protocol](https://microsoft.github.io/language-server-protocol/) by Microsoft ## 设计哲学 diff --git a/openspec/mcp.md b/openspec/mcp.md index 31c7b93e4..25ba387b3 100644 --- a/openspec/mcp.md +++ b/openspec/mcp.md @@ -6,6 +6,19 @@ MCP（Model Context Protocol）是由 **Anthropic** 创建的开放协议，用 **核心定位**：MCP 为 AI 模型提供标准化的工具调用和上下文获取能力，类似于 USB 协议为设备提供的标准化连接方式。 +## 实现状态 + +| 组件 | 状态 | 说明 | +|------|------|------| +| MCP Client (Python) | ✅ 部分实现 | `astrbot/api/mcp.py` 有简单封装，非完整实现 | +| MCP Client (Rust) | ⚠️ 待实现 | 应迁移到 Rust 核心 | +| MCP Server | ❌ 不计划 | AstrBot 不托管 MCP 服务器 | +| Stdio 传输 | ⚠️ 待实现 | - | +| HTTP/SSE 传输 | ⚠️ 待实现 | - | +| Tools/Resources/Prompts | ⚠️ 待实现 | - | + +> 相关协议: [ABP](abp.md)（插件协议）, [ACP](acp.md)（Agent 通信）, [agent-message](agent-message.md)（消息处理框架） + ## 核心功能 MCP 服务器通过三个构建块提供功能： diff --git a/openspec/path.md b/openspec/path.md index c03145e7f..af2074ba9 100644 --- a/openspec/path.md +++ b/openspec/path.md @@ -8,6 +8,8 @@ AstrBot 遵循 [XDG Base Directory Specification](https://specifications.freedes - **Linux/macOS 桌面**：遵循 XDG 规范 - **Linux 服务器**：使用 `/var/lib/astrbot`（systemd 服务场景） - **Windows**：不遵循 XDG，使用 `%APPDATA%` / `%LOCALAPPDATA%` / `%USERPROFILE%` + +> 相关: [config.md](config.md)（配置规范）, [env.md](env.md)（环境变量） - **BSD/Unix**：遵循 XDG 规范 ## Linux 服务器场景 @@ -359,3 +361,5 @@ Claude Code 使用 `~/.claude/` 作为根目录，**不遵循 XDG 规范**： - Windows 平台**不遵循** XDG 规范，使用 Windows 标准路径 - 桌面客户端（packaged desktop runtime）使用 `~/.astrbot/` 作为数据根目录 + +> 相关: [config.md](config.md)（配置规范）, [env.md](env.md)（环境变量）