Pine/opc-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(memory): 新增项目记忆库技能（.claude/skills/memory + .claude/memory）

Browse Source 
- 主 skill SKILL.md：简明，指向 总约束/长期/短期/当前计划 与各端口记忆；定义强制工作流（读记忆→校验基线→改动→校验→提交→更新记忆）与 path:line 行号锚点规范。
- 总约束 MASTER.md：全局规则、仓库纪律、git 约定、进程铁律、记忆纪律。
- 计划三层：LONG-TERM(阶段0-5)/SHORT-TERM(当前迭代)/CURRENT(进行中)。
- 各端口记忆 ports/*.md：root/server-core/agent-desktop/park-desktop/compute-engine/training/web-official/admin-portal 的进度/已实现/已知问题/锚点。
- 各项目约束 projects/*.md（子skill）：仓库/强制流程/关键路径/行号规范。
- CLAUDE.md 增补第 11 条：每次开发/改动必须调用 /memory 并提交+更新记忆。
- .gitignore 排除 .claude/settings.local.json。
This commit is contained in:
Pine
2026-08-24 13:03:04 +08:00
parent e4fa481e17
commit 9cbf4b4a8b
24 changed files with 619 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/memory/MASTER.md
+57
View File
@@ -0,0 +1,57 @@
# 总约束（MASTER）
> 全局、跨项目、不可违背。冲突优先级：**项目内 AGENTS.md/README.md 的具体规则 > 本总约束 > 本项目 CLAUDE.md 概述**。
> 每次开发改动前先读本文件（经 /memory）。
## 1. 目录分桶（不可混放）
- `code/` 一切可运行代码 / 代码仓库
- `design/` 项目设计与架构文档
- `materials/` 课程内容、政策研究、园区数据等非代码资料
- `reference/` 参考源（独立仓库，根忽略）
## 2. 仓库纪律
- 主仓库（`opc`）只管 `design/ materials/` 与根文档、全局规范；**不跟踪各 `code/*` 子项目代码，保留文件夹**。
- `code/*` 各为独立仓库（组织 Pine）；`reference/*` 独立仓库。
- 任一子项目改动，在**各自仓库**内分批提交，不得混入根仓库或其它仓库。
## 3. git 提交约定
- 用**中文**、按**功能分批**提交，避免多文件一次提交。
- 提交信息不允许包含 `Co-Authored-By: Claude <noreply@anthropic.com>`。
- 先询问用户验证，通过后再提交。
- 上线/部署相关提交由用户手动执行（`backend-deploy-by-user`）。
## 4. 进程管理铁律
- **AI 绝对禁止启动/重启/停止任何前后端服务进程**（server-core :8090、park-desktop :10085、s2s :8765、vite、Tauri 等）。
- 需要时先通知用户，由用户亲自操作。AI 只做改代码、编译检查、接口测试（仅在服务已运行且不重启前提下）。
## 5. 凭据卫生
- `*.env*`、`*.local` 含密钥/凭据，默认 gitignore，勿提交。
- `.claude/settings.local.json` 为本地配置，勿提交。
## 6. 记忆纪律（本 skill 强制）
- 每次开发/改动**前**调用 `/memory` 载入记忆。
- 每次改动**后**：校验 → 提交 → 更新 `ports/<port>.md` 与 `CURRENT.md`。
- 记忆必须用 `path:line` 锚点，可直接定位。
- 计划变化同步 `LONG-TERM / SHORT-TERM`；规则变化同步本文件或对应 `projects/<port>.md`。
## 7. 后端架构标准（server-core）
- FastAPI **四层架构**（接口→业务→领域→基础设施），禁止反向依赖。
- server-core 与算力调度经**内部 IP/loopback** 交互；对外算力统一走服务端 `/api/v1`。
## 8. UI 基调
- 前端设计不偏离 `code/agent-desktop/console/` 主基调；admin-portal 用 shadcn/ui（遵循 `design/installation.md`）。
- 培训网站/小程序遵循自身「暗色粒子品牌语言」，但整体以 console 为基准。
## 9. 待办 / 已知落差（重要，随时更新）
- server-core 现状为「身份/门户演示」内核：无 `dispatcher.py`、无 `app/training` 子应用（设计与实现不符，待阶段2重构入口）。
- 8 个 RBAC 既有失败测试（权限种子问题）**非本次引入**，待排查。
- 若干 `/admin/*`（课程/活动/报名/测评/园区）与算力管理端点属阶段2-4，尚未实现。
.claude/memory/plans/CURRENT.md
+29
View File
@@ -0,0 +1,29 @@
# 当前计划（CURRENT）
> 进行中任务、待办、上次进展、本次改动的基线记录。**每次改动后必须更新。**
> 更新：改「上次进展/下一步」；记「本次改动（path:line 基线）」。
## 上次进展（2026-08-24）
- 完成 **server-core 阶段0-1**：5 个登录/算力端点 + compute_client + relay 改走引擎 + schemas。见 `ports/server-core.md`。
- 新建 **admin-portal**（Vite+React+TS+shadcn），登录/身份选择/RBAC/7 管理页，`npm run build` 通过。见 `ports/admin-portal.md`。
- 工作区结构已按规范名定版（code 下 6 仓库 + admin-portal）。
## 本次改动
> 每次改动前在此登记；改动后更新并清空为下一步。
- （无进行中的改动）
## 下一步
- [ ] 用户验收 server-core 阶段0-1 + admin-portal（先编译/联调，再由用户启动服务）。
- [ ] 推进阶段 2：业务域表 + `/admin/*` 端点，给 admin-portal 页面供电。
- [ ] 排查 server-core 8 个 RBAC 既有失败测试。
- [ ] admin-portal 独立仓库初始化（git init + infoepoch/infoepoch_lan 远端 + 首提交）。
## 待办 / 已知落差
- server-core 无 `dispatcher.py`、无 `app/training`（设计§12.1 与实现不符）。
- `/admin/compute/provision` 的 new-api 管理路径需按 `controller/user.go` 实测核对。
- 8 个 RBAC 既有失败（`test_rbac.py`/`test_operator_rbac.py`/`test_pine_universal.py`）非本次引入。
.claude/memory/plans/LONG-TERM.md
+28
View File
@@ -0,0 +1,28 @@
# 长期计划（LONG-TERM）
> 愿景与宏观阶段，源自《云超服一体化架构设计方案.md》§九。用「阶段 0-5」作为不可变里程碑，具体执行看短期/当前计划。
## 目标态（6 端 + 统一后端）
小程序 · web业务 · web官网 · **admin管理平台** · 智能体桌面 · 园区大屏；统一身份（一账号多端口）+ 统一后端（模块化，可演进微服务）+ 算力引擎（仅服务、管理自研）。
## 阶段（演进路线）
| 阶段 | 内容 | 退出条件 | 状态 |
|------|------|---------|------|
| **0 · 基座** | Pydantic/OpenAPI 契约；compute_client 打通 new-api；users 补 wx_openid + 手机/微信登录端点 | 六端能连后端登录 | 🔄 进行中 |
| **1 · 身份统一** | training accounts 迁移；六端登录归一；API_BASE 收敛 | 同一账号六端互通 | ⏳ |
| **2 · 业务域迁移** | courses/activities/bookings/tests 建表 + /admin/* + web platform 迁 console | 运营端单入口可管理课程/活动/报名/测评 | ⏳ |
| **3 · 用户端补全** | 算力/园区入驻/政策申报/财务/工商 + /opc/* + console Opc 页 | 用户端六功能可用 | ⏳ |
| **4 · 园区大屏** | dpm 多租户化 + data_source 接真实数据（替换 sim_engine） | 大屏真实人员+实时 token/流水 | ⏳ |
| **5 · 收尾** | 退役 training server / website mock / website platform；文档同步 | 单后端+四前端稳定 | ⏳ |
## 架构要点（长期遵循）
- 一个身份（user_id 为唯一归属）、一个后端、专业服务外置、算力服务端统一管控、契约可校验、迁移渐进可回滚。
- 数据模型总表（§七）：身份/Agent/生态/内容已建；新增业务域（courses/activities/bookings/tests/compute/park 等 16 表）未建。
## 关联
- 主设计文档：`云超服一体化架构设计方案.md`（根目录）。
- 每阶段细节见 `SHORT-TERM.md`。
.claude/memory/plans/SHORT-TERM.md
+18
View File
@@ -0,0 +1,18 @@
# 短期计划（SHORT-TERM）
> 当前迭代目标（一个迭代 = 一个可交付阶段）。迭代内细粒度任务看 `CURRENT.md`。
## 本迭代：阶段 0-1（后端基座 + 算力打通）+ admin-portal 脚手架
- **目标**：六端可手机/微信走后端登录；桌面端模型调用经 compute-engine 计量；server-core 产出 OpenAPI 契约；新增 admin 管理端骨架。
- **状态**：server-core 阶段0-1 已落地（登录端点 + compute_client + relay 改走引擎 + 契约 schema）；admin-portal 已建（Vite+TS+shadcn+登录+RBAC+7 管理页，构建通过）。
### 本迭代完成后（验收口径）
1. server-core 提供 `/auth/send-code / phone-login / wx-login` 与 `/admin/compute/ping|provision`；新端点带 `response_model`。
2. 桌面端模型调用经 server-core → compute-engine `/v1` 计量；服务端可建号/发 PAT/查余额流水。
3. admin-portal `npm run build` 通过；登录+身份选择+RBAC 路由可用。
### 下一步（下一迭代候选）
- **阶段 2**：courses/activities/bookings/tests 建表 + `/admin/*` 端点 + admin-portal 页面接真数据。
- 排查 8 个 RBAC 既有失败。
- 阶段0-1 联调用真实 compute-engine（引擎需用户先启动）。
.claude/memory/ports/admin-portal.md
+36
View File
@@ -0,0 +1,36 @@
# admin-portal 记忆
## 角色
云超服**运营管理平台**（新，独立仓库 `Pine/admin-portal`）。React18 + TS(strict) + Vite6 + Tailwind4 + **shadcn/ui**（依 `design/installation.md`）。接入 server-core（`/auth`、`/admin/*`）。
## 进度 / 现状（2026-08-24，脚手架+骨架完成，`npm run build` 通过）
### 结构（锚点）
| 文件 | 说明 |
|------|------|
| `package.json` / `vite.config.ts` / `tsconfig*.json` / `components.json` / `index.html` | 脚手架（vite 代理 /auth /admin → :8090） |
| `src/index.css` | Tailwind4 主题（亮/暗变量，`--mascot-accent`） |
| `src/lib/utils.ts` | `cn()` |
| `src/components/ui/*` | shadcn 组件（radix-ui 单片 + lucide + cva） |
| `src/lib/auth.tsx` | 认证上下文(localStorage) |
| `src/lib/rbac.tsx` | 八端口导航过滤 + 权限 |
| `src/api/client.ts` | fetch + token + 401 登出 |
| `src/api/resources.ts` | 用户/课程/活动/报名/测评/算力/园区 |
| `src/components/layout/AppShell.tsx` | 侧边栏+顶栏+身份切换 |
| `src/App.tsx` | `RequireAuth` + `RoleRoute`(operator/carrier) |
| `src/pages/{login,overview,users,courses,activities,bookings,tests,compute,park}` | 登录+总览+7 管理页 |
## 已知问题 / 待办
- 部分 `/admin/*`（courses/activities/bookings/tests/park）server-core **未实现**，页面已优雅降级（提示「暂未接入」），需阶段2 供电。
- 算力页 `ping/provision` 已对应 server-core 阶段0-1，可直接联调。
- 仓库尚未 git init / 注册远端 / 提交。
- esbuild 首次构建有 allow-scripts 提示（构建已验证可用）。
## 下一步
- 用户验收（`npm run dev` + 登录）。
- 初始化独立仓库 + 首提交。
- 阶段2 后端端点补齐后接入真数据。
.claude/memory/ports/agent-desktop.md
+21
View File
@@ -0,0 +1,21 @@
# agent-desktop 记忆
## 角色
智能体桌面应用（原 PineAgents；Agent OS + console + Tauri 壳）。console 亦为平台 admin 管理端（现由 admin-portal 承接）。独立仓库 `Pine/PineAgents`。
## 现状（2026-08-24）
- 后端运行时 `src/pineagents/`（agents/runtime/governance/sandbox/memory）；`app/routers/auth.py` 转发到 server-core（`PINEAGENTS_DEMO_BASE_URL`，`constant.py:168` 默认 `http://192.168.1.9:8090`，**设计期望 127.0.0.1**）。
- console（`console/src/`）：`pages/Operator/*`(admin管理)、`pages/portal/*`(8端口)、`Login`(密码+select-identity)、`auth/guards.tsx`(RequireRole)。API 手写 fetch，无 OpenAPI 生成；品牌 storage key 仍 `qwenpaw_*`（未收敛）。
## 待办
- `DEMO_BASE_URL` 默认改 `127.0.0.1:8090`（对齐设计）。
- 品牌 `qwenpaw_*` → 云超服品牌收敛。
- admin 管理功能逐步移交 admin-portal。
- 桌面端模型调用经 server-core → compute-engine 计量（依赖阶段0-1，已就绪）。
## 下一步
登录/品牌收敛；与 admin-portal 职能切分。当前无改动。
.claude/memory/ports/compute-engine.md
+26
View File
@@ -0,0 +1,26 @@
# compute-engine 记忆
## 角色
算力引擎微服务（new-api 的 fork，Go）：OpenAI 兼容 `/v1` 模型中继 + 额度/令牌/token 流水。**仅服务，管理/页面自研**（其自带 web 面板不使用）。独立仓库 `Pine/compute-engine`。
## 现状（2026-08-24）
- 结构：`main.go`(~/360 行) / `relay/` / `controller/` / `model/` / `router/api-router.go` / `common/` / `web/`。
- 端口 :3000（docker-compose `3000:3000`，`calciumion/new-api:latest`）。
- 内置 web UI 已由二进制嵌入（`main.go:42` embed `web/dist`，`main.go:198` 注册），但云超服意图不使用。
## 对接（server-core → compute-engine）
- 链路「规划中」已部分落地：server-core `app/services/compute_client.py` 封装修建号/发 PAT/余额/流水（loopback `http://127.0.0.1:3000`）；`relay.py` 上游可改走本引擎 `/v1`（配置 `PINEAGENTS_COMPUTE_ADMIN_TOKEN` 时）。
- **关键待核对**：`compute_client.py` 默认管理路径（`/api/user`建号、`/api/token`发PAT）需按 `controller/user.go`、`router/api-router.go` admin 段实测。
- DeepSeek key 在 server-core（`app/config.py`）而非此处；渠道应迁至本引擎 `/api/channel`（阶段中）。
## 关键文件 / 锚点
- `router/api-router.go`（admin/self/log/data 路由）、`controller/user.go`、`controller/log.go`、`controller/billing.go`。
- 用户侧：`/api/user/self`(GetSelf)、`/api/user/token`(GenerateAccessToken)、`/api/log/self(/stat)`、`/api/data/self`、`/api/dashboard/billing/usage`。
## 下一步
- 实测核对管理路由；AddChannel 渠道与初始管理员；供 server-core 联调（引擎由用户先启动）。
.claude/memory/ports/park-desktop.md
+24
View File
@@ -0,0 +1,24 @@
# park-desktop（dpm 大屏）记忆
## 角色
园区大屏桌面应用（Tauri2 + React + FastAPI :10085 + MQTT/SSE）。多园区通用（目标态）；现状**单园区（昆明大学生创业园）演示**。
## 现状（2026-08-24）
- 数据 100% 来自 `backend/app/sim_engine.py`（静态常量 + 随机 TOKEN 演示）；`/wall` 企业墙前端硬编码（`src/pages/CompanyWall.jsx`）。
- 无 `data_source.py`、无园区登录→org_id 隔离、不连 server-core / compute-engine。
- 后端：`app/routers.py`(REST) / `sim_engine.py` / `storage.py` / `mqtt.py` / `llm.py`/`rag.py`/`asr.py`/`s2s_bridge.py`/`vision_yolo.py` / `admin.py`(Jinja)。
- 前端路由 `/ /twin /ai /screen /voice /wall`；`/admin` 为 Jinja（非 React）；`useParkSim` 在 `src/utils/parkData.js:209`。
## 差距（阶段 4）
- 多租户化：园区账号(carrier)登录→org_id 隔离；`data_source.py` 接 server-core `/api/park/*` + compute-engine 聚合，替换 sim_engine 模拟；`/wall` 改接口。
## 关键文件 / 锚点
- `backend/app/sim_engine.py:13`（REAL 硬编码）、`backend/app/routers.py:322`(snapshot)、`src/pages/CompanyWall.jsx:15`(WALL 数组)。
## 下一步
阶段 4：dpm 多租户化 + 真实数据（依赖 server-core 园区数据域 + 算力链路）。当前无改动。
.claude/memory/ports/root.md
+23
View File
@@ -0,0 +1,23 @@
# 根仓库 / 工作区记忆
## 进度 / 现状（2026-08-24）
- 工作区按《CLAUDE.md》规范名定版：`code/` 下 `agent-desktop · server-core · web-official · park-desktop · compute-engine · training · admin-portal`。
- `.gitignore` 已覆盖全部独立仓库目录与本地配置。
- 设计/资料在 `design/`、`materials/`。
## 已完成
- 迁移：旧名仓库全部改名/克隆为规范名并同步最新（见各端口记忆）。
- 删除：`code/bark-notify`（临时，排除）、`code/training/server` 遗留（后端并入 server-core，服务器 `server/` 运行遗留已清理）。
## 关键文件 / 锚点
- `CLAUDE.md`：目录规范、进程铁律、git 约定。
- `code/README.md`：code 子项目索引。
- `design/installation.md`：shadcn 规范（admin-portal 依此）。
- 根主设计：`云超服一体化架构设计方案.md`。
## 已知问题 / 待办
- 无 `dispatcher.py`/`app/training` 的落差待阶段2重构入口。
.claude/memory/ports/server-core.md
+42
View File
@@ -0,0 +1,42 @@
# server-core 记忆
## 角色
核心服务端（FastAPI）：身份/平台 API + 培训子应用（目标态），对外 `opc.pinesound.cn`。统一入口 `dispatcher.py`（**尚未实现，现状为扁平 `app/main.py`**）。
## 进度 / 现状（阶段0-1 已完成）
- 八端口 RBAC / select-identity / token 吊销 / require_port 完整（最成熟部分）。
- **阶段0-1 新增**：统一登录（手机/微信）+ 算力打通 + 契约。
### 本次改动文件（锚点）
| 文件 | 说明 | 锚点 |
|------|------|------|
| `app/config.py` | +算力/短信/微信配置 | `app/config.py` (COMPUTE_BASE_URL 等) |
| `app/models.py` | `User` 补 `wx_openid/phone` | `app/models.py` User |
| `app/repositories.py` | create 支持 wx/phone；+set_wx_openid/set_phone | `app/repositories.py` UserRepository |
| `app/services/sms.py` | 验证码（stub 默认） | 新增 |
| `app/services/wechat.py` | code2session（空 appid 直通） | 新增 |
| `app/services/compute_client.py` | new-api 客户端 | 新增 |
| `app/schemas/*.py` | 登录/算力 Pydantic | 新增 |
| `app/routers/auth.py` | +send-code/phone-login/wx-login/wx-phone | `app/routers/auth.py` |
| `app/routers/relay.py` | 上游改走 compute-engine（可回退 deepseek） | `app/routers/relay.py` |
| `app/routers/rbac_operator.py` | +compute/ping、compute/provision | `app/routers/rbac_operator.py` |
## 已实现（功能）
- 登录：`/auth/login`(密码)、`/auth/send-code`、`/auth/phone-login`、`/auth/wx-login`、`/auth/wx-phone`；多身份 `select-identity`。
- 算力：`/admin/compute/ping`、`/admin/compute/provision`；`compute_client` 封装 create_user/issue_pat/get_balance/get_month_usage/get_logs（路径为默认值，待实测核对）。
- 契约：`app/schemas/`，新端点带 `response_model`；OpenAPI 111 路径。
## 已知问题 / 待办
- 8 个 RBAC 既有失败测试（`test_rbac.py`/`test_operator_rbac.py`/`test_pine_universal.py`），**非本次引入**，待排查。
- 无 `app/training`、无 `data/opc.db`（阶段2 建）。
- compute_client 管理路由路径需按 compute-engine `controller/user.go` 实测。
- 单测：`tests/test_phone_wx_login.py`、`tests/test_compute_client.py`（均过）。
## 下一步（阶段 2）
courses/activities/bookings/tests 建表 + `/admin/*` 端点 + `/opc/*` 业务端点。
.claude/memory/ports/training.md
+20
View File
@@ -0,0 +1,20 @@
# training 记忆
## 角色
培训前端（`miniprogram/` Taro 小程序 + `website/` Vite React；`server/` 后端已并入 server-core，本地原 server 遗留已清理）。独立仓库 `Pine/training`。
## 现状（2026-08-24）
- `miniprogram/` 页面：首页/活动报名/测评/政策/我的；登录为 手机+微信（`src/utils/api.js:7` → `https://opc.pinesound.cn`）。
- `website/`：`src/user/`(C端)、`src/platform/`(管理/报表，**尚未迁入 console/admin-portal，阶段2**)、`src/data/`(静态内容 courses/tests/policy)、`server/mock-api.mjs`(mock 后端)。
- **关键**：bookings/events/tests/ops 端点 server-core **未实现**，当前只靠 mock server；「后端已并入 server-core」尚未真正落地。
## 差距（阶段 1-2）
- 登录归一（手机/微信）、API_BASE 收敛。
- platform 管理迁入 admin-portal（阶段2）；后端接真数据。
## 下一步
阶段 1-2：依赖 server-core 补 phone-login/wx-login（已提供）与业务端点（未提供）后接入。
.claude/memory/ports/web-official.md
+20
View File
@@ -0,0 +1,20 @@
# web-official 记忆
## 角色
官网展示端（Vite+React SPA，Vite6+React18+TS+Tailwind4+shadcn「radix-nova」，组件经 `radix-ui`+shadcn 包）。独立仓库 `Pine/PineAgentsWeb`。公开展示（产品/政策/招生/案例），纯静态 + 可选登录。
## 现状（2026-08-24）
- 路由（`src/App.tsx:74-86`）：`/` Home、`/downloads`、`/blog`、`/docs`、`/release-notes`。
- 无 政策/招生/案例 页（缺失）。
- `src/config.ts:26` 读 `site.config.json`；仅 blog 统计可选接 Supabase；无登录、无业务后端。
- 仍为 QwenPaw 品牌（未改云超服）。
## shadcn 约定（供 admin-portal 参照）
- `components.json`(style radix-nova)、`@tailwindcss/vite`、Tailwind4、`src/lib/utils.ts(cn)`、依赖 `radix-ui`/cva/clsx/tailwind-merge/tw-animate-css；`ui/` 目录空（用 shadcn 包）。
## 下一步（如需）
补政策/招生/案例页；品牌收敛；可选登录。当前无改动。
.claude/skills/memory/README.md
+30
View File
@@ -0,0 +1,30 @@
# 记忆库技能（memory）
> 标准的 Claude Code **项目技能（skill）**，随主仓库提交。用于有条理地记录开发进度、功能完成、约束与计划；**强制**「改动前载入记忆、改动后提交并更新记忆」。
## 结构
```
.claude/
skills/memory/
SKILL.md # 主 skill 文件（简明：工作流 + 接口契约 + 行号规范）
README.md # 本说明
projects/*.md # 各项目约束（子 skill）
memory/
MASTER.md # 总约束
plans/{LONG-TERM,SHORT-TERM,CURRENT}.md
ports/*.md # 各端口/子项目记忆
```
## 使用
- **调用**：`/memory`（或改项目前自然触发）。经 Skill 载入记忆。
- **读**：MASTER → CURRENT → ports/<port> → projects/<port> →（按需 LONG/SHORT）。
- **写**：改动后提交 → 更新 ports/<port> 与 CURRENT → 按需 LONG/SHORT/MASTER。
## 设计要点
- 主文件简明，指向计划与端口记忆；子文件约束每项目。
- 记忆一律 `path:line` 锚点，可直接定位。
- 计划分长期（阶段0-5）/短期（迭代）/当前（进行中）三层。
- 每项目强约束「改动必提交 + 更新记忆」，见 `projects/*.md`。
.claude/skills/memory/SKILL.md
+52
View File
@@ -0,0 +1,52 @@
---
name: memory
description: 项目记忆库。任何开发/改动前必须先调用本技能载入记忆（总约束、各端口记忆、长期/短期/当前计划）；改动落地后必须校验、提交并更新对应记忆文件。用户提到「记忆」「进度」「开发到哪了」「上下文」或开始改动任一项目时触发。
---
# 记忆库（Memory）
> 强制流程：**读记忆 → 校验基线 → 改动 → 校验 → 提交 → 更新记忆**。
> 每次开发/改动项目前，**必须先调用 /memory 载入记忆**；每次改动落地，**必须完成提交并更新对应记忆文件**。
## 记忆文件一览（接口契约）
| 文件 | 作用 | 何时更新 |
|------|------|---------|
| `.claude/memory/MASTER.md` | **总约束**（全局规则、不可违背项） | 规则变化 |
| `.claude/memory/plans/LONG-TERM.md` | 长期计划（愿景 / 架构阶段 0-5） | 阶段变更 |
| `.claude/memory/plans/SHORT-TERM.md` | 短期计划（当前迭代目标） | 迭代开始/结束 |
| `.claude/memory/plans/CURRENT.md` | **当前计划**（进行中任务、待办、上次进展） | **每次改动后** |
| `.claude/memory/ports/<port>.md` | 各端口/子项目记忆 | **每次改动后** |
| `.claude/skills/memory/projects/<port>.md` | 各项目**约束**（子skill：仓库/流程/关键路径） | 项目约定变更 |
## 标准工作流（6 步）
1. **载入**：读 `MASTER.md` ⇒ 读 `CURRENT.md` ⇒ 读目标端口 `ports/<port>.md` ⇒ 读对应 `projects/<port>.md` 约束 ⇒ 按需读 `LONG-TERM / SHORT-TERM`。
2. **基线**：在 `CURRENT.md`「本次改动」记录将改的文件与 `path:line` 现状。
3. **改动**：只改锁定范围；完成后跑编译 / 类型检查 / 相关测试。
4. **提交**：在**该子项目仓库**内中文+功能分批提交（见 MASTER 约定），不得混入根仓库或其它仓库。
5. **记录**：更新 `ports/<port>.md`（进度 / 已实现 / 已知问题 / 新锚点）与 `CURRENT.md`（完成、下一步）；影响计划则更新 `SHORT-TERM / LONG-TERM`。
6. **收尾**：如需，回写 `MASTER.md` 规则或对应 `projects/<port>.md` 约束。
## 端口 → 记忆/约束文件对照
| 端口 | 记忆 | 约束 |
|------|------|------|
| 工作区/根 | `ports/root.md` | `projects/root.md` |
| server-core | `ports/server-core.md` | `projects/server-core.md` |
| agent-desktop | `ports/agent-desktop.md` | `projects/agent-desktop.md` |
| park-desktop (dpm) | `ports/park-desktop.md` | `projects/park-desktop.md` |
| compute-engine | `ports/compute-engine.md` | `projects/compute-engine.md` |
| training | `ports/training.md` | `projects/training.md` |
| web-official | `ports/web-official.md` | `projects/web-official.md` |
| admin-portal | `ports/admin-portal.md` | `projects/admin-portal.md` |
## 行号锚点规范
- 记忆引用一律写成 `path:line`（如 `app/routers/auth.py:145`），**据此可直接定位**，不用概念性描述。
- 变更后行号失效：更新记忆时重新核对并沿用最新行号。
- 涉及「完成度 / 已实现 / 已知问题」必须落到具体文件与行，而非仅写“已支持 X”。
## 各项目约束（子skill）
见 `projects/*.md`。每条均含「改动必须提交 + 更新记忆」的强制条款，与仓库级 AGENTS.md / CLAUDE.md 冲突时**以项目 README / AGENTS.md 与本 skill 的 MASTER 总约束为准**。
.claude/skills/memory/projects/admin-portal.md
+24
View File
@@ -0,0 +1,24 @@
# 项目约束：admin-portal
## 仓库
新独立仓库 `Pine/admin-portal`（待 init）。前端，后端为 server-core。
## 强制流程（本仓库改动）
- **改动必做**：`npx tsc -b`（strict）→ `npm run build` 通过 → 中文功能分批提交 → 更新 `ports/admin-portal.md` + `CURRENT.md`。
- **不得**：直接启动 dev/build 前端服务（用户手动）；引入未用依赖。
## 技术 / 关键路径
- Vite6 + React18 + TS(strict) + Tailwind4 + shadcn/ui（依 `design/installation.md`；radix-ui 单片 + lucide + cva）。
- `src/api/client.ts`(token) / `resources.ts`(端点在此集中，路径调整只改此文件) / `lib/auth.tsx` / `lib/rbac.tsx` / `App.tsx`(RequireAuth+RoleRoute)。
- `src/components/ui/*` shadcn 组件；`src/components/layout/AppShell.tsx`。
## 行号规范
- 组件/页面/端点引用给 `src/...:行`；调整后更新。
## 已知注意
- 部分 `/admin/*` 端点 server-core 未实现 → 页面优雅降级；后端补齐后再接真数据。
.claude/skills/memory/projects/agent-desktop.md
+23
View File
@@ -0,0 +1,23 @@
# 项目约束：agent-desktop
## 仓库
独立仓库 `git@infoepoch_lan:Pine/PineAgents.git`。console `yarn dev`(:8088 后端，Tauri 壳)。
## 强制流程
- 改动必做：类型/构建校验 → 中文分段提交（agent-desktop 仓库）→ 更新 `ports/agent-desktop.md`。
- 不启动/重启 agent 后端（:8088）或 vite/Tauri（用户手动）。
## 关键路径
- `src/pineagents/app/routers/auth.py`（转发 server-core）、`src/pineagents/constant.py:168`（DEMO_BASE_URL）。
- `console/src/`：`pages/Operator/*`、`pages/portal/*`、`auth/guards.tsx`、`api/modules/*`（手写 fetch）。
## 行号规范
`src/...:行`；改动后更新。
## 已知注意
- `DEMO_BASE_URL` 默认 `192.168.1.9:8090`（设计期望 127.0.0.1）；brand key `qwenpaw_*` 未收敛。
.claude/skills/memory/projects/compute-engine.md
+22
View File
@@ -0,0 +1,22 @@
# 项目约束：compute-engine（new-api）
## 仓库
独立仓库 `Pine/compute-engine`（origin infoepoch + infoepoch_lan）。Go 1.22+，`:3000`。AGPLv3（上游 QuantumNous/new-api）。
## 强制流程
- 改动必做：Go 校验 → 中文分段提交（compute-engine 仓库）→ 更新 `ports/compute-engine.md`。
- 遵守仓库 `AGENTS.md`：`relaykit/` 独立可编译（`cd relaykit && GOWORK=off go build ./...`）；JSON 走 `common/json.go`；三库兼容；`*Checked`/饱和；`require`/`assert` 测试。
- 不启动引擎（用户手动）。
## 关键路径
- `main.go`、`relay/`、`controller/`、`model/`、`router/api-router.go`、`common/`、`web/`。
- 对接：server-core `compute_client`（管理 API）。
## 行号规范 / 注意事项
- 改动引用给 `files:行`。
- 项目治理：**不得**移除 new-api / QuantumNous 标识（AGENTS.md）。
- 仅服务，管理/页面自研（云超服不使用其 web 面板）。
.claude/skills/memory/projects/park-desktop.md
+24
View File
@@ -0,0 +1,24 @@
# 项目约束：park-desktop（dpm 大屏）
## 仓库
独立仓库 `Pine/dpm_rust`（origin http://code.infoepoch.cn/Pine/dpm_rust.git）。后端 backend `uv run python main.py`(:10085)；前端 `yarn dev`。
## 强制流程
- 改动必做：校验 → 中文分段提交（park-desktop 仓库）→ 更新 `ports/park-desktop.md`。
- **严格禁止**启动/重启后端(:10085)、MQTT、s2s(:8765)、vite、Tauri；由用户操作。
## 关键路径
- `backend/README.md`（权威基线）、`backend/app/{routers,sim_engine,storage,mqtt,llm,rag,asr,s2s_bridge,vision_yolo,admin}.py`。
- `src/` 路由 `/ /twin /ai /screen /voice /wall`；`src/utils/parkData.js:209`(useParkSim)。
- 设计文档 `design/dpm/`。
## 行号规范
`backend/app/...:行` 或 `src/...:行`；改动后更新。
## 已知注意
- 单园区演示、数据 100% sim_engine；阶段 4 才多租户化 + 真实数据。
.claude/skills/memory/projects/root.md
+24
View File
@@ -0,0 +1,24 @@
# 项目约束：工作区 / 根仓库（opc）
## 范围
`design/ materials/` 内容、根文档（CLAUDE.md/README）、全局规范、`.claude/`。
## 强制流程
- **改动根仓库必做**：校验 → 中文分段提交（根仓库）→ 更新 `ports/root.md` + `CURRENT.md`。
- **不得**把各 `code/*` 子项目代码提交进根仓库；子项目改动去各自仓库。
## 关键路径
- `CLAUDE.md`（目录规范/进程铁律/git约定）、`code/README.md`（code 索引）、`云超服一体化架构设计方案.md`（主设计）。
- `design/`、`materials/`、`reference/`（独立）。
## 行号规范
- 引用根文档用 `文件:行`；规范修订同步。
## 注意事项
- 进程管理铁律、凭据卫生、目录分桶贯穿全工作区。
- `.claude/settings.local.json` 不提交。
.claude/skills/memory/projects/server-core.md
+25
View File
@@ -0,0 +1,25 @@
# 项目约束：server-core
## 仓库
独立仓库 `git@infoepoch:Pine/PineAgentsServer.git`（origin，另有 infoepoch_lan 副远端）。启动 `uv run python main.py`(:8090)。
## 强制流程（本仓库改动）
- **改动必做**：编译/导入校验（`uv run python -c "from app.main import app"`、`compileall`）→ 相关单测（`uv run python -m pytest`）→ 中文功能分批提交 → 更新 `ports/server-core.md` + `CURRENT.md`。
- **不得**：启动/重启服务（用户手动）；把无需新依赖的 `uv.lock` 噪音提交；跨仓库混提交。
## 架构 / 关键路径
- 四层目标态；现扁平：`app/{config,models,dependencies,repositories,rbac,jwt,main,seed}.py`、`app/routers/*`、`app/services/*`、`app/schemas/*`。
- 入口 `app/main.py`（现状；`dispatcher.py` 未实现）。
- 数据：`data/app.db`(SQLite)；`PINEAGENTS_DEMO_DATABASE_URL` 可覆盖。
## 行号规范
- 涉及功能/完成度必须给 `path:line`（如 `app/routers/auth.py:145`）；变更后更新。
## 已知注意
- 8 个 RBAC 既有失败测试（非本次引入，勿在阶段0-1 阻断）。
- new-api 管理路径需按 compute-engine 实测核对。
.claude/skills/memory/projects/training.md
+24
View File
@@ -0,0 +1,24 @@
# 项目约束：training
## 仓库
独立仓库 `Pine/training`。`miniprogram/` Taro 小程序（`yarn dev:weapp`）、`website/` Vite React（`pnpm dev`）。
## 强制流程
- 改动必做：类型/构建校验 → 中文分段提交（training 仓库）→ 更新 `ports/training.md`。
- 小程序↔网页同步约束：C 端任一功能改动须同步两端（见 `materials/培训计划/课程体系0.1/小程序同步约束.md`）。
- 不启动前端（用户手动）。
## 关键路径
- `miniprogram/src/utils/api.js:7`(API_BASE `https://opc.pinesound.cn`)、`miniprogram/src/{utils/auth.js,pages/*}`。
- `website/src/{user,platform,data}/`、`website/src/services/*.js`、`website/server/mock-api.mjs`。
## 行号规范
`src/...:行`；改动后更新。
## 已知注意
- bookings/events/tests/ops 端点 server-core 未实现，当前靠 mock；platform 管理待迁 admin-portal（阶段2）。
.claude/skills/memory/projects/web-official.md
+23
View File
@@ -0,0 +1,23 @@
# 项目约束：web-official
## 仓库
独立仓库 `Pine/PineAgentsWeb`（origin infoepoch）。`pnpm install && pnpm run dev`。
## 强制流程
- 改动必做：tsc/构建校验 → 中文分段提交（web-official 仓库）→ 更新 `ports/web-official.md`。
- 不启动前端（用户手动）。
## 关键路径 / shadcn 基线
- `src/App.tsx:74-86`(路由)、`src/config.ts:26`(site.config.json)、`components.json`(radix-nova)、`@tailwindcss/vite`、`src/lib/utils.ts(cn)`。
- 依赖 `radix-ui`/cva/clsx/tailwind-merge/tw-animate-css/shadcn 包。
## 行号规范
`src/...:行`；改动后更新。
## 已知注意
- 仍为 QwenPaw 品牌；缺政策/招生/案例页；无登录/业务后端。
.gitignore
+3
View File
@@ -50,3 +50,6 @@ materials/园区数据资料/
.idea/ .idea/
.vscode/ .vscode/
.DS_Store .DS_Store
# Claude 本地配置（误提交会暴露机器设置）
.claude/settings.local.json
CLAUDE.md
+1
View File
@@ -77,6 +77,7 @@
- **同步全子项目**：同步 / 部署时必须**同步所有子项目**（`agent-desktop / server-core / web-official / park-desktop / training / compute-engine`），逐个 `git pull`/`push`，不得遗漏。 - **同步全子项目**：同步 / 部署时必须**同步所有子项目**（`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`。 10. **server-core 架构标准**：FastAPI 采用**四层架构**（接口层→业务层→领域层，基础设施层含数据模型层），**禁止反向依赖**；server-core 与**算力调度服务**经**内部 IP / loopback** 交互，对外算力调用统一走**服务端 `/api/v1`**。工程化（`serverdata/` 数据目录、`serverrun/` 容器启动、`ops/` 运维脚本）参考 `C:\Users\Administrator\MyCode\PineSoundServer`。
11. **记忆技能（强制）**：每次开发/改动项目前**必须**调用 `/memory` 技能载入记忆；改动落地后**必须**完成提交并更新对应记忆文件。记忆库为 `.claude/skills/memory/`（技能）+ `.claude/memory/`（总约束、long/short/current 计划、各端口记忆），随主仓库提交，具体约束与工作流见技能 `SKILL.md` 与 `MASTER.md`。
--- ---