ec540f6625
AI 先读 AGENTS.md 自主完成安装/排错；install.sh 同步 Hub、部署 MCP、冒烟验收。 修复 sync_pchat_runtime 使用本仓库 lib/src/web 结构。 Co-authored-by: Cursor <cursoragent@cursor.com>
169 lines
6.5 KiB
Markdown
169 lines
6.5 KiB
Markdown
# 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 增强」。
|