跳到內容

五分鐘上手

  • Bun 1.4.4 以上。
  • PostgreSQL。init 建立的專案附有 docker-compose.yml,可以直接啟動一個。
  • 一個 Discord bot:有 bot 使用者、開了 Message Content intent,也已經邀請進你的伺服器。
  • 模型登入:你選的模型的供應商 API key(anthropic/... 用 ANTHROPIC_API_KEY),或之前用 Pi 登入過的帳號。
  • 一個從網際網路連得到這個行程的位址,例如通道(tunnel)。Discord 要從這個位址抓 agent 的頭像。

這一頁建立的是 Discord 專案。 想建立沒有 Discord、讓經 OpenID Connect 供應商登入的人用網頁聊天的專案,請執行 npx pi-roundtable init my-desk --adapter web,改看網頁聊天套件。 從 0.7 升級的話,見 Migrating to 0.8(英文)。

  1. 建立專案。init 會寫出一個能跑的專案,過程不會問你任何祕密資訊。 Bun 沒裝、版本太舊,或要建立的檔案已經存在時,它什麼都不寫。

    終端機視窗
    npx pi-roundtable init my-bot # 或:bunx pi-roundtable init my-bot
    cd my-bot
  2. 安裝依賴,並啟動 PostgreSQL。

    終端機視窗
    bun install
    docker compose up -d
  3. 把 .env.example 複製成 .env,然後填入內容。 Bun 會自己讀 .env,.gitignore 也已經擋掉它。

    終端機視窗
    cp .env.example .env
  4. 執行 doctor。全新的專案只會卡在還沒填的憑證,它會列出是哪幾個。

    終端機視窗
    bunx roundtable doctor
  5. 啟動 bot。

    終端機視窗
    bunx roundtable start

.env.example 說明了每個值的來源。

變數 內容
DISCORD_TOKEN bot 的 token,在應用程式的 Bot 頁面取得
DISCORD_GUILD_ID、DISCORD_ENTRY_CHANNEL_ID 伺服器,以及負責統籌的 agent 所在的頻道(開啟開發者模式後,按右鍵複製 id)
OWNER_ID、OWNER_NAME 你自己:唯一能改動一切的人
DATABASE_URL PostgreSQL;預設值與 docker-compose.yml 一致
MODEL agent 使用的模型,格式為 <provider>/<id>
PUBLIC_URL 能從網際網路連到這個行程的位址

bunx roundtable doctor 依序檢查下列項目,逐項印出通過或失敗,並說明如何修正:

  1. Bun 的版本。
  2. .env 對 .env.example 列出的每個變數都有值。
  3. roundtable.config.ts 符合其 schema,失敗時指出是哪個鍵。
  4. 每個外掛都能載入、沒有兩個外掛同名,而且註冊內容有效。
  5. access 服務哪些人:列出 owner;主機有不只一個 surface、又寫了 everyone: true 時提出警告,因為它會讓每個 surface 上的所有人都能對話。
  6. 有沒有外掛填了 images 槽位。沒有也不算失敗,agent 的頭像是組合出來的角色,不再靠它繪製。
  7. PostgreSQL 連得上,且能執行 migration。
  8. principal:預演下次啟動會從資料庫已知的人建立哪些 principal;設定裡 owner 的身分若連到別的 principal 就判定失敗(主機會因此無法啟動);owner 被停用時提出警告。
  9. Discord token 有效、bot 已在你的伺服器裡、Message Content intent 已開啟,而且 bot 在入口頻道有它需要的權限(包含 Pin Messages)。 bot 還不在伺服器裡的話,它會給你一個邀請連結,連結已經帶好這些權限。
  10. 模型登入存在。
  11. PUBLIC_URL 的格式正確;加上 --reachable 還要求它有回應,所以 bot 得先跑起來。

只要有一項失敗,就以非零狀態結束。 檢查過程不會改動任何東西。

bunx roundtable start 先執行不需要網路的檢查,其中任何一項失敗就停下來,並印出與 doctor 相同的訊息;全部通過則啟動 bot。 啟動後,agents.ts 裡的 agent 都有了自己的頻道,/roundtable schedule list 可以列出排程。 想知道第一句話寫在哪裡,看第一次對話。 收到 SIGTERM 或 SIGINT 時,它會先讓進行中的工作完成再停止。

想讓 agent 用上 Notion、行事曆或其他 MCP server 的工具,見 MCP connector 和 remote MCP。