Ginkgo 使用指南

Ginkgo 要求 macOS 14 或更高版本。两种安装方式装的是同一个 app:装好后 Ginkgo 安静地住进菜单栏,不占 Dock。

一行命令会取回最新发布,把 Ginkgo 放进「应用程序」并自动启动;curl 下载不带隔离属性,因此不会遇到 Gatekeeper 的首启拦截。想固定版本,可在命令前加 GINKGO_VERSION=v0.1.2。

• DMG 安装:从官网下载页取回 Ginkgo.dmg,打开后把 Ginkgo 拖进「应用程序」。

或用 Homebrew 安装(与 DMG、install.sh 为同一发布版本):

从 Clipmate 升级:Ginkgo 前身是 Clipmate,首次启动时会自动把旧历史一次性、安全地迁移进来,旧的自写入依旧不会被再次捕获;设置不迁移(不同的 defaults 域),需要重新调整。

Ginkgo 启动后住进菜单栏,就是屏幕右上角的银杏叶。启动瞬间,一张更大的带银杏叶与名字的卡片会浮现约 1.5 秒,随后会自动打开历史记录窗口,方便你看到剪贴内容保存在哪里。在计时结束前点一下卡片可以只关掉闪屏、不打开历史记录;卡片在屏幕上时不会激活 app,也不抢焦点。

左键单击银杏叶打开快捷粘贴(与全局热键同一套切换);右键单击打开菜单,里面是几件常用事:

• 「打开历史记录…」(⌘H):打开历史记录窗口。
• 「设置…」:打开设置窗口(⌘, 也可以)。
• 「解锁完整版…」:打开官网购买页。
• 「退出 Ginkgo」(⌘Q):退出 app。

首次启动还会遇到唯一一次权限询问:粘贴板访问。

1. 01在 macOS 15 及更高版本,后台读取剪贴板由系统的「来自其他 App 的粘贴」开关管理;Ginkgo 启动时会弹出一扇小的引导窗口说明这件事。
2. 02点「打开系统设置…」,在「系统设置 › 隐私与安全性 › 其他 App 的粘贴板」里开启 Ginkgo。
3. 03点「仍然继续」可以先跳过——但只有允许之后,复制的内容才会自动进入历史记录;允许后无需重启。
4. 04在 macOS 14 上没有这道门槛:无需任何操作,复制已在记录。

在任何 app 里按下 ⌘C,屏幕右下角浮出一层小面板:上方是刚复制的原文(文本、图片缩略图,或带图片/PDF 预览磁贴的 Finder 文件名),命中插件的洞察紧贴其下。点按图片或文件预览磁贴,会在系统的「快速查看」中打开,可缩放。从 Finder 复制单个图片文件时按截图类图片剪辑处理;单个 PDF 在恢复/粘贴时写入 PDF 字节而非路径。面板不激活 app、不抢键盘焦点,前台输入不受任何影响。

同一时刻菜单栏图标会轻跳一下确认捕获——与轻浮层同一闸门——浮层被挡住或一闪而过时也能感知到。系统开启「减少动态效果」时不跳。

• 时间戳:Unix 时间戳或 ISO 8601,一眼译成可读时刻。
• 词典:复制单词,释义就地展开——查词在设备上经「词典」App 完成;可在 设置 › 插件 › 词典 选择英语→中文或中文→英语。
• 证书:PEM 证书一眼看清主题、签发者、有效期与指纹。
• JSON:payload 按键排序、对齐呈现。
• 未命中的内容,原文永远原样呈现。

「采用」把洞察结果写回剪贴板;在你采用之前,剪贴板一直保留原始内容,直接关掉面板不改变任何东西。

面板约 6 秒自动消失;新的复制会替换内容并重新计时;随时可点关闭按钮,或向右一挥——它跟随光标,松手即飞出屏幕;短拖、左拖或竖直拖会弹回原处。

「采用」旁有一枚相机按钮:把结果拍成署名分享卡片(见下一节);还有「在历史记录中打开」,直接跳到这条剪辑。

相机按钮拍下的是插件的完整结果——不是面板上的缩短预览:一张深色窗口样式的卡片,插件名作标题,落款「Ginkgo」,以 PNG 写入剪贴板,直接可贴进聊天窗口。

