haxaml

# Haxaml [](https://pypi.org/project/haxaml/) **强制智能体规划。记录行为。从头开始构建结局。** ## 为什么选择 Haxaml ### 问题所在 我创建了 Haxaml，因为我注意到一个反复出现的模式：智能体是建造者，但他们跳过了蓝图。他们阅读几段代码，猜测意图，然后直接进行实施。这种即兴表演往往导致真正的失败。大多数编码问题不是因为模型有限，而是因为智能体在没有理解项目、规则或“完成”的标准的情况下工作。 ### 规则 这个项目是我尝试解决这个问题的方法。Haxaml本质上是一个智能体日记和工作流协议。它建立在一个简单的规则之上：**没有规划，不允许构建**。 ### 模型 它使用我称之为 **FRAME** 的模型，将项目理解分为五个部分：事实、规则、行为、地图和期望。FRAME是存储库拥有的标准和项目大脑。 与其让智能体猜测，我给他们一个笔记本，让他们填写。如果他们跳过一步或忽略项目规则，合同就会失效。 ### 交接 目标是将项目的“大脑”从人工智能提供商的临时内存转移到存储库本身。当您在Claude Code、Cursor、Windsurf或任何其他工具之间切换时，下一个智能体应该能够读取日记、地图和预期的运行手册，并从真实的项目状态继续，而无需重新阅读整个代码库。 ## 智能体日记哲学 我希望从充当智能代码生成器的智能体转向充当经验丰富的建造者的智能体。真正的专业人士不会从敲打钉子开始：他们会研究现场并在第一个工具被使用之前验证材料。Haxaml为他们提供了维持这种纪律所需的结构： 1. **收集材料：** 就像建造者如果业主不购买材料就无法工作一样：智能体必须在开始之前识别并请求他们需要的每个工具、API密钥或数据库URI。 2. **规划结局：** 他们必须在触摸一行代码之前定义什么是“成功”。 3. **预算令牌：** 虽然令牌预算在这里是一个方便的功能：它对于效率很重要。Haxaml使用增量读取来确保智能体仅拉取他们需要用于特定任务的上下文增量。 4. **澄清意图：** 我希望智能体在任务高风险或意图模糊时停止并向我提问。 ## 生命周期的工作原理 Haxaml通过MCP（模型上下文协议）服务器运行，该服务器强制执行确定的顺序。进入存储库的每个智能体都遵循此剧本： | 阶段 | 工具 | 目的 | |---|---|---| | **关于** | `haxaml_about` | 智能体读取“土地法”并学习如何在该环境中操作。 | | **指导** | `haxaml_guidance` | Haxaml确定请求是真实的项目工作还是仅是一个快速的非主题问题。 | | **预建** | `haxaml_prebuild` | **架构师阶段。** 此阶段，智能体对任务进行分类，检查风险，识别缺失的材料，并将请求的最终状态转换为预期的运行路径。 | | **上下文** | `haxaml_context_pack` | **构建阶段。** 智能体拉取任务范围的上下文包。此阶段使用刷新增量来节省令牌。 | | **构建** | *(外部)* | 实现智能体在Haxaml工具外部进行工作（编辑、测试、命令）。 | | **验证** | `haxaml_session_verify` | **检查阶段。** 智能体必须提供他们检查的内容和仍然存在的风险的证据。 | | **记录** | `haxaml_session_record` | 结果被写入行为日记中，供下一个智能体继续。 | | **同步** | `haxaml_expect_sync` | 记录的结果更新预期的运行手册，以便下一个智能体看到计划的内容、实际发生的内容和接下来应该发生的内容。 | ## 当前架构拆分 保持这个思维模型简单： - FRAME = 标准、模式和规范层 - FrameSDK / `framesdkpy` = Python SDK层 - Haxaml = 受管运行时层 用白话来说： - FRAME定义了五个文件的含义。 - FrameSDK通过`framesdkpy` Python包加载、翻译、验证和组装FRAME。 - Haxaml决定生命周期顺序、上下文策略、验证规则、记录和同步。 这种拆分很重要，因为Haxaml应该操作项目大脑，而不是秘密拥有大脑本身的含义。 ## 安装 Haxaml分为三个相关包： - `haxaml`：核心引擎和CLI。 - `haxaml-mcp`：用于编辑器的stdio启动器。 - `haxaml-ui`：用于人类的本地浏览器仪表盘。 对于此存储库中的本地开发，Haxaml通过可编辑的`framesdkpy`包使用FrameSDK。它不应导入存储库本地的`frame`桥。 **关于需求的说明：** 我强烈建议首先安装 [uv](https://docs.astral.sh/uv/)。Haxaml在内部使用它来进行托管升级、启动任务和快速工具执行。 ### 1. 推荐：uv 工具 这是将 Haxaml 添加到您的全局路径的最干净的方法： ```bash uv tool install "haxaml[full]" ``` ### 2. 传统安装 发布的安装可能仍然使用正常的Python打包，但此存储库中的本地开发应使用uv和可编辑的FrameSDK依赖项： ```bash uv sync ``` ### 3. 立即运行 如果您想在没有持久安装的情况下立即运行MCP服务器： ```bash uvx haxaml-mcp ``` ## 设置和采用 我希望 Haxaml 难以使用不当，因此设置现在是单一的 onboarding 集成点。 - `haxaml setup` 现在作为最小的脚手架风格的终端流程运行，默认在真正的 TTY 中，但保持机器友好，在非交互式或 `--format json` 流程中。 - 设置合同是提供者感知的：强目标证据应指导默认值，弱共享信号（如 `AGENTS.md`）应保持建议，最终输出应显示确切的目标、路径和预览，然后再写入。 - 在一个全新的存储库中，它会创建 `.haxaml/`，然后写入所选目标的原生指令以及您请求的任何匹配的技能、智能体、配置或工作流适配器。 - 在现有的存储库中，它应该采用原生文件而不是替换它们。Haxaml 在安全的地方追加托管指针块，将完整的托管适配器保留在 `.haxaml/setup/targets/` 中，并在 `.haxaml/adoption/` 中记录采用状态。 - 已知的 MCP 配置形状仅合并 Haxaml 拥有的条目或表 (`mcpServers.haxaml` 或 `[mcp_servers.haxaml]`)，并保留无关的配置。 - `haxaml setup --dry-run` 现在显示确切的路径和简明的预览，而不是仅显示文件计数。 - `haxaml setup print` 仍然显示完整的渲染内容，然后再写入。 - `haxaml setup doctor` 检查缺失的托管文件、漂移和手动跟进。 1.0强化轨道将设置目标清晰度和重跑幂等性视为阻塞器。设置时不应无声地将选定的提供程序降级为`generic`，而默认情况下，重跑设置在活动FRAME状态上应该是安全的。 托管升级使用已安装的`haxaml` CLI。`haxaml upgrade` 默认刷新核心和MCP，`haxaml upgrade --include-ui` 在您使用全套功能时添加仪表盘包。 如果您只想要没有入职流程的裸FRAME脚手架，请使用`haxaml init`。该命令现在创建缺失的核心FRAME文件，然后停止。 ## 本地仪表盘 我构建了一个轻量级仪表盘，您可以查看存储库的“联盟状态”。它是只读的，在localhost上运行。它允许您深入了解行为历史，检查项目事实，检查地图边界，并查看智能体当前预期构建的内容。 ```bash haxaml dashboard ``` ## FRAME 文件 - `.haxaml/facts.yaml`：项目真相：堆栈、目标和硬约束。 - `.haxaml/rules.yaml`：智能体的操作规则。 - `.haxaml/acts.yaml`：发生了什么的记录：最近的决定、验证证据、记录的运行以及与计划相比实际发生的情况。 - `.haxaml/map.yaml`：模块所有权和影响规则，解释哪些更改可以影响哪些内容。 - `.haxaml/expect.yaml`：前瞻性计划：最终预期状态、预期运行、检查点、里程碑和智能体正在努力实现的完成标准。 重要的循环很简单：`expect` 定义计划路径和终点，`acts` 记录检查和实际结果，`map` 解释它们之间的范围和影响边界。 ## 路线图和文档 - [goals.md](./goals.md)：规范的产品愿景、理论和功能方向。 - [learn/FRAME.md](./learn/FRAME.md)：底层记忆模型。 - [learn/haxaml.md](./learn/haxaml.md)：Haxaml如何将FRAME变成一个工作的受管系统。 - [learn/haxaml-mcp.md](./learn/haxaml-mcp.md)：面向操作员的MCP指南。 - [docs/architecture.md](./docs/architecture.md)：模块如何拆分。 - [CONTRIBUTING.md](./CONTRIBUTING.md)：如何帮助构建协议。