Pine/opc-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
daf35321200630f49a8a78b8056457e7d910823b
opc-backup/CLAUDE.md
T
Pine daf3532120 refactor: 工作区多仓库结构定版 + 总设计文档迁根目录 
- 总设计文档迁至根目录（云超服一体化架构设计方案.md，figures/ 随迁）
- 设计文档补充 §十二 各代码项目工作原理
- code 六个子项目转独立仓库（组织 Pine），移出根跟踪、保留文件夹
- CLAUDE.md 补充主项目/子项目约束（分别提交、同步全子项目）
2026-08-23 22:47:22 +08:00

14 KiB
Raw Blame History

云超服 / 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，不得遗漏。
    • 分别提交：任一子项目有修改时，在各自仓库内分批用中文提交并推送，不得混入根仓库或其它子项目。

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

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。
# 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。

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。
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 为入口。
# 小程序
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 为准。

Reference in New Issue View Git Blame Copy Permalink