较短的原文(比如时间戳背后的那串 epoch 数字)会以说明文字出现在结果上方。

四种卡面在「设置 › 分享卡片主题」里挑选:暮色银杏(默认)、银杏叶、金秋、素笺;下一次拍摄即刻生效,历史记录里把转换拷贝为图像的操作,用的也是同一个主题。

菜单栏的「打开历史记录…」(⌘H)打开一个普通窗口(标题「Ginkgo 历史记录」):左侧列表、右侧详情,分栏可拖动,窗口大小与位置跨启动保留。与轻浮层不同,它正常接收键盘焦点——这是你主动打开的管理界面。

• 浏览:每行显示类型图标,或 Finder 文件剪辑的 32 pt 图片/PDF 预览磁贴、标题、相对时间、标签与置顶标记;列表获得焦点时,↑↓ 移动选择。详情对每个可预览的图片/PDF 条目显示更大预览(点按打开快速查看)以及名称与路径。
• 查找:⌘F 聚焦搜索,对标题、预览与正文做大小写不敏感的子串匹配;类型与标签筛选(任一所选类型 / 任一所选标签)与搜索取交集;窗口开着时,新的复制实时出现。
• 详情:标题下一排动作——置顶、标签、删除,以及醒目的「拷贝」;删除按名称确认,误删可用 ⌘Z(或撤销条)恢复,元数据与已存转换一并回来。
• 整理:标题旁的铅笔就地重命名(Return 保存,Esc 取消);标签在弹窗里附加或新建——每个标签有颜色(创建时默认随机,可选色板,之后可在弹窗改色);删除标签会在确认后从所有剪辑移除(不可撤销)。
• 恢复:「拷贝」通过与轻浮层相同的受守卫写入器把原文放回剪贴板——恢复写入不会被再次捕获,也不会重新唤起浮层。
• 智能体:列表列底部的 ✨(齿轮旁),或全局快捷键 ⌘⇧A(默认;「设置 › 快捷键」可改),在阅读窗口打开智能体标签——已许可且已配置时的全局入口。状态栏菜单没有智能体项。
• 智能体会话:选中带智能体对话的剪辑时,详情页出现「智能体会话」分区——每个会话一张卡片(标题与相对更新时间,最新的在前),点按即在阅读窗口的智能体标签打开该会话。
• 窗口内键:⌘P 切换选中项(含多选)置顶;⇧⌘M 合并当前多选(与批量「合并」按钮同一确认对话框);⌘O 打开选中剪辑首条文字转换的阅读器(没有可读转换时静默)。默认全局键 ⌘⇧H 也可从任意应用打开历史。

在详情页底部输入 / 或点按输入框右侧的下拉按钮,列出此剪辑可用的已启用插件;继续输入即可筛选,Return 或点按运行。结果就地保存在这条剪辑上,重开窗口仍在;转换从不写剪贴板,也不会多出兄弟条目。

Base64 / URL 编解码与 MD5 / SHA-256 只对文本剪辑列出,且只在按需运行——编码器与哈希几乎能「命中」任何文本,放在复制时只会淹没真正需要的洞察。

翻译(/translate,需要 macOS 26 或更高版本):在本机用 Apple 翻译框架翻译选中的文本剪辑,从不在复制时运行。

• 目标语言在运行时选择,共十种:简体中文、English、日语、韩语、法语、德语、西班牙语、俄语、葡萄牙语、意大利语。
• 输入可按中文名、英文名或代码筛选(ja、日 都能找到日语),↑↓ 或点按选择;直接 Return 运行预选的默认值——即「设置 › 插件 › 翻译 › 默认目标语言」(新装默认简体中文)。
• 源语言自动检测;已是目标语言、无法检测源语言,或系统不支持这对语言时,给出一行提示,不保存任何东西。
• 结果作为该剪辑的转换保存,标题为「源 → 目标」;再次翻译会替换上一次结果。
• 翻译需要语言对的语言包:缺失时会提示去「系统设置 › 通用 › 语言与地区 › 翻译语言」添加(下载来自 Apple);低于 macOS 26 时,/translate 不在列表里,设置子页会写明「需要 macOS 26 或更高版本」。

