# Hub 通知脚本用法

仅在 Hub 已按 [通知规则](dingtalk-progress-reporting.md) 判断需要通知、准备调用脚本时读取。脚本须由部署负责人放在目标 Hub 项目的 `scripts/`；安装 Skill 本身不会部署脚本、配置或凭据。找不到入口时说明未部署并继续主任务，不猜绝对路径、不临时绕过封装。

## 选一个入口，不重复调用

共用实现为 `scripts/dingtalk_notify.py`，依赖 Python 3.9+；真实发送还需原生 `dws`。相对命令从目标项目根目录执行。

所有系统由封装统一从目标项目 `.dingtalk/config.env` 的 `DINGTALK_PROGRESS_CLIENT_SECRET` 读取机器人密钥，不回退到环境变量或钥匙串。配置由部署负责人本地维护；Hub 不打开或展示真实配置、不在会话索取密钥。普通发送不需要 DWS 用户登录，按姓名提醒才额外需要同组织的已登录账号配置。

| 环境 | 项目事件 | 中文摘要／负责人提醒 |
| --- | --- | --- |
| 通用 Python | `python scripts/dingtalk_notify.py progress ...` | `python scripts/dingtalk_notify.py message ...` |
| Windows PowerShell 7.3+ | `./scripts/dingtalk-progress.ps1 ...` | `./scripts/dingtalk-bot-message.ps1 ...` |
| macOS/Linux | `sh scripts/dingtalk-progress ...` | `sh scripts/dingtalk-bot-message ...` |

Python 在 macOS/Linux 通常叫 `python3`；Windows 也可用 `py -3`。这是同一实现的不同入口，不是失败后依次尝试的备选发送渠道。原有 `./scripts/dingtalk-progress` 调用仍可使用，前提是该文件有执行权限。

## 项目事件通知

```text
python scripts/dingtalk_notify.py progress milestone "**已完成**：本阶段成果已确认并归档。下一步安排联调。"
```

事件仍只有 `start`、`milestone`、`blocked`、`complete`、`failed`。脚本自动加项目名、中文状态和本机带时区时间；不自动判断项目阶段或完成状态。

多行 Markdown 可直接作为一个参数传入。较长或含引号的摘要优先保存为 UTF-8 正文文件，再用 `--file`；不要把大段成果或日志当通知：

```text
python scripts/dingtalk_notify.py progress milestone --file "项目资料/00-项目管理/通知摘要.md"
```

这里的路径是调用示例，须先在实际项目中生成相应摘要，不能假定文件存在。文件路径相对当前工作目录解析；`--file` 是读取消息正文，不是上传附件。进度摘要和 `--file` 二选一。

## 自定义摘要与负责人提醒

```text
python scripts/dingtalk_notify.py message --title "联调需补充接口说明" --text "缺少接口返回值说明，联调暂时无法继续。请负责该接口的人补齐，并在自己的角色会话中同步结果。"
```

这个入口允许自定义标题，但不新增项目状态，不替代应该记录的阻塞事件。需要 @ 已知负责人时追加 `--at "完整姓名"`；多个姓名用逗号分隔或重复传入 `--at`。正文也可用 `--file` 代替 `--text`。

- 负责人称呼来自 Etunel 已绑定的 `member_alias`，不要把角色名称 `display_name` 当人员姓名，也不要让人每轮确认身份。
- 按姓名查找由封装执行，只使用部署时配置的同组织账号。没有配置账号、查不到、重名或返回无法识别时，本条不发送；请负责人澄清姓名或让部署负责人修正映射，不选择第一个、不换组织碰运气。
- `--at-id "姓名=userId"` 仅兼容已有且同组织的有效映射，由真实工具结果或部署负责人提供；不从 Etunel 角色标识推导，不主动索要人员编号。
- 默认发项目配置群。`--group` 仅保留给用户明确指定其他目标群的情形，不由 AI 猜群或扩大通知范围。
- 同一事项只形成一条合并通知。已经由事件通知说明清楚时，不额外发一遍提醒；没有变化时不循环催促。
- 通知必须指向实际下一步。负责人在线下讨论后回自己的角色会话补充结果，由角色完成原任务并经 Etunel 返回 Hub；群里已读或口头回复都不自动完成任务。

## 预览与结果

两个入口均支持 `--dry-run`；项目配置的预览开关也同时约束两者。预览不要求安装 `dws` 或填写密钥；会读取已有配置，但不使用密钥认证、不输出密钥、不查人员、不发送，只显示本地正文，@ 对象及目标配置未验证。

标准输出为精简 JSON，面向负责人时转述中文结果，不粘贴机器输出：

- `accepted`：服务端已接受，并返回有效 `processQueryKey`；不代表已读。
- `preview`：只有预览，未发送。
- `skipped`：未配置或未启用，未发送。
- `error`：本次停止；按说明区分失败和结果未知，不声称已发送或自行补发。

前三种退出码为 0，错误为 1；错误参数可能返回 2，因此不能只凭退出码 0 宣布已发送。封装内部处理有限重试，不要在脚本外再套重试。缺配置、凭据、权限或安装问题交部署负责人处理；通知失败不影响 Etunel 主流程。