Repo-Viewer-Search

Repo-Viewer-Search 是 Repo-Viewer 的离线索引生成器与校验工具，提供：

• 索引生成：输出分片索引文件与 manifest.json，支持 gzip 压缩。
• GitHub Actions 复合 Action：一键生成并维护 RV-Index 分支。
• 质量保障：索引校验与过期索引清理工具。
• 历史保留：每个分支默认最多保留 10 个索引文件。
• 增量复用：当索引参数一致时复用历史条目并跳过无变化分支。

当前索引协议为 schemaVersion: 2.0（manifest 为 2.0），索引仅包含文件路径与倒排索引（详见 docs/search-index-spec.md）。

环境要求

• Node.js 24.12.0
• Git >= 2.40（索引分支仍使用 worktree）

安装与构建

npm install
npm run build

常用脚本：

• npm run lint：ESLint 检查。
• npm run typecheck：TypeScript 严格检查。
• npm run test / npm run test:coverage：Vitest 单测与覆盖率。
• npm run ci：CI 串行执行 lint + test。
• npm run dev：用 tsx 运行 CLI，便于调试。

Node.js API

• generateSearchIndex(options)：生成索引文档数组（可分片）。
• buildManifest(options, branchInputs)：构建或合并 manifest。
• validateIndex(options)：校验 manifest 与索引文件一致性。
• pruneOldIndex(options)：清理历史索引文件。

CLI 命令

npx repo-viewer-search validate-index --manifest ../RV-Index/manifest.json --branch main,develop
npx repo-viewer-search prune-old-index --manifest ../RV-Index/manifest.json --keep-latest 2 --dry-run

GitHub Actions 集成

name: Repo Viewer Search Index

on:
  push:
    branches:
      - main
      - develop
  workflow_dispatch: {}

jobs:
  generate-index:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Generate Repo Viewer search index
        uses: H-Sofie/Repo-Viewer-Search@main
        with:
          token: ${{ secrets.RV_SEARCH_TOKEN }}
          branches: main, develop
          max-files-per-index: 4000
          index-compression: gzip

Action 输入

输入	说明	默认值
token	PAT 或 GITHUB_TOKEN，用于推送 index-branch	workflow GITHUB_TOKEN
branches / branch	需要生成索引的分支列表	默认分支或当前触发分支
index-branch	存放索引的目标分支	RV-Index
short-sha-length	文件命名使用的短提交哈希长度（>=7）	7
include-globs / exclude-globs	额外包含/排除规则（picomatch）	** / .git/**
max-files-per-index	单个索引文件最多条目数，0 表示不分片	4000
index-compression	索引压缩方式（none / gzip）	gzip
commit-message	提交信息模板（支持 {updates}）	chore(search-index): update {updates}
git-user-name / git-user-email	提交用户信息	Repo Viewer Bot / repo-viewer-bot@users.noreply.github.com
skip-empty-commit	无变更时是否跳过提交	true
push	是否推送到远程	true

参考文档

• docs/search-index-spec.md：索引协议与字段说明。
• docs/search-index-workflow.md：Action 运行流程与参数建议。
• docs/faq.md：常见问题与排查。