ShowDoc-Index：AI加持的文档索引神器，让查找效率提升10倍

zhych0828

194人浏览 · 2026-06-07 21:45:39

zhych0828 · 2026-06-07 21:45:39 发布

ShowDoc-Index：AI加持的文档索引神器，让查找效率提升10倍

一、背景：传统文档查阅的痛点

背景：团队开发项目，需要统一的标准的流程，需要的一个公共的文档载体提供服务。传统的知识库都是使用RAG方式实现的，随着AI coding的兴起，我们的需求也由网页的方式转为了Markdown方式。所以信息完整性就凸显的尤为重要。整篇通读会很大减少信息遗留造成项目不稳定的风险。现有的MCP方法找文件不够高效，于是就有了添加整个项目引导文件的方式，也是受到了书籍目录的启发。
一句话：为ShowDoc项目自动生成AI索引页，让文档查找从“逐层遍历”变成“一次定位”

1.1 场景还原

开发团队日常查阅文档的典型路径：

打开 ShowDoc → 找项目 → 点目录 → 展开子目录 → 找不到 → 搜关键字
→ 搜出 30 条结果 → 逐个点开 → 不是这个 → 继续找...

1.2 数据量化

项目规模	每次查文档操作次数	平均耗时
10 个文件	6-8 次点击	1-2 分钟
50 个文件	15-20 次点击	3-5 分钟

1.3 AI 编辑器的困境

当使用 MCP（Model Context Protocol）让 AI 帮我们查文档时，问题更严重：

AI 需要逐层调用目录 API 才能找到目标
每次调用返回冗余数据（标题、时间、作者等），浪费大量 token
100 个文件的项目，AI 可能需要 15-30 次请求才能定位

二、解决方案：AI 索引文件

2.1 核心思路

为每个项目自动生成一个 _index 索引页，把所有文件信息聚合到一页中：
在这里插入图片描述

2.2 效果对比

	传统方式	使用 _index
定位文件	逐层遍历目录	一次读取索引
AI 请求次数	15-30 次	3 次
Token 消耗	高（每次返回完整元数据）	低（只返回摘要）
使用门槛	需要知道目录结构	关键词匹配即可

三、安装部署

3.1 Docker 一键部署

docker run -d --name showdoc \
  -p 4999:80 \
  -v /data/showdoc:/var/www/html \
  --restart always \
  zhych/showdoc-index:latest

3.2 Docker Compose

services:
  showdoc:
    image: zhych/showdoc-index:latest
    ports:
      - "4999:80"
    volumes:
      - ./showdocdata/html:/var/www/html
    restart: always

3.3 访问

http://<服务器IP>:port
默认账号：showdoc / 123456

四、功能详解

4.1 Header 控制栏

登录项目页面后，Header 中部有三个按钮：

[⚡更新索引] [🟢自动索引] [🟢索引记录]

按钮	功能
更新索引	手动触发 AI 生成/更新索引
自动索引	切换自动/手动模式
索引记录	查看历史生成记录、任务状态

4.2 自动索引模式（推荐）

编辑文件 → 自动记录变更 → 60s 静默窗口 → AI 增量更新 _index

核心机制：

增量更新：只处理变更文件，不改的文件不动，省 token
60s 去重：连续编辑不重复触发，60s 静默后才执行
智能识别：自动跳过 _index 自身的修改，不会无限循环

4.3 手动索引模式

适合不想频繁触发 AI 的场景：

编辑文件 → 只记录变更，不触发 → 手动点「更新索引」→ AI 增量处理

手动→自动切换时：如果有未处理的变更，立即触发一次更新。

4.4 任务中心

点击「索引记录」打开抽屉：

查看所有历史生成记录
每页 5 条，支持分页
展开「更新文件」查看具体文件名
正在执行的任务每 1 秒刷新进度
失败任务支持重试

五、AI 模型配置

5.1 后台设置

路径：管理后台 → 系统设置 → AI 标签页

