Cruxible Core

Cruxible

cruxible.ai · 快速入门 · 文档 · 套件 · 技能

Cruxible 是面向 AI Agent 的受治理状态引擎。 它生成一种 Crux： 一种可执行的领域知识产物，具有类似代码的生命周期—— 具备类型、经过审查、版本化、可审计，并通过实际结果进行测试。

问题所在。 代码有类型、经过审查并进行版本控制；它确定性地执行，测试可在几秒内验证代码。Agent 产出的判断、观察、可复用操作和决策却都落在散文中——它们无法执行，没有从提议到可信的受治理路径，也无法限制哪些内容会被重复采用。真实决策往往要数周或数月后才有结果，那时早已无人继续跟踪。而散文无法作为共享依据：运行众多 Agent 的组织需要它们都依据同一套最新声明、规则和经过审查的行动方式行事，而不是各自解读文档。

工作原理。 你在 YAML 中声明领域本体及其规则。可复现的流水线将可信源数据转化为类型化状态。当 Agent 或人员作出判断时，Cruxible 可以要求提供证据并经过审查，声明才能生效。当 Agent 学会一种有效的行动方式时，也可以将其提议出来：Procedure 与声明一样要经过相同的审查周期，并且只能在其声明的输入、前置条件和限制范围内运行。决策在获接受之前，可以被要求声明何种结果算作成功；结果契约会按自身计划到期，并记录现实给出的答案。查询和操作针对同一实时状态运行，无效变更会被拒绝。引擎内部不运行 LLM。

为何使用它。 每个 Agent 都基于相同的实时声明工作，并可调用相同的、经过审查且有明确边界的 Procedure。无效写入和操作会被拒绝，矛盾会持续显现，直到得到解决；决策可以根据实际发生的情况进行核验，计算结果、变更和操作运行都会附带说明缘由的凭据。快照会在某个修订版本中捕获确切的配置、锁文件、图状态和流程定义，以供比较、分支和传输；备份则保留完整的审计存储，以便恢复。整个产物的生命周期不受任何单次会话或模型的限制。

来看一个简单示例：供应商库存和事件源会根据固定来源构建实体。Agent 得出结论，认为某起事件会影响某个供应商，但这种关联被声明为需要判断的事项：

entity_types:
  Incident:
    id: incident_id
    properties:
      title: string indexed
  Supplier:
    id: supplier_id
    properties:
      name: string indexed

relationships:
  - incident_impacts_supplier: Incident -> Supplier
    write_policy: proposal_only        # judgment call: enters only through review

named_queries:
  incident_impacted_suppliers:
    mode: traversal
    entry_point: Incident
    returns: Supplier
    traverse:
      - relationship: incident_impacts_supplier
        direction: outgoing

现在，策略已成为运行时的一部分。直接写入会被拒绝，审查通过后该判断才会生效，查询则会计算其影响：

  $ cruxible relationship add incident_impacts_supplier \
      Incident INC-TW-RAIL-2026-07 Supplier S-CN-DG-HARNESS
- Error: DirectWriteRefusedError: Direct write to relationship
- 'incident_impacts_supplier' is refused (write_policy=proposal_only).
- Use 'group propose' to stage a governed proposal. (receipt: RCP-…)

  $ cruxible propose --workflow propose_incident_impacts_supplier
  $ cruxible group resolve --group <GRP-id> --action approve \
      --rationale "Confirmed against supplier geography"

  $ cruxible query run incident_impacted_suppliers \
      --param incident_id=INC-TW-RAIL-2026-07 --json
+ { "items": [ { "entity_type": "Supplier", "entity_id": "S-CN-DG-HARNESS" } ],
+   "receipt_id": "RCP-2f61a90c84d3" }

来源事实通过确定性摄取进入系统；推断出的边则通过审核加入。现在，查询可以沿着它追溯影响，守卫和门控可以对其执行操作，之后的观察也可以与之矛盾，而不会悄然改写历史。

INGEST       pinned feeds -> Incident, Supplier, Product, and Shipment state
CLAIM        incident_impacts_supplier: pending -> live (evidence + reviewer)
QUERY        incident_impacted_suppliers -> [S-CN-DG-HARNESS]

PROCEDURE    hold_exposed_shipments v1: pending -> live (config + lock pinned)
DECISION     hold exposed shipments; success = zero exposed shipments released
RUN          bounded provider calls complete -> receipt RCP-run-...
OUTCOME      pinned query at check time -> satisfied -> receipt RCP-outcome-...

OBSERVATION  new evidence says the supplier was outside the incident boundary
ATTESTATION  contradict incident_impacts_supplier (claim remains live)
REVIEW       attestation upheld; separate adjudication rejects the claim
QUERY        incident_impacted_suppliers -> []

SNAPSHOT     exact config + lock + graph state + Procedure definitions captured

