# 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)