docs: 自动同步提交 e05dd65

docs/snapshots/index.md

@@ -0,0 +1,5 @@
+# 文档快照
+
+这里存放按 AstrBot Tag 归档的文档快照。
+
+- [v4.24.4](/snapshots/v4.24.4/)

docs/snapshots/v4.24.4/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+venv/
+.DS_Store
+node_modules/
+.vitepress/cache
+*dist

docs/snapshots/v4.24.4/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: skill-astrbot-dev
+description: Reference + workflow notes for AstrBot plugin development (messages, platform adapters, plugin config, agent system).
+metadata:
+  short-description: AstrBot dev reference
+---
+
+# skill-astrbot-dev
+
+This skill is the source-of-truth index for AstrBot developer docs in this repo (`docs/`).
+
+Goal: when this skill is selected, immediately ground on the minimum required docs + code entrypoints,
+avoid duplicated reading, and always prefer code as the final authority.
+
+## When to use
+
+Use this skill when you ask for help with:
+
+- AstrBot plugin structure, decorators/hooks, lifecycle, schema, sessions
+- Message model/event flow and message-chain conversion
+- Platform adapter interface and message conversion patterns
+- Agent topics (tools/providers/personas/subagents/sandbox/cron/context compression)
+
+## Mandatory workflow (use this every time)
+
+1. Start from a single entrypoint (avoid broad loading):
+   - Site index: `docs/index.md`
+   - Core concepts: `docs/design_standards/core_concepts.md`
+2. Pick one topic folder and stay focused:
+   - Agent system: `docs/agent/`
+   - Plugin config: `docs/plugin_config/`
+   - Messages: `docs/messages/`
+   - Platform adapters: `docs/platform_adapters/`
+3. For Agent Runner (v4.7.0+): `docs/agent/agent-runner.md`
+4. If the user targets a specific AstrBot version, cross-check:
+   - `docs/snapshots/<version>/`
+5. If docs and code disagree, treat code as truth:
+   - Core code lives under `astrbotcore/astrbot/core/` (read only the needed files)
+
+## STRONGLY ADVISED: use AstrBot SDK while writing plugins
+
+When writing plugin code, strongly advised to install AstrBot SDK locally and use it for API reference,
+signature lookup, and IDE auto-completion.
+
+```powershell
+python -m pip install -U astrbot
+```
+
+Use SDK symbols first when implementing hooks, provider/context calls, and agent runner integration.
+This helps reduce guesswork and signature mismatch.
+
+If AstrBot source code in this repo is available, still treat repo code as higher priority than package docs.
+
+## Plugin project structure (strongly advised)
+
+A standard AstrBot plugin project should include:
+
+- `main.py`: entrypoint. Implement plugin startup and primary features here.
+- `metadata.yaml`: plugin metadata (name, version, author, repo, description).
+- `README.md`: installation, usage, feature overview, and dev links.
+- `.gitignore`: ignore Python cache (`__pycache__`) and IDE config files.
+- `LICENSE`: open-source license file.
+
+## `metadata.yaml` minimal template
+
+```yaml
+name: astrbot_plugin_helloworld # 插件唯一识别名，最好以 astrbot_plugin_ 前缀开头
+display_name: helloworld # 展示名（v4.5.0+）
+desc: AstrBot 插件示例。 # 插件简短描述
+version: v1.3.0 # 版本号：v1.1.1 或 v1.1
+author: Soulter # 作者
+repo: https://github.com/Soulter/helloworld # 插件的仓库地址
+astrbot_version: ">=4.16,<5" #声明插件要求的 AstrBot 版本范围。
+```
+
+## Code rules for plugin implementation
+
+- Use `async def` for handlers/hooks/tool functions.
+- Keep `main.py` focused on plugin entry and orchestration; extract complex logic into submodules.
+- Add type hints for public methods and hook signatures.
+- Do not hardcode provider IDs or secrets; expose configurable fields in `_conf_schema.json`.
+- Prefer small, testable functions over large monolithic handler bodies.
+- Keep README and metadata consistent with actual plugin behavior and version.
+  -If you are writing AstrBot core code instead of plugins, you must submit a PR to https://github.com/AstrBotDevs/AstrBot-docs if the changes require doc updates (for instance: new hooks, new APIs, new features, platform adapter changes, and so on). If you don't see the docs repo, please remind the user to clone the docs-repo and add it to the workspace.
+Ensure that a `requirements.txt` file is created in the plugin directory and populated with the necessary dependencies.
+plugin i18n is recommanded ,but is still in experiment state use it carefully
+It's best to keep the plugin size under 32MB.
+For large resources like high-resolution images, it is best to use a CDN instead of hardcoring.
+### 
+
+## Hooks: avoid missing / outdated references
+
+There are two different "hook" layers you must not mix up:
+
+- Plugin event hooks (decorators): `docs/plugin_config/hooks.md`
+- Agent runner hooks (`BaseAgentRunHooks`): `docs/agent/agent-related-hooks.md`
+
+If you need a complete hook inventory (because context may be truncated), generate it locally:
+
+```powershell
+python scripts/generate_hook_inventory.py
+```
+
+This writes to `docs/.tmp/hook_inventory/` (gitignored). Use it as a scratchpad for writing/updating docs;
+do not reference `.tmp` paths as public documentation URLs.
+
+## High-signal code entrypoints (open only when needed)
+
+- Event hooks registration + signatures: `astrbotcore/astrbot/core/star/register/star_handler.py`
+- Event types: `astrbotcore/astrbot/core/star/star_handler.py`
+- Agent runners + hook call order: `astrbotcore/astrbot/core/agent/runners/`
+- Agent hook interface: `astrbotcore/astrbot/core/agent/hooks.py`
+- Main agent build (sandbox/cron/tools): `astrbotcore/astrbot/core/astr_main_agent.py`
+- Skills system (AstrBot runtime skills): `astrbotcore/astrbot/core/skills/skill_manager.py`
+- Subagents config loading: `astrbotcore/astrbot/core/subagent_orchestrator.py`
+
+## v4.5.7+ New Tool Definition Pattern
+
+推荐使用 dataclass 模式定义 Tool（见 `docs/design_standards/core_concepts.md` 第7节）：
+
+```python
+from pydantic.dataclasses import dataclass
+from astrbot.core.agent.tool import FunctionTool
+
+@dataclass
+class MyTool(FunctionTool):
+    name: str = "my_tool"
+    description: str = "工具描述"
+    parameters: dict = {...}
+
+    async def call(self, context, **kwargs) -> str:
+        return "结果"
+```
+
+注册：`self.context.add_llm_tools(MyTool())`
+
+装饰器方式仍然支持，但推荐新项目使用 dataclass 模式。
+

