# 钉钉审批客户端安装任务

用户把本文件或本文件的链接交给你，即表示授权你为当前用户安装或更新“钉钉审批”客户端、Skill 和名为 `dingtalk-approval` 的 MCP。该授权不包含同意、拒绝、退回、撤回或发起任何审批。

请从“步骤 1”开始逐项执行并验收，不要跳步，不要让用户手工填写企业凭证，也不要根据经验自行改写安装器返回的路径或 MCP 配置。Windows 是完整支持的平台，必须优先使用下面的 PowerShell 步骤。

## 固定发布入口

- 版本：`{{VERSION}}`
- 安装器：`{{INSTALLER_URL}}`
- 安装器 SHA-256：`{{INSTALLER_SHA256}}`
- 发布公钥：`{{PUBLIC_KEY_URL}}`
- 公钥 SHA-256：`{{PUBLIC_KEY_SHA256}}`
- 公钥编号：`{{RELEASE_KEY_ID}}`
- 签名清单：`{{MANIFEST_URL}}`
- 清单签名：`{{MANIFEST_SIGNATURE_URL}}`
- 统一网关：`{{GATEWAY_URL}}`
- Node.js：`>=22.13.0`

首次安装通过上述 HTTPS 地址和固定 SHA-256 建立信任；安装器随后必须使用固定公钥验证 Ed25519 清单签名和全部发布物哈希。URL、TLS、签名或哈希任一不匹配都必须停止。不得索取 AppKey、AppSecret、AuthoritySecret、CorpId、userId、员工号、Cookie 或 Token。

## 完成标准

只有以下条件全部成立，才能告诉用户“安装完成，可以使用”：

1. Node.js 版本满足要求，安装器与公钥 SHA-256 均正确；
2. 安装器 JSON 返回 `ok: true`；
3. 已按当前 Agent 的官方方式安装返回的 `skillPath`；
4. 已原样使用返回的 `mcpConfig` 注册并信任本地 stdio MCP；
5. `approval_login` 确认已登录；
6. `approval_list_todos` 的双来源验证中，钉钉 OA 与薪福通都为 `ok`；
7. 未执行任何审批写操作。

## 步骤 1：检查运行环境

在当前用户权限下运行：

```text
node --version
npm --version
```

Node.js 必须为 `22.13.0` 或更高版本，npm 必须可用。不要使用管理员权限、`sudo`、全局 npm 安装、DWS 或浏览器自动化。若刚安装或升级 Node.js，先打开一个新的终端，再重新执行版本检查。

## 步骤 2：下载并校验首次安装文件

不要在浏览器中复制下载内容，不要对 URL 解码、重新编码或手工拼接。原样使用上面的 HTTPS URL。

### Windows（PowerShell）

在普通 PowerShell 中逐行运行：

```powershell
$dingInstallDir = Join-Path ([System.IO.Path]::GetTempPath()) ("dingmcp-install-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $dingInstallDir -Force | Out-Null
$dingInstaller = Join-Path $dingInstallDir "installer.mjs"
$dingPublicKey = Join-Path $dingInstallDir "release-signing-public.pem"
Invoke-WebRequest -Uri "{{INSTALLER_URL}}" -OutFile $dingInstaller
Invoke-WebRequest -Uri "{{PUBLIC_KEY_URL}}" -OutFile $dingPublicKey
$dingInstallerHash = (Get-FileHash -Algorithm SHA256 $dingInstaller).Hash.ToLowerInvariant()
$dingPublicKeyHash = (Get-FileHash -Algorithm SHA256 $dingPublicKey).Hash.ToLowerInvariant()
if ($dingInstallerHash -ne "{{INSTALLER_SHA256}}") { throw "安装器 SHA-256 不匹配，停止安装" }
if ($dingPublicKeyHash -ne "{{PUBLIC_KEY_SHA256}}") { throw "发布公钥 SHA-256 不匹配，停止安装" }
```

任一 `Invoke-WebRequest` 或哈希检查失败都必须停止，不能忽略错误继续。

### Linux / macOS（POSIX shell）

```bash
ding_install_dir="$(mktemp -d)"
curl --fail --location --output "$ding_install_dir/installer.mjs" "{{INSTALLER_URL}}"
curl --fail --location --output "$ding_install_dir/release-signing-public.pem" "{{PUBLIC_KEY_URL}}"
printf '%s  %s\n' '{{INSTALLER_SHA256}}' "$ding_install_dir/installer.mjs" | sha256sum --check --strict
printf '%s  %s\n' '{{PUBLIC_KEY_SHA256}}' "$ding_install_dir/release-signing-public.pem" | sha256sum --check --strict
```

macOS 没有 `sha256sum` 时，使用 `shasum -a 256` 分别计算并精确比较，不得跳过校验。

