byte-stash

纯本地、单人、零部署、零云依赖的知识库——把你积累的代码项目、代码片段、Markdown 笔记、代码模板沉淀为一个可检索的库，通过桌面端、CLI、VSCode 插件管理，并内嵌 MCP 服务器让 AI 直接检索你的内容。

中文 | English

目录

• 它解决什么
• 功能特性
• 快速开始
• 桌面端
• CLI 用法
• AI 集成（MCP）
• VSCode 插件
• 架构
• 数据位置
• 构建
• 技术栈
• 参与贡献
• 开源许可证

它解决什么

代码、片段、文档散落各处——本地仓库、聊天记录、笔记软件、浏览器收藏夹。byte-stash 把它们沉淀为一个本地可检索的库：标签、分类、收藏、全文搜索（中文友好），并让 AI 在写代码时能"查到"你已经验证过的内容。

核心特点：

• 纯本地 — 数据全在你的机器（SQLite + 文件目录），无云端、无账号、无订阅
• 零部署 — 打开即用，关掉即走，不需要服务器
• AI 原生 — 内嵌 MCP 服务器，Claude / Cursor 可直接检索你的库
• 多端管理 — 桌面端（GUI）/ CLI / VSCode 插件，共享同一套数据

功能特性

内容管理

• 项目 — 导入代码目录（自动遵循 .gitignore），保留文件树，可读取/编辑单文件
• 代码片段 — 单条代码记录，支持语言 / 标签 / 分类
• Markdown 笔记 — 所见即所得编辑（md-editor-v3），支持图片资产管理
• 代码模板 — 带 ${name} 变量的骨架，编辑器内 trigger 补全，展开生成代码
• 图表 — Mermaid 流程图 / 时序图

智能检索

• 全文搜索 — SQLite FTS5 + 中文 LIKE 模糊兜底，中文关键词可命中
• 分类与标签 — 自由标签 + 层级分类，多维度筛选
• 跨类型统一搜索 — 项目 / 片段 / 笔记 / 图表 / 模板合并检索

个性化

• 主题系统 — 5 套预设配色（蓝 / 翡翠 / 紫罗兰 / 琥珀 / 玫瑰）+ 可视化自定义 + 区域语义层
• 壁纸系统 — 面板级毛玻璃，各面板独立半透明
• 动画系统 — GSAP 驱动的统一交互动画

数据安全

• 软删除 + 回收站 — 误删可恢复（项目 / 片段 / 笔记 / 图表 / 模板 / 资产各有回收站）
• 备份 / 恢复 — 一键导出 zip（DB + 全部内容文件）

集成

• MCP 服务器 — 8 个统一工具，stdio / HTTP 双传输
• REST API — 供第三方应用 HTTP 对接，含 OpenAPI 文档
• VSCode 插件 — 编辑器内插入 / 捕获片段与模板
• 分享外链 — 生成只读分享 token，配合 REST 服务对外访问

快速开始

方式一：桌面端（普通用户）

从 GitHub Releases 获取 Windows 安装包（.msi / .exe）。当前发布周期内若暂无预编译包，可按下方构建章节自行打包。

桌面端目前打包目标为 Windows（msi / nsis）。macOS / Linux 用户请用 CLI 或从源码构建。

方式二：CLI（开发者 / 自动化）

# 需要 Rust 工具链
cargo build --workspace          # 构建 bs（在 target/debug/bs）
# 或
cargo install --path apps/cli    # 安装到 ~/.cargo/bin

bs stats                          # 查看知识库概览

方式三：VSCode 插件

在 VSCode 扩展市场搜索 “Byte-Stash”；或在 apps/vscode 下 npm install && npm run build && vsce package 后安装生成的 .vsix。

桌面端

Tauri v2 + Vue 3 构建的桌面应用，提供：

• 项目 / 片段 / 笔记 / 模板 / 图表的完整 GUI 管理
• 文件树浏览与在线代码编辑（Monaco）
• Markdown 笔记编辑（md-editor-v3）
• 主题与壁纸个性化
• 资产（图片）管理与独立回收站
• 设置页：数据目录、排除规则、REST / MCP 服务、API Key、动画

CLI 用法

bs 是命令行工具，所有命令支持 --json 输出（脚本 / AI 友好）。

# 导入项目（自动遵循源目录 .gitignore）
bs add ./my-project --title "我的项目" --tag rust --lang rust

# 列出 / 查看 / 搜索
bs list
bs get <shortId> --tree                 # 文件树
bs get <shortId> --file src/main.rs      # 读单文件
bs search "mcp server"

