TagSpaces 6.13.9 常用 CLI 命令与工具详解

TagSpaces 官方 CLI @tagspaces/shell（tscmd）4.8.10 六命令（indexer/thumbgen/metacleaner/tag/describe/search）全参数实测详解：tsi/tsft 索引结构、CJK 切词、增量索引陷阱、rename/sidecar 双打标法与排障实录，回显逐行照抄。

TagSpacesTagSpaces自托管Linux2026/11/01

TagSpaces 6.13.9 常用 CLI 命令与工具详解

目标：讲清 TagSpaces 官方命令行工具 @tagspaces/shell（可执行命令 tscmd，版本 4.8.10）的六个子命令——indexer（索引）、thumbgen（缩略图）、metacleaner（旁车清理）、tag（打标）、describe（描述）、search（检索）——的参数与真实行为，包括索引文件结构、中日韩（CJK）切词、增量索引陷阱与排障实录。全部命令与回显均在本地容器实测照抄。

一、环境信息

  • 操作系统：Linux x86_64；工具运行容器：node:22-slim（Node.js 22）
  • 工具与版本：@tagspaces/shell@4.8.10（npm 全局安装，实测 npm ls -g 回显 +-- @tagspaces/shell@4.8.10；tscmd --version 回显 4.8.10）
  • 安装方式：npm install -g @tagspaces/shell（npm 包名），安装后提供可执行命令 tscmd
  • 工作目录：宿主 /opt/data/quzuo/tmp/tagspaces/cliwork（挂载进容器 /work，下文命令均以 docker exec -w /work tagspaces-6.13.9-tscmd tscmd ... 形式执行，等价于在容器内 /work 下直接敲 tscmd ...）
  • 实验语料（/work/docs/ 初始状态）：
    • memo.txt（内容 plain memo text）
    • note.md（内容：# 项目笔记 / Q1 收入增长 20%。）
    • photo.jpg（188 字节的 1×1 JPEG）
    • report[finance 2026 invoice].pdf（内容为文本 fake-pdf-content，非真实 PDF——用于演示非法 PDF 的处理）
  • 语料说明：.pdf/.jpg 为实验最小样张；后文按实验顺序推进，tag 改名、新增 todo.md/logo.png、删除 report 等变更均会在对应小节注明

二、工具概览

tscmd --help 实测回显（全文照抄）：


████████╗ █████╗  ██████╗ ███████╗██████╗  █████╗  ██████╗███████╗███████╗
   ██╔══╝██╔══██╗██╔════╝ ██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██╔════╝
   ██║   ███████║██║  ███╗███████╗██████╔╝███████║██║     █████╗  ███████╗
   ██║   ██║  ██║╚════██║██╔═══╝ ██╔══██║██║     ██╔══╝  ╚════██║
   ██║   ██║╚██████╔╝███████║██║     ██║  ██║╚██████╗███████╗███████║
   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═════╝╚═╝     ╚═╝  ╚═╝ ╚═════╝╚══════╝╚══════╝

  tscmd v4.8.10  —  TagSpaces CLI for indexing, thumbnails, tagging & more

Usage: tscmd <command> [options] <dir...>

Commands:
  tscmd thumbgen <dirs...>     Generate thumbnails for files in one or more
                               directories
  tscmd indexer <dirs...>      Create a search index for one or more directories
  tscmd metacleaner <dirs...>  Remove obsolete sidecar files and thumbnails
  tscmd tag <paths...>         Add tags to files or folders
  tscmd describe <paths...>    Set description on files or folders
  tscmd search <dir>           Search a directory's index for matching files

Options:
  -h, --help     Show help                                             [boolean]
  -v, --version  Show version number                                   [boolean]

Quick reference:
  thumbgen   -p, --pdf          Include PDF thumbnails
  indexer    -f, --fulltext     Extract full-text content (MD, HTML, TXT, PDF)
             -l, --links        Extract links from content (requires --fulltext)
             --force            Force full re-index (skip incremental)
  metacleaner -a, --analyze     Dry-run mode (default: true)
  tag        -t, --tags         Tags to add (space-separated)
             -m, --method       "rename" (default) or "sidecar"
  describe   -d, --description  Description text to set
             -f, --file         Read description from a file
  search     -q, --query        Query; +tag=AND, -tag=NOT, |tag=OR
             -t, --tags         Extra AND tags (merged with +tag in -q)
             --type             File type group (e.g. images, documents)
             -s, --search-type  fuzzy (default), semistrict, or strict
             -n, --max-results  Maximum number of results (default: 100)

