context-foundry

Foundry

自主构建循环：规划、构建、审查并学习。

Foundry 读取 TASKS.md 任务列表，并通过 TUI 中的 Claude Code Agent 逐项处理，每完成一项任务就提交一次。多种运行模式决定接下来会发生什么：启用任务发现并持续运行（Auto）、完成后停止（Sprint）、每项任务完成后暂停以供人工审查（Review），或作为构建服务无人值守运行（Service）。

何时使用此流水线： 对于可验证的工程工作，harness 能发挥放大作用——这类任务包含规划器可以据此确认的 file:line 引用、审计器可以检查的约束，以及 BUILD 或 AUDIT 可以针对代码验证的行为。对于写作类工作（更新 README、头脑风暴、架构决策记录、重写文档），流水线只会带来计划审查和审计成本，却没有任何额外收益，因为没有内容可供它验证。请直接完成这些工作。完整指南：docs/task-composition.md。

演示

• 用 Loop 构建第二大脑 — Foundry 自主处理实施计划，根据任务列表构建第二大脑应用，同时 TUI 实时显示每个 Agent 的输出。
• 用 Loop 增强第二大脑 — 后续运行中，foundry 从上次中断处继续，发现新工作，并基于首轮运行中学到的模式迭代第二大脑应用。
• 技术概览 — 架构参考，涵盖所有子系统：流水线、双模型竞技场、git 集成、TUI 布局、配置、插件和 MCP 工具。
• 概览 — 以德克萨斯为主题的介绍页面，面向软件架构师说明 Context Foundry。

任务流程

Load patterns from ~/.foundry/patterns/
  │
SCOUT → .buildloop/scout-report.md (investigate codebase)
  │
PLAN (+ patterns + scout report) → .buildloop/current-plan.md
  │
IMPLEMENT → build the code, run checks
  │
VERIFY (fresh context) → audit claims, fix issues, write verdict
  │
PATTERN EXTRACTOR → merge into ~/.foundry/patterns/
  │
LOCAL GIT COMMIT → feat(task_id) or WIP(task_id)
  │
OPTIONAL AUTO-PUSH → only if `auto_push_remote` is configured

工作原理

Foundry 是一个适用于 Claude Code 的 harness。每个 Agent（规划器、构建器、审查器、修复器、发现器）都是一次 Claude Code CLI 调用，拥有专属提示词和受限的工具访问权限。Rust 二进制程序负责编排、流式传输和状态管理，所有推理和文件编辑工作则由 Claude 完成。

循环

如果没有防护措施，自主构建循环很快就会退化。任务 3 会建立在任务 2 的错误之上，而任务 2 又建立在任务 1 的错误之上。错误不断累积，代码库也会偏离预期架构。

核心设计原则：任何 Agent 都不与其他 Agent 共用上下文窗口。 每个阶段都从干净的上下文开始，只接收上一阶段精心整理的产物。侦察器编写结构化报告。规划器阅读报告并编写计划。构建器阅读计划并编写代码。验证器在完全不知道代码为何如此编写的情况下阅读代码。没有共用的对话历史，没有累积的推理，也没有继承的盲点。每个阶段获取的是有用信号，而非噪声。这正是 foundry 防止错误在长任务队列中不断累积的方式。

Foundry 的循环围绕两种形式的反压设计：

短期：验证关卡。 实施完成后，验证 Agent 会在完全独立的上下文中审计更改，与构建器没有共享历史；它会运行构建检查和测试，并进行结构化代码审计。刚写完代码的模型仍保留着自己的推理过程，因此不太可能质疑自己的决定。独立实例只拿到声明和代码，更容易发现作者看不见的 bug。如果发现 HIGH 或 MEDIUM 级问题，它会修复问题并重新运行验证。如果全部通过，任务会以 feat(task-id) 提交；如果仍有问题，则以 WIP(task-id) 提交。验证关卡可防止不良代码悄然流入后续阶段。 流水线追踪（QRPBA）。 每项任务都会附带一个进度指示器，记录运行过哪些流水线阶段，以及这些阶段是否成功。该指示器会与每项任务一同保存在 TASKS.md 中，并随代码一起提交，因此你会拥有永久的审计记录。

- [x] T1.1: Set up project scaffolding          [QRPBA]
- [x] T1.2: Implement auth flow                 [--PBA]
- [x] T1.3: Add rate limiting                   [QRPBA!]
- [ ] T1.4: Write integration tests             [....]

每个字符代表一个流水线阶段：

位置	字母	阶段	含义
1	Q	查询	- = 已跳过
2	R	研究	- = 已跳过
3	P	规划	- = 已跳过（简单任务）
4	B	构建	Builder 已运行
5	A	审计	- = 已跳过
后缀	!		审计未通过（WIP 提交）

示例：QRPBA = 完整流水线，顺利通过。--PBA = 跳过查询和研究，完成规划、构建和审计。QRPBA! = 完整流水线，但审计发现了无法修复的问题（WIP 提交）。完整参考请见 docs/progress-indicators.md。

TUI 会在任务队列中以颜色标示这些指示器；由于它们直接写入任务文件，因此重启后仍会保留。

为什么精心整理上下文很重要。 这种隔离上下文架构采用的多实例审查模式，与 Anthropic 的 Claude Certified Architect 项目中所述的生产环境最佳实践相同。关键在于：Agent 通过结构化文件制品（.buildloop/scout-report.md、current-plan.md、build-claims.md、review-report.md）进行通信，而不是依赖共享的对话历史。每份制品都是经过整理的交接内容——规划器不会获取侦察器完整的工具调用历史，而是收到一份简明报告。构建器不会获取规划器的推理过程，而是收到一份包含文件操作和验证命令的确定性计划。

