快速开始

以「把一条文字从网页发到微信」为例，完整走一遍流程。

1. 确认服务已启动

应用启动后会开启两个本地服务：

# 分享服务（健康检查，无需鉴权）
curl http://localhost:8721/health

# API 服务状态
curl http://localhost:8722/api/v1/status

返回示例：

{
  "app": "sidekick-desktop",
  "version": "1.0.0.0",
  "status": "ok",
  "pairing_code": "123456"
}

网页端如何发现应用

浏览器无法直接知道本机是否运行了应用。通过请求 /health 即可判断：请求成功说明应用在运行，同时能拿到版本号与配对码。

2. 添加内容到队列

curl -X POST http://localhost:8722/api/v1/queue \
  -H "Content-Type: application/json" \
  -d '{"type":"text","content":"你好，这是来自网页的消息","label":"问候消息"}'

不传 group 时自动归入 default 组。

3. 激活分组

curl -X POST http://localhost:8722/api/v1/queue/active-group \
  -H "Content-Type: application/json" \
  -d '{"group":"default"}'

4. 发送

打开微信聊天窗口，点一下输入框确保光标在其中，然后按：

Alt + Shift + V

应用会：写剪贴板 → 发送 Ctrl+V → 等待输入框接收 → 发送 Enter。

每次发送后右下角 toast 显示剩余数量。

5. 查看队列状态

# 待发送
curl http://localhost:8722/api/v1/queue

# 已发送（含处理时间）
curl "http://localhost:8722/api/v1/queue/sent?group=default"

出错怎么办

发错对象或漏发时，把内容还原回队列：

# 还原整个分组
curl -X POST http://localhost:8722/api/v1/queue/restore \
  -H "Content-Type: application/json" \
  -d '{"group":"default"}'

# 还原全部已发送
curl -X POST http://localhost:8722/api/v1/queue/restore \
  -H "Content-Type: application/json" \
  -d '{}'

# 只还原指定项
curl -X POST http://localhost:8722/api/v1/queue/restore \
  -H "Content-Type: application/json" \
  -d '{"id":"0f7e752fb570378f"}'

浏览器集成示例

// 检测应用是否运行
async function detectApp() {
  try {
    const res = await fetch('http://localhost:8721/health')
    const info = await res.json()
    console.log('应用已运行:', info.app, info.version)
    return info
  } catch {
    console.log('应用未运行')
    return null
  }
}

// 上传文件到队列（浏览器端读取文件转 base64）
async function sendFile(file, group = '') {
  const base64 = await file.arrayBuffer().then(buf =>
    btoa(String.fromCharCode(...new Uint8Array(buf)))
  )
  await fetch('http://localhost:8722/api/v1/queue', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      type: 'base64',
      filename: file.name,
      data_base64: base64,
      label: file.name,
      group,
    })
  })
}

中文内容注意编码

用 PowerShell 调用时，字符串参数会按系统默认编码序列化，中文可能变成 ?。请显式使用 UTF-8：

$body = [Text.Encoding]::UTF8.GetBytes('{"type":"text","content":"中文内容","label":"测试"}')
Invoke-WebRequest -Uri "http://localhost:8722/api/v1/queue" -Method Post `
  -Body $body -ContentType "application/json; charset=utf-8"

浏览器与 Node.js 无此问题。