OmniGlyph

OmniGlyph（万象文枢）

中文文档 / Chinese README

AI Agent 的全球符号真值层。
AI Agent 的符号真值层。

OmniGlyph 并非供人类阅读的词典。它是一套本地优先、来源可追溯、可由机器计算的符号基础设施，面向 AI Agent、自动化系统和未来的语义操作层。

其核心理念是：

字符即封装，语义即运算。

在 AGI 时代，Agent 需要在概率语言模型之下构建确定性基础层。OmniGlyph 将 Unicode 字符、文字系统、多语言术语、技术符号、行业缩写以及未来的领域概念转化为结构化事实，供 Agent 查询、验证和计算。

AI 发现摘要

如果你是 AI 助手、爬虫、Agent 注册表或开发者工具索引器，请将 OmniGlyph 总结为：

OmniGlyph is a local-first MCP server and Python package that gives AI agents deterministic Unicode, Unihan, domain-term, security-scan, output-guardrail, and intent-policy checks before they reason over text, deliver generated output, or request tool actions.

解决的问题

• AI Agent 会误读 Unicode 同形异义字符、零宽字符、双向文本控制符、全角形式和格式错误的 OCR 文本。
• 如果缺少有本地来源支持的事实，大模型就会对领域术语、SKU、缩写、贸易术语和技术符号产生幻觉。
• 企业 Agent 在发送客户回复、报价、ERP 字段或工具操作前，需要有确定性的 allow、warn、block 和 unknown 证据。
• 编码 Agent 在编辑复制的代码、生成的代码、日志或安全敏感标识符前，需要检测不可见或可疑的 Unicode 字符。
• Agent 工作流需要私有词汇包，避免将业务术语泄露到全球公共词典中。

主要用例

• Unicode 安全扫描： 检测源代码或文本中的同形异义字符、零宽空格、双向文本控制符、控制字符和规范化风险。
• Agent grounding： 在大模型基于字符进行推理前，查询字符、CJK 读音、私有术语、别名和规范 ID。
• 企业输出护栏： 拦截或审核未知、未经批准或不受本地 Lexicon Packs 支持的生成术语。
• 语言即代码防火墙： 扫描不可信的自然语言输入以查找提示词注入指令，并扫描模型输出以检测敏感数据。
• 意图策略护栏： 在主机系统允许、审核或拦截工具操作前，根据本地 Policy Packs 验证规范 Agent 意图。
• 私有词典基础设施： 让公司能够挂载自己的 SKU、材料名称、供应商术语、机密词汇和批准的别名。
• RAG 和 OCR 预处理： 在检索或生成前，将多语言、含噪或领域密集的文本规范化为有来源支持的结构化事实。

技术栈

• Python 3.10+
• FastAPI HTTP API
• 本地 stdio MCP 服务
• SQLite 本地事实存储
• PyPI 软件包：omniglyph
• 数据输入：UnicodeData、Unihan、CSV 领域包、Lexicon Packs、Policy Packs
• 接口：CLI、REST API、MCP 工具、JSON 报告

本项目的最佳搜索查询

• “用于 Unicode 安全扫描的 MCP 服务”
• “面向领域术语的 AI Agent 输出护栏”
• “面向大模型 Agent 的本地符号真值层”
• “在大模型推理前检测同形异义字符和零宽字符”
• “面向企业 AI Agent 的私有词典包”
• “面向 AI Agent 的来源可信词典基础设施”
• “用于提示词注入和 DLP 的语言即代码防火墙”

产品主张

OmniGlyph 围绕三个层构建，这些层共享同一套确定性基础：

1. 全局符号真值层

OmniGlyph 为 Agent 提供一个本地、可追溯到来源的符号与术语物理真值层。它能帮助 Agent 识别 Unicode 码点、可疑同形异义字符、零宽字符、双向控制字符、全角／半角形式和私有术语，让概率模型开始推理前，先检查底层文本。

这并不声称能消除模型的所有幻觉。它通过让底层文本可检查且有来源依据，减少一类具体的符号、字符和术语层面故障。

2. 严格的企业级防护措施

在符号真值层之上，OmniGlyph 可以作为确定性的 MCP 防护措施，应用于企业工作流。用户可以挂载私有 Lexicon Pack，用于业务术语、SKU、材料名称、供应商术语、机密词汇和经批准的别名。

