liliu-z/stashbase · 上手攻略
- 仓库：liliu-z/stashbase
- 链接：https://github.com/liliu-z/stashbase
- 分类：AI 写作工具 · Local-First · Agent 协作
- 作者：Tom
- 更新：2026-10-05
是什么
StashBase 是一个本地优先的 AI 写作工作区，核心理念是「像 IDE 一样写作，但由 AI 驱动」。它允许你用自己的知识库（文件、笔记、过往写作）作为上下文，让 Claude 或 Codex 帮你起草、修改、审查文章，而不必把私有内容交给第三方。
关键差异化在于文档 Diff 视图：AI 对 Markdown 文档的修改不是行级别的代码 Diff，而是在原文 prose 内部展示——删除文字加红色删除线，新增文字加绿色高亮。审稿人在阅读时就能逐段接受或拒绝修改，段落结构和格式保持不变。
解决什么问题
- 写作时不离开自己的资料：文件本地存储，AI 只能在你打开的项目范围内读写，无需上传到云端。
- 保持个人写作风格：可以用自己过往的文稿和修改记录训练 AI 理解你的语气和表达习惯。
- 透明审稿：AI 每次修改都有视觉对比，不用去对照旧文件猜改了哪里。
- 语义搜索：按语义（而非关键词）搜索知识库，适合当你「记得内容但忘了怎么说」的时候。
快速安装
macOS（推荐 Homebrew）
brew install --cask liliu-z/stashbase/stashbase
安装后从 Applications 打开，或命令行运行 stashbase。
⚠️ 需要 macOS 12+；Apple Silicon（M 系列）和 Intel 分别有独立安装包，Homebrew 自动匹配。若手动下载，文件名含
arm64（M 系列）或x64（Intel），不得混用。
Windows
- 前往 Releases 页面 下载
StashBase-*-win-x64.exe - 运行安装程序，按提示完成安装
- 若 SmartScreen 拦截，请确认下载来源为官方 Releases 页面，再选择「Run anyway」
⚠️ 不建议为绕过 SmartScreen 而关闭杀毒软件；报告持续拦截而非禁用防护。
Linux（社区支持）
# Debian/Ubuntu（推荐 apt 安装，自动处理依赖）
sudo apt install ./StashBase-*-linux-amd64.deb
# 便携版（AppImage，无需安装）
chmod +x StashBase-*-linux-*.AppImage
./StashBase-*-linux-*.AppImage
要求：x86_64，Debian 12+ 或 Ubuntu 22.04+。
更新与卸载
- 更新（Homebrew）：
brew upgrade --cask stashbase；其他方式重新运行新版本安装包即可，项目和设置保留。 - 卸载：macOS 从 Applications 删除或
brew uninstall --cask stashbase；Windows 在设置→应用中找到卸载；Linuxsudo apt remove stashbase。卸载 App 不会删除你的项目文件。
核心用法
1. 打开或创建项目
首次启动显示 Welcome 界面，可选择：
- 打开已有文件夹（本地写作项目）
- 创建空项目
- 从 Gallery 复制（社区整理好的项目模板，如 Stanford CS183B 创业课+创始人手册）
- 导入公开 GitHub 仓库
2. 选择 Agent 并配置
支持三种 Agent：
| Agent | 说明 |
|---|---|
| Claude | 需配置你的 Anthropic 账户 |
| Codex | 需配置你的 OpenAI 账户 |
| Default Agent | 内置 fallback，使用 StashBase 免费额度，无需单独申请 API Key |
在侧边栏底部登录 StashBase 账号即可使用 Default Agent 的免费额度。
3. 开始写作对话
典型工作流示例：
「我想写一篇关于 Humanizer 的博客。先采访我，了解我的想法，然后再起草。」
在 Chat 中发起请求，Agent 会主动提问收集背景，然后生成大纲或初稿。
4. 文档 Diff（核心特色）
当你让 Agent 修改一个打开的 Markdown 文档时：
- 删除内容 → 红色删除线展示
- 新增内容 → 绿色高亮展示
- 改动出现在原文 prose 中，而非跳转到旧/新行对比
你可以： - 逐处接受或拒绝（鼠标点击绿/红标记） - Accept All / Reject All 批量操作 - 拒绝全部 → 文档恢复原样，无任何文件变更
5. 快捷键
| 操作 | 快捷键 |
|---|---|
| 打开文件 | Cmd/Ctrl + O |
| 命令面板 | Cmd/Ctrl + Shift + P 或 F1 |
| 新窗口 | Cmd/Ctrl + Shift + N |
| 关闭当前文档标签 | Cmd/Ctrl + W |
| Chat 中插入文件路径 | @ 提及文件/文件夹 |
6. 语义搜索（需配置）
- 关键词搜索：开箱即用，无需账号
- 语义搜索（Search by Meaning）：需在
Settings → Advanced → Search by Meaning添加 OpenAI 或 OpenRouter API Key；该 Key 仅用于 embedding 计费，StashBase 不作他用
7. MCP 外部集成
StashBase 可作为 MCP Server，供其他 AI 客户端（如 Cursor、Claude Desktop）连接读取/搜索/编辑当前项目文件。
配置路径：Settings → Advanced → External apps (MCP)，复制连接配置到目标客户端。
典型适用场景
- 技术博主：本地有大量笔记和文档，用语义搜索找到相关内容，AI 辅助起草，透明审稿
- 独立写作者：不希望把未完成的草稿上传到第三方云服务
- 内容团队：用 Gallery 模板标准化工作流，多人共用同一套 prompt 框架
- 学术写作者：需要引用大量 PDF 文献（本地 OCR 提取文字）并保持文风一致
坑与注意
- Intel Mac 旧系统功能受限：macOS 12~14 的 Intel Mac 可打开项目和编辑文件，但本地搜索和 PDF/图片文字提取不可用（需要 macOS 15+）。Agent 运行时也可能因模型版本要求而受限。
- 语义搜索需额外 API Key：Default Agent 免费额度不含语义搜索，如需必须自备 OpenAI/OpenRouter Key。
- Agent 模型版本：若选择的模型版本过旧，Chat 会提示
Update Claude，按提示更新 Agent 运行时。 - 项目文件 vs StashBase 数据：删除项目仅从 StashBase 注销，不会删除磁盘上的源文件；但
移除文件夹会清除 StashBase 生成的索引和派生数据。 - Linux 为社区支持：非官方维护，系统兼容性坑可能比 macOS/Windows 更多。
- 文件格式支持有限：部分格式只读、不可编辑，或不支持被 Agent 引用，具体见 Format Capability Matrix（设计文档中）。
与同类对比
| 工具 | 本地优先 | 文档 Diff | Agent 选型 | MCP 支持 | 适用场景 |
|---|---|---|---|---|---|
| StashBase | ✅ 本地文件夹 | ✅ prose 级 | Claude/Codex/内置 | ✅ | 写作+知识库 |
| Notion AI | ❌ 云端 | ❌ 无 | 仅内置 | ❌ | 协作笔记 |
| Obsidian + AI 插件 | ✅ 本地 | 依赖插件 | 多种 | 部分 | 双链笔记+AI |
| CherryStudio | ✅ 本地 | ❌ 无 | 多种 | ✅ | LLM 聚合 |
| Cursor | ✅ 本地 | 代码级 | Claude/GPT | ✅ | 代码+文档 |
StashBase 的核心差异是写作场景的文档 Diff 和本地知识库优先——不同于通用 AI 聊天工具，它专为「人机协作写作+审稿」流程设计。
一句话推荐结论
本地写作优先，注重文稿审稿透明度的个人写作者或小型内容团队，StashBase 是目前上手最顺的工具之一。 特别适合已有大量本地笔记、希望 AI 辅助起草但又不放弃内容控制权的用户。