Pine
82 lines
5.0 KiB
Markdown
82 lines
5.0 KiB
Markdown
# 总约束（MASTER）
|
||
|
||
> 全局、跨项目、不可违背。冲突优先级：**项目内 AGENTS.md/README.md 的具体规则 > 本总约束 > 本项目 CLAUDE.md 概述**。
|
||
> 每次开发改动前先读本文件（经 /memory）。
|
||
|
||
## 1. 目录分桶（不可混放）
|
||
|
||
- `code/` 一切可运行代码 / 代码仓库
|
||
- `design/` 项目设计与架构文档
|
||
- `materials/` 课程内容、政策研究、园区数据等非代码资料
|
||
- `reference/` 参考源（独立仓库，根忽略）
|
||
|
||
## 2. 仓库纪律
|
||
|
||
- 主仓库（`opc`）只管 `design/ materials/` 与根文档、全局规范；**不跟踪各 `code/*` 子项目代码，保留文件夹**。
|
||
- `code/*` 各为独立仓库（组织 Pine）；`reference/*` 独立仓库。
|
||
- 任一子项目改动，在**各自仓库**内分批提交，不得混入根仓库或其它仓库。
|
||
|
||
## 3. git 提交约定
|
||
|
||
- 用**中文**、按**功能分批**提交，避免多文件一次提交。
|
||
- 提交信息不允许包含 `Co-Authored-By: Claude <noreply@anthropic.com>`。
|
||
- 先询问用户验证，通过后再提交。
|
||
- 上线/部署相关提交由用户手动执行（`backend-deploy-by-user`）。
|
||
|
||
## 4. 进程管理铁律
|
||
|
||
- **AI 绝对禁止启动/重启/停止任何前后端服务进程**（server-core :8090、park-desktop :10085、s2s :8765、vite、Tauri 等）。
|
||
- 需要时先通知用户，由用户亲自操作。AI 只做改代码、编译检查、接口测试（仅在服务已运行且不重启前提下）。
|
||
|
||
## 5. 凭据卫生
|
||
|
||
- `*.env*`、`*.local` 含密钥/凭据，默认 gitignore，勿提交。
|
||
- `.claude/settings.local.json` 为本地配置，勿提交。
|
||
|
||
## 6. 记忆纪律（本 skill 强制）
|
||
|
||
- 每次开发/改动**前**调用 `/memory` 载入记忆。
|
||
- 每次改动**后**：校验 → 提交 → 更新 `ports/<port>.md` 与 `CURRENT.md`。
|
||
- 记忆必须用 `path:line` 锚点，可直接定位。
|
||
- 计划变化同步 `LONG-TERM / SHORT-TERM`；规则变化同步本文件或对应 `projects/<port>.md`。
|
||
|
||
## 7. 后端架构标准（server-core）
|
||
|
||
- FastAPI **四层架构**（接口→业务→领域→基础设施），禁止反向依赖。
|
||
- server-core 与算力调度经**内部 IP/loopback** 交互；对外算力统一走服务端 `/api/v1`。
|
||
|
||
## 8. UI 基调
|
||
|
||
- 前端设计不偏离 `code/agent-desktop/console/` 主基调；admin-portal 用 shadcn/ui（遵循 `design/installation.md`）。
|
||
- 培训网站/小程序遵循自身「暗色粒子品牌语言」，但整体以 console 为基准。
|
||
|
||
## 9. 待办 / 已知落差（重要，随时更新）
|
||
|
||
- server-core 现状为「身份/门户演示」内核：无 `dispatcher.py`、无 `app/training` 子应用（设计与实现不符，待阶段2重构入口）。
|
||
- 8 个 RBAC 既有失败测试（权限种子问题）**非本次引入**，待排查。
|
||
- 若干 `/admin/*`（课程/活动/报名/测评/园区）与算力管理端点属阶段2-4，尚未实现。
|
||
|
||
## 10. 项目仓库映射表（迁移 → OPC-Hub 组织）
|
||
|
||
> 组织 `OPC-Hub` 已建；迁移**按规范名仓库**（server-core/agent-desktop/…，即新名 repo，含四层重构）→ `OPC-Hub/<同名>.git`。
|
||
> 原则：① 先把各项目最新代码（含我在旧仓库的改动）**合并/port 进规范名仓库**再转让；② **保留 Pine 旧仓库作备份**；③ 迁后全线用 OPC-Hub，不再碰 Pine。
|
||
> 主远端 `origin`=infoepoch，副远端 `infoepoch_lan`。`Pine/*` 旧名仓库（PineAgents/PineAgentsServer/PineAgentsWeb/DPM/opc）作备份保留，不迁移。
|
||
|
||
| 项目（规范名） | 被迁仓库 | 来源（Pine） | 目标（OPC-Hub） | 状态 |
|
||
|------|------|------|------|------|
|
||
| server-core | server-core | `Pine/server-core` | `OPC-Hub/server-core` | ✅ 已迁 `b90539a`（旧 `Pine/*` 备份保留） |
|
||
| agent-desktop | agent-desktop | `Pine/agent-desktop` | `OPC-Hub/agent-desktop` | ⏳ 需先合并 TaskSquare |
|
||
| web-official | web-official | `Pine/web-official` | `OPC-Hub/web-official` | ⏳ |
|
||
| park-desktop | park-desktop | `Pine/park-desktop` | `OPC-Hub/park-desktop` | ⏳（本地 origin dpm_rust 缺失） |
|
||
| compute-engine | compute-engine | `Pine/compute-engine` | `OPC-Hub/compute-engine` | ⏳（本地即新名） |
|
||
| training | training | `Pine/training` | `OPC-Hub/training` | ⏳（本地即新名） |
|
||
| admin-portal | admin-portal | `Pine/admin-portal`（待建） | `OPC-Hub/admin-portal` | ⏳（需新建+推送） |
|
||
|
||
> 其它（reference/ 下 PinePixel、cloud-opc；bark-notify 临时）**不在**迁移范围。
|
||
> 迁移完成一个即回写本表状态与 `ports/*.md`、`CURRENT.md`；本地克隆远端改指 `OPC-Hub/<同名>.git`（origin + infoepoch_lan）。
|
||
> Gitea 管理 token 存于仓库外自动记忆（勿入库）：[[gitea-opchub-token]]。
|
||
|
||
## 11. 仓库迁移执行记录
|
||
|
||
- **server-core**（试点）：port 阶段0-1 至四层仓库 → 推 `Pine/server-core`(`b90539a`) → `POST /repos/Pine/server-core/transfer`(new_owner=OPC-Hub) 成功 → 本地 `code/server-core` 已改为 `OPC-Hub/server-core` 全新克隆。备份：`Pine/server-core`（及旧 `Pine/PineAgentsServer`）保留。
|