Part One: Project Summary

What are Gadgets

Gadgets (repository directory named gadget/) is a set of daily development tools covering five types of needs: AI conversation summarization, paper research, performance testing, blog publishing, and document translation.

The five tools under tools/ can be used independently. They share the common/ package in the repository root, which provides capabilities such as LLM calls, caching, file writing, translation, and Hugo deployment.

The development workflow and Claude Code skills are placed in another repository, ai-companion, located in the sibling directory ../ai-companion/, and integrated via hooks from this repository.

Repository Structure

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 打包与安装配置

Enter tools/<工具名>/ to modify tool logic; enter common/ to modify common capabilities; check scripts/sync.py to modify synchronization logic; enter the independent ai-companion repository to modify development workflows or skills.

What the Five Tools Do

common/ also includes JSON parsing and repair, SHA-256 disk caching with namespaces and TTL, atomic writes, and content hashing. scripts/ is responsible for operations; ai-companion is responsible for code change tracking, testing and HTML reports, as well as development processes like /idea → /ccplan → /ccedit.

Part Two: Beginner’s Tutorial

All following commands are from the provided README. Except for Benchmark and commands explicitly containing cd, they are executed in the gadget/ repository root by default.

The README is positioned as an overview and does not provide complete installation and configuration steps. Missing content will be explicitly stated; no speculative commands will be written.

1. Prepare Environment

The required basic environment is as follows:

If you already have a AI Conda environment, you can execute:```bash conda activate AI

The README does not provide the clone address for the gadget repository, nor does it provide installation commands for Python, Conda, Ollama, Hugo, rclone, pngquant, or HandBrakeCLI; therefore, a complete "from scratch" installation process cannot be provided here.

**2. Install Python Packages and Tool Dependencies**

Install common base packages:

```bash
pip install -e .

Install common along with the extras for Summarize, Research, Benchmark, and Website:

pip install -e ".[all]"

Note: all does not include Translator. If a translator is needed, install it separately:

pip install -e ".[translator]"

If only the dependencies corresponding to Website are required, the README also provides:

pip install -e ".[website]"

Among them, Website extras include torch and transformers used for translation; Translator extras include Gradio and the GGUF translation stack.

3. Prepare Configuration

In the repository root, copy config.example.json to config.json, then modify as needed. The README does not show the full structure of the configuration fields, so configuration content should not be fabricated.

Relevant configuration entry points are as follows:

config.json and tokens/ are ignored by Git; do not commit the contents of tokens/. The README does not provide API key filenames, formats, or assignment examples for the above environment variables.

LLM functionality for Summarize and Research can be selected using --api:

The README does not provide the full configuration process for these backends, nor does it show complete command examples with --api.

Translation functionality uses local inference. Special attention is needed as the README’s description of the default translation model varies:

• The Website and Translator sections describe tencent/Hy-MT2-1.8B, which is automatically downloaded upon first use; Translator also lists its GGUF variants.
• The Environment Requirements and Notes sections describe Ollama defaulting to gemma4:26b, while other in-process backends use tencent/Hy-MT2-1.8B.

Therefore, based solely on this README, one cannot assert that all translation paths default to the same model.

4. Optional: Machine Initialization and Basic Checks

If you wish to configure a new machine, the README provides two paths:

• Repository-level initialization: Run scripts/onboard.py after filling in tokens/onboard.yaml. It will configure SSH, Claude/Codex installation and authentication, pip extras, ai-companion, tool settings, and rclone bootstrap. The README does not provide the full execution command or YAML examples.
• Ubuntu server-level initialization: The script is located in the ai-companion repository and supports Ubuntu 22.04/24.04. You can view its help first:

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

The --companion-repo of the server script should point to the ai-companion repository git@github.com:TzJ2006/ai-companion.git; after splitting, --companion-ref is no longer required. The README does not provide the full installation command.

After installation, a read-only smoke test can be run:

bash scripts/smoke.sh

It checks the --help, --info, and imports of each tool, without calling LLMs, accessing the network, or writing files.

5. Summarize: Generate AI Conversation Reports

The typical workflow is: export conversation logs from each device → sync via cloud drive or manual aggregation → merge daily to generate daily reports → generate weekly and monthly reports after daily reports have accumulated.

Phase one, export all dates that have not yet been exported:

python -m summarize daily export

In multi-device scenarios, each device exports separately, then records are aggregated. Phase two, sync all dates and merge them daily:

python -m summarize daily merge --sync-all

Generate a weekly report for a specified week based on existing daily reports, and deploy:

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

Generate a monthly report for a specified month based on existing daily reports, and deploy:

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

2026-W12 and 2026-02 are example values from the README; replace them with the target week or month when in use.

You can also run the full automated process:

python -m summarize auto --deploy

It executes export, merge, weekly report, monthly report, and deployment.

This tool uses the source-specific namespace command of ccusage 20.x to count tokens and costs for each agent CLI. The README does not provide the installation command for ccusage, conversation source paths, or exported data formats.

The old daily_summary.py, weekly_summary.py, and monthly_summary.py entry points are still compatible, but using the above python -m summarize format is recommended.

6. Research: Discover Papers, Analyze Researchers, and Citation Relationships

Research uses a single entry point tools/research/research_scout.py.

Run a complete paper research workflow for a project:

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

It executes search, three-stage evaluation, and report generation. The three stages are rapid screening, in-depth evaluation, and citation impact analysis.

my-project is an example project name. The README does not explain how projects are defined or provide the project configuration format, so project configuration cannot be completed based solely on this README.

Search using natural language:

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

This command will automatically select the search source.

Generate researcher profiles:

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

The profiling feature combines arXiv, Semantic Scholar, and LLM to analyze research trajectories, calculate hierarchy scores, and discover mentor-student relationships through homepage information and co-authorship patterns. It also supports name disambiguation and reverse lookup.

Analyze paper citation graphs:

python tools/research/research_scout.py citations 2301.12597

Input supports arXiv ID or DOI; analysis includes forward citations, backward references, and LLM impact interpretation.

Deploy research reports to Hugo:

python tools/research/research_scout.py deploy

The README also introduces --insight in-depth paper analysis: downloading full texts, analyzing writing structure, publication strategies, and reusable knowledge, matching OpenReview comments, and synthesizing cross-paper writing guides. However, it does not provide a complete invocation example, so speculative commands are not concatenated here.

7. Benchmark: Test CPU/GPU Performance

Benchmark commands have special directory requirements: enter tools/benchmark/ first.

cd tools/benchmark

Run all tests:

python -m benchmark.cli

Test CPU only:

python -m benchmark.cli --cpu-only

Test GPU only:

python -m benchmark.cli --gpu-only

Run tests and generate an HTML report:

python -m benchmark.cli --report

The /benchmark/ to run tests, generate reports, and publish to Hugo:

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

These are different running methods; choose according to your needs.

Testing uses warm-up, formal measurement, median statistics, and IQR outlier removal, and explicitly synchronizes the GPU. Results are saved to a CSV in an append mode, making it easy to accumulate scores for various hardware.

Actual GPU testing supports NVIDIA CUDA, Apple Silicon MPS, and Intel XPU. OpenCL may appear in the detection results of --info, but it is not listed as an actual GPU testing backend in the README. Precision includes FP64, FP32, FP16, BF16, and experimental FP8.

The README mentions a public leaderboard submission feature but does not provide the submission command, nor does it give specific hardware driver installation steps.

After execution, subsequent tool commands must be run after returning to the gadget/ root directory in the terminal.

8. Website: Preview and Publish Hugo Blog

If Website extras are not yet installed, execute in the root directory:

pip install -e ".[website]"

Local preview:

cd tools/website && hugo server -D

-D indicates including drafts during preview.

Build and publish on macOS/Linux:

cd tools/website && bash update.sh

On Windows, execute in the repository root:

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

The Windows script will enter its own directory automatically.

The publish script performs incremental media compression, Hugo builds, and pushes to Pages. Incremental compression is based on .last_build: images use pngquant, and videos use HandBrakeCLI.

These update scripts will publish the website, not just generate a local preview. The corresponding site in the README is https://tzj2006.github.io/, and the deployment repository is tzj2006/tzj2006.github.io; the README does not explain how to change to your own site or configure push authentication.

Automatically generated content is written directly to:

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

These files carry a gadget_generated marker; handwritten files without this marker will not be overwritten.

tools/website/public/ is an independent deployment repository that is automatically committed and pushed by the build script; do not commit directly to it.

9. Translator: Translate Documents in the Browser

Install dependencies in the repository root:

pip install -e ".[translator]"

Start the interface:

python -m translator

It will open the Gradio GUI in your browser. You can translate text, .md, .txt, .pdf, .docx, or image files through the interface, and switch models via the interface’s model management.

Language selection behavior:

• When the source language is set to auto, it detects based on the proportion of CJK characters in the text.
• When the target language is set to auto, it toggles between Chinese and English.

The translator reuses common.engine.create_engine() to automatically select the backend: if the model tag has been pulled, it prioritizes Ollama; the fallback for Windows is transformers, Linux prioritizes vLLM, and low-VRAM scenarios provide llamacpp/GGUF options.Models will reside in memory; models are lazy-loaded on demand when switching. Discrepancies between the default model and environment requirements have been explained in the configuration section. The README does not provide commands for manually pulling models, specifying ports, or translating command-line files.

10. Data Synchronization and Output Management

Synchronization is centrally managed by scripts/sync.py, which requires pre-configuring rclone. The configuration is located in the sync section of the root directory config.json.

The basic entry point provided in the README is:

python scripts/sync.py

Cross-device push and pull:

python scripts/sync.py push

python scripts/sync.py pull

The script also supports status, bootstrap, and config operations, covering categories such as summarize, website, research, benchmark, and backups; a special dag category is used to generate and deploy DAG sites. The README does not provide the complete command syntax for these categories.

For Summarize, the local Ollama auxiliary script also provides the following environment loading command:

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

This script is used to create an Ollama variant suitable for Summarize and output environment settings; it is not the Ollama installation command provided in the README.

Regular generated artifacts are concentrated in:

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

Website content is a clear exception: it is written directly to tools/website/content|static, with no separate outputs/site staging directory.

Do not include auto-generated content, rclone sync data, build/, gadget.egg-info/, or the deployment and theme repositories under Website in the repository commits.

Key Details Not Yet Provided in the README

