66 lines
7.2 KiB
Markdown
66 lines
7.2 KiB
Markdown
# AGENTS.md
|
||
|
||
## 范围与工作入口
|
||
|
||
本文件适用于整个仓库，更具体的子目录说明在其范围内生效，当前任务中的明确用户要求优先。本仓库维护中心业务 Skill、流程文档、记录模板和钉钉通知封装，没有应用构建步骤。
|
||
|
||
1. 先读 [ep-hub/SKILL.md](ep-hub/SKILL.md)，仅按本次任务路由读取相关 reference。
|
||
2. 当前设计来源为 [V2.0 总流程图](doc/Codex多角色项目推进总流程图.html)，运行规则已整理到中心 Skill；不要求目标项目具备流程 HTML。流程文档固定路径更新，历史由 Git 保留，不另建日期或版本副本。
|
||
3. 先后检查 Git 状态与差异，保护用户已有改动和未跟踪资料。不要删除用户保留的旧源文件来制造干净工作区。
|
||
4. 当前工具 schema、运行时契约、成员登记和已确认项目基线与通用 Skill 有冲突时，说明具体差异；不自行猜测能力、改写已确认基线或绕过运行时权限。
|
||
|
||
仓库更新不等于安装 Skill、修改 Etunel 配置或迁移在途项目。配置和通信使用已安装的 etunel-use；本仓库不维护独立的全角色 Hook 源树，不重造队列、投递、重试、去重、会话授权或文件传输。
|
||
|
||
## 修改时必须保留的业务边界
|
||
|
||
- 一个项目使用一个持续的中心会话；默认角色为项目Hub、业务、产品、技术负责人、嵌入式应用层、嵌入式底层、硬件、测试。新增角色按已确认职责和 Etunel 实际管理能力配置，不伪造已创建结果。
|
||
- 每项任务只有一名主责真人，按交付结果或内聚任务包管理。真人自行设计内部工作流程、直接协作并决定是否使用 Agent；成员 Agent 之间仍经中心中继。
|
||
- 中心组织交付和结果确认，处理依赖、跨角色冲突、信息交接及留档，不替专业真人做结论。阶段推进由中心真人决定，不能代替业务授权、产品资源排期确认及外部验收。
|
||
- 原计划、当前有效计划和实际完成时间分别保存；实际完成只取任务提交后对应真人明确确认完成的时间。工具完成、排队、送达、已读或 Agent 检查不能替代。
|
||
- 一项任务保留一份原记录，跨阶段引用。项目层持续显示未完成事项、原计划和当前计划时间、影响及必须完成的阶段；改期、退回、重开保留历史。
|
||
- 正式成果只保存真人完成并确认的最终版和确认；草稿、旧版、历史确认与推进决定进入过程记录。链接成果只登记地址，不要求重复下载、摘要或截图。
|
||
- 中文职责名称统一为“业务”，机器字段仅在实际接口需要时保留。面向人不索取或编造成员、会话和任务技术编号。
|
||
|
||
修改阶段、成果、确认、时间或通知规则时，同步核对 [八阶段规则](ep-hub/references/project-lifecycle.md)、[留档规则](ep-hub/references/project-records.md)、相关模板和通知示例。详细要求下沉到 reference，不重复复制整套规则，也不重新引入成员内部工作流程。
|
||
|
||
实际项目资料只写在目标项目。本仓库的模板是生成指引，使用时用真实事实替换；未知可写待确认，不保留填写说明为项目成果，不伪造记录、确认或文件链接。
|
||
|
||
## 钉钉集成
|
||
|
||
- 只有中心／主 Agent 使用 [通知规则](ep-hub/references/dingtalk-progress-reporting.md) 和 [脚本用法](ep-hub/references/dingtalk-script-usage.md)。通知是辅助可见性和行动提醒，不是角色任务通道、审批、真人确认、推进依据或事实源。
|
||
- 只用 `scripts/dingtalk_notify.py` 的 `progress`／`message` 或等价平台入口；事件只有 start、milestone、blocked、complete、failed。progress 使用实际当前阶段，正文按已确认进展、待办、遗留分条，真实姓名按约定原位 @。
|
||
- 先维护事实记录再通知，不为通知重新分配已有责任、期限或新建清单，不省掉已明确的停止事项和范围限制。
|
||
- 不绕过封装调用 OpenAPI 或其他入口，不增加外层重试／通知队列。仅明确 DNS 失败最多 3 次、间隔 10 秒，未知结果不重发。
|
||
- 首次账号、组织、群及通知范围由真人确认，配置用真实查询值；换账号或群重新确认。初始化和部署见 [.dingtalk/README.md](.dingtalk/README.md)。只保存开关、账号、群和项目名，本地配置不提交、不在普通回复或群中输出内部标识。
|
||
- 不读取、输出或提交 DWS 登录凭据、Client Secret、DING_SEC、App Token；不静默将旧机器人授权变成个人代发。保留 AI 标识，发送不代表真人批准。
|
||
- 仓库维护只用隔离假配置和离线测试。真实发送需要任务明确要求且环境已授权，不能作为普通冒烟测试。API 接受不代表接收端渲染或已读。
|
||
- `.agents/skills/dingtalk-*` 是官方参考副本，除非明确要求，不批量改动。
|
||
|
||
## 编辑与发布
|
||
|
||
- 中文编写说明、成果名称和面向人的消息；Markdown 相对链接须可解析，文本保持 LF。
|
||
- 入口保持精简，新增 reference 和模板须能按条件发现。不放日志、缓存、机器配置、凭据或未完成脚手架；模板的填写指引不当作真实记录。
|
||
- 历史模板笔记保留来源和适用年代，不能用旧规则覆盖当前基线。模拟与真实成果分开，不将未执行写通过，不将不适用写失败。
|
||
- 版本统一为 vX.Y.Z：X.Y 跟随 HTML 已确认流程版本，Z 是该流程下仓库迭代。流程不变只升第三位，流程改到新的 X.Y 时 Z 从 0 开始；不按变更规模自行调整前两位，组件不另编号。详见 [版本与升级](README.md#版本与升级)。
|
||
- 仅在用户要求时提交、推送或发版；已发布标签不可覆盖或移动，推送后核对远程提交。日常修改不自动创建标签。
|
||
- 发布说明写基线、变更、验证、安装／配置更新和在途影响。发布不等于部署，插件缓存更新及在途迁移须明确确认，不把仓库版本规则塞进运行时 Skill。
|
||
|
||
## 验证与完成
|
||
|
||
从仓库根目录执行适用检查：
|
||
|
||
```powershell
|
||
python -X utf8 "$env:USERPROFILE/.codex/skills/.system/skill-creator/scripts/quick_validate.py" ep-hub
|
||
python -X utf8 scripts/test_dingtalk_notify.py
|
||
git diff --check
|
||
git status --short
|
||
```
|
||
|
||
Skill Creator 验证器按本机安装定位，不复制进仓库。若已安装 rtk，可使用其等价包装；没有时直接执行上述命令。
|
||
|
||
- 改 Skill 后通过结构校验，并检查渐进式路由、相对链接及规则一致性；结构通过不代表业务行为已验证。
|
||
- 改钉钉脚本时运行离线测试。改 Shell 入口时用 bash -n 检查；改 PowerShell 入口时检查解析和隔离配置下的实际参数传递。需要发送能力时使用独立 Python，商店版仅可用于离线检查。
|
||
- 最终说明改了什么、依据什么、验证了什么，以及未验证／未部署的部分，不把本地源码修改当成线上生效。
|
||
|
||
改变尚未获确认的流程基线、角色集合或职责边界，删除未获授权的历史资料，批量替换官方参考包，真实通知或其他不可逆操作，先取得对应授权。当前任务已明确授权的改造继续完成，不反复索要同一确认。
|