企业官网建设流程全解析

Maka WorkHub 协调会话架构解析：给 Session 加一个角色，而不是再造一套系统

【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka

Maka 的 WorkHub 要当一个持久的协调入口，却不许拥有第二套数据库、事件存储或转录基座。这篇架构解析讲清它如何把协调会话挂进既有 Session 基座：谁对什么事实负责、一次委派怎么写进存储、崩溃之后如何恢复、模型输出在哪里被拦下。

一个持久协调者，为什么不能自带存储

WorkHub 的设定是"每个 Runtime Host 一个持久会话"：普通提问、澄清、延续旧工作、创建新工作都从这里开始。R2.4 只交付了确定性的路由与上下文延续基线，并没有持久化对话能力。要补齐这块，最省事的做法是给 WorkHub 单建一套存储和转录基座——ADR 的第一条约束就是否定它：

绝不产生第二个 WorkHub 数据库、事件存储、转录基座，或与 Session 并行的生命周期权威。

理由不是省事，而是权威必须唯一。执行转录、工件、恢复、归档/删除这些事实的归属方只能是普通 Session 那一侧；协调对话的归属方只能是协调会话本身。两套存储并立之后，崩溃恢复、状态一致性、权限边界全部要重新做一遍。

约束还包含一条按 Host 的隔离原则：一个协调会话只协调同一 Runtime Host 下的普通 Session。切换 Host 就是换另一个协调会话，不存在全局协调会话，也没有跨 Host 协调。这个边界在用户切换 Host 时会割裂连续性，但 ADR 认为这比引入一个跨 Host 的单一权威便宜得多。

特殊角色：把协调会话塞回既有 Session 基座

方案的核心只有一句话：每个 Runtime Host 持有一个稳定的协调会话（Coordination Session），它是既有 Session 的一个特殊角色，不是新实体。首次需要时惰性创建，Host 或应用重启后解析回同一个 Session。

源码里这个角色被显式保留下来，见packages/core/src/session.ts（L88-L96）：

export const WORKHUB_COORDINATION_SESSION_ROLE = 'workhub_coordination' as const; export const WORKHUB_COORDINATION_SESSION_ID = 'maka_workhub_coordination' as const; export function isWorkHubCoordinationSessionId(sessionId: string): boolean { return sessionId === WORKHUB_COORDINATION_SESSION_ID; }

SessionHeader上的role字段缺省即普通 Session；注释特意说明特殊角色仍驻留在同一 Session 基座上。Session 的工具配置清单里另有workhub-coordination-v1与workhub-coordination-v2两个配置——协调会话复用的就是现有 Session 执行通道，只是叠加了专门的工具面。

这个特殊角色还背着一组"负面义务"：对普通 Session 列表隐藏；被排除在所有路由候选集之外。自我路由的拒绝只是纵深防御，不能替代"从普通导航与目标发现中结构性排除"这件事。

权威分账：意图不等于授权

ADR 最值钱的是一张权威分账表，这里改成三组要点：

• 协调对话——用户在 WorkHub 发的消息、问答、澄清、协调决策、有界委派引用、协调摘要——归当前 Host 的协调会话。
• 执行——具体运行、项目与文件范围、模型与权限模式、根 Turn 准入、工具、工件、恢复、归档/删除，以及权威执行转录——归目标普通 Session。
• WorkHub 卡片、过滤器、状态摘要、导航辅助——没有持久化权威，全部是从 Session 事实可重建的投影。

由此有两条铁律：协调会话永远拿不到对普通 Session 执行或生命周期的权威；意图（intent）只描述用户想要什么，选择权威的是确定性的准入机制，不是意图。

路由四处置、链接三操作，以及模型能看什么

每条普通路由输入最终解析为恰好一个提议的处置：answer_here（就地回答）、delegate_existing（委派给有界且有效的既有 Session）、create_new（先建再委派）、clarify（继续澄清，不猜目标、不建 Session）。纠正、停止、恢复则不是第五种处置，而是作用于既有持久委派的链接操作：纠正的替换目标只能是delegate_existing或显式create_new；停止与恢复沿"委派 → Session → Turn"的持久谱系走，不靠名称相似的 Session 猜。

流程长这样：

user input -> intent analysis -> Session Resolver / linked-target resolution -> Coordination policy（建议性提案） -> 确定性 Action Gate（唯一写入关卡） -> owning Host / Session

Session Resolver 只返回有界的既有证据，绝不创建 Session；链接目标解析从 WorkHub 持有的委派出发，沿持久谱系推进，缺失、过期或歧义一律失败关闭。所有模型输出都只是建议。