长期目标：模式学习。 每项任务验证完成后，模式提取 Agent 会扫描构建制品、审查结果和计划，提取可复用的经验（例如，“移动 Roblox 部件时使用 CFrame，而不是 Position”，或“字符串切片前始终验证 UTF-8 边界”）。这些经验会以结构化 JSON 的形式保存到 ~/.foundry/patterns/。在下一个任务中——无论属于哪个项目——匹配的模式都会作为参考数据注入规划器和审查器的提示词中。重复出现 3 次或以上的模式会自动提升（auto_apply），也就是说，匹配时会获得更高评分；但要纳入任务，仍至少需要与任务的关键字或 tech_stack 重叠。这就是系统随时间不断改进的方式：一次犯下的错误，会变成应用于各处的检查项。

按复杂度扩展的流水线。 并非每项任务都需要完整流水线。任务复杂度分类器会根据描述长度、关键词信号和文件数量提示，将每项任务评为简单、中等或复杂。简单任务会跳过查询、研究和规划器，采用更少的模式（0-2 个，而非 10 个），并可完全跳过审计循环——从构建器直接进入提交。QRPBA 指示器会反映这一点：---B- 表示查询、研究、规划器和审计均已跳过。复杂任务始终会执行完整流程。

学习得出的疑虑置信度。 疑虑循环使用 Ollama 嵌入向量进行语义聚类，跟踪各类任务的通过/失败历史。持续通过审查的任务描述（连续 5 次或以上顺利通过）会获得“可信”状态，并自动跳过疑虑检查。任何失败都会将该簇重置为零。随着时间推移，效果会不断累积——foundry 会学习哪些类型的更改能可靠地处理好，并在需要的地方保留全面审查。

并行构建器。 对于涉及多个文件的任务，构建器可以拆分为并行子 Agent。系统会解析计划中的“文件操作”部分来构建依赖关系图——没有交叉引用的文件会在并行工作树中运行，有依赖关系的文件则按顺序运行。疑虑循环会捕获合并过程中出现的任何集成问题。通过在 .foundry.json 中设置 parallel_builder: true 启用此功能。 **会话事件日志。**每个流水线事件（任务启动、Agent 完成、审查发现、提交、模式使用情况、速率限制）都会以 JSON 行的形式追加到 ~/.foundry/observatory/events.jsonl。这是即将推出的 Foundry Observatory 分析仪表板（独立项目）的数据收集层。尽力而为——绝不会阻塞流水线。

CCA 对齐

Context Foundry 的架构与 Anthropic 的 Claude Certified Architect -- Foundations 考试指南中的原则相一致：55 项原则中已实现 43 项，3 项部分实现（架构约束），0 项尚未解决。将每项原则映射到具体代码位置的完整交叉引用见 CCA 对齐矩阵（交互版本）。

运行模式

Foundry 有多种运行模式，用于控制流水线在任务之间的推进方式。可在启动屏幕按 Ctrl+M 切换，或在 .foundry.json 中设置 run_mode。

模式	行为	发现	PR
Auto（默认）	运行所有任务，然后发现新工作并持续执行	是	否
Sprint	运行所有任务，然后停止	否	否
Review	一次运行一个任务，每个任务创建一个 PR，并暂停等待批准	否	是（每个任务）
Coach	在 Scout 之前运行 intake 预检，明确 SPEC.md，然后按 Auto 模式继续	是	否
Service	无人值守的构建服务模式：运行所有任务后停止；WIP / 审计失败任务为终态（不重试）	否	否

Auto 是完全自主模式。循环不会自行停止——任务队列清空时，发现 Agent 会扫描代码库寻找新工作，并将其追加到 TASKS.md。演示视频中展示的就是此模式。

Sprint 是半自主模式。它会使用与 Auto 相同的流水线（scout、规划、实现、验证、提交）处理所有待处理任务，但队列清空后就会停止，而不会运行发现流程。如果你已有明确的任务列表，希望 foundry 完成任务而非寻找更多工作，请使用此模式。

Review 是面向团队工作流的人工参与模式。每个任务完成后，foundry 会推送一个功能分支（foundry/{task_id}），创建 GitHub PR，然后暂停。TUI 会显示 PAUSED (Review)，并等待以下任一操作：

• 用户按 Enter 手动继续，或
• GitHub PR 获得批准，foundry 通过轮询 gh pr view 检测到该批准（可通过 pr_poll_interval_secs 配置，默认值为 30s）

如果审查者要求修改，TUI 会显示相应状态。Review 模式要求已安装并完成身份验证的 gh CLI。

{
  "run_mode": "review",
  "pr_poll_interval_secs": 30,
  "create_issue_on_wip": true
}

create_issue_on_wip 标志适用于任何模式——当任务验证失败并产生 WIP() 提交时，foundry 会根据审查发现自动创建 GitHub issue。

Service 是 Context Foundry 构建服务（foundry serve）使用的无人值守模式。与 Sprint 一样，它会运行所有待处理任务，然后停止且不执行发现流程；但它还会将 WIP / 审计失败任务视为终态：任务会记录其 ! 失败标记和 WIP() 提交，然后循环转到下一个任务，不重试，也不会因连续 WIP 而停止。此模式下的无头运行（--no-tui）也会跳过后台 GitHub 更新检查。Service 面向自动化、有界限的构建作业，而非交互式使用。

双模型竞技场

