内容
<p align="center">
<a href="https://cruxible.ai">
<img src="assets/cruxible_logo.png" alt="Cruxible" width="400">
</a>
</p>
# Cruxible 核心
[](https://pypi.org/project/cruxible-core/)
[](https://python.org)
[](LICENSE)
**Cruxible 是 AI 代理的持久状态。**
类型化、管控、持久状态，超越单一模型、会话或上下文窗口。
代理从提示、检索和聊天历史中重新推导出事实，而无论上下文工程如何改进，都无法保证重建的可靠性。更好的模型可以读取更好的内容，但无法证明其自身的输出。Cruxible 的答案是**建模领域而非工程化上下文**：持久的事实切片成为类型化的实体和关系，具有生命周期和审查状态，代理和人类在此基础上进行操作，而不是重建。
相同的工作适用于工作本身。读取是确定性的查询，而不是检索。重复过程被声明为工作流——预览、锁定、可重放——而不是代理循环粘合工具调用。模型仅在需要判断时被调用，其提议经过审查和验证，人工在环中参与其中，并在必要时留下记录。
核心是确定性的：没有 LLM，没有隐藏的 API 调用。它适用于任何代理或控制系统，而不是替换源系统，而是指向它们，引用特定的记录或块，并仅将值得协调的声明转化为状态。
## 入门指南
对于 `0.2`，从克隆中安装，以便捆绑的启动套件从 checkout 中解析（版本化的 OCI 套件镜像即将推出；在此之前，checkout 是规范路径）：
```bash
git clone https://github.com/cruxible-ai/cruxible-core.git
cd cruxible-core
uv sync --extra server --extra mcp
source .venv/bin/activate
CRUXIBLE_SERVER_STATE_DIR="$HOME/.cruxible/server" cruxible server start
```
守护进程默认仅限本地访问，并绑定到 `127.0.0.1:8100`。从套件中初始化实例并运行您的第一个查询：
```bash
cruxible --server-url http://127.0.0.1:8100 init --kit agent-operation
cruxible --server-url http://127.0.0.1:8100 --instance-id <instance_id> \
query run actor_work_queue --param actor_id=alice --json
```
返回的 `instance_id` 是每个表面（CLI、MCP 工具、HTTP 客户端、UI）从此以后使用的句柄。相同的查询表面可从 Python 访问：
```python
from cruxible_client import CruxibleClient
with CruxibleClient(base_url="http://127.0.0.1:8100") as client:
result = client.query(
"<instance_id>",
"actor_work_queue",
{"actor_id": "alice"},
)
for item in result.items:
print(item)
```
有关身份验证、强化和守护进程操作，请参阅 [快速入门](docs/quickstart.md) 和 [运行时身份验证和代理角色](docs/runtime-auth-and-agent-roles.md)。
## 受管控的领域是什么样子
一个最小的供应链本体切片，如在套件配置中编写的那样：
```yaml
entity_types:
Supplier:
properties:
supplier_id: { type: string, primary_key: true }
name: { type: string, indexed: true }
primary_geography: { type: string, optional: true }
Component:
properties:
component_id: { type: string, primary_key: true }
name: { type: string, indexed: true }
criticality: { type: string, optional: true, enum_ref: criticality }
Incident:
properties:
incident_id: { type: string, primary_key: true }
title: { type: string, indexed: true }
severity: { type: string, optional: true, enum_ref: incident_severity }
relationships:
- name: supplier_supplies_component
from: Supplier
to: Component
# 受管控的判断：事件实质上影响供应商。
- name: incident_impacts_supplier
from: Incident
to: Supplier
named_queries:
# 爆炸半径：从事件出发，遍历受影响的供应商到他们提供的组件。
components_exposed_by_incident:
mode: traversal
entry_point: Incident
returns: Component
traversal:
- relationship: incident_impacts_supplier
direction: outgoing
- relationship: supplier_supplies_component
direction: outgoing
```
本体只是配置的一部分：同一个文件声明了守卫、提案路由、工作流和提供者，以便领域的模型、规则和程序作为一个版本化的、可组合的套件一起交付。
代理（或应用程序）现在可以询问事件的爆炸半径（通过其受影响的供应商暴露的组件），而无需手动扫描电子表格或追踪物料清单：
```bash
cruxible query run components_exposed_by_incident \
--param incident_id=INC-42 \
--json
```
结果返回带有收据：从查询参数到遍历的边到返回的行确定性路径。
```json
{
"items": [
{ "entity_type": "Component", "entity_id": "component-main-board" }
],
"receipt_id": "RCP-...",
"receipt": {
"operation_type": "query",
"query_name": "components_exposed_by_incident",
"parameters": { "incident_id": "INC-42" },
"nodes": [
{ "node_type": "query", "detail": { "entry_point": "Incident" } },
{ "node_type": "edge_traversal", "relationship": "incident_impacts_supplier" },
{ "node_type": "edge_traversal", "relationship": "supplier_supplies_component" },
{ "node_type": "result", "entity_type": "Component", "entity_id": "component-main-board" }
]
}
}
```
收据不是日志——它们是类型化的证据图。突变收据记录了确切的更改内容，而受管控的边携带一个引用回创建它们的运算的收据。
## 管控
Cruxible 将状态写入与接受状态分开。状态通过两种方式进入：
| 写入模式 | 用途 | 会发生什么 |
|---|---|---|
| **直接写入** | 断言硬状态——导入、确定性关系、源证据 | 立即生效，可查询，带有证据时，但直到受管控流程批准前未审查 |
| **受管控的提案** | 判断调用——不确定或解释性关系 | 候选者分组在一个论点下，带有信号证据，并路由到人类或自动解决策略；批准的写入接受状态，带有出处，拒绝记录原因 |
守卫在配置中声明，并在单个写入检查点强制执行。关系类型可以完全拒绝直接写入；工作项可以被阻止，直到链接批准的审查；写入可以需要共同创建链接的实体在同一个工作单元中；声明可以需要携带源证据。证据要求被强制执行，而不是装饰性的——如果每个引用都不能解析为注册的源块，其内容哈希匹配，则写入将被拒绝。
## 工作流和固定的提供者
工作流将读取、提供者、整形和写入作为一个声明的、可重放的过程。提供者是工作流调用的构建块——确定性转换和数据加载器，以 Python、HTTP 或命令的形式存在。它们是固定的，而不是受信任的。套件锁定文件 (`cruxible.lock.yaml`) 记录每个提供者的版本、内容摘要和声明的副作用，并且每个调用都会留下执行跟踪，以便运行可重放。
规范的工作流是**先预览**：
```bash
cruxible run --workflow build_local_state # 执行克隆，返回应用摘要
cruxible apply --workflow build_local_state --from-last-preview
```
`run` 永远不会触及实时状态。`apply` 在提交之前重新验证预览的摘要与当前配置、锁定文件和头部快照。如果任何内容在下面发生变化，它将被拒绝。生成受管控提案的工作流通过 `cruxible propose` 运行，并进入审查而不是实时状态。
声明 → 预览 → 应用，每个步骤都有收据。
## 为什么不是 Markdown、RAG 或向量内存？
Markdown、检索和向量内存给模型提供了文本来读取，因此每个会话都会从头开始重建事实。Cruxible 将其持久化为类型化的、受管控的状态——读取，而不是重建。有什么变化：
| Markdown · RAG · 向量内存 | Cruxible |
|---|---|
| 声明只是文本——没有源，没有审查状态 | 声明带有出处和审查状态；证据门控写入拒绝无法解析为内容哈希验证的源块的引用 |
| 任何内容都可以编辑；没有任何内容强制执行可能更改的内容 | 写入通过类型化验证、守卫、审查和生命周期规则 |
| 检索返回类似的块；它无法遵循确切的链接 | 跨类型关系的多次遍历，带有在每个跳跃处应用的可见性规则 |
| 计数和汇总是近似的摘要 | 确切的、可重复的计数和连接作为确定性的工作流步骤 |
| 每次读取都是新鲜的，可能与上一次不一致 | 一个接受的状态——每个代理和应用程序的相同答案 |
| 更正只是更多的文本——没有任何内容将其与更正的声明联系起来 | 反馈和结果附加到特定的声明、决策或工作流结果作为类型化的、可查询的信号 |
| 静态文本不会因使用而改进 | 声明从提议到接受成熟；本体随着使用而迭代 |
| 更好的模型读取更好，但无法证明其自身的输出 | 保证来自模型外部的确定性层 |
Markdown 和检索仍然是大多数文本的合适工具（草稿、探索、一次性问题），而 Cruxible 本身引用 markdown 块作为源证据。表格是关于持久切片的：声明是重复的、共享的、容易出错的，而重新阅读文本每次都支付重建成本，并带有每次读取的风险。
## 领域状态和操作状态
Cruxible 建模两种状态，最强的是结合使用。
**领域状态** 是代理推理的持久模型——资产、漏洞、供应商、产品、案例、控件、策略、风险。它回答了什么是真实的、提议的、审查的或约束的。 *哪些资产暴露于已知的被利用漏洞？哪些供应商事件影响哪些产品和发货？*
**代理操作状态** 是工作本身的持久协调层——工作项、审查请求、决策、开放问题、风险、参与者、依赖关系、血统。它跟踪什么处于活动状态或被阻止、原因、谁审查了它以及发生了什么变化。
领域套件建模正在处理的对象；操作状态套件跟踪围绕它的工作、决策和审查。类型化的操作到领域边（或实例之间的 `SubjectRef`）将它们组合成一个可查询的图：
```mermaid
flowchart LR
subgraph KEV["KEV 领域状态"]
Asset["Asset: ASSET-42"]
Product["Product: Apache HTTP Server"]
CVE["Vulnerability: CVE-2021-41773"]
end
subgraph Ops["代理操作层"]
Owner["Actor: Agent A"]
Reviewer["Actor: human reviewer"]
Work["WorkItem: patch ASSET-42"]
Review["ReviewRequest: verify remediation"]
Decision["Decision: emergency patch window"]
Risk["Risk: exposed to active exploit"]
end
Asset -- "runs" --> Product
CVE -- "affects" --> Product
Work -- "targets" --> Asset
Work -- "mitigates" --> Risk
Risk -- "attaches to" --> CVE
Decision -- "constrains" --> Work
Work -- "owned by" --> Owner
Review -- "reviews" --> Work
Review -- "requested by" --> Owner
Review -- "assigned to" --> Reviewer
```
## 状态的复合
知识不应被上下文刷新、模型交换或交接所抹去。三个循环使状态随着使用而改进：
1. **反馈和结果。** 纠正、缺失的上下文和策略差距被记录为反馈；结果记录决策或工作流结果是否后来正确、不正确、部分或未知。重复的不良结果会在产生它们的路径上生成信任撤消建议。
2. **受管控的提案。** 不确定的关系被提议、审查和接受或拒绝，并带有出处；解析路径带有明确的信任状态。
3. **配置迭代。** 本体本身在被使用时被完善（新的实体类型、关系、守卫和查询），因此领域模型随着数据一起成熟。
模型可以更改：交换供应商、升级、同时运行多个。复合的内容属于您。状态、证据、审查历史、反馈、结果和本体本身累积在您拥有的数据库中，可以移植到单个文件，而不是供应商的权重或平台的内存中。代理所做的工作成为您的资产。
## 它如何适配
```text
AI 代理和人类
编写配置、审查提案、运行工作流、记录结果
|
v
CLI / HTTP 客户端 / MCP 工具
薄表面上的服务层
|
v
Cruxible 核心
确定性运行时，没有 LLM
|
v
state.db
图状态、收据、跟踪、组、反馈、结果、决策、
快照、源工件
```
## 套件
| 套件 | 类型 | 状态 | 它建模什么 |
|-----|------|--------|----------------|
| [agent-operation](kits/agent-operation/) | 代理操作状态 | 就绪 | 工作项、审查请求、决策、风险、开放问题、状态笔记、参与者、生命周期和依赖关系上下文。 |
| [kev-reference](kits/kev-reference/) | 领域参考状态 | 就绪 | 公共已知利用漏洞参考数据。 |
| [kev-triage](kits/kev-triage/) | 领域叠加状态 | 就绪 | 本地资产暴露、服务影响、控件、事件、发现、补救和受管控的漏洞三级评估。 |
| [supply-chain-blast-radius](kits/supply-chain-blast-radius/) | 领域状态 | 进行中 | 供应商、组件、组件、产品、发货和事件爆炸半径。 |
| [case-law-monitoring](kits/case-law-monitoring/) | 领域状态 | 进行中 | 以案件为中心的案例法律监测和权威影响。 |
独立的套件可以定义一个完整的模型。叠加套件可以扩展上游模型状态带有本地状态、受管控的提案和本地工作流。
**状态** - *就绪* 套件提供可用的提供者（KEV 还提供公共参考数据），因此其工作流端到端执行。*进行中* 表示本体、治理、命名查询和反馈/结果循环已完成并验证，但数据导入和评估提供者是占位符 - 实现它们或连接您自己的数据，然后运行工作流。
## 代理设置
对于代理，请使用分环境：
- `cruxible-core` 在守护进程/运行时环境中运行。
- 代理环境安装 `cruxible-client` 或使用 MCP。
- `CRUXIBLE_REQUIRE_SERVER=1` 将代理保留在守护进程路径上。
- `CRUXIBLE_SERVER_STATE_DIR` 位于代理的可写工作空间之外。
```bash
pip install cruxible-client
```
MCP 示例：
```json
{
"mcpServers": {
"cruxible": {
"command": "cruxible-mcp",
"env": {
"CRUXIBLE_MODE": "governed_write",
"CRUXIBLE_SERVER_URL": "http://127.0.0.1:8100"
}
}
}
```
本地权限模式是实用的强化层，而不是完整隔离。如果信任级别很重要，请将守护进程状态放在代理工作空间之外，并仅公开客户端、HTTP 或 MCP 表面。参见
[隔离部署](docs/isolated-deployment.md)。
## 文档
**开始使用**
- [快速入门](docs/quickstart.md) - 安装到第一个查询
- [概念](docs/concepts.md) - 架构和基元
**建模和创作**
- [建模状态](docs/modeling-state.md) - 设计本体（实体、关系、门控 vs 标志）
- [配置参考](docs/config-reference.md) - YAML 配置模式
- [套件作者](docs/kit-authoring.md) - 套件清单、结构和打包
- [套件演练](docs/kit-walkthroughs.md) - 构建独立和叠加套件
- [常见提供者和数据流步骤](docs/common-providers.md) - 提供者和工作流构建块
**参考**
- [CLI 参考](docs/cli-reference.md) - 终端命令
- [MCP 工具参考](docs/mcp-tools.md) - 代理工具表面
- [AI 代理指南](docs/for-ai-agents.md) - 协调模式
**操作和部署**
- [本地状态和备份](docs/local-state-and-backups.md) - SQLite、守护进程状态和可移植性
- [运行时身份验证和代理角色](docs/runtime-auth-and-agent-roles.md) - 凭证、权限层和启动
- [状态解析和维护](docs/state-resolution-and-maintenance.md) - 提案解析、信任分级和维护信号
- [隔离部署](docs/isolated-deployment.md) - 运行守护进程仅暴露客户端/MCP 表面
- [托管运行时镜像](docs/hosted-runtime-image.md) - 运行时容器镜像
**指南**
- [技能分类规模](docs/skill-classification-at-scale.md) - 一个受管控的分类代理演练手册
## 技术
**技术**
- [Pydantic](https://docs.pydantic.dev/) - 验证
- [NetworkX](https://https://networkx.org/) - 内存图操作
- [Polars](https://pola.rs/) - 数据操作
- [SQLite](https://sqlite.org/) - 本地持久状态
- [FastAPI](https://fastapi.tiangolo.com/) - 守护进程
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 工具
## 许可证
Apache 2.0
<!-- mcp-name: io.github.cruxible-ai/cruxible-core -->
