# AGENTS.md

## Project Overview

本仓库维护 Etunel 多 Agent 项目的角色协作约束，核心交付是：

- `etunel-role-collaboration/`：供各角色按需读取的渐进式披露 Skill；
- `etunel-role-hook-contexts/`：供 Etunel 独立配置的八角色精简 Hook 上下文；
- `doc/`：当前流程设计基线和模板参考资料；
- 钉钉参考集成：仅帮助 Hub 理解如何调用辅助通知，不属于 Etunel 任务通信主链路。

这是以 Markdown、HTML 为主、附带 Python 和平台启动脚本的约束仓库，没有需要猜测的应用构建步骤。

## Scope

本文件适用于整个仓库。若后续子目录新增更具体的 `AGENTS.md`，以距离目标文件最近的规则为准；当前任务中的明确用户要求始终优先。

## 开始工作前

1. 先读根 Skill：[etunel-role-collaboration/SKILL.md](etunel-role-collaboration/SKILL.md)。
2. 只按其中的条件路由读取本次修改涉及的 reference，不要一次加载所有角色和测试细则。
3. 当前设计基线为 [V1.0 总流程图](doc/Codex多角色项目推进总流程图.html)（文档生效日期 2026-09-08）。`doc/` 只维护当前流程文件和配套参考，不再按日期或版本复制文档；后续直接更新同一文件，历史通过 Git 提交追溯。仓库更新不等于部署 Skill／Hook 或迁移在途项目；已运行项目继续使用其登记基线，迁移及插件缓存更新须明确确认。
4. 运行时 Hook、Etunel 工具 schema、项目角色契约、成员登记及已确认的项目流程基线，高于 Skill 的通用说明。发现冲突时说明冲突，不要自行猜测或发明能力。
5. 保留用户已有改动；修改前后检查 Git 状态与差异。

不要让运行时 Skill 依赖某个带版本号的流程图或提示词文件。应把已确认且仍有效的规则整理为稳定约束，并放入正确的渐进式 reference；流程文档只作为设计来源，历史以 Git 提交追溯。

## 必须保持的协作边界

- 默认八个角色是项目Hub、业务、产品、技术负责人、嵌入式应用层、嵌入式底层、硬件和测试。
- 项目Hub是成员 Agent 之间唯一的跨角色中介。现阶段不支持成员角色直接通信；所有跨角色信息必须交给 Hub 定向中继。
- 一个项目使用一个持续的 Hub 会话贯穿生命周期；不同阶段与不同角色会话交接，不为每个阶段另建 Hub。
- 每项任务只有一个主责角色。依赖已满足的多项任务可以形成任务波次；同一角色的内聚工作可以一次组成任务包。
- Hub 派发内容必须足以执行，并与要求的成果文件或成果包一致。成员先与本角色真人负责人对齐、自审并确认，再向 Hub 返回正式结果。
- Hub 使用 `mcp__etunel__etunel_list_roles` 返回的 `role` 路由任务，以 `display_name` 面向人显示；不得向负责人索取或制造成员、会话和任务编号。
- Hub 校验身份、结构、版本、证据、确认、依赖和门禁，不代替专业角色完成内容或作出专业结论。
- 新自定义角色必须先形成职责契约，再由 Hub 真人负责人在 Etunel 中手动添加并绑定；AI 不得宣称已自动创建角色。
- Etunel 运行时拥有队列、投递、重试、去重、会话授权和文件传输机制。本仓库只约束角色流程，不重复设计这些软件逻辑。
- 中文职责名称统一写“业务”；仅在运行时标识、文件名或技术映射中使用 `business`。

## Key Paths

