From 7d6c0827dd164bc1329c9779cec8188a4b16b73e Mon Sep 17 00:00:00 2001 From: huangruiteng <14976749+huangruiteng@users.noreply.github.com> Date: Thu, 17 Sep 2026 20:43:09 +0800 Subject: [PATCH] docs(blog): explain LoopX as native Kanban for long-running agents Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com> --- apps/presentation/site/public/blog/blog.css | 2 + .../images/agent-facing-kanban/authority.svg | 44 +++ .../blog/images/agent-facing-kanban/board.svg | 53 ++++ .../blog/images/agent-facing-kanban/lease.svg | 44 +++ .../images/agent-facing-kanban/objects.svg | 46 +++ .../blog/zh/agent-facing-kanban/index.html | 278 ++++++++++++------ .../index.html | 2 +- .../site/public/blog/zh/index.html | 4 +- 8 files changed, 380 insertions(+), 93 deletions(-) create mode 100644 apps/presentation/site/public/blog/images/agent-facing-kanban/authority.svg create mode 100644 apps/presentation/site/public/blog/images/agent-facing-kanban/board.svg create mode 100644 apps/presentation/site/public/blog/images/agent-facing-kanban/lease.svg create mode 100644 apps/presentation/site/public/blog/images/agent-facing-kanban/objects.svg diff --git a/apps/presentation/site/public/blog/blog.css b/apps/presentation/site/public/blog/blog.css index 64b1733c8e..efd7a08934 100644 --- a/apps/presentation/site/public/blog/blog.css +++ b/apps/presentation/site/public/blog/blog.css @@ -174,6 +174,8 @@ caption { text-align: left; font-size: 12px; margin-bottom: 12px; color: var(--b .architecture-viewport img { display: block; width: 100%; height: auto; } .architecture-viewport:focus-visible { outline: 2px solid var(--blue); outline-offset: 3px; } .architecture-hint { display: block; margin-top: 6px; } +/* Keep the foundations diagrams readable in the narrower tablet article column. */ +.kanban-figure a { min-width: 720px; } @media (max-width: 600px) { .architecture-viewport a { min-width: 960px; } } diff --git a/apps/presentation/site/public/blog/images/agent-facing-kanban/authority.svg b/apps/presentation/site/public/blog/images/agent-facing-kanban/authority.svg new file mode 100644 index 0000000000..a70fb420bf --- /dev/null +++ b/apps/presentation/site/public/blog/images/agent-facing-kanban/authority.svg @@ -0,0 +1,44 @@ + +04 Shared Authority State:哪份事实算数 +CLI、前端和 Lark 使用已有入口,经 typed lifecycle owner 校验后读写所选权威来源。未迁移与 canonical 状态分别处理。File、SQLite、PostgreSQL 是各自需要验收的替代选项。下游是回执和只读投影。 + + + + + + + +04 Shared Authority State:哪份事实算数 +入口可以不同;每次写入都必须知道自己服从哪套规则、哪份当前状态。 + +CLI +命令与结构化读回 + +Frontend +看板与详情 + +Lark +消息 / 配置后的适配 + + +Typed lifecycle owner · 接收并验证合法操作 +身份与权限 → 当前版本与前置条件 → 状态提交 / 拒绝 → 操作回执 + + +由 Goal 的 provider 选择与 promotion 状态决定权威来源 +尚未迁移:已有 Markdown / 本地 writer 规则 +Canonical 路径:选中的 provider 承担相应事务 + +File · 分别验收 + +SQLite · 分别验收 + +PostgreSQL · 分别验收 + + +回执与只读投影 · 当前状态 / 看板 / 有界证据时间线 +投影保留来源与身份;provider 失败不悄悄回退成另一个 writer。 +选择 provider 不等于迁移 Goal;三个 provider 是配置选项,不是三个并行主库。 +LOOPX / 看板基础 · 合成示例 + + diff --git a/apps/presentation/site/public/blog/images/agent-facing-kanban/board.svg b/apps/presentation/site/public/blog/images/agent-facing-kanban/board.svg new file mode 100644 index 0000000000..82a7a1bd89 --- /dev/null +++ b/apps/presentation/site/public/blog/images/agent-facing-kanban/board.svg @@ -0,0 +1,53 @@ + +02 用一张板读懂当前局面 +合成看板:集成验证已认领且有运行证据;发布等待有范围的 Gate;实现与评审已有结果。Goal 尚未完成。列是解释性投影,不是持久化状态枚举。 + + + + + + + +02 用一张板读懂当前局面 +Goal · 安全交付批量导出 / 当前还缺:大数据量验证、发布确认 + + + +可以推进 +等待决定 +已有结果 + +C · 集成验证 +负责人:验证 Agent +Claim:已认领 +Lease:有效(本例启用) +运行记录:测试进行中 +下一步:回写结果与证据 + +监控 · 验证任务结果 +到期观察;无变化则安静 + +D · 发布候选版本 +发布 Gate:未确认 +作用范围:发布决定 +前置事实:验收通过 +下一步:满足条件后发布 + +只阻塞匹配的工作 +独立验证仍可继续 + +A · 导出实现 +状态:done · 候选修订 A +证据:权限隔离负例通过 +后继:B 独立评审 + +B · 独立评审 +负责人:评审 Agent +证据:修订 A 评审通过 +后继:C 集成验证 +同一份 Todo,按不同 Agent 的资格和责任呈现。 +列名仅作解释,不是持久化状态枚举。已认领不等于执行中;运行需要自己的证据。 +单张卡片 done,也不等于 Goal 已验收。 +LOOPX / 看板基础 · 合成示例 + + diff --git a/apps/presentation/site/public/blog/images/agent-facing-kanban/lease.svg b/apps/presentation/site/public/blog/images/agent-facing-kanban/lease.svg new file mode 100644 index 0000000000..7367467b3d --- /dev/null +++ b/apps/presentation/site/public/blog/images/agent-facing-kanban/lease.svg @@ -0,0 +1,44 @@ + +03 Claim 与 Lease:从负责到有效执行 +五步时间线:认领、获取租约、续租、到期重新判断、合格接管。续租不改变归属与范围。接管不是到期自动发生,租约只保护接入 fencing 的路径。 + + + + + + + +03 Claim 与 Lease:从负责到有效执行 +Claim 表示责任;Lease 进一步约束执行。以下仅说明已具备相应资格的租约路径。 + + + +1 +认领工作 +Agent A 成为 Todo 的负责人;单凭 claim 不证明进程活着。 + + +2 +取得有效租约 +执行实例 A 持有当前租约:期限、版本、epoch 与限定写入范围。 + + +3 +在到期前续租 +校验持有者与预期版本;推进版本和期限,保留归属与范围。 + + +4 +到期后重新判定 +到期不杀死进程;先检查宽限、准入和恢复条件,再决定是否接管。 + + +5 +合格接管后再执行 +新执行实例使用新的租约身份;旧 epoch 的受保护写入被拒绝。 + +历史回执 ≠ 当前租约 有效租约 ≠ 发布授权 Fencing ≠ 外部效果恰好一次 +继续行动前读取当前事实;外部进程与副作用仍由对应 Runtime 和系统约束。 +LOOPX / 看板基础 · 合成示例 + + diff --git a/apps/presentation/site/public/blog/images/agent-facing-kanban/objects.svg b/apps/presentation/site/public/blog/images/agent-facing-kanban/objects.svg new file mode 100644 index 0000000000..e15b410e61 --- /dev/null +++ b/apps/presentation/site/public/blog/images/agent-facing-kanban/objects.svg @@ -0,0 +1,46 @@ + +01 一张看板,几种不同的问题 +Goal 定义结果与验收,Todo 组织工作。Claim 表示归属,Lease 约束执行,Gate 表示决定,依赖表示前置事实。Evidence 支撑判断,Lane 组织视图,权威状态决定事实。 + + + + + + + +01 一张看板,几种不同的问题 +从结果、工作和约束,读到共同事实。 + +Goal · 交付可用的批量导出 +Acceptance · 大数据量可用,权限隔离通过,发布经过确认 + + +Claim · 谁负责 +开发 Agent 认领实现 +Lease · 哪次执行有效 +可选:期限、版本、写入范围 + +Todo · 一块可交付工作 +实现导出与权限负例 +稳定身份 · 当前状态 · 下一步 +完成后回看 Goal 的验收缺口 + +Gate · 还缺什么决定 +发布前由 Owner 确认 +Dependency · 前置事实 +例如:评审已通过 + + + + +Evidence · 凭什么判断 +修订 A 的测试、评审与产物引用 + +Lane · 当前视角怎样读 +可推进 / 等决定 / 监控到期 / 他人负责 + +Shared Authority State · 共同遵守的权威状态与写入规则 +看板读取并展开这些事实;展示列本身不授予权限。 +LOOPX / 看板基础 · 合成示例 + + diff --git a/apps/presentation/site/public/blog/zh/agent-facing-kanban/index.html b/apps/presentation/site/public/blog/zh/agent-facing-kanban/index.html index 573bbb640a..75ccaa193c 100644 --- a/apps/presentation/site/public/blog/zh/agent-facing-kanban/index.html +++ b/apps/presentation/site/public/blog/zh/agent-facing-kanban/index.html @@ -4,14 +4,14 @@ - 从任务看板到长程协作:Agent-facing Kanban 的四个设计问题 · LoopX - + LoopX:长程 Agent 的原生 Kanban · LoopX + - - + + @@ -27,114 +27,212 @@
← 全部文章 -

长程协作 · 设计实践

-

从任务看板到长程协作:Agent-facing Kanban 的四个设计问题

-

看板不只展示进度,还要让下一位 Agent 知道怎样继续、凭什么完成、什么时候必须停下来。

- +

Agent-native Kanban · 长程协作

+

LoopX:长程 Agent 的原生 Kanban

+

让 Agent 围绕目标认领工作、遵守门禁、提交证据,在同一份权威状态上持续协作。从 Goal、Todo 到 Claim、Lease 与 Lane,读懂 LoopX 的原生看板。

+
-
+
+
-

看板里的隐性知识

-

给几个 Agent 一张共享看板,让它们认领、执行、交付任务,是一种很自然的协作方式。困难出现在工作跨过几个会话之后:卡片还在,接手的 Agent 却不一定知道“待评审”指哪个版本、“完成”还欠哪些验证、“阻塞”究竟禁止了什么。

-

人能从一次会议、一段聊天,甚至对同事的了解中补齐这些区别。Agent 换了会话或执行器,这些隐性知识就容易丢失。于是,看板上的进度看起来连续,实际决策却断了。

-

我的判断是:Agent-facing Kanban 应当是一份可执行的协作契约,而不只是任务状态的展示面。这里的 Kanban 指看板式协作界面,不是对整个 Kanban 方法的重新定义。状态机、依赖、审批和自动化也并非 Agent 时代才有;区别在于,当模型成为持续读写看板的参与者,哪些规则不能再依赖人的默契。

-

此前,我在小红书的长程 Agent 可执行看板图文中,用看板解释了 LoopX 的状态、迁移与恢复。本文沿着这个思路,展开四个设计问题:怎样推进状态,依据什么决策,做完之后怎么办,以及等待时还能做什么。

-

下面用一个构造场景串起来:两位 Agent 协作交付“批量导出”功能,一位开发,一位评审;允许开发和测试,发布需要人确认。它用于解释设计,不是真实客户案例或效果数据。

+

从一个交付场景开始

+

假设你对 Agent 说:“帮我交付批量导出功能。要支持大数据量,不能泄露其他用户的数据;开发、测试和写说明可以继续,正式发布前让我确认。”

+

过一会儿,你最想知道的通常不是模型调用了多少次工具,而是:目标还差什么,谁正在做,哪些工作能继续,哪些必须等,以及凭什么相信已经做完。LoopX 的看板围绕这些问题组织信息。

+

本文用这个构造场景解释完整的基础模型。先读懂一张卡片,再看它如何成为可接手、可恢复的协作过程。最后回到 Agent-facing Kanban 的四个进阶问题。这里的 Kanban 指看板式协作界面,不是对整个 Kanban 方法的重新定义。

+
看板是读懂和操作工作的入口

目标、任务、归属、门禁和证据有各自的身份与规则。看板把它们组织成列、泳道和详情;合法操作由控制面接收和验证。屏幕上的排列方式不会自行变成新的权限或新的事实来源。

-
-

1. Kanban 要提供可执行的 Transition 算子

-

“开发中 → 待评审”看似只是一次卡片移动。真正的交接至少需要回答:交付的是哪个修订,做过哪些验证,评审者要检查什么,以及开发者此后还能否修改这份交付。

-

把这些事都藏在备注里,下一位 Agent 就得重新猜。把它们表达成迁移契约,控制面才能检查前置条件、执行者权限、证据绑定与后继关系,再接受或拒绝这次推进。模型判断下一步怎么走,控制面验证这次变化能否成为共同事实。

-
-

一次交接,不只是移动卡片

-
提出迁移开发 Agent 提交候选修订、验证证据和评审请求。
- -
检查契约身份与范围是否匹配?证据对应当前交付吗?后继是否明确?
- -
-
接受并记录保存迁移结果,关联可接手的评审工作。
-
拒绝并解释返回缺少的证据或失效条件,不伪造进展。
-
-
这是一份设计示意,不是一个跨代码仓库、看板和部署系统的原子事务。
-
-

LoopX 已将 Todo 完成、后继绑定和下一步更新做成生命周期操作,而不是任意字段覆盖;实现可见 Todo Next Action。批量导出的完整评审流程仍需由领域能力组织,不能从这些基础操作推导出“一条通用命令自动完成所有交付”。

-

不必把“开发、评审、发布”这条业务流程硬编码进 Kernel。Kernel 保证身份、权限和合法迁移;上层能力定义不同工作的验收与后继。展示列可以按团队习惯调整,不应因此改写任务的执行状态和授权。

-

还要区分状态迁移与外部副作用。创建远程评审请求后进程崩溃,重试不能仅凭卡片仍在“开发中”就再创建一次。外部动作需要幂等键、结果回查或人工核对;缺少这些保证时,就应显式保留“不确定”,不能声称恰好执行一次。相关恢复边界在总览的 Effect Program 一节展开。

+
+

一张图读懂基本对象

+

这些概念不是一组必须一次填完的表单。先有目标和工作项;协作、风险、并发或恢复需要出现时,再由对应的契约表达它们。一个本地单 Agent Goal 可以很简单,多 Agent 也仍然复用同一套基本对象。

+
LoopX 看板对象关系图:Goal、Todo、Claim、Lease、Gate、Evidence、Lane 与共享权威状态
图 1 · Goal 定义结果,Todo 组织工作;归属、约束与证据回答不同问题,Lane 是这些事实的一种读法。窄屏可横向滚动,点击图片可查看原图。图中均为合成示例。
+
+ + + + + + + + + +
读卡片时,先问每个字段回答什么问题
概念回答的问题批量导出示例
Goal · 目标最终要达成什么,哪些约束不能丢?交付可用、安全、可验证的批量导出。
Acceptance · 验收观察到什么,才能判断结果成立?大数据量、权限隔离和使用路径经过验证。
Todo · 工作项下一块可交付工作或明确等待是什么?实现导出、独立评审、集成验证、发布。
Claim · 认领目前由哪个 Agent 负责?开发 Agent 认领实现,评审者认领评审。
Lease · 租约启用相应模式时,哪次执行在什么期限和范围内有效?一次受控执行的 owner、有效期、版本和写入范围。
Gate · 门禁哪项决定或授权尚缺,具体挡住谁?发布确认挡住发布,不自动挡住独立测试。
Evidence · 证据某个判断依据什么,适用于哪个版本?候选修订 A 的测试结果、评审结论与产物引用。
Lane · 工作通道从当前 Agent 或操作者视角,工作被怎样分组和选择?可推进、到期监控、等待决定、其他人负责。
Shared Authority State · 共享权威状态多人并发时,哪份受规则保护的状态算数?共同认可的 Todo、claim、lease 及相应提交回执。
+

目标决定方向,工作项承载行动,认领表达责任,租约约束执行占用,门禁约束合法性,证据支撑判断。它们互相连接,但不能互相代替。

-
-

2. Agent-facing 看板需要有界的决策上下文

-

把整张看板和全部历史都塞进上下文,并不等于给足信息。工作越多,当前任务的限制越容易被不相关细节淹没。只返回一句“去做下一个任务”,又会让 Agent 看不到依赖、风险和其他可选路线。

-

我更倾向于提供当前任务附近的 Planning Horizon:选中的工作、相关依赖与后继、等待条件、验收缺口,以及少量值得比较的替代工作。摘要应有界,必要时按稳定身份展开原始证据。

-
评审 Agent 接手时,真正需要知道什么?

当前评审对应修订 A;单测已通过,大数据量验证尚缺;开发者正在另一个任务里补验证,不能把它误判为无人负责;修订若变为 B,需要重新确认评审范围;发布仍未授权。

-

LoopX 的 Planning Horizon 投影会沿任务关系选择上下文,并限制条目、关系、验收缺口和文本长度。引用版本的上限分别为 5 个任务、8 条关系和 2 个验收缺口;这些数字是当前实现的边界,不是所有场景的最优配置。

-

有界也意味着可能遗漏。必须让截断可见,并保留继续查证的入口;不能让一个局部投影冒充完整事实。接口是否有效,要看 Agent 能否据此做对决策,而不只是输出变短了多少。

-

这里最容易混淆的是三个层次:可见,不等于可执行;推荐,不等于强制;认领,也不等于获得全部权限。Planning Horizon 是读模型,推荐动作是 Guidance。是否能写入、验收或发布,仍取决于当前 Scope、Gate、Claim/Lease 和其他执行约束。下一位 Agent 能理解别人的任务,不意味着它可以接管别人的任务。

+
+

Goal 与 Todo:目标和当前计划要分开

+

Goal 是控制面的目标边界,有稳定的 goal_id,关联当前状态、工作项、约束和历史。一个 Git 仓库可以承载多个 Goal,一个目标也可以涉及多个仓库。仓库位置不应代替目标身份。

+

Todo 是 Goal 内的一项有身份的工作,使用 todo_id。标题“修一下导出”不够:接手者还需要知道具体行动、验收、依赖、负责人和允许的范围。修改标题不应让它变成另一个任务;方向改变时则应通过替代关系保留来龙去脉。

+
Goal:交付批量导出
+验收:权限隔离正确;大数据量可用;用户能按说明完成导出
+约束:允许开发与验证;正式发布需确认
+
+Todo A:实现导出与基本测试
+Todo B:独立评审候选修订,禁止原作者自审
+Todo C:验证大数据量与权限边界
+Todo D:发布已验收的候选版本,等待发布决定
+

这是解释用的工作记录,不是可直接执行的 CLI payload。A 到 D 是当前计划,不是目标本身:如果评审发现更简单的方案,可以替代部分 Todo;目标和已确认的约束仍须保留。

+

多 Agent 时,per-Agent Vision 补充“这位 peer 当前负责哪个方向、有什么验收与重规划触发条件”。它是有界的执行方向记录,不是另建一个 Goal,也不是把某位 Agent 变成全局管理员。基础模型见 工作图、权限与 Peer 协作。

-
-

3. Task 完成后,要重新判断 Goal

-

一个 PR 合入,不一定意味着批量导出已经交付。还可能缺集成验证、灰度、使用说明或用户验收。把“最后一张卡片完成”直接等同于“目标完成”,就会让长程任务在局部成功处悄悄断线。

-

因此,完成操作除了记录产物和证据,还应该交代后续:创建新的后继,链接已有后继,或者明确说明为什么没有后继。LoopX 的 Todo Contract把这些选择放进显式契约,而不是依赖 Agent 在最终回复里顺口提一句。

-
本次完成:批量导出的实现与单元测试
-交付身份:候选修订 A,以及绑定到 A 的测试记录
-尚缺验收:大数据量集成验证、发布确认
-后继工作:链接已有集成验证任务,不重复创建
-当前边界:可以继续验证;不允许发布
-

上面是解释用记录,不是 CLI Payload。实际调用应读取当前交互契约,遵守写回、消耗结算和完成操作的顺序。

-

如果当前任务链已耗尽,Goal 的验收仍未满足,就需要 Replan:选择新的有效路线,或者记录具体阻塞和恢复条件。LoopX 的重规划结算会把处理绑定到具体任务完成身份或重规划义务,要求真实后继或 No-follow-up 理由,而不是制造只为关闭流程的填充任务。

-

No-follow-up 关闭的是这次局部工作的续接问题,不是自动签发整个 Goal 的验收。同样,Replan 也不是要求 Agent 永远找活干。目标已满足就应停止;权限不足就等待;路线无效就调整。模型和领域验证器仍要判断证据是否足够,控制面不能只凭一段“已完成”的文字替它们证明正确。

+
+

卡片、状态与 Lane:同一份工作,可以有不同读法

+
批量导出示例看板:任务、负责人、租约、发布门禁和验证证据
图 2 · 一张解释用看板。列和泳道是读模型,不对应一套新的持久化枚举;“执行中”需要运行证据,不能只凭 claimed_by 推断。窄屏可横向滚动,点击图片可查看原图。图中均为合成示例。
+

卡片正面适合放工作名称、优先级、负责人、关键等待、最新证据和下一步。完整依赖、历史、租约详情与失败原因放进详情。这样,人能快速判断,Agent 又能沿稳定身份展开事实。

+

不要把三种“分组”混为一谈:生命周期状态说明 Todo 是 open、blocked、deferred 或 done;工作类型说明它是推进、监控、门禁还是提醒;Lane则是面向某位执行者的分组、候选集合或调度路径。“开发中”“待评审”可以是领域展示列,不必成为 Kernel 的通用状态。被替代则通过 supersede 操作与 superseded_by 等关系记录,不额外创造一个通用状态枚举。

+
+ + + + + +
常见 task_class:类型决定路由,不靠标题猜测
工作类型用途关键区别
advancement_task实现、研究、验证、文档或修复。应产出可验证的结果,不限于写代码。
continuous_monitor按条件或节奏观察外部变化。没有实质变化时保持安静,不把轮询次数当交付。
user_gate等待一项会阻塞相关工作的决定。必须明确范围,不能只写“等用户”。
user_action提醒人处理一项事情。提醒本身不授予权限,也不自动阻塞工作。
blocker记录缺少的执行条件及恢复路径。未必需要人来解决,例如等待测试环境恢复。
+

同一张“独立评审”卡片,对开发 Agent 可能是“可见,但被排除执行”;对评审 Agent 才是“可认领”。被别人认领的工作仍可作为上下文出现,却不能因此被当前 Agent 接管。claimed_by、excluded_agents、依赖、能力、门禁和当前预算会共同影响执行候选。

+

因此,open 不等于 runnable,优先级高不等于能越过 Gate,出现在看板里也不等于当前 Agent 可以执行。Quota/scheduler 依据这些事实生成当前路由;可执行义务与建议分别由返回的契约说明。图与 Planning Horizon 负责帮助理解,不是第二个调度器。

+
+ +
+

Claim 与 Lease:责任归属和执行占用不是一回事

+

Claim:谁负责这张卡

+

Claim 通常体现在 Todo 的 claimed_by。它让其他 Agent 知道工作已经有人负责,也让状态写回能够检查行动者。它是软归属:不证明进程仍活着、不证明 Host 已绑定,也不是绕过权限的通行证。

+

普通生命周期操作要遵守当前 owner 与授权规则;必要的跨 owner 完成、重分配或替代,需要已有契约允许的明确委托。一个 Agent 被称为“管家”或“协调者”,不会自动获得修改所有 Todo 的权力。

+

Lease:哪次执行当前仍然有效

+

当 Goal 选择了相应的 hard-lease 协作模式,租约可进一步携带执行实例身份、TTL、版本和写入范围。续租要证明仍是合法持有者且版本匹配;到期、失效或旧版本不能被当作当前执行权。支持的操作还取决于所选 provider 和已经完成的迁移阶段。

+

读租约时,TTL 是有效时长,version 用于识别当前修订;epoch 可理解为一次执行占用的代次,用来分辨新旧执行者。Fencing 是写入前的校验:过期或失去资格的执行者,即使仍在运行,也不能凭旧身份提交受保护的写入。

+
Claim 与 Lease 的时间线:归属、有效租约、续租、失效和旧执行者的写入拒绝
图 3 · 已启用并通过相应恢复资格的租约路径。版本/epoch 的具体字段由所选契约定义;重新分配必须经过当前准入、宽限与恢复检查。租约到期本身不会杀死旧进程。窄屏可横向滚动,点击图片可查看原图。图中均为合成示例。
+

当前 quota 不会自动消费 hard lease;是否采用租约,要看实际 Host 与执行路径的接入。可以有 claim 而没有 hard lease;也可以有有效 lease,却因为发布 Gate、能力缺失或预算边界而不能执行。租约只约束被接入这套 fencing 的路径,不能替所有外部系统提供“恰好执行一次”。旧执行器的停止与新执行器的启动,还需要对应 Runtime 的监督与恢复机制。

+

一个易错点是把“重放成功”看作“仍有权限”。幂等重放返回的是原操作的历史结果,不会自动续期。继续写入前要读取当前租约。现有 canonical lease renew 已明确支持 promoted 本地 File/SQLite 的续租;这不等于每个 provider 的 transfer、release、reclaim 和完整 Actor 生命周期都已经合格。

-

4. Blocked 和 Human-in-the-loop 要有作用范围

-

“发布前等我确认”应该阻塞发布,不应自动阻塞已经授权的测试、分析和文档。某位 Worker 等待外部验证,也不代表整个 Board 都必须停止。

-

如果系统只有一个全局 Blocked 开关,会出现两种相反的错误:过度停止,浪费仍可推进的时间;或者为了继续干活,干脆忽略人的限制。解决办法不是调一个更激进的 Prompt,而是明确等待约束的作用范围。

-
- - - - - - - -
同一个目标可以同时存在的状态
工作当前状态允许的下一步
发布候选版本等待 Owner 确认准备决策所需证据,不执行发布
大数据量验证已授权,环境可用在既定预算内执行并回写结果
使用说明依赖接口稳定接口未确认时等待;确认后重新检查执行条件
-

LoopX 的 Decision Scope 契约区分不同范围的决策。Scoped Gate 的行为测试也覆盖了“提示一个需要人处理的问题,同时推进不受它阻塞的已选后继”。这不意味着所有 Gate 都局部生效:如果 Owner 明确暂停整个 Goal,它就应约束整个 Goal。

-

等待还需要恢复条件。测试结果返回、候选修订变化、审批到达,都是可以重新检查的事件。定时唤醒本身不是新证据,曾经批准过也不代表当前仍然有效。恢复的第一步是重新检查准入条件,而不是直接执行上次记住的命令。如果权限已经撤回,即便等待的结果到了,也不能越过新的边界。

+

Gate 与依赖:准确地等,也准确地继续

+

依赖回答“事实是否已经成立”,Gate 回答“相关决定或授权是否已经具备”。测试环境未恢复、上游产物未到达,不一定需要人批准;发布需要确认,也不能靠多跑几轮监控来代替授权。

+

Gate 必须有作用范围。只阻塞一位 Agent 的决定,用对应 lane scope;只影响某项动作时,用具体 Todo 关联或 typed decision scope。真正暂停整个 Goal 才使用显式 global gate。goal-bound 这样的续接绑定并不自动代表全局阻塞。

+
“发布前让我确认”怎样落到看板上?

发布 Todo 关联 production 决定;集成验证和说明文档若独立、已授权且其他条件满足,可以继续。把发布卡拖到“准备好”不会消费 Gate,用户的一句普通回复也不能被任意解释成发布批准。

+

同样要分清 dependency、successor 与 supersede。依赖是前置条件;successor 说明谁承接后续,不自动等于“必须等前项完成”;supersede 表示旧路线被新路线取代,不应把失效工作伪装成成功。等待条件可以绑定 Todo 完成、Monitor 的实质变化或其他支持的事件。

+

恢复时重新检查当前条件:修订可能变了,授权可能撤销,产物可能失效。相关规则见 Decision Scope、Todo Contract 和 任务关系投影。

+
+ +
+

Evidence:让“做完了”成为可以检查的判断

+

看板上的“完成”需要能展开理由。先区分三个东西:Artifact 是交付物,Evidence 是判断依据,Receipt 是某次操作被接受或观察到的记录。一份导出文件是产物;权限测试及样本核对是证据;“发布请求已提交”的回执只说明那个动作发生过。

+
+ + + + + +
一条有用的证据,至少让接手者能回答这些问题
问题示例
验证对象是谁?候选修订 A、对应 Todo 与这次执行。
做了哪种检查?权限隔离负例、大数据量集成测试、独立评审。
结论和边界是什么?通过、失败、未验证分别记录,写明适用输入与环境。
怎样展开与复核?有权限的产物引用、运行记录、准确版本或摘要。
什么变化会使它过期?代码、输入、依赖或授权发生了影响结论的变化。
+

“摘要里有一个 hash”“测试命令返回了 0”“Agent 发来一条消息”,各自能证明的事情有限。证据是否足以满足验收,需要领域验证和必要的独立判断;控制面负责保存身份、范围、结果与关系,不替人或验证器发明正确性。

+

在共享看板里放有权限的简要引用,原始日志、用户数据和私有文档留在授权的存储中。拥有一个引用不等于读过内容,收到材料不等于采纳,能读证据不等于能执行动作。Agent-scoped evidence ledger 提供有界的时间线与其他 Agent 的压缩 frontier,不是第二份任务数据库。

+
+ +
+

Shared Authority State:让所有参与者知道哪份状态算数

+

当两个 Agent 同时读取“无人认领”,或一位 Agent 在另一个 Host 上拿着旧状态返回,仅靠共享一张表不够。系统必须知道:谁有权提交、基于哪个版本、冲突时谁失败、操作已提交但响应丢失后如何恢复。

+

Shared Authority State 指共同遵守的权威状态与写入边界。它不要求把一切都塞进一个大数据库。Todo/claim/lease 的相应聚合有自己的 owner;Goal 意图、请求和返回、外部副作用也保留各自事务边界。跨边界通过明确关系和回执对账,不假装存在一个包住所有系统的事务。

+
共享权威状态分层图:入口、规则 owner、所选状态来源、回执与只读投影
图 4 · 多种入口读取同一套规则约束下的事实;具体来源由 Goal 当前的选择与 promotion 状态决定。图中的三个 provider 是不同配置选项,不是三个同时写入的主库。窄屏可横向滚动,点击图片可查看原图。图中均为合成示例。
+

共同事实,按版本提交

+

在已经支持的 canonical transaction 路径中,提交携带预期 revision。比较并交换(CAS)检查“我读取之后,有没有人先改过”;提交结果绑定事件与原操作回执。竞争者不能因为也看过旧卡片就覆盖新 owner。Lost response 则通过原操作身份恢复,而不是盲目执行第二次。

+

本地默认、provider 选择与 promotion 要分别读

+

LoopX 同时保留 legacy 路径和逐步迁移的 provider(状态提供方)路径。Promotion 指把某个 Goal 的权威来源正式迁移到选中的 canonical provider。未迁移的 Goal 仍遵守已有 Markdown/本地 writer 的权威规则;provider-first 调用没有 selector 时选择 File profile。选择 File、SQLite 或 PostgreSQL 的 provider,并不等于已迁移一个 Goal,更不等于自动获得跨主机写权限。

+

File/SQLite 已有具体事务和真实后端验证;SQLite 的完整连续运行资格、默认切换与 owner promotion 仍是单独边界。PostgreSQL 有 provider/service 接入契约及测试基础,认证服务、租户隔离、网络故障和跨主机运行要按对应 profile 验收。不能把“代码里有实现”直接写成“任意部署都已 ready”。

+

迁移后,所选 canonical provider 读空就按空处理,失败就明确报告;不能悄悄回退到旧 Markdown 或旧 lease 文件继续写。Markdown 仍可以作为可读投影保留,UI、缓存和同步到外部看板的行也仍是投影。更详细的来源边界见 Local Authority Provider 选择 与 Shared Authority RFC。

+
+ +
+

把这些对象串成一次完整协作

+
    +
  1. 明确结果。Owner 提交批量导出的 Goal、验收和发布约束。工作被拆成有身份的 Todo;评审与实现的责任边界明确。
  2. +
  3. 选择并认领。开发 Agent 读取当前可执行候选、认领实现工作。若所选模式要求 lease,再取得有效执行占用。Claim 成功后仍需检查环境、能力和授权。
  4. +
  5. 执行并回写。实现产生候选修订与测试证据。失败或部分成功如实记录;一次 Turn 结束不自动代表 Todo 完成。
  6. +
  7. 接手与验证。后继评审绑定候选身份和验收。评审者通过自己的准入与认领路径接手,读取产物并形成结论。登记接收者、投递消息和真实接手,是三个不同的事实。
  8. +
  9. 处理等待。集成验证可继续;发布 Gate 只约束匹配的工作。若修订变化,旧评审不直接用于新候选,相关验证需要重新确认。
  10. +
  11. 验收与返回。满足约定验收、得到必要发布授权后,按对应领域流程交付并回读结果。还有缺口就链接已有后继或重规划;完成结论要返回原来的受众。
  12. +
+

这条路径展示的是各个能力如何配合,不表示当前存在一条“一键完成全部协作”的通用命令。Frontend、Lark、CLI 和实际 Runtime 的入口、接手与结果返回,必须逐条验证;注册人数也不能代替实际运行与验收。

+
+ +
+

怎样实际读一张 LoopX 看板

+

日常查看时,按这个顺序就够:先看 Goal 的验收缺口,再看当前 Agent 的工作通道;打开选中 Todo,确认 owner、依赖与 Gate;需要并发执行约束时查看 lease;最后展开证据和下一步。发现信息不完整,沿稳定身份查详情,不从“没显示”推断“不存在”。

+

下面是已连接 Goal 的查询入口。将占位符替换成真实、已注册的身份;源码开发从相应 worktree 使用 uv run --extra test loopx …,安装版直接使用 loopx。

+
# 当前目标与可展开的工作图
+loopx --format json status --goal-id <goal-id> --include-task-graph
+
+# 当前 Agent 视角的任务;任务身份不等于显示顺序
+loopx --format json todo list --goal-id <goal-id> --role agent --agent-id <agent-id>
+
+# 某个工作项的当前租约事实
+loopx --format json task-lease inspect --goal-id <goal-id> --todo-id <todo-id>
+
+# 当前 Agent 可见的有界证据时间线
+loopx --format json evidence-log --goal-id <goal-id> --agent-id <agent-id> --thin --limit 20
+

写操作通过当前 Todo、Gate、claim/lease 与运行契约提供的生命周期入口完成,不靠改展示列或拼一段状态文本。需要什么参数、是否要执行实例身份,以及当前能否继续,读取当前命令帮助和返回的动作契约。

+

CLI 与本地前端提供不同粒度的操作与读面;Lark 也有相应消息、目标通道和 Base 看板适配,但不能因此宣称所有界面字段和动作已完全等价。Lark Kanban adapter 目前仍标明 prototype contract:同步和触发需要配置,外部看板不自行创造另一套任务身份。

+
+ +
+

进阶一:状态迁移要成为可执行的契约

+

基础对象齐全之后,“开发中 → 待评审”就不只是一次卡片移动了。它需要说明交付修订、证据、评审工作和此后的修改边界。模型提出下一步,控制面检查身份、前置条件和相应权限,再记录接受或拒绝的结果。

+

LoopX 已将 Todo 完成、后继绑定和下一步更新组织成生命周期操作,见 Todo Next Action。业务上的“开发、评审、发布”由领域能力组织;不必把所有项目的业务列硬编码进 Kernel。

+

请求提交、执行成功、状态提交和用户收到结果仍是不同阶段。一次操作完成时,应能回答“现在共同事实是什么,下一位参与者怎样接手”,而不只增加一条活动记录。

+
+ +
+

进阶二:给 Agent 有界、可展开的决策上下文

+

把全看板和全部历史塞给模型,可能淹没当前限制;只返回“做下一项”,又丢失依赖和替代路线。Planning Horizon 提供当前任务附近的工作、关系、等待、验收缺口和少量可比较选项。

+

LoopX 的 Planning Horizon 是有界读模型。读模型要披露覆盖和截断,并允许按身份展开;它不应通过摘要顺序偷偷改变权限,也不能把局部视野当成全局状态。

+

评审者需要的是:“评审修订 A,当前测试通过但大数据量证据尚缺,开发者正在补验证,发布未授权。”这比完整聊天记录更贴近决策。建议仍是建议;机器要求的执行义务要在契约里明确表达。

+
+ +
+

进阶三:Todo 做完后,重新判断 Goal

+

PR 合并可能只完成实现,不代表用户已能使用批量导出。局部完成时,应明确链接后继、创建真正需要的新工作,或说明为什么无需后继;方向改变则保留替代关系。

+

任务链耗尽而验收仍未满足,需要 Replan;验收成立则应停止。LoopX 的 重规划结算 把写回绑定到具体完成身份或义务,不把“补一个只用于关闭流程的任务”当作进展。

+

No-follow-up 关闭的是当前续接问题,不是自动签发整个 Goal 的验收。消息被采纳、lease 被释放、Todo 被标记 done,也分别只证明对应那一层发生了变化。

-

把边界留在正确的层

-

这四点并不要求 Runtime 长出一套完整的看板产品。我的划分是:Runtime/Harness 提供执行、工具调用和会话能力;控制面维护持久身份、权限、迁移与结算;领域能力和模型定义工作路线、验证方式与后继;看板把它们投影成适合人与 Agent 使用的界面。

-

跨层接口要能表达“提议—验证—接受/拒绝—接手”,而不是让展示面绕过权限直接改事实,或让 Kernel 接管全部业务推理。对 LoopX 来说,Kanban 是语义控制面的一种工作形态,不是它唯一的 UI,也不是一套固定的多 Agent 组织结构。

-

人负责定义目标、关键取舍和授权;Agent 在边界内自主选择并推进工作。好的控制面应减少重复解释,而不是把所有人和模型都变成填写表单的操作员。

+

进阶四:跨层恢复时,保留事实与边界

+

Runtime/Harness 提供执行和会话;控制面维护身份、状态与合法迁移;领域能力和模型组织路线与验收;看板把结果呈现给人和 Agent。好的接口让它们协作,不让任一层偷偷替其他层做主。

+

如果远端动作已发生而本地响应丢失,状态仍显示“待处理”不代表动作没做。应按既有幂等身份、回执和结果查询恢复;缺少确定证据时保留“不确定”。Lease 到期不会撤销已经发生的外部动作,重试也不能一概视作安全。

+

Shared authority 可以保护它自己负责的提交;跨代码仓库、发布系统和消息通道的流程仍需各自的效果与对账契约。完整分层与 Effect Program 见《从一次性 Agent 到长程控制面》。

-

怎样检验这套设计

-

我更愿意用几个故障场景检查设计,而不是只看正常流程能否跑通:

+

怎样判断看板真的帮助了协作

    -
  • 交付版本变了:旧评审结果能否被误用到新修订?
  • -
  • 交接中断了:接手者能否识别已完成的外部动作与尚未完成的状态写回,避免盲目重复?
  • -
  • 卡片清空了:系统能否发现仍未满足的验收,而不是直接宣布 Goal 完成?
  • -
  • 发布在等人:其他已授权工作能否继续,同时确实不越过发布边界?
  • -
  • 上下文截断了:Agent 能否发现缺口并查证,而不是把局部可见当成全局完备?
  • +
  • 两人同时认领:是否能确认谁成功,谁需要重新读取,而不是双方都以为自己有执行权?
  • +
  • 旧执行者返回:已过期的租约、版本或来源能否被误用?未接入 fencing 的外部动作是否被明确标出?
  • +
  • 评审版本变化:旧证据会不会被当成新版本已验证?
  • +
  • 发布等待确认:Gate 是否挡住发布,同时允许独立且已授权的验证继续?
  • +
  • 卡片完成或被替代:能否读回产物、验收缺口、后继和变更原因?
  • +
  • 权威来源不可用:会不会偷偷回退到旧文件,产生两个 writer?
  • +
  • 看板或历史被截断:能否发现还有未展示的工作,而不是错误宣布 Goal 完成?
-

这些是验证问题,不是宣称 LoopX 已在所有 Host 和场景下完全解决。本文引用的是可检查的代码、契约和测试;它们不替代生产环境验证,也不直接证明多 Agent 相比单 Agent 更省钱或更准确。还应测量任务验收率、重复执行、无效重规划、人工介入次数,以及每次有效交付的时间和成本。

-

任务看板解决“工作放在哪里”。长程协作还要解决“换一个 Agent,工作能否带着正确的理由、证据和边界继续”。这四个问题,就是我认为 Agent-facing Kanban 值得认真设计的部分。

-

关于 LoopX 更完整的分层、恢复与协作模型,见《从一次性 Agent 到长程控制面》。

-

实现依据固定到公开仓库修订 4f33d5ac6。示例中的业务流程是设计说明,不是生产落地承诺。

+

这也是阅读能力状态的方法:把已发布的基础契约、可选模式、具体 provider 的已验证操作,以及仍需端到端验收的产品路径分开。本文固定到公开修订;相应版本的命令 readback 和 qualification 证据,决定某个部署能做什么。

+

一张有用的 LoopX 看板,应让人和接手的 Agent 一起回答:我们要到哪里,现在谁负责,什么可以继续,什么必须等待,依据是什么,下一步怎样被验证。基础对象提供共同语言,长程协作让这套语言跨过会话、中断和方向变化仍然有效。

+

实现与文档依据固定到 a96c9aa91。四张图与批量导出场景均为解释性合成示例,不是生产截图或效果数据。本文不宣称全部 Host、provider 与产品入口已经完成同等资格验证。

diff --git a/apps/presentation/site/public/blog/zh/from-one-shot-agents-to-long-horizon-control/index.html b/apps/presentation/site/public/blog/zh/from-one-shot-agents-to-long-horizon-control/index.html index b88da077a2..fda64a202a 100644 --- a/apps/presentation/site/public/blog/zh/from-one-shot-agents-to-long-horizon-control/index.html +++ b/apps/presentation/site/public/blog/zh/from-one-shot-agents-to-long-horizon-control/index.html @@ -129,7 +129,7 @@

3. 外置状态,可重建的展示面

4. 帮助 Agent 在合法空间内决定下一步的 CLI

可以把 LoopX 直观理解为一张可执行 Kanban。卡片有稳定身份、依赖、Claim、Scope、Evidence 和 Successor。移动卡片意味着申请一次可验证的状态迁移,看板展示的是这份契约。

-

Agent-facing Kanban 还需要回答四个问题:状态怎样合法推进,Agent 依据什么有界上下文决策,Task 做完后怎样重新判断 Goal,以及某条路径等待时其他工作能否继续。它们决定了看板能否成为可接手的协作契约,而不仅是进度展示。具体实践见《从任务看板到长程协作:Agent-facing Kanban 的四个设计问题》。

+

Agent-facing Kanban 还需要回答四个问题:状态怎样合法推进,Agent 依据什么有界上下文决策,Task 做完后怎样重新判断 Goal,以及某条路径等待时其他工作能否继续。它们决定了看板能否成为可接手的协作契约,而不仅是进度展示。具体实践见《LoopX:长程 Agent 的原生 Kanban》。

它帮助 Agent 在合法空间内决定下一步,而不是给出一条不可偏离的唯一路线。next_cli_actions、推荐路线和 Planning Horizon 是 Guidance;只有由 Typed Contract 执行的权限、Gate、Quota、Claim、Lease 与验收边界,才是 Hard Boundary。

CLI 将工作连续性写进交互。完成任务时,可以创建后继、链接已有后继,或在验收满足后记录结构化 No-follow-up 理由。这样,一次局部成功不会让更大的任务链断线。具体规则见 Todo Contract。

Interaction Contract 分开表达“人需要听到什么”和“Agent 必须做什么”。通知通道可以安静,同时要求 Agent 执行一段有界工作。反过来,状态要求等待时,调度器唤醒也可以合法地不产生工作。

diff --git a/apps/presentation/site/public/blog/zh/index.html b/apps/presentation/site/public/blog/zh/index.html index 8d4aee007e..757a4c43dd 100644 --- a/apps/presentation/site/public/blog/zh/index.html +++ b/apps/presentation/site/public/blog/zh/index.html @@ -33,8 +33,8 @@

LoopX · 博客

长程工作的工程实践。

关于长程 Agent 的设计、工程与实践。

-

长程协作 · 设计实践

2026 年 9 月 15 日

-

从任务看板到长程协作:Agent-facing Kanban 的四个设计问题

从 LoopX 的实践看可执行迁移、有界决策上下文、任务完成后的目标对齐,以及有作用范围的等待与人工介入。

阅读全文
+

Agent-native Kanban · 长程协作

2026 年 9 月 15 日

+

LoopX:长程 Agent 的原生 Kanban

用四张图理解 Goal、Todo、认领、租约、门禁、证据与共享权威状态,再看它们如何支持长程协作。

阅读全文

架构 · 设计笔记

2026 年 9 月