auricui-skill 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # AuricUI Skill
 
-为编码 Agent 安装 AuricUI 组件库指南，包括 API 查询、基础组件、AI 聊天、Studio、主题动画、依赖检查和可编译示例。需要 Node.js >=20.19；附带的依赖/API 检查工具使用 Python 3 标准库。
+为编码 Agent 安装 AuricUI 组件库指南，包括 API 查询、基础组件、Agent / Personal Agent、AI 聊天、Studio、主题动画、依赖检查和可编译示例。需要 Node.js >=20.19；附带的依赖/API 检查工具使用 Python 3 标准库。
 
 此 npm 包是 Skill 安装器，React 组件库本身为 `auricui`。安装器只复制技能文件；在应用中安装 UI 库由 Agent 按 Skill 指南完成。
 
@@ -25,6 +25,6 @@ npx auricui-skill@latest --dry-run
 
 自定义目录参数表示技能的父目录，安装器会追加 `auricui`。已有目录默认不覆盖；`--update` 的备份位于 skills 父目录下的 `.auricui-skill-backups/`，终端会输出确切位置。符号链接目标不会被覆盖。
 
-安装后刷新 Agent 技能列表或新开会话，使用 `$auricui`；不支持自动扫描技能的 Agent 可显式读取安装目录中的 SKILL.md。组件基线为 `0.1.0-preview.1`，实际安装版本不同则按其声明核对 API。
+安装后刷新 Agent 技能列表或新开会话，使用 `$auricui`；不支持自动扫描技能的 Agent 可显式读取安装目录中的 SKILL.md。组件基线为 `0.1.0-preview.3`，实际安装版本不同则按其声明核对 API。
 
 包含的源参考快照和本地组件包保留 MIT 与第三方许可；详见 Skill 内来源资料和组件包的 LICENSE / THIRD-PARTY-NOTICES.md。

package/bin/install.mjs

