opc-backup/.claude/memory/MASTER.md

总约束（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）保留。