# 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**。