EP-Hub-Skill/ep-hub/references/dingtalk-progress-reporting.md

Hub 钉钉项目进度汇报

仅当当前会话是 Hub 且发生汇报事件或需提醒负责人处理具体问题时读取。钉钉是面向项目群组的单向辅助可见性与异常提醒，不是任务派发、跨角色沟通、审批、门禁、人类确认或项目记录的事实源。

权限与封装入口

• 只有 Hub／主 Agent 可以发送；成员 Agent 只把成果、状态或阻塞交给 Hub。

• 项目首次初始化时，由 Hub 查询可用个人 DWS 账号和群，以姓名、组织和群名向负责人确认自动通知范围，再调用 init 创建配置；不让人填写编号或密钥。确认并启用后，范围内通知不需每条再次询问，变更账号或群须重新确认。

• 只用项目封装：dingtalk-progress 处理五类项目事件，dingtalk-message 处理自定义中文摘要或负责人提醒；二者共用 scripts/dingtalk_notify.py，统一使用确认的个人 DWS 账号。初始化、跨平台入口及 @ 用法见 通知脚本用法。

• Agent 不得直接调用底层 OpenAPI、dws api 或其他消息入口绕过封装脚本。

• 配置只保存开关、固定账号、项目群和项目名称；Hub 可在已确认范围内创建或更新，登录凭据由 DWS 管理，不索取、读取或输出 Token、密码与应用密钥。旧机器人配置须重新初始化，不静默切换发送身份。

• 不在 Skill 或群消息里硬编码账号、群或人员标识；标识从同一账号的真实工具结果取得，仅用于本地配置和工具参数。不因默认账号切换而更换发送人，不退回机器人或 Webhook。

汇报单位与顺序

汇报以整个项目生命周期为单位。Hub 合并同一阶段或任务波次的相关结果，不为每条队列消息、普通回复、单个小步骤或短小只读问答发送通知。

Hub 必须先核对真实事实，更新对应任务、阶段和项目进度记录；涉及正式成果变化时再更新成果与索引，然后发送钉钉消息。不为一次通知新增成果文件。钉钉发送失败不回滚留档，也不阻塞项目主任务。

阶段交接与结项总结

• 每次中心真人批准推进，或已有条件授权实际满足并已执行交接后，在已启用且获授权的通知范围内，将上一阶段总结与下一阶段安排合为一条 milestone。标题使用实际当前阶段。
• 等待推进决定时，先在中心会话按 阶段汇报规则 说明成果、未完成项及待决定事项，不发宣称已进入下一阶段的总结；已授权的实质进展或阻塞通知仍可按实际事件发送。
• 正文仍用“已确认的进展／待办事项／遗留”：进展写上一阶段成果和真实推进决定；待办写下一阶段全部已确认任务、主责和期限，未知字段如实说明；遗留写未完成及待确认、影响和承接。完整成果汇报放中心会话，群里可引用适合接收者访问的有效记录入口，不能为缩短篇幅遗漏待办或停止事项。
• 第八阶段取得明确关闭决定后发送一次 complete 结项总结，列有效成果、关闭决定及承接事项的主责和计划。后续资料整理、补地址不重复发关闭通知。
• 将总结正文、对应决定和实际发送结果记入阶段过程记录；生成前核对是否已通知同一次交接或关闭。复用原记录，不增加通知队列或脚本外重试。API 接受、投递和已读分别记录，未知结果不盲目重发。

事件判定

start

每个项目最多一次。在第一个真实可执行任务或任务波次已经交给主责真人且已有实际接收依据后（可以通过 Etunel 或其他已授权渠道）发送。仅建立计划、等待输入或讨论想法时不发送。

milestone

在可验证、会改变下一步的实质进展完成并已留档时发送，例如：

• 关键成果或版本成为当前有效版本；
• 一个有意义的任务波次完成并触发角色或阶段交接；
• 门禁、受控跳转、回退或豁免完成真实记录和必要确认；
• 正式阻塞解除，项目恢复到明确下一动作；
• 统一固件、版本矩阵、测试结论、验收或发布组合形成。

保留已授权范围内的阶段关键进展通知；同一处理轮或同一波次合并成一条，不逐个小任务刷屏。同轮发生阶段交接时合入交接总结，核对阶段过程记录避免重复。没有固定时间间隔。

blocked

出现下列实际阻塞时立即发送：

