KnowFlick

macOS 个人学习工作台 — 阅读、复习与知识管理

KnowFlick 是用 SwiftUI 编写的 macOS 个人学习工作台（最低支持 macOS 14）。从今日目标开始阅读，完成后进入复习安排；在知识库搜索、分类、编辑和导出自己的卡片。沉浸刷卡、AI 追问与知识星图仍可从工作台进入。内置知识可离线使用，也可配置兼容的 AI 服务生成新卡。

工作台的具体操作、复习规则与数据口径见学习工作台说明。

Android 端是同仓库内的独立原生应用（Kotlin + Jetpack Compose），构建、安装与发版见 Android 端说明。

当前版本

macOS v0.2.0：学习工作台与统计布局优化、侧栏折叠及悬停提示、搜索状态与保存反馈修复。发布说明
Android v0.10.3：筛选与主题优化、跨日和时区刷新、统计边界与语音控制器持有修复。发布说明
本地 MCP / CLI 使用说明：检索、地图、学习路径与人工确认暂存；自动刷新卡库并保护并发写入。

功能

今日学习：可调整每日目标、进度、下一篇阅读与主题掌握情况。
复习计划：按阅读时间和回忆反馈安排到期队列，显示未来复习日期。
知识管理：全文搜索、主题和状态筛选、保留学习记录的内容编辑、导出当前结果。
可折叠导航：今日学习、复习计划、知识库在同一窗口切换，窄窗口自动收起导航文字。
双重画报外观模式（深色 / 浅色 / 跟随系统）：深度适配 macOS 原生外观，提供暗色人文画报与浅色典雅画报两种完整排版风格。窗口画布、毛玻璃质感、42 类柔和光晕、弹窗与卡片阴影全量动态演算；顶栏提供快捷切换胶囊按钮，设置页可随时设定默认偏好
暗色人文画报风（Dark Editorial）：以原生宋体（Songti SC Black）为主标题字模，辅以高透气衬线正文排版，多阶非线性动态遮罩（DynamicScrim），带来沉浸式出版物级阅读质感
千卡千面智能背景与严格防重算法（Strict Min-Distance Deduplication）：精选 42 套高品质暗黑杂志风摄影底图（覆盖科技、前沿物理、生命科学、地球生态、商业金融与人文哲学细分领域），采用严格同图距离排布算法（Min-Distance Greedy Layout），保证连续刷卡时相同底图至少相隔 5 张以上（可见栈 3 张卡片 100% 底图各异），划卡平滑出队不打散既有队列，带来张张不同、各美其美的沉浸式视觉享受；主窗体环境光晕随顶卡与划卡飞出动画实时流转
触觉与 3D 动力学：macOS 触控板震动实体反馈（达阈值震动、松手磁吸回弹、刷卡确认）；手势 1:1 跟手与 3D 俯仰透视；底层卡片平滑上浮放大，极速丝滑无闪烁（Flying Card Overlay）
原生应用图标：黑曜石磨砂底盘与琥珀金「K」卡片交叠，完美契合 macOS Sonoma / Sequoia 超椭圆原生规范
随机刷卡：从本地卡片库随机抽取，左右划快速浏览
详情 + 链接：按 ⏎ 展开水墨晕染大图与详情、查看卡片化来源链接；详情页内可连续刷卡（点操作自动切下一张，←/→ 直接切换）
历史记录：自动保存浏览历史，图文画报流卡片呈现，随时回看（支持按感兴趣/不喜欢筛选）
撤销：⌘Z 撤销上一张卡片
分类自定义：设置页可增删改分类（名称 + 内容方向描述，支持分类专属色微标预览），内置「冷知识」分类收纳预置知识库；AI 生成按每个分类的内容方向产出对应领域卡片
主流 AI 服务商一键预设：内置 DeepSeek、硅基流动 (SiliconFlow)、Kimi (月之暗面)、智谱 GLM、OpenAI、本地私有 Ollama，自动补全 Base URL 与热门模型，只需填入 Key 即可使用（Ollama 免填 Key），同时支持「自定义」模式连接任意兼容端点
AI 智能生成：卡片不足或想开拓新领域时自动补充新卡；流式生成、够数即停，自动做分类规范化与近重复去重
知识库增量合并与重置：应用更新时自动同步新增的种子知识卡片，老用户无缝获取扩充内容；设置页实时显示卡库探索进度，支持一键重置卡堆重新体验
来源配置：设置页可分别开关「预置精选库」与「AI 生成内容」两种信息来源，并配置 AI 引用站点偏好（生成内容与检索链接都优先这些站点）
AI 内容标记：AI 生成的卡片在正面显示橙色徽章、详情页显示核实提示条，可一键关闭
偏好过滤：设置里多选偏好分类，刷卡队列优先偏好分类，刷完自动回退其他分类
学习统计：杂志专栏风呈现——已刷/感兴趣率/连续天数 + 分类双轨条形图 + 近 7 天渐变趋势柱状图
健壮模态路由：采用单一状态入口模态调度（ActiveSheet），彻底根治 macOS SwiftUI 多弹窗覆盖失效

