项目总结

Gadgets 是一个旨在简化日常开发流程的实用工具集。它集成了 AI 助手、学术研究、性能基准测试、自动化博客发布以及文档翻译等多个功能模块。

仓库结构

• tools/: 项目的核心功能区，包含 5 个独立的工具：
  • summarize: 处理 AI 对话记录，生成日/周/月度总结报告。
  • research: 学术研究工具，包含论文发现、研究者分析及引用图谱。
  • benchmark: 跨平台的 CPU/GPU 性能基准测试套件。
  • website: 基于 Hugo 的博客系统，包含自动化部署和媒体压缩。
  • translator: 基于 Gradio 的文档翻译工具，支持多种格式且保留 Markdown 格式。
• common/: 共享基础设施包，包含 LLM 调用、缓存、翻译引擎、Hugo 部署等通用功能。
• scripts/: 运维与维护脚本，处理数据同步、环境初始化、语言检查等。
• outputs/: 存放所有生成的内容（日志、报告、缓存等），不计入 Git 仓库。
• ai-companion (独立仓库): 位于同级目录，提供开发工作流、代码变动追踪及一系列 AI 技能。

使用教程

本教程旨在帮助初学者快速上手 Gadget 项目。

1. 环境准备

在开始之前，请确保您的机器满足以下要求：

• Python: 3.10+（推荐使用名为 AI 的 Conda 环境）。
• Node.js: 18+（主要用于 ai-companion 模块）。
• 基础依赖: 建议先安装好基础的 rclone 工具（用于数据同步）。

2. 安装与初始化

克隆仓库后，进入项目根目录执行以下步骤：

基础安装（包含核心工具与大部分功能）：

pip install -e ".[all]"

若需使用翻译功能（需额外安装相关依赖）：

pip install -e ".[translator]"

新机器初始化（自动配置环境）： 如果你是第一次在某台机器上配置此项目，可以利用 onboarding 脚本：

1. 在 tokens/ 目录下填好 onboard.yaml（包含 API Key 等信息）。
2. 运行以下命令自动完成配置（包括 SSH、工具配置、rclone 初始化等）：

   python scripts/onboard.py
   

3. 核心工具使用指南

每个工具都可以在其对应的目录下独立运行或通过统一的模块调用。

A. AI 对话总结 (Summarize)

用于将你的 AI 对话记录（Claude, ChatGPT 等）整理成结构化的报告。

• 全自动流程（推荐）：

  python -m summarize auto --deploy
  

• 分步操作：
  • 导出未导出的日期：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

B. 学术研究 (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
  

C. 性能基准测试 (Benchmark)

跨平台的 CPU/GPU 性能测试。注意：执行前请进入对应目录。

cd tools/benchmark
# 运行所有基准测试并将结果追加到 CSV
python -m benchmark.cli
# 仅测试 GPU
python -m benchmark.cli --gpu-only
# 运行测试并生成 HTML 报告
python -m benchmark.cli --report
# 生成报告并发布到 Hugo 网站
python -m benchmark.cli --report --deploy

D. 文档翻译 (Translator)

启动一个 Gradio 界面，用于翻译各类文档（支持 .md, .pdf, .docx 等）。

• 启动翻译界面：

  python -m translator
  

E. 博客同步与部署 (Website)

用于管理和更新 Hugo 博客。

• 安装相关依赖：pip install -e ".[website]"
• 更新并推送内容：
  • Windows: powershell -ExecutionPolicy Bypass -File tools/website/update.ps1
  • Linux/macOS: cd tools/website && bash update.sh
• 本地预览：

  cd tools/website && hugo server -D
  

4. 其他常用操作

• 数据同步：如果你在多台设备上操作，可以使用同步脚本：

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

• 切换模型后端： 所有支持 LLM 的工具（Summarize, Research）都可以通过 --api 参数切换后端：ollama (默认), claude_cli, anthropic, openai。
  • 示例：python -m summarize auto --api anthropic

5. 注意事项

• 配置文件：项目核心配置位于根目录的 config.json（初次使用请复制 config.example.json）。
• 输出目录：所有生成的内容都会保存在 outputs/ 文件夹中。
• Git 规范：不要提交 outputs/、build/、gadget.egg-info 以及 tools/website/ 下的部署相关内容。

1. 项目总结

Gadgets 是一个由开发者日常积累的实用工具集，旨在通过 AI 能力自动化处理开发、研究和内容发布中的重复性任务。它不仅包含多个独立的工具，还通过一个核心共享包（common）构建了一套完整的自动化工作流。

仓库结构

• tools/: 核心工具目录，存放五个独立的工具产品。每个工具都可以独立运行。
• common/: 共享基础设施包。为所有工具提供统一的底层能力，如 LLM 调用、JSON 解析、磁盘缓存、原子写入、翻译引擎及 Hugo 部署功能。
• scripts/: 运维与维护脚本，用于数据同步、新机器初始化配置等。
• outputs/: 所有生成的产物（报告、缓存、日志、数据等）存放地。
• docs/: 设计文档与归档。
• ai-companion/ (外部仓库): 该项目通过 hook 关联的兄弟目录，负责提供开发工作流引擎（规划/执行/变更跟踪）及所有 Claude Code 相关技能。

工具功能概览

1. Summarize: AI 对话总结工具。自动读取不同设备的 AI 对话记录（Claude/ChatGPT 等），生成日/周/月报。
2. Research: 学术研究工具。支持论文发现、深度论文洞察（分析写作结构/OpenReview 评论）、研究员画像分析及引用图谱分析。
3. Benchmark: 性能测试套件。跨平台（NVIDIA/Apple/Intel）的 CPU/GPU 浮点运算性能测试。
4. Website: Hugo 博客管理。包含媒体自动压缩、双语翻译及自动化构建与发布流程。
5. Translator: 文档翻译器。基于 Gradio 的本地化翻译 Web 界面，支持保持 Markdown 格式的文档、图片及文件翻译。

2. 使用教程

本教程面向初次接触 Gadgets 的用户。

一、 环境准备

在开始之前，请确保您的系统已安装以下环境：

• Python 3.10+ (建议使用 Conda 管理环境，例如 conda activate AI)
• Node.js 18+ (主要用于关联的 ai-companion 仓库)
• Ollama (推荐，用于本地运行 LLM)

二、 安装与配置

1. 安装核心包及大部分工具: 进入项目根目录，运行以下命令安装 common 包以及大部分工具所需的依赖：

   pip install -e ".[all]"
   

2. 安装翻译器工具 (需额外安装): 由于翻译器依赖特定的 Gradio 和模型栈，需单独安装：

   pip install -e ".[translator]"
   

3. 初始化配置:

   • 项目使用 config.json 进行配置。请先从模板复制一份：

     cp config.example.json config.json
     

   • 新机器一键配置: 如果您是在一台全新的服务器上部署，可以使用内置的 onboarding 脚本（需先准备好 tokens/onboard.yaml）：

     python scripts/onboard.py
     

三、 工具典型用法

1. 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
  

• 一键全流程 (导出 $\rightarrow$ 合并 $\rightarrow$ 周报 $\rightarrow$ 月报 $\rightarrow$ 部署)

  python -m summarize auto --deploy
  

• 提示：可通过 --api 参数切换后端，如 --api ollama 或 --api openai。

2. Research (学术研究)

使用统一的入口 research_scout.py 进行操作。

• 执行完整调研流水线 (搜索 $\rightarrow$ 评估 $\rightarrow$ 报告)

  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)

  python tools/research/research_scout.py citations 2301.12597
  

