dsh-agent-kit

支持

遇到问题

先运行一次 doctor（在可选的 @mc/dsh-agent-kit-admin 中），它会指出缺什么、怎么修。仍然解决不了时，欢迎在 GitHub 上提 issue。

提交 issue

请在 GitHub Issues 提交，并附上以下信息：

$npx @mc/dsh-agent-kit-admin doctor --profile <名字> --json

常见问题

为什么六个 Service 默认都是禁用的？

未启用的 Service 不会被加载，也不会校验配置，所以只用其中一两个时，不需要为其余的准备配置或环境变量。在 Profile 的 cordis.patch.yml 中按 id 启用即可；装了可选的 @mc/dsh-agent-kit-admin 时，也可以用 setup 或设置页勾选。

doctor 提示 dws 未登录怎么办？

在运行 Profile 的同一个系统用户下执行 dws auth login。admin 包的 setup 在配置 user 身份时也可以直接拉起登录；业务包也可以调用 ctx.dingtalk.login()，把返回的授权链接交给要登录的人。钉钉的 dryRun 模式与 webhook 身份不检查登录态。

Windows 上提示找不到 dws？

本包会在 PATH 中查找 dws.exe，或把 npm 全局安装生成的 dws.cmd 定位到它背后的 dws.js。仍然找不到时，在钉钉配置中把 dwsPath 设为 dws.exe 或 dws.js 的绝对路径；不要指向 .cmd 或 .bat。

doctor 提示飞书身份不可用怎么办？

bot 身份在运行 Profile 的同一个系统用户下执行 lark-cli config init，填写飞书应用的 App ID / App Secret；user 身份再执行 lark-cli auth login --scope "im:message.send_as_user im:message"，或由业务包调用 ctx.feishu.login() 把授权链接交给要登录的人。admin 包的 setup 在配置飞书时也可以直接拉起这两个命令。飞书的 dryRun 模式不检查身份。

怎么把通知从钉钉换成飞书？

业务包 inject notify、调用 ctx.notify.send() 时，只需启用并配置飞书行（agent-kit-feishu），再把 agent-kit-notify 的 channel 改成 feishu：手动编辑 cordis.patch.yml，或用 admin 包的设置页「通知渠道」卡片、重新运行 setup。修改原地生效，不需要改业务代码，业务插件也不会重新加载。同一时间只发往一个渠道；业务包也可以在运行中调用 ctx.notify.use('feishu') 临时切换，dsh 重启后回到配置值。

一定要装 @mc/dsh-agent-kit-admin 吗？

不需要。六个 Service 都在 @mc/dsh-agent-kit 里，业务包也只依赖它；配置直接写在 Profile 的 cordis.patch.yml 中即可。admin 包是可选的运维工具：doctor 检查、setup 交互式配置、dsh Web「设置 → Agent Kit」页，以及业务包设置入口的登记。需要时用 dsh plugin --profile <名字> add @mc/dsh-agent-kit-admin 加入 Profile。

claude-code 任务报 unsupported_permissions？

claude-code 和 codex 不支持按任务过滤工具，本包无法替它们强制只读，因此要求你在 agent-tasks 配置的 declaredPermissions 中如实声明 provider 实例的权限上限。claude-code 默认的 permissionMode: dontAsk 下不能执行命令或写文件，可以声明为 read-only。

TypeSafe Key 应该放在哪里？

读取顺序是环境变量 TYPESAFE_API_KEY、macOS 钥匙串（默认服务名 ai.typesafe.api-key）、dsh 凭据文件 $DSH_HOME/.credentials.yaml。用 admin 包的 setup 与设置页保存时，macOS 默认写入钥匙串，Linux 与 Windows 写入 dsh 凭据文件。

为什么设置页是只读的？

设置页由可选的 @mc/dsh-agent-kit-admin 提供。只有 dsh Web 绑定在 127.0.0.1 时设置页才可修改。绑定到其他地址，或没有加载 Web 服务时，设置页一律只读，避免把配置写入接口暴露到网络上。页面上会显示具体原因。

没有 dws、lark-cli 或 Agent 登录态，怎么在本地开发业务包？

把钉钉或飞书设为 dryRun: true，并使用 @mc/dsh-agent-kit/testing 导出的本地 WebSocket 测试服务端、假 subagent provider、Jev mock、假 dws 脚本（createFakeDws）和假 lark-cli 脚本（createFakeLark）。

没有 TypeSafe Key，能在本地跑 Jev 判断吗？

可以。把 Jev 行配置为 provider: laya，并给出 baseURL 指向本地部署的 Laya（例如 laya-serve，默认 http://127.0.0.1:8000）。Laya 与 Jev 接口相同，ctx.jev.judge() 用法不变；此时不需要 TypeSafe Key，也不会发送它。Laya 的准确率与 Jev 不同，切换前请用同一批问题对比结果与阈值。

可以和 gitflow-cli 共用 TypeSafe Key 吗？

可以。两者在 macOS 上都读取钥匙串中服务名为 ai.typesafe.api-key 的条目。如果你的 Key 还在旧名 gitflow-cli-typesafe 下，可以复制一份到新名，或在 Jev 配置中写 keychainService: [ai.typesafe.api-key, gitflow-cli-typesafe]。

Agent 任务为什么不出现在 dsh Web 的会话列表里？

claude-code 与 codex 以不持久化会话的方式运行，本包也不为每个任务创建根会话。审计依赖本包的结构化日志（prompt 与答案只记录长度与哈希）和业务包自己的记录。