To truly complete the initial configuration of all functions, the documents pointed to by the README are also required: the root directory TUTORIAL.md, tutorials for each tool, and the installation instructions for ai-companion. The current content does not provide the fields for JSON/YAML configuration, API key formats, Ollama installation and model preparation, rclone remote configuration, Research project definitions, or deployment settings for personal Hugo sites; therefore, these tutorials maintain these gaps without fabricating commands or parameters.

The following is based solely on the README you provided. Since the README is positioned as a project overview, any configuration fields, installation steps, or command parameters not provided will be explicitly marked and will not be fabricated.

I. Project Summary

Gadgets (the repository directory is named gadget/) is a set of practical tools accumulated during the development process, containing five independently usable tools:

They all collectively depend on the common/ Python package in the root directory. The development workflow and Claude Code skills come from the independent ai-companion repository.

The repository structure is as follows:

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 打包和安装配置

To modify a specific tool, enter tools/<工具名>/; to modify shared LLM, cache, translation, or deployment capabilities, enter common/; to modify the development workflow or skills, enter the peer-level ../ai-companion/.

II. Preparation Before Use

Required environments:

If the Conda environment recommended by the README has already been created, you can run:

conda activate AI

The README does not provide the clone address for the gadget repository, nor does it provide installation commands for software such as Python, Conda, Ollama, Hugo, or rclone; therefore, these commands are not supplemented here.

Except for Benchmark and commands that explicitly include cd, the following are organized based on being executed in the gadget repository root directory. After entering a subdirectory, please return to the repository root before executing the root directory commands in the next section.

III. Installing Project Dependencies

To install only the shared packages and the basic editable installation of the project:

pip install -e .

If you intend to use Summarize, Research, Benchmark, and Website, you can install the collection provided by the README:

pip install -e ".[all]"

all does not include Translator. If you also need web-based document translation, install it separately:

pip install -e ".[translator]"

If you only intend to use the website functions, the README also provides the corresponding installation method:

pip install -e ".[website]"

Website dependencies include torch and transformers for translation; Translator dependencies include Gradio and GGUF translation components.

These installation methods should be chosen as needed; there is no need to execute them one by one. The generated build/ and gadget.egg-info/ are located in the repository root and are ignored by Git.

IV. Configuring the Project

1. Prepare the Main Configuration File

   Copy the config.example.json from the root directory to config.json, then fill it in according to actual needs.

   The README explicitly states:

   • Tool settings are located in the root directory config.json.
   • GADGET_CONFIG can override the configuration file path.
   • rclone synchronization configuration is located in the sync section.
   • Summarize’s persistent configuration is located in the summarize section.

   The README does not show specific JSON fields and values, so a reliable complete configuration example cannot be written based on this.

2. Select LLM Backend

   The LLM functions of Summarize and Research support the following backends:

   Backend Value	Description in README
   ollama	Default, local Ollama, no API key required, uses Gemma4-26B
   claude_cli	Reuses Claude Code CLI login status, no API key required
   anthropic	Anthropic API backend
   openai	OpenAI API backend

   Switch via the --api parameter, or select globally via GADGET_LLM_BACKEND.

   The README does not provide specific fields for API keys, file formats, or complete backend switching examples; therefore, the original commands are retained below without manually concatenating parameters.

3. Understanding Translation Configuration

   Translation is performed locally and does not call cloud translation APIs. Relevant configuration entry points are:

   Configuration Entry	Function
   GADGET_TRANSLATION_BACKEND	Select local translation backend
   GADGET_TRANSLATION_MODEL	Override Translator default model
   Model management in Translator interface	Manage models within the interface

   Backends involve ollama, llamacpp, vllm, and transformers; among them, GGUF/llamacpp is a low-VRAM option.

   There are discrepancies in the README’s description of the default translation model: The Website and Translator sections mention tencent/Hy-MT2-1.8B, and Translator also lists GGUF versions; however, Environment Requirements and Notes state that the default Ollama path reuses gemma4:26b, while other in-process backends use Hy-MT2. Based solely on this README, all translation scenarios cannot be described as using the same default model.

4. Saving Sensitive Configurations

   tokens/ is used to save API keys and machine initialization tables; it is ignored by Git, so do not commit its contents. The config.json in the root directory is also ignored by Git.

V. Summarize: Generating Reports from AI Conversations

Supports reading Claude Code, Codex, Cursor Agent, ChatGPT, and general JSON conversation records.

It employs a two-stage process: first exporting from each device, then aggregating and merging to generate daily reports; after accumulating daily reports, weekly and monthly reports can be generated.

Step 1: On each device where conversation records need to be collected, export all dates that have not yet been exported:

python -m summarize daily export

Step 2: Synchronize aggregated export records via cloud drive or manual copying, then sync all dates and merge them day by day:

python -m summarize daily merge --sync-all

Step 3: Generate weekly or monthly reports based on existing daily reports. The following uses example dates from the README and includes deployment operations:

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

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

You can also run the full pipeline, executing export, merge, weekly report, monthly report, and deployment in sequence:

python -m summarize auto --deploy

Tips:

• --deploy will trigger deployment; relevant website configurations should be prepared before use.
• Token usage and cost statistics are completed through the various source commands in ccusage 20.x.
• The old daily_summary.py, weekly_summary.py, and monthly_summary.py entry points are still compatible, but using the module entry points mentioned above is recommended.
• The README does not provide path configurations for each conversation source, general JSON formats, or the ccusage installation command.

Further explanations are located in TUTORIAL.md and tools/summarize/tutorial.md, but their main text is not included in the provided materials.

VI. Research: Paper Discovery and Scholar Analysis

The unified entry point is tools/research/research_scout.py.

Typical Usage 1: Generate a research report around a project, performing search, three-stage evaluation, and report generation:

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

The three-stage evaluation consists of rapid screening, in-depth evaluation, and citation impact analysis. my-project is an example project name from the README; specific project configuration methods are not provided.

