release: v1.0.2 跨平台钉钉通知与流程版本编号约定

2026-09-09 11:52:17 +08:00
1 parent 4f9efd175d
commit a08cfd6a3b
@@ -1,83 +1,105 @@
-# 钉钉进度通知参考
+# Hub 钉钉通知接入

-这里的脚本和配置只演示 Hub 如何向项目群发送辅助通知，不属于 Etunel 的任务通信主链路，也不能代替任务派发、负责人确认、阶段门禁或项目留档。成员 Agent 不调用本脚本。
+这套封装只帮助 Hub 向项目群发送进度、异常摘要和负责人提醒，不是 Etunel 任务通道，也不负责审批、阶段门禁或项目留档。仅更新此仓库不会部署到实际项目；由部署负责人明确安装，成员 Agent 不调用。

-当前布局刻意把工具和项目配置分开：
+## 文件与依赖

- `dingtalk-workspace-cli@1.0.60` 由 Bun 安装在用户级全局目录，项目不保存二进制或 `node_modules`。
- 官方 multi skills 保留在项目 `.agents/skills/dingtalk-*`，只对本项目生效。
- Client ID、群目标、`robotCode` 和汇报开关保存在项目 `.dingtalk/config.env`。
- Client Secret 从环境变量 `DING_SEC` 读取，未设置时回退到 macOS Keychain；脚本只临时注入给 `dws api`，App Token 由 DWS 自动获取和缓存。
+- [dingtalk_notify.py](../scripts/dingtalk_notify.py)：共用 Python 实现，含配置、消息、人员解析和有限重试。
+- [dingtalk-progress](../scripts/dingtalk-progress)／[dingtalk-progress.ps1](../scripts/dingtalk-progress.ps1)：项目事件入口。
+- [dingtalk-bot-message](../scripts/dingtalk-bot-message)／[dingtalk-bot-message.ps1](../scripts/dingtalk-bot-message.ps1)：自定义 Markdown 与负责人提醒入口。
+- [离线测试](../scripts/test_dingtalk_notify.py)：假配置、假凭据及模拟命令，不发送真实消息。

-项目统一通过稳定入口调用全局命令：
+依赖 Python 3.9+，不需要第三方 Python 包、jq 或 Bash 才能在 Windows 运行。PowerShell 入口要求 7.3+；也可直接运行 Python。macOS/Linux 保留 Shell 入口。

-```sh
-./scripts/dws version
-```
+真实发送需要 [官方 DingTalk Workspace CLI](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli) 的原生可执行文件。按官方安装说明选择系统版本；Windows 使用 `dws.exe`，不要把 npm/Bun 的 `dws.cmd` 或 `dws.bat` 当原生程序。可以把原生文件加入 Hub 进程的 PATH，或在项目配置的 `DINGTALK_PROGRESS_DWS_PATH` 填它的绝对路径。本仓库不保存二进制，不自动安装、登录或更新全局 Skills。

-Bun 默认阻止上游 `postinstall`；本机安装时已校验官方 SHA-256 并只释放 DWS 原生二进制，没有执行会发布全局 Skills 的安装脚本。升级 DWS 时也应保持这一边界。
+部署后检查 `python --version`（macOS/Linux 可用 `python3`）及原生 `dws version`。所用 DWS 需支持 `api --data -` 从标准输入读 JSON；正文、群参数不放命令行，密钥仅临时注入子进程环境。更换 DWS 版本后由部署负责人核对兼容性，离线预览不证明真实接口可用。

-## 应用身份（无需用户登录）
+## 部署到 Hub 项目

-本项目不执行 `dws auth login`。进度脚本通过 `dws api` 调用企业内部应用 OpenAPI：
+将共用 Python 文件和需要的平台入口一起放入目标项目的 `scripts/`，不要只复制一个入口。重试逻辑已合入共用实现，无需复制源项目的 `dingtalk-dns-retry.sh`。保持下列布局：

 ```text
-POST https://api.dingtalk.com/v1.0/robot/groupMessages/send
+目标项目/
+├── scripts/
+│   ├── dingtalk_notify.py
+│   ├── dingtalk-progress
+│   ├── dingtalk-bot-message
+│   ├── dingtalk-progress.ps1
+│   └── dingtalk-bot-message.ps1
+└── .dingtalk/
+    └── config.env
 ```

