# https://github.com/safal207/Causal-Memory-Layer 项目说明书

生成时间：2026-06-18 11:56:33 UTC

## 目录

- [Overview & Core Concepts](#page-1)
- [SDK Architecture & API Surface](#page-2)
- [Integrations, Examples & Use Cases](#page-3)
- [vCML Reference Implementation & Research](#page-4)

<a id='page-1'></a>

## Overview & Core Concepts

### 相关页面

相关主题：[SDK Architecture & API Surface](#page-2), [vCML Reference Implementation & Research](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md)
- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [cml/experimental/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/experimental/__init__.py)
- [cml/report.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
- [READY_FOR_REVIEW.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/READY_FOR_REVIEW.md)
- [api/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/api/__init__.py)
- [scripts/run_safety_eval.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_safety_eval.py)
</details>

# Overview & Core Concepts

## 项目定位与核心问题

**Causal Memory Layer（CML）** 是一个面向结构化动作追踪（structured action traces）的开源因果审计层（causal audit layer），专注于验证某个动作是否具有"有效的因果授权 / 因果许可"（causal permission / responsibility）。项目以"因果有效性检查"（causal-validity checking）作为唯一聚焦的原语，文档明确指出 CML 并非要解决所有的 AI 安全、安全性或合规问题，而是对"功能性正确但因果无效"这一类隐蔽缺陷提供可检视的能力。资料来源：[README.md:1-40]()

```mermaid
flowchart LR
    A[结构化动作追踪<br/>Structured Action Trace] --> B[CML 引擎<br/>记录 / CTAG / 链 / 审计]
    B --> C[因果链重构]
    B --> D[审计结论与 Finding]
    D --> E[Markdown / JSON 报告]
    D --> F[API / CLI 暴露面]
    C --> G[责任链可追溯性]
    D --> G
```

CML 关注的核心问题是：当一个智能体（agent）行为在表面上看起来正常执行（功能层 OK）时，其"授权—批准—责任"因果链是否仍然完整？CML 把这个区分变成可审计、可检查的报告输出。资料来源：[README.md:13-26]()

## 范围与非目标（Non-Claims）

CML 的设计哲学强调清晰的边界划定。其显式声明的"非目标"包括：不解决通用 AI 安全；不替代 OS 级安全策略；不充当合规结论的最终判定者。完整的 scope 边界被维护在独立文档中，便于审阅者与资助方快速对照。资料来源：[README.md:31-40]()

研发方向被定位为：面向"智能体监督（agentic oversight）"的因果有效性检查。一种实用的框架表述是：

> "如何检测那些表面有效、但因授权、批准或责任链路缺失、模糊或断裂而因果无效的动作？"

资料来源：[README.md:42-50]()

## 核心架构与组件

CML 的核心 Python 包名为 `cml`，从 [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py) 暴露的子模块与公共 API 如下：

| 子模块 | 主要导出 | 角色 |
|---|---|---|
| `cml.record` | `CausalRecord`、`Actor`、`Action`、`load_jsonl`、`records_to_index` | 数据模型与日志加载 |
| `cml.ctag` | `DOM`、`CLASS`、`CTAGState`、`compute_ctag`、`decode_ctag`、`compute_lhint` | 16 位因果标签计算与解码 |
| `cml.chain` | `reconstruct_chain`、`has_path`、`find_root`、`group_by_pid` | 链重构与路径查询 |
| `cml.audit` | `AuditEngine`、`AuditConfig`、`AuditResult`、`Finding`、`Severity`、`CustomRule` | 审计引擎（R1–R4） |
| `cml.report` | `to_markdown`、`to_json`、`to_text` | 报告生成 |

资料来源：[cml/__init__.py:1-60]()

报告层支持人类可读的 Markdown、机器可读的 JSON 以及紧凑的文本视图。报告生成时会附带生成时间、被审计日志路径，并按 `Severity` 维度（`OK` / `WARN` / `FAIL`）聚合统计指标。资料来源：[cml/report.py:1-30]()

实验性研究助手被单独隔离在 `cml.experimental` 包中，文档明确指出该包为"非规范性"，API 可能在研究概念尚未成熟为稳定 CML 语义前发生变动。资料来源：[cml/experimental/__init__.py:1-5]()

CML 同时提供 `api/` 子包承载基于 FastAPI 的本地 HTTP 接口（健康检查、审计、CTAG 解码等），以及 `cli/main.py` 形式的命令行入口，形成"SDK + API + CLI"三套一致的暴露面。资料来源：[api/__init__.py:1-1]()、[README.md:9-12]()

## 关键概念：因果记录、CTAG 与审计

### 因果记录（vCML Causal Record）

`vCML` 草案 v0 规定了因果记录的最小语义结构，强调 append-only、不可变、语言/传输/存储均无关，并要求"记忆的是权限与责任，而非执行结果"。核心字段包括：`id`、`timestamp`、`actor`、`action`、`object`、`permitted_by`（语义引用）、`parent_cause`（使本动作得以发生的因果记录标识，可被用于链重构）。资料来源：[vcml/FORMAT.md:9-90]()

一个重要的语义约定是：当 `parent_cause` 为 `null` 但原因并非"根事件"而是"因果断裂"时，`permitted_by` 应当取 `"unobserved_parent"`；显式根事件（如系统启动、init、break-glass）则允许 `parent_cause` 为 `null`。资料来源：[vcml/FORMAT.md:70-86]()

### CTAG（16-bit 因果标签）

CTAG 是 CML 提供的轻量级硬件友好型标签，可将域（DOM）、类别（CLASS）、代数（GEN）等信息压缩到 16 位中，从而支撑缓存行标签、DRAM 元数据、嵌入式 MCU 等受限环境的"零拷贝 / 近零开销"因果记忆。资料来源：[vcml/hardware/CTAG-8-16.md:5-20]()

### 审计与安全评估

审计引擎的核心 API 是 `AuditEngine().run(records)`，返回包含 `findings` 与 `passed()` 状态的 `AuditResult`。项目还配套提供 `scripts/run_safety_eval.py` 以运行确定性安全评估基准（safety-eval benchmark），并可将快照输出为 Markdown。资料来源：[scripts/run_safety_eval.py:1-25]()

## 社区关注与版本脉络

社区近期高度关注的方向包括：本地 API 的冒烟测试覆盖（健康检查、审计、CTAG 解码）、审计 Finding 代码到自然语言释义的"术语表"建设，以及"签名因果回执（signed causal receipts）+ 时序来源"的研究扩展——后者主张 CML 验证因果、签名回执补足作者证明，二者构成互补关系。资料来源：[issue #47](https://github.com/safal207/Causal-Memory-Layer/issues/47)、[issue #65/66](https://github.com/safal207/Causal-Memory-Layer/issues/65)、[issue #139](https://github.com/safal207/Causal-Memory-Layer/issues/139)

版本里程碑方面：v0.1 划定概念与非目标；v0.4.0 作为首个生产 PyPI 发布候选；v0.4.1 新增"审批链路（Approval Lineage）"可运行演示；v0.5.1 引入只读的审计语义（vCML），新增"因果缺口"检测与 `SECRET → NET_OUT` 校验，但**不做强制执行**——只解释语义层面含义。资料来源：[v0.1 Foundation](https://github.com/safal207/Causal-Memory-Layer/releases/tag/v0.1.0-foundation)、[v0.4.0](https://github.com/safal207/Causal-Memory-Layer/releases/tag/v0.4.0)、[v0.4.1](https://github.com/safal207/Causal-Memory-Layer/releases/tag/v0.4.1)、[v0.5.1](https://github.com/safal207/Causal-Memory-Layer/releases/tag/v0.5.1-audit-semantics)

## See Also

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md)
- [docs/NON_CLAIMS.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/NON_CLAIMS.md)

---

<a id='page-2'></a>

## SDK Architecture & API Surface

### 相关页面

相关主题：[Overview & Core Concepts](#page-1), [Integrations, Examples & Use Cases](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [cml/report.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py)
- [cml/experimental/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/experimental/__init__.py)
- [api/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/api/__init__.py)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [vcml/hardware/CTAG-8-16.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/hardware/CTAG-8-16.md)
- [scripts/run_safety_eval.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_safety_eval.py)
- [scripts/run_mcp_demo_payloads.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_mcp_demo_payloads.py)
- [examples/crewai_signed_receipt_sidecar.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/crewai_signed_receipt_sidecar.py)
- [integrations/vscode-cml/package.json](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/package.json)
- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
- [LICENSE_COMMERCIAL.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/LICENSE_COMMERCIAL.md)
- [PRICING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/PRICING.md)
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md)
</details>

# SDK 架构与 API 接口

## 1. 目的与范围

Causal Memory Layer（CML）是一个**因果审计层**，用于判断结构化动作轨迹中的因果许可与因果链完整性。"SDK 架构与 API 接口"一词涵盖仓库中**对开发者公开、可直接调用或扩展**的代码与协议面，包括 Python 包 `cml` 的公共符号、报告生成器、CLI 入口、REST API / MCP / 编辑器等集成壳层，以及 vCML 记录格式与 CTAG 计算库（[README.md:7-43]）。

仓库同时承载三类内容：工作制品（Python 引擎、CLI、API、示例、测试）、规范层（`vcml/FORMAT.md`）和研究层（`cml/experimental`）。SDK 表面只承诺**稳定且已实现的语义**，研究性子包显式标注为 non-normative（[cml/experimental/__init__.py:1-5]）。

## 2. Python SDK 总体架构

`cml/__init__.py` 是 SDK 公共入口。它通过 `importlib.metadata` 解析已安装的 `causal-memory-layer` 包版本，在未安装时回退到 `0.0.0+unknown` 字符串；随后将 `record`、`ctag`、`chain`、`audit`、`report` 五个子模块的符号集中 re-export（[cml/__init__.py:11-30]）。调用者只需 `from cml import ...` 即可。

```mermaid
flowchart LR
    A[JSONL 记录] --> R[record.load_jsonl]
    R --> I[records_to_index]
    I --> CH[chain.reconstruct_chain]
    I --> AU[audit.AuditEngine]
    AU --> RES[AuditResult]
    RES --> RP[report.to_markdown / to_json / to_text]
    CT[ctag.compute_ctag / decode_ctag] --> I
```

上图展示了 SDK 的**单向数据流**：原始 JSONL 记录经 `record` 解析为索引；`chain` 与 `audit` 并列消费索引；`audit` 输出 `AuditResult`；`report` 把结果序列化为 Markdown / JSON / 文本。`ctag` 在解析阶段为记录补充 16 位因果标签，但本身不参与最终审计裁决。

## 3. 公共 API 表面

下表汇总 `cml/__init__.py` 中 re-export 的核心符号及其语义角色，作为"SDK 对外契约"的总览。

| 类别 | 符号 | 来源模块 | 作用 |
|------|------|----------|------|
| 记录 | `CausalRecord`、`Actor`、`Action`、`load_jsonl`、`records_to_index` | `cml/record` | 解析与索引 JSONL 记录 |
| 标签 | `DOM`、`CLASS`、`CTAGState`、`compute_ctag`、`decode_ctag`、`compute_lhint` | `cml/ctag` | 16 位 CTAG 计算、解码与线索 |
| 链 | `reconstruct_chain`、`has_path`、`find_root`、`group_by_pid` | `cml/chain` | 父-子因果链查询 |
| 审计 | `AuditEngine`、`AuditConfig`、`AuditResult`、`Finding`、`Severity`、`CustomRule` | `cml/audit` | R1–R4 审计规则执行 |
| 报告 | `to_markdown`、`to_json`、`to_text` | `cml/report` | 人类/机器可读输出 |

快速开始示例（取自 `cml/__init__.py` 顶部 docstring）：

```python
from cml import load_jsonl, AuditEngine, AuditConfig

records = load_jsonl("causal.jsonl")
engine  = AuditEngine()
result  = engine.run(records)
print(result.passed(), result.findings)
```

## 4. 报告、CLI 与集成工具链

`cml/report.py` 把 `AuditResult` 序列化为 Markdown、JSON 与纯文本三种形态，Markdown 标题默认为 `vCML Audit Report`；严重程度使用 emoji 渲染：`OK → ✅`、`WARN → ⚠️`、`FAIL → 🔴`（[cml/report.py:1-40]）。`to_markdown` 在未提供 `log_path` 与 `index` 时会跳过对应行，调用者应自行决定是否补齐上下文。

CLI 与脚本入口方面，仓库提供两条与 SDK 直接衔接的命令：

- `scripts/run_safety_eval.py` 调用 `cml.safety_eval.run_safety_eval` 运行确定性安全评估基准，可选输出 Markdown 快照（[scripts/run_safety_eval.py:1-40]）；
- `scripts/run_mcp_demo_payloads.py` 通过 `cml.integrations.mcp.core` 演示 MCP 健康检查、审计追踪与 Cause Band 评估三类工具的载荷（[scripts/run_mcp_demo_payloads.py:1-40]）。

`examples/crewai_signed_receipt_sidecar.py` 演示如何把"签名收据"作为**侧车**叠加在 CrewAI 风格因果轨迹之上；该示例显式声明它**不是**生产级加密签名、不做钱包身份管理、也不构成第三方安全认证，仅用于演示 deterministic hash 与 tamper detection（[examples/crewai_signed_receipt_sidecar.py:1-30]）。这与社区关于"signed causal receipts with temporal provenance"的研究方向一致（issue #139），但 SDK 自身并不强制启用收据。

编辑器集成方面，`integrations/vscode-cml/package.json` 注册了三条命令——`cml.auditCurrentLog`、`cml.showChainForSelectedRecord`、`cml.auditExampleLog`——其真值来源仍是本地 CML Python CLI（[integrations/vscode-cml/package.json:1-50]）。

## 5. 已知边界与失败模式

- `cml/experimental/` 子包 API 可能在研究语义稳定前变动（[cml/experimental/__init__.py:1-5]）。
- 当前 REST API（`api/server.py`）的烟雾测试覆盖仍处社区提议阶段（issue #47），本地运行需自行验证 `/health`、`/audit`、`/ctag/decode` 行为。
- 商业组件（多租户、SIEM 连接器、PDF 合规报告）位于 `enterprise/` 与 Hosted API 之下，属 MIT 范围之外（[LICENSE_COMMERCIAL.md:1-80]、[PRICING.md:1-50]）。
- `vcml/hardware/CTAG-8-16.md` 中描述的 8 位紧凑 CTAG 是**草案**，与 16 位 CTAG 共享语义但位宽不同，调用方需明确告知下游使用哪个版本。
- 贡献者提交行为变更时须同步更新测试与文档，遵循 [CONTRIBUTING.md:1-15] 的清单要求。

## 另请参阅

- 审计规则与 R1–R4 语义
- CTAG 16 位标签与硬件映射（CTAG-8/16）
- vCML 记录格式规范
- MCP Agent 审计集成
- 签名收据（Signed Receipts）研究笔记
- Approval Lineage Demo（v0.4.1）

---

<a id='page-3'></a>

## Integrations, Examples & Use Cases

### 相关页面

相关主题：[Overview & Core Concepts](#page-1), [SDK Architecture & API Surface](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/crewai_style_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/crewai_style_causal_audit.py)
- [examples/agent_approval_lineage_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/agent_approval_lineage_audit.py)
- [examples/grok_xai_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/grok_xai_causal_audit.py)
- [examples/openai_claude_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/openai_claude_causal_audit.py)
- [examples/gemini_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/gemini_causal_audit.py)
- [examples/qwen_kimi_deepseek_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/qwen_kimi_deepseek_causal_audit.py)
- [examples/crewai_signed_receipt_sidecar.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/crewai_signed_receipt_sidecar.py)
- [docs/integrations/LLM_PROVIDER_MATRIX.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/LLM_PROVIDER_MATRIX.md)
- [docs/integrations/CREWAI_STYLE_CAUSAL_AUDIT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/CREWAI_STYLE_CAUSAL_AUDIT.md)
- [docs/integrations/MCP_AGENT_AUDIT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/MCP_AGENT_AUDIT.md)
- [docs/integrations/CURSOR_MCP_QUICKSTART.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/CURSOR_MCP_QUICKSTART.md)
- [integrations/vscode-cml/package.json](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/package.json)
- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
</details>

# Integrations, Examples & Use Cases

## 概览：集成与示例在 CML 中的定位

CML（Causal Memory Layer）以一个最小化的"因果有效性"原语为核心，而其工程价值依赖完整的集成与示例生态。仓库中 `examples/`、`docs/integrations/`、`integrations/` 三个目录分别承担"可运行示例"、"供应商对接指南"、"编辑器/MCP 适配"三类职责，使 CML 能在不修改核心 schema 的前提下覆盖七种 LLM 工具调用协议，并在智能体协作、CI 流水线、本地开发等场景中落地。资料来源：[README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)

集成层明确遵循"SDK 独立（SDK-independent）的确定性映射"原则：示例不会真正调用模型或执行工具，只演示 provider 原生 ID（如 `call_id`、`tool_use_id`、`functionCall.id`、`tool_call_id`）到 CML `parent_cause` 与 `permitted_by` 字段的转换路径。资料来源：[ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)

## LLM 供应商集成矩阵

仓库提供针对七家供应商的端到端确定性示例与对应集成文档，统一在 `docs/integrations/LLM_PROVIDER_MATRIX.md` 矩阵中索引：OpenAI、Claude、Gemini、Grok/xAI、Qwen、Kimi、DeepSeek。资料来源：[README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)

每个供应商都有一份独立示例脚本：

- OpenAI / Claude：[examples/openai_claude_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/openai_claude_causal_audit.py)
- Gemini：[examples/gemini_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/gemini_causal_audit.py)
- Grok / xAI：[examples/grok_xai_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/grok_xai_causal_audit.py)
- Qwen / Kimi / DeepSeek：[examples/qwen_kimi_deepseek_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/qwen_kimi_deepseek_causal_audit.py)

```mermaid
flowchart LR
  subgraph Providers["LLM 工具调用协议"]
    OAI[OpenAI] -->|call_id| MAP
    CLA[Claude] -->|tool_use_id| MAP
    GEM[Gemini] -->|functionCall.id| MAP
    GRO[Grok/xAI] -->|tool_call_id| MAP
    QWE[Qwen] --> MAP
    KIM[Kimi] --> MAP
    DEE[DeepSeek] --> MAP
  end
  MAP["CML parent_cause / permitted_by 映射"] --> CORE((CML AuditEngine))
  CORE --> FIND["CML-AUDIT-R1..R4 结论"]
```

关键约束：provider 关联 ID 仅作为相关性元数据保留，CML 的因果授权完全由 `parent_cause` 与审批祖先链决定；Kimi 与 Gemini 的推理相关 state 仅以"安全 handling metadata / digest"形式保留，不发布原始推理内容。资料来源：[ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)

## 智能体审计与签名回执示例

`examples/crewai_style_causal_audit.py` 演示 CrewAI 风格的多智能体 trace 审计；`examples/agent_approval_lineage_audit.py` 对应 v0.4.1 "审批祖先链演示"，用于检测"操作上成功但缺乏上游审批祖先链"的代理行为。资料来源：[docs/integrations/CREWAI_STYLE_CAUSAL_AUDIT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/CREWAI_STYLE_CAUSAL_AUDIT.md)

在此基础上，`examples/crewai_signed_receipt_sidecar.py` 引入"签名回执 sidecar"研究扩展：使用 SHA-256 对每条记录生成确定性哈希并模拟篡改检测；文件开头明确声明"非生产级密码学签名、非钱包身份、非第三方安全认证"。资料来源：[examples/crewai_signed_receipt_sidecar.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/crewai_signed_receipt_sidecar.py)

社区中亦讨论"带时间来源的签名因果回执"作为 CML 因果有效性之外的下一研究方向（GitHub Issue #139），目标是为 CML 补齐"作者证明"维度；需要留意该方向曾在 CI 的 `Security Baseline` secret-scan 任务中触发失败（Issue #141），目前仍处研究阶段。

## 工具链与编辑器集成

- **VS Code**：[integrations/vscode-cml/package.json](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/package.json) 注册 `cml.auditCurrentLog`、`cml.showChainForSelectedRecord`、`cml.auditExampleLog` 三个命令，对 `.jsonl` 资源提供右键菜单分组 `cml`；要求 `engines.vscode ^1.85.0`，分类为 `["Other","Linters"]`，其真正的"事实来源"始终是本地 Python CLI。
- **MCP 代理审计**：[docs/integrations/MCP_AGENT_AUDIT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/MCP_AGENT_AUDIT.md) 描述 MCP server 与 `AuditEngine` 的对接方式。
- **Cursor 快速上手**：[docs/integrations/CURSOR_MCP_QUICKSTART.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/integrations/CURSOR_MCP_QUICKSTART.md) 提供在 Cursor 中启用 CML MCP 审计的步骤。
- **本地 API 冒烟测试**：[tests/test_api_smoke.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/tests/test_api_smoke.py) 覆盖 `GET /health`、`POST /audit`、CTAG 解码等接口（社区讨论见 Issue #47）。

Python SDK 主入口 [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py) 一次性导出 `AuditEngine`、`AuditConfig`、`AuditResult`、`Finding`、`Severity`、`CustomRule`、`reconstruct_chain`、`compute_ctag` 等 API，使所有示例脚本以一致方式消费同一套因果验证原语。

## 常见使用模式与限制

- **典型工作流**：先用 `load_jsonl` 读取 trace，再用 `AuditEngine().run(records)` 产出 `AuditResult`，最终通过 `to_markdown`/`to_json` 渲染报告。资料来源：[cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- **Scope 边界**：CML 不解决所有 AI 安全/合规问题，仅提供"结构化动作 trace 的因果有效性检查"，详见 [docs/NON_CLAIMS.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/NON_CLAIMS.md)。资料来源：[README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- **企业化路径**：商业授权、托管 API 与合规包仍处草案阶段，详见 [LICENSE_COMMERCIAL.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/LICENSE_COMMERCIAL.md) 与 [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)。

## 另请参阅

- vCML 记录格式：[vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- CTAG 16-bit 因果标签：[vcml/CTAG.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/CTAG.md)
- 审计结果术语表（社区需求）：GitHub Issues #65、#66
- 外部验证协议：[docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md)

---

<a id='page-4'></a>

## vCML Reference Implementation & Research

### 相关页面

相关主题：[Overview & Core Concepts](#page-1), [SDK Architecture & API Surface](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [vcml/audit.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/audit.md)
- [vcml/CTAG.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/CTAG.md)
- [vcml/multi_boundary.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/multi_boundary.md)
- [vcml/linux-ebpf/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/README.md)
- [vcml/linux-ebpf/exec_monitor.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/exec_monitor.py)
</details>

# vCML 参考实现与研究

## 概述与设计原则

vCML（virtual Causal Memory Layer）是 Causal Memory Layer 项目的**参考实现与研究路径**，用于探索如何把"因果有效性"这一原语嵌入到真实系统。vCML FORMAT v0 规定记录必须 append-only、immutable once written，并保持 language-agnostic、transport-agnostic 与 storage-agnostic——它只记录 *permission* 与 *responsibility*，不记录动作的成功或失败结果。这一边界也在 `README.md` 的"Bottom line"中得到呼应："一个系统在功能上正确，不等于在因果上有效"。

资料来源：[vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)、[README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)

## 最小因果记录

`CausalRecord` 的最小语义结构包含七个核心字段：

| 字段 | 含义 |
|------|------|
| `id` | 记录唯一标识，单调或基于 UUID |
| `timestamp` | 跨越边界的时间，纳秒级精度 |
| `actor` | 发起动作的实体（pid / uid / gid / comm） |
| `action` | 边界类型：`exec` / `open` / `read` / `write` / `connect` / `send` |
| `object` | 动作目标（路径 hash、网络地址、fd） |
| `permitted_by` | 权限、能力、策略或前置原因的语义引用 |
| `parent_cause` | 使本动作得以发生的因果记录 ID |

格式还预留了 `integrity` 占位字段，供未来加入 hash 或 signature。Python SDK 在 `cml/record.py` 中实现 `CausalRecord` 与 `Actor`（含 `to_dict` / `from_dict` 双向序列化），并在 `cml/__init__.py` 通过 `load_jsonl` 与 `records_to_index` 暴露给用户。

资料来源：[vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)、[cml/record.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/record.py)、[cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)

## Linux eBPF 参考路径

`vcml/linux-ebpf/` 提供第一条参考实现路径，目标是 Linux + eBPF。eBPF 能在不修改内核源码、不引入重型内核模块的前提下，对 syscall 边界做精准插桩。第一个目标边界被选定为 `exec`（进程执行），因其父-子关系清晰、因果链可见性高、歧义最小。

`exec_monitor.py` 的工作流为：① 通过 BCC 框架挂载 `sched:sched_process_exec` tracepoint；② 捕获 PID / PPID / filename；③ 在用户空间维护 `PID -> CausalID` 映射；④ 以 JSONL 输出带 `parent_cause` 的因果记录。若父进程未被该工具观测过，记录的 `parent_cause` 为空——这在 v0.5.1 的 read-only audit semantics 中是"causal gap"的预期信号，而非工具 bug。运行需 root、`python3-bpfcc` 及匹配运行内核的 kernel headers。

资料来源：[vcml/linux-ebpf/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/README.md)

## 硬件映射与 CTAG 研究

`vcml/hardware/CTAG-8-16.md`（v0.7）把 16 位 CTAG（Causal Tag）映射到硬件 metadata、pointer metadata 与 capability systems，使因果记忆在硅层成为 zero-copy、near-zero-overhead 的一等公民。在受限环境（cache line tag、DRAM metadata、嵌入式 MCU）中可使用 8 位紧凑 CTAG-8：位段 `b7..b5 = DOM`、`b4..b2 = CLASS`、`b1 = GEN 奇偶位`、`b0 = SEAL`，LHINT 字段被丢弃，完整 16 位 CTAG 由 memory-side metadata 携带或由上下文重建。软件侧由 `cml/ctag` 模块的 `compute_ctag` / `decode_ctag` / `compute_lhint` 实现并通过 `cml/__init__.py` 顶层导出。

资料来源：[vcml/hardware/CTAG-8-16.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/hardware/CTAG-8-16.md)、[cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)

## 审计与报告输出

审计管线在 `cml/report.py` 中提供 `to_markdown` / `to_json` / `to_text` 三种输出，Severity 用 ✅/⚠️/🔴 三档分别表示 OK / WARN / FAIL。审计对象 `AuditResult` 与 `Finding` 由 `cml/audit.py` 暴露的 `AuditEngine` 计算；规则集命名上沿用 R1–R4。`cml/__init__.py` 在顶层把 `AuditEngine`、`AuditConfig`、`CustomRule` 与三种报告器一并打包，使 SDK 用户无需关心内部模块切分。

资料来源：[cml/report.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py)、[cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)

## 路线图里程碑

- **v0.1 Foundation**：界定 scope、non-goals 与 invariants，无实现。
- **v0.2 vCML Skeleton**：交付 `vcml/README.md`、`vcml/FORMAT.md`、`vcml/linux-ebpf/README.md` 与空 reference 目录，只规定"形"与"义"，无执行代码。
- **v0.3 First Boundary (exec)**：交付可运行的 `exec_monitor.py`、causal record stream（JSONL）与有/无 `parent_cause` 的 demo。
- **v0.4 Causal Tags in Action (CTAG)**：交付 16-bit CTAG 规范（`vcml/CTAG.md`）与 `cml/ctag.py` 的完整实现，覆盖 DOM / CLASS / GEN。

资料来源：[ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)

## 常见限制与失败模式

- **eBPF 依赖**：未启用 `CONFIG_BPF_SYSCALL`、缺少匹配内核头或非 root 环境会让 `exec_monitor.py` 直接失败。
- **causal gap**：父进程未被观测时新进程的 `parent_cause` 为空，是设计上的"可观测缺口"，需在审计结果中明确标记。
- **CTAG-8 信息丢失**：LHINT 被丢弃后，部分语义需依赖 memory-side metadata 或上下文重建，单凭寄存器或缓存 tag 不足以完整还原。

资料来源：[vcml/linux-ebpf/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/README.md)、[vcml/hardware/CTAG-8-16.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/hardware/CTAG-8-16.md)

## 另请参阅

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md) — 项目总览与 quickstart
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md) — 最小因果记录规范
- [vcml/linux-ebpf/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/README.md) — eBPF 参考实现
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md) — 版本节奏与里程碑

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：safal207/Causal-Memory-Layer

摘要：发现 11 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Research: signed causal receipts with temporal provenance。

## 1. 安全/权限坑 · 来源证据：Research: signed causal receipts with temporal provenance

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Research: signed causal receipts with temporal provenance
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/139 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安全/权限坑 · 来源证据：good first issue: add a plain-language audit findings glossary

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：good first issue: add a plain-language audit findings glossary
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/66 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 配置坑 · 可能依赖账号登录

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 login/OAuth/account/sign in 等关键词。
- 对用户的影响：用户无法离线体验，账号权限和授权范围需要提前说明。
- 证据：packet_text.keyword_scan | https://github.com/safal207/Causal-Memory-Layer | matched login / oauth / account keyword

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/safal207/Causal-Memory-Layer | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/safal207/Causal-Memory-Layer | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/safal207/Causal-Memory-Layer | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/safal207/Causal-Memory-Layer | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：CI: Security Baseline secret-scan failed after signed receipts research note

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CI: Security Baseline secret-scan failed after signed receipts research note
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/141 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 安全/权限坑 · 来源证据：test: add API smoke tests for health, audit, and CTAG decode

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：test: add API smoke tests for health, audit, and CTAG decode
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/47 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/safal207/Causal-Memory-Layer | issue_or_pr_quality=unknown

## 11. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/safal207/Causal-Memory-Layer | release_recency=unknown

<!-- canonical_name: safal207/Causal-Memory-Layer; human_manual_source: deepwiki_human_wiki -->