KitionAI/kition · 上手攻略

  • 仓库：KitionAI/kition
  • 链接：https://github.com/KitionAI/kition
  • 分类：agent / desktop-app / local-first
  • 作者：spark
  • 更新：2026-10-26

三证 checklist（开篇自检） - ✅ GitHub URL：已 fetch（https://github.com/KitionAI/kition，2026-10-26 抓取，HTTP 200） - ✅ 版本锚点：最新 release v0.2.0（发布于 2026-10-10，commit 0d5d135），package.json 中 version: 0.2.0 - ✅ README 子模块 anchor：docs/runtime-development.md（crate 布局表）、docs/design-studio.md（.kidesign 契约）、docs/email-connections.md（IMAP/SMTP 供应商表） - ⚠️ 顶会/期刊 venue：不适用——本项目为产品型开源仓库，README 全文未出现任何会议/期刊引用，故不构成缺口 - ⚠️ 私有运行时：README 与 docs/runtime-development.md 表述存在版本漂移（详见「坑 1」），已标注

一、这是什么

Kition 是一个本地优先（local-first）的桌面 AI 工作区，用 Tauri 2 + React 写成一个应用，把五类东西塞进同一个工作区：

组件 文件格式 作用
文档（Documents） .md Markdown 实时预览、内部链接、反向链接、callout、KaTeX 数学公式、Mermaid 图、每日笔记、全文搜索、PDF 导出
表格（Tables） .ktable 类型化字段、附件、公式、筛选、排序、分组、多视图、AI 字段
白板（Boards） .kboard 无限画布上的流程图、思维导图、便签、手绘草图
智能体（Agent） — 可调用工具的 AI agent，能读/改文档、检索网页、查表结构、写回工作区
工作流（Workflows） — 触发器-动作画布、单步测试、运行历史

额外还有 Design Studio（.kidesign）：把文档、表格记录、Board 帧或 Agent 生成图变成可编辑海报，并输出 PNG/JPEG/SVG/PDF。

一句话概括产品主张：不是又一个"从空白对话框开始"的 AI 工具，而是给 Agent 一套可编辑的真实项目文件——有类型的记录、附件、可见的执行过程，让 AI 的操作可以被检查、修正和重复执行。

技术栈（来自 package.json + README 技术表）：

  • 桌面壳：Tauri 2（Rust）
  • 界面：React 19 + TypeScript + Vite
  • 文档渲染：Marked、Mermaid、KaTeX
  • 数据与状态：IndexedDB、Jotai、Zod（loro-crdt 1.16.4 提供 CRDT 协同）
  • 测试：Vitest、Playwright
  • 运行时：Rust workspace crates/，模型侧接 OpenAI Responses 与 Anthropic Messages
  • 许可：Apache-2.0；作者署名 Heartie Technology Limited（package.json 的 author 字段）

仓库活跃度（GitHub API，2026-10-26 实测）：530 stars / 39 forks / 2 open issues，主语言 TypeScript，最近推送 2026-10-26T07:00Z（当天仍在提交）。组织 KitionAI 创建于 2026-05-31，只有 4 个公开仓库——这是一个非常年轻的产品团队，这点在后面"坑"里会展开。

二、它解决什么问题

传统 AI 工作流的痛点是上下文在工具之间断掉：你在聊天框问 AI，AI 给你一段文字，你复制粘贴到文档；过两天你让 AI 改这个文档，AI 看不到上次改了什么、也看不到旁边的表格数据。

