dsh-actions

dsh plugin --profile web add dsh-actions

DSH Actions

简体中文 ｜ English




写一份跟随仓库的 actions.json，它同时是你在右侧栏点一下就跑的面板入口，和 Agent 可以直接调用的结构化工具——同一份定义，同一个审批闸门。

开发过程中要反复执行的操作，远不止跑一遍测试：

• 各类 check 与测试；
• 生成代码、生成文档的脚本；
• 数据上传、资源同步；
• 提交前跑一遍 lint；
• 触发一次 CI 构建、查一次构建状态；
• 按环境发布；
• 查一次线上服务状态。

它们的共同点有两个：一是反复执行——做同一个需求、跑同一类任务时，这些操作会被一遍遍重复；二是要切平台——在终端跑完命令，得去浏览器看 CI 状态，再登录另一个系统点发布。

让 Agent 来做，成本反而更高：查文档、编写、运行、调试，多轮循环才跑通一次，而下个会话又从头再来一遍，token 就这么一遍遍烧掉。

VS Code Tasks 的答案是「不用离开编辑器」。DSH Actions 更进一步——不用离开对话，而且跑一次就固化：人在面板上点一下，Agent 在会话里说一句话，输出就在同一个工作区里实时出现。

核心价值

1. 给人一个快捷启动方式——右侧面板里每个任务都是一次点击，不用再回忆命令、不用翻散落在各处的脚本；

2. Agent 参与构建——编写与固化都交给 Agent：一句指令把一个复杂操作变成可复用任务，多步流程也由它编码、由它调试。于是固化复杂操作从「要下决心做一次的工程量」变成顺手的事，不好用就丢掉，试错成本几乎为零；

3. 固化与复用——工作区层随仓库提交，就是团队共享（新同事 clone 下来就有全套任务）；全局层是个人跨项目；只在当前会话有意义的任务放会话层，用完即弃，经得起用的再提升到文件层；

4. 人与 Agent 共用同一套定义——人固化一次，Agent 在任何会话里都能调用；Agent 在工作中固化的任务，人点开就能复跑。

输出不只是文本：实时流式出现在 run tab 工作区，状态徽章一眼可读；失败即停、随时重跑；重复触发不会起重复实例，而是定位到正在跑的那个；把任务或某次运行以 chip 引用发给 Agent，就能接着输出继续追问。

高危任务还有一层 VS Code Tasks 没有的东西：审批闸门——标记过的任务，无论人点还是 Agent 调，都要经过你的显式确认才会启动。

执行权限按入口区分：你在面板中手动运行时，行为与 VS Code Tasks 类似，以 DSH Host 所属用户的本机权限执行；这会绕过 DSH 文件沙箱（但不会绕过操作系统权限），因此应把仓库中的 Action 视为可执行的本机代码。Agent 通过 actions_run 调用时，approval: never 默认继承会话沙箱；approval: agent/always 使用一次合并审批，明确授权运行及本次 danger-full-access，批准后以本机用户权限执行，不改变会话权限。权限失败可通过 actions_run 的 retryRunId + justification 申请提权重试，无需绕回 Bash。两者共用定义、运行状态和日志，Agent 不能未经审批获得额外权限。Web 面板及其同源插件代码属于同一受信任客户端边界；approval 是防误触确认，不是抵御已被攻陷客户端的安全隔离。

配置的唯一来源是独立的 actions.json（JSONC）——不提供、也不计划提供对其他任务格式的运行时导入或桥接。

现状：新会话启动时，可供 Agent 调用的 Action 摘要与四个 actions_* 工具的职责会自动进入运行时上下文；完整命令、参数细节和运行输出仍通过 actions_query 渐进披露。尚未完成的是「在会话框直接触发一次运行、把结果回插进对话」。

目录