Typical Usage 2: Search directly using natural language:```bash python tools/research/research_scout.py ask “找 Pieter Abbeel 最近的机器人操作论文”

The tool automatically selects the search source, and also supports conference paper search and author search.

Typical Usage 3: Analyzing Researchers:

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

Researcher analysis includes papers and citation data, research trajectories, hierarchical scoring, and discovering mentor-student relationships through homepages and co-authorship patterns; it also supports name disambiguation and reverse lookup.

Typical Usage 4: Analyzing the citation relationships of a specific paper:

python tools/research/research_scout.py citations 2301.12597

Supports specifying a paper using arXiv ID or DOI, analyzing subsequent citations and references, and interpreting impact in combination with LLM.

Typical Usage 5: Deploying reports to Hugo:

python tools/research/research_scout.py deploy

The README also describes the --insight deep interpretation feature: downloading full texts, analyzing writing structures, publication strategies, and reusable knowledge, matching OpenReview comments, and synthesizing them into cross-paper writing guides. The original text does not provide the complete invocation command for this parameter, so it is not inferred here which subcommand it should follow.

VII. Benchmark: Testing CPU/GPU Performance

First, enter the specified directory from the repository root:

cd tools/benchmark

The following commands are all run in that directory; choose one according to your needs.

Run all benchmarks:

python -m benchmark.cli

Test only CPU:

python -m benchmark.cli --cpu-only

Test only GPU:

python -m benchmark.cli --gpu-only

Run tests and generate an HTML report:

python -m benchmark.cli --report

Run tests, generate reports, and publish to Hugo via /benchmark/:

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

Results and hardware support:

• Actual GPU testing supports NVIDIA CUDA, Apple Silicon MPS, and Intel XPU.
• OpenCL may only appear in the detection information of --info, which does not represent support for actual testing.
• Covers precisions such as FP64, FP32, FP16, BF16, etc.; FP8 is experimentally supported.
• Measurements include warmup, formal measurement, and statistical analysis, with explicit GPU synchronization.
• Results are written to CSV in an append mode without overwriting existing records, facilitating the accumulation of multi-hardware leaderboards.

The README mentions that you can submit to public leaderboards, but does not provide a submission command.

VIII. Website: Previewing and Publishing Hugo Blogs

This website uses the PaperMod theme; the corresponding site in the README is https://tzj2006.github.io/.

When website dependencies are not yet installed, execute in the repository root:

pip install -e ".[website]"

Local preview:

cd tools/website && hugo server -D

Among them, -D will include drafts.

For formal build and publish, choose according to the operating system. For macOS/Linux, run from the repository root:

cd tools/website && bash update.sh

For Windows, run from the repository root:

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

The Windows script will enter its own directory automatically. These update scripts will execute the website build and publish process, including media incremental compression and pushing to Pages.

File relationships to understand:

• Automatically generated website content is written directly to tools/website/content and tools/website/static.
• Automatically generated files carry the gadget_generated tag; handwritten files without this tag will not be overwritten.
• Images are compressed via pngquant, videos via HandBrakeCLI, processing only media that has changed since .last_build.
• tools/website/public/ is an independently deployed repository; the build script will automatically commit and push, do not commit directly to it.

The README does not provide configuration steps for changing this site to a personal domain or a personal GitHub Pages repository.

IX. Translator: Translating Text and Files in a Web Page

Install dependencies and start in the repository root:

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

After starting, the Gradio interface will open in the browser.

Typical usage process:

1. Input text to be translated, or provide .md, .txt, .pdf, .docx, or image files.
2. Select source language and target language.
3. Select models as needed through the model management in the interface.
4. Execute translation.

Meaning of automatic language selection:

• Source language is auto: judged based on the proportion of CJK characters in the text.
• Target language is auto: toggles between Chinese and English.

The translation engine protects Markdown snippets such as code blocks, URLs, and Hugo shortcodes; models remain resident and are loaded on demand when switching models. The README states that the default Hy-MT2 model will be automatically downloaded upon first use; for specific differences in default models, see the configuration instructions above.

The README does not provide interface ports, listening addresses, or startup parameters, nor does it explain export operations for various file types.

X. Synchronization, Inspection, and New Machine Initialization

Centralized data synchronization entry:

python scripts/sync.py

Cross-device push or pull:

python scripts/sync.py push

python scripts/sync.py pull

Before use, you need to configure rclone and the sync section of the root directory config.json. Synchronization overwrites summarize, website, research, benchmark, backups, and includes the special dag category used for generating and deploying DAG sites. The README also lists status, bootstrap, and config functions, but does not provide detailed parameters.

Run a read-only smoke check:

bash scripts/smoke.sh

This check covers help information, detection information, and imports; it does not call LLMs, access the network, or write files. It can be used for basic checks but cannot prove that API, synchronization, or publishing processes have been successfully configured.

Load environment settings from the local LLM auxiliary script output in Bash:

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

The README states that this script is used to create Ollama variants optimized for Summarize and output environment settings, but does not expand on the full service preparation steps.

There are two paths for new machine initialization:

• Repository-level initialization: Fill in tokens/onboard.yaml, then run scripts/onboard.py, used for SSH, Claude/Codex installation authentication, pip extras, ai-companion, tool configuration, and rclone initialization. The README does not provide YAML fields or complete execution commands.
• Ubuntu 22.04/24.04 system-level installation: The script is located in the independent ai-companion repository; you can view its help first:

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

ai-companion should be at the same level as ../ai-companion/ and requires Node.js 18+. The README provides the repository address git@github.com:TzJ2006/ai-companion.git, but does not provide complete installation commands; installation instructions point to its scripts/install.ts.

XI. Where to Find Results After Running

Generated results are usually concentrated in:

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

Website content follows explicit special paths: written directly to tools/website/content and tools/website/static, with no outputs/site temporary directory.

Do not include automatically generated content, rclone synchronized data, build artifacts, or the deployment and theme repositories under tools/website/ in the gadget’s Git commits.

This README is sufficient to provide installation entry points and typical running commands, but complete configuration still requires the TUTORIAL.md it points to, configuration examples, and documentation for each tool; the above does not supplement these unprovided contents.

I. Project Overview

Gadgets is a collection of daily development tools covering AI conversation summarization, paper retrieval, performance testing, blog publishing, and document translation. The five tools under tools/ can be used separately; they share the common/ package in the repository root.

ai-companion is an independent repository located in ../ai-companion/, providing development workflows and skills, and is not part of the Gadgets tools/. Blog generated content is written directly to tools/website/content or tools/website/static; the website’s public/ is a separate deployment repository.

II. Getting Started from Scratch

The following commands are all from the provided README. Unless otherwise noted, run them in the Gadgets repository root.

1. Environment Preparation and Installation

Python 3.10 or higher is required. The README recommends using a conda environment named AI:

conda activate AI

If using the independent ai-companion repository, Node.js 18 or higher is also required. For specific dependencies of each tool, see the requirements.txt in its directory.

Install the shared package and dependencies for summarize, research, benchmark, and website:

pip install -e ".[all]"

all does not include translator. When translation tools are needed, install separately:

pip install -e ".[translator]"

When preparing only blog-related dependencies, the command given by the README is:

pip install -e ".[website]"

2. Configuration

Tool configurations are located in config.json at the repository root: create this file using config.example.json as a template. The README does not list specific fields and values; check the template before modifying. GADGET_CONFIG can be used to specify other configuration file paths.

LLM functionality uses local Ollama by default; other backends listed in the README include claude_cli, anthropic, and openai, which can be selected via the --api parameter of each tool, or specified globally using GADGET_LLM_BACKEND. claude_cli reuses the login status of the Claude Code CLI; anthropic and openai involve respective API credentials. The README does not provide steps for filling in credentials.Translation uses local inference. The README lists GADGET_TRANSLATION_BACKEND to select the translation backend and GADGET_TRANSLATION_MODEL to override the default translation model. Models may be downloaded upon first use. tokens/ stores API keys and new machine configuration tables; it is Git-ignored, so do not commit its contents.

For cross-device synchronization, rclone must be configured first. The one-time configuration entry for a new machine is to fill in tokens/onboard.yaml and then run scripts/onboard.py; the README does not provide the exact execution command or YAML fields for this script, so they are not supplemented here.

3. Summarize: Generate AI Conversation Reports

First, export unexported conversation dates from each device, then synchronize and merge them day by day:

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

Once sufficient daily reports are available, you can generate and publish reports for a specified week or month:

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

You can also run the complete workflow provided in the README to sequentially complete export, merge, weekly report, monthly report, and publishing:

python -m summarize auto --deploy

When using multiple devices, conversation logs can be synchronized via cloud drives or manually copied and aggregated. For specific data formats and step-by-step configuration, refer to TUTORIAL.md and tools/summarize/tutorial.md pointed out in the README.

4. Research: Retrieve Papers and Analyze Researchers

Run the complete project report workflow, which includes retrieval, three-stage evaluation, and report generation:

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

Ask questions in natural language to let the tool select retrieval sources:

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

Generate researcher profiles or analyze citation relationships by arXiv ID/DOI:

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

Publish reports to Hugo:

python tools/research/research_scout.py deploy

This tool also supports capabilities such as deep full-text paper analysis and OpenReview comment analysis; the README only mentions --insight without providing complete example commands. For project settings and detailed operations of these functions, refer to TUTORIAL.md and tools/research/TUTORIAL.md.

5. Benchmark: Test CPU/GPU Performance

First enter tools/benchmark/; the README explicitly requires the following commands to be executed in this directory:

cd tools/benchmark

Select one running method as needed:

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

They represent respectively: run all tests, test CPU only, test GPU only, test and generate HTML report, and test, generate report, and publish to Hugo via /benchmark/. Results are written to CSV in an append mode. Actual GPU testing supports CUDA, Apple MPS, and Intel XPU; OpenCL may only appear in detection information.

6. Website: Preview, Build, and Publish Blog

The blog is based on Hugo. The README provides the local preview command; run from the repository root:

cd tools/website && hugo server -D

-D will include drafts in the development server. The publishing script incrementally compresses images and videos that have changed since the last build, then translates, builds, and pushes the site. Select the corresponding command from the README based on your operating system:

macOS/Linux

cd tools/website && bash update.sh

Windows PowerShell

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

The publishing script will automatically handle the separate tools/website/public/ deployment repository; you should not commit directly to it. Generated content carries the gadget_generated tag; handwritten files without this tag will not be overwritten.

7. Translator: Open Document Translation Page

After installing the translator dependencies, start from the repository root:

python -m translator

It will open a Gradio page. Inputs listed in the README include text, .md, .txt, .pdf, .docx, and images; Markdown snippets such as code blocks, URLs, and Hugo shortcodes will be protected during translation. When the source language is set to auto and the target language is set to auto, it will switch between Chinese and English. Models are loaded on demand and may be downloaded upon first use.

8. Common Maintenance Commands and Output Locations

The entry point for data synchronization scripts, and the cross-device push/pull forms provided in the README:

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

The second line is the README’s combined representation of the two operations; in actual use, choose one from push and pull. Synchronization requires pre-configuring rclone, with settings located in the sync section of config.json.

Perform cross-tool smoke tests without calling LLMs, accessing the network, or writing files:

bash scripts/smoke.sh

View the environment settings output from the local Ollama service script:

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

Generated artifacts are concentrated in outputs/: logs/ for intermediate logs, reports/ for final reports, cache/ for cache, data/ for structured data, images/ for charts and images, and backups/ for backups of overwrite operations. This directory is Git-ignored. For finer configuration values, data formats, and troubleshooting, the README explicitly points to the repository’s TUTORIAL.md and each tool’s own documentation; this tutorial does not fabricate those unshown steps.

Project Summary

Gadgets is a repository that centralizes commonly used tools in daily development, including AI conversation reports, paper discovery and analysis, performance benchmarking, Hugo blog automation, and document translation. Tools under tools/ are independent of each other; common/ provides shared LLM, cache, file I/O, translation, and Hugo deployment capabilities.

Repository Structure

Chinese Usage Tutorial

The following only organizes the environment requirements, configuration instructions, and commands provided in the README. For more detailed operations, data formats, and FAQs for each tool, please refer to the TUTORIAL.md pointed out in the README and the documentation of each tool.

1. Environment Preparation

1. Prepare Python 3.10 or higher. The README recommends using the Conda environment AI:

   conda activate AI
   

2. Node.js 18 or higher is only for use with the independent ../ai-companion/ repository.

3. Prepare the dependencies required by the tools as needed. Each tool directory has its own requirements.txt; you can also install dependencies for common, summarize, research, benchmark, and website:

   pip install -e ".[all]"
   

   .[all] does not include translator. If the translator is needed, install it separately:

   pip install -e ".[translator]"
   

4. The Website’s .[website] installation command will include the torch and transformers required for translation:

   pip install -e ".[website]"
   

2. Configuration Instructions

• Tool settings are located in config.json at the repository root. The README mentions they can be copied from config.example.json; this file is git-ignored.
• To use other configuration file paths, you can set GADGET_CONFIG.
• API keys and machine initialization tables are placed in the git-ignored tokens/ directory; never commit its contents.
• The LLM backend for Summarize and Research can be selected via --api: ollama (default), claude_cli, anthropic, or openai; you can also specify it globally using GADGET_LLM_BACKEND.
• Ollama is the default local inference option. The README mentions that website and translation functions use local inference by default; the translation backend can also be specified via GADGET_TRANSLATION_BACKEND.
• Cross-device data synchronization relies on rclone configuration. Use python scripts/sync.py to view the synchronization entry described in the README.

The README does not list the complete fields for each tool’s configuration files, specific settings for API keys, or the installation command for Ollama; these details must be found in the repository tutorials and tool documentation.

3. Summarize: Generate AI Conversation Reports

This tool reads conversation records from Claude Code, Codex, Cursor Agent, ChatGPT, or general JSON formats to generate daily, weekly, and monthly reports via LLM. In multi-device scenarios, first export records on the devices, then synchronize or manually aggregate them, and finally merge them by date to generate reports.

Execute in the repository root:

python -m summarize daily export

After exporting unexported dates, merge all dates:

python -m summarize daily merge --sync-all

Generate and deploy a report for a specified week:

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

Generate and deploy a report for a specified month:

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

You can also run the full process:

python -m summarize auto --deploy

Supports switching LLM backends via --api. The README also states that old entries python tools/summarize/daily_summary.py, weekly_summary.py, and monthly_summary.py are still compatible, but using python -m summarize is recommended.

4. Research: Paper Discovery and Researcher Analysis

Research provides a unified command entry via tools/research/research_scout.py, covering paper search and reporting, researcher profiling, citation graph analysis, and deployment.

Generate a research report for a specific project:

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

Query papers using natural language:

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

Generate a researcher profile:

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

Analyze citation relationships by arXiv ID or DOI:

python tools/research/research_scout.py citations 2301.12597

Deploy reports to Hugo:```bash python tools/research/research_scout.py deploy

The LLM capabilities of Research support selecting backends via `--api`. The README also introduces capabilities such as deep paper insights and searching for conference papers and authors; please refer to the tool tutorials for specific parameters and operational steps.

## 5. Benchmark: CPU/GPU Performance Benchmarking

