kanban

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

What this is

简介

The official agent connector is
kanban_agent_skill/
. This is THE skill to hand to any agent — your own, a teammate's, anyone's — to give it read/write access to a Kanban board. Give that folder out, install it, and the agent is wired to the board. Everything else in this directory (
server.js
,
kanban.html
) is for hosting a board;
kanban_agent_skill/
is for using one.

A self-contained Kanban system that lives in this skill's own folder (

skills/kanban/

kanban.html
— the board UI (React, single file).
```
API_BASE
```
is derived from
```
window.location.pathname
```
, so the same file works locally and behind any published path prefix. No edits needed on publish.
server.js
— Node server on port 5555, file-backed (
```
data.json
```
), exposing the
```
/ajax/tasks/*
```
API the UI and the agent both use.
kanban_agent_skill/
— the connector skill for agents (registered as
```
kanban-agent
```
, auto-discovered when this skill is installed). This is the folder an agent — yours or a collaborator's — uses to read/write the board. It auto-resolves the board URL at runtime (see its SKILL.md), so once you publish, the agent is wired up with zero edits and the file never needs updating.

Deployment model — one board per user. Each user serves their own

server.js

and publishes it to

https://community.iamstarchild.com/{USER_ID}-kanban-board

. Your agent connects to your board. There's no shared server and no shared

data.json

, so two users never collide. (To collaborate on one board, use

kb_use_board(url)

from the companion skill to point at someone else's URL.)

官方Agent连接器为
kanban_agent_skill/
。这是赋予任意Agent（你自己的、同事的，任何人的）读写Kanban看板权限的专属技能。将该文件夹分发、安装后，Agent即可与看板建立连接。本目录中的其他文件（
server.js
、
kanban.html
）用于托管看板；而
kanban_agent_skill/
用于使用看板。

一个自包含的Kanban系统，存放在本技能的专属目录（

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。）

Setup — publish your board (run these in order)

搭建步骤——发布你的看板（按顺序执行）

1. Serve the board locally

1. 本地部署看板

The board files (

server.js

kanban.html

) live in this skill's own directory — normally

skills/kanban

. Serve from there; do NOT copy the files anywhere else (copies drift). Use the

preview

tool (NOT a raw

node

call — the preview registry is what

publish_preview

reads):

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

If a preview is already registered (check

/data/previews.json

for a

kanban

-suffixed id), reuse its id and make sure its

dir

points at

skills/kanban

— don't serve a duplicate.

看板文件（

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. Publish it to a public URL

2. 发布至公开URL

Load the community-publish skill (

read_file

its SKILL.md), then:

python

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

This maps the running service to

https://community.iamstarchild.com/{USER_ID}-kanban-board

. The

USER_ID

prefix is added automatically — keep the slug exactly

kanban-board

so the companion skill's auto-detect finds it without extra config.

Requires running inside the Starchild container (needs
FLY_MACHINE_ID
). Publishing only allocates the URL — it does NOT list the board on the public gallery. That's a separate, deliberate
list_in_dashboard()
call if wanted.

加载community-publish技能（使用

read_file

读取其SKILL.md），然后执行：

python

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. Record the published URL in the connector's SKILL.md

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

After publishing, take the actual public URL returned by

publish_preview

(or read it from

/data/previews.json

) and write it into the connector skill's doc so the live board link is captured in the skill itself, not just guessed.

Edit

skills/kanban/kanban_agent_skill/SKILL.md

and replace the placeholder board URL with the real published URL. Specifically, in its Overview section change the auto-detect line:

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

to the concrete URL you just published, e.g.:

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

Use

edit_file

for this, then run

skill_refresh

so the change is reloaded. This keeps the connector's documentation pointing at the real live board rather than a placeholder. (The runtime resolver still works either way — this is so the URL is written down, per request.)

发布完成后，获取

publish_preview

返回的实际公开URL（或从

/data/previews.json

中读取），并将其写入连接器技能的文档中，以便看板的实时链接被记录在技能本身中，而非仅靠猜测。

编辑

skills/kanban/kanban_agent_skill/SKILL.md

，将占位符看板URL替换为真实的已发布URL。具体来说，在其概述部分修改自动检测行：

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. Verify the connection

4. 验证连接

Load the companion skill (

read_file skills/kanban/kanban_agent_skill/SKILL.md

) and run:

python

kb_health()

Expect

resolved_via: "community (auto)"

ok: true

, and

resolved_url

matching your

{USER_ID}-kanban-board

URL. If it resolved to

localhost

, the publish didn't take — recheck step 2.

加载配套技能（

read_file skills/kanban/kanban_agent_skill/SKILL.md

）并执行：

python

kb_health()

预期返回

resolved_via: "community (auto)"

、

ok: true

，且

resolved_url

与你的

{USER_ID}-kanban-board

URL匹配。如果解析到

localhost

，说明发布未成功——请重新检查步骤2。

5. Hand the user their link

5. 向用户提供链接

Give them the live URL from step 2, e.g.

https://community.iamstarchild.com/{USER_ID}-kanban-board/

. On Telegram/WeChat, send the full public URL (no preview panel there).

将步骤2中的实时URL提供给用户，例如

https://community.iamstarchild.com/{USER_ID}-kanban-board/

。在Telegram/微信上发送完整的公开URL（无需预览面板）。

After setup — using the board

搭建完成后——使用看板

Day-to-day task management is the companion skill's job. Its functions auto-resolve to the board you just published — no arguments needed:

python

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

See

kanban_agent_skill/SKILL.md

for the full function reference.

日常任务管理由配套技能负责。其函数会自动解析到你刚发布的看板——无需传入参数：

python

from exports import kb_health, kb_summary, kb_create_task, kb_move_task
kb_summary()   # 查看概览：列信息 + 任务数量

完整函数参考请见

kanban_agent_skill/SKILL.md

。

Collaborate — give a colleague's agent access to your board

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

Your board is one shared URL. To let a teammate's agent read/write it, they need the connector skill only — not the whole board (they don't run a server).

