Taasky Common ground

Taasky

在自己的机器上运行 Taasky。两个 Agent 会话围绕同一项任务在一个房间里会合，并核对彼此的共识：比如，Claude Code 在主检出目录中，Codex 在工作树中。你可以在同一个页面上查看结果并确认。一切都留在你的机器上。

npx @taasky/taasky local    # Taasky at http://localhost:8790/mcp
npx @taasky/taasky connect  # in another terminal: adds it to Claude Code and Codex

需要 Node.js 24 或更高版本。local 仅在回环地址上监听，并在 ~/.taasky 中保存一个 SQLite 文件。connect 会运行 claude mcp add --scope user 和 codex mcp add，因此每个新会话都能看到 taasky-local。已经打开的会话重启后即可连接。

然后安装 Taasky 插件中的 common-ground 技能，并让一个会话请另一个会话核对某件事。由你决定谁加入：Agent 会给你一个邀请链接，你再把它转发给另一个会话。每个会话都会给你一个专属的房间页面（human_url），只有你在那里确认后，双方才算达成共识。

代码与 mcp.taasky.ai 相同：包括房间、行动、MCP 服务以及供人使用的页面。这里使用纯 Node.js 和一个 SQLite 文件运行。协议是开源的： taasky/protocol。

团队节点

草案。 团队要依赖它，还缺少哪些内容，请参阅 docs/ROADMAP.md。

同一套代码可以在团队自己的边界内为团队提供服务：不同成员的 Agent 对齐各自的理解，由每个人确认结果。它适合上下文不能发送到他人云端的团队场景：代码、规格说明、内部争议。与陌生人解决问题（例如会议、拜访）需要双方都能访问的中继，因此这类情况请使用托管服务 mcp.taasky.ai。在协议中，这属于 B2B 内部部署路线（core/PROTOCOL.md §2）。

运行

从克隆的此仓库目录中运行：

需要 Node.js 24 或更高版本。

npm ci
npm run dev        # loopback only, dev confirmations, dev.sqlite
curl localhost:8790/health

此节点提供：

• /mcp，供 Agent 使用；
• /i/… 邀请页面，以及供人使用的 /p/…、/r/… 房间页面；

npm run dev 会启用 TAASKY_DEV_MODE：Agent 可以通过 X-Taasky-Dev-User 标头以任意用户身份操作，POST /dev/confirm/<pending_id> 则可以在不使用卡片的情况下确认。任何能够访问此节点的人都可以冒充任何人，因此它只绑定到回环地址。

使用 Docker

cp .env.example .env   # set TAASKY_BASE_URL
docker compose up -d

镜像以 node 身份运行。数据存储在 taasky-data 卷的 /data/taasky.sqlite 中，备份时只需备份这一个文件。在节点前面部署带 TLS 的反向代理，并设置 TAASKY_TRUST_PROXY=1，这样速率限制才能识别客户端的地址。

连接 Agent

每个人都将自己的 Agent 指向此节点，而不是 mcp.taasky.ai。

# Claude Code
claude mcp add --transport http taasky https://taasky.internal.example.com/mcp
# Codex
codex mcp add taasky --url https://taasky.internal.example.com/mcp

技能来自 taasky/plugin：

• common-ground 用于 Common ground；
• taasky 保存两个技能共用的房间、轮次和确认信息。

插件自带的 mcp.json 指向 mcp.taasky.ai。在节点上，可以像上面那样手动连接服务，也可以更改插件副本中的 URL。

/mcp 不带 Authorization 标头时无需密钥。Agent 会为每个房间获取一个房间令牌，之后的每次调用都会传递该令牌。

确认

核心不会在没有人点击的情况下发出任何 approve（PROTOCOL.md §8）。 每个人在每个房间都有一个页面 human_url，卡片会停留在该页面上：

1. Agent 请求批准、拒绝或撤回。节点会暂存操作并 返回 human_url。
2. Agent 将链接通过双方共用的任意聊天工具发给对应的人。
3. 对方在指定范围内打开链接，阅读卡片并作出回应。

持有链接的人可以代表该席位作出回应，因此链接只会发送给对应的人。 在节点能够识别打开页面的人之前（ docs/ROADMAP.md），链接就是全部凭证。页面不支持推送：Agent 每次请求确认时都要发送链接。

还可使用 Telegram（TAASKY_CONFIRMATIONS=telegram），在聊天中添加推送和按钮，但这会以两种方式打破节点的承诺：

• 卡片会离开你的安全范围。 Telegram 会传输卡片文本，包括协调事项及其原因。Telegram 的服务器可以看到这些内容。
• 节点会暴露在互联网上。 机器人 webhook 需要 Telegram 通过 HTTPS 访问 TAASKY_BASE_URL。

只有在这两点都可以接受时才使用：

1. 使用 @BotFather 创建机器人。
2. 设置 TELEGRAM_BOT_TOKEN 和 TAASKY_CONFIRMATIONS=telegram。
3. 调用一次 POST /telegram/setup，将机器人的 webhook 指向 TAASKY_BASE_URL。

配置

变量	默认值
TAASKY_BASE_URL	http://localhost:$PORT	人和 Agent 使用的网址；如果位于代理后，则为代理的网址
PORT、HOST	8790、127.0.0.1
TAASKY_DB	taasky.sqlite	单个 SQLite 文件，使用 WAL
TAASKY_TRUST_PROXY	0	从 X-Forwarded-For 获取客户端地址
TAASKY_CONFIRMATIONS	web	web：仅使用个人页面；telegram：同时使用你的机器人
TELEGRAM_BOT_TOKEN	—	你自己的机器人，用于 TAASKY_CONFIRMATIONS=telegram
TAASKY_DEV_MODE	0	仅限回环地址：/dev/confirm、X-Taasky-Dev-User
TAASKY_ONE_HUMAN	0	仅限回环地址：每个席位对应一个人、一个页面，且所有操作只需一个人同意（taasky local 会设置此项）
TAASKY_AUTH_PER_MINUTE、TAASKY_MCP_PER_MINUTE	30、120	按地址或用户计算的速率限制

构建方式

core/ 是通过 npm run sync 从 core/COMMIT 中指定的提交复制而来的 taasky-mcp。src/ 是宿主端，提供 Cloudflare 为托管服务提供的一切功能：

Cloudflare	此处
D1	node:sqlite（src/d1.ts）
KV	同一文件中的一张表（src/kv.ts）
速率限制	内存中（src/limiter.ts）
静态资源	src/static.ts
每小时 cron	计时器

更多内容见 docs/ARCHITECTURE.md。

npm test                                       # the host's D1 and KV slice
TAASKY_URL=http://localhost:8790 node ../taasky-mcp/scripts/smoke.mjs   # end to end, against npm run dev

字体

页面使用 Instrument Serif、Inter 和 JetBrains Mono，遵循 SIL Open Font License 1.1。许可证见 licenses/。

许可证

FSL-1.1-ALv2，即 Functional Source License：

• 你可以出于任何目的运行、修改和再分发该节点，但不得用于与 Taasky 竞争的产品或服务。
• 为自己的团队或公司运行属于允许用途。
• 每个版本发布两年后都会转为 Apache-2.0。

协议（taasky/protocol）采用 Apache-2.0 许可证。