@@ -41,11 +41,11 @@ function main() {
   const source = fileURLToPath(new URL('../skill/', import.meta.url));
   if (!fs.existsSync(path.join(source, 'SKILL.md'))) throw new Error('Skill payload missing. Build the distribution package before running it.');
   const present = fs.existsSync(target) || (() => { try { return fs.lstatSync(target).isSymbolicLink(); } catch { return false; } })();
+  console.log(`Destination: ${target}`);
+  if (dry) { console.log('Dry run: no files written.' + (present ? ' Destination already exists; an actual update requires --update.' : '')); return; }
   if (present && fs.lstatSync(target).isSymbolicLink()) throw new Error(`Refusing to replace a symlink: ${target}`);
   if (present && !update) throw new Error(`Skill already exists: ${target}\nUse --update to back it up and replace it.`);
   if (present && !fs.statSync(target).isDirectory()) throw new Error(`Destination is not a directory: ${target}`);
-  console.log(`Destination: ${target}`);
-  if (dry) { console.log('Dry run: no files written.'); return; }
   fs.mkdirSync(base, {recursive: true});
   const staging = fs.mkdtempSync(path.join(base, '.auricui-stage-'));
   let backup;

package/package.json

@@ -1,12 +1,31 @@
 {
   "name": "auricui-skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Install the AuricUI component-library skill for coding agents",
   "type": "module",
   "license": "MIT",
-  "bin": { "auricui-skill": "bin/install.mjs" },
-  "files": ["bin", "skill", "README.md", "LICENSE"],
-  "engines": { "node": ">=20.19" },
-  "publishConfig": { "access": "public", "tag": "latest" },
-  "keywords": ["auricui", "agent", "skill", "react", "ui"]
+  "bin": {
+    "auricui-skill": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "keywords": [
+    "auricui",
+    "agent",
+    "skill",
+    "react",
+    "ui"
+  ],
+  "author": "hehuan"
 }

package/skill/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: auricui
-description: 使用 auricui React 组件库开发深色应用、设置面板和 AI 聊天界面；提供组件选择、准确的 props、主题与动画、服务适配和安装排错。用户提到 AuricUI、auricui/chat、auricui/studio，或要求沿用这套视觉系统时使用。
+description: 使用 auricui React 组件库开发深色应用、设置面板和 AI 聊天界面；提供组件选择、准确的 props、主题与动画、服务适配和安装排错。用户提到 AuricUI、auricui/agent、auricui/chat、auricui/studio，或要求沿用这套视觉系统时使用。
 ---
 
 # AuricUI
 
-以已安装的 `auricui` 成品包开发应用。文档和可编译示例基于 `0.1.0-preview.1`；版本不同时，以安装包的 `package.json`、`exports` 和 `.d.ts` 为准。所有附带路径相对于本 Skill，跨项目使用不需要原开发仓库。
+以已安装的 `auricui` 成品包开发应用。文档和可编译示例基于 `0.1.0-preview.3`；版本不同时，以安装包的 `package.json`、`exports` 和 `.d.ts` 为准。所有附带路径相对于本 Skill，跨项目使用不需要原开发仓库。
 
 ## 工作流程
 
@@ -21,6 +21,7 @@ description: 使用 auricui React 组件库开发深色应用、设置面板和
 | --- | --- |
 | 安装、入口、React/SSR、全局样式 | [esm-package.md](references/esm-package.md) |
 | 按钮、表单、设置、弹窗、颜色和数字字段 | [core-components.md](references/core-components.md) |
+| Agent 消息、工具执行、记忆、简报与个人助手 | [agent-components.md](references/agent-components.md) |
 | AI 聊天、富文本、模型菜单、附件、工具和问答 | [chat-components.md](references/chat-components.md) |
 | 项目、时间轴、媒体、专业编辑器 | [studio-components.md](references/studio-components.md) |
 | 配色、字体、层级、Portal、动画 | [theme-motion.md](references/theme-motion.md) |
@@ -35,12 +36,14 @@ description: 使用 auricui React 组件库开发深色应用、设置面板和
 ```bash
 python3 <Skill目录>/scripts/inspect_api.py --entry core --symbol CardButton --project <前端目录>
 python3 <Skill目录>/scripts/inspect_api.py --entry chat --symbol PromptEditor --project <前端目录>
+python3 <Skill目录>/scripts/inspect_api.py --entry agent --symbol MemoryCard --project <前端目录>
 python3 <Skill目录>/scripts/inspect_api.py --entry studio
 ```
 
 无 `--symbol` 时列出入口导出。工具基于 [API 索引](references/api-index.json)，区分运行时和 type-only 导出；版本不同则沿安装包入口的 `export *` 检查当前声明，不把基线索引当成新版契约。
 
 附带可复制并经过编译检查的示例：
+- 主题和新增组件：`assets/examples/Theme.tsx`、`Drawer.tsx`、`Tree.tsx`、`MessageList.tsx`、`ToolCall.tsx`、`MemoryCard.tsx` 等，均使用公开导出。
 - [BasicApp.tsx](assets/examples/BasicApp.tsx)：应用根、表单、设置、确认弹窗和 Toast。
 - [ChatPanel.tsx](assets/examples/ChatPanel.tsx)：消息、输入、发送/取消与流式响应，通过 `reply` 注入业务请求。
 - [ChatControls.tsx](assets/examples/ChatControls.tsx)：模型选择、单步/多步问答、工具活动和文件差异。

package/skill/assets/examples/ApprovalCard.tsx

@@ -0,0 +1,8 @@
+import { useState } from 'react';
+import { ApprovalCard } from 'auricui/agent';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [status,setStatus]=useState<'pending'|'approved'|'rejected'>('pending');
+  return <div style={{display:'grid',gap:16,width:'100%'}}><ApprovalCard title="发送这封邮件？" description="收件人：design@example.com" status={status} onApprove={()=>setStatus('approved')} onReject={()=>setStatus('rejected')}><p>主题：本周设计评审</p></ApprovalCard>{status!=='pending'&&<button type="button" onClick={()=>setStatus('pending')}>重新演示</button>}</div>;
+}

package/skill/assets/examples/BriefingCard.tsx

@@ -0,0 +1,8 @@
+import { useState } from 'react';
+import { BriefingCard } from 'auricui/agent';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [selected,setSelected]=useState('');
+  return <div style={{width:'100%'}}><BriefingCard title="早上好，hehuan" subtitle="今天有一些值得关注的小事。" items={[{id:'1',title:'产品设计评审',detail:'准备好你的三个关键问题',meta:'10:30',onSelect:()=>setSelected('产品设计评审')},{id:'2',title:'阅读计划',detail:'本周已经完成 2 天',meta:'20 分钟'}]} footer="根据你提供的日程与目标整理"/>{selected&&<p role="status" style={{fontSize:12,marginTop:12}}>已选择：{selected}</p>}</div>;
+}

package/skill/assets/examples/Checkbox.tsx

@@ -0,0 +1,13 @@
+import { useState } from 'react';
+import { Checkbox } from 'auricui';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [selected, setSelected] = useState(['notes']);
+  const items = [{ id: 'notes', label: '笔记' }, { id: 'files', label: '文件' }, { id: 'tasks', label: '任务' }];
+  return <div style={{ display: 'grid', gap: 14 }}>
+    <Checkbox label="选择全部资料" checked={selected.length === items.length} indeterminate={selected.length > 0 && selected.length < items.length} onCheckedChange={checked => setSelected(checked ? items.map(item => item.id) : [])} />
+    {items.map(item => <Checkbox key={item.id} label={item.label} checked={selected.includes(item.id)} onCheckedChange={checked => setSelected(checked ? [...selected, item.id] : selected.filter(id => id !== item.id))} />)}
+    <Checkbox label="受保护的内容" description="禁用的选项不能被修改。" disabled />
+  </div>;
+}

package/skill/assets/examples/Combobox.tsx

@@ -0,0 +1,14 @@
+import { useState } from 'react';
+import { Combobox } from 'auricui';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [value, setValue] = useState('shanghai');
+  return <div style={{ display: 'grid', gap: 14 }}><Combobox label="简报使用的时区" value={value} onValueChange={setValue} placeholder="搜索城市或时区…" options={[
+    { value: 'shanghai', label: '上海 · Asia/Shanghai' },
+    { value: 'tokyo', label: '东京 · Asia/Tokyo' },
+    { value: 'london', label: '伦敦 · Europe/London' },
+    { value: 'new-york', label: '纽约 · America/New_York' },
+    { value: 'custom', label: '自定义时区（未开通）', disabled: true },
+  ]} /><p role="status">已选择：{value}</p></div>;
+}

package/skill/assets/examples/Drawer.tsx