| 路径 | 用途 | 修改要求 |
| --- | --- | --- |
| `etunel-role-collaboration/SKILL.md` | 入口、共享硬约束、条件路由 | 保持精简；只放高频、跨角色且必须立即知道的规则 |
| `etunel-role-collaboration/references/` | Hub、成员、生命周期、消息、成果、异常等详细规则 | 按条件拆分；新增 reference 必须能从 `etunel-role-collaboration/SKILL.md` 或已路由文件发现 |
| `etunel-role-collaboration/references/roles/` | 七个成员角色的职责契约 | 角色专属决定、输入、输出和边界写在对应文件 |
| `etunel-role-collaboration/references/testing/` | 测试角色二级细则 | 只保留匹配任务时才需要的深层内容 |
| `etunel-role-hook-contexts/` | 八角色 Hook 的完整精简职责与每轮提醒 | 独立于 Skill 发现树；简短、可直接注入、与正式职责一致 |
| `doc/` | 当前流程来源及模板参考 | 固定路径维护一份当前文档；不建日期或版本副本，历史查 Git；变更同步核对链接与基线说明 |
| `.agents/skills/dingtalk-*` | 钉钉官方能力的项目内参考副本 | 不是 Etunel 核心 Skill；除非任务明确要求更新参考包，否则不要批量改动 |
| `.dingtalk/`、`scripts/` 中的钉钉封装 | Hub 通知配置说明、跨平台入口、共用 Python 实现和离线测试 | 不把通知能力扩大为任务派发、审批、门禁或事实源 |

修改共享流程、角色边界、阶段、正式成果或跨角色信息流时，必须同步检查根 Skill、相关公共 reference、受影响角色 reference 和对应 Hook。角色细节优先下沉到角色文件；测试专项优先下沉到测试二级 reference。不要靠复制整段规则维持一致性。

实际项目的运行资料不预先创建在本仓库中。Hub 应按 [项目文件与进度留档](etunel-role-collaboration/references/project-files-and-progress.md) 在使用此 Skill 的目标项目里建立阶段目录、保存正式成果并维护进度和成果索引。

## 钉钉参考集成边界

钉钉内容存在于本仓库，是为了给 Hub 提供“如何调用钉钉发送项目通知”的参考和演示能力，不是本项目的核心职责系统：

- 只有 Hub／主 Agent 可以调用通知；成员 Agent 只向 Hub 返回成果、状态或阻塞。
- 通知是项目群的单向辅助可见性与异常提醒，不是角色间通信、任务派发、审批、人类确认、项目门禁或项目事实源。
- Agent 只用 `scripts/dingtalk_notify.py` 的 `progress`／`message`，或等价的 `dingtalk-progress`／`dingtalk-message` Shell、PowerShell 入口，统一以已确认的个人 DWS 账号发送。进度事件仍限定为 `start`、`milestone`、`blocked`、`complete`、`failed`；负责人提醒不新增状态。同一事项不重复通知，不得绕过封装直接调用 OpenAPI 或 `dws api`。可验证里程碑先完成项目留档，再发送简短中文 Markdown。例如：

  ```sh
  python scripts/dingtalk_notify.py progress milestone "**已完成**

  - 阶段成果已确认并归档

  **下一步**

  - Hub 安排后续任务"
  ```
- 事件语义与消息格式以 [dingtalk-progress-reporting.md](etunel-role-collaboration/references/dingtalk-progress-reporting.md) 为准；安装与本机配置参考 [.dingtalk/README.md](.dingtalk/README.md)。
- 通知封装是辅助接入参考，不得据此反推或改变 Etunel 主流程；不创建通知队列或外层重试。仅明确 DNS 失败最多 3 次、间隔 10 秒，结果未知不盲目重发。
- 仓库维护和测试期间不得把真实发送当作冒烟测试。只有任务明确要求发送且当前环境已经授权时，才允许触发真实通知。
- Hub 首次查询个人账号及项目群，以姓名、组织和群名取得负责人确认后，用封装 `init` 创建 `.dingtalk/config.env`；只含通知开关、固定账号、群和项目名，不保存机器人或登录密钥。AI 可以在授权范围内维护该配置，但不提交或在群里展示内部标识；换账号或群须重新确认。
- 不读取、输出或提交 DWS 登录凭据、Client Secret、`DING_SEC`、App Token。旧机器人配置须经确认重新初始化，不静默启用个人代发；保留 AI 标识，个人通知不代表负责人亲自批准。

## 编辑约定

