Etunel 多角色项目协作约束

本仓库为 Etunel 多 Agent 项目提供一套中文版、渐进式披露的角色职责与协作流程：项目Hub负责跨角色中继和全局推进，七个成员角色在各自真人负责人参与下完成专业任务，并以可追踪成果交回 Hub。

钉钉定位说明： 仓库中的 .agents/skills/dingtalk-*、.dingtalk/ 和 scripts/dingtalk-progress 只作为参考与演示，用来告诉 Hub 如何调用钉钉发送项目进度或异常通知。钉钉不是 Etunel 的角色通信链路、任务队列、审批、门禁或项目事实源，也不会改变任何角色边界。

先了解这三件事

1. 主 Skill 是角色 AI 的统一入口，只保留共享硬约束和条件路由；详细职责按当前任务逐层读取。
2. Hook 上下文 是给 Etunel 单独配置的精简提醒，不属于 Skill 的渐进式发现树，也不应替代完整职责文件。
3. doc/20260902/ 中 V0.14 总流程图是当前设计基线；V0.13 Hub 系统提示词只作补充和历史追溯。Skill 已把适用规则整理成稳定约束，运行时不依赖这些版本文件存在。

仓库没有应用安装、编译或发布流程。主要工作是维护角色约束、流程文档、Hook 上下文以及 Hub 通知参考集成。

协作模型

一个项目使用一个持续的 Hub 会话贯穿整个生命周期。成员之间现阶段不能直接通信，所有跨角色问题、补充信息、成果和返工都由 Hub 定向中继。

flowchart LR
    subgraph project["一个项目 / 一个持续的 Hub 会话"]
        hub["项目 Hub<br/>Hub AI + Hub 负责人"]
        business["业务<br/>角色 AI + 负责人"]
        product["产品<br/>角色 AI + 负责人"]
        tech["技术负责人<br/>角色 AI + 负责人"]
        app["嵌入式应用层<br/>角色 AI + 负责人"]
        low["嵌入式底层<br/>角色 AI + 负责人"]
        hardware["硬件<br/>角色 AI + 负责人"]
        testing["测试<br/>角色 AI + 负责人"]

        business <--> hub
        product <--> hub
        tech <--> hub
        app <--> hub
        low <--> hub
        hardware <--> hub
        testing <--> hub
    end

    hub -. "公开进度与异常摘要" .-> ding["钉钉群<br/>辅助通知"]

图中的成员节点均表示“角色 AI 与对应真人负责人”。箭头只连接 Hub：成员不能绕过 Hub 相互发消息。钉钉只有 Hub 发出的单向虚线，不参与任务交付或状态判定。

默认角色共八个：

角色	主要定位
项目Hub	建立项目、维护状态、规划任务波次、校验交付结构、协调阻塞并完成跨角色中继
业务	形成商业需求、客户与授权信息、业务验收及发布结项输入
产品	把业务需求转化为产品定义、范围、交互和验收标准
技术负责人	负责总体技术方案、接口与跨技术域设计协调
嵌入式应用层	负责应用层软件设计、实现、联调和对应成果
嵌入式底层	负责驱动、BSP、底层接口与对应实现成果
硬件	负责硬件方案、设计交付、样机与测试配合
测试	独立制定测试策略、执行验证、管理缺陷并给出质量结论

自定义角色不是自动生效的。它必须先形成职责契约，再由 Hub 真人负责人在 Etunel 中手动添加。Hub 从 Etunel 实际角色清单读取 role、display_name 和 relationship，不让负责人手工确认不存在的成员或会话编号。

正常生命周期为：业务需求 → 产品定义 → 方案设计 → 项目规划 → 软硬件实现 → 测试验证 → 业务验收 → 发布结项。项目可以按已确认基线进行受控跳转、回退或暂缓；模拟项目应显式记录模拟状态，不能冒充真实交付。

仓库结构

EP-Hub-Skill/
├── AGENTS.md                         # 后续 Agent 和协作者的仓库级工作规则
├── README.md                         # 项目入口与结构说明
├── etunel-role-collaboration/        # 核心渐进式披露 Skill
│   ├── SKILL.md                      # 共享硬约束和条件路由
│   ├── agents/openai.yaml            # Skill 展示信息与默认提示词
│   └── references/
│       ├── hub-workflow.md           # Hub 工作流
│       ├── member-workflow.md        # 成员通用工作流
│       ├── project-lifecycle.md      # 八阶段、成果和门禁
│       ├── project-status-and-membership.md
│       ├── etunel-message-lifecycle.md
│       ├── artifacts-and-evidence.md
│       ├── exceptions-and-coordination.md
│       ├── human-readable-communication.md
│       ├── project-files-and-progress.md
│       ├── dingtalk-progress-reporting.md
│       ├── roles/                    # 七个成员角色职责
│       └── testing/                  # 测试任务按需读取的二级细则
├── etunel-role-hook-contexts/        # 八角色独立 Hook 源文件
├── doc/                              # 当前设计基线和历史流程资料
├── .agents/skills/dingtalk-*/        # 钉钉官方能力参考副本，不是核心 Skill
├── .dingtalk/                        # 通知接入说明与无秘密示例配置
└── scripts/dingtalk-progress         # Hub 钉钉通知的当前演示封装

