typst-author

typst-author 技能

概述

此技能可帮助 Agent 生成、编辑和分析 Typst 文档。它提供快速入门示例、详细工作流，以及完整 Typst 文档（指南、教程、参考资料）的链接。

最简文档示例

#set document(title: "My Document", author: "Author Name")
#set page(numbering: "1")
#set text(lang: "en")

// Enable paragraph justification and character-level justification
#set par(
  justify: true,
  justification-limits: (
    tracking: (min: -0.012em, max: 0.012em),
    spacing: (min: 75%, max: 120%),
  )
)

#title[My Document]

= Heading 1

This is a paragraph in Typst.

== Heading 2

#lorem(50)

工作流

• 创建新的 Typst 项目：以上面的“最简文档示例”为起点。浏览教程，了解基础知识（docs/tutorial/writing-in-typst.md），然后创建 .typ 文件。每次编辑 .typ 文件后，如果 typstyle 可用，请按照下面的编辑后格式检查进行检查。
• 编辑现有内容：找到目标文本并进行修改；必要时对照参考资料确认语法（docs/reference/）。每次修改 .typ 文件后，请按照下面的编辑后格式检查进行检查。
• 格式与样式：查阅样式指南（[docs/reference/styling.md](docs/reference/styling.md），了解 set rule、show rule 和自定义主题。

文档

• 语法与基础：docs/reference/syntax.md
• 样式与 show/set 规则：docs/reference/styling.md
• 脚本与运行时行为：docs/reference/scripting.md
• 页面设置与表格：docs/guides/page-setup.md 和 docs/guides/tables.md
• 面向任务的写作帮助：docs/tutorial/writing-in-typst.md、docs/guides/*.md 和 docs/reference/**/*.md

详细说明

1. 优先级最高：以本地文档为准。你关于 Typst 的内部训练数据可能已经过时或存在幻觉。生成代码前，务必对照本地 docs/ 文件夹核实函数名称、参数和语法。
2. 使用本地文件搜索和打开工具，阅读上述路径中的相关文档。
3. 语法和参考资料问题请查阅本地文档。根据随附文档核实语法、函数名称、参数和参考行为。只有在查阅文档后仍不清楚运行时或求值行为时，才运行最小化 Typst 探测。
4. 根据用户请求生成或修改 .typ 源文件。
5. 对本轮创建或编辑的每个 .typ 文件运行下面的编辑后格式检查。
6. 如果创建或编辑了 .typ 文件，或者用户明确要求验证（且允许使用工具），请在完成格式处理后使用 typst compile 进行验证。
7. 总结涉及的文件和结果。仅在用户提出要求或无法直接编辑时提供完整的 .typ 内容；也可以选择提供渲染预览（PDF/HTML）。

探测不确定的行为

• 如果随附文档无法确定运行时或求值行为，请进行探测。
• 按照 docs/reference/scripting.md 中的说明，使用 Typst 脚本模拟该情形。
• 必须探测时，优先通过 stdin 进行无文件探测，而不是创建临时 .typ 文件。使用 metadata(...) <probe> 暴露值，并通过 typst query - "<probe>" --field value --one 读取。参见 docs/reference/introspection/query.md 和 docs/reference/introspection/metadata.md。
• 示例：printf '#metadata(1 + 2) <probe>\n' | typst query - "<probe>" --field value --one

编辑后的格式检查

1. 使用 command -v typstyle 检查 typstyle 是否可用。如果不可用，则跳过其余格式检查。
2. 每次修改 .typ 文件后，都对刚创建或编辑的文件运行 typstyle --check <file>。
3. 如果 typstyle --check 失败，先使用 typstyle --diff <file> 检查格式化变更，再决定如何处理。
4. 只有当格式化变更仅涉及新创建的文件，或当前任务中由你创建或编辑的代码时，才使用 typstyle -i <file> 应用格式。
5. 如果格式化会更改未触及的现有代码，请停下来询问用户。如果差异涉及你自己的编辑范围之外的内容，或者你无法确信每项格式化变更都仅涉及你编辑的内容，请先询问，不要格式化。

语法速查

关键区别

• 数组：(item1, item2)（圆括号）。参见 docs/reference/foundations/array.md。
• 字典：(key: value, key2: value2)（带冒号的圆括号）。参见 docs/reference/foundations/dictionary.md。
• 内容块：[markup content]（方括号）。参见 docs/reference/foundations/content.md。
• 没有元组：Typst 只有数组。

哈希符号的用法（标记语言与代码）

• 在标记语言或内容块中，使用 # 开始代码表达式，以区分代码和文本。对于生成内容的函数调用和标记语言中的字段访问，这是必需的：#figure[...]、#image("file.png")、text(...)[#numbering(...)]。
• 在代码上下文中（参数列表、代码块、show 规则主体）不要使用 #。示例：#figure(image("file.png"))（image 前不加 #）。
• 参考：docs/reference/scripting.md、docs/tutorial/writing-in-typst.md

// Incorrect (missing # inside content block)
text(...)[(numbering(...))]

// Correct
text(...)[(#numbering(...))]

样式规则：set 与 show

• set：设置规则，用于配置元素函数的可选参数（样式默认值的作用范围限定于当前块或文件）。
• show：显示规则，用于匹配选定元素，并应用设置规则或转换／替换元素输出。
• 通用样式使用 set；选择性或结构性变更（例如 heading.where(level: 1)、标签、文本、正则表达式）使用 show。

// Set rule: configure optional parameters for an element type
#set heading(numbering: "I.")
#set text(font: "New Computer Modern")

// Show-set rule: apply a set rule only to selected elements
#show heading: set text(navy)

// Show transform rule: replace/reshape element output
#show heading: it => block[#emph(it.body)]

应避免的常见错误

• 将内容称为“元组”（Typst 只有数组）。
• 用 [] 表示数组（应改用 ()）。
• 使用 arr[0] 访问数组元素（应使用 arr.at(0)）。
• 在标记语言／内容块中漏写 #（例如，text(...)[numbering(...)] 应写为 text(...)[#numbering(...)]）。
• 在代码上下文中使用 #（例如，在参数列表中写 figure(#image("x.png"))）。
• 混淆内容块 [] 与代码块 {}。
• 访问导入的变量／函数时忘记包含命名空间（例如，使用 color.hsl，而不是单独使用 hsl）。
• 使用 LaTeX 语法（不要使用 \begin{...}、\section 或其他 LaTeX 命令）。
• 臆造环境（例如，不存在 tabular；应使用 table）。

高级功能

• 自定义主题：主题创建方法参见 docs/reference/styling.md。
• 脚本编写：使用 Typst 的脚本功能（参见 docs/reference/scripting.md）进行自动生成。
• 数学与可视化：公式和图表参见 docs/reference/math/ 和 docs/reference/visualize/。

大型项目

处理大型项目时，可考虑将项目组织到多个文件中。

• 使用 #include "file.typ" 将内容拆分到多个文件中
• 相关文档：docs/reference/foundations/module.md

故障排除

缺少字体警告

如果看到“unknown font family”警告，请移除字体设置并使用系统默认字体。注意：字体警告不会阻止编译；文档将使用备用字体。

找不到模板/包

如果导入失败并提示“package not found”：

• 在 Typst Universe 上确认准确的包名称和版本。
• 检查 @preview/package:version 语法中是否有拼写错误。

编译错误

常见修复方法：

• “expected content, found ...”：在需要标记语法的地方使用了代码——请用 #{ } 包裹，或使用正确的语法。
• “expected expression, found ...”：在标记语法/内容块中缺少 #（或 #(...)）。
• “unknown variable”：检查拼写，并确保导入正确。
• 数组/字典错误：检查语法——两者都使用 ()；字典需要 key: value；单元素数组写作 (elem,)。