HLF Hieroglyphic Logic Framework MCP

📜 HLF——层次逻辑框架·MCP服务器

HLF旨在成为一种受控语言，将意图转化为可审计的机器动作。 打包的MCP服务器是目前最快的尝试方式，但真正的目标比服务器更大：语言、治理、运行时、内存、协调、解释和实际代码输出。

______________________________________________________________________

🚦 当前真相（2026年3月）

• 打包的FastMCP服务器 (hlf_mcp/)：作为stdio和HTTP/streaming HTTP MCP服务器运行。
• 确定性语言核心：编译器、语法、格式化器、linter、字节码、运行时和capsule执行都是真实的，并且经过测试。
• 受控路由、内存和审计：路由跟踪、内存证据和审计表面是公开和可查询的。
• 面向操作员的工具: hlf_do, _toolkit.py status，以及 hlf_test_suite_summary 提供有界的本地构建辅助和回归摘要。
• 受控构建循环：包装好的HLF可以在进一步开发过程中进行检查、测试和自我解释（“狗粮”）。
• 健康终点：包装 hlf_mcp HTTP/SSE通道返回 200 OK 从 /health 在明确的培养下。
• 所有测试均通过：从本版本开始，816/816测试通过。
• 本地MCP接线：工作区本地VS代码MCP配置现在针对打包的 uv run hlf-mcp 入口点。

______________________________________________________________________

🐕 狗食/递归构建辅助

HLF现在被用来帮助构建、测试和解释自己：

• 有限制、有管理的自用：打包的HLF MCP服务器已经可用于检查、测试和解释其自身的构建状态、回归健康状况和面向操作员的证据。
• 操作员工作流程：使用 hlf_do, _toolkit.py status，以及MCP工具/资源，以推动下一个构建步骤、记录证据和表面差距。
• 非完全自托管该系统尚未达到最大意义上的“自我建设”，但它已经在以一种真实、有限的方式行使自己的治理、审计和证据表面。
• 桥梁工程：添加、测试每个新的网桥切片（路由、验证、编排、角色、库等），然后用于进一步协助下一轮构建和恢复。

看 SSOT_HLF_MCP.md, BUILD_GUIDE.md，以及 docs/HLF_OPERATOR_BUILD_NOTES_2026-03-19.md 用于权威的当前状态和操作员工作流程。

   

HLF — Hieroglyphic Logic Framework · MCP Server

______________________________________________________________________

TL；面向开发人员的DR

• HLF为您提供了一个真正的编译器、格式化器、linter、字节码运行时和FastMCP服务器，用于受管代理工作。
• 目前最快的入口车道是打包的 hlf_mcp/ 曲面：从开始 stdio 本地，然后移动到 sse 或 streamable-http 当您需要HTTP传输时。
• 快速首次运行：同步依赖关系，编译 fixtures/hello_world.hlf，在本地运行它，然后启动打包的MCP服务器 HLF_TRANSPORT=stdio uv run hlf-mcp.
• 此自述文件有意使愿景、当前真相和桥梁上下文可见；使用 SSOT_HLF_MCP.md, BUILD_GUIDE.md，以及 docs/HLF_CLAIM_LANES.md 当你需要严格的界限时。

从这里开始

HLF不应仅被视为当前打包的版本。

此回购同时包含三件事：

• HLF试图成为什么样的人
• 现在已经存在的代码
• 桥梁工程需要在不使其变平的情况下恢复更大的系统

三车道视图： 通过愿景、现实和桥梁来阅读回购，而不是一个扁平的故事。

flowchart LR
    V[Vision Lane
North-star HLF doctrine
Larger than current package]
    C[Current-Truth Lane
What is implemented and safe to claim now]
    B[Bridge Lane
Recovery path from packaged truth
toward the fuller system]

    V --> B
    C --> B

    classDef vision fill:#f7e6c4,stroke:#8a5a00,color:#2b1d00
    classDef truth fill:#d9f0e3,stroke:#1d6b43,color:#113222
    classDef bridge fill:#dce9f9,stroke:#285a8f,color:#12263f

    class V vision
    class C truth
    class B bridge

首次读者快速阅读指南：

对于第一次通过后的更广泛的文档映射，请使用 HLF_IMPLEMENTATION_INDEX.md, HLF_SOURCE_EXTRACTION_LEDGER.md, HLF_SUPPORTIVE_SOURCE_CONTEXT_MAP.md，以及 docs/HLF_DOCTRINE_TEST_COVERAGE_MATRIX.md.

对于经过来源验证的外部基线摄入量，使用 docs/HLF_EXTERNAL_TECHNIQUE_SOURCE_AUDIT_2026-03-23.md 连同 docs/HLF_KNOWLEDGE_SUBSTRATE_RESEARCH_HANDOFF.md 和 docs/HLF_ROBOTICS_EMBODIED_FIT_ASSESSMENT.md.

如需了解分支机构的公众评论和PR阅读，请使用：

• docs/claims-ledger.html
• docs/HLF_BRANCH_AWARE_CLAIMS_LEDGER_2026-03-20.md
• docs/HLF_MERGE_READINESS_SUMMARY_2026-03-20.md
• docs/HLF_REVIEWER_HANDOFF_2026-03-20.md
• docs/HLF_STATUS_OVERVIEW.md
• docs/index.html

对于合并的GitHub Pages状态界面，请使用：

• docs/HLF_STATUS_OVERVIEW.md
• docs/index.html
• docs/merge-readiness.html
• docs/claims-ledger.html

存储库边界：

• hlf_mcp/ 是包装产品的表面和主要实施线。
• hlf/ 是一个保留的兼容性和支持层，具有有用的遗留和桥接资产。
• hlf_source/ 保存了源上下文，并从更广泛的主权体系中重建了证据。

第一站开发者链接：

• BUILD_GUIDE.md 对于当前为true的安装、测试和服务器命令
• docs/cli-tools.md 对于打包的CLI界面
• CONTRIBUTING.md 用于贡献工作流和低风险启动任务
• extensions/hlf-vscode/README.md 对于当前的VS代码桥和脱机VSIX安装路径

HLF不应该止步于整洁的MCP包装。 它旨在成为一种受治理的语言和协调基础，连接意图、工具、记忆、策略、执行和人类可读的信任。 这个回购已经包含了该系统的真实部分，其余部分应该被恢复，而不是被抛弃。

桥梁施工注意事项：

• plan/architecture-hlf-reconstruction-2.md 是主重建测序伪影。
• docs/HLF_DOCTRINE_TEST_COVERAGE_MATRIX.md 是目前将理论支柱映射到实际回归证明的桥梁工件。
• docs/HLF_RECURSIVE_BUILD_STORY.md 是对递归构建通道为什么重要以及应该如何解释的规范解释。
• docs/HLF_MESSAGING_LADDER.md 是从规范解释中衍生出来的针对特定受众的措辞指南。
• 第一个可信的递归构建故事是局部和有界的：打包的HLF通过 stdio, hlf_do, hlf_test_suite_summary，并建造观察面；远程 streamable-http 自托管保持门控状态，直到MCP初始化首尾相连成功。

为什么这个Repo脱颖而出

HLF的目标不仅是在系统完成后发挥作用。 它正在被塑造成一个受治理的语言和协调层，该层已经可以检查状态、总结回归、解释预期的操作，并在其自身构建和恢复过程的部分过程中保存证据。

这并不意味着完全的自托管已经完成。 这意味着回购已经包含一个有界的、可检查的证明，证明构建、操作和审计可以在同一个受管系统内开始收敛。

目前诚实的里程碑是首先提供本地和有界的建设援助。

• stdio 本地工作流很重要，因为它们是第一个可靠的证明通道
• hlf_do, _toolkit.py status, hlf_test_suite_summary，审计表面很重要，因为它们已经支持该循环
• 运输门控仍然很重要，因为更强的主张只应遵循更强的证据

