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/1-writing.md），然后创建 .typ 文件。
  • 每次编辑 .typ 后，如果 typstyle 可用，请按照下方的编辑后格式检查进行检查。
• 编辑现有内容：
  • 找到目标文本并进行修改；必要时对照参考文档确认语法（docs/reference/index.md）。
  • 每次修改 .typ 文件后，请按照下方的编辑后格式检查进行检查。
• 格式与样式：
  • 查阅样式指南（docs/reference/language/styling.md），了解 set rule、show rule、选择器和转换。
  • 保持视觉风格一致：新的版式、图形、表格和绘图必须沿用文档现有的字体、颜色和排版层级（除非另有指示）。应保持内部一致性（相同函数使用相同的字号和颜色）。

文档

• 入门指引：docs/overview.md 提供高层次介绍，docs/reference/index.md 介绍参考文档结构，docs/tutorial/index.md 介绍教程顺序。
• 教程：docs/tutorial/1-writing.md 介绍基础标记、函数、标签、引文和数学；docs/tutorial/2-formatting.md 介绍 set 规则、页面设置、标题和文本格式；docs/tutorial/3-advanced.md 介绍模板、show 规则和更复杂的样式；docs/tutorial/4-template.md 介绍可复用模板和包。
• 语言语法：docs/reference/language/syntax.md 介绍标记、数学和代码模式、注释、转义及标识符。
• 语言脚本：docs/reference/language/scripting.md 介绍表达式、代码块与内容块、绑定、条件语句、循环、字段、方法、模块、包和运算符。
• 语言样式：docs/reference/language/styling.md 介绍 set 规则、show 规则、选择器和转换。
• 语言上下文：docs/reference/language/context.md 介绍样式上下文、位置上下文、嵌套上下文和编译器迭代。
• 基础：docs/reference/library/foundations.md 介绍基础类型和函数、std、sys.version 和 sys.inputs。
• 文档模型：docs/reference/library/model.md 介绍标题、图表、参考文献、引文、引用、编号、大纲、列表、表格和文档结构。
• 布局：docs/reference/library/layout.md 介绍如何在页面上排列元素：页面、块、盒子、网格、分栏、对齐、间距、变换和测量。
• 文本：docs/reference/library/text.md 介绍文本样式和 text 函数。
• 数学：docs/reference/library/math.md 介绍数学语法、符号、公式、对齐、字体、无障碍功能和数学函数。
• 绘图和媒体：docs/reference/library/visualize.md 介绍形状、图像／图形基元、颜色、渐变、描边和视觉无障碍功能。
• 内省：docs/reference/library/introspection.md 介绍计数器、状态、位置、query 和感知文档的生成内容。
• 数据加载：docs/reference/library/data-loading.md 介绍如何加载和编码外部数据，例如 CSV、JSON、TOML、YAML、XML、CBOR 和原始文件。
• 符号和表情符号：docs/reference/library/sym.md 介绍命名符号和简写；docs/reference/library/emoji.md 介绍表情符号。
• 导出格式：docs/reference/export/pdf.md 介绍 PDF 标准和 PDF 专属功能；docs/reference/export/html.md 介绍 HTML 导出和类型化 HTML；docs/reference/export/bundle.md 介绍多输出包和资源；docs/reference/export/svg.md 和 docs/reference/export/png.md 介绍图像导出。
• 指南：docs/guides/page-setup.md 介绍页面、边距、页眉、页脚、编号和分栏；docs/guides/tables.md 介绍语义表格和表格样式；docs/guides/accessibility.md 介绍语义结构、替代文本、语言、PDF 无障碍功能和导出注意事项；docs/guides/for-latex-users.md 介绍如何将 LaTeX 转换为 Typst。

详细说明

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

探测不确定的行为

• 如果随附文档无法确定运行时或求值行为，请使用探测。
• 按照 docs/reference/language/scripting.md 中的 Typst 脚本说明构造案例。
• 必须进行探测时，优先使用无文件的表达式探测 typst eval，而不是创建临时 .typ 文件。有关系统值，请参阅 docs/reference/library/foundations.md；有关上下文文档查询，请参阅 docs/reference/library/introspection.md。
• 示例：typst eval '1 + 2'

编辑后格式检查

1. 使用 command -v typstyle 检查是否可用。如果不可用，则跳过其余格式检查。
2. 每次修改 .typ 文件后，运行 typstyle --check <file> 检查刚创建或编辑的文件。
3. 如果 typstyle --check 失败，在决定如何处理前，使用 typstyle --diff <file> 检查格式化器将做出的更改。
4. 仅当格式化器的更改只涉及新创建的文件或本任务中由你创建或编辑的代码时，才使用 typstyle -i <file> 应用格式。
5. 如果格式化会改动未触及的既有代码，请停止并询问用户。如果差异涉及你自行修改之外的内容，或者无法有把握地确认所有格式更改仅涉及你自行修改的内容，请先询问。

快速语法参考

重要区别

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

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

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

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

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

样式规则：set 与 show

• set：设置规则，用于配置元素函数的可选参数（样式默认值作用于当前代码块或文件）。
• show：展示规则，用于指定选定的元素，并应用 set 规则，或转换／替换元素输出。
• 常见样式使用 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/language/styling.md，了解 set 规则、show 规则，以及作用于代码块或内容块的样式。
• 脚本编写：使用 Typst 的脚本功能（docs/reference/language/scripting.md）实现自动生成。
• 数学与可视化：有关公式和图表，请参阅 docs/reference/library/math.md 和 docs/reference/library/visualize.md。

对于大型项目

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

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

故障排除

缺少字体警告

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

找不到模板／包

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

• 在 Typst Universe 中核实准确的包名称和版本。
• 检查 @preview/package:version 语法是否有拼写错误。有关包导入语法，请参阅 docs/reference/language/scripting.md；有关 Typst Universe 示例，请参阅 docs/guides/for-latex-users.md。

编译错误

常见修复方法：

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