文档与目录导航
按目的阅读
| 目的 | 文档或 Skill |
|---|---|
| 五分钟跑起项目并接上自己的后端 | 快速开始 |
| 把模板能力接到消费项目（admin-shared 迁移） | 消费方迁移清单 |
| 启动项目、连接服务、添加业务页面、构建输出 | 使用指南 · docs/skills/ug-admin-usage/SKILL.md |
| 在独立网页阅读、搜索开发者使用说明 | bun run dev:docs → http://127.0.0.1:3400；正文仍维护在本目录 |
| 修改框架、双端页面、样式、工程与测试 | 开发指南 · .agents/skills/ug-admin-maintenance/SKILL.md |
| 清理未使用的文件、导出或依赖 | Knip 使用方法 · .agents/skills/ug-admin-maintenance/SKILL.md |
| 理解依赖、认证、数据与页面合同 | 架构 |
| 替换品牌、Logo、登录文案与产品存储空间 | 使用指南：品牌配置 |
| 对接真实登录、会话、数据格式与访问控制 | 后端 Adapter 合同 |
| 开发代理、生产部署、SPA 回退与模板升级 | 部署与升级 · configs/deploy/nginx.conf |
| 用户、部门、角色字段、权限及写入保护 | 基础管理合同 |
| 布局、层级、配色与视觉验收依据 | 管理界面设计依据 |
| 字典类型、条目、业务选项与历史值保护 | 字典合同 |
| 默认后台能力、稳定用户主体及新系统扩展方式 | 组织、用户与权限体系 |
| 成熟管理源码改编的固定来源与许可 | docs/legal/THIRD_PARTY_NOTICES.md |
| 自动化代理必须遵守的硬约束 | AGENTS.md |
文档说明用法和设计；Skill 负责执行顺序与任务分流；AGENTS 保存硬约束。命令以 mise.toml、package.json 为准，API 以当前源码和类型为准，不在多处复制组件或页面清单。
规则维护
| 需要维护的内容 | 主入口 | 其他位置如何引用 |
|---|---|---|
| 不可越过的产品与工程边界 | 根 AGENTS | Skill 和指南链接，不复制执行细节 |
| 分层、依赖方向、模块扩展方式 | 架构 | 检查器落实可静态判定的约束，Skill 指向对应章节 |
| 后端与系统领域合同 | 对应 Backend、Management、Dictionaries 文档 | 类型和实现同步变更，不再另写一套协议说明 |
| 工作顺序、定位和最小验证 | 维护 Skill 与开发指南 | Skill 负责分流，具体命令及分级验证集中在指南 |
| 消费项目使用流程 | 使用指南与公开使用 Skill | 保留独立阅读所需边界，不要求复制仓库维护流程 |
| 创建项目后的开发规则 | scripts/scaffold/templates/AGENTS.md.template |
创建器替换项目名和框架；维护源模板，不手改生成副本 |
处理冲突时先遵循当前用户要求及适用项目规则，再区分“实现事实”和“设计约束”：版本、导出和命令回源码核实；当前代码违反架构不能成为放宽边界的理由。过时文档修正到真实合同，必要的合同变化同时修改实现与直接消费者，不通过追加一条相反规则绕过问题。
更新顺序是归属判断、主入口、受影响的链接或分发模板、最小验证。只有真实且长期有效的约束才进入规则；任务经过、临时结果、猜测性扩展和测试次数不固化。不为每次修改新增文档、检查器或规则目录。
配置入口
| 要调整什么 | 事实源与说明 |
|---|---|
| 安装、开发、检查与资源脚手架命令 | mise.toml · package.json；执行方法见 开发指南 |
| 换行、缩进与二进制文件属性 | .editorconfig · .gitattributes；格式规则另见 biome.json |
| 格式与未使用代码检查 | configs/biome.json · configs/knip.json；Knip 判读见 开发指南 |
| 双端浏览器测试、端口与报告 | tests/playwright.config.ts；验收命令见 开发指南 |
| React/Vue 本地公开环境变量 | apps/react/.env.example · apps/vue/.env.example；含义与生产边界见 使用指南 |
| 应用开发端口、别名和构建行为 | apps/react/vite.config.ts · apps/vue/vite.config.ts；更改别名时同步各端 TypeScript 配置与测试 |
| 新项目创建、单端业务生成 | scripts/scaffold/create-project.ts · scripts/scaffold/scaffold-resource.ts；消费方法见 使用指南 |
| 项目品牌、Provider 与业务入口 | 各应用 src/project.ts、src/backend/index.ts 和 src/modules/<业务名>/index.ts；普通业务不修改共享核心 |
以配置文件为事实源；修改后同步受影响的使用、开发或后端接入文档，不在此复制易过期的默认值。关键任务的文档回写顺序见.agents/skills/ug-admin-maintenance/SKILL.md。
configs/ 集中 Biome 格式/检查规则和 Knip 扫描配置。根 biome.json 仅保留自动发现入口、继承声明和仓库扫描范围，规则通过 extends 加载 configs/biome.json；Knip 通过现有 check:unused 命令加载 configs/knip.json，workspace 和 glob 仍相对仓库根目录。两项配置的 JSON Schema 使用已安装工具的本地文件，避免编辑器依赖远程 Schema。Playwright 通过 e2e 命令加载 tests/playwright.config.ts，服务工作目录和报告路径固定相对仓库根目录。Vite/TypeScript 配置留在各应用旁，避免改变应用根路径、别名和缓存位置。根锁文件与 workspace 清单继续服务双端构建。
第三方源码来源与许可的唯一原文在 docs/legal/THIRD_PARTY_NOTICES.md；双端 Vite 构建将它与 UG UI 包的声明合并，输出到各自 dist/THIRD_PARTY_NOTICES.txt。迁移原文时同步构建读取路径和文档链接，分发产物保留完整声明。
目录地图
| 目录 | 放什么 | 不放什么 |
|---|---|---|
apps/react、apps/vue |
独立应用、路由、页面、原生状态适配与对应单元测试 | 另一框架运行时、复制的 UG UI 基础组件 |
apps/docs |
独立开发者文档站，目录、搜索、Markdown 构建与阅读布局 | 后台业务功能、认证、第二份使用说明正文 |
packages/admin-core |
双端共同的框架无关合同、品牌、基础管理模型、共享样式、示例模型与测试夹具 | React/Vue 组件、仅一端使用的业务状态 |
tests/e2e |
双端真实浏览器场景与共享辅助函数 | 截图、报告、Trace |
configs |
跨工作区的 Biome 规则与 Knip 扫描配置 | 应用专属 Vite/TypeScript 配置 |
scripts/checks |
架构、仓库卫生和生产产物检查及其测试 | 一次性诊断 |
scripts/dev |
本地 UG UI 联调工具 | 生产依赖或部署配置 |
scripts/scaffold |
资源生成器及其测试 | 已生成的业务源码 |
scripts/testing |
工程测试的隔离工作区辅助 | 运行产物 |
docs |
使用、开发和架构合同 | 每次任务的进度日志 |
docs/legal |
第三方源码来源与许可原文，供双端构建分发 | 生成的声明副本 |
docs/skills |
面向模板使用方的公开接入 Skill | 仓库维护规则 |
.agents/skills |
仓库维护工作流 | 全局配置、重复的公开使用指南 |
temp/<task> |
诊断、报告、导出与一次性产物 | 必须保留的源码和文档 |
packages/admin-core、packages/admin-react、packages/admin-vue 都已登记为 Bun workspace 包，依赖在各自 package.json 声明：
admin-core：框架无关合同（路由、权限、数据契约、管理模型、i18n、视口与表格形态配置、共享样式）admin-react/admin-vue：页面壳与组合模式（AdminPage、AdminListPage、AdminFormPage、AdminDetailPage、搜索与确认）- 业务模块与壳层实现留在各端
apps/*/src；项目通过@ug666/admin-*子路径引用
新增包或移动目录时同步更新三个包的 package.json、两个应用的 tsconfig paths 与 vite 别名、configs/knip.json 的 workspace 条目，以及脚手架模板里的引用。
共享源码按职责归入下列目录，根目录不再堆放实现文件，也不保留旧路径转发层；消费方使用 @ug666/admin-core/<职责>/<文件>。
| 共享目录 | 职责 |
|---|---|
config/ |
环境模式、模块开关、品牌、偏好与壳层默认配置 |
auth/ |
身份与权限合同、HTTP 认证适配 |
data/ |
数据合同、HTTP 客户端、REST 适配、扩展 Provider 合同 |
routing/ |
页面声明、导航、面包屑和页签 |
management/ |
用户、部门、角色、系统页面、首页统计及写后会话复核 |
dictionaries/ |
字典模型、选项、查询与校验 |
demo/ |
可选示例的任务、看板与展示数据合同 |
testing/ |
演示适配器、内存 Provider 和测试夹具 |
styles/ |
共享样式与有序入口 |
当前没有公开 Skill 的 ZIP 下载或构建复制链路；使用方通过仓库阅读 docs/skills/ug-admin-usage/SKILL.md 及其相对引用的文档。无需为目录整理新增下载服务或打包流程。
共享包中，routing/types.ts 定义路由类型、系统模块在 management/pages.ts 登记页面，routing/admin-pages.ts 保持消费入口；config/app-modules.ts 控制启动模块，management/presentation.ts 提供核心入口、账户与偏好字段合同，management/overview.ts 提供首页统计的权限过滤与有界列表查询；config/brand.ts 配置产品身份，management/ 保存正式基础管理合同，testing/ 保存仅演示使用的实现；styles/app.css 是按职责拆分的有序样式入口。工程测试的临时目录生命周期统一由 scripts/testing/workspace.ts 管理。
如何保持清晰
新文件按职责归位。维护源码可以随消费方或职责拆分，但保留稳定入口和可追踪引用，不能仅因文件长或目录内文件少就删掉。新增目录时先证明现有职责目录无法容纳。
清理先列出精确目标，核对 Git 跟踪、导入、配置、文档和外部使用入口。编译型引用检查不能证明动态路径或文档文件可删除。生成物保持忽略；依赖目录按用户约定保留，不能用清依赖替代整理源码。
从仓库根启动代理可发现 .agents/skills 中的维护工作流；公开使用 Skill 从 docs/skills 显式读取。从父级多仓目录工作时按本页入口读取对应 Skill。只更新发生变化的合同及其入口链接，不记录短期测试数量或提交编号作为永久规则。