在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

tldr-pages/tldr

菜单

客户端规范和集成

相关源文件

本文档详细介绍了 tldr-pages 的标准化客户端规范，并为客户端应用程序如何与 tldr 内容交互提供了指导。它为希望根据项目标准创建访问和显示 tldr 页面的应用程序的客户端开发人员提供了技术参考。

有关构建和部署系统的信息，请参阅构建和部署系统。

客户端规范概述

tldr-pages 客户端规范定义了访问 tldr 内容的应用程序的一致界面和行为。该规范可确保用户在不同的客户端实现中获得熟悉的体验。当前版本为 2.3，其中包含处理短格式/长格式选项和特定于平台的行为的规范。

来源：CLIENT-SPECIFICATION.md1-10 README.md60-96

规范的关键组成部分

术语

该规范定义了两个关键术语

  • 页面：描述特定命令的单个文档
  • 平台：命令分类所依据的操作系统（例如，common、linux、osx）

来源：CLIENT-SPECIFICATION.md10-27

命令行界面

具有 CLI 的客户端必须支持这些参数

选项必需？含义
-v, --version是显示客户端版本和规范版本
-p, --platform是指定平台（包括common）
-u, --update有条件更新离线缓存
-l, --list否列出当前平台上的所有页面
-L, --language否指定首选语言
--short-options否显示短格式选项
--long-options否显示长格式选项

默认情况下，如果没有指定--short-options或--long-options，客户端应仅显示长格式选项。

来源：CLIENT-SPECIFICATION.md29-54 pages/common/tldr.md3-37

目录结构

tldr 内容遵循特定的目录结构

  • pages/：英文页面的主目录
    • common/：平台无关的命令
    • linux/、windows/、osx/ 等：特定于平台的命令
  • pages.<locale>/：遵循相同结构的翻译

建议客户端将macos作为osx的别名。

来源：CLIENT-SPECIFICATION.md80-104 CONTRIBUTING.md55-81

页面结构和渲染

页面使用 CommonMark，带有特殊的占位符

  • {{...}}：用户可替换的值
  • {{[...]}}：短格式和长格式选项变体（以|分隔）

客户端必须

  • 高亮显示占位符并移除大括号
  • 仅显示短/长格式选项时，移除方括号
  • 正确处理转义的占位符（\{\{ 和 \}\}）

示例

  • ping {{example.com}} → "ping example.com"
  • git add {{[-A|--all]}} → "git add -A"（短格式）或 "git add --all"（长格式）

来源：CLIENT-SPECIFICATION.md120-140 contributing-guides/style-guide.md16-65

页面解析算法

  1. 格式化命令名称：将空格替换为连字符，小写
  2. 检查主机平台是否存在页面
  3. 如果不存在，则检查通用平台
  4. 如果不存在，则搜索其他平台（并发出警告）
  5. 如果到处都找不到，则显示错误并附带创建问题的链接

当找不到页面时，客户端应以非零代码退出。

来源：CLIENT-SPECIFICATION.md143-188

语言解析

算法

  1. 检查 LANG 环境变量
  2. 从 LANGUAGE 中提取优先级列表
  3. 将 LANG 追加到优先级列表
  4. 使用第一个可用的语言
  5. 如果没有可用的语言，则回退到英语

强烈建议在查找时优先考虑平台而非语言。

对于linux平台，当LANG=it且LANGUAGE="it:fr:en"时的示例查找

  1. 检查 pages.it/linux/command.md
  2. 检查 pages.fr/linux/command.md
  3. 检查 pages/linux/command.md（英语）
  4. 检查 pages.it/common/command.md
  5. 检查 pages.fr/common/command.md
  6. 检查 pages/common/command.md（英语）

来源：CLIENT-SPECIFICATION.md189-232

缓存机制

客户端应通过下载实现缓存

  • 完整存档：https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip
  • 特定语言存档：https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.{{language-code}}.zip
  • 英语存档：https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.zip

注意：旧的资产 URL（https://tldr.sh/assets）已弃用，将于 2025 年 12 月移除。

来源：CLIENT-SPECIFICATION.md234-240

集成客户端

集成 tldr-pages 到客户端的开发者应

  1. 实现必需的命令行界面
  2. 遵循页面解析算法
  3. 按照规范处理语言
  4. 按建议实现缓存
  5. 渲染带有正确占位符处理的页面

来源：CLIENT-SPECIFICATION.md README.md60-96

官方和社区客户端

tldr-pages 项目有几个官方客户端

  • Node.js 客户端：npm install -g tldr
  • Python 客户端：pip3 install tldr
  • Rust 客户端：brew install tlrc

有关所有客户端的完整列表，包括社区开发的客户端，请参阅项目的 Wiki。

来源：README.md60-96

版本历史

客户端规范已历经多个版本演进

版本日期关键变更
2.32025年3月7日添加了长格式/短格式规范，common作为平台选项
2.22024年3月20日将资产 URL 更新为使用 GitHub releases
2.12023年11月30日增加了对占位符语法转义的支持
2.02023年9月10日为osx添加了macos别名，删除了“all”平台，强制要求长选项
1.52021年3月17日增加了命令名称小写的要求
1.42020年8月13日增加了非零退出码的要求
1.32020年6月11日澄清了英语回退机制，更新了环境变量
1.22019年7月3日添加了语言选项，迁移到 POSIX 区域设置标签

请注意，旧版本（2.0 之前）已弃用。

来源：CLIENT-SPECIFICATION.md243-302