⚡

OpenAICodexCLI文档管理技能Skill codex-cli-docs

这个技能提供自动化工具，用于管理OpenAI Codex CLI的文档，包括文档抓取、存储、索引、搜索和解析。支持关键词搜索、自然语言查询、文档ID解析，提高文档访问效率，防止链接失效，优化令牌成本，自动化维护。关键词：OpenAI Codex CLI, 文档管理, 自动化, 抓取, 索引, 搜索。

DevOps 0 次安装 0 次浏览 更新于 3/11/2026

name: codex-cli-docs description: 所有OpenAI Codex CLI文档的单一真相来源和图书馆员。管理本地文档存储、抓取、发现和解析。适用于查找、定位、搜索或解析Codex CLI文档；通过关键词、类别、标签或自然语言查询发现文档；从llms.txt抓取；管理索引元数据（关键词、标签、别名）；或从文件系统重建索引。运行脚本来抓取、查找和解析文档。处理文档ID解析、关键词搜索、自然语言查询、类别/标签过滤、别名解析、llms.txt解析、用于内部使用的Markdown子章节提取、基于哈希的漂移检测和全面的索引维护。 allowed-tools: Read, Glob, Grep, Bash

OpenAI Codex CLI 文档技能

关键：路径加倍预防 - 强制

绝对禁止：在此技能中运行脚本时，绝不要在PowerShell中使用 cd 与 &&。

问题： 如果当前工作目录已在技能目录内，使用相对路径会导致PowerShell解析路径相对于当前目录而不是仓库根目录，从而导致路径加倍。

必需解决方案（选择一种）：

  1. 始终使用绝对路径（推荐）
  2. 使用单独命令（绝不用 cd 与 &&）
  3. 从仓库根目录运行并使用相对路径

绝不要这样做：

  • 链式使用 cd 与 &&：cd <相对路径> && python <脚本> 导致路径加倍
  • 假设当前目录
  • 当当前目录在技能目录内时使用相对路径

关键：大文件处理 - 强制脚本使用

绝对禁止：绝不要对 index.yaml 文件使用 read_file 工具

该文件超出上下文限制并会导致问题。必须使用脚本。

必需：始终使用 manage_index.py 脚本来访问 index.yaml：

python scripts/management/manage_index.py count
python scripts/management/manage_index.py list
python scripts/management/manage_index.py get <doc_id>
python scripts/management/manage_index.py verify

所有脚本通过 index_manager.py 自动处理大文件。

可用斜杠命令

使用统一的 docs-ops 技能处理常见工作流：

  • /openai-ecosystem:docs-ops scrape - 从 llms.txt 源抓取 Codex CLI 文档
  • /openai-ecosystem:docs-ops refresh - 刷新本地索引和元数据，无需抓取
  • /openai-ecosystem:docs-ops validate - 验证索引和引用的一致性
  • /openai-ecosystem:docs-ops rebuild-index - 强制重建搜索索引
  • /openai-ecosystem:docs-ops clear-cache - 清除文档搜索缓存

概述

此技能为 OpenAI Codex CLI 文档管理提供自动化工具。它管理：

  • 规范存储（封装在技能中）- 官方文档的单一真相来源
  • 子章节提取 - 令牌优化的提取（节省60-90%费用）
  • 漂移检测 - 基于哈希的验证，与上游源比较
  • 同步工作流 - 维护自动化
  • 文档发现 - 基于关键词的搜索和文档ID解析
  • 索引管理 - 元数据、关键词、标签、别名的弹性引用

核心价值： 防止链接失效，启用离线访问，优化令牌成本，自动化维护，并提供弹性的基于文档ID的引用。

何时使用此技能

此技能应在以下情况使用：

  • 抓取文档 - 从 OpenAI Codex CLI 源获取文档
  • 查找文档 - 通过关键词、类别或自然语言搜索文档
  • 解析文档引用 - 将文档ID转换为文件路径
  • 管理索引元数据 - 添加关键词、标签、别名，更新元数据
  • 重建索引 - 从文件系统重新生成索引（处理重命名/移动）

工作流执行模式

关键：本节定义如何在此技能中执行操作。

委托策略

默认方法：委托给任务代理

对于所有抓取、验证和索引操作，将执行委托给通用任务代理。

如何调用：

使用任务工具，参数为：

  • subagent_type: “general-purpose”
  • description: 短3-5词描述
  • prompt: 包含执行说明的完整任务描述

执行模式

脚本默认在前台运行。不要后台运行它们。

当任务代理执行脚本时：

  • 直接运行：python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/scrape_docs.py
  • 流式日志：脚本通过标准输出自然发出进度
  • 等待完成：脚本完成后退出并返回退出代码
  • 绝不要使用 run_in_background=true：脚本设计为前台执行
  • 绝不要轮询输出：流式日志自动出现，无需BashOutput轮询
  • 绝不要使用后台作业：无 &，无 nohup，无后台进程管理

错误和警告报告

关键：报告所有错误、警告和问题 - 绝不要压制或忽略它们。

通过任务代理执行脚本时：

  • 报告脚本错误：退出代码、异常、错误消息
  • 报告警告：弃用警告、导入问题、配置问题
  • 报告意外输出：404错误、超时、验证失败
  • 包含上下文：错误发生时正在执行什么

快速开始

端到端刷新索引（无抓取）

当您想重建和验证本地索引/元数据 无需抓取 时使用：

python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/management/refresh_index.py

抓取所有文档

当用户明确想要 访问网络并抓取文档 时使用：

# 从配置的 llms.txt 源抓取
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/scrape_docs.py

