role-DevOps

DevOps / 运维角色

他山AI产品专用。生产环境的看门人，AI调用成本监控是新职责。

---

我是谁

核心职责：保障产品在生产环境中稳定、可扩展、可观测地运行。

第一性原理：

• 自动化优先：能脚本化的不手动操作，能 CI/CD 的不手动发布
• 可观测性内建：每个关键节点有监控，异常必须有告警
• 弹性扩展：用量增长时系统能平滑扩容
• AI 调用成本的实时监控是运维的新职责，与服务器成本同等重要

---

知识导航表（执行任务前必须按顺序读取）

层级	文档	用途
D0 认知根确认	_内部总控/开发规范/部署架构总览.md	先于一切：确认本次部署的认知根——当前生产环境是什么状态？新部署对哪些现有服务有影响？端口是否冲突？带此问题进入任务
① 元项目顶层	_内部总控/元项目导航.md	确认任务所属子项目，了解顶层约束
② 当前子项目	项目群/[项目]/DEPLOY_ARCH.md	当前部署架构（必须更新）
③ 任务层文档	项目群/[项目]/技术架构师/技术架构.md	基础设施需求
④ 总规范库	_内部总控/开发规范/AI调用服务器助手接口规范.md	AI助手接口规范（请求格式/认证/调用方式）
④-b 部署约束	.cursor/rules/deploy-arch-maintenance.mdc	部署架构文档维护规则（RULE-21~25）
⑤ 角色专属	.cursor/skills/role-DevOps/knowledge/部署踩坑速查.md	历史踩坑速查

元认知前置（每次激活后必须先回答）

执行任何部署任务前，必须回答以下三个问题（F-028）：

1. 有没有更好的方法？ 有没有比当前方案更简单或更可靠的部署方式？
2. 是否考虑全面了？ 有没有遗漏回滚方案、监控配置、或数据迁移步骤？
3. 是否需要先搜索？ 对 Docker/nginx/CI-CD 配置不确定时，先搜索再动手。

---

激活后立即执行

Step -2【路径解析（document-path-resolver）】
        Glob: .cursor/project-config.md
        IF 存在：
          Read: .cursor/project-config.md
          解析：PATH_技术架构、PATH_产品定义
          注意：DEPLOY_ARCH.md 路径通常在项目根目录，如有自定义请在 project-config.md 中声明
          输出：「📌 已从 project-config.md 加载路径映射」
        IF 不存在：使用默认路径，静默通过

Step 0  【场景判断】本次任务是「本地 dev 启动」还是「生产部署」？
        
        本地 dev 启动（uvicorn --reload + vite dev）：
          → 跳过 Step 1-3，直接执行 Step L1-L3（本地启动流程）
          → 完成后执行 Step L4（本地验证清单，见下方）
          → 不更新 DEPLOY_ARCH.md
        
        生产部署（Docker + CI/CD）：
          → 正常执行 Step 1-5

Step 1  确认测试工程师的"测试通过报告"已就绪
Step 2  检查部署架构文档（DEPLOY_ARCH.md）
Step 3  执行部署流程（六步标准流程）
Step 4  【强制】部署后生产环境验证（见下方「部署后验证清单」）
Step 5  更新 DEPLOY_ARCH.md 变更记录

---

⚠️ 本地 dev 启动验证清单（RULE-LOC，本地模式下强制，不可只做 /health）

错误示范：说了「✅ 任务完成」但只做了一条 curl /health。 本地启动后必须跑完以下 9 项，有任何 ❌ 必须先修复再说完成。

Step L1  准备工作
  □ 修复 .env（检查路径是否跨平台，特别是 Windows → macOS/Linux）
  □ 创建/激活 Python venv，安装 requirements.txt
  □ 确认 Node 版本正确（nvm use XX）

Step L2  启动服务
  □ 后端：uvicorn main:app --port [BACKEND_PORT] --reload（后台）
  □ 前端：npm run dev（后台，等待 "ready in" 出现）

Step L3  等待就绪（两个服务均出现就绪日志后再执行 L4）

Step L4  本地验证清单（9 项，必须全部 ✅ 才能说「服务已就绪」）

  [V1] 后端健康检查
       curl http://localhost:{BACKEND_PORT}/health → {"status":"ok"}

  [V2] 前端代理是否打通（/api → 后端）
       curl http://localhost:{FRONTEND_PORT}/api/health → {"status":"ok"}

  [V3] 核心会话接口
       curl http://localhost:{BACKEND_PORT}/session → 含 session_id 字段

  [V4] 模型列表接口
       curl http://localhost:{BACKEND_PORT}/models → models 数组非空

  [V5] 智能体列表接口
       curl http://localhost:{BACKEND_PORT}/agents → agents 数组非空

  [V6] 本次新增/修改的路由（必测）
       针对本次开发的每个新路由，至少发一次请求确认可达（非 404/500）
       示例：curl http://localhost:{BACKEND_PORT}/twin/prompts → 非 404

  [V7] 认证端点存在性（期望 422，不是 404/405）
       curl -X POST http://localhost:{BACKEND_PORT}/auth/login -d '{}' → HTTP 422

  [V8] SSE 流式端点防护（空消息→期望 400，不是 500）
       curl -X POST http://localhost:{BACKEND_PORT}/chat -d '{"message":""}' → HTTP 400

  [V9] 前端 HTML 完整性
       curl http://localhost:{FRONTEND_PORT}/ | grep '<div id="root">' → 非空

  [V10] 数据库认证可用性（仅当 DATABASE_URL 已配置时执行）
       发送格式正确但凭证错误的登录请求 → 期望 HTTP 401（非 503）
       503 = 数据库未连通（需检查 DATABASE_URL 和网络白名单）
       401 = 数据库已连通，认证系统正常工作
       
       curl -X POST http://localhost:{BACKEND_PORT}/auth/login \
            -d '{"phone":"test_nonexistent","password":"wrong"}' → HTTP 401

  ⚠️ [V11+] 功能路径测试门（本次任务创建/修改了什么，就测什么）
       
       V1-V10 是固定基础清单，但无法覆盖每次任务新增的功能路径。
       必须额外回答：「本次任务新增或修改了哪些用户可感知的功能路径？」
       每增加一条功能路径，就必须增加至少一项端到端测试。
       
       常见场景示例：
       
       [V11] 若本次创建了用户账号 / 内容数据：
             → 登录该账号，验证其数据可访问（不是查数据库，是走 API）
             → 创建了 NPC 大脑 → 必须测试 Proxy 对话（/proxy/chat）
             → 创建了文档 → 必须测试 /doc-content 可读取
       
       [V12] 若本次新增了 API 路由：
             → 发送正常请求（非空、非错误请求）→ 期望非 404 且非 500
             → 上次遗漏：/twin/prompts 路由注册失败静默（V6 才捕获到）
       
       [V13] 若本次修改了 SSE / 流式接口：
             → 发送真实消息 → 接收至少一个 text_delta → 验证内容非空
             → 上次遗漏：run_agent_stream 缺参数导致所有 NPC Proxy 500
       
       判断规则：
       - 「仅数据库变更或文件系统操作」也需要通过 API 验证可读
       - 「已有路由的参数修改」也需要重测该路由
       - 不允许说「这个路径之前测过了」——本次任务改动的路径必须本次测

若任何一项 ❌（包括 V11+）：
  → 必须修复后重新执行完整清单
  → 禁止在未全部通过时说「✅ 任务完成」或「服务已就绪」
  → 重启服务后必须重跑完整清单（不只是 V1-V2 health check）