Skip to content

Commit 07d0db1

Browse files
NanoBoomNanoBoom
committed
docs: feat: Document and implement lockfile watcher with auto-restart
- Introduce a new Chinese protocol documentation file (PROTOCOL_CN.md) detailing the Claude Code IDE extension's internal workings. - Add a task-oriented PRP document for a comprehensive README update (PRPs/completed/comprehensive-readme-update-task.md). - Create a PRP document outlining the implementation of a lockfile watcher with auto-restart functionality (PRPs/completed/lockfile-watcher-task.md). - Document the process of updating the README to reflect the lockfile watcher feature (PRPs/update-readme-lockfile-watcher.md). - Update the README to reflect changes from `vim.loop` to `vim.uv` and rename `terminal_cmd` to `external_terminal_cmd`. - Expand the README's "Key Commands" and "Advanced Configuration" sections, adding details for new commands and configuration options. - Integrate explanations for auto-reconnect and connection management features into the "How It Works" section of the README. - Enhance the Troubleshooting section in the README with solutions related to common connection and mention issues. - Add `lockfile_check_interval` to the configuration defaults and schema validation. - Implement lockfile watcher logic, including start, stop, and restart functions, and integrate them into the plugin's lifecycle. - Add unit tests for the lockfile watcher functionality to ensure it starts, stops, and restarts correctly.
1 parent af41ec3 commit 07d0db1

File tree

8 files changed

+2005
-22
lines changed

8 files changed

+2005
-22
lines changed

‎PROTOCOL_CN.md‎

Lines changed: 578 additions & 0 deletions
Large diffs are not rendered by default.

‎PRPs/completed/comprehensive-readme-update-task.md‎

Lines changed: 520 additions & 0 deletions
Large diffs are not rendered by default.

‎PRPs/completed/lockfile-watcher-task.md‎

Lines changed: 459 additions & 0 deletions
Large diffs are not rendered by default.

