配置引导

doctor、setup 与设置页

本页介绍的都来自可选的运维工具 @baoyx/dsh-agent-kit-admin，不在基础包 @baoyx/dsh-agent-kit 中。业务包不需要依赖它；不装它时，五类能力照常工作，直接编辑 cordis.patch.yml 即可。需要时把它加入 Profile：

admin 包以常驻行 agent-kit-admin 注册（ctx.agentKitAdmin，即设置页调用的服务端接口），不影响基础包各行的启停。

三种方式读写的是同一份配置：Profile 目录下 cordis.patch.yml 中 id 为 agent-kit-* 的几行，以及业务包登记进来的行（见下文「业务包的行」）。手动编辑这个文件，效果也完全一样。

doctor：检查

• 只读，不修改任何文件，也不需要启动 dsh。
• 只检查已启用 Service 需要的项，每项显示通过、警告、失败或跳过，未通过的项附一条修复命令。
• 检查内容：Node 与 dsh 版本、基础包是否在 Profile 的 bundle 中、配置修改能否即时生效；各 Service 配置；钉钉 dws 安装与当前用户登录态；通知依赖的钉钉行是否已启用；Agent provider 与权限声明；Jev SDK 与 Key 来源。
• 缺少 dws 时，修复建议给出安装命令：npm i -g dingtalk-workspace-cli@1.0.62。
• --json 输出机器可读的报告；有失败项时退出码为 1，可以接入 CI。

setup：交互式配置

1. 选择 Profile。Profile 没装基础包时，会提示要执行的 dsh plugin --profile <名字> add @baoyx/dsh-agent-kit @baoyx/dsh-agent-kit-admin。
2. 多选要启用的 Service，已启用的默认勾选。
3. 安装缺少的 dws：启用了钉钉、而 dws 不在 PATH 中时，展示将要运行的安装命令并请你确认。跳过或安装失败时只打印手动命令。
4. 逐个配置，当前值作为默认值：
   • 钉钉：固定使用 user 身份；可以按群名搜索群，或直接输入群 ID；未登录时可以拉起 dws auth login；最后可以发送测试消息。
   • 通知：固定使用钉钉；未启用钉钉行时会提示。
   • Agent 任务：工作目录；为 claude-code、codex 声明权限上限。
   • Jev：先选服务（TypeSafe Jev 或本地 Laya）。TypeSafe：Key 输入时不回显；显示将保存到哪里；已有 Key 时可以保留。本地 Laya：填写服务地址；Laya 开启了鉴权时可保存 Key 到 dsh 凭据文件。
5. 以差异视图展示 cordis.patch.yml 的改动，确认后才写入。密钥单独保存，不出现在差异中。
6. 自动运行 doctor。

任何一步取消都不会写入文件；已保存的密钥保留。

设置页：在 dsh Web 中操作

Profile 中装了 admin 包时，启动后进入 dsh Web 的「设置 → Agent Kit」：

• 每个 Service 一张卡片：启用开关、运行状态、检查结果与配置表单。
• 钉钉卡片：当前登录的 user 扫码授权、群 ID → 业务插件路由、未命中群消息；不展示发送身份、默认目标或 dryRun。二维码由 dws 返回的真实设备授权链接在本机生成，能否完成授权取决于钉钉组织的 CLI 数据访问权限。
• 通知 Service 仍可由业务代码调用，但设置页不展示独立的通知卡片。业务插件可登记 dingtalk-target 字段，在自己的卡片中搜索并选择群或个人作为发送目标。
• 界面文案跟随 dsh Web 的语言，支持中文和英文；检查项的标题、详情和修复建议由服务端生成，目前只有中文。
• 保存时会比对配置文件的版本；如果期间有人改过这份文件（包括另一个终端里的 setup 或手动编辑），会提示冲突并刷新，避免覆盖。
• 保存成功后，dsh 会用新配置重新加载对应 Service（通知渠道例外，原地生效），页面随后自动刷新状态。
• TypeSafe Key 只能写入或清除，不能读回；页面只显示「已配置」与来源。清除与 gitflow-cli 共用的钥匙串条目前会先确认。
• Jev 卡片可在 TypeSafe Jev 与本地 Laya 之间切换。选 Laya 时填写服务地址，TypeSafe Key 面板换成 Laya Key（只存 dsh 凭据文件），检查项改为 Laya 服务能否连接。

业务包的行

业务包可以把自己的 loader 行登记进来：设置页多出一张同样的卡片（启用开关、运行状态、检查结果、配置表单和密钥），doctor 也会列出它的检查，scope 为该行的 id。

• 登记方式有两种：在业务包 package.json 的 dsh.agentKit.entries 里声明无副作用的清单模块；或在插件里调用 ctx.agentKitAdmin.registerEntry(...)。推荐用清单——业务插件没启用、配置有误或启动失败时，卡片和检查照样出现，而这正是最需要它们的时候。
• 条目类型与 defineEntry 从 @baoyx/dsh-agent-kit-admin/entry 导入（defineEntry 只做类型推断，业务包把 admin 包放进 devDependencies 即可）。运行时登记的插件要 inject agentKitAdmin，因此 Profile 中必须装有 admin 包。
• 保存任何一行，只替换那一行的文本；其他行（包括注释和格式）逐字节不变，并与基础包的行共用冲突检测。
• 业务行的密钥只写入 dsh 凭据文件；密钥名可以取自配置（例如 tokenEnv），保存新配置后跟随新名字。
• 业务行可登记 kind: 'dingtalk-target' 字段：按名称搜索当前 dws 账号可见的群或个人，人工选择后只保存稳定 ID。钉钉卡片的群消息接收路由与此发送目标互不绑定。
• patchReload: live 时，停用基础包的某一行会连带卸载所有依赖它的业务插件，dsh 进程仍在运行，systemd 等外部守护进程察觉不到。业务行声明了 dependsOn 时，设置页会在保存前列出会被连带停止的插件并请求确认。

写法见 README 的「把业务包的配置接入设置页与 doctor」。

密钥保存在哪里

平台	setup 与设置页的默认保存位置	读取顺序
macOS	钥匙串，服务名 ai.typesafe.api-key	环境变量 → 钥匙串 → dsh 凭据文件
Linux	$DSH_HOME/.credentials.yaml	环境变量 → dsh 凭据文件
Windows	$DSH_HOME/.credentials.yaml，写入后收紧为仅当前用户可访问	环境变量 → dsh 凭据文件

dsh 凭据文件与 .env 一样是明文，只靠文件权限保护；Agent 子进程以同一用户运行，理论上可以读到它。