第一部分：项目总结

Gadgets 是什么

Gadgets（仓库目录名为 gadget/）是一组日常开发工具，覆盖五类需求：AI 对话总结、论文研究、性能测试、博客发布和文档翻译。

tools/ 下的五个工具可以独立使用。它们共用仓库根目录的 common/ 包，该包提供 LLM 调用、缓存、文件写入、翻译和 Hugo 部署等能力。

开发工作流和 Claude Code skills 放在另一个仓库 ai-companion 中，位置是同级目录 ../ai-companion/，通过本仓库的 hooks 接入。

仓库结构

gadget/
├── tools/
│   ├── summarize/      # AI 对话日报、周报、月报
│   ├── research/       # 论文发现、研究者分析、引用图分析
│   ├── benchmark/      # CPU/GPU 性能测试
│   ├── website/        # Hugo 博客、媒体压缩、构建和发布
│   └── translator/     # Gradio 文档翻译器
├── common/             # 工具共用的基础能力
├── scripts/            # 同步、机器配置、检查等维护脚本
├── docs/               # 设计文档、计划、审计报告、历史归档
├── outputs/            # 可重新生成的输出，已被 Git 忽略
├── AGENTS.md           # AI agent 工作协议
├── CLAUDE.md           # Claude Code 仓库指南
└── pyproject.toml      # Python 打包与安装配置

修改工具逻辑时进入 tools/<工具名>/；修改公共能力时进入 common/；修改同步逻辑时查看 scripts/sync.py；修改开发工作流或 skills 时进入独立的 ai-companion 仓库。

五个工具分别做什么

common/ 还包括 JSON 解析与修复、带命名空间和 TTL 的 SHA-256 磁盘缓存、原子写入及内容哈希。scripts/ 负责运维；ai-companion 负责代码变更跟踪、测试与 HTML 报告，以及 /idea → /ccplan → /ccedit 等开发流程。

第二部分：新手使用教程

以下命令全部来自提供的 README。除 Benchmark 和明确包含 cd 的命令外，默认在 gadget/ 仓库根目录执行。

README 定位是总览，未提供完整安装与配置步骤。缺失的内容会明确说明，不补写猜测性的命令。

1. 准备环境

需要的基础环境如下：

如果已有 AI Conda 环境，可以执行：

conda activate AI

README 没有给出 gadget 仓库的克隆地址，也没有提供 Python、Conda、Ollama、Hugo、rclone、pngquant 或 HandBrakeCLI 的安装命令，因此这里不能给出完整的“从空机器开始”安装流程。

2. 安装 Python 包和工具依赖

安装公共基础包：

pip install -e .

安装 common 及 Summarize、Research、Benchmark、Website 的 extras：

pip install -e ".[all]"

注意：all 不包含 Translator。需要翻译器时另行安装：

pip install -e ".[translator]"

如果只需要 Website 对应的依赖，README 也提供了：

pip install -e ".[website]"

其中 Website extras 包含翻译所用的 torch 和 transformers；Translator extras 包含 Gradio 和 GGUF 翻译栈。

3. 准备配置

在仓库根目录，将 config.example.json 复制为 config.json，再按需修改。README 没有展示配置字段的完整结构，因此不应自行编造配置内容。

相关配置入口如下：

config.json 和 tokens/ 已被 Git 忽略；不要提交 tokens/ 的内容。README 未给出 API 密钥文件名、格式或上述环境变量的赋值示例。

Summarize 和 Research 的 LLM 功能支持用 --api 选择：

README 没有提供这几个后端的完整配置过程，也没有展示带 --api 的完整命令示例。

翻译功能使用本地推理。需要特别注意，README 对默认翻译模型的描述存在差异：

• Website 和 Translator 专节描述了 tencent/Hy-MT2-1.8B，首次使用自动下载；Translator 还列出其 GGUF 变体。
• 环境要求和 Notes 又描述 Ollama 默认复用 gemma4:26b，其他进程内后端使用 tencent/Hy-MT2-1.8B。

因此，仅依据这份 README，不能断言所有翻译路径都默认使用同一个模型。

4. 可选：机器初始化与基础检查

如果希望配置新机器，README 提供两条路径：

• 仓库级初始化：填写 tokens/onboard.yaml 后运行 scripts/onboard.py。它会配置 SSH、Claude/Codex 安装与认证、pip extras、ai-companion、工具设置和 rclone bootstrap。README 未给出完整执行命令或 YAML 示例。
• Ubuntu 服务器级初始化：脚本位于 ai-companion 仓库，支持 Ubuntu 22.04/24.04。可以先查看其帮助：

bash ../ai-companion/scripts/onboard-server.sh --help

服务器脚本的 --companion-repo 应指向 ai-companion 仓库 git@github.com:TzJ2006/ai-companion.git；拆分后不再需要 --companion-ref。README 未提供完整安装命令。

安装后，可运行只读烟雾检查：

bash scripts/smoke.sh

它检查各工具的 --help、--info 和导入，不调用 LLM、不访问网络、不写文件。

5. Summarize：生成 AI 对话报告

典型流程是：各设备导出对话记录 → 云盘同步或手动汇总 → 逐日合并生成日报 → 在日报积累后生成周报、月报。

第一阶段，导出所有尚未导出的日期：

python -m summarize daily export

在多设备场景中，各设备分别导出，再汇总记录。第二阶段，同步所有日期并逐日合并：

python -m summarize daily merge --sync-all

根据已有日报生成指定周的周报，并部署：

python -m summarize weekly generate --week 2026-W12 --deploy

根据已有日报生成指定月份的月报，并部署：

python -m summarize monthly generate --month 2026-02 --deploy

2026-W12 和 2026-02 是 README 的示例值，使用时替换为目标周、月份。

也可以运行完整自动流程：

python -m summarize auto --deploy

它执行导出、合并、周报、月报和部署。

该工具通过 ccusage 20.x 的分来源命名空间命令统计各 agent CLI 的 token 和费用。README 未提供 ccusage 的安装命令、对话来源路径或导出数据格式。

旧的 daily_summary.py、weekly_summary.py、monthly_summary.py 入口仍兼容，但推荐使用上述 python -m summarize 形式。

6. Research：发现论文、分析研究者和引用关系

Research 使用单一入口 tools/research/research_scout.py。

运行一个项目的完整论文研究流程：

python tools/research/research_scout.py report --project my-project

它执行搜索、三阶段评估和报告生成。三阶段分别是快速筛选、深度评价和引用影响分析。

my-project 是示例项目名。README 未说明项目如何定义，也未给出项目配置格式，所以无法仅凭这份 README 完成项目配置。

使用自然语言搜索：

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

该命令会自动选择搜索来源。

生成研究者画像：

python tools/research/research_scout.py profile "Sergey Levine"

画像功能结合 arXiv、Semantic Scholar 和 LLM，分析研究轨迹、计算层级评分，并通过主页信息和共同署名模式发现导师—学生关系。也支持同名消歧和反向查找。

分析论文引用图：

python tools/research/research_scout.py citations 2301.12597

输入支持 arXiv ID 或 DOI；分析包含向前引用、向后参考文献及 LLM 影响解读。

部署研究报告到 Hugo：

python tools/research/research_scout.py deploy

README 还介绍了 --insight 深度论文分析：下载全文，分析写作结构、发表策略和可复用知识，匹配 OpenReview 评论，并综合跨论文写作指南。但没有提供完整调用示例，因此这里不拼接猜测性的命令。

7. Benchmark：测试 CPU/GPU 性能

Benchmark 的命令有特殊目录要求：先进入 tools/benchmark/。

cd tools/benchmark

运行全部测试：

python -m benchmark.cli

仅测试 CPU：

python -m benchmark.cli --cpu-only

仅测试 GPU：

python -m benchmark.cli --gpu-only

运行测试并生成 HTML 报告：

python -m benchmark.cli --report

运行测试、生成报告并发布到 Hugo 的 /benchmark/：

python -m benchmark.cli --report --deploy

这些是不同的运行方式，按需要选择。

测试使用预热、正式测量、中位数统计和 IQR 异常值剔除，并显式同步 GPU。结果以追加方式保存到 CSV，便于积累多种硬件的成绩。

实际 GPU 测试支持 NVIDIA CUDA、Apple Silicon MPS 和 Intel XPU。OpenCL 可能出现在 --info 的检测结果中，但不属于 README 列出的实际 GPU 测试后端。精度包括 FP64、FP32、FP16、BF16 和实验性的 FP8。

README 提到公共排行榜提交功能，但未提供提交命令；也未给出具体硬件驱动安装步骤。

执行完后，后续工具的根目录命令需要在终端回到 gadget/ 根目录再运行。

8. Website：预览和发布 Hugo 博客

如果还未安装 Website extras，在根目录执行：

pip install -e ".[website]"

本地预览：

cd tools/website && hugo server -D

-D 表示预览时包含草稿。

macOS/Linux 构建并发布：

cd tools/website && bash update.sh

Windows 在仓库根目录执行：

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

Windows 脚本会自行进入它所在的目录。

发布脚本执行增量媒体压缩、Hugo 构建，并推送 Pages。增量压缩以 .last_build 为依据：图片使用 pngquant，视频使用 HandBrakeCLI。

这两个更新脚本会发布网站，不只是生成本地预览。 README 对应的站点是 https://tzj2006.github.io/，部署仓库是 tzj2006/tzj2006.github.io；README 没有说明如何更换为自己的站点或配置推送认证。

自动生成内容直接写入：

• tools/website/content
• tools/website/static

这些文件带有 gadget_generated 标记；没有该标记的手写文件不会被覆盖。

tools/website/public/ 是独立的部署仓库，由构建脚本自动提交和推送，不要直接向它提交。

9. Translator：在浏览器中翻译文档

在仓库根目录安装依赖：

pip install -e ".[translator]"

启动界面：

python -m translator

它会打开浏览器中的 Gradio GUI。可以在界面中翻译文本或 .md、.txt、.pdf、.docx、图片文件，并通过界面的模型管理切换模型。

语言选择行为：

• 源语言设为 auto 时，根据文本的 CJK 字符比例检测。
• 目标语言设为 auto 时，在中文和英文之间切换。

翻译器复用 common.engine.create_engine() 自动选择后端：模型 tag 已拉取时自动优先使用 Ollama；Windows 的回退是 transformers，Linux 优先使用 vLLM，低显存场景提供 llamacpp/GGUF 选项。

模型会驻留内存；切换模型时按需延迟加载。默认模型及环境要求中的描述差异已在配置部分说明。README 未提供手动拉取模型、指定端口或命令行翻译文件的命令。

10. 数据同步与输出管理

同步由 scripts/sync.py 统一管理，需要事先配置 rclone。配置位于根目录 config.json 的 sync 部分。

README 给出的基础入口是：

python scripts/sync.py

跨设备推送和拉取：

python scripts/sync.py push

python scripts/sync.py pull

脚本还支持 status、bootstrap、config 操作，覆盖 summarize、website、research、benchmark 和 backups 等类别；特殊的 dag 类别用于生成并部署 DAG 站点。README 没有给出这些类别的完整命令语法。

对于 Summarize，本地 Ollama 辅助脚本还提供以下环境加载命令：

eval "$(bash scripts/serve_local_llm.sh env)"

该脚本用于创建适合 Summarize 的 Ollama 变体并输出环境设置；它不是 README 提供的 Ollama 安装命令。

常规生成产物集中在：

outputs/
├── logs/         # 导出日志、运行日志等中间产物
├── reports/      # Markdown、JSON、HTML 报告
├── cache/        # LLM 缓存、搜索缓存
├── data/         # CSV、JSON 画像等结构化数据
├── images/       # 图表和生成图片
└── backups/      # 强制覆盖操作的备份

网站内容是明确的例外：直接写入 tools/website/content|static，没有单独的 outputs/site 暂存目录。

