理解 LearnGraph
从一条真实调用链开始

LearnGraph 仍处于早期开发阶段。开发者文档采用三种状态词，防止将未来设计或配置入口误解为已完成能力。

根目录脚本负责编排 React/Vite 前端与 FastAPI 后端。默认数据库和对象存储均为本地实现。

# 安装依赖并启动（首次运行）
npm.cmd run dev:install

# 后续联合启动
npm.cmd run dev

# 静态检查、现有测试与生产构建
npm.cmd run check

当前实现是前后端分离的模块化单体。浏览器只调用 LearnGraph 后端；外部模型、搜索、抓取、研究、 MCP 和存储都由后端经 Port/Adapter 边界访问。

后端依赖方向

业务服务不直接依赖厂商 SDK。新增外部能力应先定义或复用 Port，再提供适配器、能力探测和明确失败状态。

媒体不是“把文件塞进 prompt”。当前输入管线先判断文件能力，再选择原生模型、转录 Provider、索引检索或外挂视觉描述，并把每一步的状态保留下来。

当前仓库没有独立的网关微服务。FastAPI 的统一 /api/v1 路由层就是应用网关： 它终止认证、解析工作区作用域、校验权限、稳定错误结构，并把请求交给领域服务。

网关职责

路由域

SQLite 是 MVP 的规范业务事实源。本地文件系统承载默认对象存储， 但文件路径、外部 UUID 或 SSE 事件都不能替代数据库中的稳定业务身份。

Provider 是外部能力网关，不是业务事实源。业务层依赖 Protocol 定义的 Port； 适配器负责协议差异、探测、超时、限额和 Provider Trace。

能力快照与按供应商门控

供应商协议差异（搜索参数、思考模式开关、图片输入、计费字段）被建模为能力快照， 而不是散落在调用点的 if。发不发 enable_search 由"该供应商是否支持"决定—— 曾因向 OpenAI 兼容中继发送未知字段 enable_search 触发 400，修复后： 非 DashScope 中继一律不发；存量误标由 repair_non_dashscope_capabilities.py 修正。 极速模式的思考关闭同样按模型维护关闭矩阵（required / disabled / none / off），并拦截图片模型误作文本模型。

原生协议特化通道

DashScope 联网搜索的"返回搜索来源"（enable_source → search_info.search_results）与 "角标标注"（enable_citation + citation_format → 文本 [ref_N]）仅原生协议支持， OpenAI 兼容方式（Chat Completions 与 Responses）均不支持。QwenChatProvider 在 is_dashscope_origin 且开启 native_web_search、无 tools、纯文本时自动切原生通道 （POST /api/v1/services/aigc/text-generation/generation，X-DashScope-SSE: enable）， 带 tools 的 Agent 回合与多模态保持兼容模式；prepend_search_result 可提前返回搜索来源降低首包延迟。

模型消息抽象

ProviderChatMessage 保留 system/user/assistant/tool 角色、tool calls、reasoning summary 与协议原生 response items。原生 continuation state 作为不透明数据保存，不能被业务层臆造或跨协议消费。 Provider 连接按计划缓存跨请求复用（避免每条消息重建 HTTP 客户端与 TLS 握手）；usage 归一化拆分 input / cached / cache-creation，缓存 token 参与计费与预算（CNY/USD 多币种）。

Agent 模式是在持久化 Chat Session 上运行的受控工具循环。模型决定是否发起工具调用， 但工具可见性、授权、执行、结果裁剪、审计和持久化均由 LearnGraph 控制。

一次 Agent Turn

1. 01
   持久化用户输入

   用户消息、附件引用、所选节点与 Session 绑定先成为可追踪事实。

2. 02
   构建授权上下文

   只加入本次允许访问的节点、文件、选区和 Skill 指令；文档片段被标记为不可信参考数据。

3. 03
   计算工具注册表

   内置工具按角色开放；声明式 Skill 与 MCP 还必须具有 enabled 状态和持久 always Grant。

4. 04
   调用模型 Provider

   适配器把结构化消息与 JSON Schema 工具定义发送给已配置远程模型。

5. 05
   受控执行 Tool Call

   服务端解析参数、重新校验作用域与授权、执行领域服务或 Provider，并保存 Invocation / Audit。

6. 06
   继续或结束

   工具结果作为 tool 消息回填；模型可继续调用工具，最终文本和所有 MessagePart 一并持久化。

