从命题到
双平面科研工作台

0.1 一句话产品

Open AI for Scientist（OpenAI4S）：跑在科学家自己电脑上的混合式科研智能体工作台——用便宜的豆包/方舟 API（¥9.9/月档也能用），完成从文献/数据库检索、数据分析、可视化到可复现证据包的闭环；不是又一个编程 IDE Agent，也不是多租户 SaaS。

0.2 Persona

0.3 Jobs-to-be-done

1. 检索并落地证据：查 UniProt / RCSB / PubChem / arXiv，结果要可哈希、可归档。
2. 在持久环境里算：多步 pandas/scanpy/RDKit 分析不因"每步重新开进程"而崩。
3. 留下可审计轨迹：每一步工具/Cell 进账本；危险操作弹审批卡。
4. 交付可分享包：导出 session / 证据包给合作者，而不是截图聊天。
5. 用得起：默认对接火山方舟 ark，¥9.9 Small 套餐可跑通主路径。

0.4 Non-goals（写进 PRD 才能挡住 scope creep）

0.5 成功指标

0.6 约束

• 模型：优先火山方舟（豆包等），亦支持 OpenAI / Anthropic / Gemini 线；密钥永不进仓库。
• 平台：macOS（Apple Silicon 为一等）+ Linux x86_64；Windows = WSL2。
• 运行时：Python 3.10+；核心纯 stdlib；科学栈进内核环境，不进控制面 venv。
• 数据根：~/.openai4s（可用 OPENAI4S_DATA_DIR 改）。
• 合规语气：生物安全筛查默认开；遥测默认关且需同意。

0.7 MVP vs v0.1

0.8 这一句话里藏着的墙

我们的首条用户故事：

"帮我查人胰岛素 INS，从 UniProt/RCSB 拉序列和结构，画一张简单图，把结果存成可复现产物，用中文总结。"

0.9 把 PRD 写成可执行的里程碑（建议排期）

0.10 产品原则（写代码时用来否决需求）

1. 账本是真相，UI 是投影。 任何"只改前端就当完成了"的 PR 直接打回。
2. 控制面与科学面不要竞赛。 同一步只走一个通道。
3. 错误的 provenance 比缺失更糟。 不知道就写明 missing reason。
4. 无订阅者不得默认允许。 安全事件不能因为"没人看卡片"而放行。
5. 核心零依赖是约束不是风格。 想加 httpx/fastapi 先写清楚为什么不能 urllib/http.server。

✅ 本步验收：你能向投资人/实验室 PI 用 90 秒讲清：两个平面、stdlib daemon、非 IDE、非 SaaS、¥9.9、macOS+Linux。

目的

把 PRD 里的边界变成目录所有权。OpenAI4S 后期翻车，80% 是"新能力塞错包"：把 GPU provider 写进 skills/、把 SQL 写进 gateway.py、把完成契约注册成普通 Tool。

实现形式

目标树（对照 85e9fa0）：

openai4s/
  agent/          # 外环：engine、ports、actions、ledger、compaction、delegation
  kernel/         # 内环：manager、worker、lazy、r_kernel、sandbox 协作
  sdk/            # 注入到 worker 的 host 门面
  host/           # 能力实现（files/llm/delegation/…）
  host_dispatch.py
  llm/            # urllib 多供应商
  tools/          # Native JSON Tool 子类 + registry
  store.py        # SQLite 门面
  storage/        # repositories + migrations
  server/         # gateway、SessionRunner、webui/
  skills_loader/  # 配方加载
  compute/        # BYOC 宿主侧（后期）
  security/       # 分层策略
  config.py prompts.py …
skills/           # 内置配方（数据，不是引擎）
envs/             # conda/micromamba 环境定义
openai4s_compute_provider/  # 远程侧 stdlib worker SDK

技术栈

• Python 3.10+ 包布局 + pyproject.toml / setuptools
• 禁止在核心包加硬第三方 import（numpy 等只允许内核侧或 try/except ImportError）

功能定义取舍

优劣分析

• 优：CI 与评审有"东西该放哪"的答案；mypy 可只严守 agent/{engine,ports,…} + host_dispatch.py。
• 劣：新人目录多；需要双语 README 守门（OpenAI4S 就是这么干的）。

如何与前后模块配合

• 前：PRD 的 non-goals 直接决定"没有 ide/、没有 saas/"。
• 后：第 2 步配置、第 4 步引擎、第 11 步 server 都挂在这棵树上。

flowchart LR
    PRD["PRD 边界"] --> PKG["包所有权表"]
    PKG --> AGENT["agent 外环"]
    PKG --> KER["kernel 内环"]
    PKG --> TOOLS["tools 控制面"]
    PKG --> SRV["server 投影"]
    PKG --> DATA["skills/envs 数据"]

1.4 第一周最小可运行骨架（建议直接建这些文件）

pyproject.toml
openai4s/__init__.py
openai4s/__main__.py
openai4s/config.py
openai4s/agent/{__init__,ports,models,events,actions,engine}.py
openai4s/llm/{__init__,client,transport,registry}.py
openai4s/tools/{__init__,base,registry}.py
openai4s/host_dispatch.py
openai4s/sdk/host.py
openai4s/kernel/{manager,worker,lazy}.py
openai4s/store.py
openai4s/server/{gateway.py,webui/index.html,webui/app.js,webui/style.css}
tests/test_agent_route_action.py

先让 python -m openai4s 打印版本；再让 AgentEngine 在 FakeModel 下跑通 finalize。不要一上来写 WebUI 美化。

1.5 所有权表示例（贴墙上）

✅ 本步验收：画一张"新 Tool / 新 Host 能力 / 新 SQL / 新 UI 路由"分别落点的表；随便指出一个错误落点并说明后果。

目的

在写 LLM 之前，先定：密钥从哪来、数据写哪、进程绑哪个口。科学用户会从 UI 配模型，也会用 .env；两者不能互相踩。

实现形式

• openai4s/config.py：Config / LLMConfig dataclass + 零依赖 .env 加载
• 环境变量分层：OPENAI4S_<PROVIDER>_API_KEY → OPENAI4S_LLM_API_KEY → provider 默认
• 数据根：~/.openai4s/{logs,artifacts,tool-results,compaction-history,openai4s.db,agent-workspaces,…}
• 端口：OPENAI4S_HOST=127.0.0.1，OPENAI4S_PORT=8760

技术栈

• dataclasses + os.environ + 手写 dotenv（不引 python-dotenv）

功能定义取舍

优劣分析

• 优：方舟/Claude/Gemini 密钥可共存；测试可把 OPENAI4S_DATA_DIR 指到 tmp。
• 劣：分层解析调试时要打印"到底命中哪一层"。

如何与前后模块配合

