Astryx Agentic States 设计规范为 Agent 驱动的思考、流式输出与工具执行建立状态语言【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读本篇围绕 Astryx 设计规范中的种子草案 docs/design/agentic-states.md 展开讲解这个开源设计系统如何为Agent 驱动的界面状态——思考thinking、流式输出streaming、工具执行tool execution、等待输入awaiting input、同步synchronizing、检视inspecting与渲染rendering——定义统一的状态语言。文中不仅完整保留该规范的原则与八个开放问题还会对照 Chat 组件族 与 useStreamingText 等真实源码说明草案中的问题如何在现有实现中被部分回答。读完你将理解为什么 Agent 反馈不能泄露隐藏推理、如何复用既有状态语言而非发明第二套语言以及一个未定型规范应该如何管理自己的决策边界。一、为什么需要第三套状态语言User / System / Agent 三分法Astryx 的 设计规范索引 明确定义了状态分类学state taxonomy——状态记录按由谁驱动变化划分为恰好三类记录归属User states人驱动的 rest、hover、press、focus、selection 与 manipulation 状态System states系统驱动的 disabled、loading、processing、status 与 transient 反馈状态Agentic statesAgent 驱动的 thinking、streaming、tool execution、waiting、synchronization、inspection 与 rendering 状态关键区分在于User states 由人的交互驱动System states 由系统进程驱动而 Agentic states 由自主代理驱动。一个人工智能体一边思考、一边把 token 流式吐给屏幕、一边并行执行工具调用——这种看起来像处理中但背后是一个自主实体在工作的体验恰好落在前两套语言之间的缝隙里。种子草案在 docs/design/agentic-states.md 中写明了其用户意图与 Agent 一起工作的人应当无需学习第二套无关的状态语言就能理解它是在推进progressing、等待waiting、检视inspecting、同步synchronizing还是在展示结果。Agent 反馈应当传达可操作的系统状态而不是暴露私有或隐藏的推理过程。这两句话是整个规范的两根支柱语言复用不引入第二套状态语言与隐私边界反馈是可操作状态不是内心独白。二、核心设计原则DR1——先扩展既有状态语言草案目前只批准了一条设计原则原文如下DR1 — Extend established state language first.Agentic states SHOULD reuse representations fromdesign:user-statesanddesign:system-stateswhen the underlying intention is the same.DR1——优先扩展既有状态语言。当底层意图相同时Agentic states 应当复用design:user-states与design:system-states中的既有表示。DR1 是一条默认门禁任何新的 Agent 状态表示先要回答现有的 loading、processing、status、selection、temporal-overlay 语言为什么不够用而不是默认发明新视觉。这条原则在 Astryx 已有组件里能找到非常具体的执行样例system-states.md 的 DR1 规定系统状态必须保留原组件的几何与身份DR2 规定每个语义状态必须把颜色与图标、标签或等价非颜色信号配对。Agent 相关的反馈同样继承了这一要求。ChatToolCalls 组件文档 显示工具调用行用themed semantic success/error icon或 pending/running 时的 spinner表达状态——这正是把design:system-states的semantic indicator 必须配 icon、label 或等价线索落实到 Agent 场景。该组件的calls属性中status取值pending | running | complete | error并明确指出省略 status 时默认complete、对仍在运行或已失败的调用具有误导性见 ChatToolCalls.doc.mjs——即未完成必须显式表达这呼应了草案 OQ5 中required human response 必须压过被动进度的意图。三、草案刻意留下的空白Anatomy 与 State representation与很多直接给视觉方案的规范不同这份种子草案故意不为任何 Agent 状态批准视觉表示。它明确声明Anatomy 与层级wiki 未定义 Agent 状态的 anatomy 或关系这些留给未来的提案而不是由本草案推断。State representation候选处理必须先证明既有 loading、processing、status、selection 或 temporal-overlay 语言为什么不足否则不予通过。Responsive 与输入行为候选提案必须在相关开放问题中处理 reflow 下的归因attribution、增量输出incremental output、中断interruption与 reduced motion。Accessibility 意图与视觉处理一同解决评估非动效/非颜色替代方案、播报频率announcement frequency、焦点稳定性、阅读位置与输入可操作性。这是一种刻意的规范工程手法把未解决记录为显式的设计表面而不是把标签悄悄变成政策。规范宁可保留不确定性也不允许未经验证的视觉方案借seed draft之名被实现方引用。值得注意的无障碍边界agentic-states.md本记录不要求披露隐藏的 chain-of-thought。任何用户可见的 rationale 都是产品内容必须遵循其自身的隐私、安全与内容契约。也就是说不披露隐藏推理是规范底线是否展示可见的理由属于产品内容决策不在本规范管辖范围。这与 system-states.md 中不依赖颜色感知或动画也能识别状态类别、影响范围与下一步动作的可访问性意图一脉相承。四、八个开放问题Agent 状态设计的核心矛盾草案把最富技术含量的问题集中在 Open Questions 一节agentic-states.md。这八个问题事实上勾勒出了 Agent 界面状态设计的完整问题域编号问题核心矛盾OQ1Thinking or processingAgent 的工作何时需要区别于普通系统 processing 的表示OQ2User-visible rationale什么处理能区分有意撰写的解释与普通输出又不暗示可访问隐藏推理OQ3Streaming增量文本如何保持可见地未完成又不干扰已可用文本OQ4Tool execution哪些后端工作信息对人有价值何时应保持折叠OQ5Awaiting input必需的人类响应如何压过被动进度同时保留任务上下文OQ6Synchronizing / synchronized挂起与完成的同步如何区别于通用 processing 与 successOQ7InspectingAgent 检视是否需要独立状态还是普通进度 限定上下文就够OQ8Rendering生成的 UI 如何表达部分挂载→完成又不暴露实现抖动4.1 OQ1Thinking与 OQ2Rationale隐私边界的表达难题OQ1 追问Agent 的思考是否需要一个与系统 processing 不同的表示OQ2 追问如果展示理由如何让人知道这是 Agent 有意撰写的解释而不是看到了它的隐藏推理从源码看Astryx 目前选择了不呈现思考过程只呈现可操作结果的路线ChatToolCalls 组件 的定位是显示 AI Agent 采取了什么行动展示工具名、目标文件路径/命令/搜索词、耗时与结果详情——这是行动证据不是推理过程。这与草案的隐私底线完全一致。4.2 OQ3Streaming增量文本的可见不完整与不打扰OQ3 是八个问题中源码证据最充分的一个。Astryx 提供了专门的原语 useStreamingText它解决的核心问题正是bursty 的流式分块如何变成平滑的字符级揭示解耦到达率与显示率用requestAnimationFrame按固定节奏排空字符而不是每收到一个 chunk 就整段渲染。三档速度预设useStreamingText.tsnatural自然逐字揭示、fast随积压加速、instant跳过动画直接返回全文。动效 token 驱动节拍tick 间隔派生自主题的--duration-fast-min动效 token自然档取 1/10快速档取 1/20下限 4ms无 Theme Provider 时回退到默认值。grapheme 边界保护snapToGraphemeBoundary用Intl.Segmenter把渲染切片回退到最近的 grapheme cluster 边界避免 tick 落在代理对surrogate pair、国旗序列或 ZWJ emoji 中间渲染出半个字形Intl.Segmenter不可用时退化为避开孤立低代理。reduced motion 优先通过 SSR 安全的useMediaQuery((prefers-reduced-motion: reduce))用户偏好减弱动效时跳过渐进揭示、直接返回全文useStreamingText.ts——这正好回应了草案responsive 与输入行为一节中对 reduced motion 的要求。配套的 Markdown/streaming.ts 与 incremental.test.ts 说明流式场景下还有增量 Markdown 解析这一层避免半截语法在渲染时闪烁。README 的用法示例const displayed useStreamingText(rawText, isStreaming); return Markdown{displayed}/Markdown;给出了最小接入方式。4.3 OQ4Tool execution何时折叠后端工作OQ4 问哪些后端工作信息对人有价值何时保持折叠ChatToolCalls 的 anatomy 与使用实践 给出了一个可操作的参考答案单条调用内联渲染多条调用折叠成摘要把最新调用显示在表面点击组头wrench 图标 调用计数展开完整列表。每条调用包含 status icon或运行中 spinner、等宽字体工具名、节点徽标cli:remote-server、workspace、目标标签、diff 统计增删行数与耗时。最佳实践要求每个调用都带 target 字符串文件路径/命令/搜索词、完成调用显示耗时让用户判断哪个工具慢、响应为何耗时、为产生输出的调用提供 resultDetail 代码块diff、终端输出供内联检查。同时有一条反实践不要把工具调用放在聊天消息上下文之外它们是 assistant 消息的组成部分不是独立 UI。这些实践恰恰回答了什么信息有用目标、耗时、结果与何时折叠多条时默认折叠、最新可见、可展开——虽然组件实现先于规范批准但二者方向一致。4.4 OQ5Awaiting input与 OQ6Synchronizing优先级与类别区分OQ5 问必需的人类响应如何压过被动进度OQ6 问挂起/完成的同步如何区别于通用 processing 与 success。这两问都指向 system-states.md 的prominence 分级思想反馈的显著度应匹配其持续性与紧迫性DR3且改变显著度不得改变底层语义DR4。草案把这些决策留给了未来的提案只要求候选方案在同一框架内回答。4.5 OQ7Inspecting与 OQ8Rendering检视与生成 UI 的挂载表达OQ7 质疑 Agent 检视是否需要独立状态OQ8 追问生成式 UI 如何表达部分挂载→完成。草案给出的判据是是否复用普通 progress scoped context 即可。从 Chat 组件族 的文档看Astryx 用 gap 独立行LLM tool events 或 streamed blocks、ghost 气泡AI 富内容如代码块/Markdown 无可见边界等机制承载渲染中的内容可视为 OQ8 的候选素材但正式决策同样未批准。五、无障碍意图不靠颜色、不靠动效、不打扰综合草案与姊妹规范Agent 状态的无障碍底线可以归纳为不依赖颜色design:system-states的 DR2 要求语义状态必须配 icon、label 或等价非颜色信号ChatToolCalls 的 status icon / spinner 就是落地。不依赖动效prefers-reduced-motion下流式揭示直接跳过useStreamingText.ts。不反复打断阅读与焦点草案要求评估 announcement frequency、focus stability 与 reading position。等待期可感知system-states的 DR8 规定 reduced-motion 模式下忙碌反馈仍须传达工作未完成。一个值得注意的实现细节ChatMessageList 把消息列表做成rolelog/aria-livepolite区域并在流式期间设置aria-busy{isStreaming || undefined}——辅助技术会等待并在完成后播报完整消息。这正是草案播报频率问题的一个工程化回应忙碌期不逐 token 播报完成时一次性播报。六、内容边界这份规范不管辖什么种子草案在 Content boundary 中明确划界本文件框定未解决的人机界面 Agent 状态。它不定义 agent 协议、隐藏推理披露、工具遥测、进度事件 schema、产品文案、实现机制或已批准的视觉处理。也就是说以下内容不属于本规范另有归属Agent 协议如工具调用协议与工具遥测如进度事件 schema——属实现机制隐藏推理是否披露、用户可见理由的内容契约——属产品内容与隐私决策产品文案product copy——属内容团队具体的 prop 名、ARIA 属性、token 名、审计检查——按 docs/design/README.md 的原则这些应归属组件契约、架构记录与实现而不进入设计规范。这套边界保证了规范管视觉与交互意图、实现管机制与 API二者互不越界也与 user-states.md、system-states.md 的边界声明完全一致。七、决策日志与权威状态draft 的意义草案的 front-matteragentic-states.md暴露了它的治理信息authority: draftapproved_by: nullverified_by: []评审触发条件为visual, interaction, accessibility架构关联为architecture:theme-tokens。对照 docs/design/README.md 的晋升规则新设计规范从draft起步晋升为current、后续修改与规范资产更新都需要cixzhang、imdreamrunner或.github/DESIGNOWNERS成员的 exact-head 审批。因此任何组件都不得声称采纳了 Agent 状态表示——Component contract links 一节明确在单个状态表示被决定并批准之前面向 Agent 的组件不应声称采纳。可视参考资产不应随意加入——规范要求候选证据在某个开放问题获得提案之后才可添加。这种先框问题、后批准方案、再让组件认领的顺序是设计系统防止实现先于规范、规范被实现绑架的关键机制。从源码看Astryx 的 Chat 族组件ChatToolCalls、useStreamingText、ChatMessageList 的 aria-busy已经提供了丰富的候选实践但它们服务于当前产品需求不构成对草案中视觉处理的批准——这正是种子草案刻意维持的状态。八、对实践者的启示如何在未定型规范下工作如果你正在 Astryx 上构建 Agent 界面这份草案给出的实操指引可以总结为默认复用Agent 的等待/失败/成功优先套用 system-states 的 disabled / processing / status / temporal-overlay 词汇不要急着造新视觉。流式输出用现成原语接入 useStreamingText 处理增量揭示记得尊重 reduced motion并用Markdown流式解析避免半截语法闪烁。工具调用用 ChatToolCalls为每次调用提供 target、status、耗时与结果详情多条时让它默认折叠、最新可见不要省略 status 字段。播报克制借助 ChatMessageList 的rolelogaria-busy模式忙碌期不逐字播报完成时一次性播报。遵守边界不把草案当已批准的视觉政策引用不声称组件已采纳未批准的 Agent 状态参与 OQ1–OQ8 的讨论时先论证既有语言为什么不足再给出带证据的提案。结语agentic-states.md 是一份罕见的诚实的种子草案它不假装知道答案而是把 Agent 状态设计中最难的问题——思考与处理的区分、可见理由与隐藏推理的边界、流式的打扰控制、工具信息的折叠策略、同步与检视的类别归属、生成 UI 的挂载表达——逐条编号、留白并设定先复用、后发明、未批准不认领的纪律。结合 Astryx 仓库中 Chat 组件族与流式原语的真实实现你可以看到这些问题如何在工程侧被部分回答、在规范侧如何保持开放。这套问题即文档的治理方式正是 Agent-ready 设计系统在视觉方案成熟之前管理不确定性、保护组件契约不被过早绑定的范本。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考