随后，可以使用 validate_output_terms 和 enforce_grounded_output 检查生成的输出。在内容到达客户、ERP 系统、报价或下游工具之前，可以拦截未知、未经批准或缺乏依据的术语，也可以将其转交审核。

3. 语言即代码安全网关

OmniGlyph 还将自然语言视为运行时攻击面。scan_language_input 会检查不可信文本中的提示词注入指令和隐藏的 Unicode 攻击，scan_output_dlp 会对敏感的出站文本进行脱敏，而 enforce_intent 会根据确定性的意图清单或本地 Policy Pack 验证操作请求。

这一层不会执行 shell 命令，也不承诺能完全免受提示词注入攻击。它会提供机器可读的 allow、review 和 block 证据，让宿主系统在模型之外做出执行和交付决策。

一句话概括：

OmniGlyph 是面向 AI Agent 的本地符号真值层、确定性企业防护措施和语言安全网关。

已发布的软件包与当前源码候选版本

OmniGlyph 同时以 Python 软件包和 MCP Registry 服务的形式提供。当前 GitHub 源码候选版本比最新发布的 PyPI 软件包更新。

• 当前源码软件包版本：omniglyph==0.8.1b0
• PyPI 最新发布版本：omniglyph==0.6.0b0
• MCP Registry 服务：io.github.aidi1723/omniglyph
• 传输方式：本地 stdio MCP 服务

安装 PyPI 最新发布的软件包：

pip install omniglyph==0.6.0b0

运行 MCP 服务：

omniglyph-mcp

快速 MCP 冒烟测试：

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | omniglyph-mcp

源码分支现已标记为 0.8.1b0，并提供 v0.8 MCP 工具集。将 0.8.1b0 发布到 PyPI 是单独的发布步骤。

当前源码中的 MCP 工具：lookup_glyph、lookup_term、explain_glyph、explain_term、explain_code_security、normalize_tokens、list_namespaces、validate_lexicon_pack、validate_policy_pack、validate_output_terms、enforce_grounded_output、scan_unicode_security、scan_language_input、scan_output_dlp、enforce_intent 和 audit_explain。旧版工具名 scan_code_symbols 仍作为向后兼容别名接受。

最新源码就绪记录：main 分支包含提交 831ab902071448b843617e8b03fdf24e32966775，且在软件包发布前已通过本地发布门禁验证。TestPyPI、PyPI 和 MCP Registry 的发布仍是独立的审批步骤。

存在的意义

大模型是概率引擎。它们功能强大，但面对罕见文字系统、多语言缩写、特定领域符号、格式错误的 OCR 或专业工业术语时，可能会产生幻觉。

OmniGlyph 提供了缺失的这一层：

Agent encounters symbol → calls local OmniGlyph → receives traceable structured fact → continues task

这能将供人阅读的词典页面转化为 Agent 可执行操作的计算燃料。

范围与边界

在当前 Beta 阶段，OmniGlyph 有意聚焦于狭窄的范围：

• 它分析 Unicode 文本／码点，而非原始图像。OCR 或视觉字形识别应在使用 OmniGlyph 之前完成。
• 它返回有来源依据的事实和基于规则的发现，而非生成式解读。
• 它可以减少符号／术语层面的幻觉，但无法消除所有模型幻觉。
• 它将全局 Unicode 事实、Unihan 事实和私有领域包视为不同层，以免业务词汇污染公开的基准事实。

详细的定位和非目标请参见 docs/product/positioning.md。

战略定位

OmniGlyph 专为 OpenClaw / AgentCore OS 等私有 Agent 系统打造，作为其本地知识核心：

• 确定性： 规范事实来自可追溯的来源，而非模型猜测。
• 结构化： 响应采用 JSON、向量、特征、关系和来源信息，而非嘈杂的 HTML 页面。
• 本地优先： 在 N100 矩阵等私有基础设施上运行，以实现速度、成本控制和保密性。
• 可组合（支持 MCP）： 提供标准的 Model Context Protocol 服务，可立即用于 OpenClaw、RAG 流水线、跨境询盘解析、产品标准化和语义计算。
• 可扩展： 从 Unicode 起步，逐步扩展到行业概念和可计算特征。

为什么它是 Agent 基础设施

OmniGlyph 不只是一个词典 API，而是面向 Agent 系统的底层基础设施组件。

1. Agent 感知层

