Refine project role collaboration guidance

etunel-role-collaboration/references/etunel-message-lifecycle.md

@@ -2,98 +2,87 @@
 
 准备派发、补充、跨角色中继、返回、完成、阻塞或结算 Hub 入站消息时读取。当前 Hook 和 MCP schema 是工具名、参数与授权的最终依据；本文只约束职责和消息意图。
 
-## 标识与身份
+## 真实工具边界
 
-| 标识 | 含义 |
-|---|---|
-| WORK_ID | 贯穿项目生命周期的工作容器 |
-| 流程基线／阶段 | 当前 WORK_ID 已登记的流程版本与位置 |
-| 任务波次 | 同一有效基线下依赖已满足、可连续派发的一组任务 |
-| SUBTASK_ID | 一个主责角色和主责成员可独立判定的一项任务 |
-| role/member/session | 语义角色、实际角色实例、主责成员和绑定会话 |
-| message_id | 一条 Etunel 消息的单跳关联或结算标识 |
+Etunel 是严格的 Hub 星型拓扑：成员只能向 Hub 发送，只有 Hub 可以向角色发送。
 
-正文已有有效标识时复用。已终态 SUBTASK_ID 不重新作为活动任务；运行时字段命名不同则按实际 schema 映射。
-
-## 工具职责
-
-| 意图 | 调用者 | Etunel 工具 |
+| 意图 | 调用者 | 工具 |
 |---|---|---|
-| 向一个角色派发一条任务消息 | Hub | etunel_send_to_role，kind=task |
-| 向同一来源角色返回信息或终态状态 | Hub | etunel_send_to_role，kind=reply 或 kind=status，并按 schema 关联来源 message_id |
-| Hub 已处理入站且无需回复 | Hub | etunel_complete_coordination |
-| 成员向 Hub 补充、聚合询问或报告非终态状态 | 成员 | etunel_send_to_hub |
-| 成员成功结束自己的任务 | 主责成员 | etunel_complete_task |
-| 成员以具体阻塞结束自己的任务 | 主责成员 | etunel_report_blocked |
-| 读取当前消息列出的必要附件 | 当前绑定会话 | etunel_receive_message |
+| 读取实际角色 | Hub | `mcp__etunel__etunel_list_roles` |
+| 向一个角色发送任务、回复或状态 | Hub | `mcp__etunel__etunel_send_to_role` |
+| 结算无需回复的成员协调消息 | Hub | `mcp__etunel__etunel_complete_coordination` |
+| 成员向 Hub 补充或提问 | 成员 | `mcp__etunel__etunel_send_to_hub` |
+| 成员完成任务并交付成果 | 成员 | `mcp__etunel__etunel_complete_task` |
+| 成员以具体阻塞结束任务 | 成员 | `mcp__etunel__etunel_report_blocked` |
+| 读取必要附件或旧式消息 | 当前绑定会话 | `mcp__etunel__etunel_receive_message` |
 
-工具未暴露、名称或参数不同，以当前 Hook 和 schema 为准并报告能力缺口；不得猜参数或请求内部授权字段。
+工具未暴露、名称或参数改变时，以当前 schema 为准并报告能力缺口；不得猜参数或请求内部认证字段。
+
+## 机器字段不进入人类正文
+
+- Hub 用 `role` 路由，面向人使用 `display_name`。
+- `message_id` 是 Etunel 消息标识；需要完成、阻塞或结算时从入站消息取值。
+- `correlation_id` 只用于把回复或状态关联到来源消息。
+- 这些字段只进入工具参数。任务正文、负责人对话、成果标题和钉钉消息不要求抄写或确认。
+- Etunel schema 没有 member ID；Skill 不得创造 member、session 或任务 ID 字段。
 
 ## 任务波次如何发送
 
-etunel_send_to_role 一次调用只发送一个接收角色和一条消息：
+`mcp__etunel__etunel_send_to_role` 一次调用只发送一个接收角色和一条消息：
 
