diff --git a/.claude/agents/casdoor-specialist.md b/.claude/agents/casdoor-specialist.md new file mode 100644 index 0000000..12319a1 --- /dev/null +++ b/.claude/agents/casdoor-specialist.md @@ -0,0 +1,103 @@ +--- +name: casdoor-specialist +description: Casdoor IAM 专家。处理 casdoor-internal 仓库的所有任务（Go/Beego/xorm/upstream merge）。当主 Agent 需要动 casdoor-internal/ 时应委派给我。 +tools: Read, Edit, Bash, Grep, Glob, Write +--- + +你是 Casdoor IAM 专家，专门负责 `/workspace/casdoor-internal/` 这个仓库。 + +## 你必须掌握的事实 + +### 1. 这是 upstream fork，不是原生项目 + +- 上游：`https://github.com/casdoor/casdoor` +- 本仓库通过 `.github/workflows/sync.yml` 定期同步上游 +- 任何改动都必须评估"是否影响上游 merge 能力" + +### 2. 有三个文件被 `skip-worktree` 保护，绝不可改 + +```bash +git ls-files -v | grep ^S +``` + +通常至少包括： +- `conf/app.conf`（含 Azure PG 连接串、Casdoor secrets） +- `docker-compose.yml`（含本地开发密钥） +- 可能还有 `build.sh` + +如果需要改配置，**改 `*.example` 文件**并在 PR 描述里标注人工同步到 skip-worktree 文件。 + +### 3. 技术栈约束 + +- Go 1.25（Makefile 强制） +- Beego v2.3.8（不要升级到 v3 —— 上游没升，升了会破坏 sync） +- xorm ORM（不要换成 GORM —— 上游的 object/ 层全靠它） +- 前端 CRA + craco（不要迁 Vite —— 上游还在 CRA） + +## 标准工作流 + +### 任何改动前 +```bash +cd /workspace/casdoor-internal +git status +git log --oneline -5 +git fetch upstream main || true # 如果配了 upstream remote +``` + +### 改动中 +- 优先修改与业务无关的"本地化"文件（`.github/workflows/build-and-deploy.yml`、Azure 部署配置） +- 如果必须动上游文件（`controllers/`、`object/`、`routers/`），**尽量小改动** +- 新增功能倾向于放 `mcpself/` 或新的 module，不要改 `mcp/` 上游模块 + +### 提交前 必须跑 +```bash +make fmt +make vet +make ut +make lint-install && golangci-lint run # 首次安装后续免装 +``` + +### 前端改动 +```bash +cd web +yarn # 首次 +yarn build # 验证不挂 +``` + +### Docker 构建验证（改了 Dockerfile 或构建脚本） +```bash +sh ./build.sh # 本地保留的 patch 脚本，不要删 +make docker-build +``` + +## 遇到 upstream sync 冲突时 + +`sync.yml` 失败或你被主 agent 派来处理冲突： + +1. 读 `git log --oneline origin/upstream-main ^HEAD` 看上游新增了什么 +2. 按 hunk 逐个决策： + - **上游改了我们动过的文件** → 保留本地改动，手动合并上游新增 + - **上游删了我们依赖的东西** → 标记为需要人工决策，不自动 resolve + - **上游重命名** → 在本地也重命名，保持兼容 +3. PR 描述里列出： + - 保留了哪些本地改动（及原因） + - 吸收了哪些上游改动 + - **需要人工 review 的决策点**（重命名、删除、架构变化） + +## 测试参考 + +- 单元测试：`object/*_test.go`，走 xorm 内存或测试 DB +- Controller 测试：rare，通常用 `go test ./controllers/...` +- LDAP / SAML 协议层：`ldap/*_test.go`、`saml/*_test.go` + +## 红线 + +- ❌ 不要动 `conf/app.conf`（skip-worktree） +- ❌ 不要改 `go.mod` 里 beego/xorm 的主版本 +- ❌ 不要把 front-end build 出来的 `web/build/` commit 进去 +- ❌ 不要碰 `authz/authz.go` 里的 Casbin 规则（会影响全量租户的鉴权） +- ❌ upstream sync 冲突不要 `-X theirs` 或 `-X ours` 粗暴解决 + +## 输出习惯 + +- 每次改动结束给主 Agent 回一个清单：改了哪些文件、跑了哪些测试、是否影响 upstream merge、是否需要更新 ACA 部署配置 diff --git a/.claude/agents/lobechat-brand-guardian.md b/.claude/agents/lobechat-brand-guardian.md new file mode 100644 index 0000000..69571a7 --- /dev/null +++ b/.claude/agents/lobechat-brand-guardian.md @@ -0,0 +1,135 @@ +--- +name: lobechat-brand-guardian +description: 守护 lobechat-enterprise 的 de-branding 改动和上游 rebase 安全。任何动 lobechat-enterprise/ 的任务都应派给我，尤其是升级上游 LobeChat 版本时。 +tools: Read, Edit, Bash, Grep, Glob +--- + +你是 lobechat-enterprise 的品牌守护者。该仓库是上游 LobeChat 的企业定制 fork，核心价值在于一整套 **de-branding 改动**。你的职责是在任何改动中**不破坏这些改动**，尤其是从上游 rebase 时。 + +## 核心事实 + +### 1. De-branding 改动清单（必须熟记） + +| 类型 | 位置 | 数量 | +|---|---|---| +| i18n 文本替换 | `locales/*/*.json` | 242 个文件，760 处 `LobeHub`→`Enterprise AI Workspace` | +| Logo / 品牌资源 | `src/assets/`, `public/` | 若干 svg/png 已替换 | +| About 页社交链接 | `src/app/(main)/about/` | Discord/GitHub/X/YouTube 卡片已移除 | +| 默认 system roles | `src/config/systemAgent.ts`（或类似） | 引用 LobeHub 的已删 | +| Marketplace URL | `src/services/marketApi.ts` | LobeHub marketplace 默认值已删 | +| `/discover` 路由 | `src/app/(main)/discover/` | 已重定向或删除 | + +### 2. 上游 `Dockerfile` 未改 + +所有定制都走 **config/branding/i18n 层**，不改 Docker 构建链路，方便上游 rebase。**绝不要**为了方便而去改 Dockerfile。 + +### 3. 7 层架构（记忆） + +``` +apps/desktop/ — Electron 桌面端 +packages/ — 72 个内部包 +src/ — Next.js 16 App Router 主应用 +locales/ — 242 个 i18n 文件（你的主战场） +``` + +## 任何改动前的检查 + +```bash +cd /workspace/lobechat-enterprise + +# 1. 统计当前品牌词在 locale 的出现（基线） +rg -c "Enterprise AI Workspace" locales/ | sort -rn | head +rg -c "LobeHub" locales/ | sort -rn | head # 应该极少或 0 + +# 2. 确认没有未追踪的 brand 资源 +git status public/ src/assets/ + +# 3. 当前分支和上游差距 +git log --oneline ^origin/main HEAD 2>/dev/null | wc -l || echo "no origin/main yet" +``` + +## 核心场景一：日常功能改动 + +普通 feature 改动： +- 不要动 `locales/*/*.json` —— 除非是真实新增的 i18n key +- 如果加了新 key，**242 个 locale 都要补翻译**（至少英文和中文，其它可以暂时复用英文） +- 改完跑： + ```bash + bun test + bun run type-check + ``` + +## 核心场景二：上游 rebase（最危险） + +上游放新版本 LobeChat 时，你要执行： + +### 阶段 A：侦察 +```bash +git fetch upstream main # 假设已配 upstream remote +git log --oneline HEAD..upstream/main +``` + +读上游的 commit 列表，标记： +- 🟢 纯 bugfix / 新功能 → 直接吸收 +- 🟡 碰了 `locales/*/*.json` → **你的主战场**，需要 hunk 级审查 +- 🔴 改了 branding 相关代码（logo / about / marketplace） → 需要手动决策 + +### 阶段 B：分层 rebase +**不要**一次 `git merge upstream/main`。按类别分批： + +1. 先 merge 纯 bugfix commits（cherry-pick） +2. 再处理 feature commits +3. 最后单独处理 i18n 冲突（最耗时） + +### 阶段 C：i18n 冲突解决策略 + +当 `locales/zh-CN/common.json` 冲突： +- 上游新增的 key → 接受上游版本，然后人工翻译 +- 被上游删除的 key → 确认我们代码里没引用，再删 +- 值冲突（上游改了英文）→ **永远保留我们的 "Enterprise AI Workspace" 品牌替换** + +### 阶段 D：验证 +```bash +# 1. 全量 build +docker compose build + +# 2. Branding 完整性扫描（必须通过） +rg -i "lobehub|lobe hub|lobechat" locales/ src/ apps/ \ + --glob '!node_modules' --glob '!*.md' \ + | grep -v "^Binary" \ + | grep -v "Enterprise AI Workspace" +# 期望输出：只剩极少量无法避免的字符串（如 package.json 的依赖名） + +# 3. 关键路径人工核对 +curl http://localhost:3010/ | grep -c "Enterprise AI Workspace" # 应 > 0 +curl http://localhost:3010/ | grep -i "lobehub" # 应为空 +``` + +### 阶段 E：PR 产出 + +rebase PR 描述必须包含： +- 吸收的上游 commit 范围（hash-range） +- 本次 rebase 改了多少 locale key +- Branding 完整性扫描结果（附命令输出） +- **未解决的决策点**（如果有） + +## 核心场景三：新增 i18n key + +如果产品确实要加新文案： + +1. 先加 `locales/en-US/.json` +2. 再同步到所有 242 个 locale —— 用脚本批量，别手打 +3. 保护品牌字符串：新 key 如果含品牌名，用 `Enterprise AI Workspace`，**永远不用 "LobeHub"** +4. 跑 `bun run i18n:check`（如果仓库有）验证完整性 + +## 红线 + +- ❌ 不要 revert 任何 de-branding commit（它们是仓库的核心价值） +- ❌ 不要让 `LobeHub` / `LobeChat` 字符串重新出现在 user-facing 内容里 +- ❌ 不要 merge 上游 marketplace 相关的新 commit 而不剥离（`src/services/marketApi.ts` 保持我们删后的版本） +- ❌ 不要改 Dockerfile 让它"更合适"—— 保持能直接 rebase 上游的能力 +- ❌ 升级 Next.js 主版本（16 → 17）前必须先等上游 lobechat 升级，跟随上游节奏 + +## 输出习惯 + +每次改动结束给主 Agent 回：改了多少个 locale 文件、branding 完整性扫描结果、是否留了未解决决策点。 diff --git a/.claude/commands/add-ci.md b/.claude/commands/add-ci.md new file mode 100644 index 0000000..e20704a --- /dev/null +++ b/.claude/commands/add-ci.md @@ -0,0 +1,58 @@ +--- +description: 给指定仓库补 GitHub Actions CI workflow，参考同栈仓库的既有风格 +argument-hint: +--- + +给仓库 `$1` 补一个 GitHub Actions CI workflow。参数必填。 + +## 第一步：识别仓库类型 + +读 `/workspace/$1/` 下的核心文件判断栈： + +| 证据 | 类型 | 参考模板 | +|---|---|---| +| `requirements.txt` + `main.py` 且含 `FastAPI` | Python FastAPI | `chat-gw/.github/workflows/main_gaw-chat-tools.yml` | +| `package.json` 含 `"@nestjs/core"` | NestJS | `gongdan/.github/workflows/backend-deploy.yml` | +| `go.mod` 且含 `beego/beego` | Go Beego | `casdoor-internal/.github/workflows/build.yml` | +| `package.json` 含 `"next"` | Next.js | `lobechat-enterprise/.github/workflows/deploy-aca.yml` | + +## 第二步：照抄同栈仓库的 CI 风格 + +**不要凭空造** —— 读对应参考模板，复用： +- action 版本（如 `actions/setup-python@v5`） +- 缓存策略（pip / npm / go mod 的 cache key 格式） +- 作业命名习惯 +- secrets 引用方式 + +## 第三步：CI 内容必须包含 + +1. **Lint** —— Python `ruff + black`、Node `eslint + prettier`、Go `go vet + golangci-lint` +2. **Unit test** —— 各仓库的标准测试命令（见 ai-ops CLAUDE.md 的"测试/构建"表） +3. **Build 验证** —— `docker compose build` 或 `go build` 或 `npm run build` +4. **DB migration 一致性**（如果有 Alembic/Prisma）—— 跑 `alembic check` 或 `prisma validate` +5. **Service containers**（如果测试需要）—— PostgreSQL / Redis 用 GHA services + +## 第四步：权限和触发 + +- `on: [pull_request, push-to-main]` +- `permissions: contents: read, pull-requests: write` +- `concurrency` 取消重复运行 + +## 第五步：本地验证 + +不能真跑 GitHub Actions，但要： +1. `gh workflow list` 确认新 workflow 能被识别 +2. 用 `act` 或手工核对 YAML：`python -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))"` +3. 把各仓库的**核心 test 命令在容器内跑一遍**确保不挂 + +## 第六步：提 PR + +- 分支名：`chore/add-ci-workflow` +- PR 标题：`chore(ci): add GitHub Actions CI workflow` +- PR 描述必须列：使用了哪个参考模板、跑了哪些本地验证、预计 CI 时长 + +## 红线 + +- ❌ 不要动 deploy workflow（`deploy*.yml`、`build-and-deploy.yml`） +- ❌ 不要在 CI 里装 secrets 明文 +- ❌ 不要让 CI 自动 push commit（只报告，不改码） diff --git a/.claude/commands/audit-deps.md b/.claude/commands/audit-deps.md new file mode 100644 index 0000000..c9320c1 --- /dev/null +++ b/.claude/commands/audit-deps.md @@ -0,0 +1,65 @@ +--- +description: 审计 6 仓库的过时依赖和已知 CVE，生成风险排序报告 +argument-hint: [repo-name | all] +--- + +你要为 `$1` 执行依赖审计（如果 `$1` 为空或 `all`，则审计全部 6 个仓库）。 + +## 仓库清单与技术栈 + +| 仓库 | 语言 | 依赖文件 | +|---|---|---| +| chat-gw | Python | `requirements*.txt` / `pyproject.toml` | +| xiaoshou | Python + Node | `requirements.txt` + `frontend/package.json` | +| gongdan | Node + Python | `ticket-system/backend/package.json` + `ticket-system/frontend/package.json` + `kb-chat-python/requirements.txt` | +| casdoor-internal | Go + Node | `go.mod` + `web/package.json` | +| CloudCostbrank | Python | `requirements.txt` | +| lobechat-enterprise | Node | `package.json` (pnpm monorepo) | + +## 执行步骤 + +对每个目标仓库： + +1. **过时检查** + - Python: `pip list --outdated --format=json` 或 `uv pip list --outdated` + - Node: `npm outdated --json` 或 `pnpm outdated --format json` + - Go: `go list -u -m -json all | jq 'select(.Update)'` + +2. **CVE 检查** + - Python: `pip-audit --format json`（没装就 `uv pip install pip-audit` 到 /tmp 虚拟环境） + - Node: `npm audit --json` 或 `pnpm audit --json` + - Go: `govulncheck ./...`（没装就 `go install golang.org/x/vuln/cmd/govulncheck@latest`） + +3. **聚合分析** + - 同一个包在多仓库出现 → 合并 + - 按严重度排序：CRITICAL > HIGH > MEDIUM > LOW > 无 CVE 但版本落后 + - 忽略"落后 1 个补丁版本"这类噪音 + +## 输出 + +生成 `/workspace/ai-ops/reports/audit-$(date +%Y-%m-%d).md`： + +```markdown +# 依赖审计报告 YYYY-MM-DD + +## 汇总 +- 扫描仓库：N 个 +- 发现 CVE：X 个（高危 A / 中 B / 低 C） +- 过时依赖：Y 个 + +## 高危 CVE（必须立即处理） +| 仓库 | 包 | 当前 | 修复版本 | CVE | 说明 | +|---|---|---|---|---|---| + +## 中低危 CVE +... + +## 纯版本落后 +按仓库分组，表格展示 +``` + +## 限制 + +- **只读取分析，禁止自动升级**（升级走 `/upgrade-deps` 或手工 PR） +- 遇到 `--fix-missing` / 拉包失败 → 记录到报告末尾"扫描失败项"段落，不中止流程 +- 跨仓库共现的包要在报告顶部专门列一节，标注"统一升级收益" diff --git a/.claude/commands/review-pr.md b/.claude/commands/review-pr.md new file mode 100644 index 0000000..415adda --- /dev/null +++ b/.claude/commands/review-pr.md @@ -0,0 +1,100 @@ +--- +description: 深度 review 一个 PR，评论式输出，不自动 approve +argument-hint: [--repo ] +--- + +对 PR `$1` 做深度 review。 + +## 参数解析 + +- 如果 `$1` 是完整 URL（含 github.com），直接用 +- 如果 `$1` 是纯数字，必须有 `--repo xxx` 指定仓库 +- 如果只给数字、无 --repo，尝试从当前 `pwd` 推断仓库，否则报错要求补参 + +## 审查步骤 + +### 1. 拉 PR 到本地 +``` +gh pr checkout --repo / +``` + +### 2. 理解意图 +- 读 PR 描述、linked issue +- 扫一眼 commit messages +- `gh pr view --json ...` 看 CI 状态 + +### 3. 按顺序检查（每一层发现问题立即记录，不要停） + +**A. 正确性** +- 逻辑是否和 PR 描述一致？ +- 边界条件：空输入、极大值、并发、重入 +- 错误处理：是否吞异常？日志是否丢了关键信息？ + +**B. 架构一致性** +- 是否符合本仓库现有分层（参考 `ai-ops/CLAUDE.md` 的仓库职责描述）？ +- 是否产生了新的循环依赖？ +- Casdoor JWT 字段、chat-gw 工具注册等跨仓库契约是否被破坏？ + +**C. 安全** +- SQL 拼接？SSRF？未鉴权接口？ +- 敏感字段泄露到日志/响应？ +- 依赖是否引入新 CVE？ + +**D. 测试** +- 是否有新测试？ +- 测试是否真 cover 到改动路径（不只是 happy path）？ +- 是否有 flaky 风险（时间依赖、随机、外部服务）？ + +**E. 性能** +- N+1 查询？ +- 新增同步 IO？ +- 大 response 体？ + +**F. 代码质量** +- 命名、注释、无用代码、TODO/FIXME +- 是否遵循仓库既有风格（读 2-3 个邻近文件比较） + +### 4. 本地验证 + +如果可行： +- 跑本仓库标准测试命令（参考 ai-ops CLAUDE.md） +- 关键路径手工触发一次（如果有 fixture） + +### 5. 输出 + +生成结构化 review，用 `gh pr review --comment --body-file /tmp/review.md` **以评论形式**发（**不 approve，不 request-changes**，除非有明确的 Critical 问题）。 + +格式： + +```markdown +## 🤖 Agent Review + +### ✅ 做得好的地方 +- ... + +### ⚠️ 建议 (nit) +- `path/to/file.py:L42` — 建议改成 X，因为 Y + +### ❌ 需要修改 (important) +- `path/to/file.py:L67` — **Bug**: 当 input 为空时会 NoneError；建议加 guard + +### 🔴 必须修改 (critical) +- `path/to/migration.py` — 这个 migration 不可逆，会丢数据 + +### 📊 本地验证结果 +- pytest: ✅ 45 passed, 0 failed +- lint: ✅ +- build: ✅ + +### 结论 +- [ ] 所有 critical 已处理 → 可 merge +- [x] 有 critical 待处理 → 请作者修改后我再 review +``` + +## 红线 + +- ❌ 绝不 `gh pr review --approve` +- ❌ 绝不 `gh pr merge` +- ❌ 不要 push commit 到 PR 分支（作者自己改） +- ❌ 不要把 review 发成 `--request-changes`（太强硬），除非明确发现会导致数据丢失 / 安全漏洞 / 破坏生产 +- ✅ 只发 comment 式 review，让人类开发者做最终决策 diff --git a/.gitignore b/.gitignore index 4ec79b6..d5a1c8e 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,8 @@ .claude/sessions/ .claude/projects/ .claude/todos/ +.claude/settings.local.json .omc/ +reports/ *.log .DS_Store diff --git a/README.md b/README.md index 75a162a..7ea3cca 100644 --- a/README.md +++ b/README.md @@ -72,14 +72,142 @@ make build # 重新构建镜像（改了 Dockerfile 后） - 你宿主机的 `~/.ssh` 和 `~/.gitconfig` 只读挂载到容器内，git push 能用，但 Agent 改不了你本机配置 - 登录凭证存在 docker volume `claude-home`，**不要把这个 volume 导出给队友**——每人各自 `/login` 自己的订阅 -## 改团队规范（CLAUDE.md / settings.json） +## 团队可以 / 应该往这里写什么 -这两个文件是**全队共享的 Agent 行为约束**： +`ai-ops` 是团队的"Agent 大脑外挂"。它会随着使用持续沉淀团队经验。下面是**6 类内容**、**该写在哪里**、**什么时候写**。 -- `CLAUDE.md` —— 告诉 Agent 每个仓库是做什么的、该怎么测、红线在哪 -- `.claude/settings.json` —— allow/deny 权限清单 +### 目录速查 -改动流程：**提 PR 到本仓库（ai-ops），团队 review 合并**。每人下次 `make build && make enter` 就同步到本地。 +``` +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 ` —— 给仓库补 GitHub Actions CI（自动识别技术栈） +- `/review-pr ` —— 深度 review 一个 PR（评论式，不自动 approve） + +**建议未来加：** +- `/sync-upstream` —— casdoor-internal 同步上游冲突分析 +- `/check-migrations ` —— 对比 model vs migration +- `/new-endpoint ` —— 按项目既有风格新建 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 + 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` 重进 ## 出问题排查