lightest-typst

name	lightest-typst
skill_id	typst_writing_skill
controlled	true
description	当用户要写或改 Typst 源文件（.typ）、维护含 main.typ 的写作项目、排查 Typst 编译报错、对章节做 apply_patch，或在 Typst 数学模式写公式时使用；覆盖写作项目创建、writing_compile_check 与 read 验版。**触发**：Typst、.typ、main.typ、编译失败、writing_compile_check、apply_patch、数学 $...$（禁止 LaTeX 反斜杠）。**加载**：`skills_fetch(skill_ids=["typst_writing_skill"])` → read `references/writing-project-guide.md`。**勿用**：研报双栏 / Fletcher / CeTZ / 三线表成稿 → `lightest_typst_report_skill`；报告正文润色 → 先 `lightest_writing_skill`；用户明确 LaTeX 顶会稿 → `lightest_latex_skill`。
references	["references/writing-project-guide.md"]

LighTest Typst 学术写作（内置 Skill）

官方内置：连接本地项目时同步到 .lightest/skills/lightest-typst/；扫描器读 skill_id: typst_writing_skill；不在 skills.ts 注册。

技能分工

技能	何时
本技能	.typ 语法、数学、编译报错、main.typ 写作项目、章节 patch
lightest_typst_report_skill	研报版式、双栏、Fletcher/CeTZ、成稿 PDF
lightest_writing_skill	成稿后 prose 润色 / 去 AI
lightest_latex_skill	用户明确要 LaTeX 顶会模板而非 Typst

详细工作流（强制）

写作项目根 = 含 main.typ 的目录（project_path / read 的 path 传文件夹，不要传 main.typ 文件路径）。

阶段	动作	工具 / 参数
0. 摸底	看清目录与既有章节	list_dir；需要定位 token 时 grep_search
1. 创建项目	在 Agent 项目下选定目录（如 papers/thesis/），写入入口	apply_patch 新建 main.typ（及 #include 的章节 .typ、.bib、图片等）
2. 改源码	改前先读将动区域；多文件用 #include / #import	read(items=[{path, start_line, end_line}]) → apply_patch
3. 编译验收	每批 .typ 改动后必须编译	writing_compile_check({ project_path: "papers/thesis" })
4. 修错循环	有错误：读日志对应行 ±10–20 行 → 修 → 再编译，直到通过	全局 grep 重复 token（见下节「失败模式」）
5. 验排版	编译通过后看 PDF 页	`read(items=[{path:"papers/thesis", pages:[1,2], type:"text"
6. 磁盘 PDF（可选）	仅当用户要项目内 main.pdf 文件	writing_compile_check({ project_path, export_pdf: true })

平台：本机 writing_compile_check 支持 macOS / Windows（Typst）；Linux 本机不支持，须 SSH 远端。编译成功的 PDF 默认只在 App 内存，list_dir 不一定能看到；验版用步骤 5 的 read(项目根+pages)。

纪律：未 read 相关源码不得盲改；未编译通过不得宣称「已完成」；严禁在 .typ 混入 \section、\frac、\cos、$$...$$ 等 LaTeX 写法。

示例 1：修复编译错误（unknown variable: local）

现象：writing_compile_check 报 unknown variable: local，指向含 A_{local} 的公式行。

正确流程：

1. grep_search 搜 _{local}、text{、$$ — 确认是否多处重复段落（只改第一处仍会报同样错）。
2. read 报错行前后 15 行。
3. apply_patch：数学文本下标改为引号形式，例如 A_("local")；若整段 LaTeX 污染，优先整段重写为纯 Typst。
4. writing_compile_check({ project_path: "papers/thesis" }) 直至无 error。
5. read(items=[{path:"papers/thesis", pages:[1]}]) 确认版式。

示例 2：在 Typst 中写数学（禁止 LaTeX 反斜杠）

需求：行内「设 $f(x)=\ln(\cos x)$」与行间积分，含文本下标 local / strided。

设 $f(x) = ln(cos x)$，$x in (-pi/2, pi/2)$。

$ integral_0^(pi/4) sqrt(1 + tan^2 x) dif x $

$ A = A_("local") union A_("strided") $

禁止对照（会触发 unclosed delimiter / unknown variable）：

禁止	改用
$$...$$	独立成段的 $ ... $（前后各一空格）
\cos x, \frac{a}{b}, \alpha	cos x, frac(a,b), alpha
x_{local}（多字母裸下标）	x_("local")
$ text{depth: } d = alpha $	数学外用自然语言，或 "depth:" 字符串

完整对照表与更多片段见 references/writing-project-guide.md §二、§七。

常见失败模式

场景 / 报错	会出现的问题	处理要点
project_path 指向 main.typ 文件	编译 / read PDF 失败或找不到项目	改为含 main.typ 的目录
改完未跑 writing_compile_check	以为已交付，实际仍编译失败	每批 patch 后必编译
用 $$...$$ 或 LaTeX \frac/\cos	unclosed delimiter / unknown variable	全文改为 Typst 数学；grep $$、\frac
数学里 x_{local} 无引号	unknown variable: local	x_("local")
数学里 text{depth:}	unknown variable: depth	移到数学外或改用 "depth:"
只修 grep 第一处匹配	同一错误反复出现	批量替换所有匹配后再编译
文件混 LaTeX 结构 + 重复章节	报错行与肉眼所见不一致	grep \section、= 标题 重复；必要时整文件重写
writing_compile_check 成功就 list_dir 找 PDF	磁盘无 PDF 误以为失败	验版用 read(项目根, pages)；要落盘才 export_pdf: true
Linux 本机编译	本机 writing_compile_check 不可用	SSH 远端同一 project_path
系统字体名（宋体、SimSun）	unknown font family	New Computer Modern + Noto Serif CJK SC
多 .bib 重复 cite key	编译或引用异常	全局唯一 key（见 reference §四）

调试三原则（详见 reference §七）：先读报错上下文；delimiter/bracket 连环错时整段重写；修完仍报错先 grep 是否还有旧段落。

References 索引

文件	内容
references/writing-project-guide.md	主 reference（必读）：创建写作项目、Typst 语法与数学对照、中文/字体、引用、协作策略、编译错误速查、布局容器、工具列表与工作流、重复内容检测、主文件保护

加载本 skill 后应 先 read 上表主文件；SKILL.md 只保留路由与工作流，不重复全文对照表。

任务路由（简表）

用户要	先做
新建 Typst 论文 / 章节	工作流 §1–5 + reference §零
修编译报错	失败模式表 + reference §七、§十（全局 grep）
写 / 改数学公式	示例 2 + reference §二
从代码 / CSV / PDF 写初稿	reference §十三
研报双栏、架构图、CeTZ	改加载 lightest_typst_report_skill

与写作链衔接

1. 未定稿 prose → lightest_writing_skill（体裁 + 去 AI baseline）
2. 定稿进 Typst 语法与编译 → 本技能
3. 调研报告版式与 Fletcher/CeTZ → lightest_typst_report_skill