Foundry 可以通过不同的 AI 提供商运行任务。在启动屏幕按 Ctrl+D 切换，或在 .foundry.json 中设置 dual_selection。

**配置：**在 builder_models 中定义两个提供商：

{
  "builder_models": ["claude:opus", "codex:"],
  "dual_selection": "both"
}

每个条目的格式为 provider:model，例如 claude:opus 或 codex:（模型为空时使用提供商的默认模型）。

三种选择模式（按 Ctrl+D 循环切换）：

模式	运行方式
仅第一个	整个流水线（Scout -> Plan -> Implement -> Verify）通过 builder_models[0] 运行
仅第二个	整个流水线通过 builder_models[1] 运行
两者	两条完整且独立的流水线并行运行，每个提供商各运行一条

**关键设计原则：提供商选择作用于整个流水线，而非单个阶段。**选择“Codex”后，每个阶段都会通过 Codex 运行——侦察、规划、构建、审查和发现。Foundry 会自动清除属于错误提供商的模型名称（例如，“sonnet”是 Claude 模型名称，因此通过 Codex 运行时会将其清空，让 Codex 使用默认模型）。这样可以避免“model 'sonnet' is not supported by Codex”之类的错误。

**双模式（“两者”）**会在 Scout 阶段之前分叉到两个 git 工作树，并运行两条完全独立的流水线：

Pipeline A (Claude)                    Pipeline B (Codex)
.buildloop/arena/claude/               .buildloop/arena/codex/
  scout-report.md                        scout-report.md
  current-plan.md                        current-plan.md
  build-claims.md                        build-claims.md
  review-report.md                       review-report.md

每个模型都会侦察自己的代码库视图、编写自己的计划、实现自己的方案，并验证自己的输出。人工比较的是两个已经完成、架构决策各自独立的结果，而不是基于同一计划的两种实现。

**双模式下的 TUI：**按 1 查看流水线 A 的输出，按 2 查看流水线 B 的输出。标签栏会显示每个数据流的事件数。流水线图会显示每条流水线当前所处的阶段。两条流水线完成后，竞技场结果会保留在 .buildloop/arena/ 中，供人工比较——foundry 不会自动选出优胜者。

全局配置：~/.foundry/config.json 中的设置会作为所有项目的默认值。项目级 .foundry.json 字段会覆盖全局值。这意味着你只需在全局配置中设置一次 builder_models 和 dual_selection，而不必在每个项目中重复设置。

Docker 沙箱隔离

Foundry 可以在 Docker 容器中运行 Agent，使其只能访问项目目录，无法访问你的主目录、凭据或其他仓库。检测到 Docker 时，沙箱默认开启；未检测到时则会关闭并显示警告。

设置：

1. 安装 Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
2. 构建沙箱镜像：

   bash docker/build-sandbox.sh
   

3. 正常运行 foundry——它会自动检测镜像

TUI 会在标题栏（绿色的 [sandboxed]、黄色的 [sandbox degraded]（Docker 或镜像缺失时），或红色的 [sandbox disabled]（通过配置覆盖时））、统计面板和启动屏幕中显示沙箱状态。

**工作原理：**沙箱启用后，foundry 会将每个 Agent 的 CLI 调用封装在 docker run 中，并将项目目录绑定挂载到 /work。容器以非 root 用户（UID 1000）运行。ANTHROPIC_API_KEY 会自动转发。PTY 后端会被强制启用（tmux 与容器化 Agent 不兼容）。

配置（位于 .foundry.json 中）：

{
  "sandbox": true,
  "sandbox_image": "foundry-sandbox:latest",
  "sandbox_extra_mounts": ["/data:/data:ro"]
}

字段	默认值	用途
sandbox	true	启用/禁用沙箱隔离
sandbox_image	"foundry-sandbox:latest"	沙箱容器使用的 Docker 镜像
sandbox_extra_mounts	[]	额外的绑定挂载（例如，共享缓存）

**优雅降级：**如果未安装 Docker 或尚未构建镜像，foundry 会退回到直接在主机上运行 Agent，并在 TUI 中显示黄色警告。无需更改配置。

**Windows：**Docker Desktop 的 WSL2 后端会自动转换路径（C:\Users\... 会变为 /c/Users/...）。

模式匹配与注入

每项任务开始时，foundry 会加载 ~/.foundry/patterns/ 中的所有模式，并将它们与任务描述进行匹配。匹配采用关键词评分：每个模式都有 keywords 和 tech_stack 字段，与任务描述中的完整词匹配即可得分。如果 Ollama 在本地运行，还会使用语义（嵌入）匹配进行重排序。

匹配到的模式会经过格式化，并作为参考数据注入规划器和审查员 Agent 的提示词中。TUI 会在两处跟踪这些数据：

指标	位置	含义
已注入	模式面板 + 统计行	匹配到并注入 Agent 提示词中的模式
已学习	模式面板	从构建产物中提取的新模式
已应用	统计行	关键词出现在 Agent 输出中的已注入模式（Agent 很可能采用了相关建议）

这三项计数都按会话统计——它们会在 foundry 启动时重置，并在各项任务中累积。同一模式可以被多次注入（每项匹配该模式的任务注入一次）。

使用 Ollama 进行语义匹配

当模式与任务包含明显相同的词语时，关键词匹配效果很好，但它无法发现语义关联。例如，任务“构建 korg 808 模拟器”应该匹配音频／DSP 设计模式，但如果模式的关键词是“振荡器”“波形”或“采样率”，就无法匹配，因为这些词都没有出现在任务描述中。僵化的关键词匹配只能找到预先指定的内容，无法泛化。

