chenmingxuan/EP-Hub-Skill
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
v1.0.3
EP-Hub-Skill/README.md
T

19 KiB
Raw Permalink Blame History

Etunel 多角色项目协作约束

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

钉钉定位说明： 仓库中的 .agents/skills/dingtalk-*、.dingtalk/ 和 scripts/ 下的钉钉封装只作为接入参考，用来告诉 Hub 如何发送项目进度、异常摘要或负责人提醒。钉钉不是 Etunel 的角色通信链路、任务队列、审批、门禁或项目事实源，也不会改变任何角色边界。

先了解这三件事

  1. 主 Skill 是角色 AI 的统一入口，只保留共享硬约束和条件路由；详细职责按当前任务逐层读取。
  2. Hook 上下文 是给 Etunel 单独配置的精简提醒，不属于 Skill 的渐进式发现树，也不应替代完整职责文件。
  3. 当前设计基线为 V1.0 总流程图（文档生效日期 2026-09-08）。流程文档只维护一份，后续直接更新同一文件，旧版通过 Git 历史追溯，不再按日期或版本另存。仓库更新不代表部署 Skill／Hook 或自动迁移在途项目；运行时规则已整理进稳定 reference，不要求目标项目持有流程 HTML。

仓库没有应用安装或编译步骤；发布对象是职责 Skill、Hook 上下文及配套文档，不是设备固件或运行中的 Etunel 服务。

版本与升级

本版为 v1.0.3，流程设计基线仍为 V1.0。版本采用 vX.Y.Z：前两位 X.Y 跟随 HTML 主流程中明确标注且已确认的版本，第三位 Z 表示该流程版本下的仓库发布迭代。正式发布以 Git 标签和对应发布包为准，主分支可能包含尚未发布的修改。

变更 版本规则
HTML 流程版本不变，更新 Skill、Hook、脚本、配置或说明等任意内容 只递增第三位，例如流程保持 V1.0，v1.0.1 → v1.0.2
HTML 流程正式更新到新的 X.Y 前两位同步，第三位从 0 开始，例如流程 V1.1 对应 v1.1.0
日常提交，尚未安排发布 不必为每次提交创建标签；下一次正式发版按上述规则编号

全仓库只维护这一套发布序列，不给 Skill、Hook 或脚本分别编号。前两位不按功能规模、变更文件数或兼容性自行调整，也不为新增脚本等非流程更新修改 HTML 版本。这不是按变更性质升主／次版本的语义化版本规则，第三位更新也可能需要配置迁移；职责或门禁变更仍须先确认流程。日常修改正常提交，需要交给团队使用时才统一校验、确定版本、创建 Git 标签及发布说明；已发布标签和内容不覆盖，修正发新版本。

发布说明应写清：流程基线、改了什么、使用者需要更新哪些文件、在途项目是否需要重新确认。不要把“仓库已发布”写成“角色已更新”。更新插件缓存、Etunel 中独立配置的 Hook 或迁移在途项目，都需另外明确确认；已运行项目继续使用其登记基线。

v1.0.3 更新范围

阶段汇报和负责人 @ 提醒统一改为个人 DWS。Hub 首次查询账号和群，经负责人确认后用 init 自动创建四项无密钥配置；旧机器人配置不能直接沿用。摘要入口改名为 dingtalk-message／dingtalk-message.ps1，不再部署机器人或 Stream 实验。更新时同步脚本、通知 reference 和中心 Hook；其他角色边界及 V1.0 主流程不变。详见 部署与迁移。

  • 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 修改的是完整职责区块，中心两个区块均有调整。
  • 八角色、八阶段、正式成果、原有审批与测试验收条件不变；不自动迁移在途项目、不关闭真实遗留问题。本版不涉及钉钉脚本更新。

协作模型