Kition 的解法是把上下文固化成文件：

  1. 文档不是 AI 的输出缓冲区，是 AI 的工作对象。Agent 直接改当前 Markdown 文档的真实文件，改完弹出 diff 审阅界面，你逐项 accept/reject，任务执行轨迹和文档始终并排可见。
  2. 结构化数据与叙述性知识同处一地。研究结论既在文档里，也在 .ktable 的类型化字段里；AI 字段（AI-assisted table fields）能让一行记录基于上下文自动生成文本、结构化值和媒体。
  3. 不确定的活儿交给 Agent，重复的活儿交给 Workflow。工作流在可视化画布上组装触发器-动作，启用前必须解决缺失输入、有运行历史可查。
  4. 可审阅的变更是核心设计，不是事后补丁。README 用了一整段讲"文件在编辑器外部发生变化时，Kition 会打开文档差异审阅界面"。

内置场景（都是普通 .ktable 文件，提示词/字段关系/审核状态全部可见可改）： - 缩略图生成器：核心信息 + 人像照片 → 类型化字段声明内容类型与目标情绪 → AI 字段为每条记录生成 16:9 与 9:16 缩略图。 - 收据 OCR：附件字段丢进票据照片 → 视觉字段在同一行里提取商户、地址、类别、结构化 JSON 和纯 OCR 文本。 - 批量产品设计：一个产品概念 → 多套设计方案、正交视图、功能图、生活方式图、风格板、发布文案，结果全部挂在源记录旁边。

三、快速安装

3.1 只想用（推荐路径）

桌面版通过 GitHub Releases 发布，不需要自己编译：

  • macOS：下载最新 .dmg（v0.2.0 资产含 Kition-0.2.0-macos-arm64.dmg、macos-x64.dmg）
  • Windows：下载最新安装程序
  • Linux（实验性）：下载最新 x86_64 .AppImage（v0.2.0 资产名为 Kition-0.2.0-linux-x64.AppImage）
  • 历史版本：https://github.com/KitionAI/kition/releases
# Linux 示例：下载并赋予执行权限
curl -L -o kition.AppImage \
  https://github.com/KitionAI/kition/releases/download/v0.2.0/Kition-0.2.0-linux-x64.AppImage
chmod +x kition.AppImage && ./kition.AppImage

⚠️ 上面的 URL 拼装形式是按 Release 资产命名规律推导的，我未实际执行过下载；建议直接点 Release 页面下资产，别手搓 URL。

3.2 要改代码（开发者路径）

硬性环境要求（engines 字段 + README + CONTRIBUTING 三处一致）：

  • Node.js 22.19.0（"node": ">=22.19.0 <23"）
  • pnpm 10.33.0（packageManager: pnpm@10.33.0；engines.pnpm 放宽为 >=10.16.0 <11）
  • Rust stable + 对应平台的 Tauri v2 系统依赖
pnpm install --frozen-lockfile
pnpm dev          # = tauri dev，编译 Tauri 壳并把 Rust 运行时编进去

只做渲染层/组件/编辑器/样式开发，不需要运行时集成时走更快的路径：

pnpm dev:web      # vite --config tooling/vite.config.ts --mode web-preview

pnpm dev:web 以"无后端预览模式"启动，依赖运行时的可选启动请求会被跳过，但文档编辑和视觉开发完全可用。若想连一个已经在跑的 API：

KITION_API_TARGET=http://127.0.0.1:18101 pnpm dev:web

Rust 侧检查：

pnpm check:desktop   # cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace

四、核心用法

4.1 让 Agent 改文档并审阅 diff

  1. 打开一个 Markdown 文档。
  2. 用自然语言描述目标（例如"把第三节改写成三点式，保留所有引用"）。
  3. Agent 读取当前文档 → 做出作用域受限的修改 → 写回真实文件。
  4. Kition 打开 diff 审阅界面，标出新增/删除/改写，逐项 accept 或 reject，或整体一次性审核。
  5. 完整任务轨迹与文档并排保留。

4.2 用 .ktable 做结构化流水线

表格是普通文件，可在 UI 里建，也可当数据源被 Agent 查询：

  • 类型化字段（含附件字段）
  • 公式字段、筛选、排序、分组、多视图
  • AI 字段：基于同行上下文生成文本、结构化值、媒体
  • Agent 可被要求"inspect table schemas"、创建/修改记录

