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

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

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

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

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

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

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

后端依赖方向

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

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

网关职责

路由域

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

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

模型消息抽象

ProviderChatMessage 保留 system/user/assistant/tool 角色、tool calls、reasoning summary 与协议原生 response items。原生 continuation state 作为不透明数据保存，不能被业务层臆造或跨协议消费。

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

一次 Agent Turn

1. 01
   持久化用户输入

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

2. 02
   构建授权上下文

   只加入本次允许访问的节点、文件、选区、Memory 和 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，不会退化执行。 系统内有两条互相独立的执行路径——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 等命令按路径逐一核对会话级 Grant（仅 work/ 子树，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 面

记忆系统是一套 Goal-Scoped Memory Graph：Canonical 事实存 SQLite，Provider 只做可重建投影。 每条记忆由 LearnGraph 生成稳定 lgm_<uuid>；Provider 路径或 Mem0 UUID 只是 Binding。 基线召回不依赖任何外部模型；抽取、语义检索、会话摘要三条增强管线按工作区独立开启。

记忆类型注册表

九种类型集中定义在 domain/memory_types.py，每种声明默认知识作用域、跨作用域合并策略与衰减策略。 权威业务状态（掌握分、路线版本、存储路径等）禁止写入记忆正文，创建时会被 422 拒绝。

召回管线（每轮对话）

1. 01
   策略闸门

   工作区总开关与 Session 开关必须同时开启，否则返回空包；Agent 的记忆/跨会话检索工具随同一开关一起消失，关记忆等于真隔离。

2. 02
   候选筛选

   只取 active 且位于 hot / recent / topics 区的记录；archive 区不参与召回。会话命名空间只见本 Session。

3. 03
   作用域动态继承

   子作用域不复制父记忆，查询时按 workspace → goal → node 组装有效视图；当前消息与选中节点作为召回上下文传入。

4. 04
   打分与语义放大

   启发式得分乘上可选的 Embedding 余弦相似度放大项；Embedding 未配置、失败或预算耗尽时静默退回纯启发式。

5. 05
   类型感知合并

   OVERRIDE / INHERIT_UNTIL_OVERRIDE 只保留最近作用域赢家并记录冲突；LOCAL_ONLY 不跨界。

6. 06
   Top-8 + Token 预算

   注入块受输入预算约 8%（400–3000 tokens，CJK 感知估算）约束，低排名条目被丢弃而非溢出；只有实际注入的记忆才累计访问强化。

strength = importance + 0.25·ln(1+access) + 0.30·confirm + 0.20·success
           + goal_bonus − decay_rate·elapsed_days − conflict_penalty
score    = strength × proximity × confidence × zone_factor × boost
# proximity: node 1.0 / goal 0.85 / session 0.8 / workspace 0.55
# zone_factor: hot 1.0 / recent 0.9 / topics 0.8；resolved 误区降至 0.15
# 配置 Embedding 后: score ×= 1 + weight·max(cosine, 0)

草稿流：唯一的自动写入通道

Agent 与后台抽取都不能直写长期记忆，一切变更先落 MemoryDraft（八种操作）。 CREATE 在置信度 ≥ 0.75 且类型不要求确认时可自动提交；UPDATE 一律人工审核； SUPERSEDE 会创建新记忆并以 supersedes_id 记录血缘，旧记录移入 archive 冷区留作审计。

写入与删除语义

1. 01
   Canonical mutation

   创建新 Revision、Provider-neutral Journal 与内容 Hash；更新走 expected_revision 乐观锁，冲突返回 409。

2. 02
   Provider projection

   写入 Active Provider，并按稳定 ID + Revision 精确回读校验。

3. 03
   Commit binding

   只有回读 Hash 一致才提交 Binding 与业务事务。

4. 04
   Recoverable delete

   删除后正文以每记忆独立密钥加密保留 30 分钟，密钥落在 SQLite 之外；Revision 正文立即清空。

5. 05
   Cryptographic destruction

   窗口到期由保留期调度器销毁内容密钥与恢复密文；删除 Journal 元数据最长保留 7 天。

可选增强管线

配置集中在 WorkspaceSetting memory.enhancement，三条管线互相独立、默认关闭； 全部调用计入 usage_events（feature 分别为 memory_extraction、memory_embedding、context_summarization），常见模型自动落价。

API 面

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

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

可信组件是助手消息流里的声明式 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 面

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

新增 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
   验证完整循环

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