Work System zh CN

Work 任务系统

语言： English · 简体中文

LWC 会把耗时较长、需要中断恢复的状态变更交给持久化 Work 执行。发起命令会尽快返回 Work ID，随后由脱离当前终端的 worker 记录进度、结果与错误。

Work 是执行凭据，不是完成证明。命令返回 graph.work、work 或 graph_work 时，必须跟踪到终态才能验收该操作。

哪些操作会创建 Work

当前 Work 类型包括：

• 文档图投影；
• Schema 迁移；
• 维护性重建索引；
• Markdown 物化；
• SQLite 压缩。

普通检索以及规范 Page、Source 读取不会变成 Work。无关后台任务运行时，这些读取仍可使用。

状态流转

queued -> running -> succeeded
                  -> failed -----> resume -> queued
                  -> cancelled --> resume -> queued
stale interrupted -------------> resume -> queued

succeeded、failed 与 cancelled 都是终态。成功记录包含操作结果，失败和取消记录包含结构化错误。

Work 还会提供当前 phase、已完成数量、可确定时的总量、百分比、处理速率、预计剩余时间、更新序号、时间戳、运行中的进程 ID 和取消标记。这些字段用于观察进度，真正的验收依据仍是终态及其结果。

查看 Work

lwc --scope project work list
lwc --scope project work status <work-id>
lwc --scope project work watch <work-id>

list 按最近更新时间倒序返回所选 Wiki 的 Work；status 读取一次当前快照；watch 会轮询到 Work 进入终态，再返回最终记录。

Work ID 是 64 位十六进制标识。它属于当前选中的 Wiki；草稿操作还必须匹配对应 changeset 运行目录。

验收规则

看到 queued 或 running 不能停止：

lwc --scope project work watch <work-id>
lwc --scope project graph verify

图投影需要同时满足：

1. Work 状态为 succeeded；
2. graph verify 返回 ok=true。

前者证明 worker 已执行完成，后者证明派生图与规范 Wiki 状态一致。

维护类 Work 完成后，要检查终态中的 result，再针对修复目标执行验收，例如 lint、检索、Markdown 物化结果或图校验。

协作式取消

lwc --scope project work cancel <work-id>
lwc --scope project work watch <work-id>

取消采用协作机制。cancel 只记录请求，worker 会在安全的进度边界观察它，并以 cancelled 结束，错误码为 work_cancelled。如果 Work 已经进入终态，cancel 会原样返回，不改写原结果。

因此，第一次 cancel 响应不一定已经是 cancelled，仍需继续 watch 到终态。

恢复执行

lwc --scope project work resume <work-id>
lwc --scope project work watch <work-id>

失败、已取消或 stale interrupted Work 可以 resume。LWC 会清除取消请求，把同一份持久化请求重新排队，并保留原 Work ID。刚进入队列、仍在运行或已经成功的 Work 会返回 work_not_resumable。

只有先消除失败原因，恢复才有意义。例如，文件系统权限或配置导致维护任务失败时，应先修好对应问题。

并发与合并

每个 Wiki 运行目录同一时间只允许一个状态变更 Work。已有任务占用时启动其他类型会返回 work_busy。

文档图投影会主动合并。新的脏文档键进入持久化 pending set，正在运行的 graph-project 会在结束前继续消费后续批次。因此，多次 Page 变更可能拿到同一个活动 Work，而不是为每次 mutation 创建独立 worker。

如果完成边界又收到新图文档，LWC 会启动下一项投影 Work。所有相关 Work 结束后仍必须运行最终图校验。

草稿隔离

检查草稿 Work 时必须沿用创建它的 changeset selector：

lwc --scope project --changeset architecture-refresh work list
lwc --scope project --changeset architecture-refresh work watch <work-id>
lwc --scope project --changeset architecture-refresh graph verify

每份草稿都有独立 Work root 与图 sidecar。草稿 A 的 Work ID 在草稿 B 中会返回 work_not_found，live Work 与草稿 Work 同样彼此隔离。

Commit、rollback 和 discard 只有在规范恢复契约允许后才会清理草稿运行状态。禁止手工把 Work 文件或图 sidecar 在不同 store 之间移动。

持久状态与进程中断

Work 请求和状态快照保存在所选 Wiki 的运行目录下。状态文件采用替换写入；系统支持时会限制目录权限，并拒绝符号链接或数据库作用域不匹配的路径。

Worker 独立于发起命令的终端运行。进程如果消失且没有写下终态，heartbeat 超过 30 秒后会被视为 stale，此时可以通过 resume 重新启动。

不要编辑 Work JSON、删除 active marker，也不要自行调用隐藏 worker 命令。统一通过 status、cancel 与 resume 操作，才能保持归属和恢复保证。

失败处理

结合结构化错误与当前 Work 状态判断：

• work_not_found：该 ID 不属于当前选择的 live 或草稿 Wiki；
• work_busy：另一项状态变更 Work 正占用运行目录；
• work_not_resumable：Work 已成功，或仍处于新鲜的活动状态；
• work_cancelled：取消请求已到达安全边界；
• work_invalid：持久状态、路径归属或 Work 类型无效。

创建 Work 的命令如果同时报告规范状态已部分成功，应执行其准确的 recovery_command，不要只凭 Work 错误自行拼接恢复步骤。

完成证据

Work 驱动的操作满足以下条件才算完成：

• Work ID 已与发起操作一起记录；
• watch 返回终态；
• 终态为 succeeded，且已经检查其中的结果；
• 目标子系统对应的验收检查通过；
• 失败或取消的任务只在消除原因后恢复；
• 草稿 Work 始终通过正确 changeset selector 查询。

下一篇：Checkpoint 与回滚