# 桌面唤起（Deep Link）

Deep Link 让任意本机软件（脚本、快捷方式、第三方应用、网页链接）通过自定义 URL 协议唤起 Circow 桌面客户端并执行动作，无需 SDK。

## 1. 协议基础

URL 由 scheme（按客户端区域版本二选一）、action 与参数组成。

| scheme | 说明 |
| --- | --- |
| `circow-desktop-cn://` | 国内版客户端注册的协议头 |
| `circow-desktop-global://` | 海外版客户端注册的协议头 |

```
{scheme}://{action}/{path}?{query}
```

- `action`：动词在前的 kebab-case，如 `run-flow` / `install-skill`
- `path`：可选路径参数（如 `run-flow/{flowId}`）
- `query`：普通 URL query，需 URL 编码

触发后：客户端未运行则冷启动并执行；已运行则由常驻实例接管并聚焦主窗口。调用即发即忘——链接本身不返回结果，参数错误会在客户端内以 toast 提示。

scheme 与当前区域版本不匹配、action 未注册、或签名校验失败的链接会被直接拒绝，并在客户端内 toast 提示原因。

### 从各种环境触发

```html
<a href="circow-desktop-cn://run-flow/{flowId}">打开桌面客户端</a>
```

```bat
start "" "circow-desktop-cn://run-flow/{flowId}?prompt=5L2g5aW9&autosend=1"
```

```javascript
window.location.href = "circow-desktop-cn://run-flow/{flowId}?prompt=5L2g5aW9&autosend=1"
```

```bash
# macOS
open "circow-desktop-cn://run-flow/{flowId}"
```

登录开发者中心「桌面唤起」栏目有一个 run-flow URL 生成器，可自动完成 base64url 编码并一键测试唤起。

## 2. Action 参考

当前注册的全部公开 action。示例中的 `<sha256>` 为文件内容的 SHA-256 十六进制摘要。

### run-flow（L0）

唤起客户端并进入指定工作流的聊天页，预填 prompt，可选自动发送。

| 参数 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- |
| flowId | path | 是 | 目标工作流的 UUID（可在开发者中心「API 集成」栏目的工作流列表中获取） |
| prompt | query · base64url | 否 | base64url（无填充，即 `+`→`-`、`/`→`_`、去掉尾部 `=`）编码的 UTF-8 文本，解码后不超过 8000 字符；缺省则只跳转不预填 |
| autosend | query | 否 | 值为 `1` 时自动发送 prompt；其他值或缺省仅预填不发送 |

```
circow-desktop-cn://run-flow/8b1f…d3a0?prompt=5L2g5aW9&autosend=1
```

base64url 编码示例（Python）：

```python
import base64
def b64url(s: str) -> str:
    return base64.urlsafe_b64encode(s.encode()).decode().rstrip("=")
url = f"circow-desktop-cn://run-flow/{flow_id}?prompt={b64url('你好')}&autosend=1"
```

### install-skill（L0）

下载并安装技能包（zip）。安装前客户端会弹出确认，进度在客户端内展示。

| 参数 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- |
| url | query · URL | 是 | 技能包 zip 的下载地址 |
| name | query | 否 | 技能名（展示用） |
| hash | query · SHA-256 | 否 | zip 的 SHA-256，用于防篡改校验，市场分发时必带 |

```
circow-desktop-cn://install-skill?url=https://example.com/my-skill.zip&name=my-skill&hash=<sha256>
```

### install-mcp（L0）

两种模式：市场安装（传 url + hash，下载 zip 解压注册）；本地安装（`mcps/<name>/` 目录已就位，仅注册启动）。传了 `url` 即走市场模式。

| 参数 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- |
| url | query · URL | 市场模式必填 | MCP 包 zip 下载地址 |
| hash | query · SHA-256 | 市场模式必填 | 包的 SHA-256（身份与去重依据） |
| env_vars | query · JSON | 否 | 市场模式可选：JSON 对象，注入 MCP 进程的环境变量 |
| name | query | 本地模式必填 | MCP 名（即目录名），要求 `{CIRCLE_CONFIG_DIR}/mcps/<name>/` 下已有 mcp.json 与代码 |

```
# 市场安装
circow-desktop-cn://install-mcp?url=https://example.com/my-mcp.zip&hash=<sha256>&env_vars={"API_KEY":"xxx"}
# 本地安装
circow-desktop-cn://install-mcp?name=my-mcp
```

### manage-mcp（L0）

管理已安装 MCP 的生命周期。start / stop 是持久声明（写 `auto_start`，应用重启后仍生效）。

| 参数 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- |
| op | query · start\|stop\|uninstall | 是 | start（启动）/ stop（停止）/ uninstall（停进程 + 删目录 + 删配置） |
| name | query | 是 | 目标 MCP 名 |

```
circow-desktop-cn://manage-mcp?op=stop&name=my-mcp
```

### install-template（L0）

从官方市场安装一个员工模板（即复制到自己账号）。模板是统一的 `.circle` 包，可能是单个员工、一个团队或一个合集（多个团队 + 独立员工）；安装时一次性创建包内全部团队与员工。员工公开主页 `https://circow.cn/e/{template_id}` 的下载按钮在检测到已装客户端时走的就是这条链接；macOS 上该 https 链接也作为 universal link 直接映射到本 action。

| 参数 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- |
| template_id | query | 是 | 市场员工模板的 UUID |

```
circow-desktop-cn://install-template?template_id=<uuid>
```

## 3. 安全模型

每个 action 有固定安全等级，派发前统一校验。

| 等级 | 包含 action | 说明 |
| --- | --- | --- |
| L0 · Public | run-flow / install-skill / install-mcp / manage-mcp / install-template | 任意软件可触发，无需签名。run-flow 的 autosend 视为用户知情授权；安装类动作有 hash 校验与客户端内确认兜底 |
| L1 · BackendSigned | oauth-callback | 需要后端签名参数（`__sig` / `__exp`，HMAC-SHA256，5 分钟内有效），仅由官方服务端签发，外部开发者不可直接调用 |

Public 类 action 的 URL 即使被附加 `__sig` / `__exp` 也会在校验后被剔除，无法借此提权。