# Agent 协作说明（Codex / Cloud / Cursor / Claude / 其它 AI 工具通用）

本文件供所有在仓库内工作的 AI 编码助手阅读。仓库级开发、测试、发布规范以 [ENGINEERING_WORKFLOW_RULES.md](ENGINEERING_WORKFLOW_RULES.md) 为准；生产发布规范以 [PRODUCTION_RELEASE_RULES.md](PRODUCTION_RELEASE_RULES.md) 为准。

## 必读：分支与发布闸门

1. 新建分支前必须先同步远端主线，推荐执行 `bash scripts/new-branch.sh feature/xxx`。
2. 发布前必须重新检查当前分支是否落后 `origin/main`。
3. 发布来源必须是干净、可追溯的 Git commit。
4. 禁止从脏工作区、detached HEAD、落后主线的分支发布。
5. 发布前必须执行：

```bash
bash scripts/check-release-ready.sh
```

## 仓库边界

- `memind_adm` 可以独立开发，但共享用户、权限、策略、技能、计费体系必须继续复用 `Memind` 主实现。
- 发版须 Git commit，禁止本机直 `rsync` 到 `103/105`。
- 共享用户、计费、空间额度、策略同步相关改动必须保留业务验收记录。

## 必读：本仓库是唯一合法的管理后台 UI（5174）

**所有平台管理后台的前端功能只能在本仓库（memind_adm）开发，本地端口 5174，生产 gadm。禁止在 Memind 仓库的 `ops/`（约 3002）新增任何管理页面、导航或 API 客户端。**

| 组件 | 端口 | 职责 |
|------|------|------|
| **memind_adm 前端（本仓库 `src/`）** | **5174** | 管理后台 UI：用户、计费、图片额度、策略、模型中心等 |
| memind_adm API（`server/`） | 8085 | 挂载 `/admin-api/*`，复用 Memind 共享模块 |
| Memind `ops/` | ~3002 | Plaza 运营 + 遗留 admin；**只读维护，禁止扩展** |
| Memind 后端 | 8081 / 8082 | 业务逻辑与 Portal；UI 不在此仓库 |

新增管理功能时：在本仓库添加 `src/admin/pages/*`、更新 `AdminNav.tsx` 与 `App.tsx`；若需新 API，在 `server/app.mjs` 挂载并复用 Memind 模块。Memind 侧仅实现共享业务，不在 `ops/` 做 UI。