opc-backup/CLAUDE.md

# 云超服 / PineAgents — 项目总览（工作区根目录）

本目录是 **云南省 OPC 超级个体综合服务平台（云超服，Cloud 超服）** 与相关配套业务（园区大屏展播、OPC 培训体系、资料搜集）的工作区根目录。

> **整体不是单一 monorepo**，而是「多个独立 git 仓库 + 若干根仓库跟踪内容」的组合。请勿在根目录 `git init`，也不要把独立仓库并入根仓库。
>
> **目录规范（分桶）**：本项目严格按「代码 / 设计文档 / 资料内容」三桶分层，**不得把代码与设计、资料混放在一起**：
> - `code/` → 一切可运行代码 / 代码仓库
> - `design/` → 项目设计与架构文档
> - `materials/` → 课程内容、政策研究、园区数据等非代码资料

---

## 一、业务背景与合作关系

- **甲方 / 作者**：云南派音人工智能科技有限公司（AI 开发专家团队），入驻 **昆明市大学生创业园**。
- **园区运营方**：昆明市大学生创业园是**唯一一个政府直属的创业园区**（直属昆明市人社局），由**云南浙青创投资有限公司**运营。
- **合作**：派音与浙青创联合开发了**云南省超级个体服务平台（云超服）**，并合作开展一系列 OPC 培训、运营、扶持项目。
- **获客逻辑**：以园区为基础开展公益课 / 交流沙龙引流 → 最终导向双方合作的线上线下课程（见 `materials/培训计划/`）。
- 合作背景详见 `materials/培训计划/课程体系0.1/项目背景.md` 与 `商业模式审查与完善.md`。

---

## 二、目录布局

### 顶层分桶

| 桶 | 说明 | 跟踪方式 |
|----|------|----------|
| `code/` | **所有代码 / 代码仓库**（见下） | 混合（部分根仓库跟踪，部分独立仓库） |
| `design/` | **项目设计与架构文档**（见下） | 根仓库 |
| `materials/` | **资料 / 课程内容 / 政策研究 / 园区数据** | 根仓库（园区数据资料已忽略） |
| `reference/` | 参考源（`PinePixel/` 园区像素可视化、`cloud-opc/` OPC 前端骨架） | 独立仓库（含 .git，根仓库忽略） |
| `CLAUDE.md` / `README.md` / `.gitignore` / `.claude/` | 根级文档与配置 | 根仓库 |

### `code/` — 代码仓库

| 子目录 | 说明 | Git |
|--------|------|-----|
| `code/agent-desktop/` | **智能体桌面应用**（原 PineAgents）：Agent OS + console + Tauri 壳。 | 独立仓库（忽略） |
| `code/server-core/` | **核心服务端**（原 PineAgentsServer）：身份/平台 API + 培训子应用（`app/training`），`dispatcher.py` 统一对外 `opc.pinesound.cn`。 | 独立仓库（忽略） |
| `code/compute-engine/` | **算力引擎微服务**（new-api，原 `reference/new-api`）：OpenAI 兼容 `/v1` 模型中继 + 额度/令牌/流水；**仅服务，管理/页面自研**。 | 根仓库 |
| `code/web-official/` | **官网展示端**（原 PineAgentsWeb）：Vite + React SPA。 | 独立仓库（忽略） |
| `code/park-desktop/` | **园区大屏桌面应用**（原 dpm）：Tauri + React 大屏 + FastAPI 后端，多园区通用。 | 独立仓库（忽略） |
| `code/training/` | **培训前端**（原 opc-training，后端已并入 server-core）：`miniprogram/` 小程序、`website/` 业务 Web。 | 根仓库 |
| `code/bark-notify/` | Bark 推送工具（**临时测试，非项目**，勿纳入）。 | 根仓库 |

### `design/` — 项目设计与架构文档

| 子目录 | 说明 |
|--------|------|
| `design/云超服平台/` | 云超服平台设计文档（含 `DESIGN.md` 顶层总览、系统方案、身份体系、全量方案、架构推演、Creative-Cards、`任务类别.json`）。 |
| `design/dpm/` | DPM 大屏系统文档（部署、更新、语音、MQTT 手册、ESP32）。 |

