# 云超服 / 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`）。

## 常用操作

```bash
# 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` 为准；本文件仅描述整体结构与跨项目约定。