coryhacking/wavefoundry

# Wavefoundry [](https://github.com/coryhacking/wavefoundry/releases) [](https://modelcontextprotocol.io) [](https://github.com/coryhacking/wavefoundry) [](https://www.python.org/downloads/) [](LICENSE) 你的 AI 编码 agent 会忘记它上个会话做了什么，跳过你要求它遵循的审查步骤，并且交付偏离计划的工作成果。Wavefoundry 是一个针对这三者的本地框架。它在你的机器上运行。没有服务，没有账号，没有遥测。 ## 适用对象 - 正在使用 **AI 编码 agent 交付生产级工作** 的团队或独立工程师。 - 注重审查规范、可追溯性以及“之前做了什么决定？”的代码库。 - **目前还没有太多工程流程**，但拥有将长期维护的代码的团队：Wavefoundry 提供了你原本需要自己发明的结构，并且从第一天起 MCP 智能功能就能发挥作用，即使在生命周期门禁启用之前也是如此。 任何将要长期存在的东西都能从中受益。 ## 你将获得什么 **结构化的交付生命周期** — 规划变更 → 准备 wave → 实施 → 审查 → 关闭。其中两个阶段是强制门禁。`Prepare wave` 会拒绝推进不完整的变更文档。未经操作员签字，`Close wave` 将拒绝执行。 **一个具备代码库工作知识的本地 MCP 服务器。** 运行生命周期的同一服务器会在本地为你的代码和文档建立索引，并将其作为 agent 工具公开： - **针对代码和文档的语义搜索** — agent 根据意图进行搜索，而不是依赖 grep 匹配模式，并在你的代码和 `docs/` 目录树中提供重新排序后的结果。 - **代码图查询** — 调用层次结构、影响分析、引用、依赖项遍历、社区聚类。 所有这些都作为 MCP 工具公开 — `docs_search`、`code_search`、`code_ask`、`code_callhierarchy`、`code_impact`、`code_references`、`code_graph_community`、`wave_graph_report` 等等。它们在任何 wave 运行之前就能工作。agent 不再凭空捏造不存在的函数，而是开始从你的实际代码中回答“我们在哪里处理了 X？”。 **内置机密检测。** 该框架在每次 wave 中使用基于 [Gitleaks](https://github.com/gitleaks/gitleaks) 的 TOML 规则集（MIT 许可证，由社区维护）扫描你的项目中的硬编码凭证、API 密钥和 token。检查结果会记录在 `docs/scan-findings.json` 中，并具有生命周期 — `pending` → `false-positive`（需要多名审查人员确认）或 `confirmed-secret`（需要在每次 wave 中得到操作员确认）。在所有检查结果解决之前，`Close wave` 将拒绝执行。随时调用 `wave_scan_secrets` 进行按需扫描；当规则集发生更改时，增量模式会自动升级为全面扫描。 ## 设计原则 - **本地优先。** 操作状态存在于磁盘上的代码仓库和你的主目录中。没有服务，没有账号，没有遥测。 - **结构强制优于策略。** 门禁在框架中触发，而不是在种子 prompt 语言中触发。agent 无法通过花言巧语绕过 `wave_close`。 - **框架作为可部署的制品。** Wavefoundry 以 zip 格式发布，任何代码仓库都可以安装或升级。该框架在 Wavefoundry 自身的 wave 流程中演进、打包，并传播到下游项目。 - **对范围诚实。** 必需的就是必需的；可选项会被明确标记。 ## 前置条件 三个硬性前置条件。在全部满足之前，请勿运行任何安装命令。 1. **Python 3.11 或更高版本。** 使用以下命令检查： python3 --version # 预期：Python 3.11.x（或更高） *在 `python3 --version` 报告 3.11 或更高版本之前，请勿继续执行此步骤之后的操作。* 通过你的包管理器（`brew install python@3.11`、`apt install python3.11`）或 [`pyenv`](https://github.com/pyenv/pyenv) 进行安装。 2. **受支持的宿主机操作系统** — macOS、Linux，或通过 WSL2 运行的 Windows。 3. **支持 MCP 的 agent 宿主。** 建议首次安装时使用 **Claude Code** 或 **Codex CLI** — 两者都从磁盘配置（`.mcp.json` / `.codex/config.toml`）自动加载 MCP，因此安装过程无需任何手动 UI 步骤即可运行。**Cursor**、**Junie**、**GitHub Copilot**、**Windsurf**、**Air** 和 **Warp** 也可以通过它们各自的 MCP 接口进行连接 — 请参阅 [宿主支持](#host-support)。 ## 快速开始 两个操作员步骤，一次 MCP 重启，如果 Python 已就绪大约需要 3 分钟。**安装由 agent 驱动** — 你只需将 zip 文件放入你的代码仓库并输入 `Install Wavefoundry`；剩下的由 agent 完成。 ### 安装指南 安装在**两个阶段**中进行，两者之间需要重启 MCP 宿主。这两个阶段都由 agent 驱动 — 操作员仅有的操作是拖入 zip 文件、输入安装指令，以及在 agent 提示时重启你的宿主。 **(a) 将发布版的 zip 文件放在你的代码仓库根目录** 前往 [Releases](https://github.com/coryhacking/wavefoundry/releases) 并下载附加到**最新版本**的资产。将 zip 文件 — 保持压缩状态，不要解压 — 放在你目标代码仓库的根目录中。 **(b) 将此快捷指令作为聊天消息发送给你的 AI agent：** ``` Install Wavefoundry ``` 这是发送给你的 AI agent 的**聊天消息**，而不是 shell 命令。Agent 必须已经在你的代码仓库中打开（该代码仓库被设为工作目录）并连接到受支持的 AI 宿主： - **推荐用于首次安装：** **Claude Code** 或 **Codex CLI** — 两者都从磁盘配置自动加载 MCP，因此无需任何手动 UI 步骤即可运行安装。 - **同样支持：** **Cursor**、**Junie**、**GitHub Copilot**、**Windsurf**、**Air**、**Warp** — 有关各宿主的连接方式，请参阅 [宿主支持](#host-support)。 #### 第一阶段 — 引导框架（尚无 MCP） 第一阶段安装的是 Wavefoundry MCP 服务器，因此该阶段仅从你 agent 的一般功能开始运行 — 尚未调用任何 `wave_*` MCP 工具。Agent 会： - **解压发布版的 zip 文件。** 标志：`.wavefoundry/`、`docs/` 和 `.mcp.json` 出现在你的代码仓库根目录。 - **设置生命周期起点**于 `docs/workflow-config.json` 中（默认设为你项目的首次 git 提交日期）。 - **运行 `setup_wavefoundry.py`** — 该编排器会在 `~/.wavefoundry/venv/` 创建共享工具 venv，安装依赖项，构建框架及项目的语义索引，写入 `.wavefoundry/bin/` 启动器和你宿主的 MCP 配置，并在你重启之前试运行 MCP 服务器以捕获启动故障。标志：编排器以 0 状态退出；最终汇总行报告索引就绪。 - **停止并告诉你重启你的 MCP 宿主。** 这是明确的阶段 1 → 阶段 2 的交接；不要尝试在当前的 agent 会话中继续。 #### → 重启你的 MCP 宿主，然后继续 退出并重新启动你的 agent，或使用你宿主的 MCP 重新加载命令。重启后，`wavefoundry` MCP 服务器会出现在你宿主的 MCP 服务器列表中，并且 agent 可以调用 `wave_*` 工具。 **要继续，请再次输入 `Install Wavefoundry`。** 安装快捷方式是状态感知的：当 `.wavefoundry/install-log.md` 已经存在时，agent 会从第一个未勾选的行（即第 2 阶段的第 2.1 行，`wave_install_audit(phase=1)`）继续。不需要单独的“开始第 2 阶段”的指令。 #### 第二阶段 — 项目发现（由 MCP 驱动） 在可以访问 MCP 服务器的情况下，agent 会逐行遍历 `.wavefoundry/install-log.md`，在行与行之间调用 `wave_install_audit` 以强制执行边做边 lint（lint 错误和缺失的制品会阻碍进展）。第 2 阶段引导为你的代码仓库量身定制的项目专属制品 — 这也是 Wavefoundry 从一个通用的安装程序转变为看起来像*你的*代码仓库的框架的阶段。Agent 会： - **审计阶段 1 的制品**（`wave_install_audit(phase=1)`） — 如果有任何缺失则进行恢复。 - **分析你的代码仓库** — `docs/repo-profile.json`（原型、特征、适用因素）、`docs/repo-index.md`。 - **引导规范的 `docs/` 结构** — `architecture/`、`contributing/`、`plans/`、`references/`、`prompts/`、`waves/`、`agents/`。 - **生成各角色的 agent 文档** — 按启用的角色生成 `docs/agents/.md`，包括从其权威 seed 加载的三个委员会专家角色（`wave-council`、`red-team`、`archetype-council`）。 - **映射你的架构** — `docs/ARCHITECTURE.md` 以及 `current-state.md`、`domain-map.md`、`layering-rules.md`、`cross-cutting-concerns.md`、`data-and-control-flow.md`、`testing-architecture.md`。 - **确立基态** — `QUALITY_SCORE.md`、`RELIABILITY.md`、`SECURITY.md`、`PERFORMANCE.md`（视情况而定）。 - **配置文档门禁**，**生成 prompt 接口**，**引导 wave 制品**，**合成角色设定**，**引导角色专属日志**，以及**登记偏移预期**。 - **确认完成。** 最终的 `wave_install_audit()` 返回 `{status: "complete"}`。Agent 会提供一份操作员总结，涵盖已 seed 的内容、工作流、命令、角色以及文档门禁。 ## 安装内容 `Install Wavefoundry` 完成后，你的代码仓库将具有以下结构。它是持久化的 — 在升级过程中，相同的路径会出现在相同的位置。 ### 在你的代码仓库中 ``` .wavefoundry/ framework/ Framework code, seeds, dashboard assets bin/ Repo-local CLI shims index/ Local semantic + graph indexes (LanceDB) * logs/ Build, upgrade, dashboard logs * docs/ prompts/ Public command catalog waves/ Wave records — your delivery history plans/ Change docs being authored architecture/ Architecture docs agents/ Agent role docs, journals, session handoff references/ Long-form project references AGENTS.md Agent-facing entry surface CLAUDE.md Claude Code-specific entry surface .mcp.json MCP server stdio entry ``` \* `.wavefoundry/index/` 和 `.wavefoundry/logs/` 已被 gitignored — 属于单机且可重新生成。一些宿主机本地的 runtime 制品也已被 gitignored：`.wavefoundry/guard-overrides.json`、`.wavefoundry/dashboard-server.json`、`.wavefoundry/*.lock`、`.wavefoundry/framework/test-cache.json`。 Wavefoundry 仅写入上述路径。框架本身会被提交，因此团队中的每个人都会拥有锁定在代码仓库中的相同版本。如果你运行特定于宿主的渲染器（Claude Code、Cursor、Codex、Junie、GitHub hooks），它们将写入 `.claude/`、`.cursor/hooks.json`、`.codex/config.toml`、`.junie/` 和/或 `.github/hooks/` — 所有这些都会被提交。 每个 `docs/` 子目录包含的内容 — agent 会读取它们以作为其工作的基础： - **`docs/prompts/`** — agent 查询以路由快捷指令的目录（`Plan feature`、`Create wave` 等）。 - **`docs/waves/`** — 你的交付历史。每个关闭的 wave 都是一条已提交的记录，说明了谁决定了什么、谁进行了审查以及交付了什么。 - **`docs/plans/`** — 在被接纳进 wave 之前，正在编写的变更文档的暂存区。 - **`docs/architecture/`** — 领域映射、分层规则、当前状态快照、数据/控制流、ADR。Agent 在起草计划之前会阅读此内容，以免违反边界。 - **`docs/agents/`** — 角色文档（wave-coordinator、planner、reviewer 专家）、角色设定、日志以及会话交接文件。Agent 在每一步之前都会阅读其自身的角色描述和任何活动的监控点。 - **`docs/references/`** — 持久的项目上下文：记忆、已知陷阱、项目概述。 ### 在你的用户主目录中 | 路径 | 用途 | |---|---| | `~/.wavefoundry/venv/` | 共享工具 venv（依赖项 — LanceDB、ONNX 等） | | `~/.wavefoundry/cache/fastembed/` | Embedding 和 reranker 模型权重（FastEmbed 量化的 ONNX），在首次构建索引时从 H Face 获取，此后进行本地缓存 | ### 网络足迹 **Runtime 时对 Wavefoundry 控制的端点访问为零。** Embedding 模型权重会在首次构建索引时从 Hugging Face 获取，并在此后进行本地缓存。依赖项会在 `setup_wavefoundry.py` 期间以及框架升级期间通过 `uv`（或 `pip` 回退）进行安装。没有服务，没有账号，没有遥测。 ## 你的第一个 wave 三轮对话，从头到尾。第 3 步包含一个你无法用语言绕过的结构性拒绝 — 这正是该框架的核心意义所在。 ### 1. 规划变更 ``` > Plan feature: add /healthz endpoint to the API server [agent reads docs/architecture/, drafts the change doc] Agent: I've drafted docs/plans/12abc-feat add-healthz-endpoint.md with Rationale, Requirements, Acceptance Criteria, Tasks, and Risks. Want me to admit it into a new wave? > yes, create a wave for it ``` Agent 创建了一个*变更文档*（针对单个工作单元的计划制品），并准备将其并入一个*wave*（接纳一个或多个变更的交付单元）。 ### 2. 创建 wave，接纳，准备 ``` > Create wave: api-healthz Agent: Created docs/waves/12abd api-healthz/wave.md. Admitting 12abc... Wave status: planned, 1 admitted change. > Prepare wave Agent: Running readiness checks… - Change docs complete: ✓ - AC priority recorded: ✓ - Required review lanes selected: code-review, qa-review: ✓ - Wave Council readiness review: PASS Wave status: active. Pre-implementation review gate next. ``` `Prepare wave` 是一个真正的门禁。文档 lint 必须通过。每个接纳的变更文档必须完整。必须记录验收标准（AC）优先级。配置后，结构化的委员会审查必须记录 `wave-council-readiness`。只有满足这些条件，wave 才会被**就绪** — 它保持为 `planned` 状态；一个独立的、单一 OPEN 门控步骤（`Implement wave`）会将其开启为 `active`/`implementing`。任意数量的 wave 可以并行进行计划和就绪；但同时只能有一个处于 OPEN 状态。 ### 3. 实施，审查，关闭 ``` > Implement wave [agent edits api/server.py, adds tests, runs them] Agent: Implementation complete. Tests pass. Review lanes: code-review: approved qa-review: approved Ready to close? > Close wave Agent: wave_close returned an error. Diagnostic: operator_signoff_missing Recovery: operator must record `operator-signoff: approved` in ## Review Evidence on wave.md before close can succeed. > approved, go ahead and close Agent: Recorded operator-signoff. Running wave_close again… Wave closed. 1 change implemented. Session handoff updated. ``` 第一次尝试被拒绝正是其目的所在。`wave_close` 受到结构性的拦截 — agent 绝不可能通过花言巧语绕过它。门禁即是框架，而不是 prompt。 ## 核心概念 ### 生命周期 变更文档通过被接纳进 wave 而进入流水线。Wave 会经历五个阶段 — **规划变更**、**准备 wave**、**实施**、**审查**、**关闭** — 其中两个阶段是*强制门禁*： - **`Prepare wave`** 会阻塞，直到文档 lint 通过。每个接纳的变更都必须记录 AC 优先级。配置后，必须记录结构化的委员会就绪审查。 - **`Close wave`** 会阻塞，直到每个必需的审查通道都记录了签字，并且操作员已确认关闭。 Agent 无法绕过任何一个门禁。上面的记录展示了当缺少先决条件之一时，拒绝的情况是怎样的。 ### Waves *Wave* 是交付单元。工作以一个或多个*变更文档*的形式被接纳进 wave，通过 `Prepare wave` 进行门禁，通过 `Implement wave` 进行实施，通过 `Review wave` 进行核对，最后由 `Close wave` 封存。 **最接近的类比：** 一个功能分支结合了一份发行说明草稿。**关键区别：** wave 的生命周期具有*强制门禁* — 当未满足先决条件时，框架会拒绝关闭，而不是依赖软性约定。 ### 变更文档 *变更文档* 是针对单个工作单元的结构化计划制品：基本原理、需求、验收标准、任务、风险、决策日志。 **最接近的类比：** 一个 GitHub Issue 加上一份设计文档加上一份内部的 RFC。**关键区别：** 变更文档位于你代码仓库中的代码旁边（计划期间在 `docs/plans/`，接纳后在 `docs/waves//`），并且是 agent 读取、编辑以及框架进行 lint 的对象。 ### Seeds *Seeds* 是带编号的 prompt 主体 — 目前从 `001` 到 `250+` — 它们定义了 agent 在每个生命周期步骤中应如何表现。它们位于 `.wavefoundry/framework/seeds/` 中，涵盖了从安装框架到进行对抗性委员会审查的所有内容。 **最接近的类比：** 一份风格指南结合操作手册。**关键区别：** seeds 由 MCP 服务器（`seed_get`、`docs_search`）进行索引和检索，因此 agent 会直接在行内获取它们，而不是在每次交互时重新阅读它们。 ### 反馈传感器 分为两类：**计算型传感器**（在检查失败时会阻塞的 linter、验证器、门禁脚本）和**推理型传感器通道**（基于 LLM 的代码审查、架构审查、安全审查、QA 审查等，作为结构化证据记录在 wave 上）。机密检测是一种内置的计算型传感器 — 它在每次 wave 中扫描硬编码的凭证，并阻塞关闭，直到每一个检查结果都被分类。 **最接近的类比：** CI pipeline 结合 PR 审查分配。**关键区别：** 传感器将其检查结果作为结构化证据记录在 wave 文档本身上，并且在必需的通道签字存在之前，`wave_close` 会阻塞。 ### MCP 服务器 一个本地 MCP 服务器（`wavefoundry`）公开了对代码仓库自身文件进行操作的工具。它与你 agent 的宿主一起运行。没有服务，没有账号，没有遥测。 **最接近的类比：** 一个你自己使用结构化 I/O 调用的 CLI。**关键区别：** agent 在对话期间直接调用工具，因此生命周期门禁会在对话过程中触发，而不是仅仅在你记得运行检查时才触发。 ## 宿主支持 任何感知 MCP 的宿主都可以连接到本地的 Wavefoundry 服务器。对于某些宿主，`render_platform_surfaces.py` 会为你写入配置；对于其他宿主，你需要自行将 stdio 条目粘贴到宿主的 MCP 设置中。 | 宿主 | 操作方式 | |---|---| | **Claude Code** | `render_platform_surfaces.py --platform claude` | | **Codex CLI** | 提交的 `.codex/config.toml` 在项目受信任时加载 | | **Cursor** | `render_platform_surfaces.py --platform cursor` | | **Junie** | `render_platform_surfaces.py --platform junie` | | **GitHub Copilot · Windsurf · Air · Warp** | 将 [`docs/prompts/install-wavefoundry.prompt.md`](docs/prompts/install-wavefoundry.prompt.md) 中的 stdio 条目粘贴到你宿主的 MCP 设置中 | ## 日常指令 日常使用大约六个指令；其余功能在你需要时随时可用。 - `Plan feature` — 编写变更文档 - `Create wave` — 开启一个交付单元 - `Add change to wave` — 将变更接纳进活动的 wave - `Prepare wave` — 实施前的就绪门禁 - `Implement wave` — 由协调器管理、带有审查通道的实施循环 - `Close wave` — 具有操作员签字的结构化关闭 [完整工具接口](docs/prompts/index.md) 涵盖了 wave 管理、代码搜索、图查询、dashboard 控制、门禁管理和对抗性审查。可以从 agent 内部搜索该目录（`docs_search`、`code_ask`）。 ## 对于企业内部 fork 如果你 fork Wavefoundry 用于内部分发，上面上游的 GitHub URL（`github.com/coryhacking/wavefoundry/releases`、版本徽章的**链接目标**，以及内置 `install/install-block.md` 中的链接）需要指向你的 fork。版本徽章**图像**现在是一个静态的 shields 徽章，其值由 `build_pack.py --release` 自动加盖，因此它是 fork 稳定的 — 只需要重定向其链接目标。快捷指令、安装流程以及 zip 包内的各种接口都是 fork 稳定的；只有下载/发布页面的链接需要重定向。 当你进行 fork 时，需要更新的具体位置： - 这份 `README.md` — 版本徽章的**链接目标**（大约第 3 行；徽章图像是静态的，其版本由 `build_pack --release` 自动加盖）以及**快速开始 → (a)** 中的 Releases 下载链接。 - `.wavefoundry/framework/install/install-block.md` — 底部附近的 README 链接。此块会通过 `build_pack.py --release` 自动添加到每个发行版的说明前面，因此该链接会指向你 fork 的发布页面。 - 任何逐字引用安装步骤的内部文档或新手引导演示文稿。 该框架有意不去自动检测“这是哪个 fork” — GitHub 的远程 URL 是事实来源，但安装接口是静态的，以便气隙隔离的操作员仍然可以阅读它们。Fork 需自行管理重定向步骤。 ## 对于团队 评估 Wavefoundry 的团队通常会问三个问题。 ### 采用成本 安装它，端到端驱动一个小型的 wave，然后决定这种规范是否适合你的代码库。框架按代码仓库进行配置，完全存在于你的代码仓库以及 `~/.wavefoundry/` 中。无需运维任何基础设施，也没有需要运行的共享服务。 ### 锁定 所有的计划制品（变更文档、wave 记录）都是你 `docs/` 目录树中的 Markdown 文件。它们是可读的、可被 grep 搜索的，并且在 Wavefoundry 被删除后依然存在。`.wavefoundry/index/` 中的语义索引可以从源代码重新生成。移除 Wavefoundry 只需 `rm -rf .wavefoundry/`，如果你不想要宿主 shim，再加上 `rm .mcp.json AGENTS.md CLAUDE.md` 即可 — 你的 `docs/` 目录依然记录着已交付内容的故事。 ### 安全性 仅限本地操作。Runtime 时不对 Wavefoundry 控制的端点进行任何网络调用。没有服务，没有账号，没有遥测。Embedding 模型权重在首次构建索引时从 Hugging Face 获取，并在本地缓存。依赖项在安装和升级期间通过 `uv` 以及供应链时间锁进行安装。经过审计的文件写入接口 — Wavefoundry 从不编辑 [已安装内容](#what-got-installed) 中所示路径之外的文件。 内置凭证扫描：框架使用社区的 Gitleaks 规则集检查每个项目文件，并阻塞 wave 关闭，直到检查结果被分类。你的 `docs/scan-rules.toml` 可扩展或覆盖框架的默认设置，以满足项目的特定需求。 ## 升级 ``` Upgrade wave framework ``` Agent 会检测框架偏移，核对 prompt 和 hook 接口，运行文档门禁，重启 MCP 服务器，并更新语义索引。升级程序会搜索项目根目录、`~/.wavefoundry/` 以及 `~/.wavefoundry/dist/`，以寻找可用的最高 semver zip 包。 ## 贡献 Wavefoundry 使用 Wave 框架来开发自身。维护者使用的与发布到下游项目的 MCP 工具是相同的 — 语义搜索、代码图查询、生命周期门禁。此代码仓库中的 wave 目录就是其实践的证明。 有关如何贡献，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 安全 请参阅 [SECURITY.md](SECURITY.md) — 本地优先意味着没有可被攻击的服务，但供应链接口（`uv`、依赖项安装）依然是真实存在的。Wavefoundry 还使用内置的基于 Gitleaks 的规则集扫描你的项目文件以查找硬编码凭证；检查结果会被记录在 `docs/scan-findings.json` 中，并且必须在 wave 关闭之前得到解决。 ## 许可证 Apache 2.0 — 请参阅 [LICENSE](LICENSE)。

标签：AI辅助开发, MCP, 代码智能, 数据管道, 生命周期管理, 软件工程, 逆向工具