键盘快捷键

系统菜单命令（任何界面可用；需要当前卡片的命令在卡堆为空时不可用）

快捷键	功能
`⌘F`	全局智能搜索与全文检索（支持拼音）
`⌘J`	向卡片追问（AI 伴学导师深入探讨）
`⌘P`	语音朗读 / 暂停（当前卡片）
`⌥⌘P`	打开听书控制台
`⇧⌘P`	开启 / 退出磨耳朵连续播报
`⌘K`	开启沉浸式知识测验
`⌘G`	探索全景知识星图与引力链
`⌘B`	打开知识收藏阁（沉淀笔记）
`⌘S`	生成并导出分享海报
`⌘N`	AI 生成 3 张新知识
`⌘?`	快捷键帮助面板
`⌘,`	打开偏好设置

沉浸刷卡界面

快捷键	功能
`←` / `→`	不喜欢 / 感兴趣（划走）
`⏎`	展开卡片详情与来源链接
`⌘Z`	撤销上一张卡片
`Esc`	关闭当前弹出的面板

详情页内

快捷键	功能
`⌘J`	向当前知识卡片深入探讨追问
`⌘P`	朗读 / 暂停全文语音
`⌘D`	收藏 / 取消收藏当前卡片
`⏎` 或 `Esc`	关闭详情
`←` / `→`	切换上一张历史卡片 / 下一张待刷卡片（刷卡区进入时）

测验面板内

快捷键	功能
`空格` / `⏎`	翻转卡片（查看背面答案与解析）
`⌘1` / `⌘2` / `⌘3`	自评：没想起来 / 犹豫想起 / 熟练掌握
`Esc`	退出当前测验

下载安装

从 Releases 页面下载最新 KnowFlick.app.zip，解压后拖入「应用程序」即可。

提示：未签名应用首次打开时，若被 Gatekeeper 拦截，请在「系统设置 → 隐私与安全性」中点击「仍要打开」；或执行 xattr -dr com.apple.quarantine /Applications/KnowFlick.app。

构建与运行

需要 Swift 6.0+ 工具链（生产代码保持 Swift 5 语言模式），部署最低版本仍为 macOS 14。

质量检查

./tools/test.sh

测试使用 Swift Testing，脚本兼容 Xcode 与 Command Line Tools 的框架路径。覆盖分类、统计、文件恢复、密钥编码隔离、刷卡状态、追问会话、API 传输与星图。网络测试通过本地 URLProtocol 替身执行，不请求真实 AI 服务。文档中的测试计数为 @Test 声明数（参数化用例运行时会展开为多条）。

# 图标构建链路（build_icon 自动调用 iconutil 打包 ICNS，随后逐像素校验）
swift tools/build_icon.swift apps/mac/Resources/AppIcon-artwork.png /tmp/icon-check
swift tools/verify_icon.swift /tmp/icon-check/AppIcon.icns /tmp/icon-check/AppIcon.png

# 课程导入脚本单元测试
python3 tools/test_import_lessons.py

语音配置

语音与聊天模型独立配置。默认使用 macOS 系统语音；设置页可以保存多套语音配置，每次启用一套，服务不可用时回退系统声音。

云端：填写 HTTPS Base URL、TTS 模型、音色和独立 API Key。兼容 /v1/audio/speech 的服务，例如硅基流动 CosyVoice/MOSS-TTSD。
本地：运行 Kokoro-FastAPI、CosyVoice 网关或其他兼容服务，填写 http://127.0.0.1:<端口>/v1，不需要 API Key。
模型文件由本地语音服务加载，不直接放进 KnowFlick.app；这样避免应用体积和内存被模型权重占满。API Key 只进 Keychain。

Android 端

Android 端的实施边界和语音协议见 apps/android/README.md，发布记录见 docs/。

直接运行（开发）

cd apps/mac
swift run

打包成 .app

cd apps/mac
./build_app.sh

脚本会执行 swift build -c release，并把可执行文件、Info.plist 和资源 bundle 手工组装为 dist/KnowFlick.app（无需 Xcode 工程）。需要完整 Xcode（SwiftUI 宏依赖其工具链插件）。

