Horizon Fidelity Monitor

Horizon 保真度监控器

“质量不是模型的属性，而是对话的属性。”

Horizon 是一款面向 AI Agent 的实时对话健康监控器。它跟踪多轮对话的结构动态——语义漂移、信息增益、本体间隙宽度、时间不同步、昼夜节律认知负荷、对话速度和因果可达性；这些维度无法由大模型在对话内部可靠地呈现。

Horizon 提供两个测量平面。对话平面（上文所述，始终启用）逐轮测量对话健康状况。可选的任务平面 ——Memento Mori——测量相对于目标的日历时间流逝：时长、截止日期、停滞、各实体延迟，以及有限时间范围的占比。在配置存储之前，该平面不会运行。请参阅任务平面。

Horizon 不是操纵、谄媚或影响人的检测器——它测量的是对话的动态，而不是 Agent 是否在引导或奉承用户。请参阅 LEGAL.md §1。

为什么需要外部监控器？大模型的自我认知有限且不可靠：内省研究表明，大模型只能部分访问自身状态，这种能力很脆弱，在复杂或分布外任务中会退化（Binder 等，2024；arXiv:2512.12411）。因此，Horizon 不依赖模型报告自身的对话动态，而是通过廉价、确定、始终运行且完全不调用模型的算术方法，从外部对其进行测量。

为什么要构建它

多轮 AI Agent 会丧失准确性。ICLR 2026 杰出论文《LLMs Get Lost In Multi-Turn Conversation》（Laban、Hayashi、Zhou 和 Neville——Microsoft Research / Salesforce Research）报告称，多轮评估中的平均准确率下降了 39%——这是标准可观测性工具（LangSmith、RAGAS、DeepEval）无法发现的一种结构性特征，因为这些工具测量的是回复，而非对话。

Horizon 旨在弥补这一差距。它首先是一款可观测性工具：通过廉价、确定且不调用模型的算术方法，呈现回复级工具无法捕捉的对话动态。在四个受控的 A/B 场景中，Horizon 事件促成了重新锚定干预；我们测得综合质量提升 15.7%，且幻觉事件减少 87%——但这些只是采用手动调优控制器的合成脚本场景，并非生产环境结果。应将其视为有希望的内部证据，而非有保证的结果（请参阅验证和 LEGAL.md §5）。每个信号——信息增益、偏离度、估算本体间隙宽度、因果可达性——都是基于文本嵌入和时间戳计算的标准信息论或算术指标；完整定义请参阅四维时空信号。

• 阅读需求依据 → ICLR 2026 杰出论文（Laban 等）
• 阅读类别论证 → docs/content/naming-the-category-conversation-dynamics-monitoring.md
• 阅读工程论证 → docs/content/why-every-production-agent-needs-conversation-dynamics-monitoring.md

入门

三种方式——选择最适合你工作流的方式：

方式 1 — 托管式 MCP（最快，无需安装）

这是将 Horizon 添加到任意 Cursor、VS Code 或 Claude Desktop 工作区的最快方式。无需 Python。

申请 alpha 密钥 → 发起讨论，然后为你的客户端添加配置：

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "horizon": {
      "url": "https://horizon.leocelis.com/sse",
      "headers": { "Authorization": "Bearer YOUR_KEY_HERE" }
    }
  }
}

VS Code / GitHub Copilot（工作区中的 .vscode/mcp.json）：

{
  "servers": {
    "horizon": {
      "type": "http",
      "url": "https://horizon.leocelis.com/sse",
      "headers": { "Authorization": "Bearer YOUR_KEY_HERE" }
    }
  }
}

VS Code 说明： 使用 "servers"（而非 "mcpServers"）和 "type": "http"——VS Code 会先尝试 Streamable HTTP，失败后自动回退到 SSE，因此 "type": "http" 可与 /sse URL 配合使用。

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "horizon": {
      "url": "https://horizon.leocelis.com/sse",
      "headers": { "Authorization": "Bearer YOUR_KEY_HERE" }
    }
  }
}

就这样。重新加载 MCP 客户端后，会出现三个工具：new_conversation、process_turn、configure_session。

Alpha 访问权限： Horizon 的托管端点目前处于私人 alpha 阶段。密钥会发放给希望监控真实项目的 Agent 开发者。发起讨论申请密钥——请描述你的用例，我们会发送密钥。

方式 2 — 使用 pip 安装（库集成）

目前尚未发布到 PyPI——在发布之前，请使用下方的方式 3（从源代码安装）。

pip install horizon-monitor

验证安装（在 5 个规范场景上运行完整流程，约 25 秒）：

