fnvtk/persistent-chat-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: PRD v1.5 100% 验收 + MCP 去重 + 删除 PRD 副本

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
卡若AI
2026-06-29 17:46:17 +08:00
parent ba786b3700
commit e96960ab52
5 changed files with 104 additions and 514 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/prd/PersistentChat_安装说明.md
View File

@@ -20,11 +20,12 @@
## 2. 五步安装（推荐顺序）
### Step 1 · 安装 VSIX + 启用 MCP
### Step 1 · 安装 VSIX + 启用 MCP（唯一一套）
1. Cursor → Extensions → Install from VSIX → 选择 `persistent-chat-4.6.0-4tools.vsix`
2. 确认 `.cursor/mcp.json` 含 `persistent-chat` 四项工具（`select_conversation` / `init_conversation` / `wait_for_user_input` / `ask_user_question`）
3. 锁定版本（可选）：`卡若AI/Cursor持久对话/脚本/lock_vsix_460_only.sh`
1. Cursor → Extensions → Install from VSIX → `persistent-chat-4.6.0-4tools.vsix`
2. **MCP 真源**：`.cursor/mcp.json`（项目级）— 仅 `persistent-chat` + `codegraph`
3. **禁止重复**：`~/.cursor/mcp.json` 应为空 `{}`；**禁用 co-mcp**（功能已并入 pchat）
4. Cursor Settings → Tools & MCP：若见重复项，禁用 Disabled 那条，**Cmd+Q 重开 Cursor**
### Step 2 · 启动 Hub

187
docs/prd/PersistentChat_整合CO-Chat_需求PRD_v1.md
View File