### `materials/` — 资料 / 内容

| 子目录 | 说明 |
|--------|------|
| `materials/培训计划/` | **OPC 培训课程体系**（课程内容、模板、知识库、配套件；代码已移至 `code/training/`）。 |
| `materials/搜集资料/` | **云南 OPC 政策与研究资料**（政策汇总、创业伙伴调研方案、网页存档）。 |
| `materials/园区数据资料/` | 园区原始数据资料（PDF / 定稿压缩包 / 表格），**已 gitignore**。 |

---

## 三、关键约定（必须遵守）

1. **UI 风格基调**：凡涉及前端设计，**必须不偏离 `code/agent-desktop/console/` 的主基调**（见其 `src/styles`、主题与组件体系）。不得另起一套视觉语言。培训网站/小程序遵循自身「暗色粒子品牌语言」（见 `materials/培训计划/课程体系0.1/知识库/`），但整体观感仍以 console 为基准。
2. **文档位置**：云超服平台架构 / 系统设计 / 设计规范文档放 `design/云超服平台/`；DPM 系统文档放 `design/dpm/`；培训课程内容放 `materials/培训计划/`；大屏/培训系统代码放 `code/`。
3. **代码与内容分离**：新增代码一律入 `code/`，新增设计文档入 `design/`，新增资料/内容入 `materials/`，**不得混放**。
4. **参考源**：园区像素可视化参考 `reference/PinePixel/`；OPC 平台前端骨架参考 `reference/cloud-opc/`。
5. **Git 远端规范**：独立仓库远端遵循 `git@<host>:Pine/<ProjectName>.git`。两个主机：`infoepoch`（生产 Gitea，47.108.226.213）与 `infoepoch_lan`（局域网 Gitea，192.168.1.3）。新项目默认同时注册，主远端命名 `origin`。
6. **进程管理铁律**：**AI 绝对禁止启动 / 重启 / 停止任何前后端服务进程**（server-core :8090、park-desktop 后端 :10085、s2s 语音 :8765、vite、Tauri 等）。需要时先通知用户，由用户亲自操作。AI 只做改代码、编译检查、接口测试（仅在服务已运行且不重启的前提下）。参见各子项目 `AGENTS.md`。
7. **凭据卫生**：`*.env*`、`*.local` 含密钥 / MQTT 凭据，默认加入 `.gitignore`，勿提交。DPM 的 `backend/.env` 与根 `.env.local` 尤其要注意。
8. **工作流**：改动代码后先询问用户验证，通过后按功能分批用**中文**提交，避免多文件一次提交。
9. **主项目 / 子项目约束**（多仓库结构）：
   - **主项目 = 根仓库（`opc`）**：负责 `design/`、`materials/`、根文档与全局规范；**不跟踪各 code 子项目的代码，但保留其文件夹**——`code/*` 各为独立仓库（组织 Pine），被根仓库忽略。
   - **同步全子项目**：同步 / 部署时必须**同步所有子项目**（`agent-desktop / server-core / web-official / park-desktop / training / compute-engine`），逐个 `git pull`/`push`，不得遗漏。
   - **分别提交**：任一子项目有修改时，在**各自仓库**内分批用中文提交并推送，**不得混入根仓库或其它子项目**。
10. **server-core 架构标准**：FastAPI 采用**四层架构**（接口层→业务层→领域层，基础设施层含数据模型层），**禁止反向依赖**；server-core 与**算力调度服务**经**内部 IP / loopback** 交互，对外算力调用统一走**服务端 `/api/v1`**。工程化（`serverdata/` 数据目录、`serverrun/` 容器启动、`ops/` 运维脚本）参考 `C:\Users\Administrator\MyCode\PineSoundServer`。

---

## 四、各子项目说明与常用操作

### 1) 云超服平台（code/agent-desktop / server-core / web-official）