这就是为什么这个回购的构建故事是其产品证据的一部分，而不仅仅是背景过程。

有关该声明的完整版本，请阅读 docs/HLF_RECURSIVE_BUILD_STORY.md。有关观众措辞规则，请阅读 docs/HLF_MESSAGING_LADDER.md.

对于代理商和建筑商

如果你以代理用户、构建者或操作员的身份评估这个仓库，正确的思维模式是：

• HLF是支配意义和协调基础
• 打包的MCP服务器是当前主要的产品界面

这在实践中意味着什么：

• 如今，打包的MCP表面已经是一个真正的受控接口，用于编译、验证、执行、翻译、解释、检查和面向内存的工作
• 对于构建者来说，同一个曲面是有界递归构建辅助的第一个稳定通道
• 对于代理来说，目标不仅是更好的工具访问，而且是一个受控的环境，在这个环境中，意图、效果边界、记忆、协调和解释保持联系

它的作用 不 平均值：

• MCP本身并不是完整的意义层
• 传输可用性与架构完成不是一回事
• 目前的封装表面尚未恢复每个构成的HLF柱

所以干净的位置是：

MCP服务器现在是HLF的右前门、右当前产品通道和右引导面，而更大的HLF愿景在语义、治理、内存、协调、信任和执行方面仍然比MCP大。

关于这一区别的完整教义版本，请阅读 docs/HLF_MCP_POSITIONING.md.

MCP前门视图： 装运的MCP表面是入口通道，而不是系统的完整本体。

flowchart TD
    MCP[MCP Front Door
Packaged FastMCP server
Current product surface]

    subgraph HLF[Fuller HLF System Target]
        S[Semantics]
        G[Governance]
        M[Memory]
        E[Execution]
        C[Coordination]
        L[Human Legibility]
        R[Real-code Output]
    end

    MCP --> S
    MCP --> G
    MCP --> M
    MCP --> E
    MCP --> C
    MCP --> L
    MCP --> R

    classDef front fill:#dce9f9,stroke:#285a8f,color:#12263f
    classDef system fill:#efe3f8,stroke:#6f3f8f,color:#2a1736

    class MCP front
    class S,G,M,E,C,L,R system

构成支柱视图： 这些是repo试图保持在一起的主要表面，而不是崩溃为仅解析器或仅MCP的故事。

flowchart TB
    Core[Semantic Core
grammar
compiler
bytecode]
    Gov[Governance Spine
ALIGN
capsules
policy]
    Mem[Knowledge Substrate
memory
witness
provenance]
    Exec[Execution Surface
runtime
admission
tool and host effects]
    Coord[Coordination Layer
routing
lifecycle
orchestration]
    Trust[Human Legibility
audit
explainability
operator review]
    Bridge[Real-world Bridge
MCP
real-code output
delivery surfaces]

    Core --> Exec
    Gov --> Exec
    Mem --> Coord
    Exec --> Coord
    Coord --> Trust
    Exec --> Trust
    Bridge --> Exec
    Bridge --> Trust
    Gov --> Trust
    Mem --> Trust

    classDef core fill:#efe3f8,stroke:#6f3f8f,color:#2a1736
    classDef gov fill:#f7e5d8,stroke:#9a5b2e,color:#3d200d
    classDef mem fill:#e8f2e1,stroke:#4c7a4c,color:#173117
    classDef exec fill:#dce9f9,stroke:#285a8f,color:#12263f
    classDef coord fill:#f5eddc,stroke:#8b6a2b,color:#36270b
    classDef trust fill:#f4f1ea,stroke:#705f49,color:#2b241a
    classDef bridge fill:#e9e9e9,stroke:#6a6a6a,color:#222222

    class Core core
    class Gov gov
    class Mem mem
    class Exec exec
    class Coord coord
    class Trust trust
    class Bridge bridge

阅读规则：

• 这是系统目标的形状，而不是声称现在每个支柱都同样完整
• 打包回购在每个领域都有真正的部分，但并非每个支柱都得到了同等的恢复
• 桥梁工程的存在是为了防止任何一根支柱冒充整个系统

紧凑型状态图例：

• present =现在存在真实的打包当前真值表面
• partial =包装表面存在，但仍需要桥接恢复或验证工作
• source-only =存在构成性的上游权威，但打包回购尚未诚实地要求完全恢复

快速阅读当前回购条件下的支柱图：

• 语义核心： present
• 治理骨干： present 到 partial，取决于您所指的控制面
• 知识基础和记忆治理： partial
• 执行表面： present 到 partial
• 协调层： partial
• 人类可读性： partial
• 现实世界的桥梁： present

视觉指南： 当将递归构建故事视为证明阶梯而非口号时，其效果最为显著。

flowchart TB
    A[Operator intent] --> B[Packaged MCP front door
hlf_do and related surfaces]
    B --> C[Bounded local workflow
stdio first]
    C --> D[Build observation
_toolkit.py status
hlf_test_suite_summary
artifact freshness]
    D --> E[Governed evidence
capsules
verifier admission
memory and witness traces]
    E --> F[Operator review
exportable audit and evidence]
    F --> G[Stronger remote recursive-build claims]

    classDef current fill:#d9f0e3,stroke:#1d6b43,color:#113222
    classDef bridge fill:#dce9f9,stroke:#285a8f,color:#12263f
    classDef gated fill:#f7e5d8,stroke:#9a5b2e,color:#3d200d

    class A,B,C,D,E,F current
    class G gated

阅读规则：

• 较低的层次已经是有意义的当前真理或桥梁支持的工作流表面
• 阶梯并不意味着回购是基本的；这意味着更有力的索赔是按顺序获得的
• 在远程MCP初始化和预期的烟雾路径在打包的工作流程中被证明可重复之前，顶层一直处于门控状态

目录

1. 什么是HLF？

- 企业精神-以人为本，透明治理

1. 快速开始
2. 架构概述
3. 语法和语言参考
4. 编译器管道（5遍）
5. 字节码VM
6. 意图胶囊层模型
7. 主机功能注册表
8. Stdlib-8个完整模块
9. HLF知识库（HKS）
10. 本能SDD生命周期
11. MCP服务器和传输
12. MCP工具参考

操作员证据审查

打包的CLI包括 hlf-evidence 用于审查受管理的每周工件。

有用的命令：

uv run hlf-evidence list --status promoted
uv run hlf-evidence show weekly_demo
uv run hlf-evidence show weekly_demo --json
uv run hlf-operator witness-status --json
uv run hlf-operator governed-route --json
uv run hlf-operator instinct-status --json
uv run hlf-operator formal-verifier --json
uv run hlf-operator entropy-anchor --json
uv run hlf-operator approval-review --json

面向操作员 show 输出有意与原始JSON不同。当附加受管审查时，纯文本视图直接公开角色移交合同，包括变更类、所有者角色、审查角色、所需关卡、升级目标、操作员摘要和移交模板参考。

具名 hlf-operator review命令现在为路由、见证、生命周期、证明、漂移和批准表面提供了一流的shell入口点，因此可以检查仓库的信任和编排通道，而无需回退到原始资源URI。

Instinct/操作员桥现在也比原始任务转储更强大：打包的生命周期表面公开了证明状态摘要、执行覆盖率、验证姿势、阻断器、CoVE门状态和密封证据，因此编排进度可以作为操作员证明合同进行审查，而不仅仅是存储的任务blob。

看 docs/cli-tools.md 以供命令参考。 15\. 基准结果 16\. 治理与安全 17\. 发展 18\. 路线图

______________________________________________________________________

1.什么是HLF？

HLF不仅仅是另一个DSL，也不仅仅是当前的MCP服务器。

HLF试图在人类意图和机器动作之间构建一个受控制的意义层：一种让代理协调、工具执行、内存持久化、策略约束和人类用简单的语言检查正在发生的事情的语言。

