1实现原理 · 为什么它能做到
整条流水线由一份 SKILL.md 的 8 步指令 + 模型阅读构成，目录内没有任何脚本：抽取靠 shell，理解靠模型，汇总靠固定报告模板。
gemini-history-analyzer/SKILL.md
Extract, categorize, and analyze Google Takeout ZIP exports of Gemini Apps activity. The skill handles:
glob 核实该 skill 目录下只有 SKILL.md 一个文件（无 scripts/、无 references/、无 evals/）。后面的关键词搜索、分类、报告生成全部是「让 agent 用通用工具去做」，skill 只提供方法与纪律。
先判类型再选策略：抽样 3-5 个文件，用「说话人标签 / 内容形态 / 长度分布 / 文件命名」四个信号区分「会议转写」还是「提示-应答」，两类走不同的分析路线。
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 的三条命令分别对应「按扩展名计数 / 列全部 txt / 按大小排序取前 30」，然后才进入 Step 3 抽样。这个顺序保证不会在没摸清规模时就一头读进上下文。
关键词检索被明确定位为「第一步而不是答案」：必须回读命中处前后 10 行上下文再判定，并把命中分三类。
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，然后只对 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.』两条合起来构成一个「规模 → 读法」的决策规则。
输出结构固定为 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核心能力
01解包 Google 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/密钥/环境变量，也不需要任何账号，输入就是用户自己导出的 ZIP 文件）、无外部 API、无埋点、无第三方镜像。之所以不是绿色：全流程要跑真实 shell 命令（含 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 导出、想知道「我这一年到底跟 Gemini 聊了些什么」的个人用户；也适合需要从一大堆对话记录里定位某个领域（金融/法务/人事）内容的研究型用法——关键词检索 + 上下文核验 + 假阳性说明这套流程正好解决「grep 出一堆无关命中」的问题。对需要输出一份可交付、结构固定的分析报告（7 节）的场景尤其省事。
不适合： 不适合想自动整理/重排对话记录的场景（它只分析不重组）；不适合在无法接受把私人历史送进模型上下文的环境（无本地匿名化步骤）；不适合需要确定性统计口径的场景（分类与占比由模型判断，不可复现）；不适合非 Google Takeout 格式的聊天导出；也不适合期待一键出结论、不需要人工判断的用户——它要求 agent 回读上下文、人工归类假阳性，本身就偏重。
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.