# Hub 个人 DWS 通知用法

仅在 Hub 初始化通知或按 [通知规则](dingtalk-progress-reporting.md) 准备发送时读取。脚本放在实际 Hub 项目的 `scripts/`，配置位于同项目 `.dingtalk/config.env`；安装 Skill 不会自动部署脚本。缺少入口时说明并继续主任务，不猜路径或绕过封装。

## 项目首次初始化

1. 用 `dws profile list --format json` 查询账号，向负责人显示姓名与组织；未登录请负责人完成 DWS 登录，不索取凭据。
2. 在选定账号下，用 `dws chat +chat-search --query "负责人提供的群名称" --page-all --profile "实际账号标识" --format json` 查群。账号或群有歧义、结果不完整时先澄清，不猜编号、不选第一项。
3. 一次确认发送账号、项目群及是否允许自动进度和必要 @ 提醒。人只确认名字与用途，不负责找编号。
4. 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，不再设置机器人相关参数。这些入口是同一实现，不能重复调用。

## 日常发送

```text
python scripts/dingtalk_notify.py progress milestone --stage "阶段八：复盘结项" "**已确认的进展**

- 相关负责人已确认：产品验收材料已在线下完成，业务已确认客户验收通过。
- 项目已进入资料归档与复盘结项阶段，目前开始整理结项资料，项目尚未关闭。
- 已通知相关负责人进行阶段交接，不新增审批。

**待办事项**

- 结项资料整理：由中心真人负责人组织四类结项成果，Hub 协助整理工作稿。
- 资料补充：由产品负责人、业务负责人补充现有线下成果及确认记录，不重做验收。
- 旧事项停止：由 Hub 停止此前的验收准备催办。
- Bug 事实确认：由 Hub 请 @{示例中心负责人} 先确认全部 Bug 的事实、对象、版本和实际处理或承接，已有有效确认直接引用。
- Bug 处理确认：中心确认事实后，由 Hub 请 @{示例产品负责人} 再次确认并在职责内决定处理；双方无异议后登记最终安排。
- 结项确认：四类成果、遗留承接及 Bug 双方确认具备后，由 Hub 请 @{示例业务负责人} 确认结项。
- 关闭决定：业务确认结项后，由 Hub 请 @{示例中心负责人} 决定是否关闭；结项必需项完成后锁定四类成果。
- 本轮工作范围：不新增应用修复、设备测试或发布验证。

**遗留**

- 原测试不通过的结果如实保留，不因进入结项阶段改为通过。
- 已接受延期的问题如实保留，后续沿用 Bug 系统中的记录和已有处理安排继续跟进。" --at "示例业务负责人" --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 按[通知写法](dingtalk-progress-reporting.md#消息写法)组织“已确认的进展”“待办事项”“遗留”三个栏目，待办用“事项名称：由谁做什么”逐条编写。脚本生成加粗标题、时间与自动汇报说明，原样保留正文的条件、范围、顺序和完成状态，仅转换指定的 @ 标记，不自动拆句、推断责任人或追加任务。较长通知优先使用 `--file`，文件只保存三个栏目的正文。

- 多行中文 Markdown 作为一个参数传入；较长摘要可先保存成 UTF-8 文件，再用 `--file "实际正文文件路径"` 替代摘要或 `--text`。文件须实际存在，路径相对工作目录；这是正文，不是上传附件，不发送大段成果或日志。
- `progress` 和 `message` 均支持 `--at`，多个姓名可逗号分隔或重复传入。负责人姓名来自项目中已确认的真人分工；使用 Etunel 时可读取已绑定的 `member_alias`，不把角色名称当姓名；人员查询和发送固定使用初始化账号，不跟随默认账号切换。
- 在待办或遗留条目中使用 `@{完整姓名}`，并在 `--at` 中列出同一姓名；脚本在该位置生成原生 @，不把已原位提及的人再追加到末尾。只传 `--at` 而未在正文指定位置的人仍追加到末尾。多人可分别放在各自事项中，同一人重复出现时只查询一次、发送接收人去重。缺少配对姓名或标记不完整时停止，不把普通文字 @ 当成原生提醒。
- 脚本只接受唯一姓名匹配，自动构造个人消息所需的 `openDingTalkId` 和提及标记。查不到、重名或权限不足时停止，不让负责人手填编号，不删掉 @ 降级发送。
- 默认且仅发配置的项目群。同一事项合成一条，事件通知可直接 @ 人，不额外重复提醒。提醒讨论结果通过已约定渠道返回并留档，不在群里另派任务或批准。

## 阶段交接和关闭通知

中心真人已批准推进或条件授权实际满足后，将上一阶段总结与下一阶段已确认安排合为一条 `milestone`。阶段内已授权的关键进展、阻塞、失败通知保留，同轮合并。等待决定时先在中心会话汇报，不宣称已进入下一阶段。

项目实际关闭后，用 `complete` 发送一次结项总结，保留未修复 Bug、失败测试和已确认承接；后续整理资料不重复发送。完整示例见 [通知规则](dingtalk-progress-reporting.md)。较长正文可保存为 UTF-8 文件，先离线预览：

```text
python scripts/dingtalk_notify.py progress milestone --stage "实际当前阶段" --file "阶段交接正文.md" --at "已确认完整姓名" --dry-run
python scripts/dingtalk_notify.py progress complete --stage "阶段八：复盘结项" --file "结项总结正文.md" --at "已确认完整姓名" --dry-run
```

正文文件和姓名须替换为实际值，正文无真人提醒时省略 `--at`。通知范围已授权且本次满足触发条件后，真实调用去掉 `--dry-run`；用户要求先审核时先取得本次发送确认。脚本仅渲染和发送，推进授权、Bug 确认和是否已发由中心查原记录判断。正文及真实结果回写阶段过程记录，不新增队列或外层重试。

## 检查与结果

排障可用 `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 不追加外层重试。登录失效交负责人恢复，不换身份或渠道；通知异常不阻塞主任务，也不递归发送异常通知。