@@ -0,0 +1,10 @@
+import { useState } from 'react';
+import { Checkbox, RadioGroup, Textarea, Drawer, CardButton } from 'auricui';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [open, setOpen] = useState(false);
+  const [side, setSide] = useState<'left' | 'right' | 'top' | 'bottom'>('right');
+  const [enabled, setEnabled] = useState(true);
+  return <div style={{ display: 'grid', gap: 18 }}><RadioGroup label="打开方向" value={side} onValueChange={value => setSide(value as typeof side)} orientation="horizontal" options={[{ value: 'left', label: '左侧' }, { value: 'right', label: '右侧' }, { value: 'top', label: '顶部' }, { value: 'bottom', label: '底部' }]} /><CardButton onClick={() => setOpen(true)}>打开抽屉</CardButton><Drawer open={open} onOpenChange={setOpen} title="助手偏好" description="设置这个工作空间中的个人偏好。" side={side} footer={<CardButton weight="primary" onClick={() => setOpen(false)}>完成</CardButton>}><div style={{ display: 'grid', gap: 24 }}><Checkbox label="接收每日简报" checked={enabled} onCheckedChange={setEnabled} /><Textarea label="补充说明" placeholder="例如：早上 9 点前保持安静" /></div></Drawer></div>;
+}

package/skill/assets/examples/MemoryCard.tsx

@@ -0,0 +1,9 @@
+import { useState } from 'react';
+import { MemoryCard } from 'auricui/agent';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [content,setContent]=useState('我偏好简洁的回答，重要事项使用列表。');
+  const [forgotten,setForgotten]=useState(false);
+  return forgotten?<button type="button" onClick={()=>setForgotten(false)}>重新演示记忆</button>:<MemoryCard content={content} source="你的明确偏好" updatedAt="今天 09:00" onEdit={()=>setContent('我喜欢先看到结论，再阅读详细说明。')} onForget={()=>setForgotten(true)}/>;
+}

package/skill/assets/examples/MessageList.tsx

@@ -0,0 +1,8 @@
+import { useState } from 'react';
+import { MessageBubble, MessageList } from 'auricui/agent';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [count,setCount]=useState(8);
+  return <div style={{width:'100%'}}><MessageList>{Array.from({length:count},(_,i)=><MessageBubble key={i} role={i%2?'assistant':'user'}>第 {i+1} 条消息。向上滚动查看历史时，新增消息会保留你的阅读位置。</MessageBubble>)}</MessageList><button type="button" onClick={()=>setCount(count+1)}>追加消息</button></div>;
+}

package/skill/assets/examples/Theme.tsx

@@ -0,0 +1,14 @@
+import { useState } from 'react';
+import { AuricUIProvider, CardButton } from 'auricui';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [theme, setTheme] = useState<'dark' | 'light'>('dark');
+  return <AuricUIProvider theme={theme}>
+    <main style={{ background: 'var(--bg)', color: 'var(--text)', minHeight: '100vh', padding: 24 }}>
+      <CardButton onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+        切换到{theme === 'dark' ? '浅色' : '深色'}
+      </CardButton>
+    </main>
+  </AuricUIProvider>;
+}

package/skill/assets/examples/ToolCall.tsx

@@ -0,0 +1,8 @@
+import { useState } from 'react';
+import { ToolCall } from 'auricui/agent';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [done,setDone]=useState(false);
+  return <div style={{display:'grid',gap:16,width:'100%'}}><ToolCall name="search_documents" status={done?'success':'running'} defaultOpen input={'{"query": "设计规范"}'} output={done?'找到 3 份相关文档。':'正在检索…'}/><button type="button" onClick={()=>setDone(!done)}>{done?'重新演示':'模拟完成'}</button></div>;
+}

package/skill/assets/examples/Tree.tsx

@@ -0,0 +1,15 @@
+import { useState } from 'react';
+import { Tree } from 'auricui';
+import 'auricui/styles.css';
+
+export default function Example() {
+  const [selected, setSelected] = useState('guide');
+  return <div style={{ display: 'grid', gap: 16 }}><Tree label="知识库目录" value={selected} onValueChange={setSelected} defaultExpanded={['workspace']} nodes={[
+    { id: 'workspace', label: '工作空间', children: [
+      { id: 'guide', label: '使用指南.md' },
+      { id: 'projects', label: '项目', children: [{ id: 'auric', label: 'AuricUI.md' }, { id: 'ideas', label: 'Ideas.md' }] },
+      { id: 'locked', label: '已锁定资料', disabled: true },
+    ] },
+    { id: 'personal', label: '个人笔记', children: [{ id: 'reading', label: '阅读清单.md' }] },
+  ]} /><p role="status">已选择：{selected}</p></div>;
+}

package/skill/references/agent-components.md