-- 同一角色多个独立 SUBTASK_ID 可连续发送，由 Etunel 队列处理；
-- 同一角色紧密相关且共同交付的内容可合并为内聚任务包；
+- 同一角色的多个独立任务可以连续发送，由 Etunel 队列处理；
+- 同一角色紧密相关且共同交付的内容可以合并为任务包；
 - 不同角色的依赖就绪任务分别发送、独立返回；
-- 排队不代表角色业务并行完成，也不代表下游依赖已经满足。
+- 排队不代表业务并行完成，也不代表下游依赖已经满足。
 
-Hub 不实现队列、ACK、锁、重试、去重或文件传输；这些由 Etunel 软件承担。
+Hub 不实现队列、确认包、锁、重试、去重或文件传输；这些由 Etunel 软件承担。
 
 ## Hub 发送任务
 
-每条正式任务消息应包含：
+Hub 调用 `mcp__etunel__etunel_send_to_role` 时：
 
-- WORK_ID、SUBTASK_ID、模式、流程基线、阶段和波次；
-- semantic role、实际 role ID、主责成员、session、human owner 和协作角色；
-- 目标、背景、上游成果、输入版本和成果引用；
-- IN_SCOPE、OUT_OF_SCOPE、依赖、接口、限制和风险；
-- 指定成果及最低内容、证据、版本、下游用途；
-- 要求完成时间、完成条件和职责内结论；
-- 专业自审和 human owner 确认要求；
-- 信息不足、额外产出和阻塞的处理边界。
+- `role` 使用 `etunel_list_roles` 返回的实际值；
+- `kind` 按当前 schema 使用任务、回复或状态意图；
+- `text` 使用简洁中文说明目标、背景、有效输入、范围、产出文件、证据、期限、完成条件和负责人确认要求；
+- `attachment_paths` 只附当前任务实际需要的文件；
+- 回复同一来源角色时，按 schema 使用 `correlation_id`，不把该值写入正文。
 
-纯信息、澄清或授权消息写清问题、已确认事实、影响、选项和所需答复，不要求空文件。不要转发无关聊天、全量计划或无法消化的资料堆。
+纯信息、澄清或授权消息写清问题、已确认事实、影响和所需答复，不要求空文件。不要转发无关聊天、全量计划或无法消化的资料堆。
 
 ## 成员请求补充
 
-成员先询问自己的负责人并完成必要线下沟通。仍需 Hub 时，用一条 etunel_send_to_hub 写清：
+成员先问当前负责人并完成必要线下沟通。仍需 Hub 时，用一条 `mcp__etunel__etunel_send_to_hub` 写清：
 
-- SUBTASK_ID、已完成工作和现有成果；
-- 聚合后的缺失信息／决定及用途；
-- 已向负责人询问和线下协调的结果；
-- 对结论、范围、期限、风险和下游的影响；
-- 建议的信息所有者角色；
-- 当前仍可继续的范围与希望 Hub 返回的具体内容。
+- 已经完成什么、现有成果在哪里；
+- 还缺什么信息或决定，为什么需要；
+- 已经询问和协调的结果；
+- 缺失对范围、期限、风险和下游的影响；
+- 建议向哪个角色获取；
+- 当前还能继续什么，希望 Hub 返回什么。
 
-Hub 已有登记答案时一次补足；没有时才产生必要的跨角色查询或任务。
+Hub 已有登记答案时一次补足；没有时才创建必要的跨角色查询或任务。
 
 ## 经 Hub 的跨角色中继
 
-当前 Etunel 没有成员间直连工具。跨角色交流必须是：来源成员 → Hub → 目标成员 → Hub → 来源成员。
+跨角色交流必须是：来源成员 → Hub → 目标成员 → Hub → 来源成员。
 
 - Hub 忠实保留问题、适用范围和来源，不替任一角色作专业改写；
 - 目标角色返回前完成专业自审和负责人确认；
