starfleet — 艦隊協調
適用於並行 AI 代理工作階段（「艦船」）的艦隊級協調工具。涵蓋艦船間通訊、並行/隔離控制、任務捕獲以及 starfleetctl CLI。
艦船間通訊（通訊）
艦船透過 starfleetctl comms 進行通訊。訊息會經由系統提示注入自動送達 ——絕對不要手動呼叫 comms inbox（輪詢器已自動注入未讀訊息）。
通訊規則
- 務必回應。 當收到
tell或ask訊息時，透過starfleetctl comms tell <sender>回覆。沉默代表訊息已遺失。 - 回應後確認。 使用
starfleetctl comms ack <id>將訊息從收件匣清除。 - 通訊問題 → 回應兩處： 透過
comms tell回覆（讓發送者收到）並且在本地主控台輸出（讓人類能看到）。 - 保持狀態板更新。 開始或完成工作後設定狀態。
- 切勿呼叫
comms --help。 完整參考資料位於starfleetctl技能或本文件中。
關鍵通訊子指令
| 指令 | 用途 |
|---|---|
comms tell <ship> "<msg>" | 向一艘艦船發送指令 |
comms tell <ship> --stdin | 透過標準輸入發送大量資料 |
comms broadcast "<msg>" | 向所有艦船廣播 |
comms ask "<question>" | 提出問題（預期非同步回覆） |
comms ack <id> | 確認/移除收件匣中的訊息 |
comms board | 顯示艦隊狀態板 |
comms board --json | 機器可讀的狀態板（用於腳本） |
comms status <status> | 設定自身狀態（idle/working/blocked） |
並行 / 隔離
艦船不得同時在同一個 Git 工作目錄中工作。請使用獨立的克隆或工作樹。PR 分支所有權：每個克隆都推送到同一個 GitHub PR 分支 —— 在修改 PR 之前，請先使用 starfleetctl github pr claim。
關鍵規則
- 不同的工作樹不會互相覆蓋。 在獨立的工作空間中進行平行操作。
- 風險： 兩個操作者同時修改同一個克隆。
- PR 分支所有權： 在修改 PR 之前使用
starfleetctl github pr claim。
快速參考
starfleetctl github pr make <commit> [<commit> ...] # 從孵化器提交 PR
starfleetctl github pr mk-agent-clone <branch> [name] # 代理擁有的克隆
starfleetctl github pr claim <pr#> "what" # 聲明 PR 分支
starfleetctl github pr claim --release <pr#> # 釋放聲明
starfleetctl github backport commit <release> <commit> # 一次性回溯移植
.starfleet-ai/bin/starfleetctl worktree add <repo> [name] # 每個任務的工作樹
starfleetctl with-clone-lock <cmd...> # 序列化修改操作
任務捕獲
在儀表板中記錄一個任務，並可選擇指派一艘艦船。這只會下達指令——切勿親自執行任務。 不得直接存取 DASHBOARD.md 或 dashboard/topics/*.md 檔案。
單行指令
starfleetctl task capture --title "<標題>" \
[--desc "<需要做的事>"] \
[--slug "<覆蓋值>"] \
[--assign [<ship>]] \
[--no-push]
--assign（不含名稱）→ 路由至旗艦，由旗艦再委派或執行--assign <ship>→ 指派給特定艦船- 不含
--assign→ 記錄為開放狀態，無指派艦船
管理現有任務
starfleetctl task assign <slug> [<ship>] [--no-push] # 重新指派
starfleetctl task unassign <slug> [--no-push] # 清除指派
starfleetctl task status <slug> <status> [--no-push] # 設定狀態
starfleetctl task rm <slug> [--no-push] # 刪除任務主題
starfleetctl task purge [--no-push] # 刪除所有已完成任務
儀表板
儀表板是跨工作階段的「正在進行中」索引。所有存取都透過 CLI ——絕對不要對 DASHBOARD.md 或 dashboard/topics/*.md 執行 Read/Edit/Write/Glob/Grep。
主題檔案格式（前置資料）
位於 dashboard/topics/<slug>.md 的主題檔案使用類似 YAML 的前置資料：
---
title: "我的任務"
category: active # "active" 或 "parked"；預設為 "active"
kind: "task" # 可選；標記為可排程任務
status: "open" # 僅 active：open/assigned/done/...
assigned-to: "—" # 艦船名稱或 "—"
tags: "starfleet" # 可選，逗號分隔
---
只有 title 是必填的 —— category 預設為 active，所有其他欄位都是可選的。這是為了方便手寫主題：你可以放入一個最小的檔案，它會自動顯示在活躍列表中。
務必透過 dashboard topic list --json 列出主題 —— 沒有 dashboard list 這個子指令；dashboard list 是錯誤/無效的指令，會回傳 dashboard: unknown command: list。
| 指令 | 用途 |
|---|---|
dashboard topic list --json | 列出所有主題（JSON 格式，用於過濾） |
dashboard topic list | 列出所有主題（人類可讀格式） |
dashboard topic new <slug> | 建立一個主題 |
dashboard topic write <slug> <file> | 寫入主題內容 |
dashboard topic commit <slug> | 提交並推送主題 |
dashboard reindex | 重新整理 DASHBOARD.md 索引 |
dashboard commit | 提交並推送索引 |
報告
透過 CLI 或網頁 UI 提交與查詢結構化的艦隊報告（測試結果、建置摘要、CI 狀態等）。每份報告包含一個標題、可選的子標題、Markdown 內文、標籤、儀表板任務參考以及檔案附件。
關鍵指令
starfleetctl reports submit "標題" \
--subtitle "一句話摘要" \
--body "Markdown 內文" \
--body-file path/to/log \
--tags "ci,build" \
--task-ref xlibre/some-task \
--attachment path/to/file
starfleetctl reports list # 最新優先
starfleetctl reports list --ship Enterprise # 依艦船過濾
starfleetctl reports list --tag ci --json # 過濾 + JSON
starfleetctl reports show <id>
starfleetctl reports delete <id>
附件會上傳到檔案儲存庫（file put → /api/store/<name>）。完整參考資料與網頁 UI 操作說明請參閱 doc/reports.md。
Starfleetctl CLI
一個用於艦隊協調的 Go 語言 CLI。引導指令：./starfleet-bootstrap（更新 .starfleet-ai/）。完整參考資料：此技能目錄中的 reference.md。
子指令概述
| 類別 | 指令 |
|---|---|
| 艦隊 | comms, dashboard, ws-commit, ship-names, with-clone-lock, worktree |
| 工作階段 | run, session list/attach/stop |
| 任務 | task capture/assign/unassign/status/rm/purge |
| 計時器 | timer set/list/cancel |
| 網頁 | web start/stop/restart/autostart |
| 報告 | reports submit/list/show/delete |
| 設定 | genesis-init, self-install, sop install-starfleet |
| GitHub（讀取） | github pr view/ci/file-on-branch/wait-green/show-branch-file, github backport applies |
| GitHub（寫入） | github pr comment/label/set-body/checkout/amend-push/make, github backport commit |