Benchmark measures CPU/GPU floating-point performance. The README requires entering the tool directory first:

```bash
cd tools/benchmark

Run all benchmarks, appending results to a CSV:

python -m benchmark.cli

Test only CPU or only GPU:

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

Run tests and generate an HTML report:

python -m benchmark.cli --report

Generate a report and publish it to Hugo’s /benchmark/:

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

The README mentions that GPU testing will detect CUDA, Apple MPS, and Intel XPU; OpenCL may only appear in --info detection information and is not an actual GPU testing backend.

6. Website: Hugo Blog

Website is a Hugo static blog, including incremental media compression, build, and publishing workflows. Install dependencies:

pip install -e ".[website]"

Execute incremental compression, build, and publish on macOS/Linux:

cd tools/website && bash update.sh

Run the corresponding script on Windows:

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

Local preview (including drafts):

cd tools/website && hugo server -D

The README states that Hugo content is located in tools/website/content|static; automatically generated files are marked with gadget_generated. tools/website/public/ is a separate deployment repository, which is automatically committed and pushed by the build script.

7. Translator: Gradio Document Translator

Translator can translate text as well as .md, .txt, .pdf, .docx and image files, while preserving Markdown formatting as much as possible. It uses a local inference engine, with the default model being tencent/Hy-MT2-1.8B, which is automatically downloaded upon first use; models can also be overridden via GADGET_TRANSLATION_MODEL or through model management in the GUI.

Install and start:

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

The command will launch the Gradio graphical interface and open it in a browser. The README does not provide details on step-by-step operations within the GUI.

8. Synchronization, Initialization, and Auxiliary Scripts

Cross-device data synchronization requires rclone configuration. The entry point provided in the README is:

python scripts/sync.py

For initializing a new machine, fill in tokens/onboard.yaml first, then run:

python scripts/onboard.py

This script handles SSH, Claude/Codex CLI installation and authentication, pip extras, ai-companion installation, tool configuration, and rclone initialization.

Run a read-only tool smoke check:

bash scripts/smoke.sh

The README also lists auxiliary scripts such as serve_local_llm.sh, language.py and profile_translation.py, but does not provide their full usage workflows; please consult the corresponding scripts or tutorial documentation before use.

I. Project Summary

1. What is Gadget

Gadget is a set of practical tools accumulated from daily development, primarily covering five types of tasks:

• Generation of daily, weekly, and monthly reports for AI conversation logs
• Academic paper discovery, deep paper analysis, and researcher profiling
• CPU/GPU floating-point performance testing
• Hugo blog building, translation, media compression, and automatic publishing
• Local document translation

The five tools under tools/ are independent of each other and can be used separately. They collectively depend on the common/ package in the repository root. common/ provides general capabilities such as LLM invocation, JSON repair, disk caching, atomic writes, local translation, and Hugo deployment.

The project’s development workflow and Claude Code skills are not in this repository, but in an adjacent independent repository ../ai-companion/, integrated into Gadget via hooks under .claude/ and .codex/.

The project uses the GPL-3 license.

2. Repository Structure

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 配置

When modifying different types of functions, the corresponding locations are as follows:

3. What Each Tool Does

Summarize

Reads AI conversation logs from Claude Code, Codex, Cursor Agent, ChatGPT, or general JSON formats to generate structured daily, weekly, and monthly reports.

It employs a multi-device, two-stage process:

1. Export conversation logs on each device.
2. Aggregate them via cloud drive synchronization or manual copying, then generate reports on a daily basis.

Once daily reports accumulate to a certain amount, weekly and monthly trend summaries can be further generated.

It uses the source-specific commands of ccusage 20.x to statistics token usage and costs for different agent CLIs, such as ccusage claude, ccusage codex, and ccusage gemini.

It supports four LLM backends:

• ollama: Default, runs locally, no API key required
• claude_cli: Reuses Claude Code CLI login status, no API key required
• anthropic
• openai

Research

A unified academic research tool, entry point:

tools/research/research_scout.py

It has four main capabilities:

• Paper Discovery: Searches for papers from arXiv, bioRxiv, and PubMed; generates research weekly reports through a three-stage LLM process (“Quick Screening → Deep Evaluation → Citation Impact”) and can publish them to Hugo.
• Deep Paper Insights: Downloads full paper texts, analyzes writing structure, publication strategies, and reusable knowledge; matches OpenReview comments to analyze reviewer consensus and controversies; finally synthesizes cross-paper writing guides.
• Researcher Profiling: Retrieves paper and citation data from ArXiv and Semantic Scholar to generate research trajectory analysis and stratified scoring, and infers mentor-student relationships through personal homepages and co-authorship patterns.
• Citation Mapping: Utilizes the Semantic Scholar API to analyze forward citations and backward references, then uses an LLM to interpret the paper’s impact.

It also supports four LLM backends: ollama, claude_cli, anthropic and openai.

Benchmark

A cross-platform CPU/GPU FLOPS floating-point performance testing tool, supporting:

• NVIDIA CUDA
• Apple Silicon MPS
• Intel XPU

OpenCL may appear in --info detection results, but the README does not state that it can perform actual GPU tests.

Supported precisions include:

• FP64
• FP32
• FP16
• BF16
• FP8, experimental support

The testing process includes warmup, formal measurement, median statistics, IQR outlier removal, and explicit GPU synchronization.

Results are written to a CSV in an append mode and will not overwrite existing results, allowing for the accumulation of data from multiple hardware units to form leaderboards. The tool can also use Plotly to generate interactive HTML reports and publish them to the Hugo website or submit them to public leaderboards.

Website

A Hugo static blog named “TzJ’s Net”, using the PaperMod theme, with the target site being https://tzj2006.github.io/.

Main capabilities include:

• Only compressing media files that have changed after .last_build
• Compressing images using pngquant
• Compressing videos using HandBrakeCLI
• Generating bilingual content using local models
• Automatically building the Hugo website
• Automatically committing and pushing the GitHub Pages deployment repository

Daily, weekly, and monthly reports, research reports, benchmark pages, and images are written directly by the deployment process:

tools/website/content
tools/website/static

Automatically generated files carry the gadget_generated tag. Hand-written files without this tag will not be overwritten.

tools/website/public/ is an independent deployment repository corresponding to tzj2006/tzj2006.github.io; files should not be manually committed to it.

Translator

A Gradio-based local document translation web application with an interface similar to Google Translate.

Supports translating:

• Plain text
• .md
• .txt
• .pdf
• .docx
• Images

It attempts to preserve Markdown formatting and protects snippets like code blocks, URLs, and Hugo shortcodes.

Translation is performed entirely via local inference without using cloud LLM APIs. It automatically selects the backend via common.engine.create_engine():

• Prioritizes Ollama if the corresponding model has been pulled
• Falls back to transformers on Windows
• Prioritizes vLLM on Linux
• Uses llama.cpp/GGUF for low VRAM scenarios

The default model is:

tencent/Hy-MT2-1.8B

The GGUF version is:

tencent/Hy-MT2-1.8B-GGUF

Models are automatically downloaded upon first use. Once loaded, models remain in memory, with lazy loading applied when switching models as needed.

When the source language is set to auto, it automatically detects based on the proportion of CJK characters in the text; when the target language is set to auto, it automatically switches between Chinese-to-English and English-to-Chinese.

4. Common Modules and Operations Scripts

common/

A common Python package providing:

• A unified two-layer LLM API
• JSON parsing and repair
• SHA-256 disk caching with namespaces and TTL
• Atomic writes and content hashing
• Local translation engine
• Bilingual content generation
• Cross-platform Hugo deployment

scripts/

Main scripts include:- sync.py：Syncs summarize, website, research, benchmark, and backups data via rclone, and also supports generating and deploying DAG sites.

• onboard.py：One-time initialization for new machines, responsible for SSH, Claude/Codex CLI, authentication, Python extras, AI Companion, tool configuration, and rclone bootstrap.
• smoke.sh：Read-only smoke test, checks help, hardware info, and imports without calling LLMs, network, or performing writes.
• serve_local_llm.sh：Creates Ollama model variants suitable for summarize and outputs environment variables.
• language.py：Hugo bilingual content audit and summarize report renaming.
• profile_translation.py：Translation engine GPU profiler.

AI Companion

../ai-companion/ is a standalone Node.js/TypeScript repository providing:

• Function-level code change logs
• Test and HTML report generation
• /idea → /ccplan → /ccedit planning and execution workflow
• Claude Code and Codex integration
• Skills such as optimization, debugging, auditing, cleaning, paper writing, etc.

Node.js 18+ is only required when using this standalone repository.

II. Tutorial for First-time Gadget Users

The following tutorial is strictly limited to the information and commands provided in the README. The README places more detailed configuration fields, data formats, and FAQs in TUTORIAL.md and each tool’s own tutorials; therefore, no unprovided configuration items will be guessed here.

1. Environment Preparation

Python

Python 3.10 or higher is required.

The README recommends using a conda environment named AI:

conda activate AI

The README does not provide the command to create this conda environment, so a Python 3.10+ environment must be prepared in advance.

Node.js

Node.js 18+ is only required when using the standalone AI Companion repository:

../ai-companion/

When running only the Python tools of Gadget, the README does not require Node.js to be installed.

Other External Components

Different tools may also require:

• rclone: Cross-device synchronization
• Hugo: Blog building and local preview
• pngquant: Image compression
• HandBrakeCLI: Video compression
• Ollama: Default LLM or translation backend
• PyTorch, NumPy, Plotly: benchmark
• Gradio, GGUF/transformers: translator

Specific tool dependencies can also be found in requirements.txt within each tool’s directory.

2. Installation

All following commands should be executed in the Gadget repository root directory, unless a directory switch is explicitly requested before the command.

Installing Public Packages

pip install -e .

This is the installation method for the common/ base package that all tools depend on.

After installation, the following may be generated in the repository root:

build/
gadget.egg-info/

These are build artifacts that have been gitignored and should not be committed.

Installing All Extras for Main Tools

pip install -e ".[all]"

This all includes:

• summarize
• research
• benchmark
• website

But does not include translator.

Installing Translator Separately

pip install -e ".[translator]"

Installing Only Website-related Dependencies

pip install -e ".[website]"

This extras includes torch and transformers required for website translation.

3. Basic Configuration

Root Configuration File

The main settings for all tools are located in the repository root at:

config.json

This file is not tracked by Git. The README requires copying from the following example:

config.example.json

The README does not provide specific copy commands or field contents, so config.json should be created manually by referring to the example file.

To use a different configuration file path, you can set:

GADGET_CONFIG

LLM Backend

Summarize and Research uniformly support the following --api values:

• ollama
• claude_cli
• anthropic
• openai

The default value is ollama.

You can also select the backend via global environment variables:

GADGET_LLM_BACKEND

Note:

• ollama uses local Ollama and does not require an API key.
• claude_cli reuses the login status of Claude Code CLI and does not require an API key.
• The README does not provide specific variable names or configuration fields for Anthropic and OpenAI keys, so do not guess; please refer to project tutorials or configuration examples.

Translation Configuration

The translation model can be overridden via the following environment variables:

GADGET_TRANSLATION_MODEL

The translation backend can be selected via the following variable:

GADGET_TRANSLATION_BACKEND

Default model:

tencent/Hy-MT2-1.8B

The model will be automatically downloaded upon first use.

Token and Initialization Configuration

API keys and the new machine initialization table are located at:

tokens/

The initialization table is:

tokens/onboard.yaml

tokens/ has been gitignored; never commit its contents.

README note: After filling in tokens/onboard.yaml and running scripts/onboard.py, the repository-level one-time machine configuration will be completed, including:

• SSH configuration
• Claude/Codex CLI installation and authentication
• Python extras installation
• AI Companion installation
• Configuration for each tool
• rclone bootstrap

The README does not provide a full invocation example for onboard.py in the command block, so its parameters are not expanded here.

4. Summarize Usage Tutorial

Summarize recommends using a unified entry point:

python -m summarize

Step 1: Export conversation records on the current device

python -m summarize daily export

This command executes the first stage of the multi-device workflow, exporting all dates that have not yet been exported.

This stage should be executed on every device containing AI conversation records.

Step 2: Sync and merge by day

python -m summarize daily merge --sync-all

This command syncs data for all dates and merges them day by day to generate daily reports.

Generate a weekly report for a specific week

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

Where:

• 2026-W12 represents Week 12 of 2026.
• --deploy means generate and then deploy.

Generate a monthly report for a specific month

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

Where:

• 2026-02 represents February 2026.
• --deploy means generate and then deploy.

Run the full workflow with one click

python -m summarize auto --deploy

It will sequentially complete:

export → merge → weekly → monthly → deploy

Old Entry Point

The following old scripts are still compatible:

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

But the README recommends using:

python -m summarize

The README does not list specific parameters for the old entry point, so one should not assume the new entry point parameters are identical to the old ones.

5. Research Usage Tutorial

The unified entry point for Research is:

python tools/research/research_scout.py

Full Paper Search and Report Workflow

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

This command executes:

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

my-project is the project name used in the README example.

Search for papers using natural language

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

The tool will automatically select search sources based on the question.

Generate researcher profiles

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

Researcher profiles may include:

• Paper data from ArXiv and Semantic Scholar
• Citation data
• Research trajectory analysis
• tier score
• Advisor-student relationship discovery
• Name disambiguation
• Reverse lookup

Specific output fields are not detailed in the README.

Analyze paper citation graphs

Using arXiv ID:

python tools/research/research_scout.py citations 2301.12597

The README indicates that this position also supports DOI, but does not provide a DOI example format, so no extra examples are fabricated here.

Analysis content includes:

• Forward citations
• Backward references
• LLM-driven impact interpretation

Deploy reports to Hugo

python tools/research/research_scout.py deploy

Deep Paper Insights

The README states that Research supports --insight, which can:

• Download full paper text
• Analyze writing structure
• Analyze publication strategies
• Extract reusable core knowledge
• Match OpenReview
• Analyze review consensus and controversies
• Synthesize research writing guides

However, the README does not provide the complete --insight command combination, so it should not be guessed which subcommand it follows. Refer to tools/research/TUTORIAL.md when using it.

6. Benchmark Usage Tutorial

All Benchmark commands must first enter their respective directories:

cd tools/benchmark

Execute all benchmarks

python -m benchmark.cli

Results will be appended to the CSV and will not overwrite existing results.

Test CPU only

python -m benchmark.cli --cpu-only

Test GPU only

python -m benchmark.cli --gpu-only

The tool will automatically detect:

• CUDA
• Apple MPS
• Intel XPU

Execute tests and generate HTML report

python -m benchmark.cli --report

Reports use Plotly to generate interactive charts.

Execute tests, generate reports, and deploy

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

Reports will be published to the Hugo website at:

/benchmark/

Testing employs warmup, formal measurement, median statistics, IQR outlier removal, and GPU synchronization. Since the CSV uses append mode, it can be run repeatedly on different hardware to accumulate leaderboard data.

7. Website Usage Tutorial

Install website dependencies

Run in the repository root:

pip install -e ".[website]"

macOS/Linux: Build and Publish

cd tools/website && bash update.sh

This workflow will execute:

• Incremental compression of modified images and videos
• Local model bilingual translation
• Hugo build
• Commit and push to the GitHub Pages deployment repository

Windows: Build and Publish

Run in the repository root:

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

The Windows script will automatically switch to its own directory, so there is no need to execute cd tools/website beforehand.

Local Preview

cd tools/website && hugo server -D

-D will allow the local development server to include draft content.

Website File Notes

Automatically generated content is written directly to:

tools/website/content
tools/website/static

Files marked with gadget_generated may be automatically updated; handwritten files without this mark will not be overwritten.Do not manually submit or directly modify deployment repositories:

tools/website/public/

They are automatically committed and pushed by build scripts.

8. Translator Tutorial

Install Dependencies

pip install -e ".[translator]"

Start Translation Interface

python -m translator

After starting, a Gradio GUI will open in your browser.

In the interface, you can:

• Input text for translation
• Upload .md, .txt, .pdf, .docx or images
• Select source and target languages
• Manage or switch translation models

On the first run, the default model will be downloaded automatically.

When the source language is set to auto, the tool detects the language via CJK character ratio; when the target language is set to auto, it will automatically perform reverse translation between Chinese and English.

9. Data Synchronization

Synchronization is driven by rclone, with configuration located in the sync section of the root directory config.json.

To view the synchronization tool entry:

python scripts/sync.py

Cross-device pushing and pulling are used via:

python scripts/sync.py push

python scripts/sync.py pull

The README also specifies that sync.py supports:

status
bootstrap
config

as well as summarize, website, research, benchmark, backups, and special dag categories, but does not provide the full command combinations for these operations, so parameters are not expanded here.

10. Local Summarize Ollama Environment

The startup and environment variable loading command provided in the README is:

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

This script creates an Ollama variant suitable for Summarize and outputs the environment settings.

Long-term configuration items should be written to the summarize section of the root directory config.json, or you can use GADGET_CONFIG to point to other configuration files.

11. Run Read-only Smoke Test

bash scripts/smoke.sh

This check only performs:

• --help
• --info
• Python import checks

It does not call LLMs, access the network, or write files, making it suitable for basic verification after installation.

12. Where are the output files

All reconstructible artifacts are unified in:

outputs/

The structure is as follows:

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

Hugo content is not staged via outputs/site but is written directly to:

tools/website/content
tools/website/static

13. Important Notes for Use

• Do not commit API keys or onboarding configurations in tokens/.
• Do not commit auto-generated files in outputs/.
• Do not commit build/ and gadget.egg-info/.
• Do not commit data synchronized via rclone.
• Do not directly commit deployment repositories or theme repositories under tools/website/.
• config.json is a local configuration file and should be created from config.example.json.
• Translator is not included in .[all]; you need to install .[translator] separately.
• The website and translation functions use local inference models; downloading tencent/Hy-MT2-1.8B may be required on the first run.
• For more detailed configuration fields, data formats, troubleshooting, and incomplete usage details such as --insight, please refer to the TUTORIAL.md and tool tutorials in the repository; this README alone cannot reliably supplement them.

Project Overview

Gadgets is a collection of daily developer tools covering five categories of tasks:

• Generation of daily, weekly, and monthly reports for AI conversation logs
• Academic paper retrieval, researcher profiling, and citation mapping
• CPU/GPU performance benchmarking
• Automated Hugo blog building, media compression, and publishing
• Local model-driven document translation

Each directory under tools/ is an independently usable tool; the common/ in the root directory provides shared capabilities such as LLM calls, caching, JSON parsing, atomic writes, translation engines, and Hugo deployment. The development workflow and Claude Code skills are not in this repository but in the sibling independent repository ../ai-companion/.

Repository Structure

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 打包与依赖配置

Generated results are unified in outputs/:

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

Hugo website content is written directly to tools/website/content and tools/website/static.

Tool Purposes

Tutorial

1. Environment Preparation

The base environment specified in the README is:

• Python 3.10+
• Recommended to use Conda environment AI
• Node.js 18+: Only required if using the sibling ../ai-companion/ repository
• Website and translation functions require a local inference engine: Ollama is preferred; Linux can use vLLM, Windows can fall back to transformers
• Translation model tencent/Hy-MT2-1.8B will be downloaded automatically upon first use

If using Conda:

conda activate AI

Tool settings are located in the root directory config.json, and README instructions should be copied from config.example.json. This configuration file allows overriding paths via environment variables:

GADGET_CONFIG

Do not commit the following to Git:

• API keys and initialization tables within tokens/
• outputs/
• build/
• gadget.egg-info/
• Deployment repositories and theme repositories under tools/website/
• Auto-generated content and data synchronized via rclone

2. Install Dependencies

First, install shared packages and common tool dependencies in the repository root:

pip install -e ".[all]"

Note: all does not include the translator. If the translator is needed, install it separately:

pip install -e ".[translator]"

If only using website functions:

pip install -e ".[website]"

Each tool directory also has its corresponding requirements.txt, which can be consulted when needed.

3. LLM and Translation Backend Configuration

Supported unified LLM backends include:

• ollama: Default, local Ollama, no API Key required
• claude_cli: Reuses Claude Code CLI login status, no API Key required
• anthropic
• openai

Switching is supported via the --api parameter of each tool, or it can be set globally:

GADGET_LLM_BACKEND

Translation functions use a local inference backend, which can be selected via the following environment variables:

GADGET_TRANSLATION_BACKEND

The default selection order provided in the README is:

ollama → llamacpp / vllm / transformers

The default model is:

tencent/Hy-MT2-1.8B

The translation model can be replaced via the following environment variables:

GADGET_TRANSLATION_MODEL

4. Using the Conversation Summary Tool: Summarize

This tool adopts a two-stage, multi-device workflow:

1. Export conversation logs from each device.
2. Aggregate data via cloud drive synchronization or manual copying, and merge by date.
3. Generate daily reports first, then generate weekly and monthly reports.

Export all dates that have not yet been exported:

python -m summarize daily export

Sync all dates and merge them day by day:

python -m summarize daily merge --sync-all

Generate weekly reports and deploy:

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

Generate monthly reports and deploy:

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

Execute the complete one-click workflow from export and merge to weekly/monthly reports and deployment:

python -m summarize auto --deploy

The old entry point remains compatible, but the modular form above is recommended:

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

This tool automatically discovers and summarizes token usage and costs for various Agent CLIs through the source-specific commands of ccusage 20.x. Optional LLM backends are ollama, claude_cli, anthropic, and openai.

5. Using the Paper Research Tool: Research

The unified entry point is:

python tools/research/research_scout.py

Execute a complete paper discovery process for a specific project: search, three-stage evaluation, and report generation:

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

Search for papers using natural language; the tool will automatically route to the appropriate data source:

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

Generate a profile for a researcher:

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

Analyze citation maps based on arXiv ID or DOI:

python tools/research/research_scout.py citations 2301.12597

Deploy research reports to Hugo:

python tools/research/research_scout.py deploy

The research tool includes four types of capabilities:

• Paper Discovery: From arXiv, bioRxiv, PubMed, through a three-stage process of rapid screening, deep evaluation, and citation impact analysis.
• Deep Paper Insights: Downloads full texts via --insight to analyze writing structure, publication strategy, and reusable knowledge, and also matches OpenReview peer reviews.
• Researcher Profiling: Generates research trajectories, scores, and relationship inferences by combining papers and citation data from ArXiv and Semantic Scholar.
• Citation Mapping: Performs forward citation and reference analysis based on the Semantic Scholar API, with impact interpreted by LLM.

Its LLM backend can also be switched via --api.

6. Using the Performance Testing Tool: Benchmark

All commands require entering the tool directory first:

cd tools/benchmark

Run all benchmarks:

python -m benchmark.cli

Test CPU only:

python -m benchmark.cli --cpu-only

Test GPU only:

python -m benchmark.cli --gpu-only

Run tests and generate an HTML report:```bash python -m benchmark.cli –report