• [界面](#界面)
• [安装](#安装)
• [30 秒跑通](#30-秒跑通)
• [一份配置，两个面](#一份配置两个面)
• [使用场景](#使用场景)
• [三层设计](#三层设计)
• [项目起源](#项目起源)
• [文档地图](#文档地图)
• [包身份](#包身份)
• [致谢](#致谢)
• [License](#license)

界面

右侧栏入口 · 面板总览 · 参数 Modal

!开始页的 Actions 卡片 · !三层分区的任务面板 · !带参数的任务运行前弹出参数 Modal

运行输出 · /actions: 引用菜单 · Agent 审批流

!run tab 工作区的实时输出 · !输入 / 选择任务，引用进对话 · !Agent 调用带审批的任务：引用 → 加载 skill → 尊重审批 → 人工闸门

安装

用 DSH 自己的插件命令装，然后重启：

dsh plugin --profile web add dsh-actions
# 重启 DSH Web

这条命令做三件缺一不可的事：先按你的 DSH 版本做插件兼容性预检（版本不匹配会直接拒绝，并告诉你怎么放行），再用 profile 自己的 pnpm 安装依赖，最后把声明了 dsh.bundle 的包登记进 dsh.profile.bundles——没登记就不会被加载。

别在 ~/.dsh/profiles/web 里直接 npm install：那个目录由 pnpm 管理，而且裸装会跳过 bundles 登记，包进了 node_modules 却永远不会被加载。

从源码安装（仅开发本插件时）：clone 本仓库后——

dsh plugin --profile web add /path/to/dsh-actions

装好后打开右侧栏的「开始」页，Actions 卡片就在那里。

版本要求

需要 DSH >= 0.1.7-alpha.1（写在 peerDependencies 里，安装时 DSH 会拿你的运行时版本逐条校验）。registry 上的 latest（0.2.0-rc.2）已满足这个下界，直接装即可，不用切通道。

版本不匹配时安装会被直接拒绝（提示 nothing was installed），并给出放行命令：

dsh plugin allow-version dsh-actions@<版本> --dsh-version <你的 DSH 版本> --accept-risk

放行只针对那一对确切的版本，且意味着你接受崩溃或数据损坏的风险——插件会加载进正在跑的 Web UI。正常情况下应该升级 DSH，而不是放行。

<details>

<summary><strong>下界为什么定在 0.1.7-alpha.1（可自行核实）</strong></summary>

因为插件在 0.1.5 上跑不起来，声明一个它撑不住的下界只会让人装上之后界面报错。

界面半边只从 @deepseek-ai/dsh-client-ui-primitives 取具名导出，一共 31 个。该包在 0.1.6-alpha.2 → 0.1.7-alpha.1 之间把整套图标改了名（IconCheckOutline16 / IconCheckOutline14 → IconCheckOutlineRegular），并新增了 Checkbox。所以 0.1.5-rc.3 上这 31 个里有 20 个不存在，React 拿到 undefined 当组件渲染会直接抛异常——而这些图标用在面板和 toolview（对话里的工具卡片）两处，崩起来是整个界面的问题。

版本号里看不出这一层，所以下界是扫出来的，不是推出来的。clone 本仓库后，任何一个版本都可以自己核实（该脚本是开发工具，不随 npm 包分发）：

node scripts/verify-floor.mjs 0.1.7-alpha.1   # 通过
node scripts/verify-floor.mjs 0.1.5-rc.3      # 列出缺失的 20 个

</details>

30 秒跑通

在工作区根目录写 .dsh/actions.json：

{
  "version": "1.0.0",
  "actions": [
    { "label": "check", "command": "pnpm check", "detail": "类型检查 + lint + 全部测试" }
  ]
}

detail 那一行不是可选装饰：它同时显示在面板和 actions_query 的返回里，Agent 靠它判断这是不是它要找的任务。

打开右侧栏「开始」页的 Actions 卡片，点 check 旁的运行，在统一运行弹窗确认后，输出在下方的 run tab 工作区实时流出。弹窗始终提供「完成后通知 Agent」勾选项，默认关闭，仅对本次运行生效；无参数时只展示该勾选项，有参数时一起填写。不勾选由 Actions 自身管理，不登记宿主 Jobs；面板输出、运行记录、显式取消与插件卸载清理保留，但不出现在 Jobs 列表。勾选时额外登记 Jobs，由宿主完成报告器通知 Agent。Agent 发起的运行保持原行为。这就是完整闭环：写配置 → 面板点击 → 看输出。保存配置文件即自动生效，无需刷新。

一份配置，两个面

同一个 actions.json，对人和对 Agent 是两种用法，背后是同一份定义——不是两套东西互相同步：

· 怎么发现 · 怎么用

人 · 右侧栏 Actions 面板 · 一次点击；带参数的弹出表单；输出流式可见

Agent · actions_query · 调用 actions_run，结构化返回结果

Agent 侧一共 4 个工具：actions_query / actions_run / actions_cancel / actions_configure，语义与取舍见 Agent 集成。其中 actions_configure 把会话中发现的流程注册成会话层任务，必经你批准——Agent 给自己造可执行命令属高危操作。

插件还随包带了一个 dsh-actions-authoring skill：你让 Agent 写 actions.json 时，它自己就会拿到全字段参考和策展指导，不用你翻文档。

使用场景

三个典型场景各有详述文档：

• 策展散落的脚本入口：npm scripts / Makefile / Taskfile / scripts/ 目录太分散？让 Agent 一次性策展固化成 `.ds

…(truncated)