提示词由多个 system message 分层编译，而不是把所有内容拼成无法审计的单块文本。 核心规则稳定，工作区风格和本次授权上下文动态注入。

风格策略

工作区可选择 default、professional、friendly、candid、 efficient、exploratory、quirky 或 cynical。 五个附加特征均使用 -2…2。风格只控制表达方式，不得改变事实、工具权限或用户当前明确格式。

提示词注入防线

Tool 是给模型看的 JSON Schema 函数定义与服务端执行器的配对。注册本身无副作用； 只有模型输出 tool call 后才进入参数校验、权限检查和执行。

调用结果

执行器返回规范化的成功或失败对象，并可附带来源、Artifact、Extension Invocation ID、Sandbox Session ID 等安全元数据。意外异常不会把 SQL、HTTP、Provider 或沙箱实现细节泄露给模型；权威堆栈保留在服务端日志。

{
  "status": "completed",
  "data": { "…": "domain result" },
  "meta": {
    "extension_invocation_id": "…",
    "source_count": 3
  }
}

LearnGraph 区分两类 Skill。它们的安装、授权和运行语义不同，不能把文件包中的脚本当作自动 Tool。

生命周期

Skill Market 只提供系统级预缓存卡片；安装后才复制进工作区授权边界。本机 Skill 探测默认关闭， 只适用于前后端同机环境。翻译是按 content hash、locale 与 model 缓存的查看层，不修改源文件。

MCP Server 是工作区级外部工具目录。运行时不会信任注册表中的旧描述： 每次调用前重新发现能力并保存不可变 CapabilitySnapshot。

Transport 与网络边界

重授权规则

服务身份、工具、资源、Prompt、Schema 或注解变化会改变快照哈希；来源、版本、端点、认证指纹、 Manifest、权限或运行边界变化会改变授权哈希。任一变化都使旧 Grant 失效。 allow_once 在调用前消费，即使远程执行失败也不会恢复。

沙箱是 Docker-only、默认断网、按「聊天会话 × 属主用户」隔离的代码与文件执行边界。 宿主机永远不是 fallback：Docker、镜像 digest 或配置缺失时 probe 返回明确 unavailable，不会退化执行。 自 sandboxd 控制面（独立进程/服务）起，LearnGraph 业务进程不再直接控制 Docker Engine： 它只消费版本化、认证的 Sandbox API（create/exec/file/lifecycle），Docker socket、named volume 与 per-sandbox 内部 egress 网络均由 sandboxd 独占管理；app 生产镜像不再包含 Docker SDK。 系统内有两条互相独立的执行路径——sandbox-policy-v1 固定任务（只能跑内置 runner 检查已上传文件）与 sandbox-agent-v1 Agent 工作区（模型写文件、跑 .py/.js 脚本）——共用同一张 SandboxSession 表与后端，但按 policy_revision 严格互斥。

容器硬化基线

生命周期与双 TTL

CREATED → COLD → STARTING → RUNNING → WARM_IDLE → (COLD | EXPIRED)
# STARTING 先落库占位再调 Docker，容量统计含 STARTING/RUNNING/WARM_IDLE
# 超时 kill：容器被丢弃回 COLD；工作区数据保留
# 清理调度器对 STARTING/RUNNING 会话不动 bind mount（看门狗保护）

资源护栏

磁盘配额是双机制：内核级 fsize ulimit 限单文件 + 宿主侧聚合统计在写入前后与执行轮询每一拍检查。 宿主层另有保护：单用户 2 个活跃容器、部署级 20 个、宿主内存分配 ≤70%、CPU ≤80%、保留磁盘 ≥20 GiB、 单用户留存工作区 ≤10 个。默认值见 backend/app/core/config.py（LEARNGRAPH_SANDBOX_*）。

一次 Agent 命令的执行管线

1. 01
   argv 策略

   解释器白名单（python/node），禁止 -c/-m/-e/--eval/-p/-i 内联代码；入口必须是工作区内相对 .py/.js 文件；cwd 只能是 .；参数数与单参字节受限。

2. 02
   破坏性删除（默认免审批）

   rm / dd / mkfs / Remove-Item 等命令仅允许 work/ 子树（绝对 / .. / 盘符路径直接硬拦）；默认 LEARNGRAPH_SANDBOX_DELETE_APPROVAL_MODE=off 直接放行并保留审计（沙箱隔离，不影响宿主机文件），设为 on 时恢复会话级单次 Grant（TTL 60s–24h），缺失则 403 授权挑战经 SSE 弹窗回传。

