openspace

OpenSpace

当用户真正想问的是**“此宿主 Agent 如何从大型目录中找到、信任并改进合适的 SKILL.md？”**时使用此技能——如果用户只是想执行单个技能，则不要使用。

OpenSpace 自己的 README 将其描述为**“AI Agent 的技能管理层”**：你的技能不断增长，而 OpenSpace 会在每次运行时帮助你检索、评估和演进技能。在此仓库中，这项工作具体是：充当 jeo-skills 的技能查找／技能检索层——宿主 Agent 只需安装一次 OpenSpace，之后便可让它在已安装到 .agent-skills/（并复制到 $HOME/.agents/skills）下的约 150 个技能中搜索、排序并加载合适的 SKILL.md，而不必让 Agent 从平铺的技能列表中猜测，也不必让人工手动维护路由规则。

何时使用此技能

• 用户想要安装 OpenSpace，让宿主 Agent 能够在现有技能目录中查找技能
• 用户（或 Agent）需要从众多已安装技能中为某项任务检索／排序出最合适的技能
• 用户想根据真实执行结果，而不只是技能描述，了解哪些已安装的技能确实有效
• 用户想要基于真实运行证据，有控制地演进技能（FIX / DERIVED / CAPTURED）
• 用户想通过本地优先的中心来共享或导入技能（浏览软件包、显式导入、经过信任门控的上传）
• 用户正在 OpenSpace 与简单的目录 grep、长期维护的知识 wiki 或按仓库划分的 Agent 记忆之间做选择

何时不使用此技能

• 用户只需要在现有技能目录中进行简单的关键词／grep 查找 → 转到 codebase-search 或 semble；不要为了单次查找而搭建完整的 MCP 技能管理层
• 用户想要长期保存、经过综合整理的 Markdown 知识（概念、索引、研究笔记） → 转到 llm-wiki
• 用户想要与技能选择完全无关的按仓库划分的 Agent 记忆（交接笔记、决策日志、清单） → 转到 opencontext
• 用户只想运行一个已明确知道的特定技能 → 直接加载该技能的 SKILL.md；OpenSpace 用于查找和评判技能，而不是替代技能本身

说明

步骤 1：将任务归入一种路由模式

开始任何操作前，恰好选择一种主要模式：

1. install-as-skill-finder — 将 OpenSpace 接入宿主 Agent，使其能够搜索此目录
2. retrieve-a-skill — 根据任务查找／排序并加载合适的 SKILL.md
3. evaluate-skill-quality — 根据执行记录判断已安装技能是否可信
4. evolve-skills — 应用由证据驱动的 FIX / DERIVED / CAPTURED 更新
5. share-import-hub — 发布可信技能，或从本地优先的云端中心拉取技能
6. route-out — 该任务实际上应交由 codebase-search／semble、llm-wiki 或 opencontext 处理

完整的模式说明和转出路由理由： references/skill-discovery-routing.md。

步骤 2：安装 OpenSpace（路径 A 快速入门）

根据上游快速入门：

git clone --filter=blob:none --sparse https://github.com/HKUDS/OpenSpace.git ~/.openspace/OpenSpace
cd ~/.openspace/OpenSpace
git sparse-checkout set --no-cone '/*' '!/assets/'   # skips the ~50 MB assets/ folder

# A dedicated venv, not the system Python: `pip install -e .` against a Homebrew or
# distro Python fails with PEP 668 "externally-managed-environment", which is how
# openspace-mcp ends up missing on a machine that "installed successfully".
python3 -m venv ~/.agents/venvs/openspace          # or: uv venv --python 3.12 ~/.agents/venvs/openspace
~/.agents/venvs/openspace/bin/python -m pip install -e .
~/.agents/venvs/openspace/bin/openspace-mcp --help  # verify installation
ln -sf ~/.agents/venvs/openspace/bin/openspace-mcp ~/.local/bin/openspace-mcp

