maxgfr/reconstruct

# 重建 [](https://github.com/maxgfr/reconstruct/actions/workflows/ci.yml) `reconstruct` 是一个 [Agent Skill](https://www.skills.sh/)（Vercel 的开源代理技能生态系统）。它将一个 **薄的确定性框架** 与一个 **厚的 AI 演练本** 配对：一个捆绑的、无依赖的 Node 脚本提取通用事实，为主要的框架解析路由（及其 HTTP 方法），并为其他所有内容提供 *候选提示*；运行技能的 AI 代理提供对 **任何** 堆栈的更深入框架感知理解——完整的界面表面、数据模型和真实特性。 ## 安装 ``` # 进入当前项目（已提交，团队共享） npx skills add maxgfr/reconstruct # 或全局应用于所有项目 npx skills add -g maxgfr/reconstruct ``` 这将技能安装到您的代理中（Claude Code，Cursor，Codex，…）。然后只需提问即可： ## 它产生的内容 ``` reconstruction/ ├── REBUILD.md # master plan: build order + validation checklist ├── RECONSTRUCTION.md # (--merge) the whole tree in one markdown, WITH embedded source ├── SPECS.md # (--specs) the whole spec, code-free — the file to implement from ├── FEATURES.md # (--features) every feature PRD only, in build order ├── SUMMARY.md # (--summary) one-page digest of the reconstruction ├── 00-overview/PRD.md # product summary, stack, metrics, feature index ├── architecture/ │ ├── ARCHITECTURE.md # architecture + external services, cross-cutting policies, i18n message catalog │ ├── INTERFACES.md # interface surface (method · path · kind · handler) + per-op input/output/side-effect contracts │ ├── DATA-MODEL.md # entities, fields, relations, indexes + enums & domain types │ └── diagram.md # mermaid module diagram ├── features/ │ └── NN-/PRD.md # one PRD per feature/module (build-order tiered) ├── data/ # ground truth, copied verbatim │ ├── translations/ # i18n files │ ├── schema/ # DB schema / models │ └── config/ # build/lint/env config ├── source/ # (fidelity=mirror) copied real source, per feature └── inventory.json # machine-readable manifest ``` ## 两个轴 + 保真度 | 轴 | 值 | 影响 | | --- | --- | --- | | **模式** | `preserve` \| `redesign` \| `scratch` | 保持当前架构，为相同的功能设计一个全新的架构，或从访谈（见 [从头开始](#from-scratch-greenfield)）构建 **绿色田野**。 | | **级别** | `light` \| `complex` | 忠实且简洁，或者也可以建议代理折叠的改进。 | | **保真度** | `mirror` \| `embed` \| `describe` | 复制真实文件 / 内联关键代码 / 文本。 | 保真度默认值由以下值派生（使用 `--fidelity` 覆盖）： | 模式 + 级别 | 保真度 | | --- | --- | | preserve + light | `mirror` | | preserve + complex | `embed` | | redesign + light | `embed` | | redesign + complex | `describe` | ## 独立 CLI 确定性引擎也可以独立运行（没有代理，没有 API 密钥）： ``` node scripts/analyze.mjs --repo ./my-app --out ./my-app/reconstruction \ --mode preserve --level light --fidelity mirror # 无需编写任何内容即可检查原始库存 node scripts/analyze.mjs --repo ./my-app --json ``` 运行 `node scripts/analyze.mjs --help` 以获取所有标志。 ## 打包：一个文件或摘要 四个可选的、可组合的标志将多文件树压缩： - `--merge` → **`RECONSTRUCTION.md`**：整个树在一个连贯的 markdown 中（单个 H1，链接目录，标题降级一级；有序概述 → 架构 → 功能 → 构建顺序），**包含嵌入的原始源**。完整的存档。 - `--specs` → **`SPECS.md`**：与 `--merge` 相同的 **整个树** — 概述、架构（接口 + 数据模型）、每个功能 PRD、构建顺序——但每个文档的 `## 源材料` 部分（嵌入的原始源代码）**被删除**。自给自足（它携带功能 PRD 引用的合约）但无代码，因此它是您向代理提供的单个文件**(重新)实现项目**。 - `--features` → **`FEATURES.md`**：每个功能 PRD 仅此而已——产品功能——按构建顺序，在一个文件中（单个 H1 + 目录）。 这是 `--merge` 的功能唯一对应版本。 - `--summary` → **`SUMMARY.md`**：从清单（堆栈、库、大小、按构建顺序的功能、接口/数据计数、区域设置、未知项、下一步）的一个页面摘要。 ``` # 内联：一次性生成树和包 node scripts/analyze.mjs --repo ./my-app --out ./my-app/reconstruction --merge --specs --features --summary # 独立后步骤：（重新）从现有输出构建包，无需 --repo node scripts/analyze.mjs --merge --specs --features --summary --out ./my-app/reconstruction # 仅从现有重建中实现无代码规范： node scripts/analyze.mjs --specs --out ./my-app/reconstruction ``` 独立形式读取 `/inventory.json` + `.md` 文件，是幂等的，如果目录中没有 `inventory.json`，则明确错误。 ## 验证：它实际上可构建吗？ 只有当新的代理可以从 PRD + 架构文档单独正确地重建每个单元时，重建才有用。一旦 PRD 被丰富，运行可构建性网关： ``` node scripts/analyze.mjs --check --out ./my-app/reconstruction ``` 它在结构失败时退出非零——未解决的 `🧠` 调用或 `fill this in` 占位符、一个引用了未记录实体/操作的特性、缺少脊柱的功能 PRD、未覆盖的区域设置，以及 **被掏空** 的数据模型/界面表面/功能 PRD（一个空白的合约也会失败，而不仅仅是充满调用的一项）。 `--check` 覆盖结构；PRD 必须实际携带的 **九个合约类别**——字段级数据模型、完全枚举的枚举、操作 & 写合约（一个公共写操作不能要求所有者外键）、格式验证、外部服务、量化策略、i18n 消息目录、共享/所有 UI 组件——在 `references/buildability-checklist.md`（./references/buildability-checklist.md）中。在绿色田野模式下，引擎在渲染之前也 **验证计划的连贯性**，因此可以捕获悬空引用和匿名写入所有者-FK 冲突。 ### 两个验证层：确定性网关 + AI 审查 `--check` 是 **确定性的**——它证明 *结构*（没有遗留的调用，文档声明了实体/操作，每个 PRD 都保持其脊柱）。它不能判断 *实质*：一个 PRD 可以通过网关并通过仍然不可构建（模糊的需求、仅 Happy-path 的标准、一个不满足的写合约、一个与数据模型矛盾的枚举值）。第二个判断是 **AI 审查**——通过技能执行，而不是脚本：因为没有 `--ai` 标志和没有 API 密钥，因为运行技能的代理 *就是* 审查员。一旦 `--check` 通过，代理重新读取树并应用 `references/ai-review-rubric.md`（./references/ai-review-rubric.md）（故事完整性、可测试的需求、真实的 Given/When/Then 包括失败路径、可满足的写合约、枚举保真度、跨文档一致性、忠实性、i18n 和重建自测），在适当的位置修复每个 **阻止者**。层 1 快速且 CI 友好；层 2 是智能模型获得回报的地方。 ## 从头开始（绿色田野） 还没有存储库？将 **想法** 转换为相同的重建树。只需向您的代理提问： **您不需要手动编写 `plan.json`——代理会做。** 根据 `SKILL.md`（./SKILL.md）→ `references/scratch-playbook.md`（./references/scratch-playbook.md），它 **采访您**（文档式提问风格：一次一个问题，每次都推荐一个答案），编写领域文档（`CONTEXT.md`，`docs/adr/`）和 **`plan.json`**——采访的结构化记录——然后运行引擎并丰富 PRD： ``` # 代理为您运行此操作，一旦访谈生成了 plan.json node scripts/analyze.mjs --scratch --plan plan.json --out ./reconstruction --level complex --tdd ``` `plan.json` 是代理从您的答案生成的中间工件。如果您更喜欢，您可以手动编写一个——模式和工作示例在 `references/scratch-plan-schema.md`（./references/scratch-plan-schema.md）中。 绿色田野合并两个轴——模式始终是 `scratch`，保真度被强制为 `describe`（没有源可以镜像）——而 `--level` 仍然适用（`complex` = 一个更深入的采访，也提出替代方案和更多的 ADR）。在常规树之上，它还编写了采访的领域文档，`INTERFACES.md` / `DATA-MODEL.md` 从计划中 **预先填充**——以及采访捕获的枚举、外部服务、横切策略和 i18n 消息目录，因此从头开始的树与反向工程树一样可构建： ``` reconstruction/ ├── … # the same REBUILD / overview / architecture / features tree ├── CONTEXT.md # the glossary (from plan.glossary + data-model relations) └── docs/adr/NNNN-*.md # one terse ADR per recorded decision ``` `CONTEXT.md` 和 `docs/adr/` 在 **不存在时** 编写，因此您在采访期间编写的更丰富的版本永远不会被覆盖。添加 `--tdd`（在这里或任何模式中）以使每个功能 PRD 和 `REBUILD.md` 驱动构建 **测试优先**（红 → 绿 → 重构）。 - **采访**：`references/scratch-playbook.md`（./references/scratch-playbook.md） - **`plan.json` 合约 + 示例**：`references/scratch-plan-schema.md`（./references/scratch-plan-schema.md） - **一个完整的计划**：`tests/fixtures/scratch-plan/example.plan.json`（./tests/fixtures/scratch-plan/example.plan.json） （`pnpm run parity` 渲染此计划并检查它是否可构建；通过传递 `-- --repo ` 也检查代码路径和从头开始的路径收敛）。 ## 重建工作原理 1. 读取 `00-overview/PRD.md`、`architecture/ARCHITECTURE.md`、`architecture/INTERFACES.md` 和 `architecture/DATA-MODEL.md`。 2. 按照在 `REBUILD.md` 中的依赖层级构建顺序，一次实现一个 `features//PRD.md`。 3. 使用 `data/`（以及存在时使用 `source/`）作为事实。 **任何堆栈**。确定性框架是通用的（树、依赖项、环境、i18n、堆栈/库检测，以及路由/API/模式/入口点的 *候选提示*——因此没有专用适配器的堆栈永远不会看不见）。在此基础上，**路由适配器通过一个小型可插拔注册表为八个框架家族解析真实路由——及其 HTTP 方法**（Next.js、Express、Flask、FastAPI、NestJS、Django、Rails、Go）。更深入框架感知的深度——完整的界面表面和数据模型——来自 `SKILL.md`（./SKILL.md）+ `references/`（./references）中的 AI 演练本，以及在每个堆栈中的作弊表单在 `references/stack-guides/`（./references/stack-guides）中（Next.js、Remix、Nuxt、SvelteKit、Astro、Express/Fastify/Hono、NestJS、Django/Flask/FastAPI、Rails、Laravel、Go、Spring Boot、tRPC/gRPC、GraphQL、移动）。为堆栈添加代理指导只是 markdown；添加确定性路由适配器是一个小型、自包含的代码 PR——见 `references/adapters.md`（./references/adapters.md）。 ## 开发 ``` pnpm install pnpm run build # bundles src/ -> scripts/analyze.mjs (committed, zero-dep) pnpm test # vitest unit + integration over multi-stack fixtures pnpm run typecheck ``` ## 安全性 分析器只 **读取** 目标存储库的文件系统并将文件复制到输出。它永远不会执行分析项目中的代码。在运行在不受信任的存储库之前，请审查 `scripts/`。 ## 许可证 MIT © maxgfr

标签：AI 辅助开发, DNS解析, GNU通用公共许可证, Homebrew安装, MITM代理, Node.js, OSV, PRD 生成, Vercel, 代码分析, 代码重构, 凭证管理, 工作流, 开发效率, 开源项目, 技能平台, 接口设计, 数据模型, 数据管道, 架构设计, 知识提取, 网络可观测性, 自动化攻击, 软件工程, 软件重构, 防御加固