Generate reports and publish to Hugo's `/benchmark/` :

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

This tool supports actual GPU testing for NVIDIA CUDA, Apple Silicon MPS, and Intel XPU; OpenCL may only appear in --info detection. Results are written to CSV in append mode and will not overwrite existing results, making it suitable for aggregating scores from multiple machines.

7. Using Website Tool: Website

Install website-related dependencies:

pip install -e ".[website]"

Execute incremental compression, Hugo build, and Pages push on macOS or Linux:

cd tools/website && bash update.sh

Execute the corresponding script on Windows:

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

Start the local Hugo preview server, including draft content:

cd tools/website && hugo server -D

The website automatically handles the following:

• Compresses only media files that have changed since .last_build.
• Uses pngquant for images and HandBrakeCLI for videos.
• Automatically generated daily reports, research reports, Benchmark pages, etc., are written directly to the Hugo content root directory.
• Generated files will carry the gadget_generated tag; handwritten files without this tag will not be overwritten.
• The build script will automatically commit and push to the independent GitHub Pages deployment repository in tools/website/public/.

Do not commit content directly to tools/website/public/.

8. Using Document Translator: Translator

Install the translator:

pip install -e ".[translator]"

Start the Gradio GUI:

python -m translator

After starting, the local translation page will open in your browser.

