- Inicio
- Plugins
- Flujos y automatización
- dsh-preset-workspace-hook
dsh-preset-workspace-hook
hluica/dsh-preset-workspace-hook
DSH plugin: switch the Agent preset for new sessions by workspace path.
Instalar
dsh plugin --profile web add github:hluica/dsh-preset-workspace-hookREADME
工作区预设切换(@local/dsh-preset-workspace-hook)
最后实质性修改于Harness版本:0.2.2-rc.5
在 DSH 中按工作区目录自动为新会话选择 Agent 预设:设置页维护“工作区条件 → Agent 预设”的映射,新会话创建时命中第一条条件就切换预设;未命中时保持 DSH 原有行为。
插件提供两种可选的执行方式:
- 优先尝试激进方案(默认):在会话创建请求进入 Host 时包装
sessionController.create,在 DSH 解析预设之前改写agentPreset,新会话从 header 起就使用目标预设。 - 只使用回退方案:不包装 Host 服务,在 Agent 创建完成、首轮开始前用公开的
agentPresets.select切换空白会话的预设。
两种方式共享同一份条件与预设映射,切换执行方式不需要重启。
使用与效果
设置页
Settings → 工作区预设切换(紧跟官方“Agent 预设”页)。
- 配置文件:显示
$DSH_HOME/dsh-preset-workspace-hook/config.json(默认~/.dsh/dsh-preset-workspace-hook/config.json)与当前实际生效方式。 - 启用自动切换:关闭后保留全部条件,但不改变任何会话的预设,也不再安装创建前包装。
- 执行方式:
- 优先尝试激进方案:先尝试创建前改写;若当前 DSH 无法安装包装,自动使用回退方案。状态行会显示“已安装 / 不可用(原因)/ 等待服务”。
- 只使用回退方案:完全不安装包装,只依靠公开事件与方法。
- 两项都附有原理与取舍说明;环境变量强制生效时会显示警告。
- 执行条件:
- 每条条件包含匹配方式(完全匹配 / 前缀 / 后缀 / 通配符 / 正则)、匹配对象(目录名 / 完整路径)、模式、正则 flags(仅正则时显示)和执行结果预设。
- 条件按从上到下的顺序匹配,第一条命中生效;可用上移/下移调整优先级。
- 增/删/改都先改本地草稿;点击“保存”才写入 Host,点击“放弃更改”恢复最近一次已保存配置。
- 删除条件先在行内显示“确认删除?”并提供“确认删除 / 取消”,不会立即删除。
- 当前 DSH 工作区查询:只读。点击“查询当前工作区”后按当前编辑中的条件计算(不保存配置),显示工作区标题、完整路径、目录名、命中的条件与结果预设。列表只显示命中的工作区;没有命中时只显示文字提示。需要手动刷新,不轮询。
- 可用 Agent 预设:只读。包含全部内置与自定义预设,标记默认与不可用项;需要手动点击“刷新预设列表”。
页面按六个圆角模块分组:配置文件、自动切换、执行方式、执行条件、当前工作区查询、可用 Agent 预设。「启用自动切换」使用 DSH 内置胶囊开关(说明文字在标题下一行);「执行方式」使用无单选点的居中单选卡片。条件卡片与预设卡片使用 1px 边框以增强分隔。预设列表不显示顺序。
保存和查询都会做本地校验:模式不能为空、必须选择预设、正则必须可编译;条件错误会就地提示并禁用保存。
配置文档
{
"version": 1,
"enabled": true,
"mode": "aggressive",
"conditions": [
{
"id": "cond-example",
"match": "prefix",
"target": "path",
"pattern": "/Users/me/work/",
"presetId": "standard"
}
]
}
| 字段 | 取值 | 说明 |
|---|---|---|
version | 1 | 仅支持版本 1 |
enabled | boolean | 全局开关 |
mode | aggressive / fallback | 执行方式;默认 aggressive |
conditions[].match | exact / prefix / suffix / glob / regex | 匹配方式 |
conditions[].target | name / path | 匹配目录名或完整路径 |
conditions[].pattern | string | 匹配模式 |
conditions[].flags | string | 可选,仅 regex 使用 |
conditions[].presetId | string | 命中的结果预设 |
匹配语义:
- 路径统一把
\归一为/,去掉末尾/;非正则模式大小写敏感。正则使用配置的 flags。 - 通配符支持
*(不跨/)、**(跨/;**/也匹配零层目录)、?(单个非/字符);其他字符按字面量匹配。需要字符类、分组或选择时请用正则。 name取完整路径的最后一段目录名。
代码/调试中显式强制回退
除了设置页和 config.json 的 mode 字段,还可以在启动 DSH 前设置环境变量:
DSH_PRESET_WORKSPACE_HOOK_MODE=fallback
环境变量优先于配置文件,适合升级排查或验证回退路径;DSH_PRESET_WORKSPACE_HOOK_MODE=aggressive 可反向强制激进方案。环境变量非法时忽略。
工作原理
激进方案:会话创建前改写
- Host 行通过
ctx.inject(['sessionController'], ...)包装sessionController.create(Remote 名session/create)。 - 每次创建请求按
workspaceId→workspaceRegistry.get().path、或cwd、或workingDirectory.defaultDirectory解析工作区;cwd不是 canonical 路径时会再尝试workspaceRegistry.resolveByPath。 - 命中条件后在
SessionCreateRequest上改写agentPreset,随后才进入 DSH 的composeAgent;目标预设直接写入新会话 header,也会覆盖“复用已有空白会话”。 - 如果目标预设在当前 DSH 已不可用(
agent-preset/not-found/agent-preset/invalid),包装会记录警告并用原 request 重试一次,避免本插件让原本能创建的会话失败。 - 包装是可恢复的 own property:保存安装前的 descriptor,插件卸载或切换到回退方案时还原;用共享 symbol 防止重复包装。
回退方案:Agent 创建后切换
- 回退不依赖
sessionController,只监听 serial 的agent/created事件。 - 仅处理空白、非 fork、非子会话的顶层会话:
turnBoundaryOf为lastTurn === 0、openTurnStartSeq === null,且header.isSeeded !== true、header.origin !== 'subagent'、header.parentSession为空。 - 用会话 header 的
cwd匹配条件;命中且当前预设不同时调用公开的agentPresets.select(agent, presetId),在首轮 prompt 之前完成切换。 - 该路径覆盖新建会话与复用已有空白会话,因此即使完全不安装创建前包装也能独立完成本插件的功能;代价是目标预设切换发生在原预设已经挂载之后。
- 在激进方案下回退仍会运行,作为未被
sessionController.create覆盖的路径的兜底;select幂等检查使已命中的会话直接跳过。 - 所有异常都在监听器内部捕获并记录,不会让会话创建失败。
配置与 API
- 配置由 Host 和设置页共享读取,按 mtime/size 缓存;保存使用临时文件 +
rename原子替换。 - 设置页通过 owner-only 的
/dsh-preset-workspace-hook/api路由与 Host 通信:GET /state:读取配置、路径、错误与当前 hook 状态;PUT /state:校验并保存{ enabled, mode, conditions };POST /workspaces/query:按请求中的草稿条件计算当前工作区结果;GET /presets:读取全部 Agent 预设;GET /health:当前执行方式、配置路径与条件数。
- 设置页是公开 slot
settings.section的 React 页面,不通过 iframe,不轮询;样式只使用宿主--dsw-alias-*token。
依赖与构建
- 零 npm 运行时依赖;Host 只使用 Node 内置模块,Client 只使用 React(由页面模块表提供)。
- Host 需要 DSH 的
sessionController(激进方案)、agentPresets(两种方案)、workspaceRegistry/workingDirectory(路径解析)与webServer/connection(设置 API)。缺失时对应能力显示为不可用,回退路径仍可工作。 - 本仓库的
scripts/由local-plugins/build-system同步而来;5 个共享文件按逐字节校验,不要手改。scripts/host-contract.mjs是本插件自己的探针。
npm run build
npm run verify
npm test
build 会物化依赖并自动运行 verify;本插件没有 dependencies,因此不会创建 node_modules/。
适用范围与边界
- 只处理普通顶层会话;fork、子会话、已有轮次的会话不会切换预设。
- 激进方案只覆盖经
sessionController.create(Remotesession/create)的创建/复用;回退方案覆盖所有空白顶层会话的 Agent 创建。两者都不处理 fork 与子会话。 - 命中条件时会覆盖界面请求中显式选择的预设;未命中时完全交给 DSH。
- 预设本身必须在当前 DSH 可用;条件中引用的预设被删除或激活失败时,创建不会因本插件失败,但本次不会切换,设置页/查询结果会标记“预设不存在/不可用”。
- 配置只在本机当前进程读取;多进程或外部编辑依赖 mtime 缓存,下一次会话创建/查询时生效。
- 激进方案包装的是公开业务服务方法,但“插件包装 Host service 实例方法”不是 DSH 承诺的扩展点;DSH 升级后应先运行
npm run verify,并用设置页状态行或GET /health确认包装是否仍安装。无法安装时会自动使用回退。
故障排查
| 症状 | 处理 |
|---|---|
| 设置页没有入口 | 确认 bundle 已启用并刷新页面;检查 dsh.client 与 settings.section 注册。 |
| 状态显示“等待 sessionController 服务” | Host 的 sessionController 尚未挂载;通常出现在启动早期,稍后刷新设置页或查看 /health。 |
| 状态显示“激进方案不可用,已使用回退方案” | 当前 DSH 的 sessionController.create 无法包装;切换“只使用回退方案”可消除歧义,或检查版本契约。 |
| 新会话仍使用原预设 | 检查工作区路径是否命中条件(用设置页“查询当前工作区”)、目标预设是否可用、全局开关是否关闭;查看 GET /health。 |
| 修改后没有生效 | 设置页是否点击“保存”;配置文件是否有解析错误;环境变量是否强制了另一种方式。 |
| 预设列表为空/不可用 | 当前 DSH 未提供 agentPresets,或预设激活失败;查看官方“Agent 预设”页与 Host 日志。 |
| 配置文件损坏 | 设置页会显示错误;修复或删除 config.json 后重新加载。保存会用页面内容覆盖损坏文件。 |
版本契约
- 插件版本:
0.1.3;行为、接口或执行方式变化时按 SemVer 提升。 - 目标 DSH:
0.2.2-rc.5;peerDependencies使用^0.2.2-rc.5。升级后先运行npm run verify,再核对SessionCreateRequest、SessionController.create、Gateway 的动态方法解析、agentPresets.select与settings.section。 - 私有面缺失时:插件仍可加载;设置页可用;回退方案尽量工作;
/health报告当前状态。
命名与文件
包名 @local/dsh-preset-workspace-hook,Loader entry id 与 Client module id 均为 dsh-preset-workspace-hook。Host 入口 index.js,配置加载 config.js,匹配 match.js,hook 包装与回退辅助 hook.js,Client 入口 client.js。FEASIBILITY@0.2.2-rc.5.md 记录设计依据与实施记录。
许可证
MIT License,详见 LICENSE。
Plugins relacionados
webnovel-writer
lingfengqaq/webnovel-writer
loopx (dsh-loopx-plugin)
loopx-project/loopx
ouroboros (dsh-plugin)
q00/ouroboros
loopx (dsh-loopx-plugin)
huangruiteng/loopx