dsh-super-injector — 超级模组注入器

🎉 v0.3.0 重大声明（2026-08-14）

从经验补丁到源码契约——注入器完成规范重构。

本版本按 docs/SPEC.md（基于 DSH 0.1.0-rc.6 源码语义推导的 设计契约）重构自重载为官方 REPLACE 结构：工具只排程、绝不亲自自杀； reboot 走 entry._dispose（官方 _disposing 豁免）+ 失败自动 rollback。 从此注入器的一切行为都有源码依据，不再依赖经验补丁。

里程碑回顾：

• 三轮零上下文 subagent 评测：9/10 → 9.5/10 → 10/10
• 作死压力测试：连环自杀/坏语法/悬空 junction/循环注入卸载——零崩溃零残留
• 云源自举：下载 release 副本 → 装配 → 注入器从云端副本运行（自检 8/8）
• 免杀进程恢复：失败 → touch patch（include.refresh 进程内重装配）→ 6 秒复活
• DSH 正式版兼容：0.1.0-rc.6 一行不改直接运行（peerDeps 范围声明实证）

哲学不变：一切皆插件——注入器是 DSH 生态的运行时注入标准层， 让"插件想长成什么样就长成什么样"。

DSH 生态的 BepInEx 式模组注入入口：运行时把任意本地插件包注入运行中的 web， 不碰 patch / package.json / bundles 列表、不重启进程。注入即完整生效（host 工具 + client UI）。

灵感：官方装配机制（profile bundle / repository-plugin）是唯一的"官方入口"，就像游戏 只有启动器能装模组。本插件打破这一点——引导器走官方入口装一次，之后万物皆可运行时注入。

安装（三选一）

方式 A：Release 包（推荐，免构建）

从 Releases 下载 dsh-external-dsh-super-injector-0.0.1.tgz，解压得到插件目录（含 lib/ 与 cordis.patch.yml），然后：

# 官方装配（重启后由 bundles 接管，生产态）
dsh plugin --profile web add 

# 或运行时注入（免重启，开发态；需任一环境已常驻注入器）
# 对 AI 说：dev_inject_plugin 

方式 B：git 装配

dsh plugin --profile web add github:yjh051108/dsh-super-injector

方式 C：引导装配（源码方式，只需一次）

在 ~/.dsh/profiles/web/cordis.patch.yml 添加：

- insert:
    - id: dsh-super-injector
      name: '@yjh051108/dsh-super-injector'
      config: {}

引导器常驻后，任意超级模组随取随用，无需再碰官方配置。

兼容性

• 不硬编码 DSH 版本：peerDependencies 全部为范围声明 （@deepseek-ai/dsh-tools: >=0.0.1-rc =4.0.0-rc .mjs）热挂载 | 手术台：注入开发者预构建的完整插件包（package.json + lib/） | | 适用 | agent 随对话长出小工具（记账/天气/周报） | 装/换成品模组、自主开发闭环（写 → build → 注入 → 热重载） | | 联动 | evolve 长出的源码可升级为完整包，再走注入器上膛 | 注入后可被 dev_reload_package 热重载 |

生态定位：官方之下的运行时标准层

官方对插件体系的方向（2026-07 agent notes）：

1. 否决安装命令 + 安装数据库 + marketplace——持久化插件只有一种状态：配置（cordis.patch.yml / profile bundles / repositories），事务性 HMR 对账；
2. agent 自己管理运行时——自指 cordis 工具集，运行时归 agent 管。

翻译：官方钦定"装什么"（bundle / repository + 配置），但"装完之后怎么改"——热重载、侧挂测试、一键转正、卸载、失败自愈——是官方留白。这一整块运行时管理面，由本插件吃下。

