本地工作区命令行
`vizchat` 命令让工作区在磁盘上成为可以直接编辑的文件夹：与云端双向同步、导出与导入 .vizpkg，并回答两个纯文件工具答不上来的问题——这个文件的 ref 是什么、这个工作区还自洽吗。
VizChat 的工作区在磁盘上有确定的形态。vizchat 命令（npm 上的 vizchat 包）让你和本地
工具直接对着这个形态干活。
npm install -g vizchat
vizchat --help命令按名词分组：auth、workspace、document、board、widget、review、preferences。本页讲本地工作区命令与云端命令；
开发与发布 widget 见用命令行发布 widget。
工作区在磁盘上长什么样
~/VizChat/Q3 汇报/
├─ Q3 汇报/
│ ├─ 季度回顾.stb ← 真实文件，用什么编辑器都行
│ └─ 数据源.pdf
├─ .vizchatignore gitignore 语法，自身从不同步
└─ .vizchat/
├─ manifest.json 同步基线（≈ Git 的 HEAD）
├─ records.json 每份文档的元数据，按 ref 索引
├─ derived/<ref>/ 派生数据——下载下来的，只读
│ ├─ manifest.json 这个目录里有什么，与云端逐字节相同
│ ├─ text.md PDF 的文字层或 Office 文档的正文——纯文本，能直接搜
│ ├─ parse.json 大纲与页面区域坐标
│ ├─ ocr/text.md PDF 或图片识别出的文字（第一次被读取时识别，有它就以它为准）
│ ├─ ocr/parse.json 识别结果的大纲与页面区域坐标
│ ├─ listing.md 压缩包里有什么
│ └─ tts/** 讲稿语音
└─ local/ 本机私有，永不进包你的文件就在你放的位置、用你起的名字。VizChat 同步所需要的一切都在 .vizchat/ 下。
命令一览
| 命令 | 做什么 | 要联网吗 |
|---|---|---|
vizchat auth login | 在浏览器里批准这台机器（读、写、发布三项权限，可取消勾选写或发布），凭证存进 ~/.config/vizchat、自动续期 | 是 |
vizchat auth logout / whoami | 撤销这台机器的登录 / 看当前身份与授予的权限 | 是 |
vizchat auth exchange | 在 GitHub Actions 里用身份令牌换一个短时效凭证（须先在设置页登记可信发布）；CI 也可直接设 VIZCHAT_TOKEN | 是 |
vizchat workspace clone <工作区> [目录] | 把空文件夹绑定到云端工作区并拉下来；写成 <作者>/<slug> 则是克隆某个 widget 的工作区。对已绑定同一工作区的文件夹重跑，等于同步一次 | 是 |
vizchat workspace sync | 与云端工作区双向对账同步 | 是 |
vizchat workspace export <目录> <file.vizpkg> | 把工作区文件夹打成 .vizpkg | 否 |
vizchat workspace import <file.vizpkg> <目录> | 把导出的包展成可编辑的文件夹（目标已存在则整个替换） | 否 |
vizchat workspace check | 自查工作区：结构、保留名、悬空引用、过期的解析产物、与清单对不上的派生文件 | 否 |
vizchat document ls | 列出文档：ref、类型、有没有派生数据（提取正文、压缩包清单、讲稿语音……） | 否 |
vizchat document ref <file> | 查一个文件的 ref——写 widget 引用时要用它；--by-ref <ref> 反查路径 | 否 |
workspace sync / check 与 document ls / ref 会从当前目录向上找工作区根，所以在任意子目录里都能跑；
想指明就加 --root <dir>。
云端命令
这些命令调用的是 VizChat 网页端与已连接的 AI 应用所用的同一组操作，作用在云端工作区上。工作区（或 widget）取自你运行
命令的文件夹——--root <dir> 指向别处，--workspace <id>（或写出 widget 名）选一个不在本机上的。
| 命令 | 做什么 |
|---|---|
vizchat workspace ls [--kind widget] | 列出你的云端工作区（或 widget 草稿），以及能否同步到本地文件夹 |
vizchat board render <file> [--pages 1 2] [--theme light|dark] | 在云端逐页渲染 board。截图写到 .vizchat/local/renders/<文件>/（从不同步）；JSON 给出图片路径、测量（字数、最小字号、旁白时长）与审查发现 |
vizchat board show <file> / --board <author>/<slug> | 在 VizChat 客户端里打开 board；没装客户端则在浏览器里打开。带 --board 时打开已发布 board 的公开作品页 |
vizchat board ls [--favorited] | 列出你发布的（或收藏的）board：类型、最新版本、是否允许他人套用。还没发布的 board 是工作区里的文件 |
vizchat board search <词> [--type storyboard|dashboard] [--reusable] | 检索素材市场上已发布的 board |
vizchat board apply <author>/<slug> | 套用一份已发布的 board：连同它用到的文件复制进这个工作区的一个新文件夹，再同步一次拉到本地。别人的 board 须允许套用。带 --idempotency-key <键> 时，用同一个键重跑返回第一次复制出的那份，不再复制 |
vizchat board updates <file> / update-widgets <file> | 看 board 里哪些 widget 有新版本 / 升到新版本 |
vizchat widget render [--scenes …] [--theme …] / check | 渲染 widget 的默认快照与各页 demo / 完整审查。截图写到 .vizchat/local/renders/<作者>/<slug>/ |
vizchat widget show [widget] | 在 VizChat 客户端的编辑器里打开 widget，或在浏览器里打开 |
vizchat widget ls [--favorited] | 列出你做的 widget（草稿与已发布），或你收藏的，带草稿工作区 id |
vizchat widget search <词> / describe <widget...> / get [widget] | 检索 widget、读它的操作说明、看草稿状态 |
vizchat widget history / restore <snapshot-id> | 列出草稿快照 / 回到某个快照（回退前的状态也会存一份，可以撤回） |
vizchat review record <发现...> --kind … --decision fix|accept|user | 记下你对审查发现的决定，内容不变时不再重复提出 |
vizchat preferences get / set | 读取 / 修改个人偏好（修改需要你确认） |
它们会先推送本地改动。 渲染与展示发生在云端，所以 board render、board show <file>、widget render、widget check、
widget show 开始前先把这个文件夹里的改动推上去（只允许快进）。云端也改了同样的文件时以 merge_pending（退出码 10）停下，
先合并。改写文档的命令（board update-widgets）结束后还会再同步一次，把结果拉回文件夹；board apply 结束后同步一次，把复制出的文件拉下来。
有的需要你确认。 preferences set 在交互终端里会先问你；在脚本或 agent 里要带 --yes，且只能在你同意之后。服务端
还可能请你在 VizChat 的确认页上确认：命令会打印链接（在终端里会直接打开）——确认后再跑一次。
渲染、检查这类长任务在云端执行，命令会一直等到它结束，返回的就是任务的结果。
每个命令的 stdout 末行恒为一行 JSON，说明文字一律走 stderr——脚本和 agent 不必从人话里解析结果。
失败时 JSON 里有小写的 code（invalid_argument、auth_required、not_found、conflict、
merge_pending……）、给出下一步的 hint，退出码跟着 code 走：
| 退出码 | code |
|---|---|
| 0 | 成功 |
| 1 | internal |
| 2 | invalid_argument、client_outdated |
| 3 | auth_required |
| 4 | invalid_content |
| 5 | confirmation_required |
| 6 | unavailable（可重试） |
| 7 | permission_denied |
| 8 | not_found |
| 9 | conflict |
| 10 | merge_pending |
| 11 | quota_exceeded |
vizchat --help 会打印同一张表。服务端不再支持你这个版本的 CLI 时，命令会以 client_outdated 停下并打印升级命令，本地文件一个都不动。
配合 AI 编程助手
带普通文件工具的助手本来就能读写 .stb / .md、建目录、挪文件。光靠文件系统拿不到的只有三件事：
搜 PDF 正文。 PDF 的正文在 .vizchat/derived/<ref>/ 下：识别过的读 ocr/text.md，否则读 text.md
（文字层）。多数搜索工具默认跳过点目录，所以要加 --hidden：
rg --hidden --glob '!.vizchat/local/**' "营收"命中落在 text.md 或 ocr/text.md 里时，derived/ 下那一级目录名就是 ref；vizchat document ls 能把它换回文件名。
给文件写引用。 widget 引用文档一律用 ref 而不是路径——这样改名、移动都不会让引用失效。先拿 ref：
vizchat document ref "Q3 汇报/数据源.pdf"推送前自查。 vizchat workspace check 会报出所有会让同步失败的东西：引用了不在这里的文档、用了保留名、
文件不在清单里。它还会列出 modified——那只是你还没推送的改动，不是问题。
同步
vizchat workspace sync 把这个文件夹与云端工作区对上：云端变了的拉下来，本地变了的推上去。
第一次跑之前，先看它打算做什么：
vizchat workspace sync --dry-run它会逐条列出将要发生的变更，一个字节都不写。确认无误再跑 vizchat workspace sync。
派生数据只下行。 提取正文、压缩包清单、讲稿语音都在云端生成，云端一变就下载到 .vizchat/derived/——
只下载变了的文件，manifest.json 最后写。把这个目录当成只读的：同步从不上传它，你在里面改的东西会在
云端那份下次变化时被覆盖（在那之前 vizchat workspace check 会报出来）。
想让它一直盯着，加 --watch：有本地改动就立即同步，没有改动时也会定期回头看一眼云端
（另一台机器的改动只能这样才看得到）。Ctrl-C 结束。
它在什么情况下会停下来问你
同步唯一可能造成损失的动作是删除，所以有两道闸：
- 一次要删的文件太多（绝对数量或占比超过阈值）时不执行，先把清单列给你。外置硬盘没挂载、
同步文件夹被整个移走，看起来都像「你把文件全删了」。确认清单无误后加
--yes重跑（退出码 5，confirmation_required）。 - 离线太久（超过回收站的保留期）时，云端已经查不到那些文件是被删了还是同步出过错。 这类文件会被标成「需要确认」而不是自动删掉。
两边都改了同一个文件
文本文件两份都留：云端那版留在原处，你本地那版另存成
<原名>.conflict-<时间>-<机器名>.<扩展名> 并一并推上云端——这样你换台机器也还看得到它。
二进制文件（PDF、图片、音视频）不做合并：本地那份会成为新版本，云端原来那版另存成
<原名>.remote-<时间>.<扩展名> 留在本地，由你自己取舍。
widget 工作区：在本地合并，还是交给云端
widget 的工作区放的是代码，两份内容不能像文档那样并排留着。本地与云端都改了 widget 文件时，用 --merge 选在哪合并：
--merge local（一次性同步的缺省）：每个冲突文件的三份内容写进.vizchat/merge/<id>/{base,local,remote}/<路径>——双方出发时的版本、你的版本、云端的版本。工作目录保留你的版本， 命令以merge_pending（退出码 10）停下。把云端的改动合进工作目录（自己来，或让你的编程助手来），再跑vizchat widget merge --continue；vizchat widget merge --abort放弃，把你的改动交给云端。 合并未完成时sync与publish都拒绝执行，不会把合了一半的树推上去。 云端已经存着待合并记录时（之前的--watch或桌面客户端留下的），在克隆下来的 widget 文件夹里跑vizchat widget merge会用同样的方式取最早的一条：先同步，把三份内容写到.vizchat/merge/<id>/，再把存下的本地修改放进工作目录。合并后--continue推上去，并在云端把记录标为已合并。两边都改了的二进制文件没有内容可比——用--keep <路径>=local或--keep <路径>=remote选一份。--merge cloud（--watch的缺省——没有人可问）：把你的本地改动交给云端。不冲突的直接合进云端；冲突的文件 存成待合并记录，下次让 agent 修改这个 widget 时合并。你的文件夹恢复为云端版本。
哪些文件不同步
点文件默认不同步。想排除更多，在工作区根写 .vizchatignore（gitignore 语法）——
workspace import 时会给你生成一份默认模板。此外这些会被列进「未同步」并说明原因，但不会让整轮同步失败：
路径里有保留名的、超过单文件上限的大文件、存储已满时的新文件。
「stale」是什么意思
PDF 的提取正文与页面区域是从某一版文件算出来的。换掉 PDF 之后它们就对不上了。vizchat workspace check 把
这种情况报成 stale：正文通常仍有参考价值，但页面高亮会画到错的位置，所以在重新解析之前会被丢掉。
换行符
文本文件的换行符与 BOM 原样保留：VizChat 记下一个文件用的是哪种，在每台机器上都按原样写回。内容的哈希 按「LF、无 BOM」的口径算，所以编辑器换了换行符不会让 VizChat 以为每一行都变了——但这次切换本身照样同步， 其他机器拿到的是同样的字节。