## 步骤 3：执行唯一通用安装入口

### Windows（PowerShell）

继续使用步骤 2 的同一个 PowerShell：

```powershell
$dingInstallJson = & node $dingInstaller install --manifest-url "{{MANIFEST_URL}}" --public-key $dingPublicKey --json
if ($LASTEXITCODE -ne 0) { throw "钉钉审批安装器执行失败：$dingInstallJson" }
$dingInstall = $dingInstallJson | ConvertFrom-Json
if ($dingInstall.ok -ne $true) { throw "钉钉审批安装失败：$($dingInstall.error)" }
$dingInstall | ConvertTo-Json -Depth 20
```

### Linux / macOS

```bash
node "$ding_install_dir/installer.mjs" install --manifest-url "{{MANIFEST_URL}}" --public-key "$ding_install_dir/release-signing-public.pem" --json
```

这是唯一通用安装入口。安装器会在稳定的当前用户数据目录安装客户端与 Skill，不会全局安装 npm 包，也不会修改 Agent 私有配置。保留完整 JSON 结果，后续只使用其中的真实字段，不要猜路径。

安装结果至少必须包含：

- `ok: true`、`status: "installed"` 和 `version`；
- `cliPath`、`bridgePath`、`skillPath`；
- `loginCommand`；
- `mcpConfig.mcpServers.dingtalk-approval`；
- `postInstall`。

Windows 的 `bridgePath` 和 `mcpConfig...command` 正常应以 `dingtalk-approval-bridge.cmd` 结尾。路径中可能包含空格；保留完整字符串，不要拆分，不要去掉 `.cmd`，不要改为 `node`、`npx` 或远程 URL。

## 步骤 4：安装 Skill 并注册 MCP

1. 按当前 Agent 的官方方式安装 `skillPath` 指向的整个目录，而不是只复制 `SKILL.md`。确认目录中同时存在 `SKILL.md` 和 `references/create-approval.md`。
2. 使用 `mcpConfig` 只新增或替换名称精确为 `dingtalk-approval` 的连接器。安装器本身不会猜测或修改 Agent 的私有配置。
3. 如果 Agent 接受完整 MCP JSON，原样使用整个 `mcpConfig`；如果界面只接受单个服务器配置，原样使用 `mcpConfig.mcpServers.dingtalk-approval`。
4. 该连接器必须是本地 `stdio`，`command` 必须是返回的本地 `bridgePath`，`args` 必须为空数组。Windows 中必须保留 JSON 已正确转义的反斜杠。
5. 不要把 `{{GATEWAY_URL}}` 或 `https://approval.justconn.top/mcp` 作为 MCP URL、command 或参数；Bridge 会从已签名安装状态取得网关地址。
6. 不要添加 `--url`、企业凭证、用户 ID、额外环境变量或 shell 包装器。

正确配置的形态由安装器返回，语义如下；示例路径不能代替真实返回值：

```json
{
  "mcpServers": {
    "dingtalk-approval": {
      "type": "stdio",
      "command": "<安装器返回的本地 bridgePath；Windows 为 .cmd>",
      "args": []
    }
  }
}
```

## 步骤 5：处理首次登录状态

安装器已经主动尝试准备登录。读取返回的 `postInstall` 及其 `status`，不得等到用户第一次查询审批：

- `authorization_required`：在完成本地 Skill/MCP 配置的同一轮回复中，把 `postInstall.authChallenge.directUrl` 作为完整、可点击的 URL 原样发给用户；不得只说“已生成”或“已推送”。同时说明链接有有效期，需由用户本人核对授权页面并确认。
- `authenticated`：已有登录可复用，不需要再次让用户授权，继续步骤 6 和步骤 7。
- `unavailable`：客户端安装仍然有效。先完成步骤 4；连接器加载后调用 `approval_login` 重试。不要删除会话、不要重装。

保存 `loginCommand.command` 和 `loginCommand.args`。如果首次链接过期且 MCP 尚未加载，按该对象原样执行命令；Windows PowerShell 的通用执行方式是：

```powershell
$dingLoginJson = & $dingInstall.loginCommand.command @($dingInstall.loginCommand.args)
$dingLogin = $dingLoginJson | ConvertFrom-Json
$dingLogin | ConvertTo-Json -Depth 20
```

把新结果中的 `authChallenge.directUrl` 原样展示。该命令只检查登录或生成新链接，不下载发布物、不修改 Agent 配置。MCP 已加载时则直接重新调用 `approval_login`。登录链接过期时绝不能重新安装。

## 步骤 6：信任并加载连接器