Prepare a pre-wired copy (recommended — no manual config for the recipient). From the connector skill, run:

python

kb_export_for_sharing()

This stamps a copy of

kanban_agent_skill/

with your board URL and zips it to

output/kanban-agent-share/

. Send that folder/zip. The recipient:

Drops
```
kanban_agent_skill/
```
into their own
```
skills/
```
directory.
Their agent runs skill_refresh (registers it as
```
kanban-agent
```
).
Runs
```
kb_health()
```
— it auto-connects to your board, zero config.

Why not just send the raw folder? A raw copy auto-detects the recipient's own board, not yours — stamping is what wires it to your board. (Manual alternative: send the folder and have them set

KANBAN_URL=<your board URL>

in their

.env

or call

kb_use_board(<your board URL>)

.) Remember the API is open: anyone with the URL has full read/write.

你的看板对应一个共享URL。若要让同事的Agent读写你的看板，他们只需连接器技能——无需完整看板（无需运行服务器）。

准备预配置的副本（推荐方式——接收方无需手动配置）。从连接器技能中执行：

python

kb_export_for_sharing()

此操作会将

kanban_agent_skill/

的副本标记上你的看板URL，并压缩至

output/kanban-agent-share/

。发送该文件夹/压缩包。接收方只需：

将
```
kanban_agent_skill/
```
放入自己的
```
skills/
```
目录。
其Agent运行skill_refresh（将其注册为
```
kanban-agent
```
）。
运行
```
kb_health()
```
——无需任何配置即可自动连接到你的看板。

为什么不直接发送原始文件夹？原始副本会自动检测接收方自己的看板，而非你的——标记操作才会将其连接到你的看板。（手动替代方案：发送文件夹并让接收方在

.env

中设置

KANBAN_URL=<your board URL>

，或调用

kb_use_board(<your board URL>)

。）请注意API是开放的：任何知道该URL的人都拥有完整的读写权限。

Notes & gotchas

注意事项与常见问题

Keep the slug
kanban-board
. The companion skill auto-detects
```
{USER_ID}-kanban-board
```
. A different slug means you must set the
```
KANBAN_URL
```
env var so the agent can find it.
The board must stay running.
```
publish_preview
```
maps a running service; if the container restarts, the preview auto-starts from
```
/data/previews.json
```
(whose entry must point at
```
/data/workspace/skills/kanban
```
).
No password / open API. The UI loads directly and the API is unauthenticated. Anyone who knows the published URL can read/write the board. Don't publish sensitive data unless you're comfortable with that. To lock it down you'd add auth on the
```
/ajax/tasks/*
```
routes in
```
server.js
```
.
Local dev without publishing: run
```
node server.js
```
in
```
skills/kanban/
```
and open
```
http://localhost:5555
```
— the companion skill falls back to localhost automatically when no community board is reachable.

请保持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
```
——当无法访问社区看板时，配套技能会自动回退到本地环境。