Skip to content

README_CN.md

Latest commit

 

History

History
174 lines (113 loc) · 11.4 KB

README_CN.md

File metadata and controls

174 lines (113 loc) · 11.4 KB

OpenSpace × OpenViking 集成

为自我进化的 AI Agent 提供跨会话智能。 每个 task 都让每个 Agent 更聪明 —— 而现在，这种学习能在会话、用户与机器之间持久保留。

语言: English · Tiếng Việt · 中文

目录

  1. 设计哲学 —— 我们为什么做这件事（本页）
  2. 架构 —— 用户流、数据流、组件分解
  3. Token 经济学 —— 到底能省多少？
  4. 配置 —— 环境变量、身份解析、多租户
  5. 运维 —— 业务规则、部署、测试、故障排查

设计哲学

问题：Task 内聪明，Task 间失忆

OpenSpace 已经让 Agent 在单个 task 内部足够聪明。Skill 引导执行，evolution 修复损坏的 workflow，quality monitoring 过滤失效的工具。在公开 benchmark 上，这已经带来了 4.2× 的性能提升和 46% 的 Token 缩减。

但 task 之间，OpenSpace 又回到冷启动。刚花了 8 次 iteration 摸索出 "chromedriver 124 需要 Chrome 124+" 的 Agent，在下一个 task 开始时对这个教训没有任何记忆。上周二明确说过"我偏好柱状图"的用户，周三还得再说一遍。某个 Agent 辛苦得来的工具知识被锁在自己的本地数据库里，除非有人手动把它 upload 到云端。

我们把这个现象称作"重学习鸿沟"（relearn gap）—— "我的 skill 数据库变得更好了"和"下一个相似 task 变得明显更快"之间的断层。

洞察：OpenViking 已经解决了难的那部分

OpenViking 是火山引擎团队构建的 AI Agent 上下文数据库。它把 Agent 上下文 —— 记忆、资源、skill —— 当作一个文件系统来管理，支持 L0/L1/L2 分层加载。session commit 时自动触发记忆抽取。检索基于语义，支持目录前缀过滤。一切都通过 localhost:1933 上一个简洁的 HTTP API 暴露出来。

OpenViking 开箱即用提供给我们的：

  • 自动抽取 —— 丢进 session 消息，另一端得到结构化的记忆（工具知识、用户偏好、模式、历史案例）。无需手工整理。
  • L0 abstract —— 每条检索结果约 100 tokens。注入便宜，去重便宜。
  • 目录语义 —— viking://tenants/acme/agent/memories/tools/ 是真实路径。多租户隔离只是前缀匹配。
  • Local-first —— 在你自己的机器或团队局域网上跑一个 HTTP server。没有 SaaS 锁定，没有数据出境。

OpenSpace 需要的是跨会话记忆。OpenViking 就是那个东西。集成方案自然而然就成型了。

设计原则：叠加，而非替换

我们没有重建 OpenSpace 任何现有的 Token 节省机制。两阶段 skill-first 执行、progressive disclosure skill selection、BM25 + embedding 预过滤、iter-2 skill context 剥离、tool auto-search、message 截断 —— 全部原封不动。

OpenViking 是一个互补层：

OpenSpace（保持不变） OpenViking（新增）
Task 内智能 Task 间智能
Skill 作为可执行过程 记忆作为经验性知识
Evolution 创造新 skill 抽取创造新记忆
Quality metrics 过滤糟糕 skill 历史案例浮现好的解决方案
Workspace 本地执行 Namespace 在团队内作用域化

每次 enrichment 调用都是 best-effort。如果 OpenViking 挂了，OpenSpace 表现与集成之前完全一致。零回归风险，严格的成本上限。

五个访问路径

Viking 知识通过五条不同的路径流入 OpenSpace，每条路径都是因为跨会话提示在该阶段能产生最大杠杆：

  1. Skill selector prompt（skill 选择之前） 杠杆：用户偏好和相似历史案例帮助 selector 选出对这个用户风格已知有效的 skill —— 在很多情况下完全避免 Phase 2 fallback。

  2. Grounding agent system prompt（仅 iter 1，之后剥离） 杠杆：已知的工具陷阱、模式提示和 anti-patterns（已知失败模式）短路 2–4 次探索 iteration。iter 2 时剥离以节省 prompt token，和 skill context 完全相同的节奏。

  3. Analyzer prompt（执行后分析） 杠杆：跨会话的工具问题历史让 evolution 决策更快收敛，把推测性的 CAPTURED 建议转化为精准的 FIX 建议 —— 直接编辑已有 skill 而不是从头写一个新的。

  4. 迭代中 retrieve_memory 工具（任何 iteration，按需） 杠杆：当 grounding agent 在执行中发现需要不同的知识 —— 工具出乎意料地失败、某种方法不 work —— 它像调用任何其他工具一样调用 retrieve_memory(query, category)。类别包括 antipatterns 用于 "这个失败以前见过吗？"

  5. 给 host agent 的直接 MCP 工具（任何时候，OpenSpace 执行之外） 杠杆：Host agents（OpenClaw、Claude Code、Codex、nanobot、...）获得 5 个 MCP 工具 —— openviking_retrieve_memory、openviking_remember、openviking_forget_memory、openviking_report_stale_memory、openviking_memory_status —— 以便 host 的聊天界面可以访问跨会话记忆，而无需将任务委派给 OpenSpace 的执行引擎。

五个访问点，五个可测量的胜利 —— 路径 4 和 5 关闭了最初三点设计中最大的两个 gap。

双向反馈闭环