horizon-validate

方式 3 — 从源代码运行 MCP 服务

pip install 'horizon-monitor[mcp]'
horizon serve                             # stdio — for Cursor, Claude Desktop
horizon serve --transport sse --port 3847 # SSE — for web/team deployments

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "horizon": { "command": "horizon", "args": ["serve"] }
  }
}

完整的 Cursor 和 Claude Desktop 设置指南：docs/integrations/

监控内容

标准可观测性工具评估单条回复的质量。Horizon 评估的是对话质量——这是一个结构上截然不同的问题：

Horizon 不会取代单条回复质量评估工具或 LLM 评审工具。它的差异化之处在于测量方式：对每一轮进行确定性、零 LLM 调用的算术计算——几乎没有成本且始终运行；与之相对的是采样式 LLM 评审评估，后者按样本计费，通常离线或异步运行，而非实时运行。

快速入门

from horizon_monitor import FidelityMonitor
from datetime import datetime, timezone

monitor = FidelityMonitor()
session_id = monitor.new_conversation(metadata={"domain": "technical"})

result = monitor.process_turn(
    session_id,
    human_message="How does Python handle memory management?",
    agent_response="Python uses reference counting and a cyclic garbage collector...",
    timestamp=datetime.now(timezone.utc).isoformat(),
)

print(f"Fidelity:         {result.fidelity_score:.2f}")
print(f"Health:           {result.health_status}")
print(f"Circadian factor: {result.circadian_factor:.2f}")
print(f"Causal horizon:   {result.reachable_turns} reachable turns")
for event in result.events:
    print(f"  Event: {event.type} (confidence={event.confidence:.2f})")

框架集成

OpenAI SDK

from openai import OpenAI
from horizon_monitor import FidelityMonitor

monitor = FidelityMonitor()
session_id = monitor.new_conversation()
client = monitor.wrap(OpenAI(), session_id)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me about quantum computing."}]
)

traj = monitor.get_trajectory(session_id)
print(f"Fidelity: {traj.current_fidelity:.2f}  T*: {traj.estimated_t_star}")

monitor.wrap() 接受自定义时间戳和上下文提供程序，用于测试和回放。

Anthropic SDK

from anthropic import Anthropic
from horizon_monitor import FidelityMonitor

monitor = FidelityMonitor()
session_id = monitor.new_conversation()
client = monitor.wrap(Anthropic(), session_id)

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain RLHF."}]
)

LangChain

from langchain_openai import ChatOpenAI
from horizon_monitor import FidelityMonitor
from horizon_monitor.integrations.langchain import HorizonCallback

monitor = FidelityMonitor()
session_id = monitor.new_conversation()
callback = HorizonCallback(monitor, session_id)

llm = ChatOpenAI(callbacks=[callback])
llm.invoke("Explain the CAP theorem.")
print(f"Fidelity: {callback.last_result.fidelity_score:.2f}")

OpenAI Agents SDK

from agents import Agent, Runner
from horizon_monitor import FidelityMonitor

monitor = FidelityMonitor()
session_id = monitor.new_conversation()
agent = Agent(name="assistant", model="gpt-4o-mini", instructions="You are helpful.")

for user_message in conversation:
    result = Runner.run_sync(agent, user_message)
    monitor.process_turn(session_id, human_message=user_message,
        agent_response=result.final_output, timestamp=datetime.now(timezone.utc).isoformat())

4D 时空信号

此处的“时空”是一种隐喻，并非物理学概念。 相对论相关术语（闵可夫斯基间隔、光锥、 固有时间）只是设计灵感——它们影响了我们计算哪些量。下方每个信号都归结为文本嵌入和 时间戳上的标准信息论或算术度量，并列于通俗定义列中。Horizon 的行为或验证不依赖于 这一类比在字面上是否成立；洛伦兹 interval_class 仅作为描述性元数据输出——没有任何 事件或评分取决于它。

每次 process_turn() 都会返回一个 TurnResult，其中包含五类信号的 32 个字段：

核心（始终存在）

时间（需要 timestamp）

节奏（需要 timestamp + 轮次 ≥ 2）

时空（需要 timestamp + 轮次 ≥ 2）——仅描述性元数据

因果（需要 timestamp）

空间（需要 client_context）

16 种事件类型（对话平面）

所有事件默认处于观察模式（发出事件，不采取行动）。当事件在你的领域内达到 ≥ 0.7 的精确率/召回率后，通过 configure() 启用主动模式。

