# 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）并能拉公网镜像
- 有 **Claude Max 或 Pro 订阅**（或 Anthropic API Key）
- 能访问 6 个业务仓库的 GitHub 权限（已配好 ssh-key 或 gh auth login）

## 快速上手（3 分钟）

```bash
# 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`：

```bash
REPOS_DIR=/Users/alice/projects
```

然后 `make build && make enter` 即可。

## 常用命令

```bash
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

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

```markdown
---
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. 队友本地：
   ```bash
   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`，填 `ANTHROPIC_API_KEY=sk-ant-...`。API Key 优先级高于订阅。

## 不做什么

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

## 许可 / 归属

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