我做了一个自动生成项目入门文档的 CLI 工具

最近做了一个小工具:repo-onboard。

它的目标很简单:进入一个陌生仓库后,自动生成一份实用的 ONBOARDING.md,帮助新人快速知道项目怎么启动、有哪些常用命令、需要哪些环境变量、应该先看哪些文件。

GitHub:github.com/hyjcxy/repo...

为什么做这个

很多项目其实已经包含了新人需要的信息,但这些信息通常散落在不同地方:

  • README.md 里有一部分说明
  • package.json 里有启动和测试脚本
  • .env.example 里有环境变量
  • docker-compose.yml 里有本地依赖服务
  • Java 项目里可能还要看 pom.xml

新人接手项目时,经常要自己把这些线索串起来。这个过程不难,但很浪费时间。

所以我想做一个很小的 CLI,把这些仓库里的"入门线索"收集起来,生成一份可以直接提交到仓库里的入门文档。

它现在能做什么

目前的 MVP 支持:

  • 识别 Node.js、Java Maven、Docker 项目
  • 读取 package.json scripts
  • 从 .env.example 提取环境变量名称
  • 生成顶层目录结构概览
  • 输出 ONBOARDING.md
  • 支持 --dry-run 预览
  • 支持 --output docs/ONBOARDING.md 自定义输出路径

示例命令:

bash 复制代码
node src/cli.js /path/to/repo
node src/cli.js /path/to/repo --dry-run
node src/cli.js /path/to/repo --output docs/ONBOARDING.md

生成内容大概是这样:

md 复制代码
# sample-app Onboarding

## Project Snapshot

- Detected type: Node.js, Docker

## Quick Start

1. Install dependencies with npm install.
2. Copy .env.example to .env if the file exists.
3. Run the development or test command listed below.

## Common Commands

- dev: vite
- test: node --test

## Environment Variables

- PORT
- API_KEY

技术实现

为了让工具足够轻,第一版没有接 AI,也没有引入第三方依赖。

核心逻辑就是三块:

  • scanner:扫描仓库里的关键文件
  • markdown:把扫描结果渲染成入门文档
  • cli:处理参数、写文件或 dry-run 输出

测试用的是 Node.js 内置的 node:test,目前覆盖了 CLI、扫描器和 Markdown 生成。

后续计划

接下来可能会加:

  • Python / Go / Rust / Gradle 项目识别
  • --check 模式,用在 CI 里检查入门文档是否过期
  • 发布到 npm,支持 npx repo-onboard
  • 可选的 --ai,自动总结模块职责

如果你也经常接手陌生仓库,或者需要给项目补新人入门文档,可以试试看。

GitHub:github.com/hyjcxy/repo...

相关推荐
SEO_juper18 分钟前
Node.js 全站 SEO 体检报告生成器:一次查完标题、描述、canonical、H1、图片
开发语言·前端·node.js·html·bash
木头左1 天前
【Node.js】Markdown 转带图片 Word 文档实战:docx 库转换器设计与 5 个踩坑
node.js·word·markdown·文档自动化
思特奇时空智能1 天前
大规模点要素地图渲染性能优化实践
vue.js·arcgis·性能优化·node.js·html·gis·webgl
w3296362713 天前
飞书接单到月度结算:我用一个 DSH 插件跑通鞋类采购 WMS,附 22 项验收
pdf·node.js·飞书·后端开发·ai agent
濮水大叔4 天前
Cabloy/Vona 为什么不需要 NestJS 的 Dynamic Module
typescript·node.js·nestjs
匠云创新4 天前
读完一万段要两分钟:我们把标书读取从 WPS 对象模型搬到了 docx 解析
性能优化·node.js
某哈压力大4 天前
SSH 突然 Connection reset?不是密钥坏了,是 OpenSSL 把 sshd 干趴了
前端·node.js·命令行
回眸&啤酒鸭4 天前
【回眸】Node.js 新手从零到一实战指南
node.js
浪遏4 天前
recruitment-cli:让 AI 接手求职招聘,从架构到一次发送超时
架构·typescript·node.js
沉默小管6 天前
我用 NestJS + Nuxt 3 做了个导航站,聊几个踩过的坑
node.js·seo