Gateway / Workspace 架构重排 —— 交付汇报

一、结论

二、改了什么

2.1 一句话概括

这一轮动了两处：A 线动代码结构（gateway/ 一个包切成内核 / 骨架 / 两条产品线三层）， B 线动资产与内核契约（生产能力包从 examples/ 里搬出来独立成 workspace/tob， 内核不再靠 __file__ 硬推 agent 根）。两条线各自的前后对照分列在 2.2 与 2.3。

2.2 代码结构前后对照（A 线）

原来 gateway/ 一个包里塞了 26 个模块：内核管理器、桌面端（托盘 / webview / 登录）、飞书端混在一起， 且内核管理器反向 import 桌面端的品牌字面量。现在切成三层。

2.3 workspace 与安装器结构前后对照（B 线）

ToB 的生产能力包原来叫 examples/haitun-workspace，485 个文件，安装器打包打的就是它， 却和 11 个真示范件混住在同一个 examples/ 目录下。这一轮把它搬出来独立成顶层 workspace/tob。

2.4 关键数字汇总

2.5 workspace/toc 抽取（本轮新增）

以 workspace/tob 为起点，去掉落到飞书的能力，留下通用能力，抽出桌面版能力包 workspace/toc。

丢弃规则（按区块）：tests/ 67 个全丢（测的是 ToB 行为），channel_events/ 41 个全丢（飞书事件落库）， 43 个 ToB 专用 skill 丢，66 个不在通用闭包里的工具丢。

memory_* 5 个工具不带，因为这条链是硬的：

memory_*  →  _fusion_memory_mcp.py:56        _load_sibling_module("_fusion_memory_membership")
          →  _fusion_memory_membership.py:14  from _feishu_impl import list_chat_members_impl
          →  _feishu_impl.py

「谁的身份在写记忆」是拿飞书 open_id 认的，桌面版没有飞书身份，整条链落不了地。桌面版要长期记忆， 需要另设一套本地身份，不是把这条链搬过来 —— 列为 9.5 讨论项。

三、逐项任务与验收

A 线 · 骨架拆分（7 项）

B 线 · workspace 与内核（5 项）

四、骨架层剩下这 6 个文件，各自为什么留下

拆完之后有人会问：既然分了 ToC 包和 ToB 包，为什么骨架层还剩这几个文件？逐个给判据。

_oauth_manager.py 本来是第 7 个，本轮已搬进 feishu/，详见 4.1。

4.1 _oauth_manager.py —— 本轮已搬进 feishu/

它做的事很小：浏览器跳到 /oauth/callback 时，按一个随机串 state 把授权码 code 存进带 TTL 的内存信箱；发起方用同一个 state 从 /oauth/code 取走，一次即删。 用途是免去用户从地址栏手工复制授权码。

我最初把它留在骨架层，理由是「这段代码不认识飞书」。这一半成立 —— 69 行里零飞书字样，不碰 token 交换， 不知道 app_secret，也不知道是哪个用户。但漏查了实际消费者。补测结果：取件方全在 ToB 一侧，ToC 零调用。

workspace/tob/tools/_oauth_receiver.py:38    _CALLBACK_PATH = "/oauth/callback"
workspace/tob/tools/_oauth_receiver.py:220   client.get(f"{base}/oauth/code", ...)
workspace/tob/tools/_oauth_setup.py          整个文件都在讲飞书后台怎么登记回调
workspace/tob/tools/feishu_auth.py:16        通过 Gateway 的 /oauth/callback 中继
workspace/tob/tools/_feishu/auth.py:21       import _oauth_receiver

desktop/_auth_manager.py:7                   仅注释, 说命名风格与 OAuthRelay 同级
desktop/_auth_manager.py:16                  仅注释, "跳转留给将来的 OAuth"  ← 将来时

本轮已做（提交 456009d3）。实际改动面：文件搬到 gateway/feishu/_oauth_manager.py， server.py 去掉 3 处（app["oauth"] 赋值 + 两个 handler）与 2 条路由注册、改由 feishu/_routes.py 注册，spec 片段从 CORE_PATHS 挪进 FEISHU_PATHS， 另动 3 个测试文件与 gateway/AGENTS.md 3 处。

4.2 两个 _openapi* 文件是干什么的

不是注册路由，是生成一份 API 说明书。这两件事要分清：

访问 http://127.0.0.1:8080/openapi.json 拿到的就是这份说明书，前端和第三方靠它对接。 那三份是说明书的三个章节，第四份是装订工：