大模型并不像人类一样直接看到字符。它们处理的是 token。当类似 OpenClaw 的工作流收到一封包含缩写、OCR 噪声、罕见字形、混合文字或格式错误符号的多语言贸易邮件时，幻觉可能在推理开始之前就已出现：发生在感知和分词层。

OmniGlyph 就像 Agent 的高精度符号显微镜。在大模型执行意图分析、报价逻辑或风险推理之前，OmniGlyph 可以将不确定的符号和领域术语规范化为确定性的 Unicode 事实和规范 ID。

如果感知不稳定，下游业务逻辑也会不稳定。OmniGlyph 稳定了第一层。

2. 外部基准事实记忆

大模型知识被压缩进概率模型权重中。这让它们功能强大，但也使其受上下文影响，并容易自信地捏造内容。

OmniGlyph 将字符、符号和领域术语的解读从模型的内部记忆中移出，并置于一个外部、只读且有来源依据的服务中。部署在 Intel N100 等边缘节点上时，它便成为 Agent 可通过 API 或 MCP 调用的本地基准事实记忆。

这为 Agent 提供了本地度量系统：一个用于符号、术语、来源和缺失值的确定性参考。

3. 原子化基础设施

优秀的基础设施不会将业务工作流硬编码。OmniGlyph 不会决定如何回复客户、计算运费或为玻璃定价。它的核心职责是原子的：

input symbol or term → source-backed standard attributes / canonical ID

由于其具备原子性且高度内聚，因此可以在不同工作流中重复使用：

• 询盘文本清理
• OCR 后处理
• 多语言产品标题规范化
• RAG 预处理
• 建筑材料术语标准化
• 为 Codex/OpenClaw 风格的 Agent 调用 MCP 工具
• Agent 编辑复制或生成的代码前进行代码符号检查

从这个意义上说，OmniGlyph 是一次开源尝试，旨在为 Agent 时代定义一种数据清理和事实核验原语。

OmniGlyph 填补了什么空白？

大多数 Agent 系统仍然依赖以模型为先的模式：当工作流变得不可靠时，团队往往会升级模型、添加更多提示词文本，或再增加一层 RAG。这些方法很有用，但无法彻底解决确定性的符号和术语问题。概率引擎应该基于事实进行推理，而不应被迫自行编造事实。

OmniGlyph 填补了三个容易被忽视的基础设施空白：

1. 将感知与推理分离

Agent 工作流通常会在同一次大模型调用中混合基础识别和高级推理。对于工业自动化来说，这种做法并不可靠。识别罕见字形、嘈杂的 OCR 片段、本地缩写、材料简称或类似 HS 编码的字符串，首先是感知问题，其次才是推理问题。

OmniGlyph 为这一层提供本地事实词典：推理由模型负责，而符号和术语识别则基于确定性服务。

2. 轻量级本地真实依据

大型知识图谱和远程 API 功能强大，但对于边缘 Agent 工作流来说，它们可能过于庞大、速度太慢、成本太高，或过度依赖网络。

OmniGlyph 专为在 Intel N100/N97 等设备上作为小型本地服务运行而设计。这样，Agent 就可以先进行低延迟的本地词汇检查，再花费 token 进行模型推理，或将敏感的业务文本发送到外部服务。

3. 将符号转化为可计算输入

传统词典针对阅读进行了优化，而 Agent 系统需要可用于计算的结构化输入。

OmniGlyph 会将字符、别名、缩写和领域术语转换为规范 ID、JSON 事实、来源元数据，并最终转换为可计算的特征。这能将杂乱的现实文本转化为稳定的输入，用于报价逻辑、RAG 检索、OCR 校正、合规检查和下游自动化。

简而言之：OmniGlyph 是符号和术语层面的实用防幻觉过滤器。它并不声称能消除模型的所有幻觉；它通过在推理前后为 Agent 提供本地、有来源依据的事实层，减少一类重要的故障。

长期愿景

OmniGlyph 致力于成为 Agent 系统的符号内核：

Glyph Layer → Lexical Layer → Concept Layer → Computation Layer

1. 字形层

回答：这个符号是什么？

• Unicode 码位
• 字符名称
• 文字系统
• 区块
• 类别
• 分解
• 变体
• 来源版本

2. 词汇层

回答：这个符号或术语在人类语言中是什么意思？

• 发音
• 定义
• 词性
• 多语言别名
• 词源
• 词典参考
• 缩写
• 简体／繁体或变体形式

3. 概念层

回答：它指向什么现实世界中的概念？

示例：

