ai-ops —— 六仓库企业矩阵的 Agent 工作站

给 chat-gw / xiaoshou / gongdan / casdoor-internal / CloudCostbrank / lobechat-enterprise 这六个仓库提供一个开箱即用的 Claude Code 容器化工作环境。

每个团队成员在自己的机器上跑自己的容器，用自己的 Claude Max/Pro 订阅登录。 共享的只是这份仓库里的 Dockerfile / CLAUDE.md / settings.json。

前置条件

• macOS / Linux，装好 Docker Desktop（>= 4.30）并能拉公网镜像
• 有 DeepSeek API Key（默认）或 Claude Max/Pro 订阅 / 原生 Anthropic API Key
• 能访问 6 个业务仓库的 GitHub 权限（已配好 ssh-key 或 gh auth login）

快速上手（3 分钟）

# 1. clone 本仓库（ai-ops）到你想放的地方，例如 ~/work
cd ~/work
git clone git@github.com:your-org/ai-ops.git
cd ai-ops

# 2. 一键初始化：clone 6 个业务仓库 + 构建镜像
make bootstrap

# 3. 进容器并登录
make enter
# 容器内：
/login                    # 浏览器完成 Claude Max/Pro 授权
/status                   # 确认登录成功

完成后，容器里 /workspace 下能看到 7 个目录（6 个业务仓库 + ai-ops 本身）。

目录约定

默认布局（REPOS_DIR 不设时）：

~/work/                         ← 任意名字
├── ai-ops/                     ← 本仓库
├── chat-gw/
├── xiaoshou/
├── gongdan/
├── casdoor-internal/
├── CloudCostbrank/
└── lobechat-enterprise/

如果你 6 个仓库放在别处，编辑 .env：

REPOS_DIR=/Users/alice/projects

然后 make build && make enter 即可。

常用命令

make enter                  # 交互进入 Agent
make task CMD="扫描 6 仓库的 CVE 并提 PR"   # 非交互单任务
make logout                 # 清除登录状态
make build                  # 重新构建镜像（改了 Dockerfile 后）

权限模型

• 容器内的 Agent 按 .claude/settings.json 的 allow/deny 列表行事：
  • ✅ 允许：git 操作、pytest / npm test / make / gh pr
  • ❌ 拒绝：git push --force、rm -rf /、读 .env、alembic downgrade、生产数据库操作
• 你宿主机的 ~/.ssh 和 ~/.gitconfig 只读挂载到容器内，git push 能用，但 Agent 改不了你本机配置
• 登录凭证存在 docker volume claude-home，不要把这个 volume 导出给队友——每人各自 /login 自己的订阅

Agent 团队阵容

启动 make enter / ./scripts/enter.sh 时，banner 会列出全部已加载 agent 和命令。当前：

13 个专家 Subagent（主 Agent 根据任务自动派遣）

专家	负责仓库 / 领域
python-fastapi-expert	chat-gw / xiaoshou backend / CloudCostbrank / kb-chat-python
nestjs-expert	gongdan backend
react-frontend-expert	xiaoshou/gongdan/casdoor 前端
lobechat-brand-guardian	lobechat-enterprise + 242 locale de-branding 保护
casdoor-specialist	casdoor-internal + upstream fork
mcp-tools-architect	chat-gw 的 MCP 工具注册 + 鉴权流水线
celery-worker-expert	CloudCost 异步任务 + beat schedule
migration-reviewer	Alembic / Prisma / Drizzle / xorm migration 审查
security-auditor	OWASP + secrets + auth 审查（只读）
test-engineer	覆盖率 + flaky 治理 + e2e 设计
ci-cd-engineer	6 仓库的 GitHub Actions workflow
azure-aca-expert	Azure Container Apps + Bicep + Key Vault
docs-writer	README / API doc / runbook / PR 描述

3 个 Team 编排命令（自动组合多专家）

• /team-feature <desc> —— 跨仓库功能开发，7 阶段流水线
• /team-bug-fix <url-or-desc> —— Bug 修复，triage→RCA→fix→回归
• /team-refactor <target> —— 安全重构，test-first + 批次化