仅适用于 MCP 服务，且仅当其配置了 COMPLYEDGE_API_KEY 时：alert.compliance（始终处于主动模式）——ComplyEdge 根据某项 EU AI Act 规则标记了该轮的 human_message 或 agent_response；该事件会指出对应规则，确保下一条回复不会基于这些内容继续展开。 | signal.grounding_required | 启发式依据需求分数超过阈值——Agent 应谨慎表述或引用依据证据 | | signal.pace_premature_report | 用户回复速度快于先前标记的延迟操作在合理情况下可能完成的速度，且没有完成信号 |

任务平面（Memento Mori）

“进展不是轮次的属性——而是日历的属性。”

对话平面回答的是*这段对话是否正在恶化？*任务平面回答的是另一个问题：*这个目标是否仍在推进？它受什么时限约束？*一个月里，每次对话单独看来都很健康，却毫无进展；对于对话监控器来说，这就是一个月的完美健康状态。

名称即设计。每个存储区都恰好有一个根期限——一个由你选择的有限截止日期。其他一切都以此为基础，因此每个事项占用的每一天，都是一份肉眼可见、正在耗尽的预算。没有有限的根期限，推迟工作就没有代价，“以后再说”便永远免费。这个平面旨在让这种失效变得可见。

**默认关闭。**未配置存储区时，其七种工具不会注册，你的集成也不会有任何变化。

它能发现的问题

一项任务的截止日期是 7 月 20 日。现在已是 8 月 18 日，自 7 月 2 日以来没有人再推进这项任务。一项决定被搁置，理由是“等事情平静下来再说”，并设定了 8 月 10 日的复查日期，但这个日期已悄然过去。这项工作已经由一方持有三周。所有这些情况都不会显示在任何对话中、任何追踪器的状态栏中，也不会出现在模型的上下文窗口里——而每一段关于此事的对话，每一轮看起来都很健康。

任务平面会这样报告：任务已存在 78 天，距离上次进展已有 47 天，任务生命周期已过期，搁置已逾期 8 天，目前已由 operator 阻塞 21 天，且仍在持续。

词汇

根 horizon 下的树中，每个对象都是一个条目。共有八种类型：

输出中还会出现两个术语：驻留时段（sojourn）是某个阶段中记录的一次停留（进入 → 退出），而现行方式（incumbent）是你今天采用的工作方式，与对某种替代方案的试验相对。

快速入门

export HORIZON_MEMENTO_STORE_PATH=~/.horizon/missions.db   # the default: one local file

pip install "horizon-monitor[mysql]"
export HORIZON_MEMENTO_STORE_DSN='mysql://user:pass@host:3306/horizon'  # wins over _PATH
export HORIZON_MYSQL_SSL_CA=/path/to/server-ca.pem   # or ..._CA_B64 for a PEM in an env var

python scripts/ingest_artifacts.py --store ~/.horizon/missions.db \
    --repo /path/to/repo --item-id <mission-id>

python scripts/ingest_artifacts.py --store ~/.horizon/missions.db \
    --repo /path/to/repo --propose

from datetime import date, datetime, timezone

from horizon_monitor.memento import (
    EventKind, ItemKind, MementoConfig, MementoStore, evaluate,
)

store = MementoStore("missions.db")   # a real file; set this up once

root = store.register_item(
    kind=ItemKind.HORIZON, title="engagement horizon",
    created_valid=datetime(2026, 1, 1, tzinfo=timezone.utc),
    end_date=date(2030, 1, 1),
)
mission = store.register_item(
    kind=ItemKind.MISSION, title="ship-the-thing", parent_id=root,
    stall_days=14,                    # silence longer than this is a stall
    created_valid=datetime(2026, 6, 1, tzinfo=timezone.utc),
)
store.record_event(                   # progress: a side-effect of the work
    item_id=mission, kind=EventKind.PROGRESS,
    valid_time=datetime(2026, 7, 2, tzinfo=timezone.utc),
)

# The evaluation instant is always a parameter — the engine never reads a clock,
# so the same store at the same instant always yields the same report.
report = evaluate(
    store.snapshot(), datetime(2026, 8, 18, 12, tzinfo=timezone.utc), MementoConfig()
)

row = next(r for r in report.items if r.item_id == mission)
print(f"age:             {row.age_days} days")            # 78 days
print(f"since progress:  {row.days_since_progress} days") # 47 days
print(f"recording path:  {row.recording_path}")           # no recent work
print(f"horizon share:   {row.horizon_share:.4f}")        # 0.0595