一个项目使用一个持续的 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
│       ├── document-templates.md      # 模板复用与审核边界
│       ├── artifacts-and-evidence.md
│       ├── exceptions-and-coordination.md
│       ├── human-readable-communication.md
│       ├── project-files-and-progress.md
│       ├── dingtalk-progress-reporting.md
│       ├── dingtalk-script-usage.md    # 通知的跨平台调用与负责人提醒
│       ├── roles/                    # 七个成员角色职责
│       └── testing/                  # 测试任务按需读取的二级细则
├── etunel-role-hook-contexts/        # 八角色独立 Hook 源文件
├── doc/                              # 当前设计基线与模板参考，历史由 Git 保存
│   ├── Codex多角色项目推进总流程图.html # 当前 V1.0，后续原位更新
│   └── 文档模板参考/                  # 按任务读取的参考笔记与来源清单
├── .agents/skills/dingtalk-*/        # 钉钉官方能力参考副本，不是核心 Skill
├── .dingtalk/                        # 通知接入说明与无秘密示例配置
└── scripts/                          # Hub 辅助通知，不是 Etunel 任务机制
    ├── dingtalk_notify.py            # Python 共用实现，含有限重试
    ├── dingtalk-progress             # macOS/Linux 进度入口
    ├── dingtalk-message              # macOS/Linux 个人摘要与负责人提醒
    ├── dingtalk-progress.ps1         # Windows PowerShell 进度入口
    ├── dingtalk-message.ps1          # Windows PowerShell 个人摘要与提醒
    ├── dingtalk-python.ps1           # Windows 共用启动器，含初始化与检查
    └── test_dingtalk_notify.py       # 不联网的隔离测试

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. 只打开本次任务所需的引用：
  4. 成员先和自己的真人负责人对齐任务与输入，形成明确成果、自审并取得负责人确认后，再交给 Hub。
  5. Hub 校验任务结果，按阶段整理实际文件并更新项目进度和成果索引，只把下游需要的信息定向交给下一角色，不广播无关计划或私有对话。

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

Hook 上下文

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

每份 Hook 文档分为“完整职责 JSON”和“每轮精简提醒”两个独立配置区块，分别复制到 Etunel 对应字段。职责 JSON 不是接口请求，实际绑定与工具参数仍以 Etunel 为准。仓库源文件修改不会自动写入已安装插件或 Etunel 配置。

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

钉钉通知参考

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

只有 Hub／主 Agent 可以使用下面的通用 Python 封装入口（Python 3.9+）：

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

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

新增 message --title "中文标题" --text "问题和下一步" 用于辅助摘要与负责人提醒，可按需用 --at；提醒结果回各自角色会话，不在群里另派任务或批准。两个入口均支持文件正文与离线 --dry-run，Windows 可用 .ps1，macOS/Linux 保留原 Shell 入口。它们是同一封装，不要重复调用。

所有通知统一使用负责人确认的个人 DWS 登录，不再使用机器人。Hub 在首次初始化时查询账号和项目群，用姓名、组织和群名取得确认后，调用 init 自动生成配置；人不用找编号或填密钥。配置只保留通知开关、固定账号、固定群和项目名，个人登录凭据由 DWS 管理。progress 也支持 --at，事件汇报和行动提醒可合成一条；保留 AI 标识和自动汇报说明，不冒充本人批准。

事件语义、有限重试和结果判定见 钉钉项目进度汇报，命令细节见 通知脚本用法；跨平台安装、初始化和旧配置迁移见 .dingtalk/README.md。.agents/skills/dingtalk-* 是钉钉官方多 Skill 的项目内参考副本，不应被当作 Etunel 核心 Skill，也不应被成员用来绕过 Hub。

本地 .dingtalk/config.env 已被 Git 忽略，Hub 可在负责人授权范围内创建或修改；不要提交配置、硬编码真实账号／群标识，或读取和传播 DWS 凭据。accepted 表示取得个人发送任务回执，不等于已投递、已读或接收端 @ 提醒成功。仓库维护时不要用真实发送作为普通测试。

修改项目的推荐流程

  1. 阅读 AGENTS.md 和本次变更涉及的最小文件集合。
  2. 若变更来自流程设计，核对 当前 V1.0 总流程图，在固定文件上修改并通过 Git 提交记录变更；不要新增日期目录或旧版副本。部署及在途项目迁移另行确认。
  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 安装，不要为此把验证器复制进仓库。

修改钉钉封装后运行隔离测试；Shell 入口有修改时再检查对应语法：

python -X utf8 scripts/test_dingtalk_notify.py
bash -n scripts/dingtalk-progress
bash -n scripts/dingtalk-message

还应人工确认：

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

设计资料

Reference in new issue View Git Blame Copy Permalink