名称: 批量抓取描述: 在开发模式下使用本地插件代码为一个或多个生态系统运行抓取工作流允许的工具: 读取, Bash, 技能参数提示: “[生态系统] (claude|cursor|duende|google|openai|all)”

批量抓取

使用本地插件代码（开发模式）为一个或多个生态系统运行文档抓取工作流。

参数

解析 $ARGUMENTS 以确定模式和生态系统：

单个生态系统：claude, cursor, duende, google, openai
多个生态系统：空格分隔的列表（例如，claude google）
所有生态系统：all 或无参数
模式前缀：可选前缀为 sequential（默认）或 headless

示例：

/batch-scrape claude – 仅抓取 claude 生态系统
/batch-scrape cursor duende – 顺序抓取 cursor + duende
/batch-scrape all – 顺序，所有生态系统
/batch-scrape headless – 无头模式，所有生态系统
/batch-scrape headless claude google – 无头模式，仅 claude + google

生态系统路由表

生态系统	开发环境变量	插件路径	文档技能
`claude`	`OFFICIAL_DOCS_DEV_ROOT`	`plugins/claude-ecosystem/skills/docs-management/`	`claude-ecosystem:docs-ops scrape`
`cursor`	`CURSOR_DOCS_DEV_ROOT`	`plugins/cursor-ecosystem/skills/cursor-docs/`	`cursor-ecosystem:docs-ops scrape`
`duende`	`DUENDE_DOCS_DEV_ROOT`	`plugins/duende-ecosystem/skills/duende-docs/`	`duende-ecosystem:docs-ops scrape`
`google`	`GEMINI_DOCS_DEV_ROOT`	`plugins/google-ecosystem/skills/gemini-cli-docs/`	`google-ecosystem:docs-ops scrape`
`openai`	`CODEX_DOCS_DEV_ROOT`	`plugins/openai-ecosystem/skills/codex-cli-docs/`	`openai-ecosystem:docs-ops scrape`

开发模式环境变量

关键： 环境变量在会话中设置不会在 Claude 的 Bash 工具调用间持久化。每个 Bash 命令在新的 shell 中运行。必须在运行脚本的同一个命令中设置环境变量。

重要： Claude 的 Bash 工具在 Windows 上使用 Git Bash (MINGW64)，而不是 PowerShell。在 Claude Code 中执行的所有命令使用 Bash 内联前缀语法。

Bash 语法（在 Claude Code 中使用）：

<ENV_VAR>="<repo-root>/<plugin-path>" python <script-path>

PowerShell 语法（仅用于本地 PowerShell 终端）：

$env:<ENV_VAR> = "<repo-root>/<plugin-path>"; python <script-path>

这覆盖了已安装的插件路径，将所有操作重定向到本地开发副本。

模式 1: 顺序（默认）

在单个会话中按顺序运行每个生态系统的抓取工作流。在每个生态系统间使用 /compact 来管理上下文窗口大小。

顺序工作流

对于选中的列表中的每个生态系统：

运行生态系统的抓取工作流（见下文生态系统特定部分）-- 包括所有步骤，包括审计/修复/提交
运行 /compact 以在下一个生态系统前回收上下文

注意事项

每个抓取工作流包括其自己的审计/修复/提交步骤 – 在继续前完成它
如果上下文在完成所有生态系统前变得太大，停止并在新会话中恢复
在所有运行后检查 git log --oneline -10 以验证提交

模式 2: 无头模式

在单独的无头 Claude 会话中运行每个生态系统。这些可以在终端窗口中并行运行。

无头工作流

对于选中的列表中的每个生态系统，输出对应的 claude -p 命令：

claude -p "运行 /batch-scrape <ecosystem> 包括所有步骤，包括审计/修复/提交。" \
  --allowedTools "Read,Edit,Write,Bash,Skill,Glob,Grep"

然后指示用户在单独的终端窗口中运行它们。

注意事项