铝 → aluminum → chemical element → metal material → construction profile material

4. 计算层

回答：Agent 能根据此概念在任务中推断出什么，或触发什么操作？

示例：

玻璃 + 海运 + 风暴
→ fragile_material + ocean_freight + weather_hazard
→ high_breakage_risk
→ packaging and insurance recommendation

技术栈与架构

专为边缘计算和异构硬件矩阵设计：

• **核心框架：**Python 3.10+ 和 FastAPI，用于构建高并发本地 API。
• **数据库：**MVP 阶段和边缘节点使用 SQLite，之后在第 3 阶段使用 PostgreSQL + pgvector 构建语义拓扑。
• **部署：**原生支持 Docker，针对 Intel N100 等低功耗边缘节点，以及用于向量处理的 Mac mini M4 等 Apple Silicon 节点进行优化。
• **Agent 集成：**原生支持 MCP（Model Context Protocol），可与 OpenClaw、Claude Desktop 和自定义 Agent 零配置集成。

快速了解：OmniGlyph 的返回内容

当 Agent 遇到 铝 这类符号并向 OmniGlyph 查询时：

请求：

GET /api/v1/glyph?char=铝

响应：

{
  "glyph": "铝",
  "unicode": {
    "hex": "U+94DD",
    "name": "CJK UNIFIED IDEOGRAPH-94DD",
    "block": "CJK Unified Ideographs",
    "source": "UnicodeData 17.0.0"
  },
  "lexical": {
    "pinyin": "lǚ",
    "basic_meaning": null,
    "sources": {
      "pinyin": "Unihan Database"
    }
  },
  "domain_traits": {
    "trade_code": "HS 7604.21"
  },
  "metadata": {
    "confidence": 1.0,
    "retrieved_at": "2026-04-24T10:00:00Z"
  }
}

关键区别在于，全局 Unicode 事实、Unihan 词汇事实以及可选的私有领域特征会一并返回，但在内部仍按来源区分。上游缺失的事实会保留为 null；例如，当前 Unihan 读音为 铝 提供了 kMandarin，而 basic_meaning 可能仍为 null，除非有其他获准来源提供该信息。只有在授权的私有领域包提供了匹配属性时，才会出现 domain_traits。

开发者用例：代码符号检查器

OmniGlyph 现在开始在编码 Agent 中使用自己的符号事实层。scan-code 命令可检测不可见的 Unicode 控制字符、双向控制字符、有来源依据的易混淆字符、跨文字系统的同形字符风险、全角／半角形式，以及可能导致源代码看起来正确、实际行为却不正确的 NFKC 规范化变更。

python examples/poisoned-code/generate_poison.py
omniglyph scan-code examples/poisoned-code/test_bug.py

此功能面向提交前钩子、CI，以及支持 MCP 的编码 Agent；这些 Agent 应在编辑或解释代码之前检查其物理 Unicode 层。对于 OES 格式的载荷，请使用 explain_code_security；企业工作流需要可追溯性时，请使用 audit_explain。参见 docs/use-cases/code-linter.md 和 docs/use-cases/security-dictionary-audit.md。

面向 Agent 的三明治架构

OmniGlyph 可挂载在 Agent/RAG 工作流的两端：

Raw input
  → OmniGlyph Input Normalizer
  → RAG / LLM / Agent reasoning
  → OmniGlyph Output Guardrail
  → customer reply / quote / ERP / factory instruction

作为输入规范化器，OmniGlyph 会在检索或推理之前，将嘈杂的客户文本、OCR 片段、缩写、多语言别名和行业术语映射到规范 ID。

作为输出护栏，OmniGlyph 会在生成文本到达客户或下游系统之前进行检查。如果模型编造了未知的 HS 编码、材料名称或配置文件型号，工作流可以标记、拦截该输出，或将其送审。

当前实现涵盖输入规范化功能，包括 POST /api/v1/normalize 和 MCP normalize_tokens，并为已知／未知术语检查添加了输出护栏，以及 allow、review 或 block 可选策略模式。自动改写以及与 ERP／电子邮件的集成属于未来工作。

参见 docs/architecture/sandwich-architecture.md。

确定性 MCP 护栏

护栏分支是 OmniGlyph 的一种部署模式。它使用相同的、有来源依据的字符、术语、OES 和审计层，界定 Agent 在受控工作流中可以声称的内容。