- **server-core** 是核心服务端（身份/平台 + 培训子应用），`dispatcher.py` 统一对外 `opc.pinesound.cn`。智能体桌面 `code/agent-desktop/src/pineagents/app/routers/auth.py` 将 `/api/auth/*` 转发到 server-core（`PINEAGENTS_DEMO_BASE_URL` 默认 `http://127.0.0.1:8090`）。
- 登录身份：多身份 / 多端口账号模型（OPC 端、运营管理端、政务端、甲方企业端、服务商端、创业载体端），见 `design/云超服平台/身份体系与端口权限设计方案.md`。

```bash
# server-core 核心服务端（uv 管理，统一入口 dispatcher）
cd code/server-core && uv sync && uv run uvicorn dispatcher:app --port 8090 --reload

# agent-desktop console（yarn）
cd code/agent-desktop/console && yarn dev

# web-official（pnpm / npm）
cd code/web-official && pnpm install && pnpm run dev
```

#### 1.5) 算力引擎 compute-engine（new-api 微服务，`code/compute-engine/`）

OpenAI 兼容 `/v1` 模型中继 + 额度/令牌/流水。**仅服务，管理/页面全部自研**。完整说明见 `code/compute-engine/README.云超服.md`。

```bash
cd code/compute-engine
cp .env.example .env && docker compose up -d        # 方式1：Docker Compose（含 Redis + 数据库）
# 或 方式2：SQLite 单容器
# docker run -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data calciumion/new-api:latest
curl http://127.0.0.1:3000/api/status               # 验证
```

### 2) 园区大屏系统（`code/park-desktop/`，独立仓库）

**数字标牌 / 园区展播大屏控制**，服务昆明市大学生创业园：数据大屏、数字孪生 3D、AI 助手、语音助手、媒体轮播、企业展示墙，浏览器后台可远程控制。

- **架构**：数据走 REST（FastAPI `:10085`），控制走 **MQTT（EMQX）**，SSE `/api/events` 作回退；桌面壳为 Tauri 2。
- **后端**：`code/park-desktop/backend/`（FastAPI + uv），入口 `backend/main.py` → `app/main.py`；模块 `app/routers.py`（REST）、`app/mqtt.py`、`app/sim_engine.py`（模拟引擎）、`app/storage.py`（JSON 持久化）、`app/llm.py` + `app/tools.py` + `app/rag.py`（DashScope AI）、`app/asr.py`、`app/s2s_bridge.py`（实时语音 :8765）、`app/vision_yolo.py`（手势识别）。
- **前端**：`code/park-desktop/src/`（React 19 + Vite + Tailwind + three.js + MQTT + Tauri）。路由 `/`（数据）、`/twin`、`/ai`、`/screen`、`/voice`、`/wall`；**`/admin` 是后端 Jinja 页面，非 React 路由**。
- **文档**：权威说明 `code/park-desktop/backend/README.md`；系统/运维文档见 `design/dpm/`。
- **进程规则**：见 `code/park-desktop/AGENTS.md` —— AI 禁止启动/重启后端 / vite / Tauri。

```bash
cd code/park-desktop
yarn dev            # 前端 vite
cd backend && uv sync && cp .env.example .env && uv run python main.py   # 后端 :10085
docker compose up -d --build                                            # Docker（后端 + EMQX）
```

### 3) OPC 培训课程体系（`materials/培训计划/` 内容 + `code/training/` 前端 + server-core 培训子应用）

课程产品为「诊断 + 陪跑 + OPC 体系设计」三件套，线上标准服务（¥499–1299）与线下深度服务（¥1980–3980）两个独立付费产品。权威产品规格见 `materials/培训计划/课程体系0.1/课程产品体系.md`（三阶标准服务体系旧版文件已标注「已纠正」，以 0.1 为准）。

