StashBase：把本地文件夹变成 Agent 可搜索的上下文库
AI coding agent 现在最容易踩到的限制之一，不是它不会调用工具，而是它找不到真正有用的本地资料。代码仓库可以挂进工作区，但项目说明、合同、论文、会议录音、截图、设计文档、PDF 手册往往散在文件夹里。你可以把文件一个个拖进聊天窗口，但这不是可持续的上下文管理，更不像一个团队或长期项目能依赖的工作流。
今天看的是 liliu-z/stashbase。它的定位很直接：把本地文件变成 Agent 可搜索的上下文。你打开一个本地文件夹，StashBase 会把支持的内容准备成文本和索引，并通过本地 MCP server 交给 Claude、Codex 或其他 MCP client 使用。它不是新的聊天模型，而是给本地资料加一层可重建、可搜索、可接入 Agent 的索引。
按 GitHub repository API、repository page、README、Latest Release、tags、package.json 和默认分支 commit 在 2026-08-01 能核验的公开信息，liliu-z/stashbase 当前有 172 stars、11 forks。仓库主语言是 TypeScript，许可证是 Apache-2.0。仓库创建于 2026-05-19 05:21:06 UTC，最近公开 push 是 2026-08-01 09:46:42 UTC。默认分支 main 的当前 HEAD 是 4c3527d，提交时间 2026-08-01 09:10:54 UTC。最新 GitHub Release 是 v1.3.2，发布时间 2026-07-22 11:57:50 UTC；根 package.json 的 package name 是 stashbase，version 为 1.3.2，要求 Node.js >= 22.12.0，package manager 为 pnpm 11.5.1。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | liliu-z/stashbase |
| 定位 | 本地文件资料库、搜索索引和 MCP 上下文层 |
| Stars | 172 |
| Forks | 11 |
| 主要语言 | TypeScript |
| 许可证 | Apache-2.0 |
| GitHub 创建时间 | 2026-05-19 05:21:06 UTC |
| 最新 push | 2026-08-01 09:46:42 UTC |
| 当前默认分支提交 | 4c3527d，2026-08-01 09:10:54 UTC |
| 最新 GitHub Release | v1.3.2，2026-07-22 11:57:50 UTC |
| package | stashbase 1.3.2，Node.js >= 22.12.0，pnpm 11.5.1 |
| 关键词 | local files、semantic search、MCP、PDF、DOCX、OCR、transcription、Electron |
它处理的是文件资料，而不只是代码
StashBase 的 README 把输入范围写得很清楚：Markdown、HTML、PDF、DOCX、图片、音频和视频都可以进入准备流程。不同格式会走不同路径。Markdown 可以直接索引源文本；HTML 会抽取干净文本；PDF 会生成派生 Markdown；DOCX 会生成派生 HTML；图片走 OCR；音视频会在本机转成带时间戳的 transcript。
这个角度和常见代码搜索工具不一样。代码仓库本身已经有 rg、LSP、符号索引和很多 Agent 工具可以处理，真正难管理的是旁边那些“不是代码但影响判断”的资料。比如你让 Agent 改一个合规相关功能，它可能需要读合同条款和客户邮件；做文档生成时，它可能需要参考旧 PDF 手册；排查产品行为时，它可能需要会议录音的 transcript 和截图说明。
StashBase 的价值在于把这些本地资料放进同一个搜索面里。README 里的核心链路是：local files -> prepared text -> search index -> MCP -> Agents。原始文件仍然是 source of truth，索引是可以从文件夹重新生成的派生层。这一点很实用，因为它没有要求你把资料搬到一个新的云端知识库里。
MCP 是它和 Agent 之间的接口
StashBase 运行时会启动一个本地 MCP server。README 里列出的核心工具包括 library_info、search_library 和 reindex。外部 Agent 可以先知道当前打开了哪些 folder、embedder 状态如何，再对资料库搜索，必要时触发重建索引。
它还暴露了一组有边界的文件 helper，例如 list_directory、read_file、write_file、edit_file、move_file 和 delete_file。README 特意说明这些 helper 是给运行在 sandbox 里的 Agent client 使用的，不是通用文件系统 API。这个边界值得注意：StashBase 不是要替代操作系统文件权限，而是在用户显式打开的 folder 里给 Agent 一个可控入口。
对 Claude、Codex 这类 CLI 或桌面 client 来说，这种设计比“复制一段文档进 prompt”更稳定。资料库可以增量更新，Agent 可以搜索后再读相关文件，不必每次靠人手动挑上下文。它也适合长期项目：今天加进来的 PDF，过几周仍然能被同一个本地 library 找到。
本地优先，但语义搜索仍然需要选择
README 对本地边界讲得比较清楚。你的 folder 仍然在原处，移除 library 只会清掉 StashBase 自己的状态，不会删除磁盘上的文件。音视频转写用本地 speech model，可以在设置里下载 Tiny、Base 或 Small 模型，转写过程在本机跑。
不过语义搜索不是完全零配置。README 写到，如果没有 embedding API key，应用内 keyword search 仍然可用；如果要 semantic search，可以添加 OpenAI 或 OpenRouter API key。也就是说，StashBase 把文件准备、索引、MCP 和本地转写放在本机，但语义 embedding 是否走外部 provider，需要用户自己决定。
这正是它适合先小范围试用的原因。你可以先用不敏感资料和 keyword search 验证工作流，再决定哪些 folder 可以用语义搜索，哪些资料应该只留在本地处理。对团队来说，真正要评估的不是“能不能搜”，而是资料范围、API key、派生文本、vector store 和 Agent 写权限之间的边界。
桌面应用和内置 Agent panel 是务实选择
StashBase 的主要平台是 macOS 12+ Apple Silicon 和 Windows 10+ x64，也提供社区支持的 Linux x86_64 Debian 12+ / Ubuntu 22.04+ build。安装路径包括 macOS Homebrew cask、Windows installer 和 Linux .deb。从源码构建则是常见的 TypeScript / Electron 路线：
git clone https://github.com/liliu-z/stashbase
cd stashbase
pnpm install
pnpm setup:python
pnpm build:web
pnpm electron它还带一个内置 Agent panel，可以在当前 folder 旁边跑 Claude Code、Codex 这类本地 Agent CLI。这个 panel 不是另一套知识库，而是同一个 MCP server 的客户端。README 说它会保留 Agent CLI 自己的 session history，并允许在应用里 review tool calls 和文件编辑。
这个设计很适合处理文档驱动的任务。比如你打开一个包含 PRD、用户访谈、PDF spec 和旧截图的 folder，让 Agent 先搜资料，再改同一 folder 里的 Markdown 或代码。你不需要把“资料在哪”和“工作目录在哪”拆成两个工具。
需要注意的边界
第一，项目仍是 early alpha。172 stars、11 forks、2026 年 5 月创建，更新很活跃，但这不是已经被大量组织验证过的知识库基础设施。个人项目、研究资料夹、小团队内部试验会更合适。
第二，索引质量取决于准备流程。OCR、PDF 抽取、DOCX 转 HTML、音视频转写都会遇到格式、语言、扫描质量和模型能力的限制。搜索结果能帮 Agent 找线索，但不能保证每份资料都被完美理解。
第三，MCP 文件 helper 需要谨慎授权。它们只针对打开的 folder，但一旦接给 Agent，就意味着 Agent 可能读取或修改这些文件。把敏感资料、写权限和自动执行工作流放在一起之前，最好先分 folder、分权限、分 client 测。
第四，语义搜索可能涉及外部 embedding provider。StashBase 的本地优先模型降低了集中上传资料的压力，但如果你配置了 OpenAI 或 OpenRouter key，哪些文本会进入 embedding 请求仍然需要按自己的风险边界确认。
总结
liliu-z/stashbase 有意思的地方，是它没有把 Agent 上下文问题简化成“更长的 prompt”。它把本地文件夹、格式准备、搜索索引和 MCP 接口串起来，让 Agent 可以主动找资料，而不是等人手动喂文件。
如果你的工作主要围绕代码仓库，普通代码搜索可能已经够用。但如果项目判断经常依赖 PDF、DOCX、截图、录音、研究笔记和散落文档，StashBase 值得放进观察列表。它还很早期，但切中的摩擦非常真实：很多有价值的上下文，其实一直躺在本地文件夹里。