EP-Hub-Skill/etunel-role-collaboration/references/project-files-and-progress.md

项目文件与进度留档

Hub 创建项目资料目录、保存角色文件、维护成员清单、更新进度、完成阶段交接、跳转、回退或结项时读取。Etunel 负责附件传输，本文件只约束收到文件后的项目内整理和可追踪性。

责任边界

• 各角色负责形成、检查并提交自己的专业成果文件。
• Hub 负责接收后校验、按阶段归档、维护成果索引和项目进度，不改写角色专业内容。
• 必要成果文件未保存、不可访问或无法确认版本时，不宣布正式阶段交接完成。
• 目录整理不是新的专业评审。模拟、受控跳转、回退或暂缓可以继续，但必须先记录缺失项、原因、风险和恢复条件。
• 不强制项目使用 Git。项目已有 Git 时可正常提交，但 Git 提交不是阶段门禁。

固定目录

Hub 在项目开始时建立：

项目资料/
├── 00-项目管理/
│   ├── 项目概览.md
│   ├── 项目进度.md
│   ├── 成果索引.md
│   └── 项目成员清单/
├── 01-业务需求/
├── 02-产品定义/
├── 03-方案设计/
├── 04-项目规划/
├── 05-软硬件实现/
├── 06-测试验证/
├── 07-业务验收/
└── 08-发布结项/

每个实际发生工作的阶段按需建立：

阶段记录.md
正式成果/<角色名>/
过程记录/

默认角色目录使用稳定的中文角色名。自定义角色使用 etunel_list_roles 返回的 display_name，去除目标文件系统不允许的字符；没有参与的角色不创建空目录。不得把文件散放到 项目资料/ 根目录。

项目概览与已确认规则

00-项目管理/项目概览.md 保存项目名称、模式、流程基线、目标和当前项目已经确认的特殊规则。每条特殊规则写清内容、适用范围、决定权角色或负责人、确认依据和生效时间；Hub 只能登记有权负责人明确确认的内容，不能把自己的推断写成规则。

项目规则持续有效，直到同一决定权人明确修改或取消。各角色只确认自己决定权内的规则：产品确认产品行为和验收边界，业务确认业务范围、客户联络和正式承诺，Hub 负责人确认其权限内的流程处理，专业角色确认本领域限制；改变既有正式基线时仍按《变更申请》处理。

项目成员清单

项目创建完成、首个正式任务派发前，Hub 调用 mcp__etunel__etunel_list_roles。角色增加、替换或关系变化后重新查询。每次把同一份返回快照保存为：

• JSON 事实版：保留工具实际返回的 role、display_name、relationship；
• HTML 中文阅读版：用中文表头展示相同事实；
• 可额外记录项目名称、清单版本和导出时间。

文件放入 00-项目管理/项目成员清单/ 并版本化，不覆盖历史版本。工具未返回的 member ID、session ID、人员姓名或负责人 ID 不得补造；凭据不得进入清单。成员清单是项目过程记录，不替代阶段 4 的《角色分工》。

文件归档与版本

• Hub 校验并接受的文件放入当前阶段的 正式成果/<角色名>/。
• 有复盘价值的草案、退回材料、问题说明、会议决定、变更、豁免和阻塞资料放入 过程记录/。
• 普通问答、空确认、重复副本和没有改变行动的临时文件不留档。
• 已接受版本不得覆盖。新版本保留旧版，并在 成果索引.md 写明当前有效版本、旧版及替代关系。
• 文档类正式成果只有在范围、行为、验收、接口、专业决定或下游行动发生实质变化时才创建新版本。状态、转交、排版、相同副本和不改变结论的过程说明不升正式版本；有复盘价值时写入阶段记录。代码、固件、硬件、配置和构建物仍按本领域规则区分实际版本。
• 固件、源码包、设计源文件等有既定文件名的技术成果保留原文件名，通过版本目录或成果索引区分版本。
• 成果索引.md 至少写明中文成果名、阶段、主责角色、文件位置、版本、确认状态、当前适用性和被替代关系。
• 每项成果只标记一个当前有效版本。下游默认只接收该版本；旧版和过程材料继续留存，但不参与当前完成判断，除非被明确恢复为有效版本。

项目进度与阶段记录

00-项目管理/项目进度.md 是当前状态快照，使用简洁中文说明：当前阶段、已完成事项、正在进行事项、实际阻塞、下一步、责任角色和更新时间。

每个阶段开始时，在 阶段记录.md 写下简短的“本阶段完成约定”，分为本阶段必须完成、后续阶段处理和当前不需要；它不是新的正式成果。此后按时间追加有复盘价值的事件：任务波次开始、成果接收、影响进度的退回、阻塞与解除、重要决定、变更、门禁和阶段交接。每条记录写清发生了什么、相关文件、影响和下一步，不转存完整聊天或大段日志。

在以下事件后更新：

• 项目创建；
• 正式任务或任务波次开始；
• 角色成果被接受，或退回会改变进度；
• 阻塞发生或解除；
• 重要决定、变更或成果豁免生效；
• 阶段交接、受控跳转、回退、暂缓或结项。

Etunel 的排队、送达、普通回复和空确认本身不触发留档。

阶段交接、跳转与回退

正式阶段交接前，Hub 确认本阶段必须完成的适用成果已保存、版本可识别、负责人确认已记录、成果索引已更新，并在来源阶段写入阶段小结。小结说明完成内容、有效文件、未决项、后续依赖、风险、门禁结论和下一阶段。

本阶段门禁通过并完成上述留档后，Hub 及时结束本阶段并启动下一阶段，不等待未来阶段的全部资料提前齐备。下一阶段根据实际任务按需索取自己的输入；可选完善和后续依赖不能继续占用已经完成的阶段。

跳转、回退、暂缓或返工时：

1. 不删除、不移动、不覆盖原阶段记录和旧成果；
2. 在来源阶段记录离开原因，在目标阶段记录进入原因；
3. 更新 项目进度.md 指向当前实际阶段；
4. 新成果使用新版本，旧版本在成果索引中保留并标明是否失效或被替代；
5. 暂缓写明恢复条件和下一责任角色；
6. 模拟跳转明确标注“流程模拟”，不得混入正式成果。

与钉钉的顺序

Hub 先完成成果校验、文件归档、成果索引和项目进度更新，再根据已留档事实发送钉钉进度。钉钉发送失败不回滚留档，也不阻塞 Etunel 主流程。