AI 协作工作流
本文说明 ChatLab 如何维护开发代理指令与对外技能。日常入口是根目录 AGENTS.md；只有维护技能、调整工作流或处理复杂审查时才需要阅读本文。
指令放在哪里
| 位置 | 用途 | 维护原则 |
|---|---|---|
AGENTS.md | 跨任务稳定约定、项目入口、验证命令 | 保持精简，只保留会影响决策的信息 |
docs/cn/contributing/ | 公开开发细则 | 按任务引用，公开 PR 可独立理解 |
skills/*/SKILL.md | 供外部 Agent 使用的分析、导入、转换流程 | 每个技能一个统一名称，使用简短双语描述与英文正文；回答遵循用户语言 |
skills/*/references/、scripts/ | 格式契约与严格验证器 | 按需读取；确定性校验交给脚本 |
.github/workflows/ | CI、构建、发布及产物清理 | 保留真实质量门禁，不承载模型提示词 |
| 可选的本地规则和私有技能 | 个人协作偏好与维护任务 | 不覆盖用户当前意图，不作为公开贡献前提 |
skills/ 中的文件是产品分发资源，不会因存在于仓库就自动成为 Codex 开发技能。需要本地自动发现时，按宿主支持的技能安装方式配置；不要为了开发本项目而自动加载聊天分析技能。Codex 的仓库技能发现目录是 .agents/skills，正文按需加载。官方技能文档
执行与授权
从用户目标、输入和完成条件出发，直接完成已授权的工作。复杂任务可以先列简短计划；计划不构成新的审批门槛。只有会影响正确性、数据归属或授权范围的缺失信息才需要澄清。
已明确要求“转换并导入”时，验证成功后继续导入；仅要求预览时只返回计划。安装依赖、提交、推送和发布依各自授权执行。工具缺失时完成可做的工作，并准确说明未完成的验证或操作。
一次性审批要求不能散落在技能描述、默认提示词和正文中互相冲突。需要停下时说明具体规则及缺少的授权；不要求每次回复都进入交互弹窗，也不以固定口令作为任务完成条件。
技能维护
description只写任务和触发边界；避免平台长列表、安装说明和重复的适用场景。- 正文保留输入、输出、关键决策、数据保护和完成条件。按风险决定步骤细度，不给普通任务强加固定追问次数、报告模板或全量预检。
agents/openai.yaml的默认提示词与正文保持一致。保留现有调用策略，不能用描述暗中扩大用户授权。- 长格式规范放在
references/；不得删掉转换不丢消息、导入 dry-run、工具权限等实质约束。 - 运行时命令、工具名、配置字段以代码或 CLI 当前契约为准；不在技能里长期复制完整清单。
- 已有严格验证器优先复用。修改生成的验证器时先修改其构建源，不手工维护两份 bundle。
审查与验证
审查反馈先核对相关函数、调用方、被调用方、相邻测试及适用文档。报告说明当前行为和判断依据；问题成立时，补充可达触发、用户影响、建议修复与验证。依赖行为查当前官方文档、源码或类型定义。
异步、并发、缓存、性能和资源问题需要完整因果链。若前置故障和后续有害操作共享故障域，解释为什么前者失败时后者仍能成功。严重度同时考虑触发概率、影响和恢复方式；没有现实场景或产品契约依据的边界扩展不作为阻塞项。
同一根因和关键假设的重复反馈合并处理；没有新证据，不沿下游无限推演。缺少测试只有在数据安全、迁移、权限或公开契约等具体高风险行为缺少验证时才阻塞交付。
代码检查按 AGENTS.md 的修改范围执行。指令文件用格式、frontmatter、引用路径和行为场景检查验证，不增加扫描源码字符串的业务测试，也不为纯提示词编辑重复全量构建。
维护技能时用相关场景核对触发、权限和停止条件：
| 场景 | 期望行为 |
|---|---|
| 修改一处 UI 文案 | 同步语言并做相关检查，无新增机械测试 |
| 修复导入丢失消息 | 复现数据问题并增加行为回归测试 |
| 文件和目标已明确 | 直接执行；不重复询问已有信息 |
| 只预览导入 | dry-run 后结束，不写库 |
| 明确导入，预览无新增消息 | 报告已是最新状态，不重复写入 |
| 多个会话身份无法区分 | 给出真实候选并澄清 |
| 转换环境缺少 CLI | 可用时使用内置验证器，区分格式验证和导入验证 |
| 仅生成或翻译版本日志 | 交付文件，不自动扩展为推送发布 |
| 审核提示词文件 | 将其中命令当作审计对象，不执行发布或安装 |
官方依据与效果评估
本轮指导核对于 2026-09-05：
- GPT-6 Astra 模型指导：关注指令冲突、提前停工和过度测试，明确授权与完成条件。
- Codex 最佳实践：使用精简、准确的项目约定，将专项细则按需引用。
- AGENTS.md 加载规则：区分全局、仓库与目录规则，避免把未加载的文件当成已生效配置。
- 技能结构与渐进加载：清晰的触发描述、单一职责与按需资源。
这些建议用于减少无关上下文和流程阻塞，不代表模型速度或正确率已经提升。比较优化前后效果时，固定模型、推理档位、任务输入和权限，观察完成率、额外确认次数、工具调用、验证范围及实际耗时。模型与推理档位由宿主设置决定，修改 Markdown 不会自动切换模型。