# OpenGlyph(开放古文字)使用说明 · 写给 AI 助手 > **给人看的一句话**:把这份说明交给你常用的 AI,再对它说:"请按这份说明,一步步带我使用 OpenGlyph。"能上网的 AI,直接把链接 https://openglyph.cn/ai-guide.md 发给它;不能上网的,把全文粘贴进对话框,或者上传这个文件。 > > 适用于 openglyph.cn 网站(2026 年 10 月版)和 guwenzi-tools 0.5.1,最新版本见 https://openglyph.cn/ai-guide.md 。命令细节以 `guwenzi-tools --help` 和 `guwenzi-tools agent guide --plain` 的实际输出为准。 --- ## 0. 给 AI:先读这一段 用户把这份说明交给你,是想让你带他用上 OpenGlyph。他可能不熟悉电脑,也不熟悉 AI。请这样做: 1. **一次只讲一步。** 说清楚点哪里、输入什么,然后等用户回复"好了"或发来截图,再讲下一步。 2. **用界面上的原文指路。** 按钮名照抄并用「」括起来,例如「开始研究 ↑」。少用术语,非用不可时顺带解释一句。 3. **先弄清你自己处在什么环境**(见第 2 节),再选路线。你自己能做的事,不要推给用户;你做不到的事,不要假装做了。 4. **只说做过、看到的事。** 没运行过的命令,不要说"已完成";看不清的字,不要猜。 开场时,先用你自己的话问用户三件事: - 想做什么? - ① 读懂一份古文字资料(论文、简帛、金文图版等)里的某几页; - ② 查清某一个字的字形; - ③ 给电脑里打不出来的字"造字",排成能打印、能复制的文档。 - 有没有 OpenGlyph 账号? - 资料是什么格式(PDF、图片、Word……),存在电脑上还是手机上? ## 1. OpenGlyph 是什么(可以照这段向用户解释) OpenGlyph(开放古文字,https://openglyph.cn )是为古文字研究准备的资料空间和工具服务,能做三件事: - **保存资料**:存放文献原件,按专题整理,写研究笔记。 - **读文献**:提取原文、页面原图和单字原图;遇到疑难字,可以拿图片到字库里找相似字形。 - **造字和排印**:字库里没有的字,可以用现成部件拼出来,生成真正的字体文件(OTF/TTF),再把释文排成可编辑、可复制的 Word / HTML / PDF。 要提醒用户的边界:工具只负责保存证据、检索和排版,**不替人下结论**。机器给出的转写和相似字形,都要研究者自己核对。 ## 2. 先判断你在哪种环境,再选路线 | 你的情况 | 怎么判断 | 走哪条路线 | |---|---|---| | 普通聊天框,不能运行代码 | 你没有执行代码或命令的工具 | **A:带用户使用网站上的「研究 Agent」** | | 网页端沙箱:能运行 Python 和命令,并且能上外网(如 Kimi 等的智能体/沙箱模式) | 运行下面的联网自检,结果是"能连上" | **B:你在沙箱里装好工具,用户只需在网站上点一次授权** | | Coding agent:在用户自己的电脑上运行(Claude Code、Codex、Kimi CLI、Qwen Code、Cursor 等) | 你能在用户电脑上执行终端命令 | **C:在用户电脑上安装、授权、装 skill** | 联网自检(路线 B、C 用): ```bash python3 -c " import urllib.request, urllib.error try: urllib.request.urlopen('https://openglyph.cn/gateway/health', timeout=15); print('能连上') except urllib.error.HTTPError as e: print('能连上(HTTP', e.code, ',未登录时出现属正常)') except Exception as e: print('连不上:', e)" ``` 如果显示"连不上",说明这个沙箱不能访问外网,请改走路线 A。 三条路线都需要先有 OpenGlyph 账号(见第 3 节)。 ## 3. 共同的第一步:注册账号 1. 目前**只能凭邀请码注册**。邀请码由站点管理员发放;用户手里没有的话,请他联系把这份说明发给他的人。 2. 让用户打开 https://openglyph.cn/register/ ,填入邀请码、邮箱和密码,完成注册。以后从 https://openglyph.cn/login/ 登录。 3. 额度:网站上的「研究 Agent」会产生模型费用,内测账号**累计有 30 元体验额度**,不按月重置;可以在「账号与额度」里查看。路线 B、C 由你(AI)自己读图、做判断,只调用网站的工具服务,不消耗这笔模型额度。 **绝不向用户索要 OpenGlyph 密码。** 注册、登录和授权,都由用户自己在网站页面上完成。 ## 4. 路线 A:普通聊天框 → 带用户用网站的「研究 Agent」 网站工作台里有一个研究 Agent(模型固定为 kimi-k3),能看图、读页、查字,也能为资料里的生僻字造字,并排出可编辑的文档。你的任务是带用户把任务交给它,再帮他看懂结果。网页在手机上也能用。 ### 4.1 操作步骤(每一步都等用户确认后再继续) 1. 打开 https://openglyph.cn/workspace/ 并登录。 2. 选择资料: - 新资料:在输入框旁点「上传新文件」。PDF、图片、Word、PPT、纯文本都可以。 - 以前传过的资料:点「+ 选择资料」,在「选择本次可访问的资料」里勾选,再点「使用这些资料」。 - 上传只是保存原件;点了「开始研究」之后,资料才会交给模型处理。 3. 在输入框里写任务。可以先点「读懂这一页 ↗」或「查清这个字 ↗」自动填入示例,再按需修改;也可以由你替用户写好(见 4.2)。 4. 勾选输入框下方的"同意将本次选定资料交给模型、字形服务与隔离云沙箱处理……"。勾选之前先和用户确认这份资料可以交给云端处理,尤其是未发表的稿件。远端副本不会自动删除,需要管理员另行清理。 5. 点「开始研究 ↑」。如果按钮显示「加入队列」,说明前面还有任务,排队等待即可。 6. 等待结果: - 任务在服务器上运行,关掉网页也不会中断,之后回到同一个会话就能看到。 - 页面会显示进度;想中止就点「停止任务」。 7. 查看成果:完成后,会话下方会出现原图、HTML、PDF 和证据记录,可以预览或下载。要开始新的任务,点「+ 新的研究」。 ### 4.2 帮用户写任务描述 写清楚这五件事: 1. **页码**:指 PDF 文件里的第几页(文件页序),不是书上印的页码。两者不同时都写上,例如"PDF 第 12 页(书上第 108 页)"。 2. **范围**:整页、某一段,还是某几个字。 3. **排版方向**:竖排的资料要写明"竖排,从右往左读"。 4. **想要什么成果**:原文转写、逐字照原排录入、释读解释、原图对照,或者可编辑的 Word / PDF / HTML。 5. **特别要求**:例如"生僻字不要换成近似字,无编码的字要造字""疑字标为待核,不要猜"。 可以直接套用的任务模板: - **读一页**:「请阅读所选资料 PDF 第 3 页(书上第 57 页),竖排从右往左。先给出原文转写,再解释论证;疑字标为待核,附原图证据,并导出 HTML 和 PDF。」 - **照原排录入**:「请把所选资料 PDF 第 5 页的释文逐字照原排录入。生僻字和无编码的字用造字,正文必须是可复制的文字、不要图片,交付可编辑的 Word 和 PDF,原图对照另附。」 - **查一个字**:「请比较所选字形图片,检索相似形;区分形似、作者释读与字符身份,保存候选和原图,不要猜字。」 ### 4.3 帮用户看懂结果 - 用户可以把下载的 PDF / HTML / Word 或截图发给你。你来说明哪些是原文、哪些是作者释读、哪些是模型推断、哪些标了"待核"。 - 生僻字在别的电脑上显示成方框"□",通常是缺少字体。Word 版一般已经嵌入字体;其他场合要安装成果里附带的字体文件(.ttf / .otf)。 - 要提醒用户:"任务完成""排版成功"都不等于释读正确,请对照原图核对。 - 遇到这两种情况,可以换到能运行代码的 AI(路线 B)或电脑上的 coding agent(路线 C): - 额度用完了; - 要更细的控制,比如凭空设计一个资料里没有的新字。 ## 5. 路线 B:网页端沙箱(能运行代码、能上网) 这条路线由你在沙箱里安装命令行工具 `guwenzi-tools`,读图、判断和调用工具都由你来做。用户只需要: - 把资料文件上传到这次对话(沙箱)里; - 在网站上点一次授权; - 最后下载你交付的文件。 ### 5.1 安装 ```bash python3 --version # 需要 3.10 及以上 pip install -U "guwenzi-tools[fonts]" # 下载慢或失败时,改用国内镜像: pip install -U "guwenzi-tools[fonts]" -i https://pypi.tuna.tsinghua.edu.cn/simple guwenzi-tools --version # 应为 0.5.1 或更高 ``` `[fonts]` 用于造字后的字体合并和排版,不要省略。 ### 5.2 登录授权(关键:放在后台运行) `login` 会先打印一个网址和连接代码,然后最多等 10 分钟,等用户在网页上确认。沙箱里的命令通常要执行完才返回输出,所以**必须放到后台运行**,再读日志: ```bash nohup guwenzi-tools login --no-browser --label "AI网页沙箱" > gwz-login.log 2>&1 & sleep 5; cat gwz-login.log ``` 如果沙箱不保留后台进程,就在 Python 里启动: ```python import subprocess subprocess.Popen(["guwenzi-tools", "login", "--no-browser", "--label", "AI网页沙箱"], stdout=open("gwz-login.log", "w"), stderr=subprocess.STDOUT) ``` 日志里会出现两行: - 「请在浏览器中确认连接:https://openglyph.cn/cli/connect/?code=……」(以日志里的实际网址为准) - 「连接代码:……」 把**网址和连接代码**发给用户,并告诉他: 1. 用手机或电脑浏览器打开这个网址;还没登录 OpenGlyph 的话,先登录。 2. 核对页面上的连接代码,必须和我发给你的**完全一致**。 3. 一致就点「允许并回到终端」;不一致就点「拒绝」。 4. 请在 10 分钟内完成。 用户回复"好了"之后,检查是否成功: ```bash cat gwz-login.log; guwenzi-tools whoami ``` `whoami` 显示出用户的账号,就说明成功了。如果提示过期或被拒绝,重新运行登录命令即可。凭据直接保存在沙箱里,用户不需要、也不应该把任何密钥粘贴到聊天里。 ### 5.3 先通读完整的工具说明 ```bash guwenzi-tools agent guide --plain ``` 这是和当前版本配套的工具规则与命令用法,用工具之前通读一遍;如果和本说明有出入,以它为准。每个命令都可以加 `--help` 查看参数。 所有命令都会把结果存进 `--output` 指定的目录:完整结果在 `result.json` 里,图片在 `assets/` 下。终端只输出 JSON 摘要,不会输出图片本身。 ### 5.4 常用任务 **① 查一个字的字形和异体** ```bash guwenzi-tools glyph lookup 旣 --output work/lookup-旣 ``` - 打开 `result.json` 里 `contact_sheet_asset` 指向的图片(在 `assets/` 下),就能看到各个候选字形。 - 每个候选的 `glyph_ref` 可以直接用于造字。 - 加 `--mode parts` 可以查看这个字的部件,以及可编辑的结构模板。 **② 造一个字**(你只选部件和结构,不写笔画) ```bash guwenzi-tools glyph compose --ids "⿱⿰古文字" --output work/compose-1 ``` - **先看预览图**(`result.json` 里 `asset.path` 指向的图)。 - **比例不合适时**,改用 `--structure @tree.json` 指定部件和位置,或者换用部件的变体,例如"字"有专门放在字下部的形体。**不要编写 KAGE 笔画数据**,笔画由服务端生成。`tree.json` 的格式如下: ```json {"op": "⿱", "children": [ {"op": "⿰", "children": [{"glyph": "<古的 glyph_ref>"}, {"glyph": "<文的 glyph_ref>"}], "boxes": [[0, 0, 98, 200], [104, 0, 200, 200]]}, {"glyph": "<字的下部变体的 glyph_ref>"}], "boxes": [[0, 0, 200, 95], [0, 14, 200, 200]]} ``` `boxes` 按 200×200 的字面坐标写成 [左, 上, 右, 下],与 `children` 一一对应;`glyph_ref` 来自 `glyph lookup` 的结果。 - **结果在哪里**:`result.json` 里的 `gwz_code`(形如 `gwz:sha256:……`)是这个字形的永久身份;`print_font` 里有 OTF/TTF 字体文件和映射表(`mapping_asset`)。 - **编码**:没有正式编码的新字,放在字体的私用区(例如 U+E000),**只有配上这套字体才能显示**。没有确凿依据时,不要填 `--unicode-codepoint`。 - **一次造多个字**:用 `guwenzi-tools batch glyph_compose --json @items.json --output 目录`。它会生成一套合并字体,排版时用这套合并字体。 **③ 把含新字的文字排成 Word / HTML** 1. 把正文写进 `body.txt`。新字的位置写成 `⟦gwz:sha256:……⟧`,也就是把 compose 返回的 `gwz_code` 放在 ⟦ ⟧ 中间;普通字照常输入。 2. 写 `manuscript.json`(文件路径相对于 manifest 所在的目录): ```json {"title": "排印正文", "sections": [{"heading": "正文", "text_path": "body.txt"}], "fonts": [{"font_path": "work/compose-1/assets/<字体文件名>.otf", "mapping_path": "work/compose-1/assets/<映射表文件名>.json"}]} ``` 字体和映射表的文件名,在 compose 的 `result.json` → `print_font` → `otf_asset` / `mapping_asset` 的 `path` 里。 3. 运行: ```bash guwenzi-tools typeset manuscript.json --output 交付 ``` 会得到:可编辑的 Word(已嵌入字体)、HTML(已嵌入字体)、TXT,以及字体和映射表的 ZIP 包。 - **竖排**:在 section 里加 `"writing_mode": "vertical-rl"`。只有 HTML 会竖排,Word 仍是横排。 - **多个新字**:把各自的字体都列进 `fonts`,或者直接用合并字体。程序会统一重新编码,不要手工拼接 U+E000。 - **要 PDF**:沙箱装有 WeasyPrint 的话加 `--pdf`;否则请用户用浏览器打开 HTML,再「打印 → 存储为 PDF」。 **④ 读一页文献**(前提:你能查看沙箱里的图片) ```bash guwenzi-tools document open 文献.pdf # 上传,得到 document_id guwenzi-tools page image 3 --output work/p3 # 第 3 页(PDF 文件页序)的原图和原文字层 ``` - 原生 PDF 会附带原文字层;扫描件只有图像,需要你看图转写。 - **疑难字**的处理顺序: 1. 取出单字图:`glyph detect <页面的 asset_id> --output work/det` 检测单字框;或者用 `crop --box 左 上 右 下 --output work/crop`,按原图像素坐标裁切。 2. 按图找相似形:`glyph search <单字的 asset_id> --output work/search`。 3. 看过候选图后,用 `glyph select c3` 选定一个。 4. 都不像,就用 `glyph register ` 给这张原图登记一个永久身份。 - **多页**:`guwenzi-tools document prepare 文献.pdf --pages 1-3 --output work/doc`。中断后加 `--resume` 接着跑。 **你必须能查看沙箱里的图片,才能做识字工作。** 如果看不到图片,就不要转写或判断字形。这时可以把图片交给用户看,或者建议他改用路线 A 的网站研究 Agent。 ### 5.5 交付文件 用你所在平台的文件下载或附件功能,把成果交给用户:Word、HTML(或 PDF),以及字体和映射表的 ZIP 包。同时告诉用户:生僻字要配上这套字体才能正常显示;Word 版已经嵌入字体,可以直接打开。 ### 5.6 收尾(必须做) ```bash guwenzi-tools logout ``` 这条命令会注销沙箱里的凭据。网页沙箱属于第三方环境,用完就要注销。用户也可以在网站的「账号与额度」→「已连接的 CLI」里自己注销。 ## 6. 路线 C:Coding agent(用户自己的电脑) 基本和路线 B 相同,区别有下面几点: 1. **安装**(建议装进虚拟环境): ```bash python3 -m venv ~/.venvs/openglyph && source ~/.venvs/openglyph/bin/activate pip install -U "guwenzi-tools[fonts]" # 下载慢就加 -i https://pypi.tuna.tsinghua.edu.cn/simple ``` Windows 改用 `py -m venv %USERPROFILE%\.venvs\openglyph` 和 `%USERPROFILE%\.venvs\openglyph\Scripts\activate`。 2. **登录**:`guwenzi-tools login` 会自动打开浏览器,用户核对代码后点「允许并回到终端」。如果你的命令有超时限制,就照 5.2 的方法放到后台运行,再读输出。 3. **安装 skill**(之后你会自动遵守工具规则): ```bash guwenzi-tools agent install-skill --directory ~/.claude/skills/guwenzi-remote # Claude Code guwenzi-tools agent install-skill --directory ~/.codex/skills/guwenzi-remote # Codex ``` 没有 skill 机制的工具:每次开工前运行一遍 `guwenzi-tools agent guide --plain`,或者把它的输出存进该工具的规则文件(例如项目里的 AGENTS.md)。 4. **文件位置**:文件直接保存在用户电脑上。完成后告诉用户文件存在哪里,Word / HTML 可以直接打开。 5. **凭据**:本机的凭据可以保留,下次直接用;不再使用时运行 `guwenzi-tools logout`。 ## 7. 必须遵守的规则 **诚信** - 工具不认字。转写和判断来自你(前提是你真的看过图)或研究者。看不清、没把握的字标"待核"或"未识",不要拿一个熟字顶替。 - 字库检索的相似度只用来排序,不是"就是这个字的概率"。字库里的字形名称和 Unicode 编码,也不能证明原形就是这个字。 - 以下几样是不同层面的东西,不要互相替代:原图、Unicode 编码、字体私用区地址(PUA)、`gwz:` 身份、作者释读。 - 不做繁简转换,也不做 Unicode 规范化。 - "任务完成""排版成功""核对通过(pass)",都不等于学术结论成立。 **安全与隐私** - 不索要密码,不让用户粘贴任何令牌。授权只通过网站上的「允许并回到终端」完成。 - 只让用户批准你刚刚发给他的那个连接代码;页面上的代码对不上,就点「拒绝」。 - 上传之前,先和用户确认资料可以交给云端处理,因为远端副本不会自动删除。 - 在第三方沙箱里用完,执行 `guwenzi-tools logout`。 **稳妥操作** - 提交后不确定有没有成功时,不要重复提交。用 `guwenzi-tools status --wait --output <原来的目录>` 查看回执,并接着下载结果。 - 服务繁忙(HTTP 429)时,等一两分钟再手动重试,不要写循环反复提交。这项服务同一时间只能处理很少的任务。 ## 8. 常见问题 | 现象 | 处理办法 | |---|---| | pip 安装很慢或失败 | 加 `-i https://pypi.tuna.tsinghua.edu.cn/simple`(或阿里云镜像 `https://mirrors.aliyun.com/pypi/simple/`) | | Python 版本低于 3.10 | 换用更新的 Python 或其他环境 | | 连不上 openglyph.cn | 沙箱可能不能上外网:换成能联网的模式,或改走路线 A | | login 等待超时、提示过期 | 重新运行登录命令,10 分钟内在网页上确认 | | 提示 `login_required` 或 401 | 凭据失效或已注销,重新运行 login | | 下载结果时网络中断 | 用 `status --wait --output <同一个目录>` 续传,不要重新提交 | | 生僻字显示成方框"□" | 缺少字体:Word 用交付的嵌入字体版本;其他场合安装附带的 .ttf / .otf | | 网站按钮显示「加入队列」 | 前面有任务在运行,排队即可;关掉网页不影响 | | 网站提示额度不足 | 在「账号与额度」里查看;内测账号累计 30 元 |