本地推送 API

01概览#

信息岛在本地起一个极小的 HTTP 服务。脚本用一个 JSON 描述卡片，POST 过来即可；同一个 id 再次推送就是「更新并续期」，不会堆一屏卡片。

• 只监听 127.0.0.1，局域网与公网不可达。
• 除健康检查外，所有请求都要 Authorization: Bearer <token>。
• dcx-island.exe --push 在单实例检查之前运行：信息岛已经在跑也能用，而且不会打开或收起面板。
• 一次请求只处理一个 JSON 卡片；不支持 chunked 编码。

02鉴权#

令牌在 %LOCALAPPDATA%\dcx\island_api_token.txt，信息岛首次启动时生成。设置页「桌面信息岛 → 推送 API」可以复制或重置；重置后立即生效，不需要重启信息岛。

# 读取令牌（注意 -Raw 与 Trim）
$token = (Get-Content "$env:LOCALAPPDATA\dcx\island_api_token.txt" -Raw).Trim()

为什么令牌在文件里

这是刻意的例外：脚本需要一行就能读到它，因此不放 Windows 凭据管理器。它只授予「往岛上推卡片」这一项能力，不能读剪贴板、不能读消息、不能执行命令。

从设置页「复制」令牌后，岛内剪贴板历史会跳过与当前令牌完全相同的文本，不会落盘。

03快速开始#

两种方式：调用信息岛自带的 --push / --push-file，或者直接 POST HTTP。前者最省事，后者适合已经在写脚本的进程。

方式一：命令行推送

先确保信息岛在运行，并且设置里的推送 API 是开启状态（默认开启）。

$j = '{"id":"test","title":"测试推送","progress":0.4,"ttl_secs":30}'
[IO.File]::WriteAllText("$env:TEMP\dcx-island-push.json", $j, [Text.Encoding]::UTF8)
& "D:\dcx-dist\dcx-island.exe" --push-file "$env:TEMP\dcx-island-push.json" | Out-Host

& "D:\dcx-dist\dcx-island.exe" --push '{"id":"test","title":"测试推送","progress":0.4,"ttl_secs":30}'

echo {"id":"test","title":"测试推送","progress":0.4} > "%TEMP%\p.json"
"D:\dcx-dist\dcx-island.exe" --push-file "%TEMP%\p.json"

D:/dcx-dist/dcx-island.exe --push '{"id":"test","title":"测试推送","progress":0.4,"ttl_secs":30}'

方式二：直接 HTTP

$token = (Get-Content "$env:LOCALAPPDATA\dcx\island_api_token.txt" -Raw).Trim()
$json  = '{"id":"build-42","title":"构建中","progress":0.3,"ttl_secs":600}'
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:9841/v1/island/push" `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([Text.Encoding]::UTF8.GetBytes($json))

TOKEN=$(cat "$LOCALAPPDATA/dcx/island_api_token.txt")
curl -sS -X POST http://127.0.0.1:9841/v1/island/push \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '{"id":"build-42","title":"构建中","progress":0.3}'

import json, pathlib, urllib.request
token = pathlib.Path.home().joinpath(
    "AppData/Local/dcx/island_api_token.txt"
).read_text(encoding="utf-8").strip()
body = json.dumps(
    {"id": "build-42", "title": "构建中", "progress": 0.3},
    ensure_ascii=False,
).encode("utf-8")
req = urllib.request.Request(
    "http://127.0.0.1:9841/v1/island/push", data=body,
    headers={"Authorization": f"Bearer {token}",
             "Content-Type": "application/json"},
)
print(urllib.request.urlopen(req, timeout=5).read().decode("utf-8"))

04端点#

请求体上限 64 KB，头部上限 8 KB，一次只处理一个 JSON 卡片。健康检查不带鉴权，可以拿来探测信息岛是否在跑：

GET http://127.0.0.1:9841/v1/health

200 OK
{"ok":true,"app":"dcx-island","version":"0.1.2"}

05卡片字段#

完整示例

{
  "id": "build-42",
  "title": "构建中",
  "body": "正在编译 dcx-island（12/40）",
  "progress": 0.3,
  "ttl_secs": 600,
  "action": { "kind": "show_panel", "tab": "live" }
}

最小卡片是 {"id":"ping","title":"完成"}，TTL 默认 12 秒。固定的 id 可以「同一张卡持续更新」，每次推送续期，不会堆一屏卡片。

06动作白名单#

卡片可以带一个动作，点击卡片上的按钮时执行。动作只有三种，没有执行命令一类动作：

07命令行推送#

dcx-island.exe 支持两个模式，参数都是一个 JSON 卡片的文本：

• 退出码 0 = HTTP 200；失败时 stderr 给出原因。
• 两种模式都先于单实例检查运行：岛已经在跑也能用，且不会打开 / 收起面板。
• 推送 API 关闭时，--push 会直接报「推送 API 未启用」。

08排错#

09边界与安全#

• 仅回环：服务只绑定 127.0.0.1，局域网与公网不可达，也没有跨域开放。
• 能力最小：令牌只允许推卡片；没有读剪贴板、读消息、执行命令、读写文件的端点。
• 令牌是文件：island_api_token.txt 刻意不放进凭据管理器，方便脚本读取；泄露后重置即可。
• 数据留在本地：剪贴板与通知内容全部本地保存；推送卡片只存在内存里，到期即消失，TTL 最长 1 小时。
• 卡片数量：最多 16 张，新的顶旧的。高频推送请复用固定 id。
• 默认开启：推送 API 默认开启；关掉后 --push 直接报「推送 API 未启用」。

10扩展平台#

接入 DCX 不只有推送 API。平台本身是「宿主 + 独立 exe」的结构，新增一个应用不需要改设置窗口的导航结构，也不需要动任务栏引擎。

新增一个独立应用

三件事：新增一个 crate、在 dcx-host/src/apps.rs 的注册表加一条 AppEntry、在设置中心对应页面加一组卡片。可执行文件必须与 dcx-host.exe 同目录——宿主按 current_exe() 的父目录找它。

AppEntry {
    id: "search",
    name: "文件检索",
    exe: "dcx-search.exe",
    window_title: "文件检索", // 必须与应用的 WIN_TITLE 逐字一致
    description: "全盘文件名与内容检索，由全局热键唤起",
    default_on: false,      // 缺省不随平台自启
}

• default_on = false 表示缺省关闭：宿主不会拉起它，也不预建索引。全局热键由常驻宿主监听，按下时才 launch_on_demand。
• 一个应用只能有一个主开关，同时写应用自己的 TOML 与 apps.toml，避免两处状态不一致。
• 不要给新应用单独写开机启动项。自启永远只有一条：dcx-host.exe --no-settings，其余由 apps.toml 管理。

配置写入协议

五个 TOML 与两个 JSON 是多进程读写，所有保存都要走 dcx-win32::config_file，不要直接 fs::write + rename：

• FileLock：按文件全路径哈希生成命名互斥体，保护整个「读—改—写」；同线程可重入。
• write_atomic：临时文件带 PID 与序号并 sync_all，再 ReplaceFileW / MoveFileExW 换入。没有「rename 失败就直写」的回退。
• poisoned：解析失败的文件只读，save 返回错误，不许用默认值覆盖——否则会丢 overrides 或 library_root。

不要改的线协议

settings.toml、organizer.toml、apps.toml、box_slot.txt、box_host_alive、no_reserve 是引擎与收纳盒之间的稳定契约：文件名与语义都不改。新增应用不需要替换 dcx_engine.dll。