# @geml/geml 中文文档

规范地址：https://npmcn.com/package/%40geml/geml/

版本：1\.13\.1
npm 元数据更新时间：2026-11-10T10:57:53.290Z
中文译文更新时间：2026-11-16T03:00:35.383Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geml/geml
原文对照：https://npmcn.com/package/%40geml/geml/?lang=original
项目主页：https://geml-spec.github.io/
源码仓库：https://github.com/geml-spec/geml

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.9 MB，117 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-06-29T11:01:49.893Z
- 最新版本发布：2026-11-10T10:57:52.907Z
- 近 30 天下载量：2147（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

按块来读取并编辑长的Markdown而不是由文件来读取——geml list/find/get address any.md,没有转换. 加上GEML,是一种纯文本格式,其中块会携带ID来进行验证的写作,引用检查和每个块的历史. MCP服务器.

## 安装

```sh
npm install @geml/geml
```

也可以使用：`pnpm add @geml/geml`、`yarn add @geml/geml`、`bun add @geml/geml`

## README

![GEML](https://raw.githubusercontent.com/geml-spec/geml/main/docs/assets/logo/geml-logo-light.svg)

# @ geml/ geml (英语)

用于 **GEML 游戏** (总 则 表现标记语言)- **一个格式,两个读者.** 人和人工智能特工 共同写出同一文档:为人们保持清晰可见的纯文本,以及 **可处理、可核查和版本** 为机器.

各种结构化的内容——代码,表格,图表,数学,挂图, 元数据——乘以 **一个** 原始, 输入块 :

```
=== code {#hello lang=python}
print("hi")
===
```

-   **可处理** ——每个区块都可以命名:a `#id`,或内容地址 没有名字的; `geml get` 编号 : `geml set '<selector>'` 读取或补丁一个部分,而不重发整个文件。 块 保留 ~ 590 字节,不管文档增长到什么程度,所以保存只是 文档的大小除以块的大小,并随着文档的产生而增长—— 关于这个 repo 的 自己 规格 (`GEML-spec.geml`,130 KB,截至2026-10-05,即 关于 **220x (中文(简体) )** 上下文不如整个文件的运输.
-   **可核实** ——在构建时检查参考文献(一) `#id` 是一个 错误,而不是一个静默的死链接),解析器释放出一个文档模型JSON 带有 `diagnostics` 阵列,所以代理和CI得到结构化的通过/故障信号.
-   **已版本** —— 说 `geml history` 财务报告和审定财务报表 `geml revert` 抓取并倒转 以正文修改 `.gemlhistory` 侧车.

尝试格式 [游乐场](https://geml-spec.github.io/playground/) 没有安装。 完整投出、光谱和格式比较在 [仓库](https://github.com/geml-spec/geml)。 。 。 .

## 安装

```sh
npm install -g @geml/geml   # global CLI — installs the `geml` command
# or, per project:
npm install @geml/geml      # library + local bin
```

需要22号节点.

## 国 际

CLI是围绕一个问题构建的: 单个代理作者和保持一个 整个 `.geml` 从命令行创建、添加、编辑、删除和复制文件 其它文件中的块 ? 三次测试使指令设置诚实:

-   **完成** ——文件生命的每一步都有动词,所以从不代理 重写整个文件以更改一个块 .
-   **环境学** 很少旗帜,合理的默认, 和管道友好的I/O,所以 多步编辑链而不举行仪式.
-   **一致** ——行为是统一的和可预测的:点出一个目标 `#id` 财务报告和审定财务报表 内容通过它,每个写字都被守护,一个文件被编辑到位,同时 `-` 流来出出出.

指令集借用两个固定模型而不是发明一个 它们相互重叠. **文档是表格**: 块是一行,它的 `#id` 是主键(每个文件独一无二),以及 `[[#id]]`编号 :`[t](#id)`编号 :`[^id]`编号 : `data=#id` 是外国钥匙,所以 `get`编号 :`add`编号 :`set`编号 :`delete` 为: SELECT/INSERT/UPDATE/DEELTE(英语:UPATE). **块也是资源** 在类似URI的地址 (单位:千美元)`file#id`),在操作前命名,即REST将名词放在首位的方式. 两者 模型商定一个小正弦动词集,而不是每个使用例的方法,以及 他们同意“一能”: `set` 财务报告和审定财务报表 `delete` 具有同位素( 删除缺失) id是一个不op, 所以重试是安全的, `add` 没有.

在他们分歧的地方,他们各自覆盖对方无法覆盖的东西。 关系视图名称 诚信规则: 书写守卫是一种带有回滚功能的强制检查 `delete` 仅仅 _警告_ 关于它留下的参照物,是 **推迟** 外国钥匙检查,不是 `ON DELETE RESTRICT`它还解释了 `rename`,动词 最开放的“可以切开”——a **带有分层的初键更新 重写外键**不可减少,因为 `delete` + 键 `add` 将离开每一个 缩写,没有其他内容可以大量重写引用。 HTTP 没有 完全没有这个方法。 REST 视图提供数据库中有意做的事情 不是: 每一个电话都是 **无国籍人** ——没有会话,没有当前文档,没有配置 file,没有环境变量——这就是让我们重审的, 相并相并相并相并相并相接.

两者都以逆向回报. 因为动词是正交的,所以每个编辑都有一个 反向,这样 `revert` 永远不需要知道哪个动词做了改变——它协调了 3起(内容已更改、行缺失、行外) 没有第四个,而 `rename` 这是它自己的反向,不需要历史 都说吧 较宽的RPC形动词集(`replace`, (中文(简体) ), `move`, (中文(简体) ), `merge`, (中文(简体) ), `split`将会 需要一个反动词和一个操作日志来选择一个——一个倒置的引擎 而不是三个分支。 充分理由: [`docs/design/specs/2026-07-24-geml-block-mutation-cli-design.md`](https://npmcn.com/package/%40geml/docs/design/specs/2026-07-24-geml-block-mutation-cli-design.md)。 。 。 .

每个命令都会读取文件路径,或者 `-` 为斯丁。 退出代码 : `0` ok \\fn微软雅黑okay \\fn微软雅黑okay \\fn方正黑体简体\\fs18\\b1\\bord1\\shad1\\3ch2f2f2f}美国海军陆战队 `1` 文档/操作错误 \\ `2` 使用错误.

```sh
geml doc.geml                       # document-model JSON (default --to json)
geml doc.geml --to md|html|geml     # convert; geml notes.md -> GEML
geml list   doc.geml                # CALL FIRST: every block, its address, kind, line range
geml find   "text" doc.geml|dir     # search block CONTENT -> file<TAB>address; exit 1 = no hit
geml get    doc.geml ['<selector>'] # list addressable blocks, or print what the selector matches
geml get    doc.geml '#sec' --intro # a section cuts three ways: --head | --intro | --body
geml set    doc.geml '<selector>' [--head|--intro|--body] [--in F[#src]]   # replace ONE block's content
geml replace doc.geml OLD NEW [--within '<selector>']   # EXPERIMENTAL: literal swap, checked and reported
geml add    doc.geml (--append|--before '<sel>'|--after '<sel>') [--in F[#src]]   # insert a fragment
geml delete doc.geml '<sel>' ['<sel2>' …]  # remove every block the selectors name
geml rename doc.geml '#old' '#new'        # rename an id + every reference to it
geml revert doc.geml '#id' [--rev -1]     # undo a block: splice / resurrect / remove
geml check  doc.geml [--root <dir>]       # validate only: diagnostics + exit code (--json for the array)
# --root works on every verb above, not just check. A write is refused when the result
# would not parse, so a document whose ../sibling.md links resolve only from the repo
# root needs --root to be editable at all. The MCP server passes its own root for you.
geml history <save|get|restore|verify> doc.geml [...]   # .gemlhistory version sidecar (get = list revisions, or print one)
geml codemap <build|verify|render|serve|refresh|find>   # your codebase's call graph as GEML docs
geml mcp    --root <dir> [--graph <dir>]  # serve documents (+ the code graph) over MCP
geml --help | --version             # --version --json prints {"parser","spec"}
```

代理环 : `geml get` a 区块 `set`编号 :`add`编号 :`delete`编号 :`rename` it `geml check` → `geml history save` ——小,准确,可核查的编辑.

### 选择器

`get` 财务报告和审定财务报表 `set` 选择同一选择器,即 **过滤到块上**数字 :

| 选择器 | 匹配 |
| --- | --- |
| _(已发出)_ | 没什么.. `get` **列表** 每个可地址的块,每行一个, 按其最短的独特地址 |
| `#id` | 那个街区。 标题标识处理它 **全节** |
| `'## Heading'` | 从文档中复制出来并解析为 id 的标题行 |
| `'=== note'` | **每个** `note` 区块 - 0.N |
| `'=== note@a3f9c1d2'` | 一个街区由CAURNT, 对于没有 `#id` |
| `'@a3f9c1d2'` | 相同, 类型检查已取消 |

`get` n 匹配时使用 N 内容的回答( 文件顺序, 计数为 stderr ); `set` 写入 one 块, 因此拒绝匹配多个块的选中器( exit 2) 每个候选人的独特地址。 一节通过三种方式: `--head` 这是 航向线, `--intro` 其开放区域——它下的一切,直到第一个 副标题——和 `--body` 里面的一切,所以说 `--body` 总是包含 `--intro`,当部分没有子标题时,则等于。 全部三个 往返旅行—— `geml get f X --body | geml set f X --body` 离开文件 字节相同——和 `--intro` 区域开口的编辑方式没有 把它的分节放在上下文中。 一个街区没有介绍,一个要求是一个 使用错误而不是安静地倒回身体.

`replace` 当确切的旧文本已经知道而一无所有时, 是廉价的路径 需要读取 —— 六个位置的版本字符串, 重新命名名词 。 就是这个 gEML 可以跳动的操作 `sed` 直截了当地而不是模仿: 两个短弦,但结果 在它着陆前重新分解, 块它 触摸着它会给你起名,它就在 `.gemlhistory` 还原。 换一个 LITERAL,从来不是一个图案,并拒绝一个可以重命名为id的交换——即: `geml rename`,这也修正了引用. **警告说 撤销**; 在其上没有任何无法改变的东西.

写作会破坏文件 绝不只是因为它 移除一些东西。 进行一个掉出块的替换 被丢弃的块在 stderr 上命名 —— 未命名的块被计算, 引用左边 据报 `geml revert` 作为回来的路。 这是同样的立场 `delete` 因此删除内容有一条规则而不是两条规则,没有区域 因为里面有些东西碰巧带了个身份证明 所以变得无法编辑 这个 上方的来回没有减少任何东西: 块在您发送的文本中回来了 .

A 类 `@<hex>` **内容地址** 是该区SHA -256的第8个六分之一 自己的文本(行结束为 LF 的正则,无后端新行),其下 `~1`, (中文(简体) ), `~2`. 区分字节相同的块。 读出来 `geml get doc.geml` —— 说 每个区块都印有 `#id`作为内容衍生的 地址 **当块改变时会停止** 而不是1号出口失败 而不是无声地谈论不同的块:它作为先决条件加倍。 那个 也意味着 `set` 通过一个打印 Stderr 上的新地址。 确切的散列 输入在 [选择器设计 doc](https://npmcn.com/package/%40geml/docs/design/specs/2026-08-04-geml-get-set-selector-design-change.md) §3.4 所以第二个执行计算出相同的值.

改划是一个条目—— `geml <file> [--to json|html|md|geml]`; 输入 推定格式(`--from` 覆盖 > 扩展 > GEML,目标为 `--to` (默认:GEML → JSON,Markdown → GEML),并 `-o` 命名输出路径.

`set` 财务报告和审定财务报表 `add` 取其内容从 `--in F` (F的块,其编号等于 目标, `--in F#src` (F区块) `#src`),或 stdin (raw 字节). `set` **替换 整块** 并且将内容的id与目标正常化——这样你就可以叉出 任何块进入此槽时, 无需手动编辑其id(`--head` 交换只是 头条, `--body` τō砰. `add` **插入一个片段** (一个或多个) 街道,或裸露的流言 `--append`,或 `--before`编号 :`--after` 选择器命名 一块,保留内容本身的id(拒绝相撞). `delete` 删除每个块的选取器名称—— id、内容地址、行 区域、 标题行或过滤器; 选择者将使用 注释. `rename` 重写出一个id的申报和每一个引用.

变化(`set`编号 :`add`编号 :`delete`编号 :`rename`写 **整个最新文档**数字 : 输入为文件时的位置,或到 **静态** 当输入是 `-`· ; `-o` 重定向写入( r)`-o -` 强制stdout),故将管道进行干净的编辑. 每个字 被保护——如果会破坏文件或掉入id,则重新解析并拒绝 (左侧的参考文献) `delete` 是一种警告,而非拒绝; `geml check` 以后再标上旗来).

撤销是 `revert`,将一个区块与过去的修订相协调(`--rev`默认值 `-1`it: **相接点** 返回更改的内容, **复活** 删除块( 放置) 由其旧邻居,或 `--append`编号 :`--before`编号 :`--after`),或 **删除** 块 这当时并不存在。 所以每个前向编辑都有反向:

| 转发编辑 | 撤销 |
| --- | --- |
| `set #id` | `revert #id` (口响) |
| `delete #id` | `revert #id` (重现) |
| `add #id` | `revert #id` (撤走)——或 `delete #id` |
| `rename #old #new` | `rename #new #old` (自相倒转 |

`revert` 读取 `.gemlhistory` 侧车,所以 `set`编号 :`delete`编号 :`add` 撤销需要一个 先前 `geml history save`· ; `rename` 它本身是逆向的,不需要历史.

A 类 **标题** `#id` 处理整个问题 **节** ——走行经 在同一或更高水平的下一个标题前的行线上——因此 标题下为块-可编辑,无附加语法. Spans 重叠: 嵌入部分的块保留自己的标识, a `set` 打开 将其中之一扔下的部分被警卫拒绝. `get --json` 编号 标题覆盖与生间相同的内容: 一节信封 `{kind:"section", id, level, blocks:[heading, …its section's blocks]}` 联合国 块/脚注 id 仍然打印它的单一模型节点. `--head` 缩进 `get`编号 :`set`编号 :`revert` 至任何 id 头行——一个头行,或打入 块打开了栅栏线,所以代理重命名标题或编辑块的 属性(caption, compute,.)而不接触身体。 《公约》:保留 文档标题在 `=== meta` (单位:千美元)`title = "…"`),不是H1——孤军奋战上层 `#` 部分是整个文档,即它确实是一个标题.

## MCP 服务器

这个软件包包括一个标准模式上下文协议(MCP)服务器,它暴露出GEML文档CRUD操作. 它在当地运行,并支持Windows,macOS,和Linux.

要连接到一个与MCP兼容的客户端,请提供 `npx` 执行命令并指定 `--root` 参数(包含您的目录) `.geml` 文档).

### 克劳德桌面

添加到您的 `claude_desktop_config.json`数字 :

```json
{
  "mcpServers": {
    "geml": {
      "command": "npx",
      "args": [
        "-y",
        "@geml/geml@latest",
        "mcp",
        "--root",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}
```

### Claude 代码/ CLI 客户端

运行以下命令以添加服务器 :

```sh
claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs
```

下方有一个代码图 `--root` (单位:千美元)`geml codemap build`),同一服务器也 服务四只只读 `geml_codemap_*` 工具。 每个工具和选项: [`docs/mcp-guide.md`](https://github.com/geml-spec/geml/blob/main/docs/mcp-guide.md)。 。 。 .

## 图书馆

```js
import { parse, serialize, renderHtml, gemlToMd, mdToGeml } from "@geml/geml";

const doc = parse(src);                 // { kind:"document", children, ids, diagnostics }
const ok  = !doc.diagnostics.some(d => d.severity === "error");
const html = renderHtml(doc);           // one self-contained HTML string
const md   = gemlToMd(doc).md;          // GitHub-Flavored Markdown (lossy)
const geml = mdToGeml(markdown).geml;   // the inverse
const canonical = serialize(doc);       // GEML text; parse(serialize(parse(x))) is stable
```

`parse(src, { resolveDoc })` 允许交叉文档引用检查-通过 a 通过路径返回文件源的函数(或) `null`) (中文(简体) ).

## 文档

完整的规范规格 `geml-history/v1` 定义侧车的配置文件, ,格式比较在 [仓库](https://github.com/geml-spec/geml)。光谱本身 以 GEML 写成(`GEML-spec.geml`并解析每一次测试.

释放之间的变化: [`CHANGELOG.md`](https://github.com/geml-spec/geml/blob/main/CHANGELOG.md)。 。 。 . 解析器和规格版本独立—— `geml --version --json` 都打印出来.

## 许可证

麻省理工学院.

## 常见问题

### @geml/geml 是什么？

按块来读取并编辑长的Markdown而不是由文件来读取——geml list/find/get address any\.md,没有转换\. 加上GEML,是一种纯文本格式,其中块会携带ID来进行验证的写作,引用检查和每个块的历史\. MCP服务器\.

### 如何安装 @geml/geml？

在项目目录运行 npm install @geml/geml，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 geml，可以用 npx geml 直接运行。

### @geml/geml 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @geml/geml 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @geml/geml 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @geml/geml 可以商用吗？

@geml/geml 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @geml/geml 的下载量有多少？

根据 npm 官方下载统计，@geml/geml 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,147 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @geml/geml 还在维护吗？

最新版本 1\.13\.1 发布于 2026/11/10（5 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2026/06/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

