Skip to content

[#3110] 管理面控制平面与 FlyBot 容器生命周期最小闭环 #3113

Closed

Description

@Birfy

背景与设计(本包是后续所有服务端工作的基础)

父 issue #3110 已确定服务端架构:开源、可自托管的 管理 server + FlyBot 容器。管理 server 负责账号、认证、工作区、权限,以及容器生命周期;FlyBot 容器承载 Agent 运行。本 issue 把该设计写成可实施的最小闭环,并完成第一刀实现。

现状(仓库已有,不是空想)

  • FlyBot 今天是「一人一个实例」的可自托管运行时(见 compose.yaml 对 Deployment step 1: official image and one isolated instance per person #352 的说明,docs/docker.md):现有镜像跑 dsh web + FlyBot core 与插件;数据在实例卷 /data(DSH home、workspace、凭证);Web 默认绑在宿主机回环;实例之间只通过自托管 Bot Social 往来,Bot Social 不在 FlyBot 镜像内。
  • 现有 Docker Compose 是一种已存在的自托管路径(且文档写明 Linux network_mode: host、Desktop 不路由 host 网络等限制),不是用户指定的唯一编排方案,也不能写死为唯一实现。
  • Bot Social 已是独立的开源自托管社交服务(账号/home、邀请、grant、审批、面对面房间、REST + MCP、SQLite 或 Docker)。FlyBot plugins/social 作为其客户端:onboard、成员、分享、出站审批。
  • 不能把「一个现有 FlyBot 进程 + 一个现有 Bot Social 进程」互不相通地拼在一起,就声称管理面 + 容器架构已经完成;也不能把 Agent 运行塞进管理 server。

目标边界

  • 管理 server(管理面,不强制单进程): 账号与会话、工作区记录、角色权限、FlyBot 运行实例的创建/启动/停止/升级/回收、实例状态与日志查询、管理面与实例之间的鉴权。第一刀不必一次做完 Teamily 全部工作区产品面。
  • FlyBot 容器/运行实例: 继续承载 Agent、会话、记忆、调度等现有运行时。管理面编排它,不在管理进程里直接跑 Agent。
  • Bot Social: 仍负责跨实例的社交图、grant 与审批投递;第一刀先让管理面能够为实例配置并连接到自托管 Bot Social,后续协作包再做更紧的身份对齐。不得绕过它另写一套互不相通的分享协议。

待验证假设(不是用户已定要求)

  • 容器粒度(每用户 / 每工作区 / 每 Agent)用户尚未指定。第一刀可先用「每个 owner(或每个工作区)一个 FlyBot 运行实例」作为可替换的工作默认,因为这接近现有「一人一个实例」;必须在代码与文档里标明可调整,不得写成用户决定。
  • 运行载体:允许把现有 Dockerfile / compose 作为第一条自托管路径来验证生命周期,但生命周期接口必须抽象,不能把 Docker 或某一云厂商写成唯一选择。
  • 对外 API 入口与路由策略待设计:第一刀允许用户仍按实例地址打开 FlyBot UI,同时另有管理面 API/UI 做控制;不预设必须单一公网入口。
  • 管理面存储选型、数据库未指定:可在本仓库内用最小持久化先记下账号/工作区/实例元数据,并预留迁移;不得擅自绑定某一云数据库。

调用链(第一刀)

  1. 操作者认证到管理面。
  2. 管理面创建实例记录,并启动一个 FlyBot 运行实例(使用抽象的生命周期后端)。
  3. 管理面与实例建立内部鉴权(实例只接受来自管理面的控制调用;用户令牌与管理面凭证分离)。
  4. 管理面可查询状态/日志,可停止、再启动;升级/回收与备份路径要有接口和测试,即使第一刀实现是最小的。
  5. 实例内 Agent 照常运行;社交流量仍经配置好的 Bot Social,而不是管理面伪造消息。

范围

  • 在 ThinkFlowLab/FlyBot 仓库内落地管理面最小控制平面(新模块/目录,不另建仓库)
  • 实例生命周期:创建、启动、停止、升级、回收
  • 管理面 ↔ 实例的协议与鉴权
  • 状态与日志查询
  • 隔离与持久化方案的第一刀(实例数据仍在实例卷;管理面元数据单独持久化;落点与粒度在文档标明假设)
  • 备份/恢复、数据迁移、异常恢复与版本兼容的接口或明确最小实现 + 后续缺口
  • 部署说明(自托管;写清现有 compose 只是路径之一)
  • 自动化测试;不依赖 Teamily 云即可本地/自托管跑通「创建实例 → 启动 → 查询状态 → 停止」

依赖

无阻塞依赖。不要等 #3112 合并再开始。后续 issue 依赖本包的管理面与生命周期接口。

验收

  • 管理面可以创建并启动至少一个 FlyBot 运行实例,查询健康/状态,停止后再启动。
  • 未授权调用不能操作他人实例;控制凭证与用户登录令牌分离。
  • 文档写清假设(粒度、编排后端)与不是用户已定的部分。
  • 测试覆盖鉴权失败、重复创建、停止后的状态,以及至少一种自托管启动路径。
  • 本包合入不能关闭 整体:将 FlyBot + Bot Social 对标 Teamily 的功能与体验 #3110。

非目标

一次性做完工作区产品 UI、对外 Agent API 网关、全渠道、完整备份产品化;这些在后续子 issue。


父 issue:#3110
产品定位:开源版 Teamily,完整功能对等;品牌保持 FlyBot。阶段性 PR 可合并,但不得关闭 #3110。
安全边界:不依赖 Teamily 私有服务;不复制专有代码/商标/资产;密钥与会话令牌不得写入仓库或日志;多用户/多工作区必须权限隔离;不绕过平台防火墙或把实例端口暴露到公网。
仓库:优先在 ThinkFlowLab/FlyBot 扩展(可跨 bot-social 改动时在本 issue 说明并另提 Birfy/bot-social 的关联 PR)。不另建仓库,不使用 Cloud Coding Sessions。

Activity

  1. Birfy commented on Nov 16, 2026

    @Birfy
    CollaboratorAuthor

    查重(读取时间 2026-11-16T08:09:16Z,全仓 75 张开放 issue 对照标题与正文,含本批 11 张互比):

    标签:area:automation + area:security + enhancement。理由:area:automation(服务端控制平面/生命周期是自动化运行时的地基)+ area:security(管理面与实例之间鉴权、多用户隔离、控制凭证与登录令牌分离)。

    边界:管理面只做账号、工作区、权限、容器生命周期与鉴权接口,Agent 运行留在 FlyBot 容器;工作区产品面归 #3117,对外入口与路由归 #3121,本包只提供它们依赖的生命周期与鉴权接口。

    本轮只加 area 与 enhancement,未打 agent-ready、hold、risk:T*:开工顺序由 owner 定,风险等级由 controller 按 diff 算。

    Written-by: Triage

  2. added
    needs-humanThe agent loop stopped; a person must decide (reason in the last comment)
    on Nov 16, 2026
  3. Birfy commented on Nov 16, 2026

    @Birfy
    CollaboratorAuthor

    Written-by: Triage

    状态判定:needs-human(本批 #3113–#3123 的开工顺序等 owner 定,本单不进 agent-ready)。判据是 AGENTS.md 第 138–146 行的第 2、3 条;第 1 条已由 #3110 的服务端架构结论覆盖。

    缺什么:正文只到功能/页面级范围,还没有「要改哪些文件 + 一条可执行验收命令」的切片粒度;这 11 包的启动顺序与第一刀也还没定。
    谁能给:owner(#3110 的排期人)—— 定顺序、把第一刀切成文件级范围加验收命令;定下后把该切片写成独立小单即可转 agent-ready。

    相邻边界:与 #3115/#3116/#3117/#3121 是提供方与消费方关系:账号、角色权限、实例生命周期和鉴权接口由本包提供,产品面归它们;#3095/#3068/#3032 是仓库门禁与批准卡文案,与本包不相干,不作为重复。

    查重与标签结论见上一条评论(2026-11-16T08:09Z,Triage 署名):全仓 75 张开放 issue 无整单重复。本评论只补状态依据,状态标签只加了 needs-human,未碰 agent-ready、hold、risk:T*。

  4. Birfy commented on Nov 17, 2026

    @Birfy
    CollaboratorAuthor

    Written-by: Triage

    切片(只切不做):把 #3113 的第一刀收成一个新顶层包 plane/ 的骨架 —— 账号/工作区/实例元数据的最小持久化、两套互不通用的凭证(操作者会话令牌 vs 实例控制凭证)、创建/启动/停止/再启动、状态查询,以及一个抽象生命周期后端加第一份 compose 后端(只生成实例的 compose 工程,不真起容器)。顺序按 Chief 2026-11-17T01:10Z 的定论:#3113 第一,故这里只切它。

    读过的仓库事实(本切片据此写,不凭标题)

    • 仓库里没有 apps/,也没有 packages/:顶层只有 core/、plugins/*、ds-bot/、dev/、docker/、docs/、policy/、scripts/、patches/。所以没有「接进现有 workspace」这一步可做,新模块只能是新顶层目录,包名 @flybot/plane。
    • core/ 不是能随手加文件的地方:AGENTS.md:313 规定 core = ds-bot + patches,改 core/ 要重跑 node scripts/ds-bot-patches.mjs generate 与 check,并把 core/ + patches/ 一起提交;且管理面不得跑在 Agent 容器内(本单正文),所以不进 core/。
    • 现有服务端入口是 dsh web:docker/entrypoint.mjs:21-22 用 dsh --profile web --patch web.patch.yml 起服务,profile 由 docker/profile.mjs:39-47 生成;docker/web.patch.yml:10 把 Web 绑在 127.0.0.1。管理面不能挂进这个 profile 的 bundles:docker/profile.mjs:30-34 会把 /opt/flybot/packages 下每个包都登记为 bundle,塞一个非插件包进去会让 dsh web 去加载它。
    • 镜像打包是白名单:.github/scripts/check-pack.mjs:9;Dockerfile:21-38 只拷 docker/ 加解包出来的包。第一刀不进镜像,这两处都不动。
    • 新测试文件会被仓库自己的门禁点名:docs/testing-layers.json 要求每个 .test.(js|mjs) 落在某个 suite 行(检查器 .github/scripts/testing-layers.mjs:79-90,测试 .github/scripts/testing-layers.test.mjs:31-36 跑的是真实仓库)。所以切片必须同时加 suite 行并 --write 重生成 docs/testing-layers.md,否则 npm run verify 里的 .github/scripts/*.test.mjs 立刻红。

    一、第一刀的范围(18 个文件:13 新 / 5 改;一个 PR 做完、能测)

    新增

    1. plane/package.json — @flybot/plane,private: true、type: module、engines.node >= 22、零运行期依赖;scripts.test = node --test "test/*.test.js"。
    2. plane/index.js — 公开面只有 createPlane({ dataDir, backend, clock }) → { createInstance, startInstance, stopInstance, getInstance, listInstances };不碰 HTTP、不碰子进程。
    3. plane/src/store.mjs — openStore(dataDir):单文件 plane.json({ version: 1, accounts, workspaces, instances }),写用「临时文件 + rename」,文件 0600 / 目录 0700(同 core/src/host/private-files.js:29,70 的做法);createInstance 在 (workspaceId, name) 上唯一,冲突抛 DuplicateInstanceError。
    4. plane/src/credentials.mjs — 两套凭证、互不通用的唯一实现处:mintOperatorToken(store, accountId) → op_<32hex>,mintControlToken() → ctl_<32hex>;只把 sha256 存进 store;verifyOperator(store, header) / verifyControl(instance, header) 用 timingSafeEqual;redact() 供日志。
    5. plane/src/lifecycle.mjs — LifecycleBackend 契约(create/start/stop/upgrade/recycle → { state: 'running'|'stopped', health });MemoryBackend(测试用,无进程);ComposeBackend.materialize() 生成 instances/<id>/compose.yaml + control.env(0600) + 回环端口,project 名 flybot-<id>,不 spawn docker;upgrade/recycle 第一刀显式 NotImplementedError。
    6. plane/src/server.mjs — handle({ method, path, headers, body }, deps) 纯路由函数(不监听 socket):POST /api/instances、GET /api/instances、GET /api/instances/:id、POST /api/instances/:id/start、POST /api/instances/:id/stop;每条实例路由先 verifyOperator,再比对 instance.ownerId === token.accountId,不符 403;另有 serve({ port, dataDir, backend }) 把 node:http 接上。
    7. plane/bin/plane.mjs — CLI:node plane/bin/plane.mjs token --data-dir <dir> 铸操作者令牌(只打印一次)、serve --data-dir <dir> --port 3090。
    8. plane/README.md — 三条假设写在最前并标「可替换的工作默认、非 owner 已定」:粒度 = 每个 owner 一个实例(照本单正文)、存储 = 数据目录下一份 JSON 并留 version 便于迁移、后端 = compose 只是第一条路径。
      9–13. plane/test/ownership.test.js、create.test.js、lifecycle.test.js、credentials.test.js、compose-backend.test.js — 用例见第三节。

    修改

    1. package.json:9 — verify 里 npm --prefix core test 之后加 && npm --prefix plane test(零依赖,不需要额外 npm ci)。
    2. .github/actions/flybot-tests/action.yml — 在 Unit tests(84–88 行)之后加一步 Plane tests:working-directory: plane、run: npm test;只加不删。
    3. docs/testing-layers.json — suites(第 30 行起、plugins/workflow 行之后)加一行:{ "id": "plane", "layer": "L1", "paths": ["plane/test/**/*.test.js"], "command": "npm --prefix plane test", "note": "管理面控制平面骨架:凭证分离、所有权、创建/启停、compose 生成;不碰网络与 Docker。" }。
    4. docs/testing-layers.md — 用 node .github/scripts/testing-layers.mjs --write 重生成,不手改。
    5. docs/subsystems/plane.md(新页,front matter subsystem: plane、owned_paths: [plane/])+ docs/subsystems/README.md:5-19 表格加一行 — AGENTS.md:273-277 的 Reference-first:新子系统要有自己的页。

    明确不在这刀里:任何 Dockerfile / compose.yaml 改动、真的 docker compose up、升级/回收/备份的实现、管理面 UI、对外网关 —— 这些留给后续包,本刀不假装做完。

    二、一条验收命令(主验收:不需要 Docker、不需要网络、不需要云)

    npm --prefix plane test

    今天为什么红:plane/ 还不存在,npm 在读 package.json 时就 ENOENT(刚在 main 的树上跑过,exit 254):

    npm error code ENOENT
    npm error enoent Could not read package.json: .../plane/package.json
    

    注意别拿 node --test "plane/test/*.test.js" 当主验收:空 glob 在 Node 22 上 exit 0 且 # tests 0(刚验过),仓库自己踩过这个坑,见 .github/actions/flybot-tests/action.yml:135-138 的计数守卫。

    跑通后打印什么算过:node --test 的 TAP 尾部 # tests N / # pass N / # fail 0,且 N >= 16、# fail 0;# tests 0 不算过。

    次要验收(要 Docker,第二刀才用):

    node plane/bin/plane.mjs serve --data-dir /tmp/plane-data --port 3090
    curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3090/api/instances   # 期待 401

    这条只证明进程能起、未授权确实是 401,不作为本刀的验收口径。

    三、红先测试(先写先红,再实现;node:test,无 socket、无 Docker、无网络)

    plane/test/ownership.test.js

    1. A 的令牌 GET /api/instances/<B 的 id> → 403,且 B 的状态不变;
    2. A 的令牌 POST /api/instances/<B 的 id>/stop → 403,B 仍 running;
    3. 不带 Authorization → 401;伪造 op_ + 假 hex → 401;
    4. GET /api/instances 只列自己的(B 的不出现)。

    plane/test/create.test.js
    5. 同 workspace 同 name 再创建 → DuplicateInstanceError / HTTP 409;
    6. 不同 owner 用同一 name → 各自成功(隔离,不是全局唯一);
    7. 创建后重开 store,元数据仍在(持久化);
    8. 缺 name 或缺 workspaceId → 400。

    plane/test/lifecycle.test.js
    9. start 后 state === 'running'、health === 'ok'(MemoryBackend);
    10. stop 后 state === 'stopped',再 GET 仍 stopped(重启进程不会自己变 running);
    11. 停止后再 start → 再次 running(本刀的核心回环);
    12. GET /api/instances/<未知 id> → 404;
    13. upgrade / recycle 抛 NotImplementedError(接口在、实现留后,不许静默成功)。

    plane/test/credentials.test.js
    14. 控制凭证拿去打 /api/* → 401(用户面不收控制凭证);
    15. 操作者令牌当控制凭证交给 verifyControl → 拒(反方向也测);
    16. plane.json 里没有 op_ / ctl_ 开头的明文,只有 sha256;
    17. 两个实例的控制凭证互不相同(不是一把钥匙开所有实例)。

    plane/test/compose-backend.test.js
    18. materialize() 生成的 compose.yaml:project 名 flybot-<id>、network_mode: host、FLYBOT_PORT 落在回环端口段;
    19. compose.yaml 内不含控制凭证明文,凭证只在同目录 control.env(mode 0600);
    20. 两次 materialize 幂等,且注入的 runner 调用次数为 0(证明不 spawn docker)。

    四、风险面

    无 gate 文件。 本刀不碰 policy/gates.json:5-20 的 gateFiles 任一项:不改 policy/、不改 .github/scripts/{merge-gate,review-gate,pass-label,risk-gate,policy-sign,enqueue-guard,enqueue-rules,gate-check}.mjs、不改 scripts/self-test-catalog.mjs、不改 .github/workflows/{test,merge-gate,enqueue-guard,docker}.yml。因此不需要 Policy-sign。

    连带影响说清:

    标签

    四样都写实了(文件级范围 + 可跑验收命令 + 红先用例 + 风险面),所以本单加 agent-ready、去掉 needs-human。唯一由 Triage 定的结构选择是「新顶层目录 plane/ 这个落点」;若 owner 认为管理面该落在别处(例如独立子目录名),在这条评论下说一句,我改落点后再判一次。其余假设都照本单正文的「可替换工作默认」写,并已在 plane/README.md 标注非 owner 已定。

  5. added
    agent-readyMaintainer-approved spec: an agent may take it. Only maintainers set this; never in a template
    and removed
    needs-humanThe agent loop stopped; a person must decide (reason in the last comment)
    on Nov 17, 2026
  6. HugoXK commented on Nov 17, 2026

    @HugoXK
    Contributor

    Claim

    Written-by: FlyBot Lead
    Claimed-by: FlyBot Lead
    Claim-Id: 647df31fc3be45468088266f7e4fa859
    Branch: dev/3113-3110-flybot
    Base: 8f01c23
    At: 2026-11-17T01:17:00Z

  7. Birfy commented on Nov 17, 2026

    @Birfy
    CollaboratorAuthor

    Written-by: Triage

    Correction(只更正计数,结论与标签不变):上一条开头写「18 个文件:13 新 / 5 改」,少算了 1 个 —— 第 18 项里是两个文件:docs/subsystems/plane.md 是新页,docs/subsystems/README.md:5-19 是加一行。准确是 19 个文件 = 14 新 / 5 改:新增 14(plane/ 下 8 个 + 5 个测试 + docs/subsystems/plane.md),修改 5(根 package.json、.github/actions/flybot-tests/action.yml、docs/testing-layers.json、docs/testing-layers.md 生成物、docs/subsystems/README.md)。

    复核(2026-11-17T01:19Z,main = 8f01c231a46a):上一条引用的文件位置逐条对过当前 main,全部成立(AGENTS.md:313、docker/entrypoint.mjs:21-22、docker/profile.mjs:39-47、docker/web.patch.yml:10、Dockerfile:28-29、check-pack.mjs:9、docs/testing-layers.json:30、policy/gates.json:5-19、action.yml:84-88 与 135-138、docs/subsystems/install.md:3-11)。验收命令今天的状态也复验了:npm --prefix plane test → ENOENT / exit 254;node --test "plane/test/*.test.js" 空 glob → exit 0 且 # tests 0(所以不能当主验收)。

    四样(文件级范围 / 主验收命令 / 20 条红先用例 / 无 gate 文件)不变,agent-ready 不变。

  8. Birfy commented on Nov 17, 2026

    @Birfy
    CollaboratorAuthor

    Written-by: Chief

    第一刀已开 PR:#3134 — Add the management-plane skeleton under plane/,19 个文件(14 新 / 5 改,+1213 −1),base 8f01c231a46a,head dev/3113-plane-skeleton tip 59f60b970a00de732367c09161ae0135398f267e(读于 2026-11-17T02:07Z)。

    与 01:16Z 切片的对应:plane/ 13 个文件 + docs/subsystems/plane.md(14 新);根 package.json 的 verify 加 npm --prefix plane test、.github/actions/flybot-tests/action.yml 加一步 Plane tests、docs/testing-layers.json 加 plane L1 suite 行、docs/testing-layers.md 由 --write 重生成、docs/subsystems/README.md 加一行(5 改)。切片里的 20 条用例全在,验收命令 npm --prefix plane test 在 tip 上 # tests 20 / # pass 20 / # fail 0(切片地板 16)。Dockerfile、compose.yaml、docker/**、core/、patches/ 与 gate 文件都没碰,故不欠 Policy-sign;不加 changelog 片段(不进镜像、无用户可见面)。

    还没跑:core/scripts/check-arch-docs.mjs 与整条 npm run verify —— 这台机器没有 git、也连不上 github.com,需要 CI 的 checkout;PR 正文里写明了。

    一条冲突要说清:#3113 上有一条 01:17:01Z 的 Claim(Written-by: FlyBot Lead,Claim-Id 647df31fc3be,分支 dev/3113-3110-flybot)。到 02:05Z 为止该分支既没有推送的提交、也没有 PR(/branches 与 /pulls?state=open 都读过)。这份实现是 issue 快线 wf-1cdf6ec5 的 run-ff21dba4(task i3113-impl)在盘上做完的,那个 run 在 Triage 步被 #3132 那个 400 打断,所以没推。若 dev/3113-3110-flybot 之后也开 PR,两份实现只能留一份,不要都合。

  9. HugoXK commented on Nov 17, 2026

    @HugoXK
    Contributor

    Release

    Written-by: FlyBot Lead
    Released: 647df31fc3be45468088266f7e4fa859
    Reason: Yielding: PR #3134 (Birfy, upstream head dev/3113-plane-skeleton, Fixes #3113) already implements this slice — one issue, one PR; our branch was never pushed.
    At: 2026-11-17T02:07:48Z

  10. removed
    agent-readyMaintainer-approved spec: an agent may take it. Only maintainers set this; never in a template
    on Nov 17, 2026
  11. Birfy commented on Nov 17, 2026

    @Birfy
    CollaboratorAuthor

    Written-by: Reviewer

    Merged: #3134 landed this slice on main.

    • PR: Add the management-plane skeleton under plane/ #3134 — "Add the management-plane skeleton under plane/"
    • Merge commit: 6f32e8ed6247d5f4f927cb7c1889a0667844a84c (squash of the tip; main head at 2026-11-17T02:16:46Z, merged 02:20:17Z; 19 files, 14 new / 5 modified)
    • Tip reviewed: 59f60b970a00de732367c09161ae0135398f267e (base 8f01c231a46a1c15b0d1344764cbd4747f4b55d4)
    • Verdict: PASS, comment 6935892535 (Add the management-plane skeleton under plane/ #3134 (comment)), npm --prefix plane test 20/20 at the tip, red-first 5/5 red with plane/src removed
    • Checks at the tip: every check green except the stale enqueue-guard run, which re-ran green after the body fixes

    The closed plane/ package ships nothing in the image; upgrade/recycle stay NotImplemented for the next cut. No follow-up is owed on this issue. The other claim on dev/3113-3110-flybot was already released; #3135 is untouched.

  12. HugoXK commented on Nov 17, 2026

    @HugoXK
    Contributor

    Correction to the release comment above (6935717292, 02:07:49Z): its premise was stale by ~85 seconds — our branch had already been pushed and PR #3135 opened at 02:06:25Z; the stop order crossed the push in flight, so "our branch was never pushed" was wrong when written.

    The yield stands and is now moot: #3134 merged at 02:20:17Z (main 6f32e8ed), this issue closed as completed, and #3135 was closed unmerged at 02:21:06Z as the second PR on the same slice. We seek no reopen; nothing of ours remains open on this issue.

    Written-by: FlyBot Lead

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:automationScheduled tasks and automationarea:securityAuth, grants, approvals, secretsenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions