kami

kami · 紙

紙 · かみ —— 承载你交付物的纸张。

好的内容值得配上一张好纸。无论文档还是产品落地页，均贯穿统一的设计语言：温润羊皮纸画幅、墨蓝点缀色、衬线主导的视觉层级与严谨的书卷排版节奏。

作为 Kaku · Waza · Kami 系列的一部分 —— Kaku 负责写代码，Waza 负责磨练习惯，Kami 负责交付优雅文档。

更新检查（非阻塞）。 任务开始时，运行 bash scripts/check-update.sh。该脚本最多每天执行一次只读的版本检查；当有新版 kami 可用时输出一行提醒，将其转达给用户后继续即可。它不会发送任何数据，且在离线、沙箱环境或缺少 curl 时静默失败。切勿让其阻塞当前任务。

Step 0 · 加载品牌配置文件（若存在）

优先检查 ~/.config/kami/brand.md（推荐）或 ~/.kami/brand.md（旧版兼容）。如果存在，阅读 references/brand-profile.md 获取完整的四层应用规范（占位符替换、会话默认值、视觉自定义、习惯备注）及六项防线原则。若不存在配置文件，直接继续，无需中断。

核心优先级规则：明确的 Prompt > 编辑裁量权 > 习惯备注 > frontmatter 默认值 > 内置默认值。配置文件仅用于静默补全缺失信息，绝不会覆盖当前对话中的明确指令。

Step 0.5 · 用户项目样式扫描（显式开启）

仅在用户明确将某个同级项目作为视觉参考时运行（例如："参考我 <project> 站点的风格"、"匹配 <repo> 的风格"、"使用 <directory> 目录的视觉样式"）。若无此类参考，直接静默跳过。

触发时，在生成文档前执行：

1. 定位参考项目的样式文件：

   find <referenced-path> -maxdepth 4 \( -name "*.css" -o -name "tailwind.config.*" -o -name "theme.*" -o -name "tokens.*" \) | head -20
   

2. 提取：主色值 (hex / hsl)、字体族 (font stack)、间距阶梯 (spacing scale)、圆角阶梯 (border-radius scale)。优先使用 CSS 变量或 design token 中声明的值，而非内联字面量。
3. 作为 Layer C（视觉自定义）合并入当前会话的品牌配置文件，而非 Layer B（会话默认值）。切勿覆盖显式的 --brand 标记或用户在本轮对话中手动输入的数值。
4. 在继续之前输出一行反馈："已扫描 <project>，提取了 N 个颜色 / M 个字体；将作为视觉参考使用。"

若指定的参考路径不存在、未找到 CSS 样式类文件，或者提取出的数值与用户当前消息中的明确指令冲突，请跳过此步骤并降级使用品牌配置文件的默认值。

---

Step 1 · 确定输出语言

与用户的语言保持一致。 中文 -> *.html / slides-weasy.html。英文 -> *-en.html / slides-weasy-en.html。日文 -> 尽可能使用 CJK 路径 (.html / slides-weasy.html)，优先日文明朝体，交付前需进行视觉 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 仍可正常渲染，代码块将保持单色显示。

Step 1.5 · 意图提取（后台隐式自查表）

在选择模板之前，先确认这四个维度是否清晰。除非有 2 项及以上缺失且无法从上下文中推断，否则不要主动追问。

维度	需要提取的内容	示例
目标 (Purpose)	为什么需要这份文档	说服投资者 vs 对齐内部团队 vs 搞定候选人
受众 (Audience)	读者是谁，已了解哪些背景	技术 CTO（跳过基础知识） vs 非技术董事会成员（解释专业术语）
约束 (Constraint)	长度、格式、语气或交付方式的硬性限制	"最多一页"、"正式英文"、"适合打印的 A4"
成功标准 (Success)	怎样的结果才算达成目标	对方预约会议 / 批准预算 / 理解架构

规则：

• 若对话中已经涵盖了某个维度，直接静默跳过。
• 若某个维度可直接从文档类型推断（例如简历的目标永远是"获取面试机会"），直接跳过。
• 若确实有 2 个及以上维度不明确，用单个简明问题发起追问（最多包含 2 个子问题）。
• 切勿将这四项作为问卷清单一次性全部抛给用户。这是后台隐式核验步骤，而非表单填写。

执行契约 (Execution contract)

在创建或修改输出之前，锁定执行契约：语言、模板、输出格式、页数或长度目标、视觉验收检查以及验证命令。当意图清晰时从用户需求中推断；仅在关键字段缺失会实质影响交付物时才发起询问。

使用最贴近的现有模板和验证路径。除非当前需求无法在现有条件下满足，否则不要新增模板、共享 CSS 层、依赖项、脚本标记或可选模式。

如果修改触及了 SKILL.md、模板、脚本、参考文档或打包输入源，需判断是否在交付前更新 dist/kami.zip。只有压缩包包含更新后的文件时，最终的交付行为才算真正就述。

---

Step 2 · 选择文档类型

用户说法	文档类型	中文模板	英文模板	韩文模板
"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：上述更新日志模板专用于排版优雅的文档输出。GitHub release notes 是独立的交付物；请使用带有 Release Note Template Mode 的 /write。

Landing Page：屏幕优先的交互式模板。无 PDF 导出。包含带自动轮播的画廊、Hero 进场动画、响应式断点 (880px / 480px) 以及对 prefers-reduced-motion 的支持。可作为静态 HTML 部署至 Vercel / Netlify / 任意主机。Agent 填充 {{PLACEHOLDER}} 数值和 HTML 注释块后，保存为可直接提供服务的 .html 文件。

Landing Page 附属文件：对于生产级多语言部署，请复制主 HTML 旁的五个 landing-page-*.example 文件，移除 .example 后缀并填入占位符。它们涵盖 Vercel 重写与 HTTP 头、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»。

生产级产品站点模式：当用户需要文档、帮助中心、发布页、更新日志、路线图、法务页面或超过两种语言时，请将其作为站点系统对待。在填充模板之前，锁定产品类别、真实截图位置、语言列表、附属文件、长内容页面以及生成/检查需求。切勿将项目专属的发布产物、支付服务商、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)

合理发起单句追问的歧义示例：

• "1.5 页重度视觉的职业故事" -> 询问 "简历还是作品集？"
• "2 页带指标卡片的执行摘要" -> 询问 "单页方案还是个股研报？"
• "5 页带多张图表的论述文档" -> 询问 "长文档还是作品集？"

优先从决策树中匹配。仅在决策树完全无法判断时发起询问。

图表（基础构件，而非单独的模板类型）

当用户需要在 long-doc / portfolio / slide 内部添加图表（而非独立文档）时，路由至 assets/diagrams/ 而非模板：

用户说法	图表类型	模板