name: docs-ops description: “管理Codex CLI文档生命周期。操作：刮取、验证、刷新、重建索引、清除缓存。” argument-hint: <操作> (scrape|validate|refresh|rebuild-index|clear-cache) [选项] allowed-tools: 读取、写入、Bash、Glob、Grep
Codex CLI 文档操作
通过一个统一的技能管理Codex CLI文档生命周期。
参数路由
| 操作 | 描述 |
|---|---|
scrape |
从llms.txt源刮取文档，然后刷新和验证 |
validate |
验证索引完整性并检测漂移（只读） |
refresh |
从文件系统刷新索引，无需刮取 |
rebuild-index |
清除并立即重建搜索索引 |
clear-cache |
清除搜索缓存（下次搜索时懒惰重建） |
解析 $ARGUMENTS 来确定操作。第一个令牌是操作关键字。剩余令牌作为选项传递给操作处理程序。
操作: scrape
从配置的llms.txt源刮取所有文档。
步骤
- 运行刮取脚本:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/core/scrape_docs.py" --parallel
- 刮取完成后，重建索引:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/rebuild_index.py"
- 验证索引:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/manage_index.py" verify
报告每个步骤的结果。
操作: validate
对文档索引运行验证检查，不进行任何修改。
步骤
- 运行索引验证:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/manage_index.py" verify
- 运行完整验证并总结:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/maintenance/validate_index.py"
- 报告文档计数:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/manage_index.py" count
报告每个验证步骤的结果，突出发现的任何问题。
操作: refresh
刷新本地索引，无需从web重新刮取。当您手动修改文档文件或需要重建索引时使用此操作。
步骤
- 从文件系统重建索引:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/rebuild_index.py"
- 验证索引完整性:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/manage_index.py" verify
- 报告文档计数:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/management/manage_index.py" count
报告每个步骤的结果。
操作: rebuild-index
清除并立即重建codex-cli-docs搜索索引。这比clear-cache + 等待下次搜索更快，因为它立即触发重建。
使用时机
- 手动编辑
index.yaml或文档文件后 - 当搜索结果似乎过时或不正确时
- 在
git pull有文档更改后 - 当您需要搜索立即工作时
与clear-cache的区别
| 操作 | 行为 | 搜索可用性 |
|---|---|---|
clear-cache |
仅清除缓存 | 下次搜索时重建（懒惰） |
rebuild-index |
清除 + 重建 | 立即（积极） |
选项
- 无选项: 显示计划并要求确认
- –force: 跳过确认并立即重建
指令
此操作清除Codex CLI文档搜索缓存并立即重建索引。
检查当前状态
首先，检查当前缓存状态。报告缓存是否存在、是否有效以及最后构建时间。
请求确认
除非用户传递了--force，否则显示重建计划与当前缓存状态，并在继续前要求确认。解释重建需要几秒钟，重建期间搜索将不可用。
清除和重建
一旦确认（或如果传递了--force）：
- 使用clear_cache.py脚本清除缓存
- 使用rebuild_index.py重建索引
- 使用manage_index.py verify验证重建成功
报告结果
报告新的索引统计信息，包括文档计数和构建时间。确认搜索现在可用。
## 索引已重建
成功重建Codex CLI文档搜索索引。
**新索引统计:**
- 文档: X
- 构建时间: Xms
**搜索现在可用。**
错误处理
- 插件未安装: 报告"openai-ecosystem插件未找到。"
- 重建失败: 报告脚本错误
- 权限被拒绝: 报告并建议修复步骤
操作: clear-cache
清除codex-cli-docs搜索缓存（倒排索引）。这强制索引在下一次文档搜索时重建。
使用时机
- 手动编辑
index.yaml或文档文件后 - 当搜索结果似乎过时或不正确时
- 在
git pull有文档更改后 - 为释放磁盘空间
选项
- 无选项: 显示将被清除的内容并要求确认
- –force: 跳过确认并立即清除
步骤 1: 解析选项
检查是否出现--force标志。
force_mode = "--force" in arguments (不区分大小写)
步骤 2: 定位缓存目录
codex-cli-docs缓存位于:
${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/.cache/
或通过安装路径:
~/.claude/plugins/cache/<marketplace>/openai-ecosystem/<version>/skills/codex-cli-docs/.cache/
步骤 3: 检查缓存状态
列出缓存文件:
| 文件 | 用途 |
|---|---|
inverted_index.json |
搜索索引 |
cache_version.json |
基于哈希的有效性跟踪 |
如果缓存目录不存在或为空，报告：“缓存已清除。无事可做。”
步骤 4: 确认（除非 --force）
如果不是force_mode，呈现缓存清除计划:
## 缓存清除计划
**目标:** Codex CLI文档搜索索引
| 文件 | 大小 |
|------|------|
| inverted_index.json | X.X MB |
| cache_version.json | 512 字节 |
**总计:** X.X MB
> **注意:** 搜索索引将在下次文档搜索时自动重建。
> 对于立即重建，请在清除后使用`rebuild-index`操作。
**继续?** 回复"yes"继续，或使用`--force`跳过此确认。
步骤 5: 清除缓存
使用clear_cache.py脚本清除:
python "${CLAUDE_PLUGIN_ROOT}/skills/codex-cli-docs/scripts/maintenance/clear_cache.py"
步骤 6: 报告成功
## 缓存已清除
成功清除Codex CLI文档搜索缓存。
**已清除:**
- inverted_index.json
- cache_version.json
**下一步:**
- 搜索索引将在下次搜索时自动重建
- 或使用`rebuild-index`操作立即重建
错误处理
- 缓存未找到: 报告"缓存已清除或插件未安装。"
- 权限被拒绝: 报告"权限被拒绝。尝试以提升权限运行。"
- 插件未安装: 报告"openai-ecosystem插件未找到。"