Cruxible 自身也遵循同样的边界：在状态固定经批准的审核结果之前，此仓库会拒绝推送到 main（了解规则如何运行）。

pip install cruxible — 快速入门 将带你从安装开始完成首次查询；下方的开始使用会运行已植入数据的演示世界，约需 3 分钟，无需调用模型或使用 API 密钥。

Crux 内部

开始使用

pip install cruxible

通过创作技能 和建模状态 构建自己的 Crux，或运行演示 — 一个预先填充数据的供应链世界，约需 3 分钟，无需调用模型或 API 密钥。沙盒写入会归属于内置的 operator 身份：

# shell 1 — local sandbox daemon
CRUXIBLE_SERVER_STATE_DIR="$HOME/.cruxible/sandbox" cruxible server start

# shell 2 — kit bundles are fetched from the release and digest-verified
# (agent-operation is the optional agent-ops layer; domain-only works too)
cruxible --server-url http://127.0.0.1:8100 init --kit agent-operation --kit supply-chain-blast-radius
cruxible context connect --server-url http://127.0.0.1:8100 --instance-id <instance-id>

# deterministic ingest: preview, then commit
cruxible run --workflow build_seed_state && cruxible apply --workflow build_seed_state --from-last-preview
cruxible run --workflow ingest_incidents && cruxible apply --workflow ingest_incidents --from-last-preview

# the incident feed can only PROPOSE impact edges; the judgment is yours, on the record
cruxible propose --workflow propose_incident_impacts_supplier
cruxible group list --status pending_review
cruxible group resolve --group <GRP-id> --action approve \
  --rationale "Confirmed against supplier geography" --expected-pending-version 1

# receipted answers through the edges you just admitted
cruxible query run open_incident_impacts --json
cruxible query run incident_impacted_suppliers --param incident_id=INC-TW-RAIL-2026-07 --json

Agent 加入后，身份验证便会启用：使用 CRUXIBLE_SERVER_AUTH=true 重启、认领引导凭据，并为每个 Agent 创建专属令牌 — 每次写入都会记录归属。详情、权限层级和安全加固，请参阅： 快速入门 · 运行时身份验证与 Agent 角色。

规则在运行

Cruxible 从不要求模型遵循规则，因为规则是以代码形式运行的。在配置中声明的规则会在每次变更时于写入关口执行，并且没有任何代码路径可以绕过该关口。

守卫朝内（实时状态的写入边界）；关卡朝外（在状态一致前，外部操作会被暂缓）。

gates:
  merge-review:
    kind: git-pre-push
    entity_type: ReviewRequest
    match_property: change_head
    condition: {status: approved}
    adapter: {branch_pattern: refs/heads/main}

本仓库由该关卡保护：在状态中的审查记录得到更正之前，它拒绝了我们自己的 0.2.2 版本推送。我们修正了状态，而不是钩子。

完整演练

深入解析将端到端构建一个受治理的事实：单个经过审查的判断，就能让查询遍历递归物料清单，并沿着下游 5 个类型化节点，列出所有暴露的货物，还附带一份可用 explain 进行说明的回执。

截图展示了检视 UI中的审查界面：每条待议边都附带与之匹配的证据，并通过溯源栏追溯到工作流、回执和追踪信息。

Cruxible 的定位

Cruxible 不会取代源系统、文档或检索。这些层有助于 Agent 查找和解读证据。Cruxible 保存的是一组规模更小的承诺，系统的其余部分必须以一致的方式查询、强制执行或据此采取行动。

如果信息仅供阅读，就将其留在制品层或检索层。当跨会话的 Agent 必须依赖它作为当前信息、遍历其影响、强制执行它或据此采取行动时，就将这些知识编译为 Crux。

套件

套件是 Crux 的可复用模板：它将本体与其治理、查询、工作流和提供方打包为一个带版本、可组合的单元。每个套件的指南都会带你从头到尾完成操作。

文档

• 快速入门 — 从安装到首次查询
• 概念 — 架构和基本构件
• 深入介绍 — 从头到尾了解一个受治理的领域
• 建模状态 — 设计本体
• 配置参考 — YAML 配置架构
• CLI 参考 · MCP 工具 · AI Agent 指南
• 套件指南 — KEV、供应链、判例法、Agent 运行；另有部署、身份验证、备份和发布指南，均位于 docs/ 下；还有用于根据数据编写状态的 Agent 技能

技术

Cruxible 使用 Pydantic 进行验证，使用 NetworkX 进行内存图操作，使用 Polars 进行数据操作，使用 SQLite 存储本地持久状态，使用 FastAPI 构建守护进程， 并使用 FastMCP 提供 MCP 工具。

贡献

欢迎贡献 — 请参阅 CONTRIBUTING.md。 如果你正在解决 Agent 受治理状态方面的问题，欢迎为仓库点星或 提交 issue，介绍你的使用场景。

许可证

Apache 2.0