不要把自动生成内容、rclone 同步数据、build/、gadget.egg-info/，以及 Website 下的部署和主题仓库加入本仓库提交。

README 尚未提供的关键细节

要真正完成所有功能的首次配置，还需要 README 指向的文档：根目录 TUTORIAL.md、各工具教程，以及 ai-companion 的安装说明。当前内容未给出配置 JSON/YAML 的字段、API 密钥格式、Ollama 安装与模型准备、rclone remote 配置、Research 项目定义，以及自有 Hugo 站点的部署设置；以上教程因此保留这些缺口，没有补造命令或参数。

以下仅依据你提供的 README。README 定位为项目概览，因此没有给出的配置字段、安装步骤或命令参数，本文会明确标注，不补造。

一、项目总结

Gadgets（仓库目录名为 gadget/）是一组开发过程中积累的实用工具，包含五个可以独立使用的工具：

它们共同依赖根目录的 common/ Python 包。开发工作流和 Claude Code skills 则来自独立的 ai-companion 仓库。

仓库结构如下：

gadget/
├── tools/
│   ├── summarize/      # AI 对话日报、周报、月报
│   ├── research/       # 论文发现、研究者分析、引用图
│   ├── benchmark/      # CPU/GPU 性能测试
│   ├── website/        # Hugo 博客
│   └── translator/     # Gradio 文档翻译器
├── common/             # LLM、缓存、读写、翻译、Hugo 部署等共享能力
├── scripts/            # 同步、机器初始化、检查和维护脚本
├── docs/               # 设计文档、计划、审计报告、历史归档
├── outputs/            # 生成结果，已被 Git 忽略
├── AGENTS.md           # AI agent 工作流协议
├── CLAUDE.md           # Claude Code 仓库指南
└── pyproject.toml      # Python 打包和安装配置

修改某个工具时，进入 tools/<工具名>/；修改共用的 LLM、缓存、翻译或部署能力时，进入 common/；修改开发工作流或 skill 时，进入同级的 ../ai-companion/。

二、使用前准备

需要准备的环境：

如果已经创建好 README 推荐的 Conda 环境，可以运行：

conda activate AI

README 没有给出 gadget 仓库的克隆地址，也没有给出 Python、Conda、Ollama、Hugo、rclone 等软件的安装命令，因此这里不补充这些命令。

下文除 Benchmark 和明确包含 cd 的命令外，均按在 gadget 仓库根目录执行来组织。进入子目录后，执行下一节的根目录命令前，请先回到仓库根目录。

三、安装项目依赖

仅安装共享包及项目的基础可编辑安装：

pip install -e .

如果准备使用 Summarize、Research、Benchmark 和 Website，可以安装 README 提供的合集：

pip install -e ".[all]"

all 不包含 Translator。 如果还需要文档翻译网页，单独安装：

pip install -e ".[translator]"

如果只准备使用网站功能，README 也提供了对应安装方式：

pip install -e ".[website]"

网站依赖包含用于翻译的 torch 和 transformers；Translator 的依赖包含 Gradio 和 GGUF 翻译组件。

这些安装方式按需要选择，不必逐条重复执行。安装生成的 build/ 和 gadget.egg-info/ 位于仓库根目录，已被 Git 忽略。

四、配置项目

1. 准备主配置文件

   将根目录的 config.example.json 复制为 config.json，再根据实际需要填写。

   README 明确说明：

   • 工具设置位于根目录 config.json。
   • GADGET_CONFIG 可以覆盖配置文件路径。
   • rclone 同步配置位于 sync 节。
   • Summarize 的持久配置位于 summarize 节。

   README 未展示 JSON 的具体字段和值，因此不能据此写出一份可靠的完整配置示例。

2. 选择 LLM 后端

   Summarize 和 Research 的 LLM 功能支持以下后端：

   后端值	README 中的说明
   ollama	默认，本地 Ollama，无需 API key，使用 Gemma4-26B
   claude_cli	复用 Claude Code CLI 登录状态，无需 API key
   anthropic	Anthropic API 后端
   openai	OpenAI API 后端

   通过 --api 参数切换，或通过 GADGET_LLM_BACKEND 全局选择。

   README 没有给出 API key 的具体字段、文件格式或完整后端切换示例，因此下文保留原文命令，不自行拼接参数。

3. 理解翻译配置

   翻译在本地执行，不调用云端翻译 API。相关配置入口为：

   配置入口	作用
   GADGET_TRANSLATION_BACKEND	选择本地翻译后端
   GADGET_TRANSLATION_MODEL	覆盖 Translator 默认模型
   Translator 界面中的模型管理	在界面中管理模型

   后端涉及 ollama、llamacpp、vllm 和 transformers；其中 GGUF/llamacpp 是低显存选项。

   README 对默认翻译模型的描述存在差异： Website 和 Translator 段落提到 tencent/Hy-MT2-1.8B，Translator 还列出 GGUF 版本；环境要求和 Notes 则说明默认 Ollama 路径复用 gemma4:26b，其他进程内后端使用 Hy-MT2。仅凭这份 README，不能将所有翻译场景统一描述为使用同一个默认模型。

4. 保存敏感配置

   tokens/ 用于保存 API keys 和机器初始化表，已被 Git 忽略，不要提交其中的内容。根目录的 config.json 也已被 Git 忽略。

五、Summarize：从 AI 对话生成报告

支持读取 Claude Code、Codex、Cursor Agent、ChatGPT 和通用 JSON 对话记录。

它采用两个阶段：先在各设备导出，再集中合并生成日报；积累日报后，可以生成周报和月报。

第一步，在每台需要收集对话记录的设备上，导出所有尚未导出的日期：

python -m summarize daily export

第二步，通过云盘同步或手动复制聚合导出记录，然后同步所有日期并逐日合并：

python -m summarize daily merge --sync-all

第三步，根据已有日报生成周报或月报。以下使用 README 中的示例日期，并带部署操作：

python -m summarize weekly generate --week 2026-W12 --deploy

python -m summarize monthly generate --month 2026-02 --deploy

也可以运行完整流水线，依次执行导出、合并、周报、月报和部署：

python -m summarize auto --deploy

使用提示：

• --deploy 会触发部署，使用前应准备好相关网站配置。
• token 用量和费用统计通过 ccusage 20.x 的各来源命令完成。
• 旧的 daily_summary.py、weekly_summary.py、monthly_summary.py 入口仍兼容，但推荐使用上述模块入口。
• README 未提供各对话来源的路径配置、通用 JSON 格式或 ccusage 安装命令。

进一步说明位于 TUTORIAL.md 和 tools/summarize/tutorial.md，但它们的正文不在本次提供的材料中。

六、Research：论文发现与学者分析

统一入口为 tools/research/research_scout.py。

典型用法一：围绕一个项目生成研究报告，执行搜索、三阶段评估和报告生成：

python tools/research/research_scout.py report --project my-project

三阶段评估依次为快速筛选、深入评估和引用影响分析。my-project 是 README 中的示例项目名，具体项目配置方式未给出。

典型用法二：直接使用自然语言搜索：

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

工具会自动选择搜索来源，也支持会议论文搜索和作者搜索。

典型用法三：分析研究者：

python tools/research/research_scout.py profile "Sergey Levine"

研究者分析包含论文和引用数据、研究轨迹、分层评分，以及通过主页和合著模式发现导师—学生关系；还支持同名消歧和反向查找。

典型用法四：分析某篇论文的引用关系：

python tools/research/research_scout.py citations 2301.12597

支持用 arXiv ID 或 DOI 指定论文，分析后续引用和参考文献，并结合 LLM 解读影响。

典型用法五：把报告部署到 Hugo：

python tools/research/research_scout.py deploy

README 还描述了 --insight 深度解读功能：下载全文，分析写作结构、发表策略和可复用知识，匹配 OpenReview 评论，并综合形成跨论文写作指南。原文没有给出该参数的完整调用命令，因此这里不推断它应接在哪个子命令后面。

七、Benchmark：测试 CPU/GPU 性能

先从仓库根目录进入指定目录：

cd tools/benchmark

以下命令都在该目录运行，按需求选择一条。

运行全部基准测试：

python -m benchmark.cli

只测试 CPU：

python -m benchmark.cli --cpu-only

只测试 GPU：

python -m benchmark.cli --gpu-only

运行测试并生成 HTML 报告：

python -m benchmark.cli --report

运行测试、生成报告，并发布到 Hugo 的 /benchmark/：

python -m benchmark.cli --report --deploy

结果和硬件支持：

• 实际 GPU 测试支持 NVIDIA CUDA、Apple Silicon MPS 和 Intel XPU。
• OpenCL 可能仅出现在 --info 的检测信息中，不代表支持实际测试。
• 覆盖 FP64、FP32、FP16、BF16 等精度，FP8 为实验性支持。
• 测量包含预热、正式测量和统计分析，并进行显式 GPU 同步。
• 结果以追加方式写入 CSV，不覆盖已有记录，便于积累多硬件排行榜。

README 提到可以提交到公共排行榜，但没有提供提交命令。

八、Website：预览和发布 Hugo 博客

该网站使用 PaperMod 主题，README 对应的站点为 https://tzj2006.github.io/。

尚未安装网站依赖时，在仓库根目录执行：

pip install -e ".[website]"

本地预览：

cd tools/website && hugo server -D

其中 -D 会包含草稿。

正式构建和发布按操作系统选择。macOS/Linux 从仓库根目录运行：

cd tools/website && bash update.sh

Windows 从仓库根目录运行：

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

Windows 脚本会自行进入所在目录。这些更新脚本会执行网站构建发布流程，包含媒体增量压缩和推送 Pages。

需要理解的文件关系：

• 自动生成的网站内容直接写入 tools/website/content 和 tools/website/static。
• 自动生成的文件带有 gadget_generated 标记；没有该标记的手写文件不会被覆盖。
• 图片通过 pngquant 压缩，视频通过 HandBrakeCLI 压缩，仅处理自 .last_build 以来变化的媒体。
• tools/website/public/ 是独立部署仓库，构建脚本会自动提交和推送，不要直接向其中提交。

README 未给出如何将该站点改成个人域名或个人 GitHub Pages 仓库的配置步骤。

九、Translator：在网页中翻译文本和文件

在仓库根目录安装依赖并启动：

pip install -e ".[translator]"
python -m translator

启动后会在浏览器中打开 Gradio 界面。

典型使用过程：

1. 输入待翻译文本，或提供 .md、.txt、.pdf、.docx、图片文件。
2. 选择源语言和目标语言。
3. 按需通过界面中的模型管理选择模型。
4. 执行翻译。

语言自动选择的含义：

• 源语言为 auto：依据文本中的 CJK 字符比例判断。
• 目标语言为 auto：在中文和英文之间切换。

翻译引擎会保护代码块、URL 和 Hugo shortcodes 等 Markdown 片段；模型保持驻留，切换模型时按需加载。README 说明默认 Hy-MT2 模型会在首次使用时自动下载，具体默认模型差异见前文配置说明。

README 未提供界面端口、监听地址或启动参数，也未说明各文件类型的导出操作。

十、同步、检查与新机器初始化

集中式数据同步入口：

python scripts/sync.py

跨设备推送或拉取：

python scripts/sync.py push

python scripts/sync.py pull

使用前需要配置 rclone 和根目录 config.json 的 sync 节。同步覆盖 summarize、website、research、benchmark、backups，并包含用于生成和部署 DAG 站点的特殊 dag 类别。README 还列出 status、bootstrap、config 功能，但未给出详细参数。

运行只读冒烟检查：

bash scripts/smoke.sh

该检查覆盖帮助信息、检测信息和导入，不调用 LLM、不访问网络、不写文件。它可用于基础检查，但不能证明 API、同步或发布流程已经配置成功。

在 Bash 中加载本地 LLM 辅助脚本输出的环境设置：

