karuo-ai/01_卡资（金）/金仓_存储备份/Cursor持久对话/部署与长连接接入.md

Persistent Chat · 部署与长连接接入

版本 v1.6.14 · Skill SKILL.md · 面板 http://127.0.0.1:13458
UI 规范 卡若AI Glass UI Kit（04_卡火/火炬_全栈消息/前端开发/私域银行统一前端模块）

---

一、这是什么

本地 MCP 长连接插件：让 Cursor Agent 在 wait_for_user_input 挂起时不中断，通过 HTTP 长轮询 + 浏览器面板持续对话。

组件	路径	端口/协议
Hub（唯一 HTTP）	~/.persistent-chat-local/hub.js	13458
MCP 客户端	~/.persistent-chat-local/server.js	stdio → Cursor
面板	~/.persistent-chat-local/panel.html	浏览器
会话	sessions.json + Mongo karuo_site.持久对话会话	—

Cursor Agent ──stdio──► server.js ──HTTP──► hub.js:13458 ◄── poll ── MCP
                              ▲                    │
                              │                    ├── panel.html（浏览器）
                              └── wait/register    └── /api/wait/poll（28s 长轮询）

---

二、一键部署（本机 / 新科室 Mac）

# 1. 安装（全局 MCP + 项目规则 + 运行时）
bash "/Users/karuo/Documents/个人/卡若AI/01_卡资（金）/金仓_存储备份/Cursor持久对话/install.sh"

# 指定项目
bash install.sh --project "/path/to/repo"

# 卡若多根工作区一次装齐
bash install.sh --all-karuo

# 2. 同步最新面板/Hub（改 package 后必跑）
bash "/Users/karuo/Documents/个人/卡若AI/01_卡资（金）/金仓_存储备份/Cursor持久对话/脚本/sync-runtime.sh"

# 3. 验收
bash "/Users/karuo/Documents/个人/卡若AI/01_卡资（金）/金仓_存储备份/Cursor持久对话/check-mcp.sh"

安装后：Cmd+Q 完全退出 Cursor → 重开 → Settings → MCP → 打开 persistent-chat → 浏览器打开 http://127.0.0.1:13458

---

三、跨机 / 跨科室 checklist

步骤	命令/动作	通过标准
Node ≥18	node -v	有版本号
安装	install.sh --project <科室项目>	无报错
Hub 健康	curl -s http://127.0.0.1:13458/api/health	"ok":true, panelVersion ≥ 1.6.14
MCP 绿点	Cursor Settings → MCP	persistent-chat 在线
面板	浏览器 13458	顶部「已连接」
绑定	Agent init_conversation(cursorTitle=标签名)	返回 ct_ + 垂直绑定
长连接	Agent wait_for_user_input	面板可见会话，Hub 日志 wait register
Mongo（可选）	mongosh mongodb://127.0.0.1:27017/karuo_site	集合 持久对话会话 有增量

环境变量（可选）

变量	默认	说明
PCHAT_HTTP_PORT	13458	Hub 端口
PCHAT_INSTALL_DIR	~/.persistent-chat-local	运行时目录

---

四、长连接 API（给其他工具接入）

任何能发 HTTP 的工具（Codex CLI、Claude Desktop 自定义桥、内部脚本）均可对接 同一 Hub：

方法	路径	用途
GET	/api/health	健康检查
GET	/api/state	会话列表 + 设置
POST	/api/init	创建/复用 ct_
POST	/api/wait/register	MCP 挂起注册（内部）
GET	/api/wait/poll?token=ct_xxx	长轮询等用户回复（28s renewal）
POST	/api/reply	面板/外部发回复 {token, reply}
POST	/api/continue	手动继续
POST	/api/session/config	单对话 {token, continueMode, sessionAutoContinue}
POST	/api/settings	全局默认

长轮询时序

1. MCP wait_for_user_input → server.js POST /api/wait/register
2. server.js GET /api/wait/poll?token=ct_xxx 挂起（最长 28s）
3. 超时返回 {status:"renewal"} → 立即再 poll（长连接效果）
4. 用户面板 POST /api/reply → poll 返回 {status:"replied", reply} → Agent 继续

单对话续跑三模式（v1.6.13+）

模式	continueMode	Hub 行为
复盘	standard	追问→检索→执行（需复盘块）
直通	turbo	直推开发，不等复盘
优化	optimize	总结→WebSearch/GitHub→补文档→开发

默认：自动续跑开（sessionAutoContinue: true），在面板每个对话详情区配置。

---

五、与 MCP 管理 Skill 的关系

• 内置插件：persistent-chat 已随 install.sh 写入 ~/.cursor/mcp.json，无需 MCPfinder 再搜。
• 外接 MCP：其他能力仍走 02_卡人/水桥_平台对接/MCP管理/SKILL.md 搜索安装。
• 并存铁律：同一 Cursor 只保留 一个 persistent-chat 条目；重复时用 脚本/清理重复MCP.sh。

---

六、踩坑与经验（2026-05 面板迭代）

现象	根因	修复
左侧列表闪	每 2s 全量 innerHTML 重建	v1.6.12+ 增量 patchSessionItem
消息区弹回顶部	重渲染未区分用户滚动	msgStickToBottom + 近底自动滚
发错 ct_	多标签串 token	垂直绑定 + cursorTitle 必填
面板离线	Hub 未起	sync-runtime.sh 或 node ~/.persistent-chat-local/hub.js
优化模式不跑	未切单对话模式	面板详情区选「优化」+ 自动续跑开

---

七、UI 规范（卡若AI 组件）

面板 panel.html 使用 Glass UI Kit kir- 令牌*（毛玻璃 + 蓝紫渐变），与私域银行三端一致：

• 背景：linear-gradient 浅蓝紫
• 卡片：backdrop-filter: blur(16px) + rgba(255,255,255,.78)
• 主按钮：linear-gradient(135deg, #2563eb, #7c3aed)
• 圆角：16px（--kir-radius-lg）

真源：04_卡火（火）/火炬_全栈消息/前端开发/私域银行统一前端模块/tokens/kir-unified-tokens.css

---

八、卸载

# 删 MCP 条目（编辑 ~/.cursor/mcp.json 去掉 persistent-chat）
rm -rf ~/.persistent-chat-local
# 可选删项目规则
rm -f .cursor/rules/persistent-chat.mdc