典型收据 OCR 流程：附件字段放票据照片 → 视觉字段在同一行提取商户/地址/类别/JSON/OCR 文本 → 过滤、修正、交给 Agent 汇总 → 或送进审阅工作流。

4.3 邮件连接与收件箱同步

Kition 的工作流通过可复用的 SMTP 连接发邮件，通过 IMAP 导入收件箱。

创建连接：Settings > Email Providers → 选供应商 → 填账号地址 + 凭据。每供应商存一份，收件箱与投递工作流共用。

内置供应商（摘自 docs/email-connections.md，均为 TLS/STARTTLS）：

供应商 IMAP SMTP 凭据类型
Gmail imap.gmail.com:993 TLS smtp.gmail.com:587 STARTTLS Google 应用专用密码
Outlook / M365 outlook.office365.com:993 TLS smtp.office365.com:587 STARTTLS 需要时用应用密码
163 Mail imap.163.com:993 TLS smtp.163.com:465 TLS 客户端授权码
QQ Mail / Foxmail imap.qq.com:993 TLS smtp.qq.com:465 TLS 客户端授权码
Proton Mail Bridge 127.0.0.1:1143 STARTTLS 127.0.0.1:1025 STARTTLS Bridge 生成密码
Custom IMAP / SMTP 自填 自填 密码或 token

（另有 Yahoo、iCloud、126、Zoho、Fastmail、GMX、Mail.com，共 15 个内置项，此处节选。）

端口与 TLS 模式必须匹配，否则服务端会立刻断开连接，Kition 里表现为 EOF：

供应商设置 常用端口 Kition TLS 模式
隐式 TLS / SMTPS 465 TLS
STARTTLS 升级 587 STARTTLS
明文 SMTP 视供应商 Plain

挂到工作流： 1. 打开工作流 → 选 Send email 动作。 2. 在 Channel 区选已测试过的 SMTP 连接。 3. 保存工作流改动。 4. 配置状态有效后启用工作流。

收件箱同步：从目标 .ktable 文件进 → 侧栏打开其工作流 → New workflow → Full email inbox sync。该工作流自己拥有邮箱、目标表、调度、附件策略、当前进度和运行历史（Email Providers 不管同步执行）。

4.4 Design Studio 出图

  • 四种起手式：Layouts 面板（public/templates/design/ 下的数据模板 + 工作区品牌套件）、表格记录（右键 "Create design from record"，title/description/status 等字段自动填槽）、Board 帧（"Create design from frame"）、Agent 生成图（"Use in design" 会把图片里的文字保留成独立可编辑标题）。
  • 尺寸变体：poster / square / story / landscape 共享图层、各自记位置，文字与样式编辑同步到所有尺寸。
  • 品牌套件：Settings → Brand，工作区颜色/字体/logo 存 .kition/brand.json。
  • 与 Agent 协作：Agent 拿到的是画板、图层、品牌套件的有界描述，改动以预览流式上屏，带 accept/reject，接受后作为一步 undo 应用。契约在 contracts/runtime/agent-design.schema.json（capability agent_design_v1），客户端在改动文档前会校验每个 patch。
  • 导出：PNG / JPEG / SVG（字体与图片内嵌）/ 桌面端 PDF（按画板精确尺寸）；"Download all sizes" 导出全部变体；"Insert into document" / "Send to table" / "Copy image"。

4.5 开发者常用命令（package.json scripts 原文）

pnpm typecheck            # tsc --noEmit
pnpm test                 # = pnpm run test:unit（vitest）
pnpm test:e2e             # playwright，mock 后端的渲染层黑盒流
pnpm test:table:e2e       # bash scripts/inspect-table-widget.sh  ← 表格控件回归门禁
pnpm test:ktable:e2e      # bash scripts/inspect-ktable.sh        ← Table kit 回归门禁
pnpm build:check          # 桌面资产 + notices + typecheck + build
pnpm check                # 全量：branding/product-language/i18n/knip/deps/tessera/e2e-coverage/contracts/kit-host/lint/security/build:check/test
pnpm build:desktop        # node src-tauri/scripts/build.mjs

