用途:用于撰写或更新 Kaku 官网(kaku.fun)上面向普通用户的产品文档。站点本身是交付物,该技能提供可重复的流程,保证文档准确并在新增功能时不产生偏差。读者是普通用户而非贡献者,需说明每个页面、按钮、快捷键是什么、如何进入、使用后会发生什么,避免实现细节;项目与全局规则要求不使用长破折号和 emoji。
工作位置:站点工作树为 ~/www/kaku-site,位于 vercel 分支(不是 main),推送该分支由 Vercel 部署 kaku.fun,可用 git worktree list 确认路径。设计系统为 Kami parchment,做任何视觉改动前先读 ~/www/kaku-site/DESIGN.md,并沿用现有页面,不新造组件。文档页英文在 docs/ 下,中文在 zh/docs/ 下,二者保持同步,包括 Install、Guide、Features、CLI Reference、Configuration、Keybindings、FAQ、Contributing。Guide 是叙事式上手引导,Features 是逐功能参考,Guide 保持简短并外链参考页,不重复配置表。截图使用 shots/kaku-dark.webp 与 shots/kaku-light.webp(1920x1192),配合 <figure class="shot"> 复用。
事实来源:用户文档是公开内容,不得依据子代理摘要或功能名称照抄功能声明,发布前须对照运行代码逐条确认。默认值与行为翻转查 config/src/config.rs 及其测试(如 defaults_to)和 assets/ 中的内置配置;shell 行为查 assets/shell-integration/setup_zsh.sh;键位与菜单以现有 keybindings.html 为准,沿用其措辞。已有站点文档在语气与命名上具有权威性:新增内容需验证,引用已有内容需保持一致。
流程:先用 git log / gh release list 确认当前版本与变更范围,阅读最近的 crate 的 AGENTS.md 与 CLAUDE.md 获取功能说明;再原样阅读目标页面以克隆准确标记,注意 site-nav、docs-sidebar > docs-menu、section-toc、doc-content、doc-pager、footer 等结构,中文页的 footer 与 skip-link 措辞与英文不同,需从现有中文页原样复制。新增页面时克隆已有文档页的完整骨架,修改 title/description/canonical/hreflang/hero/菜单当前项/section-toc/doc-pager,锚点使用页面前缀(如 guide-)。导航接线:在所有英文文档页的 docs-menu 块中插入新链接,在所有中文页插入 /zh/docs/... 变体;带有 aria-current="page" 的相邻链接需单独用 sed 处理;只在两个相邻页修正 doc-pager 的前后链;把两个 URL 加入 sitemap.xml 并在 llms.txt(如枚举页面则含 llms-full.txt)加一行。仅在发布已上线时更新版本指针(nav 中的 v0.X.Y、两个 index.html 的 JSON-LD softwareVersion、AppleScript 取版本示例、llms-full.txt 的 Latest version),保留路线图叙述与历史版本记录,并先用 gh release list 确认发布已公开。
完成前验证:运行 python3 scripts/highlight.py --check(0 个文件需要高亮);确认 cleanUrls 下内部链接可解析(每个 /docs/x 有 docs/x.html);新改页面 HTML 结构完整;中英文段落、锚点、表格一一对应;用浏览器引擎截取改动或新增页面的渲染截图。Kaku 应用是原生终端,应用截图仅在维护者明确要求时才用 make app 或 /Applications/Kaku.app 加 screencapture 完成;网站页面可用浏览器调试截图,只有 Safari 时可用 Preview MCP 自带引擎(临时根目录、.claude/launch.json 配置 python3 -m http.server、preview_start 与 preview_screenshot,移动端 375px 检查,切换页面后 preview_stop 再 preview_start 强制刷新)。最后展示 diff,除非维护者当轮明确要求,否则不要提交或推送 vercel 分支(推送即立刻上线)。后续新增功能时先决定归属页面,中英文同步更新并镜像锚点与表格,重跑验证清单,保持 diff 最小且按行为原子化。