persistent-chat-plugin/docs/prd/PersistentChat_模块说明.md

Persistent Chat × CO-Chat 整合 · 模块说明

版本：v1.0 · 2026-06-29
源码根：.persistent-chat-v1.1/ · 运行时：~/.persistent-chat-local/

---

1. 架构总览

┌─────────────────────────────────────────────────────────────┐
│  Cursor IDE                                                  │
│  ├─ VSIX persistent-chat-4.6 (MCP 4 tools)                  │
│  ├─ 模式 A: persistent-chat.mdc → wait_for_user_input       │
│  └─ 模式 B: pchat-composer.mdc → Composer + 增强包          │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP
┌───────────────────────────▼─────────────────────────────────┐
│  Hub :13458  (~/.persistent-chat-local/hub.js)              │
│  ├─ 主面板 panel.html / 增强 panel-enhance.html              │
│  ├─ lib/hub-routes-prd.js  → /api/enhance/* /api/prd/*      │
│  └─ composer-enhance.json  → 门禁状态                        │
└───────────────────────────┬─────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   vendor/cochat-engine   globalStorage      Cursor settings
   (补丁引擎 3.3.34)      (co-chat storage)   (noQuota 参数)

---

2. lib/ 模块一览

模块	文件	职责	主要 API
增强核心	enhance.js	W2/W6/W8 门禁、诊断、Toggle、native 同步	/api/enhance/*
Hub 路由	hub-routes-prd.js	PRD 期路由聚合	见下表
补丁编排	patch-via-cochat.mjs	排队补丁，不强杀 Cursor	W7 apply
补丁激活	patch-activate.mjs	headless activate（备用，效果有限）	内部
桥接	bridge.js	Composer 结论 → ct_ 会话	POST /api/bridge/sync
模板	templates.js	双 Chat 模板元数据	GET /api/templates
模式	mode.js	规则互斥检测、会话 badge	GET /api/mode/check
冒烟	smoke.js	9 项 API 自动化	POST /api/smoke/run
退役	retire.js	co-chat 卸载前置检查	GET /api/retire/check
进度	prd-progress.json	Hub PRD 勾选真源	GET /api/prd/progress

---

3. enhance.js 核心概念

3.1 门禁字段（composer-enhance.json）

字段	含义
permOk	workbench 目录可写（W2）
cursorPrefOk	Plan / RunMode / HTTP1.1（W6）
patchOk	workbench 内三类 CO 标记已注入
patchNativeOk	pchat 原生路径就绪（storage + settings 已同步）
patchPending	等待 Cmd+Q 或 watcher 打补丁
enhanceEnabled	用户开启核心增强包
integrityOk	vendor SHA256 9/9

3.2 验收逻辑

gatesPass = permOk && cursorPrefOk && (patchOk || patchNativeOk)
w8GatesPass = permOk && (patchOk || patchNativeOk)
modeBGatesPass = permOk && cursorPrefOk && (patchOk || patchNativeOk)

3.3 关键函数

函数	作用
syncPchatNativeEnhance()	写 co-chat storage + Cursor settings（无卡密）
resolvePatchPending()	诊断时同步 native、清 pending、更新 PRD
diagnose()	全量门禁 + hint
setEnhanceEnabled()	Toggle；W2+W6 通过即可开
startPatchWatcher()	4s 轮询 pending-w7，Cursor 退出后重试补丁

---

4. API 路由表

方法	路径	模块
GET	/api/enhance/status	enhance
GET	/api/enhance/diagnose	enhance
POST	/api/enhance/apply	enhance (W7)
POST	/api/enhance/toggle	enhance
POST	/api/enhance/fix-perm	enhance (W2)
POST	/api/enhance/fix-prefs	enhance (W6)
GET	/api/enhance/opus-probe	enhance
GET	/api/prd/progress	prd-progress
GET	/api/mode/check	mode
POST	/api/mode/retire-cochat-rule	mode（移 co-chat.mdc → _retired）
GET	/api/templates	templates
POST	/api/bridge/sync	bridge
POST	/api/smoke/run	smoke
GET	/api/retire/check	retire
GET	/enhance	panel-enhance.html

---

5. vendor 资产

路径	说明
.persistent-chat-v1.1/vendor/cochat-engine/3.3.34/	捆绑引擎
PersistentChat_CO引擎资产清单_v1.json	SHA256 清单
开发文档/脚本/pchat_verify_cochat_bundle.sh	校验脚本
开发文档/脚本/pchat_bundle_cochat_engine.sh	打包脚本

workbench 标记（patchOk 验）：

• CO_NO_QUOTA_MCP_V1_START
• CO_COMPOSER_BRIDGE_START
• CO_NO_QUOTA_EXTHOST_V1_START（extensionHostProcess.js）

---

6. 规则文件

文件	模式	末工具
.cursor/rules/persistent-chat.mdc	A · 续跑	wait_for_user_input
.cursor/rules/pchat-composer.mdc	B · 增强	Composer（无 wait 循环）
.cursor/rules/_retired/co-chat.mdc	已退役	勿与 A 同载

模板定义：开发文档/pchat-composer.mdc（源）→ 同步到 .cursor/rules/。

---

7. 脚本

脚本	用途
开发文档/脚本/sync_pchat_runtime.sh	lib → ~/.persistent-chat-local + 重启 Hub
开发文档/脚本/pchat_smoke_test.sh	9 项 curl 冒烟
开发文档/脚本/retire_cochat.sh	卸载 co-chat 扩展
开发文档/脚本/pchat_retire_co_rule.sh	退役 workspace co-chat.mdc

---

8. 文档索引

文档	读者
PersistentChat_整合CO-Chat_需求PRD_v1.md	PM / 开发
PersistentChat_安装说明.md	用户安装
PersistentChat_经验汇总.md	排错
PersistentChat_模块说明.md	开发架构
PersistentChat_模式B_Opus探测验收.md	模式 B 实测
AGENTS.md	快速入口

---

9. 开发工作流

# 1. 改源码
vim .persistent-chat-v1.1/lib/enhance.js

# 2. 同步 + 重启
bash 开发文档/脚本/sync_pchat_runtime.sh

# 3. 冒烟
bash 开发文档/脚本/pchat_smoke_test.sh

# 4. 增强页验证
open http://127.0.0.1:13458/enhance