在 HeavenBase 上构建 GlossWise

术语表本来只是清单，直到应用的其他部分也能向它提问。

项目案例研究 - HeavenBase 团队 - 2026 年 7 月 28 日 - 约 1,700 字 - 阅读 9 分钟

GlossWise 存储已批准术语、翻译规则与示例，再为调用方智能体或应用准备紧凑简报。它同时是 Python SDK、CLI、HeavenBase 扩展、智能体 Skill 与 MCP 服务器。宿主智能体可以继续使用自己的翻译模型，直接 CLI 则使用显式的 HeavenBase LLM 预设。这种产品形态让 GlossWise 成为很好的压力测试。它需要持久化结构数据、精确短语匹配、可选语义搜索、图关系、工作区隔离、配置、LLM 调用与多个界面。真正有趣的问题不是 HeavenBase 能否存储术语，而是当所有界面共享一个模型时，会消失多少应用架构。

1. 动机

一个项目可以从 Python 映射开始：

preferred_terms = {
    "rate limit": "速率限制",
    "workspace": "工作区",
}

这在术语需要别名、禁用形式、语言范围、项目领域、优先级、示例、关系、审计字段或搜索证据之前都能工作。之后第二个文件可能添加规则，向量数据库可能添加相似度，MCP 包装器可能添加智能体访问。很快，每个界面都重建了一个略有不同的「术语表」。 GlossWise 改为维护一个显式领域。术语表示与语言无关的概念；词形存储特定语言的首选、别名、错拼或禁用文本；规则携带有范围约束的指令；示例保存已审核的源文与译文对。每个界面都调用同一个工作区绑定服务。这很重要，因为翻译一致性首先是状态问题，其次才是模型问题。更好的提示词无法取回应用从未连贯存储的决定。

2. 只建模一次领域

GlossWise 定义普通 HeavenBase 实体。下面的精简片段展示了为什么一个词形不只是字符串：

import heavenbase as hb


class GlossWiseTermForm(hb.Entity):
    identifier = "glosswise-term-form"

    term_id = hb.field(hb.Identifier["glosswise-term"])
    lang = hb.field(hb.ShortText)
    role = hb.field(hb.ShortText)
    text = hb.field(hb.ShortText)
    triggers = (
        hb.field(hb.Array[hb.ShortText])
        .default([])
        .store(strategy=hb.SparseGramIndex(normalizer="default"))
    )
    embedding = hb.field(hb.Vector[3]).optional()
    status = hb.field(hb.ShortText).default("active")

这个声明把身份、验证、描述与放置意图放在一起。SparseGramIndex 支持反向包含，因此存储的短语可以在更长文档中被找到。配置嵌入策略后，可选向量能提供语义候选。标量字段则让精确的语言、角色与状态过滤保持可检查。 GlossWise 还对结构化数组使用 SideTable，对术语、规则与示例之间的类型化关系使用 GraphEdge。HeavenBase 把这些选择保留在同一个实体与查询界面后面，应用无需直接协调 SQL、向量和图客户端。

GlossWise 仍然拥有领域验证。HeavenBase 知道如何存储和查询 role；GlossWise 决定 preferred、alias、typo 与 prohibited 才是允许的值。

3. 发布一个模块文件夹

GlossWise 不只贡献实体类。它的包根目录就是一个 HeavenBase 模块文件夹：

src/glosswise/
├── entities.py
├── service.py
├── mcp/
├── meta.yaml
└── ...

meta.yaml 描述符声明四个实体、glosswise 扩展、一个工具集 (Toolkit) family 与三个 MCP profile。紧凑片段如下：

manifest_version: 2
coordinate: glosswise/glosswise
version: 0.1.0.5
bundle: glosswise
items:
  - kind: entity
    identifier: glosswise-term-form
    source: path
    target: {module: entities, qualname: GlossWiseTermForm}
  - kind: extension
    identifier: glosswise
    source: inline
    target: definition

内置与外部模块使用同一套描述符、注册表 (Registry) 发布、解析和生命周期。安装会把基于路径的代码捕获为经过验证的内容寻址制品。检查无需导入实现就能读取记录，激活则解析精确声明的依赖。对产品作者来说，这是一个实用边界：包元数据解释产品贡献了什么，Python 解释这些部件如何工作。

4. 挂载一个工作区 API

该扩展把 GlossWiseService 挂载为 workspace.glosswise。应用设置因而可以保持简短：

import heavenbase as hb
from glosswise import install


context = hb.Context.load()
install(context)

ws = hb.HeavenBase(
    "glosswise-demo",
    backends={
        "main": {
            "type": "sqlite",
            "database": "glosswise.db",
        }
    },
    context=context,
)
ws.enable_extension("glosswise")

service = ws.glosswise

上下文 (Context) 拥有机器配置、已安装模块记录与工作区身份。工作区 (Workspace) 拥有所选扩展根、规范实体类、存储计划与数据行。挂载的服务拥有 GlossWise 规则，例如规范化、冲突处理、有界搜索与响应封装。这个划分避开了两个常见陷阱。GlossWise 不把业务逻辑藏在 CLI 命令中，也不会在已经拥有 Context 时依赖环境进程状态。

5. 一起查询精确与语义证据

服务组合普通 HeavenBase 查询。词法扫描可以询问存储的触发短语是否出现在更长的源字符串中：

TermForm = ws.entities["glosswise-term-form"]