eval "$(bash scripts/serve_local_llm.sh env)"

README 说明该脚本用于创建面向 Summarize 调优的 Ollama 变体并输出环境设置，但没有展开完整服务准备步骤。

新机器初始化有两条路径：

• 仓库级初始化：填写 tokens/onboard.yaml，再运行 scripts/onboard.py，用于 SSH、Claude/Codex 安装认证、pip extras、ai-companion、工具配置和 rclone 初始化。README 未提供 YAML 字段或完整执行命令。
• Ubuntu 22.04/24.04 系统级安装：脚本位于独立的 ai-companion 仓库，可以先查看其帮助：

bash ../ai-companion/scripts/onboard-server.sh --help

ai-companion 应位于同级 ../ai-companion/，需要 Node.js 18+。README 提供仓库地址 git@github.com:TzJ2006/ai-companion.git，但没有提供完整安装命令；安装说明指向其 scripts/install.ts。

十一、运行后去哪里找结果

通常生成结果集中在：

outputs/
├── logs/       # 导出日志、运行日志等中间产物
├── reports/    # Markdown、JSON、HTML 最终报告
├── cache/      # LLM 和搜索缓存
├── data/       # CSV、JSON profiles 等结构化数据
├── images/     # 图表和生成图片
└── backups/    # 强制覆盖时的备份

网站内容是明确的特殊路径：直接写入 tools/website/content 和 tools/website/static，没有 outputs/site 暂存目录。

不要把自动生成内容、rclone 同步数据、构建产物，以及 tools/website/ 下的部署仓库和主题仓库加入 gadget 的 Git 提交。

这份 README 足以提供安装入口和典型运行命令，但完整配置仍需它所指向的 TUTORIAL.md、配置示例及各工具文档；上文未补写这些未提供的内容。

一、项目概览

Gadgets 是一个日常开发工具集合，涵盖 AI 对话总结、论文检索、性能测试、博客发布和文档翻译。tools/ 下的五个工具可以分别使用；它们共用仓库根目录的 common/ 包。

ai-companion 是放在 ../ai-companion/ 的独立仓库，提供开发流程和技能，不属于 Gadgets 的 tools/。博客生成内容会直接写入 tools/website/content 或 tools/website/static；网站的 public/ 则是单独的部署仓库。

二、从零开始使用

以下命令均来自所给 README。除特别注明外，在 Gadgets 仓库根目录运行。

1. 准备环境并安装

需要 Python 3.10 或更高版本。README 推荐使用名为 AI 的 conda 环境：

conda activate AI

如果要使用独立的 ai-companion 仓库，还需要 Node.js 18 或更高版本。各工具的具体依赖可查看其目录下的 requirements.txt。

安装共用包及 summarize、research、benchmark、website 的依赖：

pip install -e ".[all]"

all 不包含 translator。需要翻译工具时，另行安装：

pip install -e ".[translator]"

只准备博客相关依赖时，README 给出的命令是：

pip install -e ".[website]"

2. 配置

工具配置位于仓库根目录的 config.json：以 config.example.json 为模板建立该文件。README 没有列出具体字段和值；修改前应查看模板。GADGET_CONFIG 可用于指定其他配置文件路径。

LLM 功能默认使用本地 Ollama；README 列出的后端还有 claude_cli、anthropic、openai，可通过各工具的 --api 参数选择，或用 GADGET_LLM_BACKEND 全局指定。claude_cli 复用 Claude Code CLI 的登录状态；anthropic 和 openai 涉及相应 API 凭据。README 未给出凭据填写步骤。

翻译使用本地推理。README 列出 GADGET_TRANSLATION_BACKEND 用于选择翻译后端，GADGET_TRANSLATION_MODEL 用于覆盖默认翻译模型。首次使用可能下载模型。tokens/ 存放 API 密钥及新机器配置表，已被 Git 忽略，不要提交其中内容。

如需跨设备同步，须先配置 rclone。新机器的一次性配置入口是填写 tokens/onboard.yaml，再运行 scripts/onboard.py；README 没有给出该脚本的精确运行命令或 YAML 字段，因此这里不补写。

3. Summarize：生成 AI 对话报告

先在各设备导出尚未导出的对话日期，再同步并逐日合并：

python -m summarize daily export
python -m summarize daily merge --sync-all

已有足够的日报后，可以生成指定周、指定月的报告并发布：

python -m summarize weekly generate --week 2026-W12 --deploy
python -m summarize monthly generate --month 2026-02 --deploy

也可以运行 README 给出的完整流程，依次完成导出、合并、周报、月报和发布：

python -m summarize auto --deploy

多设备使用时，对话日志可通过云盘同步或手动复制后汇总。具体数据格式和分步配置需查阅 README 指向的 TUTORIAL.md 与 tools/summarize/tutorial.md。

4. Research：检索论文与分析研究者

运行完整的项目报告流程，包含检索、三阶段评估和报告生成：

python tools/research/research_scout.py report --project my-project

用自然语言提问，让工具选择检索来源：

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

生成研究者画像，或按 arXiv ID／DOI 分析引用关系：

python tools/research/research_scout.py profile "Sergey Levine"
python tools/research/research_scout.py citations 2301.12597

将报告发布到 Hugo：

python tools/research/research_scout.py deploy

该工具还支持论文全文深度分析、OpenReview 评论分析等能力；README 只提到 --insight，没有给出完整示例命令。项目设置和这些功能的详细操作应参照 TUTORIAL.md 与 tools/research/TUTORIAL.md。

5. Benchmark：测试 CPU／GPU 性能

先进入 tools/benchmark/；README 明确要求下列命令在此目录执行：

cd tools/benchmark

按需要选择一种运行方式：

python -m benchmark.cli
python -m benchmark.cli --cpu-only
python -m benchmark.cli --gpu-only
python -m benchmark.cli --report
python -m benchmark.cli --report --deploy

它们依次表示：运行全部测试、只测 CPU、只测 GPU、测试并生成 HTML 报告、测试并生成报告且发布到 Hugo 的 /benchmark/。结果以追加方式写入 CSV。实际 GPU 测试支持 CUDA、Apple MPS 和 Intel XPU；OpenCL 可能只出现在检测信息中。

6. Website：预览、构建与发布博客

博客基于 Hugo。README 给出了本地预览命令；从仓库根目录运行：

cd tools/website && hugo server -D

-D 会在开发服务器中包含草稿。发布脚本会增量压缩自上次构建后变动的图片和视频，随后翻译、构建并推送站点。按操作系统选择 README 中对应的命令：

macOS／Linux

cd tools/website && bash update.sh

Windows PowerShell

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

发布脚本会自动处理独立的 tools/website/public/ 部署仓库，不应直接向它提交。生成内容带有 gadget_generated 标记；没有该标记的手写文件不会被覆盖。

7. Translator：打开文档翻译页面

安装 translator 依赖后，从仓库根目录启动：

python -m translator

它会打开 Gradio 页面。README 列出的输入包括文本、.md、.txt、.pdf、.docx 和图片；翻译时会保护代码块、URL、Hugo shortcode 等 Markdown 片段。源语言可设为 auto，目标语言设为 auto 时会在中英文之间切换。模型会按需加载，首次使用可能下载。

8. 常用维护命令与输出位置

数据同步脚本的入口，以及 README 给出的跨设备推送／拉取形式：

python scripts/sync.py
python scripts/sync.py push/pull

第二行是 README 对两个操作的合写表示；实际使用时在 push 和 pull 中选一个。同步需要预先配置 rclone，设置位于 config.json 的 sync 部分。

进行不调用 LLM、不访问网络、不写入文件的跨工具冒烟检查：

bash scripts/smoke.sh

查看本地 Ollama 服务脚本输出的环境设置：

eval "$(bash scripts/serve_local_llm.sh env)"

生成物集中在 outputs/：logs/ 放中间日志，reports/ 放最终报告，cache/ 放缓存，data/ 放结构化数据，images/ 放图表和图片，backups/ 放覆盖操作的备份。该目录已被 Git 忽略。更细的配置值、数据格式及故障排查，README 明确指向仓库的 TUTORIAL.md 和各工具自己的文档；本教程没有补造那些未展示的步骤。

项目总结

Gadgets 是一个把日常开发中常用工具集中起来的仓库，包含 AI 对话报告、论文发现与分析、性能基准测试、Hugo 博客自动化和文档翻译。tools/ 下的工具彼此独立；common/ 提供共用的 LLM、缓存、文件读写、翻译和 Hugo 部署能力。

仓库结构

中文使用教程

以下仅整理 README 中给出的环境要求、配置说明和命令。各工具更细的操作、数据格式及 FAQ 请参阅 README 指向的 TUTORIAL.md 和各工具文档。

1. 环境准备

1. 准备 Python 3.10 或更高版本。README 推荐使用 Conda 环境 AI：

   conda activate AI
   

2. Node.js 18 或更高版本仅供独立的 ../ai-companion/ 仓库使用。

3. 根据需要准备工具所需的依赖。每个工具目录有自己的 requirements.txt；也可以安装 common、summarize、research、benchmark 和 website 的依赖：

   pip install -e ".[all]"
   

   .[all] 不包含 translator。如果需要翻译器，单独安装：

   pip install -e ".[translator]"
   

4. Website 的 .[website] 安装命令会包含翻译所需的 torch 和 transformers：

   pip install -e ".[website]"
   

2. 配置说明

• 工具设置放在仓库根目录的 config.json。README 提到可以从 config.example.json 复制；该文件被 git 忽略。
• 如需使用其他配置文件路径，可设置 GADGET_CONFIG。
• API 密钥和机器初始化表放在被 git 忽略的 tokens/ 目录中，切勿提交其中内容。
• Summarize 和 Research 的 LLM 后端可通过 --api 选择：ollama（默认）、claude_cli、anthropic 或 openai；也可用 GADGET_LLM_BACKEND 全局指定。
• Ollama 是默认的本地推理选项。README 提到网站和翻译功能默认使用本地推理；翻译后端还可通过 GADGET_TRANSLATION_BACKEND 指定。
• 跨设备数据同步依赖 rclone 配置。可用 python scripts/sync.py 查看 README 所述的同步入口。

README 没有列出各工具配置文件的完整字段、API 密钥的具体设置方式或 Ollama 的安装命令；这些细节需查看仓库教程和工具文档。

3. Summarize：生成 AI 对话报告

该工具读取 Claude Code、Codex、Cursor Agent、ChatGPT 或通用 JSON 格式的对话记录，通过 LLM 生成日、周、月报告。多设备场景下，先在设备上导出记录，再同步或手动汇总，之后按日期合并生成报告。

在仓库根目录执行：

python -m summarize daily export

导出尚未导出的日期后，合并所有日期：

python -m summarize daily merge --sync-all

生成并部署指定周的报告：

python -m summarize weekly generate --week 2026-W12 --deploy

生成并部署指定月份的报告：

python -m summarize monthly generate --month 2026-02 --deploy

也可以运行完整流程：

python -m summarize auto --deploy

支持 --api 切换 LLM 后端。README 还说明旧入口 python tools/summarize/daily_summary.py、weekly_summary.py 和 monthly_summary.py 仍兼容，但推荐使用 python -m summarize。

4. Research：论文发现与研究者分析

Research 通过 tools/research/research_scout.py 提供统一命令入口，覆盖论文搜索与报告、研究者画像、引用图分析和部署。

生成某个项目的研究报告：

python tools/research/research_scout.py report --project my-project

用自然语言查询论文：

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

生成研究者画像：

python tools/research/research_scout.py profile "Sergey Levine"

按 arXiv ID 或 DOI 分析引用关系：

python tools/research/research_scout.py citations 2301.12597

部署报告到 Hugo：

python tools/research/research_scout.py deploy

Research 的 LLM 功能支持通过 --api 选择后端。README 还介绍了深度论文洞察和会议论文、作者搜索等能力；具体参数和操作步骤请查阅工具教程。

