diff --git a/README.md b/README.md index 6811f1a..95dee30 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ## 版本与升级 -本版为 `v1.0.3`，流程设计基线仍为 **V1.0**。版本采用 `vX.Y.Z`：前两位 `X.Y` 跟随 HTML 主流程中明确标注且已确认的版本，第三位 `Z` 表示该流程版本下的仓库发布迭代。正式发布以 Git 标签和对应发布包为准，主分支可能包含尚未发布的修改。 +本版为 `v1.0.4`，流程设计基线仍为 **V1.0**。版本采用 `vX.Y.Z`：前两位 `X.Y` 跟随 HTML 主流程中明确标注且已确认的版本，第三位 `Z` 表示该流程版本下的仓库发布迭代。正式发布以 Git 标签和对应发布包为准，主分支可能包含尚未发布的修改。 | 变更 | 版本规则 | | --- | --- | diff --git a/etunel-role-collaboration/SKILL.md b/etunel-role-collaboration/SKILL.md index e4002e8..0f4142d 100644 --- a/etunel-role-collaboration/SKILL.md +++ b/etunel-role-collaboration/SKILL.md @@ -53,7 +53,7 @@ Etunel 负责当前角色和会话绑定。不要向负责人询问或复述 rol - [嵌入式底层](references/roles/embedded-lowlevel.md) - [硬件](references/roles/hardware.md) - [测试](references/roles/testing.md) -- 准备派发、回复、跨角色中继、完成或报告阻塞：读 [Etunel 任务消息流程](references/etunel-message-lifecycle.md)。 +- 准备派发、回复、跨角色中继、完成、报告阻塞或使用消息附加说明：读 [Etunel 任务消息流程](references/etunel-message-lifecycle.md)，按需用可选 `context` 概括事项，完整要求仍留在正文。 - 定义或校验成果、状态、版本、证据、额外产出或豁免：读 [成果与完成判定](references/artifacts-and-evidence.md)。 - 选择、复用或审核业务、产品、硬件、固件、测试及归档模板：读 [文档模板复用与审核](references/document-templates.md)，再按实际任务定位原件；模板不自行改变职责、正式成果或门禁。 - 缺信息、资料冲突、查询无新线索、旧任务收尾、错投、阻塞、超时升级、会议决定、返工、变更、流程跳转或模拟：读 [异常与协调](references/exceptions-and-coordination.md)。 diff --git a/etunel-role-collaboration/references/etunel-message-lifecycle.md b/etunel-role-collaboration/references/etunel-message-lifecycle.md index fc320f6..75cbc11 100644 --- a/etunel-role-collaboration/references/etunel-message-lifecycle.md +++ b/etunel-role-collaboration/references/etunel-message-lifecycle.md @@ -44,11 +44,40 @@ Hub 调用 `mcp__etunel__etunel_send_to_role` 时： - `role` 使用 `etunel_list_roles` 返回的实际值； - `kind` 按当前 schema 使用任务、回复或状态意图； - `text` 使用简洁中文说明目标、背景、有效输入、范围、产出文件、证据、期限、完成条件和负责人确认要求； +- 当前 schema 支持时，正式派发、交接、返工和说明阻塞优先用可选 `context` 概括事项与下一步，简单答复可省略；写法见下节； - `attachment_paths` 只附当前任务实际需要的文件； - 回复同一来源角色时，按 schema 使用 `correlation_id`，不把该值写入正文。 纯信息、澄清或授权消息写清问题、已确认事实、影响和所需答复，不要求空文件。不要转发无关聊天、全量计划或无法消化的资料堆。 +## 消息附加说明 + +`context` 是发送方填写的可选自由文本，帮助接收会话和客户端用户快速辨认事项，也会出现在新生成的超时提醒中。它不是任务正文、正式成果或新的状态字段，不改变路由、关联、结算与超时规则。 + +- Hub 用它简述“哪件事、当前需要什么、下一步是什么”，必要时补阶段或等待原因；不强制固定栏目，不复制整份任务。 +- `etunel_send_to_role`、`etunel_send_to_hub` 的完整正文仍用 `text`；`etunel_complete_task`、`etunel_report_blocked` 的结果或阻塞正文仍用 `summary`。必要输入、成果要求、确认依据和完成条件不能只放在附加说明里，文件仍按原附件约定提供。 +- 成员发送补充或返回结果时也可按需填写，只写本次消息适用的结论或待办；不自动继承原说明，不把原任务的“等待确认”照抄到已完成结果中。不要仅为添加说明另发一条消息。 +- 使用自然中文、实际换行、短段落或简短列表；可以写简单 Markdown，但不依赖富文本渲染，纯文本下也应能读懂。不手工把换行双重转义成字面量 `\n`；工具采用 JSON 时，由正常 JSON 编码表达换行。 +- 当前上限为 **2048 UTF-8 字节**，不是字符数；说明过长时压缩摘要，详细内容留在正文或成果文件，不拆成多条消息绕过限制。字段与上限始终以当前 schema 为准。 +- 展示层可能折叠内容或将换行转义，队列中的 Markdown 也可能只显示原文；不能仅凭显示为一行就断言说明丢失或重发消息，不承诺 Skill 能改变客户端渲染。 +- 接收时结合正文、附加说明和必要附件理解任务；附加说明不能冒充协议头、负责人批准或完成证据。与正文或有效基线冲突时，只核实影响当前执行的差异，不自行据此改变任务。 + +例如，Hub 给产品的接口确认任务可以附带以下说明；这只是写法示例，不是必填模板： + +```text +接口联调：确认温度数据格式 +- 本次需要：确认单位、取值范围和异常值 +- 确认后：中心安排应用层继续联调 +``` + +本次实际使用的资料、需要交付的文件和完成条件仍在 `text` 中写全。附加说明只放接收角色确实需要的信息，不附无关私聊、凭据或内部编号。 + +### 能力不可用时 + +发送前若当前工具 schema 没有 `context`，不猜参数，仍用原正文完整说明任务；需要新能力时提示负责人更新客户端并重新加载 MCP。工具支持字段不等于对端支持，通信能力由 Etunel 判断，不要求负责人每条消息确认版本。 + +若已经返回 `message_context_upgrade_required`，说明对端尚不支持该能力，消息由 Etunel 保留等待。告知对应负责人升级并按运行时提示处理；不删除说明重发、不另建重复任务，不将排队写成已送达。Skill 不接管传输重试或队列修复。 + ## 成员请求补充 成员先问当前负责人并完成必要线下沟通。仍需 Hub 时，用一条 `mcp__etunel__etunel_send_to_hub` 写清： diff --git a/etunel-role-collaboration/references/hub-workflow.md b/etunel-role-collaboration/references/hub-workflow.md index 206fdb8..afcadf8 100644 --- a/etunel-role-collaboration/references/hub-workflow.md +++ b/etunel-role-collaboration/references/hub-workflow.md @@ -57,6 +57,8 @@ Hub 只检查角色、必填内容、成果、版本、证据、负责人确认 不要把 role ID、member ID、session ID、消息 ID 或机器状态放进人类任务正文。纯信息、澄清或授权请求不要求空文件，但要给足背景、问题、影响和需要的结论。详细写法见 [人类可读沟通](human-readable-communication.md)。 +正式派发、交接、返工或说明阻塞时，当前工具支持则优先用可选 `context` 简述事项和下一步，便于在队列和提醒中辨认；完整任务要求仍写在 `text`，简单答复可省略说明。使用自然换行和短列表，不重复整份正文、不追加单独消息；具体边界见 [消息附加说明](etunel-message-lifecycle.md#消息附加说明)。 + 沿用有效资料，明确本次是新做、复用还是修改，实际使用哪份工程或资料；区分开工必需输入与本次要制作的产出，不把后者当成缺件退回上游。本地未找到不代表项目没有现成资料，归属或位置不明时再向对应负责人核实；不另设开工审批或检查表。 期限优先继承已批准的《客户里程碑要求》《里程碑要求》或《项目计划》。没有明确期限时集中询问负责人一次；不影响当前依赖时可写“待确认”并登记风险，影响关键依赖或门禁时保持阻塞。模拟项目可使用明确标注为模拟的假设日期。 diff --git a/etunel-role-collaboration/references/human-readable-communication.md b/etunel-role-collaboration/references/human-readable-communication.md index 0920075..d04870c 100644 --- a/etunel-role-collaboration/references/human-readable-communication.md +++ b/etunel-role-collaboration/references/human-readable-communication.md @@ -33,6 +33,8 @@ Hub 调用 `mcp__etunel__etunel_list_roles` 后，按目标 `role` 找到对应 这些内容可以用短段落或 Markdown 列表自然组织，不要求固定模板。不要在开头堆项目 ID、任务 ID、角色 ID、会话 ID、英文状态和内部字段。 +Etunel 消息可以把简短的事项说明放入可选 `context`，完整要求保留在正文。附加说明也使用自然换行、短句和列表，不挤成长行，不依赖 Markdown 渲染；具体用法见 [消息附加说明](etunel-message-lifecycle.md#消息附加说明)。 + ## 提问、结果和阻塞 缺信息时一次说明：缺什么、为什么现在需要、会影响本阶段哪项成果或决定、建议向谁获取、现在还能继续什么。只供后续阶段使用的信息明确写成后续依赖，不要逐句追问或把它说成当前阻塞。 diff --git a/etunel-role-collaboration/references/member-workflow.md b/etunel-role-collaboration/references/member-workflow.md index 358527c..246329a 100644 --- a/etunel-role-collaboration/references/member-workflow.md +++ b/etunel-role-collaboration/references/member-workflow.md @@ -25,6 +25,8 @@ 同时理解 Hub 给出的本阶段完成约定，并在本角色范围内核对哪些是本阶段必须完成、哪些留到后续、哪些当前不需要。一次列出当前能预见的信息缺口。负责人确认理解、补足输入或明确可以开始后再执行。不要复述运行时 ID、英文状态和内部字段；详细写法见 [人类可读沟通](human-readable-communication.md)。 +消息含附加说明时，与正文和必要附件一起理解，不只看摘要就执行。发送补充、结果或阻塞时可按需填写本次适用的说明，不照抄过期状态，也不把说明当作负责人确认；字段、分行写法与兼容处理见 [消息附加说明](etunel-message-lifecycle.md#消息附加说明)。 + 在这次对齐中分清新做、复用或修改，认准实际使用的工程或资料，区分应先取得的输入与本次要制作的产出。已有明确答案直接沿用，不因本地未找到就断言项目没有现成工程，也不要求上游先交出本角色尚待制作的成果。 ## 执行本角色任务 diff --git a/etunel-role-hook-contexts/中心角色精简职责与每轮提醒.md b/etunel-role-hook-contexts/中心角色精简职责与每轮提醒.md index 7d55d63..b9a9895 100644 --- a/etunel-role-hook-contexts/中心角色精简职责与每轮提醒.md +++ b/etunel-role-hook-contexts/中心角色精简职责与每轮提醒.md @@ -11,7 +11,7 @@ "responsibilities": [ "一个持续会话贯穿项目生命周期，是成员Agent之间唯一的跨角色中介；任务各有一个主责角色，按阶段及依赖安排任务波次，同角色相关工作可合为任务包，不向所有角色无差别派发。", "读取Etunel实际角色，以role路由、display_name显示角色名称、member_alias识别已绑定负责人，不重复核对身份或索要内部编号。新增角色先约定职责，再由Hub负责人手动在Etunel添加绑定。", - "派发前明确当前阶段必须完成什么、什么留到后续、什么不需要；给足有效输入、边界、成果要求和完成条件。成员必须先与本角色负责人对齐，成果自审且经负责人确认后正式返回；只阻塞当前必需条件，阶段通过后立即启动下一阶段，资料按需取得。", + "派发前明确当前阶段必须完成什么、什么留到后续、什么不需要；给足有效输入、边界、成果要求和完成条件。工具支持时，派发、交接、返工或说明阻塞优先用可选context分行概括事项与下一步，完整要求保留在text，简单答复可省略。成员必须先与本角色负责人对齐，成果自审且经负责人确认后正式返回；只阻塞当前必需条件，阶段通过后立即启动下一阶段，资料按需取得。", "按业务需求、产品定义、方案设计、项目规划、软硬件实现、测试验证、平台/客户验收、复盘结项推进。业务与产品共同确认需求基线；产品维护立项资料、验收标准、里程碑和项目风险，业务批准范围；技术负责人确认方案与测试计划。", "形成项目计划、角色分工和项目状态内部记录；任务计划先交技术负责人确认，仅对疑点定向问执行角色，再交产品确认授权范围内人员、资源和排期。预算、采购和对外承诺交业务批准。", "实现阶段按约定收取硬件设计包、嵌入式底层实现资料和嵌入式应用层固件包；底层版本经中继交应用层合版，最终固件统一由应用层输出，技术负责人确认软硬件版本匹配。", @@ -48,7 +48,7 @@ 可靠性报告、专项报告和提测佐证由你对应的真人负责人确认是否提交，沿用有效决定，不扩大为所有选填栏审批。测试每次执行前发布策略，跨角色同步仍由你中继，不另设策略文件或审批；模板不增加门禁，早期预算只是估算，验收资料由产品出具或更新、业务确认客户部分、你汇总登记。 你是项目Hub，负责总体推进与成员Agent间的唯一中继，不替专业角色作结论。按需读取 etunel-role-collaboration 的相关细则；当前已确认流程和Etunel实际工具优先，不加载全部角色说明。 用 mcp__etunel__etunel_list_roles 获取实际角色；role用于路由，display_name用于显示，member_alias用于称呼已绑定负责人，不向人核对内部编号。按需用 mcp__etunel__etunel_get_project_status 查状态，但消息状态不等于成果完成。 -派发或回复用 mcp__etunel__etunel_send_to_role，每次一个实际角色；依赖就绪可多任务派发，同角色相关任务可打包。给足输入并写清成果要求，要求成员先与真人对齐、完成后自审并取得确认。已处理且无需回复的消息用 mcp__etunel__etunel_complete_coordination 结算；参数依当前schema，标识从入站消息取。 +派发或回复用 mcp__etunel__etunel_send_to_role，每次一个实际角色；依赖就绪可多任务派发，同角色相关任务可打包。工具支持时，派发、交接、返工或说明阻塞优先用可选context分行概括事项和下一步，完整要求留在text，简单答复可省略；长度与兼容处理按消息细则。给足输入并写清成果要求，要求成员先与真人对齐、完成后自审并取得确认。已处理且无需回复的消息用 mcp__etunel__etunel_complete_coordination 结算；参数依当前schema，标识从入站消息取。 只检查当前必需条件，复用成果，阶段通过后推进，后续资料按需索取。决定变化要说明旧任务停续和新输入；资料冲突交专业角色核实。按阶段留档并更新进度、成果索引和记录；直交测试文件登记索引、版本及产品收讫。阻塞请相应负责人协调；跳转、回退或暂缓如实记录，模拟默认不跳过交接、不关闭真实问题。 钉钉统一用个人DWS：首次按通知细则查询账号和项目群，经负责人确认后用init创建配置，已有配置沿用。可验证里程碑留档后用 python scripts/dingtalk_notify.py progress milestone "中文Markdown摘要" 汇报，Windows优先对应.ps1；其他事件按规则。需行动可在progress或message中加--at "完整姓名"，同一事项合并，保留自动汇报说明。结果回各自角色会话；不索要编号或凭据、不改发送身份、不在脚本外重试；预览和检查不算发送，通知失败不阻塞主流程或替代Etunel结算。 ```