-管理员侧只需确保：
+由部署负责人从 [配置示例](config.env.example) 新建实际配置，别覆盖已有有效配置：

- Client ID/Secret 属于企业内部应用；
- 应用已有“企业内机器人发送消息”权限（`qyapi_robot_sendmsg`）；
- `robotCode` 属于同一个应用；
- 机器人已加入目标 `openConversationId` 对应的群。
+- UTF-8，可带 BOM，支持 Windows CRLF 和 LF；值按字面解析，不执行 Shell、不展开变量，不加 Shell 引号。
+- 初始保持 `ENABLED=0`、`DRY_RUN=1`（实际字段均有 `DINGTALK_PROGRESS_` 前缀）。
+- 配置包括应用、机器人、目标群、项目名称、开关及机器人密钥。机器人必须属于配置的应用，已经加入目标群，并具备企业内机器人发送消息权限（`qyapi_robot_sendmsg`）；脚本不自动加群或申请权限。
+- macOS/Linux 对实际配置执行 `chmod 600 .dingtalk/config.env`；接受 400 或 600。Windows 不以 Unix 权限位作门槛，由部署负责人用 NTFS 权限限制其他用户读取或修改配置。
+- 实际配置必须被目标项目的 Git 忽略。不要把它、真实凭据或内部标识回传给 AI 会话或提交仓库。

-当前使用 zsh 环境变量时，先确保它已导出（不要把真实值写进项目文件）：
+路径与当前工作目录无关：配置总从 Python 脚本所在项目根目录读取。消息的 `--file` 路径则相对当前工作目录解析。
+
+## 凭据：所有系统统一读取配置
+
+普通进度发送使用内部应用身份，不需要用户 OAuth 登录。Windows、macOS、Linux **只从本地 `.dingtalk/config.env` 的 `DINGTALK_PROGRESS_CLIENT_SECRET` 读取机器人密钥**，不再从 `DING_SEC`、其他环境变量或 macOS 钥匙串回退取值。
+
+由部署负责人在本地编辑器中填写该字段，保持单行字面值，不加 Shell 引号；不要在会话、命令历史或仓库示例里填写真实值。密钥为空或字段缺失时，真实发送停止并提示负责人补配置；离线预览不要求填写密钥。
+
+脚本仅在发送时把该值临时注入 DWS 子进程的 `DWS_CLIENT_SECRET`，同时注入配置中的 `DWS_CLIENT_ID`。这只是脚本内部对接 DWS 的方式，不需要负责人再配置环境变量。密钥不进入命令参数、消息正文、预览或错误输出；人员搜索进程也不会取得机器人密钥。
+
+实际 `config.env` 现在包含明文密钥：macOS/Linux 设为 400 或 600；Windows 通过文件“属性 → 安全”限制为 Hub 运行账号及必要管理员可访问，不放在公共共享目录。目标项目必须忽略实际配置及其备份，只提交空值示例。不要把配置文件用作 `--file` 正文、成果或通知附件。
+
+### 从旧配置迁移
+
+1. 更新共用 Python 脚本及需要的平台入口。
+2. 由部署负责人在本地配置补填 `DINGTALK_PROGRESS_CLIENT_SECRET`；删除旧的 `DINGTALK_PROGRESS_KEYCHAIN_SERVICE` 字段。
+3. 检查文件权限与 Git 忽略，再做离线预览；正式发送仍需要启用开关、正确的应用权限和目标群。
+4. 旧环境变量与钥匙串不再被脚本读取；本次改动不会删除其中原有内容。
+
+脚本每次调用重新读取本地配置，不再因为密钥配置依赖 Hub 继承某个终端的环境变量；Python、dws 路径及按姓名查询所需的 DWS 登录仍须对实际运行 Hub 的操作系统账号可用。
+
+## 可选的按姓名提醒
+
+`--at` 会调用 DWS 人员搜索，和应用机器人发送是不同的认证需求。只有使用按姓名提醒时，部署负责人需要：
+
+1. 在 DWS 中登录需要使用的组织账号；
+2. 将已确认的稳定 profile 填入 `DINGTALK_PROGRESS_PROFILE`；
+3. 确认该账号、机器人应用、目标群属于同一组织，且账号允许查询人员。
+
+脚本在搜索和发送中传入同一个 profile，不自动选择或切换账号；应用归属与群归属仍需部署负责人核对，脚本不能仅凭 profile 字符串证明二者一致。查询只接受完整姓名的唯一匹配；查不到、重名、权限不足或返回结构不支持时整条提醒停止，不默认选择第一个，也不静默删掉 @ 后发送。
+
+`--at-id` 和 `--group` 保留源脚本兼容能力，仅用于已有真实映射或用户明确指定的目标；不让 AI 猜编号或在群之间试发。普通进度通知不需要配置人员账号。
+
+## 先做离线预览
+
+在目标项目根目录选一种入口。以下命令只预览，不联网，不需要 dws，不查通讯录、不使用密钥认证。已有配置会在本地读取，但密钥不会输出：
+
+```powershell
+python scripts/dingtalk_notify.py progress milestone '本阶段成果已确认并归档，下一步安排联调。' --dry-run
+./scripts/dingtalk-bot-message.ps1 --title '需要补充接口说明' --text '请接口负责人补齐返回值说明，并回自己的角色会话同步结果。' --dry-run
+```
+
+macOS/Linux 等价命令：

 ```sh
-export DING_SEC='<Client Secret>'
+sh scripts/dingtalk-progress milestone '本阶段成果已确认并归档，下一步安排联调。' --dry-run
+sh scripts/dingtalk-bot-message --title '需要补充接口说明' --text '请接口负责人补齐返回值说明，并回自己的角色会话同步结果。' --dry-run
 ```