提交前 CI 等价命令（CONTRIBUTING 明确列出）：

pnpm check
pnpm test:e2e
pnpm test:table:e2e
pnpm test:ktable:e2e

改桌面壳还要加：

pnpm check:desktop
pnpm test:desktop:e2e

五、典型适用场景

  1. 研究者 / 知识工作者：文献综述写进 .md，每条研究的结构化元数据（标题、方法、样本、结论）放 .ktable 的类型化字段，Agent 跨两者检索并更新文档，diff 审阅保证不乱改。
  2. 内容团队批量生产：一个产品概念 → .ktable 记录 → Agent 生成多套设计/正交视图/风格板 → Design Studio 出海报与社交图 → 全部挂回源记录，便于比对、返工、交付。
  3. 财务 / 行政票据归档：收据照片进附件字段 → 视觉字段同行抽取商户/地址/类别/JSON/OCR 文本 → 过滤修正后进审阅工作流 → 通过 SMTP 发回。
  4. 小团队流程自动化：可视化画布组装触发器-动作，启用前测试单步、查运行历史、解决缺失输入。邮件进出都走同一套工作流。
  5. 贡献者 / 前端工程师：想给一个 local-first AI 工作区写 UI，或者想读懂"AI agent 如何被约束在可审阅的文件边界内"这套设计——contracts/runtime/ 是一份相当完整的公共契约样板。

六、坑与注意（7 条）

坑 1 · README 说运行时是私有的，runtime-development.md 说它在 crates/ 里——文档版本漂移

  • 现象：README 写 "The Kition runtime is maintained separately and its source is not included in this repository"，并强调"There is no Go source, Go module, or runtime source-build fallback in this repository"；但 docs/runtime-development.md 明确写 "The Kition runtime is the Rust workspace under crates/"，还给出 kition-api/kition-core/kition-store/kition-ai/kition-agent/kition-workflow 等 crate 职责表。
  • 影响：新贡献者无法判断改运行时行为到底该动哪个仓库；docs/development-standard.md 的"Repository boundary"节又说本仓库拥有 crates/ 里的 Rust 运行时——三处文档互相矛盾。
  • 修复：以 docs/runtime-development.md + docs/development-standard.md 为准（更新），README 那段是旧文案；改运行时行为时按开发标准走"契约 + 渲染层 mock + runtime crate 三者同改"。读 README 时对运行时边界保持怀疑。

坑 2 · 仓库处于 beta，官方明确要求备份工作区

  • 现象：README 原文 "Kition is currently in beta. Back up important workspaces and review agent changes before relying on them in production workflows."
  • 影响：Agent 会直接改你的真实文件；一旦有 bug 或模型跑偏，可能破坏工作区内容。
  • 修复：把工作区当代码对待——用 Git 或定期快照管理 .md/.ktable/.kboard/.kidesign；Agent 改完一定走 diff 审阅再合并。

坑 3 · 团队极年轻、issue 少、迭代极快，踩坑后可能无人可问

  • 现象：组织 KitionAI 2026-05-31 才创建，仅 4 个公开仓库；仓库 open issues 只有 2 个，但 2026-07-25 创建以来近三个月发布了 40+ 个 release（v0.1.41 → v0.2.0），版本号在 v0.1.x 区间快速迭代。
  • 影响：文档与实现脱节（坑 1 就是实例）；v0.1.x 的老文章/老教程引用的命令和子路径很可能已失效。
  • 修复：任何命令前先核对当前 package.json 的 scripts；本文所有命令均取自 v0.2.0 的 package.json 原文，但请以你 checkout 的 commit 为准。

