wehub-resource-sync
212 lines
14 KiB
Markdown
212 lines
14 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/tw93/Kami) · [上游 README](https://github.com/tw93/Kami/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
<img src="assets/images/logo.svg" width="120" />
|
||
<h1>Kami</h1>
|
||
<p><b>好内容值得好纸张。</b></p>
|
||
<a href="https://github.com/tw93/kami/stargazers"><img src="https://img.shields.io/github/stars/tw93/kami?style=flat-square" alt="Stars"></a>
|
||
<a href="https://github.com/tw93/kami/releases"><img src="https://img.shields.io/github/v/tag/tw93/kami?label=version&style=flat-square" alt="Version"></a>
|
||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a>
|
||
<a href="https://twitter.com/HiTw93"><img src="https://img.shields.io/badge/follow-Tw93-red?style=flat-square&logo=Twitter" alt="Twitter"></a>
|
||
</div>
|
||
|
||
## 为什么
|
||
|
||
Kami（紙、かみ）在日语中意为「纸」：成品想法最终落定的表面。AI 生成文档的能力已优于大多数人手工制作。缺失的并非能力，而是约束（constraint）：没有设计系统（design system），每次会话都会滑向千篇一律的灰色与不协调版式。
|
||
|
||
Kami 填补这一空白：一套约束语言、八种文档模板外加落地页（landing page）系统，简单到智能体（agent）可稳定运行，又严格到每一份输出都真正值得发布。
|
||
|
||
三部曲之一：[Kaku](https://github.com/tw93/Kaku))（書く）负责写代码，[Waza](https://github.com/tw93/Waza))（技）锤炼习惯，[Kami](https://github.com/tw93/Kami))（紙）交付文档。
|
||
|
||
## 展示
|
||
|
||
同一套约束下的真实 PDF，横跨多种模板与语言。点击任意预览即可打开。
|
||
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-musk-resume.pdf"><img src="assets/demos/demo-musk-resume.png" alt="Founder resume"></a>
|
||
<br><b>Resume</b> · English
|
||
<br><sub>创始人简历，2 页</sub>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-kami-print.pdf"><img src="assets/demos/demo-kami-print.png" alt="Kami print one-pager"></a>
|
||
<br><b>One-Pager</b> · 中文
|
||
<br><sub>Kami 介绍 · 白底打印版</sub>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-tesla.pdf"><img src="assets/demos/demo-tesla.png" alt="Tesla equity report"></a>
|
||
<br><b>Equity Report</b> · 中文
|
||
<br><sub>Tesla Q1 2026 财报点评</sub>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-agent-slides.pdf"><img src="assets/demos/demo-agent-slides.png" alt="Agent keynote slides" /></a>
|
||
<br><b>Slides</b> · English
|
||
<br><sub>Agent 主题演讲，8 页幻灯片</sub>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-mole.pdf"><img src="assets/demos/demo-mole.png" alt="Mole product brief"></a>
|
||
<br><b>One-Pager</b> · English
|
||
<br><sub>Mole 产品简报，1 页</sub>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-letter.pdf"><img src="assets/demos/demo-letter.png" alt="Recommendation letter"></a>
|
||
<br><b>Letter</b> · 中文
|
||
<br><sub>推荐信, 1 页</sub>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-changelog.pdf"><img src="assets/demos/demo-changelog.png" alt="Mole release notes"></a>
|
||
<br><b>Changelog</b> · English
|
||
<br><sub>Mole v1.7.1 发布说明</sub>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="assets/demos/demo-kaku.pdf"><img src="assets/demos/demo-kaku.png" alt="Kaku portfolio"></a>
|
||
<br><b>Portfolio</b> · 日本語
|
||
<br><sub>Kaku ターミナル作品集 · 7 ページ</sub>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## 安装
|
||
|
||
**Claude Code**，v2.1.142 或更新版本
|
||
|
||
```bash
|
||
/plugin marketplace add tw93/kami
|
||
/plugin install kami@kami
|
||
```
|
||
|
||
市场（marketplace）会将 Claude Code 指向生成的轻量插件包，而非整个网站与发布归档目录树。
|
||
|
||
**Codex 插件市场**
|
||
|
||
```bash
|
||
codex plugin marketplace add tw93/kami
|
||
codex plugin add kami@kami
|
||
```
|
||
|
||
这会从仓库市场（repo marketplace）将 Kami 安装为 Codex 插件，后续更新可使用 `codex plugin marketplace upgrade kami`，再执行 `codex plugin add kami@kami`。
|
||
|
||
**通用智能体**，适用于从 `~/.agents/` 读取的工具
|
||
|
||
```bash
|
||
npx skills add tw93/kami/plugins/kami -a universal -g -y
|
||
```
|
||
|
||
插件路径暴露的是生成的轻量技能包。裸用 `tw93/kami` 只会安装 `SKILL.md`，因为仓库根目录同时充当网站源码，且 `skills` CLI 会把根级技能视为单个文件。
|
||
|
||
**Claude Desktop**
|
||
|
||
下载发布资源 [kami.zip](https://github.com/tw93/kami/releases/latest/download/kami.zip),)，而非 GitHub 的源码 ZIP。打开 Customize > Skills > "+" > Create skill，直接上传 ZIP，无需解压。
|
||
|
||
ZIP 体积轻量，内含 `kami/` 技能文件夹。大型 CJK 字体未打入包内：在仓库检出环境中会优先从本地字体文件加载，否则走 jsDelivr CDN；在已安装的技能中，`scripts/ensure-fonts.sh` 会将缺失的中文字体或韩文字体恢复到用户字体目录。
|
||
|
||
**更新**
|
||
|
||
- Claude Code：`claude plugin update kami`
|
||
- Codex：`codex plugin marketplace upgrade kami`，然后执行 `codex plugin add kami@kami` 以刷新已安装快照
|
||
- Claude Desktop：下载最新 [kami.zip](https://github.com/tw93/kami/releases/latest/download/kami.zip),)，在技能卡片上点击 "..."，选择 Replace，上传
|
||
- 通用智能体：重新运行 `npx skills add tw93/kami/plugins/kami -a universal -g -y` 命令，会覆盖现有副本。暂时避免使用 `npx skills update`：当仓库根目录也存在 `SKILL.md` 时，它可能误判仓库子路径安装（vercel-labs/skills#1517）。
|
||
|
||
Kami 还会每天最多静默检查一次版本，并在聊天中提示有新版本可用；它只读取公开版本文件，不发送任何数据，离线时跳过检查。
|
||
|
||
## 使用
|
||
|
||
该技能会根据自然语言请求自动触发，无需斜杠命令。针对英文与中文优化；日文与韩文通过尽力而为的 CJK 路径支持，交付前会进行视觉 QA。
|
||
|
||
按语言划分的示例提示：
|
||
|
||
- English: `make a one-pager for my startup` / `turn this research into a long doc` / `write a formal letter` / `make a portfolio of my projects` / `build me a resume` / `design a slide deck for my talk` / `make this talk as a Marp deck` / `build a landing page for my app`
|
||
- 中文: `帮我做一份一页纸` / `帮我排版一份长文档` / `帮我写一封正式信件` / `帮我做一份作品集` / `帮我做一份简历` / `帮我做一套演讲幻灯片` / `帮我做一份 Markdown 风格的演示稿` / `帮我做一个产品落地页`
|
||
- 日本語: `スタートアップ向けの一枚資料を作って` / `この調査を長文レポートに整えて` / `正式な依頼文を作って` / `プロジェクト作品集を作って` / `履歴書を作って` / `登壇用スライドを作って` / `Marp で登壇スライドを作って` / `アプリのランディングページを作って`
|
||
- 한국어: `스타트업 원페이저를 만들어줘` / `이 리서치를 장문 문서로 정리해줘` / `정식 레터를 작성해줘` / `프로젝트 포트폴리오를 만들어줘` / `이력서를 만들어줘` / `발표용 슬라이드를 만들어줘` / `Marp 슬라이드로 만들어줘` / `앱 랜딩 페이지를 만들어줘`
|
||
|
||
**品牌配置**（可选）
|
||
|
||
创建 `~/.config/kami/brand.md` 以持久化身份、品牌、默认值与写作习惯。完整模板见 [brand.example.md](references/brand.example.md)。
|
||
|
||
该文件以 YAML frontmatter 承载结构化字段（如姓名、职位、邮箱、品牌色、语言、页面尺寸、语气），并以 Markdown 正文记录自由备注。Kami 将其视为最低分辨率上下文：仅当当前请求含糊时应用，且始终可被具体文档需求覆盖。目标是让你的作品风格连贯熟悉，而不让每份输出看起来一模一样。
|
||
|
||
## 设计
|
||
|
||
暖色羊皮纸画布 `#f5f4ed`，墨蓝 `#1B365D` 作为唯一强调色，衬线体承载层级，无硬阴影或花哨配色。这不是 UI 框架，而是印刷品的约束系统。文档应读起来像精心排版的页面，而非仪表盘。
|
||
|
||
- **模板。** 八种文档模板：One-Pager、Long Doc、Letter、Portfolio、Resume、Slides、Equity Report 与 Changelog，外加 Landing Page 系统，支持 EN、CN 与 KO。
|
||
- **图表。** 十八种内联 SVG 类型，含报告级架构图板。Sequence、class 与 ER 可由 Mermaid 文本编写：[beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid)) 渲染 SVG，`scripts/mermaid_normalize.py` 将其重新套用 Kami 调色板并使其 WeasyPrint 安全，不捆绑 Node。
|
||
- **幻灯片。** 三条渲染路径：默认 WeasyPrint HTML 转 PDF，按需 python-pptx 生成可编辑 PPTX，以及在 `assets/templates/marp/` 中的 Marp 变体，面向 Markdown 优先的演示文稿。
|
||
- **代码。** 安装 `Pygments` 时使用基于 Pygments 的语法高亮；未安装时 PDF 仍可渲染，代码保持单色。
|
||
- **打印。** 羊皮纸为默认画布；可选白底变体可将任意文档翻转为白底，便于家用或办公打印机输出，将暖色调沉入卡片与表格，层级依然清晰。[Kami 单页介绍](assets/demos/demo-kami-print.pdf)（中文）即用此变体渲染；配方见 [production.md](references/production.md)。
|
||
|
||
Kami 会根据你使用的书写语言选择对应的变体。
|
||
|
||
**字体**：每种语言在全页使用单一衬线字体。中文：TsangerJinKai02。日文：YuMincho。韩文：Source Han Serif K。英文：Charter。字体条款见 [许可证](#license)。
|
||
|
||
完整规范：[design.md](references/design.md)。速查表：[CHEATSHEET.md](CHEATSHEET.md)。
|
||
|
||
## 超越文档
|
||
|
||
同一套约束，延伸到页面之外：它既能排版可部署的网站，也能为 AI 图像渲染器撰写 brief（创作说明），让两者都呈现 Kami 风格。
|
||
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="25%" valign="top">
|
||
<a href="https://kami.tw93.fun"><img src="assets/showcase/kami-landing.png" alt="Kami 落地页" height="150"></a>
|
||
<br><b>Kami</b> · landing page
|
||
<br><sub>设计系统主页</sub>
|
||
</td>
|
||
<td align="center" width="25%" valign="top">
|
||
<a href="https://mole.fit"><img src="assets/showcase/mole-landing.png" alt="Mole 落地页" height="150"></a>
|
||
<br><b>Mole</b> · landing page
|
||
<br><sub>macOS 系统工具</sub>
|
||
</td>
|
||
<td align="center" width="25%" valign="top">
|
||
<img src="assets/illustrations/travel-spatialvla.png" alt="SpatialVLA 架构重绘" height="150">
|
||
<br><b>Architecture redraw</b> · English
|
||
<br><sub>SpatialVLA Figure 1, schematic</sub>
|
||
</td>
|
||
<td align="center" width="25%" valign="top">
|
||
<img src="assets/illustrations/travel-tesla-optimus.png" alt="Tesla Optimus 专利一览" height="150">
|
||
<br><b>Evidence layout</b> · 中文
|
||
<br><sub>Tesla Optimus 专利图一览</sub>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
落地页以可部署的多语言网站形式交付。插图由宿主自身的图像模型绘制：若宿主能生成图像（如 ChatGPT），则直接渲染；若不能（如 Claude 或 Codex），则输出 brief，供你粘贴到任意图像模型中。
|
||
|
||
```text
|
||
Redraw this as a clean editorial diagram. Background: warm parchment (#f5f4ed), never pure white. One accent only, ink blue (#1B365D); everything else in warm gray with a yellow-brown undertone, no other colors. Thin single-line geometric strokes and simple flat icons. No gradients, no drop shadows, no 3D. Labels in a serif typeface. Generous whitespace, calm and composed, like a figure in a well-typeset report.
|
||
```
|
||
|
||
<sub>由 ChatGPT Images 一次生成，无需人工修图。Kami 负责规范，渲染器负责绘制。</sub>
|
||
|
||
## 背景
|
||
|
||
我喜欢投资美股，经常让 Claude 写研究报告。每次输出都是同样的默认文档样式：灰蒙蒙、扁平乏味，每次会话布局还不一样。结构难以扫读，排版显得过时，页面也完全提不起我继续读下去的兴趣。于是我开始一点点修正字体、配色和间距，一条规则一条规则地改，直到报告变成我真正愿意阅读的页面。
|
||
|
||
后来我需要呈现《The Agent You Don't Know: Principles, Architecture and Engineering Practice》。我已有文档，不想从零做幻灯片，于是用 Claude Design 按自己的风格排版，一轮轮微调，最终达到了满意的效果。这个过程加入了内联 SVG 图表、统一的暖色调色板和更紧凑的编辑节奏。它不断扩展，直到覆盖我定期发布的每一份文档，我便持续抽象这一流程，最终形成了 kami：一套安静的设计系统，可以交给任意 agent，并信任其输出。
|
||
|
||
## 支持
|
||
|
||
- 最直接的支持方式是购买 [Mole for Mac](https://mole.fit),，我的付费 Mac 清理应用。
|
||
- 若 Kami 对你有帮助，欢迎点个 star、[分享](https://twitter.com/intent/tweet?url=https://github.com/tw93/kami&text=Kami%20-%20A%20quiet%20design%20system%20for%20professional%20documents.),，或提交 issue 或 PR。
|
||
- 我有两只猫，汤圆和 Coke。若你觉得 kami 让生活更美好，可以请它们吃 <a href="https://cats.tw93.fun?name=Kami" target="_blank">罐头 🥩</a>。
|
||
|
||
<details>
|
||
<summary>这些可爱的人已经喂过了 🐱</summary>
|
||
<br/>
|
||
<a href="https://cats.tw93.fun?name=Kami"><img src="https://cdn.jsdelivr.net/gh/tw93/sponsors@main/assets/sponsors.svg" width="1000" loading="lazy" /></a>
|
||
</details>
|
||
|
||
## 许可证
|
||
|
||
kami 代码与模板采用 MIT License。欢迎自由使用与贡献。
|
||
|
||
**字体**：TsangerJinKai02 仅供个人免费使用；商业使用须向 [tsanger.cn](https://tsanger.cn). 取得授权。Charter、YuMincho、Source Han Serif K 采用 OFL，CJK 回退字体为系统自带或开源许可。
|