3. Benchmark (性能测试)

注意： 运行前请先进入工具目录。

cd tools/benchmark
# 运行所有测试（结果追加至 CSV）
python -m benchmark.cli
# 仅运行 GPU 测试
python -m benchmark.cli --gpu-only
# 运行测试、生成 HTML 报告并发布到 Hugo 网站
python -m benchmark.cli --report --deploy

4. Website (博客管理)

• 本地预览

  cd tools/website && hugo server -D
  

• 更新网站 (压缩媒体 $\rightarrow$ 构建 $\rightarrow$ 推送到 GitHub Pages)
  • macOS/Linux: bash update.sh
  • Windows: powershell -ExecutionPolicy Bypass -File update.ps1

5. Translator (文档翻译)

• 启动 Gradio 图形界面

  python -m translator
  

  启动后，在浏览器中打开显示的地址即可进行文档翻译。首次运行时会自动下载 tencent/Hy-MT2-1.8B 模型。

1. 项目总结：Gadget 是什么？

Gadget 是一个开源的开发者工具集仓库，旨在通过自动化脚本和集成工作流，解决日常开发中的痛点。它不仅仅是一个代码库，更是一套涵盖 AI 报告生成、学术科研辅助、性能基准测试、博客自动化运维、文档翻译 的完整生态系统。

该项目采用“共享基础设施 + 独立工具”的架构设计，所有工具都依赖于根目录下的 common 包来处理 LLM 调用、缓存、原子写入等通用任务。

仓库结构概览

gadget/
├── tools/              # 核心工具目录（每个子目录是一个独立应用）
│   ├── summarize/      # AI 对话日报/周报/月报生成器
│   ├── research/       # 论文发现、研究者分析、引用图谱工具
│   ├── benchmark/      # CPU/GPU 跨平台性能基准测试
│   ├── website/        # 基于 Hugo 的个人博客站点（含自动压缩与部署）
│   └── translator/     # 基于 Gradio 的本地文档翻译 Web 应用
├── common/             # 共享基础设施包（LLM API、缓存、翻译引擎、Hugo 部署）
├── scripts/            # 运维脚本（数据同步、新机器初始化、冒烟测试）
├── docs/               # 设计文档、计划、审计报告
├── outputs/            # 所有生成产物的存放地（已 gitignore，可重建）
├── AGENTS.md           # AI 代理工作协议
├── CLAUDE.md           # Claude Code 指引
└── pyproject.toml      # Python 打包配置（支持 pip install -e .）

注：开发工作流和技能（Skills）位于独立的同级仓库 ../ai-companion/ 中。

各工具功能详解

2. Gadget 详细使用教程

本教程面向首次使用 Gadget 的开发者。我们将按照 环境准备 -> 安装配置 -> 各工具使用 的顺序进行。

第一阶段：环境准备与安装

1.1 环境要求

• Python: 3.10+ (推荐在 Conda 环境中，环境名为 AI)
• Node.js: 18+ (仅当需要使用 ai-companion 仓库的功能时需要)
• 依赖工具:
  • rclone: 用于数据同步（可选，多设备用户必装）
  • Hugo: 静态站点生成器（用于 Website 工具）
  • pngquant & HandBrakeCLI: 用于媒体压缩（用于 Website 工具，可选但推荐）
  • Ollama: 本地 LLM 运行环境（推荐，用于默认 LLM 后端和翻译）

1.2 克隆仓库

# 克隆主仓库
git clone git@github.com:TzJ2006/gadget.git
cd gadget

# 克隆 AI 伴侣仓库（同级目录，用于开发工作流和技能）
git clone git@github.com:TzJ2006/ai-companion.git ../ai-companion

1.3 安装 Python 依赖

Gadget 使用 pyproject.toml 管理依赖。

方案 A：安装除 Translator 外的所有核心工具依赖（推荐大多数用户）

# 激活 Python 环境
conda activate AI  # 或者你的虚拟环境

# 安装 common 包及 summarize, research, benchmark, website 的依赖
pip install -e ".[all]"

方案 B：如果需要文档翻译功能 [all] 不包括 translator，因为它的依赖较大（涉及 GPU 推理栈）。

# 单独安装 Translator 依赖
pip install -e ".[translator]"

注意：translator 依赖包括 gradio, gguf 翻译栈等。

1.4 配置配置文件

工具配置位于仓库根目录的 config.json（该文件已被 gitignore，需手动创建）。

1. 复制示例配置：

   cp config.example.json config.json
   

2. 编辑 config.json，填入必要的 API 密钥（如果你使用 Claude/Anthropic/OpenAI 后端）或调整其他设置。
   • LLM 后端切换：全局默认通过 --api 参数或环境变量 GADGET_LLM_BACKEND 控制。
   • 翻译模型：默认使用 tencent/Hy-MT2-1.8B，首次运行自动下载。

1.5 新机器一键初始化（可选）

如果你是在新服务器上配置，可以使用自带的 Onboard 脚本自动配置 SSH、CLI 认证、Pip 依赖等。