@@ -0,0 +1,33 @@
+# Agent 与 Personal Agent
+
+基线：`0.1.0-preview.3`。从 `auricui/agent` 导入，CSS 仍只导入一次 `auricui/styles.css`。这些组件不依赖 Chat Provider 或模型 SDK；宿主传入数据、维护状态并实现回调。
+
+| 需求 | 组件 |
+| --- | --- |
+| 消息与滚动 | MessageBubble、MessageActions、MessageList、ResponseSwitcher |
+| 内容与引用 | CodeBlock、Citation、SourceList、ArtifactCard、AttachmentChip |
+| 输入辅助 | Suggestion、PromptTemplate、ContextUsage |
+| 执行状态 | ThinkingIndicator、ReasoningDisclosure、AgentStatus、ToolCall、TaskSteps、RunSummary、Checkpoint |
+| 会话与身份 | AgentCard、ConversationList |
+| 操作确认 | ApprovalCard |
+| 个人助手 | MemoryCard、GoalCard、ScheduleCard、ConnectorCard、ProactiveSuggestion、ActivityTimeline、AutonomyControl、BriefingCard |
+
+先查询真实契约，例如：
+
+```bash
+python3 <Skill目录>/scripts/inspect_api.py --entry agent --symbol ToolCall --project <前端目录>
+python3 <Skill目录>/scripts/inspect_api.py --entry agent --symbol MemoryCard --project <前端目录>
+```
+
+## 容易接错的行为
+
+- MessageList 只在用户位于底部时跟随新增内容；用户向上阅读时保留位置。传入稳定的消息 key，不用随机 key 重建消息。
+- ReasoningDisclosure 展示宿主提供的过程摘要，不生成模型内部思维链。ToolCall 的输入、输出、错误与执行状态也来自宿主。
+- CodeBlock 复制原始字符串，默认没有语法着色；需要时通过 `renderLine` 接入项目的高亮器。
+- Citation 仅接受 HTTP/HTTPS 来源，摘要使用 body Portal，支持 Escape、外部点击和视口边界。Portal 读取全局主题。
+- ResponseSwitcher 索引从 0 开始；Pagination 的页码从 1 开始。ContextUsage 容量未知时传入无效 limit，会展示未知而不是编造百分比。
+- ApprovalCard 的 `status` 来自应用；请求中传 `submitting`，完成后传 `approved` / `rejected`。回调不等同服务端授权。AutonomyControl 只是偏好选择器，权限仍由服务端执行。
+- ScheduleCard 只展示 timezone / nextRun 并通知开关变化，不创建定时任务。ConnectorCard 不实现 OAuth。MemoryCard 的编辑/忘记回调不自动修改存储。
+- ConversationList 的搜索值和筛选结果由宿主管理；PromptTemplate 字段和值受控，提交结果由应用消费。
+
+独立可复制示例位于 `assets/examples/`：MessageList、ToolCall、ApprovalCard、MemoryCard、BriefingCard。示例动作仅改变演示状态，接入应用时替换为实际回调。

package/skill/references/api-index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-preview.1",
+  "version": "0.1.0-preview.4",
   "entries": {
     "core": [
       {
@@ -7,6 +7,31 @@
         "kind": "runtime",
         "declaration": "dist/types/library/provider.d.ts"
       },
+      {
+        "name": "Avatar",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Avatar.d.ts"
+      },
+      {
+        "name": "AvatarProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Avatar.d.ts"
+      },
+      {
+        "name": "Breadcrumb",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Breadcrumb.d.ts"
+      },
+      {
+        "name": "BreadcrumbItem",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Breadcrumb.d.ts"
+      },
+      {
+        "name": "BreadcrumbProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Breadcrumb.d.ts"
+      },
       {
         "name": "Card",
         "kind": "runtime",
@@ -22,6 +47,16 @@
         "kind": "runtime",
         "declaration": "dist/types/components/Card.d.ts"
       },
+      {
+        "name": "Checkbox",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Checkbox.d.ts"
+      },
+      {
+        "name": "CheckboxProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Checkbox.d.ts"
+      },
       {
         "name": "ColorField",
         "kind": "runtime",
@@ -32,6 +67,21 @@
         "kind": "runtime",
         "declaration": "dist/types/components/ColorPicker.d.ts"
       },
+      {
+        "name": "Combobox",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Combobox.d.ts"
+      },
+      {
+        "name": "ComboboxOption",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Combobox.d.ts"
+      },
+      {
+        "name": "ComboboxProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Combobox.d.ts"
+      },
       {
         "name": "ConfirmDialog",
         "kind": "runtime",
@@ -72,11 +122,31 @@
         "kind": "runtime",
         "declaration": "dist/types/components/PaneDivider.d.ts"
       },
+      {
+        "name": "Drawer",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Drawer.d.ts"
+      },
+      {
+        "name": "DrawerProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Drawer.d.ts"
+      },
       {
         "name": "EdgeGlyph",
         "kind": "runtime",
         "declaration": "dist/types/components/inspector-fields.d.ts"
       },
+      {
+        "name": "EmptyState",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/EmptyState.d.ts"
+      },
+      {
+        "name": "EmptyStateProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/EmptyState.d.ts"
+      },
       {
         "name": "FIELD",
         "kind": "runtime",
@@ -192,6 +262,16 @@
         "kind": "runtime",
         "declaration": "dist/types/components/inspector-fields.d.ts"
       },
+      {
+        "name": "Pagination",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Pagination.d.ts"
+      },
+      {
+        "name": "PaginationProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Pagination.d.ts"
+      },
       {
         "name": "PaneDivider",
         "kind": "runtime",
@@ -207,6 +287,31 @@
         "kind": "runtime",
         "declaration": "dist/types/components/Card.d.ts"
       },
+      {
+        "name": "Progress",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Progress.d.ts"
+      },
+      {
+        "name": "ProgressProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Progress.d.ts"
+      },
+      {
+        "name": "RadioGroup",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/RadioGroup.d.ts"
+      },
+      {
+        "name": "RadioGroupProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/RadioGroup.d.ts"
+      },
+      {
+        "name": "RadioOption",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/RadioGroup.d.ts"
+      },
       {
         "name": "RadiusGlyph",
         "kind": "runtime",
@@ -317,6 +422,16 @@
         "kind": "runtime",
         "declaration": "dist/types/components/settings/ui.d.ts"
       },
+      {
+        "name": "Skeleton",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Skeleton.d.ts"
+      },
+      {
+        "name": "SkeletonProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Skeleton.d.ts"
+      },
       {
         "name": "SliderField",
         "kind": "runtime",
@@ -327,6 +442,31 @@
         "kind": "runtime",
         "declaration": "dist/types/components/inspector-fields.d.ts"
       },
+      {
+        "name": "TabItem",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Tabs.d.ts"
+      },
+      {
+        "name": "Tabs",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Tabs.d.ts"
+      },
+      {
+        "name": "TabsProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Tabs.d.ts"
+      },
+      {
+        "name": "Textarea",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Textarea.d.ts"
+      },
+      {
+        "name": "TextareaProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Textarea.d.ts"
+      },
       {
         "name": "Toast",
         "kind": "runtime",
@@ -347,6 +487,21 @@
         "kind": "runtime",
         "declaration": "dist/types/components/Tooltip.d.ts"
       },
+      {
+        "name": "Tree",
+        "kind": "runtime",
+        "declaration": "dist/types/components/primitives/Tree.d.ts"
+      },
+      {
+        "name": "TreeNode",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Tree.d.ts"
+      },
+      {
+        "name": "TreeProps",
+        "kind": "type",
+        "declaration": "dist/types/components/primitives/Tree.d.ts"
+      },
       {
         "name": "usePaneSize",
         "kind": "runtime",
@@ -2171,6 +2326,368 @@
         "kind": "runtime",
         "declaration": "dist/types/studio/components/WhatsNew.d.ts"
       }
+    ],
+    "agent": [
+      {
+        "name": "ActivityEvent",
+        "kind": "type",
+        "declaration": "dist/types/agent/ActivityTimeline.d.ts"
+      },
+      {
+        "name": "ActivityTimeline",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ActivityTimeline.d.ts"
+      },
+      {
+        "name": "ActivityTimelineProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ActivityTimeline.d.ts"
+      },
+      {
+        "name": "AgentCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/AgentCard.d.ts"
+      },
+      {
+        "name": "AgentCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/AgentCard.d.ts"
+      },
+      {
+        "name": "AgentState",
+        "kind": "type",
+        "declaration": "dist/types/agent/AgentStatus.d.ts"
+      },
+      {
+        "name": "AgentStatus",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/AgentStatus.d.ts"
+      },
+      {
+        "name": "agentStatusLabels",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/AgentStatus.d.ts"
+      },
+      {
+        "name": "AgentStatusProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/AgentStatus.d.ts"
+      },
+      {
+        "name": "ApprovalCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ApprovalCard.d.ts"
+      },
+      {
+        "name": "ApprovalCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ApprovalCard.d.ts"
+      },
+      {
+        "name": "ArtifactCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ArtifactCard.d.ts"
+      },
+      {
+        "name": "ArtifactCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ArtifactCard.d.ts"
+      },
+      {
+        "name": "AttachmentChip",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/AttachmentChip.d.ts"
+      },
+      {
+        "name": "AttachmentChipProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/AttachmentChip.d.ts"
+      },
+      {
+        "name": "AutonomyControl",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/AutonomyControl.d.ts"
+      },
+      {
+        "name": "AutonomyControlProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/AutonomyControl.d.ts"
+      },
+      {
+        "name": "AutonomyOption",
+        "kind": "type",
+        "declaration": "dist/types/agent/AutonomyControl.d.ts"
+      },
+      {
+        "name": "BriefingCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/BriefingCard.d.ts"
+      },
+      {
+        "name": "BriefingCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/BriefingCard.d.ts"
+      },
+      {
+        "name": "BriefingItem",
+        "kind": "type",
+        "declaration": "dist/types/agent/BriefingCard.d.ts"
+      },
+      {
+        "name": "Checkpoint",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/Checkpoint.d.ts"
+      },
+      {
+        "name": "CheckpointProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/Checkpoint.d.ts"
+      },
+      {
+        "name": "Citation",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/Citation.d.ts"
+      },
+      {
+        "name": "CitationProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/Citation.d.ts"
+      },
+      {
+        "name": "CodeBlock",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/CodeBlock.d.ts"
+      },
+      {
+        "name": "CodeBlockProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/CodeBlock.d.ts"
+      },
+      {
+        "name": "ConnectorCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ConnectorCard.d.ts"
+      },
+      {
+        "name": "ConnectorCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ConnectorCard.d.ts"
+      },
+      {
+        "name": "ContextUsage",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ContextUsage.d.ts"
+      },
+      {
+        "name": "ContextUsageProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ContextUsage.d.ts"
+      },
+      {
+        "name": "ConversationItem",
+        "kind": "type",
+        "declaration": "dist/types/agent/ConversationList.d.ts"
+      },
+      {
+        "name": "ConversationList",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ConversationList.d.ts"
+      },
+      {
+        "name": "ConversationListProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ConversationList.d.ts"
+      },
+      {
+        "name": "GoalCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/GoalCard.d.ts"
+      },
+      {
+        "name": "GoalCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/GoalCard.d.ts"
+      },
+      {
+        "name": "MemoryCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/MemoryCard.d.ts"
+      },
+      {
+        "name": "MemoryCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/MemoryCard.d.ts"
+      },
+      {
+        "name": "MessageAction",
+        "kind": "type",
+        "declaration": "dist/types/agent/MessageActions.d.ts"
+      },
+      {
+        "name": "MessageActions",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/MessageActions.d.ts"
+      },
+      {
+        "name": "MessageActionsProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/MessageActions.d.ts"
+      },
+      {
+        "name": "MessageBubble",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/MessageBubble.d.ts"
+      },
+      {
+        "name": "MessageBubbleProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/MessageBubble.d.ts"
+      },
+      {
+        "name": "MessageList",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/MessageList.d.ts"
+      },
+      {
+        "name": "MessageListProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/MessageList.d.ts"
+      },
+      {
+        "name": "ProactiveSuggestion",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ProactiveSuggestion.d.ts"
+      },
+      {
+        "name": "ProactiveSuggestionProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ProactiveSuggestion.d.ts"
+      },
+      {
+        "name": "PromptTemplate",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/PromptTemplate.d.ts"
+      },
+      {
+        "name": "PromptTemplateProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/PromptTemplate.d.ts"
+      },
+      {
+        "name": "PromptVariable",
+        "kind": "type",
+        "declaration": "dist/types/agent/PromptTemplate.d.ts"
+      },
+      {
+        "name": "ReasoningDisclosure",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ReasoningDisclosure.d.ts"
+      },
+      {
+        "name": "ReasoningDisclosureProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ReasoningDisclosure.d.ts"
+      },
+      {
+        "name": "resolvePromptTemplate",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/PromptTemplate.d.ts"
+      },
+      {
+        "name": "ResponseSwitcher",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ResponseSwitcher.d.ts"
+      },
+      {
+        "name": "ResponseSwitcherProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ResponseSwitcher.d.ts"
+      },
+      {
+        "name": "RunMetric",
+        "kind": "type",
+        "declaration": "dist/types/agent/RunSummary.d.ts"
+      },
+      {
+        "name": "RunSummary",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/RunSummary.d.ts"
+      },
+      {
+        "name": "RunSummaryProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/RunSummary.d.ts"
+      },
+      {
+        "name": "ScheduleCard",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ScheduleCard.d.ts"
+      },
+      {
+        "name": "ScheduleCardProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ScheduleCard.d.ts"
+      },
+      {
+        "name": "SourceItem",
+        "kind": "type",
+        "declaration": "dist/types/agent/SourceList.d.ts"
+      },
+      {
+        "name": "SourceList",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/SourceList.d.ts"
+      },
+      {
+        "name": "SourceListProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/SourceList.d.ts"
+      },
+      {
+        "name": "Suggestion",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/Suggestion.d.ts"
+      },
+      {
+        "name": "SuggestionProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/Suggestion.d.ts"
+      },
+      {
+        "name": "TaskStep",
+        "kind": "type",
+        "declaration": "dist/types/agent/TaskSteps.d.ts"
+      },
+      {
+        "name": "TaskSteps",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/TaskSteps.d.ts"
+      },
+      {
+        "name": "TaskStepsProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/TaskSteps.d.ts"
+      },
+      {
+        "name": "ThinkingIndicator",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ThinkingIndicator.d.ts"
+      },
+      {
+        "name": "ThinkingIndicatorProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ThinkingIndicator.d.ts"
+      },
+      {
+        "name": "ToolCall",
+        "kind": "runtime",
+        "declaration": "dist/types/agent/ToolCall.d.ts"
+      },
+      {
+        "name": "ToolCallProps",
+        "kind": "type",
+        "declaration": "dist/types/agent/ToolCall.d.ts"
+      }
     ]
   }
 }

