Ray Template AI Harness
从 AGENTS.md 进入。LLM 可先读取 入口索引 定位相关文件。任务上下文来自 scopes.json,跨模块关系见 架构地图。CLI 使用项目锁定的 Node.js 和 pnpm,可在本机和 CI 运行。
开始任务
- 根据
.nvmrc和package.json#packageManager选择运行时,首次执行pnpm install --frozen-lockfile和pnpm env:check。 - 查看
git status。用pnpm harness context查找任务域,再用pnpm harness context <scope>找到入口和回归测试。跨域变更分别查看受影响的任务域。 - 明确可观察的验收条件。涉及多步迁移或跨会话接续时,记录范围、分阶段验收、关键决策与剩余项。可参考 建设计划。
- 追踪调用方和数据流后实施。先用定向测试缩短反馈周期,最后运行全量验收。
pnpm harness context routing
pnpm harness verify routing
pnpm harness verify
工程约定
- UI 沿用 Vue 3 Composition API、
defineComponent+ TSX 与现有 SFC 的<script setup lang="ts">,优先复用 Naive UI 和项目组件。图表使用 ECharts。 - Vue、Router 和 Pinia API 由
unplugin-auto-import管理。类型使用import type,生成声明通过生成器更新。 - 路由维持名称唯一、权限 meta、缓存和翻译键。变更权限时同时验证菜单可见性和直接导航。
- Store 对外复用
src/store/hooks。持久化 key 和序列化格式属于已有数据契约,变更前检查历史数据。 - 请求从
src/api进入src/axios。Mock 只用于演示与本地验证。服务端密钥不能放入会打包到浏览器的VITE_*。 - 维护公共 API 时检查调用方、导出与已有回归测试。涉及工程配置时更新对应文档和 验证记录。
验收与证据
| 命令 | 验证范围 |
|---|---|
pnpm harness check |
上下文路径存在,回归路径至少指向一个测试文件 |
pnpm harness verify <scope> |
环境检查和该任务域的 Vitest 回归 |
pnpm harness verify |
pnpm check 的全部检查 |
pnpm check |
环境、Harness、图标同步、类型、规范、格式、单测、生产构建 |
verify 逐步执行,首个失败即停止并返回非零退出码。运行结束时打印 .harness-local/runs/<run>/report.json 的位置,其中记录命令、结果、耗时、运行时和信号。每次执行独立留档。全量报告以 pnpm check 作为一个步骤,阶段详情查看当次终端输出。参数或上下文校验失败,以及被强制中断的运行,可能没有报告。
GitHub Actions 在 Linux、Windows 和 macOS 运行同一份 pnpm check。单独执行 pnpm lint、pnpm format:check 和 pnpm typecheck 可定位问题。pnpm lint:fix 与 pnpm format 会改写文件。pnpm check 会同步图标清单并生成 dist/production,交付前检查生成差异。
浏览器验收
页面行为变化时使用 pnpm dev,打开 http://127.0.0.1:9527/ray-template/。涉及构建或部署子路径时,运行 pnpm build 和 pnpm preview,使用终端给出的地址和部署 base。用本地演示数据复现,核对受影响的路由、动作和控制台错误。
| 变更 | 检查 |
|---|---|
| 页面、主题或文案 | 对应页面、简体中文和英文、明暗主题。布局改动增加窄屏检查 |
| 路由、权限或缓存 | 从菜单进入、直接访问、刷新,核对守卫和恢复行为 |
| 图标、部署 base 或构建 | 检查生产预览、资源 URL 和控制台 |
在交付或 PR 中记录复现步骤、实际结果及未验证项。临时报告、日志和截图放入 .harness-local/。浏览器结果单独记录,单元测试报告仅覆盖其中列出的命令。
维护
影响外部读者的功能或兼容性改动,按 站外文档交接 同步到文档仓库。
任务域的路径或测试位置变化时,更新 scopes.json 并运行 pnpm harness check。测试目录以 / 结尾,单个文件使用仓库相对路径。优先完善现有测试和上下文入口,把可稳定复现的失败纳入共同检查。