可选的模型路由适配器分两阶段，边界由packages/core/src/workhub-routing.ts（L44-L59）的常量锁死：

export const WORKHUB_ROUTING_MAX_TRANSCRIPT_MESSAGES = 8; export const WORKHUB_ROUTING_MAX_CANDIDATES = 32;

Intent 模型只看到当前请求和至多 8 条有界转录消息，看不到任何候选，系统提示明令"Intent 不得选择 Session"。Recall 模型仅在execute和普通continue时第二次被调用，最多看 32 个候选，每个候选只有请求作用域内的不透明引用、有界名称、状态与新旧分桶；稳定的 Session 身份、路径、文件内容、工具与能力一概不传。模型输出无效、提供方失败、候选不可用、召回为空、结果歧义，全部失败关闭到clarify——任何情况都不隐含create_new。

适配器装上之后，结果挂在根 Turn 准入上供恢复复用；每个新根（含排队的跟进与待处理消息恢复）都有独立决策。改变操作、候选集或候选引用的副作用提案，在 Action Gate 之前就被拒绝。生产默认值若要变，必须走仓库既有的maka evalExperiment/Cell/Attempt/Result 路径比较评估，并分别报告 Intent 准确率、召回类型准确率、Recall@K、MRR、不安全绑定、隐式创建、不必要澄清、延迟、Token 用量与成本——刻意不另建 WorkHub 专用评估框架。

准入、幂等与破坏性操作：确定性关卡的全部规矩

packages/runtime-host/src/server/workhub-coordination-action-gate.ts（L285-L291）里的WorkHubCoordinationActionGate是策略提案与 Session 副作用之间唯一的准入模块。它校验：Host 与目标有效性、归档与等待状态、自我路由排除、显式create_new、既有工具与权限上限。提案只携带不透明的candidateRef——模型选出的 Session id 无法直接变成写入，这就是"候选发现与执行共用同一接口"要防的事。

替换（replacement）的门槛更高：可信用户文本里必须有显式纠正证据、按协调转录顺序声明源委派、拒绝任何后来的竞争性替换意图。Gate 还实现了基于动作指纹的幂等重放：同一actionId携带不同请求指纹时以action_conflict拒绝，相同指纹则返回已缓存的重放结果。重试同一动作不会执行两次。

直接停止采用第一索赔胜出：先问 Host"该 Session 上哪些委派仍持有可停止的工作"，提案只带解析出的不透明委派身份及其所属 Session，显示名只是检索证据，永不进入准入。Gate 在任何效果之前重验三件事——分配仍存在、仍属于被提议的 Session、没有其他委派仍持有可停止的工作。可信用户文本必须携带直接停止命令，user_stop确认保持在策略输出之外。持久化形式是两笔记录：退役前落delegation_stop_requested声明，退役后落delegation_stop_resolved观察；待处理取消墓碑保留破坏性动作身份，两条记录之间崩溃仍保持cancelled_pending。根 Turn 的停止用动作派生的中止源，恢复时不会把普通 Session 停止误认为 WorkHub 投递。

所有持久 WorkHub 记录按"它关于什么"键控——分配按动作键控，停止与替换按委派键控——因此没有任何单条记录能看到跨到第二个委派的同一动作身份。在一个相同协调准入下、任何效果之前单独取得的持久动作声明就是全局所有者：精确重放收敛于它，身份复用（含已拒绝或恢复中的尝试、跨 Host 重启）在效果之前失败关闭。声明不携带 Session 外键，因为已提交的破坏性声明必须比目标移除更长寿；目标 Session 消失时，让停止到达终结解析的是它的移除墓碑，而不是仅仅不可读的目标。

原子提交、可重建投影与崩溃接缝

委派链接链接转录，不复制转录。一次委派只在协调转录与执行转录之间持久化一个有界链接：

delegationId coordinationTurnId targetSessionId / targetMessageId / targetTurnId disposition

提交发生在一次runtime.sqlite事务里：协调会话的delegation_assigned记录与目标待处理消息准入同时落盘，create_new时目标 Session 元数据也在同一事务中创建。事务就是用户可见的分配边界——提交前两个 Session 都看不到工作，提交后链接与目标输入同时存在，唤醒或继续内存执行器只发生在提交之后。Host 在提交与唤醒之间崩溃，由普通待处理消息恢复接管；WorkHub 不拥有第二个恢复状态机或补偿链。delegation_assigned记录本身即投影出可见的 WorkHub Turn，渲染器不追加第二条摘要。消息 schema 见packages/core/src/session.ts（L1014-L1030）的WorkHubDelegationAssignedMessage，协议层操作（workhub.coordination.actFromTurn、workhub.coordination.selectAndDelegate）见packages/runtime-host/src/protocol/workhub-coordination.ts（L249-L348）。