每个 claude -p 调用获得其自己的上下文窗口 – 无交叉污染
在单独的终端窗口中运行以并行执行
运行完成后检查所有提交：git log --oneline -20
使用 --resume 继续中断的会话
无头模式根据抓取工作流指令自动提交 – 在推送前检查差异

生态系统: claude

使用本地插件代码在 plugins/claude-ecosystem/skills/docs-management/ 抓取 Claude Code / Anthropic 文档。

步骤 1: 运行抓取

OFFICIAL_DOCS_DEV_ROOT="<repo-root>/plugins/claude-ecosystem/skills/docs-management" python <repo-root>/plugins/claude-ecosystem/skills/docs-management/scripts/core/scrape_all_sources.py --parallel --skip-existing

停止并验证： 检查输出前几行的 [DEV MODE]。如果看到 [PROD MODE]，环境变量设置不正确。不要继续 – 先排除环境变量问题。

步骤 2: 使用 Python 3.13 运行验证

OFFICIAL_DOCS_DEV_ROOT="<repo-root>/plugins/claude-ecosystem/skills/docs-management" py -3.13 <repo-root>/plugins/claude-ecosystem/skills/docs-management/scripts/management/refresh_index.py

停止并验证： 检查输出中的 [DEV MODE]。如果出现 [PROD MODE]，停止并排除问题。

步骤 3: 运行基于年龄的清理

清理基于 published_at 日期过期的 Anthropic 文章。阈值从 references/sources.json 中的 max_age_days 自动读取。

OFFICIAL_DOCS_DEV_ROOT="<repo-root>/plugins/claude-ecosystem/skills/docs-management" python <repo-root>/plugins/claude-ecosystem/skills/docs-management/scripts/maintenance/cleanup_old_anthropic_docs.py --execute

停止并验证： 检查输出中的 [DEV MODE]。查看清理摘要 – 应该报告“未找到旧文档”或列出具体删除的文件。

注意： --execute 标志是必需的以实际删除文件（默认为干运行）。年龄阈值自动从 sources.json 读取。

步骤 4: Git 状态检查

运行 git status 查看本地仓库中的文件更改。

重要： 仅分析和报告 plugins/claude-ecosystem/ 内的更改。忽略其他插件中的更改 – 这些来自单独的抓取运行。

步骤 5: 内容差异分析

分析抓取的内容更改以检测来自外部源更改的潜在问题：

# 检查抓取文档中的显著内容更改
git diff --stat plugins/claude-ecosystem/skills/docs-management/canonical/

# 查看具体更改以检测潜在问题：
# - 上游更改导致的格式损坏
# - 缺失部分或内容
# - 可能需要元数据更新的新内容
# - 编码问题或意外字符
git diff plugins/claude-ecosystem/skills/docs-management/canonical/ | head -200

需要寻找的内容：

大规模删除：可能表示上游页面重组或移除
格式更改：损坏的 markdown、缺失的标题、格式错误的链接
编码问题：意外字符、乱码或编码伪影
元数据漂移：可能需要 index.yaml 更新的更改
脚本调整需求：表明抓取逻辑需要更新的模式

如果发现问题，调查源 URL 并确定是否需要调整 sources.json 或抓取脚本。

步骤 6: 过滤效果分析

查看 git diff 后，执行结构分析以检测潜在的过滤间隙。此分析应是未来可靠的（不依赖于脆弱的文本模式）。

分析步骤：

源类型关联：按源路径前缀分组修改的文件：
- anthropic-com/research/ - 研究文章
- anthropic-com/news/ - 新闻文章
- anthropic-com/engineering/ - 工程博客
- code-claude-com/ - Claude Code 文档
- docs-claude-com/ - API 文档
红旗： 如果来自同一源的 5+ 个文件都更改了，这可能表示该源的过滤配置存在结构性问题（不是真正的内容更新）。
更改位置分析：对于源组中的每个修改文件：
- 检查更改是否仅在文件的后 20%（可能是页脚/相关部分）
- 检查差异是否仅显示 frontmatter（content_hash）更改，且内容行更改 <10
红旗： 多个文件更改集中在末尾 = 可能是“相关内容”或页脚部分未被过滤。
与抓取器日志交叉引用：在抓取期间，ContentFilter 记录消息如：
```
从 URL 过滤 N 个部分：原因=[...], 标题=[...]
```
红旗： 如果文件显示为 git 修改，但抓取器日志显示该源类型的 sections_removed: 0 = 该源的过滤配置可能缺失。