该存储区是一个真实数据库，因此只需运行一次初始化设置——按设计，注册第二个根节点会引发 DuplicateRootError，这是单一有限根节点保证正常生效，并非错误。要了解完整示例——任务过期、暂存项逾期、阻塞实体、写入被拒绝以及信号触发——请运行 examples/memento_mori_mission_clock.py（无需参数、网络或 API 密钥；每次运行都会使用一个全新的临时存储区）。

衡量内容

12 种信号类型（任务平面）

与对话平面的 16 种事件类型分开，且不是其扩展。每种信号都只会在状态边缘触发一次——也就是其判定条件变为真时；条件持续期间绝不重复触发，并且每轮至多触发一个新信号，因此糟糕的一周也不会让你收到大量通知。等级决定这一上限的顺序：P1 表示时间紧迫，P2 表示结构性事项，P3 表示信息性事项。

这些信号沿用现有的 process_turn 会话契约，适用于通过 associate_mission 绑定的会话。每个事件都带有 plane: "mission"，而且该契约刻意设计得醒目——任务信号会连同数值一并展示给操作者，不像对话信号那样静默生效。请参阅Agent 规则，了解要粘贴到宿主中的代码块。

它拒绝做什么

只做核算，绝不估算。引擎绝不凭空编造时长、日期或金额：

• 不做预测、不预测完成时间，也不计算反事实的“另一条路径会花费多少”
• 不做 NPV/IRR/DCF，不使用贴现率，不进行货币换算——金额只会与测得的时间相乘
• 不对路径延迟进行 p 值、置信区间或序贯检验：在单个操作者的样本量下，任何优势主张都经不起审计，因此比较仅作描述
• 不做人员分析——实体延迟按功能岗位报告；测量某人的等待时间，但绝不将其转化为评分、排名或可解析的身份标识
• 缺少输入时，结果会直接省略并附上说明字段，绝不会用替代值填补

每一行都带有 derivation 字符串，逐项说明其计算过程；任何汇总统计还会附带其汇总的 n。相同的数据存储和相同的评估时刻会生成字节完全相同的报告。

文档：产品需求 · 技术规范 · Agent 规则 · 验收测试计划

配置

# Per-session override
monitor.configure(
    session_id=session_id,
    clarification_threshold=0.25,           # tighter D_JS gate
    event_modes={"alert.drift": "active"},  # activate one event
)

# Compound weight override
monitor.configure(
    fidelity_weights={"alpha": 0.35, "lambda_r": 0.12, "lambda_i": 0.28, "beta": 0.25},
    temporal_weights={"gamma": 0.08, "delta": 0.04},
    spacetime_coefficients={"alpha": 1.0, "beta": 1.0, "gamma": 0.8, "delta_st": 0.5},
)

导出

# JSON
result = monitor.export_to(session_id, target="json")

# LangSmith / Langfuse / OpenTelemetry / Arize
result = monitor.export_to(session_id, target="langsmith",
    connection={"api_key": "ls__..."})

尚未发布到 PyPI——暂时请参阅 路径 3，从源代码安装。

pip install horizon-monitor[langsmith]   # or langfuse, otel, arize

架构

Input: plain strings (human_message, agent_response, optional timestamp, optional client_context)

Core pipeline (< 50ms on CPU):
  1. Embed both turns (local sentence-transformers, lazy-loaded)
  2–6.  IGT · D_JS · TWR · Bipredictability · Epsilon
  7. Temporal signals  — gap, retention, circadian, deictic
  8. Fidelity dynamics — composite score
  9. Health classification
 10. Pace signals       — velocity, acceleration
 11. Spacetime interval — ds² and interval class
 12. Causal reachability — light-cone membership
 13. Spatial signals    — device, location, frame shift
 14. Mode detection     — auto-classify conversation type
 15. Event evaluation   — 16 threshold checks
 16. Optional: SQLite persistence

Output: TurnResult dataclass (32 fields)

设计约束（由测试强制执行）：

• 不调用大模型——仅执行纯算术运算并使用本地嵌入
• 默认不进行外部网络调用——完全本地运行
• 核心代码不依赖任何传递引入的框架
• CPU 上的核心流水线耗时 < 50ms——软性目标（CI 会标记超过 50ms 的回归，并在 150ms 时硬性失败）
• 100 轮对话的内存占用 < 100MB——按所声明的数值硬性执行
• 默认观察所有事件——除非明确配置，否则绝不干预

验证

哪些结论已得到证实，哪些尚未证实。 Horizon 的信号是域内相关性测量，与人工质量评分高度吻合。它们属于可观测性，而非经过验证的结果保证。以下是各项结论的真实状态：

