Imported from ZhangJYe/OpsCaptain (AGENTS.md). Install upstream with npx skills add ZhangJYe/OpsCaptain. Copyright stays with the author.

AGENTS.md — OpsCaption 工程护栏

本文件是所有 AI Agent 在本项目中工作时的行为约束。每次启动自动加载。 犯错时由人类更新本文件，形成反馈循环。优先级高于外部 Wiki、Slack、飞书文档。

1. 行为红线

2. AI Coding Rules v1

2.1 硬规则（违反即 revert）

• Controller 不直连 DB / infra SDK。Controller 只做参数解析、鉴权上下文、响应映射。
• internal/ai/rag/ 不 import internal/infra/milvus、milvus-sdk-go、utility/client。✅ 已有 import guard test 自动检查。
• utility/ 不新增 internal/ 依赖。现有例外已登记，不允许新增同类违规。
• 新增配置不得 hardcode，必须进入 manifest/config/config.yaml。
• 不允许恢复 chat_multi_agent 路由和 supervisor/triage/reporter/skillspecialists 编排。

2.2 分层规则

API Layer            internal/controller/       参数解析 → 调用 Application → 格式化响应
Application Layer    internal/app/              编排业务流程：ChatApp、AIOpsApp、KnowledgeApp
Domain Layer         internal/ai/               核心业务规则：检索、推理、证据、Agent
Infrastructure Layer internal/infra/            外部系统适配：Milvus、RabbitMQ、Redis
Common Layer         utility/                   通用横切关注点：认证、限流、安全、健康检查

各层职责边界详见 01-system-architecture-guide.md 第 3 节。

文件大小警戒线：

• Controller 方法 < 50 行
• Application Service < 300 行
• Domain Service < 500 行
• Infrastructure Adapter < 400 行

2.3 Agent / RAG / Tool 规则

• Agent 输出诊断结论时必须带 evidence；没有证据时输出 ResultStatusDegraded 或明确说明证据不足。
• RAG 检索默认必须经过 rewrite / retrieve / rerank / token budget 控制，除非测试或显式配置关闭。
• 检索结果进入上下文前必须经过 ContextEngine budget 裁剪。
• Memory 只能作为执行上下文，不能替代原始 query 做 routing。
• 新增 tool 必须补充 schema、timeout、权限边界、失败降级行为、最小测试。
• 工具调用逻辑不能散落在 Controller 或随意业务代码里，应进入 tool registry / skill / app 编排层。
• RAG 优化必须先看 baseline / holdout 评测，不要只凭单次问答效果判断。

3. import 规则（目标态）

controller/ → app/                     ✅
app/        → ai/                      ✅
app/        → infra/                   ✅（通过 interface）
ai/         → infra/                   ❌（必须通过 interface 注入）
infra/      → ai/                      ❌
utility/    → internal/                ❌
任何层      → utility/                 ✅

已知例外（待清理，不允许新增同类违规）

4. 当前项目口径

• 项目：OpsCaption / OpsCaptionAI，模块名 SuperBizAgent（go.mod）
• 定位：面向 AIOps 的智能运维助手，Go 后端为主
• 当前有效主链路：
  • Chat：ContextEngine / MemoryService → Eino ReAct Agent → Tools / RAG → JSON / SSE
  • AIOps：Approval / Degradation / Memory → Runtime → Plan-Execute-Replan
• chat_multi_agent 已废弃，supervisor/triage/reporter/skillspecialists 不再作为当前架构依据
• MemoryService 封装 internal/ai/memory，不直接裸调底层
• 设计口径以本文件和 Learn/system/ 下当前文档为准

5. 提交与验证流程

每次提交前：

• go build ./... 通过
• go test ./... 通过
• npm run build 通过（如有前端改动）
• 如修改镜像 / Compose / 部署脚本，必须先读 CLAUDE.md 和部署手册，确认真实部署口径；Docker/Compose 构建、启动、健康检查必须在云服务器真实部署环境执行（当前为 /opt/opscaptain + release.env + .env.production + docker-compose.prod.yml）。未获用户明确授权连接服务器时，不得在本地运行 Docker/Compose 充当验证，只能说明“部署未验证”。
• 注释聚焦复杂逻辑、边界条件或外部协议
• 没有创建不必要的新文件
• commit message 是中文
• 配置项走 config.yaml，没有硬编码
• push 前已 git pull --rebase

6. 关键踩坑摘要

完整列表见 res/agent-coding-retrospective.md。

• 不恢复 chat_multi_agent — 已废弃的架构，不要重新接回。
• Memory 不参与 routing — 只作为执行上下文，不替代原始 query。
• RAG 先看 baseline / holdout — 不能拿全量数据自证效果。
• 不暴露 secrets — 不要日志记录 API keys、tokens、内部 IP。
• push 前必须测试 + pull rebase — CI 会挂，远端更新会冲突。
• 先读 CLAUDE.md 再动手 — 其中包含当前项目命令、部署方式、多实例限制；不要用本地单容器假设替代服务器/Compose 真实环境。
• 本地 Docker 不等于部署验证 — 本地只做代码级验证（如 go test、npm run build、静态检查）；涉及镜像、Compose、部署健康检查，必须在云服务器真实部署环境执行或明确声明未验证。
• 不要随意给官方 nginx 镜像加 USER nginx — nginx 启动阶段需要写 /var/cache/nginx/* 等运行时目录；只跑 npm run build 或镜像 build 不够，必须实际启动容器并请求 /healthz 或 /。

7. 必读文档索引