7 个快速 Slash Command

• /audit-deps [repo|all] · /add-ci <repo> · /review-pr <pr> · /sync-upstream · /check-migrations
• 外加 team 命令

1 个 Playbook

• playbooks/casdoor-upstream-rebase.md —— 季度级上游同步流程

1 个 Hook（默认开启）

• .claude/hooks/pre-commit-check.sh —— PreToolUse 拦截密钥 / 超大 diff

---

权限模型

所有 agent（包括 azure-aca-expert）享有全部只读权限、受控写权限：

• ✅ gh 全读（view/list/diff）+ 写（pr create/comment、issue create）
• ✅ az 全读（show/list/get-access-token）
• ✅ kubectl 全读（get/describe/logs）
• ✅ 数据库只读查询（psql SELECT、redis GET/KEYS）
• ✅ 各语言测试/lint/build 命令
• ❌ Azure 任何资源的 create/update/delete
• ❌ PR merge / approve / force push / git reset --hard
• ❌ 数据库 DROP/DELETE/UPDATE/FLUSH
• ❌ 读 .env、secrets/、casdoor app.conf

改动生产环境必须由人类 approve。

---

团队可以 / 应该往这里写什么

ai-ops 是团队的"Agent 大脑外挂"。它会随着使用持续沉淀团队经验。下面是6 类内容、该写在哪里、什么时候写。

目录速查

ai-ops/
├── CLAUDE.md                 ← ① 团队规约（描述每个仓库的职责、测试命令、红线）
├── .claude/
│   ├── settings.json         ← ② 权限清单（allow/deny）
│   ├── agents/               ← ③ 专家子 Agent（专业领域深度）
│   └── commands/             ← ④ 斜杠命令（重复任务封装）
├── playbooks/                ← ⑤ 长流程剧本（季度级任务）
├── mcp-servers/              ← ⑥ 自定义工具（高阶，暂不做）
└── reports/                  ← Agent 生成的审计报告（已 gitignore）

---

① CLAUDE.md —— 团队规约（最核心）

写什么：

• 每个仓库的角色、技术栈、端口、测试/构建命令
• 跨仓库契约（如 Casdoor JWT 字段要同步改 chat-gw/xiaoshou/gongdan/lobechat）
• 硬红线（skip-worktree 文件、不可删的 locale 改动等）
• 失败处理策略

何时更新：

• Agent 做错过某件事 → 加一条明确规则
• 团队商量出了新规范 → 写进来
• 仓库加了新测试命令 → 更新测试命令表
• 有人提 PR 被 review 出同类问题两次以上 → 沉淀成规则

② .claude/settings.json —— 权限清单

写什么：

• permissions.allow —— 无需询问就能执行的命令模式
• permissions.deny —— 绝对禁止的命令和路径

何时更新：

• 队友抱怨"XX 命令每次都问我要不要执行" → 加入 allow
• 发生了误操作 → 加入 deny 永久拦截
• 新仓库加入矩阵 → 补充相关路径规则

③ .claude/agents/ —— 专家子 Agent

写什么： 对某个"需要深度知识的领域"封装一个专家，格式：

---
name: xxx-specialist
description: 何时应该派给这个专家
tools: Read, Edit, Bash, Grep
---

系统 prompt：专家应该掌握的事实、工作流、输出习惯、红线。

已有：

• casdoor-specialist —— Casdoor/Go/Beego/upstream fork 专家
• lobechat-brand-guardian —— 守护 242 个 locale 文件的 de-branding

建议未来加：

• migration-reviewer —— Alembic / Prisma migration 深审
• python-fastapi-expert —— chat-gw / xiaoshou / CloudCost 通用
• nestjs-expert —— gongdan 后端

④ .claude/commands/ —— 斜杠命令

写什么： 把团队常跑的任务封装成 /xxx 命令。进容器后一敲就出结果。

已有：

• /audit-deps [repo|all] —— 依赖 + CVE 审计，生成风险排序报告
• /add-ci <repo> —— 给仓库补 GitHub Actions CI（自动识别技术栈）
• /review-pr <pr-url> —— 深度 review 一个 PR（评论式，不自动 approve）

