本文件是本仓库的通用智能体协作规范。任何模型/智能体在本项目中进行实现、重构、测试或文档更新时，都必须遵守本文件。
- 用户的最新明确指令优先级最高。
- 需求、计划、架构信息是实现依据；其中需求与 BUG 统一以 GitHub Issues 为准，计划与架构信息位于
docs/plan/、docs/architecture/。 - Git 工作流与发布流程统一以
docs/Git 使用规范.md为准。 - 本文件定义通用协作规则，不限定具体业务功能。
冲突处理优先级（从高到低）：
- 用户最新明确指令
- 任务对应的需求文档
- 本文件（AGENT.md）
- 计划与路线图文档
- 分支策略严格遵循
docs/Git 使用规范.md。 - 禁止直接向
main提交或推送代码；必须通过合并流程进入main。 - 新功能开发分支必须从
develop创建，并合并回develop。 - 发布分支使用
release/*，生产紧急修复使用hotfix/*。 hotfix/*修复完成后必须同时回合并到main与develop。- 版本标签遵循语义化版本（
vMAJOR.MINOR.PATCH），并与发布记录一致。 - 客户定制化优先采用配置/模块化/功能开关；仅在无法解耦时使用客户长期分支。
智能体在执行 Git 相关操作时必须：
- 先确认当前分支是否符合规范再开始编码。
- 若分支不符合规范，先提示并给出正确分支建议（例如从
develop拉feature/*）。 - 未经用户明确要求，不得直接在
main上提交代码。
- 先读需求与计划，再编码；禁止未读上下文直接改代码。
- 优先完成前置依赖任务，再做后置任务；不得跳过关键前置条件。
- 每次提交应是最小可验证改动，避免把多个不相关改动混在一起。
- 若需求不完整，先按仓库既有模式做最小可行实现，并在说明中列出假设。
- 遵循仓库已有目录边界与模块职责；无必要不重排目录。
- 接口层、业务层、基础设施层应尽量分离，避免耦合实现细节。
- 新增模块优先放在语义清晰、可发现的目录，并与现有命名风格一致。
- 不在单个函数中混合参数解析、核心业务、外部 I/O 和输出格式化。
- 优先可读性与可维护性：短函数、清晰命名、单一职责。
- 仅在必要时添加注释；注释解释“为什么”，不重复“做了什么”。
- 新增依赖要最小化，并在变更说明中写明必要性与替代方案评估。
- 严禁提交密钥、密码、Token、私钥、真实账号等敏感信息。
- 任何对外行为变更（CLI/API/配置）都要保持兼容，或明确记录破坏性变化。
- 结构化输出（如 JSON）应保持字段稳定；新增字段优先向后兼容。
- 错误信息应可诊断、可区分，避免仅返回模糊失败文案。
每个可交付改动至少满足：
- 有对应测试或可重复验证步骤。
- 覆盖至少一个失败场景或边界场景。
- 文档在行为变化时同步更新（README、用法、配置或设计文档）。
- 不引入与当前任务无关的大规模改动。
- 未经明确要求，不进行大范围重构或风格化清理。
- 不随意修改公共接口命名、配置键名、文件格式。
- 若必须做破坏性调整，先在文档标注影响范围与迁移方案。
- 已阅读本文件与任务相关文档。
- 已确认前置依赖与影响范围。
- 已定义验证方式（测试或命令复现步骤）。
- 已保证改动最小且边界清晰。
- 已准备同步更新必要文档。
若无法满足上述任一项，应先输出阻塞点与备选方案，再继续执行。