_openapi_core.py    728 行  →  18 条公共接口的说明   (/sessions /ais /titles /oauth ...)
desktop/_openapi.py 111 行  →   6 条 ToC 专属接口     (/ui/* /workspace/*)
feishu/_openapi.py   98 行  →   2 条 ToB 专属接口     (/feishu/route /feishu/routes)
_openapi.py          58 行  →  把上面三份订成一本

18 + 6 + 2 = 26 条，与改前 915 行单文件的 path key 集合一字不差〔实测两边都是 26〕

改前的毛病：26 条说明混在一个大字典里。飞书容器想只发布自己那 2 条做不到， 只能把 ToC 那 6 条一起发出去 —— 等于把桌面端的内部接口告诉飞书那边的对接方。

五、验证：怎么证明没坏

5.1 全量测试 —— 判据是「失败集逐条相同」，不是「失败数相同」

# 全量
57 failed, 1481 passed, 7 skipped, 653 warnings in 350.67s   ← 含 toc 抽取后的最新一次

# passed 由 1469 涨到 1481: toc 进契约表后 3 个 workspace 遍历测试的参数化用例
#   8 条 test_compact_history_chaining + 2 条 test_compaction_prompt_injection
#   + 2 条 test_workspace_hook_contract   (len(WORKSPACES) 12 → 13)

# 那 57 条不是回归，是 Windows 既有失败（asyncio 子进程 NotImplementedError）
基线 baseline-failures.txt : 57 行, md5 6af0fceab6945fb18c2f85d4efbf326b
本轮 junit-xml 提取        : 57 条
diff --strip-trailing-cr   : IDENTICAL   ← 参数化标记 [asyncio] 完整保留

5.2 路由表逐条核对

A7 把装配函数整体搬包，最大风险是漏挂路由。用同一份脚本跑改前（3d687c37）与改后两棵树，路由表逐条字节相同。

desktop routes: 46    feishu routes: 5    合计 51

5.3 三个前端产物实测

三份 dist/ 均被 .gitignore 覆盖，0 个产物被跟踪，git status 无受跟踪改动。

5.4 三向同步

本轮同步更新 8 份 AGENTS.md：根、gateway/、runtime/、session/、 workspace/tob/、desktop/spa/、desktop/spa-v2/、feishu/feishu-web/。

六、当前启动形态（团队常问）

# gateway/__init__.py:246  骨架先起
app = await create_core_app(aim, sm, tm, rm=rm, ...)
# :257  ToC 贴纸
await register_desktop_routes(app, favicon_path=..., app_name=..., attention=..., authm=...)
# :264  ToB 贴纸
register_feishu_routes(app, feishu_ai_id=..., feishu_workspace_root=...)

本轮拆的是装配函数，不是进程入口。收益在于「谁认识什么」现在写在函数签名里，两者零交叉。 真要一个纯 ToB 进程，代价是少调一行，不需要重构。启动命令一个字不变：

psi-agent gateway --listen http://127.0.0.1:8080 --browser

七、遗留与建议

7.1 workspace/toc 本轮已落地，Gateway 已能挂上，还差真跑一轮对话

原来的遗留是：workspace/ 下只有 tob 一个包，它一身两职 —— 既是 ToC 桌面端出厂的能力包 （安装器 haitun.iss:79 打的就是它），又是 ToB 飞书机器人的 workspace。实测其构成：

140 个 tools 的构成。另有 145 个 skills，其中 30 个名字含 feishu / 飞书。

本轮已做（提交 80b54129）：从现有包减出 ToC，不按原方案「以 openclaw-style 为基线新建」—— 实测该基线只有 5 个 tools、1 个 skill，从它起步等于把 ToC 出厂能力砍到近零， 是回退不是演进。落地数字与判定方法见 2.5。

两件相关事实：.iss 现在打的仍是 workspace\tob，抽 toc 没改它一行，安装器该打哪个包属 9.1； 共享层已查清 —— ToolRegistry.load(cls, tools_dir: Path, session_id: str = "") 只收一个 tools_dir，不改内核就没有多根目录，toc 与 tob 之间的重复无法避免，列为 9.4。

7.2 其他已知未修（均非本轮引入）

7.3 review 提出的改动（本轮已处理）

7.4 已推后（负责人决定）

B4 升级保数据、T1 真装真升实验 —— 属打包部署，落点取决于 workspace 结构。

八、我明确没验到的

如实交代，不含糊。

九、需要讨论的细节

9.0 讨论结论（2026-08-29 已过会，结论先行）

9.1 ToC 出厂内容与用户数据混在一起 —— 已定方向 A，实施推后

问题：安装器 haitun.iss 用一条通配 Source: workspace\tob\* 整目录拷贝， 出厂内容（systems/ tools/ skills/ 与几份提示词模板）和用户数据 （SOUL.md USER.md schedules/）落在同一个 {app}\app 下，结构上分不出来。

实测事实：{app}\app 挂的是 [Code] 段的 SwapComponent('app')， 升级时整目录换新。B3 试过把三项摘成独立 Source:（11 → 14 条），已撤回 —— 因为 Flags 不变的话，单独列出来的三项照样被换掉，清单长了 3 行，保护一点没多。

9.2 ToC / ToB 开发时怎么启动：一个进程还是两个 —— 已定：加启动参数分开选

问题：现在 workspace/toc 和 workspace/tob 两个包都在库里了，但开发时怎么起、起几个，没定。

Gateway.default_agent (__init__.py:79, 真参数)
  → resolve_default_agent(explicit)          _defaults.py:99
  → resolve_agent_package(explicit, repo_candidate="workspace/tob")
      1. explicit 非空 → 就用它                 ← 传 workspace/toc 这里就中了
      2. 否则 cwd/workspace/tob 是目录 → 用它     ← 「写死」其实只是这一层的候选
      3. 否则 cwd 自带 tools/+skills/ → 用 cwd    ← 装机形态
      4. 否则 "" → agent ≡ workspace

ERROR serve_session: Failed to start session server on
      \\.\pipe\psi\channels\<sid>: [WinError 5] 拒绝访问。
ERROR Session '<sid>' crashed: PermissionError(13, '拒绝访问。', None, 5, None)

9.3 SOUL.md / USER.md 到底归谁 —— 并入 9.1 的方向，实施推后

问题：这两个文件同时是出厂模板和用户数据。安装器要放一份初始版本进去 （否则新装用户没有），可它们又会被 agent 自己改写、被用户积累内容 —— 一旦改过，就不能再当出厂文件覆盖。

为什么单列：9.1 的三个选项都绕不开它。A 要求把用户数据搬出 {app}， 那「初始版本」是谁在什么时候放进去的（安装器？首次启动时生成？）；B 的 onlyifdoesntexist 正好为这种文件设计，但它意味着出厂模板一旦发布就再也改不动了 —— 老用户永远拿不到新版模板。

9.4 toc 与 tob 的重复成本是结构性的 —— 已定：短期接受重复，记为欠账

问题：workspace/toc 抽出来了，但它和 tob 之间没有共享层， 85 个工具文件、整个 systems/、102 个 skill 都是拷贝。tob 那边改一处通用工具的 bug，toc 不会跟着变。

实测事实：内核的签名是

ToolRegistry.load(cls, tools_dir: Path, session_id: str = "")   ← 只收一个根

不改内核就没有多根目录，符号链接 / 构建期拷贝那些办法都是在绕这个签名。

9.5 桌面版要不要长期记忆 —— 仍开放

问题：memory_* 那 5 个工具（跨会话长期记忆）没进 workspace/toc。

实测事实：这条链是硬的 ——

memory_*  →  _fusion_memory_mcp.py:56        _load_sibling_module("_fusion_memory_membership")
          →  _fusion_memory_membership.py:14  from _feishu_impl import list_chat_members_impl
          →  _feishu_impl.py

「谁的身份在写这条记忆」认的是飞书 open_id。桌面版没有飞书身份，整条链落不了地。 所以这不是「少拷了几个文件」，是桌面版缺一套身份。

9.6 ToC 的用户隔离靠什么 —— 并入 9.1 的方向（B 打底），C 仍开放

问题：ToB 的多用户隔离是完整的，ToC 没有对应物。桌面版是单机单进程，一台机器上如果有多个使用者 （家庭共用、同一台办公机多人登录），谁的会话、文件、记忆归谁，现在没有任何边界。

实测事实：ToB 侧隔离全部锚在飞书 id 上，三层都是（gateway/feishu/_feishu_manager.py）：

session id   私聊 feishu-<open_id>        群聊 feishu-chat-<chat_id>
workspace    <root>/<open_id>            <root>/chat-<chat_id>
管道名        psi\channels\<session id>

_sanitize_open_id 还专门把私聊 id 里的 - 转义，防止某人 open_id 恰为 chat-oc_x 时与群 oc_x 撞成同一个 session —— 注释直接写明那是「陌生人共享上下文的隐私事故」。 桌面版没有 open_id，这三层锚点同时失效：所有会话落在同一个 --default-workspace， 共用同一份 state/、histories/、todos/。

9.7 这次重排怎么合并、怎么推给全团队 —— 已定：一次性合并，改名先落，冻结期内做

7 个 CONFLICT (file location) 全部同源：main 在 examples/haitun-workspace/ 里新增了文件， 而本分支把这个目录搬走了。清单：tests/test_feishu_leave_query.py、tests/test_feishu_sheet_find_columns.py、 tests/test_feishu_sheet_grid_range.py、tests/test_feishu_sheet_truncation.py、 tests/test_todo_completion_standard.py、tools/_feishu/leave.py、tools/feishu_leave_query.py。 main 在这个目录里共 23 文件 / 2997 insertions，这批改动是合并的主要工作量。

问题：这次重排是 18 次提交、跨 gateway/runtime/session/workspace 四层的结构性改动，目前只在 refactor/gateway-workspace-evolution 一条分支上。怎么并回主干、并回去之后团队里在跑的分支和各自的 workspace 怎么跟上，没定。

9.8 顶层目录改名（会上追加决定）