需要 Python 3.12+。

或者运行捆绑的安装程序，它会以非交互方式执行相同步骤、复制两个宿主技能（步骤 4），并注册 MCP 服务（步骤 3）：

bash scripts/install-openspace.sh --help
bash scripts/install-openspace.sh --dry-run
bash scripts/install-openspace.sh

各宿主的完整接入说明：references/install-and-mcp-wiring.md。

步骤 3：接入 MCP 服务，并将 OPENSPACE_HOST_SKILL_DIRS 指向此仓库的技能根目录

在机器上安装的每个 AI 运行时中注册 openspace MCP 服务—— Claude Code 及其兼容 Anthropic 的分支（kimi、glm/zai、deepseek、grok、qwen）、 Codex、Gemini CLI、Cursor、OpenCode，以及 pi / gjc / jeopi Agent 运行时。对于 jeo-skills，OPENSPACE_HOST_SKILL_DIRS 必须指向 $HOME/.agents/skills——这是 此仓库的安装程序复制技能、供宿主 Agent 加载的位置，因此 OpenSpace 应扫描并据此排序的目录就是这里。

请使用内置注册器，而不是手动编辑每个配置：

bash scripts/register-openspace-mcp.sh --dry-run   # preview every runtime it would touch
bash scripts/register-openspace-mcp.sh             # merge in place
bash scripts/register-openspace-mcp.sh --force     # overwrite an existing openspace entry

它会写入 mcpServers JSON（~/.claude.json、~/.claude/claude_desktop_config.json、 ~/.gemini/settings.json、~/.qwen/settings.json、~/.cursor/mcp.json、 ~/.kimi/mcp.json、~/.glm/mcp.json、~/.zai/mcp.json、~/.deepseek/mcp.json、 ~/.pi/agent/mcp.json、~/.gjc/agent/mcp.json、~/.jeopi/agent/mcp.json）、TOML [mcp_servers.openspace]（~/.codex/config.toml、~/.grok/config.toml），以及 OpenCode 的 mcp 块（含 type: local，位于 ~/.config/opencode/opencode.json）。现有文件会保留其权限，并以原子方式替换；符号链接和非普通配置文件会被拒绝；如果运行时的配置目录不存在，则会跳过而不会新建。写入的是虚拟环境二进制文件的绝对路径，因此注册不依赖 Agent 的 PATH 中包含 ~/.local/bin（查找顺序：$OPENSPACE_VENV/bin/openspace-mcp、~/.local/bin/openspace-mcp、PATH、旧版 ~/.openspace/venv/bin/openspace-mcp）。

写入的条目等效于：

{
  "mcpServers": {
    "openspace": {
      "command": "$HOME/.agents/venvs/openspace/bin/openspace-mcp",
      "toolTimeout": 600,
      "env": {
        "OPENSPACE_HOST_SKILL_DIRS": "$HOME/.agents/skills",
        "OPENSPACE_WORKSPACE": "$HOME/.openspace/OpenSpace",
        "OPENSPACE_CLOUD_MODE": "local",
        "OPENSPACE_CLOUD_API_KEY": "sk-xxx (optional, for cloud)"
      }
    }
  }
}

OpenSpace 支持三种启动模式；本地使用时首选 stdio：

• stdio — 在宿主配置中保留 command: "openspace-mcp"（最简单的选项）
• SSE — openspace-mcp --transport sse --host 127.0.0.1 --port 8080 → 端点 http://127.0.0.1:8080/sse
• 可流式传输的 HTTP — openspace-mcp --transport streamable-http --host 127.0.0.1 --port 8081 → 端点 http://127.0.0.1:8081/mcp

在 openspace-mcp --help 可正常运行且 MCP 客户端能够看到 OpenSpace 的工具之前，请勿报告安装成功；较长的 execute_task 调用需要至少 600 秒的 toolTimeout。

步骤 4：复制两个用于指导 Agent 何时以及如何调用 OpenSpace 的宿主技能

