5.0 KiB
Hub 通知脚本用法
仅在 Hub 已按 通知规则 判断需要通知、准备调用脚本时读取。脚本须由部署负责人放在目标 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 调用仍可使用，前提是该文件有执行权限。
项目事件通知
python scripts/dingtalk_notify.py progress milestone "**已完成**：本阶段成果已确认并归档。下一步安排联调。"
事件仍只有 start、milestone、blocked、complete、failed。脚本自动加项目名、中文状态和本机带时区时间；不自动判断项目阶段或完成状态。
多行 Markdown 可直接作为一个参数传入。较长或含引号的摘要优先保存为 UTF-8 正文文件，再用 --file；不要把大段成果或日志当通知：
python scripts/dingtalk_notify.py progress milestone --file "项目资料/00-项目管理/通知摘要.md"
这里的路径是调用示例，须先在实际项目中生成相应摘要，不能假定文件存在。文件路径相对当前工作目录解析；--file 是读取消息正文，不是上传附件。进度摘要和 --file 二选一。
自定义摘要与负责人提醒
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 主流程。