# 1. 填写 tokens/onboard.yaml (包含 SSH 密钥、API Keys 等敏感信息，请勿提交)
# 2. 运行初始化脚本
python scripts/onboard.py

该脚本会自动完成：SSH 配置、Claude/Codex CLI 安装与认证、Pip Extras 安装、Rclone 基础配置。

第二阶段：各工具典型用法

2.1 Summarize：AI 对话日报/周报/月报

此工具自动聚合你在不同设备上（Claude Code, Codex, ChatGPT 等）的 AI 对话记录，生成统计报告。

前置条件：确保各 AI 工具的日志导出功能已开启，或手动导出日志到指定目录。

典型工作流：

1. 第一阶段：导出对话日志 将所有未导出的日期的对话日志提取出来。

   python -m summarize daily export
   

2. 第二阶段：同步与合并 如果你有多台设备，先通过 scripts/sync.py 同步数据，然后合并每日数据。

   # 同步所有日期的数据并逐日合并
   python -m summarize daily merge --sync-all
   

3. 生成报告

   # 生成指定周的周报并部署到博客
   python -m summarize weekly generate --week 2026-W12 --deploy
   
   # 生成指定月的月报并部署到博客
   python -m summarize monthly generate --month 2026-02 --deploy
   

4. 一键全流程（推荐） 自动执行：导出 -> 合并 -> 生成周报 -> 生成月报 -> 部署。

   python -m summarize auto --deploy
   

提示：默认使用 ollama 后端（本地 Qwen3.8-27B），无需 API Key。如需切换，使用 --api claude_cli 或 --api anthropic。

2.2 Research：科研助手

这是一个强大的学术工具，支持自然语言查询、论文深度分析、学者画像和引用图谱。

1. 自然语言搜索论文 自动路由到合适的数据源（arXiv, PubMed 等）。

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

2. 生成完整研究周报 执行全流程：搜索 -> 三阶段 LLM 评估（快筛 -> 深评 -> 引用影响）-> 生成报告。

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

3. 研究者画像 获取学者的论文、引用数据，生成轨迹分析、评分及导师-学生关系。

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

4. 引用图谱分析 基于 arXiv ID 或 DOI，分析前向引用和后向参考文献。

python tools/research/research_scout.py citations 2301.12597

5. 部署报告到博客

python tools/research/research_scout.py deploy

2.3 Benchmark：性能基准测试

测量 CPU/GPU 的 FLOPS 性能，支持 NVIDIA (CUDA), Apple Silicon (MPS), Intel (XPU)。

注意：Benchmark 命令需要在 tools/benchmark/ 目录下执行。

1. 运行所有基准测试 结果会追加到 CSV 文件中（支持多硬件累积）。

cd tools/benchmark
python -m benchmark.cli

2. 仅测试 CPU 或 GPU

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

3. 生成 HTML 报告

python -m benchmark.cli --report

4. 生成报告并部署到博客 将基准测试结果发布到 Hugo 网站的 /benchmark/ 路径下。

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

查看报告：访问 https://tzj2006.github.io/benchmark/

2.4 Website：Hugo 博客自动化

此工具负责将其他工具生成的内容（日报、周报、图表）整合到博客，并处理媒体压缩和双语翻译。

1. 更新博客（压缩 + 构建 + 部署） 这是最核心的命令，执行增量压缩（仅处理新文件）、Hugo 构建、并推送到 GitHub Pages。

# macOS / Linux
cd tools/website && bash update.sh

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

2. 本地预览 在本地启动 Hugo 开发服务器，查看草稿和最新更改。

cd tools/website
hugo server -D

注意：-D 表示包含草稿（Drafts）。

3. 翻译机制 Website 工具内置了翻译引擎。在构建过程中，它会自动检测双语内容，并调用本地模型（默认 tencent/Hy-MT2-1.8B）进行翻译。

• 默认后端：ollama
• 备选后端：vllm (Linux), transformers (Windows)
• 模型会自动下载，无需手动配置。

2.5 Translator：本地文档翻译

提供一个 Web 界面，用于翻译本地文件（.md, .pdf, .docx, 图片等），并保留 Markdown 格式。

1. 启动翻译服务

# 确保已安装 translator 依赖: pip install -e ".[translator]"
python -m translator

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

2. 使用方式

1. 打开浏览器中的本地地址（通常是 http://127.0.0.1:7860）。
2. 上传文件或输入文本。
3. 选择源语言和目标语言（支持 auto 自动检测）。
4. 点击翻译。
5. 复制结果或下载翻译后的文件。

高级配置：

• 模型切换：默认使用 tencent/Hy-MT2-1.8B。可以通过 GUI 中的模型管理界面切换，或设置环境变量 GADGET_TRANSLATION_MODEL。
• 后端切换：默认优先 ollama。如果未安装 Ollama，会自动回退到 transformers (Windows) 或 vllm (Linux)。也可通过 GADGET_TRANSLATION_BACKEND 强制指定。

第三阶段：运维与数据同步

3.1 数据同步 (Rclone)

如果你在多设备间开发，可以使用内置的同步脚本。

# 查看同步状态
python scripts/sync.py status

# 推送本地更改到云端
python scripts/sync.py push

# 从云端拉取最新数据
python scripts/sync.py pull

配置位于 config.json 的 sync 部分。

3.2 冒烟测试 (Smoke Test)

在运行完整流程前，可以快速检查环境是否配置正确（只读操作，不消耗 LLM Token）。

bash scripts/smoke.sh

3.3 输出目录管理

所有生成物（日志、报告、图表、缓存）都存放在 outputs/ 目录下。

• 该目录已被 .gitignore 忽略。
• 如果删除了 outputs/，所有报告均可通过重新运行对应工具的 generate 命令重建。

常见问题 (FAQ)

Q: 如何使用不同的 LLM 后端？ A: 大多数工具支持 --api 参数。

• ollama (默认): 本地运行，无需 Key，推荐 Qwen3.8-27B。
• claude_cli: 复用 Claude Code 的登录状态，无需额外 API Key。
• anthropic: 使用 Anthropic API Key。
• openai: 使用 OpenAI API Key。 全局默认值可通过环境变量 GADGET_LLM_BACKEND 设置。