潜在改进输出：

如果检测到问题，包括一个“潜在改进”部分，提供可操作的建议：

“考虑将 news_blog_stop_sections 添加到源 X 的 content_filtering.yaml”
“过滤器可能未触发匹配模式 Y 的文件 - 检查 source_filters 映射”
“源 Z 有 N 个文件仅有页脚更改 - 检查过滤规则”

参考： 过滤配置在 plugins/claude-ecosystem/skills/docs-management/config/content_filtering.yaml

步骤 7: 最终报告

总结：

抓取结果（抓取的文档、跳过的、错误）
验证结果（索引完整性、元数据覆盖）
基于年龄的清理结果（移除的文件，如果有）
内容差异分析发现（检测到的任何问题）
过滤效果分析（识别的任何潜在改进）
准备提交的文件（仅 plugins/claude-ecosystem/ 更改）

步骤 8: 审计、修复和提交

最终报告后，如果有更改的文件准备提交：

内联审计：检查所有修改的规范文件：
- 编码问题（乱码、智能引号、非 UTF-8 字符）
- 损坏的链接或格式错误的 markdown
- 空/存根文件，无有意义内容
- Frontmatter 不一致
修复发现的问题：直接应用修复 – 不要将发现写入单独的文件

Lint markdown：在修改的文件上运行 markdownlint：

npx markdownlint-cli2 --fix "plugins/claude-ecosystem/skills/docs-management/canonical/**/*.md"

提交：使用 melodic-software:git-commit 技能。建议格式：
- feat(claude-ecosystem): 重新抓取文档，包含[更改摘要]
- fix(claude-ecosystem): 修复抓取文档中的编码/格式问题
停止并确认：在执行前向用户展示提交计划

生态系统: cursor

使用本地插件代码在 plugins/cursor-ecosystem/skills/cursor-docs/ 抓取 Cursor 文档。

步骤 1: 运行抓取

CURSOR_DOCS_DEV_ROOT="<repo-root>/plugins/cursor-ecosystem/skills/cursor-docs" python <repo-root>/plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/scrape_docs.py --llms-txt "https://cursor.com/llms.txt" --skip-existing

停止并验证： 检查输出前几行的 [DEV MODE]。如果看到 [PROD MODE]，环境变量设置不正确。不要继续 – 先排除环境变量问题。

步骤 2: 运行索引刷新（重建 + 提取元数据）

运行完整的索引刷新管道，重建索引并提取关键词/元数据：

CURSOR_DOCS_DEV_ROOT="<repo-root>/plugins/cursor-ecosystem/skills/cursor-docs" python <repo-root>/plugins/cursor-ecosystem/skills/cursor-docs/scripts/management/refresh_index.py

停止并验证： 检查输出中的 [DEV MODE]。如果出现 [PROD MODE]，停止并排除问题。

重要： 使用 refresh_index.py（不是 rebuild_index.py）。刷新脚本运行完整管道：

从文件系统重建索引
提取所有文档的关键词和元数据
生成摘要报告

仅使用 rebuild_index.py 将从索引中剥离元数据（关键词、子部分、标签、描述）。

步骤 3: 运行验证

验证索引完整性：

CURSOR_DOCS_DEV_ROOT="<repo-root>/plugins/cursor-ecosystem/skills/cursor-docs" python <repo-root>/plugins/cursor-ecosystem/skills/cursor-docs/scripts/maintenance/validate_index.py

步骤 4: Git 状态检查

