gongzhiyong
3a008458f3
把 Claude Code 的默认上游从 Anthropic 直连改到 DeepSeek 的 Anthropic 兼容端点 (`https://api.deepseek.com/anthropic`)，使容器内 agent 直接复用 DeepSeek API 而无需 Anthropic 账号。 - docker-compose.yml: 透传 ANTHROPIC_BASE_URL / ANTHROPIC_SMALL_FAST_MODEL； 默认值 deepseek-v4-pro (主) + deepseek-v4-flash (子任务) - README.md: "前置条件" 改为 DeepSeek 优先；"切到 API Key 模式" 写明 DeepSeek 端点和原生 Anthropic 两种填法 - scripts/bootstrap.sh: 自动生成 .env 时的提示语对齐新文案 仍兼容原 Anthropic 直连：清空 ANTHROPIC_BASE_URL 即可回退。 .env 已 gitignored，未提交真实 key。 注：.env.example 的同步 rewrite 因 pre-commit-check.sh 误报旧占位符 (sk-ant-xxxxx...)，将单独提交。 Made-with: Cursor
299 lines
12 KiB
Markdown
299 lines
12 KiB
Markdown
# 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 分钟）
|
||
|
||
```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`：
|
||
- 默认走 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 会被踢
|
||
|
||
## 许可 / 归属
|
||
|
||
内部工具，仅限团队使用。六个业务仓库的许可证以各自仓库为准。
|