3. 03
   幂等与审计

   Idempotency-Key 去重；持久化 SandboxAgentCommand 只存 argv 摘要与脱敏副本，stdout/stderr 落库前同样脱敏。

4. 04
   容量与容器

   进程锁 + 跨进程文件锁下校验用户/宿主容量，先提交 STARTING 占位再 docker create；失败回滚 COLD。

5. 05
   快照 → 执行 → 恢复

   执行前对工作区做 inode 级快照；100ms 粒度轮询超时与聚合配额；执行后凡未授权的删除一律从快照恢复并抛授权挑战——argv 拦不住的 shutil.rmtree 类软删除由此兜底。

6. 06
   结果与 SSE

   exit code / 超时 / 截断 / 延迟落库；结果转成 sandbox_status / sandbox_artifact MessagePart 流式呈现。

双层存储：物理工作区 + 逻辑工作区

Agent 工具面

六个工具（sandbox_write_file / read_file / list_files / exec / transcribe_audio / publish_file） 仅在 workspace.manage 权限且 SANDBOX_AGENT_ENABLED 时注入；chat_session_id 由服务端注入，模型不可伪造。Agent 模式开流前先过 agent_sandbox_readiness() 就绪契约， 不可用则整轮拒绝并给出中文修复步骤。音频转写是宿主侧桥：容器不联网、不接触凭据，ASR 调用在宿主完成计费与执行后回写工作区。

API 面

沙箱没有直接出网。需要联网的能力（网页抓取、依赖下载）必须经过工作区级审批链； 没有合法策略时容器保持 network_mode="none"（fail-closed，默认拒绝网络是安全基线）。

外部来源可信获取：联网下载，离线执行

download_external_image 与 download_github_source 不会给沙箱临时联网，也不向模型暴露 curl / wget / git clone。宿主侧 ExternalAcquisitionService 复用 Egress 审批卡 UI，但使用独立的 external_acquisition capability：下载批准只放行宿主下载器，绝不派生沙箱出网策略，通用沙箱 Grant 也不会自动放行下载。 allow_once 额外绑定规范化资源请求的 SHA-256，并在联网前通过条件更新原子认领（并发只允许一次执行）。 每次连接都重新解析全部 DNS 答案并拒绝任何私网/环回/元数据地址，HTTPS 连接固定到已分类的公网 IP；跨主机重定向必须再次审批。

web_fetch 热容器池

沙箱隔离的网页抓取每次请求原本要付完整容器生命周期（create → materialize → run → delete ≈ 1.5-3s 宿主开销/次）。 进程级热容器池按 工作区 + 白名单 + settings 指纹 复用空闲容器：

预构建镜像与真实进度

本地构建分钟级，支持发布预构建镜像到阿里云 ACR：只持久化 RepoDigest（本地 image ID 不可移植）， docker-py pull 显式传完整 tag（丢 tag 会静默拉 :latest 404），auto 模式拉取失败回退本地构建、显式 prebuilt 仍 fail-closed。 构建进度百分比来自后端真实 docker 事件（下载/解压/构建阶段 40-68%），BuildKit 的 \r/ANSI 日志清洗为可读行， 进度持久化、只前进不倒退、刷新不回跳；前端只渲染、不模拟。

整体 Docker 部署后，容器内 127.0.0.1 是容器自己，Provider/MCP 配置里保存的 http://127.0.0.1:11434（Ollama）这类逻辑地址无法直达真机。LearnGraph 不做 if docker: host.docker.internal 补丁，而是由Host Service Resolver在装配点 （backend/app/providers/factory.py 的 effective_base_url 与探测路径）按部署形态统一改写， 业务层与数据库始终保存逻辑地址。改写策略由 LEARNGRAPH_HOST_ACCESS_MODE 决定： auto（默认）｜ bridge ｜ direct ｜ off。

改写规则（host_service_resolver）

LEARNGRAPH_HOST_ACCESS_MODE=direct
docker compose up -d --build

状态与提示

GET /api/v1/providers/host-bridge/status 返回 host_access_mode、 bridge_reachable（bridge 可达性）、host_gateway_reachable（direct 模式下 host.docker.internal 是否可解析）、bridge_token_ready 与现成的中文 guidance； Provider 管理页按模式展示：bridge 未运行 → 提示启动 node scripts/host-bridge.mjs 并重启容器； direct 网关不可达 → 提示核对 extra_hosts: host.docker.internal:host-gateway。