5. Benchmark：CPU/GPU 性能基准测试

Benchmark 测量 CPU/GPU 浮点性能。README 要求先进入工具目录：

cd tools/benchmark

运行所有基准测试，结果追加到 CSV：

python -m benchmark.cli

只测 CPU 或只测 GPU：

python -m benchmark.cli --cpu-only
python -m benchmark.cli --gpu-only

运行测试并生成 HTML 报告：

python -m benchmark.cli --report

生成报告并发布到 Hugo 的 /benchmark/：

python -m benchmark.cli --report --deploy

README 提到 GPU 测试会检测 CUDA、Apple MPS 和 Intel XPU；OpenCL 仅可能出现在 --info 检测信息中，并非实际 GPU 测试后端。

6. Website：Hugo 博客

Website 是 Hugo 静态博客，包含增量媒体压缩、构建和发布流程。安装依赖：

pip install -e ".[website]"

macOS/Linux 上执行增量压缩、构建并发布：

cd tools/website && bash update.sh

Windows 上运行对应脚本：

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

本地预览（包含草稿）：

cd tools/website && hugo server -D

README 说明 Hugo 内容位于 tools/website/content|static；自动生成的文件带有 gadget_generated 标记。tools/website/public/ 是单独的部署仓库，由构建脚本自动提交并推送。

7. Translator：Gradio 文档翻译器

Translator 可翻译文本及 .md、.txt、.pdf、.docx 和图片文件，并尽量保留 Markdown 格式。它使用本地推理引擎，默认模型为 tencent/Hy-MT2-1.8B，首次使用时自动下载；模型也可通过 GADGET_TRANSLATION_MODEL 或 GUI 中的模型管理覆盖。

安装并启动：

pip install -e ".[translator]"
python -m translator

命令会启动 Gradio 图形界面并在浏览器中打开。README 没有给出 GUI 中逐步操作的细节。

8. 同步、初始化和辅助脚本

跨设备同步数据需要 rclone 配置。README 给出的入口是：

python scripts/sync.py

新机器初始化可先填写 tokens/onboard.yaml，再运行：

python scripts/onboard.py

该脚本会处理 SSH、Claude/Codex CLI 安装与认证、pip extras、ai-companion 安装、工具配置及 rclone 初始化。

运行只读的工具 smoke 检查：

bash scripts/smoke.sh

README 还列出 serve_local_llm.sh、language.py 和 profile_translation.py 等辅助脚本，但未提供它们的完整使用流程；使用前应查阅对应脚本或教程文档。

一、项目总结

1. Gadget 是什么

Gadget 是一组从日常开发中积累出来的实用工具，主要覆盖五类任务：

• AI 对话记录的日报、周报和月报生成
• 学术论文发现、论文深度分析和研究者画像
• CPU/GPU 浮点性能测试
• Hugo 博客构建、翻译、媒体压缩和自动发布
• 本地文档翻译

tools/ 下的五个工具彼此独立，可以单独使用。它们共同依赖仓库根目录下的 common/ 包。common/ 提供 LLM 调用、JSON 修复、磁盘缓存、原子写入、本地翻译和 Hugo 部署等通用能力。

项目的开发工作流和 Claude Code skills 不在本仓库中，而是在相邻目录的独立仓库 ../ai-companion/ 中，通过 .claude/ 和 .codex/ 下的 hooks 接入 Gadget。

项目采用 GPL-3 许可证。

2. 仓库结构

gadget/
├── tools/
│   ├── summarize/      # AI 对话日报、周报、月报
│   ├── research/       # 论文发现、研究者分析、引用图谱
│   ├── benchmark/      # CPU/GPU 性能测试
│   ├── website/        # Hugo 博客构建和发布
│   └── translator/     # Gradio 文档翻译器
├── common/             # 所有工具共享的基础设施
├── scripts/            # 同步、初始化、维护脚本
├── docs/               # 设计文档、ECL 计划、审计和历史文档
├── outputs/            # 自动生成的输出，已被 gitignore
├── AGENTS.md           # AI agent 工作协议
├── CLAUDE.md           # Claude Code 仓库指南
└── pyproject.toml      # Python 包及 extras 配置

修改不同类型的功能时，对应位置如下：

3. 各工具分别做什么

Summarize

读取 Claude Code、Codex、Cursor Agent、ChatGPT 或通用 JSON 格式的 AI 对话记录，生成结构化的日报、周报和月报。

它采用多设备、两阶段流程：

1. 在每台设备上导出对话记录。
2. 通过云盘同步或手动复制进行汇总，然后按日生成报告。

当日报积累到一定数量后，还可以进一步生成周报和月度趋势总结。

它通过 ccusage 20.x 的分来源命令统计不同 agent CLI 的 token 用量和费用，例如 ccusage claude、ccusage codex、ccusage gemini。

支持四种 LLM 后端：

• ollama：默认，本地运行，不需要 API key
• claude_cli：复用 Claude Code CLI 登录状态，不需要 API key
• anthropic
• openai

Research

统一的学术研究工具，入口为：

tools/research/research_scout.py

它有四项主要能力：

• 论文发现：从 arXiv、bioRxiv、PubMed 搜索论文，通过“快速筛选 → 深度评估 → 引用影响”三阶段 LLM 流程生成研究周报，并可发布到 Hugo。
• 深度论文洞察：下载论文全文，分析写作结构、发表策略和可复用知识；匹配 OpenReview 评论，分析审稿共识和争议；最后综合生成跨论文写作指南。
• 研究者画像：从 ArXiv 和 Semantic Scholar 获取论文及引用数据，生成研究轨迹分析、分层评分，并通过个人主页和合著模式推测导师—学生关系。
• 引用图谱：利用 Semantic Scholar API 分析前向引用和后向参考文献，再由 LLM 解读论文影响。

它同样支持 ollama、claude_cli、anthropic 和 openai 四种 LLM 后端。

Benchmark

跨平台 CPU/GPU FLOPS 浮点性能测试工具，支持：

• NVIDIA CUDA
• Apple Silicon MPS
• Intel XPU

OpenCL 可能出现在 --info 检测结果中，但 README 没有说明它能执行实际 GPU 测试。

支持的精度包括：

• FP64
• FP32
• FP16
• BF16
• FP8，实验性支持

测试过程包括预热、正式测量、中位数统计、IQR 异常值剔除以及显式 GPU 同步。

结果以追加方式写入 CSV，不会覆盖已有结果，因此可积累多台硬件的数据并形成排行榜。工具还可以用 Plotly 生成交互式 HTML 报告，并发布到 Hugo 网站或提交到公共排行榜。

Website

一个名为“TzJ’s Net”的 Hugo 静态博客，使用 PaperMod 主题，目标站点为 https://tzj2006.github.io/。

主要能力包括：

• 只压缩 .last_build 之后发生变化的媒体文件
• 使用 pngquant 压缩图片
• 使用 HandBrakeCLI 压缩视频
• 使用本地模型生成双语内容
• 自动构建 Hugo 网站
• 自动提交并推送 GitHub Pages 部署仓库

日报、周报、月报、研究报告、benchmark 页面和图片，会由部署流程直接写入：

tools/website/content
tools/website/static

自动生成文件带有 gadget_generated 标记。没有该标记的手写文件不会被覆盖。

tools/website/public/ 是独立的部署仓库，对应 tzj2006/tzj2006.github.io，不应手动向其中提交文件。

Translator

基于 Gradio 的本地文档翻译 Web 应用，界面类似 Google Translate。

支持翻译：

• 普通文本
• .md
• .txt
• .pdf
• .docx
• 图片

它会尽可能保留 Markdown 格式，并保护代码块、URL、Hugo shortcode 等片段。

翻译完全在本地推理，不使用云端 LLM API。它通过 common.engine.create_engine() 自动选择后端：

• 已拉取对应模型时优先使用 Ollama
• Windows 回退到 transformers
• Linux 优先使用 vLLM
• 低显存场景可使用 llama.cpp/GGUF

默认模型是：

tencent/Hy-MT2-1.8B

GGUF 版本为：

tencent/Hy-MT2-1.8B-GGUF

模型会在第一次使用时自动下载。模型加载后会常驻内存，切换模型时按需延迟加载。

源语言设为 auto 时，根据文本中的 CJK 字符比例自动检测；目标语言设为 auto 时，会在中译英和英译中之间自动切换。

4. 公共模块和运维脚本

common/

公共 Python 包，提供：

• 统一的两层 LLM API
• JSON 解析与修复
• 带命名空间和 TTL 的 SHA-256 磁盘缓存
• 原子写入和内容哈希
• 本地翻译引擎
• 双语内容生成
• 跨平台 Hugo 部署

scripts/

主要脚本包括：

• sync.py：通过 rclone 同步 summarize、website、research、benchmark 和 backups 数据，也支持生成及部署 DAG 站点。
• onboard.py：新机器的一次性初始化，负责 SSH、Claude/Codex CLI、认证、Python extras、AI Companion、工具配置和 rclone bootstrap。
• smoke.sh：只读 smoke test，检查帮助、硬件信息和导入，不调用 LLM、网络或执行写入。
• serve_local_llm.sh：创建适合 summarize 的 Ollama 模型变体并输出环境变量。
• language.py：Hugo 双语内容审计以及 summarize 报告重命名。
• profile_translation.py：翻译引擎 GPU profiler。

AI Companion

../ai-companion/ 是独立的 Node.js/TypeScript 仓库，提供：

• 函数级代码变更记录
• 测试和 HTML 报告生成
• /idea → /ccplan → /ccedit 规划执行流程
• Claude Code 和 Codex 集成
• 优化、调试、审计、清理、论文写作等 skills

Node.js 18+ 只在使用这个独立仓库时需要。

二、第一次使用 Gadget 的教程

以下教程严格限定在 README 已给出的信息和命令范围内。README 将更细的配置字段、数据格式和 FAQ 放在 TUTORIAL.md 及各工具自己的教程里，因此这里不会猜测未给出的配置项。

1. 环境准备

Python

需要 Python 3.10 或更高版本。

README 推荐使用名为 AI 的 conda 环境：

conda activate AI

README 没有提供创建该 conda 环境的命令，所以需要事先自行准备一个 Python 3.10+ 环境。

Node.js

只有在使用独立的 AI Companion 仓库时才需要 Node.js 18+：

../ai-companion/

仅运行 Gadget 的 Python 工具时，README 没有要求必须安装 Node.js。

其他外部组件

不同工具还可能需要：

• rclone：跨设备同步
• Hugo：博客构建和本地预览
• pngquant：图片压缩
• HandBrakeCLI：视频压缩
• Ollama：默认 LLM 或翻译后端
• PyTorch、NumPy、Plotly：benchmark
• Gradio、GGUF/transformers：translator

具体的工具依赖也可查看各工具目录中的 requirements.txt。

2. 安装

以下命令都应在 Gadget 仓库根目录执行，除非命令前明确要求切换目录。

安装公共包

pip install -e .

这是所有工具依赖的 common/ 基础包安装方式。

安装后，仓库根目录可能生成：

build/
gadget.egg-info/

它们是构建产物，已经被 gitignore，不应提交。

安装主要工具的全部 extras

pip install -e ".[all]"

这个 all 包含：

• summarize
• research
• benchmark
• website

但不包含 translator。

单独安装 Translator

pip install -e ".[translator]"

只安装 Website 相关依赖

pip install -e ".[website]"

这个 extras 包括网站翻译所需的 torch 和 transformers。

3. 基础配置

根配置文件

所有工具的主要设置位于仓库根目录的：

config.json

该文件不会被 Git 跟踪。README 要求从以下示例复制：

config.example.json

README 没有给出具体复制命令或各字段内容，因此应参照示例文件手动创建 config.json。

如需使用其他配置文件路径，可设置：

GADGET_CONFIG

