// 手动编写的HTTP请求封装示例
public ApiResponse createQualityRule(Long projectId, String ruleName, 
        Integer ruleType, String checkExpression, Long tenantId) {
    return httpClient.post("/api/quality/rules")
        .queryParam("projectId", projectId)
        .body(new JSONObject()
            .put("projectId", projectId)
            .put("ruleName", ruleName)
            .put("ruleType", ruleType)
            .put("checkExpression", checkExpression)
            .put("tenantId", tenantId)
        )
        .execute();
}

这里最容易出错的地方是：参数名拼写错误、参数遗漏、数据类型不匹配。因为全程是人工从开发者工具面板中手抄过来的，一个驼峰拼写的差异就会导致接口调用失败。

[
  {
    "method": "GET",
    "url": "https://bff.example.com/api/quality/tree?projectId=100001",
    "requestBody": null,
    "responseBody": "{\"requestId\":\"xxx\",\"data\":[ ],\"code\":200}"
  },
  {
    "method": "POST",
    "url": "https://bff.example.com/api/quality/catalog?projectId=100001",
    "requestBody": "{\"projectId\":100001,\"parentId\":0,\"level\":1,\"name\":\"测试文件夹\",\"tenantId\":700000000000}",
    "responseBody": "{\"requestId\":\"xxx\",\"data\":{\"id\":12},\"code\":200}"
  }
]

测试用例名称: 数据质量自定义模板管理
测试步骤:
1. 查询质量目录树，确认初始为空
2. 创建目录文件夹
3. 检查模板名称唯一性
4. 创建自定义规则模板
5. 查询用户自定义模板列表，验证创建成功

录制数据 = 完整的接口调用序列（机器可理解的事实）
用例描述 = 测试意图和验证目标（人类的业务期望）
二者结合 = AI可以生成既技术正确又业务准确的代码

// AI自动生成的HTTP请求封装（参数精确匹配录制请求）
public ApiResponse createCatalog(Long projectId, Long tenantId, 
        Integer parentId, Integer level, String name) {
    return httpClient.post("/api/quality/catalog")
        .queryParam("projectId", projectId)
        .body(new JSONObject()
            .put("projectId", projectId)
            .put("parentId", parentId)
            .put("level", level)
            .put("name", name)
            .put("tenantId", tenantId)
        )
        .execute();
}
// AI自动生成的测试用例（正确编排数据流）
@Test(description = "数据质量自定义模板管理")
public void testCustomTemplateManagement() {
    var catalogId = stepCreateCatalog();      // 创建目录，获取ID
    var isUnique = stepCheckNameUnique();     // 用目录ID检查名称
    var templateId = stepCreateTemplate(catalogId); // 用目录ID创建模板
    stepVerifyTemplateCreated(templateId);    // 验证创建结果
    reportTestResults();
}

跳转微信打开

每当我向同事介绍 Skill 时，最常被问到的一个问题是：

"你把自己的工作流写进 Skill，让 AI 自动跑——那以后还需要你吗？还需要我吗？"

这其实是同一道题的两面：当 AI 学会了我们的"流程"，我们的"价值"还在哪里？

黄仁勋在那段访谈里给了一个非常性感的回答——任务（Task）会被自动化，但体验（Experience）和判断（Judgment）不会。AI 看片子比放射科医生准，结果放射科医生不降反升，因为医生的工作从"看片子"升级成了"诊断疾病"。

把这个逻辑放回 Skill 的语境里：

• ❌ Skill 替代的不是"你"，而是替代你身上那些重复、冗长、易错、本来就不该占用大脑的"任务"。

• ✅ Skill 替代不了的"你"，是你生成的Skill在体验上的丝滑和你对Skill执行的准确性的判断成为你新的价值。

💡 **你需要焦虑的不是"被 Skill 替代"，而是"还没学会用 Skill"**。当别人开始用 Skill 把自己的经验沉淀、复用、放大时，你还在反复手工执行同一套流程——这才是差距的开始。

至于"那以后到底还需要做什么？"，这个问题我会在最后一章 《六、其实你只要一个 Skill》 给出我的解答。先别急着翻到最后，先跟着这份指南把 Skill 的本质看明白，再回头看那个答案，会更有体感。

接下来，让我们从「什么是 Skill」开始 👇

💡 一句话说清楚

Skill 是一份结构化的指令文档，它告诉 AI Agent「在什么场景下、按什么步骤、用什么工具、完成什么任务」。你可以把它理解为 Agent 的 「技能卡」—— 插上就能用，拔掉就没有。

想象你是新入职的员工刘一航（化名），公司给了你一本《阿里开发操作手册》：

Skill 并不是一股脑全部塞给 Agent 的，它采用渐进式加载策略，按需提供信息：

💡 为什么要分级加载？

Agent 的上下文窗口是有限的。如果所有 Skill 的全部内容都一次性加载，会迅速耗尽上下文空间。分级加载让 Agent 只在需要时才读取详细指令，既节省资源又保证精准执行。

Skill 平台是 Skill 的发布、搜索与安装中心，类似于应用商店。你可以在平台上浏览他人发布的 Skill、一键安装到本地，也可以将自己编写的 Skill 发布出去供他人使用。

除了专门的 Skill 平台，各类 Agent 工具也原生支持 Skill 的加载与使用。以下是常见 Agent 平台的 Skill 使用方式：

# Aone Copilot
unzip my-skill.zip -d ~/.aone_copilot/skills/
# QCoder（项目级）
unzip my-skill.zip -d .skills/
# 其他平台参考各平台文档，将解压后的目录放入对应 Skill 目录即可

方式三：使用 aone-kit CLI 安装（推荐）

aone-kit 是阿里内部的 Skill 管理命令行工具，支持从 Aone Skills 市场一键搜索、安装和管理 Skill。

第 1 步：安装 aone-kit

前提：需要 Node.js 18 或以上版本

npm install -g @ali/aone-kit --registry=https://registry.anpm.alibaba-inc.com

第 2 步：安装 Skill

在项目目录下执行以下命令，Skill 默认安装到项目下的 .agents/skills/{name}/ 目录：

aone-kit skill install <skill-name>

常用参数：

第 3 步：查看已安装 Skill

aone-kit skill list

方式三：直接创建

在 ~/.aone_copilot/skills/ 下新建一个文件夹，创建 SKILL.md 文件，写入 Skill 内容即可。详见第三章。

安装完成后，直接在 Aone Copilot 查看Skill模块或者在输入中用"/"唤起。

别紧张，跟着下面的步骤走，5 分钟就能搞定你的第一个 Skill 🎉

创建 Skill 推荐使用 skill-creator（一个专门用来创建 Skill 的 Skill 🤯）。当然，你也完全可以手动创建。

🎯 使用 skill-creator 的好处

它会引导你完成意图确认、草稿编写、测试用例设计和迭代优化的完整流程，就像有一位经验丰富的 Skill 工程师在旁边手把手教你。只需对 Agent 说："帮我创建一个 Skill，用来 xxx"，skill-creator 就会自动接管。

一个 Skill 本质上就是一个文件夹，最简单的情况下只需要一个文件：

my-awesome-skill/
├── SKILL.md          ← 唯一必需的文件！
└── (可选) 附加资源
    ├── scripts/      ← 可执行脚本（Python、Node.js、Shell 等）
    ├── references/   ← 参考文档（按需加载到上下文）
    └── assets/       ← 静态资源（模板、图标、字体等）

这是 Skill 的灵魂文件。它由两部分组成：YAML 头部和 Markdown 正文。

YAML 头部（frontmatter）

---
# 必需字段
name: dingtalk-webhook-skill
description: 通过钉钉自定义机器人 Webhook 发送群消息。当用户提到钉钉、机器人、webhook、群消息、通知、dingtalk、发消息时触发。
# 可选字段（按需添加）
license: MIT
compatibility:
  - claude-3.5+
  - aone-copilot
allowed-tools: Read Bash WebFetch
metadata:
  author: zefei.szf
  version: 1.2.0
  category: communication
  tags: [dingtalk, webhook, notification]
---

📖 字段规范来源：以上字段遵循 Anthropic Agent Skills[4] v0.1 开源规范（业界事实标准），同时兼容 skills.sh / ClawHub / Aone Skills 等主流平台。其中 name 和 description 是所有平台都强制要求的核心字段，其余按需添加。

⚠️ description 是触发的关键

Agent 目前倾向于「少触发」而非「多触发」。因此，description 要写得稍微「积极」一些，多列举可能的触发关键词和场景。例如：

• ❌ 不够好：发送钉钉消息的技能

• ✅ 推荐写法：通过钉钉自定义机器人 Webhook 发送群消息。当用户提到钉钉、机器人、webhook、群消息、通知、dingtalk、发消息时触发。

Markdown 正文

正文就是你给 Agent 的「操作手册」，通常包含以下部分：

1.快速开始 / 使用示例 — 给出 1-2 个典型的用户输入示例，让 Agent 快速理解使用场景

2.参数列表 — 用表格清晰列出每个参数的名称、是否必需、默认值和说明

3.工作流 / 执行步骤— Skill 的核心，用分步骤的方式描述 Agent 应该如何执行任务

4.错误处理 — 列出常见的错误场景和对应的处理方式

5.附加资源引用 — 如果有 scripts/ 或 references/，明确指出何时、如何使用

创作思维

在动笔写 SKILL.md 之前，先按下面的四步思考，能让你的 Skill 结构更清晰、触发更精准、行为更可控：

