@ 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 #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数字 :
{
"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
都打印出来.
许可证
麻省理工学院.