@geml/geml

中文文档
1.13.1发布于 2026/11/10MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 2147

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

中文使用文档
文档目录9 节
  1. 安装
  2. 国 际
  3. 选择器
  4. MCP 服务器
  5. 克劳德桌面
  6. Claude 代码/ CLI 客户端
  7. 图书馆
  8. 文档
  9. 许可证

GEML

@ 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 侧车.

尝试格式 游乐场 没有安装。 完整投出、光谱和格式比较在 仓库。 。 。 .

安装

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。 。 。 .

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

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 §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默认值 -1it: 相接点 返回更改的内容, 复活 删除块( 放置) 由其旧邻居,或 --append编号 :--before编号 :--after),或 删除 块 这当时并不存在。 所以每个前向编辑都有反向:

转发编辑撤销
set #idrevert #id (口响)
delete #idrevert #id (重现)
add #idrevert #id (撤走)——或 delete #id
rename #old #newrename #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数字 :

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

Claude 代码/ CLI 客户端

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

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。 。 。 .

图书馆

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 定义侧车的配置文件, ,格式比较在 仓库。光谱本身 以 GEML 写成(GEML-spec.geml并解析每一次测试.

释放之间的变化: CHANGELOG.md。 。 。 . 解析器和规格版本独立—— geml --version --json 都打印出来.

许可证

麻省理工学院.

版本与发布记录

@geml/geml 共发布 59 个版本,首次发布于 2026/06/29;过去 12 个月发布了 59 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.13.1latest2026/11/105 天前
1.13.02026/10/2720 天前
1.12.62026/10/1630 天前
1.12.52026/10/091 个月前
1.12.42026/10/081 个月前
1.12.32026/10/051 个月前

关于 @geml/geml 的常见问题

@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 和提交记录判断。