holaOS(Holaboss)桌面资源 Org 作用域设计:Automations / Channels / Projects / Browsers 的租户计费与可见性治理

原创2026-10-02 19:36:251,980 阅读
文章标签:AI AgentAgent 框架AI 应用人工智能桌面应用MCP 服务本地部署多智能体前端工作流自动化插件系统AI 技能

holaOS(Holaboss)桌面资源 Org 作用域设计:Automations / Channels / Projects / Browsers 的租户计费与可见性治理

本文基于 holaOS 仓库内的技术提案 docs/plans/2026-07-16-org-scoping-desktop-resources.md 展开。该提案围绕桌面运行时的"活跃 Org"(active tenancy + billing context)语义,系统梳理了四类桌面资源(Automations 自动化、Channels 渠道、Projects 项目、Browsers 浏览器档案)是否需要做 Org 级隔离,并给出与既有 Session 迁移(033-session-org-id)完全一致、可落地的统一实现模式。读完本文,你将理解"无人值守计费正确性"与"租户可见性一致性"这两种判据如何决定每个资源的去留,掌握迁移、创建、列表过滤、触发链路四段式改造的完整套路,并能直接对照仓库源码逐行验证。

一、背景:单用户单机下的"Org"到底是什么

Holaboss 桌面端的设计前提是 single-user / single-machine / single-root:一台机器、一个用户、一个根级安装。在这种架构下,提案中反复出现的 "Org" 并非传统的多租户组织实体,而是用户当前以何种身份行事的语义 —— 具体指:

  • Personal(个人):无 Org 归属;
  • 团队 Org(team org):用户切换到某个团队后,后续后端调用与计费都以该 Org 为准。

用户切换活跃 Org(active org)后,后端调用与账单归属随之重新作用域化(re-scope)。这个"活跃 Org"的来源,在源码中体现为 runtime/api-server/src/app.ts 里的 currentActiveOrgId() 函数:

// Org-owned sessions: the org active RIGHT NOW (from runtime-config.json, which
// the desktop keeps current on every org switch). Stamped onto a session at
// creation so all its runs bill this org regardless of later switches. Null =
// unattributed (the run falls back to the live runtime-config org).
function currentActiveOrgId(): string | null {
  return (
    resolveProductRuntimeConfig({
      requireAuth: false,
      requireUser: false,
      requireBaseUrl: false,
    }).orgId ?? null
  );
}

值得注意:currentActiveOrgId() 读取的是 runtime-config.json 中当前生效的 orgId,桌面端每次切换 Org 都会保持该文件为最新,因此它天然代表"此刻正在使用的身份"。

现状盘点:只有 Session 是 Org 作用域的

提案用一张表格明确给出了四类资源的现状,这是理解后续所有改动的起点:

特性 底层存储 已有 org_id?
Sessions(会话) agent_sessions 表 ✅
Projects(项目) projects 表 ❌
Automations(自动化) cronjobs 表 ❌
Channels(渠道) channel_connections 表 ❌
Browsers(浏览器档案) browser-profiles/index.json(文件,非数据库) ❌

也就是说,今天只有会话是 Org 作用域的。agent_sessions.org_id 由迁移 033-session-org-id 在会话创建时打上当时活跃 Org 的印记;运行时计费读取的是会话记录上的 org_id,而不是"活的" runtime-config,因此:

  • 工作中途切换 Org,该会话所有轮次的消费仍归属创建时的 Org;
  • 两个 Org 各跑一个会话,花费也能正确归属;
  • NULL 表示"未归属 / 遗留"(legacy),此时运行回退到当前 runtime-config 的 Org 计费。

这套"创建时打戳、触发时读记录"的语义,正是本次提案要复制到其他资源上的模板(详见后文"统一实现模式")。

二、决定每个案例去留的判据:计费正确性 vs 租户一致性

提案的核心方法论是:Org 作用域这件事,要拆成两个相互独立的原因分别判断,不能混为一谈。

判据 A:计费正确性(Billing correctness)——谁为这件事触发的 Agent 工作买单

只有在工作无人值守(unattended)触发时才真正关键:触发瞬间没有任何 UI 打开,所以"当前活跃 Org"这个概念此时毫无意义。这类资源必须在创建时就打上 Org 戳,并在触发时从记录上读取(而不是从活的 runtime-config 读取)——这正是迁移 033 总结出的教训。

判据 B:租户一致性 / 可见性(Tenancy coherence)——哪个 Org 在 UI 里看到 / 拥有它