Supported translations:

• Plain text
• .md
• .txt
• .pdf
• .docx
• Images

The translator will protect code blocks, URLs, Hugo shortcodes, etc., in Markdown to preserve the original format as much as possible. The source language can be set to auto, which identifies based on the proportion of CJK characters in the text; when the target language is set to auto, it will automatically switch between Chinese and English.

9. Operations and Sync Scripts

View or execute centralized rclone data synchronization:

python scripts/sync.py

The README explicitly lists the push and pull forms for cross-device synchronization:

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

The sync configuration is located in the config.json section of the root directory sync, and other configuration files can also be specified via GADGET_CONFIG.

One-time initialization process for new machines:

1. Fill out tokens/onboard.yaml.
2. Execute:

python scripts/onboard.py

It will complete SSH, Claude/Codex CLI installation and authentication, pip extras, ai-companion, configuration for various tools, and rclone initialization.

Execute a read-only smoke test that produces no network, LLM calls, or writes:

bash scripts/smoke.sh

Create an Ollama variant optimized for summarize and output environment configurations:

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

For system-level installation of SSH public keys, Claude Code, Codex, Superpowers, Ponytail, and AI Companion on Ubuntu 22.04/24.04 servers, refer to the scripts in the sibling repository for help:

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

I. Project Summary

1. What is Gadget

Gadget is a collection of practical development tools composed of multiple independent tools, covering:

• AI conversation daily, weekly, and monthly report generation
• Academic paper discovery and researcher analysis
• CPU/GPU performance benchmarking
• Hugo blog automatic building and publishing
• Local model-driven document translation

Each tools/ subdirectory is a tool that can be used independently. The common/ in the repository root provides shared capabilities, including:

• LLM calls
• JSON parsing and repair
• Disk caching
• Atomic writes
• Local model translation
• Hugo deployment

Development workflows, code change tracking, and Claude Code skills are provided by ../ai-companion/ outside the repository.

2. Repository Structure

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 打包配置

When modifications are needed:

3. Functions of Each Tool

summarize

Reads AI conversation logs from sources such as Claude Code, Codex, Cursor Agent, ChatGPT, etc., and calls LLMs to generate:

• Daily reports
• Weekly reports
• Monthly reports and trend summaries

It uses a multi-device two-stage process:

1. Each device exports conversation logs
2. Aggregates data and generates reports by day

It also uses ccusage to statistics token usage and costs for different Agent CLIs.

Supports four LLM backends:

• ollama: Default, local Ollama, no API Key required
• claude_cli: Reuses Claude Code login status
• anthropic
• openai

research

An academic research tool containing four types of capabilities:

• Paper Discovery: Searches arXiv, bioRxiv, PubMed, and performs a three-stage LLM evaluation
• Deep Paper Insights: Analyzes paper writing structure, publication strategies, core knowledge, and OpenReview reviews
• Researcher Profiling: Combines ArXiv and Semantic Scholar data to analyze research trajectories, citations, and advisor-student relationships
• Citation Mapping: Analyzes forward citations and backward references of papers

benchmark

A cross-platform CPU/GPU floating-point performance testing tool.

Supports:

• NVIDIA CUDA
• Apple Silicon MPS
• Intel XPU

Supports multiple precisions, including FP64, FP32, FP16, BF16, and experimental FP8.

Results are appended to CSV and will not overwrite historical data; it can also generate Plotly interactive HTML reports and leaderboards.

website

A Hugo-based blog site using the PaperMod theme, published to GitHub Pages.

Main features:

• Incremental compression of images and videos
• Automatic translation of bilingual content
• Automatic building of the Hugo website
• Automatic commit and push of the deployment repository
• Receives automatically generated content such as daily reports, weekly reports, research reports, and benchmark pages

Website content writing:

tools/website/content
tools/website/static

tools/website/public/ is a separate deployment repository and should not be committed directly to the current project.

translator

A Gradio-based local document translator, supporting:

• Text
• Markdown
• TXT
• PDF
• DOCX
• Images

It protects Markdown code blocks, URLs, Hugo shortcodes, and other content. It uses the local model tencent/Hy-MT2-1.8B by default, and also supports GGUF versions.

The translation backend is automatically selected by the shared translation engine:

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

4. common/, scripts/ and outputs/

common/

A shared Python package used by various tools after installation, containing LLM, cache, IO, translation, and Hugo deployment functionalities.

scripts/

Main scripts include:

• sync.py: Uses rclone to synchronize data
• onboard.py: New machine initialization
• smoke.sh: Performs read-only smoke tests on all tools
• serve_local_llm.sh: Creates Ollama model variants suitable for summarize
• language.py: Checks Hugo bilingual content
• profile_translation.py : Analyzes translation engine GPU performance

outputs/

All generated artifacts are concentrated here:

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

This directory is ignored by Git and can be automatically regenerated.

II. Chinese User Tutorial

1. Environment Preparation

Project requirements:

• Python 3.10+
• Node.js 18+, only required for ../ai-companion/
• Extra dependencies for each tool can be found in the corresponding directory’s requirements.txt

The README recommends using a conda environment named AI:

conda activate AI

If using AI Companion, it also needs to be placed in the sibling directory of the current repository:

../ai-companion/

It is an independent repository and does not belong to Gadget itself.

2. Installing Basic Dependencies

Execute in the repository root:

pip install -e .

This installs the common/ shared package from the root directory in editable mode.

To install dependencies for summarize, research, benchmark, and website, you can execute:

pip install -e ".[all]"

Note: all does not include translator.

Install translator dependencies:

pip install -e ".[translator]"

If website functionality is needed, you can execute:

pip install -e ".[website]"

Website dependencies include PyTorch and transformers required for translation.

3. Configuration Files and Keys

Tool settings in the project root directory are located at:

config.json

The README states that this file is ignored by Git and should be configured after copying from:

config.example.json

Other configuration file paths can also be specified via environment variables:

GADGET_CONFIG

API Keys and initialization configurations are placed in:

tokens/

This directory is also ignored by Git and cannot be committed to the repository.

LLM backends can be uniformly selected through --api:

• ollama
• claude_cli
• anthropic
• openai

They can also be set via global environment variables:

GADGET_LLM_BACKEND

The translation backend can be controlled via:

GADGET_TRANSLATION_BACKEND

And the translation model can be overridden via:

GADGET_TRANSLATION_MODEL

4. New Machine Initialization

The project provides a one-time initialization script. The README requires filling out ```text tokens/onboard.yaml

 first, and then running:

```bash
python scripts/onboard.py

This script will automatically handle:- SSH configuration

• Claude/Codex CLI installation and authentication
• pip extras installation
• ai-companion installation
• Configuration of each tool
• rclone initialization

The server-level Ubuntu 22.04/24.04 initialization script is located in the ai-companion repository:

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

5. Data Synchronization and Basic Checks

The project uses rclone for cross-device data synchronization. See the synchronization script for help:

python scripts/sync.py

Synchronize data:

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

Run a read-only smoke check:

bash scripts/smoke.sh

This check verifies the help information, info detection, and import of each tool; it will not call LLM, access the network, or write data.

III. How to Use Each Tool

1. Summarize: Generate AI Conversation Reports

Daily Report Workflow

Phase 1: Export all dates that have not yet been exported:

python -m summarize daily export

Phase 2: Synchronize all dates and merge them day by day:

python -m summarize daily merge --sync-all

Generate a weekly report for a specified week and deploy to Hugo:

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

Generate a monthly report for a specified month and deploy to Hugo:

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

One-click Full Workflow Execution

python -m summarize auto --deploy

This command executes:

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

Legacy entry points are still compatible, for example:

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

But the README recommends using:

python -m summarize

LLM Backend

Summarize uses local Ollama by default, but also supports:

ollama
claude_cli
anthropic
openai

The specific backend is switched via the --api parameter.

2. Research: Paper Search and Researcher Analysis

Generate Research Project Report

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

This workflow performs paper searching, three-stage evaluation, and report generation.

Search for Papers Using Natural Language

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

The tool automatically selects data sources based on the question.

Generate Researcher Profiles

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

It retrieves paper and citation data and generates research trajectory analysis.

Analyze Paper Citation Networks

python tools/research/research_scout.py citations 2301.12597

Parameters can be an arXiv ID or a DOI.

Deploy Research Reports

python tools/research/research_scout.py deploy

The LLM backend for Research also supports:

ollama
claude_cli
anthropic
openai

Switched uniformly via --api.

3. Benchmark: Run CPU/GPU Performance Tests

README special note: All Benchmark commands require entering the directory first:

cd tools/benchmark

Run all benchmarks:

python -m benchmark.cli

Results will be appended to the CSV.

Run only CPU tests:

python -m benchmark.cli --cpu-only

Run only GPU tests:

python -m benchmark.cli --gpu-only

Run tests and generate an HTML report:

python -m benchmark.cli --report

Run tests, generate reports, and deploy to Hugo:

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

The tool automatically detects CUDA, Apple MPS, and Intel XPU. OpenCL may only appear in the --info detection results and does not mean an OpenCL benchmark will be executed.

4. Website: Build and Preview Hugo Website

Install website dependencies:

pip install -e ".[website]"

macOS/Linux: Build and Publish

cd tools/website && bash update.sh

This workflow includes:

1. Incremental compression of media files
2. Executing Hugo build
3. Pushing to GitHub Pages

Images are compressed using pngquant, and videos are processed using HandBrakeCLI.

Windows: Build and Publish

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

This script will automatically switch to its own directory.

Local Preview

cd tools/website && hugo server -D

-D indicates including drafts during preview.

Automatically generated content in the website is written directly to:

tools/website/content
tools/website/static

Automatically generated files with the gadget_generated tag can be updated by the deployment process; handwritten files without this tag will not be overwritten.

5. Translator: Start Local Document Translator

Install translator dependencies:

pip install -e ".[translator]"

Start the Gradio GUI:

python -m translator

A browser will open after starting.

The translator supports text and the following file types:

.md
.txt
.pdf
.docx
图片

The default model is:

tencent/Hy-MT2-1.8B

The GGUF version is:

tencent/Hy-MT2-1.8B-GGUF

The model will be downloaded automatically upon first use. The translator prioritizes local Ollama by default; on Linux, vLLM can be used; on Windows, it can fall back to transformers, and it also supports the low-VRAM GGUF/llama.cpp path.

When the source language is set to auto and the target language is set to auto, it will automatically switch between Chinese and English.

IV. Common Notes

• Files in outputs/ are automatically generated and should not be committed.
• tokens/ contains keys and initialization information and cannot be committed.
• build/ and gadget.egg-info/ are build files produced by installation.
• Do not directly commit tools/website/public/ or the website theme/deployment repository.
• Cross-device synchronization requires configuring rclone first.
• Website and translation functions depend on local inference engines, defaulting to Ollama.
• ../ai-companion/ is an independent repository responsible for development workflows and skills.
• The project uses the GPL-3 license.

The following content is based solely on the README you provided; the summary and tutorial will not supplement commands or parameters not appearing in the README.

I. Project Summary

Gadget is a collection of practical tools accumulated during daily development, covering scenarios such as AI conversation daily/weekly/monthly report generation, paper discovery and researcher analysis, performance benchmarking, Hugo blog automation, document translation, etc.

Its core design is: each directory under tools/ is a tool that can be used independently; the common/ in the repository root is a shared infrastructure package, installed via pip install -e ., providing common capabilities like LLM calling, JSON parsing, disk caching, atomic writing, translation, Hugo deployment, etc., to various tools. The development workflow and Claude Code skills are not within this repository but are provided by the independent repository in the adjacent directory ../ai-companion/ and integrated via hooks.

Repository Structure

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/ is used for centralized storage of generation results:

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

Hugo website content is not written to outputs/site first, but is written directly to tools/website/content|static by the deployment process.

Roles of Each Tool

tools/summarize/：AI conversation report generation tool.
Automatically reads AI conversation records from Claude Code, Codex, Cursor Agent, ChatGPT, general JSON, etc., and calls LLMs to generate daily, weekly, and monthly trend summaries. Supports multi-device workflows: each device exports conversation logs, aggregates them via cloud drive synchronization or manual copying, and then generates the final report. Uses ccusage 20.x to statistics token usage and costs for each agent CLI. The LLM backend can be switched uniformly via --api, including ollama, claude_cli, anthropic, and openai.

tools/research/：Academic research tool.
The unified entry point is tools/research/research_scout.py, providing four types of capabilities: paper discovery, deep paper insights, researcher profiles, and citation network analysis. Supports arXiv, bioRxiv, PubMed, Semantic Scholar, and uses LLMs to complete filtering, evaluation, impact analysis, writing structure analysis, research trajectory analysis, etc.

tools/benchmark/：CPU/GPU performance benchmarking tool.
Measures floating-point performance across different hardware and precision levels on multiple platforms, supporting actual GPU execution for NVIDIA CUDA, Apple Silicon MPS, and Intel XPU. Results are appended to a CSV, and it can generate Plotly interactive HTML reports and leaderboards, as well as support deployment to Hugo websites.

tools/website/：Hugo blog site.
This is the Hugo static blog “TzJ’s Net”, using the PaperMod theme, deployed to GitHub Pages. It features an incremental image/video compression workflow, using pngquant for images and HandBrakeCLI for videos. Automatically generated content is written to tools/website/content|static with a gadget_generated tag; handwritten files without this tag will not be overwritten. tools/website/public/ is a separate deployment repository and should not be committed directly.

tools/translator/：Gradio document translator.
Based on the common translation engine, it provides a local translation web page similar to Google Translate. It supports translating text and files such as .md, .txt, .pdf, .docx, and images, while attempting to preserve Markdown formatting and protecting code blocks, URLs, Hugo shortcodes, etc. The default model is tencent/Hy-MT2-1.8B, with a GGUF variant tencent/Hy-MT2-1.8B-GGUF.

common/：Shared infrastructure.
Provides capabilities such as unified LLM calling, JSON parsing and repair, SHA-256 disk caching, atomic writing, content hashing, local inference translation engine, bilingual content generation, and cross-platform Hugo deployment.

scripts/：Operations and maintenance scripts.
Includes sync.py data synchronization, onboard.py new machine initialization, smoke.sh read-only smoke checks, serve_local_llm.sh local Ollama variant configuration, language.py Hugo bilingual auditing and report renaming, profile_translation.py translation engine GPU profiling, etc.

../ai-companion/：Independent repository.
Does not belong to the gadget repository itself. It is responsible for function-level code change records, testing and HTML report generation, the /idea→/ccplan→/ccedit planning and execution workflow, and Claude Code skills.

II. Chinese Usage Tutorial

1. Environment Preparation

The basic requirements listed in the README are as follows:

# Python 版本要求
Python 3.10+

It is recommended to use the conda environment AI:

conda activate AI

If you need to use the adjacent ../ai-companion/ repository, you will need:

Node.js 18+

Specific dependencies for each tool can be found in the corresponding requirements.txt directory.To install the full extras for common, summarize, research, benchmark, and website, you can run the following in the repository root:

pip install -e ".[all]"

Note: all does not include translator. The translator needs to be installed separately:

pip install -e ".[translator]"

The website and translation functions use a local inference engine. The README states that Ollama is used by default; vLLM is available on Linux, and transformers is available as a fallback on Windows. Model tencent/Hy-MT2-1.8B will be automatically downloaded upon the first run.

2. Configuration Preparation

Tool configuration is located in config.json at the repository root, which is gitignored. The README explains that it should be copied from config.example.json.

If you need to override the configuration file path, you can set:

GADGET_CONFIG

The LLM backend can be switched via the --api parameter of each tool. The optional backends mentioned in the README are:

ollama
claude_cli
anthropic
openai

You can also use a global environment variable:

GADGET_LLM_BACKEND

The translation backend is controlled by the following environment variable:

GADGET_TRANSLATION_BACKEND

The README states that the translation path defaults to using a local Ollama server, followed by llamacpp / vllm / transformers. The translation model can be overridden via the following environment variable:

GADGET_TRANSLATION_MODEL

API keys and onboarding sheets are located in the tokens/ directory, which is gitignored; the README specifically warns not to commit its contents.

3. Installation

Install the shared package and main tool dependencies in the repository root:

pip install -e ".[all]"

To use the document translator, install the translator extras:

pip install -e ".[translator]"

If you only target the website functionality, the installation command provided in the README is:

pip install -e ".[website]"

4. New Machine Initialization

The README mentions that new machine configuration can use scripts/onboard.py. The process involves first filling out:

tokens/onboard.yaml

Then running:

python scripts/onboard.py

It will complete SSH configuration, Claude/Codex CLI installation and authentication, pip extras, ai-companion installation, tool configurations, rclone bootstrap, etc.

Server-level system installation has been migrated to ../ai-companion/:

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

5. Data Synchronization

Cross-device data synchronization uses scripts/sync.py and requires rclone configuration.

The general running method provided in the README is:

python scripts/sync.py

It also mentions that cross-device synchronization can use:

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

Configuration is located in the sync section of config.json at the repository root; you can also use GADGET_CONFIG to override the configuration path.

If you only want to sync data, the README explicitly states in the repository structure section:

python scripts/sync.py

6. Summarize: AI Chat Daily, Weekly, and Monthly Reports

This tool recommends using the new module entry point:

python -m summarize

A typical workflow is as follows.

Export all dates that have not yet been exported:

python -m summarize daily export

Sync all dates and merge them day by day:

