persistent-chat-plugin/AGENTS.md

AGENTS.md · Persistent Chat 插件

AI 第一入口：收到「安装 pchat / Persistent Chat / 持久对话」类任务时，先读本文件，再按步骤自主执行，无需用户逐步确认（sudo/W2 除外需用户输密码）。

Gitea：http://192.168.110.101:3000/fnvtk/persistent-chat-plugin
一键安装：bash install.sh [工作区绝对路径]

---

0. AI 必读顺序

顺序	文件	何时读
1	本文件 AGENTS.md	每次安装/排错起手
2	install.sh	执行一键安装
3	docs/prd/PersistentChat_经验汇总.md	某步失败时查现象→解法
4	docs/prd/PersistentChat_模块说明.md	需理解 API/架构时
5	docs/prd/PersistentChat_整合CO-Chat_需求PRD_v1.md	需求边界争议时

禁止：同时加载 co-chat.mdc + persistent-chat.mdc；禁止调用 reset-cursor-env --quit-cursor 强杀 Cursor。

---

1. 产品一句话

Persistent Chat（pchat） = VSIX + Hub :13458 + MCP 4 工具（init/select/wait/merge）。模式 A 无限续跑（wait_for_user_input）；模式 B Composer 增强（无 CO 卡密，patchNativeOk）。

---

2. 自主安装协议（AI 逐步执行）

Step 0 · 克隆（若未克隆）

git clone http://192.168.110.101:3000/fnvtk/persistent-chat-plugin.git
cd persistent-chat-plugin

Step 1 · 一键安装

bash install.sh "/path/to/workspace"

通过标准：脚本末尾 冒烟 fail=0；curl -sf http://127.0.0.1:13458/api/health。

Step 2 · 验证（AI 必须跑）

bash scripts/co-integration/pchat_smoke_test.sh
curl -sf http://127.0.0.1:13458/api/mode/check | python3 -m json.tool   # conflict: false
curl -sf http://127.0.0.1:13458/api/enhance/diagnose | python3 -m json.tool  # gatesPass: true
curl -sf http://127.0.0.1:13458/api/prd/progress | python3 -c "import sys,json; d=json.load(sys.stdin); assert d['percent']==100"

任一项失败 → 跳 §4 排错，修完从 Step 1 重跑 sync 或对应脚本。

Step 3 · 增强向导（gatesPass 为 false 时）

1. 打开 http://127.0.0.1:13458/enhance
2. W2 修权限（需用户 sudo 密码）
3. W6 修 Cursor 前置
4. 打开 核心增强包 Toggle
5. 点 ① 诊断 → W8 应 ✅ 原生OK
6. 再跑 Step 2 验证

Step 4 · 告知用户

安装完成后 必须 提示：Cmd+Q 完全退出 Cursor → 重开（MCP 配置生效）。

Step 5 · VSIX（若用户尚未安装）

VSIX 不在本仓库；需用户手动：Cursor → Install from VSIX → persistent-chat-4.6.0-4tools.vsix。装完后重跑 Step 1。

---

3. 仓库根目录地图

persistent-chat-plugin/
├── AGENTS.md              ← AI 读本文件（你在这里）
├── install.sh             ← 人类/AI 一键安装
├── README.md              ← 人类概览
├── cursor-config/         ← MCP + rules 真源 → deploy-cursor-config.sh
├── src/                   hub.js · server.js（MCP）
├── lib/                   enhance · bridge · smoke · retire
├── web/                   panel.html · panel-enhance.html
├── vendor/                cochat-engine 3.3.34
├── scripts/
│   ├── ensure-hub.sh      MCP 启动器
│   └── co-integration/    冒烟 · sync · retire 脚本
├── mcp-config/            MCP JSON 模板
└── docs/prd/              PRD · 经验 · 模块说明

运行时目录（install 写入）：~/.persistent-chat-local/

---

4. 排错决策树（AI 自主修复）

现象	检测命令	修复动作
Hub 不通	curl :13458/api/health	bash scripts/co-integration/sync_pchat_runtime.sh
冒烟 fail	bash scripts/co-integration/pchat_smoke_test.sh	看失败项；通常 Hub 未起或 lib 未同步
MCP duplicate / Loading	Cursor Settings	确认 ~/.cursor/mcp.json 为 {}；项目级仅 persistent-chat+codegraph；bash cursor-config/deploy-cursor-config.sh "$WS"；Cmd+Q
conflict: true	/api/mode/check	bash scripts/co-integration/pchat_retire_co_rule.sh "$WS"
permOk false	/api/enhance/diagnose	Hub /enhance → W2；或 vendor/cochat-engine/scripts/cochat_fix_write_permission.sh
Toggle 打不开	diagnose	先 W2+W6；读经验汇总 §1.5
W8 待重启	diagnose	点「诊断」→ patchNativeOk；读经验汇总 §1.1
co-chat 扩展仍在	ls ~/.cursor/extensions/co-chat*	bash scripts/co-integration/retire_cochat.sh（需 gatesPass）
patchOk false 但 patchNativeOk true	正常	非阻塞；增强包可用
codegraph Error	路径是否存在	检查 cursor-config/mcp.project.json 内 codegraph 脚本路径；或暂时 disabled

详细根因：docs/prd/PersistentChat_经验汇总.md

---

5. MCP 配置真源（唯一一套）

层级	路径	内容
项目	<workspace>/.cursor/mcp.json	persistent-chat（ensure-hub）+ codegraph
用户	~/.cursor/mcp.json	{} 空（防双载）
规则 A	.cursor/rules/persistent-chat.mdc	wait 续跑
规则 B	.cursor/rules/pchat-composer.mdc	Composer 增强

部署：bash cursor-config/deploy-cursor-config.sh "/path/to/workspace"

MCP 4 工具：init_conversation · select_conversation · wait_for_user_input · merge_conversation

---

6. Hub API 速查

API	用途
GET /api/health	Hub 存活
GET /api/enhance/diagnose	三门禁 + gatesPass
GET /api/enhance/status	composer-enhance.json
POST /api/smoke/run	9 项自动化验收
GET /api/mode/check	规则互斥
GET /api/prd/progress	PRD 100% 进度
GET /enhance	增强向导 UI

---

7. AI 执行铁律

1. 先跑命令再下结论 — 用 §2 Step 2 验证，不要猜状态
2. 失败查经验汇总 — 不要发明新解法
3. 只保留一套 MCP — 禁止 co-mcp + persistent-chat 并存
4. 不强杀 Cursor — W7 排队，用户手动 Cmd+Q
5. W8 以 patchNativeOk 为准 — patchOk 可选
6. 安装完 push 不必 — 除非用户要求改仓库
7. 中文回复用户 — 步骤清晰、带验证结果

---

8. 验收完成标准（100%）

• install.sh 成功 + 冒烟 fail=0
• /api/mode/check → conflict: false
• /api/enhance/diagnose → gatesPass: true
• /api/prd/progress → percent: 100
• 用户已 Cmd+Q 重启 Cursor

全部满足 → 向用户报告「安装完成，可开 ct_ 续跑 + /enhance 增强」。