docs: 更新 openspec 规范文档

- 添加实现状态表格 - 更新配置规范 - 添加新的协议规范
2026-07-15 17:30:13 +08:00 · 2026-03-27 19:10:49 +08:00
parent 18bc37aaae
commit 14a1e37261
11 changed files with 190 additions and 12 deletions
--- 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 |
--- 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 |
--- 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)（消息处理框架）
+
 ## 架构

 ```
--- 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)（工具协议）
+
 ## 架构图

 ```
--- 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)（配置规范）
+
 ## 服务器配置

 ### 启动参数
--- 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）

 ### 配置域

--- 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 插件迁移
--- a/openspec/env.md
+++ b/openspec/env.md
@@ -4,7 +4,7 @@

 本文档定义 AstrBot 环境变量的规范，所有环境变量以 `ASTRBOT_` 为前缀。

-## 变量分类
+> 相关: [config.md](config.md)（配置规范）, [path.md](path.md)（路径规范）

 | 分类 | 前缀 | 说明 |
 |------|------|------|
--- 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

 ## 设计哲学
--- 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 服务器通过三个构建块提供功能：
--- 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)（环境变量）