运行 git status 查看本地仓库中的文件更改。

重要： 仅分析和报告 plugins/cursor-ecosystem/ 内的更改。忽略其他插件中的更改 – 这些来自单独的抓取运行。

步骤 5: 内容差异分析

分析抓取的内容更改以检测来自外部源更改的潜在问题：

# 检查抓取文档中的显著内容更改
git diff --stat plugins/cursor-ecosystem/skills/cursor-docs/canonical/

# 查看具体更改以检测潜在问题
git diff plugins/cursor-ecosystem/skills/cursor-docs/canonical/ | head -200

需要寻找的内容：

大规模删除：可能表示上游页面重组或移除
格式更改：损坏的 markdown、缺失的标题、格式错误的链接
编码问题：意外字符、乱码或编码伪影
元数据漂移：可能需要 index.yaml 更新的更改
脚本调整需求：表明抓取逻辑需要更新的模式

如果发现问题，调查源 URL 并确定是否需要调整 sources.json 或抓取脚本。

步骤 6: 标签分布分析

抓取后，验证标签分布合理。Cursor 文档使用标签（不是类别）：

# 按标签计数文档
CURSOR_DOCS_DEV_ROOT="<repo-root>/plugins/cursor-ecosystem/skills/cursor-docs" python -c "
import yaml
with open('<repo-root>/plugins/cursor-ecosystem/skills/cursor-docs/canonical/index.yaml', 'r', encoding='utf-8') as f:
    index = yaml.safe_load(f)
tags_count = {}
for doc_id, meta in index.items():
    tags = meta.get('tags', [])
    for tag in tags:
        tags_count[tag] = tags_count.get(tag, 0) + 1
for tag, count in sorted(tags_count.items(), key=lambda x: -x[1]):
    print(f'{tag}: {count}')
"

预期标签：

标签	预期范围
cursor	100-110（所有文档）
agent	15-25
cli	15-25
configuration	10-20
inline-edit	10-15
examples	8-15
enterprise	5-15
context	5-10
reference	4-10
mcp	3-8

红旗：

总计数与约 100-110 个文档显著不同
任何文档缺少 cursor 标签（所有文档应有）
标签有 0 个文档，但之前有内容

步骤 7: 最终报告

总结：

抓取结果（抓取的文档、跳过的、错误）
验证结果（索引完整性、元数据覆盖）
内容差异分析发现（检测到的任何问题）
标签分布（任何异常）
准备提交的文件（仅 plugins/cursor-ecosystem/ 更改）

步骤 8: 审计、修复和提交

最终报告后，如果有更改的文件准备提交：

内联审计：检查所有修改的规范文件：
- 编码问题（乱码、智能引号、非 UTF-8 字符）
- 损坏的链接或格式错误的 markdown
- 空/存根文件，无有意义内容
- Frontmatter 不一致
修复发现的问题：直接应用修复 – 不要将发现写入单独的文件

Lint markdown：在修改的文件上运行 markdownlint：

npx markdownlint-cli2 --fix "plugins/cursor-ecosystem/skills/cursor-docs/canonical/**/*.md"

提交：使用 melodic-software:git-commit 技能。建议格式：
- feat(cursor-ecosystem): 重新抓取文档，包含[更改摘要]
- fix(cursor-ecosystem): 修复抓取文档中的编码/格式问题
停止并确认：在执行前向用户展示提交计划

生态系统: duende

使用本地插件代码在 plugins/duende-ecosystem/skills/duende-docs/ 抓取 Duende IdentityServer 文档。

步骤 1: 运行抓取

DUENDE_DOCS_DEV_ROOT="<repo-root>/plugins/duende-ecosystem/skills/duende-docs" python <repo-root>/plugins/duende-ecosystem/skills/duende-docs/scripts/core/scrape_docs.py

停止并验证： 检查输出前几行的 [DEV MODE]。如果看到 [PROD MODE]，环境变量设置不正确。不要继续 – 先排除环境变量问题。

