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> | 设置自身状态（空闲/工作中/阻塞） |
并发 / 隔离
舰船不得同时在同一 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 "<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 — 切勿 Read/Edit/Write/Glob/Grep 操作 DASHBOARD.md 或 dashboard/topics/*.md。
主题文件格式（前置元数据）
位于 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 或 Web 界面提交和查询结构化舰队报告（测试结果、构建摘要、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>）。完整参考和 Web 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 | 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 |