LLM 后端

Summarize 和 Research 统一支持以下 --api 值：

• ollama
• claude_cli
• anthropic
• openai

默认值是 ollama。

也可以通过全局环境变量选择后端：

GADGET_LLM_BACKEND

注意：

• ollama 使用本地 Ollama，不需要 API key。
• claude_cli 复用 Claude Code CLI 的登录状态，不需要 API key。
• README 没有给出 Anthropic 和 OpenAI 密钥的具体变量名或配置字段，因此不要自行猜测，需查看项目教程或配置示例。

翻译配置

翻译模型可通过以下环境变量覆盖：

GADGET_TRANSLATION_MODEL

翻译后端可通过以下变量选择：

GADGET_TRANSLATION_BACKEND

默认模型：

tencent/Hy-MT2-1.8B

模型会在第一次使用时自动下载。

Token 和初始化配置

API key 和新机器初始化表放在：

tokens/

初始化表为：

tokens/onboard.yaml

tokens/ 已经被 gitignore，绝对不要提交其中的内容。

README 说明：填写 tokens/onboard.yaml 后运行 scripts/onboard.py，即可完成仓库级的一次性机器配置，包括：

• SSH 配置
• Claude/Codex CLI 安装和认证
• Python extras 安装
• AI Companion 安装
• 各工具配置
• rclone bootstrap

README 没有在命令块中给出 onboard.py 的完整调用示例，因此这里不扩展其参数。

4. Summarize 使用教程

Summarize 推荐使用统一入口：

python -m summarize

第一步：在当前设备导出对话记录

python -m summarize daily export

该命令执行多设备流程的第一阶段，导出所有尚未导出的日期。

每台有 AI 对话记录的设备都应执行这一阶段。

第二步：同步并按日合并

python -m summarize daily merge --sync-all

该命令同步所有日期的数据，并逐日合并生成日报。

生成指定周的周报

python -m summarize weekly generate --week 2026-W12 --deploy

其中：

• 2026-W12 表示 2026 年第 12 周。
• --deploy 表示生成后部署。

生成指定月份的月报

python -m summarize monthly generate --month 2026-02 --deploy

其中：

• 2026-02 表示 2026 年 2 月。
• --deploy 表示生成后部署。

一键运行完整流程

python -m summarize auto --deploy

它会依次完成：

export → merge → weekly → monthly → deploy

旧版入口

以下旧脚本仍然兼容：

python tools/summarize/daily_summary.py ...
python tools/summarize/weekly_summary.py ...
python tools/summarize/monthly_summary.py ...

但 README 推荐使用：

python -m summarize

README 没有列出旧入口的具体参数，因此不应把新入口参数直接假设为旧入口参数。

5. Research 使用教程

Research 的统一入口是：

python tools/research/research_scout.py

完整论文搜索和报告流程

python tools/research/research_scout.py report --project my-project

该命令执行：

搜索 → 三阶段评估 → 生成报告

my-project 是 README 示例中的项目名称。

使用自然语言搜索论文

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

工具会根据问题自动选择搜索来源。

生成研究者画像

python tools/research/research_scout.py profile "Sergey Levine"

研究者画像可能包括：

• ArXiv 和 Semantic Scholar 的论文数据
• 引用数据
• 研究轨迹分析
• tier score
• 导师—学生关系发现
• 同名消歧
• 反向查找

具体输出字段没有在 README 中展开。

分析论文引用图谱

使用 arXiv ID：

python tools/research/research_scout.py citations 2301.12597

README 表明该位置也支持 DOI，但没有提供 DOI 示例格式，因此不额外编造示例。

分析内容包括：

• 前向引用
• 后向参考文献
• LLM 驱动的影响力解读

将报告部署到 Hugo

python tools/research/research_scout.py deploy

深度论文洞察

README 说明 Research 支持 --insight，可以：

• 下载论文全文
• 分析写作结构
• 分析发表策略
• 提取可复用核心知识
• 匹配 OpenReview
• 分析审稿共识和争议
• 综合生成研究写作指南

但 README 没有给出完整的 --insight 命令组合，因此不应猜测它应放在哪个子命令之后。使用时应查看 tools/research/TUTORIAL.md。

6. Benchmark 使用教程

所有 Benchmark 命令都必须先进入其目录：

cd tools/benchmark

执行全部 benchmark

python -m benchmark.cli

结果会追加到 CSV 中，不覆盖已有结果。

只测 CPU

python -m benchmark.cli --cpu-only

只测 GPU

python -m benchmark.cli --gpu-only

工具会自动检测：

• CUDA
• Apple MPS
• Intel XPU

执行测试并生成 HTML 报告

python -m benchmark.cli --report

报告使用 Plotly 生成交互式图表。

执行测试、生成报告并部署

python -m benchmark.cli --report --deploy

报告将发布到 Hugo 网站的：

/benchmark/

测试采用预热、正式测量、中位数统计、IQR 异常值剔除和 GPU 同步。由于 CSV 使用追加模式，可以在不同硬件上反复运行并累积排行榜数据。

7. Website 使用教程

安装网站依赖

在仓库根目录运行：

pip install -e ".[website]"

macOS/Linux：构建并发布

cd tools/website && bash update.sh

该流程会执行：

• 增量压缩修改过的图片和视频
• 本地模型双语翻译
• Hugo 构建
• 提交并推送 GitHub Pages 部署仓库

Windows：构建并发布

在仓库根目录运行：

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

Windows 脚本会自动切换到自身目录，不需要提前执行 cd tools/website。

本地预览

cd tools/website && hugo server -D

-D 会让本地开发服务器包含草稿内容。

网站文件注意事项

自动生成内容直接写入：

tools/website/content
tools/website/static

带有 gadget_generated 标记的文件可能被自动更新；没有该标记的手写文件不会被覆盖。

不要手动提交或直接修改部署仓库：

tools/website/public/

它由构建脚本自动提交和推送。

8. Translator 使用教程

安装依赖

pip install -e ".[translator]"

启动翻译界面

python -m translator

启动后会打开浏览器中的 Gradio GUI。

可以在界面中：

• 输入文本进行翻译
• 上传 .md、.txt、.pdf、.docx 或图片
• 选择源语言和目标语言
• 管理或切换翻译模型

第一次运行时，默认模型会自动下载。

将源语言设为 auto 时，工具会通过 CJK 字符比例检测语言；将目标语言设为 auto 时，会自动在中文和英文之间反向翻译。

9. 数据同步

同步由 rclone 驱动，配置位于根目录 config.json 的 sync 部分。

查看同步工具入口：

python scripts/sync.py

跨设备推送和拉取分别使用：

python scripts/sync.py push

python scripts/sync.py pull

README 还说明 sync.py 支持：

status
bootstrap
config

以及 summarize、website、research、benchmark、backups 和特殊 dag 分类，但没有给出这些操作的完整命令组合，因此这里不扩展参数。

10. 本地 Summarize Ollama 环境

README 提供的启动及环境变量加载命令为：

eval "$(bash scripts/serve_local_llm.sh env)"

该脚本会创建适合 Summarize 的 Ollama 变体并输出环境设置。

长期配置项应写入根目录 config.json 的 summarize 部分，也可以用 GADGET_CONFIG 指向其他配置文件。

11. 运行只读 smoke test

bash scripts/smoke.sh

该检查只执行：

• --help
• --info
• Python 导入检查

它不会调用 LLM、访问网络或写入文件，适合安装后做基础验证。

12. 输出文件在哪里

所有可重建的生成物统一放在：

outputs/

结构如下：

outputs/
├── logs/         # 导出日志、运行日志等中间产物
├── reports/      # Markdown、JSON、HTML 最终报告
├── cache/        # LLM 和搜索缓存
├── data/         # CSV、JSON profile 等结构化数据
├── images/       # 图表和生成图片
└── backups/      # 强制覆盖前的备份

Hugo 内容不经过 outputs/site 暂存，而是直接写入：

tools/website/content
tools/website/static

13. 使用时必须注意

• 不要提交 tokens/ 中的 API key 或 onboarding 配置。
• 不要提交 outputs/ 中的自动生成文件。
• 不要提交 build/ 和 gadget.egg-info/。
• 不要提交 rclone 同步过来的数据。
• 不要直接提交 tools/website/ 下的部署仓库或主题仓库。
• config.json 是本地配置文件，应从 config.example.json 创建。
• Translator 不包含在 .[all] 中，需要单独安装 .[translator]。
• 网站和翻译功能使用本地推理模型，第一次运行时可能需要下载 tencent/Hy-MT2-1.8B。
• 更细的配置字段、数据格式、故障排除和 --insight 等未完整展示的用法，需要查阅仓库中的 TUTORIAL.md 和各工具教程；仅凭本 README 无法可靠补充。

项目概述

Gadgets 是一个开发者日常工具集合，覆盖五类任务：

• AI 对话记录的日报、周报、月报生成
• 学术论文检索、研究者分析与引用图谱
• CPU/GPU 性能基准测试
• Hugo 博客自动构建、媒体压缩与发布
• 本地模型驱动的文档翻译

tools/ 下的每个目录都是可独立使用的工具；根目录的 common/ 提供它们共用的能力，例如 LLM 调用、缓存、JSON 解析、原子写入、翻译引擎和 Hugo 部署。开发流程和 Claude Code 技能不在本仓库中，而在同级目录的独立仓库 ../ai-companion/。

仓库结构

gadget/
├── tools/
│   ├── summarize/   # AI 对话日报 / 周报 / 月报
│   ├── research/    # 论文发现、研究者分析、引用图谱
│   ├── benchmark/   # CPU/GPU 性能测试
│   ├── website/     # Hugo 博客及自动发布
│   └── translator/  # Gradio 文档翻译器
├── common/          # 所有工具共享的基础能力
├── scripts/         # 同步、初始化、检查等运维脚本
├── docs/            # 设计文档、ECL 计划、审计与历史资料
├── outputs/         # 可重新生成的输出文件（已忽略 Git）
├── AGENTS.md        # AI Agent 工作流程协议
├── CLAUDE.md        # Claude Code 仓库说明
└── pyproject.toml   # Python 打包与依赖配置

生成结果统一放在 outputs/：

outputs/
├── logs/      # 导出及运行日志
├── reports/   # Markdown、JSON、HTML 报告
├── cache/     # LLM 与搜索缓存
├── data/      # CSV、JSON 等结构化数据
├── images/    # 图表和生成图片
└── backups/   # 强制覆盖时的备份

Hugo 网站内容则直接写入 tools/website/content 和 tools/website/static。

各工具用途

使用教程

1. 环境准备

README 指定的基础环境为：

• Python 3.10+
• 推荐使用 Conda 环境 AI
• Node.js 18+：仅当需要使用同级的 ../ai-companion/ 仓库时需要
• 网站与翻译功能需要本地推理引擎：优先 Ollama；Linux 可使用 vLLM，Windows 可回退到 transformers
• 翻译模型 tencent/Hy-MT2-1.8B 会在首次使用时自动下载

如果使用 Conda：

conda activate AI

工具设置位于根目录 config.json，README 说明应从 config.example.json 复制得到。该配置文件可用环境变量覆盖路径：

GADGET_CONFIG

不要提交以下内容到 Git：

• tokens/ 内的 API 密钥和初始化表
• outputs/
• build/
• gadget.egg-info/
• tools/website/ 下的部署仓库和主题仓库
• 自动生成内容及 rclone 同步的数据

2. 安装依赖

先在仓库根目录安装共享包和常用工具依赖：

pip install -e ".[all]"

注意：all 不包含翻译器。若需要翻译器，再单独安装：

pip install -e ".[translator]"

如只使用网站功能：

pip install -e ".[website]"

各工具目录也有对应的 requirements.txt，可在需要时查阅。

3. LLM 与翻译后端配置

支持的统一 LLM 后端包括：

