Holon

在自己的电脑或服务器上创建和运行开源 AI 助手。分配任务、查看进展、持续跟进工作。面向个人和团队。
跳到正文
浏览文档
本页提纲

搭建 AI Agent 生态研究员：跨多开源项目的持续深度调研

在跟踪快速演进的技术领域（例如 AI Agent 框架、运行时与协议）时，单纯依赖一次性的模型对话或网页搜索往往难以胜任：

  • 缺乏一手源码证据：网页抓取与二次解读容易泛化甚至过时，真正的关键细节隐藏在开源项目的架构实现、提交历史、Release 契约和测试用例中；
  • 多项目上下文混乱：技术调研往往需要横向对比多个独立的开源项目（例如不同的 Harness、运行时调度器或通信协议）。如果将 Agent 限制在单个目录，它无法跨仓库对比；如果让 Agent 在被测仓库内随意记录笔记，又会污染原始代码库；
  • 缺乏长期资产沉淀：一次会话结束，研究过程和对比矩阵便丢失了，无法做增量跟踪和基线复核。

本指南演示如何利用 Holon 的 Research Steward（研究管家）模板 理念以及 多工作区挂载（Multi-Workspace Attach）机制，搭建一个名为 ecosystem-researcher 的长效技术调研 Agent。

在这个体系中：

  • 模板开箱即用：从研究模板创建的 Agent 默认装配了调研所需技能，无需繁琐的手动配置；
  • 全自动维护与挂载：无需提前手动克隆仓库，直接让 Agent 自动克隆并挂载工作区；日常使用无需手动建目录或写配置，Agent 全自动维护私有知识库，本文将剖析其背后的结构化沉淀原理；
  • 极简指令交互：代码定位准则、事实推论区分与产物归档路径已内置在长效契约中，日常发任务只需一两句自然表达；
  • 日常随手交互：在手机端或桌面端直接向 Agent 转发开源项目链接或文档，由 Agent 在后台异步完成深度调研，点击产物链接即可阅读。

核心心智模型

在动手前，先理解本场景涉及的核心设计边界：

  1. 研究角色契约（Role Contract）与证据准则： 研究类 Agent 的核心职责是“证据收集与决策简报”，而不是“越权替人类做决策”或“修改产品代码”。复用 research-steward 模板可以为 Agent 注入严格的证据规则：

    • 区分事实（有明确源码 commit/行号或官方文档支撑）、判断（基于多方证据的架构推论）与建议（对内部产品的行动意见）；
    • 一手来源优先，不将未经引证的搜索摘要直接作为结论；
    • 结论默认只对基线 Commit 有效，增量更新采用追加记录，不随意推倒重来。

  2. 全自动维护与底层沉淀原理（Autonomous Maintenance）： 使用者不必扮演“文件管理员”。在实际使用中，知识库的目录初始化、项目登记索引表维护以及架构报告归档，都是由 Agent 根据指令或转发的链接自主驱动、全自动完成的。了解其背后的知识库目录规范，有助于理解 Agent 如何维持稳定的长期记忆。

  3. Agent 专属 Home 与外部代码工作区解耦：

    • agent_home：Agent 的独立私有空间，用于保存该 Agent 的长期知识库、调研登记表（registry.yaml）、生态分类法（taxonomy.md）和历史产物；
    • 挂载外部 Workspace：将多个外部开源代码仓库作为工作区挂载进来。Agent 可以平滑切换执行根进行跨项目源码审查，而不会把任何研究过程产物写入外部代码库，保持被观察项目绝对纯净。

  4. 多端触达与异步任务机制： 依托 Holon 的持久化守护进程与 WorkItem 机制，调研任务支持真正的异步执行。你在移动端随手分享一个 GitHub 链接，便可关闭屏幕离开；Agent 在后台持续抓取、分析、比对，完成后自动呈递交付简报。

前置条件

  • 本地已安装并启动 Holon 守护进程（Web GUI 默认在 http://localhost:8080，终端 holon CLI 亦可用）。
  • 无需提前在本地克隆代码仓库：你可以直接将 GitHub 仓库地址发给 Agent，由 Agent 自行完成克隆并添加为工作区；若本地已有项目目录，也可直接指定路径。

操作步骤

1. 从研究模板创建 Agent

Holon 提供了面向深度调研场景的 Agent 模板 research-steward，预置了严谨的证据收集契约。

