2026-11-04 16:47:18 +08:00

5.3 KiB
Raw Blame History

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 里的路径 文件移动后,入口和说明可以互相矛盾而全量检查仍通过

设计

  1. AGENTS.md 只保留仓库级协作约定和入口;llms.txt 提供无需运行时的任务路由,按需链接 架构地图 和具体主题。
  2. harness/context/<scope>.md 按实际问题列首读源码、应用/共享包/示例边界及相关测试。行为契约留在源码、就近 README 和公开文档中。架构地图说明工作区、关键运行链和部署。
  3. scopes.json 保存主题简介与可执行验证配置;按 ID 定位同名索引,context <scope> 直接显示。保留六个已有 ID 和各自测试,新增 TablePro、布局、文档站和工具链。文档与工具链使用已有检查脚本。
  4. 将索引入口、相对链接和测试目标接入现有 harness check,继续由 pnpm check 和 CI 执行。范围是导航文档,不追踪外链或证明描述正确;语义通过走查和回归验证。

实施前自审

检查 修订后的决定
是否要在 JSON 和 Markdown 重复维护实现路径? 用同名索引作为 CLI 输出,正文只维护一份;不生成第二份源码树
是否让每个任务先跑命令、阅读全图? 保留静态入口;按需求打开一张主题索引。架构图用于跨模块任务,不作为前置必读
是否给所有任务域强行配 Vitest? 文档用 docs:check;工具链用包边界与类型检查。明确哪些问题仍需生产预览或全量检查
是否能区分同名入口与真正实现? 用 TablePro 搜索、动态路由、请求取消、偏好导入、旧文档重定向和部署产物逐条走查,索引写明主实现和宿主适配

验收:静态入口可到达所有主题;原命令和报告契约兼容;断链、缺失主题和失效回归路径会使检查失败;代表任务能从索引到达实现和验证;最后执行 pnpm harness verify。