DuiqiDock 使用文档

图标是什么

DuiqiDock 上每个图标都是一个组件：由「类型 + 该类型的配置」定义， 自己回答三个问题 —— 要打开哪个地址、画什么图标、 现在是什么状态。类型决定了后面要填哪些字段。

怎么加一个图标

1. 点 dock 下方的 ＋（图标多的时候它还是最后一行）。
2. 在编辑器里选类型，填该类型的字段 —— 类型那一行右边的 「参考文档 ↗」永远指向当前类型的这一页。
3. 保存。新建的图标会追加到 dock 末尾，可以按住拖动排序。

状态只存在本机

运行状态、进程、日志、指示器圆点的颜色都只活在这台机器的内存里， 不写进 items.json。所以布局同步（同步密钥）会把配置—— 包括指示器的脚本源码——同步到别的机器，但不会因为 A 机开着某个服务， 就让 B 机也显示「运行中」。

网络一律走系统工具

抓网站图标、检查地址是否可达、指示器脚本里的 HTTP，全都由 dock 调系统的 curl.exe 完成。这是理解两件事的关键：指示器脚本里没有 fetch（要用 host.http），以及它不受任何 CORS 限制。

网站

最直接的一类：点一下就在窗口里打开那个地址。

字段

行为

• 窗口位置和大小按网址记忆：关掉再开，回到你上次放的地方。
• 图标探测的结果按内容寻址缓存在应用数据目录里（icons.json + icons/<sha>）， 所以启动第一帧就有图标，不用等网络。探测不到时会退回「首字母 + 底色」。
• 网站图标没有「日志」可看，所以它的右键菜单只有「打开」「编辑」这类操作。它的网址是固定的， 所以还多出「复制URL」「使用Chrome打开」「使用Edge打开」三项 —— 直接把地址交给系统里的浏览器。

这一类不需要安装任何东西。

本地（Local Run）

点图标 → 在本机跑一条命令 → 从它的输出里认出监听的地址 → 打开那个地址的窗口。 先把服务起起来这件事，dock 帮你做了。

字段

地址是怎么定下来的

按顺序，先命中的赢：

1. 输出里最新的一条地址（stdout 和 stderr 都算）。认得出的是这两种写法：
   • http://… 或 https://… 且能解析成合法地址；
   • 这一行提到 listen / running / started / ready / serving / server / url / http / local / address / port 之一， 并且出现了 localhost / 127.0.0.1 / 0.0.0.0 / [::1] / ::1 加端口。这一条是为了让「Listening on 127.0.0.1:5173」 这种不带协议的横幅也能用。
   服务重启会打印新横幅，所以取最新的一条：那是当前有效的地址。
2. 端口探测（进程活着、安静了一会儿还没说出地址时，只试一次）： 先试你填的端口，再试它 ±1、±2，然后依次试 3000 4173 5000 5173 7000 8000 8080 8501 8888 9000， 第一个能连上的就用。不会扫整段端口。
3. 兜底地址：填了就直接用。

认出来的地址如果写的是通配地址（0.0.0.0 或 [::]， vite 和 python 的 http.server 都会这么打印），会被换成一个真正能连的地址 —— 本机跑的就换成 127.0.0.1。通配地址本身不是目的地，直接开它会失败。

窗口什么时候开

点图标时如果服务还没起来，会先启动它、等地址解析出来，再开窗。 地址一旦有人应答（任何 HTTP 状态码都算，包括 404 —— 判断的是「有没有人在听」， 不是「页面正不正常」），就认为可以打开了。

日志

命令的 stdout、stderr 逐行进日志环（每项保留最近 200 行）， 右键图标 →「查看日志」能看，编辑器底部也会显示。 「程序在运行，但没能从输出里认出地址」这类提示，答案通常就在这几行里。

子进程的归属

每个图标一棵 job object。dock 退出（包括被杀）时，它的子进程和孙子进程会一起被收拾， 不会留下一个还占着端口的孤儿进程。

这一类不需要安装任何东西：命令走系统 cmd.exe。

远程（Remote Run）

和「本地」同一套逻辑，只是命令通过系统的 ssh.exe 在另一台机器上执行， 地址也是从那边的日志里解析出来的。

字段

必须先配好密钥

ssh 以 BatchMode 运行：它不会弹密码提示，也不读交互输入。 没配好免密钥登录时，它只会直接失败——日志里是 ssh 自己的 stderr，退出码 255。 Windows 上请先跑一次 ssh user@host 把主机指纹确认掉，再配 authorized_keys。

解析出来的地址是「远端局域网地址」

远端程序如果打印通配地址，会被换成你填的那台 ssh 主机（因为通配在那边意味着「远端的所有网卡」）。 至于那个地址从这台机器过不过得去（同一局域网？VPN？端口放行了吗？）， 由你和那台机器决定 —— dock 只负责把地址解析出来并打开。

依赖系统 ssh.exe（Win10 及以上自带）。

扩展（Extension）

跑一条入口命令，然后打开它起的 web server。命令在一个属于自己的目录里执行； 需要的话，先把一个 git 仓库 clone 到那里再跑。

字段

