READMEs that cannot lie about their numbers.
不会在数字上撒谎的 README 生成器。
CLI tool · Rust · 30 files · MIT
- Quick start
- By the numbers
- Why this project
- Installation
- Usage
- Project structure
- Contributing
- License
Pick the path that matches how you want to use it.
| Action | What to do |
|---|---|
| Bookmark | Star the repo |
| Own a copy | Fork it |
| Use locally | Clone the repository |
git clone https://github.com/TheRealMilesLee/Auto-Generate-Readme.git
cd Auto-Generate-Readme
# optional shallow clone: faster, less history
git clone --depth 1 https://github.com/TheRealMilesLee/Auto-Generate-Readme.git| Metric | Value |
|---|---|
| Folders | 4 |
| Files | 30 |
| Languages | Rust (16), Shell (1), PowerShell (1) |
| Test files | 1 |
READMEs rot for a simple reason: the numbers are written by hand. A hero line that says "3,000 images" is correct on the day it is typed and wrong three months later. Structure drifts the same way.
This tool splits the problem into three layers. Facts are scanned from
the repository — counts, sizes, languages, folders, dependencies, git.
Meaning lives in a reviewable readme.yml. Rendering is
deterministic. A rebuild is boring: same facts in, byte-identical document
out.
Prose is optional. A local llama.cpp server (or Ollama) can write the
narrative sections, but it never supplies a number: every digit is traced
back to the scan or to a human-authored annotation. If a model invents one,
the section is rejected, retried once, and then dropped.
| Manual README pain | What this tool does |
|---|---|
| Numbers go stale | Embeds a facts hash; check fails on drift |
| Structure is reinvented per project | Five presets share one section graph |
| AI invents numbers | Every digit is traced to facts or readme.yml |
| Regeneration overwrites edits | keep blocks survive rebuilds |
Everything runs locally: cargo test plus scripts/check.sh. No hosted CI
is required.
The reference benchmark is a multi-gigabyte wallpaper archive with dozens of folders and thousands of images. That README is excellent because it is specific; this tool makes the specific parts reproducible and the tasteful parts editable. Start with the architecture, the configuration reference, and the benchmarks.
Build from source with the commands for your platform.
cargo build --release
cargo install --path .Scan first, then generate and validate:
readme-gen scan --out .readme/facts.json
readme-gen init --preset showcase --lang en,zh
readme-gen build
readme-gen check --strictTo let a local model write the prose sections (a 7–8B model is enough):
llama-server -m models/Qwen2.5-7B-Instruct-Q5_K_M.gguf \
--host 127.0.0.1 --port 8080 -ngl 99 -c 8192 -fa on --jinja
readme-gen build --llm llama.cpp --model localSee the model guide for 8 GB / 32 GB hardware profiles, quantisation and alternatives.
check is the gate: it verifies links, anchors, markers, bilingual parity,
and that every number in the document exists in the facts or in this file.
Auto-Generate-Readme/
├── docs/
│ ├── ARCHITECTURE.md
│ ├── BENCHMARKS.md
│ ├── CONFIGURATION.md
│ ├── DESIGN-v2.md
│ └── MODELS.md
├── scripts/
│ ├── check.ps1
│ └── check.sh
├── src/
│ ├── annotations.rs
│ ├── error.rs
│ ├── glob.rs
│ ├── json.rs
│ ├── lang.rs
│ ├── lib.rs
│ ├── llm.rs
│ ├── main.rs
│ ├── outline.rs
│ ├── render.rs
│ ├── scan.rs
│ ├── sha256.rs
│ ├── util.rs
│ ├── validate.rs
│ └── yaml.rs
├── tests/
│ └── integration.rs
├── .gitattributes
├── .gitignore
├── Cargo.lock
├── Cargo.toml
├── CONTRIBUTING.md
├── LICENSE
└── readme.yml
Issues and pull requests are welcome. Please keep changes small and focused, and run the test suite before opening a PR.
See CONTRIBUTING.md for details.
Released under the MIT license. See LICENSE.
按你的使用方式选一条路径。
| 操作 | 说明 |
|---|---|
| 收藏 | 点 Star |
| 自己留一份 | Fork 到自己的账号 |
| 本地使用 | 克隆仓库 |
git clone https://github.com/TheRealMilesLee/Auto-Generate-Readme.git
cd Auto-Generate-Readme
# 可选浅克隆: 更快，历史更少
git clone --depth 1 https://github.com/TheRealMilesLee/Auto-Generate-Readme.git| 指标 | 数值 |
|---|---|
| 目录 | 4 |
| 文件 | 30 |
| 语言 | Rust (16), Shell (1), PowerShell (1) |
| 测试文件 | 1 |
README 会过期，原因很朴素：数字是手写的。首页写着「3,000 张图片」，写下的 那天是对的，三个月后就是错的；结构也会以同样的方式漂移。
这个工具把问题拆成三层。事实由仓库扫描得到——数量、体积、语言、目录、
依赖、git；意义放在可评审的 readme.yml；渲染是确定性的。于是重建
变得很无聊：同样的输入，产出逐字节一致。
散文是可选的。本地 llama.cpp 服务（或 Ollama）可以撰写叙事章节，但它不
提供任何数字：每个数字都能追溯到扫描结果或人工注解。模型若编造数字，该章节
会被拒绝、重试一次，然后丢弃。
| 手工 README 的痛点 | 这个工具的做法 |
|---|---|
| 数字会过期 | 写入事实 hash，check 在漂移时失败 |
| 每个项目重造结构 | 五个 preset 共用一张章节图 |
| 模型编造数字 | 每个数字都追溯到事实或 readme.yml |
| 重新生成覆盖手写内容 | keep 区块跨重建保留 |
一切都在本地完成：cargo test 与 scripts/check.sh，不依赖托管 CI。
参照样本是一份数 GiB、几十个目录、数千张图片的壁纸归档。那份 README 之所以 好，是因为它足够具体；这个工具让具体的部分可复现，让有品味的部分可编辑。可以 先读 架构说明、配置参考 与 性能基准。
按所在平台从源码构建。
cargo build --release
cargo install --path .先扫描，再生成和校验：
readme-gen scan --out .readme/facts.json
readme-gen init --preset showcase --lang en,zh
readme-gen build
readme-gen check --strict允许本地模型撰写散文（7–8B 已经够用）：
llama-server -m models/Qwen2.5-7B-Instruct-Q5_K_M.gguf \
--host 127.0.0.1 --port 8080 -ngl 99 -c 8192 -fa on --jinja
readme-gen build --llm llama.cpp --model local模型大小、量化、显存预算与替代方案见 模型指南。
check 是闸门：它检查链接、锚点、标记、双语对齐，以及文档里的每个数字
是否都存在于事实或本文件中。
Auto-Generate-Readme/
├── docs/
│ ├── ARCHITECTURE.md
│ ├── BENCHMARKS.md
│ ├── CONFIGURATION.md
│ ├── DESIGN-v2.md
│ └── MODELS.md
├── scripts/
│ ├── check.ps1
│ └── check.sh
├── src/
│ ├── annotations.rs
│ ├── error.rs
│ ├── glob.rs
│ ├── json.rs
│ ├── lang.rs
│ ├── lib.rs
│ ├── llm.rs
│ ├── main.rs
│ ├── outline.rs
│ ├── render.rs
│ ├── scan.rs
│ ├── sha256.rs
│ ├── util.rs
│ ├── validate.rs
│ └── yaml.rs
├── tests/
│ └── integration.rs
├── .gitattributes
├── .gitignore
├── Cargo.lock
├── Cargo.toml
├── CONTRIBUTING.md
├── LICENSE
└── readme.yml
欢迎提交 Issue 和 Pull Request。请保持改动小而聚焦，并在提交前跑完测试。
详见 CONTRIBUTING.md。
本项目采用 MIT 许可证。 详见 LICENSE。
Generated by readme-gen v0.1.0 from repository facts. Facts hash: 3e97e1ca783f.