• ollama：默认，本地 Ollama，不需要 API Key
• claude_cli：复用 Claude Code CLI 登录状态，不需要 API Key
• anthropic
• openai

支持通过各工具的 --api 参数切换，也可以全局设置：

GADGET_LLM_BACKEND

翻译功能使用本地推理后端，可通过下列环境变量选择：

GADGET_TRANSLATION_BACKEND

README 给出的默认选择顺序是：

ollama → llamacpp / vllm / transformers

默认模型为：

tencent/Hy-MT2-1.8B

可通过下列环境变量替换翻译模型：

GADGET_TRANSLATION_MODEL

4. 使用对话总结工具：Summarize

该工具采用两阶段、多设备工作流：

1. 在每台设备导出对话日志。
2. 通过云盘同步或手动复制聚合数据，并按日期合并。
3. 生成日报后，再生成周报和月报。

导出所有尚未导出的日期：

python -m summarize daily export

同步所有日期并逐日合并：

python -m summarize daily merge --sync-all

生成周报并部署：

python -m summarize weekly generate --week 2026-W12 --deploy

生成月报并部署：

python -m summarize monthly generate --month 2026-02 --deploy

执行从导出、合并到周报、月报和部署的一键完整流程：

python -m summarize auto --deploy

旧入口仍保持兼容，但推荐使用上面的模块化形式：

python tools/summarize/daily_summary.py
python tools/summarize/weekly_summary.py
python tools/summarize/monthly_summary.py

该工具通过 ccusage 20.x 的分来源命令，自动发现并汇总各类 Agent CLI 的 token 使用与成本。可选 LLM 后端为 ollama、claude_cli、anthropic、openai。

5. 使用论文研究工具：Research

统一入口是：

python tools/research/research_scout.py

对某个项目执行完整论文发现流程：搜索、三阶段评估和报告生成：

python tools/research/research_scout.py report --project my-project

用自然语言搜索论文；工具会自动路由到合适的数据源：

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

生成某位研究者的画像：

python tools/research/research_scout.py profile "Sergey Levine"

根据 arXiv ID 或 DOI 分析引用图谱：

python tools/research/research_scout.py citations 2301.12597

将研究报告部署到 Hugo：

python tools/research/research_scout.py deploy

研究工具包括四类能力：

• 论文发现：来自 arXiv、bioRxiv、PubMed，经过快速筛选、深度评估、引用影响力分析三阶段流程。
• 深度论文洞察：通过 --insight 下载全文并分析写作结构、发表策略和可复用知识，也会匹配 OpenReview 的评审意见。
• 研究者画像：结合 ArXiv 与 Semantic Scholar 的论文、引用数据生成研究轨迹、评分和关系推断。
• 引用图谱：基于 Semantic Scholar API 做正向引用与参考文献分析，并由 LLM 解读影响力。

其 LLM 后端同样可用 --api 切换。

6. 使用性能测试工具：Benchmark

所有命令都要求先进入工具目录：

cd tools/benchmark

运行全部基准测试：

python -m benchmark.cli

只测 CPU：

python -m benchmark.cli --cpu-only

只测 GPU：

python -m benchmark.cli --gpu-only

运行测试并生成 HTML 报告：

python -m benchmark.cli --report

生成报告并发布至 Hugo 的 /benchmark/：

python -m benchmark.cli --report --deploy

该工具支持 NVIDIA CUDA、Apple Silicon MPS 和 Intel XPU 的实际 GPU 测试；OpenCL 只可能出现在 --info 检测中。结果以追加形式写入 CSV，不会覆盖原有结果，适合汇总多台机器的成绩。

7. 使用 Hugo 网站工具：Website

安装网站相关依赖：

pip install -e ".[website]"

在 macOS 或 Linux 上执行增量压缩、Hugo 构建和 Pages 推送：

cd tools/website && bash update.sh

在 Windows 上执行对应脚本：

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

本地启动 Hugo 预览服务器，并包含草稿内容：

cd tools/website && hugo server -D

网站自动处理以下工作：

• 仅压缩自 .last_build 后发生变化的媒体文件。
• 图片使用 pngquant，视频使用 HandBrakeCLI。
• 自动生成的日报、研究报告、Benchmark 页面等会直接写入 Hugo 内容根目录。
• 生成文件会带 gadget_generated 标记；没有该标记的手写文件不会被覆盖。
• 构建脚本会自动提交并推送 tools/website/public/ 中独立的 GitHub Pages 部署仓库。

不要直接向 tools/website/public/ 提交内容。

8. 使用文档翻译器：Translator

安装翻译器：

pip install -e ".[translator]"

启动 Gradio 图形界面：

python -m translator

启动后会在浏览器中打开本地翻译页面。

支持翻译：

• 纯文本
• .md
• .txt
• .pdf
• .docx
• 图片

翻译器会保护 Markdown 中的代码块、URL、Hugo shortcode 等片段，以尽可能保留原格式。源语言可设置为 auto，它会根据文本中 CJK 字符比例识别；目标语言设为 auto 时，会在中文和英文之间自动切换。

9. 运维与同步脚本

查看或执行集中式 rclone 数据同步：

python scripts/sync.py

README 明确列出了跨设备同步的推送和拉取形式：

python scripts/sync.py push
python scripts/sync.py pull

同步配置位于根目录 config.json 的 sync 部分，也可通过 GADGET_CONFIG 指定其他配置文件。

新机器的一次性初始化流程：

1. 填写 tokens/onboard.yaml。
2. 执行：

python scripts/onboard.py

它会完成 SSH、Claude/Codex CLI 安装与认证、pip extras、ai-companion、各工具配置以及 rclone 初始化。

执行不产生网络、LLM 调用或写入的只读冒烟检查：

bash scripts/smoke.sh

创建面向 summarize 的 Ollama 变体并输出环境配置：

eval "$(bash scripts/serve_local_llm.sh env)"

如需系统级安装 Ubuntu 22.04/24.04 服务器上的 SSH 公钥、Claude Code、Codex、Superpowers、Ponytail 和 AI Companion，可查看同级仓库脚本帮助：

bash ../ai-companion/scripts/onboard-server.sh --help

一、项目总结

1. Gadget 是什么

Gadget 是一个由多个独立工具组成的实用开发工具集合，覆盖：

• AI 对话日报、周报、月报生成
• 学术论文发现与研究者分析
• CPU/GPU 性能基准测试
• Hugo 博客自动构建与发布
• 本地模型驱动的文档翻译

每个 tools/ 子目录都是一个可以独立使用的工具。仓库根目录的 common/ 提供共享能力，包括：

• LLM 调用
• JSON 解析与修复
• 磁盘缓存
• 原子写入
• 本地模型翻译
• Hugo 部署

开发流程、代码变更跟踪和 Claude Code 技能由仓库外部的 ../ai-companion/ 提供。

2. 仓库结构

gadget/
├── tools/
│   ├── summarize/      # AI 对话日报、周报、月报
│   ├── research/       # 论文发现、研究者分析、引用图谱
│   ├── benchmark/      # CPU/GPU 性能测试
│   ├── website/        # Hugo 博客
│   └── translator/     # Gradio 文档翻译器
├── common/             # 共享基础设施
├── scripts/            # 同步、初始化、维护脚本
├── docs/               # 设计文档、计划和历史资料
├── outputs/            # 生成的报告、缓存、数据和图片
├── AGENTS.md           # AI Agent 工作流协议
├── CLAUDE.md           # Claude Code 使用说明
└── pyproject.toml      # Python 打包配置

需要修改时：

3. 各工具功能

summarize

读取 Claude Code、Codex、Cursor Agent、ChatGPT 等来源的 AI 对话记录，调用 LLM 生成：

• 日报
• 周报
• 月报和趋势总结

它采用多设备两阶段流程：

1. 各设备导出对话记录
2. 汇总数据并按天生成报告

同时通过 ccusage 统计不同 Agent CLI 的 token 使用量和成本。

支持四种 LLM 后端：

• ollama：默认，本地 Ollama，无需 API Key
• claude_cli：复用 Claude Code 登录状态
• anthropic
• openai

research

学术研究工具，包含四类能力：

• 论文发现：搜索 arXiv、bioRxiv、PubMed，并进行三阶段 LLM 评估
• 深度论文洞察：分析论文写作结构、发表策略、核心知识和 OpenReview 评审意见
• 研究者画像：结合 ArXiv 和 Semantic Scholar 数据分析研究轨迹、引用情况及导师-学生关系
• 引用图谱：分析论文的前向引用和后向参考文献

benchmark

跨平台 CPU/GPU 浮点性能测试工具。

支持：

• NVIDIA CUDA
• Apple Silicon MPS
• Intel XPU

支持多种精度，包括 FP64、FP32、FP16、BF16 和实验性的 FP8。

结果会追加写入 CSV，不会覆盖历史数据；还可以生成 Plotly 交互式 HTML 报告和排行榜。

website

基于 Hugo 的博客站点，使用 PaperMod 主题，发布到 GitHub Pages。

主要功能：

• 增量压缩图片和视频
• 自动翻译双语内容
• 自动构建 Hugo 网站
• 自动提交并推送部署仓库
• 接收日报、周报、研究报告、基准测试页面等自动生成内容

网站内容写入：

tools/website/content
tools/website/static

tools/website/public/ 是单独的部署仓库，不应直接提交到当前项目。

translator

基于 Gradio 的本地文档翻译器，支持：

• 文本
• Markdown
• TXT
• PDF
• DOCX
• 图片

它会保护 Markdown 代码块、URL 和 Hugo shortcode 等内容。默认使用本地模型 tencent/Hy-MT2-1.8B，也支持 GGUF 版本。

翻译后端由共享翻译引擎自动选择：

• Ollama
• vLLM
• transformers
• llama.cpp/GGUF

4. common/、scripts/ 和 outputs/

common/

共享 Python 包，安装后供各工具使用，包含 LLM、缓存、IO、翻译和 Hugo 部署功能。

scripts/

主要脚本包括：

• sync.py：使用 rclone 同步数据
• onboard.py：新机器初始化
• smoke.sh：对所有工具执行只读冒烟检查
• serve_local_llm.sh：创建适合 summarize 的 Ollama 模型变体
• language.py：检查 Hugo 双语内容
• profile_translation.py：分析翻译引擎 GPU 性能

outputs/

所有生成物集中在这里：

outputs/
├── logs/
├── reports/
├── cache/
├── data/
├── images/
└── backups/

该目录已被 Git 忽略，可以自动重新生成。

二、中文使用教程

1. 环境准备

项目要求：

• Python 3.10+
• Node.js 18+，仅 ../ai-companion/ 需要
• 各工具的额外依赖见对应目录中的 requirements.txt

README 推荐使用名为 AI 的 conda 环境：

conda activate AI

如果使用 AI Companion，还需要将其放在当前仓库的兄弟目录：

../ai-companion/

它是独立仓库，不属于 Gadget 本身。

2. 安装基础依赖

在仓库根目录执行：

pip install -e .

这会以可编辑模式安装根目录的 common/ 共享包。

如果要安装 summarize、research、benchmark 和 website 的依赖，可以执行：

pip install -e ".[all]"

注意：all 不包含 translator。

安装翻译器依赖：

pip install -e ".[translator]"

如果需要网站功能，可以执行：

pip install -e ".[website]"

网站依赖包含翻译所需的 PyTorch 和 transformers。

3. 配置文件和密钥

项目根目录的工具设置位于：

config.json

README 说明该文件被 Git 忽略，应从：

config.example.json

复制后再配置。

也可以通过环境变量指定其他配置文件路径：

GADGET_CONFIG

API Key 和初始化配置放在：

tokens/

该目录同样被 Git 忽略，不能提交到仓库。

LLM 后端可以统一通过 --api 选择：

• ollama
• claude_cli
• anthropic
• openai

也可以通过全局环境变量：

GADGET_LLM_BACKEND