# 片段 / 笔记 / 模板（均支持 add/list/get/search/remove/patch）
bs snippet add --title "工具函数" --lang rust --code 'fn id<T>(x: T) -> T { x }'
echo "# 会议纪要" | bs note add --title "晨会"
bs template add --title "Rust 函数" --body 'fn ${name}() { todo!() }'

# 分类 / 统计
bs category create 后端
bs stats

# 备份 / 恢复
bs backup --output ~/bk.zip
bs restore ~/bk.zip

修改内容用 patch（行号范围替换，省 token）：bs note patch <id> --start 1 --end 3 --new "新内容"。

完整命令参考见 skills/byte-stash/SKILL.md。

AI 集成（MCP）

内嵌 MCP 服务器，配置到 Claude Desktop / Cursor 即可让 AI 检索与修改你的库。8 个统一工具：

工具	说明
search	跨类型搜索（project / snippet / note / diagram / template / all）
list	列出内容（project / snippet / note / diagram / template / tag / category）
get	读取详情 / 文件 / 文件树（meta_only=true 只返回元数据省 token）
stats	统计概览
create	创建 snippet / note / file / template / diagram
patch	局部修改（行号范围替换）
delete	删除（移入回收站，可恢复）
expand_template	展开模板 ${name} 变量

// Claude Desktop / Cursor 的 MCP 配置
{
  "mcpServers": {
    "byte-stash": { "command": "bs", "args": ["mcp", "serve"] }
  }
}

HTTP 模式（多客户端 / 调试）：bs mcp serve --transport http --port 8217

VSCode 插件

在编辑器内直接操作知识库：

• 插入 片段 / 模板（trigger 智能补全，按当前文档语言过滤）
• 捕获 选中代码或整个文件为片段 / 模板
• 导入 文件夹为项目（自动遵循 .gitignore）
• 三种数据访问模式：auto（检测到 bs CLI 就用 CLI，否则走 HTTP）/ cli / http

架构

byte-stash/                   Cargo workspace
├── crates/core/              核心库：业务逻辑 + 数据层 + MCP 工具实现（CLI/Desktop 共享）
├── apps/cli/                 CLI（bs）：命令实现 + 输出格式化
├── apps/desktop/             Tauri v2 + Vue 3 桌面端
│   ├── src/                  Vue 前端
│   └── src-tauri/            Rust 后端（命令层 + 应用状态）
└── apps/vscode/              VSCode 插件

核心逻辑收敛到一个 Rust crate（byte-stash-core），CLI 与桌面端共享同一套业务逻辑与数据层，保证行为一致。

数据位置

~/.cicbyte/apps/byte-stash/         ← app 根目录（BYTE_STASH_HOME 可覆盖）
├── config/config.toml              ← data_dir / 偏好 / 备份设置 / API Key（固定）
└── data/                           ← 数据目录（可在设置页移到任意路径）
    ├── db/bytestash.db             ← SQLite（元数据 + FTS5 索引）
    ├── projects/{shortId}/         ← 项目文件
    ├── snippets/{前2}/{3-4}/{id}.ext← 片段（前缀分桶）
    ├── notes/{前2}/{3-4}/{id}.md   ← 笔记（前缀分桶）
    └── wallpapers/                 ← 壁纸

config/ 固定在 app 根；data/ 可移动到外置硬盘 / 网盘同步目录。前缀分桶（{前2}/{3-4}/）避免单目录万级文件平铺。

构建

# 前置：Rust (stable)、Node.js 18+、pnpm

# CLI + core + desktop 后端
cargo build --workspace
cargo test --workspace

# 桌面端开发模式（启动窗口）
cd apps/desktop && pnpm install && pnpm tauri dev

# 桌面端打包（产出 msi / nsis）
cd apps/desktop && pnpm tauri build

# VSCode 插件打包（产出 .vsix）
cd apps/vscode && npm install && npm run build && vsce package

技术栈

层	选型
语言	Rust
数据库	SQLite + FTS5（rusqlite bundled，零外部依赖）
MCP	官方 rmcp（stdio + StreamableHTTP）
桌面	Tauri v2
前端	Vue 3 + Ant Design Vue + Pinia
编辑器	Monaco（代码）/ md-editor-v3（笔记）/ Mermaid（图表）
动画	GSAP

参与贡献

欢迎提 Issue 与 PR。开发相关请见构建与架构章节。

开源许可证

MIT © cicbyte