67 lines
5.7 KiB
Markdown
67 lines
5.7 KiB
Markdown
# 个人 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 "**已完成**：阶段成果已归档。下一步安排联调。"
|
||
python scripts/dingtalk_notify.py progress blocked "缺少接口说明，请补充后回自己的角色会话同步。" --at "完整姓名"
|
||
python scripts/dingtalk_notify.py message --title "资料补充提醒" --text "请补齐已约定资料，并回自己的角色会话确认。" --at "完整姓名"
|
||
```
|
||
|
||
通知保留 AI 标识并标注自动汇报；摘要用简短中文 Markdown。`--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
|
||
```
|