当前的MCP服务器很重要，因为它是当今最简单的采用途径。 但更大的目标是为受管代理工作提供真正的语言和运行时。

[HLF-v3]
Δ analyze /security/seccomp.json
  Ж [CONSTRAINT] mode="ro"
  Ж [EXPECT] vulnerability_shorthand
  ⨝ [VOTE] consensus="strict"
Ω

换言之： 前门是当前紧张的产品真相，而更完整的HLF系统仍然是更大的架构目标。

核心属性

5-表面语言

HLF程序有五种可互换的、可往返的表示形式：

Glyph Source  ──compile──▶  JSON AST  ──codegen──▶  .hlb Bytecode
     ▲                          │                         │
     │ hlffmt                   │ insaits                 │ disassemble
     │                          ▼                         ▼
ASCII Source            English Audit             Assembly Listing

企业精神——以人为本，透明治理

• 人和他们的工作是优先事项；隐私是默认的，HLF执行严格的法律，而不是家长式的过滤器。
• 人工智能是工具——人类制定约束，这些约束在仓库中保持透明和可审计。
• 有道德的州长在编译时执行严格的法律：先失败后危害，支持宣布的红帽研究路径，并以加密方式记录每一个决定。
• 监督的透明度：治理文件（ALIGN规则、道德文档）保持人类可读性，因此可以检查和讨论约束。
• 自由使用HLF；当界限适用时，它们是明确的，旨在保护人们，永远不会压制合法的研究或创造力。

安全责任： 虽然HLF和MCP实施了强大的、可审计的边界，但并非所有安全风险都可以在协议或软件级别得到缓解。用户负责自己的操作安全，包括（但不限于）使用受信任的VPN，维护信誉良好的本地安全套件（例如Bitdefender或同等产品），并遵循端点保护的最佳实践。项目精神是赋权，而不是保证；最终安全是系统及其操作员之间的共同责任。

看 docs/ETHICAL_GOVERNOR_HANDOFF.md 用于指导下游伦理模块实施的切换简报。

到达类比——为什么符号打败句子

如果你看过这部电影 *降临*，你知道前提：外星访客通过圆形标识进行交流，其中一个符号同时编码了整个命题——主语、动词、宾语、时态、因果关系和意图。像这样的人类句子 *“我们提供武器”* 取四个代币；七足语符在一个非线性字形中捕捉到了完整的意义、否定、条件和后果。语言学家不学语言，她学的是 意义的新思维，其中时间和意图不是连续的，而是同时的。

HLF就是为人工智能代理实现的想法。

当一个人写作 "Audit /security/seccomp.json, read-only, and report vulnerabilities"，这是一个 线性、模糊、高熵 句子。不同的LLM会以不同的方式解析它。令牌之间的上下文丢失。对于“只读”的含义或“报告”是否意味着文件写入权限，没有正式的保证。

当HLF将其压缩为：

[HLF-v3]
Δ [INTENT] goal="audit_seccomp"
  Ж [CONSTRAINT] mode="ro"
  Ж [EXPECT] vulnerability_shorthand
  ⨝ [VOTE] consensus="strict"
Ω

…每一个歧义都得到了解决 数学上. Ж [CONSTRAINT] mode="ro" 这不是一个建议——这是一个严格的、编译器强制的、燃气计量的边界。这 ⨝ [VOTE] 节点在接受结果之前需要达成共识。这 Ω 终结者密封了Merkle链审计的意图。每个符号都有一个精确的语义角色、一个定义的gas成本和一个加密哈希。

与七足语标一样，HLF字形 非线性命题：一个符号同时编码什么（意图）、如何（约束）、谁（层）、多少（gas）和证明（审计跟踪）。下面的数学——用于压缩的香农熵、用于消歧的KL散度、用于质量门控的置信阈值——是使这种方法可靠而不是聪明的原因。

前门是英国的。发动机是数学。字形就是桥。

有关包括13层三脑模型、Rosetta引擎（确定性编译等价）、EnCompass（概率天使非确定性）、ROMA编排和Darwin Gödel机器进化在内的完整架构愿景，请参阅 主权代理操作系统README --特别是最后几节中的升级建议，包括分层剖面、正式效果系统、5面往返以及从“有趣系统”到“行星级语言”的90天路线图

______________________________________________________________________

2.快速入门

30秒本地路径

# install the packaged toolchain
uv sync

# compile and run the smallest fixture
uv run hlfc fixtures/hello_world.hlf
uv run hlfrun fixtures/hello_world.hlf

# start the packaged MCP front door locally
HLF_TRANSPORT=stdio uv run hlf-mcp

如果你已经在这个仓库的活动Python虚拟环境中工作，那么同样的命令也适用于 python -m ...；参见 BUILD_GUIDE.md 对于规范变体。

选项A——Docker（推荐给任何代理）

# SSE transport (remote agents, web clients)
docker run -e HLF_TRANSPORT=sse -e HLF_PORT= -p : ghcr.io/grumpified-oggvct/hlf-mcp:latest

# Streamable-HTTP transport (modern MCP clients)
docker run -e HLF_TRANSPORT=streamable-http -e HLF_PORT= -p : ghcr.io/grumpified-oggvct/hlf-mcp:latest

# stdio transport (Claude Desktop, local agents)
docker run -i -e HLF_TRANSPORT=stdio ghcr.io/grumpified-oggvct/hlf-mcp:latest

对于HTTP传输，请明确选择并设置端口。打包服务器不再处理 8000 作为默认 sse 或 streamable-http.

这些传输示例显示了打包的运行时可用性。 它们本身并不提倡递归构建成熟度声明。

SSE处于活动状态时的端点：

选项B——本地安装

# 1. Install with uv (Python ≥ 3.12 required)
uv sync

# 2. Compile and run a fixture
uv run hlfc fixtures/security_audit.hlf
uv run hlfrun fixtures/hello_world.hlf

# 3. Start MCP server on an explicit chosen SSE port
HLF_TRANSPORT=sse HLF_PORT= uv run hlf-mcp

对于不熟悉的代理或操作员，请使用 docs/HLF_AGENT_ONBOARDING.md 在工作之前 hlf/ 或 hlf_source/ 直接。

选项C——Docker Compose（全栈）

HLF_PORT= docker compose up -d
# MCP SSE server → http://localhost:$HLF_PORT/sse
# Health check  → http://localhost:$HLF_PORT/health

递归构建声明的当前证明边界：

• stdio 仍然是第一条可靠的建造辅助车道
• 苏格兰和南方能源公司 streamable-http 保持有用的运输表面并提出目标
• 不要治疗远程 streamable-http 作为递归构建故事的中心，直到在打包的工作流中证明端到端的MCP初始化

克劳德桌面(claude_desktop_config.json)

使用Docker （集装箱）：

{
  "mcpServers": {
    "hlf": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HLF_TRANSPORT=stdio",
               "ghcr.io/grumpified-oggvct/hlf-mcp:latest"]
    }
  }
}

没有Docker （本地Python——不需要容器）：

{
  "mcpServers": {
    "hlf": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\gerry\\generic_workspace\\HLF_MCP", "hlf-mcp"],
      "env": {"HLF_TRANSPORT": "stdio"}
    }
  }
}

如果 uv 不在您的PATH中，请使用 python -m hlf_mcp 从回购的venv内部：

{
  "mcpServers": {
    "hlf": {
      "command": "python",
      "args": ["-m", "hlf_mcp"],
      "cwd": "C:\\Users\\gerry\\generic_workspace\\HLF_MCP",
      "env": {"HLF_TRANSPORT": "stdio"}
    }
  }
}

这是相同的——每个MCP客户端都会按需启动自己的服务器子进程。Docker是打包的便利性，而不是运行时的要求。

______________________________________________________________________

3.架构概述