沙箱、Agent 和可信组件产生的产物（sandbox_artifact、组件 Artifact、子应用 bundle）统一经过 Artifact Gateway 管理，遵循"发布即冻结"的版本模型，而不是工作区临时文件。

SSE 是传输层，不是事实源。Session、Message、MessageVersion、MessagePart 与流事件均持久化， 从而支持刷新读取、断点续传、分支、版本比较和 Provider 协议续接。

前端以 Message Part 渲染文本、来源、推理摘要、工具状态、可信组件和沙箱 Artifact。 未知组件安全降级为数据预览，不注入任意 HTML、脚本或 React 代码。

单写者下的落库工程

SQLite 只有一个写者，如果每个流 delta 都 commit，token 投递会被串行化在 fsync/锁获取后面。策略：

心跳、断线与恢复

可信组件是助手消息流里的声明式 UI 卡片（选择题、填空、天气卡、指标卡、图片框等）。它用 JSON Schema 声明数据面，而不是把任意 HTML/React 注入宿主 DOM。Agent 可通过 canvas_emit_trusted_component 发布内置组件，也可注册并授权第三方组件 Manifest 再发布。所有写操作经后端 Schema 守卫、哈希与审计， 前端对未注册或未通过 Schema 的组件安全降级为 JSON 预览，绝不执行脚本。

协议生命周期

1. 01
   register

   提交完整 Manifest，服务端做静态 Schema 守卫、签名记录与 example_data 校验，落 Plugin 与 ManifestVersion。

2. 02
   health_check

   对当前 Manifest 跑 JSON Schema 校验（render 检查在隔离浏览器未配置时标记 unavailable，不阻断）。

3. 03
   authorize + enable

   工作区对当前版本 + 权限指纹授权并启用插件；内置组件由系统固定，工作区不可改。

4. 04
   artifact / event_validate

   用授权后的组件把 data 校验成 Artifact，或把用户事件按 event_schema 校验后再处理。发布前由 assert_can_enable 校验 Manifest、授权与 health 全部当前。

Manifest 字段规范

Schema 安全约束

内置组件最小合法 props

{
  "title": "你更希望怎样验收这次学习？",
  "description": "单选一项后继续",
  "options": [
    { "id": "project", "label": "完成一个小项目" },
    { "id": "explain", "label": "能够清楚讲解" }
  ],
  "allow_custom": true,
  "allow_skip": true,
  "submit_label": "确认并继续"
}

{
  "title": "请补全 ACID 中的 A",
  "prompt": "ACID 中的 A 代表 ____",
  "placeholder": "Atomicity / 原子性",
  "multiline": false,
  "submit_label": "提交",
  "blank_ids": ["answer"]
}

{
  "title": "简答题",
  "columns": ["问题", "你的回答"],
  "rows": [["为什么需要索引？", ""]]
}

{
  "title": "杭州明日天气",
  "location": "杭州",
  "condition": "多云",
  "temperature_c": 27,
  "high_c": 29,
  "low_c": 21,
  "summary": "适合户外轻量复习",
  "unit": "C",
  "actions": [
    { "id": "create_plan", "label": "生成明日学习计划", "event": "create_plan" }
  ]
}

{
  "title": "今日学习指标",
  "description": "来自当前目标进度",
  "metrics": [
    { "id": "mastery", "label": "掌握度", "value": "62%", "hint": "近 7 日" },
    { "id": "reviews", "label": "待复习", "value": 3 }
  ]
}

{
  "title": "示意图",
  "alt": "B+ 树结构示意",
  "status": "placeholder"
}

完整第三方 Manifest 示例

以下是一个自定义 quiz_card 的完整 Manifest，可直接用于 POST /api/v1/plugins/components 或智能体的 component_register_manifest 工具。它满足全部 Schema 安全约束：顶层闭合对象、无禁用字段、 无 pattern / 外部 $ref、example_data 能通过自身 data_schema。

