Qiulin Fan

将 kgdistiller 变成 Skills 的外接大脑：职责拆分需求文档

Wed, 05 Aug 2026 00:00:00 GMT

这是一份面向实现的需求文档。它记录为什么要把现有的知识图谱工作流拆成四个职责明确的 Skill，以及 kgdistiller 作为“外接大脑”时必须提供怎样的查询、对齐和入库边界。

用户原始需求（逐字记录）

你说的有一点是不对的, 需要我纠正:
- "qlblog 固定使用仓库内的 kgdistiller 版本，CI 不再偷偷跟随外部 main"
恰恰相反, 我会经常更新 qlblog 中, kgdistiller 的版本. 并且我正在计划, 把这个流程按照职能划分给多个 skills.
现在我需要实现:

我希望原本的:
- 1. 笔记 export  web-> 顺便提取知识图谱的 skill, 只负责好(识别我直接写的知识图谱以及) 从 git 改动中提取知识图谱的这一步. 而它原本还需要
  - 在提取的知识图谱的过程中, 确认哪些是现有的知识图谱中已经有的. 不添加新的词条, 而是给 ref
  - 负责把知识图谱合进大的知识图谱里
- 2. 从论文中提取知识图谱的 skill, 只负责好从论文中提取知识图谱; 而它有一步是: 在给出所有知识词条的解释之前, 先查询现有的知识图谱(现在改成查询现有的知识库), 确认哪些知识是已经有的, 便:
  - 不再给出这些知识的词条
  - 并且通过这些知识节点, 连接两张图谱(不并进大的个人知识图谱里, 只是给一个快照. 只有额外要求时才会并进去并给出源)
这些行为, 原本都是属于这两个 skills 的职能. 但是太冗长. 一方面, 单个 skill 负责太多功能会导致幻觉; 另一方面, 它们原本阅读大的知识图谱, 会导致 tokens 消耗过多.

我希望职能分责. 现在我们做了这个仓库, 本质就是: 给它们一个外接大脑. 这个知识图谱的知识源全部封装在这个kgdistiller 的数据库里. 它提供入库和查询 api 即可!

入库和查询, 分别做成一个 skill, 伴随着 kgdistiller. 它们给现有的两个 skills 调用.

这是一件宏大的事情, 其实就是精简现有的两个 skills, 以及创造两个新的 skills. 我们可以暂时不管现在的这个 graphRAG 知识库系统实现的精准度如何, 先精确地规划这一套流程.

后续交付要求同样逐字记录：

非常好, 把我的要求 (原话) 以及你刚才的这段理解全部写成 dev blog: 需求文档
然后推送. 然后先实现全部的 skills, 再交给我 review

已确认的理解与方案

正确的版本策略应该是：

kgdistiller 高频升级，单次运行可追溯。

qlblog 会持续跟随 kgdistiller 的 main 并经常更新 submodule revision；每个 qlblog commit 记录当次实际使用的版本，以便复现，而不是永久固定在某个版本。

一、最终只保留四个职责

Skill	唯一职责	不再负责
`extract-and-export-notes`（原 `export-typst-math-notes`）	从任意领域 Git 改动和用户显式 marker 中提取候选图，按查询结果写 `kn/ref`，最后导出网页	读取完整知识图谱、执行身份匹配、直接合并全局图谱
`extract-paper-concepts`	通读论文，生成独立论文候选图和论文内部学习关系	读取个人大图谱、重复解释已知词条、默认导入个人图谱
新建 `query-kgdistiller`	只读查询、批量消歧、GraphRAG、候选图对齐和比较	修改 authority、alignment 或个人图谱
新建 `ingest-kgdistiller`	将已经审查的 marker、entry、ref、edge 事务性写入知识库	从原文发现概念、猜测歧义身份、读取整篇论文

现有 kgdistiller-distill 与新结构重复，完成迁移后退出主流程，只保留短期兼容入口或直接删除。

二、外接大脑的真正边界

从其他 Skill 看，kgdistiller 是一个不透明知识库：

flowchart LR
    N["笔记 Git diff"] --> C["候选图快照"]
    P["论文全文"] --> C
    C --> Q["query-kgdistiller<br/>只读查询与对齐"]
    Q --> D{"调用场景"}
    D -->|笔记| I["ingest-kgdistiller<br/>唯一图谱写入口"]
    I --> K["个人知识库"]
    K --> W["网页导出"]
    D -->|论文默认| S["论文 × 个人图谱<br/>联邦快照"]
    S -->|明确要求导入| I

