refactor: delete _internal

remove deprecated API modules and example scripts; update core modules (agents, providers, tools, platform adapters, utils), dashboard package and components, and unit tests.
2026-07-20 10:57:22 +08:00 · 2026-04-23 04:16:30 +08:00
parent 33ec7bbf9c
commit c4048bb8eb
72 changed files with 5906 additions and 6453 deletions
--- a/openspec/agent-message.md
+++ b/openspec/agent-message.md
@@ -1,366 +0,0 @@
-# Agent 消息处理流程规范
-
-## 概述
-
-本文档定义 Agent 层消息处理的设计规范与契约（语言中立）。目标是提供一套清晰的、可实现的消息流、缓冲、流控、工具调用与安全策略，使不同语言或运行时实现都能遵循统一语义与行为。
-
-注意事项：
- 本文档只描述设计与接口语义，不绑定任何具体实现语言或特定库。
- 所有数据结构应为可序列化格式（例如 JSON），便于跨进程或跨语言传输与测试。
- 实现必须清楚描述并发语义、错误处理、资源释放与边界情况。
-
---
-
-## 目录（概要）
-
-1. 工具、技能与 Agent 协作体系  
-2. 输入缓冲区（Input Buffer）  
-3. 流控引擎（Flow Control）  
-4. Agent 核心（Context 管理与运行时）  
-5. 工具调用策略（Tool Calling Strategy）  
-6. 安全层（Security）  
-7. 权限模型（Permission）  
-8. 输出缓冲区（Output Buffer）  
-9. 记忆管理（Memory）  
-10. 平台适配（Platform Adaptation）  
-11. 配置汇总  
-12. 错误处理与恢复  
-13. 扩展点与插件接口
-
---
-
-## 1. 工具、技能与 Agent 协作体系
-
-设计要点：
- 将工具（internal）、外部工具（MCP/remote）、技能（skills）视为统一的“工具集”层级。Agent 在执行时向工具集发起调用，由工具路由器（Tool Router）负责选择与调度。
- 支持多来源工具合并：本地内建工具、注册的外部 MCP 服务器、可加载的 skills。
- 提供工具元数据（schema、并发限制、超时、权限要求），以支持运行时决策。
-
-接口示例（语言中立签名）：
- `ToolRouter.register_internal_tool(name: str, schema: dict) -> None`
- `ToolRouter.register_mcp_server(name: str, endpoint: dict) -> None`
- `ToolRouter.route_tool_call(call: {name: str, arguments: dict}) -> {status: str, result: any}`
-
-工具选择策略应考虑：
- 优先级（internal > skill > mcp 可配置）
- 并发与速率限制
- 依赖关系（某些工具需按顺序调用）
- 权限与安全策略
-
-Agent 协作（ACP）：
- 定义 Agent-to-Agent 调用契约（例如 RPC/HTTP/消息队列），包含调用接口、超时、重试与鉴权。
- 上层应能发现已注册 Agent 实例并列出其能力（capabilities）。
-
---
-
-## 2. 输入缓冲区（Input Buffer）
-
-目标与语义：
- 输入缓冲负责按会话或用户分隔消息队列，支持优先级、分段消息与限流。
- 缓冲应支持批出队和基于策略的溢出处理。
-
-核心数据模型（语言中立描述）：
- InputMessage（示例字段）:
-  - `message_id` (string): 全局唯一 ID
-  - `platform` (string)
-  - `user_id` (string)
-  - `conversation_id` (string)
-  - `content` (object/string)
-  - `timestamp` (ISO8601)
-  - `metadata` (dict)
-  - `priority` (int)
-
-缓冲配置要点：
- `max_queue_size`: 每用户/会话的最大消息数
- `max_message_age`: 消息超期策略
- `overflow_strategy`: [DropOldest, DropNewest, Block]
- `per_user_queue` / `per_conversation_queue` 可配置
-
-行为契约：
- `enqueue_message(msg: InputMessage) -> message_id`：如果队列已满，按 `overflow_strategy` 决定是丢弃、阻塞或返回错误。
- `dequeue_messages(limit: int) -> list[InputMessage]`：批量出队以提高吞吐。
- `get_queue_depth(session_id: str) -> int`
- `clear_queue(session_id: str) -> None`
-
-实现建议：
- 使用分段锁或细粒度并发结构避免全局锁。
- 明确队列边界与持久化选项（内存/磁盘/数据库）。
-
---
-
-## 3. 流控引擎（Flow Control）
-
-目标：
- 在全局与会话层实现速率限制，保护上游 LLM 提供方与下游平台，避免突发流量导致超限或费用高涨。
-
-常见策略：
- 令牌桶（Token Bucket）与漏桶
- 按 API-key / 会话 / 平台 的分层限流
- 自动限流（根据错误率或响应延迟自适应）
-
-接口契约：
- `set_rate_limit(scope: str, requests: int, period_seconds: float) -> None`
- `acquire(scope: str) -> bool`（非阻塞）
- `wait_for_token(scope: str, timeout_seconds: float) -> bool`（阻塞/等待）
-
-配置细节：
- `safety_margin`：预留给突发重试的额外容量
- `min_interval` / `max_interval`：自适应限流的上下界
-
-实现建议：
- 在高并发场景下使用原子操作或专用速率库实现高性能令牌桶。
- 将统计和指标暴露用于监控与告警。
-
---
-
-## 4. Agent 核心（Agent Core）
-
-职责：
- 管理用户会话上下文（context）、系统提示、工具与内存（memory）。
- 执行 Agent 的消息处理循环：接收输入 → 权限检查 → 安全过滤 → 工具调用决策 → LLM 调用 → 输出分发。
-
-核心概念：
- AgentContext:
-  - `messages`: 历史消息列表（按时间排序）
-  - `system_prompt`: 系统级提示
-  - `tools`: 可用工具清单与元数据
-  - `memory`: 与会话关联的记忆项
-  - `metadata`: 额外上下文信息
-
-行为契约：
- `ContextManager.build_context(agent_id, recent_messages, limit) -> context_payload`
- 支持上下文压缩（compress）策略以控制 tokens/长度（例如 summarize、truncate_by_turns 等）
- 明确并文档化 `max_context_length` 的单位（tokens / characters / turns）
-
-实现建议：
- 提供异步构建上下文接口（以避免阻塞事件循环）
- 将上下文管理与存储分离（缓存 + 后端存储）
-
---
-
-## 5. 工具调用策略（Tool Calling Strategy）
-
-目标：
- 定义工具调用的执行策略（并行/顺序/失败重试/超时/回退）。
- 管理工具依赖、分组与并行度。
-
-配置要点：
- `strategy`: e.g., "sequential", "parallel", "dependency-aware"
- `max_calls_per_request`
- `timeout`（每个工具调用）
- `max_retries`, `retry_backoff`
- `parallel_calls`, `max_parallel_calls`
-
-行为契约：
- `execute_tools(request_id: str, calls: list[ToolCall]) -> list[ToolResult]`
- 工具调用结果应包含：`id`, `name`, `status`（success/fail/timeout）, `result`, `error`（可序列化）
-
-工具选择策略示例：
- 优先最近使用（recency boost）
- 按相关度和能力（schema matching）选择 best-fit 工具
- 避免超过并发与配额限制
-
-实现建议：
- 提供工具调用审计日志，支持回放与重试。
- 在并行执行时以安全方式聚合结果并保证顺序语义（如需要）。
-
---
-
-## 6. 安全层（Security Layer）
-
-目标：
- 在输入与输出路径实现注入检测、内容过滤、敏感信息屏蔽与泄露防护。
-
-策略：
- 使用可配置的检测规则集合（正则、关键字、模式、ML-based classifier）
- 在发现注入时根据策略选择动作：`block`, `warn`, `sanitize`, `redact`
- 对输出执行隐私检测（例如屏蔽 secrets、标识个人信息）
-
-接口契约：
- `SecurityFilter.filter_messages(messages: list, mode: str) -> {filtered_messages, detections}`
- `SecurityFilter.filter_output(output: str) -> {safe_output, detections}`
-
-实现建议：
- 将规则编译为高效匹配结构，避免在高吞吐下成为瓶颈。
- 为检测提供事件与审计日志，便于事后分析。
-
---
-
-## 7. 权限模型（Permission Model）
-
-设计目标：
- 提供基于角色的权限模型（RBAC），支持命令级权限、会话级白名单/黑名单与资源配额。
-
-要点：
- 角色（Owner, Admin, Member, Guest, Blocked）
- 权限项（capabilities）可细粒度到 API/命令/工具
- 会话级别覆盖全局策略
-
-接口契约：
- `RoleManager.get_role(user_id, conversation_id) -> Role`
- `PermissionMiddleware.check_message(event, context) -> PermissionResult {allowed: bool, reason: str}`
-
-实现建议：
- 提供默认策略并允许动态配置、继承与角色映射。
- 在权限拒绝处返回可展示的用户提示语以改善用户体验。
-
---
-
-## 8. 输出缓冲区（Output Buffer）
-
-职责：
- 管理对外发送的消息队列与分发策略（streaming, segmented, full）。
- 提供按会话的结果队列、流式发送以及平台适配。
-
-数据模型：
- OutputMessage:
-  - `session_id`, `content`, `format` (plain/markdown/html), `strategy` (streaming/segmented/full), `metadata`
-
-接口契约：
- `enqueue_result(session_id, result) -> result_id`
- `dequeue_result(session_id) -> OutputMessage | None`
- `set_dispatch_strategy(session_id, strategy)`
-
-输出策略：
- Streaming：分片推送，适合实时交互
- Segmented：根据语言/句子边界分段发送
- Full：一次性发送完整响应
-
-实现建议：
- 分段器（Segmenter）应支持语言与平台特定规则。
- 提供 backpressure 机制避免下游拥堵。
-
---
-
-## 9. 记忆管理（Memory Management）
-
-目标：
- 支持短期工作记忆（working）与长期记忆（semantic）存储与检索。
- 提供记忆压缩、摘要与定期清理策略。
-
-配置要点：
- `backend`：sqlite/redis/remote vector DB 等
- `retention`、`auto_summary_threshold`、`working_memory_days`
-
-接口契约：
- `MemoryBank.add(entry) -> entry_id`
- `MemoryBank.search(query, top_k) -> list[MemoryEntry]`
- `MemoryBank.summarize_old() -> None`
-
-实现建议：
- 支持 embedding 存储与检索（若使用 vector DB）。
- 在写路径增加去重与重要性评分。
-
---
-
-## 10. 平台适配（Platform Adaptation）
-
-目标：
- 将抽象输出与行为适配到不同平台（Telegram, Discord, Webchat 等），考虑平台最大长度、支持的格式、mention/quote 行为。
-
-要点：
- 平台能力描述（supports_streaming, max_message_length, supports_markdown, supports_mentions...）
- 平台策略选择器负责为特定平台选择最合适的输出策略与格式。
-
-接口契约：
- `PlatformAdapter.render(output_message, platform_capabilities) -> platform_payload`
-
-实现建议：
- 将平台特性维护为可配置字典，并提供测试矩阵。
-
---
-
-## 11. 配置汇总
-
-重要配置域：
- `input_buffer`, `flow_control`, `context`, `tool_calling`, `security`, `output`, `memory` 等
- 优先级：环境变量 > secrets > 用户配置 > 默认值
-
-建议：
- 使用 JSON Schema 或等价方案为每个配置文件定义 schema，便于验证与 UI 生成。
-
---
-
-## 12. 错误处理与恢复
-
-分类：
- RateLimit, Timeout, Network, Api, Tool, Security, Internal
-
-策略：
- 为每个错误类型定义可配置的动作（Retry, Fail, Block, Fallback）
- 提供统一的错误对象：
-  - `{ code: int, name: str, message: str, details: dict }`
-
-行为契约：
- 所有对外接口在失败时返回结构化错误，调用者不得假定隐式成功。
- 关键路径应提供幂等性保证（或文档化其非幂等行为）。
-
-实现建议：
- 在工具调用与 LLM 请求路径实现可配置的重试策略与指数退避。
- 在错误统计与监控系统中上报错误码与聚合指标以便告警。
-
---
-
-## 13. 扩展点（Plugins / Hooks）
-
-支持点：
- InputBufferPlugin：pre_add_message / post_add_message
- OutputBufferPlugin：pre_send_message / post_send_message
- SecurityPlugin：check_injection / filter_content
- Scheduler 插件：自定义调度器选择下一个消息
-
-契约：
- 插件通过稳定的接口注册并被沙箱化执行（若属于同一进程，需明确资源与权限边界）。
- 插件注册表应保留版本与能力元数据，支持热加载/卸载。
-
---
-
-## 调试、测试与验证建议
-
- 提供端到端回环（loopback）transport 与“虚拟工具”以在 CI 中进行集成测试。
- 为每个模块（缓冲、流控、工具调用、安全）编写单元与压力测试用例，覆盖边界条件（队列溢出、速率突变、工具超时）。
- 导出丰富的指标（队列深度、工具调用延迟、错误计数、令牌消耗），并在实现中保持可观测性（logs, traces, metrics）。
- 实现一致的日志格式与结构化事件，便于聚合与分析。
-
---
-
-## 可序列化示例数据模型（JSON Schema 风格，语言中立）
-
-InputMessage（示例字段说明）：
- `message_id`: string
- `platform`: string
- `user_id`: string
- `conversation_id`: string
- `content`: object | string
- `timestamp`: ISO8601 string
- `metadata`: object
- `priority`: integer
-
-ToolCall（请求示例）：
- `id`: string
- `name`: string
- `arguments`: object
-
-ToolResult（返回示例）：
- `id`: string
- `name`: string
- `status`: "success" | "fail" | "timeout"
- `result`: any
- `error`: { code: int, message: string } | null
-
-ErrorObject（统一错误）：
- `code`: int
- `name`: string
- `message`: string
- `details`: object | null
-
---
-
-结束语
-
-本规范为语言中立的 Agent 层消息处理设计文档，旨在为实现方（无论使用何种语言/运行时）提供统一的接口、数据模型与行为约定。实现时请务必补充：
- 具体实现细节（并发原语、线程模型或事件循环策略）
- 绑定/序列化策略（如何在不同进程或语言之间传输数据）
- 运行时监控与故障恢复方案
-
-如需我把本规范中的某个模块进一步细化成接口定义、JSON Schema 或示例调用序列（包含错误路径），告诉我具体模块与目标实现语言/环境（例如 Python 异步服务、Go 微服务、或独立进程插件），我会继续输出详细设计。
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -1,118 +0,0 @@
-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 插件迁移