Run tscmd <command> --help for full details on a specific command.

六个子命令与 TagSpaces 元数据体系的对应关系：

命令产物/作用落盘位置
indexer生成目录索引：条目+标签索引、全文分词索引.ts/tsi.json、.ts/tsft.jsonl
thumbgen为图片（可用 -p 扩展到 PDF）生成缩略图.ts/<文件名>.jpg
metacleaner清理「过时」的旁车/缩略图（默认干跑）删除 .ts/ 下被判定过时的文件
tag打标签：改名法（默认）或旁车法文件名 / .ts/<文件名>.json（文件夹为 .ts/tsm.json）
describe写描述（旁车法）.ts/<文件名>.json 的 description 字段
search查询目录索引（全文 + 标签过滤），只读不落盘

💡 技术拓展：tsi.json 是「目录里有哪些文件、各自有什么标签/描述」的条目索引；tsft.jsonl 是逐行 JSON 的全文分词索引（每行 {"p":"文件名","t":"分词结果"}）。Web 版浏览器搜索消费的正是这两个文件（索引有效期由位置参数 maxIndexAge 控制，见本专栏《TagSpaces 6.13.9 配置参数详解》）。

三、前置条件

  1. Node.js 环境（实测 22）与全局安装：npm install -g @tagspaces/shell；
  2. 一个待管理的文件目录（本文 /work/docs）；目录权限需允许改名（tag 改名法会重命名文件）与创建 .ts/ 子目录；
  3. 理解两种打标落盘机制（改名 vs 旁车）——见本专栏《TagSpaces 介绍与选型指南》第二章；
  4. 无需任何账号/密钥：tscmd 全部命令面向本地文件系统目录，不直接操作 S3（S3 桶里的索引由 Web 版浏览器生成，或把桶同步到本地处理后回传）。

四、各工具详解

4.1 indexer：索引生成

indexer --help 实测回显（横幅与总帮助一致，此处略）：

tscmd indexer <dirs...>

Create a search index for one or more directories

Options:
  -h, --help      Show help                                            [boolean]
  -f, --fulltext  Extract full-text content from files (MD, HTML, TXT, PDF)
                                                      [boolean] [default: false]
  -l, --links     Extract links from file content (requires --fulltext)
                                                      [boolean] [default: false]
      --force     Force full re-index (skip incremental)
                                                      [boolean] [default: false]
  -v, --version   Show version number                                  [boolean]

实验 1：全量索引（含全文）。 语料为初始 4 个文件：

tscmd indexer docs --fulltext --force

实测回显：

Skipping PDF extraction: report[finance 2026 invoice].pdf (Not a valid PDF file)
✔ Index generated: docs
  4 files, 0 folders
  259 B total size
  2 files with fulltext, 19 tokens
  0.0s elapsed

行为解读：非法 PDF 被跳过并给出原因（跳过不报错、不中断）；4 个文件全部进 tsi.json，其中 memo.txt 与 note.md 的文本可提取（report.pdf 是假 PDF 无文本、photo.jpg 是图片），故 2 files with fulltext。

产物结构实测——tsi.json（单条条目示例，note.md 携带 description 元数据）：

{"name":"note.md","path":"note.md","meta":{"description":"Q1 项目笔记，含收入数据"},"isFile":true,"size":38,"lmdt":1793507733960.9722,"cdt":1793507733960.9722,"uuid":"e23ff212669d46389819d0b6eadebe95","extension":"md"}

tsft.jsonl 全文索引（逐行照抄，可观察 CJK 切词）：

{"p":"memo.txt","t":"plain memo text"}
{"p":"note.md","t":"项目 目笔 笔记 项 目 笔 记 q1 收入 入增 增长 收 入 增 长 20。"}

💡 说明：对中文内容 # 项目笔记 Q1 收入增长 20%。，切词输出为二元组（项目/目笔/笔记、收入/入增/增长）与一元单字（项/目/笔/记…）的混合——这是 CJK 文本无需分词器也能命中多字词的实现方式；英文按整词（plain memo text）。

实验 2：增量索引陷阱（重点）。 新增一个文件后不带 --force 再跑：

printf '# 待办
明天验证 TagSpaces 索引增量行为。
' > docs/todo.md
tscmd indexer docs --fulltext

实测回显：