package/skill/references/core-components.md

@@ -28,3 +28,17 @@
 设置面板可直接使用 [BasicApp.tsx](../assets/examples/BasicApp.tsx)。`SettingsDialog` 提供壳和页面导航，页面内容由应用提供。`SettingsModal` 是 `auricui/studio` 的专业业务设置页面，需要服务适配，不用于代替普通设置壳。
 
 通用浮层使用 `Popover` 包含 `Card` 或带 `POPOVER_CHROME` 的面板。不要从 npm 导入演示工程私有的 `Modal`；包中也没有通用 `Button` / `Input` 别名。列表、表格、路由等需求先查真实导出，缺失时用已有控件和原生语义元素组合，不要虚构组件。
+
+## preview.3 新增的基础组件
+
+以下现在是 `auricui` 的正式导出，不需要复制展示站的原生 HTML 配方：
+
+- Checkbox：原生表单属性、`label`、`indeterminate`、`onCheckedChange`；三态时由应用计算 `checked` 和 `indeterminate`。
+- RadioGroup：`options`、`value/defaultValue`、`onValueChange`；原生 radio 键盘与表单语义。
+- Drawer：受控 `open/onOpenChange`、四个 `side`、`size`、footer；body Portal、进出动画、焦点约束、焦点恢复和滚动锁。
+- Tree：稳定唯一的 node.id；`value/onValueChange` 与 `expanded/onExpandedChange` 独立控制；单选，支持方向键及键入查找。不提供异步加载、多选或虚拟化。
+- Combobox：`value/onValueChange`、`options`、`label`；客户端过滤与键盘选择。大列表或远端搜索需要宿主另行实现。
+- Tabs：items 包含 value/label/content；支持键盘切换，保留隐藏面板状态。
+- Textarea、Progress（无 value 时不定进度）、Skeleton、EmptyState、Avatar、Breadcrumb、Pagination。
+
+通过 `inspect_api.py --entry core --symbol Drawer` 等命令读取准确属性。可运行示例：`assets/examples/Drawer.tsx`、`Checkbox.tsx`、`Tree.tsx`、`Combobox.tsx`。使用 CSS 变量，不需要安装额外 headless 或动画库。