hits = (
    ws.query(TermForm)
    .where(TermForm.triggers.contained_in("Retry after the rate limit resets."))
    .where(TermForm.status == "active")
    .select("term_id", "lang", "role", "text", "match")
    .execute()
    .rows()
)

结果包含 object_id 与匹配证据。GlossWise 随后可以补全父术语，应用语言与领域策略，组合可选向量候选，并解释哪些存储决定进入了翻译简报。 Query.explain() 和 execute() 同样重要。声明的能力并不能证明一个具体字段会在一个具体后端上原生执行。GlossWise 测试所选处理器模式，并诚实地保留有界回退，而不会把绿色的设置检查误写成性能承诺。

6. 在多个界面复用同一个核心

GlossWise 通过以下方式暴露同一个应用：

面向 Python 调用方的 GlossWiseApp
面向终端工作流的 glosswise
面向智能体且带命名空间的 glosswise_* MCP 工具
教智能体何时及如何调用这些工具的打包 Skill

CLI 与 MCP 函数都是薄适配器。它们选择工作区，验证边界输入，调用 workspace.glosswise，再序列化有界结果。它们不会重新实现术语搜索或策展。模块描述符让 MCP 界面可检查。读取 profile 暴露搜索、扫描、翻译简报与 Skill 访问；策展 profile 在其上增加经过验证的写入；本地 profile 只添加得到显式授权的文件范围与 PDF OCR 工具。这里最能看见 HeavenBase 的回报：产品不需要一个 Python 仓库、一个 CLI 仓库、一个 MCP 仓库，再加第四套努力保持一致的模式。

7. 让模型选择保持可见

GlossWise 准备上下文，不会假装上下文与生成是同一件事。宿主智能体用自己的模型翻译；直接命令通过命名预设使用 hb.LLMSession，并报告解析后的入口 (Gateway)、提供商、模型与模型 id。可复用的翻译与 OCR 指令通过 hb.Prompt 渲染。页面图像流经配置的视觉预设，而 GlossWise 拥有文件授权、页面范围、临时文档句柄与清理。这种分工是刻意的。HeavenBase 提供 Context 绑定的 LLM 与提示基础设施；GlossWise 提供产品策略，决定什么可以读取、什么必须披露，以及哪些术语证据必须到达模型。

8. HeavenBase 去掉了什么，又没有去掉什么

关注点	HeavenBase 提供	GlossWise 仍然拥有
数据模型	实体模式、身份、验证、放置	术语语义与跨记录不变量
持久化	工作区生命周期与后端路由	托管工作区默认值与产品迁移
检索	类型化过滤、Sparse GRAM、向量、图遍历	排名、阈值、冲突与有界简报
扩展打包	模块描述符、Registry 解析、制品	GlossWise 记录与兼容性声明
智能体访问	Toolkit family、MCP profile、序列化器	工具名、授权策略与结果契约
生成	Context 绑定的 LLM 会话与提示	翻译工作流、披露与不确定性模式

这张表就是框架边界的实际收益：HeavenBase 去掉重复基础设施，却没有吞掉应用本身。

9. 来自真实外部项目的经验

GlossWise 也发现了真实缺口。外部分发与信任仍然依赖本地安装器。工作区清单尚不能导出语言提示等扩展自有配置。短生命周期 CLI 进程需要承担明显的模式重放成本。某些带过滤的向量与 Sparse GRAM 路径需要显式边界或项目侧变通。这些限制是有用证据，而不是失败的演示。当外部项目既能展示删掉了什么代码，也能展示仍需编写什么策略时，框架才开始变得可信。最重要的结果是架构性的：GlossWise 可以继续做一个术语产品。它的中心对象是工作区绑定服务，领域只声明一次，每个界面都是这个所有者之上的适配器。HeavenBase 让这种普通形态可以跨越存储与智能体边界。

10. 试用 GlossWise

安装当前源码，并用你常用的语言集创建工作区：

python -m pip install "git+https://github.com/Magolor/GlossWise.git"
glosswise setup '["en","zh"]'
glosswise ws get

随后把 MCP 服务器连接到支持的智能体，或使用 Python SDK。GlossWise 仓库包含完整快速开始、外部模块测试、MCP profile 与项目详细的 HeavenBase 集成反馈。

摘要

GlossWise 只建模一次术语、规则、示例与证据。
HeavenBase 把该模型变成存储、搜索、Extension、CLI、Skill 与 MCP 表面。
产品特定策展留在 GlossWise，而基础设施所有权保持可见。

进一步探索

相关资源：

实体 - 定义共享领域模型
后端 - 路由字段并检查执行证据
扩展 - 发布一个外部模块文件夹
工具集 - 构建 profile 限定的智能体工具
LLM 概览 - 解析可见的模型预设
GitHub 上的 GlossWise - 阅读完整产品与测试

​1. 动机

​2. 只建模一次领域

​3. 发布一个模块文件夹

​4. 挂载一个工作区 API

​5. 一起查询精确与语义证据

​6. 在多个界面复用同一个核心

​7. 让模型选择保持可见

​8. HeavenBase 去掉了什么，又没有去掉什么

​9. 来自真实外部项目的经验

​10. 试用 GlossWise

​摘要

​进一步探索

1. 动机

2. 只建模一次领域

3. 发布一个模块文件夹

4. 挂载一个工作区 API

5. 一起查询精确与语义证据

6. 在多个界面复用同一个核心

7. 让模型选择保持可见

8. HeavenBase 去掉了什么，又没有去掉什么

9. 来自真实外部项目的经验

10. 试用 GlossWise

摘要

进一步探索