mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-22 19:43:37 +08:00
5.3 KiB
5.3 KiB
AI Harness 建设计划
目标是让接手 Ray Template 的开发者和 AI 助手,能按任务找到相关代码、独立复现验证,并把实际结果交给下一位维护者。工程入口和命令见 AI Harness。
| 阶段 | 建设内容 | 验收条件 |
|---|---|---|
| 1. 收拢上下文 | 重写根 AGENTS.md,移除旧工具配置和旧开发指南。保留架构、注释、视觉和工具链的各自职责 |
README 指向新入口,活跃文档没有旧指南引用。TypeScript 项目说明可从架构地图找到 |
| 2. 建立反馈 | 按路由、UI、API、图标、公共工具和 Harness 提供上下文与回归。复用 pnpm、Vitest 和构建命令 | 任务域可查询,定向验证可执行,缺失的上下文或回归路径会被拒绝 |
| 3. 接入验收 | 将 Harness 校验纳入 pnpm check 和现有 CI,提供本机 JSON 报告与浏览器验收步骤 |
定向和全量运行均可追溯,失败会以非零退出码返回,报告与截图排除在源码和打包输入之外 |
日常维护时,以实际反复出现的失败为依据扩充 Harness。优先将已有覆盖缺口补进 Vitest,待浏览器流程有稳定夹具和可重复结果时,再评估纳入自动化门禁。迁移的实测结果见 工具链记录。
设计参考 OpenAI Docs 的仓库工作流实践 与 上下文分层建议。
Monorepo 索引补全
审查基线为 58fc0b63。现有命令、回归和报告已形成反馈闭环,主要缺口在查找和判断代码归属:
| 发现 | 影响 |
|---|---|
架构地图混用旧 src/ 路径与工作区路径,仍将路由、图标和组件实现归到应用目录 |
目录存在不等于拥有实现。例如应用侧 Schema、取消器和部分组件只是兼容入口 |
ui 同时覆盖布局、公共组件、文案、Hooks 和演示;没有 TablePro、文档站及构建的独立入口 |
查表格筛选或 VitePress 重定向时,需要自行从大目录找实现、示例和验证 |
llms.txt、架构地图与 scopes.json 分别列源码路径;检查只覆盖 JSON 里的路径 |
文件移动后,入口和说明可以互相矛盾而全量检查仍通过 |
设计
AGENTS.md只保留仓库级协作约定和入口;llms.txt提供无需运行时的任务路由,按需链接 架构地图 和具体主题。harness/context/<scope>.md按实际问题列首读源码、应用/共享包/示例边界及相关测试。行为契约留在源码、就近 README 和公开文档中。架构地图说明工作区、关键运行链和部署。scopes.json保存主题简介与可执行验证配置;按 ID 定位同名索引,context <scope>直接显示。保留六个已有 ID 和各自测试,新增 TablePro、布局、文档站和工具链。文档与工具链使用已有检查脚本。- 将索引入口、相对链接和测试目标接入现有
harness check,继续由pnpm check和 CI 执行。范围是导航文档,不追踪外链或证明描述正确;语义通过走查和回归验证。
实施前自审
| 检查 | 修订后的决定 |
|---|---|
| 是否要在 JSON 和 Markdown 重复维护实现路径? | 用同名索引作为 CLI 输出,正文只维护一份;不生成第二份源码树 |
| 是否让每个任务先跑命令、阅读全图? | 保留静态入口;按需求打开一张主题索引。架构图用于跨模块任务,不作为前置必读 |
| 是否给所有任务域强行配 Vitest? | 文档用 docs:check;工具链用包边界与类型检查。明确哪些问题仍需生产预览或全量检查 |
| 是否能区分同名入口与真正实现? | 用 TablePro 搜索、动态路由、请求取消、偏好导入、旧文档重定向和部署产物逐条走查,索引写明主实现和宿主适配 |
验收:静态入口可到达所有主题;原命令和报告契约兼容;断链、缺失主题和失效回归路径会使检查失败;代表任务能从索引到达实现和验证;最后执行 pnpm harness verify。