1.确定触发时机：先想清楚"用户在什么场景会用到"，把关键词、口令、上下文条件梳理出来 —— 这直接决定description 怎么写。

2.确定输入与输出：明确 Skill 需要哪些参数、最终交付什么产物，避免后续流程发散。

3.确定大致流程：把核心步骤、调用的工具、依赖的外部资源用 3-7 步串起来，先骨架后细节。

4.补充细节与规则：补全边界情况、错误处理、约束条件，并准备好示例或模板，让 Agent 在执行时有据可依。

💡 顺序很重要：很多人一上来就写第 3 步流程，结果触发不准（缺第 1 步）或者交付不稳（缺第 2 步）。务必从「触发时机」开始倒推。

写作原则

• 📝 用祈使句— 直接告诉 Agent 该做什么，而不是描述性地说明

• ✅ 从用户输入中提取 webhook_url 参数

• ❌ Agent 应该从用户输入中提取参数

• 🎯 解释「为什么」 — 与其堆砌 MUST / SHOULD，不如解释原因，让 Agent 理解意图后自主决策

• ✅ 使用 --headed 模式打开浏览器，因为会议室平台会检测 headless 环境并拒绝访问

• 📏 控制篇幅— SKILL.md 正文建议控制在 500 行以内。超出时，将详细内容拆分到 references/ 目录，在正文中用链接引用

• 🌍 保持通用性 — Skill 应该是通用的，不要过度绑定到特定的示例。用理论指导代替硬编码的特例

description 编写技巧

description 是 Skill 被触发的唯一入口，它的质量直接决定了 Skill 的可用性。

资源组织模式

当 Skill 需要支持多个变体（如不同框架、不同平台）时，推荐按变体组织 references：

cloud-deploy/
├── SKILL.md              ← 通用工作流 + 变体选择逻辑
└── references/
    ├── aliyun.md         ← 阿里云部署指南
    ├── aws.md            ← AWS 部署指南
    └── azure.md          ← Azure 部署指南

Agent 会根据用户的实际需求，只读取相关的 reference 文件，避免无关信息占用上下文。

脚本编写建议

• 零依赖优先：脚本尽量使用语言标准库，避免需要额外安装依赖
• 多语言 fallback：提供 Python → Node.js → Shell 的降级方案，适配不同环境
• 结构化输出：脚本输出 JSON 到 stdout，方便 Agent 解析结果
• 明确退出码：成功返回 0，失败返回非 0，让 Agent 能判断执行结果

💡 脚本的妙用

scripts/ 目录下的脚本可以不加载到上下文就直接执行。这意味着你可以把复杂的、确定性的操作（如签名计算、数据格式转换）封装成脚本，Agent 直接调用即可，既省上下文又保证准确性。

让我们来看一个真实的 Skill 示例 —— 一个用于发送钉钉群消息的 Skill：

---
name: dingtalk-notifier
version: 1.0.0
description: 通过钉钉机器人发送群消息通知。当用户提到"发钉钉消息"、
  "钉钉通知"、"群消息"、"webhook"时触发。
---
# 钉钉群消息通知
通过钉钉自定义机器人 Webhook 发送群消息。
## 快速开始
用户输入示例：
> 帮我发一条钉钉消息到部署群，内容是：v2.1.0 已发布上线
## 参数列表
| 参数 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| webhook_url | 是 | - | 机器人的 Webhook 地址 |
| message | 是 | - | 消息正文 |
| msg_type | 否 | markdown | 消息类型 |
## 工作流
### Step 1：解析参数
从用户输入中提取 webhook_url、message 等参数。
缺少必要参数时，友好地向用户询问。
### Step 2：发送消息
执行 scripts/send.py 发送消息：
python3 scripts/send.py --url URL --msg "消息内容"
### Step 3：确认结果
检查返回的 errcode，向用户报告发送结果。
## 错误处理
| 错误 | 处理方式 |
|------|---------|
| token 无效 | 提示用户检查 Webhook 地址 |
| 签名错误 | 提示用户检查加签密钥 |

🎉 恭喜！ 如果你跟到了这里，你已经掌握了创建 Skill 的核心知识。接下来我们来看看如何让你的 Skill 写得更好。

一个 Skill 从诞生到被广泛使用，需要经历完整的生命周期：发布、更新、安装。

✏️ 编写  →  🧪 测试  →  📤 发布  →  📥 安装  →  🔄 更新  →  📊 反馈迭代

为什么选择 Aone 平台发布 Skill

• 🔗 打通 Code 平台、关联 Git 仓库，开发体验友好：创建 Skill 时自动生成对应的 Git 仓库，本地 push 即可触发发布，告别"压 zip → 上传 → 替换"的繁琐流程，写代码与发版无缝衔接。

• 🏷️ 自动版本管理，无需手动维护版本号：平台基于 Git commit 自动生成版本信息，不用自己在 Skill 文档里手动改号。

Aone 平台的 Skill 发布分为 2 种方式：git 仓库发布、zip 发布。

推荐使用 git 仓库发布，方便做后续的版本管理。Aone 创建 Skill 时会自动生成对应的 git 仓库，你只需将你本地待发布的 Skill 代码 push 到该仓库。

💡特别注意！！！

Aone Skill 的 git 仓库默认的主分支（发布分支）是main分支而不是master。

git 仓库上传后，回到 Aone 的 Skill 页面，点击发布，审核通过后即发布成功，在你项目目录下自动生成 package.json 文件做版本控制。

重复上述发布流程即可。

一个正常的教程应该到这就结束，我们仿佛已经学完了完整的 Skill 发布、管理流程，但我们明显不正常，一切才刚刚开始...

坦诚地说，Skill 生态还在早期阶段，你在后续的迭代过程中可能会遇到一系列的疑惑和痛点。

不同平台对 Skill 的解析行为有差异。只要严格按name + description + 正文的标准结构写，至少 80% 的内容天然可移植，问题出在那 20% 的"平台增量语法"。

三种常见的"污染"

badcase：

应对：三纯净 + 注释隔离 + 三检测

写作期：「三纯净」原则

1.正文纯文本：不写任何平台特定的 @、/、!触发符。必须提及就用引号当例子讲，而不是当指令用。

2.工具用能力描述：写「调用 shell 命令执行 xxx」而非「调用 Bash工具」，让平台自己映射。

3.路径不写死：用相对路径或 ~/<workspace>/占位。

隔离期：用 HTML 注释隔离平台增量

<!-- platform: accio-work -->
当任务需要团队协作时，使用 `@团队成员` 触发分配。
<!-- /platform -->
<!-- platform: aone-copilot -->
当任务需要工单流转时，使用 `/ticket assign` 命令。
<!-- /platform -->
<!-- platform: default -->
当任务需要分配时，输出"建议指派给：<候选人>"，由用户手动操作。
<!-- /platform -->

支持的平台按需渲染，不支持的平台 LLM 通常会忽略注释。

发布期：「三检测」清单

兜底原则：确定性逻辑下沉到scripts/