Markdown(/markdown):把文本剪辑或复制的 .md / .markdown 文件转成自包含的带样式 HTML 文档;历史记录里有应用内渲染预览与可选中的 HTML 源码,「拷贝 HTML」经受守卫路径写入,不新增历史行。围栏 mermaid 代码块会渲染为图表(内置运行时,无网络)。从不在复制时运行。

HTML(/html):把看起来像 HTML 的纯文本(或复制的 .html / .htm 文件)在历史记录里安全渲染为应用内预览——经消毒、关闭内容 JS、禁止远程拉取。与 Format 的 HTML 美化打印不同。以预览为主(无「拷贝 HTML」);从不在复制时运行。

格式化(/format):在本机把文本剪辑按 JSON、JSONC、YAML、XML、JavaScript、TypeScript、HTML 或 CSS 美化输出。语言在命令第二段显式选择(默认 JSON,不做自动识别);语言与内容不符或剪辑超过约 250 KB 时给出一行提示且不保存,全部通过内置引擎在本机完成——不经网络。

二维码(/qr):把文本剪辑生成一张可扫描的二维码 PNG,铺在你选的底图上——四种预设渐变底图(素白、银杏、海洋、晚霞),或在「设置 › 插件 › 二维码」里上传一张自选图片作底图(「选择图片…」,即时生效)。内容过长时给出一行提示且不保存任何东西。从不在复制时运行。

图片(/image):针对图片剪辑的按需转换:缩小到 75% / 50% / 25%,或中心裁剪为 1:1 / 4:3 / 16:9。原始剪辑永不改动;重跑会用新结果替换已存结果。

文字识别(/ocr):用本机 Apple Vision 识别图片剪辑中的文字——.accurate、简繁中文与英文,全程无云——并存为该记录的纯文本转换,「拷贝」经受守卫的路径写出识别文字。没有第二阶段可选(无参数);图中无文字、或内置缩放后仍过大,给出一行提示且不保存任何东西。从不在复制时运行。

图像转换:转换结果也可以是一张图片——卡片就地显示图像,点按在系统的「快速查看」中打开放大查看(详情页的原图与轻浮层的图片缩略图同样一点即开)。卡片动作是「拷贝图片」——经受守卫的写入器写回剪贴板,不会回流进历史——与移除。图像转换不会同步到其他设备,留在生成它的那台 Mac 上。

智能体(/agent,需要许可):在这条剪辑上运行一个多步、会使用工具的 AI 智能体,使用你自己的云模型 key(OpenAI、Anthropic 或任意 OpenAI 兼容服务商,在设置里配置)。它可以读取本剪辑(图片剪辑会把画面一并发往你配置的服务商)、搜索历史、读取剪辑所指的文件、抓取公开网页,每次受限调用都先经确认卡片批准;命令后直接输入指令即可自由把控方向。从不在复制时运行;已存的运行会把工具调用与来源一并带进阅读器。

运行智能体:回答随生成逐步流入。轻浮层上,剪辑对应的预设胶囊一点即跑;「更多…」在该剪辑上打开阅读窗口的智能体标签(可携带已完成的回答)。历史记录里 /agent 在详情页就地运行;列表底部的 ✨ 打开同一智能体标签的全局入口。标签内为文档式排版:每个回合自上而下是你的提问、智能体走过的步骤(每个工具一行:做了什么、具体是哪个网址/路径/查询/剪辑),以及正在流入的回答。以 #(或全角 ＃)开头一个词,输入框上方会弹出可搜索的历史剪辑下拉:↑↓ 移动、Return 插入 #标题 、Esc 关闭,输入法组字中不会触发;发送时被引用的剪辑只以标题与 id 附进消息,模型经 read_history_clip 读取其内容,且恰好这些被引用的 id 本次运行不再请求批准——其他 id 照常询问。多行输入框按 Return 发送(Option/Shift+Return 换行,输入法组字中的 Return 只上屏不发送),Esc 停止运行或拒绝待确认的调用,但不会关上阅读窗口(只有在转换标签上 Esc 才关窗)。

