215 lines
15 KiB
Markdown
215 lines
15 KiB
Markdown
# Etunel 多角色项目协作约束
|
||
|
||
本仓库为 Etunel 多 Agent 项目提供一套中文版、渐进式披露的角色职责与协作流程：项目Hub负责跨角色中继和全局推进，七个成员角色在各自真人负责人参与下完成专业任务，并以可追踪成果交回 Hub。
|
||
|
||
> **钉钉定位说明：** 仓库中的 `.agents/skills/dingtalk-*`、`.dingtalk/` 和 `scripts/dingtalk-progress` 只作为参考与演示，用来告诉 Hub 如何调用钉钉发送项目进度或异常通知。钉钉不是 Etunel 的角色通信链路、任务队列、审批、门禁或项目事实源，也不会改变任何角色边界。
|
||
|
||
## 先了解这三件事
|
||
|
||
1. [主 Skill](etunel-role-collaboration/SKILL.md) 是角色 AI 的统一入口，只保留共享硬约束和条件路由；详细职责按当前任务逐层读取。
|
||
2. [Hook 上下文](etunel-role-hook-contexts/) 是给 Etunel 单独配置的精简提醒，不属于 Skill 的渐进式发现树，也不应替代完整职责文件。
|
||
3. 当前设计基线为 [V1.0 总流程图](doc/Codex多角色项目推进总流程图.html)（文档生效日期 2026-09-08）。流程文档只维护一份，后续直接更新同一文件，旧版通过 Git 历史追溯，不再按日期或版本另存。仓库更新不代表部署 Skill／Hook 或自动迁移在途项目；运行时规则已整理进稳定 reference，不要求目标项目持有流程 HTML。
|
||
|
||
仓库没有应用安装或编译步骤；发布对象是职责 Skill、Hook 上下文及配套文档，不是设备固件或运行中的 Etunel 服务。
|
||
|
||
## 版本与升级
|
||
|
||
本版为 `v1.0.1`，流程设计基线仍为 **V1.0**。发布版本表示一套可领取的仓库文件，流程基线表示其依据的已确认流程，两者不必同步递增。正式发布以 Git 标签和对应发布包为准，主分支可能包含尚未发布的修改。
|
||
|
||
| 变更 | 版本规则 |
|
||
| --- | --- |
|
||
| 不改变既定角色边界、必需成果或阶段条件的纠错、澄清与执行优化 | 升修订号，例如 `1.0.0 → 1.0.1` |
|
||
| 增加可选能力或场景，原有项目仍能按原约定执行 | 升次版本号，例如 `1.0.1 → 1.1.0` |
|
||
| 改变既有职责、成果或阶段门禁，旧项目需重新确认执行方式 | 升主版本号，例如 `1.x.x → 2.0.0` |
|
||
|
||
全仓库只维护这一套发布序列，不给 Skill、Hook 分别编号。流程设计变更先确认，再同步受影响文件；只修正 Skill 执行说明时，不必改流程图版本。日常修改正常提交，需要交给团队使用时才统一校验、确定版本、创建 Git 标签及发布说明；已发布标签和内容不覆盖，修正发新版本。
|
||
|
||
发布说明应写清：流程基线、改了什么、使用者需要更新哪些文件、在途项目是否需要重新确认。不要把“仓库已发布”写成“角色已更新”。更新插件缓存、Etunel 中独立配置的 Hook 或迁移在途项目，都需另外明确确认；已运行项目继续使用其登记基线。
|
||
|
||
### v1.0.1 更新范围
|
||
|
||
- 根据一轮项目复盘，补清旧任务收尾、开工输入与本次产出的区分、资料异常交专业角色核实、查询无新线索时转交负责人决定，以及模拟不默认跳过交接。
|
||
- 更新核心 Skill；Hook 仅调整中心与产品两份，保持完整职责 JSON 和每轮提醒分开配置。产品 Hook 修改的是完整职责区块，中心两个区块均有调整。
|
||
- 八角色、八阶段、正式成果、原有审批与测试验收条件不变；不自动迁移在途项目、不关闭真实遗留问题。本版不涉及钉钉脚本更新。
|
||
|
||
## 协作模型
|
||
|
||
一个项目使用一个持续的 Hub 会话贯穿整个生命周期。成员之间现阶段不能直接通信，所有跨角色问题、补充信息、成果和返工都由 Hub 定向中继。
|
||
|
||
```mermaid
|
||
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`，不让负责人手工确认不存在的成员或会话编号。
|
||
|
||
正常生命周期为：业务需求 → 产品定义 → 方案设计 → 项目规划 → 软硬件实现 → 测试验证 → 平台/客户验收 → 复盘结项。项目可以按已确认基线进行受控跳转、回退或暂缓；模拟项目应显式记录模拟状态，不能冒充真实交付。
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
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
|
||
│ ├── document-templates.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/ # 当前设计基线与模板参考，历史由 Git 保存
|
||
│ ├── Codex多角色项目推进总流程图.html # 当前 V1.0，后续原位更新
|
||
│ └── 文档模板参考/ # 按任务读取的参考笔记与来源清单
|
||
├── .agents/skills/dingtalk-*/ # 钉钉官方能力参考副本，不是核心 Skill
|
||
├── .dingtalk/ # 通知接入说明与无秘密示例配置
|
||
└── scripts/dingtalk-progress # Hub 钉钉通知的当前演示封装
|
||
```
|
||
|
||
Skill 被用于实际项目时，Hub 在目标项目中维护统一的 `项目资料/`，而不是把项目成果写回本约束仓库：
|
||
|
||
```text
|
||
项目资料/
|
||
├── 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](etunel-role-collaboration/SKILL.md) 的共享约束。
|
||
3. 只打开本次任务所需的引用：
|
||
- Hub 先读 [Hub 工作流](etunel-role-collaboration/references/hub-workflow.md)；
|
||
- 成员先读 [成员通用工作流](etunel-role-collaboration/references/member-workflow.md)，再读自己的一个[角色职责文件](etunel-role-collaboration/references/roles/)；
|
||
- 涉及派发、中继或返回时读 [Etunel 任务消息流程](etunel-role-collaboration/references/etunel-message-lifecycle.md)；
|
||
- 涉及成果、证据、状态或豁免时读 [成果与完成判定](etunel-role-collaboration/references/artifacts-and-evidence.md)；
|
||
- 涉及对负责人发消息时读 [人类可读沟通](etunel-role-collaboration/references/human-readable-communication.md)；
|
||
- 涉及阶段成果、进度或复盘资料时读 [项目文件与进度留档](etunel-role-collaboration/references/project-files-and-progress.md)；
|
||
- 涉及缺信息、阻塞、返工、变更或流程跳转时读 [异常与协调](etunel-role-collaboration/references/exceptions-and-coordination.md)。
|
||
4. 成员先和自己的真人负责人对齐任务与输入，形成明确成果、自审并取得负责人确认后，再交给 Hub。
|
||
5. Hub 校验任务结果，按阶段整理实际文件并更新项目进度和成果索引，只把下游需要的信息定向交给下一角色，不广播无关计划或私有对话。
|
||
|
||
不要为了“全面了解”一次加载全部引用。测试专项文件也只有在任务类型匹配时才继续深入读取。
|
||
|
||
## Hook 上下文
|
||
|
||
[etunel-role-hook-contexts/](etunel-role-hook-contexts/) 为八个默认角色各提供一份“精简职责与每轮提醒”。它们适合由 Etunel Hook 在每轮会话中注入，用来持续提醒身份、边界、负责人参与和工具使用。
|
||
|
||
每份 Hook 文档分为“完整职责 JSON”和“每轮精简提醒”两个独立配置区块，分别复制到 Etunel 对应字段。职责 JSON 不是接口请求，实际绑定与工具参数仍以 Etunel 为准。仓库源文件修改不会自动写入已安装插件或 Etunel 配置。
|
||
|
||
Hook 文件需保持短小，并与完整 Skill 职责一致。它们由 Etunel 独立配置，因此不需要从 `SKILL.md` 中发现；修改角色边界时，应同时检查对应角色 reference 与 Hook，避免两套规则漂移。
|
||
|
||
## 钉钉通知参考
|
||
|
||
钉钉集成是 Hub 的辅助通知参考，不是 Etunel 协作系统的一部分。仓库保留它，是为了让 Hub 在满足事件条件时有一个清晰、安全、可替换的调用方法。
|
||
|
||
只有 Hub／主 Agent 可以使用下面的封装入口：
|
||
|
||
```sh
|
||
./scripts/dingtalk-progress <start|milestone|blocked|complete|failed> "<简短中文 Markdown 摘要>"
|
||
```
|
||
|
||
五类事件分别表示项目正式开始、可验证里程碑、真实阻塞、整体完成和最终失败。可验证里程碑由 Hub 先完成成果和进度留档，再发送钉钉消息。成员角色不得发送钉钉消息，只把结果交给 Hub。通知正文可使用多行 Markdown，只写可公开的已验证结论、下一步或阻塞原因，不发送密钥、个人数据、大段日志和未经证实的推断。
|
||
|
||
更详细的 Hub 事件语义、有限重试和结果判定见 [钉钉项目进度汇报](etunel-role-collaboration/references/dingtalk-progress-reporting.md)；当前演示接入与本地配置见 [.dingtalk/README.md](.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](AGENTS.md) 和本次变更涉及的最小文件集合。
|
||
2. 若变更来自流程设计，核对 [当前 V1.0 总流程图](doc/Codex多角色项目推进总流程图.html)，在固定文件上修改并通过 Git 提交记录变更；不要新增日期目录或旧版副本。部署及在途项目迁移另行确认。
|
||
3. 把共享规则放在公共 reference，把角色专属规则放在对应角色文件，把低频测试细节放在测试二级 reference。
|
||
4. 只有必须让所有角色立即知道的规则才进入根 `SKILL.md`；同时保持条件路由可发现。
|
||
5. 同步检查受影响的 Hook 文件，并验证链接、结构和 Shell 语法。
|
||
|
||
## 验证
|
||
|
||
本仓库没有构建步骤。提交前至少运行：
|
||
|
||
```sh
|
||
git diff --check
|
||
git status --short
|
||
```
|
||
|
||
修改核心 Skill 后，使用已安装的 Skill Creator 对 `etunel-role-collaboration/` 运行 `scripts/quick_validate.py`。Skill Creator 的位置取决于协作者的 Codex 安装，不要为此把验证器复制进仓库。
|
||
|
||
修改钉钉演示脚本后再运行：
|
||
|
||
```sh
|
||
bash -n scripts/dingtalk-progress
|
||
```
|
||
|
||
还应人工确认：
|
||
|
||
- 新增 reference 能从根 Skill 或已路由文件按条件发现；
|
||
- Markdown 相对链接实际存在；
|
||
- 根 Skill、角色 reference 与 Hook 没有职责漂移；
|
||
- 没有占位符、秘密配置、真实凭据或不存在的工具与文件；
|
||
- 钉钉仍只是 Hub 辅助通知参考，没有进入任务通信或门禁主链路。
|
||
|
||
## 设计资料
|
||
|
||
- [当前总流程图 V1.0](doc/Codex多角色项目推进总流程图.html)
|
||
- [文档模板参考](doc/文档模板参考/README.md)
|
||
- 历史流程与变更说明通过 `git log --all -- doc/` 查询，不在工作目录保留旧版副本。
|
||
- [核心 Skill](etunel-role-collaboration/SKILL.md)
|
||
- [Hub 工作流](etunel-role-collaboration/references/hub-workflow.md)
|
||
- [项目生命周期](etunel-role-collaboration/references/project-lifecycle.md)
|