package/skill/references/dependencies.md

@@ -13,8 +13,10 @@
 | 富文本 | Lexical/@lexical/react/Yjs 由包依赖安装 | 按使用功能安装，Lexical各包版本一致 |
 | 动画 | 内置 CSS keyframes/transition | 移植原样式和触发逻辑 |
 
-脚本检查 React 主版本、清单与安装状态、React/DOM 一致性、包入口和传递依赖是否存在。它不完整求解 semver，也不检查每个依赖的实际运行兼容性；升级包后仍应运行项目类型检查和构建。`npm ls` 可进一步核验依赖树。
+脚本检查 React 主版本、清单与安装状态、React/DOM 一致性、根入口、agent/chat/studio 入口和传递依赖是否存在。它不完整求解 semver，也不检查每个依赖的实际运行兼容性；升级包后仍应运行项目类型检查和构建。`npm ls` 可进一步核验依赖树。
 
 源码模式显式传 `--mode source`，默认检查 React19、TS、Tailwind4、字体与图标；Vite工程检查插件。已有其他构建器保留其配置。scope包名可用 `--library-package @scope/name`。
 
 GSAP、Motion、Zustand 不为套用视觉而必装。依赖通过后人工确认全局 CSS、首屏主题、Chat Portal、原生动画/reduced-motion。消费方不得把技能检查通过等同于交互或视觉验收。
+
+当前成品包使用 Lucide 0.482.0。旧版 0.469.0 声明可能因 ReactSVG 类型报错，项目直接使用图标时请运行严格类型检查确认兼容；不要用 skipLibCheck 掩盖该错误。

package/skill/references/esm-package.md

@@ -2,21 +2,21 @@
 
 ## 版本与安装
 
-本文基线 `auricui@0.1.0-preview.1`，纯 ESM，入口为 `auricui`、`auricui/chat`、`auricui/studio`、`auricui/styles.css`。用户已提交 npm 发布并能看到包页面，但先前安装曾遇到 registry 可见性/缓存问题；每个目标环境以实际查询和安装结果为准。不要把网页可见当作目标版本可下载的证据。
+本文基线 `auricui@0.1.0-preview.3`，纯 ESM，入口为 `auricui`、`auricui/agent`、`auricui/chat`、`auricui/studio`、`auricui/styles.css`。该版本已通过本地 tarball 验证，尚未发布 npm；新增组件请使用附带包。远端命令仅在该版本实际发布后可用，先查询再安装。
 
 已有项目优先使用锁文件中的兼容版本；新项目可查询并锁定基线版本。沿用项目包管理器，以下为 npm 示例：
 
 ```bash
-npm view auricui@0.1.0-preview.1 version --registry=https://registry.npmjs.org/ --prefer-online
-npm install --save-exact auricui@0.1.0-preview.1 --registry=https://registry.npmjs.org/
+npm view auricui@0.1.0-preview.3 version --registry=https://registry.npmjs.org/ --prefer-online
+npm install --save-exact auricui@0.1.0-preview.3 --registry=https://registry.npmjs.org/
 ```
 
 仅当用户希望跟随预览渠道时用 `auricui@next`，`next` 会移动，不能假设永远对应本文基线。已有 React 19 项目复用其 React/DOM 版本；新建项目按框架要求安装两者。包的 peer 是 `^19.0.0`，未验证 React 18。
 
-离线或 registry 不可用时，可将 Skill 内 `assets/library/auricui-0.1.0-preview.1.tgz` 复制到目标项目 `vendor/`，再安装相对路径。它提供当前基线包本体，传递依赖仍需网络或缓存。不能把用户全局 Skill 的绝对路径写入项目依赖。校验摘要见 [library-manifest.json](library-manifest.json)。
+离线或 registry 不可用时，可将 Skill 内 `assets/library/auricui-0.1.0-preview.3.tgz` 复制到目标项目 `vendor/`，再安装相对路径。它提供当前基线包本体，传递依赖仍需网络或缓存。不能把用户全局 Skill 的绝对路径写入项目依赖。校验摘要见 [library-manifest.json](library-manifest.json)。
 
 ```bash
-npm install ./vendor/auricui-0.1.0-preview.1.tgz
+npm install ./vendor/auricui-0.1.0-preview.3.tgz
 ```
 
 ## 应用根

package/skill/references/library-manifest.json

