Apache Maka WorkHub 协调会话架构拆解一个持久协调者如何不造第二套数据库【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/makaApache MakaIncubating的 WorkHub 是用户与多个工作会话之间的统一对话入口。它的架构决策记录ADR给出了一个克制而完整的答案让协调会话Coordination Session成为既有 Session 的一个特殊角色而不是新建一套持久化体系。本文拆解这个设计为什么成立、边界在哪里、付出了什么代价涉及的核心文件是docs/architecture/workhub-coordination-session-adr.md、packages/core/src/workhub-routing.ts与packages/runtime-host/src/server/workhub-coordination-action-gate.ts。矛盾锚定持久协调者 vs 第二套持久化体系WorkHub 缺的是一种能力用户在对话中提问、澄清、延续旧工作、创建新工作之后这些协调行为本身必须可延续——重启应用后协调者还记得自己做过什么决定。最直觉的做法是新建一套 WorkHub 专用的数据库、事件存储或转录基座给协调者配一个独立的持久化家底。这条路走不通。Maka 的执行层已经有一套完整且权威的 Session 基座转录、轮次Turn、模型调用、恢复与生命周期都挂在它上面。再为协调层造一套持久化体系意味着同一份工作可能在两个权威下各有一份状态双写冲突、恢复分叉、归档语义分裂都会随之而来而且协调层迟早会顺手拿到对执行层的控制权。绝不允许产生第二个 WorkHub 数据库、事件存储、转录基座或与 Session 并行的生命周期权威。这条约束是不可妥协的锚点协调者必须站在既有的 Session 基座之上获得持久性。硬约束清单从 ADR 中提炼出四条绝不 / 只能类规则后续所有机制解释都会回扣到这些编号约束①绝不产生第二套持久化权威。协调会话只能复用现有 Session、Turn、转录与事件基础设施。违反后果产生第二套持久化权威协调事实与执行事实双写不一致恢复时两套账本对不上。约束②协调会话只对协调对话具有权威。它永远不能获得对普通 Session 执行或生命周期的权威。违反后果协调层变成影子权威普通 Session 的归档、删除、恢复会被两条路径同时修改。约束③委派只持久化有界链接不复制转录。普通 Session 的完整转录绝不进入协调会话。违反后果产生转录副本副本随执行推进持续漂移WorkHub 卡片变成不可信的过期快照。约束④所有模型与路由输出都只是建议性的advisory。任何写入、停止或执行权威扩展在发生前必须由确定性动作关卡Action Gate准入或拒绝。违反后果模型输出可以直接授权写入与停止提示注入或模型幻觉会变成真实副作用。补充一条结构性约束协调会话对普通 Session 列表隐藏并被排除在所有路由候选集之外。动作关卡的自我路由拒绝只是纵深防御不能替代协调会话根本不在候选集里这一结构保证。方案总览角色每个 Runtime Host 拥有一个稳定的协调会话它是既有 Session 的保留角色而非新实体。数据归属协调对话归协调会话执行、转录、恢复归目标普通 Session卡片与状态摘要无任何持久化权威。写入路径模型只产出建议确定性动作关卡在所有写入之前做最终裁决。失败语义链接缺失、过期、歧义、模型输出无效一律失败关闭fail closed到澄清clarify。隔离边界按 Host 隔离是有意为之不存在跨 Host 的全局协调会话。上图是协调会话的可见时间线每次委派都以已交给卡片的形态出现在转录中卡片携带目标会话名与状态标签。这个卡片正是delegation_assigned记录的可重建投影而非独立存储。核心机制拆解路由处置四种闭合选项与建议性证据数据从哪来。用户在 WorkHub 发出的每条输入最终都解析为恰好一个提议的路由处置routing dispositionanswer_here在协调会话中直接回答delegate_existing委派给一个有界的、有效的普通 Sessioncreate_new先创建普通 Session再委派clarify继续澄清不猜测目标、不创建 Session。纠正correction、停止stop、恢复resume不是第五种处置而是作用于既有持久委派的链接操作linked operations。这一区分解决一个子问题破坏性操作的目标必须锚定在曾经委派过的那条链上而不能凭名字相似的 Session 推断。输入输出边界很清楚。Session Resolver 只返回有界的既有 Session 证据绝不创建 Session链接目标解析从 WorkHub 持有的有界委派出发沿其持久的 Message、Turn 与延续谱系推进不回退到名称相似性匹配。两者的输出都是建议性的——意向intent描述用户想要什么但它不选择权威Intent 描述用户想要什么它不选择权威。选择权威的是确定性的准入机制。失败语义链接缺失、过期、歧义全部失败关闭到clarify任何情况下都不隐含create_new。这直接对应约束④——模型与路由策略没有直接授权的通道。模型路由适配器Intent 与 Recall 的硬边界协调策略之上有一个可选安装的模型路由适配器分两阶段调用工具无关tool-free模型。边界在packages/core/src/workhub-routing.ts中以常量固化意向模型看到当前请求与至多 8 条有界用户/助手消息WORKHUB_ROUTING_MAX_TRANSCRIPT_MESSAGES 8看不到任何候选其系统提示明确要求Intent 不得选择 Session。召回模型仅在execute与普通continue时被第二次调用看到至多 32 个候选WORKHUB_ROUTING_MAX_CANDIDATES 32。每个候选只含请求作用域内的不透明引用、有界的会话/工作区名称、状态与新旧分桶不接收稳定的 Session 身份、路径、文件内容、工具或能力。这个机制解决的是让模型参与路由但不让模型拥有路由权。它不做什么意向输出不含目标Resolver 输出只含不透明候选引用模型排序或工具选择单独不能授权工作。每个提案仍要携带原始可信用户请求经过 Host 拥有的动作关卡。失败语义全部收敛到clarify模型输出无效解码函数直接抛错、提供方失败、候选不可用、召回为空、结果歧义。applyWorkHubRoutingPolicy同文件 L123-L139是从模型评估到产品路由决策的唯一映射它没有兜底委派分支——没有ranked结果就落到clarify。适配器显式安装后其结果存储在根轮准入root-Turn admission上并被恢复流程复用任何改变其操作、候选集或候选引用的副作用提案在既有动作关卡之前就被拒绝。动作关卡唯一有裁决权的确定性组件谁有最终裁决权。实现上packages/runtime-host/src/server/workhub-coordination-action-gate.ts的WorkHubCoordinationActionGate类L291 起是所有写入前的最后一道闸。它检查Runtime Host 与目标有效性、归档archived与等待waiting状态、自我路由排除、显式create_new、既有工具与权限上限。对替换操作关卡额外要求三件事可信用户文本中存在显式纠正证据按协调转录顺序声明源委派拒绝任何后来的竞争性替换意图。从源码看act方法还实现了基于**动作指纹action fingerprint**的幂等重放同一actionId若携带不同请求指纹以action_conflict拒绝L337-L342 起相同指纹则返回已缓存的重放结果。崩溃点与恢复路径进程重启后内存缓存清空关卡重新从持久状态读取既有分配与声明精确重放收敛到既有事实身份复用在任何效果发生前失败关闭。这直接对应约束④无论是模型还是路由策略都不能直接授权写入、停止或扩展执行权威。委派链接一次 runtime.sqlite 事务在哪里落盘。一次委派只在协调转录与执行转录之间持久化一个有界链接delegationId coordinationTurnId targetSessionId targetMessageId targetTurnId disposition落盘使用既有协调转录中一条闭合的、类型化的delegation_assigned记录schema 定义在packages/core/src/session.tsL1061 起的WorkHubDelegationAssignedMessage。在协调会话与目标 Session 的准入权威之下一次runtime.sqlite事务同时提交该记录与目标待处理消息准入create_new时目标 Session 元数据也在同一事务中创建。记录携带确切的用户文本、已解析的目标与目标 Message/Turn 身份、创建上下文与稳定显示名其动作指纹拒绝动作身份的冲突复用。这条事务就是用户可见的分配边界提交前两个 Session 都看不到工作提交后 WorkHub 链接与目标输入同时存在。崩溃点与恢复路径Host 在提交之后、唤醒执行器之前崩溃由普通待处理消息恢复接管——WorkHub 不拥有第二个恢复状态机或补偿链对应约束①恢复能力直接复用 Session 基座已有的那套。delegation_assigned记录本身就投影出可见的 WorkHub Turn渲染器不再追加第二条摘要。它不做什么初始分配链接不镜像目标 Turn 的执行生命周期。目标的接受、运行、等待、完成、失败、中止与恢复状态仍是普通 Session 的事实对应约束②协调会话不复制普通 Session 的完整转录只保留有界投影或协调摘要对应约束③。混合第一响应即时确认 可重建投影用户发出委派后的第一响应是混合的原子的delegation_assigned记录是即时的持久确认WorkHub 无需等待目标执行即可确认接受而执行状态是只读投影。投影的构造方式目标 Message 是稳定的委派身份targetTurnId只记录其准入位置。WorkHub 向目标 Message 权威查询哪个 Turn 持久消费或准入了该 Message再联合已解析 Turn 记录的寿命周期与目标 Session 的确切活跃 Turn 成员关系投影出running、waiting_for_user、completed、failed与aborted。这套投影在两个边缘场景下仍然正确未消费的转向消息被折叠进后继 Turn恢复把多个待处理 Message 聚合到一个新 Turn 之下。持久的取消墓碑cancellation tombstone可把撤回的排队 Message 解析为aborted。失败语义目标权威暂时不可读时投影为recovering不虚构终结结果。这些执行状态从不作为可变的协调记录追加Session 变更通知使投影失效重启后打开 WorkHub 从同一链接与目标事实重建投影。渲染器在确认之前只持久化一个 Host 作用域的动作 idComposer 草稿文本使用独立的存储键——重载保留幂等性不会冻结旧文本。替换与直接停止破坏性操作的两段事实崩溃后怎么恢复在破坏性操作上最见真章。替换replacement是两段式退役。任何破坏性退役之前先持久化一条对源委派身份唯一的delegation_replacement_requested记录随后目标 Session 的普通 Message 权威要么取消确切的仍待处理委派 Message要么解析该 Message 如何进入执行 Turn由该 Message 创建的根 Turn 可以被停止而只是把它当作转向消息消费的既有用户 Turn 属于共享权威必须保持运行。替换分配与旧链接的delegation_superseded证明原子提交重试同一动作恢复退役/停止之后、替换分配之前的崩溃接缝。替换指纹绑定的是已解析的稳定目标 Session id 而非临时候选引用元数据刷新不改变动作身份。若目标在破坏性边界之后变为归档、消失或等待状态协调转录追加delegation_replacement_aborted终结事实后续重试返回同一终结结果而不是展示一个已停止却未超期的悬空链接。直接停止采用第一索赔胜出first-claim-wins。它先经共享 Session Resolver 解析目标再向 Host 询问该 Session 的哪些委派仍持有可停止的工作然后才回答用户或提出提案——WorkHub 投影是可重建的、窗口打开时可能为空绝不从投影给出破坏性回答。提案只携带不透明委派身份及其所属 Session显示名只是提案侧的检索证据永不进入准入提案不声称拥有自己的证明证明由 Host 从持久状态制作。关卡在任何效果之前立即重新验证分配仍存在、仍属于被提议的 Session、该 Session 上没有其他委派仍持有可停止的工作。持久化形式退役前持久化delegation_stop_requested声明退役后持久化delegation_stop_resolved观察待处理取消墓碑保留破坏性动作身份使两条协调记录之间的崩溃仍保持cancelled_pending。准入时同时持有协调会话与每个活动目标 Session 通道并发分配必须在唯一委派证明之前落定、等到停止声明之后或导致准入失败关闭。可信用户文本必须携带直接停止命令user_stop确认保持在策略输出之外——模型输出或显示名都不能选择停止对象再次回扣约束④。全局动作声明action claim把恢复语义闭合每个持久 WorkHub 记录都以它关于什么为键一个在任何效果之前单独取得的持久动作声明就是全局所有者——精确重放收敛于它任何身份复用包括已拒绝或仍在恢复的尝试之后、跨 Host 重启都在效果之前失败关闭。声明不携带Session 外键因为已提交的破坏性声明必须比其目标的移除更长寿目标 Session 消失后允许停止到达终结解析的是其移除墓碑而不是消失的 Message 证明。**恢复resume**走普通 Session 的延续准入报告resume_started或already_running不创建另一个协调恢复账本。协议层的提案类型完整定义于packages/runtime-host/src/protocol/workhub-coordination.tsL163-L213持久消息 schema 定义于packages/core/src/session.tsL1032-L1118。目标选择交互select_and_delegate 是能力不是协议分叉最后一环解决候选有多个时由谁拍板。默认的协调模型在候选发现之后可以调用tasks.select_and_delegateHost 用既有交互权威发布一个持久 Form接受一个确切的不透明选项再把绑定的 Session/工作区传给既有动作关卡。时序与恢复语义协调 Turn 在等待期间已被准入只有后续关卡与目标准入才能启动委派执行操作在等待之后重读活动 Run 权威保留原始已准入的用户内容永不重写既有路由决策渲染器重载会重新查询待处理交互取消/停止关闭它过期提案不能悄悄选择另一项工作。候选集 id 必须匹配sha256:[a-f0-9]{64}格式候选数量上限 32WORKHUB_COORDINATION_CANDIDATE_MAX_ITEMS同文件 L92。旧的前准入answer - targetSelection - answer协议与渲染器 Promise 已被移除而不是保留为第二个选择实现。边界与代价收益用户层面WorkHub 获得持久的会话连续性且协调与执行互不越权架构层面不增加第二个持久权威、数据库、事件存储或转录副本。成本按 Host 的边界在切换 Runtime Host 时割裂连续性——每个 Host 有独立的协调转录无法协调另一 Host 的 Session特殊 Session 角色带来预置、查找、恢复、保留与 UI 的额外义务每个被委派的协调 Turn 增加一条类型化分配记录。⚠️已知局限Work 与 Session 是 1:1、1:N 还是独立持久实体仍未解决跨 Runtime Host 协调被推迟暂停pause与基于代词的停止控制仍是后续工作ADR 中提到的 Resolver临时精确名称基线从未实现——今天的协调是模型驱动的。再评估触发若受支持的工作流需要一个 WorkHub 对话协调多个 Host 上的普通 Session或 Host 切换造成可重建投影无法解决的用户可见连续性损失应重新评估按 Host 决策若该特殊角色的生命周期需要第二持久权威或普通 Session 基座无法安全强制的例外应重新评估特殊角色方案。设计复盘ADR 明确否决了四条路线每条都对应一条硬约束第二套 WorkHub 数据库/事件存储/转录基座/生命周期权威——直接违反约束①一个跨 Runtime Host 的全局协调会话——破坏按 Host 隔离把普通 Session 完整转录复制进 WorkHub——违反约束③的链接而非复制允许模型或路由输出绕过确定性动作关卡直接授权写入——违反约束④。这套模式的本质是给既有执行子系统的一个实体赋予保留角色把跨实体关系表达为转录内原子提交的有界链接把状态表达为可重建的只读投影把所有写收口到一个确定性关卡。当你的产品已有一个具备事务性提交与恢复能力的统一执行基座、且需要在其上叠加持久协调层时这个思路可以直接复用。反过来如果执行层本身就是多后端、无法用单事务跨越或者协调层确实需要独立的审计与保留策略那么硬压进单一套基座只会把复杂度转移到投影层——此时独立存储才是正确选择。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考