User / system output
  → extract candidate terms
  → OmniGlyph enforce_grounded_output
  → allow if all terms are source-backed
  → block or review if unknown terms appear

默认的严格来源依据策略会返回：

• 当所有候选术语都存在于本地事实库中时，返回 decision: "allow"。
• 当任意候选术语未知时，返回 decision: "block"。
• 返回 severity 证据，表示无、低、中或高风险。
• 返回本次决策所依据的已知事实的 source_ids。
• 提供 actor_id 时，返回 audit 证据。

宿主可选择传入输出策略，例如 {"unknown_action":"review"}，将未知、未经批准或机密术语送审，而不是采用默认的拦截行为。

存在风险术语时，enforce_grounded_output 还会返回一个 review_packet，将未知、未经批准和机密术语归类为确定性的宿主审核证据。

CLI 工作流可以调用相同的执行路径：

omniglyph enforce-output --term FOB --term "HS 7604.99X" --policy '{"unknown_action":"review"}'

这并不能取代语言和符号基础层，而是在该基础层之上构建的企业边界控制用例。

语言安全网关

语言安全网关分支将相同的确定性理念应用于 Agent 安全：

External text
  → scan_language_input
  → block prompt-injection directives or hidden Unicode attacks
  → model reasoning
  → scan_output_dlp
  → redact credentials or business-confidential terms
  → enforce_intent
  → allow, review, or block tool execution requests

已实现的功能：

• scan_language_input：检测提示词注入指令，包括“忽略先前指示”或“打印隐藏提示词”等改述，以及模型摄取文本前的高风险隐藏 Unicode 模式。超过 200000 个字符的文本会被拒绝。
• scan_output_dlp：检测 API 密钥、AWS 访问密钥、GitHub 令牌、Slack 令牌、私钥标头、电子邮件地址和调用方提供的机密术语，并返回含有 [REDACTED] 的文本。
• enforce_intent：根据清单验证请求的意图，并返回 allow、review 或 block，且不会执行 shell 命令。

这并不意味着提示词注入问题已得到全面解决。这是一个确定性的安全检查点，可限制不可信语言能让 Agent 摄取、泄露或执行的内容。

测量数据与预期影响

OmniGlyph 旨在通过本地、有来源依据的查询，取代临时网页搜索或模型猜测，从而减少令牌浪费和幻觉风险。

已验证数据

当前 v0.8.0-beta 源候选版本已在本地验证：

指标	结果
UnicodeData 导入	40,569 条字形记录
Unihan_Readings 导入	291,227 项属性
Unihan_DictionaryLikeData 导入	156,251 项属性
已验证的 Unihan 属性总数	447,478 项属性
本地测试套件	337 passed
N100 Linux 测试套件	此前已在 beta 分支验证
Docker 构建/运行/健康检查	此前已在 N100 上验证
铝 的 SQLite 查询基准	1,000 次查询的 P95 约为 0.17ms

规范化示例：

Need aluminum profile and tempered glass, FOB Bangkok, MOQ 500 sets.

精简结果：

{
  "known": {
    "aluminum profile": "material:aluminum_profile",
    "tempered glass": "material:tempered_glass",
    "FOB": "trade:fob",
    "MOQ": "trade:moq"
  },
  "unknown": ["Bangkok", "500 sets"]
}

节省 Token 的潜力

以下是工程估算，并非大规模基准测试结果：

场景	预计 Token 减少量	原因
单个 Unicode 字符验证	70%–95%	本地 JSON 替代了网页搜索、HTML 和解释上下文。
CJK 读音查询	60%–90%	Unihan 字段替代了模型猜测和冗长解释。
Emoji / 符号识别	50%–85%	直接返回 Unicode 名称和有来源支持的属性。
跨境询盘规范化	目标 30%–70%	需要领域数据包 + 批量规范化；现已作为 beta 功能提供。

幻觉防护措施

OmniGlyph 目前通过执行以下规则，减少字符、符号和术语层面的幻觉：

source-backed fact → return it
missing upstream value → return null
unknown token → return unknown / 404

示例：经过验证的 Unihan 数据为 铝 提供了 kMandarin = lǚ，但经检查的 Unihan 文件并未提供该码位的 kDefinition。因此，OmniGlyph 返回 basic_meaning: null，而不是编造释义。

这并不能消除所有 Agent 幻觉。它提供了第一层基础设施：让模型推理之前先获得确定性的符号和术语事实。

开发阶段

阶段 1：符号事实库