默认携带技能说明： research-steward 模板在创建时已默认包含技术调研所需的技能集（如 ghx 用于获取 GitHub 数据与源码检索、sview 用于结构化只读代码审查、writing-clearly-and-concisely 保证简报精炼严谨等）。创建完成后即可直接使用，无需再单独配置或手动启用这些技能。

方式 A：通过 Web GUI 操作

  1. 打开 Web GUI：在浏览器中访问 Holon Web GUI（例如 http://localhost:8080）。
  2. 创建 Agent：
    • 在左侧导航栏点击 Templates（/templates）；
    • 在模板列表中找到 research-steward；
    • 点击 Create Agent 按钮，在弹出表单中输入：
      • Agent ID：ecosystem-researcher
      • 名称：生态调研员
    • 点击确认创建。

方式 B：通过 CLI 终端操作

在终端中运行一行命令完成创建：

holon agent create ecosystem-researcher --template research-steward --name "生态调研员"

创建完成后，该 Agent 根目录下的 AGENTS.md（位于 ~/.holon/agents/ecosystem-researcher/AGENTS.md）已完整载入长效角色契约与证据准则。

2. 添加多个开源项目工作区（Workspaces）

若需让 Agent 深入分析本地源码，可通过多工作区机制将目标项目连接进来。

方式 A：直接在对话中让 Agent 自动克隆并挂载（推荐）

目前 Web GUI 尚未提供独立的 Attach Workspace 图形按钮，最简便直接的做法是在对话框中直接告诉 Agent：

“帮我把 https://github.com/org/project-a 和 https://github.com/org/project-b 克隆到本地，并添加为你的工作区。”

Agent 收到后会自动在本地拉取仓库，并通过 Holon 内置的工作区工具自动完成挂载。

方式 B：通过 CLI 挂载本地已有目录

如果本地已有克隆好的代码仓库，也可以在终端中直接挂载：

holon workspace attach --agent ecosystem-researcher /path/to/project-a
holon workspace attach --agent ecosystem-researcher /path/to/project-b

验证挂载状态：

holon agent get ecosystem-researcher

输出中的 attached_workspaces 会列出关联的所有外部路径。

注意：workspace attach 仅扩展 Agent 对外部代码目录的访问授权，不会改变默认执行根。Agent 日常活动依然以私有的 agent_home 为核心。

3. 背后的原理：Agent 自动维护的专属知识库体系

重点机制说明： 在实际日常使用中，你完全不需要手动创建这些目录或逐行编写 YAML 配置文件！ 当你向 Agent 下达研究目标或转发项目链接时，Agent 会根据角色契约全自动初始化目录结构、自动填充对象索引表并增量归档调研报告。 本节展示其内部结构，是为了让你理解背后的沉淀原理——为什么该 Agent 能够在经历多次会话与长期运行后，依然条理清晰、记忆不丢失。

在 Agent 专属的 agent_home 中，Agent 会自动组织并维持如下知识库布局：

~/.holon/agents/ecosystem-researcher/
├── AGENTS.md                  # 长效角色契约与证据准则
├── work/agent-ecosystem/      # 核心研究知识库（Agent 自主维护）
│   ├── taxonomy.md            # 生态分类法（Agent 自动归类与迭代演进）
│   ├── registry.yaml          # 被观察对象的唯一登记索引表（自动增删与状态记录）
│   ├── projects/              # 各项目的独立长期分析归档
│   │   ├── project-a/
│   │   │   ├── metadata.yaml  # 源码路径、基线 commit、仓库元数据
│   │   │   ├── architecture.md# 架构拆解与核心模块证据
│   │   │   └── updates.md     # 随版本发布的增量跟踪记录（只追加不重写）
│   │   └── project-b/
│   └── matrices/              # 跨项目横向比对矩阵（按技术专题汇总）

索引登记表规范（registry.yaml 原理）

当 Agent 获悉新的观察对象时，它会自动在 registry.yaml 中维护条目：

meta:
  initialized: 2026-10-29
  description: "AI Agent 生态研究对象索引"

objects:
  - slug: project-a
    name: "Project A Runtime"
    category: "agent_runtime"
    status: "monitoring"
    upstream: "https://github.com/org/project-a"
    sources:
      - role: primary
        local_path: "/home/user/src/github.com/org/project-a"
        baseline_commit: "a1b2c3d4..."
    research_path: "projects/project-a"

  - slug: project-b
    name: "Project B Harness"
    category: "harness"
    status: "monitoring"
    upstream: "https://github.com/org/project-b"
    sources:
      - role: primary
        local_path: "/home/user/src/github.com/org/project-b"
        baseline_commit: "e5f6g7h8..."
    research_path: "projects/project-b"