混合第一响应契约把"确认"与"状态"拆开：delegation_assigned是即时的持久确认，不必等目标执行；目标 Message 是稳定的委派身份，targetTurnId只记录准入位置。执行状态是向目标权威查询后投影出来的running、waiting_for_user、completed、failed、aborted——未消费的转向消息被折叠进后继 Turn、恢复把多个待处理消息聚合进一个新 Turn，投影都仍然正确；持久的取消墓碑能把撤回的排队消息解析为aborted；目标权威暂时不可读时投影为recovering，不虚构终结结果。这些状态从不作为可变协调记录追加，Session 变更通知使投影失效，重启后从同一链接与目标事实重建。

破坏性操作的恢复契约同样按接缝切分。纠正走两段式退役：先持久化对源委派身份唯一的delegation_replacement_requested，再让目标 Session 的普通消息权威取消确切的仍待处理委派消息，或解析该消息如何进入执行 Turn——根 Turn 可以停，既有的用户 Turn 只是消费过转向消息则属于共享权威，必须保持运行。替换分配与旧链接的delegation_superseded证明原子提交；重试同一动作恢复的正是"退役/停止之后、替换分配之前"的崩溃接缝。替换指纹绑定已解析的稳定目标 Session id 而非临时候选引用，元数据刷新不改变动作身份。目标在破坏性退役边界后变为归档、不可用或等待状态时，协调侧追加delegation_replacement_aborted终结事实，重试返回同样的终结结果。

目标选择是独立于前准入模型路由的交互能力：默认协调模型在候选发现后可调用tasks.select_and_delegate，Host 用既有交互权威发布一个持久 Form，接受一个确切的不透明选项，把绑定的 Session/工作区传给 Action Gate（协议侧即workhub.coordination.selectAndDelegate，支持candidate_set_stale错误，候选集 id 必须匹配sha256:[a-f0-9]{64}，上限 32 项）。时序语义值得记住：协调 Turn 在等待期间已准入，只有后续 Gate 与目标准入才启动委派执行；操作在等待后重读活动 Run 权威，保留原始已准入的用户内容，永不重写既有路由决策；渲染器重载重新查询待处理交互，取消/停止关闭它，Host 恢复关闭孤儿延续；旧的answer -> targetSelection -> answer前准入协议与渲染器 Promise 已被移除，而不是保留为第二个选择实现。

代价、未决问题与再评估触发点

按 Host 的边界在切换 Runtime Host 时会割裂 WorkHub 连续性；特殊 Session 角色即使复用现有基座，也增加了预置、查找、恢复、保留与 UI 义务；每个被委派的协调 Turn 多一条类型化分配记录（它同时是可见时间线的来源）；Work 与 Session 是 1:1、1:N 还是独立持久实体仍未解决。

ADR 同时列了四条被拒绝的路线：第二个 WorkHub 存储或生命周期权威、跨 Host 全局协调会话、把普通 Session 完整转录复制进 WorkHub、允许模型或路由输出在 Gate 之外直接授权写入。再评估触发点也很明确：受支持的工作流确实需要跨 Host 协调，或 Host 切换造成可重建投影无法解决的用户可见连续性损失，就重审按 Host 决策；若特殊角色生命周期需要第二个持久权威，就重审角色方案本身。

对照main的实现状态：角色表示、惰性创建、持久查找、恢复、按 Host 的 UI 解析、闭合处置与 Gate 均已落地；链接纠正、目标拥有的待处理取消与 Turn 停止、原子超期、基于重试的替换恢复、直接停止也都可用。文档里提到的 Resolver"临时精确名称基线"从未实现——今天的协调是模型驱动的，准入重新验证不透明身份与预期状态，停止与恢复提案携带显式持久目标而非显示名。

这套架构给出的答案并不复杂：协调层不是新系统，而是既有 Session 的一个保留角色；委派是转录里原子提交的有界链接，不是数据复制；执行状态永远是被查询的投影，不是第二份真相；一切写入收口在确定性关卡。省掉的第二套持久层，换来的是崩溃恢复只需一条既有恢复路径、权限边界只需一个准入模块——对任何想在通用执行子系统上叠协调层的产品，这是可以直接抄的结构。 🧩

【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka