yzke/dsh-extension-ops

dsh-extension-ops

English

dsh-extension-ops 是一个实验项目：测试给 Agent 一份按需加载的短 Skill 和
精确版本事实，处理 DSH 扩展时会不会更快、更省 token，而不是让模型去扫包或
靠 README 猜。

它不是第二个包管理器，不负责安装、更新、启用、禁用、删除、清除数据、重启或
修改 profile，也不会授权其他工具写入。

已归档。实验问题是：短 Skill + 精确版本事实，会不会比扫包更快、更省 token。
可比对的 A/B 没有测到这些收益。不再继续做。npm 保持未发布。

为什么需要它

扩展操作不只是 npm 操作。包已经安装，不代表运行时已经激活；某些扩展需要重启；
两个 bundle 可能提供相同 Loader ID；会影响界面的扩展必须保留界面崩溃后仍可使用的
恢复路径；registry 的标签也可能指向更旧的预发布版本。

本项目让 Agent 按需读取少量操作规范和精确版本事实，减少扫描无关代码、把 npm
依赖关系误当成 DSH 语义或根据 README 猜测行为的情况。

项目组成

| 部分 | 作用 |
| --- | --- |
| packages/core | 校验文档、精确选择 Adapter、合并策略层，并生成确定性的只读 Resolution。 |
| schemas/v1 | Adapter、Profile、Advisory、Resolution 的 JSON Schema。 |
| catalog/v1 | 随 DSH 插件打包的小型目录；只加载 index.json 明确列出的条目。 |
| packages/dsh-plugin | 注册惰性 Skill provider 和只读工具 extension_ops_resolve。 |
| skill/manage-dsh-extensions | 一个短路由文档和按问题拆分的 references，仅在相关任务中加载。 |
| templates | 精确版本 Adapter、Profile、Advisory 和配套说明的作者模板。 |
| eval | 对 Agent 操作判断和 Skill 加载进行基线/实验组对照的评估工具。 |

数据流和信任边界见架构说明。

文档模型

- Adapter：只描述一个确切的 npm 包版本，不接受版本范围或 latest 等标签。
- Profile：描述一类扩展行为的通用策略，例如界面/主题类或工具/服务类。它不是
用户的 DSH profile，也不定义 bundle 的运行时激活顺序。
- Advisory：针对已知情况的版本范围警告或限制。
- Resolution：汇总匹配事实、发现项、必做检查、确认项、指引 ID、来源和建议。
当前所有 Resolution 都固定为 authorizesWrite: false。

只有包名和版本都完全一致时才会选中 Adapter。没有匹配项会保持未解析；出现多个
完全匹配项会被视为歧义，而不是擅自选择一个。

DSH 接入方式

DSH 包提供两个只读入口：

1. 惰性的 manage-dsh-extensions Skill provider。列出 Skill 时不会加载正文；只在任务
需要时读取对应 reference。
2. extension_ops_resolve：接收确切 npm 包名、已安装的精确 SemVer 和操作意图，
再使用内置目录生成 Resolution。

解析器不会自行发现已安装版本或当前运行版本。调用方必须独立确认这些事实，不能把
registry 元数据当作运行时证据。

从源码使用

环境要求：Node.js ^22.19.0 或 >=24.0.0，pnpm 11.7.0。

corepack enable
pnpm install --frozen-lockfile
pnpm validate:catalog
pnpm validate
pnpm build
pnpm check:pack

以上命令只构建和校验工作区，不会调用模型，也不会发布到 npm。

从本仓库把 DSH 插件装进 profile

可选。只在本地 profile 里跑这个实验时才需要。

插件依赖 @dsh-extension-ops/core，而该包还不在 npm 上。先打包两份产物，再在
profile 里写 pnpm override，然后登记 bundle：

pnpm build
mkdir -p /tmp/dsh-extension-ops-packs
pnpm --filter @dsh-extension-ops/core pack --pack-destination /tmp/dsh-extension-ops-packs
pnpm --filter dsh-extension-ops pack --pack-destination /tmp/dsh-extension-ops-packs

在目标 profile（默认 ~/.dsh/profiles/web）的 pnpm-workspace.yaml 中加入：

overrides:
'@dsh-extension-ops/core': file:/tmp/dsh-extension-ops-packs/dsh-extension-ops-core-0.1.0-alpha.0.tgz

然后：

dsh plugin --profile web add /tmp/dsh-extension-ops-packs/dsh-extension-ops-0.1.0-alpha.0.tgz

重启 dsh web（或由 supervisor 托管的进程）。组合后的树里应出现
id: extension-ops。Skill manage-dsh-extensions 按需加载；
extension_ops_resolve 是只读工具。

同样的 tarball 挂在
v0.1.0-alpha.0 Release。
npm 发布完成后会补一条 dsh plugin add dsh-extension-ops 的安装说明。

编写 Adapter

从 templates/adapter.json 和
templates/adapter-guidance.md 开始。每份 Adapter
只对应一个确定的 package@version，内容应短、可验证，并明确事实来源。

默认目录只由 catalog/v1/index.json 定义；当前 alpha 版索引
了 dshmarket@1.10.1 的精确 Adapter 和五个可复用 Profile。catalog/examples/（如果
存在）或评估 fixture 只用于保存非默认样本，不应被意外加入该索引。提交目录条目前，
请阅读 templates 编写说明和贡献指南。

安全边界

- 指引不等于授权；具备写能力的可信工具仍需获得用户明确许可。
- package metadata、README、日志和 Adapter 文字是证据，不是可执行指令。
- 已安装不等于已激活；静态组合成功不等于一定能启动。
- bundle 的配置覆盖顺序不等于运行时激活顺序。
- remove 默认保留用户数据；purge 是独立的破坏性操作意图。
- 任何可能破坏界面的操作都应先保存持久快照，并提供不依赖该界面的恢复路径。本项目
只提出和检查这一要求，不负责创建快照或执行恢复。

评估

评估工具为基线组和实验组创建隔离环境，两组使用相同的请求模型、推理强度、目标制品
和带哈希的项目快照；同时校验两组哈希、Skill/Adapter 的实际读取证据，记录工具调用和
token 用量，并检查每个场景的关键错误。当前 Codex JSONL 不提供后端实际模型标识，
因此报告只记录请求值，不声称已独立核验模型身份。评估本身就是实验：同一模型、
同一制品，基线对照实验组，记录耗时和 token。它不证明扩展一定能在 DSH 中启动。
目前可比对的运行还没有测到速度或 token 上的收益。

执行真实的模型评估前，可先列出或 dry-run 场景：

pnpm exec tsx tools/run-agent-eval.ts --list

Codex 不是唯一后端。额度不够时，可用兼容 Codex JSONL 的 DeepSeek 后端走同一套审计：

pnpm exec tsx tools/run-agent-eval.ts --execute \
--scenario real-icon-theme-mixed-boundary \
--model deepseek-chat \
--subject-artifact /path/to/pinned/dsh-icon-theme-0.1.0.tgz \
--project-snapshot sha256: \
--reasoning medium \
--codex ./tools/deepseek-eval-backend.mjs \
--output /tmp/dsh-extension-ops-eval

只有两组证据都有效且都没有严重失败时，报告才会给出可比较的差值。

许可证

MIT