把"必须确定执行"的逻辑放进 scripts/*.py——Python 脚本天然跨平台，只要平台支持 shell 就能跑，避免靠 LLM 在不同平台"复述"指令。这是 Anthropic Skill spec 反复强调的 determinism through code 原则。

Anthropic 已于 2025-12 把 SKILL.md 格式开源为 Agent Skills v0.1[5] 标准，目前 16+ 平台已对齐（Claude Code、Cursor、Codex、Gemini CLI、Copilot、Aone Skills、Accio Work 等）。优先遵循该标准，是降低跨平台成本的最佳起点。

Skill 生态目前没有 npm/pip 那样的成熟包管理，发布与分发链路上有两个突出问题。

问题一：发布严肃性不足

写一个 SKILL.md push 一下就发版了，没有 CR、灰度、SPE 评审、自动化测试。在阿里内部应用发布场景这些都是默认配置，但 Skill 长期处于"个人项目"状态——一个错别字、一个被污染的指令，可能直接打到全公司用户。

核心观念转变：把 Skill 当"代码包"而不是"文档"。Skill 一旦被加载就拥有类工具的执行能力，理应享受与代码同等的发布严肃度。

问题二：已安装用户无法自动感知更新

Skill 更新后，已装用户不会自动收到推送。同一个 Skill 在生态里长期存在多个"僵尸版本"，bug 修了但用户用的还是旧版。

社区正在推进 Skill Package Manifest RFC[10]，目标对齐 npm 的 "manifest + lockfile + registry" 模型，预计 2026 年内更多平台会原生支持。

创建 Skill 很快，但调试与迭代很慢。常见反模式：改一行 SKILL.md → 跟 Agent 说"重新加载" → Agent 没加载到 → 手动重启会话 → 复测一次……一个小修改 5–10 分钟。**真正的瓶颈不在写，在"改完之后让 Agent 看到改完的版本"**。

社区已把这归纳为 Skill local-dev-loop 问题，2025 H2 起出现了一批方案。

跑通这套环，单次迭代从 5–10 分钟压到 30 秒以内——Reddit 上 Claude Code 2.1 用户报告的 "24x faster iteration" 就是这么来的。

进阶：让 Skill 自我进化

前面 5 项解决的是"人快速迭代 Skill"。2026 年业内出现了更激进的方向——让 Skill 自己迭代自己：每次执行记录成功/失败信号，用反思机制提炼"经验补丁"，再回写到 SKILL.md。

4 步反馈闭环

执行 Skill → Binary Eval 自动打分 → 失败时 Reflection Agent 提炼修复 patch → 通过 eval 复测 → 自动 git commit

业内代表性方案

穷人版落地（不需要复杂基建）

1.SKILL.md 末尾加元指令：

## 自我进化机制
每次执行完本 Skill 后：
1. 评估输出是否达成目标（pass / fail）
2. fail 时反思失败原因，在 diary/YYYY-MM-DD.md 追加「失败案例 + 修复建议」
3. 某条修复建议在最近 3 次执行中被反复提及时，提炼为正式规则，提交 PR 修改本 SKILL.md

2.配 scripts/log-execution.py：每次触发自动记录 prompt + 输出 + 用户反馈到 JSONL。

3.用 skill-creator eval 做兜底：自我修改后必须通过既有回归用例才能 commit，避免自我退化。

⚠️ 风险：没有 eval 兜底的自我修改 = 慢性自杀——Agent 可能为通过单个 case 而引入与其他场景冲突的规则，越改越烂。务必配套 binary eval + 版本快照 + 关键节点人工 review。

Anthropic 已在 Claude Code 2.x roadmap[20] 中暗示原生支持 skill auto-evolution，预计 2026 H2 落地。在那之前，"元指令 + binary eval + git 兜底"是最稳过渡方案。

讲了这么多，到目前为止我们的文章还是限定在原有的人类思维中，即学习工具然后使用工具。然后扪心自问，AI时代技术井喷式发展，你真的能学得过来，也许你学会了上述的所有内容，可是明天可能还没等你去实践，技术已经更新换代。

所以回到我们开头聊的，我们应该把我们的价值放到体验（Experience）和判断（Judgment），无论你是大神还是小白，关于目前的 Skill 技术，你应该需要更好的使用体验，只需做出自己宝贵的判断。因此，以上关于 Skill 的内容，一个 SKill 就可以搞定：skill-dev-aio：一站式Skill开发助手

功能一演示：快速创建Skll

功能二演示：一键发

功能三演示：优跑分

功能四演示：检查询

功能五演示：跨平台迁移

功能六演示：批更新

相关链接：

[1] https://www.skills.sh/

[2]https://clawhub.ai/skills

[3]https://skillsmp.com/

[4]https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

[5]https://agentskills.io/

[6]https://jfrog.com/blog/agent-skills-new-ai-packages/

[7]https://github.com/anthropics/claude-code

[8]https://code.claude.com/docs/en/plugin-marketplaces

[9]https://code.claude.com/docs/en/plugin-marketplaces

[10]https://github.com/agentskills/agentskills/discussions/210

[11]https://paddo.dev/blog/claude-code-21-pain-points-addressed

[12]https://github.com/luongnv89/asm

[13]https://tessl.io/registry/skills/github/jeremylongshore/claude-code-plugins-plus-skills/exa-local-dev-loop

[14]https://medium.com/@reliabledataengineering/claude-skills-2-0-the-self-improving-ai-capabilities-that-actually-work-dc3525eb391b

[15]https://www.mindstudio.ai/blog/self-improving-ai-skills-binary-evals-claude-code/

[16]https://github.com/Shmayro/singularity-claude

[17]https://www.cognee.ai/blog/deep-dives/building-self-improving-skills-for-agents

[18]https://www.linkedin.com/posts/lawrencewu920_day-3-of-my-claude-code-daily-tips-series-activity-7427735749086752768-ASH5

[19]https://arxiv.org/html/2512.17102v2F

[20]https://github.com/anthropics/claude-code/issues/15858

跳转微信打开

书接上回，我在之前的一篇文章中深入分析了 OpenClaw 及其背后的 Harness Engineering 实践，同时构想了一套 “Harness Framework” 来讲解如何将这套理念应用到企业级智能体开发中。

好消息是，AgentScope Java 1.1.0 版本正式发布了，在这个里程碑版本中，我们完整的实现了这套 “Harness Framework” 规划。开发者可以基于 1.1 版本快速实践 Harness，开发面向个人提效的 XxxClaw、Coding Agent 等本地应用，也可以开发面向分布式场景的 DataAgent、SRE Agent 等企业级应用。

AgentScope Java 1.1.0 在这个版本中交付了四项核心能力：

• 工作区驱动的 Agent 运行环境：Agent 的人格、知识、技能、记忆、子 Agent 规格统一沉淀在一个结构化工作区里，每次运行自动从工作区加载上下文、结束后自动回写记忆，Agent 的能力随时间持续演化。

• 可插拔的抽象文件系统：工作区的物理存储可以自由切换——本机磁盘、远端共享存储、隔离沙箱均通过同一套接口操作，同一份 Agent 逻辑无需修改即可适配个人开发环境与企业分布式部署。

• 开箱即用的上下文管理：内置对话压缩、双层记忆沉淀与全文检索，解决长对话上下文膨胀和跨会话记忆丢失两个顽固问题，并通过后台维护机制保证记忆库不随时间失控增长。

• 子 Agent 编排与隔离执行：支持声明式定义子 Agent、同步或异步委派子任务；工具执行可配置在隔离沙箱内完成，并在多轮对话间保持沙箱状态可恢复，兼顾多租户场景的会话与用户维度隔离。

过去一年，OpenClaw、Hermes、Claude Code 等智能体产品掀起了一波热潮，也带火了这些产品背后的 Harness Engineering 理念——用结构化的工作区、上下文管理与工具约定，替代"每次对话各自为战"的原始使用方式。越来越多的团队开始把这套思路搬进自己的 Agent 开发中。

然而，真正动手落地的人往往会发现，这条路走到"企业级"就开始卡壳。我们梳理了来自一线开发者最常提到的五个障碍：

1. 多用户、多副本，工作区怎么办？OpenClaw 用一个本地目录做工作区，单机单用户完全没问题。但服务要对外，多个用户的工作空间要隔离，Agent 水平扩容到多台机器后，同一用户的工作区又要在副本间共享——本地目录这套假设直接崩掉了。

2. Tool 和 Skill Script 不能在宿主机上跑，怎么隔离执行？Agent 调用 Shell 或运行用户提供的代码，放在本地可信开发机上无所谓，一旦上服务，把任意用户输入的命令直接在宿主机上执行就是安全漏洞。沙箱是必须的，但"有沙箱"只是第一步：沙箱里的 Tool 还需要看到完整的上下文，多轮对话中同一个沙箱实例要可恢复，而不是每次都从零开始。

3. "workspace + 文件系统"的组合如何搬到分布式环境？文件系统驱动的工作区是 Harness Engineering 里最直觉、也最有效的模式，但这套模式的前提是"文件系统"。分布式场景下没有统一的本地磁盘，远端存储、KV 服务、对象存储各有各的接口，重写一遍等于把 Agent 逻辑和基础设施耦合死了。

4. Multi-Agent 怎么做才对？子任务分发、上下文隔离、异步执行、结果回收、超时取消——每一项单独做都不难，但要拼成一个可管理的编排层，代码复杂度会快速上升，而且大多数框架只提供原语，工程上的"怎么声明子 Agent、什么时候 spawn、怎么管理状态"全靠自己摸索。

5. 上下文压缩和分层记忆有没有开箱即用的实现？Harness Engineering 把这两件事讲得很清楚，但真正做起来要处理的细节非常多：压缩时机、压缩策略、压缩前的事实提取、历史的可检索性、跨进程重启后的恢复……大多数框架只给了 short/long memory 的抽象接口，具体实现还是要自己来。

这五个问题的根源是同一件事：个人助手型 Agent 和企业级 Agent 是两种不同的工程形态，用同一套假设去应对两种场景必然碰壁。

从部署形态看：个人助手是单用户单进程，所有状态都可以放在一台机器上；企业级 Agent 要水平扩容、要多租户、要服务不中断，状态必须能分布式存储和恢复。从安全边界看：本机工具执行没有风险，生产环境上任意 Shell 执行则是一个严重的攻击面，沙箱和权限边界不是"可选的优化"而是"上线的前提"。从运维可观测性看：个人工具出了问题自己看日志就行，企业服务要求记忆落盘、会话可审计、状态变更可追踪。从Token 经济看：个人用户对延迟和费用不敏感，企业场景每一次无效的上下文重推都是真实的成本开销。

那么，有没有一款框架能让你"写一套逻辑，按需切换形态"？AgentScope Java 1.1.0 的 Harness 模块（入口类HarnessAgent）就是围绕这个目标设计的：它不替换ReActAgent的推理循环，而是在循环的关键时机插入 Hook，补齐一组工具与工作区约定，把上面五个问题的工程答案打包进来，让你专注于 Agent 的业务逻辑，而不是基础设施。

AgentScope Java Harness 的设计哲学可以用一句话概括：把"下一轮怎么办、下一天怎么办、上下文爆了怎么办、状态丢了怎么办"的工程答案打包进来，而不是让每个 Agent 项目各自发明一遍。

具体到实现层面，有两个核心支柱支撑起整个框架。

Harness 为每个 Agent 引入了workspace 工作空间的概念——一个结构化目录，用于承载 Agent 运行所需的一切持久化内容：人格定义（AGENTS.md）、长期记忆（MEMORY.md）、领域知识（knowledge/）、可复用技能（skills/）、子 Agent 规格（subagents/）以及会话历史（agents/<agentId>/）。

这并不是一个新想法——OpenClaw、Hermes 在实践中都发现，让 Agent 有一个稳定的"工作台"比每次重新初始化有效得多。Harness 把这个直觉系统化了：工作区是 Agent 的唯一事实来源（Source of Truth），所有状态的读写都围绕工作区展开，而不是散落在代码、数据库和内存的各个角落。

实际运行中，每次推理开始前，WorkspaceContextHook会把AGENTS.md、MEMORY.md、knowledge/等关键文件自动注入到 system prompt 里，确保 Agent 的人格和知识在每一轮都完整呈现。Agent 运行结束后，MemoryFlushHook会提炼本次对话的新事实写入记忆文件，后台的MemoryConsolidator再周期性地把流水账合并成精炼的长期记忆。工作区在对话中持续演化，每一次运行都比上一次"更了解"用户和任务。

工作区的理念很美好，但有一个现实约束：本地磁盘目录在分布式场景下行不通。多个 Pod 各有一块本地磁盘，MEMORY.md写到哪里？哪个副本的版本才是"真"的？

AgentScope Java Harness 用AbstractFilesystem抽象层来解决这个问题。对上层而言，Agent 只需要调用统一的read/write/ls/grep等接口，不关心"文件"实际落在哪；对下层而言，可以适配到本机磁盘、远端对象存储（OSS）、KV 数据库（Redis）、沙箱文件系统等任意介质，甚至通过CompositeFilesystem把不同路径路由到不同后端。

如上图所示，基于 AbstractFilesystem 接口，AgentScope Java 内置提供了三种拓展实现，对应三种使用模式。

待详细展开三种实现与模式。

在 AgentScope Java 1.1 版本中，workspace 是 agent 的核心抽象，我们 AbstractFilesystem 作为 workspace 的物理实现载体，所有文件操作、命令执行、记忆管理工具都以 AbstractFilesystem 为标准操作入口。

基于这一层文件系统抽象，AgentScope Java 框架直接为智能体开发带来了三大工程能力：

安全与隔离

• Shell/Code/Skill 的执行通过沙箱后端隔离，用户输入驱动的命令不再直接在宿主机上运行；

• 工作区本身也可以运行在沙箱内，实现文件读写层面的隔离；

• 工具的注册与暴露由框架统一管理，execute工具仅在后端实现了沙箱接口时才出现；

分布式部署

• Agent 可以多副本对等部署，MEMORY.md、会话日志等关键文件通过 Remote 后端路由到共享存储，天然实现跨节点同步；

• 通过IsolationScope（SESSION / USER / AGENT / GLOBAL）与RuntimeContext组合，在代码不变的前提下实现 session 级隔离、用户级共享等多种租户策略；

Subagent 与异步任务

• 子 Agent 的工作区、文件系统、会话状态都从父 Agent 继承或独立配置，编排策略由规格声明，不需要手工拼装；

• 异步任务的状态机（PENDING/RUNNING/COMPLETED/FAILED/CANCELLED）与结果回收机制开箱即用，支持替换为跨进程实现；

下面三个场景覆盖了从个人到企业的典型开发形态。它们并不是非此即彼的选项，而是代表了三条不同的复杂度路径——你可以从最简单的一条开始，随着需求演化逐步迁移。

这类场景的特点：单用户、本机运行、需要操作本地文件或执行脚本，典型产品是个人助理、笔记机器人、本地 Coding Agent。

这类场景的核心诉求是"让 Agent 真正了解我、记住我"，而不只是一个无状态的问答机器。Harness 在这里的价值是：工作区里的AGENTS.md定义了 Agent 的人格和行为偏好，对话结束后会自动提炼新的事实写入记忆，下次打开时 Agent 依然认识你、记得上次的进度。技能（skills）和领域知识也都住在工作区里，随时可以编辑调整，不需要动代码。

本机部署下还可以开放 Shell 执行能力，让 Agent 直接运行脚本、操作文件系统，这也是 OpenClaw 类产品最有吸引力的地方。而 Harness 在此之上补上了"持续演化"的那一层：工作区就像 Agent 的大脑，随着每次对话变得更有经验。

AgentScope Java Harness 在此场景提供的核心能力：

• 持续记忆：对话结束后自动将新事实提炼写入工作区，下次启动无需重新"告知"Agent 背景，长期记忆随使用积累。

• 本地 Shell 执行：在本机可信环境下，Agent 可直接运行脚本、操作文件，复现 OpenClaw 类产品的核心体验。

• 工作区即配置：修改AGENTS.md调整人格，在skills/目录里新增技能，改一个文件等于升级一次 Agent，不需要重新编译部署。

• 会话跨进程恢复：关闭再打开，只要 sessionId 不变，上次对话的状态全部还原，不是从零开始。

这类场景的特点：服务多个用户、需要执行 SQL / Python / Shell、任务耗时较长、输入来自不可信的外部用户，同时要求多轮对话状态可恢复、多副本部署时用户体验一致。

这类场景最大的风险是执行安全——用户驱动的代码不能在服务器上无限制地跑。Harness 的沙箱机制把 Agent 的文件操作和命令执行都限定在隔离环境里，服务器进程本身不受影响。更关键的是，沙箱不是"用完即毁"的，每轮对话结束后沙箱的状态会被持久化，下一轮拿回来继续，用户不会因为服务重启或切换节点就丢失工作进度。

多副本部署时，用户的长期记忆（Agent 对这个用户积累的了解）可以存放在共享存储里，无论请求落到哪个节点，Agent 看到的都是同一份记忆。长分析任务可以拆成多个子 Agent 并行执行，主 Agent 只负责协调和汇总，不必一直阻塞等待。

AgentScope Java Harness 在此场景提供的核心能力：

• 隔离沙箱执行：所有代码与命令在隔离环境内运行，宿主服务进程不受用户输入影响，安全边界清晰。

• 多轮沙箱状态恢复：每轮对话结束后自动保存沙箱状态，下轮或下次服务启动时原位恢复，用户的工作现场不丢失。

• 分布式记忆共享：用户的长期记忆存放在共享存储，多节点部署下所有副本读到同一份"对这个用户的了解"，体验一致。

• 子 Agent 并行编排：长任务可拆解为多个子 Agent 并发执行，主 Agent 只做协调，整体效率更高，也更易管理超时与失败。

• 多租户隔离：按会话或用户维度隔离工作区与执行环境，多用户同时在线互不干扰。

这类场景的特点：主要通过调用业务 API 完成任务（下单、查询、审批等），不需要在服务器上执行 Shell，但需要多实例运行、会话状态可持久、跨用户的知识共享。

这类场景的核心诉求是稳定与安全——在线服务不能因为 Agent 调用了一个不该调用的 Shell 命令而出事。Harness 在这里的价值是：不配置沙箱执行能力时，框架默认就不会暴露 Shell 工具，Agent 只能通过明确定义的业务工具与外部交互，安全边界由配置决定，而不是靠开发者自律。

会话状态和记忆可以落到远端存储，多个服务实例共享同一套用户记忆，用户换一个入口重新对话，Agent 仍然能接续上次的上下文。需要并行处理多个子任务时（比如同时查库存、计算优惠、生成摘要），子 Agent 机制同样适用，可以对接外部任务队列实现跨进程的任务管理。

AgentScope Java Harness 在此场景提供的核心能力：

• 默认安全边界：不开启沙箱执行时框架不暴露 Shell 工具，Agent 只能通过你明确注册的业务工具与外部交互，安全策略由配置决定。

• 多实例共享记忆：会话状态与用户记忆落到远端存储，任意服务实例都能读到同一份上下文，用户无感知地在多实例间切换。

• 会话跨请求连续：每次请求携带相同的用户标识，Agent 自动恢复上次的对话状态，实现真正的多轮连续对话体验。

• 并行子任务支持：需要同时处理多个业务步骤时，可将子任务委派给子 Agent 并行执行，结果汇总后统一回复，不影响主流程响应速度。

本节将从使用者视角讲清楚 AgentScope Java Harness 的核心能力：它是什么、怎么工作、配置时应该怎么想。

上手 Harness 只需三步：引入依赖、准备工作区、构建并调用 Agent。

1. 引入依赖

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>${agentscope.version}</version>
</dependency>

2. 准备工作区

在磁盘上选一个目录作为workspace，并在其中创建AGENTS.md。这不是"可选的初始化步骤"，而是 Harness 的核心入口——Agent 的人格、记忆、技能、子 Agent 规格全部围绕这个目录展开。AGENTS.md内容简单写几行约定就够，后续随使用不断演化。

3. 构建HarnessAgent并调用

HarnessAgent agent = HarnessAgent.builder()
    .name("my-agent")
    .model(model)
    .workspace(Paths.get(".agentscope/workspace"))
    .compaction(CompactionConfig.builder()     // 建议一开始就配，避免线上 context overflow
        .triggerMessages(50)
        .keepMessages(20)
        .build())
    .build();
RuntimeContext ctx = RuntimeContext.builder()
    .sessionId("user-session-001")   // 相同 sessionId 的多次 call 自动续接上下文
    .userId("alice")                 // 多用户场景必传，用于命名空间隔离
    .build();
Msg reply = agent.call(userMessage, ctx).block();

运行后检查工作区目录：AGENTS.md、memory/、agents/<agentId>/三个路径都应该存在，这说明 Agent 已经在正常写入记忆和持久化会话状态了。

完整可运行示例见agentscope-examples/harness-example中的QuickstartExample。

理解下面六个概念，基本就掌握了 Harness 的运行逻辑。

总纲：HarnessAgent负责编排，workspace负责沉淀，filesystem负责落点，RuntimeContext负责身份，sandbox负责边界，memory负责长期演化。

工作区（Workspace）：Agent 的唯一事实来源

工作区是 Harness 区别于普通 Agent 框架最重要的设计。它不是一个临时存储目录，而是 Agent 的"大脑外化"——所有需要跨会话保留的内容都住在这里。

工作区的标准目录结构如下：

workspace/
├── AGENTS.md              ← Agent 人格与行为约定，每次推理前自动注入 system prompt
├── MEMORY.md              ← 精炼的长期记忆，由后台自动维护，随使用积累
├── knowledge/             ← 领域知识，随 AGENTS.md 一起注入
├── skills/                ← 可复用技能，自动装配到 Agent 的工具集
├── subagents/             ← 子 Agent 规格声明，自动被发现和加载
└── agents/<agentId>/
    ├── context/           ← 会话状态快照（进程重启后恢复用）
    ├── sessions/          ← 对话 JSONL 与压缩上下文，供审计与检索
    └── memory/            ← 每日记忆流水账

工作区在每次推理中如何工作：推理开始前，Harness 把AGENTS.md、MEMORY.md、knowledge/等关键文件拼入 system prompt；推理结束后，把本次对话中出现的新事实提炼出来追加到当日的记忆流水账。工作区随每次对话持续演化，Agent 随时间变得"更了解"它面对的业务和用户。

为什么工作区优于把 prompt 写死在代码里：人格、知识、技能和子 Agent 规格都在工作区的文件里，调整行为只需要改文件，不需要重新编译和部署。对于有复杂业务知识的 Agent，这一点尤其关键——业务规则随时在变，更新应该轻量。

会话持久化（Session）：跨请求、跨进程的状态连续

Harness 把会话状态落盘分成两条并行的路径，它们各自解决不同的问题：

• 状态快照（context/）：每次call()结束后，Agent 的运行状态（当前的对话记忆、工具执行上下文等）序列化为 JSON 文件，存到工作区的agents/<agentId>/context/sessionId/下。下次用相同sessionId发起调用时，框架在推理开始前自动加载这份快照，恢复到上次结束的位置。这是"关掉再打开仍然记得上次"的技术保障。

• 对话日志（sessions/）：完整的对话历史以 JSONL 格式追加写入<sessionId>.log.jsonl，这个文件永远不会被压缩，供审计和session_search工具使用。另有一份<sessionId>.jsonl存放压缩后的 LLM 上下文，是模型实际"看到"的版本。

两条路径都由框架自动维护，开发者唯一需要做的是每次调用时稳定传入相同的sessionId。

记忆管理（Memory）：从对话到长期知识的自动沉淀

这是 Harness 最有工程价值的能力之一。很多 Agent 框架的"记忆"本质是把历史消息堆进上下文，迟早会撑爆；AgentScope Java 当前版本的做法是双层分离：

第一层——每日流水账：每次对话结束后，框架用 LLM 从当次对话中提炼"新增事实"，以 bullet point 形式追加到当日的记忆文件（memory/YYYY-MM-DD.md）。这一层只追加、不修改，保证任何新事实都不会丢失。

第二层——长期记忆：后台有一个调度器，会周期性地读取近期的日流水账文件，用 LLM 把它们与现有的MEMORY.md合并、去重、精炼，输出一份在 Token 预算内的"可注入版"写回MEMORY.md。这一层是被每轮推理注入到 system prompt 的"事实摘要"，质量高、体积受控。

两层之间的关系：第一层保证不丢，第二层保证可用。新事实先落在流水账，等积累够了由后台搬进长期记忆，推理时模型优先看长期记忆，找不到时用memory_search工具做全文检索（基于 SQLite FTS5）。

对话压缩是记忆管理的另一面：当对话消息数或 Token 数超过阈值，Harness 用 LLM 把之前的对话压缩成一段摘要，保留最近的若干条消息，其余的卸载到 JSONL 文件。压缩会在提炼长期记忆之后进行，确保有价值的信息先沉淀再压缩。如果模型返回了 context overflow 错误，框架还会捕获异常、强制压缩、自动重试，整个过程对调用方透明。

配置建议：

.compaction(CompactionConfig.builder()
    .triggerMessages(50)    // 消息数超过 50 触发压缩
    .keepMessages(20)       // 保留最近 20 条
    .flushBeforeCompact(true) // 压缩前先提炼记忆（默认已开启）
    .build())

子 Agent 编排（Subagent）：复杂任务的分解与委派

当主 Agent 遇到耗时长、上下文重或可并行的子任务时，可以把它委派给子 Agent 执行。子 Agent 是独立的 Agent 实例，有自己的 system prompt 和 Memory，不共享主 Agent 的对话历史，执行结果作为一条工具结果返回给主 Agent。

子 Agent 的声明方式有四种，灵活度从低到高：

1. 内置的general-purposeAgent：镜像主 Agent 的配置，适合临时委派任意子任务；

2. 工作区文件驱动：在workspace/subagents/下放 Markdown 文件（YAML front matter 定义名称、描述、工具；body 是 system prompt），框架自动发现并加载；

3. 代码声明：用builder.subagent(spec)编程式指定；

4. 自定义工厂：完全控制子 Agent 的构建逻辑。

工作区驱动的方式是最推荐的——子 Agent 的定义随工作区版本化，不需要动代码就能调整委派策略。

调用方式分同步和异步两种：

• 同步调用：主 Agent 阻塞等待子 Agent 完成再继续，适合必须拿到结果才能下一步的场景；

• 异步调用：主 Agent 提交任务后立即拿到一个任务 ID，可以继续做其他事，后续用task_output工具轮询结果。对于耗时超过几秒的任务，强烈建议用异步，避免主 Agent 白白阻塞消耗时间与 Token。

防无限递归：子 Agent 默认是"叶子"形态，本身不能再 spawn 子 Agent，框架也有最大深度限制作为兜底。

内置工具（Builtin Tools）

HarnessAgent构建时会自动注册一套覆盖"闭环所需"的工具，无需手动配置：

值得注意的是：在"远端共享存储"模式下，框架默认不注册Shell 工具——这是一个有意的安全设计，不是遗漏。如果你的业务 Agent 不需要执行命令，用这个模式可以消除一整类执行安全风险。

文件系统（Filesystem）：三种模式，按需选型

文件系统是 Harness 连通"Agent 逻辑"与"基础设施"的关键一层。框架提供三种声明式模式，选型时从业务约束出发：

模式一：本机 + Shell（默认）

不配置filesystem或显式写filesystem(new LocalFilesystemSpec())，工作区就是本机上的一个目录，可以执行 Shell 命令。适合个人本机应用和开发测试环境，最简单，没有任何额外依赖。

模式二：远端共享存储

配置filesystem(new RemoteFilesystemSpec(store))，记忆、会话日志等关键数据路由到远端 KV（如 Redis），本地文件系统只存放不需要共享的内容。默认不注册 Shell 工具，适合多副本在线服务、需要跨节点共享用户记忆但不需要代码执行的场景。

模式三：沙箱执行

配置filesystem(sandboxSpec)，文件读写和命令执行全部在隔离的沙箱环境里完成，宿主进程不受影响。适合需要执行不可信代码的场景，如 DataAgent、Coding Agent。

三种模式的核心区别在于：谁来执行命令、数据落在哪、隔离粒度是多少。同一套 Agent 代码逻辑，切换filesystem配置就能在三种模式间迁移。

沙箱（Sandbox）：隔离执行 + 状态可恢复

沙箱模式解决的不只是"隔离执行"，更是"多轮对话中隔离环境的连续性"——这两点合在一起才真正有价值。

执行边界：在沙箱模式下，Agent 调用的 Shell 命令、文件读写都发生在沙箱侧，宿主进程只起协调作用。用户输入的任意命令不会直接影响服务器。

状态可恢复：每次call()结束，沙箱当前的文件系统状态会被持久化（快照机制）。下次调用开始时，框架按sessionId或userId找到对应的快照，把沙箱恢复到上次结束的位置。用户不会因为服务重启或请求漂移到其他节点而丢失工作进度。

工作区投影：AGENTS.md、skills/、subagents/、knowledge/等宿主工作区内容，在每次call()开始时会被同步到沙箱内，保证沙箱里的 Agent 能看到完整的配置和技能定义。

隔离粒度（按需选择）：

• 会话级：每个会话有独立的沙箱状态，互不干扰，适合多用户 SaaS；

• 用户级：同一用户的多个会话共享同一沙箱状态，适合"用户长期工作台"类场景；

• 全局共享：整个 Agent 共用一个沙箱，适合工具型、只读型 Agent。

真正应用于生产环境中的 Sandbox 沙箱，还有更多要考虑的因素，可以参考官网文档了解更多：

• 沙箱生命周期如何管理：agent 内置管理、用户自行管理；

• 哪些流程需要运行在沙箱中：Tool In Sandbox、Subagent in Sandbox；

• 沙箱内部状态如何管理：state、snapshot 恢复；

Skills：工作区驱动的可复用技能

Skills 是把"可复用的操作流程"结构化的方式。在工作区的skills/<skill-name>/目录下放一个SKILL.md，框架启动时自动发现并装配进 Agent 的能力库。Agent 在推理时可以调用这些技能，技能本身描述了"做这件事的步骤和规范"。

这种设计的工程价值在于：技能是文件，可以和代码一起进 Git 版本控制、可以 Code Review、可以在不重新部署的情况下更新。当团队有大量 SOP 和操作规范需要注入 Agent 时，这比把所有内容堆进 system prompt 要清晰得多。

在沙箱模式下，技能文件会随工作区投影同步到沙箱内，技能中涉及的命令在隔离环境执行，不会影响宿主。

AgentScope Java 1.1 把 Harness Engineering 里大家最想要、却最难自己拼装的一组能力，收敛成了HarnessAgent+ 工作区约定 + 可插拔文件系统 + Hook 管线：个人场景下，它是“带记忆、带压缩、带子任务”的加强版 ReAct Agent；企业场景下，它是能把隔离、多租户、分布式记忆与子 Agent 编排变成配置项的基础设施。

若你正在评估从个人助手原型演进到可上线的企业智能体，建议从 Harness 概览[1]的快速开始跑通，再按 Filesystem[2] 选择一种声明式模式，然后按需打开压缩、沙箱与子 Agent——每一步都有对应文档与示例模块可对照，而不必从零发明一套“工作区即真理”的运行时。

参考链接：

[1]https://github.com/agentscope-ai/agentscope-java/blob/main/docs/zh/harness/overview.md

[2]https://github.com/agentscope-ai/agentscope-java/blob/main/docs/zh/harness/filesystem.md

[3]官网文档：https://java.agentscope.io

欢迎扫码加入微信群，参与更多关于 AgentScope Java 的技术探讨

或搜索钉钉群号：160170030796

跳转微信打开

最近深度体验了一把从产品设计、UI/UX，到前后端开发，再到核心算法落地的全流程闭环。目前终于成功把流程 Run 起来，虽然在高并发处理和算法精度上还有不少待优化点，但这次实践让我对系统架构的全局把控有了更立体的认知。

先说出发点为什么要做这样一个事情，目前做一个skill的方式主要有两种，一种是人工编写skill，一种是在openclaw，Claudcode上通过对话不断交互生成skill，先说这两种方式可能会有什么问题，模式一人工编写受限于个人经验与精力，存在效率比较低，质量波动大，测试覆盖不足等瓶颈，并且可能对于团队来说容易在原子通用逻辑上重复造轮子；模式二虽提升了编码速度，但本质仍是非确定性的探索过程，缺乏自动化验证闭环与工程化约束，且一次只能生成一版，需要多轮交互才能生成一个较为稳定版本。因此面向Harness设计的技能工厂的想法就油然而生了。

技能定义

首先用户可以输入自己想生成的技能，测试问题，和API接口，（后面也会支持挂载sop文档，之前做过像维修类场景会有一些标准化流程类操作，可行性上来说搭配对应的接口api是可以直接转化成skill的）。

基线诊断

首先判断是否有必要生成，是否直接用大模型就可以回答问题了又或者直接复用现有的skill就可以回答问题，为了回答这两个问题，构建了两个评估模块

• 裸模型评估：直接让模型执行目标任务，作为基线对照。

• skill匹配分析：召回相似skill，执行用户输入的测试问题，评估现有技能是否满足用户需求

如果不能解决或者不匹配这些失败点和不确定行为，本质上就是 Skill 需要解决的真实能力缺口

测试构建

目前测试构建主要是对用户之前输入的测试问题进行复用。

多路并发skill生成

之前调研anthropic，openclaw都有skill-creator—专门用于生成技能的skill，最近又看到一个专门为 Claude、Cursor、Codex 等 AI 编程助手设计的结构化工作流框架superpowers，github上138k个star。里面也有专门写skill的writing-skills技能，试用了一下感觉比较快并且执行writing-skills生成的技能react的次数会变少。很难讲用基于哪一种基础的skill-creator写出来的skill的效果最好并且这个环节中可能存在一些不稳定因素，LLM执行生成本身具有一定随机性，因此通过并行调用 3 种不同策略（或不同模型/不同 Prompt 模板）的 Creator，相当于一次性买了三张不同号码的彩票。结果：只要其中一路生成了高质量代码，整个任务就算成功。这极大地提高了首次生成成功率 (First-Time Pass Rate)，避免了因单一路径失败而导致的反复重试和用户等待。

回归迭代

目前为了保证整个流程的效率只做了单轮的测试+优化。

• 测试阶段

用户可以选上一阶段的某个版本或者所有版本进行测试，从格式规范，复用创新，功能可用性，运行稳定性，文档规范几个维度进行评价打分，然后发现一些可以优化的地方，比如测试的生成的一个skill和其它skill有功能重复的地方就可能导致复用创新性偏低。

• 优化阶段

生成优化版本skill，可以下载或者发布。

质量检查

除了上面提到的测试驱动技能生成，还对知流平台进行了适配，可以基于知流上面的MCP，http，dify agent工具直接生产技能。

对背后分析迭代流程进行封装只呈现给用户结果和分析结论，允许用户一开始选择不同的分析生成模式。

基于trace的skill机会挖掘—>规模化生产+筛选

看了千问团队的一篇文章Distill Trajectory-Local Lessons into Transferable Agent Skills，Trace2Skill 的本质是将智能体的“隐性经验”（大量具体的执行轨迹）转化为“显性知识”（结构化的技能文档）。这种方法证明了，高质量的技能不需要依赖昂贵的人工编写，也不需要更新模型参数，仅通过开源的小模型）进行轨迹分析，就能提炼出通用的专家级能力。因此我们也有机会基于我们的一些日志数据沉淀出可固定的技能，感觉也有利于agent如何稳定执行长程任务

目前有一些节点的功能还是需要进一步优化完善的，比如像回归迭代，目前只是用测试-优化-测试这种流程进行回归，但是比如像SkillRL 也是把智能体与环境交互产生的冗长轨迹蒸馏成紧凑、可复用的"技能卡片"，并在强化学习训练过程中让技能库与策略共同进化。再比如在这个“回归”的过程中我们可以融入更多的信息，用户信息，历史数据等等进行优化，还有就是对不能实际执行的技能的回归，这种情况是否有必要模拟一个虚拟环境让agent进行测试回归。

在开发过程中主要用了以下产品帮忙设计和开发，idealab，Qoderwork，爱码仕，灵码aonecopilot等编程插件。

• idealab和Qoderwork帮忙基于自己的想法做了一些产品功能页面的详细设计；

• 爱码仕主要负责前端页面生成；

• 灵码aonecopilot等编程插件 主要帮忙debug或者一些优化，还有基于想法生成整体编码框架demo，自己补充修改细节；

参考

https://docs.trae.cn/ide/best-practice-for-how-to-write-a-good-skill#84407221

https://github.com/anthropics/skills

https://github.com/openclaw/openclaw/tree/main/skills/skill-creator

附录

跳转微信打开

不知不觉，本文已经是深度解析系列的第四篇了。上一篇解析文章《深度解析 Hermes Agent 如何实现“自进化”及其 Prompt / Context / Harness 的设计实践》在发布后，引发了许多同学的讨论和关注。大家关注的焦点非常集中，主要围绕在“自进化”这个概念，包括“Skill 的自动沉淀”以及“RL（强化学习）训练”这两个核心维度上。

其实，关于RL训练这一块，我在之前的文章里有提到，官方也明确说过，这更多是面向AI研究人员或者算法同学所设计的。如果你的目标是在某个特定领域的垂直任务，或者在特定的 Benchmark 上追求极致的性能效果，那么通过 RL 进行深度训练，确实是让模型突破瓶颈、获得更好效果的有效路径。但对于大多数工程落地场景而言，这种方式的门槛和成本都相对较高。因此，除了RL这条“重资产”路线外，另一种更轻量、更具普适性的方式，就是通过“Skill”的机制来实现 Agent 的自进化。

然而，仅仅是通过Skill自动更新来解决 Agent 的“自进化”，其实还是有点不够的，也有很多人反映真正在用 Hermes Agent 的时候，也没感觉到明显的变聪明，或者看到自动沉淀的比较好的 Skill。这是因为，自动沉淀 Skill 的机制很多时候还是取决于模型自己的判断和决策，这种判断和决策的触发时机和可控性相对就比较低了。因此，通过人给予Agent更多的“知识”来提升 Agent 的能力，甚至存放知识的这个“知识库”如果能“自动梳理”、“自动组织”、“自动更新”甚至“自动进化”，那就更好了，从而就能推动 Agent 的不断“自进化”。

所以，今天的这个深度解析文章就特殊一点，我不按照之前的结构去分析Prompt、Context、Harness这些维度了，我将会从 Knowledge Engineering（知识工程）的角度展开，但知识的效果也是影响Prompt、Context、Harness 非常重要的一部分，并且也是我们的主线话题“如何构建一个好的Agent”中非常重要但提及较少的一个部分。

前段时间，Andrej Karpathy（OpenAI联合创始人）开源了一个名为“LLM-Wiki”的项目[1]，核心其是就一个 Markdown文件，目标是指导大模型Agent进行知识的更新与结构化，整个过程如下图所示[2]。这个项目的本质，其实是解决了一个长期困扰我们的痛点：如何让 Agent 自动将非结构化的资料转化为 “AI能理解”、“有结构”的知识库。另外，今天还会介绍一个项目叫做“Gbrain”[3]，它是由 Y Combinator 总裁兼 CEO Garry Tan 构建的，一个思想和 LLM-Wiki 类似但更工程化一点的知识库项目。

这背后折射出的，是人类在知识管理上的天然短板。人类其实非常擅长“无脑堆积”知识——看到好的文章就收藏，遇到有用的文档就保存（此刻，可以打开看下你的网页收藏夹、各类APP的收藏夹，以及混乱的电脑桌面文件，是不是有很多已经“落灰”很久了，哈哈哈~）。这说明人类很不擅长“组织”知识。要把这些零散的信息梳理成体系化的结构，不仅耗时耗力，更因为缺乏统一的整理标准而变得很困难，容易拖延，拖着拖着就算了。无论是从个人层面看，收藏信息、文件是真的杂乱；还是从企业层面看，以我在阿里云售后做智能客服相关算法多年的经验，企业级知识库的维护成本更是非常之高，这主要体现在两个维度：

• 时效性与动态维护。知识是有生命周期的，它会随着产品迭代、业务变更而过时或失效。如何精准识别并剔除失效知识，同时无缝接入新知识，本身就是一个巨大的挑战。

• 组织结构的复杂性。知识该如何分类？以我们阿里云的服务领域来看，是按产品维度？问题场景维度？还是按关键词维度？比如，“镜像”主要集中在ECS、轻量应用服务器这些产品，而OpenClaw的相关知识就可能横跨多个产品线，简单的树状层级结构很难刻画这种复杂的网状关系。这种多维度的交叉关联，使得人工构建和维护一个完美的类似知识图谱之类的方案几乎成为不可能完成的任务。

而在 AI 时代，尤其是对于 Agent 而言，知识的质量直接决定了效果的上限。正如我在前文中说过的，Context 不仅仅包含当前的对话指令和历史记录，更核心的组成部分是外部注入的知识。这里的“知识”是一个广义的概念，它主要包含经验性知识，也就是完成特定任务所需的策略、步骤和隐性经验；事实性知识，比如领域内的客观信息、文档、FAQ 等静态数据。

以 AI Coding 场景为例，当我让 Agent 去写代码时，我期望它遵循的不仅仅是一个语法正确的结果，而是一套完整的“编码习惯”。比如：我喜欢用什么样的命名规范、注释风格？是应该先设计接口再实现细节，还是先跑通 Demo 再重构？优先使用哪些成熟的库或框架？写完代码后，是否自动进行单元测试或静态检查？

这些隐性的、带有个人色彩的经验法则，其实就是典型的经验性知识。在 Hermes Agent 或 OpenClaw 的体系中，我们将这类经验封装为 Skill。Skill 本质上是一种结构化的经验沉淀，它告诉 Agent “在这个特定场景下，应该按照什么步骤、用什么工具、遵循什么标准去行动”。

另一类事实性知识，就比较通俗易懂了。比如：某个概念、术语的定义是什么？某个报错原理背后的机制是怎样的？针对某类常见问题的最佳实践解决方案有哪些？甚至是网上最新的技术博客摘要。这些信息构成了 Agent 回答问题的基础素材。

如果说 Prompt Engineering 是在教模型“完成什么样的任务”，那么 Knowledge Engineering（知识工程）就是在教模型“应该知道什么”以及“如何运用已知信息”。Karpathy 的 LLM-Wiki 思路之所以具有突破性，是因为它突破了传统 RAG “每次查询从头检索”的局限。通过 Schema 文件指导 LLM 主动维护结构化的 Markdown Wiki，它将原始资料“编译”为带有交叉引用、矛盾标注的持久化知识体。

在这种设计下，知识不再是静态的死水，而是随着使用持续累积、增厚的活体，避免了重复推导带来的算力浪费。在这个新范式下，人类的角色发生了转变：我们只需专注于“提问题”和“堆知识”，而将繁琐的维护工作交给大模型。再配合上 Obsidian 这类知识维护的 IDE，Agent 就成为了那个不知疲倦的知识管理助手，可以自动完成知识的清洗、去重与结构化整合。

大家在使用各类 Agent 工具的过程中，尤其是在“养虾🦞”（OpenClaw）的时候，大家会深刻体会到这 Skill 的重要性。但是，这里存在一个明显的痛点：Skill 的编写是有门槛的。虽然市面上有很多教程教你怎么写出一个高效的 Prompt 或 Skill，但这依然需要开发者对业务逻辑有深刻的理解，并且要花费大量时间去调试和优化指令。对于普通用户而言，手动将隐性经验转化为显性的、机器可执行的 Skill，成本依然很高。

这正是 Hermes Agent 引入“自进化”机制的价值所在——它试图通过自动化生成的方式，降低这一门槛。Agent 不再仅仅被动地接收人类编写的 Skill，而是能够在交互过程中，自动从历史对话、成功/失败的案例中提取模式，自动生成或优化新的 Skill。这种从“人工编写 Skill”到“Agent 自动生成 Skill”的转变，才是实现真正意义上“知识自进化”的关键一步。这个自动化生成 Skill的过程呢，这种其实也是一种也是一种自动化沉淀知识的能力。

无论是Andrej Karpathy 的 LLM Wiki，还是Garry Tan 的 GBrain。这两个项目在某种程度上都对 “Skill” 这个概念进行了泛化。

传统意义上的 Skill，往往被固化为一个特定的 SKILL.md 文件或指令集，大模型读取它来掌握某项特定技能。但 LLM Wiki 和 GBrain 的核心创新在于：它们将 Skill 泛化为一种知识组织形态。 在这种范式下，Skill 不再局限于某种固定格式，它可以是任何 Markdown 文件、文档片段甚至是零散的笔记。关键在于，通过定义清晰的元数据（Metadata）或 Schema，描述清楚“在什么场景下应该调用哪些文件”，从而实现知识的渐进式披露（Progressive Disclosure）。

GBrain 的创始人 Garry Tan 甚至使用了一个词叫“Skillify”，也有的论文里使用的词是 “Skillfully”，whatever，这两个词都挺形象的，指的就是去写 Skill 或者像 Skill 一样去组织和加载知识。这种机制允许 各类 Agent 接收各类文件、文本、链接，然后自动将其“编译”并归档到一个统一的个人知识库中。你可以把这个知识库想象成一个巨大的、结构化的 “Skill 包”，它不仅包含事实性知识、经验性知识，还可以容纳你的长期记忆、个人喜好、过往经历等所有碎片化信息。

这就好比拥有一个私人的 AI 助理，它帮你把杂乱无章的桌面文件、散落的笔记，按照 AI 可理解的方式分门别类地管理起来。你无需关心底层的存储细节，只需负责“投喂”资料，Agent 负责整理、索引和持久化。当下次遇到相关问题时，它能直接从“缓存”中提取已内化的知识，而不是重新去搜索。这种理念不仅适用于个人知识管理，对企业级知识库的建设同样具有极高的参考价值。

我回顾一下阿里云智能客服的发展历程，其实知识体系的演进大致也经历了三个阶段，这也折射出当前技术范式的变化。第一个就是“传统智能知识库时代”，从2016~2022年，早期的智能客服基本上就是面向搜索引擎的知识库。知识必须由人工进行严格的分类、打标和归档，形成树状或标签体系。检索时，系统通过关键词匹配召回相关条目。这种方式非常高度依赖人工维护成本，且灵活性比较差，难以应对长尾问题。

到了后面就是2023年，随着大模型的兴起，进入到了“RAG时代”，RAG成为主流技术。核心逻辑就是是“前置小模型检索 + 后置大模型生成”。但是，我在之前的文章《Agent / Skills / Teams架构演进过程及技术选型之道》里提到过，虽然RAG解决了海量知识的存储和召回问题，但存在几个问题：

• 模型能力断层：前置的检索模型通常比较小，语义理解能力有限，容易漏召或误召关键信息，导致后端大模型“无米之炊”。

• 搜索独立性：每次交互都是独立的检索过程。即使上一次成功找到了答案，下一次面对相似问题时，仍需重新搜索。这不仅浪费算力，更带来了结果的不确定性，导致“上次搜得准，下次未必准”。

• 知识未沉淀：为了解决这些问题，在 Agent 时代出现了Agentic RAG，虽然可以通过让大模型反复优化搜索关键词来提升召回率，但这本质上是在用昂贵的推理成本去弥补检索能力的不足，并且且依然无法解决“知识未沉淀”的问题。

• 消除重复搜索：当新知识被录入并结构化后，它就成为了 Agent 内部知识库的一部分。下次遇到类似问题，Agent 直接读取已整理的知识，无需再次触发外部检索，极大地提升了稳定性和响应速度。

• 全链路大模型参与：从知识的解析、结构化到最终的调用，主要由大模型主导。大模型像阅读一本书的目录一样，根据上下文动态决定加载哪部分知识（就是渐进式披露），避免了小模型检索带来的语义偏差。

• 知识的累积效应：每一次交互都在丰富知识库，Agent 越用越聪明，形成了真正的“飞轮效应”。

简而言之，如果说 RAG 是让大模型“带着书本进考场”，那么 Skillify 则是让大模型“把书读透并记成整理后的笔记”。前者依赖临场发挥、现找资料，后者依赖深厚积累、精准定位。对于追求高稳定性、高准确率的复杂 Agent 场景而言，构建这种基于渐进式披露的持久化知识库，或许是现阶段比单纯优化 RAG 检索策略更本质的解法。

核心思路捋清楚账号，接下来，我们先深入看一下 Karpathy 提出的 LLM Wiki。他本身就是一个 llm-wiki.md 文件，具体内容我放进来，大家可以仔细看一下：

llm-wiki.md

# LLM Wiki


A pattern for building personal knowledge bases using LLMs.


This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.


## The core idea


Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.


The idea here is different. Instead of just retrieving from raw documents at query time, the LLM **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then *kept current*, not re-derived on every query.


This is the key difference: **the wiki is a persistent, compounding artifact.** The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.


You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.


This can apply to a lot of different contexts. A few examples:


- **Personal**: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
- **Reading a book**: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like [Tolkien Gateway](https://tolkiengateway.net/wiki/Main_Page) — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
- **Business/team**: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives** — anything where you're accumulating knowledge over time and want it organized rather than scattered.


## Architecture


There are three layers:


**Raw sources** — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.


**The wiki** — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.


**The schema** — a document (e.g. CLAUDE.md for Claude Code or AGENTS.md for Codex) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.


## Operations


**Ingest.** You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.


**Query.** You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: **good answers can be filed back into the wiki as new pages.** A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.


**Lint.** Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.


## Indexing and logging


Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:


**index.md** is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.


**log.md** is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`), the log becomes parseable with simple unix tools — `grep "^## \[" log.md | tail -5` gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.


## Optional: CLI tools


At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. [qmd](https://github.com/tobi/qmd) is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.


## Tips and tricks


- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
- **Download images locally.** In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. `raw/assets/`). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
- **Obsidian's graph view** is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
- **Dataview** is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.


## Why this works


The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.


The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.


The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.



## Note


This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.

LLM Wiki 提出了一个和 RAG 很不同的方法：不是在查询时从原始文档中检索，而是让 LLM 渐进式地构建和维护一个持久的 Wiki——一个结构化的、相互链接的 Markdown 文件集合。这就像编译型语言 vs 解释型语言：知识被“编译”一次，然后保持更新，而非每次查询时重新“解释”。关键的几个区别：

他的核心思路其实非常直观且优雅：将所有的知识沉淀为一个纯粹的 Markdown 文件集合体。然后，这个系统主要由三层架构构成：

1.原始资料层（Raw Sources）：只读的存档区，存放未经处理的原始输入（如文章、文档、笔记等）。

2.Wiki层（The Wiki）：中间层，按照主题、人物、概念等维度组织起来的结构化知识页面。

3.索引层（The Schema）：顶层逻辑，定义整个系统如何运行、如何更新以及如何校验知识的元指令。

LLM Wiki 的重点不在于“大规模摄入知识”，而在于“高质量整理知识”。它不仅仅是一个问答工具，更是一套具备自我维护能力的知识管理体系。其工作流程形成了一个完整的闭环：

• 摄入（Ingest）：当一个新的知识源被添加时，LLM Wiki 不会简单存入文件夹，而是执行深度处理：LLM 阅读原始资料，提取关键要点，生成摘要页面，并自动更新全局索引及相关实体页面。值得注意的是，一个单一来源往往能联动更新 10-15 个相关 Wiki 页面。这种在摄入阶段就完成知识深度关联与重组的能力，正是其区别于传统 RAG “只存不整”的关键所在。

• 查询（Query）：用户提问时，LLM 像专家一样工作：先定位相关 Wiki 页面，阅读后综合出带引用的答案。更精妙的是，如果问答产生了新洞察，系统可将高质量答案归档为新页面。这意味着，你的每一次探索都在为知识库做增量贡献，实现了知识的自我累积与反哺，让 Agent 越用越聪明。

• 维护（Lint）：为防止知识库杂乱，LLM Wiki 引入了类似代码静态检查的“Lint”机制，定期让 LLM进行健康检查：识别事实矛盾、清理过时声明、发现无入链的“孤儿页面”以及补全缺失的交叉引用。通过这三种操作，LLM Wiki 构建了一个具备自我进化能力的知识操作系统。

LLM Wiki 还设计了两个特殊的 Markdown 文件来帮助导航：

• index.md（面向内容）：Wiki 中所有页面的目录，按类别组织。LLM 回答查询时先读索引找到相关页面。在中等规模（约 100 个来源、数百个页面）下效果比较好。

• log.md（面向时间）：什么时候发生了什么的追加记录。给 Wiki 一个演化时间线。

为什么这种模式有效？维护知识库的繁琐部分不是阅读或思考，其实是“记账”。更新交叉引用、保持摘要最新、注意新数据何时与旧声明矛盾、维护数十个页面的一致性。人类放弃 Wiki 是因为维护负担增长得比价值更快。但是 LLM 并不会觉得无聊，也不会忘记更新交叉引用，可以一次性处理 15 个文件。Wiki 保持维护的状态，是因为维护成本接近零。人类的工作是策划来源、引导分析、提出好问题、思考意义。LLM 的工作是处理一切其他的事情。并且这种设计的最大优势在于透明性与可解释性。Markdown 格式是人类可读、可编辑、可审查且易于迁移的。你可以随时打开文件查看 Agent “记住”了什么，甚至手动修正错误的知识。

LLM Wiki 其实就只是一个 Markdown 文件，其实是一篇思想文章，把这个理念扔给 Agent，主要是交给你的 Agent 来帮你实现更多的细节。但是，实际用起来的时候，你会发现人去管理这些知识，如果仅仅是基于原生“文件系统”，其实还是不太方便的，总感觉少了些什么。那么，Karpathy 推荐使用 Obsidian 这个软件来管理，也有一个 Obsidian-Wiki [4]。

Obsidian-Wiki 是一个基于 Skill 的多 Agent 框架，并且实现了 Andrej Karpathy 的 LLM Wiki 模式，它的核心设计理念是：

• Agent 无关：支持 9+ 种 Agent（比如Claude Code、Cursor、Windsurf、Codex、OpenClaw、Hermes、Gemini CLI、Kiro 等等）

• Skill 驱动：所有操作通过标准化的 Markdown Skill 文件定义

• Obsidian 原生：利用 Obsidian 的 wikilink、图谱视图、Dataview 等功能

Obsidian-Wiki 相比 LLM-Wiki 在原始的三层架构基础上都做了增强，主要是：

• Delta 追踪（差异追踪）：这是 Obsidian-Wiki 相比LLM-Wiki原始模式最重要的创新之一。使用.manifest.json 文件跟踪所有已摄入的知识来源，每个来源用 SHA-256 哈希追踪。当你运行 wiki-status 时，系统就会扫描所有来源位置，然后对比 manifest 中的哈希，并将来源分类为：new（新的）、modified（内容变化）、touched（元数据变化）、unchanged（未变）、deleted（已删除）等等。这就意味着系统知道哪些来源需要重新处理，避免重复工作。

• 来源可信度边界：这是Obsidian-Wiki 引入了一个关键的安全概念。来源文档被视为不可信的，LLM 永远不应该执行来源中的命令。这防止了通过恶意文档注入指令的攻击（prompt injection through documents）。

• 溯源标记系统：每条知识都标记其来源可靠性，比如^[extracted]是直接从来源提取；^[inferred]是基于来源推断；^[ambiguous]是存在歧义或多种解释，这基于让人和LLM都能知道每条信息的可信度。

• 可见性标签：支持 visibility/internal 和 visibility/pii 标签，允许在查询时过滤敏感内容

• hot.md 热缓存：一个 500 字的语义快照，记录最近活动。这为 LLM 提供了快速上下文感知，无需读取完整的 log.md

Obsidian-Wiki 定义了 20+ 个标准化的 Skill，每个都是一个详细的 Markdown 文件，这里面最值得关注的是两类Skill，一类是Agent历史摄入相关Skills，另一类是知识图谱相关Skills。

Agent历史摄入Skills

这是Obsidian-Wiki最体现“自进化”的设计，在于它不仅仅是一个被动的知识接收器，更是一个能够主动从你的数字生活中“挖掘”知识的 Agent。它通过一系列专门的 History Ingest Skills，自动扫描并提取你日常使用的各类 AI Agent 的历史记录，将散落在各处的碎片化交互转化为结构化的知识库。

这种设计打破了数据孤岛，让不同工具间的记忆得以互通。例如：

Claude & Codex：可以自动读取 ~/.claude/ 和 ~/.codex/ 下的 CLI 会话（JSONL）、桌面应用会话及 Memory 文件，捕捉编程与对话中的隐性经验。

OpenClaw & Hermes Agent：深度集成各家生态，优先解析 MEMORY.md、DREAMS.md 等高价值长期记忆文件，其次才是每日笔记和会话转录。

并且，这些知识的处理流程非常严谨且高效：

• 增量扫描：仅计算与上次摄取的差异，避免重复处理。

• 优先级解析：遵循 Memory 文件 > 近期笔记 > 会话记录 的权重，确保核心认知优先入库。

• 隐私过滤：自动剔除 API Key、密码等敏感信息，保障数据安全。

• 主题聚类：不按时间或会话拆分，而是按语义主题进行重组，打破线性记录的局限。

• 蒸馏沉淀：最终将清洗后的信息蒸馏为标准的 Wiki 页面。

知识图谱Skills

除了历史摄取，LLM Wiki 还配备了强大的 Knowledge Graph Skills 来维护知识的关联性。其中 cross-linker 技能尤为关键，它能自动发现页面间的潜在联系并建立交叉引用，甚至引入了置信度评分系统：精确匹配得 +4 分，共享标签、同一项目、提及实体或跨类别引用各得 +2 分。这种量化的关联机制，使得知识图谱不再是简单的链接堆砌，而是一个具备逻辑权重的有机网络。配合 graph-colorize 进行的可视化着色，用户可以直观地看到知识网络的密度与结构。