Kalka
文档

文件、Kalka 文件夹与版本

Kalka 保存的文件类型、Kalka 文件夹里有什么、自动保存和崩溃恢复如何工作,以及如何用 Git 保留设计的各个版本。

docs / files-versions

你的设计就是你电脑上的文件。Kalka 保存它们从不需要账户或服务器。

保存文档的三种方式

格式 是什么 适合
Kalka 文件夹 一个包含 HTML 页面、一个样式表、设计令牌和图片的文件夹 与开发者和智能体协作,在 Git 中保留版本
.kalka 同一个文件夹打包成的单个文件 以单个文件发送设计
.fig Figma 的文件格式 与 Figma 来回切换

保存(macOS 上为 Cmd S,Windows 和 Linux 上为 Ctrl S)写入你打开的文件。另存为… 选择一个新文件,格式为 .fig 或 .kalka。桌面应用中的 另存为文件夹… 会询问名称和位置,并在那里新建一个 Kalka 文件夹。

Kalka 文件夹里有什么

my-design/
  project.json          pages, artboard positions, settings, variables
  pages/
    home.html           one HTML file per page
    pricing.html
  styles.css            the classes your layers share
  design-system/
    tokens.json         your variables as W3C design tokens
    tokens.css          the same tokens as CSS custom properties
  assets/
    images/             every image, named by its content
  instructions/         optional rules, skills and documents for agents
文件夹面板列出一个 Kalka 文件夹:design-system、instructions、pages、project.json 和 styles.css
文件夹面板显示 Kalka 为文档写入的文件。

每个页面都是一个普通的 HTML 文件,可以在代码编辑器或浏览器中打开。开发者可以阅读它、在 Git 中审查它,并取用所需的内容。instructions/ 文件夹存放你告诉智能体的关于这个项目的信息:概要、规则、你自己的技能和参考文档。参见 Kalka 中的智能体。

安全保存

Kalka 会在旧文件旁边写入一个新文件,只有在完整写好之后才替换。即使崩溃、磁盘已满或写入失败,你的文件也会保持原样。Kalka 文件夹也以同样方式保存:每个文件都先写到一旁,所以文件夹要么是上一次保存的状态,要么是新的状态,绝不会是两者的混合。被中断的保存会在下次打开该文件夹时完成。

自动保存

新文档默认关闭自动保存。在“文件”菜单中打开 自动保存到本地文件,Kalka 会在你停止编辑几秒后保存。它需要一个可以写入的文件,所以请先保存一次文档。从云存储工作区打开的文档会自动保存。

在 Chrome 和 Edge 中,打开自动保存时浏览器会请求写入文件的权限。如果自动保存失败,Kalka 会提示你一次,并保留你的更改用于崩溃恢复,直到再次保存成功。

崩溃恢复

你工作时,Kalka 会在电脑上保存一份未保存更改的副本。如果 Kalka 或电脑在你保存前停止运行,下次启动时会显示 恢复未保存的工作:恢复 会找回这些文档,并关联到它们原来的文件,下次保存就会写入那里。丢弃 则会删除它们。

你可以在设置中关闭 自动保留未保存的工作。

其他应用修改了你的文件时

Git、同步工具或其他编辑器可能会修改你正在打开的文件。如果没有未保存的编辑,Kalka 会重新加载它。如果有未保存的编辑,Kalka 会保留它们并告诉你文件已更改;选择 Reload from disk 采用另一个版本,或者保存以用你的版本替换它。

用 Git 管理版本

左侧栏中的 历史 面板用 Git 保留文档的版本。它适用于桌面应用中保存在你电脑上的文档,并使用电脑上已安装的 git。

  1. 打开 历史。如果文件夹还没有保留版本,点击 保留版本。Kalka 会在文档所在的文件夹中创建一个 Git 仓库。
  2. 在 更改内容 中描述改了什么,然后点击 创建版本。Kalka 会先保存文档;如果保存失败,就不会记录任何内容。
  3. 要回到之前的状态,点击某个版本旁的 恢复。Kalka 会先记录你当前的状态,所以恢复本身也可以撤销,然后重新加载文档。

对于 Kalka 文件夹,一个版本记录整个文件夹。对于 .fig 或 .kalka 文件,只记录该文件:它旁边的其他文件永远不会被记录或恢复。

第一次使用时,Kalka 可能会询问你的姓名和电子邮件。它们只保存在该仓库中。

在线发布版本

要把版本保存在 GitHub 或其他 Git 托管平台上,先在那里创建一个空仓库,把它的地址粘贴到 在线发布 下,然后点击 连接。Kalka 会使用你电脑上已有的 Git 登录信息。此后,你记录的每个版本都会被发布。获取更新 会拉取从其他地方发布的版本,如果你离线时记录了版本,发布 会把它们推送上去。

如果改动是由智能体完成的,版本中会注明是哪个智能体,比如 Pebble。