docs/snapshots/v4.24.4/Storage & Utils/file_storage.md

@@ -0,0 +1,29 @@
+---
+category: storage
+---
+
+# 文件存储规范
+
+对于大文件、日志或插件特有的资源文件，AstrBot 建议遵循以下存储规范。
+
+### 目录规范
+
+所有插件特有的文件应存储在以下目录：
+`data/plugin_data/{plugin_name}/`
+
+### 获取存储路径
+
+建议在插件中使用以下方式获取路径，以确保兼容性：
+
+```python
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+
+# 获取插件专属数据目录
+plugin_data_path = get_astrbot_data_path() / "plugin_data" / self.name
+plugin_data_path.mkdir(parents=True, exist_ok=True) # 确保目录存在
+```
+
+### 注意事项
+
+- 不要将大文件直接存储在 `docs/` 或插件根目录下。
+- 建议定期清理不再使用的临时文件。

docs/snapshots/v4.24.4/Storage & Utils/kv_storage.md

@@ -0,0 +1,21 @@
+---
+category: storage
+---
+
+# 键值对存储 (KV Storage)
+
+AstrBot 为插件提供了简单易用的 KV 存储接口，适合存储配置、轻量级状态或用户数据。
+
+### 核心接口 (>= v4.9.2)
+
+这些方法在插件类（继承自 `Star`）中可以直接调用：
+
+- `await self.put_kv_data(key: str, value: Any)`: 存储数据。
+- `await self.get_kv_data(key: str, default: Any = None) -> Any`: 获取数据。
+- `await self.delete_kv_data(key: str)`: 删除数据。
+
+### 特点
+
+- **隔离性**: 数据按插件 ID 隔离，不同插件之间的 Key 不会冲突。
+- **持久化**: 数据会自动持久化到 `data/metadata/kv_storage.db`（或相应目录）。
+- **异步**: 接口均为异步方法。

