Guidedog / 文档 0.2.0

错误信息¶

诊断报告应说明问题、标明位置，并给出有用的下一步。Guidedog 将这些信息保存为结构化数据。终端显示增加颜色和源码标记；JSON 保留数据，不含终端装饰。

如何阅读诊断报告¶

UNDEFINED SUBSTITUTION                              rst.substitution.undefined

  guide/page.rst:4: See |logo| here.
                        ^^^^^^

The substitution "|logo|" is not defined.
No output was written.

Add a definition, e.g. ".. |name| replace:: text".

报告始终按以下顺序分为四部分：

标题栏。标题用大写字母说明问题类型；警告和说明分别以 WARNING: 和 NOTE: 开头。右侧显示报告代码，如 rst.substitution.undefined，这是可用于搜索的稳定名称。
位置。显示文件名、行号、源码行，以及问题文本下方的标记。若问题不涉及某一行，如目录缺失或参数错误，只显示路径，或不显示位置。
发生了什么。先解释问题；必要时再说明它对输出的影响，例如本次没有写入任何内容。
如何处理。支持彩色的终端用绿色显示具体建议。如果有多种修复方式，会依次列出，最可能适用的放在前面。

颜色只强调文字已表达的含义。--color=never 关闭颜色；--color=always 则在输出不是终端时也保留颜色。

每条提示都指明下一步¶

Guidedog 对自身消息也遵守这一要求：提示先给出动作（“Add”“Pass”“Set”“Rename”“Run”），再说明对象，如 --budget=MIB、conf.toml 中的 root_doc 或指令选项。tests/hints_test.odin 检查每条可发出的消息；提示为空、重复错误内容，或只说“report this”而不说明报告材料，测试都会失败。另允许两种已指出修正方法的形式：建议（“Did you mean numfig?”），以及无需操作时的“Nothing to do:”和原因。

若问题是 Guidedog 自身的错误，提示会明确说明，并请你提交所运行的命令、导致问题的输入，以及 guidedog --version 的输出。

供程序读取的报告¶

--diagnostics=json 将每条报告作为一个 JSON 对象写入标准错误，每行一个，便于编辑器和持续集成读取：

{"schema":1,"code":"rst.substitution.undefined","severity":"error",
 "title":"UNDEFINED SUBSTITUTION","message":"The substitution \"|logo|\" is not defined.",
 "hint":"Add a definition, e.g. \".. |name| replace:: text\".","path":"guide/page.rst",
 "line":4,"column":5,"end_line":4,"end_column":11,"source":"See |logo| here.",
 "category":""}

此处为便于阅读而折行；实际每个对象占一行。schema 是格式版本，仅字段变化时更新，读取其余内容前应先检查。列号从 1 开始，按 Unicode 标量计数，而非字节或终端格数。source 是完整原始行。终端仅显示错误附近的有限窗口，转义控制字符、测量宽字符后对齐指示符。category 是 suppress_warnings 使用的警告类别，也可为空。

内存不足时¶

内存不足也会生成诊断，不会导致崩溃。分为两种情况：

host.budget（达到内存预算）

构建达到允许持有的内存预算（--budget=MIB，默认 1 GiB）。报告指出步骤；若是模板，还指出申请内存的行。终端中会询问一次：提高预算、改用磁盘工作内存，或停止。其他环境直接停止；可提前用 --budget 或 --memory=disk 选择。提示也会用数字给出预算，例如：

Build again with --budget=256, or with --memory=disk to keep working memory on
disk (slower); or split the work into smaller files.

建议值取“当前持有量加上被拒步骤所需内存的四倍”（该步骤还需保存输出及写入副本）与“旧预算的两倍”中的较大值，向上取整到 64 MiB。当步骤能装入可用内存时，不超过机器当时的可用量；否则提示会明确说明，并先建议 --memory=disk：

Build again with --memory=disk to keep working memory on disk (slower): the step
needs a budget of about 1408 MiB, more than the 900 MiB this machine has free. Or
free that memory and build with --budget=1408, or split the document.

host.memory（内存不足）

系统拒绝了预算允许的内存申请。命令停止，不使用被拒的存储：构建不发布内容，GDS 修改要么全部应用、要么不应用，convert 要么写出整页、要么不写。释放内存或减少线程（-j 1）后重试。发布决定一旦做出，切换输出无需再申请内存，因此拒绝申请不会造成半发布。若构建发现先前未完成的发布，却没有内存规划恢复，就保留现场，交给下次构建。

两种情况都以状态 3 退出。

退出状态¶

每条命令都以以下状态之一结束，脚本可据此区分失败类型：

状态	含义
0	成功。输出已写入；若为构建命令，也已发布。
1	输入有问题：文档错误、策略拒绝（未使用 `--raw` 的原始内容）、文档无法读取，或 `-W`、`--strict` 将警告视为错误。
2	命令用法错误：未知参数或命令、缺失或无效的值，或者 `conf.toml`、`-D` 中的无效设置。
3	达到限制：内存预算（`--budget`）、嵌套深度（`--max-depth`）、节点数（`--max-nodes`）、栈（`--stack-kib`）、源文件过大，或系统无法提供内存。
4	文件或外部程序失败：路径无法读取或写入、文件读取期间发生变化，或者 Typst 无法启动或完成。
5	Guidedog 内部发生错误，报告会请你提交问题。
70	Guidedog 崩溃时，会打印 `GUIDEDOG CRASHED (internal error)`，以及执行的命令、故障和 `guidedog --version` 的输出，并给出报告地址：构建指定的问题跟踪器，或提供该构建的人。构建仅在最后发布，因此崩溃会保留之前的输出。
130	命令被 Ctrl+C 中断，已发布文件保持不变。

无论构建因何失败，上一代输出及构建记录均保持不变。修复问题后重新构建即可。