• 已有影响交付的实际阻塞，需要中心协调、有权真人决定或外部条件才能继续；
• 关键路径等待有权决定；
• 当前使用的交接渠道实际中断，且没有可用的已授权替代渠道完成必要交接；不把 Etunel 异常自动等同于整个项目阻塞。

普通排队、正常等待、角色仍可自行推进或尚未完成产出不算阻塞。阻塞解除后用 milestone 汇报恢复，不修改历史消息。

complete

项目生命周期中，阶段八满足必要条件、业务已确认结项且中心真人明确关闭后发送一次。开始结项整理不使用 complete。用户明确指定的独立整体目标最终完成时，限定在该目标范围表述，不能冒充项目关闭。模拟项目必须明确写“模拟完成”，不得表达真实发布、客户验收或生产就绪。

failed

整个项目或整体目标已经最终终止、无法恢复或明确失败时发送。可返工的测试失败、单个任务失败或临时脚本异常不使用 failed。

消息写法

标题使用“项目名称｜阶段编号：阶段名称”，例如“示例项目｜阶段六：测试验证”。Hub 每次从有效项目记录取得当前阶段编号和名称，通过 progress --stage 整体传入；编号未登记时只写已知阶段名称，不自行编号或因通知示例改变阶段顺序。阶段变化后使用新名称，不把“阶段里程碑”等事件标签当成阶段，也不根据正文猜测阶段。提醒入口的自定义标题同样先写当前阶段，再写提醒事项。跨阶段事项在对应条目中注明所属阶段，通知标题仍写项目当前阶段。

进度通知采用已确认的格式：加粗项目与阶段标题、自动汇报时间、“已确认的进展”“待办事项”“遗留”三个加粗栏目，栏目间留空行。每件事单独一条，用日常说法写清谁做什么。确实没有待办或遗留时写“无”；资料不足时说明尚未核实，不把未知写成没有。本轮没有新增已确认进展时如实说明。

• 已确认的进展：写清完成了什么、谁已作出什么决定以及适用范围。区分“已进入阶段／开始整理”和“已完成／已关闭”；已通知交接不等于对方已经完成交接。已决定的事项直接说明结果，不再请人重复批准。
• 待办事项：合并列出本轮需要决定、确认或处理的全部事项，用“事项名称：由谁做什么”逐条表述，例如资料整理、资料补充、旧事项停止、结果确认和本轮工作范围；按实际情况命名，不要求凑齐示例条目。标题已说明当前阶段，不必每条重复阶段名，涉及其他阶段时注明。需人工决定时写“条件具备后，由 Hub 请某负责人确认具体事项，确认后再执行后续动作”，条件只取已有约定；有可选方案时简短列明。需执行时写清已明确的处理人和动作，有已约定期限时沿用，必要时说明结果通过哪个已约定渠道返回。已明确停止的催办、需要复用的成果和不新增的工作须保留，不改写成新任务。
• 遗留：逐条列出当前阶段及此前阶段尚未解决、需要继续跟进的事项，说明现状、已确认的后续安排及对应处理人；沿用原计划时间、当前计划时间、必须完成的阶段和影响范围，按本轮需要说明变更；跨阶段事项注明原所属阶段。列为遗留不等于获准延期、豁免、关闭问题或通过阶段；同一问题在待办里写本轮动作，在遗留里交代未解决状态，避免重复整段内容。
• 待办和需跟进的遗留，在已明确真人处理人或决策人时，于对应条目中 @ 该人；Hub 代为请求确认时 @ 被请求确认的真人负责人，不把“Hub”或角色名称当成可查询姓名。纯 Agent 工作可直接写 Hub 或实际角色 Agent；真人姓名缺失时沿用已知角色，不猜测或编造 @ 对象，确需提醒再按项目分工与脚本用法取得已确认姓名。多人分工写清各自动作，同一人可在对应条目中重复出现，发送接收人去重。已完成且无需行动的进展不额外 @ 人。未确定的责任、期限或事实不编造，也不为填写通知重新要求分配或填表。
• 用具体动作替代“收口”“闭环”“拉齐”等笼统表述。例如“处理方式已收口”可写成“负责人已确定处理方式”，但不得把处理方式确定写成问题已解决。原决定中的“暂不修复”“无需新增清单”等范围和限制必须保留。
• 资料未说明交接或执行情况时，只写需要核实的事实及已有安排，不直接要求重新交付或执行；通用阶段职责不能直接变成本轮已派发的待办。补充事实不要求重做已经完成的工作。

