# 个人 DWS 项目通知

Hub 使用负责人确认的个人 DWS 账号发阶段汇报和 @ 提醒。只需要原生 DWS、Python 3.9+ 和一个项目配置文件；不使用机器人、应用密钥、Webhook 或 Stream 监听。

**旧版升级：** 用新的个人账号配置替换旧配置，旧机器人配置不会自动转成个人发送授权。摘要入口已改名为 `dingtalk-message`／`dingtalk-message.ps1`，删除目标部署中的旧 `dingtalk-bot-message` 入口及 Stream 实验脚本。更新脚本和 Hub Skill／Hook 不等于已经迁移在途项目；按实际部署安排确认。

## 首次由 Hub 完成配置

负责人不需要找编号、复制配置模板或填写密钥。Hub 在项目初始化时执行：

1. 检查本机 DWS；未登录时请负责人通过官方 DWS 登录流程授权，不索取密码或 Token。
2. 用 `dws profile list --format json` 查看可用账号，以姓名和组织向负责人确认发送身份。
3. 在选定的同一账号下，用 `dws chat +chat-search --query "负责人提供的群名称" --page-all --profile "查询返回的账号标识" --format json` 查群；结果不完整或有多个候选时不能自行选第一个。
4. 一次问清：“是否由这个账号向这个项目群自动发送进度、阻塞和必要的 @ 提醒？”得到确认后，Hub 把工具实际返回的账号标识、群标识及项目名称传给初始化入口。下面为参数结构，不是需要人填写的编号表：

   ```text
   python scripts/dingtalk_notify.py init --profile "实际查询结果" --group "实际查询结果" --project "项目名称" --yes
   ```

初始化检查账号存在且可登录，创建 `.dingtalk/config.env` 并启用通知；**不会发测试消息，也不会替人确认群选择**。群标识必须来自该账号的查询结果。初始化不创建钉钉群、不申请权限。已有配置默认不覆盖；迁移或变更账号、群时重新确认，再加 `--replace`，原配置被替换且不另存含密钥的备份。

配置仅 4 项：

| 字段 | 含义 | 谁填写 |
| --- | --- | --- |
| `DINGTALK_PROGRESS_ENABLED` | `1` 启用、`0` 暂停 | 初始化写入，负责人可随时要求暂停 |
| `DINGTALK_PROGRESS_PROFILE` | 固定个人账号 | Hub 使用 DWS 真实返回值 |
| `DINGTALK_PROGRESS_TARGET` | 固定项目群 | Hub 使用同账号查询并经确认的结果 |
| `DINGTALK_PROGRESS_PROJECT` | 项目名称 | Hub 使用已确认名称 |

配置不包含凭据，但仍是本机信息，本仓库已排除出 Git；Hub 在其他目标项目初始化时也应把 `.dingtalk/config.env` 加入该项目的 Git 忽略规则。不要把它或登录态复制给其他同事；各部署分别确认账号和群。登录由 DWS 自己管理，后续切换 DWS 默认账号不会改变本项目的发送身份。

## Windows 与 macOS/Linux

- Windows 使用 PowerShell 7.3+，优先运行 `./scripts/dingtalk-python.ps1 init ...`、`check ...`；事件用 `./scripts/dingtalk-progress.ps1 ...`，提醒用 `./scripts/dingtalk-message.ps1 ...`。
- PowerShell 共用启动器选择独立 Python，避免商店版 Python 无法读取终端的 DWS 登录。必要时用 `DINGTALK_PYTHON` 指定独立解释器路径；原生 `dws.exe` 须在当前进程 PATH 中。
- macOS/Linux 通常用 `python3 scripts/dingtalk_notify.py ...`；也可用 `sh scripts/dingtalk-progress ...`、`sh scripts/dingtalk-message ...`。初始化生成的配置在 POSIX 系统为仅当前用户读写；Windows 使用部署目录的访问权限。
- 将共用 Python 文件和所需平台入口放在目标 Hub 项目的 `scripts/` 中。安装职责 Skill 不会自动部署这些脚本。

DWS 安装与登录以 [官方项目](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli) 和当前命令帮助为准；不要为通知分发机器人应用密钥。

