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（port 四层+阶段0-1）
agent-desktop	agent-desktop	Pine/agent-desktop	OPC-Hub/agent-desktop	✅ f44b12f（并 TaskSquare）
web-official	web-official	Pine/web-official	OPC-Hub/web-official	✅ d33b25f
park-desktop	park-desktop	Pine/park-desktop	OPC-Hub/park-desktop	✅ 63dc6b8（并 admin UI+vision_yolo）
compute-engine	compute-engine	Pine/compute-engine	OPC-Hub/compute-engine	✅ 6880ae7
training	training	Pine/training	OPC-Hub/training	✅ 3c9a13a
admin-portal	admin-portal	（无，新建）	OPC-Hub/admin-portal	✅ 258bccf（新建+推送）

其它（reference/ 下 PinePixel、cloud-opc；bark-notify 临时）不在迁移范围。 全部 7 个 code/ 仓库已迁至 OPC-Hub；各本地克隆已改指 OPC-Hub/<同名>.git（origin=infoepoch + infoepoch_lan），工作树 clean。所有 Pine/<同名> 旧仓库与旧名（PineAgents/PineAgentsServer/PineAgentsWeb/DPM/opc 等）作备份保留，不再作为日常使用。 Gitea 管理 token 存于仓库外自动记忆（勿入库）：gitea-opchub-token。

11. 仓库迁移执行记录（2026-08-24 全部完成）

• server-core：port 阶段0-1 至四层仓库 → 推 Pine/server-core → transfer OPC-Hub（b90539a）→ 本地全新克隆。
• agent-desktop：并 TaskSquare 改（4 文件）→ 推 Pine/agent-desktop(f44b12f) → transfer。
• park-desktop：并 admin 新 UI+vision_yolo（6 文件）→ 推 Pine/park-desktop(63dc6b8) → transfer。
• compute-engine / training / web-official：transfer（web-official 采纳新仓库部署文档版）。
• admin-portal：新建 OPC-Hub/admin-portal（POST /orgs/OPC-Hub/repos）+ 推送本地。
• 所有 Pine/* 备份保留；本地 7 clone 均改指 OPC-Hub/<同名>.git。