生态入口	层	一句话分工
官方 bundle / repository	装配层	唯一官方入口，配置即状态
plugin-registry	官方薄控制台	官方格式插件管理与开发引导
marisa	agent 面工具链	临时插件 → 持久化插件的固化桥
mygo	受管对象层	插件生命周期对象化（锁定/启停/依赖图）
dsh-evolve	创造模式	agent 现场长出单文件能力
dsh-super-injector	运行时手术台	开发闭环全家桶：注入 / 热重载 / 侧挂转正 / 卸载 / 路由自愈 / UI 联动

设计原则：

1. 不发明协议：注入的是标准插件包（package.json + lib/），格式就是官方包格式，装上即官方语义；
2. 双路径，尊重"配置唯一"：运行时注入（免重启，开发态）↔ dev_install_package 落 profile bundles（重启后由官方接管，生产态）——注入清单只是运行时恢复缓存，不是第二安装数据库；
3. 模型可驱动：dev_* 全是工具，agent 自己注入/卸载/转正——正踩在官方"agent 自己管理运行时"的方向上；
4. 可逆且自愈：注入可回滚（失败保旧代）、卸载即净（fiber 全清理）、残留可自愈（路由/缓存/entry 自动清理）。

目标：成为官方装配机制之下、生态事实标准的运行时管理层——"启动器装模组"只是起点，注入器让 DSH 拥有"万物可注入、注入可回滚、改完即生效"的 Mod 级体验。

工具全家桶（全部免重启）

工具	说明
dev_inject_plugin	运行时注入本地插件包（junction 链接 + loader.create，hasActiveEntry 防重）
dev_uninject_plugin	一键卸载注入模组（fiber dispose 全清理；bundle 插件自动写 disabled 阻断自装配）
dev_injected_list	列出注入清单
dev_install_package	热装配本地 bundle 插件（profile package.json + junction + loader.create，重启后由 bundles 列表正常装配）
dev_reload_package	整包热重载（清缓存 → 重新 import → 重建 fiber，失败回滚保留旧代；含自重载）
dev_plugin_status	已装配插件清单、fiber 状态与操作成功率统计
dev_clear_routes	webserver 路由残留自愈（按 path 前缀删除孤儿路由）
dev_stage_add	开发侧挂：测试工具挂后侧（不进 tools schema，缓存零污染）
dev_stage_call	调用侧挂工具测试
dev_stage_list	列出侧挂工具（含转正状态）
dev_stage_promote	一键转正：侧挂工具挂前侧正式注册（唯一一次缓存刷新）
dev_stage_demote	撤回/注销侧挂或已转正工具

插件开发指南（生产线）

哲学：插件想长成什么样就能长成什么样——工具包 / 守护循环（timer+LLM 自主 agent loop）/ UI 面板 / 混合形态，同一注入通道；注入即完整生效（host+UI）、可热重载与自重载、卸载即净；插件自身的提示词/工具/循环皆可自我优化（改 → build → 重载闭环）。建新插件优先克隆/借鉴/重构生态已有资源（dsh-external 仓库、已注入插件、官方 packages 模式），不重复造轮子。

一分钟起步（生产线三件套）

# 1. 生成骨架（toolkit / daemon-loop / ui-panel / hybrid）
#    对 AI 说：dev_scaffold_plugin {"dir": "D:/dev/my-plugin", "name": "my-plugin", "form": "daemon-loop", "description": "..."}

# 2. 构建打包（探测 DSH_CHECKOUT → tsc host → tsdown client（如声明）→ npm pack → tgz）
#    对 AI 说：dev_build_plugin {"dir": "D:/dev/my-plugin"}

# 3. 发布（gh release create v + tgz）
#    对 AI 说：dev_release_plugin {"dir": "D:/dev/my-plugin", "version": "0.1.0"}

# 注入即活：dev_inject_plugin {"dir": "D:/dev/my-plugin"}
# 改代码 → build → 自动 watch ~1.5s 重载（或 dev_reload_package）

30 行写一个"会思考的插件"（守护循环最小示例）

