Show HN: Treedocs: 自动检查过时文档的工具

# treedocs 来源：https://dandylyons.github.io/treedocs/ Swift CLI 通过为每个文件和文件夹提供带文档说明的 `tree`，更快地理解任何代码库。 ## treedocs 演示视频 ## 可读的树形输出 只需运行 `treedocs`，即可快速概览仓库。当前文件显示为绿色，而过时或无效的条目显示为红色，使问题一目了然。 ``` ✅ 下面的 treedocs 与文件系统保持同步。 . ├── README.md 面向用户的概述、安装及命令使用文档。 ├── Sources/ treedocs 可执行文件的 Swift 包源代码。 │ └── treedocs/ treedocs 主可执行目标。 │ ├── Commands/ treedocs 子命令的 ArgumentParser 命令实现。 │ └── Core/ 用于加载、扫描、渲染和更新 treedocs 数据的核心服务。 ├── site/ 部署到项目 GitHub Pages 站点的静态文件。 │ ├── index.html treedocs GitHub Pages 站点的登录页面。 │ └── styles.css treedocs GitHub Pages 登录页面的样式表。 └── old-file.swift 过时条目：磁盘上不存在匹配的路径。 ``` ## 更快适应 为新的队友、未来的你以及编程代理提供所需的简明上下文，帮助他们理解复杂的仓库，从而避免漫无目的地探索。 ## 保持最新 通过自动漂移检查（可发出警告或失败），让文档始终保持最新。你甚至可以安装一个 Git 预提交钩子，这样永远不会提交未记录更改的代码。 ## 带上上下文的代码审查 在 `treedocs.yaml` 中存储简单、人类可读、受版本控制的摘要，使代码审查更轻松，代理在重新发现项目结构上花费更少的 tokens。 ## 安装 `treedocs` 目前支持 macOS 13 及以上版本。0.2.0 版本仅支持源码构建，因此通过 Homebrew、Mint 或 mise 安装需要 Swift 6 兼容的构建环境，通常需要 Xcode 16+。 ### mise ``` MISE_EXPERIMENTAL=true mise use -g spm:DandyLyons/[email protected] ``` mise (https://mise.jdx.dev/) 使用其 Swift 包管理器后端。treedocs 目前不发布产物包，因此 mise 从源码构建。mise 的 `spm:` 后端目前是实验性的，安装时需要设置 `MISE_EXPERIMENTAL=true`。 ### Homebrew ``` brew install DandyLyons/tap/treedocs ``` Homebrew (https://brew.sh/) 配方通过 DandyLyons tap 从源码构建 treedocs。 ### Mint ``` mint install DandyLyons/[email protected] mint run DandyLyons/[email protected] --help ``` Mint (https://github.com/yonaskolb/Mint) 从标记的 GitHub 源代码构建 Swift 可执行包。 ## 快速开始 ``` treedocs init # 创建一个 treedocs.yaml 文件 treedocs sync # 将 treedocs.yaml 与当前文件夹结构同步并检查错误。 treedocs show . # 显示带文档的树形结构 treedocs check # 检查 treedocs.yaml 中的错误。 treedocs explore . # 渐进地探索代码库。非常适合代理探索。 ``` ## `treedocs.yaml` 模式 `treedocs.yaml` 是一个受版本控制的仓库映射。它镜像你的文件树，并为每个文件和文件夹存储一个人类可读的 YAML 描述。该描述可以由 `treedocs` 丰富的工具集解析和显示。文件格式由规范化 JSON Schema (https://dandylyons.github.io/treedocs/schemas/latest/treedocs.schema.json) 定义，这意味着编辑器、CI 工具和 AI 代理都可以解析、验证并理解相同的结构。 保持文档最新是一项持续的任务，但 `treedocs` 让它变得简单！运行 `treedocs sync` 会更新 `treedocs.yaml` 文件，添加新路径并删除已不存在的路径。剩下的只需添加简短的描述。使用 `treedocs update` 可以轻松更新描述。 或者，你可以直接让一个代理填写你的 `treedocs.yaml` 文件。代理非常擅长填写描述，并且所有内容都可以通过 `treedocs check` 进行验证。