- 使用中文编写项目说明、职责约束、成果名称和面向负责人的消息；机器枚举与运行时字段只在工具确实要求时保留。
- Markdown 使用相对链接；每个新增链接都应能从仓库中解析。
- 保持渐进式披露：入口说明“何时读什么”，详细内容放在对应 reference，不在多个文件重复整套流程。
- Hook 只保留角色定位、关键边界、工具提醒和每轮控制点，避免塞入大段流程正文。
- 不伪造 Etunel 工具名、参数、角色、成员、会话、状态或尚不存在的文件。
- 不把模拟流程结果描述为真实发布、客户验收或生产就绪；不适用项对人统一写“不适用”，只在机器字段要求时使用对应枚举。
- 文本文件保持 LF；不要提交日志、缓存、临时文件、机器专属配置或凭据。

## 版本与发布

- 全仓库统一使用三位版本 `vX.Y.Z`：前两位 `X.Y` 跟随 `doc/Codex多角色项目推进总流程图.html` 内明确标注且已确认的流程版本；第三位 `Z` 是该流程版本下的仓库发布迭代号。Git 标签与发布包确定该版 Skill、Hook、脚本和文档，组件不另设发布序列。
- HTML 主流程版本不迭代时，所有变更均只递增第三位，包括 Skill／Hook 优化、脚本新增、修复、配置调整和文档更新；不按功能规模或兼容性自行提升前两位。流程保持 V1.0 时依次发布 `v1.0.0`、`v1.0.1`、`v1.0.2`。HTML 流程正式升到新的 `X.Y` 时，仓库前两位同步，第三位从 0 开始，例如流程 V1.1 对应 `v1.1.0`；不为凑发布号改流程图。
- 这是流程版本驱动的项目约定，不采用“新增功能就升次版本”的语义化版本规则；第三位更新也可能需要配置迁移，发布说明必须如实列出。涉及职责或门禁变化仍须先按项目约束确认流程，不能借版本编号规则跳过确认。
- 日常提交不必发版。发版前确认版本号、完成适用校验，说明流程基线、变更内容、需更新的 Skill／Hook 和在途项目影响；具体说明见 [README 版本与升级](README.md#版本与升级)。
- 仅在用户要求时提交、推送或发版；已发布标签不可覆盖或移动，修正另发新版本。推送后核验远程分支与标签提交，不能把本地提交当成已发布。
- 发布不等于部署。仅更新受影响的 Skill／Hook 配置，插件缓存更新及在途项目迁移仍须明确确认；不要求角色每轮核对发布号，不将仓库发版规则塞进运行时 Skill。

## Quick Commands

修改后按影响范围执行：

```powershell
rtk python -X utf8 "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" "etunel-role-collaboration"
rtk python -X utf8 scripts/test_dingtalk_notify.py
rtk "C:\Program Files\Git\bin\bash.exe" -n scripts/dingtalk-progress
rtk "C:\Program Files\Git\bin\bash.exe" -n scripts/dingtalk-message
rtk proxy git diff --check
rtk proxy git status --short
```

Skill Creator 的验证脚本位置取决于协作者的 Codex 安装。若默认路径不同，应定位已安装的 quick_validate.py，不要把验证器复制进仓库。

## Definition of Done

- 修改 Skill 时已通过 Skill Creator 的结构校验。
- 修改钉钉封装时运行离线测试；修改 Shell 入口时检查语法，修改 PowerShell 入口时核验解析和实际参数传递。只使用隔离假配置，不触发真实通知。
- 所有新增或改动的 Markdown 相对链接均能解析。
- 文件中没有待办标记、占位内容、真实凭据、群标识或误导性的缺失文件引用。
- 根 Skill、公共 reference、角色 reference 和对应 Hook 在受影响规则上保持一致。
- 最终说明修改了哪些文件、依据什么、执行了哪些验证以及仍有哪些未知项；未验证的内容不得声称通过。

## Boundaries

始终执行：保护已有改动；只读必要资料；保持 Hub 中介、人类负责人确认、正式成果和渐进式披露规则一致。

先征得确认：改变当前流程基线、角色集合或职责边界；删除历史资料；批量替换钉钉参考包；进行真实钉钉发送；执行其他不可逆操作。

绝不执行：提交秘密配置；让成员绕过 Hub 直接通信；把钉钉当成 Etunel 任务通道；用 Skill 重造 Etunel 队列机制；为不存在的工具、角色、参数或成果制造虚假规则。