通过将状态固化在结构化文件中，即便对话历史因模型上下文轮转而被截断，Agent 也能在下一次唤醒时直接读取登记表，精确找回历史基线。

4. 发起一次跨项目的深度架构对比任务

向 Agent 下发任务非常简单，不需要在每次发送时重复写大段格式与证据约束，因为这些规则已经固化在 Agent 的 AGENTS.md 中：

任务指令示例（直接在对话框中发送）：

“调研一下 project-a 与 project-b 在进程调度与中断恢复机制上的实现差异，做个对比。”

Agent 收到指令后的自动化闭环：

  1. 自动切换执行根深入源码：Agent 调用 SwitchWorkspace 临时切换到 project-a 与 project-b，利用 sview 等只读工具检索关键抽象，记录代码行号范围与 Commit SHA；
  2. 自主沉淀比对矩阵：根据契约，Agent 分析完成后切回 agent_home，将结论写入 work/agent-ecosystem/matrices/task-resumption.md，并同步更新单项目的 architecture.md；
  3. 呈递精简交付简报：在对话中返回结构化摘要与结论，并附带产物链接。

5. 验证调研产物与隔离效果

  1. 查看调研成果： 任务完成后，Agent 会在对话中输出结论摘要。

    • 直接阅读完整报告：点击简报中的关联产物链接，或者在 Web GUI 左侧文件浏览器中打开 work/agent-ecosystem/matrices/task-resumption.md 即可查阅完整比对矩阵。

  2. 核验外部代码库绝对纯净： Agent 产生的所有文件、分析笔记和矩阵全部安全保存在其私有的 agent_home 中。被观察项目的 Git 状态依然保持绝对纯净：

    git -C /home/user/src/github.com/org/project-a status
git -C /home/user/src/github.com/org/project-b status

    两者输出均为 working tree clean。这证明 Agent 的全部研究过程产物都被严格隔离在自己的私有空间中，对被测源码没有任何污染。

日常交互场景：随手转发项目与移动端异步调研

除了在电脑前进行多项目源码的深度审查外，技术生态调研往往来自于日常碎片化浏览时的偶然发现。在移动端场景下，Holon 的长效异步特性体现得尤为充分。

移动端随手分享链接

当你通过手机（无论是使用 iOS 客户端、Android 客户端 还是移动端网页浏览器）刷社交平台、技术论坛或 GitHub 时，一旦看到一个值得关注的新开源项目或深度架构文章：

  1. 直接分享或发送给 Agent： 在手机中点击分享，或在 Holon 对话界面中直接粘贴链接并附带简短诉求：

    “调研一下这个新项目：https://github.com/example/novel-runtime ，重点看它的调度机制和定位，与我们已有的生态库进行对比。”

  2. 无需驻留，离线异步执行：

    • 发送后即可直接锁屏或切换应用。因为 Holon 是运行在主机上的长效守护进程，任务由底层的 WorkItem 驱动，不需要客户端保持连接；
    • Agent 收到指令后，会自动调用网络工具（如 WebFetch、WebSearch）和 ghx 抓取仓库的主页信息、README、Release 契约和架构文档；
    • Agent 自动将其登记到 registry.yaml 索引中，并在 projects/novel-runtime/architecture.md 中生成第一期技术简评。

  3. 随时随地查阅交付简报：

    • 稍后重新打开手机客户端或电脑端 Web GUI，Agent 的研究报告已在等待你审阅：包含该项目的定位分类、核心创新点、潜在局限性以及与现有观察项目的异同；
    • 如果初评结果显示该项目非常有价值，你回到工作台后只需将其实际克隆到本地并执行一次 workspace attach，Agent 便能在现有分析基础上，无缝进入该项目的本地源码进行 AST/Commit 级的深层研读。

进阶技巧：长期增量跟踪与自动化巡检

当生态中的开源项目持续发布新版本时，无需每次重新进行全量调研：

  • 基线 Commit 锁定：始终以 Agent 记录在 registry.yaml 中的 baseline_commit 为基准。只有当你明确要求升级基线时才执行比对更新。
  • 配置定时巡检： 利用 Holon 的定时器机制（参阅调度 Agent 工作），无论在 Web GUI 还是 CLI 中，均可为 Agent 设置每周或每天的定时唤醒任务。Agent 会自动检查被观察项目的最新 Release 或提交历史，仅针对破坏性变化生成增量记录（updates.md），形成活态技术雷达。

相关内容