Q: 翻译为什么这么慢/失败？ A: 翻译使用本地推理。

1. 确保 Ollama 正在运行且已拉取模型 (ollama pull tencent/Hy-MT2-1.8B)。
2. 如果没有 Ollama，程序会回退到 transformers (CPU/内存消耗较大) 或 vllm (GPU)。
3. 检查 GADGET_TRANSLATION_BACKEND 环境变量是否正确指向你已安装的后端。

Q: 博客部署失败了？ A:

1. 检查 config.json 中的 Hugo 路径和 Git 配置。
2. 确保 tools/website/public/ 目录是一个独立的 Git 仓库（通常由脚本自动管理，不要手动 git add 此目录下的文件到主仓库）。
3. 查看 outputs/logs/ 中的构建日志。

Q: 如何备份？ A: 你的源代码在 Git 中。你的数据（对话日志、CSV 基准数据、生成的报告）建议在 outputs/ 目录之外或通过 scripts/sync.py 同步到云端。tokens/ 目录包含敏感信息，请自行备份，切勿提交到 Git。

教程结束。祝使用愉快！如有更多问题，请参阅 TUTORIAL.md 和各工具目录下的文档。

以下是基于提供的 README 内容整理的项目总结和详细使用教程。

第一部分：项目总结

1. 它是什么？

Gadget 是一个面向开发者的实用工具集，主要服务于日常开发工作流。它的核心功能涵盖：

• AI 报告生成：自动汇总 AI 对话记录并生成日报/周报/月报。
• 学术研究辅助：论文发现、研究者画像分析及引用关系图谱构建。
• 性能基准测试：跨平台（CPU/GPU）的性能跑分工具。
• 博客自动化：基于 Hugo 的博客搭建与自动发布系统，支持媒体压缩和本地翻译。
• 文档翻译：基于 Gradio的本地文档翻译网页应用。

该项目采用模块化设计，每个工具独立运行，共享底层基础设施 (common)，并依赖于一个独立的外部仓库 ai-companion 来提供开发工作流和代码变更追踪功能。

2. 仓库结构

gadget/
├── tools/              # 五个独立的工具模块（核心功能）
│   ├── summarize/      # AI 对话日报/周报/月报生成
│   ├── research/       # 论文发现、研究者分析与引用图谱
│   ├── benchmark/      # CPU/GPU 性能基准测试
│   ├── website/        # Hugo 博客系统（含自动化构建与发布）
│   └── translator/     # Gradio 文档翻译器
├── common/             # 共享基础设施包 (LLM调用、缓存、IO、翻译、Hugo部署等)
├── scripts/            # 运维与维护脚本 (同步、新机配置、烟雾测试等)
├── docs/               # 设计文档、ECL计划、审计报告及历史归档
├── outputs/            #所有生成的产物（报告、日志、缓存），已被 gitignore
├── AGENTS.md           # AI Agent 工作流协议
├── CLAUDE.md           # Claude Code 仓库指南
└── pyproject.toml      # Python 打包配置

关键依赖：

• ai-companion: 位于上级目录 ../ai-companion/，提供代码变更追踪、规划执行工作流和技能，通过 hooks集成到此项目。

3. 每个工具分别做什么？

第二部分：详细中文使用教程

本教程面向首次接触该项目的用户。请严格依据 README 提供的信息操作。

1. 环境准备

在安装之前，请确保满足以下基础环境要求：

• Python: 版本 3.10+。推荐使用 conda 环境 AI (conda activate AI)。
• Node.js: 版本 18+（仅用于独立的 ai-companion 仓库，本 repo 核心工具主要依赖 Python）。
• Git: 用于克隆代码。

前置检查（Smoke Test）： 在配置过程中，你可以运行以下命令进行只读的烟雾测试，确保无报错：

bash scripts/smoke.sh

2. 安装与初始化

第一步：克隆仓库并准备依赖

假设你的工作目录下已经存在 ai-companion 仓库。

1. 克隆 Gadget 仓库（如果尚未克隆）：

   git clone <gadget_repo_url>
   cd gadget
   

2. 安装共享基础设施包 (common) 及所有核心工具依赖： README 指出 common 是基础，而各工具作为 extras 安装。为了覆盖 summarize, research, benchmark, website，建议安装 all 额外包。

   注意：translator 不包含在 all 中，需要单独安装。

   # 安装 common 及 summarize/research/benchmark/website 的依赖
   pip install -e ".[all]"
   
   # 如果需要使用 Translator 工具，额外执行：
   pip install -e ".[translator]"
   

3. 配置 AI Companion（工作流引擎）： Gadget 的开发工作流依赖上级目录 ../ai-companion/。请确保该目录存在并已正确初始化。具体安装步骤参考 ../ai-companion/scripts/install.ts。

第二步：配置文件与密钥

1. 创建配置文件： 所有工具设置位于根目录的 config.json 中（该文件被 gitignore）。

   # 复制示例配置并修改
   cp config.example.json config.json
   

   • 可以通过环境变量 GADGET_CONFIG 指定配置文件路径。

2. 管理密钥 (Tokens)： API 密钥和 Onboarding 信息存储在 tokens/ 目录中（被 gitignore，切勿提交到 Git）。

   • API Keys: 放在 tokens/ 下对应位置。
   • Onboarding Sheet: 填写 tokens/onboard.yaml 用于一键配置机器。

3. 设置 LLM 后端： 默认使用 ollama (本地，无需 Key，使用 Qwen3.8-27B)。 全局切换可以通过环境变量 GADGET_LLM_BACKEND 或在 config.json 中设置。支持的值：ollama, claude_cli, anthropic, openai。

3. 工具详细用法

A. Summarize: AI 对话报告生成

场景：自动汇总多设备 AI 对话，生成日报/周报。 架构：两阶段（导出 -> 合并/生成）。

1. Phase 1: 导出未导出的日期数据

   python -m summarize daily export
   

2. Phase 2: 同步所有日期并合并每日数据

   python -m summarize daily merge --sync-all
   

3. 生成周报

   • 指定特定周（例如 2026年第12周）：

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

   • --deploy 参数会将报告发布到 Hugo 博客。

4. 生成月报

   • 指定特定月份（例如 2026年2月）：

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

5. 一键全量流程 执行完整管道：导出 -> 合并 -> 周/月报生成 -> 部署。

   python -m summarize auto --deploy
   

