志睿源 志睿源AI + 软件技术服务
免费评估需求
项目进展2026-09-09

SHOWTEXT 使用说明

在做什么 · showtext.js产品 · showtext.js

SHOWTEXT 是一款专为开发者、技术团队及 AI 辅助编程场景设计的命令行工具。它能够将分散在复杂目录结构中的源代码文件，智能聚合、解析依赖关系，并最终生成一份结构清晰、内容完整的 Markdown 报告。

无论是代码审查、项目交接、知识库沉淀，还是为 AI 模型提供精准的上下文，SHOWTEXT 都能帮你将庞杂的代码库瞬间转化为易于阅读和分享的静态文档。

✨ 核心特性

1. 灵活的源码收集策略

  • 多源输入：支持同时指定多个文件或目录作为扫描起点。
  • 全文本模式（默认） ：自动识别并跳过二进制文件（如图片、压缩包、可执行文件），安全高效。
  • 白名单模式：你可自定义允许的扩展名（如仅收集 .js 和 .ts），实现精准过滤。

2. 强大的依赖解析（智能关联）

  • 内置支持 JavaScript/TypeScript（require / import）、Python、PHP、C/C++（#include）以及 HTML（src / href）的导入语句解析。
  • 自动追踪并引入被依赖的文件，确保文档的完整性与关联性。
  • 支持设置解析深度（默认无限制），避免因依赖链过长导致文档膨胀。

3. 颗粒化的忽略控制

  • 内置默认忽略库：预置了 node_modules、.git、dist、package-lock.json 等常见非必要内容。
  • 自定义忽略：支持忽略特定名称（如 temp）或精确路径（如 C:/project/legacy），灵活适配各种项目结构。

4. 结构化输出与视觉优化

  • 文件结构一览：生成文件树状列表，并可选择展示每个文件的体积大小（KB）。
  • 双重组网模式：内容区域支持按 目录结构 或 文件扩展名 进行分组，方便按功能模块或技术栈阅读。
  • 语法高亮：根据文件扩展名自动匹配代码块语言标识（如 javascript、python、cpp），在 Markdown 渲染器中呈现赏心悦目的代码风格。

5. 高度可配置

  • 通过简单的 JSON 配置文件 定义所有参数（showtext.json），无需记忆复杂的命令行参数。
  • 可作为 Node.js 模块 嵌入到你的自动化构建脚本中。

📦 安装与运行

环境要求

  • Node.js (建议 v14 及以上版本)

获取工具

将代码库克隆或下载到本地目录（例如 C:/tools/showtext）。

基础用法（命令行）

# 使用默认配置（自动寻找当前目录下的 showtext.json）
node index.js

# 指定自定义配置文件路径
node index.js /path/to/your-config.json

⚙️ 配置详解（showtext.json）

在项目根目录（或任意位置）创建 showtext.json，以下为完整的配置项说明：

{
  // [必填] 源码路径数组（支持文件或目录，相对于 root_path）
  "sources": [
    "./src",
    "./index.js"
  ],

  // [必填] 输出 Markdown 文件的路径（支持相对或绝对路径）
  "output": "./docs/codebase.md",

  // [可选] 基准目录（默认为 process.cwd()）。所有 sources 和相对路径都将基于此解析
  "root_path": "C:/my-project",

  // [可选] 忽略规则数组（支持名称或路径）
  "ignore": [
    "test-data",   // 忽略名为 test-data 的目录或文件
    "./deprecated" // 忽略当前基准目录下的 deprecated 文件夹（精确路径）
  ],

  // [可选] 白名单扩展名（注释掉或留空则启用“全文本模式”）
  "allowedExts": [".js", ".ts", ".json"],

  // [可选] 特殊文件名（即使不在白名单或被认为是二进制，也强制包含）
  "specialFilenames": ["Dockerfile", ".env.example"],

  // [可选] 是否启用依赖解析，默认 false
  "resolveDependencies": true,

  // [可选] 依赖解析深度（-1 表示无限制），默认 -1
  "resolveDepth": 3,

  // [可选] 是否跟随符号链接，默认 false
  "followSymlinks": false,

  // [可选] 最大文件大小（字节），超过则跳过，默认 0（无限制）
  "maxFileSize": 1048576,

  // [可选] 是否按扩展名分组显示内容，默认 false（按目录结构分组）
  "groupByExtension": true,

  // [可选] 是否在“文件结构”列表中显示文件大小，默认 true
  "showFileSize": true,

  // [可选] 开启调试日志，默认 false
  "debug": false
}

🚀 典型使用场景

场景一：为 AI 编码助手准备上下文

当你需要将整个项目代码提交给 ChatGPT、Copilot 或本地大模型分析时，直接粘贴大量零散文件非常不便。使用 SHOWTEXT 生成一份整合的 Markdown 文件，一次性提供给 AI，模型能更完整地理解你的架构。

场景二：遗留系统交接与文档生成

面对一个没有文档、结构混乱的老项目，运行 SHOWTEXT 并开启 resolveDependencies，你不仅能快速浏览所有文件，还能清晰地看到模块之间的引用关系。

场景三：代码审查前的准备工作

在团队 Code Review 前，将变更涉及的核心目录生成文档，审查者无需在 IDE 和浏览器之间反复切换，通过一份渲染后的 Markdown 即可通览全局。

📋 输出报告样例

生成的 Markdown 文件包含三个核心部分：

  1. 配置信息表格

记录本次收集的基准目录、源路径、忽略规则及时间戳，确保文档可复现。

  1. 文件结构列表 
   | 文件路径 | 大小 (KB) |
   |----------|-----------|
   | src/utils/logger.js | 2.3 KB |
   | src/index.js | 1.1 KB |
  1. 文件内容（代码块） 
   #### src/index.js

const logger = require('./utils/logger'); console.log('Hello World');

🛠 高级技巧

  • 组合白名单与依赖解析：当你只关心核心逻辑文件（如仅 .ts 文件）时，设置 allowedExts 并开启依赖解析，工具会将 .ts 文件引用的 .d.ts 或 .json 文件（即使不在白名单）也一同纳入，确保类型定义不丢失。
  • 调试模式：遇到文件被意外跳过时，开启 "debug": true，控制台会输出详细的决策日志，方便排查忽略规则是否生效。

💡 结语

SHOWTEXT 解决了代码文档化过程中“收集难、整理烦、关联乱”的痛点。它不只是一个文件抓取器，更是一个智能的代码结构分析器。即刻配置，一键生成，让你的代码库从此清晰可见！

← 返回文章列表