坑 4 · Linux 版的架构命名在两个 release 间变了

  • 现象：v0.1.49 资产名为 Kition-0.1.49-linux-x86_64.AppImage，v0.2.0 资产名为 Kition-0.2.0-linux-x64.AppImage。
  • 影响：按老文章里的资产名拼 URL 会 404。
  • 修复：从 Release 页面点资产，别手搓文件名。

坑 5 · 邮件配置的 EOF 报错几乎总是端口/TLS 模式错配

  • 现象：文档原文——"A server can close the connection immediately when the port and TLS mode do not match, which Kition may report as EOF"；163 邮箱用 465 端口配 STARTTLS 在 "Test & Save" 阶段就返回 EOF。
  • 影响：初次配置邮箱时容易误判为"账号密码错误"或"服务挂了"。
  • 修复：465 → TLS，587 → STARTTLS；163/126/QQ/Foxmail 必须用客户端授权码而不是网页登录密码（163 还需先在邮箱设置里开启 SMTP 服务）；Gmail 必须用应用专用密码。

坑 6 · pnpm dev 需要完整 Tauri 工具链，只改前端就别用它

  • 现象：README 明确 pnpm dev 会"verifies and caches the pinned released runtime outside the Git worktree"再启动 Tauri 客户端；需要 Node 22.19.0 + pnpm 10.33.0 + Rust stable + 平台 Tauri 系统依赖。
  • 影响：在 CI 容器或缺 Rust 工具链的机器上 pnpm dev 直接失败，白等编译。
  • 修复：纯前端/组件/编辑器/样式工作用 pnpm dev:web；确需桌面运行时再装全 Tauri 依赖（Linux 还要装 webkit2gtk 等系统库）。

坑 7 · 提交前必须过两道"回归门禁"，它们不是可选项

  • 现象：CONTRIBUTING 把 pnpm test:table:e2e 与 pnpm test:ktable:e2e 列为 "Required table-widget regression gate" 和 "Required Table kit regression gate"；且 pnpm check 串联了 15 个子检查（含 check:security 跑 check-secrets.py + pnpm audit --audit-level high、check:contracts 校验契约生成物、check:knip 死代码基线）。
  • 影响：只跑 pnpm test 就提 PR，CI 会挂。
  • 修复：开 PR 前照抄 §4.5 的四条命令；涉及契约变更时按"契约 + 渲染层 mock + runtime 同改"三件套走，AGENTS.md 要求先读 contracts/runtime/。

补充 · 诚实标注（本地 API 无鉴权、遥测/账号依赖）

  • docs/runtime-development.md 明确："The local API is unauthenticated: it binds to 127.0.0.1 only and rejects requests whose Host header is not loopback."——本地 API 无鉴权，仅靠 loopback 绑定 + Host 头校验防护。不要把 18101 之类的端口暴露到公网。
  • ⚠️ 未核项：Agent 底层模型配置（OpenAI Responses / Anthropic Messages）具体走哪个 provider、是否需要账号、额度如何计算，README 只说"Settings 里可配模型、代理、MCP、账户、用量"，未给出价格与免费额度；本机 AI 能力是否可用取决于你自己的 API key 与网络，本文未能核实。
  • ⚠️ 未核项：仓库 topics 里同时有 electron 和 local-first，但实现是 Tauri 2 而非 Electron——topics 与实际技术栈不一致，按 topics 检索会误判。

七、与同类对比

