@guuey/agent-layout

中文文档
0.36.0发布于 2026/11/15MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 4885

Agent-mode layout: the two-tone shell where an app and its agent share one surface — the pane follows attention, the transport owns the stream.

原始使用文档

@guuey/agent-layout

Agent-mode layout — the layout category for surfaces where an app and its agent share one screen: app menus in the upper sidebar, the agent rail below, and a content pane whose ground follows the user's attention between the two. Address the agent and the pane takes the agent's tone; navigate and it returns to the app's. One law: layout follows attention; transport owns the stream — the tone flips on submit, never on stream events, and interrupting is the transport's business.

import {
  AgentModeProvider,
  AgentModeShell,
  AgentModeSidebar,
  SidebarPanel,
  ActivePane,
  bindGuueyChat,
  useAgentMode,
} from "@guuey/agent-layout/react";
import "@guuey/agent-layout/styles.css";

function Shell() {
  const { dispatch } = useAgentMode();
  return (
    <AgentModeShell>
      <AgentModeSidebar>
        <SidebarPanel section="app">{/* your menus — zero wiring */}</SidebarPanel>
        <SidebarPanel section="agent">
          <GuueyChat {...bindGuueyChat(dispatch)} />
        </SidebarPanel>
      </AgentModeSidebar>
      <ActivePane>{/* your routes / canvas */}</ActivePane>
    </AgentModeShell>
  );
}

<AgentModeProvider mode={mode} navigationKey={pathname} identity={<Logo />}>
  <Shell />
</AgentModeProvider>;
  • Two tones, calibrated: the default pair is the shipped warm-paper/neutral-chrome step, light and dark. Overrides are validated against a perceptibility floor (ΔL* ≥ 6, or a hue-temperature step) — two tones that measure alike are rejected with an explanation.
  • Route-derived follow: pass your router's location key as navigationKey; every navigation returns the pane to the app tone with zero per-link wiring. Same-page menu clicks are caught by the app panel's capture-phase listener.
  • No stale-content hold: while the agent has the room and nothing is presented yet, the pane shows a working state (your identity + pulse), never the previous page under the agent's tone.
  • A tall nav scrolls, the agent stays: the app panel is the sidebar's scroller (a bottom-edge fade shows while items are hidden below it), and the agent panel never shrinks under its floor, so the composer is always reachable. The floor is --guuey-layout-agent-panel-min (default 112px: @guuey/chat's header row plus its one-line composer, so nothing is clipped by default). A host that renders the composer alone may lower it; raise it when your agent surface needs more. A host that gives the agent panel a fixed height (--guuey-layout-agent-panel-flex: 0 0 auto) sets --guuey-layout-app-panel-flex: 1 1 auto (default 0 1 auto) so the app panel takes the free space and the rail stays at the bottom.
  • A drawer at phone widths: under 1024px the sidebar becomes an overlay drawer behind a ☰ toggle. At drawer widths, give the shell the viewport (100dvh): the drawer and its toggle are fixed to the viewport, and the toggle sits at its top-left, over anything the host puts above the layout. Escape closes the open drawer, and focus returns to the toggle.
  • Mode-aware: pass the same mode you give your chat surface — the lib rides your existing light/dark machinery and adds none of its own.
  • Not a chat dependency: bindGuueyChat pairs with @guuey/chat structurally; any agent surface can call the machine directly through useAgentMode().

React DOM only, zero runtime dependencies. react >= 18 is an optional peer: the ./react subpath needs it and the root (the attention machine and the tone helpers) does not, so npm does not install it for you — add react to your own dependencies when you import @guuey/agent-layout/react.

Support

Questions and help: the guuey community on Discord — https://guuey.com/discord. Bugs and feature requests: https://github.com/withguuey/guuey-sdks/issues.

版本与发布记录

@guuey/agent-layout 共发布 49 个版本,首次发布于 2026/08/25;过去 12 个月发布了 49 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.36.0latest2026/11/152 天前
0.35.02026/11/116 天前
0.34.02026/11/0610 天前
0.33.02026/11/0611 天前
0.32.02026/11/0611 天前
0.31.12026/09/291 个月前

其他发布通道:next → 0.16.15。

关于 @guuey/agent-layout 的常见问题

@guuey/agent-layout 是什么?

Agent-mode layout: the two-tone shell where an app and its agent share one surface — the pane follows attention, the transport owns the stream.

如何安装 @guuey/agent-layout?

在项目目录运行 npm install @guuey/agent-layout,或使用 pnpm add / yarn add / bun add。

@guuey/agent-layout 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guuey/agent-layout 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@guuey/agent-layout 可以商用吗?

@guuey/agent-layout 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guuey/agent-layout 的下载量有多少?

根据 npm 官方下载统计,@guuey/agent-layout 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,885 次,日均约 163 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guuey/agent-layout 还在维护吗?

最新版本 0.36.0 发布于 2026/11/15(2 天前);至今共发布 49 个版本,其中过去 12 个月发布了 49 个;首次发布于 2026/08/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。