配置项	说明
索引 AI 提供商	OpenAI 兼容 API / 外部 AI Service
索引 API Key	专用 Key（留空使用通用配置）
索引 API Host	专用 Host（留空使用通用配置）
索引模型名称	如 `deepseek-v4-pro`、`gpt-4o-mini`
索引 System Prompt	自定义生成风格和格式

如果文档内容过多可以使用deepseek V4 pro的1M上下文
在这里插入图片描述
这里设置的上下文大小可以分批执行生成，防止上下文溢出。

5.2 提示词自定义

可在 System Prompt 中自定义格式、字数、必含字段等。默认提示词：

你是一个技术文档整理专家。根据提供的项目目录结构，且严格根据实际目录生成简洁的中文索引 Markdown 文件，文件描述简明扼要，根据文档的内容篇幅大小增减描述字数。
{以下是文档格式}

  [文件名](url) — 描述。url 使用数据中标注的实际链接。按目录分组，保留路径层级。

举例如下：

## /
- [文案](/web/#/691604266/189452679) — 记录项目的各类文案内容，包括宣传语、广告词等文本资料。

## /二级/
- [会员](/web/#/691604266/189452681) — 会员体系相关文档，包含会员等级、权益及管理规则。

## /二级/项目说明/
- [订单中心](/web/#/691604266/189452683) — 订单中心功能说明与操作指南，展示订单处理流程。

{以上是文档格式}

六、MCP 接入

6.1 创建 API Token

登录 ShowDoc → 右上角头像 → AI Token
新建 Token，权限选「读写」
复制 Token（格式：ai_xxxx...）

6.2 Claude Code 配置

{
  "mcpServers": {
    "showdoc-index": {
      "type": "url",
      "url": "http://<服务器IP>:port/mcp.php",
      "headers": {
        "Authorization": "Bearer ai_xxxxxxxxxxxx"
      }
    }
  }
}

6.3 使用效果

用户：「帮我找一下订单中心的文档」

AI 操作流程（3 次请求）：
1. list_items              → 6 个项目，找到"订单中心"
2. get_page(_index)        → 读取全部文件索引
3. batch_get_pages(目标ID)  → 获取目标文件内容

输出：找到目标文档 + 完整内容

七、最佳实践

7.1 推荐工作流

1. 团队创建项目 → 打开「自动索引」
2. 日常编辑文档 → AI 自动维护 _index
3. 查阅文档 → 先看 _index 摘要，再定位
4. AI 集成 → 通过 MCP 3 次请求拿到内容

配合skills效果更好！资源中心

7.2 提示词优化建议

字数范围：设置最小/最大字数，保证摘要规范
关键词要求：让 AI 在摘要中体现核心关键词
格式约束：统一 Markdown 格式，便于解析

7.3 成本控制

场景	建议
文件频繁变更	开自动模式，60s 去重保障
大文件（>2000字）	摘要控制 30-50 字
超大项目（>100 文件）	用批量更新 + 分页

可以配合skills是用效果更好！

八、常见问题

Q：索引文件不更新怎么办？

手动点「更新索引」触发一次。检查后台 AI 配置是否正常。

Q：描述不够准确？

在 System Prompt 中调整格式要求和字数范围。

Q：生成失败？

检查 AI API Key 是否有效，模型是否可访问。查看任务中心错误日志。

Q：数据库怎么备份？

容器内 /var/www/html/Sqlite/showdoc.db.php，挂载到宿主机自动持久化。

九、技术架构

┌──────────────────────────────────────────────┐
│  前端 (Vue 3 + Ant Design)                    │
│  ├─ IndexHeaderActions  (更新/自动/记录)       │
│  ├─ IndexTaskCenter      (任务抽屉)           │
│  └─ SystemSettings       (AI 配置)            │
├──────────────────────────────────────────────┤
│  后端 (PHP 8 + Slim 4 + SQLite)               │
│  ├─ IndexService    (核心逻辑)                 │
│  ├─ AiHelper        (AI 调用)                 │
│  └─ IndexController (API 接口)                │
├──────────────────────────────────────────────┤
│  AI 模型                                      │
│  └─ OpenAI 兼容 API (DeepSeek/GPT/Claude...)  │
└──────────────────────────────────────────────┘