即使某个资源本身从不单独计费,只要它作为"容器"或"资产"承载了 Org 作用域的内容,就需要在 UI 中按 Org 过滤可见性与归属权。

关键前提:交互式(interactive)Agent 工作已经通过会话的 org_id 正确计费了。因此每个资源只需回答一个问题:它是否在没有人参与的情况下触发可计费的工作?还是它只是一个容器 / 资产? 答案直接决定它属于 A、B 还是两者兼有。

三、触发本次设计的 Bug:自动化运行会话的 Org 缺失

提案指出的直接动因是一个真实的计费泄漏点:cronjob-runtime.ts 创建定时运行(scheduled run)的会话时,没有携带 orgId。该代码位于 runtime/api-server/src/cronjob-runtime.ts,当前实现为:

store.ensureSession({
  workspaceId: workspace.id,
  sessionId,
  kind: "main_session",
  title: cronjob.name.trim() || cronjob.description.trim() || "Scheduled run",
  createdBy: "cronjob",
  projectId,
});

后果链条非常清晰:

  1. 每次自动化触发的会话 org_id 均为 NULL;
  2. 按照 033 的语义,NULL 会话在计费时回退到触发瞬间的 runtime-config 活跃 Org;
  3. 于是出现提案描述的经典事故:自动化以 iMerch 团队身份创建,凌晨 3 点触发,账单却记在"UI 最后切换到的那个 Org"头上,而非创建它的 iMerch。

这与该项目此前修复的 gateway / session 计费泄漏属于同一类问题。从 cronjob-runtime.ts 的整体结构看,fireCronjob() 每次触发都会新建一个 scheduled-${randomUUID()} 形式的主会话并排队其首轮指令(buildRunTurnText 还会在指令中显式声明"调度已存在、本次只执行任务"以避免 Agent 误改调度),随后交由标准队列 worker 执行——全程无 UI 参与,正是判据 A 的典型场景。

四、四个资源的逐项裁定

提案对四类资源给出了明确、分级的结论,这是全文最核心的"决策结果"。

Automations(自动化)—— 必须作用域 · 正确性问题 · P0

  • 为什么:自动化按定义就是无人值守的。今天的运行会错误归属(即上文 Bug),属于正在发生的计费泄漏。
  • 改法:
    1. 为 cronjobs 表新增 org_id;
    2. 创建时打上 currentActiveOrgId() 的戳;
    3. 不可妥协的部分:让 cronjob-runtime 在 ensureSession 时把该 org_id 传入,保证每次触发都归属创建它的 Org,无论当前活的 runtime-config 是什么;
    4. 自动化列表按活跃 Org 过滤。

Channels(渠道)—— 必须作用域 · 正确性问题 · P0

  • 为什么:形状与自动化相同——一条入站 Slack / Discord 消息会在没有任何 UI 上下文的情况下触发一次 Agent 运行,需要有一个在连接建立时就打好的稳定计费归属;入站运行路径应从连接记录上读取 org_id。
  • 额外依据:后端已经把渠道连接器建模为 Org 所有(例如 HolaEmployee 连接器的 org-model),桌面端对齐即可。
  • 改法:为 channel_connections 表新增 org_id;所有读 / 列表 / 状态 / 断开操作都要按 Org 作用域(不仅仅是 connect)——提案明确提示这是为了避免重蹈"跨 Org Slack 泄漏"的覆辙。

Projects(项目)—— 必须作用域 · 一致性而非计费 · P1

  • 为什么:项目只承载交互式工作(你以某个 Org 身份在项目内打开会话),计费已通过会话正确完成。但项目是 Org 作用域会话的容器:若项目保持全局,同一项目在一个 Org 里显示 N 个会话、在另一个 Org 里显示 0 个,看起来就像"空 / 坏掉的项目"。作用域化是一致性修复。
  • 改法:为 projects 表新增 org_id;项目列表按活跃 Org 过滤。

Browsers(浏览器档案)—— 不作用域(精简方案)· 保持全局 · 推迟

  • 为什么:浏览器档案是设备本地的 cookie / 指纹 / 登录态存储——它们不同步、绑定物理机器,且 Agent 的浏览器运行已经通过驱动会话的 Org 正确计费。
  • 核心洞察:"给 cookie 做 Org 作用域"实际上意味着每个 Org 都要重新登录一遍——这是摩擦(friction),不是租户隔离(tenancy)。
  • 何时重审:仅当某个团队明确要求"每个 Org 拥有独立登录集"时才重新评估。

