opc-backup/CLAUDE.md

云超服 / PineAgents — 项目总览（Monorepo 根）

本目录是 PineAgents / OPC 超级个体综合服务平台（云南省 OPC 超级个体综合服务平台，云超服）的工作区根目录。整体由多个独立 git 仓库组成（非单一 monorepo），请勿在根目录 git init 或将子项目并入根仓库。

目录布局

目录	说明	Git 远端
PineAgentsServer/	总后端。FastAPI 演示后端（认证转发、登录注册等），环境由 uv 管理。	origin → git@infoepoch:Pine/PineAgentsServer.git
PineAgents/	核心部分。前端 / 桌面端 / CLI 端。含 console/（PC 后台 UI 基调来源）。	infoepoch_lan → git@infoepoch_lan:Pine/PineAgents.git
PineAgentsWeb/	网页展示端口。Vite + React 静态站（SPA），源自 PineAgents/website 迁移。项目身份 pineagents-web。	origin → git@infoepoch:Pine/PineAgentsWeb.git + infoepoch_lan → git@infoepoch_lan:Pine/PineAgentsWeb.git
reference/	项目参考文件。cloud-opc/ = OPC 平台前端骨架；PinePixel/ = 园区像素可视化。	—
docs/	整体设计与相关文档（架构、系统方案、设计规范）。	—

关键约定

• UI 风格基调：凡涉及前端设计的，必须不偏离 PineAgents/console/ 的主基调（见其 src/styles、主题与组件体系）。不得另起一套视觉语言。
• 文档位置：整体的架构、系统设计、设计规范等文档一律放在 docs/。
• 参考源：园区像素可视化参考 reference/PinePixel/；OPC 平台前端骨架参考 reference/cloud-opc/。
• Git 远端规范：远端遵循 git@<host>:Pine/<ProjectName>.git。存在两个主机：infoepoch（生产 Gitea，47.108.226.213）与 infoepoch_lan（局域网 Gitea，192.168.1.3）。新项目默认同时注册这两个远端，主远端命名 origin。
• 后端在 PineAgentsServer/；PineAgents/ 为主后端认证转发的来源（src/pineagents/app/routers/auth.py 将 /api/auth/* 转发到 PineAgentsServer，PINEAGENTS_DEMO_BASE_URL 默认 http://127.0.0.1:8090）。

常用操作

# PineAgentsServer（uv 管理）
cd PineAgentsServer && uv sync && uv run uvicorn app.main:app --port 8090 --reload

# PineAgents console（yarn）
cd PineAgents/console && yarn dev

# PineAgentsWeb（pnpm / npm）
cd PineAgentsWeb && pnpm install && pnpm run dev

各子项目内部文档以各自的 README.md / CLAUDE.md 为准；本文件仅描述整体结构与跨项目约定。