维度 Kition Obsidian Notion AI n8n / Dify / Coze 类
形态 本地桌面（Tauri 2） 本地桌面 云端 SaaS 云端 / 自托管工作流平台
数据归属 本地文件（.md/.ktable/.kboard/.kidesign） 本地 .md + 插件 云端数据库 云端 / 自建服务器
AI 的角色 可审阅地改真实文件（逐项 accept/reject） 插件生态，AI 需自行接入 侧栏问答/写作助手 编排节点，AI 是节点参数
结构化数据 内建类型化字段表格 + 公式 + AI 字段 靠 Dataview/Database 插件 原生 Database 外部系统
可视化 Board 无限画布 + Design Studio Canvas（较新） 有限 工作流画布
自动化 触发器-动作画布 + 邮件 IMAP/SMTP 需第三方插件 数据库自动化 核心能力、最成熟
成熟度 beta，v0.2.0，团队 3 个月 十余年生态 成熟商业产品 各异

怎么选： - 已经在 Obsidian 且只想加 AI → 留在 Obsidian + Obsidian Copilot/插件，Kition 迁移成本高。 - 团队协作、需要成熟权限与审计 → Notion。 - 核心诉求是"AI 改我的真文件，而且我要能逐条审" + 本地优先 + 数据表格与文档同处 → Kition 是当前少数明确以此为主打的桌面应用。 - 纯流程自动化（无数 AI 节点）→ n8n/Dify 这类专用平台更合适，Kition 的工作流是"可见、可审"而非"极复杂编排"。

Kition 的真正差异化不是功能清单（每项单看都有竞品），而是把 AI 的写权限关进文件 + diff 审阅 + 可见执行轨迹这个组合设计——这是 Copilot 类"光标内补全"和 Agent 类"直接改仓库"之间的第三条路。

八、一句话推荐结论

推荐，但请按 beta 试用。 如果你需要的正是"AI 在我的本地文档/表格里动手改、我逐条审阅、结果可回滚"这套交互，Kition 目前在同类里设计最完整、公开契约最清晰，值得装一个 v0.2.0 在非关键工作区里试；但它只有 3 个月历史、v0.1.x 快速迭代、运行时边界文档三处打架，不适合承载不可重建的关键数据，务必先做工作区备份。

附：本文事实来源清单（全部 2026-10-26 抓取）

来源 用途
https://github.com/KitionAI/kition（README 英文） 产品定位、五大组件、技术栈表、发布方式、仓库结构
https://github.com/KitionAI/kition/blob/main/README.zh-CN.md 官方中文表述、"测试阶段/备份"警告原文
https://github.com/KitionAI/kition/releases/latest → tag v0.2.0 最新版本号、发布日 2026-10-10、commit 0d5d135
raw.githubusercontent.com/.../main/package.json version 0.2.0、engines、packageManager、全部 scripts、依赖版本、author 署名
raw.githubusercontent.com/.../main/docs/runtime-development.md crate 布局表、check:desktop 说明、本地 API 无鉴权与 Host 头校验、契约边界规则
raw.githubusercontent.com/.../main/CONTRIBUTING.md 环境要求、dev vs dev:web、身份分级 dev/rc/stable、测试门禁表、PR 前检查清单
raw.githubusercontent.com/.../main/docs/development-standard.md 仓库边界、分支/worktree 规范、Agent 任务契约模板
raw.githubusercontent.com/.../main/docs/design-studio.md .kidesign 格式、Layouts/记录/Board/生成图四种起手式、尺寸变体、品牌套件、导出、agent_design_v1 契约
raw.githubusercontent.com/.../main/docs/email-connections.md 15 个邮件供应商表、TLS 模式与端口对应、163 授权码、EOF 故障说明、Full email inbox sync 流程
GitHub REST API /repos/KitionAI/kition 530 stars / 39 forks / 2 issues / TypeScript / Apache-2.0 / topics / created 2026-07-25 / pushed 2026-10-26
GitHub REST API /repos/KitionAI/kition/releases 各版本资产文件名（Linux x86_64 → x64 命名变化）
GitHub REST API /orgs/KitionAI 组织创建日 2026-05-31、公开仓库 4 个
web_search「KitionAI kition desktop app ktable .kboard agent workflow release v0.2.0」 官方站点 kition.ai 描述侧证（结果多为无关站点，未采信）