以下四项门槛在一个带标签的 5,602 条记录语料库上均已通过（未随项目捆绑——参见证据包；scripts/build_validation_corpus.py 会重新生成用于验证门槛逻辑的合成语料库，而非这些确切数值）：

跨嵌入稳定性：在三个句子转换器后端（22M / 33M / 110M 参数）上，ρ_conv 差值为 0.026，ρ_turn 差值为 0.018。忠实度信号存在于对话结构中，而非嵌入流形中。（注意：同一语料库上的跨嵌入稳定性与跨语料库 OOD 不同——在 MT-Bench 成对标签上的首次第三方测试得到 ρ = 0.039；参见证据包 §Fix 4。）

修复缺口来源：DESIGN_FIXES_redteam_remediation.md

完整证据包：docs/reviews/V0_2_0_EVIDENCE.md

部署

自托管 Docker（端口 3847 上的 MCP 服务）

cd deploy/docker
docker compose up

Horizon 通过 SSE 提供 MCP API。将 .cursor/mcp.json 指向 http://localhost:3847/sse。Dockerfile 会在构建时预缓存 all-MiniLM-L6-v2 权重——冷启动耗时为零。

托管服务（DigitalOcean App Platform）

官方托管端点已上线：https://horizon.leocelis.com。它运行在 DigitalOcean App Platform 上（单个实例，进程内会话状态——重启后会话不会保留），并且需要 Bearer token；请求会按密钥限流并隔离。请参阅上文的路径 1。

开发

git clone https://github.com/leocelis/horizon.git
cd horizon
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt

pytest tests/ -v                         # full suite
pytest tests/unit tests/integration tests/e2e -v   # fast path (~6 min)
ruff check src/ tests/
black --check src/ tests/
./scripts/compliance/check.sh              # EU AI Act offline gate

ComplyEdge TrustLint — EU AI Act

Horizon 在面向 LLM 的制品上集成 ComplyEdge TrustLint，采用与 IVD 相同的离线 + 运行时 + 信任模式。

集成指南：docs/integrations/COMPLYEDGE.md。公开的 CE 嵌入文档：信任徽章。

仓库布局

horizon/
├── src/horizon/         # package source (PEP 517/518 src/ layout)
│   ├── engines/         # IGT, D_JS, TWR, coherence, fidelity, epsilon, mode
│   ├── spacetime/       # temporal, circadian, deictic, velocity, interval, light cone, spatial
│   ├── events/          # 16-event evaluator
│   ├── integrations/    # OpenAI, Anthropic, LangChain, export targets
│   ├── mcp/             # MCP server + CLI
│   └── storage/         # optional SQLite persistence
├── tests/               # unit / integration / e2e / perf / validation
├── examples/            # runnable framework demos
├── deploy/              # Procfile, build.sh, runtime.txt, docker/
├── docs/
│   ├── product/         # public product overview
│   ├── content/         # published pieces on conversation dynamics monitoring
│   ├── integrations/    # Cursor / Claude Desktop / Copilot setup guides
│   ├── cursor-rules/    # horizon-monitor.mdc (canonical Cursor agent rule)
│   ├── spec/            # HORIZON_TECH_SPEC.md + intent.yaml
│   └── reviews/         # E2E reviews, validation evidence
└── pyproject.toml

背景

Horizon 的设计受到 Trans-Horizon Communication Protocol（THCP）的启发。THCP 是一种推测性框架，它将人类与 AI 的通信映射到广义相对论的隐喻上。THCP 的五个“猜想”是设计直觉，而非已证实的定律——每个猜想都只有在指向一个具体、可计算的信号时才有用：

THCP 仅用于说明设计动机——完整的猜想到信号映射见 docs/product/THCP_FIDELITY_MONITOR_PRD.md。

社区

• 申请 Alpha 访问权限：发起讨论 →
• 提问：GitHub 讨论区
• Bug 报告：GitHub Issues
• 参与贡献：CONTRIBUTING.md

许可证

MIT — 见 LICENSE。

法律

性能声明： 本 README 中提到的质量提升 +15.7% 和幻觉事件减少 87%，数据来自合成的、脚本化的受控 A/B 场景，使用了经过手动调优的参考控制器——并非生产流量，也并非领域内验证语料（V1–V5 阶段使用独立的标注数据集）。结果可能因领域、模型和部署配置而异。未经自行开展特定领域评估，请勿在对外营销中使用这些数据。完整范围和证据依据请参阅 LEGAL.md §5。

高风险领域： 未经特定领域验证并确保人工监督，请勿在医疗、法律、金融或紧急服务场景中以 active 模式启用事件类型。请参阅 LEGAL.md §4。