• 后接 LLM client（第 3 步）与 Store 路径（第 8 步）；Gateway 读同一 Config。

flowchart TD
    ENV["真实环境变量"] --> RES["LLMConfig 解析"]
    DOT[".env 不覆盖已存在"] --> RES
    RES --> KEY["api_key / base_url / model"]
    RES --> CFG["Config.data_dir / host / port"]
    CFG --> DB["db_path"]
    CFG --> WS["agent-workspaces"]

✅ 本步验收：只设 OPENAI4S_ARK_API_KEY 时 provider=ark 能读到；模板占位符被判定为无 Key。

目的

科学家的 Key 可能是方舟、DeepSeek、官方 Claude/GPT/Gemini。产品要一行切换供应商，但不能为每个 SDK 引入依赖——核心必须继续纯 stdlib。

实现形式

openai4s/llm/
  client.py          # chat() 编排入口
  transport.py       # urllib 的 post_json / post_sse
  registry.py        # PROVIDERS 目录（wire/model/base_url）
  providers/
    openai.py        # Chat Completions
    responses.py     # OpenAI Responses
    anthropic.py     # Messages
    gemini.py        # generateContent
  tooling.py messages.py capabilities.py catalog.py

对外兼容门面：from openai4s.llm import chat。

技术栈

• urllib.request + SSE 行解析
• 统一归一化：ModelReply / tool_calls（保留 raw_arguments + parse_error + provider_meta）

功能定义取舍

优劣分析

• 优：打包体积小；离线测试可整段 mock transport；方舟 ¥9.9 路径零摩擦。
• 劣：SSE/错误码要自己跟各厂文档对齐；严格 schema 差异要 capability 缓冲。

如何与前后模块配合

• 前：Config 解析 Key。
• 后：AgentEngine 的 ModelPort 包一层 ChatModel；Host 的 host.llm 也走同一 chat()。

sequenceDiagram
    participant E as AgentEngine
    participant C as llm.chat
    participant T as transport.urllib
    participant P as Provider API
    E->>C: messages + tools + on_delta
    C->>C: provider_spec + capabilities
    C->>T: post_sse / post_json
    T->>P: HTTPS
    P-->>T: SSE chunks
    T-->>C: deltas + final
    C-->>E: ModelReply(tool_calls|content)

3.4 最小 chat() 形状（你要先冻结的契约）

# 教学简化版 —— 生产代码见 openai4s/llm/client.py
def chat(messages, cfg, *, on_delta=None, tools=None, post_sse, post_json):
    spec = provider_spec(cfg.provider)
    wire = spec["wire"]          # openai | responses | anthropic | gemini
    model = cfg.model or spec["model"]
    base = cfg.base_url or spec["base_url"]
    # 1) capability 门闩  2) 译 tool specs  3) 调对应 wire
    return wire_dispatch[wire](...)

返回值必须能被 ModelReply.from_mapping 吃下，至少包含：

• content: str
• tool_calls: list[{id, wire_id, name, ordinal, raw_arguments, arguments, parse_error, provider_meta}]
• usage: {prompt_tokens, completion_tokens}

取舍：raw_arguments 与 parse_error 一并保留——路由层是无损边界，不是第二个 JSON 解析器。解析失败也要进 Ledger，不能静默丢。

3.5 为什么方舟走 OpenAI 兼容 wire

火山方舟 Agent Plan 暴露的是 OpenAI Chat 兼容端点。你把 provider=ark 编进 registry，复用 providers/openai.py，只改默认 base_url/model 目录。这样 ¥9.9 路径不需要第三套协议实现。

✅ 本步验收：对 fake transport 断言：ark 与 anthropic 都能产出同一形状的 tool_calls；无 Key 时错误信息指向正确环境变量名。

目的

写出可单测、不依赖内核/服务器的外环状态机。这是整条产品的脊柱：CLI openai4s run 与 Web SessionRunner._loop 必须共用，否则两个循环会漂移。

实现形式

• agent/ports.py：ModelPort / ActionExecutor / ContextPolicy / EventSink / CancellationPort / CompletionPort / ReplyInterceptor
• agent/engine.py：AgentEngine.run 回合循环
• agent/actions.py：route_action、CodeCell、NativeToolBatch、FinalizeAction
• agent/models.py：RunState / ModelReply / ExecutionOutcome / EngineResult
• agent/events.py：RunStarted…RunFinished

核心循环（语义压缩版）：

while turn < max_turns:
  prepare context
  reply = model.complete(messages, on_delta)
  action = route_action(reply.content, reply.tool_calls)
  outcome = executor.execute(action, reply, state)
  append history
  if outcome.stop_reason or completion: break

route_action 铁律：

1. 唯一原生调用且名为 finalize_response → FinalizeAction
2. 否则只要有原生调用 → NativeToolBatch（整批，控制面优先）
3. 否则从正文抽第一个完整 python /r Cell
4. 都没有 → None（上层 nudge）

技术栈

• 纯 typing Protocol + dataclass；mypy strict 守这几份文件

功能定义取舍

优劣分析

• 优：引擎可在无网络、无子进程下测路由与终止态；Web/CLI 只换适配器。
• 劣：模型若"边说边写两个 Cell"会被裁，需要提示词与 nudge 教育。

如何与前后模块配合

• 前：LLM ModelReply。
• 后：Executor 在 CLI 由 agent/runtime.py 装配，在 Web 由 WebActionExecutor 装配；真正干活进 Host/Kernel。

flowchart TD
    R["ModelReply"] --> RA{"route_action"}
    RA -->|"sole finalize_response"| F["FinalizeAction"]
    RA -->|"其他 native calls"| B["NativeToolBatch"]
    RA -->|"无 native"| X{"extract_action"}
    X -->|python/r fence| C["CodeCell"]
    X -->|无| N["None → nudge"]
    F --> EX["ActionExecutor"]
    B --> EX
    C --> EX
    N --> EX

4.4 FakeModel 驱动的第一份测试（建议原文落地）

class FakeModel:
    def __init__(self, replies):
        self.replies = list(replies)
    def complete(self, messages, on_delta):
        reply = self.replies.pop(0)
        if on_delta and reply.get("content"):
            on_delta(reply["content"])
        return reply

class FakeExecutor:
    def execute(self, action, reply, state):
        # 断言 action 类型，然后返回 ExecutionOutcome(stop_reason=...)
        ...

先测：

1. 唯一 finalize_response → 停止原因为完成；
2. web_search + 正文里的 ```python → 走 batch，不跑代码；
3. 正文两个 python Cell → 只抽第一个；
4. 未闭合 ```python → 不执行 + nudge。

等这四条绿，再接真 HTTP。

4.5 单回合在引擎内的微观时序