{
  "component_id": "acme.quiz_card",
  "version": "1.0.0",
  "display_name": "Quiz Card",
  "renderer": "sandbox",
  "author": "Acme",
  "source": "acme-marketplace",
  "package_hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "compatible_learngraph": { "minimum": "0.1.0" },
  "uninstall_behavior": "retain_data",
  "data_schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["question", "answer"],
    "properties": {
      "title": { "type": "string", "maxLength": 500 },
      "question": { "type": "string", "maxLength": 2000 },
      "answer": { "type": "string", "maxLength": 2000 },
      "hint": { "type": "string", "maxLength": 500 }
    }
  },
  "event_schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["type", "value"],
    "properties": {
      "type": { "type": "string", "enum": ["submit", "change", "select"] },
      "value": {
        "oneOf": [
          { "type": "string", "maxLength": 10000 },
          { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 1000 } }
        ]
      }
    }
  },
  "permissions": {
    "network_domains": [],
    "file_read": false,
    "clipboard_write": false,
    "message_actions": ["submit"]
  },
  "size_limits": { "min_height": 80, "max_height": 480 },
  "skill_triggers": [],
  "example_data": {
    "title": "练习",
    "question": "2 + 2 = ?",
    "answer": "4",
    "hint": "十以内加法"
  }
}

事件协议

用户在卡片上的交互以事件形式回传，按组件 Manifest 的 event_schema 校验。内置组件的默认 event_schema 要求 type（submit / change / select） 与 value（字符串或字符串数组）。allowed_events 限定可触发的事件名， 选项类默认 ["submit"]，weather_card/metric_card 由 actions[].event 推导，image_frame 默认为空。

智能体创建并应用

Agent 在拥有 workspace.manage 权限时，可直接在对话里创建并应用可信组件，无需切到设置页：

1. 01
   component_register_manifest

   提交第三方 Manifest，服务端做静态与健康检查并落审计；内置 ID 被拒绝。

2. 02
   component_authorize

   对刚注册的 plugin_id + manifest_version_id 授权当前工作区并启用插件（enable=false 可仅授权不启用）。

3. 03
   component_list

   查询已注册组件及其授权/启用状态，决定下一步是授权还是发布。

4. 04
   canvas_emit_trusted_component

   对自定义 component_type 传其 component_id 发布；已授权则按 sandbox_artifact 交付。

API 面

交互式子应用（subapp）是可信组件的进阶形态：不只展示，还能收集用户交互数据并接收 AI 写回的状态， 形成"用户操作 → 事件 → Agent 处理 → 页面更新"的多轮对话式交互。UI 与数据契约分离—— interaction_contract 定义数据格式，"千万种交互形式，结果一致"。

协议与生命周期

1. 01
   注册 bundle

   subapp_bundles 带 interaction_contract 与 component_manifest_id；契约校验顺序与组件 ID 匹配在服务端强制。

2. 02
   发布 / 预览

   发布产生不可变版本与 bundle 预览地址（独立 preview 源）；发布/预览到期校验做时区归一化。

3. 03
   双向通道

   iframe → postMessage 数据出口（宿主桥）→ 事件入库（T1.4 只读观察）→ 事件驱动 Agent 处理 → patch_state 写回（T2.5）→ 页面更新。

4. 04
   媒体注入

   视频 / 音频经 blob 注入（零联网）；地图等外部资源走经审批的会话级媒体域名。

安全不变量

安全边界贯穿路由、服务、扩展授权、Provider Secret、沙箱和输出渲染，而不是单独依赖前端隐藏按钮。

认证、供应链与发布治理

安全是默认值而不是功能：沙箱无策略即离线（fail-closed）、工具未授权即拒绝、Provider 能力不匹配即显式 unavailable—— 任何"静默降级"都被视为缺陷。

新增 Provider

1. 01
   定义 Port

   优先复用现有 Protocol；不要让业务 Service 依赖厂商 SDK。

2. 02
   实现 Adapter

   显式建模可用性、超时、响应校验、远程能力和安全诊断。

3. 03
   接入 Catalog / Probe

   配置保存后执行真实探测，失败保持 disabled。

4. 04
   记录 Trace / Usage

   保存 Provider ID、请求标识、用量与安全错误分类。

5. 05
   真实验收

   用部署方明确配置的远程服务验证，缺凭据时标记未完成。

新增 Agent Tool

1. 01
   从领域用例开始

   Tool 只调用现有 Service 或受控 Port，不直接访问数据库句柄。

2. 02
   声明严格 Schema

   限制字段、长度、枚举与 additionalProperties。

3. 03
   确定授权与副作用

   按用户角色、工作区、资源范围与是否需二次确认注册。

4. 04
   规范化结果

   裁剪大小、脱敏错误、记录 Invocation / Audit，并返回可追踪来源。

5. 05
   验证完整循环

   真实模型发起调用、真实服务执行、刷新后仍可读取结果。