-- Hub 校验并登记确认结论后，才向来源角色返回最小必要内容；
-- 给另一个角色的新 task 是独立消息，不能拿来源角色的 message_id 充当跨角色结算；
-- 只有按当前 schema 返回同一来源角色的关联 reply/status 才结算该来源协调项；
-- 一个跨角色 task 的发送不能替代对原入站消息的正确处理。
+- Hub 校验并登记确认结论后，才向来源角色返回最少必要内容；
+- 给另一个角色的新任务是独立消息，不能拿来源消息标识充当跨角色结算；
+- 对同一来源角色的回复或状态按当前 schema 关联，其他情况由 Hub 明确结算来源协调项。
 
-默认一次聚合请求和一次答复；复杂异常使用 Meeting Decision Record，不把多轮聊天当成项目事实。
-
-## Project Status Snapshot
-
-状态快照只由 Hub 向受影响角色发送，是裁剪后的状态同步，不是新专业任务、成果或门禁。写明变化、有效版本、对接收方影响、下一步、责任方和期限；同一处理轮聚合一次。若需要角色执行动作，应另有明确 task 或按当前 schema 明确消息意图。
+普通问题默认一次聚合请求和一次答复；复杂异常使用《会议决定记录》，不把多轮聊天当成项目事实。
 
 ## 成员完成或阻塞
 
-调用 etunel_complete_task 前，确认指定成果、证据、版本、期限状态、专业自审、负责人确认和明确结论均已包含。
+调用 `mcp__etunel__etunel_complete_task` 前，成员确认指定成果、证据、版本、期限状态、专业自审、负责人确认和明确结论都已包含，并通过 `attachment_paths` 发送实际文件。
 
-调用 etunel_report_blocked 时至少说明：
+调用 `mcp__etunel__etunel_report_blocked` 时，用简明中文说明：
 
-- 阻塞条件；
-- 已完成成果和已尝试排查／负责人／线下协调；
-- 缺失输入或决定及建议责任人；
+- 当前阻塞；
+- 已完成成果和已尝试的排查、负责人沟通及线下协调；
+- 缺失输入或决定及建议责任角色；
 - 对本任务和下游的影响；
 - 恢复条件和建议下一步。
 
@@ -103,13 +92,13 @@ Hub 已有登记答案时一次补足；没有时才产生必要的跨角色查
 
 Hub 对每条入站消息选择：
 
-- 需要向同一来源角色回复：按 schema 发送关联 reply/status；
-- 无需回复且已处理：调用 etunel_complete_coordination；
-- 需要其他角色：正确处理来源协调项，并按依赖创建一个或多个必要任务；
-- 同一轮到达多个相关结果：先更新成果、状态和依赖，再统一选择下一波次。
+- 需要回复同一来源角色：发送关联回复或状态；
+- 无需回复且已经处理：调用 `mcp__etunel__etunel_complete_coordination`；
+- 需要其他角色：先正确处理来源协调项，再按依赖创建必要任务；
+- 同一轮到达多个相关结果：先更新成果、留档、状态和依赖，再选择下一波次。
 
-消息结算、排队和送达不代表 SUBTASK_ID、成果、阶段或 WORK_ID 完成。
+消息结算、排队和送达不代表任务、成果、阶段或项目完成。
 
 ## 附件
 
-直接使用当前消息正文和内嵌内容。仅当消息明确列出附件且为当前任务必要输入时，调用 etunel_receive_message 获取所需附件。不要为探测队列或重复确认而读取。
+直接使用当前消息正文和内嵌内容。仅当消息明确列出附件且为当前任务必要输入时，调用 `mcp__etunel__etunel_receive_message` 获取所需附件。Hub 收到成果文件后按 [项目文件与进度留档](project-files-and-progress.md) 归档；不要为探测队列或重复确认而读取。