sequenceDiagram
    participant P as ContextPolicy
    participant M as ModelPort
    participant R as route_action
    participant X as ActionExecutor
    participant S as EventSink
    P->>P: prepare(messages)
    M->>S: TextDelta*
    M->>R: ModelReply
    R->>X: Action|None
    X->>S: OutcomeProduced
    alt stop/completion
      X-->>P: EngineResult
    else continue
      X->>P: history 追加，下一 turn
    end

✅ 本步验收：纯单元测试覆盖：finalize 优先、工具压过代码、多 Cell 只取第一、未闭合围栏不执行。

目的

无论调用从哪来——原生 Tool、或 Cell 内 host.web_search——都必须穿过同一道权限 / 审批 / 审计 / 注入筛查 / 活动事件信封。否则你会拥有两套互不一致的安全故事。

实现形式

• openai4s/host_dispatch.py：HostDispatcher.__call__(method, args) -> data
• openai4s/host/*.py：WorkspaceFileService、LLMService、DelegationService、CompletionService、SkillService…
• soft-fail：{"error": msg} → worker 转 RuntimeError

技术栈

• 线程锁 + 可选 ThreadPoolExecutor（只读工具并行波次在控制执行器侧）
• 与 tools.registry.get_tool_by_host_method 协作

功能定义取舍

优劣分析

• 优：审计与权限单点；Web 控制工具与内核 RPC 同策略。
• 劣：门面仍大，重构必须"外科手术"，禁止整文件重写。

如何与前后模块配合

• 后：SDK 只发 host_call；Kernel manager 调 Dispatcher；Ledger 记审计。

flowchart LR
    A["Tool.invoke / host.*"] --> D["HostDispatcher"]
    D --> P["permission / approval"]
    D --> I["injection screen"]
    D --> S["host service"]
    D --> L["audit / step event"]
    S --> OUT["data | {error}"]

✅ 本步验收：同一 web_fetch 从 Tool 与 host.web_fetch 进入时，审批与 audit 字段一致。

目的

让科学代码在 Cell 执行中途同步调用宿主能力：host.llm、host.delegate、host.save_artifact……这是 tool_use 架构没有的内环。

实现形式

• openai4s/sdk/host.py：worker 内 host 单例门面
• 启动 worker 时注入 host_call(method, args) 回调
• 编解码：SDK snake_case ↔ wire camelCase；None 字段省略（避免 JSON null 撞严格校验）
• host.bash：不在 Host 执行 shell；Host 只签发与 command hash / cwd / generation / challenge 绑定的一次性 token，worker 本地执行

技术栈

• 纯 Python 门面；无第三方
• HOST_CAPABILITY_VERSION 写入 bootstrap manifest，供恢复比对

功能定义取舍

优劣分析

• 优：科学家用 for/if/库组合能力；大对象不进 prompt。
• 劣：死锁风险——必须单飞行 host_call 锁 + 单 reader 循环。

如何与前后模块配合

• 前：Dispatcher。
• 后：Kernel 协议帧 host_call / host_ack / host_response。

sequenceDiagram
    participant Cell as Python Cell
    participant SDK as host SDK
    participant W as worker.py
    participant M as Kernel manager
    participant H as HostDispatcher
    Cell->>SDK: host.web_search(...)
    SDK->>W: host_call frame
    W->>M: stdout protocol line
    M->>H: dispatch(method,args)
    H-->>M: data
    M->>W: host_response
    W-->>SDK: return
    SDK-->>Cell: result

✅ 本步验收：在测试内核里执行 host.submit_output({"ok": True}, completion_bullets=["done"])，外环 stop_reason=submitted。

目的

科学平面落地：Tool/Finalize-only 回合不起 worker；第一个 Cell 才惰性拉起；命名空间跨 Cell 持久；stdout 与协议分家；OS 沙箱约束写路径与裸网。

实现形式

• kernel/manager.py：Kernel 宿主侧，spawn + 单线程读帧
• kernel/worker.py：Python worker；compile(..., "<kernel:N>") + linecache；getrusage 记账
• kernel/lazy.py：CLI 一次性惰性所有权
• kernel/r_kernel.py + r_worker.R：同协议；协议走 fd3/fd4，杂讯进 stderr
• kernel/environment.py：子进程环境 allowlist 重建（不继承 daemon 密钥）
• security/sandbox.py：macOS Seatbelt / Linux bubblewrap；auto|enforce|off

协议（概念）：

{"type":"execute","id":"...","code":"..."}
{"type":"host_call","id":"...","method":"web_search","args":[...]}
{"type":"host_ack","id":"..."}
{"type":"host_response","id":"...","data":{...}}
{"type":"result","id":"...","ok":true,"stdout":"..."}

技术栈

• subprocess + JSON lines
• POSIX 重定向（R）；Seatbelt / bwrap

功能定义取舍

优劣分析

• 优：Code-as-Action 把 14 次工具往返收成 1 个 Cell；内存态可复用。
• 劣：崩溃恢复、generation ABA、watchdog 都要认真做（见第 17 步）。

如何与前后模块配合

• Artifact provenance 绑定 kernel generation，不是 daemon 进程包列表。
• 安全层（第 19 步）叠在 spawn 边界。

flowchart TB
    T["Tool/Finalize 回合"] -->|不 spawn| Z["无 worker"]
    C["首个 Python Cell"] --> L["Lazy start python slot"]
    R["首个 R Cell"] --> LR["Lazy start R slot"]
    L --> SB["sandbox wrap"]
    SB --> W["worker subprocess"]
    W --> NS["持久 globals"]
    W --> RPC["mid-cell host RPC"]

7.4 协议实现时的三条铁律

1. 单 reader：只有 Kernel 管理线程读 worker stdout；supervisor/watchdog 不准偷读。
2. 单飞行 host_call：worker 持锁完成 host_call → host_response；并发 RPC 会帧交错。
3. generation 单调：每次 respawn bump generation；token/lease/审批绑定旧 generation 必须失效。

7.5 最小 worker 伪代码

# worker.py 概念版
for line in sys.stdin:
    msg = json.loads(line)
    if msg["type"] == "execute":
        # 重定向 stdout 到捕获缓冲，协议帧走另一条通道
        try:
            exec(compile(msg["code"], f"<kernel:{n}>", "exec"), ns)
            send({"type": "result", "id": msg["id"], "ok": True, "stdout": buf})
        except Exception as e:
            send({"type": "result", "id": msg["id"], "ok": False, "error": ...})

Host SDK 的 host_call 必须走与 stdout 捕获分离的通道，否则 print 与 RPC 互砸。

✅ 本步验收：连续两 Cell，第二 Cell 能读到第一 Cell 的变量；纯 finalize 回合进程列表无 worker。

⚠️ 还没完：协议抗污染与 provenance 品味见 第 7.5 步；那是本教程与「普通 Agent 教程」分道扬镳的地方。

目的

第 7 步让内核「能跑」。本步让你理解作者为什么把 worker 写成那样——这是 OpenAI4S 品味的物理落点。对照源码：kernel/worker.py 文件头、manager.py 单 reader、CLAUDE.md「错误的 provenance 比没有更糟」。

实验室 A · 协议分家（必做思想实验）

假设你偷懒：协议和 print 共用 fd1。

1. 模型 Cell 里 print(huge_df)；
2. 同时 host.web_search(...) 发 host_call；
3. manager 的 readline() 读到半截表格文本 → JSON 崩 → 整会话卡死。

OpenAI4S 的解法：

• Python：dup2(2,1) + 高位协议 fd 发布到 sys._openai4s_protocol_*（每次调用重新 resolve，禁止缓存）；
• R：协议走 fd3/fd4，杂讯进 stderr。

取舍：协议实现变「丑」；产品行为变「钝感正确」。

实验室 B · 帧上限不是拍脑袋

阅读 worker.py 里 _MAX_FRAME_BYTES 注释链：

• 先有字符上限 MAX_OUTPUT；
• 再发现 UTF-8 / \uXXXX / emoji 代理对让「字节」远大于「字符」；
• 常量从错误的 6 修到 12 字节/字符最坏情形，并由测试钉住。

品味课：科学 Agent 的用户会打中文、会打分子式、会打 emoji 注释。上限必须按最坏字符推导，否则你会在「看起来遵守了文档」时丢掉 error_lineno 与 usage——又是「错误比没有更糟」。

实验室 C · 单飞行 RPC 与 generation

flowchart TB
    A["Cell 调 host.llm"] --> L["获取 _HOST_CALL_LOCK"]
    L --> S["发 host_call"]
    S --> W["等待 id 匹配的 host_response"]
    W --> U["释放锁"]
    U --> N["Cell 继续"]
    R["worker respawn"] --> G["generation++"]
    G --> X["旧 bash one-shot token 全部失效"]

验收思维：若允许并发 host_call 无锁，你省下的是延迟，买下的是偶现错绑结果——科研场景不可接受。

实验室 D · provenance 绑定 generation

错误实现：capture_environment() 冻 daemon 的 pip freeze。
正确实现：查「写出该 Artifact 的 language slot 的 generation_id」再冻那个解释器的包集；若读不到，记缺失原因。

产品文案：UI 上写「环境未知（原因）」远好过写「环境 = 一串不属于它的包」。

功能定义取舍（本步专表）

如何与前后模块配合

• 第 5–6 步 Host 的软失败契约，依赖本步把 {"error"} 变成 Cell 内异常。
• 第 14 步 Artifact，依赖本步 generation 指纹。
• 第 19 步沙箱，叠在 spawn 外包；不能替代协议分家。

✅ 本步验收：能讲清「为什么 R 用 fd3/fd4」；能讲清「为什么帧上限用 12」；能讲清「为什么 R 产物不能盖 Python freeze」。讲不清就还没读懂内核。

目的

账本先于 UI：工具声明与结果、Cell 尝试、终止事实、usage、审批决议都要可重建。daemon 重启后，不能靠"浏览器还记得什么"。

实现形式

• store.py：单连接、RLock、schema/migrations、只读查询护栏、兼容门面
• storage/：frame / artifact / action ledger / approvals / settings / memories… repositories
• agent/ledger.py：把 AgentEvent 写成不可变 group/event；reducer 在崩溃后补齐半开工具组

关键不变量：

• 原生 assistant 声明 + 其全部 tool results 是原子组（compaction 也不能拆）
• 终止态 append，不从聊天气泡反推
• host.query 只读且 denylist 掉 settings/permissions/ledger 等敏感表
• PRAGMA user_version + schema_migrations；迁移单事务，非 WAL（审计库选择）

技术栈

• stdlib sqlite3
• 显式迁移地图 Store._migrate

功能定义取舍

优劣分析

• 优：Timeline、费用、合规审计同源；测试可断言轨迹。
• 劣：要同时维护投影（messages）与真相（ledger），费脑子。

如何与前后模块配合

• Engine 事件 → Ledger writer；Gateway 投影 assistant 可见文本；恢复流程读 journal。

flowchart TB
    E["AgentEvent"] --> W["RuntimeActionLedger"]
    W --> G["action_groups"]
    W --> V["action_events"]
    G --> R["reducer → provider-safe history"]
    R --> M["下次 model.complete"]
    UI["聊天气泡"] -.->|仅投影| G

8.4 迁移纪律（抄进团队约定）

• 新版本 = 新 step 函数 + SCHEMA_VERSION += 1
• step 禁止自己 commit；外层单事务
• 先 integrity_check，再 backup API，再 migrate；失败留备份
• 回填必须 WHERE 幂等
• 不要轻率改 journal_mode/synchronous：这是审计库，不是高 QPS 业务库

8.5 host.query denylist 心智模型

Agent 可以"看自己的数据库"——这很强大，也很危险。denylist 至少盖住：settings、权限表、原始 ledger、recovery journal、credentials 相关。剥离字面量后再匹配，避免 SELECT 'settings' 误杀，但 "settings" 标识符仍要拦。

✅ 本步验收：制造一次"工具组缺结果"的崩溃夹具，重启后 reducer 补 canonical error，而不是把半开 batch 送回模型。

目的

把确定性编排做成具名 Tool 子类目录：schema、安全策略、execute() 同文件；并用 Engine 自有的 finalize_response 关闭非科学回合。

实现形式

• tools/base.py：Tool / ToolSpec / invoke()（禁止直接 execute 绕过信封）
• tools/registry.py：TOOL_TYPES 唯一内置实例化点；禁止注册 bash / submit_output
• agent/finalize.py：封闭 schema（summary/findings/metrics/artifacts/limitations/next_steps/completion_bullets）
• 科学库广度不膨胀工具数：仅 science_list_dbs + science_search

技术栈

• JSON Schema 子集校验（自研/内置）
• provider adapters 把 ToolSpec 译成各厂 wire

功能定义取舍

优劣分析

• 优：分类清晰；权限元数据与行为不漂移。
• 劣：目录会长；要靠 taxonomy/side_effect_class 管住。

如何与前后模块配合

• route_action 识别 finalize；WebActionExecutor / CLI runtime 执行 batch；结果进 Ledger。

flowchart LR
    SPEC["ToolSpec 目录"] --> LLM["provider tools 参数"]
    LLM --> CALLS["native tool_calls"]
    CALLS --> RA["route_action"]
    RA -->|batch| INV["Tool.invoke → Dispatcher"]
    RA -->|finalize| FIN["finalize.py 校验 → CompletionRecord"]

9.4 控制工具并行波次（实现时别抄错）

只读且 resource_keys 不冲突的前缀可以并行；第一个可变/未知调用是屏障，之后串行；写回历史必须按 provider 原始顺序。并行完成顺序绝不能打乱 canonical group——否则 replay 与 compaction 全坏。

9.5 finalize_response 最小 schema 心智

模型必须给出：

• summary（有根据地）
• completion_bullets（1–4 条已完成动作短语）
• 可选 findings/metrics/artifacts/limitations/next_steps

Host 再校验一遍同一封闭 schema。科学 Cell 不要用它收尾，继续用 host.submit_output。

✅ 本步验收：试图 register_tool(bash) 失败；sole finalize_response 产生 structured completion；夹带其他 tool 时不走 FinalizeAction。

目的

把领域知识（对接、单细胞、折叠流程）写成可加载配方：SKILL.md + 可选 kernel.py sidecar。模型先看见 name+summary，需要时再 host.search_skills / load_skill——渐进披露。

实现形式

• 仓库 skills/<name>/SKILL.md
• openai4s/skills_loader/loader.py
• 用户技能仅 <data_dir>/user-skills；bundled 同名冲突时 bundled 只读胜出
• sidecar 使用前 compile-check
• Host 创作流：draft → personal；Web Customize 为 user origin，不能伪造 trusted origin

技术栈

• Markdown frontmatter + 文件树
• 与 Store 的 capability 状态代际绑定（loader 不缓存已 close 的 repo）

功能定义取舍

优劣分析

• 优：科学流程可版本化、可评审；引擎保持瘦。
• 劣：配方质量参差会变成产品体验；需要 readiness 检查。

如何与前后模块配合

• Tool：search_skills / load_skill；Cell 内 host.skills.*；远程 compute skill 带 provider.py（第 20 步）。

flowchart TD
    CAT["catalog: name+summary"] --> M["模型决定是否加载"]
    M -->|load| MD["SKILL.md 全文"]
    M -->|sidecar| PY["kernel.py compile-check"]
    MD --> CELL["Cell 按配方执行"]
    PY --> CELL

10.4 写你的第一个 Skill（最小配方）

skills/insulin-quicklook/
  SKILL.md

SKILL.md 建议结构：

---
name: insulin-quicklook
summary: 从 UniProt 拉取 INS 摘要并在内核中计算序列长度
---

# Insulin quicklook

1. 用 science_search 查 UniProt: INS human
2. 将序列写入 workspace
3. 开一个 python cell 计算 len(seq) 并作图
4. host.save_artifact(...)
5. host.submit_output(...)

不要把配方写成"神秘 JSON 工具"。配方的读者是模型与人类审阅者。

✅ 本步验收：未 load 时系统提示不含全文；load 后 Cell 可 import sidecar；用户技能无法 shadow 内置目录。

目的

把引擎产品化成本机工作台：REST 管资源，WS 管回合流式事件。继续零框架——科学家环境少一份依赖冲突。

实现形式

• server/gateway.py：组成适配器（大，但是门面）
• WSHub：订阅 root_frame_id、广播、断线续游标
• SessionRunner：会话状态、任务队列、run_message、_loop
• server/webui/：index.html / app.js / style.css 无构建步骤，直接从工作树提供静态文件
• 默认 bind 127.0.0.1；本地 auth / 安全头（CSP 等）

技术栈

• http.server + 手写 WS handshake/frames（见 ws_frames.py）
• 线程模型：阻塞 POST 跑回合 + WS 推送

功能定义取舍

优劣分析

• 优：./start.sh 简单；JS 改完刷新即得。
• 劣：gateway 文件巨大，新路由要落到 focused service，避免继续膨胀。

如何与前后模块配合

• 下一章专讲发送路径；Artifact/权限/恢复服务挂同一 runner。

flowchart LR
    B["Browser"] -->|REST| G["gateway.py"]
    B -->|WS| H["WSHub"]
    G --> SR["SessionRunner"]
    SR --> ENG["AgentEngine"]
    SR --> H
    G --> STATIC["webui/*"]

✅ 本步验收：openai4s serve 后 GET / 200；WS 升级成功；第二实例因 pidfile 拒绝启动。

目的

打通用户能感知的完整闭环：输入框 → POST message → 外环多回合 → WS 事件 → 助手气泡 / Activity / Artifact。这是验收产品的主路径，也是本教程最关键的一张时序图预演。

实现形式（对照源码）

1. composer：server/webui/app.js 的 send(text, opts)
2. 如无会话：POST /frames 创建，并 sub(frameId) 订阅 WS
3. 乐观渲染用户气泡；若 S.running 则标记 queued（服务端 FIFO 接纳）
4. 先 sub(currentId)，再 POST——否则首包 text_reset / text_chunk 会因未订阅被丢
5. POST /frames/{id}/message（单数；wait:false）→ Gateway 返回 202 + {job_id, execution_id, request_id}；turn 在后台线程跑，不阻塞 HTTP
6. SessionRunner.submit_message → FIFO ticket + MessageJob → run_message
7. SessionRunner._loop 组装 AgentEngine + ChatModel + WebActionExecutor + CompactionPolicy + WebEventSink
8. 引擎回合中：TextDelta / tool / cell 事件 → emit → WSHub.broadcast（每条 stamped 单调 seq）
9. 前端把 chunk 拼进助手 bubble；工具变 Activity 卡；写文件变 Artifact
10. 完成：server/completions.py 把结构化 output / bullets / artifact delta 投影为最终助手消息，再发终端 frame_update；S.running=false，composer 解锁

WS 续传契约（必须写进产品）：connectWS() 连 /api/v1/ws；view_session 带 since_seq（本 tab 已应用的最大 seq）与 epoch（daemon 进程身份）。daemon 重启后 epoch 变了 → replay_begin.gap=true → UI 必须 REST 重拉历史，不能假装「你已追上」。缓冲只覆盖当前进行中的 turn，不是全量事件日志。

技术栈

• fetch REST + WebSocket 客户端
• 服务端 threading + Event cancellation
• 手写 WS：ws_frames.py；resume 靠 seq + epoch，不是 Socket.IO

功能定义取舍

优劣分析

• 优：用户理解的"聊天"与真实账本解耦；刷新可重拉 messages；202 让 Stop / 排队 UX 可做。
• 劣：订阅时序、admission、队列提示、epoch 间隙都是细节雷区。

如何与前后模块配合

• 完整模块级回放见文末 🎬；权限卡与 Artifact 事件插在同条 WS 流。

sequenceDiagram
    autonumber
    participant U as 用户
    participant UI as app.js composer
    participant REST as gateway POST
    participant SR as SessionRunner
    participant ENG as AgentEngine
    participant K as Kernel/Tools
    participant WS as WSHub
    participant B as 助手气泡

    U->>UI: 输入提示词并发送
    UI->>UI: 乐观用户气泡；openTurnTicket
    UI->>WS: view_session(fid, since_seq, epoch)
    UI->>REST: POST /frames/{id}/message wait:false
    REST-->>UI: 202 execution_id
    REST->>SR: submit_message → FIFO → run_message
    SR->>WS: text_reset
    SR->>ENG: _loop → Engine.run
    loop 每个 turn
      ENG->>ENG: model.complete (SSE deltas)
      ENG-->>WS: text_chunk / notebook_cell / activity seq++
      WS-->>B: 流式渲染
      ENG->>K: Tool batch 或 Cell
      K-->>ENG: observation
    end
    ENG-->>SR: submitted / finalize / max_turns
    SR-->>WS: completions 投影 + frame_update terminal
    WS-->>B: 完成态
    B-->>U: 可读回复 + Artifact 入口

12.4 前端必须做对的四件时序事

1. admission id 在 POST 前生成并记住（注释/钉选场景）；服务端发的 id 在断线后帮不上忙。
2. sub(frameId) 在 POST 前；首包 delta 不可丢。
3. 用 dispatch 当下的 S.running 快照决定是否 openTurnTicket——中间有 await，旧快照会过期。
4. 不要把 header 上的 model 覆盖会话钉选 revision（源码注释里写过这个坑）。
5. 重连时带 since_seq + epoch；epoch 变化必须 REST 重拉，不可盲信缓冲。

12.5 服务端 run_message 责任清单

• 校验 frame/project 作用域
• 写入用户消息（含 annotation 消费）
• 忙则入队，闲则开线程（wait:false 路径）
• 线程内：领 FIFO ticket → _loop → completions 投影完成消息 → 释放 ticket → 拉下一条队列
• 任何异常：写 terminal failure（注意同 job 不要双写）

✅ 本步验收：浏览器手动跑一句；Network 里可见 POST .../message 返回 202；WS 有 text_reset/text_chunk；刷新后历史仍在；运行中再发送出现排队而非消失；杀 daemon 重连后 epoch 变化触发历史重拉。

目的

科学 Agent 会写文件、联网、跑 shell。产品必须把风险动作变成可点的审批卡，并且：无浏览器订阅 ≠ 自动放行；无头默认 deny。

实现形式

• permissions.py + Store 中 permission rules/requests
• HostDispatcher 在风险工具前 ask
• WebUI 渲染审批卡；决议写回 SQLite
• 语义：
• 进程仍在：唤醒同一阻塞调用
• daemon 已重启：记录 permission_resolution（旧操作未执行），要求 Continue/replan
• once：15 分钟内精确匹配 conversation/tool/target，原子消费
• OPENAI4S_UNATTENDED_APPROVAL=deny|allow

技术栈

• 持久化请求行 + 条件变量/事件唤醒
• 前端 WS 事件 permission_request

功能定义取舍

优劣分析

• 优：实验室可接受的安全叙事；审计完整。
• 劣：重启后"点了允许但没执行"需要 UI 文案教育，否则用户以为 bug。

如何与前后模块配合

• Tool 类声明 permission target；bash capability 另层绑定 generation。

sequenceDiagram
    participant T as Tool/host call
    participant D as Dispatcher
    participant DB as SQLite
    participant UI as 审批卡
    T->>D: 风险动作
    D->>DB: 写入 permission_request
    D-->>UI: WS 推卡
    UI->>DB: allow once/session/...
    alt daemon 未重启
      DB-->>D: 唤醒原调用
      D-->>T: 继续执行
    else daemon 已重启
      DB-->>UI: requires_continue
      UI->>T: 用户显式 Continue/replan
    end

✅ 本步验收：无头 deny 下风险工具失败；有 UI 时卡可点；重启后 once 不复燃旧参数。

目的

科学家要的不是"模型说过画了图"，而是磁盘上的版本对象：可预览、可回滚、可说明"由哪个 Cell / 哪个环境 / 哪些输入"产生。

实现形式

• server/artifacts.py：ArtifactManager（捕获、版本、CAS）
• Cell 事务结束：savefig、workspace diff → 新版本
• host.save_artifact / native SaveArtifactTool
• provenance：绑定 kernel generation 的 runtime/interpreter/env_name/generation_id
• 内核内 kernel/provenance.py：对象级 lineage tags（可 OPENAI4S_PROVENANCE_OFF=1）
• 检索结果带 provenance envelope（DB、请求、时间、SHA-256）

技术栈

• 内容寻址文件 + SQLite 元数据
• matplotlib 图由 gateway 负责 savefig（不要在 worker 里 autoclose）

功能定义取舍

优劣分析

• 优：可复现叙事；UI 可做"produced by cell N"。
• 劣：大文件与版本爆炸需要配额与清理策略（后期）。

如何与前后模块配合

• finalize/submit 可引用 artifact ids；导出 package 携带版本与 provenance。

flowchart TB
    CELL["Cell 写文件 / savefig"] --> CAP["ArtifactManager.capture"]
    CAP --> V["artifact_version"]
    GEN["kernel generation"] --> V
    LIN["lineage_edges"] --> V
    V --> UI["Artifact 面板"]
    V --> EXP["session package"]

✅ 本步验收：R Cell 产物的 provenance 不得显示成 Python freeze；同路径两次编辑产生两个 version_id。

目的

长科研会话会爆上下文。压缩必须保留可复现线索，且不能拆开原生工具原子组或 code/observation 对。

实现形式

• agent/compaction.py：estimate_tokens / should_compact / compact / CompactionPolicy
• 大输出落盘为 content-addressed archive，消息里留预览 + SHA-256
• 结构化 handoff 字段：Objective / Constraints / Decisions / Done / In Progress / Blocked / Next Move / Key Artifacts / Active Kernel Generation
• 系统提示与站立上下文（skills/memory）每回合重建，不被 compaction 误伤成"对话太长"

技术栈

• 纯函数模块 + 可选 LLM 摘要（SUMMARY_FORK）
• 无 Store 硬依赖（元数据由调用方注入）

功能定义取舍

优劣分析

• 优：长会话仍可续跑；费用可控。
• 劣：摘要质量依赖模型；要测"压缩后仍知道当前 generation"。

如何与前后模块配合

• AgentEngine 每回合 context_policy.prepare；Web 传入 branch/ledger 元数据。

flowchart LR
    M["messages"] --> E["ContextEstimate"]
    E -->|超阈值| C["compact"]
    C --> S["structured handoff"]
    C --> A["disk archive sha256"]
    S --> M2["准备给模型的短历史"]

✅ 本步验收：构造超大 tool result，压缩后出现 preview+hash，且 tool 组不被拆到非法状态。

目的

主 Agent 把子任务并行派给子 Agent（文献一组、清洗一组），但必须有预算与深度叶子，否则会分形炸机。

实现形式

• agent/delegation.py：树、预算、取消、steer
• 上限：FANOUT_CAP=48，SESSION_CAP=1000，MAX_DEPTH=4（第 4 层不能再委派）
• host.delegate / collect / stop_child / send_message
• 取消精确到子树；停掉的孩子不能再发布晚到输出
• Gateway 在 SessionState 上挂共享 DelegationBudget

技术栈

• ThreadPoolExecutor + contextvars 传递树
• 子 Agent 复用同一 AgentEngine 循环

功能定义取舍

优劣分析

• 优：真并行科研拆分。
• 劣：资源与权限传播复杂；子 Agent 的 workspace/policy 要显式。

如何与前后模块配合

• Host DelegationService；UI composer 有 delegation 选项；Ledger 记子运行。

flowchart TB
    R["Root Agent"] -->|delegate| C1["Child ≤ depth 4"]
    R --> C2["Child"]
    C1 -->|depth<4| G["Grandchild"]
    C1 -->|depth=4| L["Leaf 不可再 delegate"]
    R -->|collect| OUT["汇总结果"]

✅ 本步验收：深度 4 再 delegate 失败；stop_child 后无迟到 submit_output；session spawn 超限报错。

目的

同一会话里，Agent 回合、用户 REPL、环境切换、恢复写者不能抢内核。需要精确 owner + lease 的 FIFO，而不是"对会话 PID 乱发 SIGINT"。

实现形式

• execution/：协调器与 watchdog（CLI 也要用，故不放 server/）
• server/execution_coordinator.py：Web 适配
• kernel/supervisor.py：Python/R slot 生命周期；从不读协议帧
• 中断必须带 execution_id + owner.kind + owner.id + frozen lease
• 环境切换 build-first：新 worker 就绪才切指针

技术栈

• 排队票据 + 条件变量
• generation UUID 防 ABA

功能定义取舍

优劣分析

• 优：恢复与并发可测；避免"杀错代进程"。
• 劣：概念多（ticket/lease/generation），文档要写清楚。

如何与前后模块配合

• run_message、cell_run、recovery 都来领票；Artifact 捕获挂在 ticket 生命周期内。

flowchart LR
    Q["Agent / REPL / lifecycle / recovery"] --> FIFO["ExecutionCoordinator"]
    FIFO --> OWN["exact owner + lease"]
    OWN --> K["Kernel.execute"]
    STOP["Stop"] --> OWN

✅ 本步验收：回合运行中排队第二条消息；Stop 只打断当前 ticket；模拟旧 watchdog 无法杀掉新 generation。

目的

把 UniProt/RCSB/ChEMBL/PubChem/arXiv/OpenAlex 等变成两个工具 + host.science.*，并强制 provenance，使结果成为证据而非"模型记忆"。

实现形式

• tools/science.py + host science service
• 固定 HTTPS 端点走网络开关、SSRF/redirect 守卫、egress、审批、untrusted-output 筛查
• evidence.py / session package 导出
• workflows/ + openai4s/benchmark/：真实 Store/kernel 上的科学工作流基准（LLM/网络可注入）

技术栈

• stdlib HTTP 客户端封装（经 Host）
• JSON 规范化版本号

功能定义取舍

优劣分析

• 优：工具表稳定；证据可复查。
• 劣：上游 API 变更要维护归一化；限流要有降级。

如何与前后模块配合

• 首条用户故事的主路径；Artifact source=provenance；安全层共用。

flowchart LR
    Q["science_search"] --> C["connector normalize"]
    C --> P["provenance envelope"]
    P --> A["save_artifact(source=P)"]
    A --> E["evidence / export"]

✅ 本步验收：mock 上游返回后，artifact version 含 sha256 与 timestamp；改字节则哈希变。

目的

单一沙箱救不了科研 Agent。必须把互相独立的层叠起来：OS 沙箱、环境 allowlist、预执行分类、dlopen 钩子、生物安全、注入标注、egress、会话密钥、CSP……

实现形式（层表）

技术栈

• 平台分支（darwin/linux）；自我测试探针
• 静态/启发式/可选 LLM 分类

功能定义取舍

优劣分析

• 优：单层失效仍有其他层；合规叙事完整。
• 劣：调参多；CI 必须跑 Linux 分支。

如何与前后模块配合

• 贯穿 Kernel spawn、Host 网络工具、打包后的冒烟。

flowchart TB
    CELL["Agent Cell"] --> CL["pre-exec classifier"]
    CL --> SB["OS sandbox"]
    SB --> ENV["allowlisted env"]
    ENV --> RUN["worker"]
    RUN --> RPC["host RPC"]
    RPC --> EG["egress + permission"]
    RPC --> INJ["injection annotate"]

19.4 本地暴露的正确方式

需要同事访问时：

• ✅ SSH tunnel 到 127.0.0.1:8760
• ✅ 明确的本地 auth / token 门闩（若你加了）
• ❌ 在不可信网络 0.0.0.0 裸奔
• ❌ 把 daemon 当多租户网关

docs/security.md 开篇就写了：先读再暴露。把这句话抄进你的 README。

19.5 生物安全与注入是产品功能，不是合规贴牌

生信用户会碰到双刃内容。轨迹筛查默认开；网页工具结果必须标注"数据不是指令"。关掉它们要显式 env，并在 doctor 里显示姿势。

✅ 本步验收：关沙箱 self-test 失败时 auto 报告 degraded；enforce 不起 worker；web_fetch 默认拒 link-local。

目的

本地笔记本跑不动 AlphaFold/大模型推理时，把 job 投到用户自己的 GPU（SSH 或 NIM），同时保持密钥与沙箱边界。

实现形式

• openai4s/compute/：宿主侧 manager/registry
• openai4s_compute_provider/：远程侧 stdlib worker SDK
• Skills：skills/remote-compute-<id>/（provider.json + provider.py）
• host.compute.* / host.fold（严格不伪造）
• 密钥两段擦除：入口 scrub_secret_env → 载入 provider 后再按 prefix 擦
• 远程 helper 再套一层 confinement（家目录不可读等）；网络不隔离（本来就要调 API）

技术栈

• SSH / docker CLI 传输（非通用 pluggable Transport 层）
• 暂不实现 Modal/SLURM 一等公民（可用 SSH 上手写 sbatch）

功能定义取舍

优劣分析

• 优：BYOC 契合实验室资产；核心仍瘦。
• 劣：Prototype 体验锋利；文档必须写清信任边界。

如何与前后模块配合

• 建立在稳定的 Host/审批/Artifact 之后；打包阶段可先不捆绑 GPU 栈。

sequenceDiagram
    participant A as Agent
    participant H as Host compute
    participant R as Remote provider SDK
    participant G as GPU node
    A->>H: compute.create/submit_job
    H->>H: approval + scrub
    H->>R: stage + confined helper
    R->>G: run
    G-->>R: out.tar.gz
    R-->>H: harvest
    H-->>A: artifact paths

✅ 本步验收：无凭证时 fold 失败且不造假；helper 在 confinement self-test 失败时 exit 且不读凭据。

目的

让不会 git clone 的科学家也能用：Apple Silicon dmg、Linux tarball、Windows zip→WSL2、以及 pip install openai4s。

实现形式

• pyproject.toml 发布 wheel；skills*/envs*/workflows* 必须进 package data
• scripts/ 释出管线、DMG 构建、verify_release_artifacts.py
• macOS app：内嵌 Python + 默认科学栈；ad-hoc 签名，需 Gatekeeper 指引
• Windows：启动器装入 WSL2，跑同一 Linux 构建；原生 Windows 拒绝起内核
• openai4s doctor / diagnostics / verify-package