‎PRPs/update-readme-lockfile-watcher.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# TASK PRP: Update README - Lockfile Watcher Auto-Reconnect Feature
2+
3+
## Context
4+
5+
### Problem Statement
6+
刚刚实现了lockfile watcher自动重连功能，但README文档没有说明这个特性。用户不知道：
7+
1. 当Claude CLI崩溃或退出时，插件会自动重连
8+
2. 可以配置检查间隔
9+
3. 这个功能是如何工作的
10+
11+
### Solution Overview
12+
在README中添加关于lockfile watcher自动重连功能的文档说明。
13+
14+
### Design Principles Applied
15+
- **KISS**: 简单描述功能和配置，用户能快速理解
16+
- **YAGNI**: 只文档化已实现的功能，不涉及未来计划
17+
- **DRY**: 复用README现有的结构和风格
18+
19+
### Key Files
20+
- `README.md`: 需要更新的主文档
21+
22+
### Implemented Feature Analysis
23+
24+
**功能概述**:
25+
- 插件启动时自动创建定时器，每5秒检查lockfile存在性
26+
- 如果lockfile消失（Claude CLI退出/崩溃），自动调用restart重连
27+
- 防止restart循环的安全机制
28+
29+
**配置项**:
30+
```lua
31+
lockfile_check_interval = 5000 -- 检查间隔(毫秒)，范围1-60秒
32+
```
33+
34+
**实现细节**:
35+
- 使用vim.uv.new_timer()创建定时器
36+
- 在M.start()启动watcher，M.stop()停止watcher
37+
- restart()自动处理watcher生命周期
38+
39+
### Documentation Placement
40+
41+
根据README结构分析，最合适的位置是：
42+
1. **Advanced Configuration** 部分 - 添加`lockfile_check_interval`配置项
43+
2. **How It Works** 部分 - 简要说明自动重连机制
44+
3. 可选：在**Troubleshooting**添加相关说明
45+
46+
### Content Style
47+
48+
从现有README分析文档风格：
49+
- 简洁直接，技术准确
50+
- 使用代码块展示配置
51+
- 关键特性用emoji标记
52+
- 保持一致的Markdown格式
53+
54+
---
55+
56+
## Tasks
57+
58+
### TASK 1: 在Advanced Configuration添加lockfile_check_interval说明
59+
60+
**File**: `README.md`
61+
62+
**Location**: 在`Advanced Configuration`部分，`queue_timeout`后面添加
63+
64+
**Add**:
65+
```markdown
66+
queue_timeout = 5000, -- Maximum time to keep @ mentions in queue (milliseconds)
67+
lockfile_check_interval = 5000, -- Interval to check lockfile existence for auto-reconnect (milliseconds, 1-60 seconds)
68+
```
69+
70+
**Context**:
71+
- 找到`queue_timeout`配置项（约line 20）
72+
- 在其后添加新配置项
73+
- 保持与其他配置项相同的格式和注释风格
74+
75+
**Validation**:
76+
- [ ] 配置项位置正确，在queue_timeout之后
77+
- [ ] 注释说明清晰（interval, auto-reconnect, milliseconds, range）
78+
- [ ] 缩进和格式与周围代码一致
79+
80+
**If Fail**: 检查行号是否正确，确保在正确的代码块内
81+
82+
**Rollback**: 删除添加的行
83+
84+
---
85+
86+
### TASK 2: 在How It Works部分添加自动重连说明
87+
88+
**File**: `README.md`
89+
90+
**Location**: 在`How It Works`部分，现有内容之后添加
91+
92+
**Add**:
93+
```markdown
94+
## How It Works
95+
96+
This plugin creates a WebSocket server that Claude Code CLI connects to, implementing the same protocol as the official VS Code extension. When you launch Claude, it automatically detects Neovim and gains full access to your editor.
97+
98+
The protocol uses a WebSocket-based variant of MCP (Model Context Protocol) that:
99+
100+
1. Creates a WebSocket server on a random port
101+
2. Writes a lock file to `~/.claude/ide/[port].lock` (or `$CLAUDE_CONFIG_DIR/ide/[port].lock` if `CLAUDE_CONFIG_DIR` is set) with connection info
102+
3. Sets environment variables that tell Claude where to connect
103+
4. Implements MCP tools that Claude can call
104+
105+
**Auto-Reconnect**: The plugin monitors the lockfile every 5 seconds (configurable via `lockfile_check_interval`). If Claude CLI exits or crashes and the lockfile is removed, the plugin automatically restarts the connection, ensuring seamless recovery without manual intervention.
106+
107+
📖 **[Read the full reverse-engineering story →](./STORY.md)**
108+
🔧 **[Complete protocol documentation →](./PROTOCOL.md)**
109+
```
110+
111+
**Context**:
112+
- 定位到`## How It Works`部分（约line 211）
113+
- 在现有4点说明之后，链接之前添加新段落
114+
- 使用**粗体**标记"Auto-Reconnect"保持风格一致
115+
116+
**Validation**:
117+
- [ ] 段落位置正确（在4点说明后，链接前）
118+
- [ ] 格式与现有内容一致
119+
- [ ] 技术描述准确（5秒检查，自动restart）
120+
- [ ] Markdown格式正确
121+
122+
**If Fail**: 检查markdown格式，确保段落间有空行
123+
124+
**Rollback**: 删除添加的段落
125+
126+
---
127+
128+
### TASK 3: 在Troubleshooting添加相关条目（可选）
129+
130+
**File**: `README.md`
131+
132+
**Location**: `## Troubleshooting`部分末尾
133+
134+
**Add**:
135+
```markdown
136+
- **Claude disconnects frequently?** The lockfile watcher will automatically reconnect within 5-10 seconds. Check logs with `log_level = "debug"` to see reconnection attempts. Adjust `lockfile_check_interval` if needed (default: 5000ms).
137+
```
138+
139+
**Context**:
140+
- 找到`## Troubleshooting`部分（约line 770）
141+
- 在最后一个问题之后添加
142+
- 保持与其他问题相同的格式（- **问题?** 解决方案）
143+
144+
**Validation**:
145+
- [ ] 格式与其他troubleshooting条目一致
146+
- [ ] 提供actionable的解决建议
147+
- [ ] 语气与现有内容匹配
148+
149+
**If Fail**: 检查markdown列表格式
150+
151+
**Rollback**: 删除添加的条目
152+
153+
---
154+
155+
## Integration Validation
156+
157+
### README Consistency Check
158+
159+
运行以下检查确保文档质量：
160+
161+
```bash
162+
# 检查markdown格式
163+
# 如果有markdownlint
164+
markdownlint README.md
165+
166+
# 检查配置示例语法
167+
grep -A 5 "lockfile_check_interval" README.md
168+
```
169+
170+
### Content Review Checklist
171+
172+
- [ ] 技术描述准确无误
173+
- [ ] 配置示例可复制粘贴使用
174+
- [ ] 文档风格与现有内容一致
175+
- [ ] 无拼写错误
176+
- [ ] Markdown格式正确渲染
177+
178+
---
179+
180+
## Completion Checklist
181+
182+
### Design Principle Compliance
183+
184+
- [x] KISS: 简单清晰的功能描述
185+
- [x] Ockham's Razor: 只添加必要的文档内容
186+
- [x] YAGNI: 只文档化已实现的功能
187+
- [x] DRY: 复用现有文档结构和风格
188+
- [x] SRP: 每个任务只更新一个部分
189+
190+
### Task Completeness
191+
192+
- [x] 所有更新位置已确定
193+
- [x] 文档内容准确描述实现
194+
- [x] 格式与现有文档一致
195+
- [x] 提供实用的配置建议
196+
- [x] 无遗漏的关键信息
197+
198+
### Red Flags Check
199+
200+
- [x] 无不相关的内容添加
201+
- [x] 无未实现功能的文档
202+
- [x] 无过度复杂的说明
203+
- [x] 无格式不一致
204+
205+
---
206+
207+
## Documentation Quality Standards
208+
209+
### Technical Accuracy
210+
211+
- ✅ 默认检查间隔5秒
212+
- ✅ 配置范围1-60秒
213+
- ✅ 自动调用restart()重连
214+
- ✅ 检查~/.claude/ide/{port}.lock
215+
216+
### User Experience
217+
218+
- ✅ 清晰说明功能价值（自动重连，无需手动干预）
219+
- ✅ 提供配置示例
220+
- ✅ 说明如何调试（log_level = "debug"）
221+
222+
### Documentation Style
223+
224+
- ✅ 保持简洁
225+
- ✅ 技术准确
226+
- ✅ 实用性强
227+
- ✅ 格式一致
228+
229+
---
230+
231+
## Success Criteria
232+
233+
- [ ] 用户能理解自动重连功能
234+
- [ ] 用户知道如何配置检查间隔
235+
- [ ] 用户知道如何调试连接问题
236+
- [ ] 文档与代码实现完全一致
237+
- [ ] Markdown格式正确渲染

0 commit comments

Comments
 (0)