cp -r OpenSpace/openspace/host_skills/delegate-task/ /path/to/your/agent/skills/
cp -r OpenSpace/openspace/host_skills/skill-discovery/ /path/to/your/agent/skills/

skill-discovery/SKILL.md 教宿主 Agent 搜索和发现技能； delegate-task/SKILL.md 教它执行、修复和上传。对于 jeo-skills，请将这两个文件都复制到 $HOME/.agents/skills/（这正是 scripts/install-openspace.sh 自动执行的操作）。此后无需额外提示——宿主 Agent 现在知道何时应调用 OpenSpace，而不是自行猜测。

步骤 5：为任务检索／发现合适的技能

安装完成后，请通过 openspace MCP 工具或 skill-discovery，让宿主 Agent 搜索并为当前任务的技能排序，而不是手动浏览目录。 OpenSpace 会按以下优先级顺序从 OPENSPACE_HOST_SKILL_DIRS、已配置的 skills.skill_dirs、.openspace/skills 等项目根目录、~/.openspace/skills 等用户根目录，以及最后的内置 openspace/skills 中发现技能。每个发现的技能在加载前都会通过 check_skill_safety 检查；包含危险模式（提示词注入、凭据外传）的技能会被拦截并记录日志。

两个排序阶段在运行时均为可选，失败时不会报错。 BM25 需要 OpenSpace 虚拟环境中的 rank_bm25 软件包；语义重排需要兼容 OpenAI 的密钥（OPENAI_API_KEY / OPENROUTER_API_KEY，或 nanobot/OpenClaw 宿主配置）。两者均不可用时，search_skills 仍会返回结果，每个结果的 score: 0.0，顺序也不固定——技能查找实际上只是在查找名称。务必使用意图查询进行验证（"scrape a javascript rendered page" 应当能找到 scrapling），而不要使用名称查询；即使排序功能失效，名称查询也会成功。

排序详情和路由说明：references/skill-discovery-routing.md。

步骤 6：根据实际执行证据评估技能质量

不要因为技能的描述写得好就轻信它。OpenSpace 的质量层会跟踪技能是否被选中、应用、完成或回退，以及其底层工具是否变得不可靠、缓慢或有风险——依据的是实际任务行为，而非自我报告的声明。

步骤 7：仅在证据表明有必要时迭代技能

OpenSpace 通过以下三种受控触发方式迭代技能：

• FIX — 修复损坏或过时的技能
• DERIVED — 从现有技能创建更好或更专业的版本
• CAPTURED — 保存一个可复用的子工作流，但仅当源追踪记录同时显示该工作流已执行，且所声称的后置条件已单独验证时才可进行

新建／迭代的技能默认处于暂定状态；经独立成功使用后，技能会晋升为可信，而可归因的失败会使其降级。enabled 独立于信任生命周期控制是否复用。被拦截或存在疑虑的提案会保留为仅供审计的候选项——反复出现也绝不会自动晋升。

详情：references/quality-and-evolution.md。

步骤 8：通过本地优先的中心分享或导入技能

技能在本地运行和迭代；云端用于发现和审核，而非执行：

openspace-download-skill  # download a skill from the cloud
openspace-upload-skill --skill-dir /path/to/skill/dir  # upload a trusted skill

云端上传要求对应的本地 SkillStore 记录状态为 trusted——无论公开还是私密上传，若记录处于暂定状态或未知状态，都会默认拒绝。本地信任状态本身绝不会发送到云端。可选的云端引导配置：

openspace-cloud-auth bootstrap-agent-key --email [email protected] --agent-name openspace-local-agent

即使不进行云端引导配置，所有本地功能（任务执行、迭代、本地技能搜索）仍可正常使用。

步骤 9：当 OpenSpace 不适合承担此职责时，如实转交