Skill 被用于实际项目时，Hub 在目标项目中维护统一的 项目资料/，而不是把项目成果写回本约束仓库：

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

每个实际使用的阶段按需建立 阶段记录.md、正式成果/<角色名>/ 和 过程记录/。Hub 不覆盖正式历史，也不把完整聊天记录当作项目档案。

如何使用职责 Skill

Etunel 为角色会话配置本 Skill 后，角色 AI 应按以下顺序工作：

1. 从当前 Hook、Etunel 角色契约和入站任务确认自己的职责。Hub 通过 mcp__etunel__etunel_list_roles 读取实际角色；成员不向负责人追问成员、会话或任务编号。
2. 读取 SKILL.md 的共享约束。
3. 只打开本次任务所需的引用：
   • Hub 先读 Hub 工作流；
   • 成员先读 成员通用工作流，再读自己的一个角色职责文件；
   • 涉及派发、中继或返回时读 Etunel 任务消息流程；
   • 涉及成果、证据、状态或豁免时读 成果与完成判定；
   • 涉及对负责人发消息时读 人类可读沟通；
   • 涉及阶段成果、进度或复盘资料时读 项目文件与进度留档；
   • 涉及缺信息、阻塞、返工、变更或流程跳转时读 异常与协调。
4. 成员先和自己的真人负责人对齐任务与输入，形成明确成果、自审并取得负责人确认后，再交给 Hub。
5. Hub 校验任务结果，按阶段整理实际文件并更新项目进度和成果索引，只把下游需要的信息定向交给下一角色，不广播无关计划或私有对话。

不要为了“全面了解”一次加载全部引用。测试专项文件也只有在任务类型匹配时才继续深入读取。

Hook 上下文

etunel-role-hook-contexts/ 为八个默认角色各提供一份“精简职责与每轮提醒”。它们适合由 Etunel Hook 在每轮会话中注入，用来持续提醒身份、边界、负责人参与和工具使用。

Hook 文件需保持短小，并与完整 Skill 职责一致。它们由 Etunel 独立配置，因此不需要从 SKILL.md 中发现；修改角色边界时，应同时检查对应角色 reference 与 Hook，避免两套规则漂移。

钉钉通知参考

钉钉集成是 Hub 的辅助通知参考，不是 Etunel 协作系统的一部分。仓库保留它，是为了让 Hub 在满足事件条件时有一个清晰、安全、可替换的调用方法。

只有 Hub／主 Agent 可以使用下面的封装入口：

./scripts/dingtalk-progress <start|milestone|blocked|complete|failed> "<简短中文 Markdown 摘要>"

五类事件分别表示项目正式开始、可验证里程碑、真实阻塞、整体完成和最终失败。可验证里程碑由 Hub 先完成成果和进度留档，再发送钉钉消息。成员角色不得发送钉钉消息，只把结果交给 Hub。通知正文可使用多行 Markdown，只写可公开的已验证结论、下一步或阻塞原因，不发送密钥、个人数据、大段日志和未经证实的推断。

更详细的 Hub 事件语义、有限重试和结果判定见 钉钉项目进度汇报；当前演示接入与本地配置见 .dingtalk/README.md。.agents/skills/dingtalk-* 是钉钉官方多 Skill 的项目内参考副本，不应被当作 Etunel 核心 Skill，也不应被成员用来绕过 Hub。

本地 .dingtalk/config.env 已被 Git 忽略。不要读取、输出或提交其中的配置；不要在文档、Skill、Hook 或脚本中硬编码 Client Secret、Client ID、robotCode、openConversationId、App Token 或群名。仓库维护时也不要用真实发送作为普通测试。

修改项目的推荐流程

1. 阅读 AGENTS.md 和本次变更涉及的最小文件集合。
2. 若变更来自流程设计，先核对当前 V0.14 总流程图。V0.13 Hub 系统提示词 只作补充和历史追溯；V0.13、V0.4 总流程图只用于版本比较。
3. 把共享规则放在公共 reference，把角色专属规则放在对应角色文件，把低频测试细节放在测试二级 reference。
4. 只有必须让所有角色立即知道的规则才进入根 SKILL.md；同时保持条件路由可发现。
5. 同步检查受影响的 Hook 文件，并验证链接、结构和 Shell 语法。

验证

本仓库没有构建步骤。提交前至少运行：

git diff --check
git status --short

修改核心 Skill 后，使用已安装的 Skill Creator 对 etunel-role-collaboration/ 运行 scripts/quick_validate.py。Skill Creator 的位置取决于协作者的 Codex 安装，不要为此把验证器复制进仓库。

修改钉钉演示脚本后再运行：

bash -n scripts/dingtalk-progress

还应人工确认：

• 新增 reference 能从根 Skill 或已路由文件按条件发现；
• Markdown 相对链接实际存在；
• 根 Skill、角色 reference 与 Hook 没有职责漂移；
• 没有占位符、秘密配置、真实凭据或不存在的工具与文件；
• 钉钉仍只是 Hub 辅助通知参考，没有进入任务通信或门禁主链路。

设计资料

• 当前多角色推进总流程图 V0.14
• 补充与历史追溯：项目Hub系统提示词 V0.13
• 历史总流程图 V0.13
• 历史总流程图 V0.4
• 核心 Skill
• Hub 工作流
• 项目生命周期