本地工作区命令行
`vizchat` 命令让工作区在磁盘上成为可以直接编辑的文件夹：与云端双向同步、把 .vizpkg 展开与打回，并回答两个纯文件工具答不上来的问题——这个文件的 ref 是什么、这个工作区还自洽吗。
VizChat 的工作区在磁盘上有确定的形态。vizchat 命令与 vizchat-widget 同包发布，让你和本地
工具直接对着这个形态干活。
npm install -g @vizchat/widget-scripts
vizchat --help工作区在磁盘上长什么样
~/VizChat/Q3 汇报/
├─ Q3 汇报/
│ ├─ 季度回顾.stb ← 真实文件，用什么编辑器都行
│ └─ 数据源.pdf
├─ .vizchatignore gitignore 语法，自身从不同步
└─ .vizchat/
├─ manifest.json 同步基线（≈ Git 的 HEAD）
├─ records.json 每份文档的元数据，按 ref 索引
├─ derived/<ref>/ 派生数据——下载下来的，只读
│ ├─ manifest.json 这个目录里有什么，与云端逐字节相同
│ ├─ text.md PDF 或图片的提取正文——纯文本，能直接搜
│ ├─ parse.json 大纲与页面区域坐标
│ ├─ listing.md 压缩包里有什么
│ └─ tts/** 讲稿语音
└─ local/ 本机私有，永不进包你的文件就在你放的位置、用你起的名字。VizChat 同步所需要的一切都在 .vizchat/ 下。
命令一览
| 命令 | 做什么 | 要联网吗 |
|---|---|---|
vizchat auth login | 在浏览器里批准这台机器，凭证存进 ~/.config/vizchat | 是 |
vizchat auth logout / whoami | 撤销这台机器的凭证 / 看当前身份 | 是 |
vizchat sync | 与云端工作区双向对账同步 | 是 |
vizchat unpack <file.vizpkg> <dir> | 把导出的包展成可编辑的文件夹 | 否 |
vizchat pack <dir> <file.vizpkg> | 把文件夹打回 .vizpkg | 否 |
vizchat ls | 列出文档：ref、类型、有没有派生数据（提取正文、压缩包清单、讲稿语音……） | 否 |
vizchat ref <file> | 查一个文件的 ref——写 widget 引用时要用它 | 否 |
vizchat check | 自查工作区：结构、保留名、悬空引用、过期的解析产物、与清单对不上的派生文件 | 否 |
sync / ls / ref / check 会从当前目录向上找工作区根，所以在任意子目录里都能跑；想指明就加
--root <dir>。
每个命令的 stdout 末行恒为一行 JSON，说明文字一律走 stderr——脚本和 agent 不必从人话里解析结果。
服务端不再支持你这个版本的 CLI 时，命令会以 CLIENT_OUTDATED 停下并打印升级命令，本地文件一个都不动。
配合 AI 编程助手
带普通文件工具的助手本来就能读写 .stb / .md、建目录、挪文件。光靠文件系统拿不到的只有三件事：
搜 PDF 正文。 PDF 的提取正文在 .vizchat/derived/<ref>/text.md。多数搜索工具默认跳过点目录，
所以要加 --hidden：
rg --hidden --glob '!.vizchat/local/**' "营收"命中落在 text.md 里时，它所在的目录名就是 ref；vizchat ls 能把它换回文件名。
给文件写引用。 widget 引用文档一律用 ref 而不是路径——这样改名、移动都不会让引用失效。先拿 ref：
vizchat ref "Q3 汇报/数据源.pdf"推送前自查。 vizchat check 会报出所有会让同步失败的东西：引用了不在这里的文档、用了保留名、
文件不在清单里。它还会列出 modified——那只是你还没推送的改动，不是问题。
同步
vizchat sync 把这个文件夹与云端工作区对上：云端变了的拉下来，本地变了的推上去。
第一次跑之前，先看它打算做什么：
vizchat sync --dry-run它会逐条列出将要发生的变更，一个字节都不写。确认无误再跑 vizchat sync。
派生数据只下行。 提取正文、压缩包清单、讲稿语音都在云端生成，云端一变就下载到 .vizchat/derived/——
只下载变了的文件，manifest.json 最后写。把这个目录当成只读的：同步从不上传它，你在里面改的东西会在
云端那份下次变化时被覆盖（在那之前 vizchat check 会报出来）。
想让它一直盯着，加 --watch：有本地改动就立即同步，没有改动时也会定期回头看一眼云端
（另一台机器的改动只能这样才看得到）。Ctrl-C 结束。
它在什么情况下会停下来问你
同步唯一可能造成损失的动作是删除，所以有两道闸：
- 一次要删的文件太多（绝对数量或占比超过阈值）时不执行，先把清单列给你。外置硬盘没挂载、
同步文件夹被整个移走，看起来都像「你把文件全删了」。确认清单无误后加
--yes重跑。 - 离线太久（超过回收站的保留期）时，云端已经查不到那些文件是被删了还是同步出过错。 这类文件会被标成「需要确认」而不是自动删掉。
两边都改了同一个文件
文本文件两份都留：云端那版留在原处，你本地那版另存成
<原名>.conflict-<时间>-<机器名>.<扩展名> 并一并推上云端——这样你换台机器也还看得到它。
二进制文件（PDF、图片、音视频）不做合并：本地那份会成为新版本，云端原来那版另存成
<原名>.remote-<时间>.<扩展名> 留在本地，由你自己取舍。
哪些文件不同步
点文件默认不同步。想排除更多，在工作区根写 .vizchatignore（gitignore 语法）——
unpack 时会给你生成一份默认模板。此外这些会被列进「未同步」并说明原因，但不会让整轮同步失败：
路径里有保留名的、超过单文件上限的大文件、存储已满时的新文件。
「stale」是什么意思
PDF 的提取正文与页面区域是从某一版文件算出来的。换掉 PDF 之后它们就对不上了。vizchat check 把
这种情况报成 stale：正文通常仍有参考价值，但页面高亮会画到错的位置，所以在重新解析之前会被丢掉。
换行符
文本文件的换行符与 BOM 原样保留：VizChat 记下一个文件用的是哪种，在每台机器上都按原样写回。内容的哈希 按「LF、无 BOM」的口径算，所以编辑器换了换行符不会让 VizChat 以为每一行都变了——但这次切换本身照样同步， 其他机器拿到的是同样的字节。