Pular para o conteúdo principal
H

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-hook

README

工作区预设切换(@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 预设”页)。

  1. 配置文件:显示 $DSH_HOME/dsh-preset-workspace-hook/config.json(默认 ~/.dsh/dsh-preset-workspace-hook/config.json)与当前实际生效方式。
  2. 启用自动切换:关闭后保留全部条件,但不改变任何会话的预设,也不再安装创建前包装。
  3. 执行方式:
    • 优先尝试激进方案:先尝试创建前改写;若当前 DSH 无法安装包装,自动使用回退方案。状态行会显示“已安装 / 不可用(原因)/ 等待服务”。
    • 只使用回退方案:完全不安装包装,只依靠公开事件与方法。
    • 两项都附有原理与取舍说明;环境变量强制生效时会显示警告。
  4. 执行条件:
    • 每条条件包含匹配方式(完全匹配 / 前缀 / 后缀 / 通配符 / 正则)、匹配对象(目录名 / 完整路径)、模式、正则 flags(仅正则时显示)和执行结果预设。
    • 条件按从上到下的顺序匹配,第一条命中生效;可用上移/下移调整优先级。
    • 增/删/改都先改本地草稿;点击“保存”才写入 Host,点击“放弃更改”恢复最近一次已保存配置。
    • 删除条件先在行内显示“确认删除?”并提供“确认删除 / 取消”,不会立即删除。
  5. 当前 DSH 工作区查询:只读。点击“查询当前工作区”后按当前编辑中的条件计算(不保存配置),显示工作区标题、完整路径、目录名、命中的条件与结果预设。列表只显示命中的工作区;没有命中时只显示文字提示。需要手动刷新,不轮询。
  6. 可用 Agent 预设:只读。包含全部内置与自定义预设,标记默认与不可用项;需要手动点击“刷新预设列表”。

页面按六个圆角模块分组:配置文件、自动切换、执行方式、执行条件、当前工作区查询、可用 Agent 预设。「启用自动切换」使用 DSH 内置胶囊开关(说明文字在标题下一行);「执行方式」使用无单选点的居中单选卡片。条件卡片与预设卡片使用 1px 边框以增强分隔。预设列表不显示顺序。

保存和查询都会做本地校验:模式不能为空、必须选择预设、正则必须可编译;条件错误会就地提示并禁用保存。

配置文档

{
  "version": 1,
  "enabled": true,
  "mode": "aggressive",
  "conditions": [
    {
      "id": "cond-example",
      "match": "prefix",
      "target": "path",
      "pattern": "/Users/me/work/",
      "presetId": "standard"
    }
  ]
}
字段取值说明
version1仅支持版本 1
enabledboolean全局开关
modeaggressive / fallback执行方式;默认 aggressive
conditions[].matchexact / prefix / suffix / glob / regex匹配方式
conditions[].targetname / path匹配目录名或完整路径
conditions[].patternstring匹配模式
conditions[].flagsstring可选,仅 regex 使用
conditions[].presetIdstring命中的结果预设

匹配语义:

  • 路径统一把 \ 归一为 /,去掉末尾 /;非正则模式大小写敏感。正则使用配置的 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(Remote session/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