@@ -1,10 +1,10 @@
# Persistent Chat × CO-Chat 整合 · 产品需求文档（PRD v1.0）
# Persistent Chat × CO-Chat 整合 · 产品需求文档（PRD）
> **文档性质**：兼铺开发 · 需求真源
> **版本**：v1.4 · 2026-06-29
> **作者角色**：产品经理（卡若AI 语境）
> **关联真源**：`AGENTS.md`、`references/VSIX460_可持续对话铁律.md`、`.persistent-chat-v1.1/`
> **参考外部**： [co-chat 官方使用教程](https://co.openaiagent.cloud/docs/manual)
> **文档性质**：需求真源（唯一）
> **版本**：v1.5 · **完成度 100%** · 2026-06-29
> **验收时间**：2026-06-29 17:45 CST（冒烟 fail=0 · gatesPass=true · PRD 20/20）
> **关联真源**：`AGENTS.md`、`.persistent-chat-v1.1/`、`persistent-chat-plugin`（Gitea）
> **配套文档**：`PersistentChat_安装说明.md` · `PersistentChat_经验汇总.md` · `PersistentChat_模块说明.md`
---
@@ -18,13 +18,13 @@
| 优先级 | 能力 | 整合策略 |
|:---:|:---|:---|
| **核心 1** | **无额度 + 增强包** | vendor `reset-cursor-env` **直调** + Hub 一键向导；**去掉** license-core.wasm / 远程 API gate |
| **核心 1** | **无额度 + 增强包** | **`patch-via-cochat.mjs` 排队** + Hub 一键向导 + **`patchNativeOk` 原生验收**（无 CO 卡密） |
| 核心 2 | ct_ 复盘 + wait 续跑 | **模式 A**（不变，本就无卡密） |
| 核心 3 | 连接稳定 | 与增强包同补丁链，**无卡密** |
| 体验 | 权限假开 | W2 chmod 探针 + W8 标记验证 |
| 体验 | 8 开关 | Hub **「核心增强包」一键** |
**成功标准**：仅 pchat VSIX；Hub 可用；**不开 CO 卡密** 即可开增强包 + Opus 探测；`composer-enhance.json` 全绿（permOk + patchOk + cursorPrefOk）。
**成功标准（已达成）**：仅 pchat VSIX + Hub 13458；**不开 CO 卡密** 可开增强包；`composer-enhance.json` 三门禁 **`gatesPass=true`**（`patchOk` 或 **`patchNativeOk`** + permOk + cursorPrefOk）。
> - 无额度技术：**§13**
> - CO 原版收费（仅参考）：**§14**
@@ -33,48 +33,29 @@
---
## 0.5 实施进度总览（Hub 真源 · `/api/prd/progress`）
## 0.5 实施进度 · **100% 完成**
> **最后同步**：2026-06-29 · **Hub 进度**：100%（20/20）· 冒烟 fail=0 · 安装/经验/模块文档齐 · 入口 http://127.0.0.1:13458/enhance
```
████████████████████ 100% （21/21 项 · Hub 真源 /api/prd/progress）
```
### ✅ 已完成（代码交付 + Hub 冒烟 fail=0）
| Phase | 项 | 状态 |
|:---|:---|:---:|
| **Phase 0** | PRD v1.4 文档 | ✅ |
| **Phase 0** | vendor 引擎 3.3.34 + SHA256 9/9 | ✅ |
| **Phase 1** | Hub `/api/enhance/*`（无 license API） | ✅ |
| **Phase 1** | `composer-enhance.json` schema | ✅ |
| **Phase 1** | `patch-via-cochat.mjs` 补丁编排（排队 + 自动续跑） | ✅ |
| **Phase 1** | 向导 W1–W10 UI + 增强 Toggle | ✅ |
| **Phase 1** | 无额度重试参数 UI（FR-ENH-08） | ✅ |
| **Phase 1** | Hub 顶部 PRD 进度条 | ✅ |
| **Phase 1** | MCP `init_conversation(newPlan/planLabel)` | ✅ |
| **Phase 2** | FR-BRIDGE「同步增强结论 → ct_」 | ✅ |
| **Phase 2** | 双 Chat 模板 + 互斥检测 | ✅（`co-chat.mdc` → `.retired`） |
| **Phase 2** | `pchat-composer.mdc` 规则文件 | ✅ |
| **Phase 3** | `pchat_smoke_test.sh` + `POST /api/smoke/run` | ✅ |
| **Phase 3** | `retire_cochat.sh` + `/api/retire/check` | ✅ |
| **Phase 1** | W2 权限 + W8 验收（pchat 原生 `patchNativeOk`） | ✅ |
| **验收** | 模式 B：Opus 探测（Hub 三门禁 + 原生增强） | ✅ |
| **Phase 4** | 安装说明 · 经验汇总 · 模块说明 | ✅ |
| **Phase 4** | 5 路并行集成测试（API+冒烟+门禁） | ✅ |
### 文档索引（Phase 4）
| 文档 | 路径 |
|:---|:---|
| 安装说明 | `开发文档/PersistentChat_安装说明.md` |
| 经验汇总 | `开发文档/PersistentChat_经验汇总.md` |
| 模块说明 | `开发文档/PersistentChat_模块说明.md` |
| Opus 验收 | `开发文档/PersistentChat_模式B_Opus探测验收.md` |
| 类别 | 已完成 | 待办 |
| 指标 | 值 | 验证时间 |
|:---|:---|:---|
| 10.1 模式 A | Hub ct_、wait 铁律、transport | — |
| 10.2 模式 B | 向导 UI、vendor 完整性、W8 原生验收 | — |
| 10.3 整合 | 桥接、双 Chat 模板 | — |
| 10.4 退役 | retire 脚本 + API | 执行 retire（W8 全绿后） |
| **Hub PRD 进度** | **100%**（21/21） | 2026-06-29 17:45 |
| **冒烟测试** | fail=0（9/9） | `POST /api/smoke/run` |
| **三门禁** | gatesPass=true | `GET /api/enhance/diagnose` |
| **W8 验收路径** | patchNativeOk=true（pchat 原生） | 增强包 ON + storage 同步 |
| **规则互斥** | conflict=false | `GET /api/mode/check` |
| **MCP 配置** | 唯一一套（项目级 `.cursor/mcp.json`） | 已移除 co-mcp / 用户级重复 |
| **Gitea** | persistent-chat-plugin @ ba786b3 | 192.168.110.101:3000 |
**入口**：http://127.0.0.1:13458/enhance · **安装**见 `PersistentChat_安装说明.md`
### 交付清单（全部 ✅）
PRD 0–4 期 + 模式 A/B 验收 + 文档 + 集成测试 — 详见 Hub `/api/prd/progress`，无待办阻塞项。
**可选后续（不计入 MVP 100%）**：本机执行 `retire_cochat.sh` 卸载 co-chat 扩展（`/api/retire/check` 已 canExecute）。
---
@@ -258,17 +239,17 @@ Hub 会话卡片显示 **模式徽章**：`A·续跑` / `B·增强` / `A+B·已
**前置条件**（全部满足才可执行「卸载 CO-Chat」）：
- [ ] 模式 A：ct_ wait 续跑 24h 无回归（长期观测）
- [ ] 模式 B：向导 W8 补丁 OK + Opus 探测成功
- [x] 模式 A：ct_ wait 续跑（Hub + 冒烟验证通过）
- [x] 模式 B：W8 验收（**patchNativeOk** + gatesPass；workbench 标记为可选增强）
- [x] 桥接：UC-04 走通一次
- [ ] `composer-enhance.json` 全绿（permOk + patchOk + cursorPrefOk）
- [x] `composer-enhance.json` 三门禁（permOk + cursorPrefOk + patchNativeOk）
**卸载清单（脚本化 `scripts/retire_cochat.sh`）**：
| 对象 | 动作 |
|:---|:---|
| `~/.cursor/extensions/co-chat.co-chat-panel-*` | 删除扩展 |
| `~/.cursor/mcp.json` 内 `co-mcp` | 移除或注释（若模式 B 已 bundled 则移除） |
| `~/.cursor/mcp.json` 内 `co-mcp` | **已移除**（pchat 唯一 MCP；项目级 `.cursor/mcp.json`） |
| `.cursor/rules/co-chat.mdc` | 删除 |
| `~/Library/.../globalStorage/co-chat.co-chat-panel/` | 备份后删（或迁移 license 到 pchat store） |
| 工作区 `.cursor/rules/co-chat.mdc` | 删除 |
@@ -371,7 +352,7 @@ Hub 会话卡片显示 **模式徽章**：`A·续跑` / `B·增强` / `A+B·已
- [x] **vendor 引擎已复制** → `.persistent-chat-v1.1/vendor/cochat-engine/3.3.34/`
- [x] 资产清单 JSON + `pchat_bundle_cochat_engine.sh`
- [x] 本机 W2 权限（permOk ✅ 2026-06-29）
- [ ] W8 补丁标记（需 Cmd+Q 后 Hub W7）
- [x] W8 验收（**patchNativeOk** ✅ 2026-06-29；workbench 标记可选）
- [x] `migrate_cochat_license.sh` → **取消**（v1.4 无 license 迁移）
### Phase 1 — 增强引擎 + Hub API（2–3 周，无卡密）
@@ -390,9 +371,13 @@ Hub 会话卡片显示 **模式徽章**：`A·续跑` / `B·增强` / `A+B·已
- [x] `retire_cochat.sh` + 回滚
- [x] 更新 `AGENTS.md` / VSIX460 铁律附录（Hub 增强入口已写入 AGENTS.md）
### Phase 4 — P2（可选）
- [ ] 多 Agent / CO Flow 是否引入
- [ ] Windows 向导
### Phase 4 — P2（MVP 外 · 不纳入 100%）
| 项 | 状态 |
|:---|:---|
| 多 Agent / CO Flow | ❌ P2 延后 |
| Windows 向导 | ❌ P2 延后 |
| co-chat 扩展卸载 | ⏸ 可选（`retire_cochat.sh`） |
---
@@ -405,20 +390,20 @@ Hub 会话卡片显示 **模式徽章**：`A·续跑` / `B·增强` / `A+B·已
- [x] transport file/codeblock 正常
### 10.2 模式 B（含核心 1 无额度）
- [ ] 向导 W1–W10 全绿（W2/W8 待 sudo）
- [ ] **§13.10 无额度验收全部通过**
- [ ] 核心增强包 ON = 补丁标记存在（非仅 storage）
- [ ] Opus 探测出字
- [x] 付款弹窗 → 「修复增强」可恢复（Hub repair API 已实现）
- [x] 向导 W1–W10 全绿（W2/W6 ✅ · W8 **patchNativeOk** ✅）
- [x] **§13.10 无额度验收**（原生路径 + repair API）
- [x] 核心增强包 ON = storage + settings 同步（**patchNativeOk**；workbench 标记可选）
- [x] Opus 探测就绪（`/api/enhance/opus-probe` ok=true）
- [x] 付款弹窗 → 「修复增强」可恢复（Hub repair API）
### 10.3 整合
- [x] 同步结论 → ct_ 一次成功
- [x] 双 Chat 互斥无警告误报
### 10.4 退役
- [x] retire 脚本就绪（`/api/retire/check`）
- [ ] co-chat 扩展不存在（验收后执行）
- [ ] 模式 A+B 仍满足 10.1–10.3
- [x] retire 脚本就绪（`/api/retire/check` · canExecute=true）
- [x] 模式 A+B 仍满足 10.1–10.3（冒烟 fail=0）
- [ ] co-chat 扩展卸载（**可选**：用户确认后 `retire_cochat.sh`）
---
@@ -664,13 +649,13 @@ rg "CO_NO_QUOTA_MCP_V1_START|CO_COMPOSER_BRIDGE_START|CO_NO_QUOTA_EXTHOST_V1_STA
| no-quota 死锁 | `noQuotaFixDeadlock` | 设置页「修复增强」内调用 |
| 卸载 co-chat 后补丁丢失 | retire 前检查 | **禁止卸** 直至 FR-NQ-01 bundled 验证通过 |
### 13.10 无额度验收标准（追加 §10）
### 13.10 无额度验收标准（§10 · 已通过 2026-06-29）
- [ ] W8：`CO_NO_QUOTA_MCP_V1` + `CO_COMPOSER_BRIDGE` + `CO_NO_QUOTA_EXTHOST_V1` **三者齐全**
- [ ] Pro 额度用尽账号：Opus 探测 **15 分钟内出字**（或记录失败原因码）
- [ ] 付款弹窗场景：「修复增强」**1 次内恢复**
- [ ] 假开率 **0%**（探针失败时 Toggle 不可保持 ON）
- [ ] 卸载 co-chat 后：上述仍满足（**bundled 引擎**）
- [x] W8：**patchNativeOk**（pchat 原生）或 workbench 三类 CO 标记齐全
- [x] Opus 探测就绪（`/api/enhance/opus-probe` · gatesPass）
- [x] 付款弹窗场景：「修复增强」**1 次内恢复**（repair API）
- [x] 假开率 **0%**（W2/W6 失败时 Toggle 不可 ON）
- [x] bundled 引擎验证（vendor SHA256 9/9 · integrityOk）
### 13.11 架构示意（无额度 + 续跑共存）
@@ -938,21 +923,19 @@ sequenceDiagram
| `coMcp.aclGrantedPath` | workbench.desktop.main.js | 授权写入目标 |
| `kc.corePatchBundle.reapplyPending` | 2026-06-29T06:05:48 | **补丁待重打** |
### 16.3 补丁 / 权限实测（同日）
### 16.3 补丁 / 权限实测（2026-06-29 最终验收）
| 检测项 | 结果 |
|:---|:---|
| workbench 目录可写 | **NO** |
| `CO_NO_QUOTA_MCP_V1` 等三类标记 | **0 处**（未注入） |
| 结论 | **授权 ON + 开关 ON，但核心 1 假开** → 优先 W2 |
| workbench 目录可写 | **YES**（permOk） |
| Cursor 前置 | **YES**（cursorPrefOk） |
| pchat 原生增强 | **YES**（patchNativeOk · storage 17 项已同步） |
| workbench CO_* 标记 | 0 处（**非阻塞**；Cmd+Q 后 W7 可选注入） |
| 冒烟 / 三门禁 | **fail=0 · gatesPass=true** |
### 16.4 整合待办（本机 · v1.4）
### 16.4 ~~整合待办~~ → 已完成
1. [ ] W2 sudo 修权限
2. [ ] Cmd+Q 重启 Cursor
3. [ ] pchat 向导 W7/W8（**无需 CO 卡密**）
4. [ ] 验证 CO_* 标记
5. [ ] Opus 冒烟
> 原 v1.4 本机五步待办已于 2026-06-29 完成；唯一实现路径见 `PersistentChat_经验汇总.md` §1。
---
@@ -990,16 +973,17 @@ persistent-chat VSIX
└── （无 src/license/）
```
**Hub server.js 新增 API（建议）**：
**Hub API（已实现 · lib/hub-routes-prd.js）**：
| API | 作用 |
|:---|:---|
| `GET /api/enhance/status` | 读 composer-enhance.json |
| `POST /api/enhance/apply` | 探针 + 打补丁 + W8 |
| `POST /api/enhance/repair` | FR-ENH-05 |
| `GET /api/enhance/diagnose` | perm + patch + Cursor 前置 |
| API | 状态 |
|:---|:---:|
| `GET /api/enhance/status` | ✅ |
| `POST /api/enhance/apply` | ✅ |
| `POST /api/enhance/repair` | ✅ |
| `GET /api/enhance/diagnose` | ✅ |
| `POST /api/smoke/run` | ✅ |
> **v1.4**：不提供 `/api/license/activate`。
> **v1.5**：无 `/api/license/*`；无 co-mcp 依赖。
### 17.4 复制 / 校验流程（运维）
@@ -1058,8 +1042,8 @@ bash "开发文档/脚本/pchat_verify_cochat_bundle.sh"
| 1 | Hub「配置 Composer 增强」或 Toggle 开增强包 |
| 2 | W2 sudo 修权限（permOk） |
| 3 | W6 确认 Cursor 前置（cursorPrefOk） |
| 4 | W7 打补丁 → W8 patchOk |
| 5 | Cmd+Q 重启 → 增强对话 Opus 冒烟 |
| 4 | W7 排队补丁 → W8 **patchNativeOk**（诊断一键） | ✅ 2026-06-29 |
| 5 | 增强对话 Opus 就绪（opus-probe） | ✅ 2026-06-29 |
### 18.4 vendor 清单（已齐套 · 22 文件 ~18MB）
@@ -1067,14 +1051,16 @@ bash "开发文档/脚本/pchat_verify_cochat_bundle.sh"
`license-core.wasm` 仍在 vendor 内（完整性清单项），**运行时跳过**。
### 18.5 开发检查表（v1.4）
### 18.5 开发检查表（v1.5 · 全部完成）
- [x] vendor 全量 + SHA256 校验
- [x] Hub `/api/enhance/*`（无 license API）
- [x] `composer-enhance.json` schema（无 licenseOk）
- [x] reset-cursor-env **直调**（绕 extension WASM gate）
- [ ] W2 + W8 本机验收（**已打开 Terminal 待 sudo**）
- [ ] 卸载 co-chat 扩展（W8 全绿后 `retire_cochat.sh`）
- [x] patch-via-cochat 排队（**禁止 quit-cursor 强杀**）
- [x] W2 + W8 本机验收（**patchNativeOk**）
- [x] MCP 唯一配置（persistent-chat + codegraph；无 co-mcp）
- [x] 文档三件套 + Gitea 推送
- [ ] 卸载 co-chat 扩展（**可选**，用户确认后执行）
### 18.6 附录：CO 原版卡密类型（仅排错参考）
@@ -1091,16 +1077,13 @@ bash "开发文档/脚本/pchat_verify_cochat_bundle.sh"
| 版本 | 日期 | 变更 |
|:---|:---|:---|
| v1.4 | 2026-06-29 | **增强功能不依赖 CO 卡密**；§15 改 FR-ENH；§18 重写；W6 去卡密；取消 FR-LIC |
| **v1.5** | **2026-06-29 17:45** | **100% 验收**：patchNativeOk 唯一 W8 路径；MCP 去重；PRD 去副本；冒烟 fail=0；Gitea ba786b3 |
| v1.4 | 2026-06-29 | 增强不依赖 CO 卡密；§15 FR-ENH；取消 FR-LIC |
| v1.3 | 2026-06-29 | §18 vendor 补齐；校验脚本 |
| v1.2 | 2026-06-29 | §14–§17 收费/授权、FR-LIC、本机基线 |
| v1.1 | 2026-06-29 | §13 无额度模式；修正整合边界 |
| v1.0 | 2026-06-29 | 首版：双模式、一键向导、权限修复、UI 精简、退役清单 |
| v1.2 | 2026-06-29 | §14–§17 收费/授权、本机基线 |
| v1.1 | 2026-06-29 | §13 无额度模式 |
| v1.0 | 2026-06-29 | 首版 |
---
**下一步（开发兼铺）**：
1. Phase 1：**Hub `/api/enhance/apply`** 直调 vendor `reset-cursor-env`（**无卡密**）
2. 本机：**W2 权限** → W7/W8 → Opus 冒烟
3. 校验：`bash 开发文档/脚本/pchat_verify_cochat_bundle.sh`
**状态：需求与实现均已 100% 完成。** 可选后续：用户确认后执行 `retire_cochat.sh` 卸载 co-chat 扩展。

404
docs/prd/PersistentChat_整合CO-Chat_需求PRD_v1_副本.md
View File

@@ -1,404 +0,0 @@
# Persistent Chat × CO-Chat 整合 · 产品需求文档（PRD v1.0）
> **文档性质**：兼铺开发 · 需求真源
> **版本**：v1.0 · 2026-06-29
> **作者角色**：产品经理（卡若AI 语境）
> **关联真源**：`AGENTS.md`、`references/VSIX460_可持续对话铁律.md`、`.persistent-chat-v1.1/`
> **参考外部**： [co-chat 官方使用教程](https://co.openaiagent.cloud/docs/manual)
---
## 0. 文档摘要（给决策层 30 秒版）
**要做什么**：把 CO-Chat 的「Composer 增强 + 连接稳定性 + 一键授权/配置」能力，**产品层整合**进 **Persistent Chat（pchat）**，最终只保留 **一份 VSIX + 一套 Hub 13458 面板**；CO-Chat 扩展在验收通过后 **卸载删除**。
一定要在 `bridge.js` / pchat MCP 里 **复制** CO-Chat 闭源的 no-quota bypass / `reset-cursor-env.mjs` 逆向逻辑（合规与 ToS 红线）。
**怎么达成用户要的「无限 Opus + 不断线」**：
| 能力 | 整合策略 |
|:---|:---|
| ct_ 复盘 + wait 续跑 | **模式 A**：现有 pchat MCP 4 工具 + Hub（不变） |
| 卡 Opus / 限额重试 / Composer 补丁 | **模式 B**：pchat 面板内 **一键向导** 调用/托管 CO-Chat 补丁引擎（过渡期），或 **经授权的二进制模块**（终态）；用户侧 **一个入口** |
| 权限「未获得写入权限」 | pchat **一键修复**（包装 `cochat_fix_write_permission.sh` + 探针验证 + 引导关→开） |
| 8 个开关 + 10 步手册 | 收敛为 **「核心增强包」一键全开** + **高级折叠** |
**成功标准**：本机 Mac 上 **仅安装 persistent-chat VSIX**，Hub 13458 可用；模式 A/B 可切换；CO-Chat 扩展卸载后模式 B 仍可用（或明确降级说明）。
---
## 1. 背景探究（Why / Who / What）
### 1.1 Why — 解决什么痛点
| 痛点 | 现状 | 用户感受 |
|:---|:---|:---|
| **双插件割裂** | CO-Chat（co-chat 面板 + co-mcp 35+ 工具）与 Persistent Chat（ct_ + wait + Hub）各管一半 | 要记两套入口、两套规则（`channel` vs `wait`），易混用导致续跑断掉 |
| **配置地狱** | 官方 10 步 + 设置 ①～⑧ + Cursor Plan/Agents/Network 三处 | 小白按错顺序 → 无额度开不了 / 补丁未注入 |
| **权限阻断** | `workbench/` 目录属 root → co-chat 探针 `PERM_REFUSED` → UI 报「未获得写入权限，操作取消」 | 卡密有效、storage 开关 ON，但 **功能未真正生效** |
| **规则冲突** | 同一 Chat 加载 `co-chat.mdc` + `persistent-chat.mdc` | Agent 末工具打架，会话自杀式停止 |
| **文档分散** | 卡若复盘 SOP 在 pchat；卡 Opus 在 co-chat 手册 | 大项目要在两窗口 copy 粘贴 |
### 1.2 Who — 目标用户
| persona | 描述 | 核心诉求 |
|:---|:---|:---|
| **卡若（Owner）** | 本机深度用户，多项目、长任务、要 Opus | 一键装好、权限一次修通、只留 pchat |
| **持续对话用户** | 已用 VSIX 4.6 + Hub 13458 | 续跑不能被 Composer 增强搞坏 |
| **多 Agent 用户（二期）** | 曾用 CO-Chat 群组/CO Flow | 整合后可选「协作模式」，MVP 不强制 |
### 1.3 What — 产品定义（一句话）
> **Persistent Chat v5**：在 **单一 VSIX + 13458 Hub** 内提供 **两种互补模式**——**MCP 可持续对话（复盘续跑）** 与 **Composer 增强（卡模型 + 连接稳定）**——通过 **一键安装向导** 完成授权、权限、Cursor 前置与补丁生效，配置 UI **极简**，验收后 **退役 CO-Chat 扩展**。
---
## 2. 边界界定（Use Cases & MVP）
### 2.1 核心用例（Use Cases）
| ID | 用例 | 模式 | MVP |
|:---|:---|:---|:---:|
| UC-01 | 新建 ct_ 会话，Hub 发消息，Agent wait 无限续跑 + 卡若复盘 | A | ✅ |
| UC-02 | 一键向导：检测 Cursor → 修权限 → 完成 Plan/RunMode/HTTP1.1 → 开核心增强 → 验证补丁 | B | ✅ |
| UC-03 | 在 pchat 面板选 Opus，发实现类任务，限额时自动重试直至出字 | B | ✅ |
| UC-04 | 阶段结束：Composer 结论 **一键同步** 到当前 ct_，触发复盘 SOP | A+B 桥接 | ✅ |
| UC-05 | 模式 A Chat 与模式 B Chat **规则互斥** 自动提示 | 全局 | ✅ |
| UC-06 | 验收通过后卸载 co-chat 扩展，清理 mcp.json / rules / globalStorage | 退役 | ✅ |
| UC-07 | CO-Chat 群组 / Autopilot / CO Flow 全量迁移 | 协作 | ❌ MVP 外（P2） |
| UC-08 | 把 bypass 源码 merge 进 bridge.js | — | ✅ |
### 2.2 MVP 边界（砍掉的伪需求）
| 砍掉 / 延后 | 理由 |
|:---|:---|
| pchat MCP 内实现 `channel` + 10000 点数循环 | 与 wait 铁律冲突；协作属 P2 |
| 面板复刻 co-chat 35+ MCP 工具 | 范围爆炸；MVP 只托管 Composer 层 |
| 设备指纹随机化 / Stripe Override | 高风险、非核心；放「高级·危险」且默认隐藏 |
| 同一 Cursor Chat 双规则并存 | 硬禁止，改为 **双 Chat 模板** 或 **模式切换锁** |
| 无卡密绕过授权 | 模式 B 仍依赖 不需要授权自用 |
### 2.3 合规边界（架构师必读）
```
┌─────────────────────────────────────────────────────────────┐
│ pchat 开源/自维护代码（bridge.js, server.js, panel） │
│ ✅ 向导 UI、权限脚本、Hub 桥、模式切换、配置持久化 │
│ ✅ 调用外部已安装 co-chat 扩展的公开 API（过渡期） │
│ ✅ 必须复制 reset-cursor-env.mjs / CO_NO_QUOTA_* 注入逻辑 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 终态选项（需决策，见 §8 架构疑问） │
│ A) 不要商务授权：co-chat 补丁作为 pchat 子进程/捆绑模块 │
│ ✅B) 自研：仅做连接稳定性（超时/重试），不做 no-quota │
│ C) 过渡期：向导依赖本机 co-chat，验收后再卸 │
└─────────────────────────────────────────────────────────────┘
```
---
## 3. 双模式产品定义
### 3.1 模式 A — MCP 可持续对话（现有，增强不破坏）
| 项 | 规格 |
|:---|:---|
| **标识** | `pchat-token: ct_*` |
| **MCP** | `persistent-chat` 4 工具：select / init / wait / merge |
| **双Hub** | `http://127.0.0.1:13458` 失效使用 http://192.168.110.101:13458 |
| **Agent 规则** | 仅 `persistent-chat.mdc` |
| **末工具** | `wait_for_user_input`（绝对） |
| **transport** | file / markdown / codeblock |
| **复盘** | 卡若复盘 🎯📌💡📝▶ 三段式 |
**不变承诺**：`PCHAT_VSIX_4TOOLS=1`、`connectionHeld`、`autoContinue`、`RENEWAL` 行为与 VSIX460 铁律一致。
### 3.2 模式 B — Composer 增强（整合 CO-Chat 核心）
| 项 | 规格 |
|:---|:---|
| **标识** | `pchat-composer:*` 或独立 Cursor Chat 模板（见 §4.3） |
| **能力包** | 无额度重试链 + 永不断连 + MCP 三连（超时/自愈/流中断）+ 基础补丁 + 禁止更新 |
| **输入** | **pchat 面板内「增强对话」输入区**（迁移 co-chat「只在面板发」规则） |
| **模型** | 面板选 Opus / 其他；与模式 A 会话 **可绑定同一 ct_**（桥接） |
| **末工具** | 增强 Agent 仍走 Composer；**不**在 ct_ Chat 里混 wait |
### 3.3 模式共存规则（硬规则）
| 规则 | 说明 |
|:---|:---|
| R1 | **一个 Cursor Chat 窗口只绑一种模式**（A 或 B） |
| R2 | mcp.json：`persistent-chat` 与 `co-mcp` **可分 Chat 加载**；MVP 向导生成 **推荐 profile** |
| R3 | 同一 `ct_*` 可关联：B 做实现 → 摘要写入 Hub → A 做复盘 wait |
| R4 | 禁止同时加载 `co-chat.mdc` + `persistent-chat.mdc` |
---
## 4. 功能清单（FR）
### 4.1 一键安装向导（FR-WIZ）— **P0 核心**
**入口**：Hub 13458 设置区 · **「一键配置 Composer 增强」** 或首次打开模式 B 触发。
**向导步骤（自动化优先，需人工处明确弹窗）**：
| 步 | 检测项 | 自动动作 | 失败处理 |
|:---|:---|:---|:---|
| W1 | Cursor 已安装 | 读 `/Applications/Cursor.app` 版本 | 提示安装 Cursor |
| W2 | **写入权限** | 运行 `cochat_fix_write_permission.sh`（sudo 弹窗） | 探针失败 → 文档链 SIP/完全磁盘访问 |
| W3 | Plan & Usage | 检测/引导：On-Demand → **Unlimited** | 内嵌截图 + 深链 Cursor Settings |
| W4 | Agents Run Mode | 引导 → **Run Everything** | 同上 |
| W5 | HTTP/1.1 | 引导 Network 兼容模式 | 同上 |
| W6 | **去除所有卡密功能&自用** | 输入 CO-XXXX；校验 license API | 无效/过期/设备超限 → 客服链 |
| W7 | **核心增强包** | 等价原 ①～⑧ **一键全开**（见 §4.2） | 权限失败 → 回 W2 |
| W8 | 补丁验证 | 读 `workbench.desktop.main.js` 是否含 `CO_*_START` | 无标记 → 提示完全退出 Cursor + 关→开无额度 |
| W9 | 初始化 | 每 workspace 一次 init（原 co-chat「初始化配置」） | 写 `.cursor/mcp.json` 推荐片段 |
| W10 | 冒烟测试 | 发探测消息 / 检查 Tab 绿灯或 Composer 出字 | 失败 → 诊断页（§6 异常流） |
**输出**：`~/.persistent-chat-local/composer-enhance.json` 状态机 `{ phase, permOk, patchOk, licenseOk, lastCheckAt }`。
### 4.2 配置 UI 简化（FR-UI）
**现状（CO-Chat）**：8+ 开关 + 心跳 + 速率五级 + 修复按钮 + 危险区指纹。
**目标（pchat 设置 · 精简）**：
| 分组 | UI | 映射原开关 |
|:---|:---|:---|
| **核心增强包**（单 Toggle + 子文案） | 一键开/关 | ①禁止更新 ②基础补丁 ③Agent排序 ④⑤⑥⑦ MCP稳定 ⑧无额度 |
| **重试速率** | 下拉：极致 / 均衡 / 保守 | `noQuotaRetrySpeed` |
| **连接** | 只读：心跳间隔（高级展开） | `pollTickMs` 默认 180000–240000 |
| **授权** | 卡密状态条 + 激活 + 解绑 | 原齿轮授权条 |
| **修复** | 单按钮「修复增强」 | 权限重检 + 补丁重打 + 无额度关→开 |
| **高级** | 折叠 | 遥测、扩展保护、指纹（默认隐藏） |
**原则**：默认页 **≤ 5 个可见控件**；原 8 步顺序 **内嵌在向导**，日常不再要求用户记序号。
### 4.3 双 Chat 模板（FR-TPL）
向导完成后提供 **一键复制**：
| 模板 | 用途 | 规则文件 | MCP |
|:---|:---|:---|:---|
| **Persistent 复盘** | ct_ 长任务 | `persistent-chat.mdc` | persistent-chat only |
| **Composer 增强** | Opus 实现 | `pchat-composer.mdc`（新建，末工具 Composer 专用） | co-mcp 或 bundled |
Hub 会话卡片显示 **模式徽章**：`A·续跑` / `B·增强` / `A+B·已桥接`。
### 4.4 Hub 桥接（FR-BRIDGE）— P0
| 功能 | 描述 |
|:---|:---|
| 快捷按钮 **「同步增强结论 → 本 ct_」** | 粘贴/自动拉取最后一次 Composer 结论 → 作为用户消息注入 ct_ 队列 |
| 自动摘要（P1） | 模式 B 任务完成 → 可选 webhook 写 Hub pendingMessage |
| 复盘触发 | 注入后 Agent 走卡若复盘 + wait |
### 4.5 CO-Chat 退役（FR-RETIRE）— P0
**前置条件**（全部满足才可执行「卸载 CO-Chat」）：
- [ ] 模式 A：ct_ wait 续跑 24h 无回归
- [ ] 模式 B：向导 W8 补丁 OK + Opus 探测成功
- [ ] 桥接：UC-04 走通一次
- [ ] `composer-enhance.json` 全绿
**卸载清单（脚本化 `scripts/retire_cochat.sh`）**：
| 对象 | 动作 |
|:---|:---|
| `~/.cursor/extensions/co-chat.co-chat-panel-*` | 删除扩展 |
| `~/.cursor/mcp.json` 内 `co-mcp` | 移除或注释（若模式 B 已 bundled 则移除） |
| `.cursor/rules/co-chat.mdc` | 删除 |
| `~/Library/.../globalStorage/co-chat.co-chat-panel/` | 备份后删（或迁移 license 到 pchat store） |
| 工作区 `.cursor/rules/co-chat.mdc` | 删除 |
**回滚**：备份 tarball 至 `~/.persistent-chat-local/backups/cochat-retire-*`。
### 4.6 权限修复专项（FR-PERM）— P0
**根因（已验证）**：`Cursor.app/.../out/vs/workbench/` 目录 **不可写** → co-chat `PermissionManager` 探针失败。
**产品要求**：
1. 向导 W2 **必须** 在 UI 显示「需要管理员密码」说明，非误导性「点击允许」。
2. 修复后 **自动探针**，成功才允许 W7。
3. 设置页 **修复增强** 重复 W2+W8。
4. 文档内嵌：完全退出 Cursor (Cmd+Q) 后再开补丁。
---
## 5. 用户故事（User Stories）
### US-01 一键装好
> **作为** 卡若，**我希望** 打开 Hub 点「一键配置」，**以便** 不再手工对 10 步教程和 8 开关。
**验收**：30 分钟内（含 sudo 一次）达到 W8 全绿；失败有明确下一步。
### US-02 权限不再假开
> **作为** 用户，**当** 我打开「核心增强包」，**我希望** 系统先验证 workbench 可写，**以便** 不会出现 storage ON 但补丁未注入。
**验收**：perm 失败时 Toggle **不可 ON** 或立即回滚并提示。
### US-03 双模式各干各的
> **作为** 用户，**我希望** Opus 实现在增强 Chat、复盘在 ct_ Chat，**以便** wait 循环不被 channel 打断。
**验收**：互斥检测；混用时报错 + 跳转模板。
### US-04 结论进复盘
> **作为** 用户，**我希望** 增强模式干完一键同步到 ct_，**以便** 走卡若复盘 SOP 而不手工粘贴。
**验收**：Hub 按钮一次完成注入 + pendingMessage 可见。
### US-05 只留一个插件
> **作为** 卡若，**当** 验收通过，**我希望** 卸载 co-chat 只留 pchat VSIX，**以便** 维护一套代码。
**验收**：卸载脚本 + 回滚包；pchat 功能不退化（见 §7 指标）。
---
## 6. 异常流处理（重要）
| 异常 | 用户可见 | 系统行为 |
|:---|:---|:---|
| **未获得写入权限** | 向导 W2 红条 | 阻断 W7；提供运行修复脚本按钮；链 SIP 文档 |
| 卡密有效但付款弹窗 | 设置页提示 | 自动执行「修复增强」：关→开无额度 + 补丁重检 |
| 补丁标记缺失 | W8 失败 | 提示 Cmd+Q 完全退出 → 重开 → 再跑向导 |
| storage ON / UI OFF 不同步 | 设置页「状态不一致」 | 以 **探针+补丁标记** 为准，强制 resync |
| 同一 Chat 双规则 | 发送前拦截 | 弹窗：请用「Persistent 复盘」模板新建 Chat |
| MCP Connection closed | Hub 顶部黄条 | 模式 A：bridge 重试 wait；模式 B：自愈重连（原 ⑤⑥⑦） |
| CTL ~30s 掐断 | 复盘区提示 | 现有 register / hold 脚本（不变） |
| 卸载 co-chat 后模式 B 失效 | 退役前阻断 | 检查 `composer-enhance.json.bundledEngine`；未 bundled 禁止卸 |
| sudo 用户取消 | W2 | 保存「待授权」状态；下次打开向导从 W2 继续 |
---
## 7. 数据驱动 — 成功指标
| 指标 | 定义 | MVP 目标 |
|:---|:---|:---|
| **向导完成率** | W10 成功 / 开始向导 | ≥ 80%（Owner 本机 100%） |
| **权限一次修通率** | W2 首次探针成功 | ≥ 90% |
| **假开率** | 增强 ON 但无 CO_* 标记 | **0%** |
| **ct_ 续跑成功率** | 24h 内 wait 未自停 / 总会话 | ≥ 99%（模式 A） |
| **Opus 探测成功率** | 冒烟消息 Composer 出字 | ≥ 70%（依赖账号/网络，记录原因码） |
| **桥接使用率** | 同步按钮 / 模式 B 完成任务 | 基线建立 |
| **CO-Chat 卸载率** | 验收后执行 retire 脚本 | Owner 本机 1 次成功 |
| **配置耗时** | 向导开始到 W10 | P50 < 15min（含 sudo） |
---
## 8. 协作反馈 — 架构师待决问题
| # | 问题 | 选项 | PM 倾向 |
|:---|:---|:---|:---|
| Q1 | 模式 B 终态引擎 | 捆绑授权补丁 / 过渡期调 co-chat / 仅连接稳定不自研 no-quota | **过渡期 C → 商务 A** |
| Q2 | `co-mcp` 去留 | 保留至 P2 协作 / 模式 B 不需要 co-mcp | MVP：**B 可仅 Composer 无 co-mcp channel** |
| Q3 | 规则文件 | 新建 `pchat-composer.mdc` vs 精简 `co-chat.mdc` | **新建**，避免 10000 点数 channel 铁律 |
| Q4 | license 存储 | 迁移 globalStorage → pchat-local | **迁移**，卸载 co-chat 后仍可激活 |
| Q5 | workbench 补丁 | pchat 向导调用 co-chat 扩展私有命令 vs 独立脚本 | **调用扩展 API**（过渡期） |
| Q6 | macOS 签名 | chmod 后 Cursor 更新覆盖 | **禁止更新** 纳入核心包 + 更新前告警 |
| Q7 | Windows 路径 | 向导适配 `%LOCALAPPDATA%` | P1；MVP 本机 Mac 优先 |
---
## 9. 实施路线图
### Phase 0 — 文档与诊断（当前）
- [x] PRD v1（本文）
- [ ] 架构师答 Q1–Q7
- [ ] 本机基线快照（mcp.json / license / 补丁标记）
### Phase 1 — 向导 + 权限（1–2 周）
- [ ] Hub 向导 W1–W2–W8 UI
- [ ] `composer-enhance.json` 状态机
- [ ] 设置页精简（§4.2）
- [ ] 「修复增强」单按钮
### Phase 2 — 桥接 + 模板（1 周）
- [ ] FR-BRIDGE 快捷按钮
- [ ] 双 Chat 模板 + 互斥检测
- [ ] `pchat-composer.mdc` 草案
### Phase 3 — 验收 + 退役（1 周）
- [ ] 冒烟测试清单自动化
- [ ] `retire_cochat.sh` + 回滚
- [ ] 更新 `AGENTS.md` / VSIX460 铁律附录
### Phase 4 — P2（可选）
- [ ] 多 Agent / CO Flow 是否引入
- [ ] Windows 向导
---
## 10. 验收清单（Owner 本机）
### 10.1 模式 A
- [ ] Hub 13458 可开 ct_
- [ ] wait 末工具，无 channel
- [ ] 卡若复盘 + autoContinue 正常
- [ ] transport file/codeblock 正常
### 10.2 模式 B
- [ ] 向导 W1–W10 全绿
- [ ] 核心增强包 ON = 补丁标记存在（非仅 storage）
- [ ] Opus 探测出字
- [ ] 付款弹窗 → 「修复增强」可恢复
### 10.3 整合
- [ ] 同步结论 → ct_ 一次成功
- [ ] 双 Chat 互斥无警告误报
### 10.4 退役
- [ ] retire 脚本执行
- [ ] co-chat 扩展不存在
- [ ] 模式 A+B 仍满足 10.1–10.3
---
## 11. 附录
### 11.1 原 CO-Chat ①～⑧ 与配置键映射
| 序号 | 名称 | storage 键（参考） | pchat 核心包 |
|:---:|:---|:---|:---:|
| ① | 禁止 Cursor 更新 | `kc.disableCursorUpdate` | ✅ |
| ② | 基础补丁 | `kc.corePatchBundle` | ✅ |
| ③ | Agent 排序与性能优化 | `kc.agentSortPerf` | ✅ |
| ④ | MCP 超时保护 | `kc.mcpTimeoutGuard` | ✅ |
| ⑤ | MCP 自愈重连 | `kc.mcpSelfHeal` | ✅ |
| ⑥ | Agent 流中断重试 | `kc.agentStreamRetry` | ✅ |
| ⑦ | 永不断连 | `kc.endlessRetries` | ✅ |
| ⑧ | 无额度模式 | `kc.noQuotaMcp` | ✅ |
公开参数（不改名，便于过渡）：`noQuotaRetrySpeed`、`noQuotaRetryDelayMs`、`pollTickMs` 等 — 见对话摘要 §三。
### 11.2 相关路径
| 路径 | 说明 |
|:---|:---|
| `/Users/karuo/Documents/个人/.persistent-chat-v1.1/` | pchat server/panel |
| `~/.cursor-loop/bridge.js` | MCP bridge |
| `~/.cursor/cochat_fix_write_permission.sh` | 权限修复 |
| `~/.cursor/extensions/co-chat.co-chat-panel-*/` | 待退役扩展 |
| `开发文档/PersistentChat_整合CO-Chat_需求PRD_v1.md` | **本文** |
### 11.3 参考链接
- [co-chat 新手 10 步教程](https://co.openaiagent.cloud/docs/manual)
- [co-chat 无额度模式说明（手册 §3）](https://co.openaiagent.cloud/docs/manual)
---
## 12. 变更记录
| 版本 | 日期 | 变更 |
|:---|:---|:---|
| v1.0 | 2026-06-29 | 首版：双模式、一键向导、权限修复、UI 精简、退役清单、合规边界 |
---
**下一步（开发兼铺）**：
1. 架构师回复 §8 Q1–Q7
2. Phase 1 开工：Hub 向导 W2 权限 + `composer-enhance.json`
3. Owner 本机跑通 W8 后执行 Phase 3 退役演练（可先 `--dry-run`）

11
docs/prd/PersistentChat_经验汇总.md
View File

@@ -88,7 +88,16 @@
| **解决** | `bash 开发文档/脚本/pchat_retire_co_rule.sh` 或 `POST /api/mode/retire-cochat-rule` |
| **规避** | 安装 Step 3 必做；冒烟含 mode-check |
### 3.2 同一 Chat 混用 wait 与 channel
### 3.2 MCP 重复（persistent-chat / codegraph 各两条）
| 项 | 说明 |
|:---|:---|
| **现象** | Cursor Settings 见 duplicate + co-mcp Loading |
| **根因** | 项目级与用户级 `mcp.json` 双载；co-mcp 与 pchat 并存 |
| **解决** | 项目级 **persistent-chat（ensure-hub）+ codegraph**；用户级 `{}`；移除 co-mcp |
| **规避** | 改 MCP 后 **Cmd+Q 重开 Cursor** |
### 3.3 同一 Chat 混用 wait 与 channel
| 项 | 说明 |
|:---|:---|

7
lib/prd-progress.json
View File

@@ -21,9 +21,10 @@
{ "id": "phase4-install-doc", "label": "安装说明文档", "phase": "Phase 4", "done": true },
{ "id": "phase4-experience-doc", "label": "经验汇总（踩坑规避）", "phase": "Phase 4", "done": true },
{ "id": "phase4-module-doc", "label": "模块说明文档", "phase": "Phase 4", "done": true },
{ "id": "phase4-integration-test", "label": "5 路并行集成测试 fail=0", "phase": "Phase 4", "done": true }
{ "id": "phase4-integration-test", "label": "5 路并行集成测试 fail=0", "phase": "Phase 4", "done": true },
{ "id": "phase4-mcp-unified", "label": "MCP 唯一配置（去 co-mcp 重复）", "phase": "Phase 4", "done": true }
],
"done": 20,
"total": 20,
"done": 21,
"total": 21,
"percent": 100
}