当 Ollama 在本地运行时，foundry 会使用基于嵌入的语义匹配来弥补这一不足。任务描述和模式文本会通过本地模型转换为向量嵌入，再通过余弦相似度识别概念相关的模式，即使它们之间没有任何共同关键词也能匹配。语义分数会在关键词分数的基础上作为重排序加权项——关键词匹配始终是基础，语义匹配则对其进行补充。

设置：

1. 安装 Ollama
2. 拉取嵌入模型：

   ollama pull nomic-embed-text
   

3. 启动 Ollama（或将其作为后台服务运行）

就这么简单。Foundry 会在启动时自动检测 Ollama。默认设置无需配置。

模型选择： nomic-embed-text 是一个拥有 1.37 亿个参数的嵌入模型（约 274 MB）。它足够小，可以与 foundry 一起在任何机器上运行，且不会对资源造成明显影响；其嵌入质量也足以满足模式与任务匹配的需求。它不是聊天模型——只会生成用于相似度比较的向量嵌入。

配置（均为可选，在 .foundry.json 中设置）：

{
  "semantic_match_enabled": true,
  "embedding_model": "nomic-embed-text",
  "ollama_url": "http://127.0.0.1:11435",
  "embedding_timeout_ms": 2000
}

字段	默认值	用途
semantic_match_enabled	true	设为 false 可完全禁用语义匹配
embedding_model	"nomic-embed-text"	用于嵌入的 Ollama 模型名称
ollama_url	"http://127.0.0.1:11435"	Ollama API 端点
embedding_timeout_ms	2000	每次嵌入请求的超时时间（毫秒）

平稳降级： 如果 Ollama 未运行、模型尚未拉取，或请求失败，foundry 会自动回退到仅使用关键词匹配，无需用户干预。发生故障后，熔断器会在 60 秒内抑制重试，因此 Ollama 实例不可用不会导致每项任务都增加延迟。TUI 会记录所使用的匹配模式（semantic、keyword-only 或 cooldown）。

嵌入缓存： 模式嵌入会缓存在 ~/.foundry/cache/pattern-embeddings.json 中。缓存以每个模式内容的 blake3 哈希为键，因此模式变更时会自动失效。缓存已预热时，语义匹配无需为模式调用 Ollama——只需为任务描述生成嵌入。

模式范围

模式默认是全局的。它们位于 ~/.foundry/patterns/，会加载到你机器上的每个项目中。在项目 A 中积累的经验，在构建项目 B 时也能用上。

如果需要按项目隔离，请在 .foundry.json 中将 patterns_dir 设置为项目本地路径。

发现

在 Auto 模式下，当 TASKS.md 中的所有任务都已完成时，foundry 不会停止。发现 Agent 会扫描代码库——阅读架构文档、查找 TODO/FIXME、检查测试是否失败、发现不一致之处——并将新任务追加到 TASKS.md。随后，循环会继续处理这些任务。如果发现 Agent 没有发现任何内容，就会逐步延长冷却时间（可通过 discovery_cooldown_minutes 配置）。在 Sprint 和 Review 模式下，发现功能会被禁用，队列清空后流水线便会停止。

本地模型（LM Studio + opencode）

Foundry 可以通过本地 LM Studio（或 Ollama）模型运行构建流水线，而不是使用 Claude 或 Codex。在设置浮层中选择本地模型后，builder_provider 会切换为 opencode，并通过 opencode CLI 将任务路由给启动的 Agent；opencode 会连接到 LM Studio 的 OpenAI 兼容服务 http://127.0.0.1:1234。

选择本地模型。 在 TUI 中按 ? 打开设置浮层。“Builder”行会列出所有 Claude / Codex 规格，以及从 LM Studio 的 /v1/models 和 Ollama 的 /api/tags 发现的所有模型。选择 LM Studio 条目后，会将 builder_provider = "opencode" 和 builder_model = "lmstudio/<id>" 写入 .foundry.json。规范的 ID 列表来自 opencode models lmstudio——在命令行中运行该命令即可查看 opencode 接受的确切 ID。

完整流水线路由。 当选定的构建器规格为 opencode:... 时，Config::for_pipeline()（src/config.rs）会将所有角色的提供方——全部 8 个阶段：侦察、查询、研究、规划、构建、审查、修复和发现——都切换为 opencode，并使用同一个模型。因此，选择本地模型并非“仅用于构建器”；整个流水线都会通过所选的 LM Studio 模型运行。

所需的 n_ctx。 Foundry 的提示词加上 agent_system_directives 经常会超过 4096 个 token。加载 LM Studio 模型时，请将 n_ctx 设为 >= 8192。窗口较小时会产生 [error/ContextOverflow] 事件（定义于 src/agent.rs 中的 AgentErrorKind::ContextOverflow），并中止 Agent 运行。另外两种类型化错误——ProviderUnreachable（LM Studio 未运行）和 ModelNotLoaded（LM Studio 中未加载所请求的模型）——也会以相同方式显示。

冒烟测试门禁。 在依赖本地模型路径前，请运行 bash scripts/smoke-local-model.sh。该脚本会启动一个临时项目，运行 foundry run --no-tui --output-format json，并断言六项检查（退出代码、JSON 封装结构、日志是否存在、opencode 会话标记、无类型化错误、QRPBA 指示器）。传入 --keep 可保留工作区以供检查。

无头 JSON 封装。 foundry run --no-tui --output-format json 会输出一个带版本号的对象（schema_version: 2），其中包含 tasks、session 和 config 区块。字段级别的架构说明和每项检查的失败情况解读，见 docs/local-model-setup.md。