@@ -1,11 +1,12 @@
 {
-  "file": "assets/library/auricui-0.1.0-preview.1.tgz",
+  "file": "assets/library/auricui-0.1.0-preview.4.tgz",
   "name": "auricui",
-  "version": "0.1.0-preview.1",
-  "sha256": "c402b48e7b26ce63e3bae23828feed202523dd1043ddc5abd2fe006e12efae68",
+  "version": "0.1.0-preview.4",
+  "sha256": "bf8b5548dc39f44b8f6ec41d7bc0af9b9904f38e198f22be68c3db4cee4be982",
   "format": "esm",
   "publication": {
-    "submitted": true,
-    "install_verified": false
+    "submitted": false,
+    "install_verified": true,
+    "verification": "local tarball, NodeNext types, ESM/SSR and browser build"
   }
 }

package/skill/references/theme-motion.md

@@ -19,3 +19,31 @@ Card 通常 radius=12px；CardButton 高28px、radius=8px。其他控件按自
 消费应用新增的布局和示例 `.auricui-example-*` 使用自有 CSS。只有启用应用的 Tailwind 构建时才新增相应 utility 类；包内现存类不保证覆盖将来随意写入的 utility。
 
 组件 CSS 含全局基础样式与通用变量，集成到旧站点先检查 body、字体、按钮和全局变量冲突。不要只用局部 wrapper 就宣称完整隔离。最终检查弹层继承、键盘 focus/Escape/外部点击、长文本和 reduced-motion。
+
+## 切换与自定义
+
+完整切换示例见 `assets/examples/Theme.tsx`。Provider 接受 `dark | light`，不自动保存偏好，也没有 `system` 值。需要系统主题时由宿主监听 matchMedia，并传入解析后的值。SSR 从 Cookie 等服务端信息得到初始值，同时写入 html 和 Provider，避免 hydration 与首屏颜色不一致。
+
+```tsx
+import 'auricui/styles.css';
+import './theme.css'; // 覆盖放在库样式之后
+```
+
+```css
+:root[data-theme='dark'],
+[data-theme='dark'] .auricui-chat {
+  --bg: #17181c;
+  --panel: #1d1e23;
+  --surface: #22232a;
+  --card-bg: var(--surface);
+  --text: #eeeef2;
+  --text-muted: #a5a7b3;
+  --accent: #c6bce8;
+  --accent-soft: rgba(198, 188, 232, .12);
+  --on-accent: #1d172d;
+}
+```
+
+Chat 自己声明变量，所以同时覆盖它的作用域；Provider 的 Chat layer 会匹配同一选择器。Drawer 和 Citation 挂在 body，局部 wrapper 变量不会跨 Portal；完整应用在 html 上配置主题。CardButton primary 的背景是 `--text`、文字是 `--panel`，不是 `--accent`；品牌按钮使用应用自己的 class，不改整页文本色。
+
+新增组件的统一动效变量：`--auricui-motion-fast:140ms`、`--auricui-motion-normal:220ms`、`--auricui-motion-slow:320ms`、`--auricui-ease-out:cubic-bezier(.2,.8,.2,1)`。覆盖影响使用该变量的动效，不替换原有所有 Chat/Studio 时长。系统 reduced-motion 自动降级。

package/skill/references/troubleshooting.md

@@ -20,7 +20,7 @@
 
 ```bash
 npm config get registry
-npm view auricui@0.1.0-preview.1 version --registry=https://registry.npmjs.org/ --prefer-online
+npm view auricui@0.1.0-preview.3 version --registry=https://registry.npmjs.org/ --prefer-online
 npm view auricui dist-tags --json --registry=https://registry.npmjs.org/ --prefer-online
 ```
 

package/skill/scripts/check_dependencies.py

@@ -62,7 +62,7 @@ def inspect(project, mode='package', library_package='auricui'):
             library = json.loads(location.read_text())
             base = location.parent
             exports = library.get('exports', {})
-            for key in ['.', './chat', './studio', './styles.css']:
+            for key in ['.', './agent', './chat', './studio', './styles.css']:
                 entry = exports.get(key)
                 paths = [entry] if isinstance(entry, str) else [entry.get('import'), entry.get('types')] if isinstance(entry, dict) else []
                 ok = bool(paths) and all(isinstance(p, str) and (base / p).is_file() for p in paths)
@@ -99,7 +99,8 @@ def main():
     else:
         print('AuricUI 依赖检查：' + result['project'])
         for item in result['checks']:
-            print(f"[{item['status']}] {item['package']}: {item.get('installed') or '未安装'} — {item['message']}")
+            version = f": {item.get('installed') or '未安装'}" if 'installed' in item else ''
+            print(f"[{item['status']}] {item['package']}{version} — {item['message']}")
         print('仍需人工检查：' + '；'.join(result['manual_checks']))
     return 0 if result['passed'] else 1
 

package/skill/scripts/inspect_api.py

@@ -8,7 +8,7 @@ from pathlib import Path, PurePosixPath
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--entry', choices=['core', 'chat', 'studio'], default='core')
+    parser.add_argument('--entry', choices=['core', 'chat', 'studio', 'agent'], default='core')
     parser.add_argument('--symbol')
     parser.add_argument('--file', help='Read a related declaration path, e.g. dist/types/chat/lib/question-types.d.ts')
     parser.add_argument('--project', type=Path)