docs/snapshots/v4.24.4/Storage & Utils/plugin-i18n.md

@@ -0,0 +1,146 @@
+# 插件国际化
+
+插件可以在自己的目录下提供 `.astrbot-plugin/i18n/*.json`，让 WebUI 根据当前语言显示插件名称、描述和配置项文案。
+
+## 目录结构
+
+```text
+your_plugin/
+  metadata.yaml
+  _conf_schema.json
+  .astrbot-plugin/
+    i18n/
+      zh-CN.json
+      en-US.json
+```
+
+语言文件名使用 WebUI 的 locale，例如 `zh-CN.json`、`en-US.json`。文件内容必须是 JSON object。
+
+当当前语言没有对应翻译、某个字段缺失，或语言文件不存在时，AstrBot 会回退到默认文案：
+
+- 插件名称、卡片短描述和描述回退到 `metadata.yaml` 中的 `display_name`、`short_desc`、`desc`。
+- 配置项文案回退到 `_conf_schema.json` 中的 `description`、`hint`、`labels`。
+
+## 元数据
+
+`metadata` 用于覆盖插件在插件页展示的名称、卡片短描述和描述。
+
+```json
+{
+  "metadata": {
+    "display_name": "天气助手",
+    "short_desc": "一句话天气查询。",
+    "desc": "查询天气并提供出行建议。"
+  }
+}
+```
+
+## 配置项
+
+`config` 用于覆盖 `_conf_schema.json` 中的配置文案。结构按配置项名称嵌套。
+
+例如 `_conf_schema.json`：
+
+```json
+{
+  "enable": {
+    "description": "Enable",
+    "type": "bool",
+    "hint": "Whether to enable this plugin.",
+    "default": true
+  },
+  "mode": {
+    "description": "Mode",
+    "type": "string",
+    "options": ["fast", "safe"],
+    "labels": ["Fast", "Safe"]
+  }
+}
+```
+
+对应 `.astrbot-plugin/i18n/zh-CN.json`：
+
+```json
+{
+  "config": {
+    "enable": {
+      "description": "启用",
+      "hint": "是否启用这个插件。"
+    },
+    "mode": {
+      "description": "模式",
+      "labels": ["快速", "安全"]
+    }
+  }
+}
+```
+
+`options` 是配置保存值，不建议翻译。下拉框的展示文本请使用 `labels`。
+
+## 嵌套配置
+
+如果 `_conf_schema.json` 中有 `object` 类型配置，翻译也按同样的字段结构继续嵌套。
+
+```json
+{
+  "config": {
+    "sub_config": {
+      "name": {
+        "description": "名称",
+        "hint": "显示在消息中的名称。"
+      }
+    }
+  }
+}
+```
+
+## 模板列表
+
+`template_list` 的模板名称和模板内字段也可以翻译。模板名称放在 `templates.<模板名>.name`，模板内字段继续往下嵌套。
+
+```json
+{
+  "config": {
+    "rules": {
+      "description": "规则",
+      "templates": {
+        "default": {
+          "name": "默认模板",
+          "threshold": {
+            "description": "阈值",
+            "hint": "达到该值后触发规则。"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## 完整示例
+
+下面是一个真实配置项的英文翻译示例：
+
+```json
+{
+  "metadata": {
+    "display_name": "HAPI Vibe Coding Remote",
+    "desc": "Connect to a HAPI service and control coding agent sessions from chat platforms."
+  },
+  "config": {
+    "hapi_endpoint": {
+      "description": "HAPI service URL",
+      "hint": "Example: http://localhost:3006"
+    },
+    "output_level": {
+      "description": "SSE delivery level",
+      "hint": "silence: permission requests only; simple: plain text messages and system events; summary: recent N messages when a task completes; detail: all messages in real time",
+      "labels": ["Silence", "Simple", "Summary", "Detail"]
+    }
+  }
+}
+```
+
+## 约束
+
+插件国际化只读取 `.astrbot-plugin/i18n` 目录。语言文件必须使用嵌套 JSON 结构，不支持点号扁平 key。