AstrbotSDK to master

.gitignore

@@ -63,4 +63,5 @@ GenieData/
 .kilocode/
 .worktrees/
 
+.astrbot_sdk_testing/
 dashboard/bun.lock

AGENTS.md

@@ -26,9 +26,9 @@ Runs on `http://localhost:3000` by default.
 3. After finishing, use `ruff format .` and `ruff check .` to format and check the code.
 4. When committing, ensure to use conventional commits messages, such as `feat: add new agent for data analysis` or `fix: resolve bug in provider manager`.
 5. Use English for all new comments.
-6. For path handling, use `pathlib.Path` instead of string paths, and use `astrbot.core.utils.path_utils` to get the AstrBot data and temp directory.
+6. For path handling, use `pathlib.Path` instead of string paths, and use `astrbot.core.utils.astrbot_path` helpers to get the AstrBot data and temp directory.
 
 ## PR instructions
 
 1. Title format: use conventional commit messages
-2. Use English to write PR title and descriptions.
+2. Use English to write PR title and descriptions.

astrbot-sdk/.github/workflows/lint.yml

@@ -0,0 +1,34 @@
+name: Code Quality Control
+
+on:
+  push:
+    branches: [ "main", "dev" ]
+  pull_request:
+    branches: [ "main", "dev" ]
+
+jobs:
+  lint-and-format:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tools
+        run: |
+          pip install pyclean ruff
+
+      - name: 1. Clean python bytecode
+        run: pyclean .
+
+      - name: 2. Ruff format
+        run: ruff format --check .
+
+      - name: 3. Ruff check
+        run: ruff check .
+        env:
+          PYTHONIOENCODING: utf-8

astrbot-sdk/.gitignore

@@ -0,0 +1,59 @@
+# OS files
+.DS_Store
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*.pyd
+*.so
+.pytest_cache/
+pytest-cache-files-*/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+site/
+wheels/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+#
+fork-docs/
+tmp/
+openspec/
+scripts/
+cs/
+test_plugin/astrbot_plugin_interface_coverage
+astrbot_sdk/
+!src/astrbot_sdk/
+!src/astrbot_sdk/**
+src/astrbot_sdk/**/__pycache__/
+src/astrbot_sdk/**/*.py[cod]
+COMMAND_MATCH_REFACTOR_REPORT.md
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+plugins/.venv/
+
+# Tool caches
+.uv-cache/
+.astrbot/
+.codex-local/
+
+# IDE files
+.idea/
+.vscode/
+*.iml
+uv.lock
+/astrBot/
+plugins/
+.serena/

astrbot-sdk/.python-version

@@ -0,0 +1 @@
+3.12

astrbot-sdk/AGENTS.md