-也可以不设置 `DING_SEC`，改用本项目专用的 macOS Keychain 项。`-w` 必须放在最后，它会在终端中隐藏输入：
+两种入口都遵守配置的 `DRY_RUN=1`，显式 `--dry-run` 不能被配置取消。即使没有配置，也能显式预览正文；此时不表示项目配置可用。正文支持中文多行 Markdown；复杂正文建议先保存 UTF-8 文件，用 `--file` 代替内联摘要或 `--text`，它不是附件上传。

-```sh
-/usr/bin/security add-generic-password \
-  -U \
-  -a '<Client ID>' \
-  -s 'com.example.dingtalk.your-project' \
-  -l 'Your project DingTalk bot Client Secret' \
-  -w
+确认部署与发送授权后，负责人再将 `ENABLED=1` 且 `DRY_RUN=0`。仓库维护测试不能用真实发送作冒烟测试。实际 Hub 的事件判断、参数示例和结果含义见 [通知规则](../etunel-role-collaboration/references/dingtalk-progress-reporting.md) 和 [脚本用法](../etunel-role-collaboration/references/dingtalk-script-usage.md)。
+
+## 失败处理与测试
+
+仅明确的 DNS 解析失败每隔 10 秒重试，总计最多 3 次；已获有效回执即停止。认证、权限、未知错误不重试；超时或缺少回执不盲目重发。单次 DWS 调用超时 60 秒；本次结束后由 Hub 说明，不在外层循环重试。只输出安全摘要和发送回执，不输出原始请求或错误日志。
+
+本封装不建消息队列、计划任务、重发历史或通知状态库；避免重复事件仍由 Hub 利用已有项目留档判断，不重造 Etunel 软件机制。
+
+```text
+python -X utf8 scripts/test_dingtalk_notify.py
 ```

-`dws auth status` 显示未登录是正常状态，与 App Token 发送链路无关。
-
-## 配置进度群
-
-```sh
-cp .dingtalk/config.env.example .dingtalk/config.env
-chmod 600 .dingtalk/config.env
-```
-
-填写以下非密钥参数：
-
-```dotenv
-DINGTALK_PROGRESS_MODE=app-bot
-DINGTALK_PROGRESS_CLIENT_ID=<Client ID>
-DINGTALK_PROGRESS_TARGET=<openConversationId>
-DINGTALK_PROGRESS_ROBOT_CODE=<robotCode>
-```
-
-先保持 `DINGTALK_PROGRESS_ENABLED=0`。凭据和参数就绪后改为 `1`，并保持 `DINGTALK_PROGRESS_DRY_RUN=1` 做无网络、无发送的请求预览：
-
-```sh
-./scripts/dingtalk-progress milestone "**已完成**
-
- 项目资料已经归档
- 本阶段成果已经负责人确认
-
-**下一步**
-
- Hub 将安排下一阶段任务"
-```
-
-确认请求中的目标和正文正确后，再把 `DINGTALK_PROGRESS_DRY_RUN=0`。真实发送由 Hub 按根目录 `AGENTS.md` 的时机调用；响应中的 `processQueryKey` 才表示服务端已经接受该条机器人消息。摘要可以使用多行 Markdown，重点写已经确认的结果、下一步或阻塞原因，不要粘贴大段日志。
+测试仅在临时目录使用假配置、假密钥和模拟 DWS；同时检查当前系统可用的 PowerShell/Shell 入口，不访问真实项目配置。覆盖配置密钥为唯一来源、密钥不回显、不通过命令参数传递以及预览不认证，不等于完成真实钉钉发送验收。
@@ -1,19 +1,25 @@
-# Copy this file to .dingtalk/config.env, fill the selected mode, then chmod 600 it.
-# Values are literal text after '='; do not add shell quotes.
+# 由部署负责人复制为 .dingtalk/config.env；macOS/Linux 设置 chmod 600。
+# Windows 用当前 Hub 运行用户的文件权限，不套用 Unix 权限检查。
+# UTF-8（可带 BOM），支持 LF/CRLF；等号右侧是字面值，不加 Shell 引号，不执行变量。

-# Keep both switches safe until credential setup and a dry-run have succeeded.
+# 两个入口共用开关；显式 --dry-run 也永远不发送。
 DINGTALK_PROGRESS_ENABLED=0
 DINGTALK_PROGRESS_DRY_RUN=1

-# Enterprise-internal app bot: App Token via dws api; no user OAuth login.
+# 企业内部应用机器人：发送本身不需要用户 OAuth 登录。
 DINGTALK_PROGRESS_MODE=app-bot
 DINGTALK_PROGRESS_CLIENT_ID=
+# 仅在本地 config.env 填真实 Client Secret；本示例必须保持空值，绝不提交真实配置。
+DINGTALK_PROGRESS_CLIENT_SECRET=
 DINGTALK_PROGRESS_TARGET=
 DINGTALK_PROGRESS_ROBOT_CODE=
-DINGTALK_PROGRESS_KEYCHAIN_SERVICE=com.example.dingtalk.your-project

-# Client Secret is never stored here. The script first reads exported DING_SEC,
-# then falls back to the project-specific macOS Keychain item above.
+# 所有系统统一从 config.env 取密钥，不再读取 DING_SEC 或 macOS 钥匙串。
+# 可选：原生 dws 的绝对路径（Windows 填 dws.exe，不填 cmd/bat 包装器）。
+DINGTALK_PROGRESS_DWS_PATH=
+# 可选：按姓名 @ 时必需。由部署负责人确认与应用、目标群同组织的已登录 profile。
+# 普通进度通知可留空；不是 Etunel 人员或会话编号。
+DINGTALK_PROGRESS_PROFILE=

 DINGTALK_PROGRESS_PROJECT=你的项目名称
 DINGTALK_PROGRESS_TITLE_PREFIX=[项目进度]