数据截至 (上游 commit 38277815ed44)
OpenSpace — 架构与原理
30 秒导读: OpenSpace 是一个"技能进化引擎"——你把它挂到任意 agent(Claude Code、Codex、Cursor…)上, 它接管一个任务后用技能协议把技能渐进披露给模型(先看目录、按需加载全文);任务一结束,它会回看 整段录制、经触发器作业自动判断技能哪里该修/该加,用三种手术(修好 FIX、派生 DERIVED、新捕获 CAPTURED)改写技能并存进一个 SQLite 版本图谱,还能上云和别的 agent 共享。核心承诺: 同一类活越干越省 token、越干越可靠。
1. 这是什么(零基础也能懂)
一句话定义: OpenSpace 是一层"会自我进化的技能库 + 执行器",通过 MCP 协议插到现有 agent 上, 让它们从每次真实任务里学到经验并沉淀成可复用技能。
解决什么问题 / 给谁用。 今天的 agent(Claude Code、Codex、Cursor 等)有个通病: 每次任务都从零推理——同样的活反复烧 token、同样的坑反复踩、学到的东西困在单个 agent 里出不来。 OpenSpace 面向的就是想让 agent"越用越聪明、越用越便宜"的开发者。
它把三件事补给 agent:
| 补的能力 | 白话 |
|---|---|
| 自进化(Self-Evolution) | 技能坏了自己修、成功的模式自己升级、赢过的流程自己捕获成新技能 |
| 集体智能(Collective Intelligence) | 一个 agent 学会的东西上云,别的 agent 一条命令就能下载复用 |
| 省钱(Token Efficiency) | 复用成功方案而非从零推理;README 称在 GDPVal 上 少 46% token |
它能做什么(功能)。
- 接管一个自然语言任务,端到端执行(shell / GUI / 浏览器 / MCP 工具 / 系统自省 五类后端)。
- 执行中:按 Skill Protocol 渐进披露技能——轻量目录常驻、
DiscoverSkills按需检索、Skill工具加载全文。 - 执行后:自动分析录制,经 TriggerJob 流水线定向进化技能(修/派生/捕获),并写入版本 DAG。
- 对外:既能当 CLI/TUI 单机跑,也能当 MCP server 被别的 agent 调用;还能把技能上传/下载云社区。
用起来什么样。 最小用法就是一行命令(见 pyproject.toml:79,入口
openspace = "openspace.entrypoints.cli.main:run_main"):
# 示意,非源码:把一个任务交给 OpenSpace 执行
openspace --query "把这 15 个 PDF 里的报税数据汇总成一张表"
它会自动:披露技能目录 → 模型按需加载照着做 → 复盘 → 把学到的存进技能库。下次遇到类似任务,直接命中已进化的技能。
一句话直觉/类比。 把普通 agent 想成"每次都空手上阵的临时工";OpenSpace 给它配了一个 会随经验增厚的"操作手册柜"——干一次活,手册柜就多一页或改好一页错页;而且这个柜子能和其他工友共享。
本节不涉及底层代码。记住一句话:OpenSpace = 技能协议渐进披露 + 任务后自动进化 + 跨 agent 共享。
2. 顶层全景(它大概怎么转)
相比早期版本,上游做了一次大重构:
tool_layer.py(旧总控)被拆成openspace/application.py(门面)+openspace/runtime/(运行时编排)+openspace/agents/turns/(回合循环)。 本图与全文引用均以新版源码为准。
怎么读这张图: 从上到下是一次任务的时间线。左边"控制平面"是每次任务都跑的主循环; 右边"进化平面"在任务结束后才启动,回头改写技能库;技能库(SQLite + 磁盘 SKILL.md)是两个平面共享的记忆。
宿主 agent / CLI ───▶ OpenSpace.execute(ExecutionRequest) 〔application.py:772〕
(Claude Code…) │ 委托
▼
┌──────── 控制平面:一次任务的主循环 ────────────────┐
│ ExecutionLifecycle.execute 〔runtime/execution_lifecycle.py:80〕
│ · 会话准备/录制启动/workspace 解析
│ · run_turns ─▶ GroundingAgent.process 〔grounding_agent.py:644〕
│ 回合循环:LLM 想 → 调工具 → 看结果 → 没工具调用即完成
│ · skill_listing 轻量目录注入 〔skill_engine/protocol.py:247〕
│ · DiscoverSkills 按需找技能 〔skill_engine/protocol.py:358〕
│ · Skill 工具加载 SKILL.md 全文 〔skill_engine/protocol.py:735〕
│ · 工具经接地层预选(topK) 〔grounding/core/grounding_client.py:720〕
└───────────────────────┬─────────────────────────┘
│ finalize 〔runtime/execution_finalizer.py:23〕
┌──────── 进化平面:任务后自动改写技能 ──────────────┐
▼ ▼
① 证据落盘 + 触发 器建作业 ② 进化引擎执行作业
TriggerEngine.evaluate_checkpoint EvolutionEngine.process_job
〔skill_engine/triggers/engine.py:25〕 〔skill_engine/evolution/engine.py:75〕
checkpoint: task_session_persisted packet → decision → admission
/ QUALITY_SIGNAL → authoring → commit
▼
技能库(共享记忆)
磁盘 <skill>/SKILL.md + .skill_id
SQLite openspace.db(records + lineage DAG + 统计)
│
▼
③ 对外:MCP server 〔entrypoints/mcp/server.py:2702〕
execute_task / search_skills / fix_skill / upload_skill …
↕ 云社区〔cloud/client.py:249〕跨 agent 共享
部件一句话职责:
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
OpenSpace | 顶层门面:薄壳,持有 OpenSpaceRuntime 并转发调用 | openspace/application.py:569 |
OpenSpaceRuntime | 运行时:持有全部服务与可变状态,initialize_services 装配 | openspace/runtime/app.py:146 |
ExecutionLifecycle | 单次任务编排:会话/录制/workspace → 回合 → 收尾 | openspace/runtime/execution_lifecycle.py:42 |
GroundingAgent | 真正的执行体:多轮"想→调工具→看结果"直到自然收尾 | openspace/agents/grounding_agent.py:30 |
GroundingClient | 工具接地层:统一 5 类后端、工具预选、质量监控 | openspace/grounding/core/grounding_client.py:21 |
| Skill Protocol | 技能渐进披露:skill_listing 目录 + DiscoverSkills + Skill 工具 | openspace/skill_engine/protocol.py |
SkillRegistry | 发现/管理技能(SKILL.md 格式) | openspace/skill_engine/registry.py:586 |
RecordingManager | 录制每轮对话与元数据,供事后分析 | openspace/recording/manager.py:20 |
ExecutionAnalyzer | 复盘一次执行,产出 ExecutionAnalysis | openspace/skill_engine/analyzer.py:307 |
TriggerEngine / EvolutionEngine | 触发器建作业 / 执行作业(进化流水线) | openspace/skill_engine/triggers/engine.py:25、openspace/skill_engine/evolution/engine.py:75 |
SkillEvolver | 进化的"改稿"后端:执行 FIX / DERIVED / CAPTURED 落盘 | openspace/skill_engine/evolver.py:364 |
SkillStore | SQLite 持久化:技能记录 + 血缘 DAG + 统计 | openspace/skill_engine/store.py:435 |
OpenSpaceClient | 云社区客户端:上传/下载/搜索技能 | openspace/cloud/client.py:249 |
| MCP server | 把上述能力暴露成一组 MCP 工具给宿主 agent | openspace/entrypoints/mcp/server.py |
主线走一遍(高层,不进代码):
- 宿主 agent(或 CLI)构造
ExecutionRequest,调OpenSpace.execute(request)(openspace/application.py:772)。 - 运行时
ExecutionLifecycle.execute(openspace/runtime/execution_lifecycle.py:80)准备会话、录制、workspace,然后run_turns→GroundingAgent.process跑回合循环(openspace/runtime/execution_events.py:72的run_turns)。 - 技能渐进披露:回合开始注入轻量
skill_listing目录;模型用DiscoverSkills搜、用Skill工具加载全文(openspace/agents/turns/loop.py:622-632)。 - 全程被
RecordingManager录进conversations.jsonl/metadata.json。 - 任务后(
ExecutionFinalizer.finalize,openspace/runtime/execution_finalizer.py:23):落证据 →TriggerEngine按 checkpoint 建 TriggerJob →EvolutionEngine.process_job走决策/准入/改稿/提交流水线。 - 进化结果写回磁盘 SKILL.md 和 SQLite 版本 DAG;需要时技能经 MCP
upload_skill上云,别的 agent 检索下载复用。
目标:看懂"大盘"——一条运行时主循环(左)+ 一个任务后进化平面(右)+ 一份共享技能记忆(中)+ 一层对外 MCP/云出口(下)。
3. 阅读地图(建议顺序)
本子库按"由浅入深、先主循环后进化"拆成 5 章。推荐顺序:
-
主循环:运行时编排与 Grounding Agent 回合循环 —— 先看一次任务怎么跑完:
OpenSpace.execute→ExecutionLifecycle→GroundingAgent.process的回合循环、"没有工具调用即完成"的收尾判定、任务后的 finalize 与后台进化调度。理解全局从这章开始。 -
技能协议与发现:skill_listing / DiscoverSkills / Skill —— 技能是什么(官方 SKILL.md 格式)、怎么被发现(
.skill_id持久身份)、 Skill Protocol 三件套如何渐进披露、以及 BM25+向量+LLM 的发现级联。 -
自进化引擎:触发器作业与 FIX / DERIVED / CAPTURED —— 项目的灵魂。TriggerJob 怎么从证据里产生,进化流水线(decision → admission → authoring → commit) 如何把关,三种进化手术各自的语义与血缘规则,以及 SQLite 版本 DAG。
-
工具接地层:统一后端、工具预选与质量监控 —— 五类后端(shell/gui/web/mcp/meta)如何被统一;工具太多时的"预选" (
get_tools_with_auto_preselection,BM25+向量+LLM 规划筛选);ToolQualityManager如何给坏工具打惩罚分并反哺技能修复。 -
对外集成:MCP 服务与云端技能社区 ——
entrypoints/mcp/server.py的工具面(execute_task / search_skills / fix_skill / upload_skill 等)、 宿主 agent 集成方式、以及云社区的上传/搜索/导入与可见性(public/private)。
4. 巧妙之处(这套设计值得带走的东西)
① 技能披露走"协议"而不是"预注入"。
旧版在执行前一次性把选中技能的全文塞进 system 提示、失败再回退;新版改为模型可见的三件套——
轻量 skill_listing 目录(按上下文预算截断)、DiscoverSkills 检索、Skill 工具按需加载全文
(openspace/skill_engine/protocol.py:1-9 的模块契约)。全文只在模型真正要用时进上下文。
② 进化从"散装调用"改成"作业流水线"。
任务结束后不再直接调分析器/进化器,而是 TriggerEngine 按 checkpoint(如 task_session_persisted)
建持久化 TriggerJob(openspace/skill_engine/triggers/engine.py:25),
EvolutionEngine.process_job 沿 packet → decision → admission → authoring → commit 分段处理
(openspace/skill_engine/evolution/engine.py:103)。每段都有产物与状态,失败可恢复(recovery.py)。
③ 进化是"定向手术"而不是"重训"。
坏了只修坏的那步(FIX,同名产生新版本、旧目录内容快照进 DB),而不是重建整个技能——
省 token 的关键之一(openspace/skill_engine/types.py:43 起的血缘规则)。
④ 每次改动都建新节点的版本 DAG。
FIX/DERIVED/CAPTURED 都不覆盖历史:FIX 恰好 1 个父(上一版本)、DERIVED 可多父(融合)、
CAPTURED 无父(根节点),generation 记录距根深度(openspace/skill_engine/types.py:77)。技能演化史可回溯、可审计。
⑤ 技能身份和目录解耦。
.skill_id sidecar 让技能 ID 可移植(挪目录、换机器都不变)且确定(不重生成)
(openspace/skill_engine/registry.py 的 _read_or_create_skill_id)。这是"跨 agent / 上云共享"能成立的地基。
⑥ 工具接地层自带"预选"(工具 RAG)。
工具数量超过阈值(默认 30)才触发检索,按 tool.is_deferred 契约分离即时/延迟工具,
用 BM25 + 向量 + LLM 规划筛出 topK(openspace/grounding/core/grounding_client.py:720、
search_tools.py:567 的 ToolPreselector),避免把上百个工具塞进上下文。
5. 代码地图(导航索引)
符号名比行号抗漂移——上游更新后优先用
grep符号名定位。行号 as-ofsourceCommit。
| 主题 | 文件路径 | 符号名 |
|---|---|---|
| 顶层门面 / 配置 | openspace/application.py:569、:121 | OpenSpace、OpenSpaceConfig |
| 执行入口(收 ExecutionRequest) | openspace/application.py:772 | OpenSpace.execute |
| 一次性装配 | openspace/runtime/app.py:324 | OpenSpaceRuntime.initialize_services |
| 单任务编排 | openspace/runtime/execution_lifecycle.py:80 | ExecutionLifecycle.execute |
| 回合触发 | openspace/runtime/execution_events.py:72 | ExecutionEventEmitter.run_turns |
| 任务收尾 | openspace/runtime/execution_finalizer.py:23 | ExecutionFinalizer.finalize |
| 执行体:回合循环 | openspace/agents/grounding_agent.py:644 | GroundingAgent.process |
| 回合循环实现 | openspace/agents/turns/loop.py:638 | (主 while 循环) |
| 停止策略 | openspace/agents/turns/stop_policy.py:194 | max_iterations_stop_reason |
| 初始消息组装 | openspace/agents/turns/message_builder.py:210 | construct_messages |
| 技能协议三件套 | openspace/skill_engine/protocol.py:247、:358、:735 | SkillListingService、SkillDiscoveryService、SkillTool |
| 技能发现/管理 | openspace/skill_engine/registry.py:586 | SkillRegistry |
| LLM 辅助精选(发现级联末端) | openspace/skill_engine/registry.py:1274 | select_skills_with_llm |
| 技能持久身份 | openspace/skill_engine/registry.py:207 | _read_or_create_skill_id |
| 进化数据模型 | openspace/skill_engine/types.py:33 | EvolutionType、SkillOrigin、SkillLineage |
| 技能全档案 | openspace/skill_engine/types.py:421 | SkillRecord |
| 任务后分析 | openspace/skill_engine/analyzer.py:356 | ExecutionAnalyzer.analyze_execution |
| 触发器引擎 | openspace/skill_engine/triggers/engine.py:25 | TriggerEngine.evaluate_checkpoint |
| 触发策略 | openspace/skill_engine/triggers/policies.py:44 | AnalysisTriggerPolicy、default_policies |
| 进化流水线 | openspace/skill_engine/evolution/engine.py:103 | EvolutionEngine.process_job |
| 改稿后端(旧内核所在) | openspace/skill_engine/evolver.py:364 | SkillEvolver(_evolve_fix/_evolve_derived/_evolve_captured) |
| SQLite 版本 DAG | openspace/skill_engine/store.py:435 | SkillStore(record_analysis、evolve_skill) |
| 工具接地层 | openspace/grounding/core/grounding_client.py:21 | GroundingClient |
| 工具预选(自动检索) | openspace/grounding/core/grounding_client.py:720 | get_tools_with_auto_preselection |
| 预选协调器 | openspace/grounding/core/search_tools.py:567 | ToolPreselector、ToolRanker |
| 工具质量监控 | openspace/grounding/core/quality/manager.py:27 | ToolQualityManager(record_execution、get_problematic_tools) |
| 录制管理 | openspace/recording/manager.py:20 | RecordingManager |
| MCP 服务 | openspace/entrypoints/mcp/server.py:2702 | run_mcp_server(工具:execute_task、search_skills、fix_skill、upload_skill 等) |
| 云社区客户端 | openspace/cloud/client.py:249 | OpenSpaceClient(upload_skill_v2、import_skill) |
| 云端混合搜索 | openspace/cloud/search.py:460 | hybrid_search_skills |
| CLI 入口 | openspace/entrypoints/cli/main.py:480 | run_main |
下一步:从 主循环:运行时编排与 Grounding Agent 回合循环 开始, 跟着一次任务从
execute()走到回合收尾,再看任务后进化平面如何把这次经验沉淀进技能库。