# UDhold — 完整文档

> 站点: https://udhold.cn · 索引: https://udhold.cn/llms.txt

---

# LLMs.txt

来源: https://udhold.cn/docs/development/ai/llms-txt

[llms.txt](https://llmstxt.org) 是一个专为大型语言模型设计的站点索引文件，思路类似 `robots.txt`，但目标不同：robots.txt 告诉搜索引擎爬虫「什么能爬」，llms.txt 则为 AI 工具提供网站内容的结构化摘要，帮助它们更快、更准地理解和引用文档。

UDhold 开发文档已全量适配这一标准，并且**随文档更新自动同步**——你读到这篇指南时，AI 拿到的就是最新内容。

## 可用资源

| 地址 | 内容 | 适合场景 |
|------|------|----------|
| [https://udhold.cn/llms.txt](https://udhold.cn/llms.txt) | 全站结构化索引：每个文档页的标题、链接与一句话简介 | 加入工具的文档索引、让 AI 先知道「有什么」 |
| [https://udhold.cn/llms-full.txt](https://udhold.cn/llms-full.txt) | 全部文档的 Markdown 全文（含 plugin.json 契约、API 用法、完整示例代码） | 一次性投喂给 AI，或接入上下文知识库 |

本地开发调试时同样可访问：`http://localhost:7013/llms.txt`。

## 在 AI 工具中使用

### Cursor

1. 打开 `Settings` → `Indexing & Docs` → `Docs` → `Add doc`
2. 填入 `https://udhold.cn/llms-full.txt`，保存
3. 编码时用 `@Docs` 引用，例如：

```text
@Docs 按 UDhold 插件契约帮我生成一个「待办清单」插件的工程骨架，
包含 plugin.json、Vue 3 入口和一个待办列表页面。
```

### TRAE

1. 打开「设置」→「文档集」（或对话输入框的 `#Docs` 上下文）
2. 添加文档集，URL 填 `https://udhold.cn/llms-full.txt`
3. 对话时 `#` 选中该文档集即可引用

### Claude Code / Codex 等 CLI 编码代理

在项目（或全局）的 `AGENTS.md` / 规则文件里加一行指引，代理会在开发 UDhold 插件前主动抓取文档：

```markdown
## UDhold 插件开发

开发 UDhold 插件相关代码前，先读取 https://udhold.cn/llms-full.txt 了解
plugin.json 契约、权限模型与设计系统，再动手写代码。
```

### 网页版 AI 对话（Claude / ChatGPT 等）

- 支持联网的模型：直接把 `https://udhold.cn/llms-full.txt` 链接发给它，让它基于文档回答
- 不联网的模型：先打开 llms.txt 找到相关章节，把对应文档页内容粘贴进对话

### 其他工具

任何支持 llms.txt 标准或 URL 摄取的工具（知识库、RAG 管道、IDE 插件等）都可以直接使用上面两个地址，无需额外适配。

## 让 AI 写出能跑的插件

投喂文档只是第一步，提问方式决定产出质量：

- **先文档后代码**：让 AI 先通读 llms-full.txt 再动手，避免它按 uTools 或浏览器扩展的旧经验瞎编 API
- **点明两件事**：宿主方法统一返回 `IpcResult` 信封（失败不抛异常，要检查 `code`）；敏感能力必须在 `plugin.json` 的 `permissions` 里声明
- **要完整骨架**：让 AI 按「目录结构 → plugin.json → package.json → 入口文件」的顺序输出，与[快速上手](/docs/development/quick-start/getting-started)的工程结构对齐，生成后可直接进宿主调试

## 延伸阅读

- [llmstxt.org](https://llmstxt.org)：llms.txt 标准规范
- [快速上手](/docs/development/quick-start/getting-started)：跟着文档走一遍完整开发流程

---

# 基础样式类

来源: https://udhold.cn/docs/development/design-system/base-styles

`global.css` 除了设计令牌，还内置了一组高频控件的样式类。轻量插件直接写 class 就有合格的控件外观，不必引组件库、不必手写样式；重度界面则可以与组件库配合使用。

## 按钮

```html
<button class="btn">默认按钮</button>
<button class="btn btn-solid">主操作</button>
<button class="btn btn-danger">危险操作</button>
<button class="btn btn-sm">小尺寸</button>

<button class="icon-btn" title="复制">
  <span class="i-z-copy w-4 h-4" />
</button>
```

| 类 | 说明 |
|----|------|
| `.btn` | 中性按钮：内嵌底色 + 发丝线描边，hover 反馈 |
| `.btn-solid` | 主色实心，一屏最多出现一个（主操作） |
| `.btn-danger` | 危险色实心，用于删除等不可逆操作 |
| `.btn-sm` | 小尺寸修饰，可与上面任意组合 |
| `.icon-btn` | 28×28 透明图标按钮，配图标类使用 |

## 表单

```html
<input class="input" placeholder="请输入内容" />

<select class="select">
  <option value="a">选项 A</option>
  <option value="b">选项 B</option>
</select>

<label class="flex items-center gap-2 cursor-pointer">
  <input type="checkbox" class="toggle" v-model="enabled" />
  <span class="toggle-slider" />
  <span>开机自动同步</span>
</label>
```

| 类 | 说明 |
|----|------|
| `.input` | 文本输入框：`--field` 底色、聚焦时主色光圈（`--focus-ring`） |
| `.select` | 下拉框：与 `.input` 同构，原生弹出面板跟随系统明暗 |
| `.toggle` + `.toggle-slider` | 开关：checkbox 驱动，选中态主色。两个元素必须成对出现 |

## 卡片与浮层

```html
<div class="card p-4">
  <h3 class="text-sm font-medium">卡片标题</h3>
  <p class="text-xs text-[var(--ink-2)] mt-1">卡片说明文字</p>
</div>
```

| 类 | 说明 |
|----|------|
| `.card` | `--surface` 底色 + `--radius-lg` 圆角，内容区最常用的容器 |
| `.floating-shell` / `.floating-panel` | 无边框浮窗形态：大圆角 + 四周留边投影，做脱离宿主的悬浮小窗时使用 |

## 全局细节

这些是 `global.css` 顺手处理好的事，知道即可，不用自己做：

- **高度链**：`html`、`body`、`#app` 均为 `height: 100%`，插件根布局可以直接用百分比高度撑满。
- **正文排版**：`body` 上设定 14px / 1.5 倍行距 / `--ink` 文字色 / `--bg-color` 底色。
- **文本选中**：选中态是主色 22% 透明度，不再是默认的浏览器蓝。
- **键盘焦点**：`:focus-visible` 显主色焦点环（鼠标点击不显示，键盘导航才显示）。
- **滚动条**：6px 窄滚动条，圆角 thumb，hover 加深，track 透明——与宿主完全一致。

## 与 UnoCSS 配合

工程里配好 UnoCSS 后（见[图标体系](./icons)的完整配置），原子类与这组样式类可以混用：

```html
<div class="card p-4 flex items-center justify-between">
  <div>
    <p class="text-sm text-[var(--ink)]">自动保存</p>
    <p class="text-xs text-[var(--ink-2)] mt-0.5">每 30 秒同步一次</p>
  </div>
  <input type="checkbox" class="toggle" v-model="autoSave" />
  <span class="toggle-slider" />
</div>
```

::callout{icon="i-lucide-info" color="primary"}
`.toggle` 与 `.toggle-slider` 必须相邻（样式选择器是 `input:checked + .toggle-slider`），中间插别的元素开关就不动了。
::

控件之外还需要更复杂的组件（消息提示、确认弹窗、快捷键录制……）？看[通用组件](./components)。

---

# 通用组件

来源: https://udhold.cn/docs/development/design-system/components

`@udhold/udhold-ui` 是官方共享组件库，随官方插件工程仓库分发（`workspace:*` 引用，见[快速上手](../quick-start/getting-started)）。组件按需 import，没有全局注册，样式与令牌体系一体。

## 引入方式

```ts
// 组件
import { Message, ConfirmDialog, Dropdown, Slider } from '@udhold/udhold-ui/components/common'
// 或分别引：'@udhold/udhold-ui/components/Message'
// 组合式函数与工具
import { useMessage } from '@udhold/udhold-ui/components/common'
import { useColorScheme } from '@udhold/udhold-ui/composables'
```

## Message：全局消息提示

**挂载一次，全局调用。** 根组件里挂容器（`useMessage()` 返回的响应式状态接给组件），之后任何地方 `useMessage()` 直接弹消息：

```vue
<script setup lang="ts">
// App.vue —— 挂载容器
import { Message, ConfirmDialog, useMessage } from '@udhold/udhold-ui/components/common'
const { messageState, handleClose, handleAction, confirmState, handleConfirm, handleCancel } = useMessage()
</script>

<template>
  <div id="app"><!-- 页面内容 --></div>
  <Message :items="messageState" @close="handleClose" @action-click="handleAction" />
</template>
```

```ts
// 任何业务组件里
import { useMessage } from '@udhold/udhold-ui/components/common'

const message = useMessage()
message.success('已复制颜色 #2f6fec')
message.error('导出失败：文件被占用')
message.warning('列表已过期，正在刷新')
message.info('已切换到紧凑模式')
```

| 参数 | 说明 |
|------|------|
| `type` | `success` / `error` / `warning` / `info` / `primary`，对应语义前置圆点 |
| `duration` | 停留时长，默认 3000ms |
| `position` | `top` / `bottom` |

## ConfirmDialog：确认弹窗

与 `useMessage()` 同源，命令式调用，返回 Promise——不用自己管理弹窗状态：

```ts
const { confirm, confirmWithExtra, alert } = useMessage()

// 二选一确认
const ok: boolean = await confirm({
  title: '删除记录',
  message: '删除后不可恢复，确定删除这 3 条记录吗？',
  type: 'danger',          // info / warning / danger，控制确认按钮风格
  confirmText: '删除'
})
if (ok) { /* 执行删除 */ }

// 带附加复选项（如「同时删除云端数据」）
const result = await confirmWithExtra({
  title: '卸载插件',
  message: '将删除插件及其全部数据。',
  type: 'danger',
  extra: [{ id: 'keepData', message: '保留插件数据', defaultChecked: false }]
})
// result.confirmed: boolean, result.extra: { keepData: boolean }

// 纯提示（单按钮）
await alert({ title: '导入完成', message: '共导入 128 条记录。' })
```

容器同样在根组件挂一次：`<ConfirmDialog v-model:visible="confirmState.visible" ... />`，模板见上面 Message 的 App.vue 示例。

## Dropdown：下拉选择

原生 `select` 的样式化封装（弹出面板跟随系统明暗）：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Dropdown } from '@udhold/udhold-ui/components/common'

const sort = ref('time')
const options = [
  { label: '按时间排序', value: 'time' },
  { label: '按名称排序', value: 'name' }
]
</script>

<template>
  <Dropdown v-model="sort" :options="options" placeholder="选择排序方式" />
</template>
```

## HotkeyInput：快捷键录制

点击进入录制态，按下组合键即完成录入，支持修饰键组合（含 400ms 内双击同一修饰键，如 `Ctrl+Ctrl`）与 F1–F12：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { HotkeyInput } from '@udhold/udhold-ui/components/common'

const hotkey = ref('Ctrl+Alt+P')
</script>

<template>
  <HotkeyInput v-model="hotkey" placeholder="点击录制快捷键" />
</template>
```

优先走宿主后端录制（结果与全局快捷键注册系统一致），宿主不支持时自动回退前端按键监听；不支持的按键会以 toast 提示。

## Slider：滑杆

```vue
<Slider v-model="opacity" :min="30" :max="100" :step="5" :formatter="v => v + '%'" />
```

轨道已按主色渐变渲染，无需额外样式。

## DetailPanel：二级详情面板

覆盖在内容区上方的二级页面（无遮罩、带滑入过渡），配「返回」顶栏——列表页点进详情页的标准形态：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { DetailPanel } from '@udhold/udhold-ui/components/common'
const detailId = ref<string | null>(null)
</script>

<template>
  <Transition name="slide">
    <DetailPanel v-if="detailId" :title="'详情 #' + detailId" @back="detailId = null">
      <template #header-right>
        <button class="icon-btn"><span class="i-z-copy w-4 h-4" /></button>
      </template>
      <!-- 详情内容 -->
    </DetailPanel>
  </Transition>
</template>
```

组件自带 `slide` / `slide-reverse` 过渡类，供 `<Transition>` 做一级↔二级切换动画。

::callout{icon="i-lucide-info" color="primary"}
`DetailPanel` 内部使用 `i-z-back` 图标——你的工程图标集里必须有 `back.svg`（见[图标体系](./icons)），否则返回按钮空白。
::

## AdaptiveIcon：自适应位图图标

位图 logo 在暗色模式下会隐形的痛点，交给它处理：自动分析图片主色，需要时反色：

```vue
<AdaptiveIcon :src="provider.logo" alt="服务商图标" class="w-5 h-5" />
```

懒分析（进入视口前 100px 才开始），`forceAdaptive` 属性可跳过检测强制暗色反色。

## 工具函数

`@udhold/udhold-ui/utils` 里几个高频工具：

| 函数 | 用途 |
|------|------|
| `setupThemeSync()` | 主题联动总入口（[主题与明暗模式](./theming)） |
| `isDarkMode()` | 同步判断当前是否暗色 |
| `weightedSearch(items, query, fields)` | 多字段加权搜索：`fields` 里给每个字段配权重，命中累加按分数排序，做插件内列表过滤很好用 |
| `setupPlatformClass()` | 给 `html` 加 `os-windows` / `os-mac` / `os-linux` 类，CSS 里做平台差异适配 |

```ts
import { weightedSearch } from '@udhold/udhold-ui/utils'

const result = weightedSearch(commands, keyword, [
  { value: c => c.name, weight: 3 },
  { value: c => c.description, weight: 1 }
])
```

更高层的场景组件（加载态、搜索列表、代码块、侧边导航）看下一篇[场景组件](./scene-components)。

---

# 图标体系

来源: https://udhold.cn/docs/development/design-system/icons

UDhold 插件的图标方案是**本地 SVG 图标集 + UnoCSS**：图标文件放在自己工程里、离线可用、构建时内联、颜色自动跟随主题。这一章给出完整配置与用法。

## 图标跟随主题的原理

图标加载器会把 SVG 的 `fill` / `stroke` 替换成 `currentColor`：

```html
<!-- 你的 SVG：back.svg -->
<svg fill="#333" ...>...</svg>

<!-- 渲染结果 -->
<svg fill="currentColor" ...>...</svg>
```

于是图标的颜色 = 所在元素的 `color`。文字是 `var(--ink)`，图标就是 `--ink`；放在主色按钮里就是主色；暗色主题自动反色，零额外代码。

## 工程配置

**第一步**：SVG 图标放进 `src/assets/icons/`，文件名即图标名：

```
src/assets/icons/
├── back.svg
├── copy.svg
└── search.svg
```

**第二步**：`uno.config.ts` 注册图标集：

```ts
import { defineConfig, presetAttributify, presetWind3 } from 'unocss'
import presetIcons from '@unocss/preset-icons'
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { fileURLToPath, URL } from 'node:url'
import transformerDirectives from '@unocss/transformer-directives'

export default defineConfig({
  presets: [
    presetWind3(),
    presetAttributify(),
    presetIcons({
      collections: {
        // z 图标集：本插件 src/assets/icons 目录
        z: FileSystemIconLoader(
          fileURLToPath(new URL('./src/assets/icons', import.meta.url)),
          (svg: any) => {
            // fill/stroke 替换为 currentColor，跟随主题色
            return svg
              .replace(/(<svg.*?fill=)"(?!none)(.*?)"/, '$1"currentColor"')
              .replace(/(<svg.*?stroke=)"(?!none)(.*?)"/, '$1"currentColor"')
          }
        )
      },
      extraProperties: { display: 'inline-block', 'vertical-align': 'middle' }
    })
  ],
  transformers: [transformerDirectives()]
})
```

预设组合说明：

| 预设 | 作用 |
|------|------|
| `presetWind3` | Tailwind 风格原子类（`flex`、`p-4`、`text-sm`……） |
| `presetAttributify` | 属性化写法（`text="sm"` 等价 `text-sm`），按需启用 |
| `presetIcons` | 图标类支持 |
| `transformerDirectives` | 样式块里可用 `@apply` |

**第三步**：入口引入虚拟模块（通常脚手架已带）：

```ts
import 'virtual:uno.css'
```

## 使用

类名规则：`i-z-{文件名}`，尺寸用原子类控制：

```html
<span class="i-z-copy w-4 h-4" />
<span class="i-z-search w-5 h-5 text-[var(--ink-2)]" />
<button class="icon-btn"><span class="i-z-back w-4 h-4" /></button>
```

::callout{icon="i-lucide-info" color="primary"}
官方组件库的 `DetailPanel` 组件内部使用了 `i-z-back` 图标——使用它的插件，自己的图标集里必须包含 `back.svg`（文件名一致），否则返回按钮不显示。
::

## 位图图标的自适应

`logo.png`、第三方服务的图标等**位图**没有 `currentColor` 可言，暗色主题下深色图标会隐形。这种情况用组件库的 `AdaptiveIcon` 组件：它自动分析图片主色，在暗色模式下给深色图标做反色处理。用法见[通用组件](./components)。

另外，宿主有一套 `udhold-icon:` 资源协议用于指令图标；开发态直连 dev server 时需要在 `vite.config.ts` 里加 CSP 中间件放行该协议——工程模板（见[快速上手](../quick-start/getting-started)的 vite 配置）已包含这段配置。

## 插件 logo 规范

`plugin.json` 里的 `logo` 字段（png / jpg，放插件根目录，与 `plugin.json` 同级）：

- 建议正方形、透明底、256×256 以上；
- 它会出现在搜索结果、活动栏、插件中心、任务栏（分离窗口）等多个位置，过于细长的图会被压变形；
- 深色 logo 记得同时准备浅色环境下的表现，或直接用中性色系。

---

# 场景组件

来源: https://udhold.cn/docs/development/design-system/scene-components

场景组件（beautiful 系列）解决特定页面形态的问题：等待、检索、代码展示、多栏导航。它们与宿主的视觉语言同源，用对了插件气质立刻对味。

## LoadingState：加载态

像素风格的加载动画，三形态可选手式，内置耗时计时与减少动态偏好（`prefers-reduced-motion`）适配：

```vue
<script setup lang="ts">
import { LoadingState } from '@udhold/udhold-ui/components/beautiful'
</script>

<template>
  <LoadingState label="正在解析文件" variant="Dots" />
  <!-- variant: 'Drive'（波浪）| 'Dots'（圆点）| 'Orbit'（环绕） -->
</template>
```

**与 plugin.json 联动**：清单里的 `loading` 字段声明的就是这套视觉——

```json
{ "loading": { "variant": "Drive", "label": "加载中" } }
```

它解决的是 webview 创建到插件挂载 `#app` 之间的白屏期：宿主直接注入纯 CSS 版骨架，插件 mount 后自动消失，零接入成本。`LoadingState` 组件则用于插件**运行中**的异步等待场景（请求返回前的占位、切换数据源的过渡），两者互补。

## SearchList：搜索列表

带搜索框、空态、清空按钮的列表容器，输入即过滤（包含匹配），选中高亮动画：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { SearchList } from '@udhold/udhold-ui/components/beautiful'

const items = ['计算器', '颜色工具', 'JSON 工具', '正则编辑器']
const picked = ref('')
</script>

<template>
  <SearchList
    :items="items"
    placeholder="搜索工具…"
    :preview-count="5"
    empty-title="未找到结果"
    empty-hint="调整关键词重试"
    @select="picked = $event"
  />
</template>
```

| 参数 | 说明 |
|------|------|
| `items` | 字符串数组（复杂对象先用 `weightedSearch` 过滤出标签再传入） |
| `previewCount` | 无输入时默认展示的条数 |
| 空态 | 自定义 `empty-title` / `empty-hint` |

## CodeBlock：代码块

行号 + 复制按钮的代码展示，支持流式输出（AI 场景）：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { CodeBlock } from '@udhold/udhold-ui/components/beautiful'

const code = ref('const answer = 42')
</script>

<template>
  <CodeBlock :code="code" filename="answer.ts" language="ts" />
  <!-- 流式：传 visibleLines 数字，只渲染前 N 行并尾随光标 -->
</template>
```

## SidebarNav：分组侧边导航

分组侧栏（滑动高亮浮层、徽标、可选的工作区行 / 搜索框 / 主操作按钮）：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { SidebarNav } from '@udhold/udhold-ui/components/beautiful'

const active = ref('general')
const items = [
  { key: 'general', label: '通用' },
  { key: 'sync', label: '同步', section: '数据' },
  { key: 'backup', label: '备份', section: '数据', badge: '新' }
]
</script>

<template>
  <SidebarNav
    v-model:active="active"
    :items="items"
    workspace-title="当前空间"
    workspace-subtitle="my-workspace"
    new-label="新建"
    search-placeholder="过滤设置项…"
    embedded
    @new="onCreate"
    @search="onSearch"
  />
</template>
```

`items` 不带 `section` 的归入默认组「常用」；`embedded` 属性去掉卡片外壳，让导航融入你自己的容器。

## 取材与扩展

组件库的 `components/beautiful/raw/` 目录还保留着约 20 个**原始参考组件**（对话页、思维链状态、任务行、差异对比表、筛选表格等），它们是未受控的源码参考——带演示数据、不能直接 import。想用其中某个：

1. 从 `raw/` 复制到你的插件工程（或提 PR 受控化进组件库）；
2. 剥离演示数据，改造成 `props` / `emits` 驱动；
3. 样式里只消费设计令牌（缺失的令牌补到全局体系，不要在组件内写死色值）。

这套「受控化」流程与官方维护组件库的方式一致，改造后的组件在明暗主题下天然可用。

## 设计系统小结

到这里，令牌 → 主题 → 样式类 → 图标 → 组件的完整链路就走完了。回到你的插件：先把[快速上手](../quick-start/getting-started)的工程骨架搭起来，遇到界面问题再回到对应章节查参考。祝开发顺利！

---

# 主题与明暗模式

来源: https://udhold.cn/docs/development/design-system/theming

设计令牌的两套值（亮 / 暗）靠 `html` 上的 class 切换。这一章讲清楚切换机制，以及插件接入主题联动的标准做法。

## 切换机制

体系支持三条通道，优先级从高到低：

| 通道 | 触发方式 | 效果 |
|------|----------|------|
| 强制暗色 | `html.dark` | 应用整套暗色变量，`color-scheme: dark` |
| 强制亮色 | `html.light` | 应用亮色变量，`color-scheme: light` |
| 跟随系统 | 无 class | 按系统 `prefers-color-scheme` 自动切换 |

`color-scheme` 同时让原生控件（`<select>` 弹出面板、滚动条、表单底色）跟随主题，这是免费获得的一致性。

宿主设置里选「跟随系统 / 浅色 / 深色」时，会向所有 WebView 广播 `update-theme-info` 事件；主题色（六预设 + 自定义）与窗口透明度也走同一事件。

## 三步接入（工程型插件）

**第一步**，入口引入全局样式（设计令牌都在里面）：

```ts
import '@udhold/udhold-ui/styles/global.css'
```

**第二步**，入口调用一次 `setupThemeSync()`：

```ts
import { setupThemeSync } from '@udhold/udhold-ui/utils'

setupThemeSync() // 拉取宿主当前主题 + 监听后续变更，宿主不可用时静默降级
```

它做三件事：向宿主查询当前 `ThemeInfo` 立即应用；监听 `update-theme-info` 事件实时跟随；每次变更同步三样东西——`html.dark/light` class（明暗）、`body.theme-*` class 或内联 `--primary-color`（主题色）、`--window-opacity` / `--panel-opacity`（透明度）。

**第三步**，组件里需要感知明暗做逻辑分支时（比如给代码编辑器换主题），用 `useColorScheme`：

```vue
<script setup lang="ts">
import { computed } from 'vue'
import { useColorScheme } from '@udhold/udhold-ui/composables'

const { isDark } = useColorScheme()
const editorTheme = computed(() => (isDark.value ? 'vs-dark' : 'vs'))
</script>
```

`isDark` 是响应式的：宿主切换主题的瞬间自动更新。样式层面则不需要它——令牌本身就是双份的，跟着 class 自动切换。

## 免构建插件的做法

没有 npm 工程的静态插件拿不到 `setupThemeSync`，用宿主桥直接暴露的 API 等价实现：

```html
<script>
  // 初始快照：webview 创建时宿主注入
  const boot = window.__UDHOLD_BOOT__ || {}
  apply(boot.theme || {})

  // 跟随变更
  window.udhold.onThemeChange((theme) => apply(theme))

  function apply(info) {
    const dark = info.theme === 'dark'
      || (info.theme !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches)
    document.documentElement.classList.toggle('dark', dark)
    document.documentElement.classList.toggle('light', !dark)
  }
</script>
```

页面样式则按双通道写：

```css
body { background: #f1f2f3; color: #1f2124; }
html.dark body { background: #1c1d1f; color: #f2f3f4; }
```

## 主题色的正确用法

1. **永远用 `var(--primary-color)` 表达主色**，不要抄某个预设的色值——用户切到紫色主题时，写死的蓝色会立刻变得刺眼。
2. 选中、高亮、品牌氛围用派生令牌 `--primary-light-bg`（10% 底）与 `--primary-hover`（hover 加深）。
3. 红 / 绿 / 黄等结果语义用 `--danger-color` / `--success-color` / `--warning-color`，与主色区分开：主色表达「这是谁」，语义色表达「发生了什么」。

## 检查清单

上线前过一遍：

- [ ] 入口调用了 `setupThemeSync()`，宿主切明暗时插件实时跟随
- [ ] 样式里没有写死的颜色（搜一遍 `#` 开头的色值）
- [ ] 图片图标用 `currentColor` 或自适应反色（见[图标体系](./icons)与 [AdaptiveIcon](./components)）
- [ ] 暗色下检查过对比度：次级文字 `--ink-2` 在 `--surface` 上仍可读
- [ ] 原生控件（下拉、日期选择）没有突兀地保持亮色（确认没有显式设置 `color-scheme`）

接下来看[基础样式类](./base-styles)：按钮、输入框、开关这些高频控件，引完样式文件就能直接写 class 用。

---

# 设计令牌

来源: https://udhold.cn/docs/development/design-system/tokens

设计令牌（Design Tokens）是把设计决策沉淀为 CSS 变量的一套体系。插件只要消费这些变量而不是写死颜色值，就能自动获得明暗双主题、六种主题色、以及与宿主原生功能一致的视觉风格。

引入方式（一行）：

```ts
import '@udhold/udhold-ui/styles/global.css'
```

::callout{icon="i-lucide-info" color="primary"}
第一原则：**代码里不要出现写死的颜色值**。用 `var(--ink)` 而不是 `#1f2124`，用 `var(--line)` 而不是 `#ecedef`——写死的颜色在暗色主题下必然出错。
::

## 中性色板

中性色是设计系统的语义真相源，采用「表面四级 + 文字三级 + 线两级」的结构：

| 变量 | 亮色值 | 暗色值 | 用途 |
|------|--------|--------|------|
| `--surface` | `#ffffff` | `#232427` | 卡片、浮层等表面底色 |
| `--field` | `#f2f2f3` | `#2b2c2f` | 输入框、内嵌区域底色 |
| `--hover` | `#f4f5f6` | `#2a2b2e` | 悬停反馈底色 |
| `--inset` | `#f7f8f9` | `#1f2022` | 凹陷区域（代码块底、空态图标底） |
| `--canvas` | `#f1f2f3` | `#1c1d1f` | 画布底（低于 surface 的一级背景） |
| `--ink` | `#1f2124` | `#f2f3f4` | 主文字 |
| `--ink-2` | `#62656b` | `#a5a8ad` | 次级文字（说明、辅助信息） |
| `--ink-3` | `#6c6f75` | `#9a9da3` | 三级文字（占位符、禁用态） |
| `--line` | `#ecedef` | `#2e3033` | 分隔线 |
| `--line-strong` | `#e0e2e5` | `#3a3c40` | 强分隔线、控件描边 |

另有一组历史别名（`--bg-color`、`--card-bg`、`--text-color`、`--border-color` 等）映射到上表语义色，老插件零破坏，新代码建议直接用语义名。

## 语义色与状态色

场景语义色（成功 / 危险 / 警示三类高频语义）：

| 变量 | 亮色 | 暗色 |
|------|------|------|
| `--green` | `#189a4d` | `#3dbb72` |
| `--red` | `#d8353c` | `#f3616c` |
| `--orange` | `#e56d24` | `#f08a4b` |

交互状态色（按钮、提示、表单校验等场景）：

| 变量 | 亮色 | 暗色 |
|------|------|------|
| `--primary-color` | `#2f6fec` | `#4d8cf7` |
| `--danger-color` | `#d8353c` | `#f3616c` |
| `--warning-color` | `#f59e0b` | `#fbbf24` |
| `--success-color` | `#189a4d` | `#3dbb72` |
| `--highlight-color` | `#ea580c` | `#fb923c` |

`--primary-color` 不是常量：它随用户选择的主题色变化（见下节），所以**主色操作永远引用它**。

## 主题色

用户可以在宿主设置里切换六种预设主题色（蓝 / 紫 / 绿 / 橙 / 红 / 粉）或自定义颜色。实现方式是 `body` 上挂 `theme-blue` ~ `theme-pink` 类（自定义色则直接写内联 `--primary-color`），体系自动派生：

| 派生变量 | 生成规则 | 用途 |
|----------|----------|------|
| `--primary-hover` | 主色压暗 15% | 主色按钮 hover |
| `--primary-light-bg` | 主色 10% 透明度 | 选中态底色、标签底 |
| `--focus-ring` | `0 0 0 3px` 主色光圈 | 键盘焦点环 |

```css
/* 你的组件样式 */
.tag-active {
  background: var(--primary-light-bg);
  color: var(--primary-color);
}
```

## 圆角、阴影与动效

| 变量 | 值 | 用途 |
|------|----|------|
| `--radius-sm` | `6px` | 小控件（标签、开关） |
| `--radius-md` | `8px` | 按钮、输入框 |
| `--radius-lg` | `12px` | 卡片、弹窗 |
| `--shadow-hairline` | `0 0 0 1px var(--line)` | 发丝线描边（比 border 更细腻） |
| `--shadow-raised` | 亮 `0 12px 30px rgba(20,26,40,.14)` / 暗 `rgba(0,0,0,.5)` | 悬浮层投影 |
| `--ease-out` | `cubic-bezier(0.23, 1, 0.32, 1)` | 标准缓动 |
| `--duration-fast` | `120ms` | 快速反馈（hover、按压） |
| `--duration-mid` | `200ms` | 常规过渡（面板、弹层） |

## 字体

| 场景 | 字体栈 |
|------|--------|
| 正文 | `Inter, -apple-system, 'Segoe UI', 'Microsoft YaHei', 'PingFang SC', sans-serif`（系统栈，Windows 中文走雅黑、macOS 走苹方） |
| 代码 / 数值 | `var(--font-mono)` = `'JetBrains Mono', 'SF Mono', ui-monospace, Menlo, Consolas, monospace`（woff2 随组件库打包，按需加载） |

正文基础排版由 `global.css` 设定：`font-size: 14px`、`line-height: 1.5`，插件无需重复声明。

## 窗口不透明度变量（勿覆盖）

Windows 下宿主支持窗口透明度（亚克力材质），体系通过这组变量传递混合率：

- `--window-opacity` / `--panel-opacity`：由宿主写入；
- `--bg-color-base`：原始基色（亮 `#f7f7f8` / 暗 `#1d1e20`）；
- `--bg-color`：按不透明度混合后的实际背景色。

你的样式里页面底色用 `var(--bg-color)`、卡片用 `var(--surface)` 即可自动参与透明度合成。**不要覆盖这几个变量**，也不要在它们之上再做二次 `color-mix`。

## 用法示例

```vue
<style scoped>
.setting-row {
  padding: 10px 12px;
  border-radius: var(--radius-md);
  color: var(--ink);
}
.setting-row:hover {
  background: var(--hover);
}
.setting-row .desc {
  color: var(--ink-2);
  font-size: 12px;
}
</style>
```

配合 UnoCSS 时也可以直接写 `text-[var(--ink-2)]`、`bg-[var(--hover)]` 这类原子类。

下一节看[主题与明暗模式](./theming)：令牌的值是如何随宿主设置切换的，以及插件接入主题联动的三个步骤。

---

# 常见问题

来源: https://udhold.cn/docs/development/quick-start/faq

按「开发调试 / 权限与调用 / 界面与主题 / 打包与发布」四类整理。没找到答案的问题，欢迎通过[关于页面](/about)的联系方式反馈。

## 开发调试

### 改了代码，宿主里看到的还是旧界面？

九成是 dev server 的问题。宿主只在 dev server **可达**时才直连它，探测失败会静默回退加载本地 `dist` 产物：

1. 确认 `pnpm dev` 在跑，且端口与 `development.main` 一致（建议 vite 配 `strictPort: true`，防止 vite 端口被占后自己换端口）。
2. 在浏览器里直接开 `http://localhost:<端口>` 验证页面本身能访问。
3. 确认插件在「插件开发者」里处于运行调试登记态（宿主重启后登记失效，重新点一次「运行调试」）。
4. 如果确实在加载旧 `dist`，重新 `pnpm build` 更新产物。

### development.main 可以填局域网地址方便真机调试吗？

不行。出于安全考虑，`development.main` 只允许 `localhost` / `127.0.0.1` / `[::1]` 的 http(s) 地址，宿主会拒绝登记远程页面。

### 怎么在插件里打印日志排查？

普通 `console.log` 在 WebView 开发者工具里看（调试态宿主可右键插件页面打开 DevTools）；需要留痕的日志走宿主日志域 `udhold.log`，可在宿主的[调试日志](/docs/features/debug)面板统一查看。

### 插件页面一打开就白屏？

常见原因：构建产物路径不对（vite 没配 `base: './'`，产物用了绝对路径 `/assets/...`，在宿主 asset 协议下 404）；或 `dist` 字段指错了入口文件。免构建插件则检查 `index.html` 是否在插件根目录。

### dev server 启动很慢，宿主会不会超时？

「运行调试」轮询端口就绪有 90 秒超时，覆盖正常 `pnpm install` + 启动的时间。首次安装依赖较慢属正常，后续热启动都在秒级。

## 权限与调用

### 调用 API 返回 code 403 / PERMISSION_DENIED？

`permissions` 没声明或写错了。对照排查：

- 声明是**前缀匹配**：`files.list` 精确放行一个方法，`files.*` 放行整个域。
- 拼写以能力目录为准：方法路径必须与 API 文档一致（域.方法，如 `ai.models.list`）。
- 改了 `plugin.json` 后要**重开插件**让新权限生效。
- 存储类（`db` / `dbStorage`）、路由、生命周期等基础能力免声明；文件、剪贴板历史、AI、登录态等敏感域必须声明。

### 调用其他插件（router.push / plugin.run）被拒？

跨插件调用要在 `plugin.json` 的 `plugins` 数组里登记目标插件名：`"plugins": ["files", "calculator"]`；声明 `"*"` 放行全部（审核高风险，不推荐）。打开自己豁免白名单。

### 方法调用没有抛错但拿不到数据？

宿主方法统一返回 `IpcResult` 信封，失败也是正常 resolve。要检查 `res.code !== 0`（失败）与 `res.success === false`（业务分歧，非错误）两个分支，不能只 try/catch。

### 插件数据存在哪？卸载会清掉吗？

数据落在用户数据目录 `plugin-storage/<插件名>/` 下，各插件自动隔离，互不可见。**卸载插件默认连数据一起清空**；用户在插件中心手动卸载时可选择保留。禁用则完全保留数据，随时恢复。

## 界面与主题

### 插件没有跟随宿主的明暗主题？

工程型插件检查入口 `main.ts` 是否调用了 `setupThemeSync()`（来自 `@udhold/udhold-ui/utils`），并确认引入了 `@udhold/udhold-ui/styles/global.css`。免构建插件没有这套工具，需要监听宿主事件 `udhold.onThemeChange` 手动切换样式。完整机制见[主题与明暗模式](/docs/development/design-system/theming)。

### 图标显示不出来（i-z-xxx 类）？

`i-z-*` 图标类来自插件自己的本地 SVG 图标集，检查：

1. `uno.config.ts` 配了 `presetIcons` 且用 `FileSystemIconLoader` 把 `src/assets/icons` 注册为 `z` 集合；
2. SVG 文件名与类名一致（`i-z-back` 对应 `back.svg`）；
3. 使用 `DetailPanel` 组件的插件，图标集里必须有 `back.svg`（组件内部依赖它）。

配置方法见[图标体系](/docs/development/design-system/icons)。

### Message 消息弹不出来？

`Message` 与 `ConfirmDialog` 是「挂载一次、全局调用」的组件，确认根组件模板里挂了 `<Message :items="messageState" ... />`（`useMessage()` 返回的状态要接上），否则 `message.success(...)` 不会有任何显示。

### 用 React / 原生 JS 能开发吗？

可以。插件就是 Web 页面，框架不限（官方的 JSON Tools 就是 React 工程）。注意 `@udhold/udhold-ui` 的 Vue 组件不能直接用于 React，但其**设计令牌与全局样式**（`global.css`）和工具函数（`setupThemeSync` 等）是框架无关的，照常引入即可。

## 打包与发布

### 打包后的插件缺文件 / 样式丢了？

打包严格按 `plugin.json` 的 `build` 字段收录：`["dist"]` 就只有 dist 目录。检查：

- 是否先执行了 `pnpm build`（打的是当时的旧 dist）；
- 插件根目录的 `plugin.json` 与 `logo.png` 由打包器固定收进包根，无需进 `build` 数组；`src/` 里引用的其他静态资源要随构建一起进 dist（放 `src/assets` 或 Vite `public/` 均可）；
- 需要额外收录 `services[].entry` 等根目录文件时，把它们加进 `build` 数组。

### 上传市场后在哪里看审核状态？

在「插件开发者」的发布相关页面可以查看已上传版本与审核状态；审核未通过会附原因（多数是权限声明与实际功能不符）。

### 用户怎么收到新版本？

改 `plugin.json` 的 `version`（semver，比较大小决定是否更新）→ 构建打包 → 上传市场。已安装用户**打开插件时**宿主自动检查更新并静默完成安装，无需用户操作。

### 能不能先小范围发给别人测试？

可以，不走市场：打包 zip 直接发给对方，在插件中心「本地安装」导入即可。市场发布时也可以先选「测试」状态灰度，验证无误再转「正式」。

### 想让插件开机自启怎么做？

两种方式：纯后台场景在 `plugin.json` 声明 `"startup": "background"`（宿主启动完成后拉起无头实例，启动形式由插件自己编排）；带服务进程的插件把服务的 `startup` 设为 `"host"`（随宿主启动，不创建界面）。

---

# 快速上手

来源: https://udhold.cn/docs/development/quick-start/getting-started

这一章是一条完整的开发流水线：环境 → 创建工程 → 运行调试 → 调用能力 → 打包 → 发布。跟着做，20 分钟跑起你的第一个插件。

## 第 1 步：准备环境

| 依赖 | 要求 | 用途 |
|------|------|------|
| UDhold 桌面端 | 最新版，[下载安装](/#download) | 调试容器与打包发布都在宿主内完成 |
| Node.js | 20 LTS 或更高 | 工程型插件的构建工具链 |
| pnpm | 9+（`npm i -g pnpm`） | 官方插件工程的包管理器 |
| UDhold 账号 | 已登录 | 向导建项目、发布市场需要 |

::callout{icon="i-lucide-info" color="primary"}
只做**免构建静态插件**（纯 HTML）或全程用「插件开发者」向导的话，Node.js 可以先不装——UDhold 会用内置运行时代劳。要做工程型插件（Vue/React），再按下面步骤装。
::

装好宿主后，呼出主搜索框（默认 <kbd>Alt</kbd>+<kbd>Z</kbd>）输入「**插件开发者**」回车——这是 UDhold 内置的插件开发工作台，接下来的创建、调试、发布都在它里面完成。

### 安装 Node.js 和 npm

**npm 不用单独装**——它随 Node.js 安装包一起分发，装好 Node.js 就有了 npm。步骤：

1. 打开 Node.js 官网下载页：<https://nodejs.org/zh-cn/download>
2. 选择 **LTS 版本**（长期支持版，标绿的按钮），按操作系统下载安装包：

::tabs
:::tabs-item{label="Windows"}

下载 `*.msi` 安装包（如 `node-v22.x-x64.msi`），双击安装：

1. 一路「下一步」，默认会勾选 **Add to PATH**（自动配置环境变量）和 **npm components**，保持默认即可
2. 「Tools for Native Modules」页面可以不勾（插件开发用不到原生编译工具链）
3. 装完**重开一个终端窗口**（让 PATH 生效）

:::

:::tabs-item{label="macOS"}

两种方式任选：

- **官网安装包**：下载 `*.pkg` 双击，按提示安装
- **Homebrew**（已装 brew 的话更省事）：

```bash
brew install node@22
```

:::

:::tabs-item{label="Linux"}

推荐用 nvm 管理版本（免 sudo、可多版本切换）：

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# 重开终端后：
nvm install --lts
```

:::
::

3. 验证安装——打开终端（Windows 用 PowerShell），能打印出版本号即成功：

```bash
node -v   # v22.x.x 这样的输出（≥ v20 即满足要求）
npm -v    # 10.x 这样的输出
```

::callout{icon="i-lucide-info" color="primary"}
国内网络拉取 npm 包慢或超时，可切换国内镜像源（可选，仅影响下载速度）：

```bash
npm config set registry https://registry.npmmirror.com
```
::

### 安装 pnpm

工程型插件（见下面「方式三」）用 pnpm 管理依赖，任选一种方式安装：

::tabs
:::tabs-item{label="npm"}

```bash
npm install -g pnpm
```

:::

:::tabs-item{label="corepack"}

Node.js 自带 corepack（v16.13+），启用即得 pnpm：

```bash
corepack enable pnpm
```

:::

:::tabs-item{label="Homebrew"}

```bash
brew install pnpm
```

:::
::

验证：

```bash
pnpm -v   # 9.x 或更高
```

## 第 2 步：创建工程

三种方式任选：**CLI 脚手架一键创建**最快；**向导创建**适合快速起步和纯服务/静态插件；**手动搭建**适合理解每个文件、向官方插件仓库贡献插件。

### 方式一：CLI 脚手架一键创建（推荐）

装好 [Node.js](#安装-nodejs-和-npm) 后，用官方脚手架交互式生成完整插件框架：

::tabs
:::tabs-item{label="pnpm"}

```bash
pnpm add -g @udhold/plugin-cli
udhold create my-plugin
```

:::

:::tabs-item{label="npm"}

```bash
npm install -g @udhold/plugin-cli
udhold create my-plugin
```

:::
::

按提示完成四步：项目名 → 选模板（**Vue 3 + 设计系统**（推荐）/ **React + Vite** / **免构建静态 HTML**）→ 填插件信息（ID、标题、描述、作者）→ 自动生成工程。生成后进入工程目录 `pnpm install && pnpm dev`（静态模板免安装），直接跳到[第 3 步](#第-3-步运行调试)调试；dev 端口等细节在生成工程的 `plugin.json` 与 `vite.config` 中调整。

::callout{icon="i-lucide-info" color="primary"}
脚手架生成的工程是**独立目录**，不依赖官方仓库（`@udhold/udhold-ui` 等依赖来自 npm）。想向官方插件仓库贡献插件，把生成目录挪进 `udhold-plugin/plugins/` 下并把依赖改成 `workspace:*` 即可。
::

### 方式二：向导创建（推荐起步）

1. 在「插件开发者」的开发页点「**新建项目**」。
2. 填写插件标题、描述、简介，选择工程存放目录。
3. 选择插件形态，向导会生成对应的最小工程：

   | 形态 | 生成内容 |
   |------|----------|
   | 静态 HTML | `index.html` + `plugin.json`，免构建、零依赖 |
   | 页面 + Node 服务 | 页面 + `server.js` 后端（声明式 `services`） |
   | 页面 + Python 服务 | 页面 + Python 后端 |
   | 纯 Node 服务 | 只有后端，无界面（纯服务插件） |
   | 纯 Python 服务 | 同上 |

4. 需要登录：向导会先在市场登记插件条目（拿到全局唯一的插件 `name`），再落盘工程文件。
5. 完成后工程自动出现在工作台列表里，点「**运行调试**」即可看到插件跑起来。

::callout{icon="i-lucide-info" color="primary"}
向导生成的工程是独立目录，不依赖任何仓库。形态选错了不要紧——工程文件都是普通文件，随时可以改造成工程化开发。
::

### 方式三：手动搭建（Vue 3 + 官方设计系统）

官方插件（计算器、JSON Tools……）都在官方插件工程仓库里开发：仓库内置 `@udhold/udhold-ui` 组件库与 `@udhold/udhold-api-types` 类型包（见[开发者资源](/developers)），把你的插件放在 `udhold-plugin/plugins/` 下即可直接以 `workspace:*` 引用它们。

#### 2.1 目录结构

在 `udhold-plugin/plugins/` 下新建 `my-plugin/`：

```
my-plugin/
├── src/
│   ├── main.ts          # 入口
│   ├── App.vue          # 根组件
│   └── ...              # 你的页面与组件
├── dist/                # 构建产物（pnpm build 生成）
├── index.html           # Vite HTML 模板
├── logo.png             # 插件图标
├── plugin.json          # 插件清单（放插件根目录，与官方插件一致）
├── package.json
├── tsconfig.json
├── uno.config.ts
└── vite.config.ts
```

::callout{icon="i-lucide-info" color="primary"}
`plugin.json` 和 `logo.png` 放在**插件根目录**，不要放进 `public/`。打包时打包器会把 `plugin.json` 原文和 logo 固定收进安装包根目录，不依赖构建产物；放进 `public/` 只会让构建在 dist 里多出一份冗余副本。
::

#### 2.2 plugin.json

```json
{
  "name": "my-plugin",
  "title": "我的插件",
  "description": "一句话描述插件做什么",
  "author": "你的名字",
  "version": "1.0.0",
  "logo": "logo.png",
  "loading": { "variant": "Drive", "label": "加载中" },
  "permissions": [],
  "pluginSetting": {
    "slot": "workspace",
    "Detach": true,
    "Menu": true,
    "DesktopShortcut": true
  },
  "development": { "main": "http://localhost:5261" },
  "features": [
    {
      "code": "main",
      "explain": "我的插件主功能",
      "icon": "logo.png",
      "cmds": ["我的插件", "mypl"]
    }
  ],
  "dist": "dist/index.html",
  "build": ["dist"],
  "readme": "这里是插件详情页展示的完整介绍，支持 Markdown。"
}
```

常用字段速查（完整契约见类型包内的 schema）：

| 字段 | 说明 |
|------|------|
| `name` / `title` / `version` | 全局唯一标识 / 显示名 / semver 版本（更新的唯一判定来源） |
| `dist` | 构建产物入口；免构建插件直接写 `index.html` |
| `build` | 打包收录清单：`["dist"]` 只收 dist 目录；`["."]` 收整个插件根（自动排除 node_modules 等） |
| `development.main` | 开发态 dev server 地址，调试时宿主直连它（仅允许 localhost） |
| `pluginSetting.slot` | 面板槽位：`workspace`（工作区）/ `leftPanel` / `rightPanel` |
| `pluginSetting.Detach` | `true` 时打开即分离为独立窗口 |
| `pluginSetting.Menu` / `MenuBottom` | 进活动栏顶部 / 底部菜单 |
| `pluginSetting.SubSearch` | 分离窗口标题栏带搜索框（配合 `SubSearchPlaceholder`） |
| `features[].code` | 功能唯一标识，打开时作为启动参数回传给插件 |
| `features[].cmds` | 主搜索框关键词：字符串直接匹配（支持拼音、首字母）；对象可声明 `regex` / `over` / `img` / `files` / `window` 五种匹配规则 |
| `permissions` | 平台能力路径，如 `["files.list", "ai.*"]`，见[介绍](./introduction)的权限模型 |
| `tauri` | 原生能力标识，如 `["dialog:default", "notification:default"]` |
| `plugins` | 跨插件调用白名单 |
| `services[]` | 声明式服务进程（node / python / exe），配 `startup: "open" | "manual" | "host"` |
| `startup` | `"background"` 随宿主后台启动 |
| `exports` / `events` | 对外暴露接口与事件的声明（同时会作为 MCP 工具暴露） |
| `contextMenu[]` | Windows 资源管理器右键菜单注册 |

#### 2.3 package.json

```json
{
  "name": "@udhold-plugin/my-plugin",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "typecheck": "vue-tsc --noEmit"
  },
  "dependencies": {
    "vue": "^3.5.13",
    "@udhold/udhold-ui": "workspace:*",
    "@udhold/udhold-api-types": "workspace:*"
  },
  "devDependencies": {
    "@iconify/utils": "^3.1.0",
    "@unocss/preset-attributify": "^66.6.6",
    "@unocss/preset-icons": "^66.6.6",
    "@unocss/transformer-directives": "^66.6.6",
    "@vitejs/plugin-vue": "^5.2.1",
    "typescript": "~5.6.2",
    "unocss": "^66.6.6",
    "vite": "^6.0.3",
    "vue-tsc": "^2.1.10"
  }
}
```

`tsconfig.json` 里加上类型包，`window.udhold.*` 就有完整代码提示：

```json
{
  "compilerOptions": {
    "types": ["@udhold/udhold-api-types"]
  }
}
```

#### 2.4 vite.config.ts

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import UnoCSS from 'unocss/vite'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  base: './',
  // 端口自定义，避开常用端口即可；strictPort 防止 vite 自行换端口导致宿主连不上
  server: { port: 5261, strictPort: true, open: false },
  plugins: [
    vue(),
    UnoCSS(),
    {
      // 与内置插件对齐：允许 file:/udhold-icon: 资源源（指令图标协议）
      name: 'configure-response-headers',
      configureServer: (server) => {
        server.middlewares.use((_req, res, next) => {
          res.setHeader(
            'Content-Security-Policy',
            "default-src * 'unsafe-inline' 'unsafe-eval' data: blob: udhold-icon: file:; img-src * data: blob: udhold-icon: file:;"
          )
          next()
        })
      }
    }
  ],
  resolve: {
    optimizeDeps: { exclude: ['@udhold/udhold-ui'] },
    ssr: { noExternal: ['@udhold/udhold-ui'] },
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})
```

> `@udhold/udhold-ui` 是源码直引包（无预构建产物），必须保留 `optimizeDeps.exclude` 与 `ssr.noExternal` 两项配置，否则 Vite 依赖预扫描会报错。

#### 2.5 src/main.ts 与 src/App.vue

```ts
import { createApp } from 'vue'
import App from './App.vue'
import 'virtual:uno.css'
import '@udhold/udhold-ui/styles/global.css'
import { setupThemeSync } from '@udhold/udhold-ui/utils'

// 应用宿主主题（明暗 + 主题色），并注册后续变更监听
setupThemeSync()

createApp(App).mount('#app')
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Message, ConfirmDialog, useMessage } from '@udhold/udhold-ui/components/common'

const { messageState, handleClose, handleAction, confirmState, handleConfirm, handleCancel } = useMessage()
const count = ref(0)
</script>

<template>
  <div class="p-4">
    <h1 class="text-base text-highlighted">我的插件</h1>
    <button class="btn-solid" @click="count++">点了 {{ count }} 次</button>
  </div>

  <!-- 全局消息与确认弹窗，挂一次即可全局使用 -->
  <Message :items="messageState" @close="handleClose" @action-click="handleAction" />
  <ConfirmDialog
    v-model:visible="confirmState.visible" v-model:extra-values="confirmState.extraValues"
    :title="confirmState.title" :message="confirmState.message" :type="confirmState.type"
    :confirm-text="confirmState.confirmText" :cancel-text="confirmState.cancelText" :extra="confirmState.extra"
    @confirm="handleConfirm" @cancel="handleCancel"
  />
</template>
```

样式与组件的完整用法见[设计系统](/docs/development/design-system/tokens)系列文档。

## 第 3 步：运行调试

1. 工程目录里启动 dev server：`pnpm dev`（向导创建的工程在「插件开发者」里点「运行调试」会自动完成安装依赖、启动、登记全流程）。
2. 在「插件开发者」工作台选中工程，点「**运行调试**」。宿主会登记该工程并以 `development.main` 的地址直连 dev server——**改代码即时热更新（HMR），不用重启宿主**。
3. 呼出主搜索框，输入你在 `cmds` 里声明的关键词（如「我的插件」），回车打开插件。

调试要点：

- `development.main` 只允许 `http://localhost:*` / `127.0.0.1` 地址（安全限制，防远程页面注入）。
- dev server 没启动时，宿主探测不到端口会**回退加载本地 dist 产物**——如果你看到的是旧界面，先确认 dev server 是否在跑、端口是否与 `development.main` 一致。
- 「运行调试」的登记关系存在内存里，宿主重启后失效，重新点一次即可。
- 免构建工程（无 `development.main`）以「链接」语义直接加载工程目录里的文件。

## 第 4 步：调用宿主能力

大多数宿主方法返回统一信封 `IpcResult<T>`：`{ code, success, data, msg }`。`code !== 0` 即失败（403 = 权限未声明），失败**不会抛异常**，要靠检查 `code`：

```ts
// 基础能力（免权限声明）
udhold.dbStorage.setItem('launchCount', String((Number(udhold.dbStorage.getItem('launchCount')) || 0) + 1))
udhold.shellOpenExternal('https://udhold.cn')
await udhold.copyText('已复制的内容')

// 敏感能力：先在 plugin.json 声明 permissions，再按信封处理结果
const res = await udhold.clipboard.getHistory(1, 20)
if (res.code !== 0) {
  console.error('调用失败：', res.msg)   // 403 → 检查 permissions 声明
} else {
  console.log('历史条目：', res.data)
}
```

**启动参数**：用户从搜索框打开插件时，命中的 feature 的 `code` 会回传；跳转方通过 `router.push` 传的 `query` 也在其中。在生命周期钩子里读取：

```ts
udhold.plugin.onMounted((action) => {
  // action.code：命中的 feature 标识（缺省 'main'）
  // action.payload：启动参数（即 router.push 的 query）
  // action.from：唤起来源 main / panel / hotkey / redirect / workflow / api
  if (action.code === 'convert') {
    const input = action.payload?.text ?? ''
    // ...
  }
})
```

**清理时机**：定时器、文件监听、服务进程一律在 `onBeforeUnmount` 里释放（宿主销毁前给 200ms 宽限）：

```ts
const off = udhold.plugin.onBeforeUnmount(() => {
  clearInterval(timer)
})
```

## 第 5 步：打包与本地验证

1. 构建产物。在插件工程目录执行：

   ```bash
   pnpm build
   ```

   产出 `dist/` 目录。
2. 打包规则由 `plugin.json` 的 `build` 字段决定：`["dist"]` 只收录 dist 目录；缺省时收录整个插件根（自动排除 `node_modules`、`.git` 等）。`plugin.json` 与 `logo` 会固定打进包根。
3. 在「插件开发者」的发布页选中工程，一键打包为 `my-plugin-v1.0.0.zip`。
4. 本地验证：把 zip 发给测试者，在插件中心选「本地安装」导入（也支持双击安装），检查真实安装态下的表现。

::callout{icon="i-lucide-info" color="primary"}
免构建静态插件没有构建环节，`build` 声明 `["."]` 或留空即可，发布页会直接按目录打包。
::

## 第 6 步：发布市场

1. 确保已登录 UDhold 账号，且插件已在市场登记（向导创建建项目时自动完成；CLI 与手动搭建在发布页先「登记」）。
2. 发布页上传 zip 包，填写版本说明，选择上架状态（先「测试」再转「正式」是常见的灰度节奏）。
3. 等待审核：审核重点包括 `permissions` 与实际功能是否匹配、`plugins: ['*']` 等高风险声明、导出接口是否构成权限泄漏。
4. 审核通过即上架，全平台用户可在插件市场搜到。
5. 发新版本：改 `plugin.json` 的 `version` → 重新构建打包 → 上传。已安装用户**打开插件时宿主自动检查并静默更新**，无需手动催更。

## 接下来

功能逻辑跑通了，就该打磨界面了。去看[设计系统](/docs/development/design-system/tokens)：一套设计令牌 + 现成组件，让你的插件和 UDhold 原生功能长得像一家人。想用 Cursor、Claude 等 AI 工具辅助编码，看 [LLMs.txt](/docs/development/ai/llms-txt)；卡住了先翻[常见问题](./faq)。

---

# 介绍

来源: https://udhold.cn/docs/development/quick-start/introduction

这一章回答三个问题：插件在 UDhold 里是什么、能做成什么形态、能调用哪些能力。读完你就能判断自己的点子适不适合做成插件，该做成哪种形态。

## 插件是什么

UDhold 宿主基于 Tauri 2 构建。每个插件打开时，宿主会为它创建一个独立的 WebView（网页容器），加载插件声明的前端页面；插件与宿主之间通过注入的 `window.udhold` 桥对象通信。

```
┌─────────────── UDhold 宿主（Tauri 2 / Rust）───────────────┐
│  主面板（活动栏 / 左侧面板 / 工作区 / 右侧面板）            │
│  ┌────────────┐  ┌──────────────────┐  ┌────────────┐    │
│  │ 插件 A      │  │ 插件 B（你的插件） │  │ 插件 C      │    │
│  │ WebView     │  │ WebView          │  │ 服务进程    │    │
│  └────────────┘  └────────┬─────────┘  └────────────┘    │
│                           │ window.udhold（桥 + 权限网关） │
│  文件 / 剪贴板 / 数据库 / AI / 系统命令 ……（26 个能力域）   │
└──────────────────────────────────────────────────────────┘
```

插件工程的唯一契约是根目录的 `plugin.json`——名字、入口、面板槽位、搜索关键词、权限需求全部声明在这一个文件里，宿主按声明加载与管控。清单体系兼容 uTools 插件协议，熟悉 uTools 开发的开发者可以无缝迁移。

## 插件的四种形态

| 形态 | 构成 | 典型例子 | 适合场景 |
|------|------|----------|----------|
| **页面插件** | 前端工程（Vue / React / 纯 HTML），构建出静态产物 | 计算器、JSON Tools、待办清单 | 有界面的工具 |
| **免构建静态插件** | 一个 `index.html` + `plugin.json`，无需 Node 工程 | 简单的小工具页 | 轻量工具、快速验证想法 |
| **纯服务插件** | 只有 `services[]` 声明（Node / Python / exe），没有界面 | 后台服务、绿色软件封装 | 无界面的后台能力 |
| **页面 + 服务** | 前端页面 + 声明式服务进程 | 需要本地后端的复杂插件 | 本地数据库、爬虫、编译类工具 |

页面插件还可以通过 `pluginSetting` 进一步定制形态：嵌入工作区面板、挂在左右侧栏、打开即分离成独立窗口（`Detach`）、进活动栏顶部/底部菜单（`Menu` / `MenuBottom`）等，详见[快速上手](./getting-started)的清单字段说明。

## 能调用哪些能力

插件通过 `window.udhold` 调用宿主能力，共 26 个命名空间、200 多个方法。常用的能力域：

| 能力域 | 说明 | 示例调用 |
|--------|------|----------|
| `db` / `dbStorage` / `dbCryptoStorage` | 文档数据库 / 键值存储 / 加密键值存储，数据自动按插件隔离 | `udhold.dbStorage.setItem('k', 'v')` |
| `plugin` / `router` / `route` | 插件运行时：生命周期钩子、跨插件调用、tab 操作 | `udhold.router.push('files')` |
| `files` | 文件资源管理：列举、新建、重命名、删除、批量复制、监听 | `udhold.files.list('D:\\')` |
| `clipboard` | 剪贴板历史与读写 | `udhold.copyText('文本')` |
| `ai` / `ai.models` | 大模型推理（流式）、模型配置 | `udhold.ai({ model, messages })` |
| `system` / `shell` | 系统命令、通知、打开文件/网址 | `udhold.shellOpenExternal(url)` |
| `search` | 唤起全局搜索框 | `udhold.search.openWithKeyword('kw')` |
| `setting` | 宿主外观与行为配置 | `udhold.setting.setTheme('dark')` |
| `udbrowser` | 内嵌浏览器自动化（打开页面、点击、取数） | `udhold.udbrowser.create()` |
| `service` / `node` | 拉起并管理本地服务进程 | `udhold.service.spawn(cfg)` |
| `user` / `sync` / `netdisk` | 登录态、WebDAV 同步、简盘 | `udhold.user.isLogin()` |

除了直接调用，插件还能通过 `exports` + `registerTool` **对外暴露接口**供其他插件（以及宿主的 MCP 服务）调用，形成插件间的协作生态。

## 权限模型

UDhold 采用三层声明式权限：用到什么，就在 `plugin.json` 里声明什么，未声明的调用会被宿主权限网关拒绝（返回 `PERMISSION_DENIED`）。

| 声明字段 | 管什么 | 示例 |
|----------|--------|------|
| `permissions[]` | 平台能力路径：敏感域（文件、剪贴板历史、AI、登录态等）必须声明；存储、路由等基础能力免声明 | `"permissions": ["files.list", "ai.*"]` |
| `tauri[]` | 原生能力：对话框、通知、文件选择器等 | `"tauri": ["dialog:default"]` |
| `plugins[]` | 跨插件调用白名单：要 `push` / `invoke` 其他插件，先在这里登记目标插件名 | `"plugins": ["files"]` |

通配符只支持后缀：`user.*` 放行整个 user 域，`ai.models.list` 精确到单个方法。不要声明 `"*"`（全量授权，市场审核时视为最高风险）。

## 生命周期

插件实例有 12 个生命周期钩子，覆盖从打开到销毁的完整过程：

```ts
udhold.plugin.onMounted((action) => {})     // 页面就绪，action.code 区分被哪个 feature 唤起
udhold.plugin.onActivated((p) => {})        // tab 切入
udhold.plugin.onDeactivated((p) => {})      // tab 被切走
udhold.plugin.onDetached((p) => {})         // 分离成独立窗口
udhold.plugin.onAttached((p) => {})         // 从独立窗口回归面板
udhold.plugin.onBeforeUnmount((p) => {})    // 实例销毁前（唯一清理时机，宿主等 200ms）
udhold.plugin.onShow((p) => {})             // 获得焦点
udhold.plugin.onBlur((p) => {})             // 失去焦点
udhold.plugin.onMinimized((p) => {})        // 承载窗口最小化
udhold.plugin.onRestored((p) => {})         // 承载窗口还原
udhold.plugin.onAppLaunched((p) => {})      // 宿主启动（粘性）
udhold.plugin.onAppBeforeQuit(() => {})     // 宿主退出前
```

所有钩子返回取消函数，可多次注册叠加。`onMounted` 的 `action.from` 能区分唤起来源（主输入框 `main`、面板 `panel`、快捷键 `hotkey`、其他插件跳转 `redirect` 等）。

## 分发方式

- **插件市场**：在「插件开发者」里一键打包上传，审核通过后全平台用户可搜可装；已装用户打开插件时宿主自动检查更新。
- **本地安装包**：打包为 `.zip`，可以发给朋友双击安装，或在插件中心手动安装，适合内部分发与灰度测试。

## 开发前的准备

| 需要 | 说明 |
|------|------|
| UDhold 桌面端 | 调试与打包都在宿主里完成，[下载](/#download)安装 |
| HTML / CSS / JavaScript 基础 | 插件本质是 Web 页面；推荐用 Vue 3（官方插件与组件库同栈，生态最顺） |
| Node.js 20+ 与 pnpm | 工程型插件需要；纯静态插件可跳过 |
| 一个想法 | 从自己每天会重复做的小事开始，最容易做出好插件 |

准备好了？进入[快速上手](./getting-started)，20 分钟跑起你的第一个插件。

---

# 功能总览

来源: https://udhold.cn/docs/features

UDhold 自带的核心能力都是插件，和第三方插件用同一套机制。下面是主要内置功能，点链接看详细说明。

## 搜索与启动

| 功能 | 干什么 |
|------|--------|
| [快速启动](/docs/features/quick-start) | 搜索框搜应用、拼音、指令，快速启动 |
| [系统命令](/docs/features/system) | 截图、取色、锁屏、关机、打开网址等系统级指令 |
| [本地启动](/docs/features/local-launch) | 管理常用的应用、文件、文件夹启动项 |

## 文件

| 功能 | 干什么 |
|------|--------|
| [文件资源管理器](/docs/features/files) | 多分栏多标签的文件管理器 |
| [文件树](/docs/features/files-tree) | 左侧目录树导航，含收藏夹和最近访问 |
| [文件预览](/docs/features/preview) | 双击文件直接看文本和图片，可编辑保存 |
| UD 简盘 | 云盘客户端：云端文件浏览、上传下载 |

## 插件管理

| 功能 | 干什么 |
|------|--------|
| [插件中心](/docs/features/plugins) | 管理已装插件，浏览和安装插件市场的新插件 |

## 快捷键

| 功能 | 干什么 |
|------|--------|
| [快捷键](/docs/features/shortcuts) | 全局指令与多指令快捷键，一键触发指令 |

## 设置与其他

| 功能 | 干什么 |
|------|--------|
| [设置](/docs/features/settings) | 主题、开机自启、悬浮球、网络等通用配置 |
| 账户 | 登录 / 登出、登录态展示、个人资料编辑 |
| [关于](/docs/features/about) | 版本信息、检查更新、跨平台差异和数据迁移 |
| [调试日志](/docs/features/debug) | 查看运行日志，排查问题 |

## AI

| 功能 | 干什么 |
|------|--------|
| [AI 助手](/docs/features/ai-helper) | 内置 AI 对话窗口，多会话、多模型、图片识别 |
| [AI 模型](/docs/features/ai-models) | 按服务商配置大语言模型，支持 OpenAI / Claude / Gemini 格式 |

需要更多能力，去 [插件中心](/docs/features/plugins) 的市场里找第三方插件。

---

# 关于

来源: https://udhold.cn/docs/features/about

「关于」是一个独立的小窗口，展示 UDhold 的版本和运行环境信息。

## 打开方式

主面板顶部菜单栏点「帮助 → 关于 UDhold」。

窗口里能看到：

- 当前 UDhold 的版本号
- 内核版本（系统 WebView 内核）
- 操作系统信息

## 检查更新

UDhold 启动时会自动检查是否有新版本。发现新版本时，搜索框右侧显示「新版本已下载，点击升级」绿色提示条；点击提示确认，下载完成后自动唤出安装界面。

也可以手动触发：

- 系统托盘图标右键 →「检测更新」
- 主面板顶部菜单栏「帮助 → 检测更新」

### 更新机制

更新直接下发对应平台的完整安装包（Windows 为 exe，macOS 为 dmg），下载完成后自动唤出安装界面，按提示装完即完成升级，用户数据不会丢失。

::tip
如果自动更新失败，可手动到 UDhold 官网下载最新版覆盖安装，用户数据不会丢失。
::

## 跨平台差异

| 功能 | macOS | Windows |
|------|-------|---------|
| 全局快捷键 | `Option+Z`（默认） | `Alt+Z`（默认） |
| 系统终端 | Terminal / iTerm | CMD / PowerShell |
| 资源管理器 | Finder | 资源管理器（explorer.exe） |
| 文件路径 | `/Users/...` | `C:\Users\...` |
| 右键菜单 | 系统原生 | 系统原生（含第三方扩展） |

## 数据备份与迁移

UDhold 的所有用户数据存放在以下位置：

- **Windows**：`%APPDATA%\UDhold\`（即 `C:\Users\<用户名>\AppData\Roaming\UDhold\`）
- **macOS**：`~/Library/Application Support/UDhold/`

包含：用户设置、固定列表、剪贴板历史、插件数据等。

**迁移到新电脑**：

1. 关闭 UDhold
2. 复制上述整个目录到新电脑对应位置
3. 启动 UDhold，所有设置和插件都会保留

---

# AI 助手

来源: https://udhold.cn/docs/features/ai-helper

AI 助手（ai-helper）是 UDhold 内置的轻量 AI 对话助手，支持多会话、多模型切换、流式输出、图片识别、思考过程展示。它默认常驻主面板右侧面板，随叫随到，不用专门切窗口。

## 进入方式

- 主面板右侧面板默认就是 AI 助手；没显示时从搜索框输入「AI助手」打开
- 或从搜索框选中文字直接发起对话（over 模式，见下文）

## 界面布局

整体分为三部分：

- **顶部侧边栏**：会话管理，可收起为浮层
- **中间消息列表**：用户消息靠右、助手消息靠左
- **底部输入区**：模型选择 + 图片预览栏 + 输入框 + 上传图片 / 发送按钮

<ManualShot name="20-ai-sidebar" alt="AI 助手" />

## 会话管理

左侧边栏管理所有会话：

- **+ 新对话**：创建新会话
- **搜索框**：按会话标题过滤
- **会话列表**：每项显示标题、更新时间（今天显示时分，否则显示月日），悬停显示删除按钮
- **收起侧边栏**：把侧边栏折叠为浮层

打开插件时如果没有会话，会自动创建一个新会话，直接开聊就行。

## 发起对话

### 方式 1：直接输入

1. 在底部输入框输入消息
2. 按 `Enter` 发送（`Shift + Enter` 换行）
3. 助手开始流式输出回答

### 方式 2：发送图片

- 点击「上传图片」按钮，选择一张或多张图片
- 或直接 `Ctrl + V` 粘贴剪贴板图片
- 图片预览栏显示待发送的图片，每张可单独移除
- 输入文字后点击「发送」，图片和文字一起发送

### 方式 3：选中文字发起（over 模式）

1. 在任意应用中选中一段文字
2. 唤起搜索框（复制的内容会自动粘贴）
3. 选择「AI 助手 / 对话」指令
4. 自动新建会话并发送选中文字

## 消息操作

悬停消息时显示操作按钮：

| 消息类型 | 操作 |
|----------|------|
| 用户消息 | 编辑（内联编辑，`Ctrl + Enter` 确认 / `Esc` 取消）、复制 |
| 助手消息 | 重新生成（生成中禁用）、复制 |

助手消息支持思考过程折叠块，流式生成时自动展开，可手动折叠。

## 模型切换

底部工具栏的模型下拉选择器，列出 [AI 模型](./ai-models) 里配置的所有模型。可随时切换，下次发送就用新模型。

## 停止生成

生成中，「发送」按钮会变成「停止生成」按钮，点击立即中止流式输出。

::tip
AI 助手本身不带模型，要先在 [AI 模型](./ai-models) 里配好至少一个模型才能对话。对话经宿主 AI 代理转发，API 密钥始终留在宿主本地，不会暴露给插件。
::

---

# AI 模型

来源: https://udhold.cn/docs/features/ai-models

UDhold 本身不绑定某一个 AI，而是让你自己配置模型服务。配好之后，任何用到 AI 的插件（比如 [AI 助手](./ai-helper)）都能调用，且密钥由宿主保管、经宿主 AI 代理调用，不会下发给插件。呼出搜索框输入"AI 模型"打开。

## 服务商列表

模型按**服务商**分组管理，每个服务商一张卡片，显示：

- 提供商名称 + 模型数量（N 个模型）
- API 主机 + API 格式（OpenAI 兼容 / Anthropic / Gemini）
- 组内模型标签
- 密钥状态点（已配置 / 未配置）+ 编辑 / 删除按钮

顶部有「添加提供商」按钮和搜索框。

<ManualShot name="17-ai-models" alt="AI 模型列表" />

## 添加 / 编辑提供商

点击「添加提供商」或某服务商的「编辑」，右侧滑入编辑面板：

<ManualShot name="18-ai-model-edit" alt="添加 / 编辑提供商" />

| 字段 | 必填 | 说明 |
|------|------|------|
| 提供商名称 | 是 | 显示名，如「通义千问」 |
| API 请求地址 | 是 | 含版本段的完整前缀，如 `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| API 密钥 | 是 | 该提供商下全部模型共用；密码框，眼睛图标切换显示 |
| API 格式 | 是 | OpenAI 兼容（缺省）/ Anthropic（Claude）/ Google Gemini。格式决定端点拼接与鉴权头 |
| 模型 | 是 | 从「推荐模型」列表勾选，或手动「+ 添加模型」填模型 ID（显示名缺省同 ID），如 `qwen-plus`、`gpt-4o` |

::tip
API 格式的差异由 UDhold 自动处理：OpenAI 兼容格式在地址后拼 `/chat/completions`、密钥走 Bearer 头；Anthropic 拼 `/messages`、密钥走 `x-api-key` 头；Gemini 拼 `/models/{模型ID}`、密钥走 `x-goog-api-key` 头。地址填到版本段（`/v1`、`/v4`）即可。
::

## 常见服务商配置示例

| 服务商 | API 地址 | API 格式 | 模型 ID 示例 |
|------|----------|----------|--------------|
| OpenAI | `https://api.openai.com/v1` | OpenAI 兼容 | `gpt-4o`、`gpt-4o-mini` |
| 阿里云通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI 兼容 | `qwen-plus-latest`、`qwen-turbo-latest` |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | OpenAI 兼容 | `glm-4-plus`、`glm-4-flash` |
| 月之暗面 Kimi | `https://api.moonshot.cn/v1` | OpenAI 兼容 | `moonshot-v1-8k`、`moonshot-v1-32k` |
| DeepSeek | `https://api.deepseek.com/v1` | OpenAI 兼容 | `deepseek-chat`、`deepseek-reasoner` |
| Anthropic | `https://api.anthropic.com/v1` | Anthropic（Claude） | `claude-sonnet-4-5`、`claude-haiku-4-5` |
| Google Gemini | `https://generativelanguage.googleapis.com/v1beta` | Google Gemini | `gemini-2.5-pro`、`gemini-2.5-flash` |
| Ollama 本地 | `http://localhost:11434/v1` | OpenAI 兼容 | `llama3.1`、`qwen2.5` |

## 配好后怎么用

最直接的用法是内置的 [AI 助手](./ai-helper)：配好模型就能开聊，支持多会话、图片识别。此外，某些插件也提供"问 AI""翻译""总结"之类的功能，背后调用的就是你这里配的模型。具体能用上哪些 AI 功能，取决于你装了哪些插件。

---

# 调试日志

来源: https://udhold.cn/docs/features/debug

调试日志是个给排查问题用的工具（开发者向），能看到 UDhold 运行时实时输出的日志，支持按日志级别过滤和关键词搜索。平时用不到，遇到插件不工作、应用异常时才需要翻开看看。呼出搜索框输入"调试日志"打开。

## 能看到什么

日志会实时滚动显示，包含：

- 插件的加载、运行、报错信息
- UDhold 主程序的事件和错误
- 数据库、网络等底层操作的记录

## 怎么用

打开后日志会自动开始滚。如果是排查某个插件的问题，先触发那个操作（比如重新打开插件），然后回来找对应的日志条目。

支持按关键词过滤，在搜索框输入想筛的内容，只显示匹配的行，方便从一大堆日志里找到相关信息。

## 什么时候用

- 某个插件打不开、报错
- UDhold 卡顿、无响应
- 反馈 bug 时需要附上日志

::callout{icon="i-lucide-info" color="primary"}
向开发者反馈问题时，把调试日志里相关的部分（尤其是报错那几行）一起贴上，能帮助快速定位原因。
::

---

# 文件资源管理器

来源: https://udhold.cn/docs/features/files

UDhold 内置一个完整的双栏式文件资源管理器，由两个插件协作：

- **files-tree**（左侧面板）：提供目录树 + 收藏夹 + 最近访问
- **files**（工作区）：提供当前目录的文件列表 + 操作

呼出搜索框输入"文件资源管理器"或"文件树"打开，或点活动栏对应图标。首次进入会自动选择一个根目录（盘符），文件树显示所有盘符。

<ManualShot name="10-files-explorer" alt="文件资源管理器" />

## 文件列表

- **根目录**：盘符卡片网格（仿「此电脑」）
- **普通目录**：表格，列含名称、修改日期、类型、大小（可开关）、子项（可开关）。所有列宽可拖拽调整，列标题可点击排序

<ManualShot name="11-file-list" alt="文件列表" />

### 顶部地址栏

| 按钮 | 作用 |
|------|------|
| 上一级 | 返回上级目录（根目录时禁用） |
| 刷新 | 刷新当前目录 |
| 面包屑 | 点击各级目录跳转；点击整条切换为地址输入态，可直接输入路径 |
| 在系统资源管理器中打开 | 用 Windows 资源管理器 / Finder 打开当前目录 |

### 命令行工具栏

- **新建下拉**：文件夹 + 注册表 ShellNew 模板（文本、图片等）
- **剪切 / 复制 / 粘贴**：通过快捷键 `Ctrl+X` / `Ctrl+C` / `Ctrl+V`（工具栏按钮默认隐藏）
- **查看下拉（可多选）**：大小列可见性、子项列可见性、分隔线、显示系统文件（隐藏文件可见性）

## 行操作

| 操作 | 效果 |
|------|------|
| 单击 | 选中（支持 `Ctrl` / `Shift` 多选） |
| 双击 | 打开（目录进入、文件系统打开） |
| 右键 | 弹出 Windows 系统原生右键菜单（与资源管理器同款，包括第三方扩展） |
| 内联重命名 | 双击名称进入编辑，`Enter` 确认 / `Esc` 取消 |
| 拖拽 | 跨目录移动（同盘）或复制（跨盘） |

## 跨分栏拖拽

工作区 [分栏](/docs/getting-started/main-interface#工作区多-tab-与分栏) 时，可以在多个目录之间拖拽文件。拖到目标目录会显示「释放以移动到当前文件夹」提示。剪贴板也跨分栏共享。

## 和文件树联动

工作区打开的目录会同步到左边的 [文件树](./files-tree) 面板，那边会跟着高亮当前路径。反过来，在文件树里点一个目录，也会在这里打开——两边是联动的。

## 双击预览

文本文件 / 图片双击时，会用内置的 [文件预览](./preview) 打开——文本用 monaco-editor（VSCode 同款编辑器）支持语法高亮，图片直接预览。

---

# 文件树

来源: https://udhold.cn/docs/features/files-tree

文件树是左边面板的一个导航插件，用树状结构展示目录，方便快速跳转。呼出搜索框输入"文件树"打开，或点活动栏的文件树图标。

## 功能

- 显示所有盘符根目录，递归展开子目录
- 双击目录唤醒 [文件资源管理器](./files) 打开该目录
- 双击文件：文本 / 图片在 [文件预览](./preview) 插件打开，其他类型用系统默认程序打开
- 右键弹出系统原生右键菜单（与资源管理器一致）

## 三个视图

文件树里有三个标签：

- **目录树**：按文件夹层级展开，点一层展开一层
- **收藏夹**：你常用的目录，手动加进来，方便一键跳转
- **最近访问**：最近打开过的目录，按时间排序

## 工具栏

标题「目录」右侧的工具栏：

| 按钮 | 作用 |
|------|------|
| 刷新 | 刷新选中目录的子项；未选中则重载整树 |
| 新建 | 在选中目录下新建文件夹 / 文件（含注册表 ShellNew 模板，如「文本.txt」「图片.png」），创建后自动进入内联重命名 |

## 节点拖拽

| 操作 | 效果 |
|------|------|
| 把节点拖到另一个目录 | 复制 |
| 按住 `Alt` 拖拽 | 系统级原生拖拽（可拖到外部资源管理器） |
| 接收外部拖入文件 | 复制到当前选中节点目录 |

## 加收藏

看到常用的目录，右键选"添加到收藏夹"，下次直接从收藏夹进，不用一层层展开。

## 和文件资源管理器联动

文件树和工作区的文件资源管理器是双向联动的：

- 在文件树点一个目录 → 工作区打开这个目录
- 在工作区切换目录 → 文件树跟着高亮当前位置

这样不管你是在树里浏览还是在分栏里操作，两边的状态都是同步的。

---

# 本地启动

来源: https://udhold.cn/docs/features/local-launch

本地启动是个启动项管理器，把常用的应用、文件、文件夹集中起来，起个好记的名字，之后在搜索框输入名字就能秒开。呼出搜索框输入"本地启动"打开。

## 添加启动项

### 方式 1：拖拽添加

直接把文件 / 文件夹 / 应用拖到 localLaunch 页面，松手即添加。拖拽时会显示「释放以添加文件」蒙层。

<ManualShot name="15-local-launch" alt="本地启动" />

### 方式 2：按钮添加

- 点击「添加文件」→ 系统文件选择器，选择文件
- 点击「添加文件夹」→ 选择文件夹

## 管理启动项

每个启动项卡片显示：图标 + 名称 + 类型徽章（文件 / 文件夹 / 应用）+ 完整路径。

| 操作 | 作用 |
|------|------|
| 铅笔图标 | 修改别名。留空则使用原名。`Enter` 保存 / `Esc` 取消 |
| 外部链接图标 | 用系统方式打开 |
| 垃圾桶图标 | 删除该项（原文件不动） |

## 启动

加好之后，在主搜索框输入名称或别名就能搜索到，回车启动。输拼音首字母也行，比如设了别名"浏览器"，输 `llq` 就能命中。

::tip
示例：把常用项目文件夹 `D:\Projects\my-app` 加入本地启动，起别名 `myapp`，之后搜索框输入 `myapp` 回车即可在资源管理器打开。
::

把常用的项目目录、设计稿、文档加进来，配合拼音搜索，基本能做到一秒打开。

---

# 插件中心

来源: https://udhold.cn/docs/features/plugins

插件中心是 UDhold 的插件管理中枢，已安装管理和插件市场集成在同一个页面。点活动栏的「插件中心」图标就能进，或者呼出搜索框输入"插件中心"。

<ManualShot name="16-plugins" alt="插件中心" />

## 界面布局

页面采用左右分栏布局，列表与详情同屏：

- **左侧：已安装列表**——本机已装的插件，显示图标、名称、版本、运行状态
- **右侧：插件市场**——分类标签筛选 + 分页网格，浏览可安装的新插件
- **顶部搜索框**——同时过滤已安装列表和市场列表

整个面板也支持拖出主面板，分离成独立窗口使用。

## 已安装插件管理

在左侧列表选中插件，详情卡片里可以：

- **运行 / 停止**：控制插件运行状态
- **卸载**：彻底删掉插件和它的数据。如果只是暂时不想用，先停用就行，数据会留着
- **查看详情**：版本、描述、权限声明等信息

## 插件市场

右侧市场由官方市场服务提供，联网拉取列表：

- 顶部分类标签按用途筛选（AI、开发工具、文件 / 图片、文本 / 数据、系统 / 效率等）
- 点插件卡片展开详情，确认后点「安装」，UDhold 自动下载装好
- 市场加载失败时会提示检查网络连接；装完的插件会从市场列表标记为已安装

市场里比较受欢迎的插件比如：DeepRead 深读、JSON Tools、正则可视编辑器、起个变量名、文件批量重命名、TinyPNG 压缩图片、计算器、时间戳转换、随机密码、待办清单、番茄钟等。

## 其他安装方式

除市场外，UDhold 还支持通过 `.zpx` 文件双击安装（已注册文件关联）。

## 升级

已安装插件有新版本时，打开插件会自动检查并更新，不需要手动去市场找新包。

::callout{icon="i-lucide-info" color="primary"}
插件市场要联网访问官方服务。网络不通时可以先挂代理（[设置](./settings) → 网络）再试。
::

---

# 文件预览

来源: https://udhold.cn/docs/features/preview

文件预览是 UDhold 内置的查看器，能直接看文本文件和图片，不用专门启动编辑器。它没有独立的入口，是在 [文件资源管理器](./files) 或 [文件树](./files-tree) 里双击文件时自动唤起的。

<ManualShot name="12-preview" alt="文件预览" />

## 文本文件

支持各种代码和文本格式（`.txt`、`.md`、`.js`、`.json`、`.css` 等），打开后是带语法高亮的编辑器视图（基于 Monaco Editor，和 VS Code 同款）。可以只读查看，也能直接改，改完保存。

## 图片

支持 `.png`、`.jpg`、`.webp`、`.gif` 等常见图片格式，打开后显示图片预览。

## 怎么用

不用单独打开它。在文件管理器或文件树里，看到想看的文件双击就行，预览会在工作区新开一个标签页展示。看完关掉标签即可，不会留下多余窗口。

---

# 快速启动

来源: https://udhold.cn/docs/features/quick-start

UDhold 的核心入口是搜索框。按全局快捷键（macOS `Option + Z` / Windows `Alt + Z`）呼出后，输入内容就能搜索。快捷键可以在 [设置](./settings) 里改。

## 怎么搜

### 拼音和中文都行

UDhold 的搜索支持中文、拼音、首字母混着输：

- 输 `jsq` 能匹配到"计算器"
- 输 `wenjian` 或 `wj` 能匹配到"文件管理"
- 输英文 `set` 能匹配到"Settings"

不用记全名，输几个字母基本就能找到。

### 匹配任意输入

有些插件（比如翻译、搜索类）会接受你输入的任何内容当参数。你输完关键词选中它，输入的内容会直接传给插件处理。

## 结果列表

搜索结果按相关度排序，来源有这么几类：

- **应用**：你电脑上装的本地程序
- **插件功能**：插件提供的具体能力
- **固定项**：你手动置顶的常用入口

越常用的会排越靠前，用久了自然就形成符合你习惯的顺序。

## 键盘操作

| 按键 | 作用 |
|------|------|
| `↑` `↓` | 上下选择 |
| `←` `→` | 切换分类 / 进入子输入 |
| `Enter` | 确认执行 |
| `Esc` | 退出隐藏 |

## 固定常用项

哪个入口你经常用，可以在结果上右键选"固定"，它会一直显示在列表最前面。不想要了同样右键"取消固定"。也可以把文件拖进搜索框选"固定到搜索框"，直接固定成快捷入口。

把最常用的三五个入口固定住，配合拼音首字母，基本能做到一按键就直达。

---

# 通用设置

来源: https://udhold.cn/docs/features/settings

设置是 UDhold 的配置中心。打开方式有三种：

- 呼出搜索框，输入"通用设置"
- 在搜索框里按 `Ctrl + ,`（macOS `Cmd + ,`）
- 点活动栏最下面的齿轮图标

所有项修改即时生效并自动保存，不用单独点保存。

<ManualShot name="09-settings" alt="通用设置" />

## 基础

| 设置项 | 说明 |
|------|------|
| 呼出快捷键 | 唤起搜索框的全局快捷键，预设 `Alt+Z` / `Alt+Space` / `Ctrl+Space`，也支持自定义录入 |
| 开机自动启动 | 系统开机时自动启动 UDhold |
| 显示托盘图标 | 是否在系统托盘显示图标 |
| 显示状态栏 | 是否显示主面板底部状态栏 |
| 唤醒黑名单 | 在指定应用窗口中按快捷键不唤醒主窗口 |
| 启用工作面板 | 关闭后 UDhold 常驻托盘，只用搜索框和悬浮球 |

::callout{icon="i-lucide-info" color="warning"}
如果设置的快捷键已被其他应用占用，UDhold 会还原旧值并弹出 toast 提示。
::

## 外观

| 设置项 | 说明 |
|------|------|
| 主题设置 | 跟随系统 / 明亮 / 暗黑 |
| 主题色 | 5 种预设色（天空蓝、罗兰紫、翡翠绿、活力橙、宝石红）+ 自定义取色 |
| 窗口不透明度 | 滑块 30%–100%，控制主窗口透明度 |

更细的说明看 [主题](/docs/themes)。

## 搜索

| 设置项 | 说明 |
|------|------|
| 搜索框提示文字 | 搜索框为空时显示的提示语，可自定义 |
| 搜索框模式 | 聚合模式 / 列表模式 |
| 搜索框显示最近使用 | 聚合模式空状态是否显示「最近使用」栏 |
| 匹配推荐 | 是否启用 over 类型指令的推荐，建议保持开启 |
| 最近使用显示行数 | 聚合模式且开启最近使用时，显示 1–4 行（每行 9 个） |
| 固定栏显示行数 | 聚合模式时，已固定栏显示 1–4 行 |
| 本地应用搜索 | 搜索结果是否包含本地已安装应用 |
| 空格打开指令 | 搜索框为空时按空格打开选中指令 |
| Tab 功能 | 切换选中（在分组间切换）/ 目标指令（直接跳转到预设指令） |
| Tab 键目标指令 | 选择「目标指令」时配置具体目标，如 AI 助手 / 对话 |

## 行为

| 设置项 | 可选值 | 说明 |
|------|--------|------|
| 自动粘贴搜索框 | 关闭 / 1 秒内 / 3 秒内 / 5 秒内 / 10 秒内 | 复制内容后唤起搜索框时，自动粘贴并匹配指令 |
| 自动清空搜索框 | 立即 / 1~10 分钟 / 从不 | 多久未操作自动清空搜索框 |
| 自动返回到搜索 | 立即 / 30 秒 / 1~10 分钟 / 从不 | 多久未操作从插件模式自动返回搜索 |
| 插件默认高度 | 数字 | 新打开插件时的默认窗口高度 |
| 剪贴板历史保存天数 | 天数 | 剪贴板历史保留时长 |

## 悬浮球

桌面悬浮球是一个常驻小浮窗，可以拖到顺手的位置：

| 设置项 | 说明 |
|------|------|
| 显示悬浮球 | 开关悬浮球 |
| 悬浮球文字 | 自定义悬浮球上显示的文字，默认为 Y |
| 悬浮球双击目标指令 | 双击悬浮球直接触发的指令，如 AI 助手 / 对话 |

悬浮球还支持把文件拖到球上，配合指令处理。

## 文件

| 设置项 | 说明 |
|------|------|
| 默认文件下载路径 | 下载文件的默认保存目录 |

## 插件服务

| 设置项 | 说明 |
|------|------|
| Python 解释器路径 | 部分插件服务依赖 Python。默认按 `python3` → `python` 自动探测，也可手动指定，出错时可恢复自动探测 |

## 网络

| 设置项 | 说明 |
|------|------|
| HTTP 代理 | 填写代理地址（如 `http://127.0.0.1:7890`）后，UDhold 的网络请求走代理 |
| 接口地址 | 官方服务接口地址，留空使用默认地址 |
| 自定义插件市场 | 开关。开启后从自定义地址拉取插件市场清单 |
| 市场地址 | 自定义插件市场的基础 URL |

## 开发者

| 设置项 | 说明 |
|------|------|
| 开发者工具位置 | 控制插件开发者工具的默认打开位置 |
| 内部 API 授权插件 | 手动授权某个插件使用 internal-api（高风险，仅信任的插件可加） |
| 关闭 GPU 加速 | 禁用硬件加速渲染，可解决白屏、渲染异常等 GPU 兼容性问题，修改后需重启应用生效 |

::callout{icon="i-lucide-alert-triangle" color="warning"}
**内部 API 授权插件**：internal-api 是宿主特权 API（读写设置、管理插件、注册快捷键等），随意授权可能带来安全风险。仅为你完全信任的插件添加。
::

## 进阶

- AI 对话：用内置的 [AI 助手](./ai-helper)
- 配置 AI 模型：在 [AI 模型](./ai-models)

---

# 快捷键

来源: https://udhold.cn/docs/features/shortcuts

UDhold 的快捷键能力分布在两个内置插件里：

| 插件 | 干什么 | 作用域 |
|------|--------|--------|
| 全局指令 | 一个快捷键触发**单个指令**，支持触发后自动复制结果 | 系统（任意位置按下都触发） |
| 快捷键 | 一个快捷键按顺序串行触发**多个指令** | 系统（任意位置按下都触发） |

呼出搜索框输入「全局指令」或「快捷键」打开对应插件。

<ManualShot name="13-shortcuts" alt="快捷键主界面" />

## 全局指令：单指令一键触发

给最常用的指令绑一个全局快捷键，比如按 `Ctrl+Shift+S` 直接截图：

1. 打开「全局指令」插件，点击添加
2. 在快捷键编辑器中录入键位（按住任意组合键）
3. 选择目标指令
4. 可选：开启「自动复制」，触发后自动把结果复制到剪贴板
5. 保存

保存后立即生效，任意应用里按下就能触发。

## 多指令快捷键：一键串行多个指令

「快捷键」插件管理多指令快捷键——把一组固定操作串起来，按一次键依次执行。比如"停止所有插件 → 清除使用记录"一步到位。

- 添加时选择多个目标指令，触发时按顺序执行
- 已有条目可以随时编辑、删除
- 与全局指令共享同一份快捷键文档，按类型自动归属

## 呼出快捷键

唤起 UDhold 搜索框的组合键（默认 `Alt+Z` / macOS `Option+Z`）不在插件里配，在 [通用设置](./settings) → 基础 → 呼出快捷键里改，提供预设组合，也支持自定义录入。

::callout{icon="i-lucide-info" color="warning"}
全局快捷键不要和其他软件冲突。如果设置的快捷键已被占用，UDhold 会还原旧值并弹出 toast 提示，换一个组合就行。
::

---

# 系统命令

来源: https://udhold.cn/docs/features/system

UDhold 内置了一批系统级指令，不用装任何插件就能直接用。在搜索框里输入对应的关键词就能触发。这些指令没有独立界面，全部通过搜索框或超级面板触发。

## 指令清单

### 电源和锁屏

| 指令 | 触发词 | 作用 |
|------|--------|------|
| 关机 | 关机、Shutdown | 关闭计算机 |
| 重启 | 重启、Reboot | 重启计算机 |
| 注销 | 注销、退出登录、Log Off | 注销当前用户 |
| 睡眠 | 睡眠、Sleep | 进入睡眠模式 |
| 锁屏 | 锁屏、锁定屏幕、Lock Screen | 锁定屏幕 |

中英文指令都支持，输哪个都行。

### 截图和取色

| 指令 | 触发词 | 作用 |
|------|--------|------|
| 截图 | 截图、截屏、Screenshot | 区域截图，复制到剪贴板 |
| 屏幕取色 | 取色、Color Picker、屏幕取色 | 屏幕取色，复制颜色值到剪贴板 |

截图后直接粘贴就行，不用再单独存文件。取色的结果也会复制到剪贴板，方便贴到代码或设计软件里。

### 打开网址和文件夹

在搜索框里直接输入内容，UDhold 会自动识别：

| 指令 | 触发方式 | 作用 |
|------|----------|------|
| 打开网址 | 自动匹配（输入网址） | 用默认浏览器打开网址 |
| 前往文件夹 | 自动匹配（输入路径） | 在系统资源管理器中打开 |

不用先打开浏览器或文件管理器再粘贴，直接在搜索框一步到位。

### 文件和窗口相关

这几个指令会根据当前活动窗口或选中的文件触发：

| 指令 | 触发方式 | 作用 |
|------|----------|------|
| 复制路径 | 选中文件 / 在资源管理器中唤起 | 复制文件路径到剪贴板 |
| 在终端打开 | 选中文件夹 / 在资源管理器中唤起 | 在系统终端打开当前目录 |
| 窗口信息 | 窗口信息、Window Info | 显示当前活动窗口的信息 |
| 添加到唤醒黑名单 | 添加到唤醒黑名单、Wakeup Blacklist | 把当前应用加入唤醒黑名单 |

加进唤醒黑名单的程序，UDhold 唤起时不会跟它抢焦点。

### 清理

| 指令 | 触发词 | 作用 |
|------|--------|------|
| 停止所有插件 | 停止所有插件、Clear | 终止所有正在运行的插件，释放内存 |
| 清除使用记录 | 清除使用记录、Clear History | 清空「最近使用」历史 |

---

# 核心概念

来源: https://udhold.cn/docs/getting-started/core-concepts

UDhold 的所有功能都围绕"插件"组织。理解下面几个概念，用起来会顺手很多。

## 插件

插件是 UDhold 扩展能力的基本单元。UDhold 自带的功能（文件管理、设置、插件市场）本身就是插件，你从插件市场装的第三方工具也是插件。每个插件提供一个或多个具体功能，比如翻译、截图、颜色吸取。

## 指令

指令是触发插件的"关键词"。你在搜索框里输入的内容，UDhold 会拿去和各个插件登记的指令做匹配：

- **文字指令**：直接输入字或词，比如输入"翻译"就找到翻译插件
- **拼音**：输中文拼音或首字母也行，比如 `fy` 能匹配到"翻译"
- **文件指令**：把文件拖进搜索框，支持处理文件的插件就会出现
- **图片指令**：复制了图片后，能处理图片的插件会被触发

一个插件可以有多个指令，你也可以给同一个插件的不同功能设置不同的触发词。

## 槽位

打开一个插件时，它会显示在界面的某个固定区域，这叫"槽位"。UDhold 的主面板把界面分成三块：

```
┌────────┬──────────────────────────┬────────────┐
│        │                          │            │
│ 左面板  │       工作区（多标签）     │  右面板     │
│        │                          │            │
└────────┴──────────────────────────┴────────────┘
```

- **左侧面板**：单面板，跟随菜单切换，主要放导航类内容（如文件树、设置分组），默认宽度 240px，可在 240~480px 间拖拽调整
- **工作区**：多 tab 容器，占满中间，是主操作区（文件浏览、设置详情、AI 对话历史），tab 可分离成独立窗口，还支持分栏
- **右侧面板**：全局单例，由插件 API 唤醒，放辅助工具（如 AI 助手常驻），默认宽度 280px，可在 280~480px 间调整

插件该显示在哪是由插件自己决定的，你打开时不用管，UDhold 会自动放到合适的位置。详细的布局和操作看 [主面板布局](/docs/getting-started/main-interface)。

## 三套界面

UDhold 有三个面向用户的窗口，记住它们就掌握了 80% 的用法：

| 界面 | 用途 | 唤起方式 |
|------|------|----------|
| 主搜索框（Spotlight） | 快速搜索应用和指令 | 全局快捷键（默认 `Alt+Z` / macOS `Option+Z`） |
| 主面板（panel-shell） | 仿 VSCode 风格的工作台，承载所有插件界面 | 点击托盘图标，或搜索框中点击 logo |
| 超级面板 | 在任意应用中长按鼠标弹出的快捷指令面板 | 长按鼠标键（默认关闭，需在设置开启） |

此外还有一个可选的**悬浮球**：桌面常驻小浮窗，可拖到顺手的位置，双击直接触发你指定的指令，也支持把文件拖到球上处理。在 [设置](/docs/features/settings) → 悬浮球里开启。

## 插件市场

UDhold 内置一个插件市场，里面是社区和官方发布的插件。你可以一键浏览、安装、升级，不用手动下载解压。需要什么能力就去市场找，详见 [插件中心](/docs/features/plugins)。

接下来可以看 [主面板布局](/docs/getting-started/main-interface)，熟悉搜索框和工作区的具体操作。

---

# 主面板布局

来源: https://udhold.cn/docs/getting-started/main-interface

主面板（panel-shell）是 UDhold 的"工作台"，承载所有 UI 插件。呼出后它是你最常待的地方。

## 进入主面板

任意一种方式都行：

- 点击搜索框左侧的 logo 图标
- 点击系统托盘图标
- 在搜索框里按 `Ctrl + ,`（macOS `Cmd + ,`，打开的是通用设置）

<ManualShot name="04-main-panel" alt="主面板整体布局" />

## 整体布局

主面板从上到下、从左到右依次是：

- **顶部菜单栏**：Logo + 应用名 + 文件 / 编辑 / 帮助菜单 + 搜索框 + 窗口控制
- **活动栏**：最左侧的竖条
- **左侧面板**
- **工作区**：多 tab，占满中间
- **右侧面板**
- **底部栏**：右侧显示版本号

## 活动栏

最左边那一列竖排图标叫活动栏，分顶部组和底部组：

- **顶部组**：插件菜单（按字母或自定义顺序），默认常见的有「文件树」「UD 简盘」「AI 模型」「插件中心」「全局指令」「快捷键」等，装的插件多了会按字母排进来
- **底部组**：「账户」「通用设置」默认放在底部

| 操作 | 效果 |
|------|------|
| 单击菜单 | 切换该菜单的内容到对应槽位 |
| 右键菜单栏 | 弹出原生勾选菜单，控制每个菜单的「在活动栏显示」 |
| 长按拖拽菜单 | 在同组内重排顺序（顶部组和底部组不能互换） |
| 悬停 | 显示菜单文字标签 |

## 三个槽位的区别

<ManualShot name="06-three-slots" alt="三个槽位区别" />

| 槽位 | 类型 | 可调宽度 | 可分离为独立窗口 | 默认宽度 |
|------|------|----------|------------------|----------|
| 左侧面板（leftPanel） | 单面板，跟随菜单切换 | 是（240~480px） | 是 | 240px |
| 工作区（workspace） | 多 tab 容器，占满中间 | 否（占满） | tab 可分离，支持分栏 | — |
| 右侧面板（rightPanel） | 全局单例，由插件 API 唤醒 | 是（280~480px） | 是 | 280px |

典型用法：左侧面板承载导航类（如文件树、设置分组）；工作区是主操作区（文件浏览、设置详情、AI 对话历史）；右侧面板承载辅助工具（如 AI 助手常驻）。

## 调整面板宽度

把鼠标移到左面板右边缘（或右面板左边缘），鼠标变成双向箭头形状时拖拽。拖到宽度低于 80px 松手，面板会收起隐藏；收起后从边缘拖出可重新展开。

或者用顶部菜单栏的侧边栏切换按钮（活动栏旁边的两个图标）：

- 点击展开 / 折叠切换
- 已分离状态下点击让分离窗口回归主面板
- 面板空（所有 tab 关闭）时点击唤醒默认插件

## 工作区多 tab 与分栏

<ManualShot name="07-workspace-split" alt="工作区分栏" />

工作区支持多 tab 标签页。多个插件或多个目录（文件浏览器）可在工作区同时打开：

- 点击 tab 标题切换
- tab 标题右键关闭
- 拖拽 tab 标题脱离主面板成为独立窗口

工作区还支持分栏（全局四宫格）：

| 模式 | 说明 |
|------|------|
| single | 单格（默认） |
| horizontal | 左右两格 |
| vertical | 上下两格 |
| grid | 四宫格 |

分栏常用于「同时打开多个目录」的文件管理场景。详细的文件操作看 [文件资源管理器](/docs/features/files)。

## 面板分离成独立窗口

<ManualShot name="08-panel-detach" alt="面板分离成独立窗口" />

把鼠标移到面板头部栏（左上角图标 + 标题那一条），按住向外拖出。面板会变成独立窗口，可以单独移动、调整大小——方便放到第二块屏幕上用。

## 右侧面板的活跃插件侧边栏

当右侧面板有 2 个及以上活跃插件时，会在面板最左侧显示一条竖排图标栏（活跃插件侧边栏）。每个图标代表一个活跃的右面板插件，点击切换激活，激活的插件左侧有主题色竖线指示。

## 接下来

- [快速上手 5 分钟](/docs/getting-started/quick-tour)——跑通从唤起到装插件的完整流程
- [常用快捷键](/docs/getting-started/shortcut-keys)——键盘操作速查
- [通用设置](/docs/features/settings)——8 个分组的所有配置项

---

# 快速上手 5 分钟

来源: https://udhold.cn/docs/getting-started/quick-tour

还没装好的话，先看 [准备](/docs/preparation) 把 UDhold 装上。装好之后跟着下面四步走一遍，基本就掌握了 UDhold 的核心用法。

## 第 1 步：唤起搜索框

按下全局快捷键 `Alt+Z`（macOS 为 `Option+Z`），屏幕中央会弹出一个搜索框。快捷键可以自己在 [设置](/docs/features/settings) 里改。

<ManualShot name="02-search-box" alt="搜索框" />

## 第 2 步：搜索一个应用

输入「微信」或拼音 `wx`，搜索结果会实时筛选。按上下方向键选择，回车打开。电脑上装的软件都能这样搜——输应用名、拼音或首字母都行。

<ManualShot name="03-search-app" alt="搜索应用" />

## 第 3 步：打开主面板

程序打开时默认进入主面板。也可以点击搜索框左侧的 logo 图标，或点击系统托盘图标打开主面板。

<ManualShot name="04-main-panel" alt="主面板" />

主面板是 UDhold 的"工作台"，所有带界面的插件都显示在这里。详细布局看 [主面板布局](/docs/getting-started/main-interface)。

## 第 4 步：从插件市场装一个插件

1. 在主面板左侧活动栏点击「插件中心」图标
2. 右侧是插件市场，可按分类标签筛选，或用顶部搜索框过滤
3. 点插件卡片查看详情，点击「安装」，UDhold 自动下载装好

<ManualShot name="05-plugin-market" alt="插件市场" />

恭喜！你已经掌握了 UDhold 的基本用法。接下来按章节深入了解每个功能。

## 接下来

- [核心概念](/docs/getting-started/core-concepts)——插件、指令、槽位是什么
- [系统命令](/docs/features/system)——自带的截图、取色、关机等指令
- [插件中心](/docs/features/plugins)——管理已装插件，逛插件市场

---

# 常用快捷键

来源: https://udhold.cn/docs/getting-started/shortcut-keys

UDhold 的设计理念是"全键盘操作"。把下面这几个快捷键记住，熟练之后基本不用碰鼠标。

## 全局快捷键

| 快捷键 | 作用 |
|------|------|
| `Alt + Z`（Windows）/ `Option + Z`（macOS） | 唤起 / 隐藏搜索框 |
| `Ctrl + ,`（macOS `Cmd + ,`） | 在搜索框中打开通用设置 |

呼出快捷键可以在 [设置](/docs/features/settings) → 基础里改（预设 `Alt+Z`、`Alt+Space`、`Ctrl+Space`，也支持自定义录入），还可以在 [全局指令](/docs/features/shortcuts) 里给任意指令单独绑全局快捷键。

## 搜索框键盘操作

| 按键 | 作用 |
|------|------|
| `↑` `↓` | 上下选择结果 |
| `←` `→` | 切换分类 / 进入子输入 |
| `Enter` | 确认执行 |
| `Esc` | 退出，隐藏窗口 |
| `空格`（空状态） | 打开选中的指令 |

## AI 助手快捷键

在 [AI 助手](/docs/features/ai-helper) 对话窗口里：

| 快捷键 | 作用 |
|------|------|
| `Enter` | 发送消息 |
| `Shift + Enter` | 换行 |
| `Ctrl + Enter` | 确认编辑消息 |
| `Ctrl + V` | 粘贴剪贴板图片 |

## 自定义快捷键

想给常用指令绑一键触发？按需求选入口：

- **全局指令**：任意位置按快捷键触发单个指令，支持「自动复制」结果（在 [快捷键](/docs/features/shortcuts) 页管理）
- **多指令快捷键**：一个快捷键按顺序串行触发多个指令（同样在 [快捷键](/docs/features/shortcuts) 页配置）

::callout{icon="i-lucide-info" color="warning"}
如果设置的快捷键已被其他应用占用，UDhold 会还原旧值并弹出提示，换一个组合就行。
::

---

# 认识 UDhold

来源: https://udhold.cn/docs/getting-started/what-is-udhold

UDhold 是一款高性能、可扩展的桌面效率启动器和插件平台。它通过全局快捷键瞬间唤起，帮你快速启动已安装的应用、文件、网址，用搜索指令触达各种功能，运行你需要的插件（剪贴板、翻译、AI、文件管理、JSON / 正则、SQL 等）。

把日常开发、办公里最常用的几件事——启动程序、操作文件、跑网页自动化——都收进一个全局搜索框里，所有功能都通过插件扩展。

## 它能做什么

| 场景 | 示例 |
|------|------|
| 启动应用 | 输入 `wx` 直接打开微信 |
| 触发指令 | 输入「截图」调用截图工具，输入「关机」调用系统指令 |
| 文本增强 | 复制一段文字后按 `Alt+Z` 自动粘贴进搜索框，触发翻译 / 正则 / JSON 格式化等指令 |
| 文件增强 | 在资源管理器选中文件后唤起，触发「复制路径」「在终端打开」等指令 |
| AI 助手 | 内置 AI 对话窗口，支持多模型、多会话、图片识别 |

## 设计思路

UDhold 没有把功能写死在主程序里，而是把所有能力都做成了插件——连自带的文件管理、设置、AI 模型、插件市场本身也是插件，和第三方插件用同一套 API。这样需要什么能力就装什么插件，主程序保持轻量。

## 技术栈

| 层级 | 选型 |
|------|------|
| 应用框架 | Tauri 2 + Vue 3 + TypeScript |
| 后端 | Rust（窗口管理、剪贴板监听、截图取色、系统指令等原生能力） |
| 数据库 | LMDB（嵌入式键值存储） |
| 搜索引擎 | Fuse.js + pinyin-pro（支持拼音） |

## 接下来

- [快速上手 5 分钟](/docs/getting-started/quick-tour)——从零开始跑通唤起、搜索、装插件
- [核心概念](/docs/getting-started/core-concepts)——搞懂插件、指令、槽位这些基本概念
- [主面板布局](/docs/getting-started/main-interface)——熟悉搜索框和工作区布局
- [常用快捷键](/docs/getting-started/shortcut-keys)——速查全局与搜索框快捷键
- [插件中心](/docs/features/plugins)——看看现在有哪些可用插件

---

# 隐私协议

来源: https://udhold.cn/docs/legal/privacy

我们高度重视您的隐私。本协议说明 UDhold 在隐私方面的处理方式。请仔细阅读。

## 总体原则

UDhold 是一款主要在本地运行的桌面应用。**除您主动开启的功能外，您的个人数据不会被上传到我们的服务器。**

## 本地存储的数据

以下数据存储在您设备的本地数据库中，不会自动上传：

- 您的偏好设置（主题、语言、快捷键等）
- 插件数据（每个插件独立存储的业务数据）
- 搜索与使用历史记录
- 您配置的连接信息、账号信息（如有）

这些数据完全由您掌控，您可随时查看、导出或删除。

## 可能联网的功能

下列功能在您主动使用时会访问网络，相关数据仅用于实现功能本身：

| 功能 | 联网目的 | 数据流向 |
|------|---------|---------|
| 插件市场 | 获取插件列表、下载与更新插件 | 官方插件服务 |
| 自动更新 | 检查并下载新版本 | 官方更新服务 |
| AI 功能 | 调用大语言模型 | 您配置的 AI 服务商 |

::callout{icon="i-lucide-info" color="primary"}
AI 调用的请求直接发往**您配置的 AI 服务商**，我们不参与中转。
::

## 我们不收集的信息

我们**不**通过 UDhold 收集：

- 您的身份信息（姓名、邮箱等），除非您主动在账号体系中填写
- 您的浏览、使用行为画像
- 您设备上的文件内容
- 您在各插件中输入的具体数据

插件市场与自动更新仅请求必要的版本与列表信息，不携带可识别您个人身份的数据。

## 第三方服务

UDhold 的部分功能依赖第三方服务，这些服务有各自独立的隐私政策：

- **您的 AI 服务商**：调用 AI 时，您输入的内容受该服务商隐私政策约束

建议您在使用前阅读对应服务的隐私政策。

## 第三方插件

第三方插件可能自行收集或上传数据，其数据处理方式由插件开发者决定，不在本协议管辖范围内。安装插件前，请查看其说明或联系开发者了解其数据实践。

## 数据安全

- 您的本地数据存储在受系统保护的用户目录下
- 涉及敏感信息（如 API Key）时进行加密存储

## 您的权利

您对自己的数据拥有完全控制权，可以：

- 随时导出数据
- 随时删除指定数据或全部清空
- 通过卸载 UDhold 移除所有本地数据

## 协议变更

我们可能更新本隐私协议。重大变更时会在软件或本页面提示。继续使用 UDhold 即视为您接受更新后的协议。

## 联系我们

如对本隐私协议有任何疑问或建议，可通过邮箱联系我们：[youyuanplat@163.com](mailto:youyuanplat@163.com)。

---

# 用户须知

来源: https://udhold.cn/docs/legal/user-notice

欢迎使用 UDhold。安装或使用 UDhold 即表示您已阅读并同意本须知。请您仔细阅读以下内容。

## 软件性质

UDhold 是一款桌面应用启动器与插件平台，基于开源项目发布。本须知中"UDhold"指本软件本身，"我们"指软件的维护方，"您"指最终用户。

## 您可以做什么

- 在个人或企业环境中安装、使用 UDhold
- 在多台由您本人控制的设备上安装使用
- 根据 UDhold 适用许可证的规定，复制和分发软件
- 开发、发布第三方插件并通过插件市场分享

## 您不应做什么

- 逆向工程、反编译本软件，法律法规明确允许的除外
- 移除或篡改软件中的版权、商标等权利声明
- 以危害他人或违反法律法规的方式使用 UDhold
- 利用 UDhold 实施未经授权的系统访问、数据窃取等行为
- 冒充官方或声称 UDhold 由您开发

## 关于插件

UDhold 是一个插件平台，第三方插件由各自的开发者独立开发与维护，其内容、功能与安全性由插件开发者自行负责。我们对第三方插件不作任何明示或暗示的担保，也不对其可能造成的损失承担责任。

建议您仅从内置插件市场或可信来源安装插件。如对某个插件有疑问，可在安装前查看其描述、作者与版本信息，或联系插件开发者。

## 服务变更与中断

UDhold 在持续迭代，我们保留以下权利且无需事先通知：

- 新增、修改或停止提供某些功能
- 发布新版本，旧版本可能停止维护
- 调整插件市场的内容与可用性

因网络故障、系统维护或不可抗力导致的服务中断，我们不承担责任。某些在线功能（如插件市场、自动更新）需要网络连接，网络受限时相关功能可能不可用。

## 责任限制

UDhold 按"现状"提供。在适用法律允许的最大范围内，我们不对因使用或无法使用 UDhold 而导致的任何直接或间接损失（包括数据丢失、业务中断、利润损失等）承担责任。

请您养成定期备份重要数据的习惯。UDhold 不对您存储在本地的数据丢失负责。

## 知识产权

UDhold 软件本身及其相关文档、图标、名称等受知识产权法保护。除许可证明确授予的权利外，未授权不得使用。

## 须知变更

我们可能不时更新本须知。更新后，我们会在软件或本页面提示。继续使用 UDhold 即视为您接受更新后的须知。

## 联系我们

如对本须知有任何疑问，可通过邮箱联系我们：[youyuanplat@163.com](mailto:youyuanplat@163.com)。

---

# 准备

来源: https://udhold.cn/docs/preparation

UDhold 是一个桌面应用启动器和插件平台。开始用之前，先确认你的电脑环境，然后下载安装。

## 系统要求

| 平台 | 版本要求 |
|------|----------|
| Windows | Windows 10 / 11（x64） |
| macOS | macOS 11+（Apple Silicon 和 Intel 均支持） |
| Linux | 路线图中，暂未发布官方构建 |

## 下载

去 [UDhold 官网](/) 下载页或 [GitHub Releases](https://github.com/ZToolsCenter/ZTools/releases)，按系统选安装包：

- **Windows**：安装程序 `exe`（如 `UDhold-Beta-win32-x64-<版本>.exe`）
- **macOS**：`.dmg` 安装包，Apple Silicon 和 Intel 芯片分架构提供

## 安装

### Windows

双击安装程序，按提示选安装路径，下一步到底，完成。默认安装到 `C:\Users\<用户名>\AppData\Local\UDhold\`。

### macOS

双击 `.dmg` 把 UDhold 拖进 `Applications` 文件夹。第一次打开如果提示"无法验证开发者"，去 **系统设置 → 隐私与安全性** 点"仍要打开"。

## 首次启动

1. 启动后，UDhold 会在系统托盘驻留图标，主窗口默认隐藏
2. 首次启动会自动弹出 Bootstrap 窗口，下载默认必备插件（文件管理、设置中心、插件市场等）
3. 下载完成后，会自动打开主面板（panel-shell），提示你设置全局快捷键

<ManualShot name="01-first-start" alt="首次启动" />

::callout{icon="i-lucide-info" color="primary"}
**Windows SmartScreen 警告**：首次运行可能被拦截，点击「更多信息 → 仍要运行」即可。
::

::callout{icon="i-lucide-info" color="warning"}
**macOS 权限请求**：UDhold 会请求「辅助功能」权限（用于全局快捷键、超级面板的鼠标监听）、「屏幕录制」权限（用于截图、取色），请在系统设置中授权。
::

## 首次启动权限

启动后系统可能请求以下权限，按需授予：

| 权限 | 用途 |
|------|------|
| 辅助功能（macOS） | 全局快捷键、模拟键盘输入、超级面板鼠标监听 |
| 屏幕录制（macOS） | 截图、取色 |
| 开机自启动 | 重启后自动运行 UDhold |

Windows 一般无需额外授权。

## 唤起主界面

UDhold 装好后默认在后台运行，用全局快捷键随时呼出搜索框：

- macOS：`Option + Z`
- Windows：`Alt + Z`

呼出后输入名字或拼音就能搜索，按 `Esc` 隐藏回去。快捷键可以在 [设置](/docs/features/settings) 里改。

## 卸载

- 去「设置 → 应用」卸载，或运行安装目录下的 `Uninstall UDhold.exe`
- 用户数据保留在 `%APPDATA%\UDhold\`，需要彻底清除请手动删除

接下来看 [快速上手 5 分钟](/docs/getting-started/quick-tour)，跑通完整流程。

---

# 主题

来源: https://udhold.cn/docs/themes

UDhold 的外观可以自己调。在 **设置 → 外观** 里能换主题模式、主题色和窗口不透明度。所有项改完即时生效，不用保存。

## 主题模式

三种模式：

- **跟随系统**：跟着操作系统的亮暗设置走
- **明亮**：浅色背景，白天用
- **暗黑**：深色背景，护眼省电

在设置里切，或者直接点窗口右上角的主题图标循环切换。

## 主题色

5 种预设色，影响按钮、链接、选中项这些元素的颜色，还支持自定义取色：

| 主题色 | 感觉 |
|------|------|
| 天空蓝 | 默认，沉稳 |
| 罗兰紫 | 个性一点 |
| 翡翠绿 | 清新 |
| 活力橙 | 有活力 |
| 宝石红 | 醒目 |

预设里没有合眼的，点自定义用取色器选任意颜色。选一个立刻就生效，整个应用的颜色都会跟着变。

## 窗口不透明度

滑块 30%–100%，控制主窗口的透明度。调低一点可以隐约透出背后的内容，适合配合其他窗口对照着用。

更完整的设置项看 [设置](/docs/features/settings)。