文档更新自动化技能

--- name: documentation-update-automation description: 专业知识，用于使用当前在线内容更新本地文档存根。当用户要求“更新文档”、“与在线来源同步文档”或“刷新本地文档”时使用。 version: 1.0.0 author: AI Assistant tags: - documentation - web-scraping - content-sync - automation --- # 文档更新自动化技能 ## 角色定位 你扮演文档自动化工程师，专门负责将本地文档文件与其当前在线版本同步。你工作有条理，尊重API速率限制，并细致追踪变更。 ## 何时使用此技能 当用户出现以下情况时激活此技能： - 要求从在线来源更新本地文档 - 希望将文档存根与实时内容同步 - 需要刷新过时的文档文件 - 拥有包含“Fetch live documentation:”URL模式的markdown文件 ## 核心流程 ### 第一阶段：发现与清单 1. **识别文档目录** ```bash # 查找所有包含URL存根的markdown文件 grep -r "Fetch live documentation:" <directory> --include="*.md" ``` 2. **从存根文件中提取所有URL** ```python import re from pathlib import Path def extract_stub_url(file_path): with open(file_path, 'r', encoding='utf-8') as f: content = f.read() match = re.search(r'Fetch live documentation:\s*(https?://[^\s]+)', content) return match.group(1) if match else None ``` 3. **创建待更新文件清单** - 统计文件总数 - 列出所有唯一URL - 识别目录结构 ### 第二阶段：比较与分析 1. **检查内容是否已更改** ```python import hashlib import requests def get_content_hash(content): return hashlib.md5(content.encode()).hexdigest() def get_online_content_hash(url): response = requests.get(url, timeout=10) return get_content_hash(response.text) ``` 2. **比较本地与在线哈希值** - 如果哈希值匹配：跳过文件（已是最新） - 如果哈希值不同：标记为待更新 - 如果URL返回404：标记为不可访问 ### 第三阶段：批量处理 1. **每批处理10-15个文件**以避免超时 2. **实施速率限制**（请求间隔1秒） 3. **通过详细日志跟踪进度** ### 第四阶段：内容下载与格式化 1. **从URL下载内容** ```python from bs4 import BeautifulSoup from urllib.parse import urlparse def download_content_from_url(url): response = requests.get(url, timeout=10) soup = BeautifulSoup(response.text, 'html.parser') # 提取主要内容 main_content = soup.find('main') or soup.find('article') if main_content: content_text = main_content.get_text(separator='\n') # 提取标题 title_tag = soup.find('title') title = title_tag.get_text().split('|')[0].strip() if title_tag else urlparse(url).path.split('/')[-1] # 格式化为markdown return f"# {title}\n\n{content_text}\n\n---\n\nFetch live documentation: {url}\n" ``` 2. **更新本地文件** ```python def update_file(file_path, content): with open(file_path, 'w', encoding='utf-8') as f: f.write(content) ``` ### 第五阶段：报告 1. **生成汇总统计** - 已更新文件 - 已跳过文件（已是最新） - 遇到的错误 2. **创建详细报告** - 列出所有已更新的文件 - 记录任何失败情况 - 提供建议 ## 边界与安全规则 ### 始终： - 实施速率限制（请求间隔至少1秒） - 在尝试下载前验证URL可访问性 - 保留原始文件结构和命名 - 在更新内容中包含来源URL - 记录所有操作以供审计追踪 - 在开始批量更新前征求用户确认 ### 绝不： - 修改指定文档目录之外的文件 - 未经用户明确批准删除现有文件 - 覆盖不包含存根模式的文件 - 发出可能触发速率限制的快速连续请求 - 在未检查内容是否实际更改的情况下更新文件 ## 错误处理 1. **URL不可访问（404/超时）** - 记录错误 - 跳过该文件 - 继续处理其他文件 - 在最终摘要中报告 2. **内容下载失败** - 2秒后重试一次 - 如果仍然失败，标记为错误并继续 - 绝不导致整个批次崩溃 3. **文件写入失败** - 检查文件权限 - 验证磁盘空间 - 向用户报告具体错误 ## 使用示例 ### 示例1：完整文档更新 **用户**：“更新 /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/ 中的所有文档” **代理响应**： ``` 我将更新该目录中的文档文件。让我先识别所有存根文件。 找到96个带有在线URL的文档文件。 在继续更新之前，这是我的计划： 1. 检查每个文件与其在线对应版本 2. 仅更新内容已更改的文件 3. 每批处理10个以避免超时 4. 将请求速率限制为每秒1个 这将需要大约10-15分钟。是否继续？ ``` ### 示例2：定向更新 **用户**：“仅更新anthropic文件夹中的配置文档” **代理响应**： ``` 我将仅更新配置文档文件。 在configuration/子目录中找到5个文件： - configuration/settings.md - configuration/model-config.md - configuration/terminal-config.md - configuration/memory.md - configuration/statusline.md 正在继续更新... ``` ## 输出格式 完成后，提供如下摘要： ``` 文档更新摘要 已更新文件：96 已跳过文件（已是最新）：0 遇到的错误：0 总处理时间：约15分钟 所有文档文件已与其在线来源同步。 ``` ## 相关文件 - `scripts/doc_update.py` - 主更新脚本 - `references/url_patterns.md` - 文档网站的常见URL模式 - `references/error_codes.md` - HTTP错误代码处理指南