Pine/opc-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ada6383e49337a599c843a7e7c6f461cf4365e17
opc-backup/CLAUDE.md
T

12 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/PineAgents/ 云超服核心。前端 / 桌面端 / CLI 端，含 console/（PC 后台 UI 基调来源）。 独立仓库（忽略）
code/PineAgentsServer/ 云超服总后端。FastAPI 演示后端（认证转发、登录注册），uv 管理。 独立仓库（忽略）
code/PineAgentsWeb/ 云超服网页展示端。Vite + React SPA，项目身份 pineagents-web。 独立仓库（忽略）
code/dpm/ 园区大屏媒体轮播系统（DPM）。Tauri + React 大屏 + FastAPI 后端。 独立仓库（忽略）
code/bark-notify/ Bark 手机推送工具（Python，uv，零第三方依赖）。 根仓库
code/opc-training/ OPC 培训系统代码（miniprogram/ 小程序、website/ 三端 Web、server/ FastAPI 后端）。 根仓库

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

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

materials/ — 资料 / 内容

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

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

  1. UI 风格基调：凡涉及前端设计，必须不偏离 code/PineAgents/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 绝对禁止启动 / 重启 / 停止任何前后端服务进程（PineAgentsServer :8090、DPM 后端 :10085、s2s 语音 :8765、vite、Tauri 等）。需要时先通知用户，由用户亲自操作。AI 只做改代码、编译检查、接口测试（仅在服务已运行且不重启的前提下）。参见各子项目 AGENTS.md。
  7. 凭据卫生：*.env*、*.local 含密钥 / MQTT 凭据，默认加入 .gitignore，勿提交。DPM 的 backend/.env 与根 .env.local 尤其要注意。
  8. 工作流：改动代码后先询问用户验证，通过后按功能分批用中文提交，避免多文件一次提交。

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

1) 云超服平台（code/PineAgents / PineAgentsServer / PineAgentsWeb）

  • PineAgentsServer 是主后端认证转发的来源：code/PineAgents/src/pineagents/app/routers/auth.py 将 /api/auth/* 转发到 PineAgentsServer（PINEAGENTS_DEMO_BASE_URL 默认 http://127.0.0.1:8090）。
  • 登录身份：多身份 / 多端口账号模型（OPC 端、运营管理端、政务端、甲方企业端、服务商端、创业载体端），见 design/云超服平台/身份体系与端口权限设计方案.md。
# PineAgentsServer（uv 管理）
cd code/PineAgentsServer && uv sync && uv run uvicorn app.main:app --port 8090 --reload

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

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

2) 园区大屏系统 DPM（code/dpm/，独立仓库）

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

  • 架构：数据走 REST（FastAPI :10085），控制走 MQTT（EMQX），SSE /api/events 作回退；桌面壳为 Tauri 2。
  • 后端：code/dpm/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/dpm/src/（React 19 + Vite + Tailwind + three.js + MQTT + Tauri）。路由 /（数据）、/twin、/ai、/screen、/voice、/wall；/admin 是后端 Jinja 页面，非 React 路由。
  • 文档：权威说明 code/dpm/backend/README.md；系统/运维文档见 design/dpm/。
  • 进程规则：见 code/dpm/AGENTS.md —— AI 禁止启动/重启后端 / vite / Tauri。
cd code/dpm
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/opc-training/ 代码）

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

  • 代码（code/opc-training/）：miniprogram/（Taro+React 微信小程序）、website/（Vite+React 三端 Web）、server/（FastAPI+SQLite 后端 :8091）、sync-server.sh。见 code/opc-training/README.md。
  • 内容（materials/培训计划/课程体系0.1/）：核心模板/（T01–06）、交付SOP/（S01–03）、课程设计/（01–04）、运营工具/、宣传与运营/、知识库/、自我认知工具/、OPC创业测评/。
  • 小程序↔网页同步约束：C 端任一功能在网页改动后必须同步到小程序（共用 OPC 测评/政策/报名等模块），见 materials/培训计划/课程体系0.1/小程序同步约束.md。
  • 顶层 materials/培训计划/配套件/ 是另一套并行的课程配套模板包（作业、Prompt、政策手册、分班定制、结业四件套、直播/工作坊大纲），以 00_索引与使用说明.md 为入口。
# 小程序
cd code/opc-training/miniprogram && yarn dev:weapp
# 后端（uv）
cd code/opc-training/server && uv run uvicorn app.main:app --port 8091 --reload
# 网站
cd code/opc-training/website && pnpm dev

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/）

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/opc-training/
云南 OPC 政策 / 调研资料 materials/搜集资料/
园区原始数据资料 materials/园区数据资料/（gitignore）
参考源（像素可视化 / 前端骨架） reference/

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

Reference in New Issue View Git Blame Copy Permalink