上游 Skill 禁止：

打开或遍历 knowledge/graph/*.jsonl；
直接读取 SQLite；
自己实现名字匹配、别名判断或图遍历；
自己执行 apply/sync 合并全局图谱。

它们只能传入候选图路径或查询条件，并接收一个受预算限制的结构化结果。

内部仍保持“Markdown/Typst/LaTeX 是权威源、SQLite 是可重建索引”的原则。所谓“知识全部封装在数据库里”，是对调用方的封装，而不是丢弃来源文件和 provenance。

三、笔记工作流

extract-and-export-notes 的新流程：

用 Git diff 找出新增、修改、删除、重命名的 authority。
阅读完整改动文件，但只提取：
- 用户直接写出的 kn/ref；
- 改动中值得成为节点的候选概念；
- 候选 entry、直接关系及来源证据。
生成隔离的 qlkg-agent-snapshot-v1，不读取个人图谱。
调用 $query-kgdistiller 批量比较。
根据确定性结果修改源文件：
- known：改为现有节点的格式原生 ref，不生成 entry；
- new：保留或添加 authority marker，生成 entry；
- partial：只处理缺失的部分，不复制已有定义；
- uncertain/conflict：停止自动写入，进入 review。
调用 $ingest-kgdistiller。
收到成功回执后才允许导出网页。

因此，导出 Skill 仍然理解 Typst/Markdown/LaTeX marker，但不理解知识库内部实现。

四、论文工作流

extract-paper-concepts 分成两个阶段。

第一阶段只生成轻量候选图：

概念名、论文局部别名；
在论文中的作用；
精确来源位置；
论文内部的直接 prerequisite；
不先撰写所有完整词条。

然后调用 $query-kgdistiller。

第二阶段按比较结果生成最终快照：

known：
- 不再生成该概念的知识词条；
- 只保留论文角色、来源位置和指向个人节点的 bridge。
partial：
- 只解释个人知识库中缺失的条件、限定或论文特定部分。
new：
- 生成完整、来源支持的论文词条。
uncertain/conflict：
- 保留候选匹配和证据，禁止自动合并。

最终产物是一张联邦快照：

paper namespace
    ├── 新概念和论文特定概念
    ├── 论文内部关系
    └── alignment bridges ──> personal namespace

个人图谱的 digest 在默认论文流程前后必须完全不变。

只有用户明确提出“把这篇论文的新知识加入我的知识库”时，论文 Skill 才：

选择需要导入的 new/partial 节点；
创建带论文来源的 research authority；
将已知概念写成 ref；
调用 $ingest-kgdistiller。

五、两个新 Skill 的接口

`query-kgdistiller`

只调用只读 MCP：

kg_status
kg_resolve_concepts
kg_search
kg_build_context
kg_align_graph
kg_compare_graph

输入可以是批量名字或候选 snapshot 路径。输出沿用现有：

qlkg-alignment-report-v1
qlkg-graph-comparison-v1
qlkg-context-bundle-v1

它不保存 reviewed mapping。需要持久化 mapping 时，也必须交给 ingest Skill。

`ingest-kgdistiller`

新增统一事务协议：

qlkg-ingest-request-v1
├── mode
├── base_graph_sha256
├── candidate_snapshot_sha256
├── query_report_sha256
├── authority files
├── expected marker/ref state
├── reviewed qlkg-agent-delta-v2
└── review evidence

kgdistiller 负责执行：

precondition check
→ scan
→ apply reviewed delta
→ sync
→ curate-check
→ global check
→ rebuild disposable index
→ emit receipt

输出 qlkg-ingest-receipt-v1，包含：

写入前后 graph digest；
engine version 和 capability；
新增、复用、更新的节点；
ref 与 edge 变化；
authority/source hashes；
所有验证结果。

如果查询后图谱发生了变化，digest 不匹配，入库必须拒绝并要求重新查询。

六、Skill 的归属与升级

建议采用：

kgdistiller 仓库维护：
- 引擎 API；
- query-kgdistiller；
- ingest-kgdistiller；
- schema 和兼容性测试。
qlblog 维护：
- extract-and-export-notes；
- extract-paper-concepts；
- 个人知识源和网页策略。

make kgdistiller-update 更新到 kgdistiller main，同时更新两个伴随 Skill。每次调用先通过 kg_status.capabilities 做版本握手。

即：

持续跟随 main
+ 每次升级后跑兼容性测试
+ qlblog commit 记录本次解析到的 revision

七、实施顺序

在 kgdistiller 固化上述职责和 ingest request/receipt 协议。
实现事务型 kgdistiller ingest API 和 capability 握手。
创建两个薄 Skill；核心逻辑放在 API，不把命令编排重新塞回 Skill。
精简两个现有 Skill，并删除其中直接读图、对齐和合并的逻辑。
用两个端到端场景验收：
- 笔记 Git diff：已知概念只产生 ref，新概念才入库；
- solvablemodel：已知概念不生成词条，论文默认只生成联邦快照。
更新 qlblog 的 kgdistiller revision，跑两个仓库的完整测试、构建和网页发布。

这一轮先不优化 embedding、PPR 或别名识别精度；验收重点是：职责不串线、上游不读大图、论文默认不污染个人图谱、所有个人图谱写入只经过一个入口。

三系统 Coding Agent 安装与选择：Claude Code、Codex、OpenCode，以及 OpenClaw、Hermes 与 Multica

Mon, 13 Jul 2026 00:00:00 GMT

过去一年里，“Agent”几乎被用来描述所有带工具调用的 AI 产品。但把它们真的装到电脑上以后，会发现它们至少分成三层：

Coding agent：进入一个代码仓库，读文件、改代码、运行命令、测试和提交；
Personal autonomous agent：长期运行，有记忆、定时任务和聊天渠道，能处理编程之外的事务；
Multi-agent management plane：不亲自写代码，而是管理多个 agent 的任务、运行环境和协作关系。

这篇文章先在 Windows、macOS、Linux 上安装三款 coding agent：Claude Code、Codex、OpenCode；再讨论 OpenClaw、Hermes 为什么属于另一类产品；最后看看 Multica 如何把这些 agent 组织成团队。

层级	解决的问题	本文项目
L1：仅 Agent	在当前仓库中完成一次编码任务	Claude Code、Codex、OpenCode
L2：Agent + 记忆 + 调度	跨会话记忆、定时运行、从聊天渠道持续接活	OpenClaw、Hermes
L3：分布式 Agent 调度平台	跨机器、跨供应商分派、观察和管理许多 agent	Multica

L2 并不是“能力更强的 L1”，L3 也不是“更大的模型”。三个层级可以叠加：Multica 调度 Hermes，Hermes 再调用 coding subagent，是一种合理的组合；但层级越高，权限面、常驻进程和运维责任也越大。

本文命令核对于 2026-07-13。Agent CLI 更新很快，实际安装前最好再点开文末官方文档确认一次。

先给结论

如果只想选一个：

已经重度使用 Claude，希望得到完整、统一的 Claude 工具链：选 Claude Code；
已经订阅 ChatGPT，重视沙箱、审批和 OpenAI/Codex 工作流：选 Codex；
想自由切换模型供应商、查看开源实现、深度定制 TUI：选 OpenCode；
想要一个能常驻服务器、接入聊天软件、定时工作的个人助理：研究 OpenClaw 或 Hermes；
想同时管理许多 Claude Code、Codex、OpenCode 实例：在它们上面加一层 Multica。

一个重要原则是：比较 agent 时，要把“模型能力”和“agent harness 能力”分开。 OpenCode 可以连接 Claude、OpenAI 或其他模型；同一个模型放在不同 harness 中，也会因为上下文管理、工具、权限、提示词和压缩策略而产生不同体验。

三系统的共同准备

macOS

建议先装 Homebrew 和 Git。Node.js 只在选择 npm 安装方式时需要：

xcode-select --install
brew install git node

Linux

以 Ubuntu/Debian 为例：

sudo apt update
sudo apt install -y git curl ca-certificates

如果使用 npm 安装 OpenCode 或 Codex，再安装一个仍受支持的 Node.js 版本。不要为了省事长期依赖发行版仓库里过旧的 Node/npm。

Windows

三款工具现在都能以某种形式运行在原生 Windows 上，但如果项目本身使用 Linux 工具链，我仍建议统一放进 WSL2：

wsl --install

重启后进入 Ubuntu，把仓库 clone 到 WSL 的 ~/code，而不是长期放在 /mnt/c。这样通常能获得更好的文件系统性能、权限语义和 shell 兼容性。

原生 Windows 更适合依赖 Visual Studio、PowerShell、Windows SDK 或其他 Windows-only 工具的项目。

L1：仅 Agent

这一层的生命周期通常从 cd project 开始，到一次任务或一次会话结束。它们可以有 subagent，但核心对象仍是当前代码仓库。

Claude Code

Claude Code 是 Anthropic 的 coding agent。它提供内置文件/搜索/命令工具，并围绕 CLAUDE.md、Skills、MCP、Hooks、Subagents 和 Agent Teams 形成了较完整的扩展体系。

macOS / Linux / WSL2

Anthropic 当前推荐原生安装器：

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

macOS 也可以走 Homebrew 的稳定频道：

brew install --cask claude-code

Windows 原生

PowerShell：

irm https://claude.ai/install.ps1 | iex
claude --version

也可以使用 WinGet：

winget install Anthropic.ClaudeCode

原生 Windows 建议安装 Git for Windows；如果没有 Git Bash，Claude Code 会回退到 PowerShell。需要沙箱化命令执行时优先选择 WSL2，因为 Anthropic 文档明确说明 native Windows 暂不支持 sandboxing。

登录与启动

cd /path/to/project
claude

首次启动会打开登录流程。Claude Code 支持 Claude Pro、Max、Team、Enterprise、Console，也能通过 Bedrock、Vertex AI 等第三方平台接入。

它的优势

Claude 生态的一体化体验，配置和模型能力衔接自然；
CLAUDE.md、Skills、Hooks、MCP、Subagents 都有成熟的一等支持；
Subagent 能隔离上下文，Agent Teams 能让独立会话共享任务并互相通信；
原生安装器可以后台自动更新。

需要留意

主要围绕 Claude 模型与 Anthropic 账户体系；
Agent Teams 仍属于实验功能；
原生 Windows 与 WSL2 的沙箱能力不同；
不要盲目开启 --dangerously-skip-permissions 一类绕过保护的模式。

官方资料：安装说明、扩展体系、Subagents。

Codex

Codex 是 OpenAI 的本地 coding agent CLI，同时还存在 IDE、桌面应用和云端形态。CLI 适合在仓库中执行读写文件、命令、测试、审查与自动化任务，并用 sandbox 和 approval policy 控制风险。

macOS / Linux

官方安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

macOS 也可以使用 Homebrew：

brew install --cask codex

或者在已经有现代 Node.js/npm 的机器上：

npm install -g @openai/codex

Windows

官方 PowerShell 安装器：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --version

Codex 已提供 Windows 构建，但官方系统要求文档仍把 Windows 11 + WSL2 作为标准支持路径。对跨平台工程，WSL2 通常也是更稳妥的基线。

登录与启动

cd /path/to/project
codex

首次启动选择 Sign in with ChatGPT。官方建议 Plus、Pro、Business、Edu、Enterprise 用户直接使用 ChatGPT 账户；也可以另行配置 API key。

它的优势

OpenAI/Codex 模型与 ChatGPT 订阅的直接整合；
CLI、IDE、桌面、Web/Cloud 等多种工作入口；
对 sandbox、网络和文件权限、命令审批有明确的控制层；
AGENTS.md 可以把项目约定随仓库一起提交；
适合把重复流程保存成 Skills，或通过 MCP/插件连接外部系统。

需要留意

不同 Codex surface 的能力并不完全相同，CLI、桌面和云端不能简单视为同一个 UI；
Windows 用户要留意 native 与 WSL2 的环境边界；
API key 计费和 ChatGPT 套餐内使用是两条不同的认证/计费路径；
自动批准写文件、联网和执行命令之前，先理解当前 sandbox 与 approval 设置。

官方资料：Codex 官方仓库与安装命令、系统要求、Codex 文档。

OpenCode

OpenCode 是开源、provider-neutral 的 coding agent。它既有 TUI，也提供桌面应用和 IDE 扩展。与前两者相比，它最大的差异不是“某个固定模型更强”，而是允许你选择和组合不同模型供应商。

macOS / Linux / WSL2

官方安装脚本：

curl -fsSL https://opencode.ai/install | bash
opencode --version

macOS/Linux 也可以用官方 tap：

brew install anomalyco/tap/opencode

或者 npm：

npm install -g opencode-ai

Windows

官方仍推荐 WSL2；在 WSL 中执行 Linux 安装命令即可。原生 Windows 也有多种方式：

choco install opencode
# 或
scoop install opencode
# 或
npm install -g opencode-ai

连接模型并初始化仓库

cd /path/to/project
opencode

进入 TUI 后：

/connect
/init

/connect 用来登录 OpenCode Zen 或其他模型 provider；/init 会分析仓库并创建 AGENTS.md。

它的优势

开源且 provider-neutral，可在多种商业/开源模型之间切换；
TUI、Desktop、IDE 多种入口；
permissions 可以按 read、edit、bash、websearch、task、external_directory 等工具细分；
支持 primary agent、subagent 和针对不同 agent 的模型/权限配置；
对希望观察、修改 agent harness 的用户更友好。

需要留意

“自由选择 provider”也意味着认证、模型能力、价格和稳定性需要自己管理；
不同模型对工具调用和长任务的表现差异很大；
OpenCode 本身开源，不代表你连接的云模型或 API 免费；
Windows 虽能原生运行，官方仍建议 WSL 获得更完整体验。

官方资料：快速开始、Windows/WSL、Providers、Agents 与权限。

Claude Code、Codex、OpenCode 横向比较

维度	Claude Code	Codex	OpenCode
核心定位	Anthropic 的 coding agent	OpenAI 的 coding agent 与多 surface 工作流	开源、provider-neutral agent harness
默认生态	Claude / Anthropic	OpenAI / ChatGPT / Codex	OpenCode Zen 或自选 provider
开源情况	CLI 产品本身不是以完全开源 harness 为卖点	CLI 核心仓库 Apache-2.0	开源
项目指令	`CLAUDE.md`	`AGENTS.md`	`AGENTS.md`
扩展	Skills、MCP、Hooks、Plugins	Skills、MCP、Plugins、Hooks/配置	Agents、Plugins、MCP、Commands、Skills
多 Agent	Subagents；实验性 Agent Teams	Subagents/协作能力依 surface 和版本而异	Primary agents + subagents + task 权限
权限控制	工具权限、Hooks、sandbox（平台有差异）	sandbox + approval policy	每类工具 `ask/allow/deny`，支持 pattern
模型自由度	主要是 Claude 生态	主要是 OpenAI/Codex 生态	最灵活，可接多 provider
Windows 建议	Native 或 WSL2；沙箱优先 WSL2	标准支持路径优先 WSL2	官方推荐 WSL2
最适合	想获得完整 Claude 工作流的人	ChatGPT/OpenAI 用户、重视受控执行的人	想换模型、看源码、深度定制的人

不要只看 benchmark

对日常开发更重要的往往是：

它是否正确理解现有仓库规则；
修改前是否会先读测试和相关代码；
长任务中能否保持计划与状态；
出错后是否会诊断，而不是反复试错；
权限边界是否符合你的风险承受能力；
最终 diff 是否容易审查。

最公平的比较方法，是让三者在同一个仓库完成同一组真实任务：一个小 bug、一个跨文件 feature、一次代码审查和一次测试失败诊断。记录成功率、用时、人工干预次数、最终 diff 与实际费用，而不是只比较第一轮回答有多惊艳。

安装只是第一天：版本更新与健康检查

Agent 拥有 shell、文件和网络权限，版本更新不是为了追新功能，而是安全维护的一部分。建议每月至少检查一次；出现磁盘、CPU、内存、登录或权限异常时，第一步先记录版本和进程，再查官方 issue，不要让 agent 在未知根因下自动“清理系统”。

更新命令速查

先运行版本命令，更新后再运行一次，确认实际 binary 已变化：

工具	查看版本	推荐更新方式
Claude Code	`claude --version`	原生安装：`claude update`；Homebrew：`brew upgrade --cask claude-code`；WinGet：`winget upgrade Anthropic.ClaudeCode`
Codex	`codex --version`	安装脚本：重新运行官方 installer；npm：`npm install -g @openai/codex@latest`；Homebrew：`brew upgrade --cask codex`
OpenCode	`opencode --version`	`opencode upgrade`；检测错误时显式指定 `--method curl/npm/pnpm/bun/brew`
OpenClaw	`openclaw --version`	先 `openclaw update status` 或 `openclaw update --dry-run`，再 `openclaw update`
Hermes	`hermes version`	先 `hermes update --check`，高价值配置用 `hermes update --backup`
Multica	`multica version`	`multica update`；自托管还要按 release notes 更新 server/container

通过系统包管理器安装的工具，最好继续用同一个包管理器升级。混用 installer、npm、Homebrew 后，PATH 中可能同时存在多个版本；更新“成功”却仍运行旧 binary 时，检查：

which -a claude codex opencode openclaw hermes multica

PowerShell 使用：

Get-Command claude,codex,opencode,openclaw,hermes,multica -All

Codex SSD 写入事件：为什么必须更新

2026 年 6 月的 openai/codex#28224 报告了一个严重的 SQLite 日志写入放大问题：报告者的机器运行约 21 天后，主 SSD 累计写入约 37 TB。高频 TRACE、WebSocket/SSE payload 和镜像 OTel 日志持续写入：

~/.codex/logs_2.sqlite
~/.codex/logs_2.sqlite-wal
~/.codex/logs_2.sqlite-shm

数据库保留的逻辑内容可能只有几百 MB，但“插入 → WAL → 索引 → prune/checkpoint”的循环会造成远高于文件大小的物理写入量，所以只看 du ~/.codex 会严重低估 SSD 压力。其他官方 issue 也记录了 streaming 时约 5 MiB/s、峰值约 16 MiB/s 的持续写入，以及数分钟内 WAL 增长到上百 MB的情况。

官方仓库记录的关键缓解是：

Codex 0.142.0：停止记录每个 Responses WebSocket event，并过滤 noisy targets；
Codex 0.143.0：停止持久化 bridged log events。

报告者称这几项改动减少了约 85% 的日志。因此本文的最低建议是：不要继续运行低于 0.143.0 的 Codex；优先升级到当前 latest，并在升级后实际监控。 “减少 85%”不等于所有 SQLite/WAL 写入问题都已永久消失。

codex --version

# npm 安装
npm install -g @openai/codex@latest

# Homebrew 安装
brew upgrade --cask codex

检查日志文件大小：

du -h ~/.codex/logs_2.sqlite* 2>/dev/null

PowerShell：

Get-ChildItem "$HOME\.codex\logs_2.sqlite*" |
  Select-Object Name,Length,LastWriteTime

Linux 可以在使用 Codex 时观察：

sudo iotop -oPa

macOS 可在 Activity Monitor 的 Disk 页面观察 Codex/Code Helper 写入，或用 fs_usage 做短时间诊断。重点不是某一刻 WAL 有多大，而是空闲或普通 streaming 时是否仍持续高速写盘。

如果暂时无法升级且明确观察到该问题，官方 issue 中的临时方案是在完全退出 Codex 后，用 SQLite trigger 阻止诊断日志插入：

sqlite3 ~/.codex/logs_2.sqlite \
  'CREATE TRIGGER IF NOT EXISTS block_log_inserts BEFORE INSERT ON logs BEGIN SELECT RAISE(IGNORE); END;'

恢复诊断日志：

sqlite3 ~/.codex/logs_2.sqlite \
  'DROP TRIGGER IF EXISTS block_log_inserts;'

这会牺牲本地诊断日志，不是正式修复。应当优先升级，并在操作数据库前完全退出 Codex、备份重要工作。更早的复现和 workaround 见 #17320，Desktop/WAL 的另一组数据见 #24275。

常驻 Agent 的更新更像运维

OpenClaw、Hermes 和自托管 Multica 会运行 daemon/gateway。更新前额外确认：

配置、记忆、Skills、凭据和数据库有备份；
release notes 是否包含配置迁移；
当前任务是否可以安全中断；
更新后 daemon/gateway 是否已重启并报告新版本；
聊天渠道、cron、webhook 与 agent runtime 是否仍健康。

OpenClaw 的 update --dry-run 和 Hermes 的 update --check 都适合先只读预检；生产环境不要默认追 dev 或 beta channel。

L2：具有记忆和调度功能的 Agent

OpenClaw 和 Hermes 都可以写代码，也都能调用 subagent，但它们更接近长期运行的个人 agent 平台。它们不是“另两个 Claude Code”：重点从一次仓库任务转向跨会话记忆、定时运行、消息渠道和常驻 Gateway。

OpenClaw

OpenClaw 强调 Gateway、工作区、Skills、定时/自动化和多聊天渠道。它适合运行在个人电脑或服务器上，从 Telegram、Discord、Slack 等入口接收任务。

系统要求是 Node 22.19+、23.11+ 或 24+。推荐安装方式：

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

安装器会进入 onboarding；已有 Node 环境也可以用 npm 安装。详细方式见 OpenClaw 安装文档和官方仓库。

Hermes Agent

Hermes 是 Nous Research 的 autonomous agent，重点是 persistent memory 和内置 learning loop：它会从经验中创建、改进 Skills，并能够跨会话积累对用户和任务的理解。官方还强调定时任务、跨聊天渠道、隔离 subagents，以及 local、Docker、SSH、Singularity、Modal 等 sandbox backend。

# Linux / macOS / WSL2 / Termux
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装后可用 hermes setup --portal 完成模型与工具配置。官方资料：Hermes 文档、Nous Research 产品页、官方仓库。

两者怎么选

维度	OpenClaw	Hermes
核心心智	自托管个人助理与 Gateway	会持续学习的个人 autonomous agent
突出能力	多渠道接入、工作区、广泛集成、daemon	记忆、Skills 学习循环、调度、隔离执行
运行方式	本机/服务器常驻 Gateway	本机、服务器、容器或云 sandbox
适合	想快速搭一个跨渠道个人助理	希望 agent 长期积累习惯与可复用能力

它们拥有比 coding CLI 更长的生命周期和更广的权限面。不要一上来就给它邮箱、浏览器登录态、SSH key、云账号和无限 shell 权限。先用单独账号、最小权限、隔离容器和可审计日志做实验。

L3：Agent 分布式调度平台

Multica 与上面五个项目的关系最容易被误解。它不是第六个模型，也不是又一个终端 coding agent；它是一个 open-source managed agents platform。这一层关心的是跨机器 runtime、任务队列、状态、路由、团队和复用，而不是某一轮对话如何生成代码。

可以把层次画成：

人类 / 团队
    ↓ 创建 Issue、分派、评论、审查
Multica（任务、Squad、Runtime、状态、Autopilot、Skills）
    ↓ 调度
Claude Code / Codex / OpenCode / OpenClaw / Hermes / 其他 CLI
    ↓ 执行
本地机器 / Worktree / 云主机 / 自托管 Runtime

Multica daemon 会检测机器 PATH 上可用的 agent CLI。你在 board 上把 issue 分配给一个 agent 后，系统负责 enqueue、claim、start、complete/fail 等生命周期，实时展示进度；Squad 用一个稳定的团队入口把工作路由给成员，Autopilot 则用 cron、webhook 或手动触发重复任务。

安装

macOS/Linux：

brew install multica-ai/tap/multica
# 或
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

Windows PowerShell：

irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex

然后连接 Cloud 并启动 daemon：

multica setup

如果要自托管完整服务，则需要 Docker，并按 Self-hosting 文档部署。

Multica 的价值在 agent 数量超过一两个之后才明显：它把散落在不同终端、不同机器、不同供应商中的执行过程，变成可分派、可观察、可复用的团队工作流。官方资料：Multica 仓库、中文 README。

非必要不跑命令行：让一个 Agent 安装其他 Agent

Harness 时代，一个合理的期待是：用户不必手动复制本文几十条命令。只要机器上已经有一个可用的 coding agent，就应该让它读取安装 runbook、检测环境、展示计划，然后代为执行。

但这里存在一个无法消除的 bootstrap：如果新机器上一个 agent 都没有，第一次仍要通过图形安装器、WinGet/Homebrew，或一条官方安装命令装好 seed agent。 之后就可以“用 agent 安装 agent”。

1. Clone 这份 runbook

git clone https://github.com/qiulinfan/qiulinfan.github.io.git
cd qlblog

仓库中的 install/agent-stack.md 是给人和 agent 共同阅读的安装说明。AGENTS.md 与 CLAUDE.md 会引导 Codex、OpenCode、Claude Code 找到它。

2. 用你已有的 agent 打开仓库

三选一即可：

codex
# 或 claude
# 或 opencode

然后直接输入：

请完整阅读 install/agent-stack.md。
先只读检测我的操作系统、架构、shell、WSL、包管理器、Node/npm 版本，
以及已经安装的 agent。不要立即安装。

检测后给我一个计划，列出：
1. 已安装和缺失的工具；
2. 建议使用 native Windows 还是 WSL2；
3. 每个安装动作的官方来源、是否需要管理员权限；
4. 哪些动作会安装 daemon、gateway、登录项或定时任务；
5. Codex 是否至少为 0.143.0，以及如何监控 logs_2.sqlite 的写盘。

等我确认具体产品和层级后再执行。每安装一个工具，都验证 binary 路径和版本。

3. 按层级授权，而不是说“全部装上”

推荐分三次：

第一步只安装 L1：Claude Code、Codex、OpenCode。不要安装常驻服务。

用一段时间以后再决定：

现在评估 L2。比较 OpenClaw 和 Hermes 对我的需求；只安装我选中的一个，
先不要接入聊天账号，也不要启动 daemon/gateway，直到再次得到我的确认。

最后才考虑调度平台：

现在安装 Multica CLI，但不要运行 multica setup，也不要部署自托管服务。
先展示它将创建的配置、daemon 和网络连接，等我确认。

4. 为什么不提供“一键全自动脚本”

因为六个项目跨越三个权限层级：L1 修改代码，L2 可能常驻并连接私人渠道，L3 可能在多台机器调度它们。一个无确认的安装脚本无法理解：

你想用 native Windows 还是 WSL2；
已有工具是 npm、Homebrew 还是 installer 管理；
是否允许后台服务和开机启动；
API key、ChatGPT/Claude 订阅与模型 provider 如何选择；
Multica 用 Cloud 还是自托管；
哪些账号和目录允许 agent 访问。

所以这里的自动化边界是：agent 负责检测、查官方文档、执行和验证；人负责选择层级、授权持久化和提供凭据。 这比一条 install-everything.sh 慢一分钟，但安全得多，也更容易维护。

我的建议组合

个人开发者，先求稳定

先选 Claude Code 或 Codex 之一作为主力，再保留 OpenCode 用于跨 provider 实验。不要同时维护三套复杂配置。

Windows + Linux 工具链

把仓库和三个 CLI 都放进 WSL2。Windows 浏览器仍可完成 OAuth，VS Code/Cursor 可以通过 Remote WSL 连接同一个文件系统。

多模型研究者

以 OpenCode 为统一界面，固定一组任务分别测试 Claude、OpenAI 和其他模型。比较时保存配置、模型版本、权限和提示词，否则结果不可复现。

想做 24/7 自动化

先在隔离 VPS 或容器里试 OpenClaw/Hermes，不要直接部署到存放全部私人数据的日常电脑。为每个外部服务创建最小权限凭据。

小团队管理多个 Agent

把 Claude Code、Codex、OpenCode 当作 worker，把 Multica 当作任务与运行时控制平面。代码 review 和最终合并仍然保留人类责任。

安全清单

无论选哪一个，至少做到：

安装脚本来自官方 HTTPS 域名或官方 GitHub 仓库；
对 curl | bash、irm | iex 有顾虑时，先下载并阅读脚本再执行；
不把 API key 写进仓库、聊天记录、Notebook 输出或 core dump；
默认开启审批和沙箱，从最小权限开始；
给 GitHub、云平台、聊天渠道创建独立且可撤销的 token；
自动化 push、发消息、发邮件、部署和删除资源前保留人工确认；
定期检查 agent 创建的定时任务、daemon、Skills、MCP server 和日志；
把 AI 生成的 diff 当作未经审查的外部贡献。

结语

Claude Code、Codex、OpenCode 解决的是“这个仓库里的工作如何完成”；OpenClaw、Hermes 解决的是“这个长期在线的个人 agent 如何记忆、接收和执行任务”；Multica 解决的是“很多 agent 如何像团队成员一样被分派、观察和管理”。

与其寻找一个包打天下的产品，不如先选对层级，再组合工具。对大多数开发者，最健康的起点仍然是：一个主力 coding agent、清楚的权限边界、可复现的测试，以及一个愿意认真看 diff 的人。