persistent-chat-plugin/docs/QUICKSTART.md

5 分钟上手（QUICKSTART.md）

假设你的工作环境是 macOS + Trae CN + 公司 NAS（192.168.110.101）
跟着抄，5 分钟内跑起来。

---

Step 1 · 装到本地（30s）

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）

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）：

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）

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 · 结束（仅在用户说"结束持久对话"时）

// 用户说"结束持久对话"后
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 / MCP_SETUP.md / ARCHITECTURE.md