当 OpenSpace 的 evolver 产出一个进化后的 skill，我们通过两条通道把它写回 OpenViking：

  1. 丰富的 session —— task 描述、最终响应、工具序列、每个 skill 的 evolution 元数据、环境指纹（OS/Python/工具版本，用于未来的 staleness 检测）。OpenViking 的抽取流水线自动把这些转化为持久记忆。

  2. 结构化的 skill resource —— 进化后的 SKILL.md 内容推送到 /api/v1/skills，让 Viking 把它作为一流的可检索资源索引。在团队局域网某个地方的另一个 OpenSpace 实例现在可以通过 find_skill_knowledge() 检索到这个 skill。

没有手工 cloud upload。没有显式的"分享这个 skill"按钮。解决 task 这个行为本身就自动为集体智能做出了贡献。

Negative feedback 同样重要。 失败不会被丢弃 —— 它们成为 anti-pattern 记忆，路由到 viking://agent/memories/antipatterns/。当执行状态是 error 或 incomplete 时，OpenSpace 自动记录失败原因、失败的工具序列和环境上下文。未来的 task 查询 Viking 会在其 enrichment 块中看到这些作为 "AVOID" 警告。Host agent 和直接用户也可以通过 OpenSpace.provide_feedback(task_id, "negative", comment) 或 openviking_remember MCP 工具提供明确的反馈。

结果是一个 同时捕获成功与失败 的学习闭环 —— 和 OpenSpace 自己的 skill evolution 是同一种架构，现在通过 Viking 跨会话扩展。

隐私立场

共享智能很强大 —— 如果处理不慎也是隐私隐患。我们有意地画出了隔离边界，并用多层防御来强制执行：

  • Agent 记忆（工具、模式、skill、案例、antipatterns） 按照约定 在团队内共享。工具知识就是集体智能的全部意义；每个用户各自复制一份就失去了目的。
  • 用户记忆（偏好、profile） 通过 URI 路径中的 user_id 段 按用户隔离。"Alice 偏好柱状图"绝不能泄漏到 Bob 的会话里。
  • PII / 密钥清理 在 任何内容离开进程之前 发生。基于正则的清理器（openspace/viking/scrubber.py）会 redact API keys（Anthropic、OpenAI、GitHub、AWS、GCP、Slack、OpenRouter）、JWT、私钥、basic-auth URL、邮箱、电话号码、信用卡（经 Luhn 校验）、SSN 和 IP 地址。默认 开启。仅在完全信任 Viking 端点时通过 OPENVIKING_SCRUB_PII=false 关闭。
  • Skill 内容推送 通过环境变量 允许豁免。处理隐私敏感客户数据的团队设置 OPENVIKING_PUSH_SKILLS=false，session feedback 仍然 commit，但没有 skill 主体会离开机器。
  • Namespace 永不自动推断。跨团队意外混淆记忆的风险太大，不适合用启发式规则解决。团队要么显式设置 OPENVIKING_NAMESPACE=<team>，要么就得到单租户行为。
  • 质量阈值（OPENVIKING_MIN_SCORE）让团队可以 reject 低置信度检索，以免错误记忆进入 prompt。

完整隐私模型见 配置 和 运维。

可观测性承诺

无法测量的东西无法信任。每次 OpenSpace.execute() 调用都在 result dict 中返回一个 viking 字段：

{
    "viking": {
        "enabled": True,
        "available": True,
        "query": "build dashboard\nPrior user turns: prefer bar charts",
        "enrichment_chars": 1243,
        "hit_counts": {"tool_hints": 3, "user_preferences": 1, ...},
        "feedback_status": "committed",
        "pushed_skills": 1,
    }
}

外加每个 task 一行日志摘要：

Viking telemetry: available=True hits=9 enrich_chars=1243 feedback=committed pushed=1

Benchmark 流水线、MCP host agent 和团队 dashboard 可以直接测量跨会话记忆层的真实影响，无需解析执行日志。

量化的节省分析见 Token 经济学。

其他页面的内容

架构 —— 端到端全景。四种用户流（冷启动、温缓存、跨 Agent 传播、分析阶段增强）。带 latency 预算的具体数据流序列。文件级入口的组件分解。

Token 经济学 —— Baseline 假设、按机制拆分的节省细目、真实场景（冷/温/跨 Agent）、如何与 OpenSpace 已有的 46% 缩减叠加。失败模式成本分析。

配置 —— 每个环境变量都有优先级规则文档。OpenSpaceConfig 字段。身份解析回退链。多租户部署模式。隐私开关。

运维 —— 业务规则决策（部署模型、保留、所有权）。测试矩阵（30 个测试全部通过）。故障排查手册。Rollout 检查清单。Viking 挂掉时该做什么。

状态

  • Audit findings 已解决：10/10
  • 遗留问题已解决：4/4
  • 业务规则已决策：5/5
  • 审计后架构 gap 已关闭：5/5（host MCP 访问、迭代中检索、negative feedback、staleness 信号、质量阈值）
  • 隐私层：基于正则的 PII/密钥清理器，默认开启
  • 访问路径：5 条（selector、grounding、analyzer、迭代中工具、host MCP 工具）
  • 给 host agent 的 MCP 工具：5 个（retrieve_memory、remember、forget_memory、report_stale_memory、memory_status）
  • 测试：63 个通过（client、scrubber、MCP 工具、negative feedback、迭代中工具、身份、stats）
  • 生产就绪：每一种失败模式都已验证 graceful degradation

作者与致谢

Nguyen Ngoc Tuan（阮玉俊） Founder & CEO —— Transform Group Lark Platinum Partner facebook.com/khongphaituan

构建于：

  • OpenSpace —— HKU-DS 出品的 AI Agent 自我进化引擎
  • OpenViking —— 火山引擎出品的 AI Agent 上下文数据库

集成与 OpenSpace 一同使用 MIT 许可证。欢迎贡献与反馈。