建议未来加：

• /sync-upstream —— casdoor-internal 同步上游冲突分析
• /check-migrations <repo> —— 对比 model vs migration
• /new-endpoint <repo> <path> —— 按项目既有风格新建 API

⑤ playbooks/ —— 长流程剧本

写什么： 低频但重要的多步流程，写成剧本让 Agent 按步执行。

建议加：

• playbooks/monthly-dependency-upgrade.md
• playbooks/casdoor-upstream-rebase.md
• playbooks/new-repo-onboarding.md
• playbooks/prod-incident-response.md

⑥ mcp-servers/（高阶，不急）

只有 Claude Code 内置工具和 chat-gw 已有 MCP 都不够用时才动。建议前 3 个月不碰。

---

团队改 ai-ops 的流程（必读）

任何改动都会影响所有队友的 Agent 行为，流程必须严肃：

1. 提 PR 到本仓库（不要直推 main）
2. PR 描述必须回答 3 个问题：
   • 改了哪个文件 / 加了什么能力？
   • 触发场景是什么（哪次 Agent 做错了 / 哪个重复任务值得封装）？
   • 是放宽了 Agent 权限还是收紧了？（涉及 settings.json 必须标注）
3. 至少 1 人 review —— CLAUDE.md / settings.json 改动建议 2 人
4. 合并后群里吼一声："ai-ops 更新了，各位 pull"
5. 队友本地：

   cd <ai-ops 目录>
   git pull
   # 不用 rebuild 镜像，CLAUDE.md 和 .claude/ 都是 bind mount
   # 正在运行的容器里：退出当前 claude 再重启，新命令/agent 就生效
   

评审改动的判断标准

提 ai-ops 的 PR 时 reviewer 应该问的问题：

改动类型	关键评审点
新规则入 CLAUDE.md	是否来自真实事件？规则是否可验证？是否足够具体（不是"要仔细写代码"这种废话）？
新 command	是否真重复过 3 次以上？参数设计是否清晰？红线是否写全？
新 agent	是否有足够的领域特殊性（不是"再写一个通用 reviewer"）？系统 prompt 是否包含可验证的事实？
改 settings.json allow	放开的命令是否真的无副作用？是否能用更窄的 matcher？
改 settings.json deny	是否会误伤合理用法？有没有代替路径？

---

Claude Code 识别新加的 command / agent 的机制

• .claude/commands/*.md 和 .claude/agents/*.md 会在新 claude 会话启动时被加载
• 所以如果你正在一个 claude 会话里，加了新文件后需要 /exit 再重启 claude 才能看到新命令
• 或者直接在容器里退出后 ./scripts/enter.sh 重进

出问题排查

Docker pull 失败 / TLS 证书错误 —— 检查是否有 VPN / 代理在做 HTTPS 拦截（例如 Astrill 的 OpenWeb 模式）。换成 WireGuard / StealthVPN，或关闭 VPN 后再拉镜像。

apt 装包失败 —— Dockerfile 已配清华镜像 + 重试 8 次。如果仍失败，检查网络对 mirrors.tuna.tsinghua.edu.cn 的访问。

/login 后仍提示未登录 —— 确认你的 Claude 订阅类型是 Max 或 Pro。Free 账号没有 Claude Code 权限。

想切到 API Key 模式 —— 编辑 .env：

• 默认走 DeepSeek 的 Anthropic 兼容端点：ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic + ANTHROPIC_API_KEY=sk-...（DeepSeek 控制台申请），模型用 deepseek-v4-pro 或 deepseek-v4-flash。
• 想走原生 Anthropic：注释掉 ANTHROPIC_BASE_URL，填 ANTHROPIC_API_KEY=sk-ant-...。 API Key 优先级高于订阅。

不做什么

• 不是一个跑在云上的服务，不支持 SSH 远程访问
• 不是给 CI/CD 用的（CI 场景另用 .github/workflows/claude-review.yml + API Key）
• 不共享登录凭证 —— 每人用自己的订阅，违反 Claude TOS 会被踢

许可 / 归属

内部工具，仅限团队使用。六个业务仓库的许可证以各自仓库为准。