8.9 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 --stage "阶段八：复盘结项" "**已确认的进展**
- 相关负责人已确认：产品验收材料已在线下完成，业务已确认客户验收通过。
- 项目已进入资料归档与复盘结项阶段，目前开始整理结项资料，项目尚未关闭。
- 已通知相关负责人进行阶段交接，不新增审批。
**待办事项**
- 结项资料整理：由中心真人负责人组织四类结项成果，Hub 协助整理工作稿。
- 资料补充：由产品负责人、业务负责人补充现有线下成果及确认记录，不重做验收。
- 旧事项停止：由 Hub 停止此前的验收准备催办。
- 结项确认：四类成果及遗留承接安排具备后，由 Hub 请 @{示例业务负责人} 确认结项。
- 关闭决定：业务确认结项后，由 Hub 请 @{示例中心负责人} 决定是否关闭；结项必需项完成后锁定四类成果。
- 本轮工作范围：不新增应用修复、设备测试或发布验证。
**遗留**
- 原测试不通过的结果如实保留，不因进入结项阶段改为通过。
- 已接受延期的问题如实保留，后续沿用 Bug 系统中的记录和已有处理安排继续跟进。" --at "示例业务负责人" --at "示例中心负责人"
python scripts/dingtalk_notify.py progress blocked --stage "阶段三：方案设计" "**已确认的进展**
- 本轮无新增已确认进展。
**待办事项**
- 方案设计：请 @{示例甲} 补充接口说明，并通过已约定渠道同步。
**遗留**
- 接口说明尚未补齐，影响方案确认；沿用该事项已有的责任和期限。" --at "示例甲"
python scripts/dingtalk_notify.py message --title "阶段三：方案设计｜资料补充提醒" --text "**待办事项**
- 方案设计：请 @{示例甲} 补齐已约定的接口资料，并通过已约定渠道确认。" --at "示例甲"
以上结项场景、事项和姓名仅作格式演示；验收结论、成果数量、延期安排和确认人不作为其他项目的默认事实或要求。真实发送须使用当前项目的有效记录和已确认的真人负责人姓名。
事件仍只有 start、milestone、blocked、complete、failed。progress 必须传入 --stage，值为 Hub 从当前项目记录取得的阶段编号及中文名称；未登记编号时仅使用已知名称。脚本生成“项目名称｜阶段编号：阶段名称”、带时区时间和自动汇报说明，不推断阶段、不把阶段写进固定配置。阶段缺失、空白、包含控制字符或超过 200 字时停止，不发送泛称“阶段里程碑”的通知。保留 DWS 的 AI 标识，不能冒充负责人本人批准或承诺。
旧调用需补充 --stage，并同步更新目标 Hub 项目的脚本与中心 Skill；仓库修改不等于目标项目已经部署。正文由 Hub 按通知写法组织“已确认的进展”“待办事项”“遗留”三个栏目，待办用“事项名称：由谁做什么”逐条编写。脚本生成加粗标题、时间与自动汇报说明，原样保留正文的条件、范围、顺序和完成状态，仅转换指定的 @ 标记，不自动拆句、推断责任人或追加任务。较长通知优先使用 --file，文件只保存三个栏目的正文。
- 多行中文 Markdown 作为一个参数传入；较长摘要可先保存成 UTF-8 文件，再用
--file "实际正文文件路径"替代摘要或--text。文件须实际存在，路径相对工作目录；这是正文，不是上传附件，不发送大段成果或日志。 progress和message均支持--at，多个姓名可逗号分隔或重复传入。负责人姓名来自项目中已确认的真人分工；使用 Etunel 时可读取已绑定的member_alias，不把角色名称当姓名；人员查询和发送固定使用初始化账号，不跟随默认账号切换。- 在待办或遗留条目中使用
@{完整姓名}，并在--at中列出同一姓名；脚本在该位置生成原生 @，不把已原位提及的人再追加到末尾。只传--at而未在正文指定位置的人仍追加到末尾。多人可分别放在各自事项中，同一人重复出现时只查询一次、发送接收人去重。缺少配对姓名或标记不完整时停止，不把普通文字 @ 当成原生提醒。 - 脚本只接受唯一姓名匹配，自动构造个人消息所需的
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 不追加外层重试。登录失效交负责人恢复，不换身份或渠道；通知异常不阻塞主任务，也不递归发送异常通知。