From 85b5fc628dbdfad61b40ad7b2a384763cb295c61 Mon Sep 17 00:00:00 2001 From: XiaoDaiGua-Ray <51957438+XiaoDaiGua-Ray@users.noreply.github.com> Date: Wed, 4 Nov 2026 16:47:18 +0800 Subject: [PATCH] feat(harness): add task-oriented repository index --- AGENTS.md | 8 +- README.md | 2 +- README.zh-CN.md | 2 +- __test__/harness/cli.spec.ts | 117 ++++++++++++++++++++++----- apps/docs/guide/tooling.md | 30 +++---- docs/architecture.md | 102 ++++++++++------------- docs/docs-handoff.md | 22 ++--- harness/README.md | 24 +++--- harness/context/api.md | 14 ++++ harness/context/docs.md | 14 ++++ harness/context/harness.md | 13 +++ harness/context/icons.md | 13 +++ harness/context/layout.md | 14 ++++ harness/context/routing.md | 14 ++++ harness/context/table-pro.md | 14 ++++ harness/context/toolchain.md | 14 ++++ harness/context/ui.md | 15 ++++ harness/context/utils.md | 14 ++++ harness/plan.md | 28 +++++++ harness/run.mjs | 152 +++++++++++++++++++++++++++++------ harness/scopes.json | 108 ++++++++++--------------- llms.txt | 38 ++++----- 22 files changed, 539 insertions(+), 233 deletions(-) create mode 100644 harness/context/api.md create mode 100644 harness/context/docs.md create mode 100644 harness/context/harness.md create mode 100644 harness/context/icons.md create mode 100644 harness/context/layout.md create mode 100644 harness/context/routing.md create mode 100644 harness/context/table-pro.md create mode 100644 harness/context/toolchain.md create mode 100644 harness/context/ui.md create mode 100644 harness/context/utils.md diff --git a/AGENTS.md b/AGENTS.md index 9a6e2966..0ea1faaa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,9 @@ # Ray Template -Vue 3 + TSX 中后台模板。项目协作、定向验证和交付证据统一从 [AI Harness](harness/README.md) 开始。按任务选择上下文,不必通读仓库。 +Vue 3 + TSX 中后台模板,包含后台应用、文档站与共享包。 -- `pnpm harness context` 列出任务域。`pnpm harness context ` 给出入口、约定与回归命令。跨模块变更可查 [架构地图](docs/architecture.md)。 +- 需要定位实现时,从 [任务索引](llms.txt) 或 `pnpm harness context ` 选相关主题。跨模块变更再查 [架构地图](docs/architecture.md)。 - 先看 `git status`,保留已有改动。变更路由、持久化、请求或公共组件时,追踪调用方和现有数据契约。 -- 新增或修改注释时遵循 [注释规范](docs/comment-style.md)。页面文案同时维护中英文,页面改动按 Harness 指南验收。 -- 完成实现后运行 `pnpm harness verify`。它执行 `pnpm check` 并留存结果。交付说明实际验证及未验证项。 +- 新增或修改注释时遵循 [注释规范](docs/comment-style.md)。页面文案同时维护中英文,页面改动按 [Harness 指南](harness/README.md#浏览器验收) 验收。 +- 完成实现后运行 `pnpm harness verify`,执行全量检查并留存报告。交付说明实际验证及未验证项。 - 使用当前源码、清单和锁文件核对工程事实。敏感数据不进入源码、提示词或证据。提交、推送与部署遵循用户授权。 diff --git a/README.md b/README.md index ef0e46a3..ebafc541 100644 --- a/README.md +++ b/README.md @@ -134,4 +134,4 @@ Use the [architecture map](docs/architecture.md) to find module and configuratio [MIT License](LICENSE) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/XiaoDaiGua-Ray/ray-template/issues) -Agents can start with the [LLM entry point](llms.txt) and open only the relevant task scope. +Use the [task index](llms.txt) to find the owning implementation, its consumers, and verification steps without installing dependencies. `pnpm harness context ` shows the same index entry alongside the commands it runs. diff --git a/README.zh-CN.md b/README.zh-CN.md index 9ff3bcf4..67cd6f36 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -134,4 +134,4 @@ export default defineComponent({ [MIT 许可证](LICENSE) · [更新日志](CHANGELOG.md) · [问题反馈](https://github.com/XiaoDaiGua-Ray/ray-template/issues) -AI 助手可从 [LLM 入口](llms.txt) 按任务读取源码和验证命令。 +从[任务索引](llms.txt)查找实现归属、调用方和验证方式,无需安装依赖。`pnpm harness context ` 显示同一份索引及验证命令。 diff --git a/__test__/harness/cli.spec.ts b/__test__/harness/cli.spec.ts index 0d73f869..e0f609a2 100644 --- a/__test__/harness/cli.spec.ts +++ b/__test__/harness/cli.spec.ts @@ -17,26 +17,31 @@ let fixture: string beforeEach(() => { fixture = mkdtempSync(join(tmpdir(), 'ray-harness-')) - mkdirSync(join(fixture, 'harness')) + mkdirSync(join(fixture, 'harness/context'), { recursive: true }) + mkdirSync(join(fixture, 'docs')) mkdirSync(join(fixture, '__test__/demo'), { recursive: true }) copyFileSync( new URL('../../harness/run.mjs', import.meta.url), join(fixture, 'harness/run.mjs'), ) + + for (const path of [ + 'AGENTS.md', + 'docs/architecture.md', + 'docs/docs-handoff.md', + 'harness/README.md', + 'harness/plan.md', + ]) { + writeFileSync(join(fixture, path), '# Fixture\n') + } + + writeFileSync(join(fixture, 'llms.txt'), '[Demo](harness/context/demo.md)\n') writeFileSync( - join(fixture, 'harness/scopes.json'), - JSON.stringify({ - demo: { - description: 'Demo', - paths: ['harness'], - tests: ['__test__/demo/'], - }, - }), - ) - writeFileSync( - join(fixture, 'package.json'), - JSON.stringify({ scripts: { 'env:check': 'node -e "process.exit(23)"' } }), + join(fixture, 'harness/context/demo.md'), + '# Demo\n\n先读 [架构](../../docs/architecture.md#fixture)。\n', ) + writeScope({ tests: ['__test__/demo/'] }) + writeScripts({ 'env:check': 'node -e "process.exit(23)"' }) }) afterEach(() => { @@ -50,6 +55,26 @@ function run(...args: string[]) { }) } +function writeScope(targets: { tests?: string[]; checks?: string[] }) { + writeFileSync( + join(fixture, 'harness/scopes.json'), + JSON.stringify({ demo: { description: 'Demo', ...targets } }), + ) +} + +function writeScripts(scripts: Record) { + writeFileSync(join(fixture, 'package.json'), JSON.stringify({ scripts })) +} + +function readReport() { + const runs = join(fixture, '.harness-local/runs') + const [runDirectory] = readdirSync(runs) + + return JSON.parse( + readFileSync(join(runs, runDirectory, 'report.json'), 'utf8'), + ) +} + it('拒绝没有回归用例的目录', () => { const result = run('check') @@ -57,18 +82,72 @@ it('拒绝没有回归用例的目录', () => { expect(result.stderr).toContain('回归测试路径没有用例:__test__/demo/') }) +it('移动索引引用的实现后,检查会报告来源与断链', () => { + writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '') + expect(run('check').status).toBe(0) + + rmSync(join(fixture, 'docs/architecture.md')) + const result = run('check') + + expect(result.status).toBe(1) + expect(result.stderr).toContain( + 'harness/context/demo.md 的相对链接无效:../../docs/architecture.md#fixture', + ) +}) + +it('拒绝未从静态入口链接的已注册主题', () => { + writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '') + writeFileSync(join(fixture, 'llms.txt'), '# 空入口\n') + const result = run('check') + + expect(result.status).toBe(1) + expect(result.stderr).toContain('llms.txt 缺少可用的主题链接') +}) + +it('无 Vitest 的任务域能展示索引并执行现有项目检查', () => { + writeScope({ checks: ['docs:check'] }) + writeScripts({ + 'env:check': 'node --version', + 'docs:check': 'node -e "console.log(process.cwd())"', + }) + + expect(run('check').status).toBe(0) + const context = run('context', 'demo') + + expect(context.status).toBe(0) + expect(context.stdout).toContain( + '先读 [架构](../../docs/architecture.md#fixture)', + ) + expect(context.stdout).toContain('pnpm docs:check') + + expect(run('verify', 'demo').status).toBe(0) + expect(readReport()).toMatchObject({ + scope: 'demo', + status: 'passed', + steps: [ + { command: 'pnpm env:check', exitCode: 0 }, + { command: 'pnpm docs:check', exitCode: 0 }, + ], + }) +}) + +it('拒绝把全量检查登记为定向检查,避免递归调用', () => { + writeScope({ checks: ['check'] }) + writeScripts({ check: 'node harness/run.mjs check' }) + + const result = run('verify', 'demo') + + expect(result.status).toBe(1) + expect(result.stderr).toContain('demo 的检查命令未注册:check') +}) + it('子命令失败时停止后续验证,并记录失败状态', () => { writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '') const result = run('verify', 'demo') - const runs = join(fixture, '.harness-local/runs') - const [runDirectory] = readdirSync(runs) - const report = JSON.parse( - readFileSync(join(runs, runDirectory, 'report.json'), 'utf8'), - ) expect(result.status).toBe(23) - expect(report).toMatchObject({ + expect(readReport()).toMatchObject({ scope: 'demo', status: 'failed', steps: [{ command: 'pnpm env:check', exitCode: 23 }], diff --git a/apps/docs/guide/tooling.md b/apps/docs/guide/tooling.md index 1acdc5dd..7a6b2763 100644 --- a/apps/docs/guide/tooling.md +++ b/apps/docs/guide/tooling.md @@ -2,21 +2,21 @@ ## 常用命令 -| 命令 | 用途 | -| -------------------------------- | ---------------------------------------------------------- | -| `pnpm env:check` | 校验 Node、pnpm 与依赖安装 | -| `pnpm dev` | 同步图标清单并启动 Vite | -| `pnpm harness context` | 查任务域;追加 `routing`、`ui`、`api` 等可看实现入口和回归 | -| `pnpm harness verify ui` | 按域运行定向测试 | -| `pnpm harness verify` | 运行全量检查并生成本地报告 | -| `pnpm typecheck` | 验证图标清单,检查应用、Node 配置和测试类型 | -| `pnpm dev-build` / `pnpm report` | 构建开发版,或输出静态打包报告 | -| `pnpm build` / `pnpm preview` | 构建并在本机验收产物 | -| `pnpm packages:check` | 检查公开入口、依赖声明和循环依赖 | -| `pnpm pages:build` | 将后台与文档组装到 `dist/pages` | -| `pnpm docs:dev` | 启动文档开发站 | -| `pnpm docs:check` | 验证文档示例类型、站内链接与生产构建 | -| `pnpm docs:preview` | 预览已构建的文档站 | +| 命令 | 用途 | +| -------------------------------- | -------------------------------------------------------------- | +| `pnpm env:check` | 校验 Node、pnpm 与依赖安装 | +| `pnpm dev` | 同步图标清单并启动 Vite | +| `pnpm harness context` | 查任务域;追加 `routing`、`table-pro`、`docs` 等查看实现与验证 | +| `pnpm harness verify table-pro` | 按域运行定向测试或项目检查 | +| `pnpm harness verify` | 运行全量检查并生成本地报告 | +| `pnpm typecheck` | 验证图标清单,检查应用、Node 配置和测试类型 | +| `pnpm dev-build` / `pnpm report` | 构建开发版,或输出静态打包报告 | +| `pnpm build` / `pnpm preview` | 构建并在本机验收产物 | +| `pnpm packages:check` | 检查公开入口、依赖声明和循环依赖 | +| `pnpm pages:build` | 将后台与文档组装到 `dist/pages` | +| `pnpm docs:dev` | 启动文档开发站 | +| `pnpm docs:check` | 验证文档示例类型、站内链接与生产构建 | +| `pnpm docs:preview` | 预览已构建的文档站 | 全量检查包含环境、Harness、图标同步、类型、ESLint、Prettier、Vitest 和生产构建。Harness 在 `.harness-local/runs/` 写结果;Chrome 验收单独记录。改动交互或布局时,额外验收中英文、明暗主题和窄屏。 diff --git a/docs/architecture.md b/docs/architecture.md index a0a6429a..648911dc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,79 +1,63 @@ # 架构地图 -Ray Template 是前端中后台模板,包含可运行的组件与路由示例。Mock 只用于演示;接入真实业务时需要自己的后端、会话和权限校验。 +Ray Template 是一个 pnpm workspace:后台负责宿主集成,文档站解释公开用法,共享包拥有可复用实现。按功能定位文件从[任务索引](../llms.txt)进入;本页用于判断代码归属和追踪跨模块调用。 -Ray Template 由一个 pnpm workspace 管理。**Ray Admin** 位于 `apps/admin`,在应用入口接入路由、会话、主题和数据。**文档**位于 [apps/docs](../apps/docs/README.md),直接使用共享包的公开入口。 +## 工作区 -| 工作区 | 公开职责 | -| --------------------------- | -------------------------------------------------------------------------------- | -| `@ray-template/utils` | 精度、类型判断、数据与文件工具,以及接收存储实现的 JSON 读写。 | -| `@ray-template/composables` | 可独立使用的 Vue Hooks、元素与作用域工具。 | -| `@ray-template/directives` | Vue 指令与注册器。复制提示由宿主提供。 | -| `@ray-template/icons` | SVG 资源、清单、图标名称类型与查询。 | -| `@ray-template/ui` | 可复用组件及主题样式。TablePro、图表和条码支持按入口导入。 | -| `@ray-template/http` | 每个客户端独立的请求拦截和取消。 | -| `@ray-template/routing` | 路由配置校验、路由展开和菜单遍历。页面注册表由应用传入。 | -| `@ray-template/admin-shell` | 布局框架、布局设置、路由过渡和页面缓存渲染。宿主传入导航、内容、偏好和路由状态。 | +| 目录 | 职责与权威入口 | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| [apps/admin](../apps/admin) | Ray Admin。应用配置、路由注册、Pinia、Provider、页面、演示数据与开发 Mock。Vite 的应用根目录是这里。 | +| [apps/docs](../apps/docs/README.md) | VitePress 站点。读者指南、API、迁移和交互示例,消费共享包公开入口。 | +| [packages](../packages) | 下表列出的共享包;根入口和可导入子路径由各自的 `package.json#exports` 定义。 | +| [**test**](../__test__) | Vitest 回归,按行为分类而非逐一镜像源码目录。通过 [Harness 任务域](../harness/scopes.json) 反查覆盖。 | +| [docs](./)、[harness](../harness/README.md) | 维护者约定与跨模块说明;Harness 管理任务导航、定向验证与证据。对外文档属于 `apps/docs`。 | +| [scripts](../scripts)、[vite-helper](../vite-helper)、[unplugin](../unplugin) | 仓库级检查、Vite 插件辅助和自动导入的生成声明。根目录保留构建、类型和 CI 配置。 | -应用的 `@/components`、`@/hooks` 和 `@/utils` 继续作为模板中的导入入口。共享包声明直接依赖,公开入口通过 `exports` 控制。`pnpm packages:check` 检查跨包导入和循环依赖,独立 TypeScript 项目检查共享包能脱离应用的路径别名和全局声明。 +| 共享包 | 实现归属 | 宿主边界 | +| ----------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------- | +| [@ray-template/utils](../packages/utils/package.json) | 精度、类型判断、数据与文件工具、通用 JSON 存储 | 调用方提供 Storage;应用的 key、缓存后端和旧 AES 格式留在应用。 | +| [@ray-template/composables](../packages/composables/package.json) | Vue 组合式函数、DOM、元素与作用域工具 | 应用专用导航、主题和内容区 Hooks 留在应用。 | +| [@ray-template/directives](../packages/directives/package.json) | Vue 指令与注册器 | 宿主提供复制提示,并选择何时注册。 | +| [@ray-template/icons](../packages/icons/package.json) | SVG、清单、图标名类型与查询 | 构建将资源生成雪碧图,宿主提供图标解析服务。 | +| [@ray-template/ui](../packages/ui/package.json) | 通用组件、共享主题及 UI 服务接口 | 后台注入翻译、主题、存储等;应用组件入口转导出通用组件。 | +| [@ray-template/http](../packages/http/package.json) | 独立 HTTP 客户端、拦截器和取消机制 | 应用传入请求配置和拦截器,封装实际业务 API。 | +| [@ray-template/routing](../packages/routing/package.json) | 路由配置校验、路由展开和菜单遍历 | 应用持有页面注册表、配置来源、角色、会话和守卫。 | +| [@ray-template/admin-shell](../packages/admin-shell/package.json) | 布局外壳、布局设置、过渡与页面缓存渲染 | 宿主提供路由状态、偏好、导航和内容插槽。 | -## 启动链路 +应用侧 `@/components`、`@/hooks`、`@/utils` 有兼容入口。跟随实际导出判断实现归属。共享包不可依赖后台别名或跨 workspace 相对导入;[包边界检查](../scripts/check-package-boundaries.mjs)校验依赖声明、公开入口和循环依赖。 -`apps/admin/index.html` → `apps/admin/src/main.ts` → Pinia → 国际化 → Router → Day.js → 全局指令 → `App.tsx`。`main.ts` 同时保留无界微前端挂载和卸载入口;调整启动顺序时检查这两条路径。 +## 关键运行链路 -`src/App.tsx` 组合全局 Provider 与布局。布局位于 `src/layout`;全局 Naive UI 消息等实例由 `src/app-components/provider` 提供。不要在 Provider 初始化前使用 `window.$message` 等对象。 +| 链路 | 调用顺序与边界 | 继续阅读 | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| 后台启动 | [index.html](../apps/admin/index.html) → [main.ts](../apps/admin/src/main.ts) → Pinia → 国际化 → Router → Day.js → 指令与自动补全设置 → 挂载 [App.tsx](../apps/admin/src/App.tsx)。普通和无界模式共用插件注册顺序。 | [布局与启动](../harness/context/layout.md) | +| 导航与缓存 | [路由初始化](../apps/admin/src/router/index.ts)加载来源 → [应用模块](../apps/admin/src/router/app-route-modules.ts)展开配置 → 注册守卫和页面 → 应用菜单 Store 与布局消费路由。应用维护缓存名单,共享壳渲染过渡与 KeepAlive。 | [路由](../harness/context/routing.md)、[布局](../harness/context/layout.md) | +| 请求与演示数据 | [API](../apps/admin/src/api) → [应用 Axios 实例](../apps/admin/src/axios/instance.ts) → [共享客户端](../packages/http/src/client.ts)。开发 Mock 走 HTTP;静态人员演示可用本地数据。生产会话和资源授权由接入方后端负责。 | [API](../harness/context/api.md) | +| 文档示例 | 文档可直接消费共享包;需要后台上下文时由 [AdminExample.vue](../apps/docs/examples/AdminExample.vue) 嵌入 [example.html](../apps/admin/example.html),使用独立启动、限定路由和内存缓存。 | [文档与示例](../harness/context/docs.md) | +| 应用配置 | [Vite](../vite.config.ts) 注入 `__APP_CFG__` 和 `__DEV__`;[应用配置](../apps/admin/src/app-config)按设计、请求、路由和缓存分组。 | [构建与工具链](../harness/context/toolchain.md) | -## 模块与扩展入口 - -| 需求 | 入口 | 相关约定 | -| -------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| 新增页面与菜单 | `src/views`、`src/router/modules` | [路由文档](../apps/admin/src/router/README.md),菜单由路由生成 | -| 权限与守卫 | `src/router/utils/vue-router-register.ts`、`src/router/utils/permission.ts` | 同时检查菜单显示与实际导航;前端权限不能替代后端授权 | -| 全局状态 | `src/store/modules`、`src/store/hooks` | [Store 文档](../apps/admin/src/store/README.md),持久化配置使用 `pick`/`omit` | -| 请求与接口 | `src/api`、`src/axios` | [请求文档](../apps/admin/src/axios/README.md),请求/响应拦截器分开注册 | -| 演示接口 | `mock/demo`、`src/demo-data` | `vite-plugin-mock-dev-server`,生产环境按实际后端切换 | -| 通用组件 | `src/components` | 组件、props、types、hook、样式放在同一功能目录 | -| 模板绑定组件 | `src/app-components` | [组件说明](../apps/admin/src/app-components/README.md) | -| 公共工具 | `src/utils` | [分包、兼容入口和测试](../apps/admin/src/utils/README.md) | -| 组合式函数 | `src/hooks/web`、`template`、`components` | [19 个 Hook 的示例与生命周期](../apps/admin/src/hooks/README.md),回归测试在 `__test__/hooks` | -| 国际化 | `src/locales/lang`、`src/hooks/web/useI18n.ts` | [国际化说明](../apps/admin/src/locales/README.md),中文和英文成对维护 | -| 主题与全局样式 | `src/app-config/design-config.ts`、`src/styles` | 保留 CSS 变量和 Naive UI 明暗主题配置 | -| SVG 图标 | `src/icons`、`RIcon` | [图标说明](../packages/icons/src/A_README.md),名称与分包约定影响 symbol ID | -| 全局指令 | `src/directives/modules` | [注册约定](../apps/admin/src/directives/README.md)、[用法](../apps/admin/src/directives/README.DIR.md) | -| 构建与插件 | `vite.config.ts`、`vite.plugin.config.ts`、`vite.custom.config.ts` | 部署 base、输出目录、CDN、开发代理均在配置中管理 | -| 自动导入 | `vite.plugin.config.ts`、`unplugin` | 首次构建可更新生成声明;生成声明需要随对应依赖变化一起提交 | -| 测试 | `__test__`、`vitest.config.ts` | Happy DOM 单元测试,不能证明真实浏览器布局、下载或打印正确 | - -## 数据与调用约束 - -- `src/app-config` 管理模板配置。运行时 `__APP_CFG__` 由 Vite 注入;`__DEV__` 表示 development 模式。 -- 路径别名 `@`、`@api`、`@images`、`@mock` 在 Vite 和 TypeScript 中必须一致。 -- `src/store/hooks` 是已有业务对 Store 的访问层;所有全局可变 UI 状态统一归入 Pinia:临时状态由 `runtime` 管理且不持久化,布局偏好在 `setting.layoutConfig` 中沿用原缓存 key。 -- `src/utils/legacy-crypto`(原 `src/utils/c`)仍使用 CryptoJS 4.2.0 的同步 AES 格式。改用 Web Crypto 前需设计异步接口和历史密文迁移,不能直接替换并让既有数据无法解密。 -- 演示页与业务组件同样属于模板能力。删除 demo 或更换第三方库前需要明确任务范围;升级工具链时应保留示例功能。 - -布局模式、配置与插槽见 [布局说明](../apps/admin/src/layout/README.md)。图标按包生成独立雪碧图,完整名称和严格类型由 `scripts/icons.mjs` 统一生成。 - -页面标题、配色与示例排版见 [视觉与排版](ui-design.md);注释位置与格式遵循 [注释规范](comment-style.md)。 +公开行为变更按[应用与文档联动](docs-handoff.md)维护指南和可运行示例。页面排版见[视觉与排版](ui-design.md);代码注释见[注释规范](comment-style.md)。 ## TypeScript 项目配置 -[根配置](../tsconfig.json) 引用应用、Node 和测试项目。严格模式、模块解析和类型检查别名集中在 [共享配置](../tsconfig.base.json)。修改别名时同步更新 `vite.custom.config.ts`。 +[根配置](../tsconfig.json)引用四个项目。严格模式、模块解析和类型检查别名集中在[共享配置](../tsconfig.base.json)。调整路径别名时同步核对 [Vite](../vite.custom.config.ts) 和 [Vitest](../vitest.config.ts)。 -| 配置 | 检查范围 | -| ----------------------------- | -------------------------------------------------- | -| [应用](../tsconfig.app.json) | `src`、Vue JSX 与自动生成声明 | -| [Node](../tsconfig.node.json) | 构建与测试配置、`vite-helper`、`mock` | -| [测试](../tsconfig.test.json) | `__test__` 与引用源码,加载 Happy DOM 和 Node 类型 | +| 配置 | 检查范围 | +| ------------------------------------ | ----------------------------------------------------------------------------------------- | +| [应用](../tsconfig.app.json) | 后台 `apps/admin/src`、Vue JSX 和生成声明。 | +| [Node](../tsconfig.node.json) | 根构建与测试配置、`vite-helper`、后台 Mock。 | +| [测试](../tsconfig.test.json) | `__test__` 与引用源码,加载 Vitest 和 Node 类型。运行时环境由 Vitest 配置及测试文件决定。 | +| [共享包](../tsconfig.packages.json) | `packages/*/src`,不继承应用别名或自动导入声明。 | +| [文档站](../apps/docs/tsconfig.json) | 独立检查文档示例,由 `pnpm docs:check` 执行。 | -`pnpm typecheck` 通过 `vue-tsc --build` 检查三个项目,增量缓存存放于 `node_modules/.cache/ray-template/`。需要完整重查时使用 `pnpm exec vue-tsc --build --force`。单独检查应用或测试可用 `pnpm exec vue-tsc -p tsconfig.app.json` 或 `pnpm exec vue-tsc -p tsconfig.test.json`,Node 配置可用 `pnpm exec tsc -p tsconfig.node.json`。 +`pnpm typecheck` 先检查图标同步,再通过 `vue-tsc --build` 检查根配置引用的四个项目;增量缓存位于 `node_modules/.cache/ray-template/`。单独检查可使用 `pnpm exec vue-tsc -p <配置文件>`。 ## Deployment and search discovery -`pnpm build` 生成 `dist/production`,`pnpm pages:build` 将后台与文档组合到 `dist/pages`;将该目录的内容部署到 `vite.custom.config.ts` 中 `base` 对应的路径。默认路径为 `/ray-template/`,部署在域名根目录时改用 `/`。 +`pnpm build` 生成后台 `dist/production`;`pnpm docs:build` 生成 `apps/docs/.vitepress/dist`。`pnpm pages:build` 将两者合并到 `dist/pages`,文档放在其 `docs/` 下。后台默认 base 为 `/ray-template/`,文档默认 base 为 `/ray-template/docs/`。自建根路径或其他子路径时,同步核对[后台 base](../vite.custom.config.ts)、[文档 base](../apps/docs/.vitepress/config.mts)和[旧站跳转目标](../scripts/assemble-pages.mjs)。 -从 `dist` 分支发布 GitHub Pages 时,Vite 会将 `public/.nojekyll` 复制到产物根目录。手动上传产物时也要保留此文件,让 Pages 跳过 Jekyll,避免过滤 `_toKey-*.js` 等以下划线开头的文件。[GitHub Pages 发布说明](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) +[CI](../.github/workflows/ci.yaml)在主分支检查通过后将组合产物发布到 `dist` 分支。[后台 public 中的 .nojekyll](../apps/admin/public/.nojekyll)会随产物复制;手动部署到 Pages 时保留它,以便加载带下划线前缀的资源。 -官方 GitHub Pages 部署会设置 `RAY_TEMPLATE_SITE_ORIGIN=https://xiaodaigua-ray.github.io`。如需让自己的公开部署被搜索引擎检索,在生产构建中设置该变量为实际站点源地址,例如 `https://example.com`,路径由 Vite 的 `base` 提供。在 fork 的 GitHub Actions 中可以使用同名的仓库变量。未设置时,构建输出 `noindex`,适合预览和内部部署。 +公开构建用 `RAY_TEMPLATE_SITE_ORIGIN` 配置实际站点源地址,路径由 base 提供。未设置时,后台生产构建输出 `noindex`。公开后台首页生成 canonical、分享预览和 `sitemap.xml`,不把登录后的 hash 路由列为公开页面。域名级抓取规则由站点根目录的 `/robots.txt` 管理。站内旧链接由 [VitePress 映射](../apps/docs/.vitepress/legacy.mts)生成;配置站点源地址时,合并脚本另生成 `dist/legacy-docs`,供旧站迁移使用。 -公开构建在 HTML 中输出页面描述、规范链接(canonical)和分享预览,并生成 `sitemap.xml`。站点地图只列出公开首页;登录后的 hash 路由仍用作交互演示。可在 [Google Search Console](https://search.google.com/search-console/about) 提交部署路径下的 sitemap。若管理整个域名,也可从域名根目录的 `/robots.txt` 指向 sitemap;子目录里的 `robots.txt` 不会被识别。 +只阅读已跟踪的源码和配置来判断实现。生成产物、依赖、缓存和 `.harness-local/` 报告适合查构建与验证结果。 diff --git a/docs/docs-handoff.md b/docs/docs-handoff.md index d8974a9c..73fc9efd 100644 --- a/docs/docs-handoff.md +++ b/docs/docs-handoff.md @@ -4,25 +4,25 @@ 官网当前面向 v6,源码链接使用 Monorepo 路径,发布构建时用 `RAY_TEMPLATE_SOURCE_REF` 固定到发布提交。页内示例随工作区源码构建。v5 的源码与发布标签见[版本分界](../apps/docs/migration.md)。 -| 领域 | 应用侧证据 | 必须交代的边界 | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 组件入口与 TablePro | [公开导出](../apps/admin/src/components/index.ts)、[TablePro 契约](../apps/admin/src/components/RTablePro/README.md)、[表格示例](../apps/admin/src/views/demo/tables) | `base/`、`pro/` 深层路径失效;`RTable`、`useTable` 已移除。`useTablePro` 保留注册写法,提供 `isReady` 和当前页取数。远端 `total` 是筛选后的总数;取消依赖请求函数传递 signal;导出和打印默认仅当前页可见数据列。 | -| 路由与权限 | [路由说明](../apps/admin/src/router/README.md)、[路由类型](../apps/admin/src/router/types.ts)、[权限守卫](../apps/admin/src/router/utils/permission.ts) | 菜单显隐不等于访问授权;会话和接口权限由后端校验。缓存需要路由 name 对应组件 name,验证菜单进入、直达和刷新。 | -| 布局与 Pinia | [布局插槽和偏好](../apps/admin/src/layout/README.md)、[Store 约定](../apps/admin/src/store/README.md) | 全局 UI 单例已迁入 `runtime`,不持久化。保留历史设置和锁屏格式;自定义内容插槽时,由接入方负责保留请求取消及路由缓存。 | -| 请求与 Mock | [Axios 实现](../apps/admin/src/axios/instance.ts)、[取消器](../apps/admin/src/axios/utils/RequestCanceler.ts)、[人员查询](../apps/admin/src/api/demo/mock/person.ts) | 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。Mock HTTP 仅用于开发,静态演示有独立本地数据分支。 | -| Hooks、工具与图标 | [Hooks 行为](../apps/admin/src/hooks/README.md)、[工具兼容入口](../apps/admin/src/utils/README.md)、[图标生成](../packages/icons/src/A_README.md) | `@/hooks` 与 `@/utils` 公共入口保留;旧裸图标仅在缓存读取边界按唯一名称迁移。截图和打印测试不代表原生浏览器能力验收。 | -| 工具链与部署 | [工具链记录](toolchain-upgrade.md)、[架构地图](architecture.md)、[Vite 配置](../vite.custom.config.ts) | Node/pnpm 以清单为准。应用 base 为 `/ray-template/`,内置文档为 `/ray-template/docs/`。已发布旧站仍使用 `/ray-template-doc/`。 | +| 领域 | 应用侧证据 | 必须交代的边界 | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 组件入口与 TablePro | [公开导出](../apps/admin/src/components/index.ts)、[TablePro 契约](../packages/ui/src/RTablePro/README.md)、[表格示例](../apps/admin/src/views/demo/tables) | `base/`、`pro/` 深层路径失效;`RTable`、`useTable` 已移除。`useTablePro` 保留注册写法,提供 `isReady` 和当前页取数。远端 `total` 是筛选后的总数;取消依赖请求函数传递 signal;导出和打印默认仅当前页可见数据列。 | +| 路由与权限 | [路由说明](../apps/admin/src/router/README.md)、[路由类型](../apps/admin/src/router/types.ts)、[权限守卫](../apps/admin/src/router/utils/permission.ts) | 菜单显隐不等于访问授权;会话和接口权限由后端校验。缓存需要路由 name 对应组件 name,验证菜单进入、直达和刷新。 | +| 布局与 Pinia | [布局插槽和偏好](../apps/admin/src/layout/README.md)、[Store 约定](../apps/admin/src/store/README.md) | 全局 UI 单例已迁入 `runtime`,不持久化。保留历史设置和锁屏格式;自定义内容插槽时,由接入方负责保留请求取消及路由缓存。 | +| 请求与 Mock | [Axios 实现](../apps/admin/src/axios/instance.ts)、[取消器](../packages/http/src/RequestCanceler.ts)、[人员查询](../apps/admin/src/api/demo/mock/person.ts) | 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。Mock HTTP 仅用于开发,静态演示有独立本地数据分支。 | +| Hooks、工具与图标 | [Hooks 行为](../apps/admin/src/hooks/README.md)、[工具兼容入口](../apps/admin/src/utils/README.md)、[图标生成](../packages/icons/src/A_README.md) | `@/hooks` 与 `@/utils` 公共入口保留;旧裸图标仅在缓存读取边界按唯一名称迁移。截图和打印测试不代表原生浏览器能力验收。 | +| 工具链与部署 | [工具链记录](toolchain-upgrade.md)、[架构地图](architecture.md)、[Vite 配置](../vite.custom.config.ts) | Node/pnpm 以清单为准。应用 base 为 `/ray-template/`,内置文档为 `/ray-template/docs/`。已发布旧站仍使用 `/ray-template-doc/`。 | ## 联动流程 1. 应用改动影响公开导入、配置、缓存或行为时,在同一变更更新模块说明及 `apps/docs` 中受影响的文档和示例。破坏性改动进入迁移清单。 -2. 交互和展示的代码使用同一个 `apps/docs/examples` 文件。优先用 workspace 包,复用应用组件时按模块导入,浏览器专用示例在客户端加载。 +2. 展示正在运行的示例源码。轻量示例位于 `apps/docs/examples`,使用共享包的公开入口;需要后台上下文的示例嵌入 `example.html`,源码引用指向实际的后台演示页。定位入口见[文档主题索引](../harness/context/docs.md)。 3. 运行 `pnpm harness verify`,再用 `pnpm docs:preview` 在 `/ray-template/docs/` 检查导航、搜索、旧路径、明暗主题、窄屏和交互。线上迁址另行验证新旧地址。 ## 待同步到读者指南的内容 -应用侧已准备好 [路由接入文档](../apps/admin/src/router/README.md)、[Schema](../apps/admin/src/router/config/schema.ts)、[Segment 说明](../apps/admin/src/components/RSegment/README.md) 和 [页面设计说明](ui-design.md)。在 `apps/docs/guide/routing.md` 补充来源切换、接口示例和版本校验,在组件参考中补充 `fitContent` 的选中态与过渡规则。截图使用更新后的登录页与管理页,并核对部署子路径。 +应用侧已准备好 [路由接入文档](../apps/admin/src/router/README.md)、[Schema](../packages/routing/src/schema.ts)、[Segment 说明](../packages/ui/src/RSegment/README.md) 和 [页面设计说明](ui-design.md)。在 `apps/docs/guide/routing.md` 补充来源切换、接口示例和版本校验,在组件参考中补充 `fitContent` 的选中态与过渡规则。截图使用更新后的登录页与管理页,并核对部署子路径。 -`guide/layout.md` 补充右侧导航、通栏分组、减少动态效果和浮动退出按钮;`guide/routing.md` 增加可视化与 JSON 两个入口,明确可视化应用仅保存在当前浏览器;`reference/hooks/layout.md` 说明加载提示以可见内容区为基准。 +`guide/layout.md` 补充减少动态效果和浮动退出按钮;`guide/routing.md` 增加可视化与 JSON 两个入口,明确可视化应用仅保存在当前浏览器;`reference/hooks/layout.md` 说明加载提示以可见内容区为基准。 `guide/layout.md` 同步设置抽屉的偏好导入导出:JSON 只包含抽屉内偏好,校验通过后即时保存,独立于路由管理的 JSON 配置。 diff --git a/harness/README.md b/harness/README.md index 3fc3fb52..5c1c9837 100644 --- a/harness/README.md +++ b/harness/README.md @@ -1,17 +1,17 @@ # Ray Template AI Harness -从 [AGENTS.md](../AGENTS.md) 进入。LLM 可先读取 [入口索引](../llms.txt) 定位相关文件。任务上下文来自 [scopes.json](scopes.json),跨模块关系见 [架构地图](../docs/architecture.md)。CLI 使用项目锁定的 Node.js 和 pnpm,可在本机和 CI 运行。 +从 [AGENTS.md](../AGENTS.md) 进入。需要查实现时,从 [任务索引](../llms.txt) 打开相关主题;跨模块关系见 [架构地图](../docs/architecture.md)。只阅读索引无需安装依赖。 ## 开始任务 -1. 根据 `.nvmrc` 和 `package.json#packageManager` 选择运行时,首次执行 `pnpm install --frozen-lockfile` 和 `pnpm env:check`。 -2. 查看 `git status`。用 `pnpm harness context` 查找任务域,再用 `pnpm harness context ` 找到入口和回归测试。跨域变更分别查看受影响的任务域。 -3. 明确可观察的验收条件。涉及多步迁移或跨会话接续时,记录范围、分阶段验收、关键决策与剩余项。可参考 [建设计划](plan.md)。 -4. 追踪调用方和数据流后实施。先用定向测试缩短反馈周期,最后运行全量验收。 +1. 查看 `git status`。用静态入口或 `pnpm harness context` 选择任务域;`pnpm harness context ` 显示对应索引及验证命令。跨域变更分别查看受影响的任务域。 +2. 需要运行验证时,根据 `.nvmrc` 和 `package.json#packageManager` 选择运行时,首次执行 `pnpm install --frozen-lockfile` 和 `pnpm env:check`。 +3. 明确可观察的验收条件,追踪调用方和数据流后实施。多步迁移或跨会话接续时,记录范围、分阶段验收、关键决策与剩余项。可参考 [建设计划](plan.md)。 +4. 先运行定向验证,最后运行全量验收。 ```sh -pnpm harness context routing -pnpm harness verify routing +pnpm harness context table-pro +pnpm harness verify table-pro pnpm harness verify ``` @@ -28,8 +28,8 @@ pnpm harness verify | 命令 | 验证范围 | | ----------------------------- | --------------------------------------------------------------- | -| `pnpm harness check` | 上下文路径存在,回归路径至少指向一个测试文件 | -| `pnpm harness verify ` | 环境检查和该任务域的 Vitest 回归 | +| `pnpm harness check` | 主题已登记并可从入口到达;相对链接、回归路径和检查命令有效 | +| `pnpm harness verify ` | 环境检查和该任务域登记的 Vitest 回归或项目检查 | | `pnpm harness verify` | `pnpm check` 的全部检查 | | `pnpm check` | 环境、Harness、图标同步、类型、规范、格式、单测、应用与文档构建 | @@ -47,10 +47,12 @@ GitHub Actions 在 Linux、Windows 和 macOS 运行同一份 `pnpm check`。单 | 路由、权限或缓存 | 从菜单进入、直接访问、刷新,核对守卫和恢复行为 | | 图标、部署 base 或构建 | 检查生产预览、资源 URL 和控制台 | -在交付或 PR 中记录复现步骤、实际结果及未验证项。临时报告、日志和截图放入 `.harness-local/`。浏览器结果单独记录,单元测试报告仅覆盖其中列出的命令。 +在交付或 PR 中记录复现步骤、实际结果及未验证项。临时报告、日志和截图放入 `.harness-local/`。浏览器结果单独记录,CLI 报告仅覆盖其中列出的命令。 ## 维护 影响外部读者的功能或兼容性改动,按 [文档联动说明](../docs/docs-handoff.md) 在同一变更中更新 `apps/docs`。单独用 `pnpm docs:check` 检查示例类型、文档链接和构建;用 `pnpm docs:preview` 验收生产子路径下的交互。 -任务域的路径或测试位置变化时,更新 `scopes.json` 并运行 `pnpm harness check`。测试目录以 `/` 结尾,单个文件使用仓库相对路径。优先完善现有测试和上下文入口,把可稳定复现的失败纳入共同检查。 +- 移动实现、适配层或示例时,更新 `harness/context/` 中受影响的索引。每个主题说明何时使用、先读哪些文件、谁拥有实现及如何验证。API 细节留在源码、模块 README 或读者文档。 +- 新增任务域时,在 [scopes.json](scopes.json) 注册简介和 `tests` 或 `checks`,添加同名 `harness/context/.md`,并从 [llms.txt](../llms.txt) 链入。测试目录以 `/` 结尾;项目检查复用 CLI 允许的根脚本。原有任务域可保留为较宽的验证入口。 +- 索引用普通行内相对链接指向仓库文件或目录。`pnpm harness check` 检查主题及其入口文档的文件目标,不请求外部链接或验证标题锚点。调整内容后再从一个真实任务出发走查实现和测试归属。 diff --git a/harness/context/api.md b/harness/context/api.md new file mode 100644 index 00000000..4819cc92 --- /dev/null +++ b/harness/context/api.md @@ -0,0 +1,14 @@ +# API、请求与 Mock + +用于新增接口、调试 Axios 响应和拦截器、定位重复请求或切页取消、修改演示数据。先看[请求契约](../../apps/admin/src/axios/README.md)。 + +| 要查什么 | 先读 | 接着追踪 | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 业务接口、分页数据、请求配置 | [应用 API](../../apps/admin/src/api)、[应用请求实例](../../apps/admin/src/axios/instance.ts)、[请求配置](../../apps/admin/src/app-config/request-config.ts) | [人员接口调用](../../apps/admin/src/api/demo/mock/person.ts)、[接入指南](../../apps/docs/guide/requests.md) | +| Axios 拦截器、异常和客户端隔离 | [共享客户端](../../packages/http/src/client.ts)、[共享类型](../../packages/http/src/types.ts) | [应用请求拦截器](../../apps/admin/src/axios/axios-interceptor/request/provider.ts)、[响应拦截器](../../apps/admin/src/axios/axios-interceptor/response/provider.ts) | +| 重复请求、AbortSignal、切页取消 | [共享 RequestCanceler](../../packages/http/src/RequestCanceler.ts)、[应用取消 Provider](../../apps/admin/src/app-components/provider/AppRequestCancelerProvider) | [布局内容插槽](../../apps/admin/src/layout/default/ContentWrapper/index.tsx)、[TablePro 远端请求](table-pro.md) | +| 开发 Mock 与静态演示不同 | [开发 Mock](../../apps/admin/mock/demo/person.mock.ts)、[共用演示数据](../../apps/admin/src/demo-data/people.ts) | [应用调用的环境分支](../../apps/admin/src/api/demo/mock/person.ts)、[Vite Mock 插件](../../vite.plugin.config.ts) | + +应用 `axios/utils` 中有兼容转导出。请求的默认 signal 只在调用方未传 signal、且未禁用默认取消时注入。演示数据不代表生产接口或授权;前端 `VITE_*` 配置不可用于密钥。 + +定向验证:`pnpm harness verify api`,包括[应用请求](../../__test__/axios/request.spec.ts)、[客户端隔离](../../__test__/workspace/http-client.spec.ts)和 [Mock](../../__test__/mock/database.spec.ts)。生产后端接入、浏览器下载和真实链路需另验。 diff --git a/harness/context/docs.md b/harness/context/docs.md new file mode 100644 index 00000000..959b0f1d --- /dev/null +++ b/harness/context/docs.md @@ -0,0 +1,14 @@ +# 文档站与可运行示例 + +用于修改指南、API 参考、导航、主题、旧链接或交互示例。站点开发和预览命令见[文档站 README](../../apps/docs/README.md)。 + +| 要查什么 | 先读 | 接着追踪 | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 对外用法、API 或兼容迁移 | [开发指南](../../apps/docs/guide)、[API 参考](../../apps/docs/reference/index.md)、[迁移说明](../../apps/docs/migration.md) | [应用与文档联动](../../docs/docs-handoff.md)、[共享包边界](../../docs/architecture.md) | +| 站点主题、导航、源码链接 | [VitePress 配置](../../apps/docs/.vitepress/config.mts)、[侧栏](../../apps/docs/.vitepress/sidebar.mts)、[主题](../../apps/docs/.vitepress/theme) | [版本与仓库链接](../../apps/docs/.vitepress/source.mts) | +| 旧文档路径与重定向 | [站内旧路径映射](../../apps/docs/.vitepress/legacy.mts) | [合并站点和旧站跳转产物](../../scripts/assemble-pages.mjs)、[构建与部署](toolchain.md) | +| 页内交互与源码引用 | [轻量 Vue 示例](../../apps/docs/examples)、[后台 iframe 包装](../../apps/docs/examples/AdminExample.vue) | [example.html](../../apps/admin/example.html)、[独立演示启动与路由](../../apps/admin/src/documentation-example.tsx)、[后台示例页面](../../apps/admin/src/views/demo) | + +轻量示例通过共享包公开入口运行。需要后台上下文的示例走 `example.html` 的限定路由和内存缓存;使用和展示同一份运行源码。涉及公开契约时回到所属主题核实,维护指南、示例及迁移说明。 + +定向验证:`pnpm harness verify docs` 执行 `docs:check`,包含类型、站内链接和生产构建。嵌入后台、部署子路径和旧站跳转使用 `pnpm pages:build` 生成组合产物,再按 [README](../../apps/docs/README.md) 预览。 diff --git a/harness/context/harness.md b/harness/context/harness.md new file mode 100644 index 00000000..a3b0470d --- /dev/null +++ b/harness/context/harness.md @@ -0,0 +1,13 @@ +# Harness、索引和验证证据 + +用于新增或改动任务索引、回归范围、命令和本地报告。执行方式见 [Harness README](../README.md)。 + +| 要查什么 | 先读 | 接着追踪 | +| -------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| 助手从哪里进入、怎么选主题 | [根约定](../../AGENTS.md)、[静态任务入口](../../llms.txt) | [主题索引](./)、[跨模块地图](../../docs/architecture.md) | +| CLI、上下文与定向目标 | [任务注册表](../scopes.json)、[CLI 实现](../run.mjs) | [CLI 回归](../../__test__/harness/cli.spec.ts)、[根检查命令](../../package.json) | +| 全量验证、报告和历史决策 | [验证与证据](../README.md#验收与证据)、[CI](../../.github/workflows/ci.yaml) | [建设计划与设计自审](../plan.md)、[工具链记录](../../docs/toolchain-upgrade.md) | + +移动源码时更新受影响的索引链接。新增主题时同步任务注册表、同名 Markdown 和静态入口;长篇契约保留在所属模块。报告由现有 CLI 写入被忽略的 `.harness-local/runs/`;截图和其他临时证据不放进索引。 + +定向验证:先运行 `pnpm harness check` 检查索引,变更 CLI 后运行 `pnpm harness verify harness`。涉及全量流程时,用真实 `pnpm harness verify` 验证报告。 diff --git a/harness/context/icons.md b/harness/context/icons.md new file mode 100644 index 00000000..5703b0ce --- /dev/null +++ b/harness/context/icons.md @@ -0,0 +1,13 @@ +# SVG 图标与生成 + +用于新增或移动图标、排查图标类型、symbol ID、雪碧图 URL 或热更新。 + +| 要查什么 | 先读 | 接着追踪 | +| ------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| 资源、分包及命名 | [图标维护说明](../../packages/icons/src/A_README.md)、[SVG 资源目录](../../packages/icons/src) | [包公开入口](../../packages/icons/package.json)、[应用适配](../../apps/admin/src/icons) | +| 清单、类型、生成及 HMR | [生成器](../../packages/icons/scripts/icons.mjs)、[根脚本入口](../../scripts/icons.mjs) | [Vite 图标适配](../../vite-helper/icons.ts)、[插件配置](../../vite.plugin.config.ts) | +| 渲染、应用注入和读者用法 | [RIcon](../../packages/ui/src/RIcon/index.ts)、[应用图标服务](../../apps/admin/src/App.tsx) | [图标示例](../../apps/admin/src/views/demo/svg-icons)、[读者参考](../../apps/docs/reference/icons.md) | + +SVG 与生成器是来源;[manifest.ts](../../packages/icons/src/manifest.ts) 由 `pnpm icons:generate` 更新。移动分包可能改变完整名称;检查菜单、路由配置、缓存中的引用及生产资源 URL。 + +定向验证:`pnpm icons:check` 与 `pnpm harness verify icons`,包括[生成](../../__test__/icons/generation.spec.ts)和[热更新](../../__test__/icons/hmr.spec.ts)回归。资源路径变更按[浏览器验收](../README.md#浏览器验收)核对生产预览。 diff --git a/harness/context/layout.md b/harness/context/layout.md new file mode 100644 index 00000000..279a2387 --- /dev/null +++ b/harness/context/layout.md @@ -0,0 +1,14 @@ +# 启动、布局与应用状态 + +用于定位 Provider、导航布局、页面缓存、设置抽屉、Pinia 或持久化问题。 + +| 要查什么 | 先读 | 接着追踪 | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 首屏、无界挂载、全局服务 | [应用启动](../../apps/admin/src/main.ts)、[App Provider 组装](../../apps/admin/src/App.tsx) | [应用 Provider](../../apps/admin/src/app-components/provider)、[共享 UI 服务接口](../../packages/ui/src/services.ts)、[模板启动后校验](../../apps/admin/src/__ray-template/index.ts) | +| 侧栏、顶部导航、标签与搜索 | [应用布局适配](../../apps/admin/src/layout/index.tsx)、[应用导航 Hook](../../apps/admin/src/hooks/template/useAppNavigation.ts) | [共享 AdminShell](../../packages/admin-shell/src/AdminShell.tsx)、[宿主布局部件](../../apps/admin/src/layout/components)、[插槽契约](../../apps/admin/src/layout/README.md) | +| 内容区、加载、切页及 KeepAlive | [宿主内容插槽](../../apps/admin/src/layout/default/ContentWrapper/index.tsx)、[宿主过渡适配](../../apps/admin/src/components/RTransitionComponent) | [共享过渡与缓存渲染](../../packages/admin-shell/src/RouteTransition.vue)、[缓存名单](../../apps/admin/src/store/modules/keep-alive/index.ts)、[页面请求取消](api.md) | +| 布局偏好、JSON 导入导出、临时状态 | [设置 Store](../../apps/admin/src/store/modules/setting/index.ts)、[偏好文件校验](../../apps/admin/src/store/modules/setting/preference-file.ts)、[runtime Store](../../apps/admin/src/store/modules/runtime/index.ts) | [宿主设置抽屉](../../apps/admin/src/layout/components/SiderBar/components/SettingDrawer/index.tsx)、[共享布局设置](../../packages/admin-shell/src/LayoutSettings.tsx)、[读者指南](../../apps/docs/guide/layout.md) | + +布局包负责壳和渲染,应用提供导航、设置、内容及运行时状态。应用 Store 通过 [hooks](../../apps/admin/src/store/hooks) 访问;持久化范围和历史格式见 [Store 约定](../../apps/admin/src/store/README.md)。偏好文件只处理布局设置,路由来源和 JSON 归[路由](routing.md)。 + +定向验证:`pnpm harness verify layout`,包括[布局回归](../../__test__/layout)、[Provider](../../__test__/app/global-provider.spec.ts)和相关 Hook。浏览器复核受影响的布局模式、窄屏、缓存恢复及偏好读回。 diff --git a/harness/context/routing.md b/harness/context/routing.md new file mode 100644 index 00000000..e8493777 --- /dev/null +++ b/harness/context/routing.md @@ -0,0 +1,14 @@ +# 路由、菜单与权限 + +用于新增页面或菜单、调试直达和刷新、变更动态路由来源或配置。先看[路由接入与配置契约](../../apps/admin/src/router/README.md)中与任务相关的段落。 + +| 要查什么 | 先读 | 接着追踪 | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 静态页面注册、菜单排序 | [应用路由模块](../../apps/admin/src/router/modules)、[路由模块装配](../../apps/admin/src/router/app-route-modules.ts) | [视图](../../apps/admin/src/views)、[菜单 Store](../../apps/admin/src/store/modules/menu/index.ts)、[共享展开逻辑](../../packages/routing/src/expand-routes.ts) | +| 动态 JSON 字段、校验错误、允许的页面 | [共享 Schema](../../packages/routing/src/schema.ts)、[JSON Schema 导出](../../packages/routing/src/json-schema.ts)、[应用页面 ID 注册表](../../apps/admin/src/router/config/views.ts) | [应用绑定](../../apps/admin/src/router/config/contract.ts)、[管理页](../../apps/admin/src/views/route-management)、[读者指南](../../apps/docs/guide/routing.md) | +| 静态、本地、远端来源及降级 | [来源加载与保存](../../apps/admin/src/router/config/source.ts) | [路由初始化](../../apps/admin/src/router/index.ts)、[实际注册的路由](../../apps/admin/src/router/routes.ts) | +| 菜单可见性、直达、登录后落地 | [导航守卫](../../apps/admin/src/router/utils/permission.ts)、[路由与白名单配置](../../apps/admin/src/app-config/router-config.ts) | [菜单显隐](../../apps/admin/src/router/utils/valid-menu-item-show.ts)、[会话 Store](../../apps/admin/src/store/modules/signing/index.ts)、[共享导航遍历](../../packages/routing/src/navigation.ts) | + +[应用 Schema](../../apps/admin/src/router/config/schema.ts) 是转导出;共享包负责通用校验,页面加载器、角色和登录状态由应用接入。保持路由名唯一;启用缓存的页面检查组件名与路由名。前端菜单和守卫都不能替代服务端授权。 + +定向验证:`pnpm harness verify routing`,优先看[动态配置](../../__test__/router/config.spec.ts)和[权限回归](../../__test__/router/permission.spec.ts)。行为改动补测菜单进入、直接访问、刷新及切换来源;涉及缓存或设置再看[布局与状态](layout.md)。 diff --git a/harness/context/table-pro.md b/harness/context/table-pro.md new file mode 100644 index 00000000..c568a1db --- /dev/null +++ b/harness/context/table-pro.md @@ -0,0 +1,14 @@ +# TablePro + +用于 `RTablePro`、`useTablePro`、高级搜索、远端分页、列设置、导出或打印。共享包拥有实现,后台和文档站分别消费同一公开 API。 + +| 要查什么 | 先读 | 接着追踪 | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 导出、Props、实例方法 | [共享入口](../../packages/ui/src/RTablePro/index.ts)、[Props](../../packages/ui/src/RTablePro/src/props.ts)、[类型](../../packages/ui/src/RTablePro/src/types.ts) | [注册 Hook](../../packages/ui/src/RTablePro/src/useTablePro.ts)、[包导出](../../packages/ui/package.json)、[应用组件入口](../../apps/admin/src/components/index.ts) | +| 搜索草稿、校验、条件生效、请求竞争 | [搜索状态](../../packages/ui/src/RTablePro/src/useTableSearch.ts)、[搜索值处理](../../packages/ui/src/RTablePro/src/search.ts)、[分页与请求](../../packages/ui/src/RTablePro/src/TablePro.tsx) | [搜索控件](../../packages/ui/src/RTablePro/src/components/Search.tsx)、[后台搜索示例](../../apps/admin/src/views/demo/tables/search.tsx)、[搜索回归](../../__test__/components/table-pro-search.spec.ts) | +| 列可见性、布局、当前页导出与打印 | [表格面板](../../packages/ui/src/RTablePro/src/TablePanel.tsx)、[列设置](../../packages/ui/src/RTablePro/src/columns.ts) | [CSV](../../packages/ui/src/RTablePro/src/csv.ts)、[打印](../../packages/ui/src/RTablePro/src/printing.ts)、[列回归](../../__test__/components/table-pro-columns.spec.ts) | +| 示例、文案和公开约定 | [组件契约](../../packages/ui/src/RTablePro/README.md)、[文档参考](../../apps/docs/reference/table-pro.md) | [后台示例和夹具](../../apps/admin/src/views/demo/tables)、[文档轻量示例](../../apps/docs/examples/TableProDemo.vue)、[组件语言资源](../../packages/ui/src/RTablePro/src/locale.ts) | + +远端 `total` 是筛选后的总数,取消需要请求函数透传 `signal`。修改实例能力时同时检查组件暴露、Hook 和公开导出;修改示例参数时确认是文档轻量示例还是[嵌入后台示例](docs.md)。 + +定向验证:`pnpm harness verify table-pro` 覆盖表格、搜索、列和导出。真实滚动、下载、打印和窄屏布局使用对应示例在浏览器验收。 diff --git a/harness/context/toolchain.md b/harness/context/toolchain.md new file mode 100644 index 00000000..d47d37fa --- /dev/null +++ b/harness/context/toolchain.md @@ -0,0 +1,14 @@ +# 工作区、类型检查、构建与 CI + +用于修改依赖、公开导出、别名、自动导入、生产构建或部署配置。运行时以 [.nvmrc](../../.nvmrc) 和[根清单](../../package.json)为准。 + +| 要查什么 | 先读 | 接着追踪 | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 工作区和依赖边界 | [pnpm workspace](../../pnpm-workspace.yaml)、[锁文件](../../pnpm-lock.yaml)、[工作区清单与职责](../../docs/architecture.md#工作区) | [包边界检查](../../scripts/check-package-boundaries.mjs)、[环境检查](../../scripts/doctor.mjs) | +| 路径别名、类型检查和自动导入 | [TypeScript 项目图](../../docs/architecture.md#typescript-项目配置)、[共享配置](../../tsconfig.base.json)、[Vite 别名](../../vite.custom.config.ts) | [插件配置](../../vite.plugin.config.ts)、[生成声明](../../unplugin)、[Vitest 配置](../../vitest.config.ts) | +| 构建入口、部署 base 与 SEO | [应用 Vite 配置](../../vite.config.ts)、[部署配置](../../vite.custom.config.ts)、[站点元数据](../../vite-helper/site-seo.ts) | [文档站配置](../../apps/docs/.vitepress/config.mts)、[产物合并](../../scripts/assemble-pages.mjs)、[部署约定](../../docs/architecture.md#deployment-and-search-discovery) | +| CI、镜像和发布产物 | [GitHub Actions](../../.github/workflows/ci.yaml)、[Dockerfile](../../Dockerfile)、[Compose](../../docker-compose.yml) | [全量验证步骤](../../harness/README.md)、[工具链演进记录](../../docs/toolchain-upgrade.md) | + +公开导出以对应 workspace 的 `package.json#exports` 为准;改别名时比较 Vite、TypeScript 和 Vitest 的解析。生成声明通过配置更新。发布组合站点时同时核对后台和文档的 base。 + +定向验证:`pnpm harness verify toolchain` 执行包边界和类型检查。改动构建或部署时还需全量检查、生成相关产物并预览;定向通过不能证明 CI、Docker 或线上发布成功。 diff --git a/harness/context/ui.md b/harness/context/ui.md new file mode 100644 index 00000000..a9cbbfd7 --- /dev/null +++ b/harness/context/ui.md @@ -0,0 +1,15 @@ +# 页面、公共组件、Hooks 与指令 + +用于新增或修改页面、公共 UI、主题、双语文案、Vue Hooks 或指令。TablePro 和布局各有更窄的入口:[表格](table-pro.md)、[布局](layout.md)。 + +| 要查什么 | 先读 | 接着追踪 | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 页面、登录、示例 | [页面目录](../../apps/admin/src/views)、[登录页](../../apps/admin/src/views/login/index.tsx)、[演示页骨架](../../apps/admin/src/views/demo/components/DemoPage.tsx) | [路由注册](routing.md)、[视觉约定](../../docs/ui-design.md) | +| Modal、Segment、图表、条码等通用组件 | [应用组件入口](../../apps/admin/src/components/index.ts)、[共享 UI 公开导出](../../packages/ui/package.json) | [组件实现](../../packages/ui/src)、[API 参考](../../apps/docs/reference/components.md) | +| 依赖模板状态的组件与 Provider | [应用组件说明](../../apps/admin/src/app-components/README.md) | [App 组装](../../apps/admin/src/App.tsx)、[Naive UI 自动补全默认值](../../apps/admin/src/app-components/provider/AppAutocompleteDefaults) | +| 主题、样式、应用文案 | [应用设计配置](../../apps/admin/src/app-config/design-config.ts)、[样式入口](../../apps/admin/src/styles/entry.ts)、[语言资源](../../apps/admin/src/locales/README.md) | [应用主题 Hook](../../apps/admin/src/hooks/template/useTheme.ts)、[共享主题](../../packages/ui/src/theme.css)、[文档站样式](docs.md) | +| Hooks、全局指令 | [应用 Hooks 入口](../../apps/admin/src/hooks/index.ts)、[共享组合式函数入口](../../packages/composables/src/index.ts)、[应用指令注册](../../apps/admin/src/directives/index.ts) | [Hooks 说明](../../apps/admin/src/hooks/README.md)、[共享指令实现](../../packages/directives/src/modules)、[指令用法](../../apps/admin/src/directives/README.DIR.md) | + +应用的 `@/components` 和部分 Hook/指令路径保留兼容导出;修通用行为前沿导出进入所属共享包。宿主特有服务通过注入接入,避免共享包引用应用别名。界面新增文案应补齐中英文。 + +定向验证:`pnpm harness verify ui`,先按实际行为选择[组件](../../__test__/components)、[Hooks](../../__test__/hooks)或[跨包消费](../../__test__/workspace/consumer.spec.tsx)用例。涉及页面效果,按 [Harness 浏览器验收](../README.md#浏览器验收) 检查。 diff --git a/harness/context/utils.md b/harness/context/utils.md new file mode 100644 index 00000000..5e3622be --- /dev/null +++ b/harness/context/utils.md @@ -0,0 +1,14 @@ +# 工具、缓存与数据兼容 + +用于修改基础工具、精度、文件、缓存读写或历史密文。先通过[应用入口说明](../../apps/admin/src/utils/README.md)确认实现归属。 + +| 要查什么 | 先读 | 接着追踪 | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| 精度、对象、文件与基础工具 | [共享包导出](../../packages/utils/package.json)、[共享工具](../../packages/utils/src) | [应用兼容入口](../../apps/admin/src/utils/index.ts)、[工具 API](../../apps/docs/reference/utils.md) | +| 应用缓存 key、Storage 后端、文档示例隔离 | [应用缓存](../../apps/admin/src/utils/cache.ts)、[缓存后端](../../apps/admin/src/utils/cache-backend.ts)、[key 前缀](../../apps/admin/src/utils/app/prefix-cache-key.ts) | [应用缓存键配置](../../apps/admin/src/app-config/app-config.ts)、[共享 JSON 存储](../../packages/utils/src/storage.ts)、[布局和状态](layout.md) | +| 历史同步 AES 密文 | [兼容实现](../../apps/admin/src/utils/legacy-crypto)、[旧导入入口](../../apps/admin/src/utils/c/index.ts) | [历史密文回归](../../__test__/utils-contracts/legacy-crypto.spec.ts) | +| Vue 生命周期、DOM 和元素工具 | [共享组合式函数与工具](../../packages/composables/src) | [应用 Hooks 与 UI](ui.md)、[Vue 工具回归](../../__test__/vue) | + +保持调用方依赖的 key、存储类型和序列化格式。共享存储由调用方传入 Storage 实现;应用持久化和文档 iframe 的内存缓存需分别检查。同步 AES 格式或 API 若需替换,先设计历史数据迁移。 + +定向验证:`pnpm harness verify utils`,从[缓存测试](../../__test__/cache)、[精度测试](../../__test__/precision)或[工具契约](../../__test__/utils-contracts)选择与任务相关的回归。 diff --git a/harness/plan.md b/harness/plan.md index 91bcc933..027010f9 100644 --- a/harness/plan.md +++ b/harness/plan.md @@ -11,3 +11,31 @@ 日常维护时,以实际反复出现的失败为依据扩充 Harness。优先将已有覆盖缺口补进 Vitest,待浏览器流程有稳定夹具和可重复结果时,再评估纳入自动化门禁。迁移的实测结果见 [工具链记录](../docs/toolchain-upgrade.md)。 设计参考 [OpenAI Docs 的仓库工作流实践](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex) 与 [上下文分层建议](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra)。 + +## Monorepo 索引补全 + +审查基线为 `58fc0b63`。现有命令、回归和报告已形成反馈闭环,主要缺口在查找和判断代码归属: + +| 发现 | 影响 | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| 架构地图混用旧 `src/` 路径与工作区路径,仍将路由、图标和组件实现归到应用目录 | 目录存在不等于拥有实现。例如应用侧 Schema、取消器和部分组件只是兼容入口 | +| `ui` 同时覆盖布局、公共组件、文案、Hooks 和演示;没有 TablePro、文档站及构建的独立入口 | 查表格筛选或 VitePress 重定向时,需要自行从大目录找实现、示例和验证 | +| `llms.txt`、架构地图与 `scopes.json` 分别列源码路径;检查只覆盖 JSON 里的路径 | 文件移动后,入口和说明可以互相矛盾而全量检查仍通过 | + +### 设计 + +1. `AGENTS.md` 只保留仓库级协作约定和入口;`llms.txt` 提供无需运行时的任务路由,按需链接 [架构地图](../docs/architecture.md) 和具体主题。 +2. `harness/context/.md` 按实际问题列首读源码、应用/共享包/示例边界及相关测试。行为契约留在源码、就近 README 和公开文档中。架构地图说明工作区、关键运行链和部署。 +3. `scopes.json` 保存主题简介与可执行验证配置;按 ID 定位同名索引,`context ` 直接显示。保留六个已有 ID 和各自测试,新增 TablePro、布局、文档站和工具链。文档与工具链使用已有检查脚本。 +4. 将索引入口、相对链接和测试目标接入现有 `harness check`,继续由 `pnpm check` 和 CI 执行。范围是导航文档,不追踪外链或证明描述正确;语义通过走查和回归验证。 + +### 实施前自审 + +| 检查 | 修订后的决定 | +| -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| 是否要在 JSON 和 Markdown 重复维护实现路径? | 用同名索引作为 CLI 输出,正文只维护一份;不生成第二份源码树 | +| 是否让每个任务先跑命令、阅读全图? | 保留静态入口;按需求打开一张主题索引。架构图用于跨模块任务,不作为前置必读 | +| 是否给所有任务域强行配 Vitest? | 文档用 `docs:check`;工具链用包边界与类型检查。明确哪些问题仍需生产预览或全量检查 | +| 是否能区分同名入口与真正实现? | 用 TablePro 搜索、动态路由、请求取消、偏好导入、旧文档重定向和部署产物逐条走查,索引写明主实现和宿主适配 | + +验收:静态入口可到达所有主题;原命令和报告契约兼容;断链、缺失主题和失效回归路径会使检查失败;代表任务能从索引到达实现和验证;最后执行 `pnpm harness verify`。 diff --git a/harness/run.mjs b/harness/run.mjs index c5b31d90..322767c3 100644 --- a/harness/run.mjs +++ b/harness/run.mjs @@ -8,7 +8,7 @@ import { statSync, writeFileSync, } from 'node:fs' -import { join, relative } from 'node:path' +import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path' import { fileURLToPath } from 'node:url' const root = fileURLToPath(new URL('../', import.meta.url)) @@ -17,23 +17,59 @@ const scopes = JSON.parse( ) const [action = '--help', scope, ...extra] = process.argv.slice(2) const testPattern = /^__test__\/(?:[\w-]+\/)+(?:[\w.-]+\.spec\.tsx?)?$/ +const scopePattern = /^[a-z][a-z\d]*(?:-[a-z\d]+)*$/ +const allowedChecks = new Set(['docs:check', 'packages:check', 'typecheck']) +const indexFiles = [ + 'AGENTS.md', + 'llms.txt', + 'docs/architecture.md', + 'docs/docs-handoff.md', + 'harness/README.md', + 'harness/plan.md', +] + +function contextPath(name) { + return `harness/context/${name}.md` +} function checkScopes() { const problems = [] + const { scripts } = JSON.parse( + readFileSync(join(root, 'package.json'), 'utf8'), + ) - for (const [name, { paths, tests }] of Object.entries(scopes)) { - for (const path of paths) { - if (!existsSync(join(root, path))) { - problems.push(`${name} 的上下文路径不存在:${path}`) + for (const [name, { description, tests = [], checks = [] }] of Object.entries( + scopes, + )) { + if (!scopePattern.test(name) || name === 'all') { + problems.push(`无效任务域:${name}`) + } + + if (typeof description !== 'string' || !description.trim()) { + problems.push(`${name} 需要任务描述`) + } + + if (!Array.isArray(tests) || !Array.isArray(checks)) { + problems.push(`${name} 的 tests 和 checks 必须为数组`) + continue + } + + if (tests.length === 0 && checks.length === 0) { + problems.push(`${name} 需要至少一个回归测试路径或检查命令`) + } + + for (const script of checks) { + if (!allowedChecks.has(script) || typeof scripts?.[script] !== 'string') { + problems.push(`${name} 的检查命令未注册:${script}`) } } - if (tests.length === 0) { - problems.push(`${name} 需要至少一个回归测试路径`) - } - for (const path of tests) { - if (!testPattern.test(path) || !existsSync(join(root, path))) { + if ( + typeof path !== 'string' || + !testPattern.test(path) || + !existsSync(join(root, path)) + ) { problems.push(`${name} 的回归测试路径无效:${path}`) continue } @@ -55,6 +91,71 @@ function checkScopes() { } } +function checkIndexes() { + const problems = [] + const cards = Object.keys(scopes).map(contextPath) + const entryLinks = new Set() + + for (const path of [...indexFiles, ...cards]) { + const file = join(root, path) + + if (!existsSync(file) || !statSync(file).isFile()) { + problems.push(`索引文档不存在:${path}`) + continue + } + + // 索引统一使用行内相对链接;只检查文件目标,不请求外链或解析标题。 + const markdown = readFileSync(file, 'utf8') + + for (const [, href] of markdown.matchAll(/\[[^\]\n]+\]\(([^)\s]+)\)/g)) { + const [target] = href.split('#', 1) + + if (!target || /^(?:[\w+.-]+:|\/\/)/.test(target)) continue + + const destination = resolve(dirname(file), target) + const fromRoot = relative(root, destination) + + if ( + isAbsolute(target) || + isAbsolute(fromRoot) || + fromRoot === '..' || + fromRoot.startsWith(`..${sep}`) || + !existsSync(destination) + ) { + problems.push(`${path} 的相对链接无效:${href}`) + } else if (path === 'llms.txt') { + entryLinks.add(destination) + } + } + } + + for (const path of cards) { + if (!entryLinks.has(join(root, path))) { + problems.push(`llms.txt 缺少可用的主题链接:${path}`) + } + } + + for (const file of globSync('harness/context/*.md', { cwd: root })) { + if (!cards.includes(file.split(sep).join('/'))) { + problems.push(`主题索引尚未注册:${file}`) + } + } + + if (problems.length > 0) { + throw new Error(problems.join('\n')) + } +} + +function scopeCommands(name) { + const { tests = [], checks = [] } = scopes[name] + + return [ + ['env:check'], + ...checks.map((script) => [script]), + ...(tests.length ? [['test:run', ...tests]] : []), + ] +} + function showContext(name) { if (!name) { for (const [id, { description }] of Object.entries(scopes)) { @@ -64,12 +165,15 @@ function showContext(name) { return } - const { description, paths, tests } = scopes[name] + const path = contextPath(name) - console.log(`${name} ${description}`) - console.log(paths.map((path) => ` ${path}`).join('\n')) - console.log(`定向验证:pnpm harness verify ${name}`) - console.log(`回归用例:pnpm test:run ${tests.join(' ')}`) + console.log(`阅读入口:${path}(正文链接相对此文件)\n`) + console.log(readFileSync(join(root, path), 'utf8').trimEnd()) + console.log(`\npnpm harness verify ${name} 执行:`) + + for (const args of scopeCommands(name)) { + console.log(` pnpm ${args.join(' ')}`) + } } function verify(name) { @@ -77,10 +181,7 @@ function verify(name) { checkScopes() } - const commands = - name === 'all' - ? [['check']] - : [['env:check'], ['test:run', ...scopes[name].tests]] + const commands = name === 'all' ? [['check']] : scopeCommands(name) const reports = join(root, '.harness-local', 'runs') const startedAt = new Date().toISOString() const steps = [] @@ -96,7 +197,7 @@ function verify(name) { console.log(`\n> ${command}`) - // Windows 需要 shell 启动 pnpm.cmd,参数来自固定命令与已校验的测试路径。 + // Windows 需要 shell 启动 pnpm.cmd,只传入允许的脚本名与已校验的测试路径。 const options = { cwd: root, stdio: 'inherit' } const result = process.platform === 'win32' @@ -138,12 +239,16 @@ function verify(name) { } try { - const knownScope = scope && Object.hasOwn(scopes, scope) + const knownScope = + scope && + scope !== 'all' && + scopePattern.test(scope) && + Object.hasOwn(scopes, scope) if (action === '--help' && !scope) { console.log(`pnpm harness context [scope] 查看任务上下文 pnpm harness verify [scope] 定向验证,省略 scope 时执行全量检查 -pnpm harness check 检查上下文与回归路径`) +pnpm harness check 检查主题索引、相对链接和验证目标`) } else if ( action === 'context' && extra.length === 0 && @@ -158,7 +263,8 @@ pnpm harness check 检查上下文与回归路径`) verify(scope ?? 'all') } else if (action === 'check' && !scope) { checkScopes() - console.log('✓ Harness 上下文与回归路径有效') + checkIndexes() + console.log('✓ Harness 索引、相对链接和验证目标有效') } else { throw new Error( '无效命令或任务域。使用 pnpm harness --help 或 pnpm harness context。', diff --git a/harness/scopes.json b/harness/scopes.json index ea1f2aab..852dac0c 100644 --- a/harness/scopes.json +++ b/harness/scopes.json @@ -1,16 +1,6 @@ { "routing": { - "description": "路由、菜单、权限与持久化", - "paths": [ - "apps/admin/src/router", - "apps/admin/src/router/README.md", - "apps/admin/src/store", - "apps/admin/src/store/README.md", - "apps/admin/src/router/config/schema.ts", - "apps/admin/src/router/config/views.ts", - "apps/admin/src/views/route-management", - "packages/routing" - ], + "description": "页面注册、菜单、动态路由 JSON、角色与守卫", "tests": [ "__test__/router/", "__test__/hooks/useVueRouter.spec.ts", @@ -19,26 +9,20 @@ "__test__/cache/" ] }, + "layout": { + "description": "启动、Provider、布局、KeepAlive、Pinia 与偏好文件", + "tests": [ + "__test__/app/", + "__test__/layout/", + "__test__/hooks/useAppNavigation.spec.ts", + "__test__/hooks/useLayoutScroll.spec.ts", + "__test__/hooks/useSiderBar.spec.ts", + "__test__/hooks/useTheme.spec.ts", + "__test__/cache/" + ] + }, "ui": { - "description": "页面、组件、布局、主题与国际化", - "paths": [ - "apps/admin/src/views", - "apps/admin/src/components/README.md", - "apps/admin/src/app-components/README.md", - "apps/admin/src/layout/README.md", - "apps/admin/src/locales/README.md", - "apps/admin/src/hooks/README.md", - "docs/ui-design.md", - "apps/docs/examples", - "apps/admin/src/views/login", - "apps/admin/src/views/demo/components/DemoPage.tsx", - "apps/admin/src/components/RSegment/README.md", - "apps/admin/src/app-components/provider/AppAutocompleteDefaults", - "packages/ui", - "packages/admin-shell", - "packages/composables", - "packages/directives" - ], + "description": "页面、公共组件、主题、国际化、Hooks 与指令", "tests": [ "__test__/app/", "__test__/components/", @@ -47,51 +31,25 @@ "__test__/workspace/consumer.spec.tsx" ] }, + "table-pro": { + "description": "RTablePro、useTablePro、搜索、分页、选列、导出与打印", + "tests": [ + "__test__/components/table-pro.spec.ts", + "__test__/components/table-pro-search.spec.ts", + "__test__/components/table-pro-columns.spec.ts", + "__test__/components/table-pro-exports.spec.ts" + ] + }, "api": { - "description": "API、Axios 拦截器与演示 Mock", - "paths": [ - "apps/admin/src/api", - "apps/admin/src/axios/README.md", - "apps/admin/mock/demo", - "apps/admin/src/demo-data", - "packages/http" - ], + "description": "业务 API、Axios、请求取消、拦截器与演示 Mock", "tests": [ "__test__/axios/", "__test__/mock/", "__test__/workspace/http-client.spec.ts" ] }, - "icons": { - "description": "图标分包、类型清单与热更新", - "paths": [ - "packages/icons/src/A_README.md", - "scripts/icons.mjs", - "vite.plugin.config.ts", - "packages/icons/scripts/icons.mjs" - ], - "tests": ["__test__/icons/"] - }, - "harness": { - "description": "工程协作入口、回归范围与验收报告", - "paths": [ - "harness/README.md", - "harness/run.mjs", - "harness/scopes.json", - "llms.txt", - ".github/workflows/ci.yaml", - "scripts/check-package-boundaries.mjs", - "scripts/assemble-pages.mjs" - ], - "tests": ["__test__/harness/"] - }, "utils": { - "description": "公共工具、兼容入口与数据契约", - "paths": [ - "apps/admin/src/utils/README.md", - "apps/admin/src/utils/index.ts", - "packages/utils" - ], + "description": "公共工具、缓存、历史密文和兼容入口", "tests": [ "__test__/basic/", "__test__/cache/", @@ -101,5 +59,21 @@ "__test__/utils-contracts/", "__test__/vue/" ] + }, + "icons": { + "description": "SVG 分包、图标名、清单生成和热更新", + "tests": ["__test__/icons/"] + }, + "docs": { + "description": "VitePress、API 参考、内嵌示例、侧栏与旧页跳转", + "checks": ["docs:check"] + }, + "toolchain": { + "description": "工作区、公开导出、类型检查、Vite、构建与 CI", + "checks": ["packages:check", "typecheck"] + }, + "harness": { + "description": "索引、回归范围、验证命令和本地报告", + "tests": ["__test__/harness/"] } } diff --git a/llms.txt b/llms.txt index c8dbf516..a2e82d24 100644 --- a/llms.txt +++ b/llms.txt @@ -1,29 +1,23 @@ # Ray Template -> Vue 3 + TypeScript/TSX + Vite + Pinia + Vue Router 中后台模板。应用入口在 apps/admin/src,工程验收由 AI Harness 管理。 +> Vue 3 + TypeScript/TSX 中后台模板。pnpm workspace 包含后台应用、VitePress 文档站和共享包。 -先读 AGENTS.md,再按任务执行 pnpm harness context 。构建和检查以 package.json、pnpm-lock.yaml、.nvmrc 与 CI 为准。 +遵循 [AGENTS.md](AGENTS.md),按任务选择下列入口。索引可直接阅读,也可用 `pnpm harness context ` 查看同一份内容和定向验证命令。 -## 任务入口 +## 任务索引 -- [协作约定](AGENTS.md): 工作区保护、验证、交付范围 -- [AI Harness](harness/README.md): 定向上下文、测试、浏览器验收 -- [架构地图](docs/architecture.md): 应用启动、跨模块调用与部署 -- [读者文档](apps/docs/README.md): VitePress 本地开发、API 参考和页内示例 -- [路由与动态配置](apps/admin/src/router/README.md): 来源切换、后端 JSON、字段与权限 -- [路由 JSON Schema](apps/admin/src/router/config/schema.ts): 配置结构和 TypeScript 类型的唯一来源 -- [页面 ID 注册表](apps/admin/src/router/config/views.ts): 路由配置可引用的页面及 KeepAlive 名称 -- [路由管理页](apps/admin/src/views/route-management/index.tsx): 配置录入、校验、导入和导出 -- [Pinia](apps/admin/src/store/README.md): 菜单、会话、布局和持久化边界 -- [组件入口](apps/admin/src/components/index.ts): 公开组件与 hooks 导出 -- [TablePro](packages/ui/src/RTablePro/README.md): 列表、数据源、分页、缓存与打印 -- [页面样式](docs/ui-design.md): 主题变量、示例布局和 UI 验收 -- [请求与取消](apps/admin/src/axios/README.md): 请求实例、拦截器及接口契约 -- [图标](packages/icons/src/A_README.md): 图标资源、生成和类型清单 +- [routing](harness/context/routing.md):新增页面和菜单、动态路由 JSON、页面 ID、角色与守卫。 +- [layout](harness/context/layout.md):启动、Provider、导航栏、KeepAlive、Pinia、偏好导入导出。 +- [ui](harness/context/ui.md):公共组件、页面与登录、主题和双语文案、Hooks、指令。 +- [table-pro](harness/context/table-pro.md):RTablePro、useTablePro、搜索、请求、选列、导出与打印。 +- [api](harness/context/api.md):业务 API、Axios、AbortSignal、拦截器、Mock 与静态数据。 +- [utils](harness/context/utils.md):精度、文件、存储、历史 AES 格式和应用兼容入口。 +- [icons](harness/context/icons.md):SVG 分包、图标名、清单生成和热更新。 +- [docs](harness/context/docs.md):VitePress、API 参考、内嵌示例、侧栏与旧页跳转。 +- [toolchain](harness/context/toolchain.md):工作区依赖、公开导出、TypeScript、Vite、产物与 CI。 +- [harness](harness/context/harness.md):索引维护、回归目标、验证命令与报告。 -## 按任务验证 +## 按需背景 -- 路由、权限、菜单、持久化使用 pnpm harness verify routing -- 组件、登录、示例页面使用 pnpm harness verify ui -- 接口和 Mock 使用 pnpm harness verify api -- 全量验收使用 pnpm harness verify +- [架构地图](docs/architecture.md):工作区边界、运行链路、类型检查和部署。 +- [AI Harness](harness/README.md):验证流程、浏览器验收和本地证据。