From 707a28bde3fd8330da2ce659a2a2830beb012573 Mon Sep 17 00:00:00 2001 From: XiaoDaiGua-Ray <51957438+XiaoDaiGua-Ray@users.noreply.github.com> Date: Wed, 4 Nov 2026 10:30:33 +0800 Subject: [PATCH] docs: add task-based navigation for AI assistants --- README.md | 2 ++ README.zh-CN.md | 2 ++ docs/docs-handoff.md | 4 ++++ docs/toolchain-upgrade.md | 4 ++++ docs/ui-design.md | 4 ++++ harness/README.md | 2 +- harness/scopes.json | 19 ++++++++++++++++--- llms.txt | 28 ++++++++++++++++++++++++++++ src/store/README.md | 6 ++++++ 9 files changed, 67 insertions(+), 4 deletions(-) create mode 100644 llms.txt diff --git a/README.md b/README.md index b3347b73..4739bf20 100644 --- a/README.md +++ b/README.md @@ -143,3 +143,5 @@ export default defineComponent({ Use the [architecture map](docs/architecture.md) to find module and configuration entry points. See the [deployment guide](docs/architecture.md#deployment-and-search-discovery) for root or subpath hosting and search metadata. Contributors and coding agents share the instructions in [AGENTS.md](AGENTS.md) and the [AI Harness](harness/README.md). [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. diff --git a/README.zh-CN.md b/README.zh-CN.md index 9dfd6a9a..10cca0d0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -143,3 +143,5 @@ export default defineComponent({ 二次开发可从[架构地图](docs/architecture.md)定位配置与模块。部署到域名根目录或子路径、为公开站点启用搜索元数据时,参考[部署指南](docs/architecture.md#deployment-and-search-discovery)。人工和 AI 协作共用 [AGENTS.md](AGENTS.md) 与 [AI Harness](harness/README.md)。 [MIT 许可证](LICENSE) · [更新日志](CHANGELOG.md) · [问题反馈](https://github.com/XiaoDaiGua-Ray/ray-template/issues) + +AI 助手可从 [LLM 入口](llms.txt) 按任务读取源码和验证命令。 diff --git a/docs/docs-handoff.md b/docs/docs-handoff.md index 0c7d89a2..eccdad14 100644 --- a/docs/docs-handoff.md +++ b/docs/docs-handoff.md @@ -18,3 +18,7 @@ 1. 应用改动影响公开导入、配置、缓存或行为时,先更新所属模块的 README 和示例,写清旧用法、新用法、兼容性及回归路径。记录已验证的应用提交;可从 `pnpm harness context` 定位任务域。 2. 文档仓库在对应变更中标注应用提交,按任务组织教程,给关键说法附固定提交的源码链接。破坏性改动进入迁移清单;旧 URL 映射到新版主题,旧正文可从历史提交查阅。 3. 应用运行 `pnpm harness verify`;文档运行 `pnpm build` 并预览生产子路径,检查导航、搜索、旧链接、明暗主题和窄屏。两个仓库的变更互相链接。发布前确认文档引用的应用提交已可访问,且在线演示已部署相应能力。 + +## 动态路由与示例页交接 + +应用侧已准备好 [路由接入文档](../src/router/README.md)、[Schema](../src/router/config/schema.ts)、[Segment 说明](../src/components/RSegment/README.md) 和 [页面设计说明](ui-design.md)。应用提交可访问后,在站外的 `guide/routing.md` 补充来源切换、接口示例和版本校验,在组件参考中补充 `fitContent` 的选中态与过渡规则。站外截图使用更新后的登录页与管理页,并核对部署子路径。 diff --git a/docs/toolchain-upgrade.md b/docs/toolchain-upgrade.md index e308aacd..cd4b83cc 100644 --- a/docs/toolchain-upgrade.md +++ b/docs/toolchain-upgrade.md @@ -170,3 +170,7 @@ Pinia 设置沿用原持久化 key,旧裸 Logo 名称在读取时迁移;锁 - [Vue Language Tools 的 TypeScript 7 支持进度](https://github.com/vuejs/language-tools/issues/5381) - [SVG Spritemap 子路径部署](https://spiriitlabs.github.io/vite-plugin-svg-spritemap/guide/deployment.html) - [Faker 本地化](https://fakerjs.dev/guide/localization.html) + +### 远端 CI 回查 + +[历史 Ubuntu 失败](https://github.com/XiaoDaiGua-Ray/ray-template/actions/runs/41588971650) 的失败项为 `detectOperatingSystem.spec.ts`。测试读取 Linux 运行器的真实 user agent,断言固定期待 `Unknown`。提交 `83bada95` 使用模拟 user agent 和触点数量覆盖各系统。当前基线 `80e80775` 的 [CI](https://github.com/XiaoDaiGua-Ray/ray-template/actions/runs/41612553267) 已通过 Ubuntu、macOS、Windows 和部署。现有矩阵继续运行同一条 `pnpm check`。 diff --git a/docs/ui-design.md b/docs/ui-design.md index f8d750bb..971a9156 100644 --- a/docs/ui-design.md +++ b/docs/ui-design.md @@ -8,6 +8,8 @@ - `src/styles/base.scss` 是全局样式入口,`design-system.scss` 管理主题变量与基础焦点样式,`setting.scss` 管理布局尺度。`naive.scss` 仅维护模板通用的控件默认值;布局与组件内部规则放在对应组件目录,避免影响嵌套的 Naive UI 实例。 - 控件通常为 8px 圆角、卡片为 12px;页面区块间距使用 20–28px。强调色用于选择与主要操作,正文、说明、眉题使用不同文字层级。 - 顶栏、标签栏和侧栏使用轻分割线,不叠加区域阴影;少量内容卡片使用两层轻阴影。 +- 页面标签平时只显示名称。可关闭的标签在悬停或聚焦时展开关闭按钮,触屏设备可在当前标签直接关闭。 +- 偏好抽屉按可用宽度使用双列或单列字段。分类导航和恢复默认操作放在统一位置。 - 内容最大化时,布局提供置顶的退出操作,使用按钮或 Esc 恢复。 - 页面标题复用 `AppPageHeader`:眉题、一个主标题、简短说明与可选操作区。不要以大段说明或同等权重的卡片标题代替页面层级。 @@ -24,3 +26,5 @@ 检查桌面与 390px 窄屏、明暗主题、中英文、长代码和操作按钮换行。默认正文用色按至少 4.5:1、输入框等控件边界按至少 3:1 选取;用户自定义主色仍需按实际组合确认。 保留 `forced-colors` 系统颜色回退、可见键盘焦点与减少动态效果设置。截图、颜色数值与浏览器检查不能互相替代,也不代表已验证全部最低版本设备。 + +登录页在宽屏并排显示品牌区和登录区,窄屏按文档顺序堆叠。Ray 标识用带两颗瓜籽的青瓜切面表现「呆瓜」,资源见 [SVG](../src/icons/logo/ray.svg)。示例应用默认关闭 HTML 自动填充,含延迟渲染和 Teleport 控件。需要允许时,在目标控件显式提供 `autocomplete`,Naive UI 的输入组件使用 `inputProps`。 diff --git a/harness/README.md b/harness/README.md index 3e7c6dc9..efe1cb71 100644 --- a/harness/README.md +++ b/harness/README.md @@ -1,6 +1,6 @@ # Ray Template AI Harness -从 [AGENTS.md](../AGENTS.md) 进入。任务上下文来自 [scopes.json](scopes.json),跨模块关系见 [架构地图](../docs/architecture.md)。CLI 使用项目锁定的 Node.js 和 pnpm,可在本机和 CI 运行。 +从 [AGENTS.md](../AGENTS.md) 进入。LLM 可先读取 [入口索引](../llms.txt) 定位相关文件。任务上下文来自 [scopes.json](scopes.json),跨模块关系见 [架构地图](../docs/architecture.md)。CLI 使用项目锁定的 Node.js 和 pnpm,可在本机和 CI 运行。 ## 开始任务 diff --git a/harness/scopes.json b/harness/scopes.json index c176dcba..3e54c128 100644 --- a/harness/scopes.json +++ b/harness/scopes.json @@ -5,7 +5,10 @@ "src/router", "src/router/README.md", "src/store", - "src/store/README.md" + "src/store/README.md", + "src/router/config/schema.ts", + "src/router/config/views.ts", + "src/views/route-management" ], "tests": [ "__test__/router/", @@ -24,7 +27,11 @@ "src/layout/README.md", "src/locales/README.md", "src/hooks/README.md", - "docs/ui-design.md" + "docs/ui-design.md", + "src/views/login", + "src/views/demo/components/DemoPage.tsx", + "src/components/RSegment/README.md", + "src/app-components/provider/AppAutocompleteDefaults" ], "tests": [ "__test__/app/", @@ -49,7 +56,13 @@ }, "harness": { "description": "工程协作入口、回归范围与验收报告", - "paths": ["harness/README.md", "harness/run.mjs", "harness/scopes.json"], + "paths": [ + "harness/README.md", + "harness/run.mjs", + "harness/scopes.json", + "llms.txt", + ".github/workflows/ci.yaml" + ], "tests": ["__test__/harness/"] }, "utils": { diff --git a/llms.txt b/llms.txt new file mode 100644 index 00000000..493f2b86 --- /dev/null +++ b/llms.txt @@ -0,0 +1,28 @@ +# Ray Template + +> Vue 3 + TypeScript/TSX + Vite + Pinia + Vue Router 中后台模板。业务入口在 src,工程验收由 AI Harness 管理。 + +先读 AGENTS.md,再按任务执行 pnpm harness context 。构建和检查以 package.json、pnpm-lock.yaml、.nvmrc 与 CI 为准。 + +## 任务入口 + +- [协作约定](AGENTS.md): 工作区保护、验证、交付范围 +- [AI Harness](harness/README.md): 定向上下文、测试、浏览器验收 +- [架构地图](docs/architecture.md): 应用启动、跨模块调用与部署 +- [路由与动态配置](src/router/README.md): 来源切换、后端 JSON、字段与权限 +- [路由 JSON Schema](src/router/config/schema.ts): 配置结构和 TypeScript 类型的唯一来源 +- [页面 ID 注册表](src/router/config/views.ts): 路由配置可引用的页面及 KeepAlive 名称 +- [路由管理页](src/views/route-management/index.tsx): 配置录入、校验、导入和导出 +- [Pinia](src/store/README.md): 菜单、会话、布局和持久化边界 +- [组件入口](src/components/index.ts): 公开组件与 hooks 导出 +- [TablePro](src/components/RTablePro/README.md): 列表、数据源、分页、缓存与打印 +- [页面样式](docs/ui-design.md): 主题变量、示例布局和 UI 验收 +- [请求与取消](src/axios/README.md): 请求实例、拦截器及接口契约 +- [图标](src/icons/A_README.md): 图标资源、生成和类型清单 + +## 按任务验证 + +- 路由、权限、菜单、持久化使用 pnpm harness verify routing +- 组件、登录、示例页面使用 pnpm harness verify ui +- 接口和 Mock 使用 pnpm harness verify api +- 全量验收使用 pnpm harness verify diff --git a/src/store/README.md b/src/store/README.md index 4826baa1..39906679 100644 --- a/src/store/README.md +++ b/src/store/README.md @@ -90,3 +90,9 @@ setRuntimeState('globalSpinning', false) ``` 布局用法和插槽见 [布局说明](../layout/README.md)。 + +## 菜单同步 + +- 菜单树和路径索引在角色变化或显式刷新时构建,不修改模块中的原始路由。路由完成后用 Vue Router 已匹配的记录同步标签页和面包屑。 +- 保留原有缓存键和标签列表结构。恢复时按已注册路由和角色重建旧标签,忽略已经删除或不可访问的路由。只有标签列表变化时才写会话缓存。 +- KeepAlive 按最近访问顺序更新,去重并按上限裁剪。主题合并仅由生效主题驱动,色弱模式和文档标题独立监听。