- **代码**：`code/training/`（`miniprogram/` 小程序、`website/` 业务 Web）；**后端已并入 `code/server-core/app/training/`**（FastAPI 子应用，`/api/*`，独立 `data/opc.db`），由 server-core `dispatcher.py` 统一对外 `opc.pinesound.cn`。见 `code/training/README.md`、`code/server-core/README.training.md`。
- **内容**（`materials/培训计划/课程体系0.1/`）：`核心模板/`（T01–06）、`交付SOP/`（S01–03）、`课程设计/`（01–04）、`运营工具/`、`宣传与运营/`、`知识库/`、`自我认知工具/`、`OPC创业测评/`。
- **小程序↔网页同步约束**：C 端任一功能在网页改动后必须同步到小程序（共用 OPC 测评/政策/报名等模块），见 `materials/培训计划/课程体系0.1/小程序同步约束.md`。
- 顶层 `materials/培训计划/配套件/` 是另一套并行的课程配套模板包（作业、Prompt、政策手册、分班定制、结业四件套、直播/工作坊大纲），以 `00_索引与使用说明.md` 为入口。

```bash
# 小程序
cd code/training/miniprogram && yarn dev:weapp
# 网站
cd code/training/website && pnpm dev
# 培训后端（已并入 server-core，/api/* 由 dispatcher 提供）
cd code/server-core && uv run uvicorn dispatcher:app --port 8090 --reload
```

### 4) 云南 OPC 资料搜集（`materials/搜集资料/`）

- `政策汇总.md` — 云南 OPC 政策权威汇总（v2026-08-20）：省级核心政策、云岭创业贷、创业赛事、风险提示，含官方来源链接。
- `云南OPC创业伙伴深度调研方案.md` — 面向园区视察的调研方案（抽样 / 问卷 / 深度访谈 / 6+1 维度）。
- `网页文章/` — 网页存档（OPC 真实案例拆解、省人社厅政策通知）。

### 5) Bark 推送工具（`code/bark-notify/`）

> ⚠️ **临时测试项目，与云超服无关，勿纳入项目范围**。

Python（uv，零第三方依赖）发送 Bark 手机推送。入口 `bark-notify`，默认服务器 `http://47.108.226.213:10086`、设备 key 经 `BARK_DEVICE_KEY` 覆盖。

---

## 五、设计文档索引（`design/`）

> 📍 **总设计文档在根目录**：`云超服一体化架构设计方案.md`（统一身份 / 后端服务群 / 6 端前端 / 多园区大屏 / 算力引擎；SVG 架构图在根 `figures/`）。

### `design/云超服平台/`
- `DESIGN.md` — 云超服平台**顶层系统设计总览**（简洁版）。
- `云南省OPC超级个体综合服务平台（云超服）系统设计方案.md` — **主设计文档**（平台定位、三端政务协同、AI 智能体、服务生态）。
- `云超服平台全量方案设计.md` — 构建蓝图（身份体系、六端口管理功能、状态机、数据模型、接口设计）。
- `身份体系与端口权限设计方案.md` — 多身份 / 六端口账号与 RBAC + 数据范围模型。
- `架构初步设计.md` — 分阶段架构推演。
- `Creative-Cards-DESIGN.md` — Creative Cards 组件设计规范。
- `任务类别.json` — 任务撮合分类数据（种子/参考数据）。

### `design/dpm/`
- `win-deploy.md`（Windows 部署 / 地址覆盖）、`update-check.md`（更新接口）、`voice-integration-plan.md`（实时语音）、`mqtt-commands.md`（MQTT 控制手册）、`esp32-ir-control.md`（ESP32 遥控）。

---

## 六、目录规范速查

| 放什么 | 放哪里 |
|--------|--------|
| 可运行代码 / 代码仓库 | `code/` |
| 云超服设计 / 架构文档 | `design/云超服平台/` |
| DPM 大屏系统文档 | `design/dpm/` |
| 培训课程内容 / 模板 / 知识库 | `materials/培训计划/` |
| 培训前端代码（小程序/网站） | `code/training/`（后端已并入 `code/server-core/app/training/`） |
| 云南 OPC 政策 / 调研资料 | `materials/搜集资料/` |
| 园区原始数据资料 | `materials/园区数据资料/`（gitignore） |
| 参考源（像素可视化 / 前端骨架） | `reference/` |

> 各子项目内部文档以各自的 `README.md` / `CLAUDE.md` / `AGENTS.md` 为准；本文件仅描述整体结构与跨项目约定。对园区大屏系统，权威说明以 `code/park-desktop/backend/README.md` 为准。