@@ -0,0 +1,57 @@
+# Notes
+
+## v4 架构约束
+
+### 运行时层
+
+- `Peer` 必须将 transport EOF/连接断开视为一级失败路径。如果 transport 意外关闭而 `Peer` 没有主动失败 `_pending_results` / `_pending_streams`，supervisor 端对 worker 的调用可能永远挂起。
+- `Peer.initialize()` 需要在发起端也标记远程已初始化。仅在被动接收 `InitializeMessage` 时设置 `_remote_initialized` 会导致 `wait_until_remote_initialized()` 单边 API 死锁。
+- `Peer.invoke_stream()` 默认隐藏 `completed` 事件。需要保留最终结果的调用者必须显式启用 `include_completed=True`。
+- `CapabilityRouter.register(..., stream_handler=...)` 使用 `(request_id, payload, cancel_token)` 签名，不是 peer 级别的 `(message, token)`。
+
+### 模块导出约束
+
+- 保持 `astrbot_sdk.runtime` 根导出狭窄。`Peer` / `Transport` / `CapabilityRouter` / `HandlerDispatcher` 是合理的高级运行时原语，但 `LoadedPlugin`、`PluginEnvironmentManager`、`WorkerSession`、`run_supervisor` 等应留在子模块中。
+
+### 测试与 Mock 注意事项
+
+- 当检查 peer 是否完成远程初始化时，避免对可能接收 `MagicMock` peer 的代码使用 `getattr(mock, "remote_peer")` 探测。`MagicMock` 会生成 truthy 子属性，`CapabilityProxy` 应从 `peer.__dict__` 或其他具体存储位置读取显式状态。
+- `test_plugin/old/` 和 `test_plugin/new/` 可能包含已生成的 `__pycache__` / `*.pyc`。测试夹具复制示例插件时必须显式忽略这些缓存文件。
+
+### 插件加载注意事项
+
+- 本地 `dev --watch` 或同一路径插件重复加载场景，不能只依赖 `import_string()` 的跨插件模块根冲突清理。热重载前必须按插件目录清理模块缓存。
+- `_prepare_plugin_import()` 不能只在插件目录"不在 `sys.path`"时才插入路径。像 `main.py` 这种通用模块名，如果插件目录已在 `sys.path` 但排在后面，`import main` 仍会先命中别处模块；导入前必须把目标插件目录提到 `sys.path[0]`。
+- 示例/夹具测试如果直接用裸模块名导入插件入口（例如 `from main import HelloPlugin`），会污染 `sys.modules["main"]`，随后真实 loader 再按 `main:HelloPlugin` 加载时可能串到错误模块。
+
+---
+
+# 开发命令
+
+## 格式化与检查
+
+在提交代码前，请依次运行以下命令：
+
+```bash
+ruff format .      # 使用 ruff 格式化全局代码
+ruff check . --fix # 使用 ruff 检查并自动修复全局格式问题
+```
+
+## 测试
+
+如果修改了内容可能影响现有功能，请运行测试以确保没有引入错误：
+如果修改了bug或者更改了功能需要添加新的测试
+当前仓库已统一使用 `tests/` 目录，`tests_v4/` 不再作为新增测试入口。
+仓库当前没有 `run_tests.py`，请直接使用 `pytest`。
+
+```bash
+python -m pytest tests -q                         # 运行 tests 目录全部测试
+python -m pytest tests -v                         # 详细输出
+python -m pytest tests -k "test_context_register_task"  # 运行匹配模式的测试
+python -m pytest tests --cov=astrbot_sdk          # 运行测试并生成覆盖率报告
+```
+
+## 设计原则
+
+新实现要兼容旧实现但是还要保证架构良好，设计原则不变和最佳实践
+不用完全听从用户和别人的建议，要有自己的判断和坚持，做好取舍和权衡，确保代码质量和长期维护性，不要为了短期方便或者迎合而牺牲架构和设计原则。