技术栈

• uv / pip；平台脚本；可选 micromamba 内核环境

功能定义取舍

优劣分析

• 优：分发面覆盖实验室主流机器。
• 劣：三平台释出成本高；公证/签名是持续负担。

如何与前后模块配合

• 前置所有运行时不变量；workflows 漏打包会导致 benchmark 假绿——CI 必须挡住。

flowchart TB
    SRC["源码 + skills/envs/workflows"] --> WHEEL["pip wheel"]
    SRC --> DMG["macOS arm64 dmg"]
    SRC --> TGZ["linux x86_64 tar.gz"]
    SRC --> ZIP["windows zip → WSL2"]
    WHEEL --> V["verify_release_artifacts"]
    DMG --> V
    TGZ --> V

✅ 本步验收：uv build 后 wheel 内能发现 skills 与 workflows；在干净机器 pip install 后 openai4s serve 能起。

模块触达清单（请对照着看）

sequenceDiagram
    autonumber
    participant U as 用户
    participant UI as app.js
    participant GW as gateway.py
    participant SR as SessionRunner
    participant FIFO as ExecutionCoordinator
    participant ENG as AgentEngine
    participant LLM as llm.chat urllib
    participant RA as route_action
    participant HD as HostDispatcher
    participant PERM as permissions+SQLite
    participant K as Kernel worker
    participant SDK as sdk/host
    participant ART as ArtifactManager
    participant LED as ActionLedger
    participant WS as WSHub
    participant STORE as Store SQLite

    U->>UI: 输入提示词，回车
    UI->>UI: 乐观渲染用户气泡；清空 composer
    alt 无 currentId
      UI->>GW: POST /frames
      GW->>SR: 创建 SessionState + workspace
      GW->>STORE: 持久化 frame
      GW-->>UI: {id}
      UI->>WS: sub(id)
    end
    UI->>WS: sub(currentId) 再发消息前强制订阅
    UI->>GW: POST /frames/{id}/message wait:false
    GW->>STORE: append user message
    GW->>SR: run_message(...)
    SR->>FIFO: 申请 ticket（若忙则排队）
    FIFO-->>SR: 获得 owner+lease
    SR->>ENG: _loop 装配 ports 后 Engine.run

    Note over ENG,LLM: Turn 1 · 控制平面检索
    ENG->>ENG: CompactionPolicy.prepare
    ENG->>LLM: complete(messages, tools, on_delta)
    LLM-->>WS: text deltas（经 WebEventSink）
    WS-->>UI: text_chunk → 助手气泡流式出现
    LLM-->>ENG: ModelReply(tool_calls=[science_search...])
    ENG->>RA: route_action → NativeToolBatch
    ENG->>LED: 打开 tool action group
    ENG->>HD: Tool.invoke → science_search
    alt 需要审批
      HD->>PERM: permission_request
      PERM-->>UI: 审批卡
      U->>UI: Allow once
      UI->>PERM: resolve
      PERM-->>HD: 继续
    end
    HD-->>ENG: 归一化结果 + provenance
    ENG->>LED: append tool results（原子组）
    ENG->>STORE: usage / frames tokens
    Note over ENG: observation 写回 messages，turn+=1

    Note over ENG,K: Turn 2 · 科学平面 Cell
    ENG->>LLM: complete(...)
    LLM-->>UI: 可选短说明文本
    LLM-->>ENG: ModelReply(content 含 ```python)
    ENG->>RA: route_action → CodeCell(python)
    ENG->>LED: cell attempt group
    ENG->>K: 若无 worker则 lazy spawn + sandbox
    K->>K: 执行分析代码，matplotlib 作图
    K->>SDK: host.save_artifact(...)
    SDK->>HD: host_call save_artifact
    HD->>ART: 登记版本
    ART-->>WS: artifact 事件
    WS-->>UI: Artifact 面板出现
    K->>SDK: host.submit_output(output, bullets)
    SDK->>HD: completion
    HD-->>ENG: CompletionPort 置位
    ENG->>LED: terminal submitted
    ENG-->>SR: EngineResult(stop_reason=submitted)

    SR->>STORE: 投影最终助手消息（中文总结+bullets+artifact delta）
    SR-->>WS: terminal / done 类事件
    WS-->>UI: 气泡定格；Stop 隐藏；composer 解锁
    UI-->>U: 可读结论 + 可点开的图与版本

    Note over FIFO: 释放 ticket；若有排队消息则下一轮 run_message

这一条链路上，你写的代码在哪？

推理可以租，科研运行时必须是自己的。

若模型选择"工具-only 然后 finalize"

路径在 Turn 2 变为：FinalizeAction → agent/finalize.py 校验 → 无内核启动 → 仍经 Ledger 与消息投影回气泡。这正是双平面的意义：不是事事进内核。

若用户在运行中又发了一句

send() 发现 S.running：气泡标 queued → 同一 POST messages 被 FIFO 接纳 → 当前 ticket 结束后自动开下一 turn。旧版"直接 return 丢消息"是产品级事故，不能回去。

B.13 帧上限按 ASCII 拍脑袋

症状：中文/emoji 多时 Notebook 丢 traceback。
根因：字符上限 × 错误的每字符字节假设。
修法：按最坏 UTF-8/JSON 转义推导（见 worker.py 注释）；加回归测试。

B.14 worker 里 autoclose matplotlib

症状：「图明明 show 了但 Artifact 没有」。
根因：gateway 还没 savefig，worker 先关了 figure。
修法：捕图责任在 gateway；worker 禁止擅自 close。

B.15 用 daemon 的 pip freeze 当 R 产物环境

症状：溯源面板看起来很完整，论文复现对不上。
根因：错误的 provenance 比没有更糟。
修法：绑定写出文件的 kernel generation；否则显式记缺失。