决策汇总表

特性 是否作用域 原因 优先级
Automations ✅ 无人值守计费(修复现存泄漏) P0
Channels ✅ 无人值守计费 + 后端已把连接器归 Org 所有 P0
Projects ✅ 与 Org 作用域会话保持一致性 P1
Browsers ❌ 设备本地资产;已通过会话计费 推迟

五、统一实现模式:完整镜像迁移 033

提案最重要的工程价值在于:四张表的改动不需要各自发明方案,而是全部套用迁移 033 已验证的模式。这个模式分为四个步骤,每一步都能在既有源码中找到对应实现。

第 1 步:迁移——新增可空 org_id + 部分索引

为每张待作用域的表新增可空 org_id TEXT,并建立 (org_id, updated_at DESC) 索引,条件为 org_id IS NOT NULL;不做回填(pre-existing 行保持 NULL,视为个人 / 遗留);迁移要以表存在为门槛,全新安装时为空操作(no-op)。

这一步的"标准答案"已经存在于 runtime/state-store/src/migrations/033-session-org-id.ts,其实现细节可以逐行对照:

export const migration: Migration = {
  id: 33,
  name: "session-org-id",
  up: (db) => {
    if (!listTableNames(db).has("agent_sessions")) {
      return; // 表不存在 → no-op(全新安装先建 seed schema)
    }
    ensureColumn(db, "agent_sessions", "org_id", "TEXT");
    // 索引 Org 作用域的侧边栏列表;NULL org_id 行被排除
    // (它们通过查询的 `OR org_id IS NULL` 匹配所有 Org,而非此索引)
    db.exec(`
      CREATE INDEX IF NOT EXISTS idx_agent_sessions_org_updated
          ON agent_sessions (org_id, updated_at DESC, created_at DESC)
       WHERE org_id IS NOT NULL;
    `);
  },
};

三个值得注意的实现要点:

  • 部分索引(partial index):WHERE org_id IS NOT NULL 让索引只覆盖有 Org 归属的行。NULL 行天然匹配所有 Org(通过查询侧的 OR org_id IS NULL),不需要索引支持——注释里解释得很清楚;
  • ensureColumn 幂等:先 PRAGMA table_info 检查列是否已存在,存在则直接返回,保证迁移可重复执行;
  • 表存在性门控:通过查询 sqlite_master 得到全部表名集合,若目标表不存在(例如全新安装时 seed schema 尚未创建对应表)则整体跳过。

第 2 步:创建路径——打上 orgId: currentActiveOrgId()

所有创建入口统一调用 currentActiveOrgId() 打戳。该函数在 runtime/api-server/src/app.ts 中定义,且已在该文件多处创建路径中投入使用(例如第 1787、9058、10717、10845 行等位置的 orgId: currentActiveOrgId()),说明"创建时读取、写入时固化"的调用方式在会话侧已经是成熟惯例,直接照搬到 cronjobs / channel_connections / projects 即可。

第 3 步:列表 / 读取路径——按活跃 Org 过滤

过滤规则是:

  • 团队 Org:严格 org_id = ?;
  • Personal:org_id IS NULL(个人 + 遗留数据合并视图)。

并且复用与 listSessions 完全相同的 orgId / onlyUnattributedOrg 参数形状。该形状的既有实现位于 runtime/state-store/src/store.ts:

listSessions(params: {
  workspaceId: string;
  includeArchived?: boolean;
  limit?: number;
  offset?: number;
  owningAppId?: string | null;
  excludeAppOwned?: boolean;
  /** Org-scoped sidebar: return only sessions owned by this TEAM org (strict
   *  `org_id = ?`). Omit to not filter by org. Personal is modeled as "no org"
   *  — use `onlyUnattributedOrg` for the Personal view, not this. */
  orgId?: string | null;
  /** Personal (no-org) view: return only sessions with `org_id IS NULL`
   *  (personal + legacy/pre-033). Ignored when `orgId` is set. */
  onlyUnattributedOrg?: boolean;
}): AgentSessionRecord[] {
  const clauses = ["(? = 1 OR archived_at IS NULL)"];
  const values: unknown[] = [params.includeArchived ? 1 : 0];
  const appId =
    typeof params.owningAppId === "string" ? params.owningAppId.trim() : "";
  if (appId) {
    clauses.push("owning_app_id = ?");
    values.push(appId);
  } else if (params.excludeAppOwned) {
    clauses.push("owning_app_id IS NULL");
  }
  const orgId =
    typeof params.orgId === "string" ? params.orgId.trim() : "";
  if (orgId) {
    clauses.push("org_id = ?");
    values.push(orgId);
  } else if (params.onlyUnattributedOrg) {
    clauses.push("org_id IS NULL");
  }
  values.push(params.limit ?? 100, params.offset ?? 0);
  const rows = this.workspaceRuntimeDb(params.workspaceId)
    .prepare<unknown[], Record<string, unknown>>(`
      SELECT *
      FROM agent_sessions
      WHERE ${clauses.join(" AND ")}
      ORDER BY updated_at DESC, created_at DESC, session_id DESC
      LIMIT ? OFFSET ?
    `)
    .all(...values);
  return rows.map((row) => this.rowToAgentSession(row, params.workspaceId));
}

