admin.xpcool.com/agents.md

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）已验证的运行方式 —— 直接复制可用

# 前置：把 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）

registry=https://registry.npmmirror.com
package-import-method=copy

4. 常用命令

# 依赖
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 端口