5.8 KiB
Hub 个人 DWS 通知用法
仅在 Hub 初始化通知或按 通知规则 准备发送时读取。脚本放在实际 Hub 项目的 scripts/，配置位于同项目 .dingtalk/config.env；安装 Skill 不会自动部署脚本。缺少入口时说明并继续主任务，不猜路径或绕过封装。
项目首次初始化
- 用
dws profile list --format json查询账号，向负责人显示姓名与组织；未登录请负责人完成 DWS 登录，不索取凭据。 - 在选定账号下，用
dws chat +chat-search --query "负责人提供的群名称" --page-all --profile "实际账号标识" --format json查群。账号或群有歧义、结果不完整时先澄清，不猜编号、不选第一项。 - 一次确认发送账号、项目群及是否允许自动进度和必要 @ 提醒。人只确认名字与用途，不负责找编号。
- Hub 将真实查询结果传入
python scripts/dingtalk_notify.py init --profile "实际账号标识" --group "实际群标识" --project "项目名称" --yes。这是参数结构示例；值必须替换为同一账号的实际结果。脚本创建仅含开关、账号、群和项目名的配置，不存机器人密钥或登录凭据，不发测试消息。
已有有效配置直接沿用；变更发送账号或群须重新确认，初始化时加 --replace。旧机器人配置必须重新初始化，不能静默转换发送身份。账号、群选择与查询由 Hub 完成；init 校验账号登录，不替代负责人对目标群的确认。暂停通知可由 Hub 按负责人要求将 DINGTALK_PROGRESS_ENABLED 改为 0。配置和标识只用于本地工具，不粘贴到群或普通回复，不提交真实配置。
初始化时同时确认目标项目的 Git 忽略规则包含 .dingtalk/config.env，不把本机通知配置提交到仓库。
选择本机入口
共用实现依赖 Python 3.9+ 和已登录的原生 DWS。相对命令从目标项目根目录执行。
| 环境 | 初始化／检查 | 项目事件 | 摘要／提醒 |
|---|---|---|---|
| 通用 Python | python scripts/dingtalk_notify.py init ...／check ... |
同入口 progress ... |
同入口 message ... |
| Windows PowerShell 7.3+ | ./scripts/dingtalk-python.ps1 init ...／check ... |
./scripts/dingtalk-progress.ps1 ... |
./scripts/dingtalk-message.ps1 ... |
| macOS/Linux | 通常用 python3 执行共用入口 |
sh scripts/dingtalk-progress ... |
sh scripts/dingtalk-message ... |
Windows 优先用 .ps1，须同时部署共用启动器 dingtalk-python.ps1，它选择独立 Python，不使用可能隔离 DWS 登录的商店版；必要时用 DINGTALK_PYTHON 指定解释器。各系统均通过 PATH 查找原生 DWS，不再设置机器人相关参数。这些入口是同一实现，不能重复调用。
日常发送
python scripts/dingtalk_notify.py progress milestone "**已完成**：阶段成果已确认并归档。下一步安排联调。"
python scripts/dingtalk_notify.py progress blocked "缺少接口说明，请补充后回自己的角色会话同步。" --at "完整姓名"
python scripts/dingtalk_notify.py message --title "资料补充提醒" --text "请补齐已约定资料，并回自己的角色会话确认。" --at "完整姓名"
事件仍只有 start、milestone、blocked、complete、failed。脚本增加项目名、中文标题、带时区时间和自动汇报说明，不替 Hub 判断阶段。保留 DWS 的 AI 标识，不能冒充负责人本人批准或承诺。
- 多行中文 Markdown 作为一个参数传入；较长摘要可先保存成 UTF-8 文件，再用
--file "实际正文文件路径"替代摘要或--text。文件须实际存在，路径相对工作目录；这是正文，不是上传附件，不发送大段成果或日志。 progress和message均支持--at，多个姓名可逗号分隔或重复传入。负责人姓名来自 Etunel 已绑定的member_alias，不把角色名称当姓名；人员查询和发送固定使用初始化账号，不跟随默认账号切换。- 脚本只接受唯一姓名匹配，自动构造个人消息所需的
openDingTalkId和提及标记。查不到、重名或权限不足时停止，不让负责人手填编号，不删掉 @ 降级发送。 - 默认且仅发配置的项目群。同一事项合成一条，事件通知可直接 @ 人，不额外重复提醒。提醒讨论结果回各自角色会话，不在群里另派任务或批准。
检查与结果
排障可用 python scripts/dingtalk_notify.py check --at "完整姓名"，省略 --at 只查登录；它联网但不发送，不是每轮必做。两个发送入口加 --dry-run 可完全离线预览，不查人、不验证目标或 @ 效果。
initialized：已创建经确认的个人通知配置，未发送。accepted：真实个人发送响应成功且含非空openTaskId，请求已接受，不等于已投递、已读或接收端提醒成功。保留回执供排障，面向负责人只说中文结果。checked／preview／skipped：分别为只读检查、离线预览、未配置或未启用；都没发送。error：本次停止，按说明区分失败与未知，不自行补发。错误退出码为 1，参数错误可能为 2，不能只凭退出码 0 判断已发。
需要进一步核实投递时，按发送回执在同一账号下调用 dws chat +messages-query-send-status --open-task-id "真实回执值" --profile "配置账号" --format json 只读查询；按实际结果判断，不把 openTaskId 当消息 ID。脚本只在明确 DNS 失败时最多尝试 3 次、间隔 10 秒；其余失败或未知结果不重发，Agent 不追加外层重试。登录失效交负责人恢复，不换身份或渠道；通知异常不阻塞主任务，也不递归发送异常通知。