步骤 2: 运行索引重建

从新抓取的文件重建索引：

DUENDE_DOCS_DEV_ROOT="<repo-root>/plugins/duende-ecosystem/skills/duende-docs" python <repo-root>/plugins/duende-ecosystem/skills/duende-docs/scripts/management/rebuild_index.py

停止并验证： 检查输出中的 [DEV MODE]。如果出现 [PROD MODE]，停止并排除问题。

步骤 3: 运行验证

验证索引完整性：

DUENDE_DOCS_DEV_ROOT="<repo-root>/plugins/duende-ecosystem/skills/duende-docs" python <repo-root>/plugins/duende-ecosystem/skills/duende-docs/scripts/maintenance/validate_index.py

步骤 4: Git 状态检查

运行 git status 查看本地仓库中的文件更改。

重要： 仅分析和报告 plugins/duende-ecosystem/ 内的更改。忽略其他插件中的更改 – 这些来自单独的抓取运行。

步骤 5: 内容差异分析

分析抓取的内容更改以检测来自外部源更改的潜在问题：

# 检查抓取文档中的显著内容更改
git diff --stat plugins/duende-ecosystem/skills/duende-docs/canonical/

# 查看具体更改以检测潜在问题
git diff plugins/duende-ecosystem/skills/duende-docs/canonical/ | head -200

需要寻找的内容：

大规模删除：可能表示上游页面重组或移除
格式更改：损坏的 markdown、缺失的标题、格式错误的链接
编码问题：意外字符、乱码或编码伪影
元数据漂移：可能需要 index.yaml 更新的更改
脚本调整需求：表明抓取逻辑需要更新的模式

如果发现问题，调查源 URL 并确定是否需要调整 sources.json 或抓取脚本。

步骤 6: 类别分布分析

抓取后，验证类别分布合理：

# 按类别计数文档
DUENDE_DOCS_DEV_ROOT="<repo-root>/plugins/duende-ecosystem/skills/duende-docs" python <repo-root>/plugins/duende-ecosystem/skills/duende-docs/scripts/management/manage_index.py count

预期类别：

类别	预期范围
identityserver	50-80
bff	20-40
accesstokenmanagement	3-10
identitymodel	1-10
identitymodel-oidcclient	3-10
introspection	2-10
general	1-5
uncategorized	100-200

红旗：

类别有 0 个文档（类别检测损坏）
未分类文档大幅增加（URL 模式更改）
总计数与约 248 个文档显著不同

步骤 7: 最终报告

总结：

抓取结果（抓取的文档、跳过的、错误）
验证结果（索引完整性、元数据覆盖）
内容差异分析发现（检测到的任何问题）
类别分布（任何异常）
准备提交的文件（仅 plugins/duende-ecosystem/ 更改）

步骤 8: 审计、修复和提交

最终报告后，如果有更改的文件准备提交：

内联审计：检查所有修改的规范文件：
- 编码问题（乱码、智能引号、非 UTF-8 字符）
- 损坏的链接或格式错误的 markdown
- 空/存根文件，无有意义内容
- Frontmatter 不一致
修复发现的问题：直接应用修复 – 不要将发现写入单独的文件

Lint markdown：在修改的文件上运行 markdownlint：

npx markdownlint-cli2 --fix "plugins/duende-ecosystem/skills/duende-docs/canonical/**/*.md"

提交：使用 melodic-software:git-commit 技能。建议格式：
- feat(duende-ecosystem): 重新抓取文档，包含[更改摘要]
- fix(duende-ecosystem): 修复抓取文档中的编码/格式问题
停止并确认：在执行前向用户展示提交计划

生态系统: google

使用本地插件代码在 plugins/google-ecosystem/skills/gemini-cli-docs/ 抓取 Gemini CLI 文档。

步骤 1: 运行抓取

GEMINI_DOCS_DEV_ROOT="<repo-root>/plugins/google-ecosystem/skills/gemini-cli-docs" python <repo-root>/plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_all_sources.py --parallel --skip-existing