此架构视图显示了打包的传输和服务器表面。 它不应该被解读为促进 streamable-http 仅通过传输存在进行递归构建证明。

flowchart TD
    subgraph Agents["🤖 Agent Layer"]
        A1[Claude / GPT / Gemini]
        A2[Local Ollama Agent]
        A3[Autonomous Swarm]
    end

    subgraph Transports["🌐 MCP Transports"]
        T1[stdio]
        T2[SSE :$HLF_PORT/sse]
        T3[Streamable-HTTP :$HLF_PORT/mcp]
    end

    subgraph Server["⚙️ HLF MCP Server  (hlf_mcp/server.py)"]
        S1[FastMCP packaged tool and resource surface]
    end

    subgraph Compiler["📐 Compiler Pipeline"]
        C0[Pass 0: NFKC + Homoglyph Norm]
        C1[Pass 1: LALR-1 Lark Parse]
        C2[Pass 2: SET Env Collection]
        C3[Pass 3: Dollar-VAR Expansion]
        C4[Pass 4: ALIGN Ledger Validate]
        C0 --> C1 --> C2 --> C3 --> C4
    end

    subgraph VM["🖥️ Bytecode VM"]
        V1[BytecodeCompiler → .hlb]
        V2[HlfVM Stack Machine]
        V3[Gas Meter]
        V1 --> V2
        V3 --> V2
    end

    subgraph Memory["🧠 HKS / Knowledge Substrate"]
        M1[SQLite WAL  fact_store]
        M2[Merkle Chain  Writer]
        M3[Cosine Dedup  0.98 threshold]
    end

    subgraph Instinct["🔄 Instinct SDD"]
        I1[SPECIFY → PLAN]
        I2[PLAN → EXECUTE]
        I3[EXECUTE → VERIFY]
        I4[VERIFY ──CoVE Gate──▶ MERGE]
        I1 --> I2 --> I3 --> I4
    end

    subgraph Governance["🔐 Governance"]
        G1[ALIGN Ledger  5 rules]
        G2[bytecode_spec.yaml  single source of truth]
        G3[host_functions.json  28 functions]
        G4[Intent Capsules  hearth / forge / sovereign]
    end

    Agents --> Transports --> Server
    Server --> Compiler
    Server --> VM
    Server --> Memory
    Server --> Instinct
    Server --> Governance
    Compiler --> VM

______________________________________________________________________

4.语法和语言参考

七个象形文字

字形语句以七个Unicode字形之一开头。HLF还支持关键字主导的语句，例如 SET, ASSIGN, IF, FUNCTION, TOOL, CALL, IMPORT，以及本能规范形式。下表显示了编译器使用的当前打包字形集和当前打包字节码降低：

报表类型（共21种）

glyph_stmt   — Δ/Ж/⨝/⌘/∇/⩕/⊎ [TAG] key="val" ...
assign_stmt  — ASSIGN name = expr       (mutable binding)
set_stmt     — SET name = expr          (immutable binding)
if_block_stmt — IF expr { ... } ELIF expr { ... } ELSE { ... }
if_flat_stmt — IF expr => stmt
for_stmt     — FOR name IN expr { ... }
parallel_stmt — PARALLEL { ... } { ... }
func_block_stmt — FUNCTION name(args) { ... }
intent_stmt  — INTENT name key="val" { ... }
tool_stmt    — TOOL name key="val"
call_stmt    — CALL name(args)
return_stmt  — RETURN value?
result_stmt  — RESULT code msg?
log_stmt     — LOG "message"
import_stmt  — IMPORT module_name
memory_stmt  — MEMORY entity confidence="0.9" content="..."
recall_stmt  — RECALL entity top_k=5
spec_define_stmt — SPEC_DEFINE name key="val"
spec_gate_stmt — SPEC_GATE name key="val"
spec_update_stmt — SPEC_UPDATE name key="val"
spec_seal_stmt — SPEC_SEAL name

Bridge注意：当前的打包语法现在是真实可用的，但长期的HLF语言目标比单独的语法清单更大，需要跨字形、ASCII、AST、字节码和审计/反编译形式的更强规范表面规范。

规范标签

INTENT  CONSTRAINT  ASSERT  EXPECT  DELEGATE  ROUTE  SOURCE
PARAM   PRIORITY    VOTE    RESULT  MEMORY    RECALL
GATE    DEFINE      MIGRATION  ALIGN

表达式优先级（低→ high)

_expr   (20) : ==  !=    =  AND  OR
_term   (30) : +  -
_factor (40) : *  /  %
_unary  (50) : NOT  -  (unary negation)
_atom        : string · int · float · bool · $VAR · ${VAR} · ident · path

程序结构

[HLF-v3]          ← header: version declaration
       ← body: one or more statements
Ω                  ← omega terminator (required)

类型注释(TYPE_SYM)

𝕊  — string    ℕ  — integer    𝔹  — boolean    𝕁  — JSON    𝔸  — any

示例程序

你好，世界

# HLF v3 — Hello World
[HLF-v3]
Δ [INTENT] goal="hello_world"
    Ж [ASSERT] status="ok"
    ∇ [RESULT] message="Hello, World!"
Ω

安全基线审计（哨兵模式）

# HLF v3 — Security Baseline Audit
[HLF-v3]
Δ analyze /security/seccomp.json
    Ж [CONSTRAINT] mode="ro"
    Ж [EXPECT] vulnerability_shorthand
    ⨝ [VOTE] consensus="strict"
Ω

多代理任务委派（编排器模式）

# HLF v3 — Multi-Agent Task Delegation
[HLF-v3]
⌘ [DELEGATE] agent="scribe" goal="fractal_summarize"
    ∇ [SOURCE] /data/raw_logs/matrix_sync_2026.txt
    ⩕ [PRIORITY] level="high"
    Ж [ASSERT] vram_limit="8GB"
Ω

实时资源中介（MoMA路由器）

# HLF v3 — MoMA Router
[HLF-v3]
⌘ [ROUTE] strategy="auto" tier="${DEPLOYMENT_TIER}"
    ∇ [PARAM] temperature=0.0
    Ж [VOTE] confirmation="required"
Ω

______________________________________________________________________

5.编译器管道（5遍）

下图总结了五个命名编译器过程。当前的打包编译路径还包括围绕这些命名通道的道德规范挂钩、气体估计和AST缓存。

flowchart LR
    src["HLF Source\n.hlf file"]

    subgraph P0["Pass 0 — Normalize"]
        n1["Unicode NFKC\nnormalization"]
        n2["Homoglyph\nsubstitution\nCyrillic/Greek/Math"]
        n1 --> n2
    end

    subgraph P1["Pass 1 — Parse"]
        p1["Lark LALR-1\nparser"]
        p2["HLFTransformer\n→ JSON AST"]
        p3["InsAIts\nhuman_readable\non every node"]
        p1 --> p2 --> p3
    end

    subgraph P2["Pass 2 — Env"]
        e1["Collect immutable\nSET bindings\ninto env dict"]
    end

    subgraph P3["Pass 3 — Expand"]
        v1["Resolve\n$VAR / ${VAR}\nreferences"]
    end

    subgraph P4["Pass 4 — ALIGN"]
        a1["Regex pattern scan\nagainst 5 ALIGN rules\n(credentials, SSRF,\ninjection, traversal, exfil)"]
    end

    out["JSON AST\n+ human_readable nodes\n+ version and counts\n+ normalization and ALIGN metadata"]

    src --> P0 --> P1 --> P2 --> P3 --> P4 --> out

字形混淆（第0遍）

通过0阻止 IDN同形词攻击 --其中一个视觉上相同的西里尔字母 а 替换拉丁文 a 通过解析器走私意外行为：

桥注：打包的编译器已经强制执行了一个真正的确定性管道，但通往更完整HLF完成的桥需要更强的一致性表面、往返证明和更严格的规范到实现的规范性，而不仅仅是传递图所能显示的。