目录在哪、什么时候更新

• 每个图标一个目录：%APPDATA%\app.duiqi.dock\extensions\<图标 id>\。 两个扩展不会互相踩，删掉一个也不影响另一个。
• 填了仓库：第一次点击时 clone；目录已存在时执行 git pull --ff-only —— 用 --ff-only 是刻意的：这个程序不该替你在仓库里制造一个 merge commit。
• 不自动装依赖。入口命令就是一条完整的命令，需要装就自己写上： npm i && npm run dev。这样 docker 想跑什么就跑什么，dock 不猜。

填了仓库才依赖系统 git.exe；纯 npx 的条目只依赖 node。

指示器

一段 JavaScript，驱动 dock 上的一个彩色圆点。它不打开任何窗口， 只回答一个问题：现在该是什么颜色。适合盯一个服务是否活着、一个队列积压了多少、 一次构建跑完了没有 —— 任何「扫一眼就知道」的状态。

脚本是怎么跑起来的

dock 用这样的命令行启动宿主进程，你的脚本在这个进程里求值：

node.exe indicator-host.js --name <图标名称> --cwd <工作目录> --lang <zh|en>

• 整段脚本被包在 (async () => { … })() 里，所以顶层 await 可用。
• 每次保存脚本、或 dock 重新拉起宿主，都会重新加载整段脚本： 上一次绑定的所有 handler 会被清空，圆点回到默认的灰色，旧脚本里还没回来的 await 不会影响新脚本。
• 工作目录决定脚本里相对路径的落点，也决定 host.cwd 的值。留空时 node 继承 dock 自己的当前目录。
• 宿主进程和 dock 同生共死：dock 退出时它的 stdin 被关闭，宿主跟着退出，不会留下孤儿 node。

脚本里能用什么

只有这些东西，没有别的：

没有 fetch、require、process、Buffer、 URLSearchParams、TextEncoder、AbortController、 crypto、WebSocket、localStorage。 要访问网络就用 host.http（它是 curl，因此也不受 CORS 限制）； 要微任务用 Promise.resolve().then(…)。用错了会看到 ReferenceError: fetch is not defined 这类报错，落在日志里。

host.* 逐个说

host.name / host.cwd

host.log(...args)

写一行日志。参数之间用空格连接，字符串原样，其它值用 util.inspect 展开 （深度 4）。日志进这个图标的环形缓冲，保留最近 200 行， 右键图标 →「查看日志」或编辑器底部能看到。

host.log("检查完成", { status: 200, ms: 42 });

host.setIndicator({ color, blink, text })

改圆点。三个字段都是可选的，而且是局部合并 —— 只写 text 不会清掉上一次设置的颜色。

圆点默认是灰色 #8b949e。灰色表示「还没报」，不是失败 —— 脚本启动到第一次 setIndicator 之间就是灰的。

host.http.get(url, opts)

发一个 HTTP 请求。这是脚本唯一的网络出口。

返回一个对象：

底层是 curl，而且固定带这几个开关：跟随重定向（-L）、 不校验证书（-k，为了内网自签名的 https 站点）、一个 Chrome 的 User-Agent。

host.http.stream(url, opts, onChunk)

流式读取，适合 SSE、持续输出的日志接口。每收到一块就调一次 onChunk(text)，返回的 Promise 在流结束时给出 { status }。 opts 可以省略，直接写 stream(url, onChunk)。

host.request(url | { url, name })

让 dock 开一个窗口，最常写在 onClick 里。 name 是那个窗口的标题，不写就用 host.name。

host.onClick(() => host.request({ url: "https://example.com/panel", name: "面板" }));

四种事件

每个事件可以绑多个 handler（按绑定顺序跑）。没绑 onClick 时， 点击图标什么都不会发生 —— 这不是错误，只是「这个指示器没有可点的东西」。 handler 里抛出的异常不会中断任何东西，只会往日志里写一行 onTick 抛错：…（各事件同理，并把错误信息截到 400 字符）。

出错了会怎样

从最简单的开始

把这个贴进「脚本」，保存。每 5 秒它会请求一次那个地址，通就是绿的，不通就是红的：

host.onTick(async () => {
  const r = await host.http.get("http://127.0.0.1:8123/", { timeout: 5 });
  host.setIndicator({ color: r.ok ? "#3fb950" : "#f85149" });
});

再进一步：连不上时区分「服务坏了」和「服务没了」，连续失败就让它闪。

let fails = 0;

host.onTick(async () => {
  let color = "#8b949e", text = "检查中";
  try {
    const r = await host.http.get("http://127.0.0.1:8123/", { timeout: 5 });
    if (r.ok) {
      fails = 0;
      color = "#3fb950";
      text = "正常 · HTTP " + r.status;
    } else {
      color = "#d29922";          // 有人应答，但答案不对
      text = "异常 · HTTP " + r.status;
    }
  } catch (e) {
    fails += 1;
    color = "#f85149";
    text = "连不上（连续 " + fails + " 次）";
    host.log("健康检查失败：", e.message);
  }
  host.setIndicator({ color, blink: fails >= 3, text });
});

几个常用的写法