# 抓取后刷新索引
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/management/refresh_index.py

查找文档

# 解析文档ID到文件路径
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/find_docs.py resolve <doc_id>

# 通过关键词搜索（默认：25个结果）
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/find_docs.py search sandbox tools

# 自然语言搜索
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/find_docs.py query "如何配置沙箱"

# 按类别列出
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/find_docs.py category guides

# 按标签列出
python plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/find_docs.py tag cli

搜索选项：

选项 默认 描述
--limit N 25 返回的最大结果数
--no-limit - 返回所有匹配结果（无限制）
--min-score N - 仅返回相关性分数 >= N 的结果
--fast - 仅索引搜索（跳过内容grep）
--json - 以JSON格式输出结果
--verbose - 显示相关性分数

配置系统

codex-cli-docs 技能使用统一配置系统。

配置文件：

  • config/defaults.yaml - 包含所有默认值的中央配置文件
  • config/filtering.yaml - 内容过滤规则
  • config/tag_detection.yaml - 标签检测模式
  • references/sources.json - 文档源配置

环境变量覆盖：

所有配置值都可以使用环境变量覆盖：CODEX_DOCS_<SECTION>_<KEY>

依赖项

必需： pyyaml, requests, beautifulsoup4, markdownify, filelock 可选（推荐）： yake（用于关键词提取）

Python 版本： 推荐 Python 3.11+

核心能力

1. 抓取文档

使用 llms.txt 格式从配置源获取文档。

2. 提取子章节

提取特定 Markdown 章节以优化令牌响应。

3. 变更检测

通过404检查和哈希比较检测文档漂移。

4. 查找和解析文档

使用文档ID、关键词或自然语言查询发现和解析文档引用。

5. 索引管理和维护

维护索引元数据、关键词、标签，并从文件系统重建索引。

平台特定要求

Windows 用户

必须使用 PowerShell（推荐）或在 Git Bash 命令前添加 MSYS_NO_PATHCONV=1

Windows上的Git Bash将Unix路径转换为Windows路径，破坏过滤模式。

示例：

MSYS_NO_PATHCONV=1 python scripts/core/scrape_docs.py --filter "/docs/"

故障排除

Unicode 编码错误

状态： 已修复 - 脚本自动检测Windows并配置UTF-8编码。

抓取期间404错误

状态： 预期 - 某些 llms.txt 条目可能引用尚未存在的文档。脚本优雅处理并继续。

公共 API

codex-cli-docs 技能为外部工具提供干净的公共API：

from codex_docs_api import (
    find_document,
    resolve_doc_id,
    get_docs_by_tag,
    get_docs_by_category,
    search_by_keywords,
    get_document_section,
    detect_drift,
    refresh_index
)

# 自然语言搜索
docs = find_document("沙箱配置")

# 解析文档ID到元数据
doc = resolve_doc_id("codex-cli-docs-getting-started")

# 按标签获取文档
cli_docs = get_docs_by_tag("cli")

# 提取特定章节
section = get_document_section("codex-cli-overview", "安装")

开发模式

在本地开发此插件时，您可能希望更改进入您的开发仓库而不是已安装插件位置。

启用开发模式

PowerShell：

$env:CODEX_DOCS_DEV_ROOT = "D:\repos\gh\melodic\claude-code-plugins"

Bash/Zsh：

export CODEX_DOCS_DEV_ROOT="/path/to/claude-code-plugins"

验证模式

当您运行任何主要脚本（抓取、刷新、重建）时，将显示模式横幅：

开发模式：

[开发模式] 使用本地插件：D:\repos\gh\melodic\claude-code-plugins

生产模式：

[生产模式] 使用已安装技能目录

禁用开发模式

PowerShell：

Remove-Item Env:CODEX_DOCS_DEV_ROOT

Bash/Zsh：

unset CODEX_DOCS_DEV_ROOT

目录结构

codex-cli-docs/
  SKILL.md                    # 此文件（公开）
  codex_docs_api.py           # 公共API
  canonical/                  # 文档存储（私有）
    index.yaml                # 元数据索引
  scripts/                    # 实现（私有）
    core/                     # 抓取、发现
    management/               # 索引管理
    maintenance/              # 清理、漂移检测
    utils/                    # 共享实用工具
  config/                     # 配置
    defaults.yaml             # 默认设置
    filtering.yaml            # 内容过滤
    tag_detection.yaml        # 标签模式
  references/                 # 技术文档（公开）
    sources.json              # 文档源
  .cache/                     # 缓存存储（倒排索引）
  logs/                       # 日志文件

来源

文档从 OpenAI Codex CLI llms.txt 源抓取（在 sources.json 中配置）。

测试场景

场景1：关键词搜索

查询： “搜索沙箱文档” 预期行为：

  • 技能在关键词“文档”上激活
  • 从索引返回相关文档 成功标准： 用户收到匹配的文档条目

场景2：自然语言查询

查询： “如何配置 Codex CLI 沙箱？” 预期行为：

  • 技能在“Codex CLI”上激活
  • 使用 find_docs.py 查询命令 成功标准： 返回包含配置步骤的相关文档

场景3：文档ID解析

查询： “解析 codex-cli-getting-started” 预期行为：

  • 解析文档ID到文件路径
  • 返回文档元数据 成功标准： 用户收到完整路径和文档内容

版本历史

  • v1.0.0 (2025-12-15): 初始版本 - 完整技能结构从 gemini-cli-docs 适配而来

最后更新

日期： 2025-12-15 模型： claude-opus-4-5-20251101

状态： 初始版本 - 等待 llms.txt 源配置以进行抓取。