tracekit

「e2e 闭环验证 + 项目知识库」互补回路的可复用框架。

内核：知识库写的每条结论，由 e2e 实测验证过才算"已验证"；e2e 跑出的铁证，回填进知识库——文档不再和代码对不上。

📖 完整设计与决策看 docs/tracekit.md（权威总览，先读这个）。

是什么

• 通用框架（本仓库，可复用）：节点契约 + runner + 多层校验 oracle（core/）、统一工作台（ui/：React 测试台 + 知识库门户 + 项目资源，一个端口三视图）、脚手架（kit/ + bin/tracekit.js）。
• 每个接入项目：独立工作区仓库，外挂"自动化 + 知识库"，通过 tracekit.config.json 的 resources 关联实际代码仓（不钻进代码仓就地初始化）。

快速上手

# 1) 建 tracekit 工作区（dir 缺省=当前目录）
node bin/tracekit.js new ~/work/my-app "我的项目"
#   或就地：cd ~/work/my-app && node <tracekit>/bin/tracekit.js new

# 2) 进项目、开 Claude Code，跑初始化向导
cd ~/work/my-app && claude
/tracekit-start          # 收集前后端/需求 → 自动判定 mode → 关联写进 tracekit.config.json → 按 mode 路由

# 3) 起统一工作台（测试台 + 知识库门户 + 项目资源）
node bin/tracekit.js serve        # localhost:4400

# 框架升级后，项目目录内：node <tracekit>/bin/tracekit.js update

npm 包名 loopcheck（原拟 tracekit 被占、trace-kit 撞 npm 相似名保护，故取 loopcheck=e2e 闭环验证）：npm i loopcheck；CLI npx loopcheck <cmd>（bin 提供 loopcheck/tracekit 两命令，tracekit serve 兼容保留）。 仓库开发时可直接运行 node bin/tracekit.js <cmd>。（trace-kit 也避开了 tracekit 与 macOS 系统命令同名的问题。）

命令

| 命令 | 作用 | |---|---| | new [dir] [name] | 创建 tracekit 工作区（CLAUDE.md + .claude/skills + 知识库门户 + e2e + 配置） | | update [dir] | 同步框架最新托管部分进已有项目（不碰配置与已填知识库内容） | | serve [dir] | 启动统一工作台 server | | doctor [dir] | 诊断项目接入就绪度（config / e2e / manifest / 知识库 / 工作台适配器），--json 可供 CI 消费 | | help | 用法 |

给人看的最小用法

在一个 trace 仓库里，人只需要记这几个入口：

tracekit doctor .     # 看当前仓库是否可用
tracekit update .     # 同步框架托管内容：skills / runner / workbench adapter / 知识库模板
tracekit serve        # 打开工作台

如果是在 Claude 终端里说话，日常只记一个主入口：loop-integrate。它是用户级入口，但执行时只读当前目录项目的 README.md / CLAUDE.md / tracekit.config.json。

使用 loop-integrate 读取当前代码和需求，更新事实追踪、e2e 和知识库，给我一份待裁决报告

对外只保留下面几个意图级 skill：

| Skill | 什么时候用 | 你可以怎么说 | |---|---|---| | loop-integrate | 日常总控：读代码/需求/测试，更新事实、e2e、知识库并汇总待裁决项 | “使用 loop-integrate 刷新当前 trace 仓库” | | loop-setup | 初始化、升级、检查仓库 | “使用 loop-setup 同步并检查当前 trace 仓库” | | loop-prd | PRD/需求 Excel diff / 需求复核 | “使用 loop-prd 复核这次需求变更” | | loop-bug | one-bug/Tower bug 修复流程、closeout 验证与反哺 | “使用 loop-bug 处理我的待修 bug” | | loop-daily-e2e | 复用现有节点组合日常应用 E2E 风险巡检 | “使用 loop-daily-e2e 生成本项目的日常巡检套件” |

loop-evidence、loop-knowledge、Playwright / Excel 辅助能力留在框架 kit 里作为底层/专用能力，默认不铺到项目，避免入口太多。

项目关系的记录规则：

• 当前项目的人类可读关系写在项目 README.md 或 CLAUDE.md 的项目补充段。
• 当前项目的机器可读关系写在 tracekit.config.json 的 resources。
• tracekit new/update/serve/doctor 会维护用户级本地索引 ~/.loopcheck/projects.json，只用于定位已接入项目，不作为全局中枢配置。
• skill 如果发现前端/后端/PRD/Tower/one-bug 关系缺失，应先询问，得到答案后写回当前项目文件。

目录结构

core/         框架核心（节点契约 defineNode / runner runSteps / value-map / 多层校验 oracle）
ui/           统一工作台：server.js + app/(React 测试台 + 原生知识库门户，共享渲染内核)
kit/          脚手架素材：知识库模板 + .claude(CLAUDE.md/skills/command) + SOP + 配置模板 + React 门户产物
bin/tracekit.js  脚手架 CLI（new / update / serve / help）
docs/         tracekit.md(权威总览) + 设计 spec + logs-artifacts-design
SKILL.md      框架 skill 描述；FORMATS.md  节点/清单/value-map 格式参考

文档导航

• docs/tracekit.md —— 权威总览与决策（架构 / CLI / 技能 / 配置 / 工作台 / 知识库结构 / 待办）
• kit/README.md —— 脚手架细节
• SKILL.md / FORMATS.md —— 框架用法 / 格式
• docs/logs-artifacts-design.md —— 日志+产物事件流（GitHub Actions 式）
• 历史设计 spec：docs/2026-06-04-*、docs/2026-06-08-*