release: v1.0.4 支持消息附加说明与分行表达

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 标签和对应发布包为准，主分支可能包含尚未发布的修改。
 
 | 变更 | 版本规则 |
 | --- | --- |
@@ -26,30 +26,7 @@
 
 发布说明应写清：流程基线、改了什么、使用者需要更新哪些文件、在途项目是否需要重新确认。不要把“仓库已发布”写成“角色已更新”。更新插件缓存、Etunel 中独立配置的 Hook 或迁移在途项目，都需另外明确确认；已运行项目继续使用其登记基线。
 
-### v1.0.3 更新范围
+各版本的变更、验证结果和升级注意事项统一查看[发布说明](https://git.playones.com/chenmingxuan/EP-Hub-Skill/releases)。README 只维护当前项目介绍和使用入口，不累积逐版更新记录。
-
-阶段汇报和负责人 @ 提醒统一改为个人 DWS。Hub 首次查询账号和群，经负责人确认后用 `init` 自动创建四项无密钥配置；旧机器人配置不能直接沿用。摘要入口改名为 `dingtalk-message`／`dingtalk-message.ps1`，不再部署机器人或 Stream 实验。更新时同步脚本、通知 reference 和中心 Hook；其他角色边界及 V1.0 主流程不变。详见 [部署与迁移](.dingtalk/README.md)。
-
-- `progress` 与 `message` 都支持按姓名 @，查询和发送固定同一账号；保留 AI 标识和中文自动汇报说明，不自动更换身份或通知群。
-- Windows 共用启动器使用独立 Python，修复商店版 Python 子进程无法识别终端 DWS 登录的部署问题。
-- 27 项离线回归通过，覆盖配置初始化、旧配置替换、个人发送回执、@ 参数、有限重试和 Windows 实际传参。
-- Windows 个人账号里程碑消息已通过新封装实测，投递状态为 `SUCCESS`；个人 @ 请求此前已成功提交，接收端提醒效果仍待本人确认。原生 macOS/Linux 运行尚未实测，Shell 语法已检查。
-- 配置迁移、目标项目脚本部署、Etunel 中心 Hook 和插件缓存更新须按部署安排确认，不自动迁移其他项目。通知仍不是任务通道、审批、门禁或事实源。
-
-### v1.0.2 更新范围（历史，不是当前部署说明）
-
-- 明确前两位跟随 HTML 流程、其余发布迭代只升第三位的版本约定；主流程仍为 V1.0，八角色及阶段门禁不变。
-- 钉钉通知改为共用 Python 实现，保留 macOS/Linux 入口，新增 Windows PowerShell 入口；支持项目事件、自定义中文 Markdown、文件正文和按姓名提醒负责人。
-- Windows、macOS、Linux 统一从本地 `config.env` 的 `DINGTALK_PROGRESS_CLIENT_SECRET` 取机器人密钥，不再读取环境变量或钥匙串。**升级时须由部署负责人补填本地密钥字段，并删除旧 `DINGTALK_PROGRESS_KEYCHAIN_SERVICE` 字段**；不提交真实配置。
-- 两个入口统一遵守离线预览；仅明确 DNS 失败每隔 10 秒重试、总计最多 3 次，结果未知不盲目重发。补充 27 项离线测试与部署说明。
-- 更新核心 Skill 的通知路由与细则，以及中心 Hook 的完整职责和每轮提醒；其他角色 Hook 无需因本次通知更新而替换。目标项目需同步共用 Python 文件及所需平台入口，安装 Python 3.9+ 与原生 DWS；PowerShell 入口需 7.3+。
-- Windows 普通群通知已获服务端回执并经负责人确认显示成功；按姓名 @ 和原生 macOS 发送仍未实测。通知升级不自动迁移在途项目或更新 Etunel Hook／插件缓存，需按部署安排明确执行。
-
-### v1.0.1 更新范围
-
-- 根据一轮项目复盘，补清旧任务收尾、开工输入与本次产出的区分、资料异常交专业角色核实、查询无新线索时转交负责人决定，以及模拟不默认跳过交接。
-- 更新核心 Skill；Hook 仅调整中心与产品两份，保持完整职责 JSON 和每轮提醒分开配置。产品 Hook 修改的是完整职责区块，中心两个区块均有调整。
-- 八角色、八阶段、正式成果、原有审批与测试验收条件不变；不自动迁移在途项目、不关闭真实遗留问题。本版不涉及钉钉脚本更新。
 
 ## 协作模型
 
@@ -194,7 +171,7 @@ python scripts/dingtalk_notify.py progress <start|milestone|blocked|complete|fai
 
 五类事件分别表示项目正式开始、可验证里程碑、真实阻塞、整体完成和最终失败。可验证里程碑由 Hub 先完成成果和进度留档，再发送钉钉消息。成员角色不得发送钉钉消息，只把结果交给 Hub。通知正文可使用多行 Markdown，只写可公开的已验证结论、下一步或阻塞原因，不发送密钥、个人数据、大段日志和未经证实的推断。
 
-新增 `message --title "中文标题" --text "问题和下一步"` 用于辅助摘要与负责人提醒，可按需用 `--at`；提醒结果回各自角色会话，不在群里另派任务或批准。两个入口均支持文件正文与离线 `--dry-run`，Windows 可用 `.ps1`，macOS/Linux 保留原 Shell 入口。它们是同一封装，不要重复调用。
+`message --title "中文标题" --text "问题和下一步"` 用于辅助摘要与负责人提醒，可按需用 `--at`；提醒结果回各自角色会话，不在群里另派任务或批准。两个入口均支持文件正文与离线 `--dry-run`，Windows 可用 `.ps1`，macOS/Linux 可用 Shell 入口。它们是同一封装，不要重复调用。
 
 所有通知统一使用负责人确认的个人 DWS 登录，不再使用机器人。Hub 在首次初始化时查询账号和项目群，用姓名、组织和群名取得确认后，调用 `init` 自动生成配置；人不用找编号或填密钥。配置只保留通知开关、固定账号、固定群和项目名，个人登录凭据由 DWS 管理。`progress` 也支持 `--at`，事件汇报和行动提醒可合成一条；保留 AI 标识和自动汇报说明，不冒充本人批准。
 

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)。

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` 写清：

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#消息附加说明)。
+
 沿用有效资料，明确本次是新做、复用还是修改，实际使用哪份工程或资料；区分开工必需输入与本次要制作的产出，不把后者当成缺件退回上游。本地未找到不代表项目没有现成资料，归属或位置不明时再向对应负责人核实；不另设开工审批或检查表。
 
 期限优先继承已批准的《客户里程碑要求》《里程碑要求》或《项目计划》。没有明确期限时集中询问负责人一次；不影响当前依赖时可写“待确认”并登记风险，影响关键依赖或门禁时保持阻塞。模拟项目可使用明确标注为模拟的假设日期。

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#消息附加说明)。
+
 ## 提问、结果和阻塞
 
 缺信息时一次说明：缺什么、为什么现在需要、会影响本阶段哪项成果或决定、建议向谁获取、现在还能继续什么。只供后续阶段使用的信息明确写成后续依赖，不要逐句追问或把它说成当前阻塞。

etunel-role-collaboration/references/member-workflow.md

@@ -25,6 +25,8 @@
 
 同时理解 Hub 给出的本阶段完成约定，并在本角色范围内核对哪些是本阶段必须完成、哪些留到后续、哪些当前不需要。一次列出当前能预见的信息缺口。负责人确认理解、补足输入或明确可以开始后再执行。不要复述运行时 ID、英文状态和内部字段；详细写法见 [人类可读沟通](human-readable-communication.md)。
 
+消息含附加说明时，与正文和必要附件一起理解，不只看摘要就执行。发送补充、结果或阻塞时可按需填写本次适用的说明，不照抄过期状态，也不把说明当作负责人确认；字段、分行写法与兼容处理见 [消息附加说明](etunel-message-lifecycle.md#消息附加说明)。
+
 在这次对齐中分清新做、复用或修改，认准实际使用的工程或资料，区分应先取得的输入与本次要制作的产出。已有明确答案直接沿用，不因本地未找到就断言项目没有现成工程，也不要求上游先交出本角色尚待制作的成果。
 
 ## 执行本角色任务

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结算。
 ```