空差异与空闲超时。 本地模型有时会生成未修改任何文件的 Agent 输出，或在生成过程中停滞。Foundry 会处理这两种情况：EmptyDeliverable 门禁会将提交标记为 WIP 而非 feat，空闲超时（agent_implement_idle_secs，默认值为 60s）会终止停滞的子进程。请参阅本地模型运行手册中的 "Empty-diff WIP and idle-timeout behavior" 部分。

完整运行手册（前置条件、命令记录、失败情况解读指南）请参阅 docs/local-model-setup.md。

Settings Overlay

在 TUI 中按 ? 可打开 Settings Overlay——一个占屏幕 90%x80% 的模态窗口，提供约 40 个可由用户调整的配置字段，分为 11 个可折叠部分。 在任意状态下按 Esc、点击模态窗口外部，或点击 [ X ] 按钮即可关闭。确认保存后，更改会写入 .foundry.json。

此覆盖层支持内联编辑（布尔值使用 Space/Enter，枚举值使用 Left/Right，数字使用数字输入，字符串使用自由文本），并提供 Model Picker 下拉菜单，用于为各个阶段选择提供商和模型。

完整参考（各部分、字段、编辑规则、Model Picker 行为）请参阅 docs/settings-overlay.md。

Per-stage routing

默认情况下，所有流水线阶段都通过同一个提供商运行，可通过 Ctrl+D 或 Settings Overlay 中的 Builder 行选择提供商。按阶段路由覆盖设置允许将不同阶段固定到不同的提供商——例如，Plan 和 Audit 使用 Claude Opus，而 Build 使用 Codex。

在 Settings Overlay（Routing 部分）中打开相应阶段的 Model Picker 并选择模型，即可固定该阶段。该阶段会添加到 .foundry.json 中的 stage_overrides，且不会受全局 builder 切换影响。

配置 JSON 格式、运行时解析方式和示例请参阅 docs/per-stage-routing.md。

安装

预编译二进制文件

从 GitHub Releases 下载：

平台	文件
macOS (Apple Silicon)	foundry-aarch64-apple-darwin.tar.gz
macOS (Intel)	foundry-x86_64-apple-darwin.tar.gz
Linux (x86_64)	foundry-x86_64-unknown-linux-gnu.tar.gz
Windows (x86_64)	foundry-x86_64-pc-windows-msvc.zip

解压后，将文件移至 PATH 中的目录。在 macOS/Linux 上：

tar xzf foundry-*.tar.gz
sudo mv foundry /usr/local/bin/

在 Windows (PowerShell) 上：

Expand-Archive foundry-x86_64-pc-windows-msvc.zip -DestinationPath .

如果已安装 Rust，%USERPROFILE%\.cargo\bin\ 已在 PATH 中：

Move-Item foundry.exe C:\Users\$env:USERNAME\.cargo\bin\

如果没有安装 Rust，可将文件放在任意位置，并将所在文件夹添加到 PATH：

mkdir C:\tools
Move-Item foundry.exe C:\tools\
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\tools", "User")

打开新的终端，即可在任意目录中运行 foundry。

从源代码安装（所有平台）

需要安装 Rust 和 Claude Code CLI。

cargo install --git https://github.com/context-foundry/context-foundry foundry

macOS (Homebrew)

brew tap context-foundry/tap
brew install foundry

Windows（从源代码安装，分步说明）

对于禁止运行未签名二进制文件的受限设备，可从源代码编译：

1. 安装 Rust（包含 cargo）
2. 安装 Visual Studio Build Tools（选择 “C++ build tools” 工作负载）
3. 在 PowerShell 中运行：

git clone https://github.com/context-foundry/context-foundry.git
cd context-foundry
cargo install --path .

二进制文件将在你的设备上从源代码编译——无需下载未签名文件，也不会出现 SmartScreen 警告。foundry.exe 将位于 %USERPROFILE%\.cargo\bin\。

或者，如果你安装了 Claude Code，可粘贴以下提示词，让它完成所有操作：

克隆并构建 Context Foundry。运行：git clone https://github.com/context-foundry/context-foundry.git && cd context-foundry && cargo install --path .

自行更新

foundry update

用法

将 foundry 指向任意包含 TASKS.md 的项目目录：

# TUI mode (default)
foundry --dir /path/to/project

# Interactive prompt-driven studio for Claude, Codex, or both
foundry --dir /path/to/project studio

# Headless mode (CI/logs)
foundry --dir /path/to/project run --no-tui

# Check progress
foundry --dir /path/to/project status

# List all tasks
foundry --dir /path/to/project tasks

# Self-update to latest release
foundry update

Studio 的文档单独列于 docs/foundry-studio-readme.md，因为它与自主运行的 run 循环属于不同的工作流。

项目设置

项目需要两个文件才能开始：

1. TASKS.md —— 任务清单（foundry 会读取并标记已完成的任务）：

   ## Phase 1
   - [ ] 1.1: Set up project scaffolding
   - [ ] 1.2: Implement authentication
   

2. SPEC.md —— 项目规范（根据你的描述自动生成，Agent 会读取以获取上下文）

可选：

• .foundry.json —— 覆盖默认设置：

  {
    "run_mode": "auto",
    "planner_model": "opus",
    "builder_model": "sonnet",
    "reviewer_model": "opus",
    "fixer_model": "opus",
    "patterns_dir": "~/.foundry/patterns",
    "auto_push_remote": "snedea"
  }
  

• CLAUDE.md —— 项目约定（Agent 也会读取此文件）