把接口里的一个数字放到提示里（颜色沿用上一次，不用重复设）：

host.onTick(async () => {
  const r = await host.http.get("https://example.com/api/queue");
  host.setIndicator({ text: "队列积压 " + r.json().pending + " 条" });
});

点击打开一个页面：

host.onClick(() => host.request({ url: "https://example.com/dashboard", name: "面板" }));

读响应头（注意是数组，不是对象）：

host.onStart(async () => {
  const r = await host.http.get("https://example.com/login");
  const cookies = r.headers
    .filter(function (h) { return h[0] === "set-cookie"; })
    .map(function (h) { return h[1]; });
  host.log("拿到 " + cookies.length + " 条 Set-Cookie");
});

带请求头和 body 发一次 POST：

const r = await host.http.get("https://example.com/api/state", {
  method: "post",                                   // 大小写都行
  headers: { "content-type": "application/json" },  // 请求头是对象
  body: JSON.stringify({ hello: "world" }),         // 原样发出，不加换行
  timeout: 30,
});

跟着一个日志流跑（自己拼行，别假设一块就是一行）：

let buf = "";

host.onStart(async () => {
  const r = await host.http.stream(
    "http://127.0.0.1:8123/log",
    { timeout: 3600 },
    function (chunk) {
      buf += chunk;
      const lines = buf.split("\n");
      buf = lines.pop();                 // 最后一段可能只有半行，留到下一块
      for (const line of lines) {
        if (line.indexOf("ERROR") >= 0)
          host.setIndicator({ color: "#f85149", blink: true, text: line });
      }
    }
  );
  host.log("流结束，status =", r.status);
});

限制速查

编辑器里的「测试运行」

它用同一个宿主把当前编辑框里的脚本跑一遍，最多收集 6 秒的输出， 把 host.log 的内容、错误、以及最后算出的颜色显示在编辑器里 —— 不用保存就能试。两点要知道：

• 它只执行脚本体和 onStart，不发 tick、也不模拟点击。 所以逻辑写在 onTick 里的脚本，测试运行会显示灰点—— 那只是「还没报」，不是失败。
• 它会真的发网络请求（用的是编辑框里的脚本，不是已保存的版本）。

这台机器没有 node 时，「测试运行」是灰的，旁边会写明原因。

指示器需要 Node.js；其余四类用系统自带的 curl.exe / ssh.exe / git.exe。

AI Agent 连接

这一页讲的不是图标类型，而是让本机的 AI Agent 来管这个停靠栏。 DuiqiDock 在启动时开一个只监听 127.0.0.1 的小接口， 并自带一份技能（Skill）：一段说明加一个命令行客户端。 把技能装进 Agent 的技能目录之后，它用自己的命令行工具就能读和改停靠栏， 不需要你去读源码、也不需要给它贴一堆命令。

怎么用起来

1. 打开设置 → AI Agent。
2. 左栏列出本机的 Agent，以及每个的状态（待安装 / 已装 Skill / 需更新 / 未检测到）。
3. 选中一个，点安装。技能被写到它自己的技能目录里，只碰 <技能目录>\duiqidock\ 这一个子目录。
4. 回到那个 Agent 里直接说话，比如「往停靠栏加一个内部看板」。

这些目录都可以用环境变量挪走（CLAUDE_CONFIG_DIR、 WORKBUDDY_CONFIG_DIR、PI_CODING_AGENT_DIR、 HERMES_HOME、DSH_HOME）：设了就以环境变量为准。 检测不到某个 Agent 时，那一行照样列出来，写明原因（比如「.hermes 不存在」）， 安装按钮是灰的。

Agent 能做什么

改错了能退回去

图标列表的每一次改动都会先存一份改动前的完整快照，最近 50 步， 记在内存里（不落盘）。设置页那一栏的「撤销上一步」就是退回去， Agent 自己也能调。两件要知道的事：

• 撤销一次删除会把图标放回停靠栏，但那个程序 不会自己再跑起来 —— 要跑得再说一句启动。
• 反过来，撤销一次新增会把那个图标连同 它正在跑的进程和窗口一起收掉。图标都没了，留着就是没人管的 孤儿进程，所以「加错了」直接撤掉是干净的，不用自己去杀进程。
• 撤销是一次真正的本地改动，会跟着同步推到别的机器上。

这个通道的边界

• 只在本机：接口只绑 127.0.0.1 的随机端口，端口和令牌每次启动重新生成， 只有本机进程连得上。想关掉就在设置页把开关关掉（关掉后不再监听，发现文件也删掉）。
• 凭据是账号密钥，不给 Agent：读设置时「同步密钥」一律是空的，写进去也会被忽略。
• 「装上」不等于「生效」：安装只保证文件在正确的目录、内容是对的。 Agent 什么时候读它，是那个 Agent 自己的事 —— 大多数 Agent 在下次启动时才扫描技能目录。
• 同名技能不覆盖：如果技能目录里已经有一个不是本程序装的 duiqidock， 两边都会拒绝操作并在页面上说明，需要你自己先处理掉那个目录。

Agent 的每一次图标改动都会记在「最近的修改」里，能看到是它改的还是你改的。