make-plugin
Skill1 starsChanged 43 days agoMITView on GitHub
新建或改造插件、给插件加面板类型、往核心加内置面板之前,先看这份规范 —— 东西该放哪、三件套怎么接、状态/命令文件怎么走、挂件(floatBare / 鼠标穿透)、面板隔离(几块面板不许串味)、收尾四步
1 other project uses a version of this.
Adopted by
Most recently taken up by
- barnburner121/claude-plugin-marketplacetheir own version, first seen Mar 25, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- barnburner121/claude-plugin-marketplace★ 3same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-toolSkill
- design/comfyui-fluxSkill
- designSkill
- dev/refactor-safeSkill
- devSkill
- ensoul-mapSkill
- find-recipeSkill
- fix-buildSkill
- make-componentSkill
- pixal3d-comfyuiSkill
- prompt-protocolSkill
- troubleshootSkill
The file
Files
生成面板 / 插件的规范
零、先分流:东西该住哪
| 想做的 | 放哪 |
| 改现有面板的标题 / 外观 / 内容 / 按钮 / 类型 | 不写代码 —— 附 FLOAT_EDIT 提案,只写要变的字段,换类型必须给 kind |
| 把定型的面板沉淀为可复用组件 / 模板 | 不写代码 —— 参见技能 make-component,调用 component_declare 永久保存 |
| 一件功能(记录、统计、提醒、计时、状态、流程) | plugins/<名>/ 一个插件 |
| 界面渲染、停靠树、对话本身 | 只有这些住核心 src/ —— 插件跑在主进程,画不了界面 |
| 新的内置面板类型 | 两处都改:src/renderer/panel/registry.tsx + shared/types.ts 的 BUILTIN_KINDS |
| 只跟某个项目走的能力 | <工作区>/.ensoul/plugins/<名>/ —— 但它带不了脸(见下) |
新功能先问一句"插件能不能做"。核心里每多一段功能代码,拆出来的代价都要付两遍。
一、插件三件套
想改别人的插件、又不想动它的源码 —— 用同名覆盖(补丁层):
把 plugins/<名>/ 整个复制到 <工作区>/.ensoul/plugins/<名>/,改副本即可。
加载顺序是工作区在前、软件自带在后,先扫到的赢(同名的那份自带插件整个跳过,
并打一条 log 说明被顶替了)—— 于是程序更新不会把你的改动冲掉。
代价是它带不了脸(工作区插件没有 panel.tsx),只能覆盖"脑":工具、钩子、提示片段。
要连界面一起改,还是得动 plugins/ 本身。
plugins/<名>/index.js 脑:CommonJS,module.exports = { name, description, setup(api), dispose?, panel? }
plugins/<名>/panel.tsx 脸:默认导出 React.ComponentType<PanelFaceProps>,构建期 glob 收走
plugins/<名>/panel.css 皮:同上,脸里不用 import 它panel 声明是纯数据(要过 IPC),放在 module.exports = { ... } 里面:
module.exports = {
name: 'pomodoro',
description: '一句话:它是谁、面板为什么只是它的遥控器',
panel: { kind: 'pomodoro', label: '番茄钟', hint: '菜单里那句说明', title: '番茄钟', body: 'messages' },
setup(api) { /* ... */ },
};body只认messages | code | table | form | web,非法值静默当没有。kind不许撞BUILTIN_KINDS(chat / files / editor / table / form / web): 撞了内置赢,声明被忽略,不报错。- 只声明没脸装不上(控制台一条 warn);工作区插件(
.ensoul/plugins) 的脸是构建期 glob 定死的,根本带不了脸 —— 要界面就放软件自带的plugins/。
二、两条文件通道(面板和插件之间不开 IPC)
状态 .ensoul/state/<名>.json 插件写、面板读 —— 面板是哑的显示器(api.state.load/save 就是它)
命令 .ensoul/state/<名>.cmd.json 面板写、插件读 —— 面板只是遥控器- 命令文件是队列
{ panelId, seq, cmds: [...] },seq单调递增、插件认 seq —— 单条文件会把落在同一跳的两次点击盖掉,重放会执行两遍。 - 状态存绝对到点时刻 / 派生量,不存"还剩多少毫秒";磁盘只在局面真的变了时写, 倒计时让面板自己按 250ms 算。
- 计时、轮询、外部连接必须算在主进程:面板切走会被卸载、最小化后渲染层定时器被降频,
主进程的
setInterval不受影响。 - 状态文件可能是旧的、被人手改坏了 —— 读进来先 normalize,只信字段齐全的那部分。
三、脸的边界
脸只拿得到四样:panel(自己)、setText(改正文)、patch(改其它字段)、fs(读写工作区文件)。
刻意不给全量 api —— 脸跑在渲染进程,不该绕过停靠树 / 对话 / 持久化。
要更多能力,走上面那两条文件通道回主进程,别给脸开新口子。
四、挂件怎么缩放(嵌入面板的三条规矩)
面板被拖到某块区域正中就悬浮成一张便签 —— 这就是嵌入:它住的那块区域是母体, 母体大小随时会变(窗口拉小、并排的另一半变大)。三条规矩,别自己发明:
- 位置存比例,不存像素。
PanelFloat.rx / ry是"可移动范围(区域尺寸减自身尺寸)" 的比例,渲染层按当前区域大小折成像素、并且夹在框里。区域一缩,挂件自己贴回同一个 相对位置;存绝对坐标的话,母体缩一半,它照旧待在老坐标上,飞到画面外够不着。 这条在核心里(src/renderer/panel/FloatPanel.tsx),插件不用管。 - 缩放是核心自动做的,你什么都不用写。 面板只要进了容器(悬浮、停靠、嵌进别处),
核心的适配层(
src/renderer/panel/FitBox.tsx)就自己判: 内容滚不动(有overflow:hidden的层 —— 装不下就是真装不下)→ 整块缩放着装进容器, 拉大就涨、拉小就缩,既不出现滚动条、也不会裁掉半截; 内容滚得动(overflow:auto/scroll的层真的溢出了)→ 弹性内容,一根手指都不碰 —— 会话、文件树、编辑器、网页全走这条。判据是可观察的行为,面板不用声明任何东西。 所以插件这边只有一条要求:CSS 尺寸按自然尺寸写(190px就写190px), 别自己乘倍率、别自己量容器 —— 缩放是整体 transform,长度、字号、间距一起走; 也别在面板里自己写测量(那 40 行每块挂件各写一份,还特别容易写错:量成 "现在长什么样",于是只缩不涨)。 反过来,想让一块内容"装不下就滚"而不是"整块缩",就把它的滚动层写成overflow:auto/scroll—— 那正是弹性内容的判据,核心一眼认出来就往后退。 例外只有一个:面板自己就在管缩放(无限画布有view.z),在根元素上写data-fit="off"退出。这是例外,不是规则,别到处加。 要做"只剩一块东西"的挂件(番茄钟、桌宠那种),声明
floatBare: true, 并且给自己的实心件补pointer-events: auto。 这是一件事的两半,少一半就废。声明写在
panel里(纯数据,和look并列):panel: { kind: 'pomodoro', label: '番茄钟', title: '番茄钟', body: 'messages', floatBare: true, // 浮起来只剩一座钟:底是表盘自己带的 },它管两件事,都在核心的
float.css:- 壳上不画底。
panel.css给.panel-surface那层--panel是给停靠面板的, 浮在别的面板上面就得免掉,否则"容器透明、只有表盘是实心的"直接失效。 - 矩形里透明的地方不吃鼠标。 挂件是个矩形,可它看起来只有中间那点东西 —— 透明处要是不漏给底下的面板,它就是一块透明的盖子,底下明明看得见却点不到。
==
pointer-events是继承的:壳一关,里面全部跟着关。== 所以第二半必须你自己写, 核心猜不出挂件的形状(圆的表盘?一只鲸鱼娘?只有你知道):/* 实心的那几块把鼠标要回来;停靠时这几行等于没写(auto 本来就是默认) */ .pomo-ring, .pomo-actions button { pointer-events: auto; }不写会怎样:整块挂件全是穿透的 —— 看得见,摸不着,按钮一个都点不动。 核心已经替你留好的(不用你管):锁、拖动带、改大小把手、以及面板开着会话时的 对话区(
.chatdock)。反过来:普通面板(会话、文件、编辑器)别声明它。 它们浮起来照样要那块实心的底, 里面是要读的正文,透出底下的内容就没法看。
- 壳上不画底。
五、setup(api) 的全部口子(别新造)
| 口子 | 干什么 |
addTool(spec, handler) | 加工具;level 标对 read/write/full,不写默认 full;只在某种面板上有意义就写 scope: ['kind'] |
onBeforeWrite(fn) | 挂在写文件之前,返回一句话可改写内容 |
onBeforeTool(fn) | 挂在任何工具之前,返回一句话就拦下(拦了才问的 ask 要跳过,否则死循环) |
ask(spec) | 请用户点头;then 是 {tool, args} 数据不是回调 |
send(panelId, text) | 往面板发一轮;它正跑着时别发 |
addPrompt(fn) | 每轮往该面板系统提示加一段;只在某种面板上有意义就传第二个参数 { scope: ['kind'] } |
addStatusItem(item) | 输入框那一排挂一小块字 |
panels() / log() / workspace / state | 读面板与用量、记日志、工作区根、持久状态 |
- 工具 handler 失败不要 throw,把错误当文本返回(理由见 add-tool 技能)。
- 工具名与核心重名时核心赢,插件那条被静默忽略。
- 没人用的口子不要预留:第一个需要它的插件写的时候再加。
六、收尾四步(少一步都等于没改)
node --check plugins/<名>/index.js—— 加载器只记日志不抛错,语法错误在界面上只表现为"面板装不上"。build_project—— 脸和皮是构建期 glob 打进包的,不重建永远是旧的。restart_project—— 界面跑的是dist/,不重启一个字都不变。- 跨面板自检(§六) —— 两条命令各扫一遍:
node scripts/audit-plugins.js:静态查「单槽」(addPrompt / 模块级内存表 /api.state.save/ 命令文件该不该按面板分)。它只报「像」,不替你下结论 —— 确实不该分的,往脚本的EXEMPT里补一条并写清为什么。node scripts/selftest.js:跑起来验(p1/p2两块假面板各写各的清单、各读各的,别人的后台任务要标归属)。- 两条都过,再开两块真面板各跑一件不同的活,看 A 会不会说起 B 的事。这一步是唯一真正的验收。
七、面板隔离:新插件不许串味(硬规矩)
这个软件里同时有好几块面板在跑不同的活。插件只要写下任何会(a)进入模型眼前、 或(b)被某块面板读到的东西,就必须先回答一句:它属于哪块面板? 答不上来的就会串味 —— 症状是"A 面板干着干着,开始干 B 的活"。
判据一句话:模块里只要有一个"单槽"的东西(一个全局变量、一份不带 id 的状态文件、
一个 active 字段),就等于把 N 块面板黏成了一块。 有两条能跑的检查兜着,别只靠记:node scripts/audit-plugins.js 静态扫「单槽」(addPrompt / 模块级内存表 / api.state.save / 命令文件),node scripts/selftest.js 里有 p1/p2 两块假面板的隔离断言(todo 各写各的、每轮只发自己那份、后台任务标归属)。加了新口子,顺手往这两处各补一条 —— 规矩写在文档里只能靠人记得,写在脚本里才跑得起来。
会串味的口子,全都带 ctx.panelId
| 口子 | 怎么用 panelId | ||
addPrompt(fn) | fn(ctx) 里 `const mine = (ctx && ctx.panelId) | ''`,只交自己这块的正文 | |
addSummaryNote(fn) | 同上 —— 压缩那一刻也是在替某一块面板留要点 | ||
addTool(spec, (args, ctx) => …) | 返回的正文里不许掺别的面板的东西 | ||
onBeforeTool / onAfterTool(call) | call.ctx.panelId | ||
ask({ panelId, … }) | 请求挂在确实发起它的那块面板上 |
只在某种面板上有意义的东西:声明 scope,别手动判 kind
权限(level)管"这块面板有没有资格用",scope 管"这块面板上用它有没有意义"。
两回事,别混:画布那两个工具就是前者够、后者不够 —— 别的面板上根本没有画布,
给了它也只能回一句"不知道是哪块画布",却每轮都占着一份 schema 的钱。
// 工具:只在画布面板上出现
api.addTool({ name: 'canvas_read', level: 'read', scope: ['canvas'], ... }, handler);
// 提示片段:同上(第二个参数)
api.addPrompt((ctx) => digest(ctx.panelId), { scope: ['canvas'] });
// 错:在插件里手动查面板类型 —— 每块面板每轮都要跑一次,而且新面板类型一加就漏
const me = api.panels().find((p) => p.id === pid);
if (!me || me.kind !== 'canvas') return '';- 不写
scope= 到处都给(老插件一个字不用改),所以只有"明确不属于别处"的才写。 - 拿不准就别写。 声明错了是静默的功能消失(那个工具在某块面板上再也见不到), 比多给一个工具坏得多 —— 全局信息(git 局面、工作区说明、便签)本来就该到处都在。
- 判定用的是面板类型,不是某一块面板:所以这里写
['canvas'],不是 panelId。
落盘的状态:按面板分槽
// 对:各写各的槽,各读各的槽
{ at: 0, panels: { 'panel-x': { items: [...], at: 0 }, 'panel-y': { items: [] } } }
// 错:单槽 —— 后写的盖掉先写的,读到的人还以为是自己的
{ items: [...], active: 'panel-x' }active/ "最近更新"这类字段只准给面板做兜底显示("这是 XXX 的清单"), 绝不能喂给模型。- 读老文件先 normalize,迁移要保住旧数据(
todo就是这么把扁平结构搬进panels的)。 - 面板被彻底忘掉时回收自己的槽位,槽位要有上限。
- 命令文件(
.cmd.json)每条命令带panelId,面板只认自己那条。
真出过的事故(照抄它们的形状就是重犯)
todo:清单全局一份 → 每块面板都被告知"这是你的任务清单",A 的活被 B 接着干。schedule:到点记录全局一份 → A 排的提醒摆到 B 面前,B 就放下手里的活去办它。loop-guard:重复调用计数全局一份 → 两块面板交替干活时互相把对方算成"卡住了"。
三处的修法都是同一句:结构和钩子都带上 panelId。
跨面板"看得见"不等于串味(但要说清)
- 工作区文件、
@引用、AGENTS.md:本来就只有一份,谁读都是它。 history_search/history_read:故意让模型翻别的会话 —— 它是工具,由模型主动调, 回话里必须标明是哪个会话。- 全局资源(后台任务、端口、备份目录):可以看见,但必须标明归属,
否则模型会把它当成自己那摊接着干(
jobs的owner就是为这个加的)。
核心不背这个锅
src/ 已经把 panelId 递到每个口子上了(plugins.ts 的 ctx),对话、压缩摘要、
动作记录、@ 引用、面板快照、私有空间 <工作区>/.ensoul/panels/<面板 id>/、运行态
都是按面板分好的。串味一律发生在插件没接这个参数。
容易踩的坑(都是真踩过的)
panel声明放在module.exports = { ... }外面 → 整个插件语法错误、加载失败。 todo 和 pomodoro 同时这么坏过。- 块注释里写
plugins/*/panel.tsx→ 里面的*/把注释提前关掉,后面全是代码。 注释里写plugins/<名>/panel.tsx。 - 声明了
floatBare: true却忘了给实心件写pointer-events: auto→ 挂件整块穿透, 看得见摸不着,按钮一个都点不动(见 §四 第 3 条)。反过来,普通面板顺手声明了它 → 浮起来变成透明的,底下的内容透上来,正文没法读。 - 忘了
dispose:插件文件改了会重载,旧实例的setInterval留在外面就多一个永远跑着的计时器。 - 面板顶着"新面板 / 对话"这种默认名聊了几轮 —— 主动附一段只带 title 的提案,四到八个字说清它是干什么的。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

