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 已在 Gitea 建立；仓库仍位于 Pine 下，迁移待完成（需 Gitea 管理员 API token 执行转让/创建；本机无该 token，token 在部署服务器 /app/working.secret/gitea_token）。 约定：仓库名保留，组织路径改为 OPC-Hub/<同名>.git；主远端 origin，副远端 infoepoch_lan。

项目	仓库名	现状远端（Pine）	OPC-Hub 目标	主机
agent-desktop	PineAgents	git@infoepoch:Pine/PineAgents.git git@infoepoch_lan:Pine/PineAgents.git	OPC-Hub/PineAgents.git	infoepoch(生产) + infoepoch_lan(LAN)
server-core	PineAgentsServer	git@infoepoch:Pine/PineAgentsServer.git	OPC-Hub/PineAgentsServer.git	同上
web-official	PineAgentsWeb	git@infoepoch_lan:Pine/PineAgentsWeb.git	OPC-Hub/PineAgentsWeb.git	同上
park-desktop	dpm_rust	http://code.infoepoch.cn/Pine/dpm_rust.git	OPC-Hub/dpm_rust.git	同上
compute-engine	compute-engine	git@infoepoch:Pine/compute-engine.git	OPC-Hub/compute-engine.git	同上
training	training	git@infoepoch:Pine/training.git	OPC-Hub/training.git	同上
admin-portal	admin-portal	git@infoepoch:Pine/admin-portal.git	OPC-Hub/admin-portal.git	同上

其它（reference/ 下 PinePixel、cloud-opc 参考源；bark-notify 临时）不在迁移范围。 迁移完成后：各克隆本地远端改为 OPC-Hub/<同名>.git（origin + infoepoch_lan），并回写本表状态与 ports/*.md。