插件工坊 · plugin-forge

DSH agent 预设：原创插件生成 + 他人插件测绘 / 吸收 / 改造。

装上后模式下拉里多出一项「插件工坊」，会话里可以直接说：

• 「帮我写个插件：……」
• 「看看这个插件怎么实现的」
• 「照它的面板写法做一个」
• 「把这个插件改成我要的样子」

它与「逆向模式」的区别

两者都做「拆开别人的东西」，但对象不同：

逆向模式的工具链（jadx / Frida / IDA）在这里用不上——插件的源码本来就是可读的 JS。

四个执行角色

并发上限 3 个。四个角色都是叶子节点（maxDepth: 1），不会无限往下派。

六个技能

技能装在哪：$DSH_HOME/plugin-forge/skills/，由本插件启动时从包内同步。

多预设架构（怎么继续加）

本插件不是「一个预设的插件」，而是预设容器：presets/ 下每个子目录就是一个模式。

presets/
plugin-forge/          插件工坊（正式）
preset.yml
agent.cordis.yml
persona.md           人设源文件，用 %%PERSONA%% 注入
demo-mini/             演示模式（架构验证用，可删）

加一个新预设，不需要改任何 JS：

1. 在 presets/ 下建目录，目录名 = preset id（^[a-z0-9][a-z0-9-]{0,31}$）
2. 写 preset.yml：name / description / order（前两个必须单行，order 必须数字）
3. 写 agent.cordis.yml：条目列表，至少含 persona、skill-filesystem、一个 shell 工具
4. 人设长时用 %%PERSONA%% 占位符 + 同目录 persona.md
5. 重启 dsh

细节与模板见 skills/preset-scaffold/SKILL.md。

停用与移除

条目标注册实例

所有预设共享同一个技能库（$DSH_HOME/plugin-forge/skills）。所以给插件工坊加的技能，新预设自动可用。

状态文件（多预设版）

{
"ok": true,
"phase": "registered",
"presets": [
{ "id": "demo-mini", "name": "演示模式", "plugins": 11, "ok": true, "broken": null },
{ "id": "plugin-forge", "name": "插件工坊", "plugins": 19, "ok": true, "broken": null }
],
"skipped": [],
"skillsDir": "...",
"source": "...\\presets"
}

phase 取值：registered（全部成功）/ registered-partial（部分失败，看 presets[].broken）/ no-presets / waiting-registry / registry-timeout。

提示词固化在哪（防丢）

这是本插件存在的核心目的：规范不能只活在会话里。

为什么拆成 SKILL.md + references：宿主对 SKILL.md 有 8192 字符硬上限，超了会被修剪器裁掉后半段。官方技能也是这个结构——SKILL.md 只放骨架与导航，长文按需读 references/，不计入预算。

改人设的正确方式

# 1. 改 presets/plugin-forge/persona.md（唯一真源）
# 2. 校验（不写盘）
python build-composition.py --check
# 3. 重启 dsh

agent.cordis.yml 里只有一行 %%PERSONA%%，落地时自动注入全文。不要直接改落地副本（.agent-presets/plugin-forge/agent.cordis.yml）——下次启动会被源覆盖。

检索工具（省 token 的核心）

四个工具，按问题类型选：单文件降维 → 跨文件查库 → 结构搜索 → 字面量搜索。

实测数据

用法

# ① 单文件或单插件：先出大纲（读大文件之前必做）
node tools/outline.mjs '<插件目录>' --tokens

# ② 跨文件问题：建一次索引，之后都走查询
node tools/index.mjs build 'G:\AI PGRM\DSH\plugins'
node tools/index.mjs find PanelPage        # 全库几处定义
node tools/index.mjs refs handleOperation  # 谁引用了它
node tools/index.mjs slots                 # 哪些插件注册了什么槽位
node tools/index.mjs routes                # 全部路由
node tools/index.mjs effects network       # 所有网络请求点
node tools/index.mjs stats                 # 库规模 + 同名多定义

# ③ 结构化搜索（注意必须带 $OBJ. 前缀）
ast-grep run -p '$OBJ.slots.register({ name: $NAME, $$$REST }, $COMP)' -l js '<目录>'
ast-grep run -p '$OBJ.webServer.register({ $$$REST })' -l js '<目录>'

# ④ 拿到行号后再定向读
# read client.js offset=279 limit=238

ast-grep 需要自行安装

它 55MB，不在本包内。安装后加进 PATH：

ast-grep --version     # 期望 ast-grep 0.51.1 或更高

Windows 官方包是 app-x86_64-pc-windows-msvc.zip，解压后把含 ast-grep.exe 的目录加入用户 PATH。注意 sg.exe 是弃用别名，不要用。

不在 PATH 时自动降级为「大纲器 + 宿主 grep」，功能可用但结构匹配精度下降。

索引库的三个已知边界

1. 引用是「调用点 + 大写参数」，不是全量标识符。小写变量名作参数传递（fn(handler)）查不到 —— 这时改用 ast-grep。
2. 动态路由标注为 (动态: route)：config.route 这类运行期值静态还原不了，如实标注而非猜测。
3. 增量更新依赖 mtime：改文件但 mtime 没变时会滞后，删库重建即可。