• 纯 grep／关键词目录查找（不需要排序／质量评估／迭代）→ codebase-search 或 semble
• 长期积累的综合 Markdown 知识（而非技能选择）→ llm-wiki
• 按仓库保存的 Agent 记忆／交接笔记／决策日志（而非技能选择）→ opencontext

示例

示例 1：将 OpenSpace 安装为此仓库的技能查找器

输入

配置 OpenSpace，让我的编码 Agent 能从已安装的 150 个技能中找到合适的技能，而不是让我手动指定。

输出示意

• 模式：install-as-skill-finder
• 运行 bash scripts/install-openspace.sh（克隆 + pip install -e . + 验证 openspace-mcp --help）
• 使用 bash scripts/register-openspace-mcp.sh 在每个已安装的运行时中注册 openspace MCP 服务（OPENSPACE_HOST_SKILL_DIRS=$HOME/.agents/skills，OPENSPACE_WORKSPACE=$HOME/.openspace/OpenSpace）
• 将 skill-discovery/ 和 delegate-task/ 复制到 $HOME/.agents/skills/
• 验证工具可见，且本地轻量级技能搜索正常工作

示例 2：为某项任务找到合适的技能

输入

我需要抓取一个由 JS 渲染的页面——应该使用我们已安装的哪个技能？

输出示意

• 模式：retrieve-a-skill
• 让 OpenSpace 在 OPENSPACE_HOST_SKILL_DIRS 中搜索并排列与“JS-rendered page scraping”相关的技能
• 预期它会使用 BM25 + 嵌入混合排序，让 scrapling（或同等技能）排在通用候选项之前，然后加载该技能的 SKILL.md

示例 3：判断某个技能是否仍然可靠

输入

我们已经使用 deployment-automation 技能十几次了。它真的有效吗？

输出示意

• 模式：evaluate-skill-quality
• 提取执行记录：已选择 / 已应用 / 已完成 / 已回退次数，以及工具可靠性信号
• 报告信任状态（暂定还是可信），而不是轻信技能自己的描述

示例 4：不应触发——普通目录搜索

输入

只需在仓库中 grep 一下，看看哪个技能提到了“playwright”。

输出示意

• 模式：route-out
• 这是普通关键词查找，而非技能排序 / 质量评估 / 演进——应转交给 codebase-search / semble，而不是安装或调用 OpenSpace

最佳实践

1. 将 OpenSpace 定位为技能查找层，而非技能本身的替代品——由它选择和评估，Agent 仍负责执行。
2. 对此仓库，将 OPENSPACE_HOST_SKILL_DIRS 指向 $HOME/.agents/skills，以便根据实际安装的目录进行排序。
3. 本地 MCP 连接优先使用 stdio；仅当宿主无法使用 stdio，或需要独立 / 远程服务时，才使用 SSE / 可流式传输的 HTTP。
4. 根据证据（已选择 / 已应用 / 已完成 / 已回退）来信任技能，而不是看其描述写得有多好。
5. 严格控制演进——采用 FIX / DERIVED / CAPTURED，并先设为暂定再晋升为可信，绝不静默自动改写。
6. 将云端枢纽仅用于发现；执行和信任决策留在本地，上传则要求状态为 trusted。
7. 如果任务实际上并非技能检索 / 质量评估 / 演进，应如实转交给 codebase-search / semble、llm-wiki 或 opencontext。
8. 在 openspace-mcp --help 正常运行且 MCP 客户端能看到 OpenSpace 的工具之前，不要报告安装成功。

参考资料

• 安装与 MCP 连接
• 技能发现与路由
• 质量与演进
• scripts/install-openspace.sh — 非交互式安装程序、宿主技能复制和 MCP 注册
• scripts/register-openspace-mcp.sh — 将 openspace MCP 条目合并到每个已安装的运行时配置中（claude / codex / gemini / cursor / opencode / kimi / glm / zai / deepseek / grok / qwen / pi / gjc / jeopi）
• OpenSpace GitHub 仓库