astrbot-sdk/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE Notes
+
+## v4 架构约束
+
+### 运行时层
+
+- `Peer` 必须将 transport EOF/连接断开视为一级失败路径。如果 transport 意外关闭而 `Peer` 没有主动失败 `_pending_results` / `_pending_streams`，supervisor 端对 worker 的调用可能永远挂起。
+- `Peer.initialize()` 需要在发起端也标记远程已初始化。仅在被动接收 `InitializeMessage` 时设置 `_remote_initialized` 会导致 `wait_until_remote_initialized()` 单边 API 死锁。
+- `Peer.invoke_stream()` 默认隐藏 `completed` 事件。需要保留最终结果的调用者必须显式启用 `include_completed=True`。
+- `CapabilityRouter.register(..., stream_handler=...)` 使用 `(request_id, payload, cancel_token)` 签名，不是 peer 级别的 `(message, token)`。
+
+### 模块导出约束
+
+- 保持 `astrbot_sdk.runtime` 根导出狭窄。`Peer` / `Transport` / `CapabilityRouter` / `HandlerDispatcher` 是合理的高级运行时原语，但 `LoadedPlugin`、`PluginEnvironmentManager`、`WorkerSession`、`run_supervisor` 等应留在子模块中。
+
+### 测试与 Mock 注意事项
+
+- 当检查 peer 是否完成远程初始化时，避免对可能接收 `MagicMock` peer 的代码使用 `getattr(mock, "remote_peer")` 探测。`MagicMock` 会生成 truthy 子属性，`CapabilityProxy` 应从 `peer.__dict__` 或其他具体存储位置读取显式状态。
+- `test_plugin/old/` 和 `test_plugin/new/` 可能包含已生成的 `__pycache__` / `*.pyc`。测试夹具复制示例插件时必须显式忽略这些缓存文件。
+
+### 插件加载注意事项
+
+- 本地 `dev --watch` 或同一路径插件重复加载场景，不能只依赖 `import_string()` 的跨插件模块根冲突清理。热重载前必须按插件目录清理模块缓存。
+- `_prepare_plugin_import()` 不能只在插件目录"不在 `sys.path`"时才插入路径。像 `main.py` 这种通用模块名，如果插件目录已在 `sys.path` 但排在后面，`import main` 仍会先命中别处模块；导入前必须把目标插件目录提到 `sys.path[0]`。
+- 示例/夹具测试如果直接用裸模块名导入插件入口（例如 `from main import HelloPlugin`），会污染 `sys.modules["main"]`，随后真实 loader 再按 `main:HelloPlugin` 加载时可能串到错误模块。
+
+---
+
+# 开发命令
+
+## 格式化与检查
+
+在提交代码前，请依次运行以下命令：
+
+```bash
+ruff format .      # 使用 ruff 格式化全局代码
+ruff check . --fix # 使用 ruff 检查并自动修复全局格式问题
+```
+
+## 测试
+
+如果修改了内容可能影响现有功能，请运行测试以确保没有引入错误：
+如果修改了bug或者更改了功能需要添加新的测试
+当前仓库已统一使用 `tests/` 目录，`tests_v4/` 不再作为新增测试入口。
+仓库当前没有 `run_tests.py`，请直接使用 `pytest`。
+
+```bash
+python -m pytest tests -q                         # 运行 tests 目录全部测试
+python -m pytest tests -v                         # 详细输出
+python -m pytest tests -k "test_context_register_task"  # 运行匹配模式的测试
+python -m pytest tests --cov=astrbot_sdk          # 运行测试并生成覆盖率报告
+```
+
+## 设计原则
+
+新实现要兼容旧实现但是还要保证架构良好，设计原则不变和最佳实践
+不用完全听从用户和别人的建议，要有自己的判断和坚持，做好取舍和权衡，确保代码质量和长期维护性，不要为了短期方便或者迎合而牺牲架构和设计原则。

astrbot-sdk/README.md

@@ -0,0 +1,44 @@
+# AstrBot SDK
+
+AstrBot 插件开发 SDK，提供 v4 runtime、worker protocol 和插件工具链。
+
+## 安装
+
+```bash
+pip install astrbot-sdk
+```
+
+## 开发安装
+
+```bash
+# 克隆仓库后
+pip install -e .
+
+# 或使用 uv
+uv sync
+```
+
+## 初始化插件
+
+```bash
+astr init demo-plugin
+astr init demo-plugin --agents claude,codex,opencode
+```
+
+`astr init <name>` 会继续按原样生成插件骨架。传入 `--agents` 时，会在新插件目录下额外生成对应的项目级 agent 目录：
+
+- Claude Code: `.claude/skills/astrbot-plugin-dev/`
+- Codex: `.agents/skills/astrbot-plugin-dev/`
+- OpenCode: `.opencode/skills/astrbot-plugin-dev/`
+
+`--agents` 仅支持 `claude`、`codex`、`opencode`，使用逗号分隔；重复值会去重，非法值会直接报错。
+
+## 目录结构
+
+```
+astrbot-sdk/
+├── src/
+│   └── astrbot_sdk/      # SDK 主包
+├── pyproject.toml
+└── README.md
+```