内容
# 虫洞 🌀
**协同式人工智能工作流管理器**
保持您的AI编码代理同步。虫洞为Claude Code、GitHub Copilot和Cursor提供了一个共享内存层——当您在任务中切换工具时，不会丢失任何内容。
**支持：**
- 🔀 **同一工具中的多个子代理** （例如，并行Claude任务）
- 🔄 **不同的AI工具** （Claude ↔ Copilot ↔ Cursor）
⚠️ *免责声明*：虫洞是一个早期阶段的项目。API和行为可能会改变，并且可能存在一些粗糙的边缘。它是公开构建的，并根据实际开发者的反馈快速演变。
## 功能
- **通用日志** - 适用于任何操作类型的单个`log`工具
- **事件标签** - 使用标签对事件进行分类，以便更好地组织
- **会话管理** - 命名工作会话，隔离上下文
- **令牌优化** - 紧凑的输出，增量查询，相关性过滤
- **冲突检测** - 知道代理何时触及同一文件
- **过时事件拒绝** - 自动过滤不再存在于当前项目状态中的文件编辑
- **Web UI可视化** - 使用`npx wormhole ui`查看会话，时间线事件和洞察
- **知识捕获和搜索** - 保存决策/陷阱并通过意图感知搜索展现
## 快速入门
使用npx（无需安装）立即试用：
```bash
npx wormhole-mcp
```
### 最小工作流（令牌优化）
1) `start_session`
2) 拉取上下文：`search_project_knowledge` + `get_recent`
3) 编辑前：`check_conflicts`
4) 工作期间：每`log`一个`file_edit` / `cmd_run` / `decision` / `test_result` / `todos`
5) 捕获学习成果：`save_knowledge` （决策/陷阱/约定/约束）
6) 完成：使用摘要`end_session`
```javascript
start_session({ project_path: ".", agent_id: "copilot", name: "fix-auth" })
search_project_knowledge({ project_path: ".", intent: "debugging", query: "auth" })
get_recent({ project_path: "." })
check_conflicts({ project_path: ".", files: ["src/auth.ts"] })
log({ action: "file_edit", agent_id: "copilot", project_path: ".", content: { file_path: "src/auth.ts", description: "Fix timeout" } })
save_knowledge({ project_path: ".", knowledge_type: "decision", title: "Use async DB client", content: "Prevents blocking" })
end_session({ session_id: "abc-123", summary: "Auth fixed; tests green" })
```
## Web UI
使用内置的Web界面可视化代理活动：
```bash
# 启动UI服务器（默认端口：3000）
npx wormhole ui
# 或指定自定义端口
npx wormhole ui 8080
```
然后在浏览器中打开http://localhost:3000，查看：
- 📊 **仪表盘** - 事件，会话和代理的统计信息
- ⏱️ **时间线** - 带有过滤的可视化事件流
- 📋 **会话** - 带有详细信息的全部工作会话
- 📈 **洞察** - 操作类型和标签分析
## 安装
### 选项1：npx（推荐）
**Claude Code** — 添加到 `~/.claude/claude_code_config.json`：
```json
{
"mcpServers": {
"wormhole": {
"command": "npx",
"args": ["-y", "wormhole-mcp"]
}
}
}
```
**GitHub Copilot** — 添加到项目中的 `.vscode/mcp.json`：
```json
{
"servers": {
"wormhole": {
"command": "npx",
"args": ["-y", "wormhole-mcp"]
}
}
}
```
### 选项2：全局安装
```bash
npm install -g wormhole-mcp
```
然后在配置文件中使用 `"command": "wormhole-mcp"`。
### 选项3：从源代码
```bash
git clone https://github.com/fatmali/wormhole.git
cd wormhole
npm install
npm run build
```
使用 `"command": "node"` 和 `"args": ["/path/to/wormhole/dist/server.js"]`.
### Claude Code 插件
对于Claude Code用户，有一个可选的插件，将MCP服务器配置与技能捆绑在一起：
```bash
# 安装插件
claude /install-plugin ./node_modules/wormhole-mcp/plugins/wormhole
```
或本地测试：
```bash
claude --plugin-dir ./node_modules/wormhole-mcp/plugins/wormhole
```
然后在Claude Code中使用 `/wormhole:wormhole` 调用。
**独立技能** （更简单）：
```bash
cp -r node_modules/wormhole-mcp/skills/wormhole .claude/skills/
```
## MCP 工具
### `log`
适用于任何操作类型的通用日志记录：
```javascript
// 记录命令
log({
action: "cmd_run",
agent_id: "claude-code",
project_path: "/path/to/project",
content: { command: "npm test", exit_code: 0 },
tags: ["testing", "ci"] // 可选：分类事件
})
// 记录文件编辑
log({
action: "file_edit",
agent_id: "claude-code",
project_path: "/path/to/project",
content: { file_path: "src/auth.ts", description: "Added JWT validation" },
tags: ["bugfix", "auth"]
})
// 记录决策
log({
action: "decision",
agent_id: "claude-code",
project_path: "/path/to/project",
content: { decision: "Use Zod for validation", rationale: "Already in deps" }
})
// 记录测试结果
log({
action: "test_result",
agent_id: "claude-code",
project_path: "/path/to/project",
content: { test_suite: "auth.test.ts", status: "passed" }
})
// 记录用户反馈
log({
action: "feedback",
agent_id: "claude-code",
project_path: "/path/to/project",
content: { agent_suggestion: "Use async/await", user_response: "rejected", user_note: "Legacy code" }
})
// 记录待办事项
log({
action: "todos",
agent_id: "claude-code",
project_path: "/path/to/project",
content: {
items: [
{ task: "Add input validation", status: "pending", priority: "high" },
{ task: "Write unit tests", status: "done" },
{ task: "Update README", status: "pending" }
],
context: "Auth refactor"
}
})
// 记录计划输出
log({
action: "plan_output",
agent_id: "claude-code",
project_path: "/path/to/project",
content: {
title: "API Authentication Design",
type: "architecture",
content: "Use JWT with refresh tokens, store in httpOnly cookies..."
}
})
```
**操作类型：**
- `cmd_run` - 命令执行
- `file_edit` - 文件修改
- `decision` - 设计决策与理由
- `test_result` - 测试结果
- `feedback` - 用户接受/拒绝
- `todos` - 任务项与状态跟踪
- `plan_output` - 计划产物（设计，架构，任务）
- 任何自定义类型
### `get_recent`
获取最近的活动（默认为紧凑格式）：
```javascript
get_recent({ project_path: "/path/to/project" })
```
**输出：**
```
[5m] claude: npm test → ✓
[8m] cursor: edit auth.ts "Add JWT"
[12m] copilot: decided "Use Zod for validation"
[15m] claude: auth.test.ts ✓
cursor: evt_123
```
**选项：**
- `limit` - 最大事件数（默认：5）
- `detail` - `minimal` | `normal` | `full`
- `since_cursor` - 仅获取新事件（增量查询）
- `related_to` - 按文件路径过滤
- `action_types` - 按操作类型过滤
- `tags` - 按标签过滤（例如，`["bugfix", "feature"]`）
### `get_tags`
获取项目中使用的所有唯一标签及其计数：
```javascript
get_tags({ project_path: "/path/to/project" })
// 输出：
// tags:
// bugfix (12)
// feature (8)
// testing (5)
// auth (3)
```
### `save_knowledge`
持久化决策，陷阱，约定或约束，以免代理重复错误。
```javascript
save_knowledge({
project_path: "/path/to/project",
knowledge_type: "pitfall",
title: "Avoid fs.readFileSync in handlers",
content: "Blocks event loop; causes timeouts",
confidence: 0.9
})
```
### `search_project_knowledge`
存储知识的意图感知查找。优先选择与您的意图匹配的类型。
```javascript
search_project_knowledge({
project_path: "/path/to/project",
intent: "debugging",
query: "auth"
})
// → [{ type: "pitfall", summary: "Avoid fs.readFileSync", confidence: 0.9 }]
```
**选项：**
- `with_counts` - 包括每个标签的事件计数（默认：true）
### `check_conflicts`
检测并发文件编辑：
```javascript
check_conflicts({ project_path: "/path/to/project" })
```
---
## 过时事件拒绝
虫洞自动跟踪和验证文件编辑，以确保代理永远不会根据过时的信息进行操作。当记录`file_edit`事件时，带有`diff`，虫洞：
1. **提取完整补丁** - 存储来自diff的所有添加/删除行
2. **验证查询** - 当通过`get_recent`或冲突检测检索事件时，检查每个文件编辑与当前文件状态
3. **模糊匹配** - 使用智能匹配处理代码移动位置，仅拒绝真正过时的编辑
4. **自动过滤** - 自动从结果中排除被拒绝的事件
### 工作原理
当您记录文件编辑：
```javascript
log({
action: "file_edit",
agent_id: "claude-code",
project_path: "/path/to/project",
content: {
file_path: "src/auth.ts",
description: "Added JWT validation",
diff: `--- a/src/auth.ts
+++ b/src/auth.ts
@@ -10,6 +10,7 @@
function validateToken(token: string) {
+ const decoded = jwt.verify(token, SECRET);
return decoded;
}`
}
})
```
虫洞在有效载荷中存储完整的diff。稍后，当另一个代理查询最近的事件时:
- **文件仍具有更改** → 包括事件
- **代码被删除或更改** → 事件被静默过滤掉
- **代码移动到不同位置** → 仍然被识别（模糊匹配）
**注意：** `diff`字段不会被截断（与其他内容字段不同），以确保即使对于大型更改，也能进行准确的验证。
这确保代理始终使用有关代码库中当前内容的准确上下文。
### 验证算法
补丁验证使用智能模糊匹配：
**对于添加的行（+）：**
- 检查添加的代码是否在当前文件的任何位置存在
- 使用规范化比较（修剪空格）
- 接受部分匹配（代码包含或被搜索）
**对于删除的行（-）：**
- 如果删除的行仍存在于文件中 → 补丁已过时
- 这会捕获恢复删除的情况
**处理的边缘情况：**
- **文件删除**：补丁验证失败
- **代码重构**：模糊匹配仍然找到逻辑，如果它存在
- **空格更改**：规范化比较忽略格式
- **行移动**：搜索整个文件，而不仅仅是原始位置
- **未存储补丁**：保持事件（向后兼容）
- **已经拒绝**：在后续查询中跳过事件
### 性能
- 验证仅在查询事件时运行（惰性求值）
- 文件I/O由OS缓存重复读取
- 最小开销：每个`file_edit`事件约1-5毫秒
- 数据库高效存储完整diff作为TEXT列
### `cleanup`
使用作用域清理事件：
```javascript
// 清理整个项目
cleanup({ scope: "project", project_path: "/path/to/project" })
// 清理特定会话
cleanup({ scope: "session", session_id: "abc-123" })
// 清理所有内容
cleanup({ scope: "all", force: true })
```
---
## 会话管理
### `start_session`
开始命名工作会话：
```javascript
start_session({
project_path: "/path/to/project",
agent_id: "claude-code",
name: "bugfix-auth",
description: "Fixing login timeout issue"
})
// → 会话已启动： bugfix-auth (abc-123-def)
```
会话自动隔离上下文 - 以前的事件对查询隐藏。
### `end_session`
结束会话并附上摘要：
```javascript
end_session({
session_id: "abc-123-def",
summary: "Fixed timeout by optimizing DB query"
})
```
### `list_sessions`
查看会话：
```javascript
list_sessions({ project_path: "/path/to/project" })
```
**输出：**
```
● bugfix-auth (2h) by claude
○ feature-payment (1d) by cursor
```
### `switch_session`
恢复以前的会话：
```javascript
switch_session({ session_id: "xyz-789" })
```
---
## 配置
配置文件：`~/.wormhole/config.json`
```json
{
"retention_hours": 24,
"max_payload_chars": 200,
"auto_cleanup": true,
"default_detail": "minimal",
"default_limit": 5
}
```
**注意：** `max_payload_chars`设置截断大多数内容字段以进行显示，但`file_edit`事件中的`diff`字段始终存储完整，以实现准确的过时事件验证。
## 令牌优化
虫洞通过四种关键策略最小化`get_recent`响应的令牌使用：
### 1. 紧凑输出格式（默认）
而不是返回原始JSON，事件被格式化为单行摘要：
```
# 紧凑（默认）- 每事件约35个字符
[5m] claude: npm test → ✓
// 与完整JSON相比 - 每事件约200+个字符
{"id":42,"agent_id":"claude-code","action":"cmd_run","payload":"{\"command\":\"npm test\",\"exit_code\":0}","timestamp":1706621234567,"project_path":"/path/to/project","session_id":"abc-123"}
```
`detail`参数控制详细程度：
- `minimal` （默认）- 带有符号的单行摘要（✓/✗）
- `normal` - 带有关键详细信息的的多行
- `full` - 完整的JSON有效载荷
### 2. 有效载荷截断
内容字段默认截断为200个字符（`max_payload_chars`配置）：
```javascript
// 存储/显示为：
"Added authentication middleware with JWT validation and refresh token..."
// 而不是完整的2000+字符描述
```
**例外：** `file_edit`事件中的`diff`字段永远不会被截断 - 它们对于过时事件验证是必要的。
### 3. 增量查询
使用`since_cursor`仅获取自上次查询以来的事件：
```javascript
// 首次调用返回事件 + 光标
get_recent({ project_path: "." })
// → [5 events] + 光标：evt_42
// 后续调用仅返回新事件
get_recent({ project_path: ".", since_cursor: "evt_42" })
// → [0-2 events] 而不是重复所有5个事件
```
这可以防止重复发送相同的上下文。
### 4. 低默认限制
- `default_limit: 5` - 仅返回最近的5个事件
- 代理可以根据需要使用`limit`参数增加
### 令牌比较
| 场景 | 无优化 | 有优化 |
|----------|---------------------|-------------------|
| 5个事件，首次查询 | ~500-1000令牌 | ~100令牌 |
| 5个事件，增量查询（2个新事件） | ~500-1000令牌 | ~40令牌 |
| 10个事件，完整详细信息 | ~2000+令牌 | ~800令牌 |
### 配置
在 `~/.wormhole/config.json` 中调整：
```json
{
"max_payload_chars": 200,
"default_detail": "minimal",
"default_limit": 5
}
```
## 架构
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Claude Code │ │ Copilot │ │ Cursor │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└────────────────┼────────────────┘
│
┌───────▼───────┐
│ 虫洞 │
│ MCP 服务器 │
└───────┬───────┘
│
┌───────▼───────┐
│ SQLite │
│ timeline.db │
└───────────────┘
```
## 数据存储
- 数据库：`~/.wormhole/timeline.db`
- 配置：`~/.wormhole/config.json`
- 存档：`~/.wormhole/archives/`
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器