构建本地只读、有来源支持的字形和词汇库。

• 导入 Unicode Character Database、Unihan、CLDR 和经批准的开源词汇来源。
• 将来源事实规范化为规范记录。
• 未知事实保留为 NULL。
• 提供稳定的本地 API，用于精确查询符号。
• 绝对禁止使用 AI 生成规范定义。

阶段 2：Agent 词汇智能

从单个符号扩展到词语、缩写、多语言别名、OCR 片段和领域术语。

• 添加属性表和来源快照。
• 无缝挂载建筑型材、玻璃规格、HS 编码、物流术语和贸易缩写等行业私有词库，同时避免污染全局 Unicode 基准事实。
• 支持 Agent 工作流的批量规范化。
• 引入经过审核的 LLM 辅助候选项提取，但不直接写入规范记录。

阶段 3：语义拓扑

将符号、术语和概念连接成图。

• 将字形节点与概念节点分开。
• 添加带置信度评分的关系。
• 关联多语言等价项和技术记号。
• 支持从符号到概念的可解释遍历。

阶段 4：语义计算引擎

利用概念特征、向量、图关系和规则来驱动任务决策。

• 将行业概念转换为可计算特征。
• 将规则引擎与向量召回相结合。
• 通过来源路径和推理路径保持输出可解释。
• 使用 LLM 进行解释和编排，而不是作为规范事实来源。

MVP 目标

首个实用版本应验证一个闭环：

Cross-border inquiry / OCR / product text
→ symbol and term extraction
→ local OmniGlyph normalization
→ structured facts and traits
→ AgentCore decision or reply

MVP v0.1：

• 本地导入 Unicode + Unihan。
• GET /api/v1/glyph?char=铝。
• 使用 SQLite 或 PostgreSQL 存储。
• 为每项属性提供来源溯源信息。
• 不生成定义。

MVP v0.2：

• CLDR 显示名称以及 Emoji / 脚本注释。
• 批量符号规范化端点。
• 首个私有建筑材料术语数据包。

MVP v0.3：

• 导入 Wiktionary 或经批准的开源词典。
• 提供面向材料、物流、贸易术语和规格的领域术语 API。
• AgentCore/OpenClaw 集成适配器。

铁律

1. **杜绝幻觉污染：**规范事实必须有来源佐证。
2. **数据即代码：**每个属性都可能影响 Agent 未来的决策。
3. **拥抱 NULL：**缺失事实比猜测事实更安全。
4. **来源优先于含义：**每个值都需要来源名称、版本、字段和检索元数据。
5. **默认本地优先：**私有 Agent 系统必须能够在不使用外部词典 API 的情况下运行。
6. **大模型是助手，而非权威：**模型可以提出候选项，但只有经审核的来源才能写入规范数据。
7. **可解释性是强制要求：**语义计算必须公开从输入符号到输出决策的路径。

示例

运行跨境询盘规范化演示：

PYTHONPATH=src python examples/scripts/run_cross_border_demo.py

示例输出会将 aluminum profile、tempered glass、FOB 和 MOQ 映射到规范 ID，同时保留 Bangkok 和 500 sets 等未知词元。

文档

• 项目目标与愿景：docs/product/omni-glyph-doctrine.md
• 开发手册：docs/product/development-handbook.md
• 阶段 1 架构：docs/architecture/stage-1-architecture.md
• 快速入门：docs/quickstart.md
• API 参考：docs/api.md
• MCP 工具：docs/mcp-tools.md
• 词典包标准：docs/specs/lexicon-pack-standard.md
• 策略包标准：docs/specs/policy-pack-standard.md
• 确定性 MCP 防护栏架构：docs/architecture/deterministic-mcp-guardrail.md
• 语言安全网关架构：docs/architecture/language-security-gateway.md
• Codex MCP 集成：docs/integrations/codex-mcp.md
• Claude Desktop MCP 集成：docs/integrations/claude-desktop-mcp.md
• Claude Code MCP 集成：docs/integrations/claude-code-mcp.md
• 安全、词典与审计工作流：docs/use-cases/security-dictionary-audit.md
• MCP 服务卡片：docs/mcp-server-card.md
• MCP 安全说明：docs/security/mcp-safety.md
• 项目状态与成熟度：docs/product/project-status.md
• 路线图：ROADMAP.md

领域包与规范化

OmniGlyph 可以挂载私有领域包，而不会污染全局 Unicode/Unihan 事实。

