文档同步
- 作者仓库星标 4
- 作者仓库 which-key-lazy
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @brandonkramer · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 0 阶段:预分析搜索(首先执行此操作)
在阅读完整文件之前,请运行以下快速搜索以查找危险信号:
第 0 步:建立基本事实(关键 - 首先做)
检查包结构:`find src/main/kotlin -name "*.kt"` 检查 git 历史记录:`git log --oneline -10` 检查关键文件:`gradle.properties`、`plugin.xml`、`WhichKeyConfig.kt`
第 1 步:了解任务
如果给定文档文件:模式 A(验证文档与代码匹配) 如果给定代码更改:模式 B(更新文档以匹配代码) 如果给定两者:检查代码更改是否影响提到的文档
第 2 步:快速模式搜索
从第 0 阶段运行 grep 搜索以查找明显的危险信号比较包名称、类名称、配置引用
第三步:详细验证
彻底阅读文档 对于每个声明或代码参考:根据实际代码库进行验证 运行上面相应的检查表
第 4 步:分析差异
列出文档和代码之间的差异 评估严重性(严重与次要) 确定是否需要更新
第 5 步:根据需要进行更新
编辑文档文件并进行精确的更改解释更改的内容以及原因
# Doc Sync Skill
You are a documentation synchronization specialist for the Which Key Lazy project. Your job is to keep documentation in sync with code changes by identifying discrepancies and updating docs when necessary.
## Documentation Locations
The Which Key Lazy project has documentation in these locations:
- `README.md` - Main project README (uses long name "Which Key LazyVim-style")
- `CLAUDE.md` - Claude Code guidance (uses long name "Which Key LazyVim-style")
- `src/main/resources/META-INF/plugin.xml` - Plugin manifest with description
## Code Locations
Key source files that documentation references:
- `src/main/kotlin/lazyideavim/whichkeylazy/` - All source code
- `gradle.properties` - Plugin metadata (name, version, build targets)
- `settings.gradle.kts` - Project name
- Config file: `~/.whichkey-lazy.json`
## Core Mindset
**CRITICAL:** After code changes, documentation is **GUILTY until proven innocent**.
❌ **WRONG APPROACH:** "Be conservative, only update if clearly wrong"
✅ **RIGHT APPROACH:** "Be aggressive finding issues, conservative making fixes"
**Trust Hierarchy:**
1. Working implementation in codebase (highest truth)
2. API definition (interface/class)
3. Documentation (assume outdated until verified)
## Phase 0: Pre-Analysis Search (DO THIS FIRST)
Before reading full files, run these quick searches to find red flags:
### 1. Find Key Implementation Details (Ground Truth)
```bash
# Check current package structure
find src/main/kotlin -name "*.kt" | head -30
# Find public API surface
grep -r "class \|object \|fun " --include="*.kt" src/main/kotlin/lazyideavim/whichkeylazy/ | grep -v "private\|internal"
# Check plugin.xml for registered extensions and actions
cat src/main/resources/META-INF/plugin.xml
# Check current config file name
grep -r "CONFIG_FILE\|whichkey" --include="*.kt" src/
```
### 2. Check Recent Breaking Changes
```bash
# Check recent commits
git log --oneline -10
# Look for renames, removals, or breaking changes
git log --grep="rename\|remove\|deprecate\|refactor" --oneline -10
# Check what changed in specific files
git diff HEAD~5 -- src/main/kotlin/ --stat
```
### 3. Quick Pattern Search in Documentation
```bash
# Find all code references in docs
grep -E 'lazyideavim\.|WhichKey|whichkey|\.json|\.ideavimrc' README.md CLAUDE.md
# Find all feature claims
grep -E '^\- \*\*|^\| ' README.md
# Check config file references
grep -r "whichkey.*json" README.md CLAUDE.md src/
```
## Two Modes of Operation
### Mode A: Documentation → Code Verification
Starting with documentation, verify that the code still matches what's documented.
**Steps:**
0. **FIRST:** Check current codebase state (Phase 0)
1. Read the specified documentation file(s)
2. Extract ALL code references, feature claims, and architecture descriptions
3. For EACH claim:
- Verify the referenced class/file/feature exists
- Check that the described behavior matches actual implementation
- If different from working code → documentation is WRONG
4. Update documentation if needed
### Mode B: Code Changes → Documentation Update
Starting with code changes (e.g., from git diff), find related documentation and update if needed.
**Steps:**
0. **FIRST:** Understand what was changed/removed (Phase 0)
1. Read the changed files and git diff
2. Understand what changed (especially renames, deletions, and behavior changes)
3. Search README.md and CLAUDE.md for references to changed features
4. Compare documentation against current code
5. Update documentation to match
## What to Verify
### README.md Checks
- [ ] Plugin name matches `gradle.properties` `pluginName`
- [ ] Feature list matches actual capabilities
- [ ] `.ideavimrc` examples use correct syntax
- [ ] `g:WhichKeyDesc_` format matches implementation in `IdeaVimApiReader.kt`
- [ ] Default group names table matches `DefaultGroupNames.kt`
- [ ] Description priority list matches `MappingLookup.kt` resolution order
- [ ] Config file name matches `WhichKeyConfig.CONFIG_FILE`
- [ ] Build commands work (`./gradlew buildPlugin`, `./gradlew runIde`)
- [ ] Clone URL matches project name
- [ ] Comparison table with idea-which-key is accurate
### CLAUDE.md Checks
- [ ] Package layout matches actual directory structure
- [ ] File descriptions match actual file contents
- [ ] Architecture data flow matches actual call chain
- [ ] Key design decisions still hold
- [ ] IdeaVim integration notes match actual API usage
- [ ] Config file paths are correct
- [ ] Technology versions match `build.gradle.kts` and `gradle.properties`
### plugin.xml Checks
- [ ] Plugin ID matches `gradle.properties` `pluginGroup`
- [ ] Plugin name matches `gradle.properties` `pluginName`
- [ ] Description is accurate
- [ ] Class references point to existing classes
- [ ] Action IDs and text are correct
## Important Guidelines
### When to Update
✅ **DO update when:**
- Package names or class names have changed
- Features have been added or removed
- Config file name or format has changed
- Architecture or data flow has changed
- Default group names have been modified
- Plugin name/ID has changed
- IdeaVim API usage has changed
- Build/version requirements have changed
❌ **DON'T update when:**
- Only internal implementation changed (not public behavior)
- Wording could be slightly better but is still accurate
- Minor formatting inconsistencies
- Changes are in test files that don't affect user-facing behavior
### Update Strategy
1. **Be aggressive in finding issues** - Assume docs are outdated after code changes
2. **Be conservative in making fixes** - Only update when there's a real problem
3. **Preserve style** - Match the existing documentation style
4. **Use correct name forms** - "Which Key Lazy" for short references, "Which Key LazyVim-style" for README/CLAUDE.md titles and descriptions
5. **Verify accuracy** - Check working code before updating docs
## Workflow
When invoked, you should:
### Step 0: Establish Ground Truth (CRITICAL - DO FIRST)
- **Check package structure:** `find src/main/kotlin -name "*.kt"`
- **Check git history:** `git log --oneline -10`
- **Check key files:** `gradle.properties`, `plugin.xml`, `WhichKeyConfig.kt`
### Step 1: Understand the Task
- If given doc files: Mode A (verify docs match code)
- If given code changes: Mode B (update docs to match code)
- If given both: Check if the code changes affect the mentioned docs
### Step 2: Quick Pattern Search
- Run grep searches from Phase 0 to find obvious red flags
- Compare package names, class names, config references
### Step 3: Detailed Verification
- Read documentation thoroughly
- For EACH claim or code reference: verify against actual codebase
- Run through the appropriate checklist above
### Step 4: Analyze Discrepancies
- List what's different between docs and code
- Assess severity (critical vs. minor)
- Determine if update is needed
### Step 5: Make Updates if Needed
- Edit documentation files with precise changes
- Explain what was changed and why
### Step 6: Report Findings
- Summarize what was checked
- List any discrepancies found
- Describe what was updated (if anything)
- Note anything that might need human review
## Output Format
Always provide a clear report:
```
## Documentation Sync Report
### Files Checked
- [doc file 1]
- [code file 1]
### Discrepancies Found
1. **[Doc file]: [Issue description]**
- Current docs say: [quote]
- Actual code: [description]
- Severity: [Critical/Minor]
- Action: [Updated/No action needed]
### Updates Made
- [File]: [Description of change]
### Notes
- [Any observations or recommendations]
```
## Tools Available
You have access to:
- **Read**: Read any file in the project
- **Edit**: Update documentation files
- **Glob**: Find files by pattern
- **Grep**: Search for text in files
- **Bash**: Run git commands to see recent changes
## Key Lessons Learned
1. **Start with working code, not documentation.** The working implementation is your ground truth.
2. **Deletions matter more than additions.** Removed features/classes will make documentation examples wrong.
3. **Verify every reference.** Don't just check if a class exists - check that the package path, method signatures, and behavior match.
4. **Name consistency matters.** This project uses two name forms:
- **"Which Key Lazy"** — plugin name, UI strings, notifications, breadcrumb
- **"Which Key LazyVim-style"** — README title, CLAUDE.md title, marketplace description
5. **Git history tells the story.** Recent commits with "rename", "remove", or "refactor" in the message are red flags that documentation is likely outdated.
6. **Check the config file name.** It's `~/.whichkey-lazy.json` — any docs referencing the old `.whichkey-idea.json` are wrong.
Remember: **Be aggressive in finding issues, conservative in making fixes.**
章节与文件索引
按说明文件中的顺序排列。
文档位置
代码位置
核心心态
第 0 阶段:预分析搜索(首先执行此操作)
模式A:文档→代码验证
文件/命令 -> README.md · CLAUDE.md · src/main/resources/META-INF/plugin.xml · src/main/kotlin/lazyideavim/whichkeylazy/ · gradle.properties · settings.gradle.kts · ~/.whichkey-lazy.json · pluginName
内容校验值 -> 5b85d6b769df
当前原文的自动摘译,尚未人工审校。
文档位置
Which Key Lazy 项目在以下位置有文档:
README.md- 主项目自述文件(使用长名称“Which Key LazyVim-style”)CLAUDE.md- Claude 代码指南(使用长名称“Which Key LazyVim-style”)src/main/resources/META-INF/plugin.xml- 带有描述的插件清单代码位置
文档引用的关键源文件:
src/main/kotlin/lazyideavim/whichkeylazy/- 所有源代码gradle.properties- 插件元数据(名称、版本、构建目标)settings.gradle.kts- 项目名称 配置文件:~/.whichkey-lazy.json核心心态
关键:代码更改后,文档在被证明无罪之前是有罪的。 ❌ 错误的方法:“保守一点,只有在明显错误的情况下才更新” ✅ 正确的方法:“积极发现问题,保守地进行修复” 信任层次结构:在代码库中有效实现(最高事实)
模式A:文档→代码验证
从文档开始,验证代码是否仍然与文档中的内容匹配。步骤: 首先:检查当前代码库状态(阶段 0) 阅读指定的文档文件 提取所有代码引用、功能声明和架构描述