python -m summarize daily merge --sync-all

Generate and deploy a weekly report for a specific week:

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

Generate and deploy a monthly report for a specific month:

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

Execute the full workflow in one click: Export, merge, weekly report, monthly report, and deploy:

python -m summarize auto --deploy

The old entry point is still compatible:

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

But the README recommends using:

python -m summarize

The LLM backend can be switched uniformly via --api. Values listed in the README include:

ollama
claude_cli
anthropic
openai

7. Research: Paper Discovery, Researcher Analysis, Citation Graphs

The unified entry point is:

python tools/research/research_scout.py

Run the full paper discovery workflow: Search, three-stage evaluation, and report generation:

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

Natural language search; the tool will automatically route the source:

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

Generate researcher profiles:

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

Perform citation graph analysis by arXiv ID or DOI:

python tools/research/research_scout.py citations 2301.12597

Deploy research reports to Hugo:

python tools/research/research_scout.py deploy

All LLM functions also support switching backends via --api:

ollama
claude_cli
anthropic
openai

8. Benchmark: CPU/GPU Performance Benchmarking

The README explicitly states that all benchmark commands require entering tools/benchmark/ first:

cd tools/benchmark

Run all benchmarks and append results to a CSV:

python -m benchmark.cli

Run CPU only:

python -m benchmark.cli --cpu-only

Run GPU only:

python -m benchmark.cli --gpu-only

Run benchmarks and generate an HTML report:

python -m benchmark.cli --report

Generate reports and publish to Hugo’s /benchmark/:

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

The README explains that the tool automatically detects CUDA, Apple MPS, and Intel XPU. OpenCL may only appear in --info detection, but the README does not provide specific command examples for --info.

9. Website: Hugo Blog

Install website dependencies:

pip install -e ".[website]"

Incremental compression, Hugo build, and push to GitHub Pages under macOS/Linux:

cd tools/website && bash update.sh

Run PowerShell script under Windows; the script will switch to its own directory:

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

Local preview, including drafts:

cd tools/website && hugo server -D

The README specifically notes:

tools/website/public/ is a separate deployment repository tzj2006/tzj2006.github.io, which is automatically committed and pushed by build scripts; do not commit it directly.

Automatically generated content will be written to:

tools/website/content
tools/website/static

Files with the gadget_generated tag can be managed by the automated process; handwritten files without this tag will not be overwritten.

10. Translator: Gradio Document Translator

Install translator dependencies:

pip install -e ".[translator]"

Start the Gradio GUI:

python -m translator

The interface will open in your browser after starting.

It supports translating text and files; file types listed in the README include:

.md
.txt
.pdf
.docx
images

Default model:

tencent/Hy-MT2-1.8B

GGUF variants:

tencent/Hy-MT2-1.8B-GGUF

The model can be overridden via environment variables:

GADGET_TRANSLATION_MODEL

The source language can be set to auto via text CJK ratio detection; when the target language is auto, it will automatically switch between Chinese and English.

11. Smoke Checks and Local LLM Helper Scripts

Run a read-only smoke check:

bash scripts/smoke.sh

The README explains that this script checks the --help, --info, and imports of each tool without triggering LLMs, network requests, or writes.

Create a summarize-tuned Ollama variant and print environment variables:

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

Persistent configuration is placed in the summarize section of config.json at the repository root; you can also use GADGET_CONFIG to override the path.

12. Usage Notes

Do not commit these contents:

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

The README explicitly states:

• tokens/ saves API keys and onboarding sheets; it is gitignored, do not commit.
• outputs/ saves all generated files; it is gitignored.
• build/ and gadget.egg-info/ are build artifacts generated by pip install -e ..
• Cross-device synchronization depends on rclone.
• The project license is GPL-3, see LICENSE.

The following is organized solely based on the README.md you provided, without adding commands, parameters, or behaviors outside of the README.

What is the project?

Gadgets is a “set of practical tools accumulated during daily development.” The repository splits different functions into 5 independent tools, where each directory can be used separately, while common capabilities are extracted into the common/ package in the root directory.

It mainly covers:

• AI chat daily/weekly/monthly report generation
• Paper discovery and researcher analysis
• CPU/GPU performance benchmarking
• Hugo blog automated publishing
• Document translation

One important prerequisite: the development workflow and Claude Code skills are not in this repository, but in the adjacent independent repository ../ai-companion/, integrated via hooks.

Repository Structure

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      # 包装配置

What each tool does

• tools/summarize/: Reads AI chat records to generate daily / weekly / monthly summaries.
• tools/research/: Performs paper retrieval, researcher profiling, and citation relationship analysis.
• tools/benchmark/: Performs cross-platform CPU/GPU performance testing and generates reports.
• tools/website/: Automates Hugo blog building, compression, and publishing.
• tools/translator/: Gradio document translator, supporting text and file translation.

common/ is the base library shared by all tools, providing:

• LLM calls
• JSON parsing and fixing
• Disk caching
• Atomic writes
• Translation engine
• Hugo deployment

scripts/ contains some operations scripts:

• sync.py: rclone synchronization
• onboard.py: New machine initialization
• smoke.sh: Read-only smoke tests
• serve_local_llm.sh: Create summarize-tuned Ollama
• Others: language.py, profile_translation.py

Beginner’s Tutorial

The following is organized by “Environment Preparation → Installation → Configuration → Usage of each tool.”

1. Environment Preparation

The README explicitly requires:- Python 3.10+

• Recommended to use conda activate AI
• Node.js 18+ is only for the adjacent ../ai-companion/ repository
• ../ai-companion/ is an independent repository, not inside the current repository
• Specific dependencies required should refer to the requirements.txt under each tool’s directory

If you only intend to use the Python tools in this repository, the focus is on the Python environment; if you also plan to touch ai-companion, prepare Node.js as well.

2. Installation

The installation methods provided in the README consist of three layers:

pip install -e .

This will install the common/ package in the root directory and the basic capabilities of the repository.

If you want to install extra dependencies for most tools, you can use:

pip install -e ".[all]"

README notes:

• all includes summarize / research / benchmark / website
• all does not include translator

If you want to use the translator, install it separately:

pip install -e ".[translator]"

Both the website translation function and the translator depend on a local inference engine. The README mentions:

• Default is Ollama
• vLLM can be used on Linux
• transformers can be used on Windows
• Model tencent/Hy-MT2-1.8B will be automatically downloaded upon the first run

3. Configuration

The configuration points mentioned in the README are as follows:

• There is a config.json in the root directory
• config.json is gitignored by default
• Can be copied from config.example.json
• Can use GADGET_CONFIG to override the configuration file path

Regarding environment variables:

• GADGET_LLM_BACKEND: Unified switching of LLM backends
• GADGET_TRANSLATION_MODEL: Specify translation model
• GADGET_TRANSLATION_BACKEND: Specify translation backend

The tokens/ directory:

• Stores API keys and onboarding tables
• Is also gitignored
• Cannot be committed

If you are initializing a new machine, the README also mentions:

• Fill in tokens/onboard.yaml
• Then run scripts/onboard.py once
• It will automatically handle SSH, Claude/Codex authentication, pip extras, ai-companion installation, tool configurations, and rclone bootstrap

The README does not expand on the full command details in this section, so I will only retain what is explicitly written here without adding extra commands.

4. Typical Usage of Each Tool

4.1 summarize: AI Conversation Daily / Weekly / Monthly Reports

This tool automatically reads your daily AI conversation records and supports:

• Claude Code
• Codex
• Cursor Agent
• ChatGPT
• General JSON

It also combines multi-source command statistics for token and cost using ccusage 20.x.

The recommended command provided in the README is:

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

These commands represent:

• daily export: Export all unexported dates
• daily merge --sync-all: Sync all dates and merge by day
• weekly generate --week ... --deploy: Generate weekly report and deploy
• monthly generate --month ... --deploy: Generate monthly report and deploy
• auto --deploy: One-click full process, referred to as export → merge → weekly → monthly + deploy in the README

Switchable LLM backends:

• ollama, default
• claude_cli
• anthropic
• openai

The README also mentions that old entry points are still available, but the new form is recommended:

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

4.2 research: Paper Discovery, Researcher Analysis, Citation Graph

The unified entry point for this tool is:

python tools/research/research_scout.py

Typical commands provided in the 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

These commands perform:

• report: Full process: Search → Three-stage evaluation → Report
• ask: Natural language search, automatically routes data sources
• profile: Researcher profiling
• citations: Citation graph analysis, supports arXiv ID / DOI
• deploy: Deploy reports to Hugo

Similarly supports switching LLM backends:

• ollama
• claude_cli
• anthropic
• openai

4.3 benchmark: Performance Benchmarking

The README emphasizes: You must enter the directory before running this tool.

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

These commands represent:

• Run all benchmarks by default, results appended to CSV
• Run CPU only
• Run GPU only
• Run benchmarks and generate an HTML report
• Generate report and publish to Hugo’s /benchmark/

The README also states it supports:

• NVIDIA CUDA
• Apple Silicon MPS
• Intel XPU

As well as several precision levels:

• FP64
• FP32
• FP16
• BF16
• FP8 (experimental)

4.4 website: Hugo Blog

This tool is a Hugo static blog site; the README provides three common operations.

Install website-related dependencies:

pip install -e ".[website]"

Build and publish:

• macOS / Linux:

cd tools/website && bash update.sh

• Windows:

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

Local preview:

cd tools/website && hugo server -D

The README also explains:

• It performs incremental image / video compression
• Images use pngquant
• Videos use HandBrakeCLI
• Automatically generated content will be written directly to tools/website/content or tools/website/static
• tools/website/public/ is a separate deployment repository; do not commit directly into it

4.5 translator: Gradio Document Translator

Install dependencies:

pip install -e ".[translator]"

Start GUI:

python -m translator

This tool will open a local translation page in your browser, supporting:

• Text
• .md
• .txt
• .pdf
• .docx
• Images

The README specifically mentions:

• It preserves Markdown formatting
• It protects code blocks, URLs, and Hugo shortcodes
• It uses local inference, not a cloud API
• The default model is tencent/Hy-MT2-1.8B
• Can also be changed via GADGET_TRANSLATION_MODEL or the model management within the GUI

5. Operations and Auxiliary Scripts

These are also explicitly mentioned in the README and can be used directly.

sync.py:

python scripts/sync.py

The README says it is responsible for rclone synchronization, covering:

• summarize
• website
• research
• benchmark
• backups
• and one dag category

smoke.sh:

bash scripts/smoke.sh