1仕組みと動作原理
パイプライン全体はSKILL.md内の8ステップの指示とモデルによる読み込みで構成され、ディレクトリ内にスクリプトは一切含まれません。展開はシェル、理解はモデル、集約は固定レポートテンプレートに依存します。
gemini-history-analyzer/SKILL.md
Extract, categorize, and analyze Google Takeout ZIP exports of Gemini Apps activity. The skill handles:
globにより、当該skillディレクトリ内にはSKILL.mdファイルが1つだけ存在することを確認済みです（scripts/、references/、evals/は無し）。後続のキーワード検索、分類、レポート生成はすべてエージェントが汎用ツールを使用して実行し、skillは方法論と規律のみを提供します。
戦略選択の前にタイプを判定：3〜5個のファイルをサンプリングし、「話者ラベル / コンテンツ形態 / 長さの分布 / ファイル命名」の4つのシグナルを用いて「会議の文字起こし」か「プロンプト-応答」かを判別し、それぞれ異なる分析ルートを適用します。
gemini-history-analyzer/SKILL.md
Before full analysis, sample 3-5 files to determine the **conversation type**:
このセクションでは分岐後の違いも提示しています。会議の文字起こしはトピック分類/話者分析/意思決定の追跡/ユーザープロファイリングへ、プロンプト-応答は利用パターン/能力評価/関心領域マッピングへと進みます。これは、単に「読んで要約する」アプローチに対する本skillの最大の構造的差別化点であり、分析フレームワークの誤用を防ぎます。
展開手順における明確な技術選定理由：macOS標準のunzipは中国語などのマルチバイトファイル名をサイレントに破損させるため、unarの使用が必須となります。
gemini-history-analyzer/SKILL.md
Google Takeout files contain Chinese/Unicode filenames. **macOS `unzip` corrupts these — always use `unar`.**
対応するCritical Pitfallsの第1項目で具体的な結果が示されています（『files become garbled paths, many fail to extract』）。これはzipの非UTF-8フラグ処理の違いに起因する現実のツールチェーンの落とし穴であり、単なる一般的な助言ではありません。
精読前に全体を棚卸し：find + sed/uniqを用いて拡張子の分布を集計し、txt一覧を作成、サイズ順に集計してリストを構築してから精読対象を決定します。
gemini-history-analyzer/SKILL.md
find <extract-dir> -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
Step 2の3つのコマンドは「拡張子別カウント / 全txtのリスト化 / サイズ順トップ30の取得」に対応しており、その後にStep 3のサンプリングへ進みます。この順序により、全体規模を把握しないままコンテキストを消費し尽くす事態を防ぎます。
キーワード検索は「答えではなく最初のステップ」と明確に位置付け：ヒット箇所の前後10行のコンテキストを必ず再確認して判定し、結果を3つに分類します。
gemini-history-analyzer/SKILL.md
**Read surrounding context** (10 lines before/after each match) — keyword matching alone produces massive false positives. "Investment" can mean business strategy, "option" can mean UI choice, "fund" can mean insurance feature
ヒットはDefinite hit / False positive / Ambiguousの3つに分類され、definiteとambiguousのみ全文を再読します。『Never stop at grep output — context verification is mandatory.』という厳格なルールも規定されています。Pitfallsの第2項目には、金融用語リストを用いた実測で80%以上のファイルにヒットしたもののすべて偽陽性だったという知見も記録されています。
PIIの処理方針は「フラグ付けするが転記しない」：履歴書、バックグラウンド調査、連絡先リストなどを検出した場合はレポートのリスク項目に記載しますが、その内容自体はレポートやmemoryに絶対に転記しません。
gemini-history-analyzer/SKILL.md
- File: <name>, Type: <resume/background-check/etc.>, Risk: <high/medium/low>
レポート第7節の構造は「ファイル、タイプ、リスクレベルのみを記載」となっており、『(Flag if detected — do NOT include the actual PII in the report)』と明記されています。Pitfalls第4項目でも『Resumes, background check forms, contact lists — these routinely appear in conversation history. Flag them, do NOT include their contents in reports.』と再強調されています。
コンテキスト予算を守るための大容量ファイルの階層的読み込みと大規模セットの並列読み込み：単一ファイルは先頭と末尾の各10%のみを読み、100以上のファイルは並列sub-agentに10〜15件ずつのバッチで割り当てます。
gemini-history-analyzer/SKILL.md
For 100+ files, spawn parallel sub-agents to read and summarize in batches (10-15 files each). Merge results. One agent reading all files sequentially will exhaust context.
Pitfalls第5項目では実践的な基準が示されています：『A 63KB transcript is a 2-hour meeting. Don't read the whole thing unless it's flagged as highly relevant.』この2つのルールが合わさることで、「規模に応じた読み込み手法」の決定基準が構成されます。
出力構成は7セクションの固定レポート（概要/トピック分布/主要な発見/専門領域分析/注目すべき文書/価値ある引用/PIIリスク）とし、オプションでmemoryファイルを出力します。
gemini-history-analyzer/SKILL.md
# Gemini History Analysis Report
テンプレート第4節には「偽陽性の件数およびその要因となった具体例（False positives: N (with examples of what caused them)）」の記載欄まで設けられており、Step 5の検証規律が納品物の構造として定着しています。
オプション生成物であるmemoryファイルには明確なプロトコルを定義：プロジェクト既存のmemory形式に準拠し、originSessionIdによるトレーサビリティを付与、MEMORY.mdのインデックスを更新し、既存内容との重複を排除します。
gemini-history-analyzer/SKILL.md
- Include `originSessionId` or source tag pointing back to the analysis
Step 7ではトリガー条件（ユーザーの明示的な要求 / 再利用可能な知見の発見 / プロジェクト内の既存memoryシステムの存在）を限定し、他のmemoryファイルのfrontmatter規約を事前に確認することを義務付けています。これにより、長期記憶の永続化に伴う副作用を明示的に管理します。
完了時のクリーンアップにはユーザー確認が必要：分析完了後にのみ展開ディレクトリをrm -rfで削除します。
gemini-history-analyzer/SKILL.md
# Remove extracted files after analysis complete (user confirms)
注記にはユーザーの確認（user confirms）が必要である旨が明記されており、実行されるコマンドはrm -rf <extract-dir>（Step 8）です。これは解凍された個人のプライベートな履歴を残さないためのプライバシー管理であり、破壊的コマンドが保持されている理由でもあります。
2コア機能
01Google TakeoutのGemini Appsエクスポートの展開（中国語/Unicodeファイル名に対応）
02精読前の事前インベントリ作成：ファイルタイプ分布、txt一覧、サイズ順ソートによるリスト化
03対話タイプの判定（会議の文字起こし vs プロンプト-応答）および分析フレームワークの切り替え
04トピック分類と構成比率の集計（特定ドメインの深掘り分析を含む）
05コンテキスト検証を伴うキーワード検索（偽陽性の分類および要因説明を含む）
06PII/機密コンテンツの検知と「フラグ付けのみ行い転記しない」レポート作成
07固定フォーマットによる分析レポート生成（7セクション）+ 発言の逐語引用
08オプションのユーザープロファイル/フィードバック/プロジェクトコンテキストのmemoryファイル生成（インデックス更新およびトレーサビリティ追跡付き）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | unar（解包 Takeout ZIP，处理中文文件名） |
| package | Homebrew（仅在 unar 缺失时安装；命令带 2>/dev/null || true 容错） |
| cli | find / sed / sort / uniq / du（清单与统计） |
| cli | grep（领域关键词检索，随后必须人工回读上下文） |
| cli | rm（分析完成后清理解包目录，需用户确认） |
| api | 宿主 sub-agent 能力（100+ 文件时并行批处理） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
アクセス可能ドメインとキー範囲を宣言
管理者向け
最小権限のキー、リクエストログを保持
判定根拠（ファイルパスと抜粋）
- 网络端点: 外部ネットワークアクセスの宣言: 唯一の外部通信の可能性があるアクションはbrew install unarです。これはunarが存在しない場合にのみHomebrew経由でサードパーティ製パッケージを取得するために実行されます（SKILL.mdでは2>/を使用）。
- 本地工作目录: ファイルの読み書きと成果物の出力: <output-dir>/**：unarによって解凍されたTakeoutの全コンテンツ（txt文字起こし、画像、音声/動画、PDF/Officeドキュメント、ネストされたzipファイル）。
監査ノート： 統一基準に基づく判定：本skillは完全スクリプトレス（ディレクトリ内にはSKILL.mdのみ）であり、すべての動作はローカルファイル操作（展開、find/grep/duによる統計、テキスト読み込み、任意のmemory書き込み、必要時のrm -rf）で完結しています。認証情報の読み込みはなく（Cookie、APIキー、環境変数に触れず、アカウントも不要で、入力はユーザー自身がエクスポートしたZIPファイルのみ）、外部APIやトラッキング、サードパーティミラーも利用しません。完全な「緑」と判定されない理由は、一連のフローで実際のシェルコマンド（rm -rfおよび条件付きのbrew install unarサードパーティパッケージインストール）を実行し、対象が極めてプライベートな個人履歴データであるためです。同一リポジトリ内のlocal-conversation-history（青）の格付け基準（同様にローカルのプライベート履歴を読み込み、スクリプトおよびネットワークアクセスなし）と一致しています。
5二重目の独立検証
- [ok] 是否真的没有脚本（避免凭 description 臆测） — glob 结果：仅 SKILL.md。所有「处理」都是写在文档里让 agent 用通用 shell/工具执行的命令，非自带可执行文件。scripts_executed = []。
- [discrepancy] spawn 命中是否等于进程创建 — 〔第二遍标注：扫描器误报，已澄清〕SKILL.md 原文为『spawn parallel sub-agents to read and summarize in batches』，指宿主的 sub-agent 能力；全文件无 child_process / subprocess / exec / eval。
- [ok] brew install 是否被夸大成依赖 — 命令为 brew install unar 2>/dev/null || true，位于『Install unar if missing』注释下，失败被吞掉；SKILL.md 未把它列为前置条件（前置条件段落只说要 macOS 与 Takeout zip）。已在 external_deps 与 network_calls 中标为条件性、尽力而为。
- [discrepancy] rm -rf 的危险性是否被如实标注 — 〔第二遍标注：第一遍低估，已加强〕Step 8 的清理命令确为 rm -rf <extract-dir>，作用是删除解包出来的整棵目录树。命令上方注释写了『(user confirms)』，但这是文档级约束、无技术强制；已在 file_writes 与 verdict.risks 中单列，并指出它同时是隐私卫生措施（不留私人历史副本）——两个动机都要讲，避免读者只看到「破坏性」。
- [ok] PII 保护是否只是声明 — 报告第 7 节模板字段（File / Type / Risk）本身就是「不含内容」的结构；Pitfalls 4 条再次强调 do NOT include their contents；memory 段落要求 PII 摘要而非复制。三处一致，属可执行的结构性约束。
- [ok] 关键词检索纪律是否与实测证据一致 — Step 5 的四步（设计词表 → grep 全部文件 → 回读前后 10 行 → 三分类后全文重读）与 Pitfalls 2 的实测结论（80%+ 命中全为假阳性）互相印证，报告第 4 节要求列出假阳性条数与原因——方法、证据、交付物三者闭环。
- [ok] memory 写入是否有副作用管理 — Step 7 限定三个触发条件、要求遵循项目既有 frontmatter 约定、要带 originSessionId 溯源、要更新 MEMORY.md 索引、且『Never duplicate what's already in memory — update existing files instead』。副作用有明确协议。
- [ok] 元数据（license/stars/last_push） — 取自同 repo 同 commit 的池内既有值（MIT、1385★、2026-09-09T12:33:29Z）；本次未联网复核 gh。
6結論
最適な用途： Google Takeoutでデータをエクスポートしたばかりで、「この1年間にGeminiとどのような会話をしたか」を把握したい個人ユーザーに適しています。また、膨大な対話履歴から特定領域（金融/法務/人事など）のコンテンツを抽出したい調査用途にも適しており、キーワード検索 + コンテキスト検証 + 偽陽性の要因説明という一連の流れが「grepによる無関係なヒットの山」という問題を解決します。7セクションの構造化された納品レポートを出力したいシナリオに最適です。
不向きな用途： 対話記録を自動で整理・再構成したいシナリオ（分析のみを行い再構成はしません）；プライベートな履歴をモデルのコンテキストに投入することが許可されない環境（ローカルでの匿名化処理はありません）；決定論的な統計基準が求められるシナリオ（分類や割合はモデルの判断によるため再現性がありません）；Google Takeout以外のチャットエクスポート形式；人間の判断を介さずワンクリックで結論を得たいユーザー（エージェントによるコンテキストの再確認や偽陽性の手動分類を要求するため、プロセス自体が綿密に設計されています）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload gemini-history-analyzer.tar.gz
sha256:
Option B · Copy Guide for Agent16d58ad7768cadfe…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.