Incremental index: 1 added, 0 modified, 0 deleted, 4 unchanged
Skipping PDF extraction: report[finance 2026 invoice].pdf (Not a valid PDF file)
✔ Index updated: docs
  incremental: +1 ~0 -0 =4
  5 files, 0 folders
  313 B total size
  1 files with fulltext, 23 tokens
  0.0s elapsed

增量后 tsft.jsonl 实际内容：

{"p":"todo.md","t":"待办 办明 明天 天验 验证 待 办 明 天 验 证 tagspaces 索引 引增 增量 量行 行为 索 引 增 量 行 为"}

⚠️ 陷阱确认：tsi.json 正确更新为 5 个文件（+1 ~0 -0 =4），但 tsft.jsonl 被整体重写为只含本次变更文件（1 files with fulltext）——未变更文件的全文索引全部丢失。此目录内用 search 搜旧文件全文将查不到。

实验 3：--force 修复。

tscmd indexer docs --fulltext --force

实测回显：

Skipping PDF extraction: report[finance 2026 invoice].pdf (Not a valid PDF file)
✔ Index generated: docs
  5 files, 0 folders
  313 B total size
  3 files with fulltext, 42 tokens
  0.0s elapsed

tsft.jsonl 恢复为 3 行（memo.txt、note.md、todo.md）。结论：改动目录内容后，凡用到 --fulltext，一律加 --force 全量重建（本例语料毫秒级完成，代价可忽略）。

4.2 thumbgen：缩略图生成

thumbgen --help 实测回显（横幅略）：

tscmd thumbgen <dirs...>

Generate thumbnails for files in one or more directories

Options:
  -h, --help     Show help                                             [boolean]
  -p, --pdf      Include PDF thumbnails               [boolean] [default: false]
  -v, --version  Show version number                                   [boolean]

实验 4：错误路径（对初始语料直接跑）。

tscmd thumbgen docs

实测回显：

unsupported thumb format:txt
unsupported thumb format:md
unsupported thumb format:pdf
unsupported thumb format:md
Unable to resize docs/photo.jpg due to an error:  ya [vips::Error]: unable to call thumbnail_buffer
VipsJpeg: Bogus Huffman table definition
VipsJpeg: Bogus Huffman table definition
VipsJpeg: Bogus Huffman table definition

    at rb (/usr/local/lib/node_modules/@tagspaces/shell/node_modules/wasm-vips/lib/vips-node.js:106:466)
    ...(wasm 调用栈数行，略)
  ga: 4463448
}
✔ Thumbnails generated: docs

行为解读：① 不支持缩略图的扩展名逐个打印 unsupported thumb format:<ext> 后跳过；② 4.8.10 内置 wasm-vips 解码图片（栈中可见 wasm-vips 路径），本实验的 1×1 JPEG 样张虽被 file 识别为 JFIF，但编码不合法，vips 抛 VipsJpeg: Bogus Huffman table definition；③ 单个文件失败不影响整体任务，结尾仍打印汇总行。

实验 9：成功路径。 用合法 PNG（base64 解码出的 1×1 PNG）重跑：

echo 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==' | base64 -d > docs/logo.png
tscmd thumbgen docs
ls docs/.ts/ | grep logo

实测回显：

✔ Thumbnails generated: docs
logo.png.jpg

产物命名规则：.ts/<完整文件名>.jpg（logo.png → .ts/logo.png.jpg）。缩略图生成本地完成、无需 sharp 等外部原生依赖（npm ls -g 确认全局仅 @tagspaces/shell 一个包，见 FAQ Q4）。

4.3 tag：打标签（改名法 / 旁车法 / 文件夹）

tag --help 实测回显（横幅略）：

tscmd tag <paths...>

Add tags to files or folders

