> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 HeavenBase 上构建 GlossWise

> GlossWise 如何使用 HeavenBase 实体、模块、工作区 API、搜索、LLM 与 MCP，成为完整的术语产品。

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

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

GlossWise 存储已批准术语、翻译规则与示例，再为调用方智能体或应用准备紧凑简报。它同时是 Python SDK、CLI、HeavenBase 扩展、智能体 Skill 与 MCP 服务器。宿主智能体可以继续使用自己的翻译模型，直接 CLI 则使用显式的 HeavenBase LLM 预设。

这种产品形态让 GlossWise 成为很好的压力测试。它需要持久化结构数据、精确短语匹配、可选语义搜索、图关系、工作区隔离、配置、LLM 调用与多个界面。真正有趣的问题不是 HeavenBase 能否存储术语，而是当所有界面共享一个模型时，会消失多少应用架构。

<br />

## 1. 动机

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
preferred_terms = {
    "rate limit": "速率限制",
    "workspace": "工作区",
}
```

这在术语需要别名、禁用形式、语言范围、项目领域、优先级、示例、关系、审计字段或搜索证据之前都能工作。之后第二个文件可能添加规则，向量数据库可能添加相似度，MCP 包装器可能添加智能体访问。很快，每个界面都重建了一个略有不同的「术语表」。

GlossWise 改为维护一个显式领域。术语表示与语言无关的概念；词形存储特定语言的首选、别名、错拼或禁用文本；规则携带有范围约束的指令；示例保存已审核的源文与译文对。每个界面都调用同一个工作区绑定服务。

这很重要，因为翻译一致性首先是状态问题，其次才是模型问题。更好的提示词无法取回应用从未连贯存储的决定。

<br />

## 2. 只建模一次领域

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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、向量和图客户端。

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

<br />

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

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
src/glosswise/
├── entities.py
├── service.py
├── mcp/
├── meta.yaml
└── ...
```

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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 解释这些部件如何工作。

<br />

## 4. 挂载一个工作区 API

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 时依赖环境进程状态。

<br />

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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 测试所选处理器模式，并诚实地保留有界回退，而不会把绿色的设置检查误写成性能承诺。

<br />

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

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

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

CLI 与 MCP 函数都是薄适配器。它们选择工作区，验证边界输入，调用 `workspace.glosswise`，再序列化有界结果。它们不会重新实现术语搜索或策展。

模块描述符让 MCP 界面可检查。读取 profile 暴露搜索、扫描、翻译简报与 Skill 访问；策展 profile 在其上增加经过验证的写入；本地 profile 只添加得到显式授权的文件范围与 PDF OCR 工具。

这里最能看见 HeavenBase 的回报：产品不需要一个 Python 仓库、一个 CLI 仓库、一个 MCP 仓库，再加第四套努力保持一致的模式。

<br />

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

GlossWise 准备上下文，不会假装上下文与生成是同一件事。宿主智能体用自己的模型翻译；直接命令通过命名预设使用 `hb.LLMSession`，并报告解析后的入口 (Gateway)、提供商、模型与模型 id。

可复用的翻译与 OCR 指令通过 `hb.Prompt` 渲染。页面图像流经配置的视觉预设，而 GlossWise 拥有文件授权、页面范围、临时文档句柄与清理。

这种分工是刻意的。HeavenBase 提供 Context 绑定的 LLM 与提示基础设施；GlossWise 提供产品策略，决定什么可以读取、什么必须披露，以及哪些术语证据必须到达模型。

<br />

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

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

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

<br />

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

GlossWise 也发现了真实缺口。外部分发与信任仍然依赖本地安装器。工作区清单尚不能导出语言提示等扩展自有配置。短生命周期 CLI 进程需要承担明显的模式重放成本。某些带过滤的向量与 Sparse GRAM 路径需要显式边界或项目侧变通。

这些限制是有用证据，而不是失败的演示。当外部项目既能展示删掉了什么代码，也能展示仍需编写什么策略时，框架才开始变得可信。

最重要的结果是架构性的：GlossWise 可以继续做一个术语产品。它的中心对象是工作区绑定服务，领域只声明一次，每个界面都是这个所有者之上的适配器。HeavenBase 让这种普通形态可以跨越存储与智能体边界。

<br />

## 10. 试用 GlossWise

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
python -m pip install "git+https://github.com/Magolor/GlossWise.git"
glosswise setup '["en","zh"]'
glosswise ws get
```

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

<br />

## 摘要

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

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [实体](/zh/features/entities) - 定义共享领域模型
  * [后端](/zh/features/backends) - 路由字段并检查执行证据
  * [扩展](/zh/features/extensions) - 发布一个外部模块文件夹
  * [工具集](/zh/features/toolkits) - 构建 profile 限定的智能体工具
  * [LLM 概览](/zh/features/llm/overview) - 解析可见的模型预设
  * [GitHub 上的 GlossWise](https://github.com/Magolor/GlossWise) - 阅读完整产品与测试
</Tip>

<br />