116 lines
10 KiB
Markdown
116 lines
10 KiB
Markdown
# 个人 DWS 项目通知
|
||
|
||
Hub 使用负责人确认的个人 DWS 账号发阶段汇报和 @ 提醒。只需要原生 DWS、Python 3.9+ 和一个项目配置文件；不使用机器人、应用密钥、Webhook 或 Stream 监听。
|
||
|
||
**旧版升级：** 用新的个人账号配置替换旧配置，旧机器人配置不会自动转成个人发送授权。摘要入口已改名为 `dingtalk-message`／`dingtalk-message.ps1`，删除目标部署中的旧 `dingtalk-bot-message` 入口及 Stream 实验脚本。更新脚本和 中心 Skill 及实际部署配置 不等于已经迁移在途项目；按实际部署安排确认。
|
||
|
||
## 首次由 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 协助整理工作稿。
|
||
- 资料补充：由产品负责人、业务负责人补充现有线下成果及确认记录，不重做验收。
|
||
- 旧事项停止：由 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 "示例甲"
|
||
```
|
||
|
||
以上结项场景、事项和姓名仅作格式演示；验收结论、成果数量、延期安排和确认人不作为其他项目的默认事实或要求。真实发送须使用当前项目的有效记录和已确认的真人负责人姓名。
|
||
|
||
`progress` 现在必须传入 `--stage`，每次使用当前项目记录里的阶段编号和名称；未登记编号时仅写已知名称。标题显示“项目名称｜阶段编号：阶段名称”，不再显示固定的“阶段里程碑”。旧调用需补齐参数，并同步部署脚本和相关 中心 Skill 及实际部署配置；本地改动不等于在途项目已更新。
|
||
|
||
进度通知使用加粗标题和“已确认的进展”“待办事项”“遗留”三个栏目：待办按“事项名称：由谁做什么”逐条写清，当前及此前阶段尚未解决的问题列入遗留，沿用原计划、当前计划、必须完成的阶段和影响范围。保留已定前提、停止事项和工作范围，阶段启动不写成项目关闭。确实没有待办或遗留时写“无”，未核实不能当作没有；沿用已定责任和期限，不能为了通知新增工作或重填清单。具体写法见[通知规则](../ep-hub/references/dingtalk-progress-reporting.md#消息写法)。通知保留 AI 标识并标注自动汇报；摘要用简短中文 Markdown。在对应事项中写 `@{完整姓名}`，并通过 `--at` 传入相同姓名，脚本唯一匹配后原位生成原生 @；多人分别对应各自事项，同一接收人去重。仅传 `--at` 的旧写法仍在末尾追加提醒。离线预览只显示“@姓名”，不证明实际提醒成功。两个发送命令都支持 `--file` 正文和完全离线的 `--dry-run`。不支持临时换群、手填人员编号或退回机器人发送。
|
||
|
||
事件含义见 [通知规则](../ep-hub/references/dingtalk-progress-reporting.md)，详细调用与结果见 [脚本用法](../ep-hub/references/dingtalk-script-usage.md)。
|
||
|
||
## 阶段交接和关闭通知
|
||
|
||
中心真人已批准推进或条件授权实际满足后，将上一阶段总结与下一阶段已确认安排合为一条 `milestone`。阶段内已授权的关键进展、阻塞、失败通知保留，同轮合并。等待决定时先在中心会话汇报，不宣称已进入下一阶段。
|
||
|
||
项目实际关闭后，用 `complete` 发送一次结项总结，保留未修复 Bug、失败测试和已确认承接；后续整理资料不重复发送。完整示例见 [通知规则](../ep-hub/references/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 "完整姓名"`：只检查固定账号登录和可选姓名，不发消息，不证明实际 @ 提醒成功。不是每条通知的必做步骤。
|
||
- `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
|
||
```
|