# 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 · 克隆（若未克隆）

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

### Step 1 · 一键安装

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

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

### Step 2 · 验证（AI 必须跑）

```bash
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 增强」。