进行设置。

翻译后端可以通过：

GADGET_TRANSLATION_BACKEND

控制，翻译模型可以通过：

GADGET_TRANSLATION_MODEL

覆盖。

4. 新机器初始化

项目提供一次性初始化脚本。README 要求先填写：

tokens/onboard.yaml

然后运行：

python scripts/onboard.py

该脚本会自动处理：

• SSH 配置
• Claude/Codex CLI 安装和认证
• pip extras 安装
• ai-companion 安装
• 各工具配置
• rclone 初始化

服务器级别的 Ubuntu 22.04/24.04 初始化脚本位于 ai-companion 仓库：

bash ../ai-companion/scripts/onboard-server.sh --help

5. 数据同步和基础检查

项目使用 rclone 进行跨设备数据同步。查看同步脚本帮助：

python scripts/sync.py

同步数据：

python scripts/sync.py push
python scripts/sync.py pull

运行只读冒烟检查：

bash scripts/smoke.sh

该检查会验证各工具的帮助信息、信息检测和导入，不会调用 LLM、访问网络或写入数据。

三、各工具使用方法

1. Summarize：生成 AI 对话报告

日报流程

第一阶段：导出所有尚未导出的日期：

python -m summarize daily export

第二阶段：同步所有日期并逐日合并：

python -m summarize daily merge --sync-all

生成指定周的周报，并部署到 Hugo：

python -m summarize weekly generate --week 2026-W12 --deploy

生成指定月份的月报，并部署到 Hugo：

python -m summarize monthly generate --month 2026-02 --deploy

一键执行完整流程

python -m summarize auto --deploy

该命令执行：

导出 → 合并 → 周报 → 月报 → 部署

旧版入口仍然兼容，例如：

python tools/summarize/daily_summary.py
python tools/summarize/weekly_summary.py
python tools/summarize/monthly_summary.py

但 README 推荐使用：

python -m summarize

LLM 后端

Summarize 默认使用本地 Ollama，也支持：

ollama
claude_cli
anthropic
openai

具体后端通过 --api 参数切换。

2. Research：论文搜索与研究者分析

生成研究项目报告

python tools/research/research_scout.py report --project my-project

该流程会执行论文搜索、三阶段评估并生成报告。

使用自然语言搜索论文

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

工具会根据问题自动选择数据源。

生成研究者画像

python tools/research/research_scout.py profile "Sergey Levine"

它会获取论文与引用数据，并生成研究轨迹分析。

分析论文引用图谱

python tools/research/research_scout.py citations 2301.12597

参数可以是 arXiv ID，也可以是 DOI。

部署研究报告

python tools/research/research_scout.py deploy

Research 的 LLM 后端同样支持：

ollama
claude_cli
anthropic
openai

通过 --api 统一切换。

3. Benchmark：运行 CPU/GPU 性能测试

README 特别说明：所有 Benchmark 命令都需要先进入目录：

cd tools/benchmark

运行全部基准测试：

python -m benchmark.cli

结果会追加到 CSV。

只运行 CPU 测试：

python -m benchmark.cli --cpu-only

只运行 GPU 测试：

python -m benchmark.cli --gpu-only

运行测试并生成 HTML 报告：

python -m benchmark.cli --report

运行测试、生成报告并部署到 Hugo：

python -m benchmark.cli --report --deploy

工具会自动检测 CUDA、Apple MPS 和 Intel XPU。OpenCL 只可能出现在 --info 检测结果中，并不代表会执行 OpenCL 基准测试。

4. Website：构建和预览 Hugo 网站

安装网站依赖：

pip install -e ".[website]"

macOS/Linux：构建并发布

cd tools/website && bash update.sh

该流程包括：

1. 增量压缩媒体文件
2. 执行 Hugo 构建
3. 推送到 GitHub Pages

图片使用 pngquant 压缩，视频使用 HandBrakeCLI 处理。

Windows：构建并发布

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

该脚本会自动切换到自身所在目录。

本地预览

cd tools/website && hugo server -D

-D 表示预览时包含 drafts。

网站中的自动生成内容会直接写入：

tools/website/content
tools/website/static

带有 gadget_generated 标记的自动生成文件可以被部署流程更新；没有该标记的手写文件不会被覆盖。

5. Translator：启动本地文档翻译器

安装翻译器依赖：

pip install -e ".[translator]"

启动 Gradio 图形界面：

python -m translator

启动后会打开浏览器。

翻译器支持文本和以下文件：

.md
.txt
.pdf
.docx
图片

默认模型是：

tencent/Hy-MT2-1.8B

GGUF 版本是：

tencent/Hy-MT2-1.8B-GGUF

模型首次使用时会自动下载。翻译器默认优先使用本地 Ollama；Linux 上可以使用 vLLM，Windows 上可以回退到 transformers，也支持低显存的 GGUF/llama.cpp 路径。

源语言可以设置为 auto，目标语言设置为 auto 时，会在中文和英文之间自动切换。

四、常见注意事项

• outputs/ 中的文件是自动生成物，不应提交。
• tokens/ 中包含密钥和初始化信息，不能提交。
• build/ 和 gadget.egg-info/ 是安装产生的构建文件。
• 不要直接提交 tools/website/public/ 或网站主题、部署仓库。
• 跨设备同步需要先配置 rclone。
• 网站和翻译功能依赖本地推理引擎，默认使用 Ollama。
• ../ai-companion/ 是独立仓库，负责开发工作流和技能。
• 项目使用 GPL-3 许可证。

下面内容只依据你给出的 README，总结与教程中不会补充 README 未出现的命令或参数。

一、项目总结

Gadget 是一个日常开发中积累的实用工具集合，覆盖 AI 对话日报/周报/月报生成、论文发现与研究者分析、性能基准测试、Hugo 博客自动化、文档翻译等场景。

它的核心设计是：tools/ 下的每个目录都是一个可以独立使用的工具；仓库根目录的 common/ 是共享基础设施包，通过 pip install -e . 安装，为各工具提供 LLM 调用、JSON 解析、磁盘缓存、原子写入、翻译、Hugo 部署等通用能力。开发工作流和 Claude Code skills 不在本仓库内，而是由相邻目录 ../ai-companion/ 中的独立仓库提供，并通过 hook 接入。

仓库结构

gadget/
├── tools/              # 五个独立工具
│   ├── summarize/      # AI 对话日报 / 周报 / 月报
│   ├── research/       # 论文发现、研究者分析、引用图
│   ├── benchmark/      # CPU/GPU 性能基准测试
│   ├── website/        # Hugo 博客，媒体压缩，自动构建发布
│   └── translator/     # Gradio 文档翻译器
├── common/             # 共享基础设施包
├── scripts/            # 运维与维护脚本
├── docs/               # 设计文档、ECL 计划、审计报告、历史归档
├── outputs/            # 所有生成产物，gitignored，可重新生成
├── AGENTS.md           # AI agent 工作流协议
├── CLAUDE.md           # Claude Code 仓库指南
└── pyproject.toml      # common 和各工具的 Python packaging 配置

outputs/ 用于集中存放生成结果：

outputs/
├── logs/         # 中间日志和运行日志
├── reports/      # 最终报告，Markdown / JSON / HTML
├── cache/        # LLM 缓存、搜索缓存
├── data/         # CSV、JSON profiles 等结构化数据
├── images/       # 图表和生成图片
└── backups/      # 强制覆盖备份

Hugo 网站内容不会先写入 outputs/site，而是由部署流程直接写入 tools/website/content|static。

各工具作用

tools/summarize/：AI 对话报告生成工具。
自动读取 Claude Code、Codex、Cursor Agent、ChatGPT、通用 JSON 等 AI 对话记录，调用 LLM 生成日报、周报、月度趋势总结。支持多设备流程：各设备导出对话日志，通过云盘同步或手动复制聚合，再生成最终报告。通过 ccusage 20.x 统计各 agent CLI 的 token 用量和成本。LLM 后端可通过 --api 统一切换，包括 ollama、claude_cli、anthropic、openai。

tools/research/：学术研究工具。
统一入口是 tools/research/research_scout.py，提供论文发现、深度论文洞察、研究者画像、引用图分析四类能力。支持 arXiv、bioRxiv、PubMed、Semantic Scholar，并用 LLM 完成筛选、评估、影响分析、写作结构分析、研究轨迹分析等。

tools/benchmark/：CPU/GPU 性能基准测试工具。
跨平台测量不同硬件和精度层级下的浮点性能，支持 NVIDIA CUDA、Apple Silicon MPS、Intel XPU 的实际 GPU 运行。结果追加写入 CSV，可生成 Plotly 交互式 HTML 报告和排行榜，也支持部署到 Hugo 网站。

tools/website/：Hugo 博客站点。
这是 Hugo 静态博客 “TzJ’s Net”，使用 PaperMod 主题，部署到 GitHub Pages。它带有增量图片/视频压缩流程，图片用 pngquant，视频用 HandBrakeCLI。自动生成内容会写入 tools/website/content|static，并带 gadget_generated 标记；没有这个标记的手写文件不会被覆盖。tools/website/public/ 是单独的部署仓库，不应直接提交。

tools/translator/：Gradio 文档翻译器。
基于 common 翻译引擎，提供类似 Google Translate 的本地翻译网页。支持文本和 .md、.txt、.pdf、.docx、图片等文件翻译，并尽量保留 Markdown 格式，保护代码块、URL、Hugo shortcode 等片段。默认模型是 tencent/Hy-MT2-1.8B，也有 GGUF 变体 tencent/Hy-MT2-1.8B-GGUF。

common/：共享基础设施。
提供统一 LLM 调用、JSON 解析和修复、SHA-256 磁盘缓存、原子写入、内容哈希、本地推理翻译引擎、双语内容生成、跨平台 Hugo 部署等能力。

scripts/：运维与维护脚本。
包括 sync.py 数据同步、onboard.py 新机器初始化、smoke.sh 只读 smoke 检查、serve_local_llm.sh 本地 Ollama 变体配置、language.py Hugo 双语审计和报告重命名、profile_translation.py 翻译引擎 GPU profiling 等。

../ai-companion/：独立仓库。
不属于 gadget 仓库本体。它负责函数级代码变更记录、测试和 HTML 报告生成、/idea→/ccplan→/ccedit 规划执行流程，以及 Claude Code skills。

二、中文使用教程

1. 环境准备

README 中列出的基础要求如下：

# Python 版本要求
Python 3.10+

推荐使用 conda 环境 AI：

conda activate AI

如果需要使用相邻的 ../ai-companion/ 仓库，则需要：

Node.js 18+

每个工具的特定依赖见对应目录下的 requirements.txt。

如果需要完整安装 common、summarize、research、benchmark、website 的 extras，可以在仓库根目录运行：

pip install -e ".[all]"

注意：all 不包含 translator。翻译器需要单独安装：

pip install -e ".[translator]"

网站和翻译功能使用本地推理引擎。README 中说明默认使用 Ollama；Linux 上可用 vLLM，Windows 上可用 transformers 作为 fallback。模型 tencent/Hy-MT2-1.8B 会在首次运行时自动下载。

2. 配置准备

工具配置位于仓库根目录的 config.json，该文件 gitignored。README 说明应从 config.example.json 复制而来。

如果需要覆盖配置文件路径，可以设置：

GADGET_CONFIG

LLM 后端可以通过各工具的 --api 参数切换，README 中出现的可选后端是：

ollama
claude_cli
anthropic
openai

也可以用全局环境变量：

GADGET_LLM_BACKEND

翻译后端由下面的环境变量控制：

GADGET_TRANSLATION_BACKEND

README 中说明翻译路径默认优先使用本地 Ollama server，后续可走 llamacpp / vllm / transformers。翻译模型可通过下面环境变量覆盖：

GADGET_TRANSLATION_MODEL