停止并验证： 检查输出前几行的 [DEV MODE]。如果看到 [PROD MODE]，环境变量设置不正确。不要继续 – 先排除环境变量问题。

步骤 2: 使用 Python 3.13 运行索引刷新

GEMINI_DOCS_DEV_ROOT="<repo-root>/plugins/google-ecosystem/skills/gemini-cli-docs" py -3.13 <repo-root>/plugins/google-ecosystem/skills/gemini-cli-docs/scripts/management/refresh_index.py

停止并验证： 检查输出中的 [DEV MODE]。如果出现 [PROD MODE]，停止并排除问题。

步骤 3: Git 状态检查

运行 git status 查看本地仓库中的文件更改。

重要： 仅分析和报告 plugins/google-ecosystem/ 内的更改。忽略其他插件中的更改 – 这些来自单独的抓取运行。

步骤 4: 内容差异分析

分析抓取的内容更改以检测来自外部源更改的潜在问题：

# 检查抓取文档中的显著内容更改
git diff --stat plugins/google-ecosystem/skills/gemini-cli-docs/canonical/

# 查看具体更改以检测潜在问题
git diff plugins/google-ecosystem/skills/gemini-cli-docs/canonical/ | head -200

需要寻找的内容：

大规模删除：可能表示上游页面重组或移除
格式更改：损坏的 markdown、缺失的标题、格式错误的链接
编码问题：意外字符、乱码或编码伪影
元数据漂移：可能需要 index.yaml 更新的更改
脚本调整需求：表明抓取逻辑需要更新的模式

如果发现问题，调查源 URL 并确定是否需要调整 sources.json 或抓取脚本。

步骤 5: 过滤效果分析

查看 git diff 后，执行结构分析以检测潜在的过滤间隙。

分析步骤：

源分析：由于 gemini-cli-docs 使用单个源（geminicli.com llms.txt），检查：
- 所有预期页面是否正在被抓取（约 73 个预期）
- 是否有任何页面持续导致问题
- 内容结构是否已更改，需要过滤更新
更改位置分析：对于每个修改的文件：
- 检查更改是否仅在文件的后 20%（可能是页脚/相关部分）
- 检查差异是否仅显示 frontmatter（content_hash）更改，且内容行更改 <10
红旗： 多个文件更改集中在末尾 = 可能是页脚部分未被过滤。
与抓取器日志交叉引用：在抓取期间，检查记录的日志消息：
- 跳过的 URL
- 解析错误
- 过滤操作

潜在改进输出：

如果检测到问题，包括一个“潜在改进”部分，提供可操作的建议：

“考虑为 filtering.yaml 中的部分 X 添加过滤规则”
“源结构可能已更改 - 检查 llms.txt 解析”
“N 个文件仅有页脚更改 - 检查过滤规则”

参考： 过滤配置在 plugins/google-ecosystem/skills/gemini-cli-docs/config/filtering.yaml

步骤 6: 最终报告

总结：

抓取结果（抓取的文档、跳过的、错误）
验证结果（索引完整性、元数据覆盖）
内容差异分析发现（检测到的任何问题）
过滤效果分析（识别的任何潜在改进）
准备提交的文件（仅 plugins/google-ecosystem/ 更改）

步骤 7: 审计、修复和提交

最终报告后，如果有更改的文件准备提交：

内联审计：检查所有修改的规范文件：
- 编码问题（乱码、智能引号、非 UTF-8 字符）
- 损坏的链接或格式错误的 markdown
- 空/存根文件，无有意义内容
- Frontmatter 不一致
修复发现的问题：直接应用修复 – 不要将发现写入单独的文件

Lint markdown：在修改的文件上运行 markdownlint：

npx markdownlint-cli2 --fix "plugins/google-ecosystem/skills/gemini-cli-docs/canonical/**/*.md"