三个实测踩过的坑

1. ast-grep 必须带 $OBJ. 前缀。slots.register($$$A) 只匹配独立调用，漏掉 ctx.slots.register(...) 这种最常见写法。
2. 找注册点别用裸 grep。同一份测试代码，grep 命中 5 行其中 3 行是注释与字符串误报；ast-grep 只命中 1 行真实代码。
3. 建索引必须开事务。不开事务时 SQLite 逐行同步落盘，1.5MB 语料从 456ms 涨到 2 分钟以上。

预算判据

硬规则：读任何大于 20KB 的文件之前，必须先跑 outline。

中文优先

• UI 文案、按钮、错误提示：一律简体中文
• 插件展示名与描述：一律简体中文
• 默认不做多语言：不创建 en.json，不留双语字典，不写 locale 切换
• 只有用户明确要求时才做双语

安装

已在 profile 里装好。若要重装或换机器：

# 1) 包目录放到任意位置，然后加进 profile 依赖
$profile = $env:DSH_PROFILE_DIR
$pkg = Get-Content -Raw -Encoding UTF8 "$profile\package.json" | ConvertFrom-Json
$pkg.dependencies | Add-Member -NotePropertyName '@local/dsh-plugin-forge-preset' `
-NotePropertyValue 'link:<包目录绝对路径>' -Force
$pkg.dsh.profile.bundles += '@local/dsh-plugin-forge-preset'
$pkg | ConvertTo-Json -Depth 12 | Set-Content "$profile\package.json" -Encoding UTF8

# 2) 建 junction，让 Loader 能按包名解析
New-Item -ItemType Junction -Path "$profile\node_modules\@local\dsh-plugin-forge-preset" `
-Target '<包目录绝对路径>'

重启 DSH，模式下拉里就会出现「插件工坊」。

它自己做了什么（运行时行为）

启动时按顺序：

1. 把 preset.yml + agent.cordis.yml 落到 $DSH_HOME/.agent-presets/plugin-forge/
2. 把 skills/ 同步到 $DSH_HOME/plugin-forge/skills/
3. 等 agentPresets 服务就绪（最长 20 秒），然后调 ctx.agentPresets.register() 声明进下拉
4. 把结果写进 $DSH_HOME/plugin-forge/preset-declare.json

第 3 步是必须的：Web 的模式下拉只认 register()，只把目录写到 .agent-presets 不会被扫到——这是「插件装得完整、下拉里却没有它」的唯一根因。

状态文件

{
"ok": true,
"phase": "registered",
"id": "plugin-forge",
"name": "插件工坊",
"plugins": 19,
"broken": null,
"skillsDir": "...",
"presetDir": "..."
}

装完直接看这个文件判断是 registered 还是 broken。

配置项

关掉技能同步（想自己维护那份技能库时）：

- id: dsh-plugin-forge-preset
name: '@local/dsh-plugin-forge-preset'
config:
syncSkills: false

改人设

人设正文在 persona.md。改完重新生成 composition：

python build-composition.py

不要直接改 agent.cordis.yml 里的人设块——它是生成产物，下次生成会被覆盖。

重新生成后需要重启 DSH 才生效（预设只影响之后创建的会话）。

回滚

# 1) 从 profile 拿掉
$profile = $env:DSH_PROFILE_DIR
$pkg = Get-Content -Raw -Encoding UTF8 "$profile\package.json" | ConvertFrom-Json
$pkg.dependencies.PSObject.Properties.Remove('@local/dsh-plugin-forge-preset')
$pkg.dsh.profile.bundles = @($pkg.dsh.profile.bundles | Where-Object { $_ -ne '@local/dsh-plugin-forge-preset' })
$pkg | ConvertTo-Json -Depth 12 | Set-Content "$profile\package.json" -Encoding UTF8

# 2) 删 junction
Remove-Item "$profile\node_modules\@local\dsh-plugin-forge-preset" -Force

# 3) 删落地的预设与技能（可选：保留则重新装回来会复用）
Remove-Item "$env:DSH_HOME\.agent-presets\plugin-forge" -Recurse -Force
Remove-Item "$env:DSH_HOME\plugin-forge" -Recurse -Force

profile 的 package.json 旁边有安装时的备份（package.json.bak-forge-*），可以直接还原。

依赖

没有 @local/dsh-forge 也能正常加载——本 preset 不注册它的行。

验收记录

本次安装实测：

• dsh-forge 体检：14 项 PASS，0 error 0 warn
• composition 解析（真实 fail-closed 解析器）：19 行、3 个 group、无缺 name 行
• 声明链路（假 registry）：registered，ok: true，broken: null
• 生产路径（经 profile junction）：exports / files / patch / entry / lib 全通
• 技能预算：三份 SKILL.md 渲染后 4214–5862 字符，均 < 8192
• 人设无 {{...}} 变量（会被当 prompt 变量解析失败）