会话:左侧边栏列出本地保存的对话——点选切换,+ 新建不绑定剪辑的会话(空对话显示一行引导语);鼠标悬停某行才出现删除(右键菜单也可删)。从剪辑或 /agent 进入时会打开或创建绑定该历史行的会话;对已完成回答使用「存为转换」会写入这条剪辑。全应用同一时刻只跑一条智能体任务。

工具确认:每张卡片写明工具、完整展示参数,并提供「拒绝」、「始终允许」(仅限该范围:抓取按域名,其余按工具本身)与「仅允许一次」。「仅允许一次」是唯一的突出按钮,且刻意不绑定 Return——确认卡弹出时按 Return 不会有任何效果,同意永远是一次明确的点击。

所有已存转换共用一个阅读器窗口:每次打开都新增一个标签页,再次打开已打开的转换只是选中它;只有一个标签时窗口不显示标签栏,标签也不跨启动恢复。每个标签各自记住滚动位置、「预览 / 源码」选择与拷贝反馈,⌘+ / ⌘− / ⌘0 缩放(80–200%)整个窗口共享,Markdown 预览与卡片拷贝动作照常可用;⌘W 关闭当前标签(最后一个标签随之关闭窗口),Esc 关闭窗口,右键标签还能关闭其他或右侧标签,删除转换或剪辑只关闭它自己的标签。

从 app 菜单、菜单栏菜单的「设置…」,或历史记录列表列底部的齿轮打开(⌘, 也可以):固定大小的窗口,内容可滚动,所有选择即时生效、无需重启。

• 语言:跟随系统(默认;偏好语言含 zh 则解析为简体中文,否则英文)、English 或 简体中文——菜单、窗口标题、轻浮层与插件洞察一并切换。
• 外观:跟随系统(浅色为银杏白,深色为墨叶)、银杏白 · 浅色、墨叶 · 深色;轻浮层、启动卡片、历史与设置全部跟随。
• 更新:显示当前版本与「检查更新」;有新版本时可「更新 / 稍后 / 跳过此版本」。菜单栏同一行。Homebrew 安装请用 brew upgrade --cask ginkgo,不会走应用内替换;本地 ad-hoc 构建可能提示不支持应用内更新。
• 分享卡片主题:进入子页,在四种卡面的真实预览上直接挑选(返回或 Esc 退出)。
• 快捷键:子页列出三个全局动作(快捷粘贴、打开历史、打开智能体)与当前字形——可录制改键、单项恢复默认或全部恢复。写穿即时生效并跨启动保留;录制会拒绝裸键、与 Ginkgo 其他全局键重复、以及系统保留组合。页面注明:与其他应用的冲突无法探测;⌘S / ⌘C 类组合可通过但会与常见菜单撞车;每次应用更新后可能需重新授予「辅助功能」。
• 插件:一行显示已启用数量;页面把每个插件列为卡片,按优先级排列——名称、一句话描述,外部包另带「外部」徽标与包版本——每张卡带行内开关,即时生效并跨启动保留。卡片顺序就是匹配优先级:右键卡片可上移、下移或移到顶部。多数剪辑插件以第一方 .ginkgoplugin 随应用发布并在启动时同步;Markdown、HTML 预览、智能体、二维码与图片仍内置于应用。点开卡片进入详情页,有「启用」开关、描述与插件设置(翻译的「默认目标语言」、自动清理的「保留天数」、二维码的默认底图与自选图片,以及智能体的服务商、base URL、模型与 API key)。已激活的安装还会在独立分区看到全局插件「自动清理」——免费档完全不显示。插件只在这里管理。
• 外部插件:把 .ginkgoplugin 文件夹拷进 ~/Library/Application Support/Ginkgo/Plugins/——没有市场,没有应用内安装器——然后点「重新扫描」(页脚还能打开插件文件夹,并列出被拒载的包及其原因)。外部插件的开关只有在你授予其清单声明的全部能力后才会打开;授权只是同意记录,不是强制手段。外部插件在免费档可用,默认关闭,且永不自动更新——包变更后旧代码继续运行,直到你重启应用,并以提示标明。