## 日常调用

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

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

**待办事项**

- 结项资料整理：由 Hub 整理四类结项工作稿。
- 资料补充：由产品 Agent、业务 Agent 补充现有线下成果及确认索引，不重做验收。
- 旧事项停止：由 Hub 停止此前的验收准备催办。
- 结项确认：四类成果具备后，由 Hub 请 @{示例负责人} 确认结项，确认后再锁定成果。
- 本轮工作范围：不新增应用修复、设备测试或发布验证。

**遗留**

- 原测试不通过的结果如实保留，不因进入结项阶段改为通过。
- 已接受延期的问题如实保留，后续沿用 Bug 系统中的记录和已有处理安排继续跟进。" --at "示例负责人"
python scripts/dingtalk_notify.py progress blocked --stage "阶段三：方案设计" "**待办事项**

- 方案设计：请 @{示例甲} 补充接口说明，并回自己的角色会话同步；接口说明缺失影响方案确认。" --at "示例甲"
python scripts/dingtalk_notify.py message --title "阶段三：方案设计｜资料补充提醒" --text "**待办事项**

- 方案设计：请 @{示例甲} 补齐已约定的接口资料，并回自己的角色会话确认。" --at "示例甲"
```

以上结项场景、事项和姓名仅作格式演示；验收结论、成果数量、延期安排和确认人不作为其他项目的默认事实或要求。真实发送须使用当前项目的有效记录和已绑定负责人姓名。

`progress` 现在必须传入 `--stage`，每次使用当前项目记录里的阶段编号和名称；未登记编号时仅写已知名称。标题显示“项目名称｜阶段编号：阶段名称”，不再显示固定的“阶段里程碑”。旧调用需补齐参数，并同步部署脚本和相关 Hub Skill／Hook；本地改动不等于在途项目已更新。

进度通知使用加粗标题和“已确认的进展”“待办事项”“遗留”三个栏目：待办按“事项名称：由谁做什么”逐条写清，当前阶段尚未解决的问题列入遗留。保留已定前提、停止事项和工作范围，阶段启动不写成项目关闭。确实没有待办或遗留时写“无”，未核实不能当作没有；沿用已定责任和期限，不能为了通知新增工作或重填清单。具体写法见[通知规则](../etunel-role-collaboration/references/dingtalk-progress-reporting.md#消息写法)。通知保留 AI 标识并标注自动汇报；摘要用简短中文 Markdown。在对应事项中写 `@{完整姓名}`，并通过 `--at` 传入相同姓名，脚本唯一匹配后原位生成原生 @；多人分别对应各自事项，同一接收人去重。仅传 `--at` 的旧写法仍在末尾追加提醒。离线预览只显示“@姓名”，不证明实际提醒成功。两个发送命令都支持 `--file` 正文和完全离线的 `--dry-run`。不支持临时换群、手填人员编号或退回机器人发送。

事件含义见 [通知规则](../etunel-role-collaboration/references/dingtalk-progress-reporting.md)，详细调用与结果见 [脚本用法](../etunel-role-collaboration/references/dingtalk-script-usage.md)。

## 检查与失败处理

- `python scripts/dingtalk_notify.py check --at "完整姓名"`：只检查固定账号登录和可选姓名，不发消息，不证明实际 @ 提醒成功。不是每条通知的必做步骤。
- `accepted` 加有效 `openTaskId`：个人发送请求已接受，不等于已投递或已读。必要时在同账号下用 `dws chat +messages-query-send-status --open-task-id "回执中的实际值" --profile "配置中的账号" --format json` 只读查询；不把任务回执当消息编号，不循环重发。
- 仅明确 DNS 解析失败最多尝试 3 次、间隔 10 秒；认证、权限或未知结果停止。登录失效请负责人恢复登录，不切账号、不退回机器人。通知失败不阻塞 Etunel 主任务。

维护时只做离线测试；真实发送必须另获明确授权：

```sh
python -X utf8 scripts/test_dingtalk_notify.py
bash -n scripts/dingtalk-progress
bash -n scripts/dingtalk-message
```