dsh-workspace-scaffolds
把 DSH 工程与工程使用的脚手架插件关联起来：开工前准备、工作中追加、不用时休眠保留到磁盘、再次使用时随工程恢复。⚠️ 仅部分验证，实验性代码。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Eru07734/dsh-workspace-scaffolds#6eaa8a3453a76aeeab8dfd1672f30afec62f69d7Workspace Scaffolds 以 dsh-workspace-scaffolds 发布，当前版本为 0.1.12。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
✅ 评审 14 项已全部修复 · ALL 14 REVIEW FINDINGS FIXED
一次独立代码评审发现 14 项可复现缺陷（5 项 P1、9 项 P2），我已逐条对照源码确认全部成立，并已全部修复。 修复过程中又发现并修复了 1 项评审之外的缺陷（F15：
splitName静默截断超长路径，产出连自己的读取器都拒绝的归档）。 逐条状态、修法与仍未关闭的残余风险见 docs/review-response-2026-10-12.md。已在真实 DSH 0.2.0-rc2 隔离实例上验证（
D:\dsh-verify-020rc2，独立 home / profile / 端口，不触碰日常工作 profile）：
- 完整工作流：注册工程 → 导入脚手架包 → 关联 → 预览 → 生成文件 → 启用 → 休眠 → 恢复；
- 插件的安装与热载入（
application: "applied"，无需重启）；- 休眠真正在原生侧停用 bundle，恢复后重新启用；休眠不误停用别的工程仍在使用的包；
- 重启后的状态对账：关联、版本、原生状态与归档保持一致，且对账不会误钉；
- HTTP 进度：导入运行期间可轮询到中间步骤；
- 脚手架注册的工具在真实 agent 回合中被提供、被调用，其返回载荷出现在消息记录里；
- 评审 P1 的现场复核：解绑只释放被移除的那个关联；自动恢复登记共享持有者；
- 评审 P2（第二批）的现场复核：未满足的声明依赖被拒且
requires跨重启存活；重复导入不改写归属；部分绑定更新被接受；必需脚手架关闭时ready=false；- 评审 P2（第三批）的现场复核：原生安装失败会让导入失败且不留下包记录（用真实失败的安装造出来，不是 mock）；预览之后的冲突零写入。
未验证：浏览器面板的视觉渲染。逻辑与状态有测试覆盖，但真实浏览器里的画面始终没有人眼确认——这一项自始至终未变。
详细证据、缺陷记录与验证方法见 docs/verification.md。
把 DSH 工程（Workspace）与工程使用的脚手架插件关联起来的插件。
| 术语 | 含义 |
|---|---|
| 工程 | DSH 原生 workspaceRegistry 中的 Workspace，用原生 workspaceId 标识 |
| 脚手架包 | 声明了 dsh.bundle 的原生 DSH 插件包，可以另外携带文件模板 |
| 关联 | 把某个精确版本的包记入工程清单；关联本身不加载任何东西 |
| 准备 / 恢复 | 通过原生插件管理器启用插件能力；不生成模板文件 |
| 生成 | 依据模板向工程写入新文件；必须单独执行，永不覆盖已有文件 |
| 休眠 | 释放工程对插件的占用；没有其他工程需要时才真正停用，磁盘文件全部保留 |
| 解除关联 | 从工程清单移除记录；已生成的文件保留 |
| 全局常驻 | 标记某个包始终启用，任何工程休眠都不会关闭它 |
租约（lease）是推导出来的，不是存下来的。 一个工程持有某个包的租约，当且仅当它处于「使用中」且该关联处于启用状态。这样就不会出现「存的租约和实际关联不一致」这类问题。
本插件是一个原生 DSH bundle。开发目录没有第三方依赖，Host 代码和浏览器代码都是普通 JavaScript。
# 在 DSH 中通过插件管理器安装本目录或发行包
dsh plugin add /absolute/path/to/dsh-workspace-scaffolds
# 或安装打包好的发行包
dsh plugin add ./dsh-workspace-scaffolds-0.1.9.tgz
安装后需要为本插件启用 bundle（默认 cordis.patch.yml 已声明）。面板出现在 插件页 → 本插件卡片，使用 plugins.bundle.config 插槽。
在面板「注册工程」中填写项目目录的绝对路径。插件会在原生工程注册表中登记它，并建立自己的管理记录——此时不关联任何脚手架、不启用任何插件、不写任何文件。
已注册的目录再次注册不会报错，也不会产生第二个工程：原生注册表按路径去重，插件会接管既有的那个，并保留它已有的关联。
在面板「导入脚手架包」中填写绝对路径，可以是：
package.json（且声明了 dsh.bundle）的目录；.tgz 包。导入会依次完成：校验原生 bundle 声明 → 校验可选的 scaffold.json → 打包并计算 SHA-256 → 存入本地归档 → 通过原生插件管理器安装但不启用。
在「已关联脚手架」区域选择包并点击「添加到该工程」。关联只写配置，不加载插件、不写工程文件。
对声明了模板的包点击「生成预览」：
create / identical / conflict 状态；conflict 时整批阻止，此时不会写入任何文件；rolledBack / leftBehind / partial，不会假装干净。进程被硬杀或断电时不存在回滚路径，会留下部分文件。点击「恢复」。所有必需的包都会依次启用；失败时不会把工程标成「已就绪」，并且会回滚本次新启用、且没有其他工程需要的包。
点击「休眠并保留」：
面板分为四块：
所有写操作都携带当前 revision；版本冲突时面板会重新读取状态并提示，不会盲目重放。
面板标题行显示三个标签：配置版本、profile 名称、以及当前运行的构建版本（pluginVersion）。当 profile 声明的构建与内存中运行的不是同一个时，面板会额外显示一行提示和所声明的 spec —— 也就是「更新已写盘，但需要重启才生效」这个状态，不必再靠行为反推。
工具名 workspace_scaffolds，动作与 HTTP 接口一致。默认工程取自当前会话的工作目录（通过原生工程注册表按规范化路径精确匹配，不做前缀猜测）。
读操作：
list — 完整状态，包含 revision、工程、关联、包和阻塞项。operation-status — 按 operationId 查询进度与结果。scaffolds — 读取某个包的模板描述。写操作（必须携带 list 返回的 expectedRevision 与一个新的 UUID operationId）：
workspace-register — 把一个已存在的目录注册为受管工程（path，可选 title）import、bind、unbind、update-binding、set-pinwake、sleeptemplate-preview、template-applydelete-archiveoperationId 与参数一起构成幂等键：同参数重试会返回记录过的结果而不重复执行；同 ID 换参数会被拒绝（operation-id-reused）。
wake 返回 effectiveFrom: "next-model-request" —— 这是准确语义：当前已经发给模型的工具列表不会改变，新增能力在下一次请求生效。
GET /api/workspace-scaffolds/state
GET /api/workspace-scaffolds/progress # 只读进度，适合高频轮询
GET /api/workspace-scaffolds/progress?operationId=<id>
POST /api/workspace-scaffolds/execute
成功：{ "ok": true, "value": ... }；失败：{ "ok": false, "code": "...", "details": { ... } }。
请求体上限 1 MiB。配置、版本、模板冲突返回 409，输入错误 400，找不到 404。
import 会真的跑包管理器，wake 要逐个原生启用 bundle；这些请求在完成前如果不返回任何中间信息，调用方就只看到一个卡住的连接。因此耗时的动作会被登记成一条进度记录，可以在它还在跑的时候查询：
// POST /execute { "action": "import", ..., "background": true }
{ "ok": true, "value": {
"operationId": "…", "action": "import", "status": "running", "background": true,
"progress": { "phase": "validate package", "steps": [ /* … */ ] } } }
// GET /progress （或包含在 GET /state 的 progress 字段里，一次轮询即可）
{ "ok": true, "value": {
"running": [ {
"operationId": "…", "action": "import", "status": "running",
"phase": "install without enabling",
"steps": [
{ "label": "validate package", "status": "done", "detail": "dsh-scaffold-notes@0.1.0" },
{ "label": "install without enabling", "status": "active" },
{ "label": "record in warehouse", "status": "pending" }
] } ],
"recent": [ /* 最近完成的，保留 20 条 */ ] } }
实际轮询效果（真实输出，install 被注入 1.2s 延迟以便观察）：
tick 2
import running phase=install without enabling
[x] validate package (dsh-scaffold-notes@0.1.0)
[x] hash and archive (8700a0a14de3)
[x] read scaffold descriptor (1 template(s))
[>] install without enabling
[ ] record in warehouse
要点：
background: true 让耗时动作立刻返回 operationId，而不是把连接挂到跑完为止；配合 /progress 轮询即可。适用于 import、wake、sleep、template-apply。pending / active / done / failed / skipped；wake 与 sleep 会按包动态追加步骤（每个包一行），因为这些步骤在计划时就已确定但数量取决于关联。operation-status）。operation-status 对进行中的操作同样可用（读实时进度），不必等它写入操作日志。/progress 并逐步渲染，而不是只显示一个转圈。list（以及 GET /state）的返回值里带有三个诊断字段，用来回答「现在到底是哪个构建在跑」：
| 字段 | 含义 |
|---|---|
pluginVersion | 正在内存中运行的构建版本，读自该模块自己的 package.json |
profileSpec | profile manifest 为该插件声明的依赖 spec（即「请求的是哪个」），读不到时为 null |
restartPending | 前者与后者不一致，需要重启 DSH 才会生效 |
pluginVersion 取自运行中的模块自身，而不是 profile 声明——后者恰恰是会在「更新已写盘、进程仍持旧代码」时说谎的那个。
restartPending 是保守启发式：只对 file: / link: 这类把具体产物写进字符串的本地 spec 判定；^0.1.0 这类注册表范围描述的是一个可接受集合，不是另一个构建，因此永不报告为待重启。读不到版本时一律返回 false，不会把「未知」伪装成任何结论。
invalid-request、workspace-not-found、workspace-unavailable、revision-conflict、operation-id-reused、package-content-conflict、version-conflict、dependency-missing、dependency-cycle、protected-bundle、restart-required、native-overridden、native-operation-failed、template-conflict、preview-expired、preview-stale、path-outside-workspace、archive-in-use、state-corrupt、unsupported-host、not-a-bundle、package-unknown、scaffold-invalid、archive-invalid。
sleep 在有空闲问题时返回 status: "pending-idle" —— 这是正常的异步状态，不是错误。
全部状态位于当前 profile 目录下：
<profileDir>/workspace-scaffolds/
state.json 权威状态（含 revision、工程、包、预览、操作日志）
state.json.bak 上一次成功的状态，用于损坏恢复
archives/<sha>.tgz 内容寻址的脚手架包快照
operations/ 预留的操作目录
staging/ 临时解包目录（用完即删）
规则：
revision，写入使用「临时文件 + 原子改名」。state.json 损坏时先从 .bak 恢复；没有可用备份就报错停止，绝不把损坏状态当成空状态。schemaVersion 高于本插件支持的版本时只读报错，不做降级。template-apply 必须引用预览 ID。工程目录里只有你显式生成的模板文件；本插件不写隐藏清单、不改 .gitignore。
这些是已知且有意的限制，请按此预期使用：
version-conflict，不会替换正在运行的版本。agent/created 自动恢复只走快路径：只对已安装的包做启用，绝不在创建 agent 时运行包管理器。需要安装时，面板会显示待处理项，由「恢复」显式完成。自动恢复有 15 秒预算；超时会记录并标记为 degraded，不会挂起启动。验证分两层，两层都要看：
node --test test/*.test.mjs # 171 项单元测试（假宿主）
第一层：单元测试（内存假宿主，但执行的是真实的 src/host.js 适配层）：
| 验证了什么 | 没验证什么 |
|---|---|
171 项 node:test 用例全部通过 | 浏览器面板的真实渲染与交互 |
| Linux（Node 22 / 24）与 Windows 上均通过 | — 真实环境由第二层覆盖 |
真实适配层被实际执行（非桩替换）：installBundle(..., {enabled:false}) 等契约在测试范围内 |
第二层：隔离 DSH 0.2.0-rc2 实例上的端到端验证（主流程 + 评审 P1/P2 复核共 66/66、重启对账 9/9、agent 层 12/12）：
| 验证了什么 | 没验证什么 |
|---|---|
| 完整工作流：注册 → 导入 → 关联 → 预览 → 生成 → 启用 → 休眠 → 恢复 | 浏览器面板的视觉渲染（布局与样式） |
| 休眠真的在原生侧停用 bundle；恢复真的重新启用 | 与 0.2.0-rc2 以外版本的兼容性 |
| 两个工程共享同一 bundle 时，休眠不误停用别人仍在用的包 | |
| 重启后的状态对账（关联、版本、原生状态、归档一致，且不会误钉） | |
| HTTP 进度可在长操作运行期间轮询到中间步骤 | |
| 真实 agent 回合中脚手架注册的工具被提供、被调用，且其返回载荷出现在消息记录里 |
验证环境：独立 home D:\dsh-verify-020rc2、独立 profile verify、独立端口 —— 与日常工作 profile 完全隔离，验证产物也留在隔离区内。
测试覆盖的验收场景与结果见 docs/verification.md。
试用前请自行确认：本插件会在 <profileDir>/workspace-scaffolds/ 下写入状态，并会调用原生插件管理器启用／停用 bundle。请先在非关键 profile 或副本工程上验证。
一个可运行的脚手架包就是原生 DSH bundle，可以额外声明模板：
{
"name": "dsh-scaffold-notes",
"version": "0.1.0",
"type": "module",
"exports": { ".": "./plugin.js" },
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
"workspaceScaffold": "./scaffold.json"
}
scaffold.json：
{
"schemaVersion": 1,
"title": "工程笔记",
"variables": {
"projectName": { "type": "string", "required": true, "maxLength": 100 }
},
"templates": [
{
"id": "notes",
"files": [
{ "source": "templates/NOTES.md", "target": "docs/NOTES.md", "render": "text" }
]
}
]
}
render: "text" 只支持 {{variableName}} 替换，不支持表达式、脚本或递归 include。render: "copy" 原样复制二进制资源。requires 用于声明依赖其他脚手架包（精确版本），由本插件做依赖排序与环路检测。examples/ 下有两个可直接导入的示例：dsh-scaffold-notes（只提供模板）与 dsh-scaffold-checks（提供 project_checklist 工具与模板）。
MIT