gongzhiyong
e5e5f939ee
Agents (10 new, total 13): - python-fastapi-expert — chat-gw / xiaoshou / CloudCost / kb-chat-python - nestjs-expert — gongdan backend - react-frontend-expert — xiaoshou/gongdan/casdoor web - mcp-tools-architect — chat-gw tool registry + auth pipeline - celery-worker-expert — CloudCost async tasks + beat - security-auditor — OWASP + secrets + auth (read-only) - test-engineer — coverage + flaky + e2e - ci-cd-engineer — 6 repos GitHub Actions - azure-aca-expert — ACA + Bicep + Key Vault - docs-writer — README / API / runbook Team orchestration commands: - /team-feature — brainstorm → architect → split → parallel impl → QA - /team-bug-fix — triage → RCA → fix → regression test → review - /team-refactor — scope → test-first → batch → verify Infrastructure: - Dockerfile: add Azure CLI (native apt package) - docker-compose.yml: mount ~/.azure and ~/.config/gh (read-only) - scripts/enter.sh: banner showing agents/commands on start - scripts/install-plugins.sh: helper to install superpowers/OMC/agent-browser Permissions (.claude/settings.json): - Full read access: az, gh, kubectl, psql SELECT, redis GET/KEYS/INFO - Controlled write: gh pr create/comment, git push origin (not main) - Hard deny: az */update|create|delete, gh pr merge, git push --force, alembic downgrade, kubectl apply/delete, sudo, rm -rf / Docs: - CLAUDE.md: new 'Agent 团队' + '权限模型' sections - README.md: full agent roster + permission summary Note: Dockerfile changed — run 'docker compose build' to install Azure CLI
141 lines
8.1 KiB
Markdown
141 lines
8.1 KiB
Markdown
# 6-Repo Enterprise Matrix — Agent Operating Guide
|
||
|
||
你是这个企业级 SaaS 矩阵的维护者。工作目录 `/workspace` 挂载了 6 个协同工作的仓库。
|
||
|
||
## 仓库清单与职责
|
||
|
||
| 目录 | 角色 | 栈 | 端口 | 测试/构建 |
|
||
|---|---|---|---|---|
|
||
| `chat-gw/` | MCP 工具网关（权限 + 审计 + 路由） | Python 3.12 / FastAPI / asyncpg / Redis | 8000 | `pytest`；`docker compose up --build -d` |
|
||
| `xiaoshou/` | B2B 销售管理（客户 / 订单 / 账单） | FastAPI + React 18 / AntD 5 / Vite 5 | 后端 8000 / 前端 5173 | `pytest` + `npm run build`；`alembic upgrade head` |
|
||
| `gongdan/` | 工单系统 + KB 聊天 | NestJS + React + Python FastAPI | 后端 3000 / KB 8001 / 前端 5173 | `npm test`；`prisma migrate dev`；`pytest kb-chat-python` |
|
||
| `casdoor-internal/` | IAM（Casdoor fork） | Go 1.25 / Beego / xorm / PostgreSQL | 8000 | `make ut`；`make fmt vet`；`make run` |
|
||
| `CloudCostbrank/` | 多云成本聚合 | Python FastAPI + Celery + SQLAlchemy 2.0 | 8000 | `pytest`；`alembic upgrade head`；`docker compose up` |
|
||
| `lobechat-enterprise/` | 企业版聊天前端 | Next.js 16 + pgvector + Drizzle | 3010 | `bun test`；`docker compose build`；pnpm monorepo |
|
||
|
||
## 系统拓扑
|
||
|
||
```
|
||
┌──── 用户浏览器 ────┐
|
||
│ │
|
||
▼ ▼
|
||
[lobechat-enterprise] [xiaoshou / gongdan 前端]
|
||
│ │
|
||
│ ◄── JWT via Casdoor ──►
|
||
▼ ▼
|
||
[chat-gw MCP] ◄──► [xiaoshou API] [gongdan API] [CloudCostbrank API]
|
||
│ ▲
|
||
└── 统一身份 ────► [casdoor-internal]
|
||
```
|
||
|
||
## 工作原则
|
||
|
||
1. **改动前先读当前仓库的 README / Makefile / package.json**，遵循本仓库既有的命名、lint、测试约定；各仓库风格不统一，不要跨仓库硬套。
|
||
2. **跨仓库改动要成套提 PR**：例如改 Casdoor 的 role claim 字段，必须同步更新 chat-gw、xiaoshou、gongdan、lobechat 的 JWT 解析代码，并在 PR 描述里互相链接。
|
||
3. **验证闭环前不得声称完成**：改了 Python → `pytest`；改了 Go → `make ut`；改了前端 → `npm run build`；改了 SQL 模型 → 跑 `alembic revision --autogenerate` 确认 diff。
|
||
4. **提 PR 而非直推 main**：使用 `gh pr create`，描述必须含 "What / Why / Test"。
|
||
5. **数据库迁移**：xiaoshou 当前有"pending migrations"遗留问题，任何 model 改动都要显式 `alembic revision` 并检查生成的文件。
|
||
|
||
## 硬红线（禁止）
|
||
|
||
- ❌ 修改 `.env` / `secrets/**` / `conf/app.conf`（casdoor-internal 已 `skip-worktree`）
|
||
- ❌ 直接 push 到 main / master，force push 任何分支
|
||
- ❌ 跑 `docker system prune`、`rm -rf /`、`terraform destroy`、`kubectl delete`
|
||
- ❌ 读取或打印任何包含 `TOKEN` / `SECRET` / `PASSWORD` / `AZURE_STORAGE_CONNECTION_STRING` 的值
|
||
- ❌ 触碰 lobechat-enterprise 的 242 个 i18n 文件里的 "Enterprise AI Workspace" 品牌字符串（这是 de-brand 改动，升级上游时必须保留）
|
||
- ❌ 对 casdoor-internal 的 upstream merge 留下未标注的冲突决策
|
||
|
||
## CI/CD 现状（每个仓库自带 workflow）
|
||
|
||
- `chat-gw/.github/workflows/main_gaw-chat-tools.yml` — Azure 部署
|
||
- `xiaoshou/.github/workflows/{ci,deploy,frontend-deploy}.yml` — CI + 前后端部署
|
||
- `gongdan/.github/workflows/{backend-deploy,post-deploy-smoke,azure-static-web-apps-*}.yml`
|
||
- `casdoor-internal/.github/workflows/{build,build-and-deploy,sync}.yml` — 含上游同步
|
||
- `CloudCostbrank/` — **缺 CI，需补齐（优先级 P1）**
|
||
- `lobechat-enterprise/.github/workflows/deploy-aca.yml` — 仅部署，**缺 CI（优先级 P1）**
|
||
|
||
任何会改变 lint / test 行为的 PR，都要先本地跑一遍对应 workflow 的核心命令。
|
||
|
||
## 常用任务入口
|
||
|
||
- 跨仓库搜索：`rg -t py '<pattern>' chat-gw xiaoshou CloudCostbrank`
|
||
- 依赖审计：`cd <repo> && npm audit` / `pip list --outdated` / `go list -u -m all`
|
||
- 启动真实环境验证：`cd <repo> && docker compose up -d`，完事 `docker compose down -v`
|
||
- 提交前自我审查：调用 `code-reviewer` 子 agent，不要自评自批
|
||
|
||
## 失败处理
|
||
|
||
- CI 红：读 `gh run view <id> --log-failed`，定位到文件再动手，不要猜
|
||
- Casdoor upstream merge 冲突：先 `git log --oneline origin/upstream-main ^HEAD` 看上游新增，按 `sync.yml` 的策略逐个 hunk 决策
|
||
- 测试 flake：不要直接 `@pytest.mark.skip`，先 rerun 3 次确认是否真 flake
|
||
|
||
## Agent 团队（13 个专家 + 3 个 team 编排 + 7 个快速命令）
|
||
|
||
本工作站启动时自动加载 `.claude/agents/` 下全部 subagent。你（主 Agent）遇到对应领域的任务**必须派遣给专家**，而不是自己硬干。
|
||
|
||
### 专家派遣矩阵
|
||
|
||
| 任务特征 | 派遣给 |
|
||
|---|---|
|
||
| Python FastAPI 后端改动（chat-gw / xiaoshou / CloudCost / kb-chat-python） | `python-fastapi-expert` |
|
||
| NestJS 后端（gongdan backend） | `nestjs-expert` |
|
||
| React 前端（xiaoshou / gongdan / casdoor-internal 的 web/） | `react-frontend-expert` |
|
||
| Next.js 前端（lobechat-enterprise） | `lobechat-brand-guardian` |
|
||
| chat-gw MCP 工具注册 / 鉴权流水线 | `mcp-tools-architect` |
|
||
| CloudCost Celery 任务 / beat schedule | `celery-worker-expert` |
|
||
| casdoor-internal Go 代码 / upstream 同步 | `casdoor-specialist` |
|
||
| 数据库 migration（Alembic / Prisma / Drizzle） | `migration-reviewer`（审查）、对应仓库专家（实现） |
|
||
| 安全审查（认证 / 授权 / 密钥 / 输入验证） | `security-auditor` |
|
||
| 测试补覆盖 / 治 flaky | `test-engineer` |
|
||
| GitHub Actions workflow | `ci-cd-engineer` |
|
||
| Azure Container Apps 部署 / Bicep | `azure-aca-expert` |
|
||
| README / API doc / PR 描述 / runbook | `docs-writer` |
|
||
|
||
### Team 编排命令
|
||
|
||
不确定该调哪个专家，或任务跨多个领域时，用 team 命令自动编排：
|
||
|
||
| 命令 | 适用场景 | 流水线 |
|
||
|---|---|---|
|
||
| `/team-feature <desc>` | 新功能开发（可能跨仓库） | brainstorm → architect → split → parallel impl → test → docs → review |
|
||
| `/team-bug-fix <desc-or-url>` | bug 修复 | triage → reproduce → RCA → fix → regression test → review → hotfix eval |
|
||
| `/team-refactor <target>` | 大规模重构 | scope → test-first → batch → parallel refactor → verify → rollback plan |
|
||
|
||
### 外部 skills（在容器内 `/plugin install` 后可用）
|
||
|
||
| Skill | 作用 |
|
||
|---|---|
|
||
| `superpowers:brainstorming` | Phase 1 需求澄清 |
|
||
| `superpowers:writing-plans` | 生成实施计划 |
|
||
| `superpowers:subagent-driven-development` | 并行驱动子 agent |
|
||
| `superpowers:verification-before-completion` | 交付前验证 |
|
||
| `oh-my-claudecode:team` | CLI 多 agent 协作 |
|
||
| `oh-my-claudecode:ultrawork` | 高并发执行引擎 |
|
||
| `oh-my-claudecode:ralph` | 循环直到完成 |
|
||
| `oh-my-claudecode:omc-teams` | CLI-team 运行时（Claude/Codex/Gemini worker） |
|
||
| `agent-browser` | 浏览器自动化 skill |
|
||
|
||
首次安装：进入容器后运行 `/plugin install superpowers`、`/plugin install agent-browser`，或跑 `./scripts/install-plugins.sh`（在容器外）。
|
||
|
||
## 权限模型（简要）
|
||
|
||
`.claude/settings.json` 定义了两类规则：
|
||
|
||
**全读取，受控写入：**
|
||
- ✅ `gh` 全部只读（view / list / diff）+ 受控写（pr create / comment / checkout）
|
||
- ✅ `az` 全部只读（show / list / get-access-token）+ 拒绝所有 create/update/delete
|
||
- ✅ `kubectl` 只读（get / describe / logs）+ 拒绝 apply/delete/patch
|
||
- ✅ `psql` 只读 SELECT，拒绝 UPDATE/DELETE/DROP/TRUNCATE
|
||
- ✅ `redis-cli` 只读 GET/KEYS/INFO，拒绝 FLUSH/CONFIG/SHUTDOWN
|
||
- ✅ 各语言测试/lint 命令全开
|
||
|
||
**硬拦截：**
|
||
- ❌ 任何 Azure 资源的 create/update/delete/restart
|
||
- ❌ `git push --force`、`git commit --amend`、`git reset --hard`
|
||
- ❌ `gh pr merge`、`gh pr review --approve`
|
||
- ❌ `alembic downgrade`、生产 DB 的 DROP/UPDATE
|
||
- ❌ `rm -rf /*`、`sudo`、`chmod 777`
|
||
- ❌ 读取 `.env` / `secrets/**` / casdoor `app.conf`
|
||
|
||
这意味着所有 agent（包括 azure-aca-expert / security-auditor）可以**自由观察**生产资源、查任何日志 / 指标 / 密钥库 metadata，但**改动必须由人类 approve**。
|