该实现的三个可复用要点:

  • 语义分工:orgId 与 onlyUnattributedOrg 二选一,且 onlyUnattributedOrg 在 orgId 设置时被忽略——"团队 = 精确匹配、个人 = 无归属(含遗留)"的语义被固化在参数注释里,后续四个资源只需原样照搬;
  • 动态 SQL 拼装:按需向 clauses 追加条件、向 values 追加绑定参数,全部走 prepared statement,无注入面;
  • 排序稳定:ORDER BY updated_at DESC, created_at DESC, session_id DESC 保证 Org 过滤后的列表排序与全局列表一致。

第 4 步:无人值守运行器(cron、channels)——触发时读记录

只对 cron 与 channels 两类无人值守运行器:在触发瞬间从记录上读取 org_id(而不是活的 runtime-config),并传入生成的 ensureSession 调用。这正是当前 cronjob-runtime.ts 缺失、提案要求补齐的部分——改造后应形如"从 cronjob.org_id 取值并写入 ensureSession 的 orgId 字段"。

NULL 语义的一致性承诺

提案特别强调:NULL 语义与会话完全一致,因此 Personal 视图与迁移前的存量数据在四个资源面上行为保持一致——无论用户先在哪个资源上遇到"无归属"数据,看到的都是同一种预期行为,不会出现某个列表显示遗留数据、另一个列表却把它们藏起来的不一致体验。

六、悬而未决的问题(Open Questions)

提案如实列出了三个尚未定案的设计点,作为后续实施时需要决策的输入:

  1. 绑定到项目的自动化(cronjob.project_id):一旦项目也变为 Org 作用域,cronjob 的 Org 应当与其项目的 Org 保持一致——需要在创建时校验,并决定两者分歧时的行为(拒绝创建 vs. 以项目为准)。
  2. 迁移顺序 vs. 生产环境 Org 上线节奏:在生产(Supabase / Dokploy)上,该批迁移需要与已在推进中的前端 Org 网关接线(frontend org gateway wiring)按顺序编排,避免前后端语义脱节。
  3. Browsers 若未来要作用域:是给档案记录本身作用域,还是只给"驱动 Agent 的绑定"作用域——后者更轻,且能保持 cookie 在设备层面全局可用。

七、总结:一套判据、四段式模式、三个优先级

本次提案的完整逻辑可以压缩为三条主线:

  • 判据先行:先问"它是否在无人参与时触发可计费工作"——Automations 与 Channels 答"是",属计费正确性问题(P0);Projects 答"否但承载了 Org 会话",属一致性修复(P1);Browsers 是设备本地资产且已随驱动会话计费,直接推迟。
  • 模式统一:所有作用域改造复用迁移 033 的完整模式——可空 org_id + 部分索引 + 表存在门控、创建时 currentActiveOrgId() 打戳、orgId / onlyUnattributedOrg 双参数过滤、无人值守触发读记录。既有实现可分别对照 033 迁移、app.ts 的 currentActiveOrgId、store.ts 的 listSessions。
  • 修复优先:P0 的两项(Automations、Channels)直接消除正在发生的无人值守计费泄漏,P1 的项目一致性修复紧随其后,Browsers 留待团队显式提出隔离登录需求时再议。

对 Holaboss 桌面端而言,这份设计意味着:从"仅会话按 Org 计费"走向"容器与资产也按 Org 隔离",在保持 Personal 与遗留数据行为一致的前提下,让无人值守工作流的每一笔花费都归属其真正的创建者。

登录后查看全文
holaOS