提示：后端切换使用 --api 参数（如 --api openai），具体支持 ollama, claude_cli, anthropic, openai。

B. Research: 学术研究助手

入口命令: python tools/research/research_scout.py

1. 完整流水线：论文搜索与报告生成

   python tools/research/research_scout.py report --project my-project
   # 流程：搜索 -> 三阶段评估(快速筛选->深度评估->引用影响) -> 生成报告
   

2. 自然语言搜索论文

   python tools/research/research_scout.py ask "找 Pieter Abbeel 最近的机器人操作论文"
   # 自动路由到合适的数据源(arXiv/PubMed等)
   

3. 生成研究者画像

   python tools/research/research_scout.py profile "Sergey Levine"
   # 包含研究轨迹分析、师生关系挖掘等
   

4. 查看引用图谱

   python tools/research/research_scout.py citations 2301.12597
   # 通过 arXiv ID 或 DOI 分析前向/后向引用
   

5. 部署报告到博客

   python tools/research/research_scout.py deploy
   

提示：同样支持 --api 切换后端。深入分析论文内容可使用 --insight 参数（需查阅源码文档获取具体用法，README仅列出入口）。

C. Benchmark: 性能基准测试

注意：所有命令需在 tools/benchmark/ 目录下执行。

cd tools/benchmark

1. 运行所有测试 (CPU + GPU) 结果追加写入 CSV，不会覆盖旧数据。

   python -m benchmark.cli
   

2. 仅 CPU 测试

   python -m benchmark.cli --cpu-only
   

3. 仅 GPU 测试 自动检测 CUDA / MPS / XPU。

   python -m benchmark.cli --gpu-only
   

4. 生成 HTML 报告

   python -m benchmark.cli --report
   

5. 生成报告并部署到 Hugo 博客 将结果发布到 /benchmark/ 路径。

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

D. Website: Hugo 博客管理

目录: tools/website/

1. 本地预览 (开发模式)

   cd tools/website
   hugo server -D
   

2. 构建并发布到 GitHub Pages (macOS/Linux) 此脚本会执行增量媒体压缩、Hugo 构建和推送。

   bash update.sh
   

3. 构建并发布到 GitHub Pages (Windows)

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

重要警告：tools/website/public/ 是一个独立的部署仓库。不要直接对该目录进行 git commit，它由脚本自动管理。

E. Translator: 文档翻译器

场景：通过 Web UI 翻译 Markdown、PDF 等文件，保留格式。

1. 启动 Gradio 界面

   python -m translator
   # 浏览器会自动打开 (或访问 localhost:7860)
   

2. 配置默认模型 默认使用 tencent/Hy-MT2-1.8B，首次运行自动下载。 可通过环境变量 GADGET_TRANSLATION_MODEL 覆盖。

3. 后端切换 默认优先 Ollama。Windows 下回退到 transformers，Linux 下可配置 vLLm 或 GGUF。

4. 运维与维护 (Scripts)

数据同步 (Sync)

用于多设备间同步 summarize/website/research 等产生的数据。

# 推送数据
python scripts/sync.py push

# 拉取数据
python scripts/sync.py pull

# 查看状态
python scripts/sync.py status

配置在 config.json 的 sync 部分。需先配置 rclone。

新机快速配置 (Onboarding)

如果是新机器，填写 tokens/onboard.yaml 后运行：

python scripts/onboard.py

这将自动完成 SSH、CLI 认证、pip 依赖安装和 rclone bootstrap。

服务器级一键部署

针对 Ubuntu 服务器的系统级安装（Claude Code, Codex等）在 ai-companion 仓库中：

bash ../ai-companion/scripts/onboard-server.sh --help
# 示例用法 (需传入 ai-companion 路径)
# bash ../ai-companion/scripts/onboard-server.sh --companion-repo git@github.com:TzJ2006/ai-companion.git

5. 输出与注意事项

• 所有生成文件均位于 outputs/ 目录（日志、报告、缓存等），该目录已加入 .gitignore。
• 不要提交：
  • outputs/ 下的任何内容。
  • tokens/ 下的密钥。
  • tools/website/public/ (它是独立仓库)。
  • build/ 和 gadget.egg-info/。
  • rclone 同步的数据。
• LLM 后端切换：全局可通过 GADGET_LLM_BACKEND 环境变量设置，或在各工具命令中使用 --api 参数。

通过以上步骤，你即可完整运行 Gadget 项目中的所有核心工具。详细的高级配置（如特定工具的 JSON 格式、更多 CLI 参数）请参阅各工具目录下的 TUTORIAL.md 或 README.md。

Gadget 项目完全指南

一、项目总结

1.1 项目概述

Gadget 是一个开源工具集合，汇聚了日常开发积累的实用工具。它涵盖以下功能：

• AI 日报生成 — 自动统计多设备的AI对话记录，生成日/周/月报告
• 论文发现 — 从学术数据库搜索、评估论文，分析研究者和引文网络
• 性能基准测试 — CPU/GPU 跨平台FLOPS测试
• 博客自动化 — Hugo静态站点，支持增量媒体压缩和自动部署
• 文档翻译 — 本地推理的Gradio翻译器，支持文本和文件格式

1.2 仓库结构

gadget/
├── tools/                    # 5个独立工具产品
│   ├── summarize/           # AI对话日/周/月报告
│   ├── research/            # 论文发现 + 研究者分析 + 引文图
│   ├── benchmark/           # CPU/GPU性能基准测试
│   ├── website/             # Hugo博客（增量压缩 + 自动发布）
│   └── translator/          # Gradio文档翻译器
├── common/                  # 共享基础设施包（所有工具依赖）
├── scripts/                 # 运维脚本（数据同步、机器配置等）
├── docs/                    # 设计文档和ECL计划
├── outputs/                 # 生成的文件（自动重建，已gitignore）
├── CLAUDE.md               # Claude Code 仓库指南
└── pyproject.toml          # Python打包配置

1.3 每个工具的功能

1.4 基础设施

• common/ — LLM调用、磁盘缓存、翻译引擎、Hugo部署等共享能力
• scripts/ — 数据同步(sync.py)、机器初始化(onboard.py)、LLM服务(serve_local_llm.sh)等
• ai-companion/ — 分离的Node.js仓库（在../ai-companion/），提供代码变更跟踪和所有Claude Code skills