「同步」是官方的端到端加密历史同步插件(dev.ginkgo.sync,作者测试阶段需手工安装):历史在上传前先在本机加密,服务端只存密文。同步与 app 许可相互独立,需要订阅——Standard($1.29/月或 $9.99/年,1 GB 同步库、单附件 ≤ 10 MB)或 Plus($1.99/月或 $19.99/年,10 GB、≤ 100 MB)。结账完成后官网返回页会展示一次订阅密钥,创建同步库时粘贴即可。

1. 01在设置 › 同步选「创建同步库」:设置口令(输两遍)与设备名,再粘贴订阅密钥。
2. 02在另一台 Mac 上装好插件选「加入同步库」;先在已同步的 Mac 生成配对码(8 位、一次性、5 分钟),再输入该码。
3. 03历史随即在后台同步——启动时、运行中约 45 s 轮询、本地保存后 5 s、唤醒时各一次;同步页提供「立即同步 / 取消」。

• 口令只在本地以 Argon2id 包裹同步库密钥,绝不上传;忘记口令且再无已加入的 Mac 时,云端副本永久无法解密,任何人都无法重置。
• 一个订阅对应一个在用同步库;把密钥绑到新库会替换旧库(旧库停止同步、30 天后删除,期间用同一密钥可换回)。订阅取消后同步停止并开始同样的 30 天倒计时,应用内与网页统计页都会显示删除日期。
• 套餐容量只拒附件上传——记录与删除照常推送,超配额的库可以先删后补;超单文件上限的附件标记「不可用」,文本照常同步。
• 未激活 app 许可证的 Mac 拉取受免费档 200 条上限;激活序列号后会自动全量重拉补齐。
• 设置 › 同步可打开网页统计页(一次性码登录):上传热力图、累计/本周/本月上传、连续天数、存储构成、订阅状态与账单门户。

免费档不是试用:复制、轻浮层与插件洞察完全不受限。历史存满 200 条后,新的复制不再入库;已有条目永久保留,可查可恢复;删到 200 条以下,自动恢复入库。

解锁无限历史:$3.99/年订阅或 $7.99 买断(美元计价),由 Dodo Payments 托管收款与发码;购买成功后,序列号自动发到你的邮箱,一个序列号最多激活 2 台设备。

1. 01在「设置 › 许可」输入序列号,点「激活」;首次激活需要联网,之后离线照常使用。
2. 02年付订阅自动续订,序列号始终不变——约每 30 天一次的静默重验把许可向前推进;取消订阅或许可失效后回落免费档,已存历史全保留。
3. 03买断一次付清,永久使用;赠阅码自激活之日起 14 天有效。
4. 04设备名额满了:在旧设备上打开「设置 › 许可」,点「解绑此设备」释放名额(解绑后那台设备回到免费档),再在本机激活。

三个全局快捷键在任意前台应用下生效(默认见下表;可在「设置 › 快捷键」改绑)。菜单与窗口内快捷键仍只在 Ginkgo 前台时生效。退出 Ginkgo 后全局键全部停止。

快捷粘贴是 Spotlight 式的最近剪辑选单(严格按创建时间最新在前;置顶不影响次序)。选单从不激活 Ginkgo:前台应用保持焦点。图片剪辑与 Finder 图片/PDF 文件剪辑在行内显示缩略图——点按磁贴打开快速查看;Return 或点按行的其余部分执行粘贴(单个 PDF 粘贴 PDF 字节)。输入即过滤;搜索框下方是互斥的类型胶囊(→ 聚焦第一个类型并立刻按该类型筛选,继续 →/← 同步移动焦点与筛选,在第一个类型再 ← 回到搜索框并清除类型筛选)。当最近剪辑带有标签时,类型胶囊下方还有一行标签胶囊:在最后一个类型再 → 进入标签行,移动时依次单独应用所聚焦的标签(进入即清除类型筛选;在第一个标签再 ← 会清除标签筛选并恢复最后一个类型的筛选),点按标签可自由组合多选——命中任一所选标签的行即显示。↑↓ 移动列表,Return(或点按)粘贴选中项,Esc 关闭。每次打开都会重置筛选。点选单外、失焦、或再次按唤起键也会关闭。

