feat: 持久对话 MCP 插件 v1.6.37 · Hub + Panel + MCP 三形态部署
- src/: server.js (MCP 4 工具) + hub.js (HTTP Hub) + cursor-title.js - web/: panel.html (主面板) + panel.remote.html (远端 1637) - scripts/: ensure-hub.sh (stdio→http 桥) + mongo_sync.py - mcp-config/: trae.mcp.json + cursor.mcp.json - docs/: INSTALL / DEPLOY / MCP_SETUP / ARCHITECTURE / QUICKSTART - ZIP 原始安装包备查 关键机制： - 4 MCP 工具：init / select / wait / merge - 垂直绑定：workspace::cursorTitle@hostIp 三件指纹 - 真挂起：关闭 timedReply 后 wait 真正阻塞，agent turn 不结束 - 双 Hub 部署：远端 NAS 24×7 + 本地 launchd 守护备份 - 三形态组合：远端 + 本地 + Trae 插件，可同时跑
This commit is contained in:
卡若AI
161
docs/QUICKSTART.md
Normal file
161
docs/QUICKSTART.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 5 分钟上手（QUICKSTART.md）
|
||||
|
||||
> 假设你的工作环境是 macOS + Trae CN + 公司 NAS（192.168.110.101）
|
||||
> 跟着抄，5 分钟内跑起来。
|
||||
|
||||
---
|
||||
|
||||
## Step 1 · 装到本地（30s）
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.persistent-chat-local
|
||||
|
||||
# 从仓库拷核心文件
|
||||
git clone http://192.168.110.101:3000/fnvtk/persistent-chat-plugin.git /tmp/pchat
|
||||
cp /tmp/pchat/src/* ~/.persistent-chat-local/
|
||||
cp /tmp/pchat/web/panel.html ~/.persistent-chat-local/
|
||||
cp /tmp/pchat/scripts/ensure-hub.sh ~/.persistent-chat-local/
|
||||
chmod +x ~/.persistent-chat-local/ensure-hub.sh
|
||||
```
|
||||
|
||||
## Step 2 · 写 MCP 配置（30s）
|
||||
|
||||
```bash
|
||||
cat > ~/.trae/mcp.json <<'EOF'
|
||||
{
|
||||
"mcpServers": {
|
||||
"persistent-chat": {
|
||||
"type": "stdio",
|
||||
"command": "/Users/karuo/.persistent-chat-local/ensure-hub.sh",
|
||||
"args": ["--workspace=${workspaceFolder}"],
|
||||
"env": {
|
||||
"PCHAT_HTTP_PORT": "13458",
|
||||
"PCHAT_NODE": "/usr/local/opt/node@22/bin/node",
|
||||
"PCHAT_HUB_HOST": "192.168.110.101",
|
||||
"NO_PROXY": "192.168.110.101,127.0.0.1,localhost"
|
||||
},
|
||||
"disabled": false,
|
||||
"autoApprove": [
|
||||
"wait_for_user_input",
|
||||
"init_conversation",
|
||||
"merge_conversation",
|
||||
"select_conversation"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
## Step 3 · 配 Hub（远端 NAS，已有则跳过）
|
||||
|
||||
在 NAS 上（ssh fnvtk@192.168.110.101）：
|
||||
|
||||
```bash
|
||||
mkdir -p /volume1/homes/fnvtk/.persistent-chat-local
|
||||
cd /volume1/homes/fnvtk/.persistent-chat-local
|
||||
# scp 把 src/* + web/panel.html 拷过来
|
||||
chmod +x ensure-hub.sh
|
||||
|
||||
# 启动
|
||||
nohup /usr/local/opt/node@22/bin/node hub.js > logs/hub.log 2>&1 &
|
||||
disown
|
||||
```
|
||||
|
||||
## Step 4 · 配本地备份 Hub（30s）
|
||||
|
||||
```bash
|
||||
cat > ~/Library/LaunchAgents/com.karuo.persistent-chat-hub.plist <<'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key><string>com.karuo.persistent-chat-hub</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/usr/local/opt/node@22/bin/node</string>
|
||||
<string>/Users/karuo/.persistent-chat-local/hub.js</string>
|
||||
</array>
|
||||
<key>WorkingDirectory</key><string>/Users/karuo/.persistent-chat-local</string>
|
||||
<key>RunAtLoad</key><true/>
|
||||
<key>KeepAlive</key><true/>
|
||||
<key>StandardOutPath</key><string>/Users/karuo/.persistent-chat-local/logs/launchd.log</string>
|
||||
<key>StandardErrorPath</key><string>/Users/karuo/.persistent-chat-local/logs/launchd.err</string>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
|
||||
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.karuo.persistent-chat-hub.plist
|
||||
```
|
||||
|
||||
## Step 5 · Trae Cmd+Q 重开（10s）
|
||||
|
||||
完全退出 Trae（不是关窗），重开。
|
||||
|
||||
## Step 6 · 验证（30s）
|
||||
|
||||
打开 Trae → SOLO Agent 窗口 → 看到 4 个工具：
|
||||
|
||||
```
|
||||
✓ init_conversation
|
||||
✓ select_conversation
|
||||
✓ wait_for_user_input
|
||||
✓ merge_conversation
|
||||
```
|
||||
|
||||
发："**开始测试**"
|
||||
|
||||
期望：
|
||||
1. 看到 `init_conversation` 调出
|
||||
2. 拿到 `ct_xxxx` 的 token
|
||||
3. 收到 [卡若复盘] 格式回复
|
||||
4. Agent 继续 wait
|
||||
|
||||
## Step 7 · 跑三段式（持续）
|
||||
|
||||
每次用户发新消息：
|
||||
|
||||
```
|
||||
1. select_conversation(token=ct_xxx) ← 接回旧 session
|
||||
2. 执行用户任务
|
||||
3. 写 [卡若复盘] 🎯📌💡📝▶
|
||||
4. wait_for_user_input(token=ct_xxx, message=提示)
|
||||
5. 循环
|
||||
```
|
||||
|
||||
## Step 8 · 结束（仅在用户说"结束持久对话"时）
|
||||
|
||||
```javascript
|
||||
// 用户说"结束持久对话"后
|
||||
await mcp.call('merge_conversation', {
|
||||
fromToken: 'ct_xxx',
|
||||
toToken: 'ct_归档', // 或留空 = 纯归档
|
||||
cursorTitle: '当前标签',
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎉 完成
|
||||
|
||||
你现在有：
|
||||
- ✅ 远端 NAS Hub 24×7 在
|
||||
- ✅ 本地备份 Hub（挂了自动起）
|
||||
- ✅ Trae 插件 4 工具全可用
|
||||
- ✅ 持久对话循环（不主动结束）
|
||||
|
||||
---
|
||||
|
||||
## 🆘 卡住看这里
|
||||
|
||||
| 现象 | 一行修 |
|
||||
|:---|:---|
|
||||
| Trae 看不到 4 工具 | `Cmd+Q` 重开 |
|
||||
| Hub 启动失败 | `node hub.js` 前台跑看错 |
|
||||
| 提示 Token未获取 | Trae 没重启 |
|
||||
| 任务完成 = 对话死 | 不是，Hub 仍 holding，下一条进来自动续 |
|
||||
| wait 不返回 | 真挂起模式生效，等你发消息 |
|
||||
|
||||
---
|
||||
|
||||
> 详细见 [DEPLOY.md](DEPLOY.md) / [MCP_SETUP.md](MCP_SETUP.md) / [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
Reference in New Issue
Block a user