______________________________________________________________________

6.字节码VM

二进制格式(.hlb)

Offset  Size   Field
──────  ─────  ────────────────────────────────────────────
0       32     SHA-256 manifest hash (integrity guard)
32      4      Magic bytes: "HLB\x00"
36      2      Format version (0x0004 = v0.4)
38      4      Code section length (little-endian uint32)
42      4      CRC32 checksum of code section
46      2      Flags (reserved, must be 0)
48      ...    Constant pool (typed entries)
48+n    ...    Code section (3-byte fixed instructions)

指令格式

每一条指令都是 3字节:

[opcode: 1 byte] [operand: 2 bytes little-endian]

操作码表（37个操作码）

graph LR
    subgraph Stack["Stack (0x00–0x04)"]
        NOP["NOP 0x00\ngas:0"]
        PUSH["PUSH_CONST 0x01\ngas:1"]
        STORE["STORE 0x02\ngas:2"]
        LOAD["LOAD 0x03\ngas:1"]
        IMMUT["STORE_IMMUT 0x04\ngas:3"]
    end
    subgraph Arith["Arithmetic (0x10–0x15)"]
        ADD["ADD 0x10\ngas:2"]
        SUB["SUB 0x11"]
        MUL["MUL 0x12\ngas:3"]
        DIV["DIV 0x13\ngas:5"]
        MOD["MOD 0x14\ngas:3"]
        NEG["NEG 0x15\ngas:1"]
    end
    subgraph Cmp["Comparison (0x20–0x25)"]
        EQ["CMP_EQ 0x20"]
        NE["CMP_NE 0x21"]
        LT["CMP_LT 0x22"]
    end
    subgraph Ctrl["Control (0x40–0x42)"]
        JMP["JMP 0x40\ngas:1"]
        JZ["JZ 0x41\ngas:2"]
        JNZ["JNZ 0x42\ngas:2"]
    end
    subgraph Calls["Calls (0x50–0x53)"]
        CB["CALL_BUILTIN 0x50\ngas:5"]
        CH["CALL_HOST 0x51\ngas:10"]
        CT["CALL_TOOL 0x52\ngas:15"]
        OC["OPENCLAW_TOOL 0x53\ngas:20"]
    end
    subgraph HLFSem["HLF Semantic (0x60–0x68)"]
        TAG["TAG 0x60\ngas:1"]
        INTENT["INTENT 0x61\ngas:2"]
        RESULT["RESULT 0x62\ngas:1"]
        MS["MEMORY_STORE 0x63\ngas:3"]
        MR["MEMORY_RECALL 0x64\ngas:2"]
        SD["SPEC_DEFINE 0x65\ngas:4"]
        SG["SPEC_GATE 0x66\ngas:4"]
        SU["SPEC_UPDATE 0x67\ngas:3"]
        SS["SPEC_SEAL 0x68\ngas:4"]
    end
    subgraph Sys["System"]
        HALT["HALT 0xFF\ngas:0"]
    end

操作码冲突已修复: OPENCLAW_TOOL 以前在 0x65，与Instinct规范操作码冲突。现在是在 0x53The governance/bytecode_spec.yaml 文件是 单一真相来源当前的打包代码与该规范保持一致；它尚未完全从中生成。

恒定池编码

Type   Byte   Encoding
─────  ─────  ──────────────────────────────
INT    0x01     little-endian signed 64-bit
FLOAT  0x02     IEEE-754 double
STRING 0x03     length-prefixed
BOOL   0x04     0x00=false / 0x01=true
NULL   0x05      no payload

气体模型

VM计量燃气 之前 每次派遣。关于它引发的预算违约 HlfVMGasExhausted 立即——不部分执行。

Bridge注意：当前的字节码/运行时契约现在是真实的和可审计的，但更完整的完成仍然需要更强的规范驱动生成、一致性测试，以及证明运行时行为在所有表面上都保留了规范的HLF含义。

______________________________________________________________________

7.意图胶囊层模型

Intent Capsules绑定了每个代理层可以读取、写入和调用的内容——在静态（飞行前AST检查）和动态（运行时）级别强制执行。

graph TD
    subgraph hearth["🔒 hearth — Minimal Trust"]
        h1["Allowed tags include SET · IF · RESULT\nplus INTENT/CONSTRAINT/ASSERT/PARAM/SOURCE/LOG"]
        h2["No TOOL calls; memory and recall denied"]
        h3["Gas limit: 100"]
        h4["Read-only: SYS_INFO · NOW"]
    end

    subgraph forge["🔧 forge — Standard Agent"]
        f1["Allowed tags include SET · ASSIGN · IF · FOR · RESULT · TOOL · CALL\nplus memory, import, intent, route, delegate, vote, priority"]
        f2["Denied tags: SPAWN · SHELL_EXEC"]
        f3["Allowed tools include READ · WRITE · HTTP_GET\nwith explicit denied-tool checks"]
        f4["Gas limit: 500"]
    end

    subgraph sovereign["👑 sovereign — Trusted Orchestrator"]
        s1["No capsule tag deny-list by default"]
        s2["Capsule admits all tools subject to registry/runtime tier checks"]
        s3["Gas limit: 1000"]
        s4["Broadest packaged capsule surface"]
    end

    hearth -->|"promoted by operator"| forge
    forge  -->|"promoted by operator"| sovereign

太空舱飞行前验证

在执行任何VM之前，capsule静态检查AST：

1. 标记白名单/黑名单 --拒绝标签提升 CapsuleViolation 在第一条指令运行之前
2. 工具白名单/黑名单 --对显式工具/调用曲面进行检查 allowed_tools / denied_tools
3. 只读变量保护 — SET 和 ASSIGN 受保护的变量，如 SYS_INFO 并且，in hearth, NOW 被封锁
4. 天然气预算 --根据能力使用的累积气体进行检查 max_gas

Bridge注：capsules已经提供了真正的有界准入行为，但更大的HLF目标需要比当前层解释器捕获的更丰富的形式效果和批准模型。

______________________________________________________________________

8.主机功能注册表

中定义了32个主机功能 governance/host_functions.json。每个都有 tier, gas, backend，以及 sensitive 在运行时强制执行的字段。下表是当前打包注册表表面的代表性子集：

敏感输出：功能与 sensitive=true 从不记录原始返回值——只记录 SHA-256[:16] 前缀被写入审计日志。

Bridge注意：注册表已经是一个真正的能力契约，但更完整的HLF完成需要一个比当前README子集所能表达的更强大的效果模式，具有更清晰的确定性、幂等性和后端可移植性语义。

______________________________________________________________________

9.Stdlib——8个完整模块

这里列出的所有八个stdlib模块都是在打包的运行时中实现的，没有明显的占位符存根。这里的“完成”意味着现在已实现，相对于更大的HLF语言目标，语义上尚未完成。它们可以通过以下方式导入HLF IMPORT module_name 并可作为 module_name.FUNCTION(args).

加密模块-AES-256-GCM（无短路）

# ENCRYPT: random 12-byte nonce, AES-256-GCM, returns base64(nonce + GCM-tag + ciphertext)
result = crypto.ENCRYPT(plaintext, key_b64)

# DECRYPT: authenticates GCM tag before releasing plaintext — fails on tamper
plain  = crypto.DECRYPT(ciphertext_b64, key_b64)

# KEY_DERIVE: PBKDF2-HMAC-SHA256, 600,000 iterations (OWASP 2024 recommendation)
key    = crypto.KEY_DERIVE(password, salt_b64)

# MERKLE_ROOT: SHA-256 binary tree — lossless round-trip from AST
root   = crypto.MERKLE_ROOT(["leaf1", "leaf2", "leaf3"])

Bridge注意：打包的stdlib已经非常有用，但远程HLF语言界面将需要比当前stdlib摘要本身所暗示的更强的类型、效果语义、包/版本规范和更广泛的受管语言功能。