import type { Context } from 'cordis'
import type LlmService from '@deepseek-ai/dsh-llm'
import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'

type AppContext = Context & { llm: LlmService; setInterval(fn: () => void, ms: number): any }

export const name = 'my-daemon'
export const inject = ['timer', 'llm']

export function apply(ctx: AppContext): void {
  let route: { provider: string; model: string } | null = null
  ctx.on('llm/stream', (options, next) => { route = { provider: options.provider, model: options.model }; return next() })
  ctx.setInterval(() => {
    void (async () => {
      if (!route) return
      const stream = ctx.llm.stream({
        provider: route.provider, model: route.model,
        system: '判断是否需要人工介入，直接输出结论',
        messages: [createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: '检查事项...' }] })],
        reasoningEffort: ReasoningEffortId('off'), maxTokens: 200,
      })
      for await (const chunk of stream) { /* 决策 → 行动 */ }
    })().catch(() => {})
  }, 60_000)
}

规范铁律（注入器实测沉淀）：

1. 资源注册必须挂 ctx.effect（工具/路由/监听）——热重载/卸载才能自动清理，否则僵尸残留（注入器自己踩过）
2. peerDependencies 用范围声明（>=0.0.1-rc =4.0.0-rc /packages/core/tools）；

• client bundle 需单独构建：host 侧 bash scripts/build.sh（tsc），client 侧 npm run build:client（tsdown，产物 lib/client.js）——注入插件要出 UI 必须两步都构建；
• 失败 import 会毒化重试：loadCache 残留残缺 job 导致同名重载复用失败态——注入前 purgeCache 清理；
• 资源注册必须挂 ctx.effect：reloadPackage 重建失败若报 duplicate / already registered，说明资源是裸注册——挂 ctx.effect 后热重载才能正确清理重建；
• client 操作必须用完整包名：client-modules.processOne 对 entry.options.name 精确匹配，传短名会静默注册失败；
• 注入的插件不进 loader 配置持久化——重启后由注入器自动恢复（引导器常驻）。

Router Observer（实时路由观测）

DSH-better-sidebar 侧边栏「路由」tab：实时查看思维模式路由（router-standard / router-spec）的当前快照与时间线。

• 数据来源：passive observer 旁路重算——订阅 session 事件流，用 router-core 纯函数即时重算 route / promote / tool / guide 事件；不 invoke dev_router_status、不污染 agent 上下文。
• 实时：tab 可见时 2s 短轮询；面板隐藏自动暂停（DSH-better-sidebar 的 visible 约定）。未装 better-sidebar 时降级为设置页只读入口。
• API（挂在 /super-injector/api 前缀下）：
  • GET /router/sessions — 会话列表（含 confidence / observed / processed / drift）
  • GET /router/status?sessionId= — 当前快照（mode / band / persona / core / override / source / confidence）
  • GET /router/timeline?sessionId= — 有界时间线 + windowStart
  • GET /router/debug?sessionId= — 观测统计 + drift 详情 + router-core 解析来源（SHA-256）
  • GET /router/selftest — 自检结果
• 可信度来源：每条事件带 source: observed | derived | baseline | calibrated。derived = 旁路重算（≈）；observed = 观测到真实工具调用；calibrated = 从 dev_router_status 返回文本解析出的最高可信源。
• 漏洞：dev_router_mode 的 override 是 router-bootstrap 闭包内存态，observer 只能从工具调用推断；错过事件 / auto 清除 / 重启会让时间线漂移。v1 用会话启动基线 + 免费校准（解析 dev_router_status 返回文本）缓解；drift-on-mismatch：dev_router_status 解析结果与旁路推导状态不一致时发射 drift 并把 confidence 置 low。telemetry(B)（router 侧 emit 真实 override）已记入 backlog 作为终态事实源。

---

仓库：https://github.com/yjh051108/dsh-super-injector Release：https://github.com/yjh051108/dsh-super-injector/releases