1. 如果当前 Agent 要求信任本地连接器，按其官方界面或命令确认名称为 `dingtalk-approval` 的连接器。
2. 如果不能热加载，完整退出并重新启动 Agent，或新建一个确定会重新读取 MCP 配置的会话；只刷新聊天内容通常不够。
3. 重启后确认能发现 `approval_login`、`approval_list_todos` 等钉钉审批工具。当前版本应发现 13 个工具。
4. 若连接器进程退出、显示 302 或无法启动，先执行步骤 9 的 Windows 排障，不要把连接器改成远程 HTTP MCP。

## 步骤 7：确认登录并验证两个审批来源

用户完成网页授权后：

1. 调用 `approval_login`。工具不会通过其他消息通道自动推送链接；如果响应仍给出 URL，必须把 `content.text` 中的完整登录 URL 原样写入当前回复。
2. 登录成功后，按 `postInstall.verifyTool` 调用一次只读的 `approval_list_todos`，即 `source="all"`、空搜索、`limit=1`。
3. 检查结果中的 `sourceStatus`：`dingtalk.status` 和 `xft.status` 都必须是 `ok`。`disabled`、`auth_required`、`unavailable` 或缺少任一来源都不算安装验证完成。
4. 验证期间只读取最多一条待办，不调用任何写工具。
5. 成功响应包含 `onboarding.firstRun=true` 时，把其中的简短示例和安全提示向用户展示一次，不要自动执行示例。

## 步骤 8：向用户报告结果

最终只需清楚报告：已安装的版本、Skill 与 MCP 已加载、登录是否成功、钉钉 OA 与薪福通是否都通过只读验证。可以给出一次性使用示例。不要向用户倾倒安装 JSON、内部路径、Token、审批引用或诊断细节，除非用户正在排障。

安装阶段不得处理审批，也不得在登录和双来源验证完成前声称“已可使用”。

## 步骤 9：Windows 常见故障排查

按顺序排查，不要跳到重装：

1. **显示 302 或启动后立即退出**：检查连接器是否被错误配置成 `{{GATEWAY_URL}}` 或其他 HTTP URL。正确配置必须是 `type: "stdio"`，`command` 为本机 `dingtalk-approval-bridge.cmd`，`args: []`。重新复制安装结果中的 `mcpConfig`。
2. **路径不存在或 Node 升级后失效**：不要引用 Node/NVM 的版本目录。执行安装结果中的 `cliPath`，或运行 `dingtalk-approval print-config --format mcp-json` 重新取得稳定配置。
3. **Bridge 仍无法启动**：执行 `<cliPath> doctor --json`。只有所有 `checks` 都为 `ok: true` 才继续；把失败检查和错误原文报告给维护者，不要提供 Token 或会话文件。
4. **提示找不到 npm-cli.js**：当前 Node 安装不完整。安装带 npm 的 Node.js 22.13+，打开新 PowerShell，重新检查 `node --version` 和 `npm --version` 后再运行安装器。
5. **路径包含空格**：不要手写命令行字符串。把安装器返回的整个 `mcpConfig` 作为 JSON 对象交给 Agent；在 PowerShell 中执行 CLI 时用调用运算符 `&` 和独立参数。
6. **连接器一直未出现**：确认已信任本地连接器并完整重启 Agent。不要通过反复重装刷新连接器。
7. **授权链接过期**：MCP 已加载就再次调用 `approval_login`；否则执行保存的 `loginCommand`。不要重装。

## 更新

更新不需要重新下载首次安装器。使用上次安装结果中的 `cliPath`：

Windows PowerShell：

```powershell
$dingUpdateJson = & $dingInstall.cliPath update --json
$dingUpdate = $dingUpdateJson | ConvertFrom-Json
$dingUpdate | ConvertTo-Json -Depth 20
```

Linux / macOS：

```text
<cliPath> update --json
```

更新会复用已固定的签名清单地址和公钥并保留 OAuth 会话。更新成功后，重新使用返回的 `mcpConfig` 核对同名连接器，并重新连接 MCP；必要时完整重启 Agent。然后重复步骤 7 的登录确认和双来源只读验证。

## 卸载

1. 按当前 Agent 的官方方式删除名称精确为 `dingtalk-approval` 的 MCP/连接器条目。
2. 执行安装结果中的 `cliPath uninstall --yes --json`；Windows PowerShell 可运行：

```powershell
& $dingInstall.cliPath uninstall --yes --json
```

3. 确认返回 `uninstalled` 或 `cleanup_scheduled`。后者表示当前 CLI 退出后完成自清理。

卸载默认清除客户端运行时、Skill、安装记录和 OAuth 会话。不要手工递归删除未知目录。

授权页面会展示请求客户端、回调域名、权限范围或设备授权码。必须由用户本人核对并确认，不得替用户自动提交 consent。网关短暂不可用时保留现有登录状态并稍后重试，不要删除会话文件或主动要求用户重新授权。