Design
Kami · 紙
为专业文档和产品落地页排版：简历、一页纸、白皮书、信件、作品集、幻灯片、落地页。温润的羊皮纸底色、墨蓝点缀、衬线主导的层级。
紙 · かみ —— 承载你交付物的那张纸。
好内容值得配好纸。一套设计语言贯穿八种文档类型：温润的羊皮纸画布、墨蓝点缀、衬线主导的层级、紧凑的编辑节奏。
它是 Kaku · Waza · Kami 的一部分——Kaku 写代码，Waza 磨习惯，Kami 交付文档。
更新检查（非阻塞）。 任务开始时，运行 bash scripts/check-update.sh。它每天至多做一次只读的版本检查，并在有更新的 kami 可用时打印一行；将该行转达给用户，然后继续。它不发送任何数据，并在离线、沙盒或没有 curl 时静默失败。绝不要让它阻塞工作。
检查 ~/.config/kami/brand.md（首选）或 ~/.kami/brand.md（旧版回退）。如果找到，阅读 references/brand-profile.md 以获取完整的四层应用规范（占位符替换、会话默认值、视觉定制、习惯备注）及其六条护栏。如果不存在配置，则不中断地继续。
关键规则：显式提示词 > 编辑判断 > 习惯备注 > frontmatter 默认值 > 内置默认值。配置静默填补空缺；它绝不覆盖当前的对话。
仅当用户明确引用某个同级项目作为视觉参考时才运行此步骤："像我的 <project> 网站那样"、"匹配 <repo> 的风格"、"用 <directory> 的外观"。当不存在此类引用时，静默跳过。
触发时，在生成之前：
find <referenced-path> -maxdepth 4 \( -name "*.css" -o -name "tailwind.config.*" -o -name "theme.*" -o -name "tokens.*" \) | head -20
--brand 标志或用户在本轮输入的值。<project>, extracted N colors / M fonts; using as visual reference."如果被引用的路径不存在、找不到类 CSS 文件，或提取结果会与用户在当前消息中的显式值冲突，则跳过并回退到品牌配置默认值。
匹配用户的语言。 中文 -> *.html / slides-weasy.html。英文 -> *-en.html / slides-weasy-en.html。日文 -> CJK 路径（.html / slides-weasy.html）作为尽力而为，优先 JP 明朝体，发货前做视觉 QA。韩文 -> 专用的 *-ko.html / slides-weasy-ko.html 系列作为尽力而为，发货前做视觉 QA。参考文档是共享的英文规范。
当语言含糊时（例如像 "resume" 这样的单词命令），用一行问句确认，而不是猜测。
| 用户语言 | HTML 模板 | 幻灯片（PDF 默认） | 幻灯片（PPTX 回退） |
|---|---|---|---|
| 中文（主） | *.html | slides-weasy.html | slides.py |
| 英文 | *-en.html | slides-weasy-en.html | slides-en.py |
| 日文（尽力而为） | *.html | slides-weasy.html | slides.py |
| 韩文（尽力而为） | *-ko.html | slides-weasy-ko.html | 无（仅在需要 PPTX 时使用 slides-en.py） |
| 其他语言（尽力而为） | 按文字覆盖选择 CJK 或 EN 路径，然后手动核验 | 选择 slides-weasy.html 或 slides-weasy-en.html，然后手动核验 | 仅在需要 PPTX 时使用 slides.py / slides-en.py |
默认走 WeasyPrint HTML 路径；仅当用户明确需要可编辑的演示文稿时才回退到 PPTX（
slides*.py）。
在设计、写作、生产和图表方面，始终使用 CHEATSHEET.md 和 references/*.md 作为指导。
带有 class="language-*" 的代码块，仅当构建环境中安装了可选的 Pygments 时才会高亮。没有它，PDF 仍能渲染，代码块保持单色。
在选择模板之前，核验这四个维度是否清晰。除非有 2 个及以上维度缺失且无法从上下文推断，否则不要提问。
| 维度 | 提取什么 | 示例 | |---|---|---| | 目的 | 这份文档为何存在 | 说服投资人 vs. 统一内部团队 vs. 拿下一位候选人 | | 受众 | 谁在读，他们已经知道什么 | 技术型 CTO（跳过基础）vs. 非技术董事会（解释术语） | | 约束 | 在长度、格式、语气或交付上的硬限制 | "最多一页"、"正式英文"、"可印刷 A4" | | 成功 | 什么结果算成功 | 他们约了一次会面 / 他们批准了预算 / 他们理解了架构 |
规则：
在创建或修改输出之前，锁定契约：语言、模板、输出格式、页数或长度目标、视觉验收检查、以及验证命令。当用户的请求清晰时从中推断；仅当缺失字段会实质性改变交付物时才提问。
使用最接近的现有模板和验证路径。除非当前请求不添加就无法满足，否则不要新增模板、共享 CSS 层、依赖、脚本标志或可选模式。
如果某项改动触及 SKILL.md、模板、脚本、参考资料或打包输入，需判断在交接前是否必须刷新 dist/kami.zip。在打包包含改动后的文件之前，已发货的行为不算就绪。
| 用户说 | 文档 | 中文模板 | 英文模板 | 韩文模板 |
|---|---|---|---|---|
| "one-pager / 方案 / 执行摘要 / exec summary" | One-Pager | one-pager.html | one-pager-en.html | one-pager-ko.html |
| "white paper / 白皮书 / 长文 / 年度总结 / technical report" | Long Doc | long-doc.html | long-doc-en.html | long-doc-ko.html |
| "formal letter / 信件 / 辞职信 / 推荐信 / memo" | Letter | letter.html | letter-en.html | letter-ko.html |
| "portfolio / 作品集 / case studies" | Portfolio | portfolio.html | portfolio-en.html | portfolio-ko.html |
| "resume / CV / 简历 / 履歴書" | Resume | resume.html | resume-en.html | resume-ko.html |
| "slides / PPT / deck / 演示" | Slides | slides-weasy.html | slides-weasy-en.html | slides-weasy-ko.html |
| "个股研报 / equity report / 估值分析 / investment memo / 股票分析" | Equity Report | equity-report.html | equity-report-en.html | equity-report-ko.html |
| "更新日志 / changelog / release notes / 版本记录" | Changelog | changelog.html | changelog-en.html | changelog-ko.html |
| "landing page / 落地页 / 官网 / product page / 产品页" | Landing Page | landing-page.html | landing-page-en.html | landing-page-ko.html |
Changelog vs. release notes：上面的 changelog 模板用于带样式的文档输出。GitHub release notes 是另一种交付物；使用
/write的 Release Note Template Mode。
Landing Page：屏幕优先的交互式模板。无 PDF 输出。包含带自动轮播的画廊轮播、首屏入场动画、响应式断点（880px / 480px）以及 prefers-reduced-motion 支持。作为静态 HTML 部署到 Vercel / Netlify / 任意主机。代理填入 值和 HTML 注释块，然后保存为可直接服务的
.html文件。
Landing Page 配套文件：对于生产环境的多语言部署，把五个
landing-page-*.example文件复制到主 HTML 旁，去掉.example后缀，并填入占位符。它们涵盖 Vercel rewrites 和 headers、sitemap hreflang、robots AI 允许列表，以及给 AI 助手的 llms.txt + llms-full.txt。主 HTML 已在<head>中带有匹配的 hreflang 和 og:locale；landing-page-en.html末尾的 Accept-Language 重定向被注释掉，可选启用。{{SITE_ORIGIN}}是你{{CANONICAL_URL}}的协议 + 主机（例如https://example.com）。参见references/design.md第 11 节《Companion assets》。
生产产品站模式：如果用户需要文档、帮助、发布、changelog、路线图、法律页面，或两种以上语言，就把它当作一个站点系统来处理。在填充模板之前，锁定产品品类、真实截图位、语言列表、配套文件、长内容页面，以及生成器/检查需求。把项目专属的发布制品、支付提供商、appcast 规则和私有本地路径排除在 Kami 之外。参见
references/design.md第 11 节《Product site system》。
文档页面：当落地页成长为文档或帮助站点时，使用
references/design.md第 11 节《Documentation site》中的文档外壳：带 2px 品牌色边条（而非深色下划线）的粘性侧边栏导航、在平板断点以下隐藏的本页 TOC、受约束的正文行宽，以及安静无边框的上一页/下一页翻页器（文字链接，而非带边框的卡片）。在构建时高亮代码、运行时零 JS，呈现在深色代码表面上；纯代码仍是事实来源。
幻灯片：默认走
slides-weasy.html/slides-weasy-en.html/slides-weasy-ko.html（WeasyPrint HTML → PDF）。仅当用户明确需要可编辑的 PPTX 文件时才使用slides.py/slides-en.py。仅当用户明确要求 Marp / markdown 幻灯片 / 存在于.md文件中的演示文稿时，才使用assets/templates/marp/slides-marp(.md|.css)。
演示文稿配方：起草幻灯片前先阅读 design.md 第 8 节。在生成或裁剪视觉素材之前，先勾勒标题序列、论据形态和图片位。让受众文案与视觉简报分开。Marp 专属约束见 design.md §8《Marp variant》。
在求助于一行问句之前，先走一遍这棵树。仅当两个单元格确实都吻合时才提问。
| 信号 | 文档 | |---|---| | 长度目标未知 | 在分类前先问"多少页" | | ≤ 1 页 + 投资人 / 招聘者 / 执行摘要受众 | one-pager | | ≤ 1 页 + 正式信函（销售、招聘、辞职、备忘录） | letter | | 1.5-2 页 + 职业叙事 + 项目要点 | resume | | 3-6 页 + 项目展示 + 视觉为重 | portfolio | | 6-15 页 + 持续论证 + 低视觉密度 | long-doc | | 演示流程 + 演讲者支持 + 每页一个论断 | slides | | 财务 / 指标看板 + 论点 + 价格或风险视图 | equity-report | | 逐版本日志 + 发布事实 | changelog | | 产品展示 + 定价 + 截图 + 供浏览的 FAQ | landing-page |
值得用一行问句的含糊示例：
先从这棵树里挑。仅当树确实给不出答案时才提问。
当用户要求在 long-doc / portfolio / 幻灯片内嵌入图表（而非独立文档）时，路由到 assets/diagrams/，而不是某个模板：
| 用户说 | 图表 | 模板 |
|---|---|---|
| "架构图 / architecture / 系统图 / components diagram" | Architecture | assets/diagrams/architecture.html |
| "流程图 / flowchart / 决策流 / branching logic" | Flowchart | assets/diagrams/flowchart.html |
| "象限图 / quadrant / 优先级矩阵 / 2×2 matrix" | Quadrant | assets/diagrams/quadrant.html |
| "柱状图 / bar chart / 分类对比 / grouped bars" | Bar Chart | assets/diagrams/bar-chart.html |
| "折线图 / line chart / 趋势 / 股价 / time series" | Line Chart | assets/diagrams/line-chart.html |
| "环形图 / donut / pie / 占比 / 分布结构" | Donut Chart | assets/diagrams/donut-chart.html |
| "状态机 / state machine / 状态图 / lifecycle" | State Machine | assets/diagrams/state-machine.html |
| "时间线 / timeline / 里程碑 / milestones / roadmap" | Timeline | assets/diagrams/timeline.html |
| "泳道图 / swimlane / 跨角色流程 / cross-team flow" | Swimlane | assets/diagrams/swimlane.html |
| "树状图 / tree / hierarchy / 层级 / 组织架构" | Tree | assets/diagrams/tree.html |
| "分层图 / layer stack / 分层架构 / OSI / stack" | Layer Stack | assets/diagrams/layer-stack.html |
| "维恩图 / venn / 交集 / overlap / 集合关系" | Venn | assets/diagrams/venn.html |
| "K 线 / candlestick / OHLC / 股价走势 / price history" | Candlestick | assets/diagrams/candlestick.html |
| "瀑布图 / waterfall / 收入桥 / revenue bridge / decomposition" | Waterfall | assets/diagrams/waterfall.html |
绘制前先阅读 references/diagrams.md——其中有选型指南、kami token 映射，以及 AI 粗制滥造的反模式表。从模板中提取 <svg> 块，放入 long-doc / portfolio 内的 <figure> 中。
绘制前，始终自问：一段写得好的文字会不会比这张图教给读者的更少？ 如果不会，就别画。
从数据自动选择图表。 当内容包含数值数据时，选定图表类型并直接嵌入，无需等用户指定。决策树（首个匹配胜出）：
| 数据形态 | 图表 | |---|---| | 有 open/high/low/close 字段，或每日价格 | Candlestick | | 有汇总为某个总计的 + 和 - 贡献（桥、瀑布、损益） | Waterfall | | 单一序列，数值合计约 100%，项目数 ≤ 6 | Donut | | 单一序列，数值合计约 100%，项目数 ≥ 7 | Horizontal bar | | 两个或更多序列跨时间（月、季、年） | Line | | 单一序列跨时间，以较大的计数变化为主（非比率） | Bar | | 多个类别、同一时间快照、2+ 序列 | Grouped bar | | 2×2 战略或优先级定位 | Quadrant | | 深度 ≥ 2 的层级数据 | Tree | | 带决策分支的流程 | Flowchart | | 跨团队或跨角色、≥ 3 个参与者的流程 | Swimlane | | 2-3 个组之间的集合重叠或共享属性 | Venn | | 类别对比、单一序列、无时间轴 | Bar |
当数据适配多种类型时，优先选最能清晰展现差异的那种。始终嵌入到一个 <figure> 中，并配上陈述洞见（而非仅陈述数据范围）的标题。
当文档依赖用户草稿之外的事实或素材时，在提炼或填充内容之前运行此步骤。仅当用户已提供所需一切的个人草稿时才跳过。
当文档提及某个具体公司、产品、人物、发布日期、版本、融资轮次、指标、市场事实、技术规格，或任何可能变化的当前事实时触发。
当文档关于某个公司、产品、项目、场所或个人品牌时触发。
在排版前确认能让主体可识别的素材：
| 需求 | 何时必需 | 接受 | |---|---|---| | Logo | 任何品牌化文档 | 用户文件或官方 SVG/PNG | | 产品图 | 实体产品 / 场所 / 物件 | 官方图、用户图，或标注的空缺 | | UI 截图 | App / SaaS / 网站 / 工具 | 当前截图、官方产品图，或用户抓图 | | 品牌色 | 品牌化的 one-pager / portfolio / 演示文稿 | 官方值、从素材提取的值，或保留 kami 墨蓝 | | 字体 | 仅当品牌字体重要时 | 官方字体、相近的系统回退，或 kami 默认 |
如果缺少必需项，使用一个紧凑的空缺表并问一次。不要用通用图片、近似的 logo 手绘或杜撰的值来替代缺失的素材。
Logo 回退：当请求没有指定 logo、但品牌配置有 logo 路径时，按 references/brand-profile.md C 层填入 one-pager / portfolio / slides-weasy 中被注释掉的 .brand-logo 位。把 ~ 展开为绝对路径；如果文件缺失或模板没有该位，就保持其注释状态并在没有 logo 的情况下渲染（绝不插入损坏的图片）。当前请求中的显式 logo 永远胜出。
素材检查之后，在继续之前输出一个结构化的状态块。这是一次性的透明展示，不是提问：
Materials status:
- Logo: OK assets/client-logo.svg
- Brand colors: OK #1B365D mapped to --brand
- Product screenshot: MISSING (proceeding with kami default placeholder)
- UI screenshot: not required for this doc type
使用 OK、MISSING 或 not required。如果某个必需项缺失且没有用户输入到达，就用空缺表问一次；否则静默继续。
自动判断是否需要提炼。 不要问用户；从输入来判断：
| 跳过提炼（直接填充） | 运行提炼 | |---|---| | 内容有与模板结构匹配的明确小节标签 | 没有小节结构的原始散文 | | 指标已带单位量化到位 | 数字零散或隐含，未被提取 | | 用户写了 "use this as-is" / "直接用这个" / "原封不动" | 用户粘贴了多来源的堆砌（聊天 / 邮件串 / 多份文档） | | 内容数量与模板匹配（例如 4 个指标对应 4 张指标卡） | 内容数量与模板不匹配（项太多或太少） | | 一致的声音、前后一致的主张 | 跨来源的冲突主张或重复事实 |
拿不准时就运行提炼。提炼成本低；重建一份错位的文档则不然。
当用户交来原始素材（会议记录、灵感倾倒、不同格式的现有文档、聊天记录、零散要点）时：
references/writing.md）空缺检查示例：
| 模板需要 | 已找到 | 缺失 | |---|---|---| | 4 张指标卡 | "8 years"、"50-person team" | 还差 2 个可量化的结果 | | 3-5 个核心项目 | 提到了 2 个 | 至少再加 1 个带成果的 | | 素材 | 已提供 logo 文件 | 产品截图来源 |
然后带着结构化、已提炼的内容，进入步骤 2.6（幻灯片）或排版备注（其他所有文档类型）。
除幻灯片外的所有文档类型都跳过此步骤。
默认走 WeasyPrint HTML 路径。仅当用户明确需要可编辑的 PPTX 文件时切换到 pptx。仅当用户明确要求 Marp / markdown 幻灯片时切换到 Marp。
| 路径 | 模板 | 何时 |
|---|---|---|
| WeasyPrint HTML → PDF（默认） | slides-weasy.html / slides-weasy-en.html / slides-weasy-ko.html | 除非需要 PPTX 或 Marp，所有情况 |
| python-pptx → PPTX（回退） | slides.py / slides-en.py | 用户明确需要可编辑的 PPTX |
| Marp Markdown（变体） | assets/templates/marp/slides-marp.md（+ slides-marp.css）/ slides-marp-en.md（+ slides-marp-en.css） | 用户明确要求 Marp、"markdown slides" 或 .md 演示文稿。随附的 .md 是 Kami Marp 本身的可运行演示；复制它，替换内容，保留结构。通过本地 marp CLI 渲染；未捆绑。 |
默认是 280mm 158mm。仅当用户提到长度或密度约束时才询问。
| 尺寸 | 何时 |
|---|---|
| 280mm 158mm | 默认；适配大多数演示文稿 |
| 297mm 167mm | 用户想要稍多空间 |
| 338mm 190mm | 内容繁重的幻灯片，或每页数据点很多 |
在起草任何幻灯片之前，与用户确认以下要点。一次问完，已回答的跳过：
| # | 问题 | |---|---| | 1 | 受众 + 场合 —— 谁在场，是现场主题演讲、投资人 1:1，还是异步分享链接？ | | 2 | 长度目标 —— 演讲时长还是幻灯片数？（15 分钟：约 10 页 / 30 分钟：约 20 页 / 45 分钟：约 25-30 页） | | 3 | 源素材 —— 哪些内容已就绪：提纲、文档、笔记、数据？ | | 4 | 图片 —— 是否有可用的截图、图表、logo 或产品图；哪些幻灯片需要真实的论据位；是否需要单独的视觉简报？ | | 5 | 硬约束 —— 品牌色、必需 logo、是否需要 PPTX、是否有某些必须存在的幻灯片？ | | 6 | 格式确认 —— 是幻灯片演示文稿，还是一份长得像演示文稿的 one-pager？ |
在起草任何落地页或产品站之前，从源素材锁定以下要点。仅当某个缺失项会改变交付物时才问一次：
| # | 锁定 |
|---|---|
| 1 | 产品品类 —— 首屏品类：app、CLI、终端、工具、技能、模板系统，或其他用户提供的标签。 |
| 2 | 真实素材 —— 可用的产品截图、logo、图标或 UI 抓图，映射到 hero/gallery/feature/social 位。缺失的素材必须保持标注状态，不可用图库图片替代。 |
| 3 | 站点形态 —— 单页，还是首页加 docs/help/releases/changelog/roadmap/legal 页面？ |
| 4 | 语言 —— 确切的语言列表、规范路径，以及是否需要生成器/检查模式。 |
| 5 | 事实面 —— 安装路径、价格、版本、支持渠道、FAQ、llms.txt 和 llms-full.txt，它们必须保持同步。 |
.eyebrow 来标注分节编号，而非一个专门的蓝底页面（...） 替换为 · 或 ,table.t2x2，而非 CSS Gridposition: absolute; bottom: 12mm 处使用 .co这些规则同样适用于 Marp 演示文稿。Marp 专属语法：见 references/design.md §8《Marp variant》。
在加载规范和填充模板之前，写一段编辑风格的简短备注，陈述排版意图：模板选择、长度目标、叙事弧线、内嵌图表、素材状态和输出格式。匹配文档的语言。控制在 80 字以内，写成散文，而非状态面板。紧接着立即继续；不要等待。
示例（CN）：
排版意图：Equity Report 中文版，2 页 A4。先立论与目标价，进入估值 (DCF 与可比公司)，落于催化剂与风险。中段嵌一张营收趋势折线和 FY26 收入桥瀑布。Logo 已就位，产品图暂缺，header 改走纯文字。输出 HTML 与 PDF。
示例（EN）：
Layout intent: Equity Report (EN), two pages A4. Open with thesis and price target, run through valuation (DCF and comparables), close on catalysts and risks. A revenue line chart and an FY26 waterfall sit mid-doc. Logo is in hand; product image is absent, so the header stays text-only. Output: HTML and PDF.
这段备注是为了透明，不是为了审批。如果用户反对，就调整；否则继续到步骤 3。
挑选与任务匹配的层级。默认选用能覆盖工作的最低层级。
| 层级 | 何时 | 阅读 |
|---|---|---|
| 仅内容 | 更新文字、替换要点、翻译现有文档。CSS 不动。 | 仅 CHEATSHEET.md |
| 布局微调 | 调整间距、移动小节、在规范内更改字号。触及 CSS。 | CHEATSHEET.md + 模板（token 已内联） |
| 新文档 | 从零或从原始内容构建。 | 完整设计规范 + 写作规范 + 模板 |
| 简历内容 | 简历专属的要点结构、项目框架、范围-结果-成效规则。 | resume-writing.md + 模板 |
| 来源 / 素材 | 公司、产品、市场、发布、融资、规格，或品牌化主体。 | writing.md 的来源规则 + 用户/来源素材 |
| 演示文稿（>20 页） | 需要 Part Divider、Code Cards、分节标题的长演示文稿。 | 完整设计规范 + Deck Recipe（design.md 第 8 节） |
| 排障 | 渲染 bug、字体问题、页面溢出。 | production.md（如成因是 CSS，再加设计规范） |
| 反模式 | 在发货前审查 AI 生成的草稿。 | anti-patterns.md（六类清单） |
| 图表 | 在文档中嵌入 SVG。 | 仅 diagrams.md（自带 token 映射） |
如果工作中途发现需要超出初始层级，你随时可以升级。
供参考的完整规范文件：
references/design.mdreferences/writing.mdreferences/resume-writing.mdreferences/production.mdreferences/diagrams.mdreferences/anti-patterns.mdwriting.md：用数据胜过形容词，用独特措辞胜过行业陈词references/anti-patterns.md 中列出的模式：空洞、杜撰、模仿、过度、来源空缺、语气污染writing.md 的"Quality bars by document type"小节中阅读你文档类型的质量标准。结构是必要的但不充分：一条简历要点需要 Action + Scope + Result + Business Outcome；一份股票研报需要差异化认知 + 量化催化剂；幻灯片需要论断-论据式标题。达到质量标准与填满每个占位符同样重要。以下是最常见的 AI 文档失误。完整清单请交叉参考 references/anti-patterns.md。
[DATA NEEDED: description] 标注空缺每个模板的 <head> 中都有 meta 占位符。构建前把这四个都填好：
| 占位符（CN） | 占位符（EN） | 规则 |
|---|---|---|
| {{作者}} | {{AUTHOR}} | 简历/信件/作品集：用文档中那个人的名字。其余一律：保持原样（构建脚本从 git 配置或环境变量推断） |
| {{摘要}} | {{DESCRIPTION}} | 从前 2 段中提取一句话（≤150 字符） |
| {{关键词}} | {{KEYWORDS}} | 从标题 + 小节标题中取 3-5 个关键词，逗号分隔 |
| {{文档标题}} / {{信件主题}} 等 | {{DOC_TITLE}} / {{LETTER_SUBJECT}} 等 | 从 H1 或 .header .title 文本推断 |
<meta name="generator" content="Kami"> 已在模板中固定；不要更改它。
作者推断：build.py 会自动从以下来源设置 PDF /Author 元数据：
git config user.name（主）KAMI_AUTHOR 环境变量（回退）"Kami"（最终回退）对于个人文档（简历/信件/作品集），HTML 的 <meta name="author"> 应与内容中那个人的名字匹配。对于非个人文档（one-pager/long-doc），保持占位符原样，让构建脚本去推断。
适用：slides-weasy / long-doc / portfolio / equity-report / changelog。不适用 resume / one-pager / letter（这些有独立的长度合约）。
正文页填充率目标 60-80%。封面 / 目录 / 末尾署名页豁免。这条规则解决的是 AI 生成多页文档时最常见的 draft 缺陷：把内容拆得太散，结果几页都填不满。
| Template | Typical body page | Hard floor (merge if below) | |---|---|---| | slides-weasy | 1 assertion title + 3-5 supporting items, or 1 chart + 2-3 callouts | <3 items and no chart → merge into adjacent slide | | long-doc | 1 chapter heading + 2-4 paragraphs + at most 1 figure | Chapter renders to <40% page → merge into neighbor chapter | | portfolio | 1 project header + 1 hero image + 3-5 outcome bullets | No image and <3 outcomes → merge with adjacent project | | equity-report | 1 section + 1 table/chart + supporting prose | Only a 2-row table on the page → combine sections | | changelog | 1 version block + 4-8 entries | Version has <4 entries → place on the same page as the prior version |
最终定稿前，扫描草稿。任何会渲染到不足 50% 满的正文页 → 按顺序采用其一：
.co callout 钉到底部（仅限 slides-weasy）。钉住的 callout 上方的留白是有意为之，不算稀疏。"填充"稀疏页的禁忌做法：用灌水文字凑数、把标题重述成一句话、编造统计数字、用不同措辞重述前一页。如果合并选项都不适用，那这一页本身就不该存在。
最后一个正文页允许 40-60% 填充率。在末页强求平衡通常意味着灌水。版权页 / 收尾幻灯片可为任意填充率。
python3 scripts/build.py --check-density # flags >25% (WARN) / >50% (SPARSE) trailing whitespace
如果某个正文页（非封面、非末页）得到 SPARSE 警告，把它当作草稿缺陷，按合并规则重新撰写。
不要问用户要导出哪种格式。从上下文决定：
| 信号 | 输出 | 为什么 | |---|---|---| | 任何文档请求 | HTML + PDF | PDF 是默认交付物，HTML 是源 | | 幻灯片 / PPT / 演示文稿 | HTML + PDF + PPTX | 演示需要可投影的格式 | | "分享" / "发朋友圈" / "share" / "post" / "preview" | + PNG | 社交平台和即时通讯需要图片 | | "嵌入" / "插图" / "embed in another doc" | 仅 PNG | 作为素材用于其他文档内部 | | 用户明确指定某种格式 | 听用户的 | 显式请求覆盖自动选择 |
对文档模板，PDF 总是随附。落地页作为可直接服务的静态 HTML 文件发货。PPTX 跟随幻灯片。PNG 跟随分享场景。用户永远不必去想格式问题。
python3 scripts/build.py --verify # build all templates + page count + font check + slides
python3 scripts/build.py --verify resume-en # single target full verification
python3 scripts/build.py landing-page # screen-first static HTML template check
python3 scripts/build.py --verify slides # single slide deck verification
python3 scripts/build.py --check-placeholders path/to/filled.html
python3 scripts/build.py --check-resume-balance path/to/resume.pdf
python3 scripts/build.py --check-density # page whitespace scanner (skips cover)
python3 scripts/build.py --check # CSS rule violations only (fast, no build)
python3 scripts/build_metadata.py --check # Codex plugin mirror + marketplace drift check
屏幕验证：
--check-density是一道打印关卡。对于屏幕输出（落地页或文档页），改为在每种语言下以 375px 和 1280px 截图渲染后的页面，并在发货前扫描断行孤字。参见references/design.md第 11 节《Responsive screenshot verification》。
源模板有意保留 {{...}} 字段。在已完成的文档上运行占位符检查，而非在模板库上。
视觉异常（标签双矩形、字体回退、分页问题）-> production.md 第 4 部分。
仅在维护本仓库或发布包时使用这些，不用于普通的文档生成。
python3 scripts/build_metadata.py --check；对于 Codex 安装行为，还要用隔离的 CODEX_HOME=/tmp/... 进行冒烟测试，使用 codex plugin marketplace add <path>、codex plugin add kami@kami 和 codex plugin list。SKILL.md、模板、脚本、参考资料或其他打包输入发生变化，且该行为通过技能包发货，运行 bash scripts/package-skill.sh 并在交接前检查 dist/kami.zip。kami.zip，并将 ZIP 条目名称加每条目的 SHA-256 摘要与本地 dist/kami.zip 对比；页面文字、文件大小和容器哈希都不够。中文
日文（尽力而为）
-ja 模板韩文（尽力而为）
-ko 模板使用 Source Han Serif K Regular / Medium，并在每个回退栈中保留真实的 OTF 家族名 Source Han Serif KR英文
--sans: var(--serif)，每页一种字体把字体文件放在 HTML 旁、用相对的 @font-face 路径，是最稳定的方案。scripts/package-skill.sh 会从 Claude Desktop ZIP 中排除大型 CJK 字体文件，使上传的包保持在 6MB 包体上限以下。始终上传 package-skill.sh 的输出，绝不要手动 zip 的检出（被跟踪的 CJK 字体会让它过大，Claude Desktop 会拒绝上传）。
字体自动恢复（Claude Desktop）
在构建中文或韩文文档之前，确保字体存在。脚本会尝试多个 CDN 源，带重试和大小校验：
bash scripts/ensure-fonts.sh
它会下载到 XDG 用户字体目录（${XDG_DATA_HOME:-~/.local/share}/fonts/kami，用 KAMI_FONT_DIR 覆盖），而非技能的 assets/fonts——这样已安装的技能保持小巧，让 Claude Desktop 永远不触发其大小限制。fontconfig 默认扫描该目录，因此 WeasyPrint 能在那里找到 TsangerJinKai02 和 Source Han Serif K；在线渲染则回退到 jsDelivr 的 @font-face URL。构建前运行一次。如果所有源都失败，脚本会按语言打印备选方案。
当用户给出含糊的视觉反馈（"看着不对"、"太挤了"、"不够优雅"）时，不要猜测。带着当前值反问：
| 用户说 | 询问 | |---|---| | "太挤了" / "too cramped" | 哪个元素？行高（当前：X）？内边距（当前：Y）？页边距？ | | "太松了" / "too loose" | 同方向，反向 | | "颜色不对" / "color feels wrong" | 哪个元素？品牌蓝用得过多？某个灰色读起来太冷？ | | "不够好看" / "not polished" | 字体渲染？对齐？留白分布？层级不清晰？ | | "看着不专业" / "unprofessional" | 内容措辞？还是布局（对齐、一致性）？ |
模板回复："X is currently set to Y. Would you like (a) [specific alternative within spec] or (b) [another option]?"
绝不要在不指明确切属性及其新值的情况下说"我会调整间距"。
接下来：套用步骤 3 的层级表来决定读什么，然后复制匹配的模板并开始填充。