______________________________________________________________________

10.HLF知识库（HKS）

HLF知识基础或HKS是回购的受管知识体系。 HKS可以利用需要持久内存和检索的Infinite RAG，但它们在范围上是分开的。 Infinite RAG是它自己的内存子系统和引擎。 HKS是更广泛的受管理知识层，包括示例、来源、每周证据、操作员可审查的召回和跨会话的知识推广合同。

当前包装的真相：

• 无限的RAG坚持和回忆是真实的
• HKS样本捕获和召回表面是真实的
• 每周HKS工件集成挂钩是真实的
• 来源承载记忆节点和Merkle链接谱系是真实的
• 面向MCP内存的工具是真实的
• 更广泛的新鲜度、信任级别、替代、每周证据和更全面的HKS合同仍然是桥梁工作

graph LR
    subgraph Store["SQLite WAL  fact_store"]
        W[MemoryStore.store]
        D[Cosine dedup\n>0.98 threshold]
        M[Merkle chain\nwriter]
        T[TTL expiry\nprune_decay]
        W --> D --> M
        T -.prunes.-> W
    end

    subgraph Query["Semantic Retrieval"]
        Q[RAGMemory.query]
        BV[Bag-of-words\nvector]
        CS[Cosine\nranking]
        Q --> BV --> CS
    end

    subgraph Integration["MCP Tools"]
        TS[hlf_memory_store]
        TQ[hlf_memory_query]
        TT[hlf_memory_stats]
        HC[hlf_hks_capture]
        HR[hlf_hks_recall]
    end

    Integration --> Store
    Integration --> Query

    subgraph Future["🔨 Planned"]
        EM[sqlite-vec\nvector embeddings]
        SD[SHA-256\ndedup cache]
        FS[Fractal\nsummarization]
    end

HKS地产

HKS范围

该回购中的HKS目前涵盖：

• HKS样本捕获和受控召回路径
• 每周验证工件到HKS示例转换挂钩
• 来源承载知识对象和证据摘要
• 具有无限RAG持久性和检索的集成点
• 具有起源字段和TTL行为的受管内存节点
• 面向内存的MCP工具，用于存储、查询、统计和HKS示例流
• 更广泛的记忆/治理通道中的证人和审计相邻证据流

HKS旨在向一个更丰富的受管基础趋同，该基础承载新鲜度、信心、信任层语义、替代、撤销、每周知识摄入和运营商清晰的证据合同。

HLF↔ HKS Synergy

Bridge注意：在本次检查中，HKS已经不仅仅是一个通用的内存桶，但预期的受管知识基础仍然大于当前打包的持久性、示例性和每周证据表面。

______________________________________________________________________

11.本能SDD生命周期

在打包的Instinct生命周期中跟踪的每个任务都遵循确定性 指定→ Plan → 执行→ 验证→ Merge 路径。阶段跳过和向后转换被阻止。CoVE门是强制性的 VERIFY → MERGE.

stateDiagram-v2
    [*] --> SPECIFY : instinct_step(SPECIFY)

    SPECIFY --> PLAN : spec accepted
    PLAN --> EXECUTE : plan approved
    EXECUTE --> VERIFY : execution complete
    VERIFY --> MERGE : CoVE gate PASSED ✓
    VERIFY --> VERIFY : CoVE gate FAILED ✗ — merge blocked
    MERGE --> [*] : mission complete

    SPECIFY --> SPECIFY : validation error (stays)
    note right of VERIFY
        CoVE adversarial gate:
        verifies the execution output
        against the original spec before
        allowing any merge to proceed.
        Failure halts the mission.
    end note

    note right of MERGE
        ALIGN Ledger entry written.
        Merkle hash appended.
        Immutable audit record created.
    end note

生命周期规则

• 无阶段跳过：无法从 SPECIFY 到 EXECUTE --每个中间阶段都是必需的
• 无向后转换A. MERGEd任务无法重新开放 EXECUTE
• 确认登机口→MERGE：如果 cove_result.get("passed") == False，合并转换被阻止，任务仍处于 VERIFY 除非在生命周期的后期进行
• 对齐分类账日志记录：每个阶段转换都会生成一个带有SHA-256哈希和ULID时间戳的分类账条目

Bridge注：打包的生命周期已经强制执行了一个真正的确定性任务路径，但更大的HLF协调目标仍然需要比单独的生命周期总结更丰富的编排、验证证据和跨代理治理。

______________________________________________________________________

12.MCP服务器和传输

graph LR
    subgraph Clients
        C1["Claude Desktop\n(stdio)"]
        C2["Remote Agent\n(SSE HTTP)"]
        C3["Modern MCP Client\n(streamable-HTTP)"]
    end

    subgraph Server["HLF MCP Server  (FastMCP)"]
        T1["stdio\ntransport"]
        T2["SSE\n/sse + /messages"]
        T3["streamable-HTTP\n/mcp"]
        Core["packaged tools and resources\nHLF_TRANSPORT env"]
        T1 --> Core
        T2 --> Core
        T3 --> Core
    end

    subgraph Resources
        R1["hlf://grammar"]
        R2["hlf://opcodes"]
        R3["hlf://host_functions"]
        R4["hlf://examples/{name}"]
        R5["hlf://governance/*"]
        R6["hlf://stdlib"]
    end

    C1 --> T1
    C2 --> T2
    C3 --> T3
    Core --> Resources

传输配置

电流证明边界：

• stdio 仍然是有界递归构建通道的主要电流真值传输
• HTTP传输是真正的打包表面，但更强的自托管声明应该由端到端的MCP证明来控制，而不仅仅是传输可用性

# Environment variables
HLF_TRANSPORT=sse           # transport type
HLF_HOST=0.0.0.0            # bind address (SSE/HTTP only)
HLF_PORT=    # required explicit port (SSE/HTTP only)

______________________________________________________________________

13.MCP工具参考

编译器和分析工具

翻译与反编译

胶囊和安全

记忆与本能

基准测试

资源（只读）

______________________________________________________________________

14.Docker部署

多阶段构建

# Stage 1: builder — installs all deps with uv
FROM python:3.12-slim AS builder
WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Stage 2: runtime — minimal image, no build tools
FROM python:3.12-slim
COPY --from=builder /app /app
WORKDIR /app
HEALTHCHECK --interval=30s CMD python -c "import os, urllib.request; urllib.request.urlopen('http://localhost:' + os.environ['HLF_PORT'] + '/health')" || exit 1
ENV HLF_TRANSPORT=sse HLF_HOST=0.0.0.0
CMD ["/app/.venv/bin/python", "-m", "hlf_mcp.server"]

docker-compose.yml

services:
  hlf-mcp:
    build: .
    ports:
            - "${HLF_PORT:?Set HLF_PORT}:${HLF_PORT:?Set HLF_PORT}"
    environment:
      HLF_TRANSPORT: sse
      HLF_HOST: 0.0.0.0
            HLF_PORT: "${HLF_PORT:?Set HLF_PORT}"
    healthcheck:
            test: ["CMD-SHELL", "python -c \"import os, urllib.request; urllib.request.urlopen('http://localhost:' + os.environ['HLF_PORT'] + '/health')\""]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

环境参考

______________________________________________________________________

15.基准结果

用以下方法测量的实际压缩比 Tiktoken CL 100 K基座 （OpenAI的标记器）：

Token Compression by Domain
─────────────────────────────────────────────────────────────────
Hello World     [██████████████████████████████ 29.6%]
Security Audit  [█████████████████████████ 25.7%]
Delegation      [████████████ 12.2%]
DB Migration    [████████████ 12.2%]
Log Analysis    [███████ 7.0%]
Stack Deployment[░ -4.8%  (HLF tags add overhead for tiny payloads)]
─────────────────────────────────────────────────────────────────
Overall: 12.5% · In a 5-agent swarm: 415 tokens saved per broadcast cycle

