人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载本文围绕 KunLocal-first AI agent workspace一个同时承载桌面 GUI 与 TUI 的统一运行时中的 Room Proposals 机制展开。在 Kun 的房间Rooms协作模型中AI 成员可以向用户提出结构化的行动建议——固定一条约定pin an agreement、请求一次执行request an execution、添加新成员或创建一个新 Agent。本文将从数据契约、创建流程、工具暴露、用户裁决路径到渲染器采纳流程完整拆解这一Agent 只起草、用户才执行的授权边界如何落地并给出可直接对照源码的调用链与可复用的 HTTP 接口用法。核心设计绝对的授权边界Room Proposals 是由 Agent 起草的动作卡片action cards。它编码 Agent 想建议的一项结构性变更并以卡片形式渲染在房间时间线room timeline上供用户审阅。其授权边界是绝对的Agent 只能起草提案draft proposals只有用户能够确认并执行confirm and execute。Agent 侧的工具是**纯数据data-only**的永远不会自己执行被提议的动作提案的采纳adoption总是重新进入已有的、以用户为作用域user-scoped的变更路径如钉消息的 rule 端点、房间成员更新、Agent 身份创建等用户操作产生持久化的产物durable artifact后卡片才被记录为已提交committed。这保证了无论 Agent 提出什么建议实际的变更都发生在用户主动发起的请求中用户拥有最终裁决权。数据契约四种载荷与四态流转持久化记录由 kun/src/contracts/room-proposals.ts 定义使用 Zod 做运行时校验。一个提案RoomProposal包含四种载荷payload每种载荷在提交commit时都要求对应的结果引用result reference载荷Payload提交时要求的结果引用pin_agreement固定约定rule钉住提案消息所创建的规则execution_request请求执行message一条更新的、由用户撰写并携带请求的消息add_member添加成员room同一房间现已将提案中的 Agent 添加为启用成员create_agent创建 Agentagent提案之后创建的 Agent 身份从契约源码看各载荷的字段约束如下均使用.strict()拒绝未知字段pin_agreementbody为 1–4000 字符的约定正文execution_requestgoal为 1–8000 字符的目标描述memberIds最多 8 个默认空数组可选的repositoryId指向房间内仓库add_memberparticipantAgentId指定要加入的 AgentroleNotes最多 2000 字符默认空串create_agentname为 1–80 字符title最多 160 字符默认空串instructions最多 8000 字符默认空串。提案级字段还包括rationaleAgent 给出理由1–1000 字符、authorMemberId、可选的authorAgentId、originRunId、可选的rootRequestId、createdAt与可选的resolvedAt。状态机为四态open待裁决、committed已提交、dismissed已驳回、withdrawn已撤回。只有open状态的提案可以被裁决resolve。并发安全裁决resolve要求携带预期的文档修订号expectedRevision即 compare-and-swap 比较并交换。因此一张过期的卡片永远不会覆盖并发的裁决结果——如果读取后提案已被他人修改服务端会返回冲突conflict。幂等重放创建与裁决共享房间交互回执/指纹机制interaction receipt/fingerprint见 kun/src/rooms/room-interaction-store.ts 中的interactionId、interactionFingerprint、interactionReplay。重试的请求会重放第一次被接受的结果而不是重复应用两次。创建流程原子双文档提交createRoomProposal位于 kun/src/rooms/room-proposals.ts创建流程分为四步校验输入用CreateRoomProposalSchema解析请求体身份校验确认作者authorMemberId是房间的启用成员未被移除且enabled为 true否则抛出RoomStoreConflictError并发限额强制每个 run 最多 2 个 open 提案ROOM_PROPOSAL_RUN_LIMIT 2每个房间最多 20 个 open 提案ROOM_PROPOSAL_ROOM_OPEN_LIMIT 20原子提交两个文档room_proposal记录状态为open一条展示消息presentation message带presentationKind: proposal、proposalId消息状态为final消息正文即rationale。创建是**纯展示presentation-only**的它不唤醒房间成员、不写peer_inbox、不创建任务、也不消耗 Agent 预算。提交时产生的事件只有message.presentation.created与room.proposal.updated记忆捕获memory capture显式跳过提案卡片因为草稿还不是事实a draft is not yet a fact。上述不产生副作用的结论在 kun/src/rooms/room-proposals.test.ts 中有直接的测试断言创建后wake未被调用且request、peer_inbox、task、agent_budget、agent_budget_claim等文档均不存在。工具暴露propose_room_actionkun/src/rooms/room-proposal-tool.ts定义了工具propose_room_action关键约束如下暴露范围仅在房间讨论/会话步骤roomAgent上下文即roomStepKind discussion || roomStepKind conversation中通过shouldAdvertise对外展示身份宿主绑定host-bound房间、成员与 run 均从线程的房间上下文与当前 peer 激活状态推导而来复用与send_room_message相同的 freshness 校验绝不来自模型参数。源码中有三种绑定路径conversationBinding、peerBinding用于 peer 激活且拒绝handoffId存在的情况、discussionBinding传统讨论要求请求未被取消特性开关需要proposalsAgent 特性标志create_agent载荷额外要求identities特性标志载荷预校验assertProposalPayload会在创建前对照实时房间校验引用——执行请求的memberIds必须是房间启用成员、repositoryId必须属于该房间add_member的 Agent 必须存在且未归档、尚未在房间中create_agent在特性关闭时报错明确告知工具返回{ accepted: true, proposalId, status: open, note: Submitted as a draft for the user to confirm. Nothing was executed. }明示这只是等待用户确认的草稿幂等client request id 由 run 与工具调用派生agentStableId(proposal, runId, activeToolCallId)因此重试的调用会重放同一份草稿副作用声明sideEffect: read-onlyeffects全部为 false无网络、无外部写入、无进程执行、无 GUI 自动化从工具声明层面进一步固化只起草不执行。撤回路径当某个 run 被取消或主题topic停止时withdrawRunProposals同样位于 kun/src/rooms/room-proposals.ts会把该 run 仍处于open状态的提案标记为withdrawn原因分别为run_cancelled/topic_stopped。从源码调用点看主题停止由 kun/src/rooms/room-peer-runner.ts 触发run 取消由 kun/src/agents/agent-direct-runner.ts 触发。仅安静下来went quiet的 run 的草稿保持open只有用户能裁决它们。撤回时若用户裁决先落地提案已非 open冲突会被静默忽略用户裁决获胜。用户裁决绑定 HTTP 路由而非任何 Agent 工具裁决resolution绑定在 HTTP 路由上Agent 永远无法触达该路径。路由注册见 kun/src/server/routes/register-room-proposal-routes.tsGET /v1/rooms/{roomId}/proposals/{proposalId}— 读取一条提案readRoomProposalPOST /v1/rooms/{roomId}/proposals/{proposalId}/resolve— 用户裁决请求体为{ clientRequestId, expectedRevision, decision: committed | dismissed, resultRef? }契约见ResolveRoomProposalSchema。resolveRoomProposal在同一事务内完成以下校验committed裁决必须携带resultRef且其kind必须匹配载荷类型RESULT_REF_KIND映射pin_agreement → rule、execution_request → message、add_member → room、create_agent → agent针对被引用的产物做二次校验assertProposalResultrule必须指向提案消息rule.messageId proposal.messageIdmessage必须由用户撰写authorKind user且存储于草稿之后message.seq proposal.seqroom必须是同一房间且被提议的 Agent 现在是启用的、未移除的成员agent身份必须晚于提案创建agent.seq proposal.seq修订号不匹配stale revision或状态非open均返回冲突RoomStoreConflictError。裁决成功后提案写入新状态committedresultRef与resolvedAt或dismissed并发出room.proposal.updated事件。路由实现中还通过rooms.exclusive()保证房间级串行并在 finally 中rooms.wake()唤醒房间。渲染器卡片与四种采纳流程RoomProposalCardsrc/renderer/src/components/rooms/RoomProposalCard.tsx由RoomMessageRow在消息带presentationKind: proposal时分派渲染。卡片展示载荷字段、作者、理由与状态包括撤回原因并订阅房间事件自动刷新room.proposal.updated与message.created都会触发刷新/采纳逻辑。卡片只为用户提供显式动作四种载荷各有一套先走用户既有路径、再提交的采纳流程pin_agreement允许用户编辑约定文本通过既有 rule 端点钉住卡片消息pinMessage使用确定性 request id{proposalId}-pin支持重试重放必要时用updateRule更新正文最后以新 rule id 提交resultRef: { kind: rule, id: rule.id }execution_request通过kun-room-proposal-draft窗口事件填充 composer目标 goal、提及 mentions、仓库 repository、主题 topic、intent: execute并武装arm卡片记录armedAt时间戳当用户随后真实发送的消息落地message.created事件卡片校验该消息是用户撰写且创建时间晚于armedAt后以该消息作为结果引用提交resultRef: { kind: message, id: sent.id }add_member打开既有成员编辑器RoomMemberEditor预填被提议的 AgentagentMember构造默认成员通过正常房间 patch 应用成员更新roomsClient.update然后提交resultRef: { kind: room, id: room.id }create_agent打开既有 Agent 资料表单AgentProfileForm预填草稿中的name、title、instructions保存后以创建的 Agent 身份提交resultRef: { kind: agent, id: agent.id }任何open提案都可以通过带expectedRevision的 resolve 被驳回decision: dismissed。没有任何自动执行工具侧propose_room_action声明为只读且永不执行动作卡片侧只在用户自己的请求产生了持久化产物之后才提交。这正是整套机制的安全根基——即便 Agent 提议了某个动作最终落地必然经过用户的真实请求路径用户随时可以驳回或忽略。关键源码路径速查契约与载荷/裁决 Schemakun/src/contracts/room-proposals.ts创建/裁决/撤回实现含限额常量kun/src/rooms/room-proposals.ts工具暴露propose_room_actionkun/src/rooms/room-proposal-tool.tsHTTP 路由GET 读取 / POST resolvekun/src/server/routes/register-room-proposal-routes.ts渲染器卡片与四种采纳流程src/renderer/src/components/rooms/RoomProposalCard.tsx交互回执/指纹幂等机制kun/src/rooms/room-interaction-store.ts测试覆盖原子写入、幂等重放、限额、撤回kun/src/rooms/room-proposals.test.ts赞分享人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载相关推荐Room and User Statistics房间与用户统计深入解析Room and User Statistics房间与用户统计深入解析 Synapse 房间与用户统计Room User Statistics机制全后端即时通讯UBottomSheet 无障碍访问为视障用户优化弹窗交互体验UBottomSheet 无障碍访问为视障用户优化弹窗交互体验 UBottomSheet 是一款基于协议导向设计的 iPhone 地图应用底部弹窗组件专注于Synapse Edit Room Membership API 详解管理员如何强制将本地用户加入房间Synapse Edit Room Membership API 详解管理员如何强制将本地用户加入房间 导读 本文讲解 SynapseMatrix 家目录服后端即时通讯上一篇终极双语歌词下载器网易云音乐歌词获取完整解决方案下一篇CefFlashBrowser免费Flash浏览器完整指南让经典Flash内容重获新生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考