Options:
  -h, --help     Show help                                             [boolean]
  -t, --tags     Tags to add                                  [array] [required]
  -m, --method   Tagging method: "rename" embeds tags in filename, "sidecar"
                 writes to .ts/*.json
                     [string] [choices: "rename", "sidecar"] [default: "rename"]
  -v, --version  Show version number                                   [boolean]

实验 5：改名法（默认）。

tscmd tag docs/memo.txt -t work demo
ls docs/

实测回显：

Renaming file: /work/docs/memo.txt to /work/docs/memo[work demo].txt
✔ Tagged (rename): memo.txt → memo[work demo].txt
memo[work demo].txt
note.md
photo.jpg
report[finance 2026 invoice].pdf
todo.md

标签以空格分隔的多值写进文件名方括号段：memo.txt → memo[work demo].txt（标签段位置由 ExtFilenameTagPlacedAtEnd 约定，默认尾部）。

实验 6：旁车法。

tscmd tag docs/note.md -t project -m sidecar
cat docs/.ts/note.md.json

实测回显：

Creating directory: /work/docs/.ts
✔ Tagged (sidecar): /work/docs/note.md +project
{
  "description": "Q1 项目笔记，含收入数据",
  "tags": [
    {
      "title": "project",
      "type": "sidecar"
    }
  ]
}

旁车 JSON 的 tags 数组逐个追加 {"title":..., "type":"sidecar"} 条目；description 字段保持不动（Creating directory: 提示在 .ts 已存在时也会打印，无害）。

实验 7：给文件夹打标。

tscmd tag docs -t docs -m sidecar
ls docs/.ts/

实测回显（节选）：

✔ Tagged (sidecar): /work/docs +docs
note.md.json
photo.jpg.json
report[finance 2026 invoice].pdf.json
tsft.jsonl
tsi.json
tsm.json            ← 新增

文件夹的元数据落在目录自身 .ts/tsm.json（区别于文件的 .ts/<文件名>.json）。

两种打标法对比：

维度rename（默认）sidecar
落盘位置文件名方括号段.ts/<文件名>.json
文件名被修改（变长）不变
适用面本地文件系统本地 + 对象存储（S3 对象无法改名，Web 版配 persistTagsInSidecarFile: true）
肉眼可见性任何文件管理器直接可见需应用或读 JSON

4.4 describe：写描述

describe --help 实测回显（横幅略）：

tscmd describe <paths...>

Set description on files or folders

Options:
  -h, --help         Show help                                         [boolean]
  -d, --description  Description text (supports \n for newlines, use "-" to read
                     from stdin)                                        [string]
  -f, --file         Read description from a file (e.g., description.md)[string]
  -v, --version      Show version number                               [boolean]

实验 8： 对改名后的文件写描述：

tscmd describe 'docs/memo[work demo].txt' -d '工作备忘：验证 describe'
cat 'docs/.ts/memo[work demo].txt.json'

实测回显：

Creating directory: /work/docs/.ts
✔ Description set: /work/docs/memo[work demo].txt
  "工作备忘：验证 describe"
{
  "description": "工作备忘：验证 describe"
}

描述只走旁车机制（不碰文件名），产物 JSON 仅含 description 键；-f 可从文件读长描述，-d 支持 \n 换行。

4.5 search：索引检索

search --help 实测回显（横幅略）：

tscmd search <dir>

Search a directory's index for matching files

Options:
  -h, --help         Show help                                         [boolean]
  -q, --query        Query string. Bare words = fulltext. Prefixes: +tag (AND),
                     -tag (NOT), |tag (OR). e.g. "notes +work -draft |urgent"
                                                          [string] [default: ""]
  -t, --tags         Tags to match (AND logic, merged with +tag from -q)
                                                           [array] [default: []]
      --type         File type group: any, images, documents, notes, audio,
                     video, archives, bookmarks, ebooks, emails, folders, files,
                     untagged                          [string] [default: "any"]
  -s, --search-type  Search accuracy: fuzzy, semistrict, or strict
          [string] [choices: "fuzzy", "semistrict", "strict"] [default: "fuzzy"]
  -n, --max-results  Maximum number of results           [number] [default: 100]
  -v, --version      Show version number                               [boolean]

查询语法：裸词=全文检索；+tag=必须含该标签、-tag=排除、|tag=或（多标签时空格分隔）。先重索引让 tsi.json 反映 4.3/4.4 的改名与新文件（tscmd indexer docs --fulltext --force，回显 6 files, 0 folders / 3 files with fulltext, 42 tokens），再逐项实测：

实验 11：全文检索。

tscmd search docs -q memo

实测回显（全文照抄，含内部调试输出）：

  Searching 6 entries in: /work/docs
PreparingIndex: 0.527ms
fuse query: memo
fuse: 1.584ms
Results found: 1
Results sent: 1
searchtime: 2.464ms
  Found 1 result(s):
  memo[work demo].txt [work demo] (16 B)

结果行的 [work demo] 即文件名解析出的标签。大小写不敏感——-q MEMO 回显 fuse query: MEMO，结果相同（Found 1 result(s)）。CJK 全文：-q 收入 命中 note.md [project] (38 B)（依赖 4.1 的二元切词，搜「收入」可命中「收入增长」）。

实验 12：标签过滤（AND）。 tscmd search docs -q +vacation（photo.jpg 此前已带旁车标签 vacation/berlin）实测回显（节选）：

filterByTags results: 1
Results found: 1
  Found 1 result(s):
  photo.jpg [vacation berlin] (188 B)

-t 参数等价：tscmd search docs -t vacation 回显与上面相同。

实验 13：排除（NOT）。 ⚠️ 直接写 -q -vacation 会踩坑（见下），正确姿势用等号传值：

tscmd search docs --query=-vacation

实测回显（节选）：

filterByTags results: 5
Results found: 5
  Found 5 result(s):
  logo.png (70 B)
  memo[work demo].txt [work demo] (16 B)
  note.md [project] (38 B)
  report[finance 2026 invoice].pdf [finance 2026 invoice] (17 B)
  todo.md (54 B)

实验 14：或（OR）。 多个 |tag 用空格分隔：

tscmd search docs -q '|vacation |finance'

实测回显（节选）：

filterByTags results: 2
  Found 2 result(s):
  photo.jpg [vacation berlin] (188 B)
  report[finance 2026 invoice].pdf [finance 2026 invoice] (17 B)

实验 15：类型分组。 tscmd search docs --type notes（notes=md/mdown/txt/html，见配置篇 5.7）回显（节选）：

  Found 3 result(s):
  memo[work demo].txt [work demo] (16 B)
  note.md [project] (38 B)
  todo.md (54 B)

实验 16：模糊 vs 严格。 -q memoo（fuzzy 默认）实测回显（节选）：

fuse query: memoo
  Found 1 result(s):
  memo[work demo].txt [work demo] (16 B)

加 -s strict 后 Found 变为 No results found.——fuzzy 允许近似词，strict 要求精确。

实验 17：结果数上限。 tscmd search docs -q 'e' -n 1 实测回显（节选）：

Results found: 6
Results sent: 1
  Found 1 result(s):
  logo.png (70 B)

（Results found 是命中总数，Results sent/展示数受 -n 截断。）

4.6 metacleaner：旁车与缩略图清理

metacleaner --help 实测回显（横幅略）：

tscmd metacleaner <dirs...>

Remove obsolete sidecar files and thumbnails

Options:
  -h, --help     Show help                                             [boolean]
  -a, --analyze  Dry-run: list files to remove without deleting them (set to
                 false to delete)                      [boolean] [default: true]
  -v, --version  Show version number                                   [boolean]

实验 18-19：制造孤儿 sidecar 后干跑。 删除 report[finance 2026 invoice].pdf 本体（其旁车 .ts/report[finance 2026 invoice].pdf.json 成为孤儿），默认干跑：

rm 'docs/report[finance 2026 invoice].pdf'
tscmd metacleaner docs

实测回显：

[dry-run] cleaned: docs/.ts/logo.png.jpg
✔ Done cleaning: docs

实验 20：真删（--analyze false）与终态核对。

tscmd metacleaner docs --analyze false
ls docs/.ts/

实测回显：

[delete] cleaned: docs/.ts/logo.png.jpg
✔ Done cleaning: docs
memo[work demo].txt.json
note.md.json
photo.jpg.json
report[finance 2026 invoice].pdf.json
tsft.jsonl
tsi.json
tsm.json

实测结论（4.8.10 真实行为，两项都与直觉相反）：

  1. 孤儿 sidecar 没有被清理——.ts/report[finance 2026 invoice].pdf.json 在真删后依然存在（干跑与真删均未列出它）；
  2. 合法缩略图反而被判定为过时——logo.png 本体仍在，其缩略图 .ts/logo.png.jpg 被标记并删除。

实验 23：可复现性验证。 重新生成缩略图后再干跑，行为一致：

tscmd thumbgen docs        # 回显 ✔ Thumbnails generated: docs（logo.png.jpg 重建）
tscmd metacleaner docs     # 回显 [dry-run] cleaned: docs/.ts/logo.png.jpg

生产建议：把 metacleaner 当「需人工复核的工具」而非定时清理任务——先干跑审阅清单、再决定是否 --analyze false；孤儿 sidecar 需自行比对 .ts/*.json 与目录实际文件清单处理（或升级版本后复测）。--analyze 默认 true（干跑）是安全设计，真删必须显式传 --analyze false。

五、注意事项

  1. 索引不会自动更新：tag/describe/删除文件都不改索引。实测：删除 report 后未重索引时，tscmd search docs -q finance 仍命中已不存在的 report[finance 2026 invoice].pdf [finance 2026 invoice] (17 B)（回显 Found 1 result(s)）——检索结果以 tsi.json 为准，增删改文件后必须重跑 indexer --force；
  2. 增量 --fulltext 会丢旧全文（4.1 实验 2）：tsi.json 增量正确、tsft.jsonl 被重写为仅含变更文件；凡用全文索引一律 --force；
  3. -q 传 - 开头的排除标签会被 yargs 截获：-q -vacation 中 -v 被解析成版本号，实测直接打印 4.8.10 退出；排除/或标签用等号或引号+空格形式传：--query=-vacation、-q '|a |b'；
  4. |tag 是标签维度过滤：filterByTags 调试输出表明 OR 走标签过滤而非全文关键词——裸词才全文检索（实验 14 与实验 11 的内部阶段输出不同）；
  5. 命令级错误不中断批处理：thumbgen 对坏图打印错误后继续，结尾仍 ✔ 汇总；解析汇总行不能代替逐文件核对（对坏样张要人工确认）；
  6. rename 打标会改文件名：依赖原文件名的脚本/硬链接/同步工具会受影响；对象存储场景改用 -m sidecar；
  7. metacleaner 默认干跑：-a, --analyze 默认 true，真删须显式 --analyze false（见 4.6 的两项反直觉实测）。

六、常见问题

Q1：为什么搜索中文「收入增长」能命中，搜「增长」也命中，但搜英文大小写有区别吗？

大小写无区别：-q memo 与 -q MEMO 结果一致（实验 11 实测，fuse 查询层归一）。中文命中的前提是索引时带 --fulltext 且查询词与切词结果重叠（二元+一元混合切词，见 4.1 的 tsft.jsonl 实例）；未建全文索引（或不带 -f）时裸词查询命中不了文件内容。

Q2：增量索引后旧文件的全文搜不到了？

4.1 实验 2 的陷阱：indexer --fulltext（不带 --force）增量更新时 tsft.jsonl 只保留本次变更文件的分词。用 tscmd indexer <dir> --fulltext --force 全量重建即恢复（实验 3 实测 3 files with fulltext）。

Q3：search 的 |tag 为什么搜不到我想要的关键词？

| 前缀作用于标签（OR 过滤），不是全文关键词。全文检索用裸词（-q '关键词'），标签过滤用 +/-/|；组合语义见 --help 示例 "notes +work -draft |urgent"（类型组 + 必含标签 + 排除标签 + 或标签）。

Q4：运行 thumbgen 前需要先安装 sharp 吗？

不需要。官方 README 提及 sharp 的说明对应旧版本；4.8.10 实测内置 wasm-vips（4.2 错误栈可见 node_modules/wasm-vips/...），npm ls -g 全局仅 @tagspaces/shell@4.8.10 一个包时缩略图正常生成。本实验容器无外网，npm install -g sharp 执行无输出且未安装成功，thumbgen 仍工作正常——sharp 可选、非必需。

Q5：metacleaner 为什么删了我的缩略图、却留下孤儿 sidecar？

4.8.10 的实测行为（实验 18-23）：孤儿 sidecar 不在其清理范围，而新近生成的缩略图可能被判定为「过时」标记删除，且行为可复现、输出不解释判定原因。因此不要把它当无人值守的定时清理用：先干跑审阅 [dry-run] cleaned: 清单；孤儿 sidecar 按目录清单自行比对删除。此行为与工具名暗示的「Remove obsolete sidecar files」预期有差距，升级版本时建议复测。

Q6：-q -vacation 打印 4.8.10 就退出了，怎么传「排除标签」？

yargs 把 -vacation 的开头 -v 解析成了版本参数（实测回显 4.8.10）。用等号形式：tscmd search docs --query=-vacation；多标签用引号加空格：-q '|vacation |finance'。

七、参考链接

  1. npm 包主页（@tagspaces/shell）：https://www.npmjs.com/package/@tagspaces/shell
  2. TagSpaces 源码仓库：https://github.com/tagspaces/tagspaces
  3. 官方文档站（tagging/architecture 行为依据）：https://docs.tagspaces.org/
  4. 本专栏实测系列：《TagSpaces 介绍与选型指南》、《TagSpaces 6.13.9 Docker Compose 部署指南》、《TagSpaces 6.13.9 配置参数详解》