安装使用

双击 dist/KnowFlick.app 直接运行；或
把它拖到 /Applications 后从「启动台」/「应用程序」打开

AI 服务配置（开箱即用）

在应用内点击右上角「偏好设置」（齿轮图标），在「AI 驱动服务」卡片中选择服务商预设（已清晰划分为在线 API 服务与本地部署运行）：

1. 在线 API 服务

服务商预设	默认 Base URL	推荐模型	说明
DeepSeek (官方)	`https://api.deepseek.com`	`deepseek-chat`, `deepseek-reasoner`	官方高性价比模型，填入 API Key 即可
硅基流动 (SiliconFlow)	`https://api.siliconflow.cn/v1`	`deepseek-ai/DeepSeek-V3`, `Qwen/Qwen2.5-7B-Instruct`	汇聚主流满血大模型，填入 Key 即可
Kimi (月之暗面)	`https://api.moonshot.cn/v1`	`moonshot-v1-8k`, `moonshot-v1-32k`	长文本与中文常识理解，填入 Key 即可
智谱 GLM / BigModel	`https://open.bigmodel.cn/api/paas/v4`	`glm-4-flash`, `glm-4-plus`, `glm-5.2`	智谱 AI 开放平台，填入 Key 即可
阿里云百炼 (通义千问)	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-plus`, `qwen-max`, `qwen-turbo`	阿里云 DashScope 官方兼容端点
OpenCode Go	`https://opencode.ai/zen/go/v1`	`deepseek-v4-flash`, `glm-5.2`, `kimi-k3`	OpenCode 开发者中转，汇聚主流前沿模型
基元律动 (TokenRhythm)	`https://tokenrhythm.studio/v1`	`deepseek-v4-flash`, `glm-5.2`, `qwen3.8-max`	TokenRhythm 高并发聚合云端服务
小米 MiMo (Xiaomi)	`https://api.xiaomimimo.com/v1`	`mimo-v2.5`, `mimo-v2.5-pro`	小米大模型开放平台云端端点
LongCat (长猫科技)	`https://api.longcat.chat/openai`	`LongCat-2.0`	长猫科技大模型服务平台端点
蚂蚁百灵 (AntDigital)	`https://maas-api.antdigital.com/v1`	`ling-3.0-flash-fin`, `deepseek-v4-flash`	蚂蚁数科百灵大模型开放平台
NVIDIA NIM	`https://integrate.api.nvidia.com/v1`	`deepseek-ai/deepseek-v4-flash-0731`	英伟达开发者微服务推理平台
AMD 开发者平台	`https://developer.amd.com.cn/radeon/api/v1`	`DeepSeek-V4-Flash`, `Qwen3.8-Flash-Next`	AMD 开发者中心开源大模型端点
OpenAI (官方)	`https://api.openai.com/v1`	`gpt-4o-mini`, `gpt-4o`	官方 GPT 系列端点，填入 Key 即可

2. 本地部署运行

服务商预设	默认 Base URL	推荐模型	说明
Ollama (本地私有)	`http://localhost:11434/v1`	`qwen2.5:7b`, `deepseek-r1:7b`, `llama3.1:8b`	本地私有离线运行，无需 API Key
本地代理网关 (:31415)	`http://127.0.0.1:31415/v1`	`auto`, `fusion`, `gemini-3.6-flash`	本机聚合网关端口，无需 API Key

3. 自定义

服务商预设	默认 Base URL	推荐模型	说明
自定义服务商	自定义端点地址	自定义模型名	适配任意第三方 OpenAI 兼容端点或中转站

安全存储：API Key 绝不写入本地明文 JSON 文件，只存入 macOS 原生钥匙串（Keychain）中。
即选即用：切换预设时，Base URL 与推荐模型列表自动联动填入，免去查文档与手动输入的不便。
连通性测试：配置完成后可点击「测试连通性」一键校验端点与密钥是否工作正常。
自定义分类与偏好：设置面板中可增删改分类、多选偏好分类，并可设置 AI 优先引用的权威信源站点。

数据存储

内容	位置
卡片数据（含历史）	`~/Library/Application Support/KnowFlick/cards.json`
卡片备份（上一版轮转）	`~/Library/Application Support/KnowFlick/cards.backup.json`
AI 设置（base_url / model）	`~/Library/Application Support/KnowFlick/settings.json`
追问聊天会话	`~/Library/Application Support/KnowFlick/chat_sessions.json`
AI 密钥	macOS 钥匙串（Keychain）