仍在使用 ARCHITECTURE.md 和 IMPL_PLAN.md 的旧版项目仍可正常运行。如果两者都存在，Foundry 会优先使用 SPEC.md 和 TASKS.md。

Hooks

Foundry 可以在每个任务提交后运行 shell 命令。在 .foundry.json 中设置 on_task_complete：

{
  "on_task_complete": "osascript -e 'display notification \"Task done\" with title \"Foundry\"'"
}

Hook 也支持 HTTP webhook：

{
  "on_task_complete": "curl -fsS -X POST -H 'Content-Type: application/json' -d \"{\\\"task\\\":\\\"$FOUNDRY_TASK_ID\\\",\\\"status\\\":\\\"$FOUNDRY_TASK_STATUS\\\",\\\"sha\\\":\\\"$FOUNDRY_COMMIT_SHA\\\",\\\"desc\\\":\\\"$FOUNDRY_TASK_DESC\\\"}\" https://example.com/foundry-webhook"
}

该命令通过 sh -c 执行，cwd 设置为项目目录。会导出四个环境变量：

变量	值
FOUNDRY_TASK_ID	TASKS.md 中的任务 ID（例如 T1.1）
FOUNDRY_TASK_STATUS	如果 doubt 通过，则为 feat；如果 doubt 未通过，则为 WIP
FOUNDRY_TASK_DESC	任务描述，截断至 100 个字符
FOUNDRY_COMMIT_SHA	为该任务生成的提交 SHA（如果未创建提交，则为空字符串）

Hook 会启动后即不再等待：foundry 通过 tokio::spawn 启动它，并继续处理下一个任务，不会等待它完成。非零退出码会记录为后台警告（on_task_complete hook exited non-zero (...)），但不会阻塞流水线。stdout 和 stderr 会被丢弃——如果需要输出，请在 Hook 内部将日志写入文件。

Hook 会在每次运行模式（auto、sprint、review）中对所有已提交任务触发——成功的（feat(T1.1):）和失败的（WIP(T1.1):）提交都会触发。如果要根据成功或失败执行不同操作，请在 Hook 中使用 FOUNDRY_TASK_STATUS。

实现位置：src/config.rs:403-409（配置字段）、src/app/build.rs:5937-5981（spawn_completion_hook）。

流水线阶段

Foundry 的流水线通过 .foundry.json 中的 pipeline_stages 字段配置。已完成的任务使用 QRPBA 指示器（参见 docs/progress-indicators.md），而内部阶段 ID 仍为 query、research、plan、implement、doubt。默认配置会展开为：

{
  "pipeline_stages": [
    { "id": "query",     "label": "QUERY",     "enabled": true },
    { "id": "research",  "label": "RESEARCH",  "enabled": true },
    { "id": "plan",      "label": "PLAN",      "enabled": true },
    { "id": "implement", "label": "IMPLEMENT", "enabled": true },
    { "id": "doubt",     "label": "DOUBT",     "enabled": true }
  ]
}

五个有效的阶段 ID 为：query、research、plan、implement、doubt。构建循环目前无法识别其他 ID——添加 {"id":"security", ...} 会在 TUI 列表中显示，但不会运行 Agent。自定义阶段由第 29 阶段（可组合卡片）跟踪。

将阶段的 enabled: false 设置为 false，即可在构建循环中跳过该阶段。此跳过是真实生效的，并非仅改变外观：

• 禁用 implement：不会启动构建 Agent。构建循环会记录 Pipeline: implement stage disabled in config -- skipping builder for <task>，并使用合成的 StageResult::success("Builder", ...) 继续进入 doubt 阶段。参见 src/app/build.rs:4612-4626。
• 禁用 doubt：会绕过审核／审查循环。构建循环会记录 Pipeline: doubt stage disabled in config -- skipping audit，并将任务视为已验证。参见 src/app/build.rs:5158-5160 和 src/app/build.rs:5186-5190。
• query、research、plan 遵循相同的 pipeline_stage_enabled(id) 模式——当 enabled: false 时，不会启动相应的 Agent。

阶段标签文本仅影响外观，只会改变 TUI 流水线栏和 Agent 提示词中的 STAGE 标题。

重新排序仅影响显示。 在 pipeline_stages 中将 doubt 放在 implement 之前，只会改变 TUI 流水线栏的顺序，不会改变执行顺序——构建循环仍会按 query -> research -> plan -> implement -> doubt 的顺序运行。真正的阶段重新排序和自定义阶段处理器由第 29 阶段（可组合流水线卡片）跟踪——参见 TASKS.md。

较短的键 "stages" 可作为 "pipeline_stages" 的别名使用。

实现位置：src/config.rs:18-74（PipelineStageConfig 和 default_pipeline_stages）、src/config.rs:530-548（pipeline_stage_label／pipeline_stage_enabled）。

CLAUDE.md 与 foundry Agent