API key 和 onboarding 表位于 tokens/ 目录，该目录 gitignored，README 特别提醒不要提交其中内容。

3. 安装

在仓库根目录安装共享包和主要工具依赖：

pip install -e ".[all]"

如果要使用文档翻译器，再安装 translator extras：

pip install -e ".[translator]"

如果只针对 website 功能，README 给出的安装命令是：

pip install -e ".[website]"

4. 新机器初始化

README 提到新机器配置可以使用 scripts/onboard.py。流程是先填写：

tokens/onboard.yaml

然后运行：

python scripts/onboard.py

它会完成 SSH 配置、Claude/Codex CLI 安装和认证、pip extras、ai-companion 安装、各工具配置、rclone bootstrap 等。

服务器系统级安装已经迁移到 ../ai-companion/：

bash ../ai-companion/scripts/onboard-server.sh --help

5. 数据同步

跨设备数据同步使用 scripts/sync.py，需要 rclone 配置。

README 中给出的通用运行方式：

python scripts/sync.py

也提到跨设备同步可使用：

python scripts/sync.py push
python scripts/sync.py pull

配置位于仓库根目录 config.json 的 sync section，也可以用 GADGET_CONFIG 覆盖配置路径。

如果只是想同步数据，README 在仓库结构部分还明确写到：

python scripts/sync.py

6. Summarize：AI 对话日报、周报、月报

该工具推荐使用新的模块入口：

python -m summarize

典型流程如下。

导出所有尚未导出的日期：

python -m summarize daily export

同步所有日期并逐日合并：

python -m summarize daily merge --sync-all

生成并部署某一周的周报：

python -m summarize weekly generate --week 2026-W12 --deploy

生成并部署某一个月的月报：

python -m summarize monthly generate --month 2026-02 --deploy

一键执行完整流程：导出、合并、周报、月报并部署：

python -m summarize auto --deploy

旧入口仍然兼容：

python tools/summarize/daily_summary.py ...
python tools/summarize/weekly_summary.py ...
python tools/summarize/monthly_summary.py ...

但 README 推荐使用：

python -m summarize

LLM 后端可通过 --api 统一切换，README 中列出的值包括：

ollama
claude_cli
anthropic
openai

7. Research：论文发现、研究者分析、引用图

统一入口是：

python tools/research/research_scout.py

运行完整论文发现流程：搜索、三阶段评估、生成报告：

python tools/research/research_scout.py report --project my-project

自然语言搜索，工具会自动路由 source：

python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"

生成研究者画像：

python tools/research/research_scout.py profile "Sergey Levine"

按 arXiv ID 或 DOI 做引用图分析：

python tools/research/research_scout.py citations 2301.12597

部署研究报告到 Hugo：

python tools/research/research_scout.py deploy

所有 LLM 功能同样支持通过 --api 切换后端：

ollama
claude_cli
anthropic
openai

8. Benchmark：CPU/GPU 性能基准测试

README 明确说明 benchmark 的所有命令都需要先进入 tools/benchmark/：

cd tools/benchmark

运行全部 benchmark，结果追加写入 CSV：

python -m benchmark.cli

只运行 CPU：

python -m benchmark.cli --cpu-only

只运行 GPU：

python -m benchmark.cli --gpu-only

运行 benchmark 并生成 HTML 报告：

python -m benchmark.cli --report

生成报告并发布到 Hugo 的 /benchmark/：

python -m benchmark.cli --report --deploy

README 说明该工具会自动检测 CUDA、Apple MPS、Intel XPU。OpenCL 可能只出现在 --info 检测中，但 README 没有给出 --info 的具体命令示例。

9. Website：Hugo 博客

安装 website 依赖：

pip install -e ".[website]"

macOS/Linux 下增量压缩、Hugo 构建并推送 GitHub Pages：

cd tools/website && bash update.sh

Windows 下运行 PowerShell 脚本，脚本会切换到自身目录：

powershell -ExecutionPolicy Bypass -File tools/website/update.ps1

本地预览，包含 drafts：

cd tools/website && hugo server -D

README 中特别说明：

tools/website/public/ 是单独的部署仓库 tzj2006/tzj2006.github.io，由构建脚本自动 commit 和 push，不要直接提交它。

自动生成内容会写入：

tools/website/content
tools/website/static

带有 gadget_generated 标记的文件可被自动流程管理；没有该标记的手写文件不会被覆盖。

10. Translator：Gradio 文档翻译器

安装 translator 依赖：

pip install -e ".[translator]"

启动 Gradio GUI：

python -m translator

启动后会在浏览器中打开界面。

它支持翻译文本和文件，README 中列出的文件类型包括：

.md
.txt
.pdf
.docx
images

默认模型：

tencent/Hy-MT2-1.8B

GGUF 变体：

tencent/Hy-MT2-1.8B-GGUF

可以通过环境变量覆盖模型：

GADGET_TRANSLATION_MODEL

源语言可以设为 auto，通过文本 CJK 比例检测；目标语言为 auto 时，会在中英之间自动切换。

11. Smoke 检查和本地 LLM 辅助脚本

运行只读 smoke 检查：

bash scripts/smoke.sh

README 说明该脚本会检查各工具的 --help、--info、imports，不触发 LLM、网络或写入。

创建 summarize-tuned Ollama variant 并打印环境变量：

eval "$(bash scripts/serve_local_llm.sh env)"

持久化配置放在仓库根目录 config.json 的 summarize section，也可以用 GADGET_CONFIG 覆盖路径。

12. 使用注意事项

不要提交这些内容：

tokens/
outputs/
build/
gadget.egg-info/
tools/website/ 下的部署仓库或 theme repo
自动生成内容
rclone 同步数据

README 中明确说明：

• tokens/ 保存 API key 和 onboarding sheet，已 gitignored，不要提交。
• outputs/ 保存所有生成文件，已 gitignored。
• build/ 和 gadget.egg-info/ 是 pip install -e . 生成的构建产物。
• 跨设备同步依赖 rclone。
• 项目许可证是 GPL-3，见 LICENSE。

下面只依据你贴出的 README.md 整理，不补充 README 之外的命令、参数或行为。

项目是什么

Gadgets 是一个“日常开发里积累出来的实用工具集”。仓库里把不同功能拆成了 5 个独立工具，每个目录都能单独使用，同时把通用能力抽到了根目录的 common/ 包里。

它覆盖的方向主要是：

• AI 对话日报/周报/月报生成
• 论文发现与研究者分析
• CPU/GPU 性能基准测试
• Hugo 博客自动化发布
• 文档翻译

还有一个重要前提：开发工作流和 Claude Code skills 不在这个仓库里，而是在旁边的独立仓库 ../ai-companion/ 中，通过 hooks 接入。

仓库结构

gadget/
├── tools/              # 5 个独立工具
│   ├── summarize/      # AI 对话日报 / 周报 / 月报
│   ├── research/       # 论文发现 + 研究者分析 + citation graph
│   ├── benchmark/      # CPU/GPU 性能基准测试
│   ├── website/        # Hugo 博客
│   └── translator/     # Gradio 文档翻译器
├── common/             # 通用基础能力：LLM / cache / IO / translation / Hugo
├── scripts/            # 运维和维护脚本
├── docs/               # 设计文档、计划、归档
├── outputs/            # 所有生成产物
├── AGENTS.md           # 给 AI agent 的工作协议
├── CLAUDE.md           # Claude Code 仓库指南
└── pyproject.toml      # 包装配置

各工具分别做什么

• tools/summarize/：读取 AI 对话记录，生成日 / 周 / 月总结。
• tools/research/：做论文检索、研究者画像、引用关系分析。
• tools/benchmark/：做跨平台 CPU/GPU 性能测试，并生成报告。
• tools/website/：Hugo 博客自动化构建、压缩、发布。
• tools/translator/：Gradio 文档翻译器，支持文本和文件翻译。

common/ 是所有工具共享的基础库，提供：

• LLM 调用
• JSON 解析和修复
• 磁盘缓存
• 原子写入
• 翻译引擎
• Hugo 部署

scripts/ 里是一些运维脚本：

• sync.py：rclone 同步
• onboard.py：新机器初始化
• smoke.sh：只读 smoke 测试
• serve_local_llm.sh：创建 summarize 调优版 Ollama
• 其他：language.py、profile_translation.py

新手使用教程

下面按“环境准备 → 安装 → 配置 → 各工具用法”来写。

1. 环境准备

README 明确要求：

• Python 3.10+
• 推荐使用 conda activate AI
• Node.js 18+ 只给旁边的 ../ai-companion/ 仓库用
• ../ai-companion/ 是独立仓库，不在当前仓库内部
• 需要用到的具体依赖，以各工具目录下的 requirements.txt 为准

如果你只打算用本仓库的 Python 工具，重点就是 Python 环境；如果还要动 ai-companion，再准备 Node.js。

2. 安装

README 给出的安装方式有三层：

pip install -e .

这会安装根目录的 common/ 包和仓库的基础能力。

如果你要装大部分工具的额外依赖，可以用：

pip install -e ".[all]"

README 说明：

• all 包含 summarize / research / benchmark / website
• all 不包含 translator

如果你要用翻译器，再单独安装：

pip install -e ".[translator]"

网站翻译功能和翻译器都依赖本地推理引擎，README 里提到：

• 默认是 Ollama
• Linux 上可以用 vLLM
• Windows 上可以用 transformers
• 模型 tencent/Hy-MT2-1.8B 会在首次运行时自动下载

3. 配置

README 里提到的配置点如下：

• 根目录有 config.json
• config.json 默认是 gitignored
• 可以从 config.example.json 复制
• 可以用 GADGET_CONFIG 覆盖配置文件路径

环境变量方面：

• GADGET_LLM_BACKEND：统一切换 LLM 后端
• GADGET_TRANSLATION_MODEL：指定翻译模型
• GADGET_TRANSLATION_BACKEND：指定翻译后端

tokens/ 目录：

• 存放 API keys 和 onboarding 表
• 也是 gitignored
• 不能提交

如果你是新机器初始化，README 还提到：

• 填好 tokens/onboard.yaml
• 然后运行一次 scripts/onboard.py
• 它会自动处理 SSH、Claude/Codex 认证、pip extras、ai-companion 安装、各工具配置和 rclone bootstrap

README 没有在这一段里展开完整命令细节，所以我这里只保留它明确写到的内容，不额外补命令。

4. 各工具的典型用法

4.1 summarize：AI 对话日报 / 周报 / 月报

这个工具会自动读取你每天的 AI 对话记录，支持：

• Claude Code
• Codex
• Cursor Agent
• ChatGPT
• 通用 JSON

它还会结合 ccusage 20.x 的多源命令统计 token 和成本。

README 里给出的推荐命令是：

python -m summarize daily export
python -m summarize daily merge --sync-all
python -m summarize weekly generate --week 2026-W12 --deploy
python -m summarize monthly generate --month 2026-02 --deploy
python -m summarize auto --deploy

这些命令分别表示：

• daily export：导出所有未导出的日期
• daily merge --sync-all：同步所有日期并按天合并
• weekly generate --week ... --deploy：生成周报并部署
• monthly generate --month ... --deploy：生成月报并部署
• auto --deploy：一键完整流程，按 README 说法是 export → merge → weekly → monthly + deploy

可切换的 LLM 后端：

• ollama，默认
• claude_cli
• anthropic
• openai

README 也提到旧入口仍可用，但推荐新的形式：

python tools/summarize/daily_summary.py ...
python tools/summarize/weekly_summary.py ...
python tools/summarize/monthly_summary.py ...

4.2 research：论文发现、研究者分析、citation graph

这个工具的统一入口是：

python tools/research/research_scout.py

README 给出的典型命令：

python tools/research/research_scout.py report --project my-project
python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"
python tools/research/research_scout.py profile "Sergey Levine"
python tools/research/research_scout.py citations 2301.12597
python tools/research/research_scout.py deploy