资源03 · 客户端架构

CLIENT ARCHITECTURE / ONE AUTHORITY

一个客户端，一条可回放的执行真相

Kyormar 是本地优先的 Agent 工作台与 IM 协作客户端。App 拥有服务生命周期，Agent 拥有执行真相，其他表面只消费 typed contract

APP COMPOSITION ROOT / CURRENTONE SERVICE AUTHORITY
PRODUCT SURFACE / 01IMpeople · messages · collaboration
MODULE HOSTKYORMAR APPowns lifecycle, not business truth
PRODUCT SURFACE / 02AGENTgoals · tools · execution · replay
NON-CLONE OWNERAgentService

owner thread · Tokio runtime · executor · store lease · recovery

CLONEABLE PORTAgentHandle

typed command · receipt · view · observation

IM / INDEPENDENTAGENT / IN-PROCESSDEVTOOLS / DEBUG READ ONLY
02

STARTUP / COMPLETE BINDINGS OR NOTHING

服务先完整启动，再把 handle 交给界面

App shell 可以在尚未打开 Agent store 时显示登录和 IM；只有认证 session generation 完整且所有阶段成功，UI 才收到 AgentRuntimeBindings

  1. 01CONFIG运行配置

    解析已批准的本地身份与运行根，不从默认值猜测外部 identity

  2. 02STORE存储与租约

    创建 canonical Agent store，并持有唯一跨进程 store lease

  3. 03PROFILE本地身份绑定

    设备、本地 profile 与 namespace 必须完整一致

  4. 04CAPABILITY能力目录

    装配工具、Skills、MCP 与 Host capability 的 typed registry

  5. 05PROVIDER模型与工具组合

    将 provider、context、tooling 与执行策略接入同一服务

  6. 06EXECUTOR后台执行器

    唯一 Tokio runtime、executor 与 owner thread 一起启动

  7. 07RECOVERY恢复

    从 durable commits 恢复任务、进程、审批和可见视图

  8. 08MEDIA ROOT媒体缓存根

    最后安装应用媒体缓存路径，再向 UI 发布完整 bindings

03

CANONICAL CHAIN / HOT AND COLD

所有可见状态，都从一次 durable commit 出发

这条链同时服务普通 Agent 与 Coding Agent。工具、审批、工作流、多 Agent 和 managed process 不建立平行 writer、projector 或 replay truth

  1. ATYPED COMMAND

    UI 与 CLI 只提交完整意图

    命令必须携带明确 identity、selector 与封闭 payload；当前选择、标题、正文和数组位置都不是业务身份

  2. BAGENT HANDLE

    cloneable handle 是唯一业务入口

    App 保留 non-Clone AgentService；UI、CLI、DevTools 只得到同一 authority 的 bounded typed handle

  3. CCANONICAL TRANSITION

    所有语义在 Agent 内收敛

    普通 Agent、Coding Agent、工具、审批、工作流与多 Agent 共用同一 transition，不另建状态机

  4. DDURABLE COMMIT

    事务成功后才产生 commit_seq

    commit_seq 只表示提交顺序，不能替代 session、task、turn、tool 或 effect 的完整业务 identity

  5. ESOLE PROJECTOR

    每个领域只有一个 projector

    SessionView、Knowledge 等领域各自只有一个 reducer；热更新与冷回放读取相同 durable facts

  6. FTYPED OUTPUT

    回执、视图、回放和观测来自同一提交

    发布失败进入 typed Gap 或 Unavailable；消费者不能合成空状态、完成态或兼容 fallback

04

CONSUMERS / MECHANICAL ONLY

每个表面都知道自己能读什么，也知道自己不能拥有什么

IM、Server 和 DevTools 不是 Agent 的备用存储或失败回退；每条跨边界路径都有明确输入、输出和禁止拥有的状态

SURFACEINPUTOUTPUTDOES NOT OWN
UItyped commandreceipt / session view

只拥有草稿、选择、展开状态和其他 UI-only state

CLI / TUItyped commandreceipt / bounded view

不维护独立 runtime transport、store 或状态机

DEVTOOLSobservation requestcommit / view / receipt

只读；不拥有 writer、projector、cursor、transport 或 canonical cache

IMexplicit shareauthorized content copy

默认只消费 content-free control state，不拥有 Agent 执行真相

SERVERverified bindingauth / catalog / billing / policy / relay

不保存普通 prompt、reasoning、timeline、tool 参数与输出或文件正文

05

TEN CRATES / ONE COMPOSITION ROOT

十个 crate 分工，不等于十套运行时

crates/agent 只是物理分组目录。facade 包 kyormar-agent 是唯一 composition API；App 不直接拼装 implementation crates

facadecomposition root

AgentService、AgentHandle、executor supervision 与 host binding 的唯一组装入口

contract + pathstyped boundary

命令、视图、回执、identity、failure code 与受控路径策略

coredurable truth

store、transition、commit、per-domain projectors、replay、memory 与 compaction truth

context + providermodel turn

上下文装配、记忆消费、provider loop、模型能力与流式响应归一化

tooling + tools + mcpcapability execution

策略、审批、调度、内置工具与 MCP lifecycle，全部回到 durable receipt

workerdangerous isolation

仅为单次危险动作启动；不拥有 session、task、provider、projector 或 replay truth

06

INVARIANTS / FAIL CLOSED

判断架构是否走偏，只检查这些不变量

它们比“模块很多”“用了 Rust”或“界面看起来一致”更重要，因为它们直接决定状态是否可恢复、身份是否可信、危险动作是否可能重复

ONE SERVICE
App composition root 只拥有一个 AgentService 生命周期
ONE STORE LEASE
service owner thread 在 runtime 完全停止前始终持有唯一 store lease
COMMIT BEFORE PUBLISH
事务成功后才能发布 receipt、view 或 observation
SAME HOT / COLD PATH
实时更新与冷启动回放使用相同 facts 和同一个领域 projector
FAIL CLOSED
缺失、冲突或断档返回 typed failure，不从文字和缓存推断
NO CONTENT SERVER
普通本地 Agent 正文留在本地；远端只承接 content-free 控制面
打开 Kyormar 源码 打开 Kyormar-DevTools