内容
<p align="center">
<img src="apps/bamboo-clipboard-ui/ui/assets/pandaclip-logo.png" alt="PandaClip" width="320">
</p>
# PandaClip
一款本地优先的MCP服务器 + 桌面活动镜头。无需守护进程，无需云端，处处皆有SQLite。
`@vektorgeist/pandaclip` 是一个单一的服务器，拥有四个工具家族：
| 家族 | 工具 | 功能 |
|---|---|---|
| 📋 剪贴板 | `clip_*`, `snippet_*`, `channel_*` | 剪贴板历史（TTL类，标签/包含筛选器），永久命名片段，频道标签通道，秘密筛选 |
| ⚡ 缓存 | `cache_*` | 命名空间缓存，带有TTL，规范哈希键，失效，统计 |
| 🎋 竹子 | `workspace_*`, `entry_*`, `stalk_*`, `bamboo_find`, `organize_scan` | 上下文文件组织器叠加层：标签，注释和文件元数据 — 不移动或复制任何内容 |
| 🌱 花园 | `garden_*` | 知识图谱：种植/生长/修剪节点，类型化边，BFS遍历，每个节点历史 |
所有数据都存储在 `~/.panda/<area>/` （可通过 `PANDA_HOME` 重写）。一次注册，一个进程，40个工具。
## 工作原理
PandaClip 是一个单一的stdio MCP服务器（TypeScript）。您的代理的MCP客户端会启动它，它会公开这40个工具，每个工具都是对一个普通SQLite数据库的小型确定性操作 — 每个家族一个存储在 `~/.panda/<area>/` 下，WAL模式，无后台守护进程，无网络，无云。除非调用工具，否则不会发生任何事情：
- **剪贴板** — `clip_push` 将历史记录追加到具有TTL类，标签/包含筛选器和秘密筛选（明显的键和令牌在存储之前被拒绝）。片段是永久命名的剪辑；通道是同一个本地存储中的命名标签通道，因此代理可以指向您确切的剪辑。
- **缓存** — 一个具有规范哈希键的命名空间TTL缓存，用于代理不应重复的昂贵查找。
- **竹子** — 在您已经拥有的文件上添加标签，注释和元数据；不会移动或复制任何内容。
- **花园** — 一个类型化的知识图谱：种植/生长/修剪节点，类型化边，BFS遍历，每个节点历史。
桌面镜头从另一侧读取这些相同的存储。Electron应用程序会启动一个只读的监视器子进程，监视您的系统Node（>= 22.5 — 它需要 `node:sqlite` 的WAL感知读取），它会轮询存储和您配置的任何源，差异化最后的状态，并将更改事件流式传输为NDJSON到实时馈送中。服务器保持为唯一的写入者；镜头只能查看。
## 桌面镜头
`apps/bamboo-clipboard-ui/` 是一个可安装的Electron应用程序：一个实时的，只读的馈送，显示您的代理正在执行的操作。开箱即用，它会监视PandaClip自己的存储 — 剪贴板（剪辑，片段，通道），缓存写入和花园种植。三个空白插槽您可以指向 `~/.panda/config.json` 中的您自己的存储：
```json
{
"lens": {
"notes": { "dir": "~/my-notes", "skipDirs": ["drafts"] },
"git": { "dir": "~/code" },
"kg": { "db": "~/.local/share/kg/facts.sqlite3",
"vectors": "~/.local/share/kg/vectors.sqlite3",
"groupKeys": ["project"],
"typeLabels": { "journal_entry": "journal written" } }
}
}
```
`notes` 馈送markdown编辑，`git` 馈送来自目录下的新提交，`kg` 了解知识图谱的磁盘布局（一个三元组数据库 + 一个向量存储）。可选的 `kg` 键塑造了向量存储记录在馈送中的外观：`groupKeys`/`tagKeys` 选择元数据字段作为标题和标签，`typeLabels`/`idPrefixLabels` 将记录的类型字段或id前缀映射到友好标签 — 未设置，记录显示为通用。未配置的插槽简单地关闭。监视器严格只读。需要系统Node.js >= 22.5。运行 `npm start --workspace pandaclip`。
## 灵感来自jacobian-lens
镜头借鉴了Anthropic的 **jacobian-lens** 的形状 — 伴侣代码到论文 *"Verbalizable Representations Form a Global Workspace in LMs"* — 读取变换器的内部激活以显示模型倾向于在说出之前说什么。PandaClip将相同的操作应用到栈的一级上方：而不是权重和梯度，它为您提供了一个实时，只读的窗口，显示您的代理在当前正在执行的操作 — 每个剪辑，缓存写入，种植的事实，笔记编辑和提交都在馈送中实时显示。模型镜头读取模型的运行状态；PandaClip读取您的代理的运行状态。
## 与magpie-search配合使用
PandaClip故意不附带**搜索引擎**。将其与 [magpie-search](https://github.com/xfloukiex-lab/magpie-search) （[PyPI](https://pypi.org/project/magpie-search/)，`npx -y magpie-search-mcp`）配对使用，两个互相补充：magpie找到事物（转录，历史，深入查找），PandaClip保存事物（剪贴板，缓存，文件叠加层，知识图谱）。
实际上，配对如下：magpie-search **找到** — 它扩展到转录，本地文件和网络，并带回答案。PandaClip **保存** — `cache_put` 昂贵的查找以避免重复，`clip_push` 有关的摘录，`garden_plant` 带有类型化边的持久事实。下次会话时，该事实距离一个 `garden_search` 很近，而不是进行新的搜索，并且镜头显示整个循环实时发生。
将它们作为单独的MCP服务器一起运行 — 没有代码耦合，彼此也不需要。没有magpie，仍然可以正常工作；您的代理只需手动进行查找。
## 开发
```sh
npm install
npm run build
npm test
```
## 使用（Claude Code / 桌面）
参见 `examples/mcp-config.json`。将入口指向 `servers/pandaclip/dist/index.js` （或 `npx @vektorgeist/pandaclip` 一旦发布）。
## 设计规则
- 一个服务器；四个家族共享的只有 `@vektorgeist/panda-core` （SQLite帮助程序）和 `~/.panda/` 主目录。
- 工具名称是字面意义上的（`cache_get`，而不是 `feed_panda`）；panda主题保留在文档中。
- 缓存是一种优化，而不是事实的来源。
---
## 关于
**PandaClip 由 [VektorGeist LLC](https://vektorgeist.com) 构建。**
我们为运行自己的AI的人员构建本地优先的工具。PandaClip是工作状态工具箱；我们的代理平台位于 **[vektorgeist.com](https://vektorgeist.com)**。
- 网站： **[vektorgeist.com](https://vektorgeist.com)**
- 联系方式： **floukie@vektorgeist.com**
- 问题和贡献：请在此仓库中打开问题或提交PR。
## 许可证
在 **Apache License 2.0** 下许可 — 参见 [LICENSE](LICENSE)。
版权所有 © 2026 VektorGeist LLC。
*"PandaClip" 和 panda 标志是 VektorGeist LLC 的商标。代码在 Apache-2.0 下开放；品牌和名称保留。*