二、详细使用教程

2.1 环境准备

系统要求

• Python 3.10+（推荐使用conda环境）
• Node.js 18+（仅ai-companion仓库需要）
• Git

创建Python环境

# 使用conda创建Python 3.10环境
conda create -n AI python=3.10
conda activate AI

# 或者使用venv
python3.10 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或在Windows上: venv\Scripts\activate

2.2 安装步骤

第一步：克隆仓库

git clone <gadget-repository-url>
cd gadget

第二步：安装公共包和所有工具

# 安装common包 + summarize/research/benchmark/website的所有依赖
pip install -e ".[all]"

# 如果需要translator工具，需单独安装
pip install -e ".[translator]"

# 如果需要website工具的完整功能（包含torch+transformers用于翻译）
pip install -e ".[website]"

第三步：准备API密钥和配置

# 创建token目录（存放API密钥等敏感信息，已gitignore）
mkdir -p tokens/

# 从示例配置创建主配置文件
cp config.example.json config.json

# 编辑config.json，填入以下信息：
# - LLM API密钥（如果使用anthropic或openai后端）
# - Hugo部署配置（如果使用website工具）
# - rclone数据同步配置（如果需要跨设备数据同步）

第四步：一次性机器初始化（可选但推荐）

如果是新机器，可以使用自动化脚本一次性完成所有配置：

# 编辑初始化配置表
# 打开 tokens/onboard.yaml，填入SSH/API密钥/工具配置等

# 运行初始化脚本
python scripts/onboard.py

# 这个脚本会自动完成：
# - SSH配置
# - Claude Code / Codex CLI 登录
# - pip 依赖安装
# - 各工具配置
# - rclone 引导启动

第五步：验证安装

# 运行烟雾测试（只读，无LLM调用，无网络，无写入）
bash scripts/smoke.sh

2.3 工具配置

全局LLM后端配置

所有工具通过统一的 --api 参数切换后端：

# 方式1：命令行指定
python -m summarize daily export --api ollama

# 方式2：环境变量全局设置
export GADGET_LLM_BACKEND=claude_cli
python -m summarize daily export  # 自动使用claude_cli

# 可用后端
# - ollama（默认，本地Ollama，无需密钥，模型：Qwen3.8-27B）
# - claude_cli（重用Claude Code CLI登录状态，无需API密钥）
# - anthropic（需要ANTHROPIC_API_KEY环境变量）
# - openai（需要OPENAI_API_KEY环境变量）

翻译引擎配置

Website和Translator工具的翻译使用本地推理：

# 方式1：自动选择（推荐）
# - Ollama已安装且模型已拉取 → 使用ollama
# - Linux → vllm优先
# - Windows → transformers优先

# 方式2：指定后端
export GADGET_TRANSLATION_BACKEND=transformers

# 方式3：指定模型
export GADGET_TRANSLATION_MODEL=tencent/Hy-MT2-1.8B-GGUF

# 默认模型会在首次使用时自动下载

Ollama本地LLM服务（推荐）

# 启动Ollama服务并输出环境变量
eval "$(bash scripts/serve_local_llm.sh env)"

# 这会：
# 1. 拉取并启动 Qwen 模型（如果未启动）
# 2. 输出环境变量供后续命令使用
# 3. 持久化配置保存在repo根目录 config.json 的 summarize 字段

2.4 各工具详细用法

2.4.1 Summarize — AI对话日/周/月报告

功能：自动从多设备AI对话记录中提取token使用和对话内容，生成结构化的日报、周报、月报。

工作流程：

1. 在各设备上导出未导出的对话记录（Phase 1）
2. 通过云盘同步或手动复制聚合（Phase 2）
3. 生成日报、周报、月报

典型命令：

# === Phase 1: 导出所有未导出日期的对话记录 ===
python -m summarize daily export

# === Phase 2: 同步所有日期并逐日合并 ===
python -m summarize daily merge --sync-all

# === 生成周报（周号格式：2026-W12，表示2026年第12周）===
python -m summarize weekly generate --week 2026-W12

# 生成周报并自动发布到Hugo博客
python -m summarize weekly generate --week 2026-W12 --deploy

# === 生成月报（月份格式：2026-02）===
python -m summarize monthly generate --month 2026-02

# 生成月报并发布
python -m summarize monthly generate --month 2026-02 --deploy

# === 一键完整流程 ===
# 导出 → 合并 → 生成周报 → 生成月报 + 自动发布
python -m summarize auto --deploy

# === 指定LLM后端 ===
python -m summarize daily export --api anthropic
python -m summarize auto --deploy --api openai

支持的LLM后端：

• ollama（默认，本地，无密钥）
• claude_cli（重用Claude Code CLI）
• anthropic（需ANTHROPIC_API_KEY）
• openai（需OPENAI_API_KEY）

详细步骤教程：见 TUTORIAL.md — Summarize 和 tools/summarize/tutorial.md

2.4.2 Research — 论文发现与研究者分析

功能：统一的学术研究工具包，提供论文发现、深度论文分析、研究者分析、引文图分析。

入口：tools/research/research_scout.py

典型命令：

# === 论文发现完整流程 ===
# 搜索论文 → 三阶段评估（快速筛选→深度评估→引文影响）→ 生成周报 → 发布Hugo
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"

# === 引文图分析 ===
# 基于Semantic Scholar API的前向/后向引用分析
python tools/research/research_scout.py citations 2301.12597

# === 发布报告到Hugo ===
python tools/research/research_scout.py deploy

# === 指定LLM后端 ===
python tools/research/research_scout.py report --project my-project --api claude_cli
python tools/research/research_scout.py profile "Sergey Levine" --api anthropic

LLM后端选项：

• ollama（默认）
• claude_cli
• anthropic
• openai

详细步骤教程：见 TUTORIAL.md — Research 和 tools/research/TUTORIAL.md

2.4.3 Benchmark — 性能基准测试

功能：跨平台CPU/GPU FLOPS基准测试，支持多种硬件和精度。

前置要求：

cd tools/benchmark  # 所有命令必须在此目录执行

支持硬件：

• NVIDIA (CUDA)
• Apple Silicon (MPS)
• Intel (XPU)