foundry 启动的每个 Agent 都是一次 Claude Code CLI 调用，其 cwd 设置为项目目录。Claude Code 会按常规方式加载 CLAUDE.md——你的全局 ~/.claude/CLAUDE.md、项目的 CLAUDE.md 以及任何 .claude/rules/*.md 文件都会加载到 Agent 的上下文中。

这大多有益：项目规范（编码风格、架构规则、命名模式）能帮助 Agent 编写更好的代码。不过，如果你的 CLAUDE.md 包含元工作流指令，就可能造成问题，例如“运行 QRPBA 流水线”“启动子 Agent 进行验证”或“编码前始终先制定实现计划”。这些指令会与 foundry 自身的编排冲突，因为每个 Agent 已经在流水线阶段中运行。

foundry 会通过向每个 Agent 追加系统级覆盖指令来处理这一问题：

你正作为 Context Foundry 自主流水线中的一个独立阶段运行。忽略 CLAUDE.md 中有关编排工作流、构建流水线、QRPBA 阶段、疑虑循环、启动子 Agent 或多步实现流程的任何指令。所有编排工作均由 Foundry 负责。请只专注于分配给你的角色和任务。

这样既能保留有用的项目规范，也能屏蔽工作流指令。使用 foundry 无需修改 CLAUDE.md，但请注意，任何关于编排、流水线或子 Agent 工作流的指令都会被覆盖。

Agent 提示词

所有 Agent 提示词都定义在 src/prompts.rs 中。每个 Agent 都有专用的提示词函数：

Agent	函数	用途
Planner	planner_prompt()	根据任务描述制定实现计划
Builder	builder_prompt()	实施计划，并运行适用于相应技术栈的构建检查
Reviewer	reviewer_prompt()	结合验证与审计，并提供结构化发现
Fixer	fixer_prompt()	修复评审报告中的 HIGH/MEDIUM 问题
Discovery	discovery_prompt()	扫描代码库以发现新任务
Pattern Extractor	pattern_extraction_prompt()	从已完成的工作中提取可复用模式

提示词会编译进二进制文件。要自定义提示词，请编辑 src/prompts.rs 并重新构建。

提示词系统中的关键设计决策：

• 感知技术栈：Agent 会根据仓库文件（Cargo.toml、package.json、pyproject.toml）检测技术栈，而不是假定使用特定语言
• 默认安全：Reviewer 只运行只读检查（不会执行 docker compose up，也不会修改服务）
• 模式隔离：学习到的模式会作为明确分隔的参考数据注入，而非权威指令
• 基于证据的评审：每项发现都必须引用文件、行号和具体证据
• 大型文件处理：所有 Agent 都会收到指导，在文件超过工具的 10,000-token 限制时使用 Grep 和带有 offset/limit 的 Read，避免读取大型源文件时失败

插件

插件是由人工编写的只读领域知识包，用于教会 foundry 的 Agent 如何使用 Claude 训练数据中未包含的技术、API 或工作流。Foundry 会自动从三个来源发现插件（优先级从高到低）：

1. 项目本地 -- <project_dir>/plugins/
2. 祖先目录 -- 从项目目录向上遍历，检查每个父目录是否包含 plugins/ 子目录（距离最近的祖先目录优先）
3. 全局 -- ~/.foundry/plugins/

祖先目录发现机制意味着，即使你从嵌套的子目录运行 foundry，它仍能找到目录树中更高层定义的插件。例如，从 plugins/flowise/hackathon/ 运行时，会发现同级的插件，如 plugins/extend/。

插件是一个文件夹，其中包含 CLAUDE.md（领域规则）和一个 skills/ 目录，内含一个或多个 SKILL.md 文件（Anthropic Agent Skills 格式）。例如，Roblox 插件可能会教 Agent 移动部件时使用 CFrame 而不是 Position，Workday Extend 插件则可能说明 WID 是租户专属的。

插件与技能

插件和技能都会将知识注入 Agent 提示词，但用途各不相同：

	插件	技能
内容	领域知识包（CLAUDE.md + 一个或多个技能）	Anthropic Agent Skills 格式的单个 SKILL.md 文件
创建者	人工；foundry 的模式提取器也可以生成技能	Foundry 的模式提取器在每项任务后生成，或由人工编写
选择方式	手动——用户在启动屏幕上选择	自动——每项任务由混合检索器（BM25 + nomic-embed 余弦相似度 + 遥测数据）选择
注入方式	将 CLAUDE.md 原样前置到构建器和审查器提示词中	将排名靠前的匹配技能注入相关的流水线阶段
作用范围	每个项目单独设置（用户选择适用的插件）	全局（所有技能都会与所有任务进行匹配）
始终启用	是——选中后，无论任务内容如何，构建器和审查器都会获得完整内容	否——仅注入检索器排名足够靠前的技能

插件可以在 plugins/<name>/skills/ 下附带自己的技能。这些插件技能会合并到全局技能池中，并由同一检索器进行排名。因此，插件包含两类内容：选中后始终注入的强制领域规则（CLAUDE.md），以及由检索器按任务排名的可选领域专属技能（SKILL.md 文件）。

插件上下文

在启动屏幕上，foundry 会显示一个复选框面板，列出所有发现的插件及其技能数量。选择与你的构建相关的插件：

┌ Plugins ─────────────────────────────────────────┐
│ [ ] extend (1s) Workday Extend orchestrations    │
│ [x] flowise (2s) Flowise AgentFlow v2 workflows  │
│ [ ] recon (2s) Fleet ops, iDRAC                  │
│ [ ] roblox (2s) Roblox world gen, Lune scripting │
└──────────────────────────────────────────────────┘

所选插件会以程序化注入的方式，作为前置上下文加入构建器和审查器提示词。Scout 和规划器会跳过插件注入以节省令牌——它们会在不使用领域专属规则的情况下进行调查和规划，而负责编写和审查代码的 Agent 则会获取完整的插件上下文。这是确定性的约束，而非 Agent 可以自行决定是否遵循的建议。

状态栏始终显示当前启用的插件：Plugins: flowise (1 active) 或 Plugins: none。

选择会通过 plugins 键保存在 .foundry.json 中。使用 "extensions": [...] 的旧版配置仍可通过 serde 别名加载，并会在下次保存时重写为 "plugins"：

{
  "plugins": ["flowise"]
}

创建插件

plugins/your-domain/
├── CLAUDE.md                                       # Domain rules (injected into every agent prompt)
├── skills/your-domain-pitfalls/SKILL.md            # Learned pitfalls (Anthropic Skills format)
└── docs/                                           # Supporting documentation

CLAUDE.md 应包含 Agent 在你的领域中正确工作的必要规则。选中插件后，其技能会自动合并到全局技能池中——无需手动合并。

前置条件检查会在构建器运行前验证插件：如果已配置插件，但缺少其 CLAUDE.md，构建就会被阻止，并显示明确的错误信息。

架构

• config.rs — 使用 serde 默认值的设置（向后兼容 JSON）
• agent.rs — 在 PTY 中启动 Claude CLI，实现实时流式传输
• patterns.rs — 加载、匹配、格式化、合并和提取已学习的模式
• prompts.rs — Agent 提示词（规划器、构建器、审查器、修复器、发现器、模式提取器）
• studio/ — 由提示词驱动的多模型 TUI，支持工作区隔离、产物捕获，以及模块化的 Studio 应用／状态／UI 代码
• update.rs — 从 GitHub Releases 自我更新并验证校验和
• sandbox.rs — Docker 沙盒检测、配置和命令包装
• tmux.rs — 管理 Agent 后端的 Tmux 会话
• app.rs — 构建循环编排、审查循环、模式提取
• tui.rs — 使用 Ratatui 的终端 UI，实时显示 Agent 输出
• task.rs — 解析 TASKS.md 任务列表
• git.rs — 提交和推送辅助工具

.claude/ 目录

此仓库在 .claude/ 中提供两类 Claude Code 配置：

规则（.claude/rules/*.md）是 Claude Code 根据你正在编辑的文件自动加载的上下文。每条规则都通过 paths: 前置元数据限定适用范围：编辑 src/patterns.rs 时会启用 patterns.md，任何 .rs 文件都会启用 rust.md。规则会告知 Claude 项目的约定，让它编写符合项目规范的代码。

技能（.claude/skills/）是按需使用的斜杠命令（/audit、/scout、/extract-patterns）。每条命令都在分叉的上下文中运行，并限制工具访问权限。这些操作与 foundry 流水线自主运行的操作相同，只是以手动命令的形式提供，便于交互式使用。

规则和模式虽然都会影响 Agent 的行为，但两者并不相同。规则是提交到仓库中的静态项目约定。模式则是 foundry 在运行时发现的已学习问题／解决方案对，存储在 ~/.foundry/patterns/ 中，并按任务通过关键词和语义相似度进行匹配。

未来方向

Context Foundry 有两类记忆。模式库会记住代码层面的经验教训——“使用 CFrame 而不是 Position”、“切片前先验证 UTF-8 边界”。下一层是流程级记忆——学习流水线本身的表现，并随时间调整其行为。

自适应流水线

目前，流水线会为每项任务运行所有阶段。下一步是根据观测到的信号按需投入相称的工作量。

观测内容： 任务时长、重试次数、速率限制频率、审查发现的严重程度、每项任务的成本、模式命中率、双模式下各提供方的胜出率，以及按任务形态记录的 doubt 通过／失败历史（通过 Ollama 嵌入进行聚类）。

自适应内容： 规划器的深度（简单任务跳过）、是否运行 doubt（某种任务形态连续 5 次以上顺利通过时跳过，出现任何失败时重置）、是否使用双模式、Agent 之间的暂停时长，以及何时升级为人工审查。

具体示例： 重命名任务跳过 query、research 和 planner，只获取 2 个模式而不是 10 个，跳过 audit 并直接提交——耗时 30 秒，而不是 10 分钟。重写身份验证系统则运行完整的 QRPBA 流水线，获取 10 个模式并强制执行 audit。已发布的复杂度分类器负责粗粒度划分；通过学习 doubt 置信度增加细粒度层，并在每次运行后不断改进。

Foundry Observatory

一个可自托管的分析仪表板，可跟踪所有项目中的每次流水线运行。采用 SQLite 后端、轻量级 Web 服务器，无需依赖云服务。

显示内容： 会话历史记录（任务、模型、通过/失败、成本、耗时）、模式有效性（注入与应用情况、从未触发的模式）、按严重程度划分的疑点发现趋势、提供商对比（各项目中 Claude 与 Codex 的成本、速度和可靠性），以及复杂度分类准确率。

生成内容：

• 会话回顾：“本次运行将 40% 的成本花在了疑点分析上，而这些任务从未未通过审核。”
• 配置建议：“增加 pause_between_agents_secs——8 个任务中有 6 个遇到了速率限制。”
• 建议添加到 TASKS.md 的条目：“模式 #47 已注入 200 次，但只应用了 3 次——可以考虑添加一项任务来弃用或完善它。”

对话式界面。 与你的构建历史对话。询问“上周有哪些失败？”或“比较一下 Claude 和 Codex 在 health-ai 上的成本。”对话会被保存——这体现了与模式存储相同的原则，用于理解 foundry 的运行情况。你可以在聊天中建议新任务或提交问题。这些内容会作为建议性提案写入——observatory 会建议添加到 TASKS.md 的条目，由人工审核并批准，然后在下一次运行时采纳。observatory 负责提出建议；人工负责批准。

技术栈： 小型 Rust 或 Python 服务器、自包含前端、SQLite 历史记录。可与 foundry 一起在同一台机器上运行，也可作为 Docker 容器运行。

之前的版本

此 Rust 重写版本之前的 Python MCP 服务和守护进程已归档于：

• 标签： v1.0-python
• 分支： archive/python-mcp