holaOS(Holaboss)桌面资源 Org 作用域设计:Automations / Channels / Projects / Browsers 的租户计费与可见性治理
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,
});
后果链条非常清晰:
- 每次自动化触发的会话
org_id均为NULL; - 按照 033 的语义,
NULL会话在计费时回退到触发瞬间的 runtime-config 活跃 Org; - 于是出现提案描述的经典事故:自动化以 iMerch 团队身份创建,凌晨 3 点触发,账单却记在"UI 最后切换到的那个 Org"头上,而非创建它的 iMerch。
这与该项目此前修复的 gateway / session 计费泄漏属于同一类问题。从 cronjob-runtime.ts 的整体结构看,fireCronjob() 每次触发都会新建一个 scheduled-${randomUUID()} 形式的主会话并排队其首轮指令(buildRunTurnText 还会在指令中显式声明"调度已存在、本次只执行任务"以避免 Agent 误改调度),随后交由标准队列 worker 执行——全程无 UI 参与,正是判据 A 的典型场景。
四、四个资源的逐项裁定
提案对四类资源给出了明确、分级的结论,这是全文最核心的"决策结果"。
Automations(自动化)—— 必须作用域 · 正确性问题 · P0
- 为什么:自动化按定义就是无人值守的。今天的运行会错误归属(即上文 Bug),属于正在发生的计费泄漏。
- 改法:
- 为
cronjobs表新增org_id; - 创建时打上
currentActiveOrgId()的戳; - 不可妥协的部分:让
cronjob-runtime在ensureSession时把该org_id传入,保证每次触发都归属创建它的 Org,无论当前活的 runtime-config 是什么; - 自动化列表按活跃 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)
提案如实列出了三个尚未定案的设计点,作为后续实施时需要决策的输入:
- 绑定到项目的自动化(
cronjob.project_id):一旦项目也变为 Org 作用域,cronjob 的 Org 应当与其项目的 Org 保持一致——需要在创建时校验,并决定两者分歧时的行为(拒绝创建 vs. 以项目为准)。 - 迁移顺序 vs. 生产环境 Org 上线节奏:在生产(Supabase / Dokploy)上,该批迁移需要与已在推进中的前端 Org 网关接线(frontend org gateway wiring)按顺序编排,避免前后端语义脱节。
- 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 与遗留数据行为一致的前提下,让无人值守工作流的每一笔花费都归属其真正的创建者。