支持精度：FP64、FP32、FP16、BF16、FP8（实验性）

典型命令：

cd tools/benchmark

# === 运行所有基准测试（结果追加到CSV） ===
python -m benchmark.cli

# === 仅CPU测试 ===
python -m benchmark.cli --cpu-only

# === 仅GPU测试 ===
python -m benchmark.cli --gpu-only

# === 运行测试 + 生成HTML报告 ===
# 生成Plotly交互式图表、排行榜
python -m benchmark.cli --report

# === 生成报告 + 发布到Hugo /benchmark/ 页面 ===
python -m benchmark.cli --report --deploy

# === 提交到公共排行榜（如需要） ===
# 见详细文档

结果处理：

• 结果累积到CSV（追加模式，永不覆盖）
• 支持生成交互式HTML报告（Plotly）
• 支持发布到Hugo网站
• 支持提交公共排行榜

详细步骤教程：见 TUTORIAL.md — Benchmark 和 tools/benchmark/tutorial.md

2.4.4 Website — Hugo博客自动化

功能：Hugo静态博客网站，支持增量媒体压缩和自动化部署。

网站信息：

• 网站名称：“TzJ’s Net”
• 主题：PaperMod
• 部署：GitHub Pages (https://tzj2006.github.io/)

特性：

• 增量图像/视频压缩（仅压缩.last_build后改动的文件）
• 本地双语翻译（默认Ollama，Linux备选vLLM，Windows备选transformers）
• 自动翻译、压缩、构建、推送

前置依赖：

# 安装website依赖（包含torch + transformers用于本地翻译）
pip install -e ".[website]"

典型命令：

# === macOS / Linux ===
cd tools/website
bash update.sh  # 增量压缩 + Hugo构建 + 推送GitHub Pages

# === Windows ===
powershell -ExecutionPolicy Bypass -File tools/website/update.ps1
# 脚本自动cd到自己的目录

# === 本地预览（dev server） ===
cd tools/website
hugo server -D  # -D 表示包含草稿，打开 http://localhost:1313

自动生成内容处理：

• 日报/周报/月报、研究报告、基准测试页面、图表等由各工具的发布流程直接写入tools/website/content|static
• 所有自动生成的文件都标记有gadget_generated标记
• 手写文件（无标记）永不被覆盖

部署仓库：

• tools/website/public/是分离的部署仓库（tzj2006/tzj2006.github.io）
• 由build脚本自动提交+推送
• 不要直接提交到此目录

详细步骤教程：见 TUTORIAL.md — Website 和 tools/website/CLAUDE.md

2.4.5 Translator — Gradio文档翻译器

功能：本地推理的文档翻译器，支持文本和多种文件格式。

特性：

• Google翻译风格的本地翻译网页
• 支持格式：.md / .txt / .pdf / .docx / 图片
• 保留Markdown格式（代码块、URL、Hugo shortcode等被保护）
• 本地推理，无云API调用

前置依赖：

pip install -e ".[translator]"

启动应用：

python -m translator
# 自动在浏览器打开 Gradio GUI

配置：

# 默认模型（自动在首次使用时下载）
# 模型：tencent/Hy-MT2-1.8B（GGUF变体：tencent/Hy-MT2-1.8B-GGUF）

# 方式1：环境变量指定模型
export GADGET_TRANSLATION_MODEL=tencent/Hy-MT2-1.8B-GGUF

# 方式2：在GUI中管理模型

# 方式3：环境变量指定后端
export GADGET_TRANSLATION_BACKEND=ollama

功能：

• 源语言可设为auto（通过文本的CJK比例自动检测）
• 目标语言为auto时自动在中↔英间切换

详细步骤教程：见 TUTORIAL.md — Translator

代码参考：

• UI配置：tools/translator/app.py
• 翻译和文件逻辑：tools/translator/core.py
• 共享翻译引擎：common/engine.py、common/translation.py

2.5 跨设备数据同步

功能：集中式rclone数据同步，支持推送/拉取/状态/bootstrap/配置。

# 查看帮助
python scripts/sync.py

# 推送到远程
python scripts/sync.py push

# 拉取从远程
python scripts/sync.py pull

# 查看同步状态
python scripts/sync.py status

# 初始化bootstrap（首次setup）
python scripts/sync.py bootstrap

# 配置同步
python scripts/sync.py config

配置：

• 保存在repo根目录 config.json 的 sync 字段
• 覆盖配置路径：GADGET_CONFIG 环境变量
• 覆盖范围：summarize / website / research / benchmark / backups / dag（DAG网站生成+发布）

2.6 输出目录结构

所有生成的文件存储在 outputs/ 目录（已gitignore，可自动重建）：

outputs/
├── logs/         # 中间文件（导出日志、运行日志）
├── reports/      # 最终报告（Markdown、JSON、HTML）
├── cache/        # LLM缓存、搜索缓存
├── data/         # 结构化数据（CSV、JSON研究者数据）
├── images/       # 图表和生成的图像
└── backups/      # 强制覆盖备份（website-force等）

Hugo网站内容直接写入 tools/website/content|static（无单独的输出分级目录）。

2.7 常用技巧和注意事项

环境变量快速参考

# LLM后端选择
export GADGET_LLM_BACKEND=claude_cli

# 翻译后端选择
export GADGET_TRANSLATION_BACKEND=transformers

# 翻译模型选择
export GADGET_TRANSLATION_MODEL=tencent/Hy-MT2-1.8B-GGUF

# 配置文件路径（默认./config.json）
export GADGET_CONFIG=/path/to/custom/config.json

首次使用检查清单

• 环境准备（Python 3.10+、conda/venv）
• 安装依赖（pip install -e ".[all]"）
• 创建 config.json（从 config.example.json 复制）
• 准备 API 密钥（放在 config.json 或环境变量）
• 运行烟雾测试（bash scripts/smoke.sh）
• 选择工具开始使用

常见问题处理

# 测试特定工具的导入（无网络、无LLM）
python -c "import summarize; print('OK')"
python -c "import research; print('OK')"

# 查看当前配置
cat config.json

# 重置缓存（如遇cache问题）
rm -rf outputs/cache/

# 检查GPU（仅benchmark）
cd tools/benchmark && python -c "import torch; print(torch.cuda.is_available())"

2.8 AI Companion集成（可选）

本项目通过 ai-companion 仓库（在 ../ai-companion/）提供：

• 代码变更跟踪
• Claude Code planning/execution skills
• 所有domain skills（summarize、optimize等）

无需额外配置，已通过hooks自动集成。如需深入了解，见 ../ai-companion/scripts/install.ts。

2.9 快速开始示例

场景1：生成这周的AI对话周报

# 激活环境
conda activate AI

# 启动本地Ollama（如未启动）
eval "$(bash scripts/serve_local_llm.sh env)"

# 导出所有记录并生成周报
python -m summarize daily export
python -m summarize daily merge --sync-all
python -m summarize weekly generate --week 2026-W35 --deploy

场景2：搜索最新的机器学习论文

conda activate AI
python tools/research/research_scout.py report --project ml-papers --api claude_cli

场景3：测试GPU性能并生成报告

conda activate AI
cd tools/benchmark
python -m benchmark.cli --report

场景4：启动本地文档翻译器

conda activate AI
python -m translator
# 浏览器自动打开 http://localhost:7860

这份教程涵盖了从零开始使用 Gadget 的所有关键步骤。根据你的具体需求，选择相应的工具按上述命令使用即可。有任何疑问，可参考各工具的 TUTORIAL.md 和源码文档。

一、项目总结

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

这些命令分别做：

• report：完整流程，搜索 → 三阶段评估 → 报告
• ask：自然语言搜索，自动路由数据源
• profile：研究者画像
• citations：引用图分析，支持 arXiv ID / DOI
• deploy：把报告部署到 Hugo

同样支持切换 LLM 后端：

• ollama
• claude_cli
• anthropic
• openai

4.3 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

这些命令分别表示：

• 默认跑所有 benchmark，结果追加到 CSV
• 只跑 CPU
• 只跑 GPU
• 跑 benchmark 并生成 HTML 报告
• 生成报告并发布到 Hugo 的 /benchmark/

README 还说明它支持：

• NVIDIA CUDA
• Apple Silicon MPS
• Intel XPU

以及一些精度层级：

• FP64
• FP32
• FP16
• BF16
• FP8（实验性）

4.4 website：Hugo 博客

这个工具是 Hugo 静态博客站点，README 给出了三种常用操作。

安装网站相关依赖：

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 还说明：

• 它会做增量图片 / 视频压缩
• 图片用 pngquant
• 视频用 HandBrakeCLI
• 自动生成内容会直接写入 tools/website/content 或 tools/website/static
• tools/website/public/ 是单独的部署仓库，不要直接往里面提交

4.5 translator：Gradio 文档翻译器

安装依赖：

pip install -e ".[translator]"

启动 GUI：

python -m translator

这个工具会打开浏览器里的本地翻译页面，支持：

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

README 里特别提到：

• 它保留 Markdown 格式
• 会保护代码块、URL、Hugo shortcodes
• 是本地推理，不是云 API
• 默认模型是 tencent/Hy-MT2-1.8B
• 也可以通过 GADGET_TRANSLATION_MODEL 或 GUI 内模型管理改掉

5. 运维和辅助脚本

这些也都是 README 明确写到的，可以直接用。

sync.py：

python scripts/sync.py

README 说它负责 rclone 同步，覆盖：

• summarize
• website
• research
• benchmark
• backups
• 还有一个 dag 类别

smoke.sh：

bash scripts/smoke.sh

这是只读 smoke 测试，不做 LLM、网络或写入。

serve_local_llm.sh：

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

README 说明它会创建一个 summarize 调优版的 Ollama 变体，并输出环境变量。

ai-companion 相关的 server onboarding：

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

README 说明这个脚本已经迁移到 ../ai-companion/ 仓库里。

6. 一份最短上手流程

如果你只是想先跑起来，README 能支持的最短路径是：

pip install -e .
pip install -e ".[all]"

如果要用翻译器，再加：

pip install -e ".[translator]"

然后按你要做的事选工具：

python -m summarize auto --deploy
python tools/research/research_scout.py report --project my-project
cd tools/benchmark && python -m benchmark.cli --report
cd tools/website && hugo server -D
python -m translator

如果你愿意，我下一步可以把这份内容再整理成一版“更像正式文档”的中文手册，改成：

1. 适合新手阅读的长文版
2. 适合放进项目文档的精炼版
3. 按“安装 / 配置 / 使用 / 常见问题”重排的版本

一、项目总结

是什么

Gadgets 是一个日常开发中积累的实用工具合集,涵盖 AI 日报生成、论文发现、性能基准测试、博客自动化和文档翻译。tools/ 下每个目录都是一个可独立使用的工具;共享基础设施统一放在仓库根目录的 common/ 包中(通过 pip install -e . 安装),提供 LLM 调用、JSON 解析、磁盘缓存、原子写入、翻译、Hugo 部署等通用能力。

开发工作流(规划/执行/变更追踪)和所有 Claude Code skills 由 ai-companion 提供 —— 那是一个独立仓库(git@github.com:TzJ2006/ai-companion.git),检出在同级目录 ../ai-companion/,通过 hooks 接入本仓库。许可证为 GPL-3。

仓库结构

gadget/
├── tools/              # 五个独立工具产品(改工具来这里)
│   ├── summarize/      # AI 对话日报 / 周报 / 月报
│   ├── research/       # 论文发现 + 研究者分析 + 引用图谱
│   ├── benchmark/      # CPU/GPU 性能基准测试
│   ├── website/        # Hugo 博客(增量媒体压缩 + 自动构建发布)
│   └── translator/     # Gradio 文档翻译器
├── common/             # 共享基础设施包(LLM / 缓存 / IO / 翻译 / Hugo)—— 所有工具依赖它
├── scripts/            # 运维 + 维护脚本(sync.py, onboard.py, language.py, profile_translation.py, …)
├── docs/               # 设计文档、ECL 计划(docs/ecl/)、审计报告、历史归档(docs/archive/)
├── outputs/            # 所有生成产物(gitignored,可自动重建)
├── AGENTS.md           # 所有 AI agent 的工作流协议(行动前先读)
├── CLAUDE.md           # 给 Claude Code 的仓库指南
└── pyproject.toml      # common/ 与各工具的打包配置(pip install -e .)