备注：压缩随着有效载荷复杂性的增加而急剧增加。简单的结构任务，如 deploy_stack 显示接近奇偶校验，因为HLF的类型化标签增加了开销，与NLP对短有效载荷的冗长程度相匹配。在规模上（复杂意图+群体广播），HLF的优势化合物——节省了83个令牌×5个代理= 每个周期415个令牌.

______________________________________________________________________

16.治理与安全

对齐分类账（5条规则）

ALIGN Ledger在编译器中作为Pass 4运行。AST中的每个字符串文字都会被扫描：

安全层

graph TD
    A["HLF Source received"]
    B["Pass 0: Homoglyph strip\n(IDN homograph protection)"]
    C["Pass 4: ALIGN Ledger\n(5 governance rules)"]
    D["Capsule pre-flight\n(tag/tool whitelist check)"]
    E["Gas budget check\n(before every opcode)"]
    F["ACFS confinement\n(READ/WRITE path validation)"]
    G["Sensitive output hashing\n(SHA-256[:16] in logs)"]
    H["Merkle chain write\n(immutable audit trail)"]

    A --> B --> C --> D --> E --> F --> G --> H

运营商信任链

flowchart LR
    Intent[Intent input
plain language or HLF] --> Policy[Policy and governance
ALIGN and ethical governor]
    Policy --> Capsule[Capsule and admission
tier, tool, gas, verifier gates]
    Capsule --> Exec[Execution and runtime
bytecode, tools, host effects]
    Exec --> Evidence[Evidence surfaces
memory, witness, traces, Merkle chain]
    Evidence --> Operator[Operator-readable output
audit summary, rationale, export]

    classDef intent fill:#dce9f9,stroke:#285a8f,color:#12263f
    classDef policy fill:#f7e5d8,stroke:#9a5b2e,color:#3d200d
    classDef exec fill:#e8f2e1,stroke:#4c7a4c,color:#173117
    classDef evidence fill:#efe3f8,stroke:#6f3f8f,color:#2a1736
    classDef operator fill:#f4f1ea,stroke:#705f49,color:#2b241a

    class Intent intent
    class Policy,Capsule policy
    class Exec exec
    class Evidence evidence
    class Operator operator

阅读规则：

• 信任链是回购试图保持从意图到运营商审查的连续性
• 如果任何中间步骤变得不透明，即使运行时仍在执行，公共声明也会变弱
• 这就是为什么治理、承认、证据和人类可读的输出被视为核心表面而不是额外的

伦理治理——全面落实

调速器作为强制性的飞行前闸门连接到编译器管道中。它在字节码生成之前运行并引发 CompileError 在任何高严重性信号上——没有部分执行，没有无声旁路。

编译器挂钩: compiler.py 电话 governor.raise_if_blocked() 第四关结束时。被阻止的程序提高 CompileError 随着 RuleId, Article，以及完整的审计跟踪。

测试覆盖率：44个专用测试 tests/test_ethics.py 涵盖宪法违规、终止审计日志、红帽声明、流氓信号检测和编译器集成。

加密堆栈

• AES-256-GCM --带有身份验证标签的对称加密（通过Python） cryptography 图书馆）
• PBKDF2-HMAC-SHA256 --密钥推导，600000次迭代（OWASP 2024）
• HMAC-SHA256 --消息认证/签名
• SHA-256 Merkle树 --无损AST来源链
• 沙-256 .hlb 头球 --字节码完整性清单

______________________________________________________________________

17.发展

安装和测试

# Install all dependencies
uv sync

# Run the canonical automated suite
python run_tests.py
python -m hlf_mcp.test_runner

# Or call pytest directly
uv run pytest tests/ -q --tb=short

# Record a local weekly evidence snapshot
python scripts/run_pipeline_scheduled.py

# Run specific test modules
uv run pytest tests/test_compiler.py -v
uv run pytest tests/test_ethics.py -v
uv run pytest tests/test_formatter.py -v
uv run pytest tests/test_linter.py -v
uv run pytest tests/test_github_scripts.py -v

对于较短的新手路径，请使用：

uv sync
uv run pytest tests/ -q --tb=short
uv run ruff check hlf_mcp/

如果 uv 您的计算机上尚未安装，请先安装或使用等效软件 python -m pip install -e '.[dev]' 在虚拟环境中回退。

CLI工具

首次建设者常见问题解答

什么是胶囊？

意图胶囊是执行周围的准入边界。在允许运行时继续之前，它应用了层、气体上限和验证规则。从本README的第7节开始(Intent Capsule Tier Model)以及 hlf_mcp/hlf/capsules.py.

CoVE是什么？

CoVE是Instinct生命周期中合并门之前的验证。在这个回购中，它是受监管的一部分 SPECIFY → PLAN → EXECUTE → VERIFY → MERGE 故事而不是松散的口号；从本README的第11节开始(Instinct SDD Lifecycle)以及 hlf_mcp/instinct/lifecycle.py.

我应该先使用哪种交通工具？

使用 stdio 首先是本地和有界构建辅助工作流。 sse 和 streamable-http 是真正的打包传输，但更强的远程递归构建声明将保持门控状态，直到端到端证明完整的MCP初始化路径。

如何添加或更改主机功能？

更新中的治理合同 governance/host_functions.json，将打包的实现连接到 hlf_mcp/，然后重新运行涵盖注册表和服务器表面的文档和测试。 docs/HLF_HOST_FUNCTIONS_REFERENCE.md 和 docs/cli-tools.md 是最好的开始参考。

如果我想捐款，我应该从哪里开始？

使用 CONTRIBUTING.md 用于工作流、启动任务和验证命令。对于索赔敏感文档的工作，也请检查 docs/HLF_CLAIM_LANES.md 和 docs/HLF_README_OPERATIONALIZATION_MATRIX.md.

项目结构

hlf_mcp/
├── server.py               # FastMCP server and packaged MCP front door
├── hlf/
│   ├── grammar.py          # LALR(1) Lark grammar + glyph map + confusables
│   ├── compiler.py         # 5-pass compiler pipeline
│   ├── formatter.py        # Canonical formatter
│   ├── linter.py           # Static analysis
│   ├── bytecode.py         # Bytecode compiler + VM + disassembler
│   ├── runtime.py          # AST-level interpreter + 50+ builtins
│   ├── capsules.py         # Intent Capsule (hearth/forge/sovereign)
│   ├── registry.py         # HostFunctionRegistry (JSON-backed)
│   ├── tool_dispatch.py    # ToolRegistry + HITL gate
│   ├── oci_client.py       # OCI package registry client
│   ├── hlfpm.py            # Package manager (install/freeze/list)
│   ├── hlflsp.py           # Language server (diagnostics, completion, hover, definitions)
│   ├── translator.py       # HLF ↔ English translation (tone-aware)
│   ├── insaits.py          # InsAIts decompiler (AST/bytecode → English)
│   ├── memory_node.py      # MemoryNode + MemoryStore
│   ├── benchmark.py        # tiktoken compression analysis
│   └── stdlib/
│       ├── agent.py        crypto_mod.py   io_mod.py
│       ├── math_mod.py     net_mod.py      string_mod.py
│       ├── system_mod.py   collections_mod.py
├── rag/
│   └── memory.py           # Infinite RAG SQLite memory store
└── instinct/
    └── lifecycle.py        # Instinct SDD state machine + CoVE gate

governance/
├── bytecode_spec.yaml      # ← Single source of truth for all opcodes
├── host_functions.json     # 32 host functions (tier/gas/backend/sensitive)
├── align_rules.json        # 5 ALIGN Ledger governance rules
├── module_import_rules.yaml# Import policy extracted from Sovereign source
└── templates/
    └── dictionary.json     # Tag/glyph dictionary for future tooling

