a44244c7ad
Some checks failed
CI / Test (ubuntu-latest) (push) Has been skipped
CI / Lint (ubuntu-latest) (push) Has been skipped
CI / Check (ubuntu-latest) (push) Has been skipped
CodeQL / Analyze (${{ matrix.language }}) (none, javascript-typescript) (push) Has been skipped
Deploy Website on push / Deploy Push Playground Ftp (push) Has been skipped
Deploy Website on push / Deploy Push Docs Ftp (push) Has been skipped
Deploy Website on push / Deploy Push Antd Ftp (push) Has been skipped
Deploy Website on push / Deploy Push Element Ftp (push) Has been skipped
Deploy Website on push / Deploy Push Naive Ftp (push) Has been skipped
Release Drafter / update_release_draft (push) Has been skipped
Deploy Website on push / Rerun on failure (push) Has been skipped
CI / Test (windows-latest) (push) Has been cancelled
CI / Lint (windows-latest) (push) Has been cancelled
CI / Check (windows-latest) (push) Has been cancelled
CI / CI OK (push) Has been cancelled
135 lines
7.0 KiB
Markdown
135 lines
7.0 KiB
Markdown
# agents.md — 项目上下文档案（跨账号迁移单一事实源）
|
||
|
||
> **用途**：让任何 AI 助手（WorkBuddy 其他账号 / 其他 AI 工具）接手本项目时，无需重新摸索即可无缝衔接。
|
||
> **维护约定**：每次操作（改代码 / 跑命令 / 决策 / 踩坑）后，更新下方「操作日志」章节；环境与架构变化同步更新对应章节。
|
||
> **首次建立**：2026-08-24
|
||
|
||
---
|
||
|
||
## 1. 项目概况
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 业务名 | admin.xpcool.com |
|
||
| 工作目录 | `E:\xxcool\project\admin.xpcool.com` |
|
||
| 基础框架 | Vue Vben Admin **5.7.0**（官方 monorepo 模板） |
|
||
| 技术栈 | Vue 3 + TypeScript + Vite + pnpm 11 + turbo（monorepo）+ Ant Design Vue 等 |
|
||
| 代码来源 | 官方仓库 `vbenjs/vue-vben-admin` 克隆（remote 为 ghproxy 镜像：`https://ghproxy.net/https://github.com/vbenjs/vue-vben-admin.git`） |
|
||
| 当前基线 | 模板原样，**无业务定制**（web-antd views 仅有 `_core/dashboard/demos` 示例页） |
|
||
| git 分支 | `main`（仅 origin/main） |
|
||
|
||
## 2. 应用清单（apps/）
|
||
|
||
| 应用 | 包名 | UI 库 | dev 端口 | 启动命令 |
|
||
|---|---|---|---|---|
|
||
| web-antd | `@vben/web-antd` | Ant Design Vue | **5666** | `pnpm dev:antd` |
|
||
| web-antdv-next | `@vben/web-antdv-next` | Ant Design Vue Next | - | `pnpm dev:antdv-next` |
|
||
| web-ele | `@vben/web-ele` | Element Plus | - | `pnpm dev:ele` |
|
||
| web-naive | `@vben/web-naive` | Naive UI | - | `pnpm dev:naive` |
|
||
| web-tdesign | `@vben/web-tdesign` | TDesign | - | `pnpm dev:tdesign` |
|
||
| backend-mock | - | Nitro mock 后端 | **5320** | 随 dev 自动启动（VITE_NITRO_MOCK=true） |
|
||
|
||
> 本业务主应用推测为 **web-antd**（端口 5666，已确认 .env.development）。
|
||
|
||
## 3. 环境要求与本机踩坑记录（重要）
|
||
|
||
### 版本要求（package.json engines）
|
||
- Node `^22.18.0 || ^24.12.0`
|
||
- pnpm `>=11.0.0`（`packageManager: pnpm@11.16.0`）
|
||
|
||
### 本机（Windows）已验证的运行方式 —— 直接复制可用
|
||
|
||
```bash
|
||
# 前置：把 managed node 22.22.2 放到 PATH 最前（系统 node 23 会因 NODE_OPTIONS 报错）
|
||
export PATH="/c/Users/ybtdevxxl/.workbuddy/binaries/node/versions/22.22.2:$PATH"
|
||
# 关键：清空 NODE_OPTIONS（否则 WorkBuddy 的 safe-delete shim 会拦截 pnpm 的删除操作导致安装失败）
|
||
unset NODE_OPTIONS
|
||
# 用 corepack 驱动 pnpm（PATH 里的 pnpm 挂在系统 node 23 下不可用）
|
||
CORE="/c/Users/ybtdevxxl/.workbuddy/binaries/node/versions/22.22.2/corepack.cmd"
|
||
"$CORE" pnpm install # 安装依赖
|
||
"$CORE" pnpm dev:antd # 启动开发服务器
|
||
```
|
||
|
||
### 坑 1：NODE_OPTIONS 污染
|
||
- 现象：`pnpm install` 报 `[ERROR] [safe-delete] 操作失败 ... Some operations were aborted`
|
||
- 原因：环境变量 `NODE_OPTIONS=--require=...genie-safe-delete.cjs --use-system-ca`（WorkBuddy 注入）；且系统 Node 23 不支持 `--use-system-ca`，直接跑 PATH 里的 pnpm 会直接退出
|
||
- 解法：`unset NODE_OPTIONS` + 用 managed node 22.22.2 的 corepack
|
||
|
||
### 坑 2：Windows 符号链接权限
|
||
- 现象：`pnpm install` 报 `UNKNOWN: unknown error, symlink '.pnpm\postcss@8.5.26\...' -> ...`，下载完 1723 包后在 hoist 阶段失败
|
||
- 原因：本机未开「开发者模式/无管理员权限」，pnpm 默认 symlink 创建失败
|
||
- 解法：项目 `.npmrc` 已添加 `package-import-method=copy`（用拷贝替代符号链接，代价是磁盘占用/安装略慢）
|
||
|
||
### 镜像配置（.npmrc）
|
||
```ini
|
||
registry=https://registry.npmmirror.com
|
||
package-import-method=copy
|
||
```
|
||
|
||
## 4. 常用命令
|
||
|
||
```bash
|
||
# 依赖
|
||
pnpm install # 装依赖（preinstall 会校验必须用 pnpm；postinstall 跑 stub）
|
||
pnpm reinstall # 清 lock 重装（= clean --del-lock && install）
|
||
|
||
# 开发
|
||
pnpm dev:antd # 启动 web-antd（默认 http://localhost:5666）
|
||
pnpm dev # turbo 并行起所有 app
|
||
|
||
# 构建 / 检查
|
||
pnpm build:antd # 构建 web-antd
|
||
pnpm check:type # 类型检查（turbo run typecheck）
|
||
pnpm lint # 代码检查
|
||
pnpm test:unit # 单元测试（vitest）
|
||
```
|
||
|
||
## 5. 架构速览（Vben Admin 5 monorepo）
|
||
|
||
```
|
||
apps/ 应用层：web-antd（主）、web-ele、web-naive、web-tdesign、web-antdv-next、backend-mock
|
||
internal/ 内部工具：vite-config、tsconfig、eslint/stylelint/oxlint 配置、tailwind-config、turbo-run
|
||
packages/ 共享包：@core（核心 UI/布局）、effects（请求/权限/hooks/插件）、stores、locales、
|
||
preferences（偏好设置）、icons、constants、utils、styles、types
|
||
```
|
||
|
||
- 主应用源码入口：`apps/web-antd/src/`
|
||
- 路由：`src/router/routes/modules/`（dashboard.ts / demos.ts / vben.ts）
|
||
- 页面：`src/views/`
|
||
- API：`src/api/request.ts`（封装 `requestClient`）、`src/api/core/`
|
||
- 偏好：`src/preferences.ts`（`defineOverridesPreferences`，官方默认 + 少量扩展字段）
|
||
- 开发代理：`vite.config.ts` 中 `/api` → `http://localhost:5320/api`（backend-mock），rewrite 去掉 `/api` 前缀
|
||
- 环境变量：`apps/web-antd/.env.development`（`VITE_PORT=5666`、`VITE_NITRO_MOCK=true`、`VITE_GLOB_API_URL=/api`）
|
||
- 路径别名：`#/*` → `./src/*`（package.json imports）
|
||
|
||
### 关键开发约定（Vben 5 特有）
|
||
- 权限：`preferences.ts` 的 `app.accessMode`（frontend/backend/mixed）；按钮级用 `<AccessControl :codes>` / `hasAccessByRoles` / `v-access:code`
|
||
- API 请求：`requestClient.get/post<Type>(url)`，代理在 `vite.config.ts`
|
||
- 国际化：`$t()`，语言包在 `packages/locales`
|
||
- 主题：CSS 变量覆盖（`:root { --primary: ... }`），偏好里 `theme.builtinType/colorPrimary`
|
||
- 详细参考：本机已装 vben skill（`C:\Users\ybtdevxxl\.workbuddy\skills\vben`，含 20+ references）
|
||
|
||
## 6. 操作日志
|
||
|
||
> 倒序（最新在上）。每条：日期 / 操作 / 结果 / 备注
|
||
|
||
### 2026-08-24（首次搭建）
|
||
1. **梳理项目**：确认为 Vben Admin 5.7.0 官方模板克隆，无业务定制；主应用 web-antd（端口 5666）
|
||
2. **安装依赖**：
|
||
- 第 1 次失败：NODE_OPTIONS safe-delete shim 拦截 → 解法 `unset NODE_OPTIONS`
|
||
- 第 2 次失败：Windows symlink 权限 → 解法 `.npmrc` 加 `package-import-method=copy`
|
||
- 最终：`pnpm install` 成功（46 workspace 项目，1723 包）✅
|
||
3. **启动开发服务器**：`pnpm dev:antd` → 验证 http://localhost:5666 （状态见下）
|
||
4. **建立本文件 agents.md**：项目上下文档案 + 操作日志机制
|
||
5. **建立工作日志**：`.workbuddy/memory/YYYY-MM-DD.md`（每日记录，跨账号迁移时连同 agents.md 一起拷贝）
|
||
|
||
## 7. 迁移清单（换 WorkBuddy 账号 / 换机器时）
|
||
|
||
1. 拷贝整个项目目录（含 `node_modules` 可不拷，重新 install 即可）
|
||
2. 必拷文件：`agents.md`（本文件）+ `.workbuddy/memory/`（历史工作日志）
|
||
3. 本机环境要点（新机器）：
|
||
- Node ≥ 22.18；pnpm ≥ 11（corepack）
|
||
- 跑 pnpm 前 `unset NODE_OPTIONS`
|
||
- Windows 无开发者模式时保持 `.npmrc` 的 `package-import-method=copy`
|
||
4. 装依赖后先 `pnpm dev:antd` 验证 5666 端口
|