mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-16 01:40:15 +08:00
bc01532e59
`abort_signal` (asyncio.Event) is passed via **kwargs into payloads during tool_call streaming, causing "Object of type Event is not JSON serializable" when the OpenAI client tries to serialize the request body. Regression test added: test_prepare_chat_payload_strips_non_json_serializable_kwargs
119 lines
5.4 KiB
YAML
119 lines
5.4 KiB
YAML
schema: spec-driven
|
||
|
||
# 项目版本
|
||
version: "4.16.0"
|
||
|
||
# 规范实现状态
|
||
|
||
| 规范 | 文件 | 状态 |
|
||
|------|------|------|
|
||
| Rust 核心运行时 | `astrbot/rust/` | ⚠️ 仅编译产物，无源码 |
|
||
| ABP 插件协议 | `abp.md` | ⚠️ 规范完善（新增序列化+SDK），待实现 |
|
||
| 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 (胶水层), **Rust (核心运行时)**, anyio (Python 异步), pytest, ruff, uv
|
||
领域: 多平台 LLM 聊天机器人框架 (QQ, Telegram, Discord 等)
|
||
架构: **Rust 核心 + Python 胶水层**，基于协议的系统 (LSP, MCP, ACP, ABP)
|
||
|
||
# artifact 规则
|
||
rules:
|
||
tasks:
|
||
- 任务拆分为最大2小时块
|
||
- 新功能必须编写测试
|
||
- 提交前运行 ruff 和 pytest
|
||
code:
|
||
- 使用绝对导入，前缀 `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 (客户端，仅调用远程 Agent), ABP (客户端+服务端)。
|
||
Runtime 协调协议，Gateway 提供 HTTP API 后端（见 api.md）。
|
||
FFI 接口规范见 rust-ffi.md。
|
||
async_library: |
|
||
Python 胶水层使用 anyio 作为异步库。
|
||
Rust 核心内部使用 tokio 异步运行时。
|
||
coverage: |
|
||
必须提高覆盖率测试。
|
||
type_checking: |
|
||
Python 代码必须通过 `uvx ty check` (astral 的 pyright)。
|
||
避免使用 Any 和 cast。
|
||
code_style: |
|
||
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），可跨语言 |
|
||
| 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.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 插件迁移
|