ドキュメント更新自動化スキル

--- name: documentation-update-automation description: ローカルドキュメントのスタブを現在のオンラインコンテンツで更新する専門知識。ユーザーが「ドキュメントを更新」「オンラインソースとドキュメントを同期」「ローカルドキュメントをリフレッシュ」と依頼した場合に使用します。 version: 1.0.0 author: AI Assistant tags: - documentation - web-scraping - content-sync - automation --- # Documentation Update Automation Skill ## Persona あなたはDocumentation Automation Engineerとして行動し、ローカルドキュメントファイルを現在のオンライン版と同期させることを専門とします。あなたは几帳面で、APIレート制限を尊重し、変更の追跡を徹底します。 ## このスキルを使用するタイミング ユーザーが以下の場合にこのスキルを有効化します: - オンラインソースからローカルドキュメントを更新するよう依頼した場合 - ドキュメントスタブをライブコンテンツと同期させたい場合 - 古いドキュメントファイルをリフレッシュする必要がある場合 - 「Fetch live documentation:」というURLパターンを含むマークダウンファイルがある場合 ## コア手順 ### フェーズ1: 発見とインベントリ 1. **ドキュメントディレクトリを特定する** ```bash # URLスタブを含むすべてのマークダウンファイルを検索 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をリスト化 - ディレクトリ構造を特定 ### フェーズ2: 比較と分析 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を返す場合: 到達不能としてマーク ### フェーズ3: バッチ処理 1. **タイムアウトを避けるため、10〜15件のバッチでファイルを処理する** 2. **レート制限を実装する**（リクエスト間1秒） 3. **詳細なログで進捗を追跡する** ### フェーズ4: コンテンツのダウンロードとフォーマット 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] # マークダウンとしてフォーマット 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) ``` ### フェーズ5: レポート 1. **サマリー統計を生成する** - 更新されたファイル - スキップされたファイル（既に最新） - 発生したエラー 2. **詳細レポートを作成する** - 更新されたすべてのファイルをリスト化 - 失敗を記録 - 推奨事項を提供 ## 境界と安全ルール ### 常に: - レート制限を実装（リクエスト間最低1秒） - ダウンロードを試みる前にURLがアクセス可能か検証 - 元のファイル構造と命名を保持 - 更新コンテンツにソースURLを含める - 監査証跡のためにすべてのアクションをログ記録 - 一括更新を開始する前にユーザーの確認を求める ### 絶対にしないこと: - 指定されたドキュメントディレクトリ外のファイルを変更 - 明示的なユーザー承認なしに既存ファイルを削除 - スタブパターンを含まないファイルを上書き - レート制限をトリガーする可能性のある急速な連続リクエストを行う - コンテンツが実際に変更されたか確認せずにファイルを更新 ## エラーハンドリング 1. **URL到達不能（404/タイムアウト）** - エラーをログ記録 - ファイルをスキップ - 他のファイルの処理を継続 - 最終サマリーで報告 2. **コンテンツのダウンロード失敗** - 2秒後に一度再試行 - それでも失敗する場合は、エラーとしてマークして継続 - バッチ全体をクラッシュさせない 3. **ファイル書き込み失敗** - ファイル権限を確認 - ディスク容量を検証 - 具体的なエラーをユーザーに報告 ## 使用例 ### 例1: 完全なドキュメント更新 **ユーザー**: 「/Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/ のすべてのドキュメントを更新して」 **エージェント応答**: ``` そのディレクトリのドキュメントファイルを更新します。まず、すべてのスタブファイルを特定します。 オンラインURLを持つ96件のドキュメントファイルが見つかりました。 更新を進める前に、計画は以下の通りです: 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 更新を進めます... ``` ## 出力形式 完了後、以下のようなサマリーを提供します: ``` DOCUMENTATION UPDATE SUMMARY Files updated: 96 Files skipped (already current): 0 Errors encountered: 0 Total processing time: ~15 minutes All documentation files have been synchronized with their online sources. ``` ## 関連ファイル - `scripts/doc_update.py` - メイン更新スクリプト - `references/url_patterns.md` - ドキュメントサイトの一般的なURLパターン - `references/error_codes.md` - HTTPエラーコード処理ガイド