给 Claude Code 用的 Skill，让 Claude 按 LangBot 4.x 的清单式插件系统来开发、调试和发布插件。
English summary: a Claude Code skill for building LangBot 4.x plugins. It encodes the parts of the plugin system that the official docs don't cover — the failure modes that don't raise, they just silently do the wrong thing. Docs and skill content are in Chinese, matching the LangBot community.
直接让 Claude 写 LangBot 插件，通常会遇到三类问题：
- 写出 3.x 的代码。 预训练记忆里的 LangBot 插件基本是 3.x 的
（
from pkg.plugin.context import register那套），在 4.x 上根本加载不了。 - 文档覆盖不全，而且有落后。 比如子命令的
aliases参数文档里有、实际不参与派发； 事件定义的模块路径和文档给人的印象不一致。 - 有些坑只有真机踩过才知道。 最典型的是群聊里
context.session.sender_id不是当前发命令的人——字段名看着对、类型对、取出来也是个真实用户 ID， 只是那个人是「这个群第一个用过机器人的人」。不报错，数据默默全记到一个人头上。
这个 skill 把这些东西写下来了，并且教 Claude 去读 SDK 源码验证，而不是凭记忆编。
Skill 放在 ~/.claude/skills/ 下即可被 Claude Code 自动发现。
git clone https://github.com/DefensiveSniper/langbot-plugin-skill.git ~/.claude/skills/langbot-plugin想让仓库待在自己的工作目录、方便改和提 PR，就用符号链接：
git clone https://github.com/DefensiveSniper/langbot-plugin-skill.git ~/Project/langbot-plugin-skill
ln -s ~/Project/langbot-plugin-skill ~/.claude/skills/langbot-plugin装好之后不用做任何事——聊到 LangBot 插件、lbp 命令、manifest.yaml、插件市场之类的话题
Claude 会自己加载它。
| 文件 | 内容 |
|---|---|
SKILL.md |
工作流、插件类骨架、目录与导入约定、3.x 写法黑名单、「去哪读源码」对照表 |
references/pitfalls.md |
20 条坑，全部实际踩过。按写命令组件 / 消息与回复 / 存储与身份 / 运行期 / 远程调试分组 |
references/components.md |
Command、EventListener、Tool 的写法与清单格式，配置项全部类型 |
references/apis.md |
请求 API 与插件 API 速查（存储、主动发消息、调模型、消息链） |
references/publish.md |
目录规范、GitHub Release 自动化、插件市场提交、认证插件申请 |
references/testing.md |
不依赖 LangBot 实例的打桩测试方法论 |
assets/test_harness.py |
可直接改的测试脚手架，用真实 SDK 实体 + 打桩宿主 API 跑完整链路 |
evals/ |
评测用例、断言、以及一个埋了典型问题的插件样本 |
摘几条代表性的（完整清单见 references/pitfalls.md）：
- 群聊的
session.sender_id是会话首次创建者，不是当前发送者。用它来 @ 人或记录 「谁订阅的」会张冠李戴——解法是从GroupCommandSent/PersonCommandSent事件取真实发送者。 @self.subcommand(aliases=[...])的别名不参与派发，只是元数据。name="*"的兜底子命令必须至少 yield 一次，否则控制流会掉进「未知命令」分支去raise一个 pydantic BaseModel，直接TypeError: exceptions must derive from BaseException。!cmd <参数>这种单层命令必须注册name="*"——SDK 拿crt_params[0]去查子命令表， 参数会被当成子命令名。只注册name=""的话主路径 100% 崩。- 插件存储的 owner 是
author/name。改 author（比如为了上市场改成 GitHub 用户名） 会让已有数据读不到，而binary_storages.unique_key末段是个哈希，迁移得按宿主算法重算。 - 上插件市场要求
manifest.yaml的author等于你的 GitHub 用户名， 首次提交后还要在网页补使用截图才会进审核队列。
用 3 个真实场景做过带/不带 skill 的对照（对照组无法访问本 skill 与任何参考实现）：
| 场景 | 带 skill | 不带 |
|---|---|---|
| 从零写一个群待办插件 | 11/11 | 8/11 |
| 诊断「群里 @ 错人」 | 5/5 | 5/5 |
| 发布前检查一个有问题的插件 | 10/10 | 10/10 |
| 平均耗时 | 312 秒 | 546 秒 |
| 平均 token | 12.0 万 | 13.9 万 |
如实说明：后两个场景两边都满分。Claude 读 SDK 和 LangBot 主程序源码，能把大部分坑
自己挖出来。这个 skill 的价值主要在两处——省掉约一半时间和源码翻阅，以及兜住那类
源码里看不出来的坑（第一个场景里，对照组用了 session.sender_id，群里所有人的待办会
记到同一个人头上，它自己还在 README 里写「谁发的命令就是谁的清单」）。
针对 LangBot 4.x 插件系统，内容在 langbot_plugin 0.5.8 与 0.6.0b5 上核对过，
宿主行为对照的是 LangBot v4.10.11 的源码。
SDK 在演进，如果你发现某条与新版本不符，欢迎开 issue 或 PR—— skill 里也明确要求 Claude 以目标环境的 SDK 源码为准，而不是无条件相信文档或本 skill。
- LangBot · 插件开发文档 · 插件 SDK
- BilibiliReminder —— 本 skill 的经验来源，一个已上架插件市场的 4.x 插件
MIT