• Return 经守卫写入器写入剪贴板(不产生新历史行、不唤起轻浮层),再向唤起时的前台应用模拟 ⌘V——前提是已为 Ginkgo 授予「辅助功能」。
• 未授予「辅助功能」时,Return 仍会写入剪贴板并显示一行提示;请自行按 ⌘V 粘贴。有界引导窗口可深链到「系统设置 › 隐私与安全性 › 辅助功能」(最多自动出现三次,或选「暂不」永久降级)。
• 安全输入会话(例如 Terminal 里 sudo 的密码提示)同样保持选单打开、给出提示,并跳过模拟粘贴。

菜单、历史记录与转换阅读器:

多数剪辑插件(时间戳、词典、JSON、翻译、Format、文字识别及文本/哈希转换)以第一方 .ginkgoplugin 形式随应用发布——启动时会同步到 ~/Library/Application Support/Ginkgo/Plugins/(若你已在设置中卸载则不会自动恢复)。Markdown、HTML 预览、智能体、二维码与图片仍内置于应用。官方目录插件:打开「设置 › 插件」页时目录拉取一次——空搜索下的「推荐」区列出至多 6 个未安装的官方插件(按下载量排序),搜索把已安装与未安装插件放在同一卡片样式下一起匹配;已安装插件在目录有新版本时出现「更新」。安装包先经 SHA-256 与代码签名校验,才会清掉隔离属性并进入插件文件夹;首次安装在无额外权限要求时会默认启用。可在插件详情页确认后卸载包式插件。第三方包仍走手动路线:拷入文件夹后点 Rescan。每个包在运行任何代码之前都会校验;拒绝原因显示在页面底部。

1. 01手动安装(第三方包):把 YourPlugin.ginkgoplugin 拷进 Plugins 文件夹(设置 › 插件 › 打开 Plugins 文件夹,或使用上述路径)。
2. 02若从网络下载,需自行去掉隔离属性:xattr -dr com.apple.quarantine YourPlugin.ginkgoplugin——手动拷入的包 Ginkgo 不会替你清除(市场安装的官方包在校验通过后自动清除)。
3. 03Rescan 后,对 manifest 声明的每项能力逐项授权,再打开开关。授权表示用户同意,不是沙箱——Ginkgo 无法限制第三方代码的实际行为。

• 全部数据存在本机(Application Support);除非你亲自发起,剪贴板内容不会离开这台设备。
• 许可请求:激活与静默重验直连 Dodo Payments,只传序列号、实例 id 与设备名,绝不含剪贴板内容;从未激活的安装在打开「设置 › 插件」页之前零许可网络调用(下方的应用内更新检查在 Sparkle 构建上仍可运行)。
• Apple 翻译语言包:首次使用翻译时由系统下载;Apple 只收集使用指标(bundle id 与语言对),不含翻译内容。词典与翻译其余部分都在设备上完成;云翻译 API 是有意不用的。
• 插件市场:打开「设置 › 插件」页时拉取一次官方目录(推荐区与搜索都读这份快照——启动时与输入搜索词时零请求)、在你点击安装或更新时下载安装包并上报匿名安装计数(只含插件 id 与版本,绝不含剪贴板内容);未激活的安装同样可以使用,网页目录(/plugins)仅作浏览、不提供下载。
• 用户主动发起的智能体运行:需许可、默认关闭的「智能体」插件,只把提示内容发往你自配的云模型服务商(用你自己的 API key)——智能体现在也能读图,图片剪辑的画面只在你主动发起的运行中发往该服务商,发送前最长边缩到 ≤1568px——外加你批准 web_fetch 时抓取的网页;在启用插件、配置服务商并发起运行之前,它不产生任何网络调用。API key 存放在登录钥匙串——绝不写入历史、转换或分享卡片。
• 应用内更新(Sparkle):正式构建会周期性拉取公开 appcast,在你点「更新」时下载已签名的 zip——绝不含剪贴板内容;未激活亦可。Homebrew 安装继续用 brew upgrade,不走 Sparkle 替换;无更新签名的 ad-hoc 构建不发起更新请求。
• macOS 15 及更高版本的后台粘贴板读取,由「来自其他 App 的粘贴」权限管理——见「首次启动」一节。
• 你启用的外部插件是第三方代码:在你授权声明的能力之后,剪贴板文本会进入其进程;超出声明的网络或文件行为不在 Ginkgo 控制范围内——见「外部插件」。