m0n0x41d/haft
GitHub: m0n0x41d/haft
为 AI 编程 Agent 提供基于第一性原理的工程决策治理框架，将问题框架、对比、决策和验证转化为可审计、带证据衰减管理的结构化工件。
Stars: 1375 | Forks: 103
*前身为 [quint-code](https://github.com/m0n0x41d/quint-code)*
**用于 AI 辅助软件交付的 FPF 治理基座。**
你的 agent（Claude Code、Codex）编写代码的速度很快。但大多数代码库尚未准备好
进行严肃的 harness 工程：目标系统规范不足，使能系统
隐含不露，术语映射缺失，并且运行时证据
与规范脱节。Haft 能够让项目在扩展执行规模之前变得可 harness。
## 什么是 Haft？
Haft 是一个**治理基座**，它使代码库能够进行
由主导者驱动的 FPF 工程工作。它将问题框架、对比、
决策、委托和证据转化为可审计的工件，并在 kernel 边界进行强制执行。
**规约 → 思考 → 运行 → 治理。**
它不是编程 agent。也不是文档生成器。它是工具
与手之间的把手：将原始的模型能力转化为正式的
规范、受治理的决策、有边界的委托以及有证据支撑的
工程工作的那一部分。
### 三个交互面，一个工件图
Haft 通过基于一个 `.haft/` 工件图的三个交互面来使用：
- 在你的编程 agent（Claude Code、Codex、OpenCode、Cursor）中的 **技能 + 斜杠命令** —— 工作流技能会自动触发；`/h-frame /h-decide /h-verify ...` 手动运行
- **CLI** (`haft problem`, `haft solution`, `haft decision`, ...) —— 手动访问，回路中没有 LLM
- **MCP server** (`haft serve`) —— 基于 Model Context Protocol 为任何 LLM agent 提供编程访问
kernel MCP server 是跨主机的强制执行表面：它在服务器端验证
参数，并为 FPF 违规（缺少必填字段、对等性差距、最薄弱环节遗漏、没有 verify_after 的预测）返回结构化错误。技能承载过程；kernel 把守关卡。
### v8 中发生了哪些变化
v8 弃用了独立的交互式 agent (`haft agent`)、TUI 和
桌面封装。Haft 不再在运行时表面上与通用编程 agent 竞争 —— 它在你已经使用的任何 agent 之上增加治理规范。带有对等性比较的变体、回滚计划和可证伪的预测的架构调整，记录在
`.haft/decisions/dec-20260525-v8-architecture-pivot-from-standalone-agent-to-g-bbe45cb7.md` 中。
从 v7 升级？请参阅 [MIGRATION-v8.md](MIGRATION-v8.md) —— 升级检查清单
以及被弃用的内容（`haft agent`、TUI、桌面版、v7 辅助命令）。
## 基于 First Principles Framework 构建
[FPF](https://github.com/ailev/FPF) 由
[Anatoly Levenchuk](https://www.linkedin.com/in/ailev/) 提出 —— 一种严谨的、
跨学科的思考架构。
这套技能集（`h-frame`、`h-explore`、`h-compare`、`h-decide`、`h-verify` 以及
下面的完整目录）为你的 agent 提供了一个原生的 FPF 操作系统，用于
工程决策：解决方案之前先建框架，比较之前先刻画，强制对等性，带有同余性惩罚的证据，
最薄弱环节保障，以及一个在证据老化或测量失败时
重新开启自身的循环。
框架和比较技能在操作员上下文中自动触发。绑定步骤（`h-decide`、`h-commission`）根据 Transformer Mandate 仅限手动：
agent 负责建立框架并进行比较；由人类主导者记录绑定选择。
`haft fpf search`（以及来自 MCP 的 `haft_query(action="fpf")`）搜索已索引的
FPF 规范。检索是混合型的：首先匹配精确的 pattern id，然后是关键字
(FTS5)，并与内置 section 向量的语义召回相融合，因此即使是换种说法的“我
该如何思考 X”也能找到回答它的 pattern。向量内置于
二进制文件中；当缺少 embedding sidecar 时，语义召回会降级为关键字检索。
## 安装
```
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash
```
安装 URL 仍然指向历史路径 `quint-code`。安装的二进制文件是
`haft`。
然后在你的项目中，使用你的宿主 agent 标志进行初始化：
```
haft init # Claude Code (default)
haft init --local # Claude Code, repo-local commands
haft init --codex # Codex CLI / Codex App
haft init --all # Claude Code + Codex
```
Claude Code 和 Codex 是受支持的宿主。Cursor、Gemini CLI 和 OpenCode
具有实验性配置标志（`--cursor`、`--gemini`、`--opencode`），同时它们的
运行时和文档也在不断收敛。
**Cursor：** 初始化后，打开 Settings → MCP → 找到 `haft` → 启用开关。
Cursor 在默认情况下会将添加的 MCP server 置为禁用状态。
### 初始化在各工具中的具体操作
二进制文件是相同的；只是 MCP 配置和命令/技能的安装位置
有所不同。
| 工具 | MCP 配置 | 命令 / 提示词 | 技能 |
|------|-----------|--------------------|--------|
| Claude Code | `.mcp.json` (项目根目录) | `~/.claude/commands/` (使用 `--local` 时为 `.claude/commands/`) | `~/.claude/skills/` (15 个技能) |
| Codex CLI / App | `.codex/config.toml` | `~/.codex/prompts/` (使用 `--local` 时为 `.codex/prompts/`) | `~/.agents/skills/` (15 个技能) |
项目级配置（`.mcp.json`、`.codex/config.toml`）使用可移植的
项目根路径，因此对于共享代码库，将它们提交到版本库是安全的。
现有项目？在初始化后运行 `/h-onboard`。它会构建一个可解析的
目标系统规范、使能系统规范、术语映射和规范覆盖图 ——
而不仅仅是代码库摘要。
在本地检查规范载体：
```
haft spec check
haft spec check --json
```
`haft spec check` 仅限确定性的 L0/L1/L1.5 检查：它解析围栏
`yaml spec-section` 块，检查必需的结构字段，验证已知的
载体形状，并确认术语映射载体可被解析。它不进行 L2
语义判断，不进行 LLM 审查，也不进行 L3 运行时声明。
## 工作原理
### 七个 MCP 工具
| 工具 | 功能说明 |
|------|-------------|
| `haft_note` | 微决策 —— 带有类型化锚点、验证和自动过期机制的原子事实 |
| `haft_problem` | 构建问题框架，声明带有指标角色的比较维度 |
| `haft_solution` | 在多样性检查下探索变体，在对等性下进行比较 |
| `haft_decision` | 决策契约：不变量、声明、证据、基线生命周期 |
| `haft_commission` | 用于执行 harness 的 WorkCommission 生命周期 |
| `haft_refresh` | 每种工件类型的生命周期管理 |
| `haft_query` | 搜索、状态看板、代码图（调用者/被调用者/影响/探索 —— 每个到达的符号都与管辖它的决策相融合）、FPF 规范搜索 |
### 通过 `haft init` 安装的十五个技能
| 技能 | 模式 | 功能说明 |
|---|---|---|
| **h-reason** | 自动（总括） | 在一个入口中提供完整的 FPF 推理体系 —— 框架构建、探索、比较、验证、笔记，以及 slideument 模式（Goldilocks、NQD、BLP、缩放定律视角）。手动调用 `/h-reason` 始终有效；在遇到没有特定技能能够精确匹配的宽泛“让我们仔细思考一下这个问题”的信号时会自动触发。 |
| **h-frame** | 自动 | 使用 B.4.1 稳定化 + 问题分类 + 伞形词修复来构建问题框架 |
| **h-diagnose** | 自动 | 使用并行假设测试诊断故障（每个假设分配一个 Agent subagent 以防止锚定） |
| **h-explore** | 自动 | 使用 NQD 多样性原则生成独特的候选变体（并行分配方向的 agent） |
| **h-compare** | 自动 | 公平比较，带有逐维度并行评分 + Pareto 前沿（而不是单一的标量赢家） |
| **h-decide** | **手动** | 记录具有完整 DRR 的绑定 DecisionRecord —— Transformer Mandate (`disable-model-invocation`) |
| **h-verify** | 自动 | 基线 → 测量 → 带有漂移检测的证据回路 |
| **h-status** | 自动 | 只读项目 FPF 状态看板 |
| **h-onboard** | 自动 | 针对初次使用 haft 的项目进行的首次框架构建仪式 |
| **h-spec-cover** | 自动 | 规范覆盖检查，带有盲区/陈旧模块分类 |
| **h-note** | 自动 | 轻量级微决策记录 |
| **h-commission** | **手动** | WorkCommission 生命周期 —— 根据 Transformer Mandate 手动执行 (`disable-model-invocation`) |
| **h-abduct** | 子程序 | 纯 B.5.2 溯因四步法（构建提示词 → ≥3 个竞争方案 → 过滤 → 提炼） |
| **h-boundary-unpack** | 子程序 | A.6.B 边界声明的 L/A/D/E 分解 |
| **h-semio-review** | 子程序 | X-FANOUT-AUDIT —— 概念重命名 / 规范一致性审计 |
当技能描述与操作员上下文匹配时，自动触发技能将开始运行。
仅手动技能（`h-decide`、`h-commission`）需要根据
Transformer Mandate 进行显式调用 —— 绑定工件来自人类主导者，而不是
agent。子程序（`h-abduct`、`h-boundary-unpack`、`h-semio-review`）被
其他技能调用，或在处理特定的 FPF 子学科时被显式调用。
路由可靠性是可测试的：`haft check routing` 运行 40 个黄金提示集
（当前通过率为 82.5%）。
### 证据工作流
使用 `haft_decision(action="evidence", ...)` 附加证据。证据带有
形式化级别（F0–F3）、同余性级别（CL0–CL3）和过期日期。信任分数
(R_eff) 会随着证据老化而下降；陈旧的证据会触发刷新。请使用
`haft_decision(action="measure", ...)` 进行实现后的验证。
### Harness —— 执行引擎（测试版，仅限 Codex）
harness 在隔离的工作空间中，由真实的 Codex agent 实现 `DecisionRecord` 工件下的代码。它是**测试版**，并且执行 agent **仅限 Codex** —— 没有 Claude 执行路径。单一委托的
`haft harness run` 是值得信赖的操作员路径；排空模式和自动应用已在文档类委托上得到验证，因此请将它们在生产环境代码委托上视为测试版。
有两个入口点可以生成引擎。`haft run` 直接实现一个决策：
```
haft run dec-20260414-001
```
它从图中读取决策的不变量、声明和受影响的文件，
构建包含完整推理上下文的提示词，生成一个以
不变量为护栏的 Codex agent，并在完成时拍摄基线快照。
`haft harness` 通过 Open-Sleigh 运行委托的工作，带有范围防护
(`allowed_paths` / `forbidden_paths`)、每个委托的锁以及离散的
可回滚应用提交：
```
haft harness run --prepare-only # create/reuse commissions, do not start runtime
haft harness run # create/reuse commissions and start Open-Sleigh
haft harness run --drain --concurrency 4 # drain the queue (apply still manual by default)
haft harness status # inspect active/recent runs
haft harness result wc-... # inspect one completed run and its workspace diff
haft harness apply wc-... # apply a completed workspace patch to this checkout
```
委托包含一个 `delivery_policy`。默认的 `workspace_patch_manual`
将更改保留在隔离的工作空间中，直到你运行 `haft harness apply`。
`workspace_patch_auto_on_pass` 将通过的运行作为离散提交应用；
`blocked_policy` / 失败的运行会等待操作员决策。
对于默认情况下的 `needs_onboard` 项目，广泛的 harness 执行会被阻止。对于
有意为之的战术性规范外工作，请传入 `--force-skip-specs "标签：AI编程辅助, EVTX分析, LLM代理工具, MCP, 可视化界面, 开发治理, 数据管道, 软件工程