kanban

这是什么

官方 Agent 连接器是 kanban_agent_skill/。 这就是那个要交给任何 Agent 的技能 ——你自己的、队友的、任何人的——赋予它对看板的读写权限。把这个文件夹发出去、 安装好，Agent 就与看板连上了。本目录中的其他所有内容（server.js、 kanban.html）用于托管看板；kanban_agent_skill/ 用于使用看板。

一个自包含的看板系统，就位于该技能自己的文件夹中 （skills/kanban/）：

• kanban.html —— 看板 UI（React，单文件）。API_BASE 从 window.location.pathname 推导而来，因此同一个文件在本地和任何 已发布的路径前缀下都能工作。发布时无需编辑。
• server.js —— 运行在 5555 端口的 Node 服务，以文件为后端（data.json）， 对外暴露 UI 和 Agent 共同使用的 /ajax/tasks/* API。
• kanban_agent_skill/ —— 面向 Agent 的连接器技能（注册为 kanban-agent，安装本技能时自动发现）。这就是 Agent——你的或协作者的—— 用来读写看板的文件夹。它会在运行时自动解析看板 URL（见其 SKILL.md）， 因此一旦你发布，Agent 就零编辑地连接好了，该文件也永远无需更新。

部署模型——每个用户一个看板。 每个用户运行各自的 server.js 并发布到 https://community.iamstarchild.com/{USER_ID}-kanban-board。 你的 Agent 连接到你的看板。没有共享服务，也没有共享 data.json，因此两个用户永远不会冲突。（若要在同一个看板上协作，可使用 配套技能中的 kb_use_board(url) 指向他人的 URL。）

---

设置——发布你的看板（按顺序运行这些）

1. 在本地托管看板

看板文件（server.js、kanban.html）位于该技能自己的 目录中——通常是 skills/kanban。从那里托管；不要把这些文件复制到 其他任何地方（副本会漂移）。使用 preview 工具（不要直接调用 node—— publish_preview 读取的是预览注册表）：

preview(action="serve", title="Kanban Board", dir="skills/kanban", command="node server.js", port=5555)

如果已经注册了预览（在 /data/previews.json 中检查 以 kanban 结尾的 id），复用其 id 并确保其 dir 指向 skills/kanban——不要托管重复项。

2. 将其发布到公开 URL

加载 community-publish 技能（read_file 其 SKILL.md），然后：

publish_preview(preview_id="<from step 1>", slug="kanban-board", title="Kanban Board")

这会将正在运行的服务映射到 https://community.iamstarchild.com/{USER_ID}-kanban-board。USER_ID 前缀会自动添加——保持 slug 恰好为 kanban-board，以便 配套技能的自动检测无需额外配置即可找到它。

需要在 Starchild 容器内运行（需要 FLY_MACHINE_ID）。 发布只会分配 URL——并不会把看板列出到公开 图库中。如需如此，那是一次单独的、刻意的 list_in_dashboard() 调用。

3. 在连接器的 SKILL.md 中记录已发布的 URL

发布后，取 publish_preview 返回的实际公开 URL （或从 /data/previews.json 中读取），并将其写入连接器技能的 文档，这样实时看板链接就记录在技能本身中，而不仅仅是猜测。

编辑 skills/kanban/kanban_agent_skill/SKILL.md，把占位 看板 URL 替换为真实的已发布 URL。具体来说，在其 Overview 部分 修改自动检测那一行：

2. `https://community.iamstarchild.com/{USER_ID}-kanban-board` — your published board, if reachable.

改为你刚刚发布的具体 URL，例如：

2. `https://community.iamstarchild.com/1357-kanban-board` — your published board (live).

使用 edit_file 完成此操作，然后运行 skill_refresh 以重新加载该更改。 这能让连接器的文档指向真实的实时看板， 而不是占位符。（运行时解析器无论如何都能工作——这样做是为了按要求 把 URL 写下来。）

4. 验证连接

加载配套技能（read_file skills/kanban/kanban_agent_skill/SKILL.md）并运行：

kb_health()

预期 resolved_via: "community (auto)"、ok: true，且 resolved_url 与你的 {USER_ID}-kanban-board URL 匹配。如果解析到了 localhost，说明 发布未生效——重新检查第 2 步。

5. 将链接交给用户

把第 2 步中得到的实时 URL 交给他们，例如 https://community.iamstarchild.com/{USER_ID}-kanban-board/。 在 Telegram/WeChat 上，发送完整的公开 URL（那里没有预览面板）。

---

设置之后 — 使用看板

日常任务管理是配套技能的职责。它的函数 会自动解析到你刚刚发布的看板——无需任何参数：

from exports import kb_health, kb_summary, kb_create_task, kb_move_task
kb_summary()   # orient: columns + task counts

完整函数参考见 kanban_agent_skill/SKILL.md。

---

协作 — 让同事的 Agent 访问你的看板

你的看板就是一个共享 URL。要让队友的 Agent 读写它，他们只需要 连接器技能——而不是整个看板（他们不运行服务）。

准备一份预接线的副本（推荐——接收方无需手动配置）。 在连接器技能中运行：

kb_export_for_sharing()

这会将 kanban_agent_skill/ 的一份副本打上你的看板 URL 的标记，并压缩到 output/kanban-agent-share/。发送该文件夹/压缩包。接收方：

1. 将 kanban_agent_skill/ 放入他们自己的 skills/ 目录。
2. 他们的 Agent 运行 skill_refresh（将其注册为 kanban-agent）。
3. 运行 kb_health()——它会自动连接到你的看板，零配置。

为什么不直接发送原始文件夹？原始副本会自动检测接收方自己的 看板，而不是你的——标记才是将它连接到你的看板的关键。（手动替代方案： 发送该文件夹，让他们在自己的 .env 中设置 KANBAN_URL=<你的看板 URL>， 或调用 kb_use_board(<你的看板 URL>)。）记住 API 是开放的：任何拥有 该 URL 的人都具有完整的读写权限。

---

注意事项与坑

• 保持 slug 为 kanban-board。 配套技能会自动检测 {USER_ID}-kanban-board。slug 不同意味着你必须设置 KANBAN_URL 环境变量，这样 Agent 才能找到它。
• 看板必须保持运行。 publish_preview 映射的是一个正在运行的服务； 如果容器重启，预览会从 /data/previews.json 自动启动（其中的条目必须指向 /data/workspace/skills/kanban）。
• 无密码 / 开放 API。 UI 可直接加载，且 API 未经身份验证。 任何知道已发布 URL 的人都可以读写该看板。除非你能接受这一点， 否则不要发布敏感数据。要锁定它，你需要在 server.js 中为 /ajax/tasks/* 路由添加认证。
• 不发布时的本地开发： 在 skills/kanban/ 中运行 node server.js 并打开 http://localhost:5555——当无法访问任何社区看板时，配套技能会自动 回退到 localhost。