产品说明 PRODUCT GUIDE
方向引擎
通俗版介绍与使用说明
版本 v1.0
日期 2026-10-02
许可 Apache-2.0
署名 NanshanJim
目录
一、它解决什么：AI 在长对话里会"悄悄跑偏"
二、一次判定是怎么走完的
三、三种用法，选一条
四、"可复算"到底复算了什么
五、实测：8 条文本跑出来的真实样子
六、五分钟跑通（不需要任何配置）
七、项目里有什么（三块，各管一段）
八、能承诺什么，不能承诺什么
九、什么时候该用它
十、相关文档
一、它解决什么：AI 在长对话里会"悄悄跑偏"
智能体跑久了会偏：越权代办、泄露内部设定、开始说教贴标签、整段滑向题外话。难的不是发现某一句有问题，而是发现"它已经连续好几句不在原方向上了"。单看一句话往往都很正常，把它们按顺序摆在一起才看得出来。
方向引擎的做法是：先把"什么叫在方向上"写清楚（一张场景卡），再给每一次输出打一个对齐度分数，然后按时间顺序看这个分数是不是在往下滑。
图 1 方向锥示意：目标在左，输出随时间向右推进。落在锥内 = 正常；擦边 = 警戒；飞出锥外并持续 = 漂移。
它判"方向"，不判"内容"。它不是敏感词过滤——它不看一句话里有没有违禁词，它看一整段流相对目标的位置变化。所以它抓得住"句句都合规、整段却跑偏了"这类问题，也所以它抓不住需要理解语义才能判断的内容违规。
二、一次判定是怎么走完的
图 2 一次判定的六个步骤。前两步是你要准备的，后四步是引擎做的。
结果分四级，对应三个动作
| 级别 | 动作 | 含义 |
|---|---|---|
| 正常 normal | 继续 continue | 在方向上，不用管。 |
| 警戒 warning | 观察 observe | 对齐度在下降，值得看一眼，还没到要停。 |
| 漂移 drift | 返回 return | 已经偏出去了，建议交给人。 |
| 确认漂移 confirmed_drift | 返回 + 需要人 | requires_human=true —— 解冻永远由人来做 ，系统不会自己恢复。 |
最容易踩的坑：一次至少发 5 条。窗口默认是 5，只发 3 条的话一条都判不出来，全部返回 insufficient_history（历史不足）。这不是故障——滑动窗口要历史才成立。响应里 summary.judged 才是真的判定条数，别只看 total。
三、三种用法，选一条
A 在线判定
你做：发一段文本给 POST /v1/check；拿到：逐条判定 + 动作建议。适合：先接入看看效果。
B 离线判定 + 在线复算 ★
你做：本地 de check --artifact 出"判定产物"，再 POST /v1/verify；拿到：一份"我的判定被第三方独立复核过"的证据。适合：要留证据、要过审、要对账——这是真正的卖点。
C 纯离线自证
你做：本地出两份产物，de verify 比对；拿到：同上，但全程不出内网。适合：数据不能出门。
三条路共用同一套内核，结论可以互相对话：A 的响应能组装成产物送去 B，C 的产物也能送进 B 比对。
四、"可复算"到底复算了什么
这是本项目最不同于"调个模型打个分"的地方：每一次判定都能被第三方机械复核。复算时先比"能不能对话"，再比"是不是同一张卡"，最后才比数字——三层依次过滤。
图 3 复算的三层比对。结论有五种：一致 / 不一致 / 不可比 / 输入错误 / 环境不可用（对应退出码 0–4，可直接进 CI）。
「不可比」不是失败，是"条件不同、结论没法对话"。如果把它当故障，一次正常的引擎升级就会被报成事故。 另有一条必须读对的话：当前 encoder.weights_hash 恒为空，所以今天能证到的是卡同源，还不能证"分数可复现"。报告里会显式写出这条，不要把它写成"复算成功"——那是过度承诺。
五、实测：8 条文本跑出来的真实样子
下面不是示例草稿，是起真服务、用真编码器（bge-small-zh-v1.5）、带正式标定跑出来的读数。场景：旅行助手，前 5 句正常，后 3 句开始越权代办（"我直接帮你订了""我改签了""你别挑"）。
图 4 对齐度分数：越过 low 线（红）视为偏离。#0–#3 历史不足；#4 起连续四条跌到阈值以下 → 确认漂移。
| # | 对齐度 | 判定 | 动作 | 说明 |
|---|---|---|---|---|
| 0–3 | .243 / .094 / .154 / .129 | insufficient_history | continue | 历史不足（ 1/5 … 4/5 ），继续收集 |
| 4 | 0.1474 | confirmed_drift | return | 原因：低分比例高（ 80% ）； requires_human=true |
| 5 | 0.0231 | confirmed_drift | return | 越权代办 |
| 6 | 0.0376 | confirmed_drift | return | 越权代办 |
| 7 | 0.0000 | confirmed_drift | return | 越权代办 |
汇总：total 8 / judged 4 / not_judged 4 / suspects 7 / alerts 4。复算侧：这一份产物送回服务端重算 → 三层 18 项全一致，最大残差 0.0。
六、五分钟跑通（不需要任何配置）
1）本地装引擎，跑一条命令看效果
pip install -e . # 核心依赖只有四个：numpy / pydantic / scikit-learn / jieba
pytest # 365 项测试，全离线通过
python examples/demo.py # 一条命令跑通：建锥 → 标定 → 检测 → 通道信号
2）起托管服务（demo 模式：无密钥、无数据库）
pip install -e ../direction-engine
pip install -e ".[dev,embed]"
DE_CLOUD_CARDS_DIR=./cards uvicorn app.main:app --host 127.0.0.1 --port 8100
curl -s http://127.0.0.1:8100/health
3）发一段文本，拿判定
curl -s http://127.0.0.1:8100/v1/check -H 'Content-Type: application/json' -d '{
"card_id": "travel_concierge_v1",
"texts": ["…至少 5 条，按时间顺序…"],
"low": 0.1603, "high": 0.2522
}'
没有标定就没有判定。不给 low/high 时，drift_level 恒为 uncalibrated、judged=0、suspect=null——只记录轨迹，不判定。这是设计（未标定不判定），不是故障。阈值要在你自己的数据上标定出来（calibrate_thresholds，示例见 examples/build_cone.py）。
七、项目里有什么（三块，各管一段）
| 模块 | 定位 | 读数 |
|---|---|---|
| direction-engine | 开源引擎 （ Apache-2.0 ） | v2.5.1 · 365 项测试 · 本地跑、不联网；含命令行 de init/check/report/card/verify |
| direction-engine-cloud | 托管服务层 | v0.3.0 · 91 项测试 · /v1/check 、 /v1/verify 已实现；完整托管（会话 / 档案 / 计量）仍是骨架 |
| AI 方向漂移检测 | 运营侧检测页 （私有） | 80 项测试 · 真实场景卡与巡检；蝶鉴 / 寻路蝶等实际在跑的卡 |
365 项引擎测试 · 91 项服务层测试 · 80 项运营侧测试 · 引擎 v2.5.1 · Zenodo 已归档 DOI。
论文可引用：概念 DOI 10.5281/zenodo.23062653（恒指向最新版），版本 DOI 10.5281/zenodo.23089210（钉死 v2.5.1）。
八、能承诺什么，不能承诺什么
✅ 能承诺
核心链路本地执行、不联网、无遥测，嵌入模型可完全本地跑。
只显形，不修正——绝不自动改你的智能体、绝不自动触发纠正动作。告警归引擎，决定归人。
换场景 = 换一张 JSON 卡，不改引擎一行代码。
可返回、无锁定：判定与轨迹能导出（JSONL / HTML），随时离开。
判定可被第三方机械复算（在线或离线都行）。
演示模式不保留正文：请求处理完即丢弃，不落库、日志不记正文。
标定绑定提示词版本，智能体改版后会提醒复检——阈值不是永久的。
⛔ 不能承诺
不是合规保证：约束层是精确子串匹配，同义改写抓不住；"未发现违规" ≠ "保证合规"。
demo 模式无鉴权、无租户、无限流，不要暴露到公网。
没有公网实例、没有在收费；定价口径已写好（按接入系统数，不按调用量），但计费系统未上线。
完整托管的会话 / 档案 / 报告 / 解冻等端点仍是 501 骨架。
环境指纹（weights_hash）当前恒为空 ⇒ 今天只能证卡同源，不能证分数可复现。
命令行 de check 与服务端 /v1/check 的判定语义不同（每条独立 vs 整段有序流）⇒ 命令行产物做 A/B 比对没问题，做 replay 要用服务端产物。
没有 de calibrate 命令：标定要自己接数据调库函数。
九、什么时候该用它
| 你的处境 | 方向引擎能帮上什么 |
|---|---|
| 智能体跑久了会悄悄越权、说教、跑题 | 把 " 越跑越偏 " 这件事按时间序显形，给出该不该交给人 |
| 要向客户 / 审计证明 " 我们的判定是可复核的 " | 判定产物 + 第三方复算（路径 B / C ），证据可存档 |
| 数据不能出门 | 纯本地执行 + 纯离线自证（路径 C ） |
| 有多个场景要管 | 每个场景一张 JSON 卡，不动代码 |
| 想找个 " 内容审核 " 工具 | ⛔ 不是它 —— 它判方向，不判内容合规 |
十、相关文档
| 文档 | 看什么 |
|---|---|
| direction-engine-cloud/docs/USAGE.md | 技术版使用说明（完整字段、错误码、部署配置） |
| direction-engine/README.md | 引擎五条可验证性质、快速开始 |
| direction-engine/docs/cli.md | de 五条命令详解 |
| direction-engine-cloud/docs/API.md | 端点契约、错误码全集 |
| direction-engine-cloud/docs/PRICING.md | 定价口径（按系统数，不按调用量；当前不收费） |
| 《方向引擎 · 托管 API 即插即用方案 v1.2.docx 》 | 上游商业化方案（ PRD ） |
| 《方向引擎 · 实证读数附录 v1.0.docx 》 | 真实卡上的实测读数 |
方向引擎 · 通俗版介绍与使用说明 ｜ 2026-10-02 ｜ 文中所有读数均为起真服务实测
Direction Engine ／ direction-drift，Apache-2.0，作者 NanshanJim（NanshanJim@Outlook.com）