| 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} 的公式行。
正确流程：
grep_search 搜 _{local}、text{、$$ — 确认是否多处重复段落（只改第一处仍会报同样错）。read 报错行前后 15 行。apply_patch：数学文本下标改为引号形式，例如 A_("local")；若整段 LaTeX 污染，优先整段重写为纯 Typst。writing_compile_check({ project_path: "papers/thesis" }) 直至无 error。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 |
与写作链衔接
- 未定稿 prose →
lightest_writing_skill（体裁 + 去 AI baseline）
- 定稿进 Typst 语法与编译 → 本技能
- 调研报告版式与 Fletcher/CeTZ →
lightest_typst_report_skill