内置种子知识库（214 张）随 app 打包在资源 bundle 中（Contents/Resources/KnowFlick_KnowFlickCore.bundle/seed_cards.json）：

冷知识（160 张）：通识（物理/生物/天文/数学/化学/历史/心理/脑科学/语言/科技/生活/地理）+ 技术向（AI/算法/数据结构/架构/Rust/Python/编程）+ 备考向（中级会计/学习方法），全部并入内置「冷知识」分类
AI（10 张）/ AI 开发（10 张）/ AI Agent（9 张）/ 中级会计（12 张）/ 投资理财（13 张）：领域初始卡，覆盖机器学习原理、提示工程与 RAG、Agent 架构、会计实务、理财基础

卡片背景图来自 Unsplash（Unsplash License，可免费商用），已做压暗与底部渐变处理以保证文字可读性；自定义分类自动复用内置视觉资源（按分类名稳定映射）。

项目结构

多端仓库：各端应用位于 apps/，跨端共享内容位于 shared/。分支模型、版本号与发版流程见多端协作规范。

KnowFlick/
├── apps/                    # 各端应用（独立构建，互不依赖）
│   ├── mac/                 # macOS 端
│   │   ├── Package.swift        # SwiftPM 清单（macOS 14+）
│   │   ├── build_app.sh         # 打包脚本 → dist/KnowFlick.app
│   │   ├── Resources/           # 原生应用图标（AppIcon.icns / AppIcon.png）
│   │   ├── Sources/
│   │   │   ├── KnowFlick/           # 应用层
│   │   │   │   ├── KnowFlickApp.swift   # 应用生命周期入口
│   │   │   │   └── Views/               # 刷卡、详情、历史、设置、设计系统 Token、触觉辅助
│   │   │   └── KnowFlickCore/       # 核心业务逻辑（独立跨平台/可测）
│   │   │       ├── Models/              # 卡片 / 分类 / AI 设置模型
│   │   │       ├── Services/            # AI 服务、钥匙串存取
│   │   │       ├── Stores/              # AppStore 应用状态、卡片持久化
│   │   │       ├── Stats/               # 纯函数统计与趋势计算
│   │   │       └── Resources/           # 由 tools/sync_shared_assets.sh 从 shared/assets 同步（不入 Git）
│   │   └── Tests/               # Swift Testing 用例
│   └── android/             # Android 端（Gradle + Compose）
├── shared/assets/           # 跨端共享资产（唯一事实来源）
│   ├── seed_cards.json      # 种子卡数据
│   └── bg/*.webp            # 分类底图
├── tools/                   # 跨端脚本：test.sh / build_android.sh / sync_shared_assets.sh / lint_shell_vars.sh / test_import_lessons.py / import_lessons.py / build_icon / verify_icon
├── docs/                    # 多端协作规范、各端发布记录与评审报告
├── assets/                  # README 截图等展示资源
├── CHANGELOG.md             # 完整版本更新日志
├── CONTEXT.md               # 领域词汇表（架构评审与实现的统一语言）
└── dist/                    # 构建产物（不入 Git）

更新日志

详见 CHANGELOG.md 查看完整的版本迭代与演进记录。

技术说明

纯 SwiftPM 工程，无 Xcode 工程文件；swift build -c release 即可编译
双 target 结构：KnowFlickCore（模型/服务/存储/统计，可测试）+ KnowFlick（App 入口与视图）+ KnowFlickCoreTests
共享资源（seed_cards.json + 分类底图）经 tools/sync_shared_assets.sh 从 shared/assets 同步进资源目录，两端共用同一份文件；背景图由 CoreResources.bundle 定位、经 ImageIO 降采样解码后缓存
目标平台：macOS 14.0+（Apple Silicon / Intel 均可）

Navigation Menu

Repository navigation

About

Repository files navigation

KnowFlick

当前版本

功能

键盘快捷键

下载安装

构建与运行

质量检查

语音配置

Android 端

直接运行（开发）

打包成 .app

安装使用

AI 服务配置（开箱即用）

1. 在线 API 服务

2. 本地部署运行

3. 自定义

数据存储

项目结构

更新日志

技术说明

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.qoder/skills/knowflick-kb		.qoder/skills/knowflick-kb
apps		apps
assets		assets
docs		docs
shared/assets		shared/assets
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

KnowFlick

当前版本

功能

键盘快捷键

下载安装

构建与运行

质量检查

语音配置

Android 端

直接运行（开发）

打包成 .app

安装使用

AI 服务配置（开箱即用）

1. 在线 API 服务

2. 本地部署运行

3. 自定义

数据存储

项目结构

更新日志

技术说明

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages