haft

<img src="assets/banner.svg" alt="Haft" width="600"> *原名 [quint-code](https://github.com/m0n0x41d/quint-code)* **FPF 治理基底，用于 AI 辅助软件交付** 你的智能体（Claude Code、Codex）可以快速编写代码。大多数仓库在进行严肃的工程设计时并不准备就绪：目标系统未被明确规定，使能系统是隐含的，术语映射缺失，运行时证据与规范相分离。Haft 使项目在扩大执行规模之前具备可治理性。 --- ## Haft 是什么？ Haft 是一个 **治理基底**，使仓库能够进行主要领导的 FPF 工程工作。它将问题框架、比较、决策、委托和证据转化为可审计的制品，并在内核边界强制执行。 **指定 → 思考 → 运行 → 治理** 不是编码智能体。不是文档生成器。工具与人工之间的接口：它将原始模型能力转化为正式规范、受治理的决策、有边界的委托和基于证据的工程工作。 ### 三个界面，一个制品图 Haft 通过三个界面消费一个 `.haft/` 制品图： - **技能 + 斜杠命令** 在你的编码智能体（Claude Code、Codex、OpenCode、Cursor）中 — 工作流技能自动触发； `/h-frame /h-decide /h-verify ...` 手动运行 - **命令行界面（CLI）** (`haft problem`, `haft solution`, `haft decision`, ...) — 手动访问，无 LLM 参与 - **MCP 服务器** (`haft serve`) — 任意 LLM 智能体通过模型上下文协议的编程访问 内核 MCP 服务器是跨主机强制执行界面：它在服务器端验证参数并为 FPF 违规返回结构化错误（缺少必填字段、奇偶性间隙、最弱环节遗漏、预测无 verify_after）。技能承载程序；内核承载门控。 ### v8 中有什么变化 v8 放弃了独立的交互式智能体（`haft agent`）、文本用户界面和桌面包装器。Haft 不再与通用编码智能体在运行时界面竞争 — 它在你已经使用的任意智能体上添加了治理规则。转向，包括奇偶性比较变体、回滚计划和可证伪预测，在 `.haft/decisions/dec-20260525-v8-architecture-pivot-from-standalone-agent-to-g-bbe45cb7.md` 中记录。 升级到 v8？请参阅 [MIGRATION-v8.md](MIGRATION-v8.md) — 升级检查清单和已删除的内容（`haft agent`、文本用户界面、桌面、v7 帮助命令）。 --- ## 构建于首要原则框架 [FPF](https://github.com/ailev/FPF) 由 [Anatoly Levenchuk](https://www.linkedin.com/in/ailev/) — 一个用于思考的严格的、跨学科的架构。 技能集（`h-frame`、`h-explore`、`h-compare`、`h-decide`、`h-verify` 和下面的完整目录）为你的智能体提供了一个 FPF 原生操作系统，用于工程决策：在解决方案之前进行框架设计，在比较之前进行特征描述，强制执行奇偶性，证据具有一致性惩罚，最弱环节保证，以及当证据老化或测量失败时重新开启的循环。 框架和比较技能根据操作员上下文自动触发。绑定步骤（`h-decide`、`h-commission`）仅手动执行，按照 Transformer 指令：智能体进行框架设计和比较；人工领导人记录绑定选择。 `haft fpf search`（和 `haft_query(action="fpf")` 来自 MCP）搜索索引的 FPF 规范。检索是混合的：首先是精确模式 ID，然后是关键字（FTS5）与语义召回相结合，基于烘焙的章节向量，因此重新措辞的“如何思考 X”可以找到回答它的模式。向量包含在二进制文件中；当嵌入式边车不存在时，语义召回降级为关键字。 --- ## 安装 ```bash curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash ``` 安装 URL 仍然指向历史上的 `quint-code` 路径。安装的二进制文件是 `haft`。 然后在你的项目中，使用主机代理标志初始化： ```bash haft init # Claude Code（默认） haft init --local # Claude Code，本地仓库命令 haft init --codex # Codex CLI / Codex 应用程序 haft init --all # Claude Code + Codex ``` Claude Code 和 Codex 是受支持的主机。Cursor、Gemini CLI 和 OpenCode 有实验性的配置标志（`--cursor`、`--gemini`、`--opencode`），而它们的运行时和文档趋于一致。 **Cursor：** 初始化后，打开设置 → MCP → 找到 `haft` → 启用切换开关。Cursor 默认禁用 MCP 服务器。 ### 每个工具的初始化操作 二进制文件相同；只有 MCP 配置和命令/技能安装位置不同。 | 工具 | MCP 配置 | 命令/提示 | 技能 | |------|-----------|--------------------|--------| | Claude Code | `.mcp.json`（项目根目录） | `~/.claude/commands/`（或 `.claude/commands/` 与 `--local`） | `~/.claude/skills/`（15 个技能） | | Codex CLI / 应用程序 | `.codex/config.toml` | `~/.codex/prompts/`（或 `.codex/prompts/` 与 `--local`） | `~/.agents/skills/`（15 个技能） | 项目范围的配置（`.mcp.json`、`.codex/config.toml`）使用可移植的项目根路径，因此它们可以安全地提交到共享仓库。 现有项目？在初始化后运行 `/h-onboard`。它会生成一个可解析的目标系统规范、使能系统规范、术语映射和规范覆盖图 — 而不仅仅是一个代码库摘要。 在本地检查规范载体： ```bash 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` | 工作委托生命周期，用于执行治理 | | `haft_refresh` | 每个制品种类的生命周期管理 | | `haft_query` | 搜索，状态仪表板，代码图（调用者/被调用者/影响/探索 — 每个到达的符号与控制它的决策融合），FPF 规范搜索 | ### `haft init` 安装的 15 个技能 | 技能 | 模式 | 它做什么 | |---|---|---| | **h-reason** | 自动（伞形） | 完整 FPF 推理调色板在一个入口 — 框架设计，探索，比较，验证，笔记，以及幻灯片模式（Goldilocks，NQD，BLP，Scaling-Law Lens）。手动 `/h-reason` 始终有效；当没有专门的技能与上下文紧密匹配时，它会自动触发。 | | **h-frame** | 自动 | 用 B.4.1 稳定 + 问题类型 + 伞形修复来框架问题 | | **h-diagnose** | 自动 | 用并行假设测试诊断故障（每个假设一个 Agent 子智能体，以防止锚定） | | **h-explore** | 自动 | 用 NQD 多样性规则生成不同的候选变体（并行方向分配智能体） | | **h-compare** | 自动 | 公平比较，具有维度明智的并行评分 + Pareto 前沿（不是标量赢家） | | **h-decide** | **手动** | 用完整的 DRR 记录绑定决策记录 — Transformer 指令（`disable-model-invocation`） | | **h-verify** | 自动 | 基线 → 测量 → 证据循环，具有漂移检测 | | **h-status** | 自动 | 只读项目 FPF 状态仪表板 | | **h-onboard** | 自动 | 适用于新加入 haft 的项目的首次框架仪式 | | **h-spec-cover** | 自动 | 具有盲/过时模块分类的规范覆盖检查 | | **h-note** | 自动 | 轻量级微决策记录 | | **h-commission** | **手动** | 工作委托生命周期 — 按照 Transformer 指令（`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 指令 — 绑定制品来自人工领导人，而不是智能体。子程序（`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", ...)` 进行实施后验证。 ### 治理 — 执行引擎（测试版，仅限 Codex） 治理在 `DecisionRecord` 制品的隔离工作空间中实施代码。 **测试版**，执行智能体 **仅限 Codex** — 没有 Claude 执行路径。单一委托 `haft harness run` 是值得信赖的操作员路径；排干模式和自动应用在文档类委托上验证，因此在生产代码委托上将它们视为测试版。 两个入口点启动引擎。`haft run` 直接实现一个决策： ```bash haft run dec-20260414-001 ``` 它从图中读取决策的不变量、声明和受影响的文件，构建带有完整推理上下文的提示，在不变量作为护栏的情况下启动 Codex 智能体，并在完成后拍摄基线快照。 `haft harness` 通过 Open-Sleigh 运行委托的工作，具有范围守卫（`allowed_paths` / `forbidden_paths`）、每个委托的锁和离散的可回滚应用提交： ```bash haft harness run --prepare-only # 创建/重用委托，不启动运行时 haft harness run # 创建/重用委托并启动 Open-Sleigh haft harness run --drain --concurrency 4 # 排干队列（默认情况下应用仍然手动） haft harness status # 检查活动/最近的运行 haft harness result wc-... # 检查一个已完成的运行及其工作空间差异 haft harness apply wc-... # 将已完成的工作空间补丁应用到此检出 ``` 委托带有 `delivery_policy`。默认的 `workspace_patch_manual` 将更改保留在隔离的工作空间中，直到您运行 `haft harness apply`。`workspace_patch_auto_on_pass` 在通过时应用一个运行作为离散提交；`blocked_policy` / 失败的运行等待操作员决策。 广泛的治理执行因项目默认需要 `needs_onboard` 而被阻止。对于故意战术性的规范外工作，请传递 `--force-skip-specs "<reason>"`；haft 在选定的委托上记录原因。 发布存档包含 Open-Sleigh BEAM 运行时，因此正常的治理使用不需要 Elixir/Mix 安装： ```text ~/.haft/runtimes/open-sleigh/current ``` 较低级别的界面是 `haft_commission` MCP 工具和 `haft commission` 命令行界面（`create-from-decision`、`create-batch`、`create-from-plan`、`list`、`show`、`requeue`、`cancel`、`claim`，...）。每个委托操作都成为一个类型化的制品转换，而不是一个自由提示： ```text SpecSection(s) → DecisionRecord → WorkCommission → RuntimeRun → Evidence → SpecCoverage ``` --- ## 秘籍 — 常见工作流 ### 记录架构选择 ```text 操作员（对 Claude Code）：我们需要为新的摄入路径选择一个队列 ↓ h-explore 自动触发，生成具有 NQD 多样性的 3+ 个不同变体 ↓ h-compare 自动触发，并行维度评分，呈现帕累托前沿 ↓ 操作员选择一个变体，然后显式输入： /h-decide ↓ 内核验证所需的 DRR 字段；缺少字段 → 结构化错误 ↓ 通过时：DRR 写入 .haft/decisions/，可用于 `haft run` ``` ### 用竞争假设诊断故障 ```text 操作员：部署后模式迁移的测试失败 ↓ h-diagnose 自动触发，启动 3+ 个并行 Agent 子智能体，每个假设一个 ↓ 每个子智能体仅读取其假设所需的内容（无锚定） ↓ 结果合并，按 FPF B.5.2 过滤链排名 ↓ 如果确认：/h-note 记录诊断；如果架构：/h-frame ``` ### 验证决策仍然成立 ```text 操作员：dec-20260420-cache-redesign 是否真的有效 ↓ h-verify 自动触发 ↓ 读取决策预测 + valid_until + 基线文件哈希 ↓ 测量可观察的声明（测试输出，指标查询，...） ↓ 编写具有一致性/新鲜度的证据；更新 R_eff ↓ 如果 R_eff < 0.5 → 标记为过期；如果预测失败 → 重新打开问题 ``` ### 快速操作员状态 ```bash haft check # 适用于 CI 的治理验证（退出 0 清洁 / 1 发现） haft check routing # 健全性检查技能路由可靠性 ``` 从主机代理：`/h-status` 获取完整仪表板。 --- ## 使它与众不同 - **决策是活跃的** — 计算出的信任分数（R_eff）在证据老化时会降低 - **比较是诚实的** — 强制执行奇偶性，约束感知帕累托消除，抗好市多观察指标 - **推理与代码融合** — `haft_query` 在您读取或遍历符号时显示控制它的决策，因此受控节点永远不会被视为安全更改 - **跨会话的记忆** — 相关的过去决策在框架期间出现，类似的变体在探索期间出现 - **循环关闭** — 失败的测量重新打开决策，证据衰减触发审查，漂移检测标记违规 - **决策是合同** — 不变量，具有阈值的声明，回滚计划，有效期 --- ## 路线图 ### v8 — 治理基底枢轴（当前） 放弃了独立的交互式智能体、文本用户界面和桌面包装器。Haft 是一个内核 + 命令行界面 + MCP 服务器 + 15 个技能，共享跨 Claude Code、Codex、OpenCode 和 Cursor 的一个 `.haft/` 制品图。内核 MCP 返回结构化错误作为硬执行门控；绑定制品保持手动，仅按照 Transformer 指令。理由： `dec-20260525-v8-architecture-pivot-...`. 已发货的历史记录在 [CHANGELOG.md](CHANGELOG.md) 中。 ### 下一步 可防御的边缘是代码图与推理图的融合，以及该推理图的活跃度 — 而不是原始代码图覆盖率。积极的方向（想法阶段，跟踪为 `.haft/` 下的活跃问题）：编辑时不变量护栏在受控符号上，信任状态在符号上显示，治理图的相干性检查，以及在运行时治理中衡量融合图是否真正减少读取并防止错误决策。没有一个被承诺于发布版本。 --- ## 要求 - **Go 1.25+** — 从源代码构建 - **Claude Code 或 Codex** — 插件模式 - **Rust 工具链** — 仅用于从源代码构建嵌入式边车（`haft-embed`）；如果没有它，FPF 语义搜索会降级为关键字 ## 许可证 MIT