提交：使用 melodic-software:git-commit 技能。建议格式：
- feat(google-ecosystem): 重新抓取文档，包含[更改摘要]
- fix(google-ecosystem): 修复抓取文档中的编码/格式问题
停止并确认：在执行前向用户展示提交计划

生态系统: openai

使用本地插件代码在 plugins/openai-ecosystem/skills/codex-cli-docs/ 抓取 OpenAI Codex CLI 文档。

步骤 1: 运行抓取

CODEX_DOCS_DEV_ROOT="<repo-root>/plugins/openai-ecosystem/skills/codex-cli-docs" python <repo-root>/plugins/openai-ecosystem/skills/codex-cli-docs/scripts/core/scrape_docs.py --parallel

停止并验证： 检查输出前几行的 [DEV MODE]。如果看到 [PROD MODE]，环境变量设置不正确。不要继续 – 先排除环境变量问题。

步骤 2: 使用 Python 3.13 运行索引刷新

CODEX_DOCS_DEV_ROOT="<repo-root>/plugins/openai-ecosystem/skills/codex-cli-docs" py -3.13 <repo-root>/plugins/openai-ecosystem/skills/codex-cli-docs/scripts/management/refresh_index.py

停止并验证： 检查输出中的 [DEV MODE]。如果出现 [PROD MODE]，停止并排除问题。

步骤 3: Git 状态检查

运行 git status 查看本地仓库中的文件更改。

重要： 仅分析和报告 plugins/openai-ecosystem/ 内的更改。忽略其他插件中的更改 – 这些来自单独的抓取运行。

步骤 4: 内容差异分析

分析抓取的内容更改以检测来自外部源更改的潜在问题：

# 检查抓取文档中的显著内容更改
git diff --stat plugins/openai-ecosystem/skills/codex-cli-docs/canonical/

# 查看具体更改以检测潜在问题
git diff plugins/openai-ecosystem/skills/codex-cli-docs/canonical/ | head -200

需要寻找的内容：

大规模删除：可能表示上游页面重组或移除
格式更改：损坏的 markdown、缺失的标题、格式错误的链接
编码问题：意外字符、乱码或编码伪影
元数据漂移：可能需要 index.yaml 更新的更改
脚本调整需求：表明抓取逻辑需要更新的模式

如果发现问题，调查源 URL 并确定是否需要调整 sources.json 或抓取脚本。

步骤 5: 过滤效果分析

查看 git diff 后，执行结构分析以检测潜在的过滤间隙。

分析步骤：

源分析：检查：
- 来自 llms.txt 的所有预期页面是否正在被抓取
- 是否有任何页面持续导致问题
- 内容结构是否已更改，需要过滤更新
更改位置分析：对于每个修改的文件：
- 检查更改是否仅在文件的后 20%（可能是页脚/相关部分）
- 检查差异是否仅显示 frontmatter（content_hash）更改，且内容行更改 <10
红旗： 多个文件更改集中在末尾 = 可能是页脚部分未被过滤。
与抓取器日志交叉引用：在抓取期间，检查记录的日志消息：
- 跳过的 URL
- 解析错误
- 过滤操作

潜在改进输出：

如果检测到问题，包括一个“潜在改进”部分，提供可操作的建议：

“考虑为 filtering.yaml 中的部分 X 添加过滤规则”
“源结构可能已更改 - 检查 llms.txt 解析”
“N 个文件仅有页脚更改 - 检查过滤规则”

参考： 过滤配置在 plugins/openai-ecosystem/skills/codex-cli-docs/config/filtering.yaml

步骤 6: 最终报告

总结：

抓取结果（抓取的文档、跳过的、错误）
验证结果（索引完整性、元数据覆盖）
内容差异分析发现（检测到的任何问题）
过滤效果分析（识别的任何潜在改进）
准备提交的文件（仅 plugins/openai-ecosystem/ 更改）

步骤 7: 审计、修复和提交

最终报告后，如果有更改的文件准备提交：

