English | 简体中文

Workstate

受治理的工作状态层：在这里，一个任务是一条可验证的溯源链——起源、 依赖、归属、状态转移与证据——而不是一条待办事项。

属于 Octopus Core——面向受治理 AI 的开放基础设施栈。 每个仓库只做一件事，沿着 agent 生命周期排列：Scout · Observe · Experience · Blackboard · Runtime · Replay——由 Inspect 治理每一个阶段。整个栈都建立在同一个根原语之上——共享的 Evidence 原子。

本仓库——Workstate： 追踪工作从哪来、以及它为何发生状态迁移——而不只是它是否完成。

observation / decision → WorkItem → transitions (evidence chain) → done + proof
                                       ↑ every move is verifiable Evidence

大多数任务工具存储的是一个状态标志：它能不能做、谁在做、是否 已完成？Workstate 存储的是工作本身的溯源：它从哪来 （其起源的 observation 或 decision）、由谁负责、依赖于什么，以及——对于 每一次状态变更——一条提交到防篡改审计链上的 octopus-evidence Evidence。 一个只持有导出轨迹的外部审计方可以运行 verifyAuditTrail()（或 WorkStateGraph.restore()），无需信任存储方即可确认整段历史——链、证据以及 状态机可达性。当存储运营方不可信时，设置 WORKSTATE_SECRET（加密钥模式）； 不加密钥模式证明的是一致性与可达性，而非作者身份 （详见）。

快速开始

import { WorkStateGraph } from "octopus-workstate";

const graph = new WorkStateGraph();

// Work exists because something was observed — not because someone typed a to-do.
graph.add({
  id: "WORK-1",
  title: "Review flagged AI draft",
  origin: { originType: "observation", ref: { type: "observation", id: "obs-4821" } },
});

graph.transition("WORK-1", "ready", { by: { id: "alice", kind: "human", source: "oidc" } });
graph.transition("WORK-1", "claimed", { by: { id: "alice", kind: "human" } });
graph.transition("WORK-1", "in_progress", { by: { id: "alice", kind: "human" } });
graph.transition("WORK-1", "done", {
  by: { id: "alice", kind: "human" },
  reason: "Draft accurate; signed off.",
  evidence: [{ evidenceId: "ev-review-hash", kind: "human-oversight" }],
});

graph.history("WORK-1"); // the item's 来时的路 — every move, in order
graph.verify(); // { ok: true } — the audit chain re-verifies independently

运行端到端示例：node --import tsx examples/triage.ts。

CLI（对 agent 友好、零第三方依赖）

octopus-workstate 可执行程序是一个 beads 风格的接口，架设在一个 JSONL 存储之上——而这个存储 就是防篡改审计链本身。每个命令都接受 --json 以供 agent 使用。

workstate add WORK-1 "Review flagged draft" --note "from obs-4821" --origin observation
workstate add WORK-0 "Capture AI SOAP draft"
workstate link WORK-1 WORK-0            # WORK-1 blocks on WORK-0
workstate ready --json                  # the pull queue (WORK-0; WORK-1 is gated)
workstate transition WORK-0 ready --by scribe --by-kind agent
workstate transition WORK-0 done  --by scribe   # ... after claimed → in_progress
workstate history WORK-1                # the item's transition-provenance chain
workstate verify                        # re-verify the audit chain (exit 1 on tamper)

存储文件（.workstate/state.jsonl）是只追加、可 git diff 的：一个 pull request 会准确显示哪些工作发生了迁移，以及为什么。设置 WORKSTATE_SECRET 即可为链 加密钥（HMAC），从而在没有它的情况下，任何行为都无法被伪造或重排。手工编辑或 重排任何一行，verify 都会报告出来（退出码 1）；加载该存储时也会拒绝它。 尾部截断（丢掉最后几行）通过锚定一个保留的锚点来捕获 （verify --expect-length <n> --expect-head <hash>）——见 docs/DESIGN.md。

它是什么

• 一个带就绪队列的依赖图。 link(a, b) 表示 a 依赖阻塞于 b； ready() 返回没有任何东西在阻塞它的条目——也就是 agent 从中拉取的队列。
• 一个受治理的状态机。 条目在 proposed → ready → claimed → in_progress → done 之间迁移（外加 blocked / failed / cancelled）；只有 合法的迁移才被允许。
• 一条审计链。 每一次状态转移都被铸造为 Evidence 并追加到一条 防篡改链上。verify() 会重新校验它；加密钥（HMAC）模式使得没有 secret 就无法 伪造任何迁移。
• 天生可问责。 每个条目都携带一个 DecisionLink（它的 work-origin——它从哪来），每一次状态转移都携带执行的 Actor 以及任何被引用的 EvidenceRef。

边界（Workstate 不是什么）

这是一个单一职责的仓库。它刻意不是它的邻居们：

• 不是 Experience。 Experience 拥有 causal 的学习 / 信念 / 知识——系统得出了什么结论、以及为什么它可信。 Workstate 只记录 work item 的迁移溯源（transition provenance）——一个 work item 在哪、以及它为何发生状态迁移。不同的对象：知识因果 （knowledge-causality） vs 工作因果（work-causality）。
• 不是 Blackboard。 Blackboard 是共享的认知——agent 们正在共同思考什么（自由格式的共享 记忆）。Workstate 是结构化的工作——存在哪些任务、它们从哪来、处于什么 状态。名词不同：shared state vs work state。 （连“claim”都不同——在 Workstate 里是一个 work item 进入 claimed 态 / 持有资源租约；在 Blackboard 上是认领板上的一条 note，别混。）
• 不是 Runtime。 Runtime 回答 的是针对单个动作的“这个动作该不该执行？”。Workstate 追踪的是跨越多个动作的 工作状态。一个 runtime 决策（或其 Principal）是 Workstate 的一次状态转移所消费的东西——Workstate 从不重新实现那道 门禁。
• 不是 Observe。 一个 Observation 是 WorkItem 回指的起源，而不是 Workstate 所产出的东西。
• 不是一个 issue tracker。 没有项目、冲刺、评论或 UI。它是那些 工具会架设其上的工作状态事实层。

它拥有零第三方依赖：其唯一的运行时依赖是 第一方的 octopus-evidence， 它提供了规范化哈希与防篡改链。与 Runtime 的 Principal 和 Observe 的 Observation 的互操作是类型层面的——不硬依赖 于其中任何一个。

横向对比

octopus-workstate 不是一个更好的 issue tracker、编排引擎或 agent 框架——它是那些工具架设其上的、可验证的工作状态事实层。 在约 20 种工具中（beads、Jira、Linear、Temporal、Airflow、Dagster、LangGraph、 CrewAI……），没有一个同时具备以下三点：一条防篡改的可验证链、 结构化的 work-origin 溯源，以及不信任存储方的独立验证。完整、 坦诚的分析——包括竞品确实领先之处——见 docs/COMPETITIVE.md；价值论证见 docs/ROI.md；架构见 docs/DESIGN.md。

状态

v0.2.0——已成熟：以事件溯源方式架设在一条可验证的 Evidence 链之上，具备 JSONL 持久化、一个 agent CLI、资源租约，以及独立的 verifyAuditTrail() / restore()。以下内容（按设计）延后到一个商业运营层： UI/仪表盘、多租户托管，以及用于尾部截断检测的带外锚点保留。

许可

Apache-2.0 · © Ran Tao · 属于 Octopus Core。