viqueue

viqueue 是一个极简的拉取式工单看板，面向私有的单操作员 dogfood 环境。CLI 为 viq；工单 ID 形如 ABC-123。v0.4.1 仍为预发布版本，尚未达到生产就绪。

配对 PoC 契约

HTTP JSON 核心是唯一的状态机。授权刻意保持精简：

• 一次性、短时效的设备配对码；

• 固定的配对设备类型：coordinator 或 worker；

• 仅用作 worker 分配组的简单角色。

coordinator 可以创建/编辑/归档工单，分配给 worker 设备或角色，应答/审阅提交，签发/撤销配对，以及管理角色。worker 可以读取已分配的工作，原子地认领，发布受认领围栏保护的进度/问题/阻塞项/提交，或释放其认领。角色不授予任何 API 权限。

分配即启动授权。每个 HTTP、CLI 和 /viq 认领调用都使用相同的谓词：活跃的已配对 worker、开放的工单、精确的设备/角色分配、无未解决的阻塞项、且无当前认领。精确的设备/角色分配优先；符合条件的未分配自由池工单也可以在项目、角色和成员边界内原子地认领。不存在接管。没有 Start 操作、存储的 Ready 状态、通用作用域系统或活跃的 execution_authorities 路径。

认领保持为持久的、代际围栏保护的锁，直到显式释放或提交。认领和设备凭据仅在创建/配对时返回，以哈希形式存储在 SQLite 中，绝不包含在工单/模型上下文中。

Related MCP server: Ticket API MCP Server

引导与运行

需要 Node.js 22。

npm test
npm run build
viq-bootstrap --storage ./data/viqueue.sqlite --id coord --name "Coordinator"
node dist/src/server.js --storage=./data/viqueue.sqlite

viq-bootstrap 是一个本地安装操作，仅打印一次第一个 coordinator 凭据。使用 --device-token 或 VIQ_DEVICE_TOKEN 提供凭据：

viq project create ABC --device-token COORDINATOR_CREDENTIAL
viq device pair-code --kind worker --device-token COORDINATOR_CREDENTIAL
viq role create tower-pi --name "Tower Pi" --device-token COORDINATOR_CREDENTIAL
viq role grant tower-worker tower-pi --device-token COORDINATOR_CREDENTIAL
viq ticket create ABC "Fix parser" --assignee-role tower-pi --device-token COORDINATOR_CREDENTIAL
viq ticket claim-next --project ABC --device-token WORKER_CREDENTIAL

当不存在有效的本地配对时，浏览器看板会显示配对表单。新 coordinator 签发的代码绑定 actor、类型、设备 ID 和设备名称，因此仅需一次性代码的客户端只需该代码；浏览器保留 ID/名称输入以支持遗留的可空代码。看板验证 /v1/devices/me，并仅将返回的凭据存储在 localStorage['viq.deviceCredential'] 中。无效/已撤销的凭据会自动清除，断开此设备 仅清除浏览器本地状态，不会撤销服务器端的设备。

MCP 使用 VIQ_URL 和 VIQ_DEVICE_TOKEN，并暴露只读的设备/任务/状态视图；它不能获取或变更认领。使用 pi install <Viq package> 在用户的 Pi 配置文件中安装现有包。该 Unix 用户后续的 Pi 会话会发现：

/viq PAIRING_CODE [--project KEY]
/viq status
/viq pause|resume|stop

/viq PAIRING_CODE 配对并在当前可见的 Pi 会话中启动 worker；没有单独的 worker 命令或启动仪式。在每次认领尝试之前，它会在当前 Vault 中可见地运行 tools/vault-sync/vault-sync sync，并且仅在状态证明干净的 CURRENT/EQUAL 规范提交后才认领。VIQ 服务器仍然是唯一的资格和原子认领权威，完整的返回工单契约在注入时保持不变，并带有清理后的历史记录。viq_submit 再次可见地同步，并在发布成功后才提交操作者证据和精确的已发布提交；冲突、守卫或离线失败会保留围栏认领以供重试。

配对在仓库外部写入 JSON，路径为 ${XDG_CONFIG_HOME:-~/.config}/viq/credential.json，目录模式为 0700，文件模式为 0600。同一 Unix 用户的会话会复用该文件；其他用户不会。支持普通 root Pi，并接收仅 root 可读的文件。轮询是由该 Pi 会话拥有的定时器，在会话关闭时停止，没有守护进程或重复的生命周期存储。显式的 VIQ_WORKER_LOCKDOWN=1 保留历史隔离工作区/拒绝 root 的轮廓。凭据不会出现在提示、状态、工具结果、argv、环境或请求体中；受信任的 Pi 进程必然可以读取其自身 Unix 用户的文件。

一个精确的仅 worker 归档从干净的已提交 HEAD 构建，使用 npm run bundle:worker -- OUTPUT_DIR。它包含 SOURCE_COMMIT、SOURCE_TREE、配置的 package.json 发现路径，以及仅 worker 扩展/运行时。scripts/install-viq-worker.sh 需要显式的 VIQ_WORKER_ROOT、精确的候选提交和精确的当前前驱，然后才创建只读发布并原子地重命名 current 符号链接。scripts/rollback-viq-worker.sh 仅接受该已安装的候选和密封的前驱；VIQ-15 前驱为 1398284ed89a6cf9395f129483f709e63c009286。测试和演练必须使用隔离的根目录，绝不能使用 /opt/viq-worker。

迁移与回滚

前向迁移创建 devices、pairing_codes 和 device_roles。旧的 execution_authorities 表仅保留以便回滚到早期构建；候选代码既不连接、写入、消费也不暴露它。安装需要在切换客户端之前进行本地 coordinator 引导。回滚将先前的二进制文件和数据库快照一起恢复；旧二进制文件仍可读取其保留的表。

VIQ-15 切换预检和回滚有意不固定整表行数。工单、事件、角色成员资格和其他无关的实时状态在审查和切换之间可能合法地变化，必须保留。全局数据库安全改为由 SQLite 完整性、精确的模式摘要、经过认证的回滚工件以及写入者停止后源/SQLite 一致备份的模式和计数相等性来强制。协调辅助工具在 VIQ-15 更改的精确认领、开放问题、actor、分配和时间戳上单独失败关闭。

v0.2 导入器保持显式，且从不覆盖现有目标。npm run bundle 拒绝脏树，记录精确的提交/树身份，并创建确定性的本地归档。安装器写入不可变的发布目录并原子地切换 current，保留 previous；rollback-local.sh 将其切换回来。当 VIQ_STORAGE 已存在时，安装需要显式的离线确认，并使用 SQLite 的备份 API 在任何指针更改之前捕获并验证已提交的主/WAL 状态。可选的回滚恢复首先创建并验证 SQLite 一致的候选后保留副本，然后准备并验证先前的快照，再替换数据库并移除过时的 sidecar；它同样需要 VIQ_RESTORE_STORAGE=1、VIQ_STORAGE 和离线确认。卸载会移除启动器/指针，但保留发布和备份证据。这里没有任何内容发布、部署或变更实时状态。

viqueue 根据 Apache License 2.0 许可。有关受限私有 PoC 威胁模型，请参阅 SECURITY.md。