以下用结项整理场景演示已确认的通知格式，项目名与人员称呼均已泛化。示例中的验收结论、成果数量、确认人及延期安排只属于该场景，不成为其他项目的默认事实、职责或放行条件；各项目仍依据自己的有效记录和流程基线生成内容。

**示例项目｜阶段八：复盘结项**

项目进度自动汇报 · 发送时自动生成带时区的时间

**已确认的进展**

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

**待办事项**

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

**遗留**

- 原测试不通过的结果如实保留，不因进入结项阶段改为通过。
- 已接受延期的问题如实保留，后续沿用 Bug 系统中的记录和已有处理安排继续跟进。

示例标题、时间和栏目只说明最终呈现方式；调用时正文文件仅含正文，项目名、阶段标题与时间由脚本生成，不重复粘贴整条通知。

已关闭项目的结项总结示例

以下仅说明格式。事实、决定人、日期、有效成果入口、后续主责和期限都须替换为项目真实记录，不把此例当成关闭依据。

**示例项目｜阶段八：复盘结项**

项目进度自动汇报 · 发送时自动生成带时区的时间

**已确认的进展**

- 四类结项成果已取得必要确认，有效文件和入口已登记在项目成果索引。
- 全部 Bug 的处理或承接已由中心先确认、产品再次确认，双方无异议。
- 业务已确认结项，中心真人已明确关闭项目；决定的日期、范围和条件已记录。
- 已同步相关记录、锁定有效成果，停止已结束阶段的重复催办。

**待办事项**

- 遗留跟进：请 @示例处理人 按原问题记录中的当前计划继续处理已承接事项，原计划和变更历史保留。

**遗留**

- 已接受延期的 Bug 尚未修复，责任、原计划、当前计划和影响沿用原记录；项目关闭不代表问题已修复。
- 原测试不通过结论保留，版本放行、验收和关闭决定分别记录。

保留个人消息的 AI 标识和自动汇报说明，让群成员知道这是 Hub 自动通知，不是负责人本人新增批准、验收或承诺。

根据事件选择必要内容：已验证进展、关键成果、下一步和责任角色；阻塞时再说明问题、影响以及需要谁采取什么动作。尽量简短，但不能为了控制篇幅省掉本轮需要决定或处理的事项。专业细节留在成果或问题系统中，通知不新建另一份问题台账。

不在正文中写运行时 ID、英文成果名、机器状态码或内部字段。只写已验证结论，不得包含密钥、Token、个人数据、客户敏感信息、大段日志、完整内部对话或未经验证的根因推断。

负责人提醒只使用项目协作必需的已确认姓名。Hub 在原始正文中用 @{完整姓名} 指定条目内的位置，并用 --at 列出相同姓名；脚本查询唯一匹配后原位转换为钉钉原生 @。纯文字“@姓名”只用于人读预览，不能代替实际提及参数。脚本自动生成的人员标记是技术参数，不是要求 Hub 把人员编号写进摘要。需要负责人行动时，说明缺什么、影响什么、请谁做什么，以及通过哪个已约定渠道补充结果。不要在群里建立另一套任务或审批流程。

调用与结果

1. Hub 判断事件、取得当前阶段名称，按上面的栏目形成逐条中文摘要。用户要求先看内容时，先展示完整通知预览，得到本次发送确认后再调用真实发送；离线预览不代表已发送。
2. 调用封装脚本一次；脚本自行处理配置检查、发送和有限重试。
3. 只有真实个人发送响应成功且含非空 openTaskId，才表示请求已经接受；不证明已投递、已读或接收端 @ 提醒成功。必要时按脚本用法查询投递状态，不把任务回执当消息编号。
4. 缺少或未启用配置时不真实发送；显式 --dry-run 仅在本地生成正文，不查通讯录、不联网，也不证明目标配置和 @ 有效。配置仍为旧格式时停止并请求重新初始化。
5. 只有明确的域名解析失败才自动重试，总计最多 3 次，间隔 10 秒；首次收到有效回执立即停止。认证、权限或未知错误不自动重试；超时、连接中断或缺少回执可能已发出，不盲目重发。每次 DWS 子调用超时为 60 秒。
6. 有效回执优先于命令退出码，不因退出异常重复发送。发送停止或结果未知时，Etunel 主任务继续；Hub 在本地结果中向负责人说明一次，不递归发送新的阻塞或失败通知，不自动补发历史事件。

脚本输出和退出码只用于判断通知调用，不得把钉钉结果升级成项目门禁。Agent 不在脚本外追加重试循环。