fixtures/                   # 11 example HLF programs
scripts/
├── generate_tm_grammar.py  # Build TextMate grammar from packaged HLF metadata
├── gen_docs.py             # Build packaged tag and stdlib reference docs
├── hlf_token_lint.py       # Token-budget linting for .hlf corpora
├── live_api_test.py
└── monitor_model_drift.py
syntaxes/
└── hlf.tmLanguage.json     # Generated HLF syntax grammar
docs/
├── HLF_GRAMMAR_REFERENCE.md # Adapted packaged grammar reference
├── HLF_TAG_REFERENCE.md    # Generated from governance/templates/dictionary.json
├── HLF_STDLIB_REFERENCE.md # Generated from packaged Python stdlib bindings
├── stdlib.md               # Adapted packaged stdlib guide
└── ...
tests/                      # pytest test suite
Dockerfile                  # Multi-stage production build
docker-compose.yml          # Service composition with health check

代码检查

uv run ruff check hlf_mcp/
uv run ruff format hlf_mcp/

______________________________________________________________________

18.路线图

第一阶段——基础✅ （此PR）

• \[x\] LALR（1）语法：21种语句类型，7种字形，表达式优先级
• \[x\] 带有ALIGN Ledger验证的5遍编译器管道
• \[x\] 字节码VM:37个操作码，气体计量，SHA-256 .hlb 头球
• \[x\] 修复了操作码冲突(OPENCLAW_TOOL 0x65 → 0x53)
• \[x\] governance/bytecode_spec.yaml 作为唯一的真理来源
• \[x\] 32个具有层/气体/后端强制的主机功能
• \[x\] 意图胶囊：炉膛/锻造/主权层
• \[x\] 8个stdlib模块（无存根——AES-256-GCM加密、PBKDF2、HMAC-SHA256）
• \[x\] 无限RAG子系统（SQLite WAL、Merkle谱系、余弦去噪）
• \[x\] HKS桥表面（验证样本捕获/召回、每周工件挂钩、受控知识契约）
• \[x\] 本能SDD生命周期（请指定→PLAN→执行→验证→融合，CoVE门）
• \[x\] 带有打包工具、打包资源和stdio+SSE+流式HTTP传输的FastMCP服务器
• \[x\] 多级Docker镜像+Docker组合与健康检查
• \[x\] 伦理管理器：5模块编译时门（宪法·终止·红色攻击·流氓检测·管理器）
• \[x\] 打包的默认pytest套件在此分支中为绿色；使用 python run_tests.py 或 hlf_test_suite_summary 当前计数

第二阶段——强化语义学🔨 （进行中）

• \[x\] Ollama云客户端：流媒体、思维、结构化输出、工具调用、网络搜索、带断路器的4层回退链(.github/scripts/ollama_client.py)
• \[x\] 每周自动化基线：7个预定的GitHub工作流——代码质量、规范哨兵、模型漂移检测、道德审查、文档/安全审查、测试健康和演化计划——现在被规范化为共享的每周工件模式
• \[x\] 模型漂移监测：7个具有结构化输出评分的加权语义探针(scripts/monitor_model_drift.py)
• \[ \] 矢量嵌入: sqlite-vec 实余弦搜索的C扩展（替换词袋）
• \[ \] SHA-256去重缓存：预嵌入重复数据消除层
• \[ \] 分形总结：当内存接近令牌限制时，map会减少上下文压缩
• \[ \] 热/温/冷系带：Redis热→ SQLite温暖→ 拼花地板冷语境转换
• \[x\] LSP服务器 (hlflsp)：打包诊断、完成、悬停、文档符号、转到定义
• \[x\] hlfsh REPL：打包编译器/linter表面上的交互式shell
• \[x\] 最快跑步者：代码段、文件和夹具目录的打包编译+lint线束

当前结账的分行注意事项：

• \[x\] 政府审查合同：现在存在规范漂移、测试健康、道德审查、代码质量、文档准确性和安全模式审查的规范化审查有效载荷(hlf_mcp/governed_review.py)
• \[x\] 操作员证据表面：此分支上已经打包了每周工件决策持久性和证据查询/报告(hlf_mcp/weekly_artifacts.py, tests/test_evidence_query.py)
• \[x\] 符号关系边缘证明切片：ASCII第一符号提取、投影和审计日志记录已存在并经过测试(hlf_mcp/hlf/symbolic_surfaces.py, tests/test_symbolic_surfaces.py)
• \[x\] 梦境循环与媒体证据桥梁切片：咨询梦想发现、媒体证据规范化、引用链提案和多式联运合同资源都存在于这个分支中，并且仍然是桥梁车道表面，而不是完全目标状态完成(hlf_mcp/server_context.py, hlf_mcp/server_memory.py, hlf_mcp/server_resources.py, tests/test_dream_cycle.py)
• \[x\] VS代码操作员桥架脚手架：下面存在一个感知索赔通道的操作员外壳脚手架 extensions/hlf-vscode/；将其视为桥梁工程，而不是市场运送的完工

审阅者备注：

• 使用 docs/HLF_BRANCH_AWARE_CLAIMS_LEDGER_2026-03-20.md 对夸大的公共差距、有效的公共差距，分支机构解决的差距和仍然开放的架构差距进行紧凑的面向公众的分类

• 使用 docs/HLF_MERGE_READINESS_SUMMARY_2026-03-20.md 对于当前分支拆分 current-true, bridge-true，仍然开放的建筑工作

• 使用 docs/HLF_REVIEWER_HANDOFF_2026-03-20.md 对于从合并准备情况摘要中提取的PR就绪审阅者切换

第3阶段——通用可用性🌐 （计划中）

• \[ \] ASCII表面：往返 IF risk > 0 THEN [RESULT] ↔ ⊎ risk > 0 ⇒ [RESULT]
• \[ \] WASM目标：将HLF程序编译为WebAssembly以供浏览器/边缘执行
• \[ \] OCI注册表推送：完成 OCIClient.push() 用于模块发布
• \[ \] Z3形式验证: z3_verify host函数--证明SPEC_GATE断言成立
• \[ \] EGL监视器：MAP精英质量多样性网格跟踪代理专业化漂移
• \[ \] 工具HITL门UI：用于审批的web仪表板 pending_hitl 工具
• \[ \] SpindleDAG执行器：带有Saga补偿事务的任务DAG

第四阶段——生态系统整合🔗 （计划中）

通过HLF主机功能与Sovereign Agent OS集成：

第5阶段——标准，而非项目🏛️ （长期）

• \[ \] 一致性套件：每个操作码和语法生成的规范测试向量
• \[ \] 生成的文档：生成的所有规范性文件 governance/ 规范文件——没有手工编辑的漂移
• \[ \] HLF配置文件：将HLF核心/HLF效果/HLF代理/HLF内存/HLF-VM作为可分离的规范发布
• \[ \] 跨模型对齐测试：验证任何LLM都可以在不进行微调的情况下产生有效的HLF
• \[ \] 梦想状态自我提升：压缩HLF规则的夜间DSPy回归
• \[ \] HLF自编程：操作系统最终会编写自己的HLF程序来编排集成

______________________________________________________________________

相关链接

• 📖 打包的HLF参考
• 🧾 CLI工具参考
• 📚 主机功能参考
• 🔄 打包本能参考
• 🎵 苏诺赛道——门廊蓝草采用三车道原则 --对README的愿景/当前真相/桥梁框架的音乐致敬
• 📜 RFC 9000系列
• 🗺️ 统一生态系统路线图
• 🏗️ 演练
• 🔬 NotebookLM研究笔记本 --291个来源，深度研究报告，RFC目录

______________________________________________________________________

*HLF主要不是语法。它是一个 有限能力下确定性意义契约语法是可逆的，语义是规范的，效果是显式的，执行是可重复的，审计是内置的，工具是生成的，进化是受控的。*