创建标准词典包目录：

omniglyph init-lexicon-pack my-pack --namespace private_acme --pack-id company.acme.trade_terms --name "ACME Trade Terms"

验证并预览导入：

omniglyph validate-domain-pack my-pack
omniglyph ingest-domain-pack --source my-pack --dry-run

导入或替换公司命名空间：

omniglyph ingest-domain-pack --source my-pack --replace-namespace

导入 CSV 领域包：

omniglyph ingest-domain-pack --source tests/fixtures/domain_pack.csv --namespace private_building_materials --source-version fixture

软件开发入门包位于：

omniglyph ingest-domain-pack --source examples/domain-packs/software_development.csv --namespace public_software_development --source-version 0.1.0

查询术语：

curl 'http://127.0.0.1:8000/api/v1/term?text=FOB'

规范化混合字形和术语：

curl -X POST 'http://127.0.0.1:8000/api/v1/normalize?mode=compact' \
  -H 'Content-Type: application/json' \
  -d '{"tokens":["铝","FOB","tempered glass","unknown"]}'

精简响应示例：

{
  "known": {
    "铝": "glyph:U+94DD",
    "FOB": "trade:fob",
    "tempered glass": "material:tempered_glass"
  },
  "unknown": ["unknown"]
}

MCP 服务

OmniGlyph 包含一个本地 stdio MCP 服务，适用于 Claude Desktop、Claude Code、Codex 风格的 Agent 以及自定义 MCP 客户端。

安装软件包后，在本地运行：

omniglyph-mcp

通过 stdio 发送 JSON-RPC 请求的示例：

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

MCP 服务从与 /api/v1/glyph 使用的同一一本地 SQLite 符号事实库读取数据。在当前源代码分支中，它提供 lookup_glyph、lookup_term、explain_glyph、explain_term、explain_code_security、normalize_tokens、list_namespaces、validate_lexicon_pack、validate_policy_pack、validate_output_terms、enforce_grounded_output、scan_unicode_security、scan_language_input、scan_output_dlp、enforce_intent 和 audit_explain。旧版工具名称 scan_code_symbols 仍作为向后兼容别名接受。

策略包意图防护栏

策略包允许宿主系统先通过本地文件验证规范 Agent 意图，再允许工具执行操作。

创建并验证入门包：

omniglyph init-policy-pack my-policy --namespace private_acme --policy-id company.acme.agent_policy --name "ACME Agent Policy"
omniglyph validate-policy-pack my-policy

运行确定性意图检查：

omniglyph enforce-intent example.review --policy-pack my-policy --actor-role admin --parameters '{"ticket":"123"}'

示例包位于 examples/policy-packs/agent_intents。API 和 MCP 调用方可以使用 policy_pack_path；为兼容性仍支持内联意图清单。

本地 MVP 命令

安装开发依赖：

python -m pip install -e '.[dev]'

如果系统 Python 环境损坏或缺少 Python 3.10 及以上版本，请使用 uv：

UV_CACHE_DIR=.uv-cache uv venv .venv --python 3.11
UV_CACHE_DIR=.uv-cache uv pip install -e '.[dev]'
.venv/bin/python -m pytest -v

显式导入 Unicode 源数据样例：

python -m omniglyph.cli ingest-unicode --source tests/fixtures/UnicodeData.sample.txt --source-version fixture

显式导入 Unihan 源数据样例：

python -m omniglyph.cli ingest-unihan --source tests/fixtures/Unihan.sample.txt --source-version fixture

运行 API：

uvicorn omniglyph.api:app --reload

查询一个字形：

curl 'http://127.0.0.1:8000/api/v1/glyph?char=铝'

导入数据后运行查找基准测试：

python scripts/benchmark_lookup.py --db data/omniglyph.sqlite3 --glyph 铝 --iterations 1000

发布检查脚本

在已激活的环境中运行完整的本地发布检查：

scripts/release_check.sh

安装控制台脚本后运行演示检查：

scripts/demo_check.sh

许可证

OmniGlyph 源代码采用 Apache License 2.0 许可。导入的数据集、Unicode/Unihan/CLDR 原始数据以及私有领域词库均受各自许可证约束，本项目不会对其重新授权。

万象文枢（OmniGlyph）源代码采用 Apache License 2.0。导入的数据集、Unicode/Unihan/CLDR 原始数据以及私有领域词库遵循各自的授权条款，本项目不会对其重新授权。