内联审计：检查所有修改的规范文件：
- 编码问题（乱码、智能引号、非 UTF-8 字符）
- 损坏的链接或格式错误的 markdown
- 空/存根文件，无有意义内容
- Frontmatter 不一致
修复发现的问题：直接应用修复 – 不要将发现写入单独的文件

Lint markdown：在修改的文件上运行 markdownlint：

npx markdownlint-cli2 --fix "plugins/openai-ecosystem/skills/codex-cli-docs/canonical/**/*.md"

提交：使用 melodic-software:git-commit 技能。建议格式：
- feat(openai-ecosystem): 重新抓取文档，包含[更改摘要]
- fix(openai-ecosystem): 修复抓取文档中的编码/格式问题
停止并确认：在执行前向用户展示提交计划

禁止事项

不要在没有内联开发模式环境变量前缀的情况下运行脚本
不要在 Claude Code 中使用 PowerShell 语法（$env:...）-- 使用 Bash 内联前缀
不要假设环境变量在 Bash 工具调用间持久化（它们不会）
不要使用全局 /[ecosystem]:docs-ops scrape 命令（使用已安装的插件）
不要在轮询循环中后台运行脚本
如果出现 [PROD MODE] 不要继续 – 停止并修复环境变量
不要在最终报告中包含来自其他插件的更改
不要将审计发现写入计划文件 – 内联报告并直接修复
不要抓取后在未完成审计/修复/提交步骤的情况下停止
不要在同一个无头会话中运行共享脚本的多个生态系统
在所有抓取运行被审核前不要推送到远程
不要使用 Python 3.14 运行验证/刷新（spaCy 兼容性问题）
不要单独使用 rebuild_index.py 于 cursor – 使用 refresh_index.py 以保留元数据

名称: 批量抓取 描述: 在开发模式下使用本地插件代码为一个或多个生态系统运行抓取工作流 允许的工具: 读取, Bash, 技能 参数提示: “[生态系统] (claude|cursor|duende|google|openai|all)”

批量抓取

参数

生态系统路由表

开发模式环境变量

模式 1: 顺序（默认）

顺序工作流

注意事项

模式 2: 无头模式

无头工作流

注意事项

生态系统: claude

步骤 1: 运行抓取

步骤 2: 使用 Python 3.13 运行验证

步骤 3: 运行基于年龄的清理

步骤 4: Git 状态检查

步骤 5: 内容差异分析

步骤 6: 过滤效果分析

步骤 7: 最终报告

步骤 8: 审计、修复和提交

生态系统: cursor

步骤 1: 运行抓取

步骤 2: 运行索引刷新（重建 + 提取元数据）

步骤 3: 运行验证

步骤 4: Git 状态检查

步骤 5: 内容差异分析

步骤 6: 标签分布分析

步骤 7: 最终报告

步骤 8: 审计、修复和提交

生态系统: duende

步骤 1: 运行抓取

步骤 2: 运行索引重建

步骤 3: 运行验证

步骤 4: Git 状态检查

步骤 5: 内容差异分析

步骤 6: 类别分布分析

步骤 7: 最终报告

步骤 8: 审计、修复和提交

生态系统: google

步骤 1: 运行抓取

步骤 2: 使用 Python 3.13 运行索引刷新

步骤 3: Git 状态检查

步骤 4: 内容差异分析

步骤 5: 过滤效果分析

步骤 6: 最终报告

步骤 7: 审计、修复和提交

生态系统: openai

步骤 1: 运行抓取

步骤 2: 使用 Python 3.13 运行索引刷新

步骤 3: Git 状态检查

步骤 4: 内容差异分析

步骤 5: 过滤效果分析

步骤 6: 最终报告

步骤 7: 审计、修复和提交

禁止事项

名称: 批量抓取描述: 在开发模式下使用本地插件代码为一个或多个生态系统运行抓取工作流允许的工具: 读取, Bash, 技能参数提示: “[生态系统] (claude|cursor|duende|google|openai|all)”