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 插件迁移