diff --git a/README.md b/README.md index 19c633a..979e503 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,37 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/tw93/Kami) · [上游 README](https://github.com/tw93/Kami/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

Kami

-

Good content deserves good paper.

+

好内容值得好纸张。

Stars Version License Twitter
-## Why +## 为什么 -Kami (紙, かみ) means paper in Japanese: the surface where a finished idea lands. AI can produce documents better than most humans do manually. The missing piece is not capability but constraint: without a design system, every session drifts into generic gray and inconsistent layouts. +Kami（紙、かみ）在日语中意为「纸」：成品想法最终落定的表面。AI 生成文档的能力已优于大多数人手工制作。缺失的并非能力，而是约束（constraint）：没有设计系统（design system），每次会话都会滑向千篇一律的灰色与不协调版式。 -Kami fills that gap: one constraint language, eight document templates plus a landing-page system, simple enough for agents to run reliably, strict enough that every output is something you actually want to ship. +Kami 填补这一空白：一套约束语言、八种文档模板外加落地页（landing page）系统，简单到智能体（agent）可稳定运行，又严格到每一份输出都真正值得发布。 -Part of a trilogy: [Kaku](https://github.com/tw93/Kaku) (書く) writes code, [Waza](https://github.com/tw93/Waza) (技) drills habits, [Kami](https://github.com/tw93/Kami) (紙) delivers documents. +三部曲之一：[Kaku](https://github.com/tw93/Kaku))（書く）负责写代码，[Waza](https://github.com/tw93/Waza))（技）锤炼习惯，[Kami](https://github.com/tw93/Kami))（紙）交付文档。 -## Showcase +## 展示 -Real PDFs from one constraint set, across templates and languages. Click any preview to open it. +同一套约束下的真实 PDF，横跨多种模板与语言。点击任意预览即可打开。
Founder resume
Resume · English -
Founder resume, 2 pages +
创始人简历，2 页 		Kami print one-pager @@ -40,14 +46,14 @@ Real PDFs from one constraint set, across templates and languages. Click any pre Agent keynote slides
Slides · English -
Agent keynote, 8 slides +
Agent 主题演讲，8 页幻灯片
Mole product brief
One-Pager · English -
Mole product brief, 1 page +
Mole 产品简报，1 页 		Recommendation letter @@ -57,7 +63,7 @@ Real PDFs from one constraint set, across templates and languages. Click any pre Mole release notes
Changelog · English -
Mole v1.7.1 release notes +
Mole v1.7.1 发布说明 		Kaku portfolio @@ -67,139 +73,139 @@ Real PDFs from one constraint set, across templates and languages. Click any pre
-## Install +## 安装 -**Claude Code**, v2.1.142 or newer +**Claude Code**，v2.1.142 或更新版本 ```bash /plugin marketplace add tw93/kami /plugin install kami@kami ``` -The marketplace points Claude Code at the generated lightweight plugin bundle, not the whole website and release archive tree. +市场（marketplace）会将 Claude Code 指向生成的轻量插件包，而非整个网站与发布归档目录树。 -**Codex plugin marketplace** +**Codex 插件市场** ```bash codex plugin marketplace add tw93/kami codex plugin add kami@kami ``` -This installs Kami as a Codex plugin from the repo marketplace, so future updates can use `codex plugin marketplace upgrade kami` followed by `codex plugin add kami@kami`. +这会从仓库市场（repo marketplace）将 Kami 安装为 Codex 插件，后续更新可使用 `codex plugin marketplace upgrade kami`，再执行 `codex plugin add kami@kami`。 -**Generic agents** for tools that read from `~/.agents/` +**通用智能体**，适用于从 `~/.agents/` 读取的工具 ```bash npx skills add tw93/kami/plugins/kami -a universal -g -y ``` -The plugin path exposes the generated lightweight skill bundle. A bare `tw93/kami` would install only `SKILL.md`, because the repo root doubles as the website source and the `skills` CLI treats a root-level skill as a single file. +插件路径暴露的是生成的轻量技能包。裸用 `tw93/kami` 只会安装 `SKILL.md`，因为仓库根目录同时充当网站源码，且 `skills` CLI 会把根级技能视为单个文件。 **Claude Desktop** -Download the release asset [kami.zip](https://github.com/tw93/kami/releases/latest/download/kami.zip), not GitHub's source-code ZIP. Open Customize > Skills > "+" > Create skill, and upload the ZIP directly, no need to unzip. +下载发布资源 [kami.zip](https://github.com/tw93/kami/releases/latest/download/kami.zip),)，而非 GitHub 的源码 ZIP。打开 Customize > Skills > "+" > Create skill，直接上传 ZIP，无需解压。 -The ZIP is lightweight and contains a `kami/` skill folder. Large CJK fonts are excluded from the package: in a repo checkout they load from local font files first, then jsDelivr CDN; in an installed skill, `scripts/ensure-fonts.sh` recovers missing Chinese or Korean fonts into the user font directory. +ZIP 体积轻量，内含 `kami/` 技能文件夹。大型 CJK 字体未打入包内：在仓库检出环境中会优先从本地字体文件加载，否则走 jsDelivr CDN；在已安装的技能中，`scripts/ensure-fonts.sh` 会将缺失的中文字体或韩文字体恢复到用户字体目录。 -**Update** +**更新** -- Claude Code: `claude plugin update kami` -- Codex: `codex plugin marketplace upgrade kami`, then `codex plugin add kami@kami` to refresh the installed snapshot -- Claude Desktop: download the latest [kami.zip](https://github.com/tw93/kami/releases/latest/download/kami.zip), click "..." on the skill card, choose Replace, upload -- Generic agents: re-run the `npx skills add tw93/kami/plugins/kami -a universal -g -y` command, which overwrites the existing copy. Avoid `npx skills update` for now: it can mis-detect repo subpath installs while the repo root also has `SKILL.md` (vercel-labs/skills#1517). +- 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 also runs a quiet version check at most once a day and tells you in chat when a newer version is out; it only reads a public version file, sends no data, and is skipped when offline. +Kami 还会每天最多静默检查一次版本，并在聊天中提示有新版本可用；它只读取公开版本文件，不发送任何数据，离线时跳过检查。 -## Use +## 使用 -The skill auto-triggers from natural requests, no slash command needed. Optimized for English and Chinese; Japanese and Korean are supported via best-effort CJK paths with visual QA before delivery. +该技能会根据自然语言请求自动触发，无需斜杠命令。针对英文与中文优化；日文与韩文通过尽力而为的 CJK 路径支持，交付前会进行视觉 QA。 -Example prompts by language: +按语言划分的示例提示： - 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 슬라이드로 만들어줘` / `앱 랜딩 페이지를 만들어줘` -**Brand profile** (optional) +**品牌配置**（可选） -Create `~/.config/kami/brand.md` to persist identity, brand, defaults, and writing habits. See [brand.example.md](references/brand.example.md) for a full template. +创建 `~/.config/kami/brand.md` 以持久化身份、品牌、默认值与写作习惯。完整模板见 [brand.example.md](references/brand.example.md)。 -The file has YAML frontmatter for structured fields like name, role, email, brand color, language, page size, and tone, plus a Markdown body for freeform notes. Kami treats it as the lowest-resolution context: applied only when the current request is ambiguous, and always overridable by what the specific document needs. The goal is to feel familiar across your work without making every output look the same. +该文件以 YAML frontmatter 承载结构化字段（如姓名、职位、邮箱、品牌色、语言、页面尺寸、语气），并以 Markdown 正文记录自由备注。Kami 将其视为最低分辨率上下文：仅当当前请求含糊时应用，且始终可被具体文档需求覆盖。目标是让你的作品风格连贯熟悉，而不让每份输出看起来一模一样。 -## Design +## 设计 -Warm parchment canvas `#f5f4ed`, ink blue `#1B365D` as the sole accent, serif carries hierarchy, no hard shadows or flashy palettes. Not a UI framework; a constraint system for printed matter. Documents should read as composed pages, not dashboards. +暖色羊皮纸画布 `#f5f4ed`，墨蓝 `#1B365D` 作为唯一强调色，衬线体承载层级，无硬阴影或花哨配色。这不是 UI 框架，而是印刷品的约束系统。文档应读起来像精心排版的页面，而非仪表盘。 -- **Templates.** Eight document templates: One-Pager, Long Doc, Letter, Portfolio, Resume, Slides, Equity Report, and Changelog, plus a Landing Page system, in EN, CN, and KO. -- **Diagrams.** Eighteen inline SVG types, including a report-scale architecture board. Sequence, class, and ER can be authored from Mermaid text: [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) renders the SVG and `scripts/mermaid_normalize.py` re-themes it to the Kami palette and makes it WeasyPrint-safe, no Node bundled. -- **Slides.** Three rendering paths: WeasyPrint HTML to PDF by default, python-pptx for editable PPTX on request, and a Marp variant in `assets/templates/marp/` for Markdown-first decks. -- **Code.** Pygments-based syntax highlighting when `Pygments` is installed; without it, PDFs still render and code stays monochrome. -- **Print.** Parchment is the default canvas; an opt-in white-paper variant flips any document to a white background for home or office printers, sinking the warmth into cards and tables so the hierarchy still reads. The [one-page Kami intro](assets/demos/demo-kami-print.pdf) (Chinese) is rendered with this variant; recipe in [production.md](references/production.md). +- **模板。** 八种文档模板：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 picks the right variant based on the language you write in. +Kami 会根据你使用的书写语言选择对应的变体。 -**Fonts**: Each language uses a single serif font for the entire page. Chinese: TsangerJinKai02. Japanese: YuMincho. Korean: Source Han Serif K. English: Charter. See [License](#license) for font terms. +**字体**：每种语言在全页使用单一衬线字体。中文：TsangerJinKai02。日文：YuMincho。韩文：Source Han Serif K。英文：Charter。字体条款见 [许可证](#license)。 -Full spec: [design.md](references/design.md). Cheatsheet: [CHEATSHEET.md](CHEATSHEET.md). +完整规范：[design.md](references/design.md)。速查表：[CHEATSHEET.md](CHEATSHEET.md)。 -## Beyond Documents +## 超越文档 -One constraint set, applied past the page: it lays out deployable websites and briefs AI image renderers, so both come back in the Kami look. +同一套约束，延伸到页面之外：它既能排版可部署的网站，也能为 AI 图像渲染器撰写 brief（创作说明），让两者都呈现 Kami 风格。
- Kami landing page + Kami 落地页
Kami · landing page -
Design system homepage +
设计系统主页 		- Mole landing page + Mole 落地页
Mole · landing page -
macOS system utility +
macOS 系统工具 		- SpatialVLA architecture redraw + SpatialVLA 架构重绘
Architecture redraw · English
SpatialVLA Figure 1, schematic 		- Tesla Optimus patent overview + Tesla Optimus 专利一览
Evidence layout · 中文
Tesla Optimus 专利图一览
-Landing pages ship as deployable multilingual sites. Illustrations are drawn by the host's own image model: where the host can generate images, like ChatGPT, it renders directly; where it cannot, like Claude or Codex, it outputs the brief for you to paste into any image model. +落地页以可部署的多语言网站形式交付。插图由宿主自身的图像模型绘制：若宿主能生成图像（如 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. ``` -Rendered by ChatGPT Images in a single pass with no manual touch-up. Kami specifies, the renderer draws. +由 ChatGPT Images 一次生成，无需人工修图。Kami 负责规范，渲染器负责绘制。 -## Background +## 背景 -I like investing in US equities and ask Claude to write research reports all the time. Every output landed in the same default-doc look: gray, flat, a different layout each session. The structure was hard to scan, the formatting felt dated, and nothing about the page made me want to keep reading. So I started fixing the typography, the palette, the spacing, one rule at a time, until the report became a page I actually enjoyed. +我喜欢投资美股，经常让 Claude 写研究报告。每次输出都是同样的默认文档样式：灰蒙蒙、扁平乏味，每次会话布局还不一样。结构难以扫读，排版显得过时，页面也完全提不起我继续读下去的兴趣。于是我开始一点点修正字体、配色和间距，一条规则一条规则地改，直到报告变成我真正愿意阅读的页面。 -Later I needed to present "The Agent You Don't Know: Principles, Architecture and Engineering Practice." I already had the document and didn't want to build slides from scratch, so I used Claude Design to lay it out in my own style, tweaked it round after round, and eventually got it to a place I was happy with. That process added inline SVG charts, a unified warm palette, and a tighter editorial rhythm. It kept growing until it covered every document I regularly ship, so I kept abstracting the process, and it became kami: one quiet design system I can hand to any agent and trust the output. +后来我需要呈现《The Agent You Don't Know: Principles, Architecture and Engineering Practice》。我已有文档，不想从零做幻灯片，于是用 Claude Design 按自己的风格排版，一轮轮微调，最终达到了满意的效果。这个过程加入了内联 SVG 图表、统一的暖色调色板和更紧凑的编辑节奏。它不断扩展，直到覆盖我定期发布的每一份文档，我便持续抽象这一流程，最终形成了 kami：一套安静的设计系统，可以交给任意 agent，并信任其输出。 -## Support +## 支持 -- The most direct way to support me is getting [Mole for Mac](https://mole.fit), my paid Mac cleanup app. -- If Kami helped you, give it a star, [share it](https://twitter.com/intent/tweet?url=https://github.com/tw93/kami&text=Kami%20-%20A%20quiet%20design%20system%20for%20professional%20documents.), or open an issue or PR. -- I have two cats, TangYuan and Coke. If you think kami delights your life, you can feed them canned food 🥩. +- 最直接的支持方式是购买 [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 让生活更美好，可以请它们吃 罐头 🥩。
-These lovely people already did 🐱 +这些可爱的人已经喂过了 🐱
-## License +## 许可证 -MIT License for kami code and templates. Feel free to use and contribute. +kami 代码与模板采用 MIT License。欢迎自由使用与贡献。 -**Fonts**: TsangerJinKai02 is free for personal use only; commercial use requires a license from [tsanger.cn](https://tsanger.cn). Charter, YuMincho, Source Han Serif K under OFL, and CJK fallbacks are system-bundled or open-licensed. +**字体**：TsangerJinKai02 仅供个人免费使用；商业使用须向 [tsanger.cn](https://tsanger.cn). 取得授权。Charter、YuMincho、Source Han Serif K 采用 OFL，CJK 回退字体为系统自带或开源许可。