From bb678945174147ddc867c30989151725a64f1e6d Mon Sep 17 00:00:00 2001 From: shazhou-ww Date: Wed, 25 Mar 2026 15:02:03 +0000 Subject: [PATCH] docs: add Memex knowledge base and OpenClaw Skills guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/shared/memex-knowledge-base.md: Memex 知识管理文档 - 三层记忆体系、安装、CLI 用法、卡片规范、决策树、Git 同步、最佳实践 - docs/shared/openclaw-skills.md: OpenClaw Skills 文档 - Skills 概念、自建 Skills 清单、目录结构、创建指南、ClawHub 市场 - mkdocs.yml: 添加两篇新文档到共享知识导航 --- docs/shared/memex-knowledge-base.md | 295 ++++++++++++++++++++++++++++ docs/shared/openclaw-skills.md | 170 ++++++++++++++++ mkdocs.yml | 2 + 3 files changed, 467 insertions(+) create mode 100644 docs/shared/memex-knowledge-base.md create mode 100644 docs/shared/openclaw-skills.md diff --git a/docs/shared/memex-knowledge-base.md b/docs/shared/memex-knowledge-base.md new file mode 100644 index 0000000..9aa6f3c --- /dev/null +++ b/docs/shared/memex-knowledge-base.md @@ -0,0 +1,295 @@ +# 🧠 Memex 知识管理 + +> 原子卡片 + 双向链接 — Agent 团队的共享外部记忆 + +--- + +## 概述 + +[Memex](https://github.com/anthropics/memex) 是一个基于 Zettelkasten 方法论的 CLI 知识管理工具。它将知识拆解为**原子卡片**（每张卡片一个知识点），通过 `[[双向链接]]` 构建知识网络。 + +我们用 memex 作为 Agent 团队的**共享外部记忆**——所有 agent 产生的可复用技术知识都汇聚在这里，跨 session、跨 agent 持久保存。 + +## 三层记忆体系 + +我们的知识管理分为三层，各司其职： + +``` +┌─────────────────────────────────────────────────┐ +│ 人类可见层 │ +│ OC Wiki / 飞书文档 │ +│ 面向人类的结构化文档、教程、指南 │ +├─────────────────────────────────────────────────┤ +│ 外存层（共享） │ +│ memex (~/.memex/cards/) │ +│ 跨 agent 共享的系统性知识库 │ +│ 原子卡片 + 双向链接 + Git 同步 │ +├─────────────────────────────────────────────────┤ +│ 内存层（私有） │ +│ 各 agent 的 MEMORY.md + memory/*.md │ +│ 个人偏好、与主人的互动记忆、日常操作日志 │ +└─────────────────────────────────────────────────┘ +``` + +| 维度 | MEMORY.md（内存） | memex（外存） | OC Wiki（文档） | +|:-----|:-----------------|:-------------|:---------------| +| **范围** | 单个 agent 私有 | 所有 agent 共享 | 面向人类 | +| **内容** | 个人偏好、互动记忆 | 技术知识、架构决策、踩坑记录 | 教程、指南、项目说明 | +| **粒度** | 自由格式 | 原子化，一卡一知识点 | 结构化长文 | +| **链接** | 无 | `[[双向链接]]` | 文档内链接 | +| **持久性** | agent 定期整理 | 长期沉淀，极少删除 | 版本控制 | + +## 安装 + +memex 的 npm 包名为 `@touchskyer/memex`： + +```bash +npm install -g @touchskyer/memex +``` + +验证安装： + +```bash +memex --version +# 0.1.24 +``` + +安装后卡片存储在 `~/.memex/cards/` 目录下，纯 Markdown 文件。 + +## 使用方法 + +### 搜索卡片 + +```bash +# 全文搜索 +memex search "docker compose" + +# 无参数列出所有卡片 +memex search +``` + +### 读取卡片 + +```bash +memex read +# 例：memex read docker-compose-port-binding +``` + +### 写入卡片 + +```bash +# 方式一：echo + 管道（短卡片） +echo '--- +title: "Docker Compose Port Binding Gotcha" +created: "2026-03-25" +source: "openclaw-huasheng" +tags: [docker, devops, gotcha] +category: devops +--- + +`ports: ["3000:3000"]` 会绑定到 0.0.0.0。 +只想本地访问需要 `ports: ["127.0.0.1:3000:3000"]`。 + +相关：[[docker-network-basics]]' | memex write docker-compose-port-gotcha +``` + +```bash +# 方式二：heredoc（长卡片，避免引号转义） +memex write api-versioning-strategy << 'CARD' +--- +title: "API Versioning Strategy" +created: "2026-03-25" +source: "openclaw-huasheng" +tags: [api, architecture, decision] +category: architecture +--- + +采用 URL 路径版本控制 `/v1/`, `/v2/`。 +CARD +``` + +### 查看链接图谱 + +```bash +# 查看某张卡片的出入链 +memex links + +# 查看全局链接概览（孤立卡片、热点等） +memex links +``` + +### 归档卡片 + +```bash +# 将过时卡片移至 ~/.memex/archive/ +memex archive +``` + +### Git 同步 + +```bash +# 首次配置 +memex sync --init + +# 开启自动同步（每次 write 后自动 push） +memex sync on + +# 手动同步 +memex sync +``` + +## 卡片规范 + +### Frontmatter 必填字段 + +每张卡片必须包含以下 YAML frontmatter： + +```yaml +--- +title: "卡片标题" # 必填，≤60 字符，名词短语 +created: "2026-03-25" # 必填，ISO 日期 +source: "openclaw-" # 必填，来源标识 +tags: [tag1, tag2] # 可选 +category: "architecture" # 可选 +links: [slug1, slug2] # 可选，显式链接 +--- +``` + +!!! warning "三个字段必填" + `title`、`created`、`source` 缺少任何一个都会报错。 + +### Slug 命名规则 + +- **格式**：kebab-case，全英文，3-60 字符 +- **要求**：描述性但简洁 + +| ✅ 好的 | ❌ 不好的 | +|:--------|:----------| +| `docker-compose-port-binding` | `note-1`（无意义） | +| `nextjs-app-router-migration` | `docker`（太宽泛） | +| `openclaw-feishu-doc-api-limits` | `how-to-fix-the-bug-we-found`（太长） | + +### 特殊前缀 + +| 前缀 | 用途 | 示例 | +|:-----|:-----|:-----| +| `adr-*` | 架构决策记录 | `adr-memory-three-layers` | +| `gotcha-*` | 踩坑记录 | `gotcha-yaml-date-auto-parse` | +| `pattern-*` | 设计模式 / 最佳实践 | `pattern-retry-with-backoff` | +| `tool-*` | 工具使用技巧 | `tool-memex-cli-usage` | + +### 标签体系 + +**按领域**：`docker`、`nodejs`、`typescript`、`react`、`api`、`database`、`devops`、`security`、`openclaw` + +**按类型**：`decision`、`gotcha`、`pattern`、`howto`、`reference`、`debug` + +**分类（category）**：`architecture`、`backend`、`frontend`、`devops`、`tooling`、`security`、`workflow` + +## 什么知识放哪里 + +遇到新知识时，按以下决策树判断归属： + +``` +新知识产生 + │ + ├─ 只对我一个 agent 有用？ + │ ├─ 是 → MEMORY.md + │ │ 例：主人的偏好、与主人的约定 + │ └─ 否 ↓ + │ + ├─ 可复用的技术知识？ + │ ├─ 是 → memex 卡片 + │ │ 例：API 设计模式、Bug 根因、工具配置 + │ └─ 否 ↓ + │ + ├─ 需要人类阅读的文档？ + │ ├─ 是 → OC Wiki + │ │ 例：部署手册、项目说明 + │ └─ 否 → memory/YYYY-MM-DD.md 日志 + │ + └─ 特殊情况： + ├─ 架构决策记录 (ADR) → memex + OC Wiki（双写） + └─ 今日操作日志 → memory/YYYY-MM-DD.md +``` + +## Git 同步（跨 VM） + +通过 Git 仓库在多台 VM 之间同步 memex 卡片： + +``` +KUMA-VM NEKO-VM +~/.memex/cards/ ~/.memex/cards/ + │ │ + └──── git push/pull ────────────────┘ + │ + GitHub Private Repo +``` + +### 配置步骤 + +```bash +# 1. 首次配置（每台 VM 执行一次） +memex sync --init + +# 2. 开启自动同步 +memex sync on + +# 3. 手动同步（需要时） +memex sync +``` + +### 同步策略 + +- **自动同步开启**：`memex sync on`，每次 write 后自动 push +- **读前拉取**：任务开始 recall 前先 `memex sync` 确保最新 +- **冲突处理**：定期 `memex links` 检查，organize 会标记冲突 +- 卡片粒度小且 slug 唯一，合并冲突概率极低 + +## 最佳实践 + +### 任务开始：Recall + +每次开始新任务前，先搜索相关知识： + +```bash +memex search "<关键词>" # 搜索相关卡片 +memex read # 深入阅读 +memex links # 查看关联 +``` + +!!! tip "先搜再做" + 避免重复踩坑。前人（其他 agent）的经验可能已经记录在卡片里了。 + +### 任务结束：Capture + +完成任务后，如果有**非显而易见的**新知识，写一张卡片： + +- 一张卡片一个原子知识点 +- 用 `[[wikilink]]` 链接相关卡片 +- 只记有价值的，不记琐碎的 + +### 定期维护：Organize + +```bash +# 检查知识图谱健康度 +memex links + +# 归档过时卡片 +memex archive +``` + +定期检查： + +- **孤立卡片** — 没有任何链接的卡片，考虑补充链接或归档 +- **热点卡片** — 被大量引用的卡片，确保内容准确 +- **过时卡片** — 信息已不适用，及时归档 + +!!! info "source 字段约定" + 统一使用 `openclaw-` 格式标识来源，如 `openclaw-huasheng`、`openclaw-xiaomo`、`openclaw-lvdou`。便于追溯谁写了什么。 + +--- + +
+:material-brain:{ .middle } 知识不记下来，就等于没学会 +
diff --git a/docs/shared/openclaw-skills.md b/docs/shared/openclaw-skills.md new file mode 100644 index 0000000..05790b5 --- /dev/null +++ b/docs/shared/openclaw-skills.md @@ -0,0 +1,170 @@ +# 🧩 OpenClaw Skills + +> 模块化能力扩展 — 让 Agent 按需装备新技能 + +--- + +## 什么是 Skills + +Skills 是 OpenClaw 的模块化能力扩展机制。每个 Skill 是一个独立的指令包，教会 Agent 如何完成特定类型的任务。 + +核心思想： + +- **按需加载** — Agent 根据任务自动匹配并加载相关 Skill +- **可复用** — 一个 Skill 可以被多个 Agent 使用 +- **可分享** — 通过 ClawHub 社区市场发布和安装 +- **声明式** — 用 Markdown 描述，不需要写代码 + +## 我们的自建 Skills + +以下是 `/home/azureuser/.openclaw/workspace/skills/` 下的自建 Skills： + +| Skill | 描述 | +|:------|:-----| +| **agent-team-orchestration** | 编排多 Agent 团队：角色定义、任务生命周期、交接协议、Review 工作流。适用于 2+ Agent 协作场景 | +| **memex-zettelkasten** | 基于 memex CLI 的共享知识库（Zettelkasten 原子卡片 + 双向链接）。任务开始 recall、任务结束 capture、知识图谱健康检查 | +| **openai-whisper-api** | 通过 OpenAI Audio Transcriptions API（Whisper）转写音频。支持 SiliconFlow 等兼容 API | +| **project-management-2** | 项目管理：任务追踪、优先级排序、项目规划、截止日期管理。覆盖多种方法论和工具选择 | +| **session-logs** | 使用 jq 搜索和分析 Agent 的历史 session 日志 | +| **story-time** | 互动式小说 — 自选冒险。内置故事和自定义创作框架 | +| **summarize** | 使用 summarize CLI 摘要 URL、PDF、图片、音频、YouTube 视频等 | + +## Skill 结构 + +一个标准的 Skill 目录结构如下： + +``` +my-skill/ +├── SKILL.md # 必需 — Skill 主文件，包含描述和指令 +├── scripts/ # 可选 — 辅助脚本 +│ └── run.sh +├── references/ # 可选 — 参考资料（API 文档、示例等） +│ └── api-spec.md +└── assets/ # 可选 — 静态资源 + └── template.json +``` + +### SKILL.md 规范 + +`SKILL.md` 是 Skill 的核心文件，包含 YAML frontmatter 和 Markdown 正文： + +```yaml +--- +name: my-skill +description: > + 简要描述这个 Skill 做什么，以及什么时候触发。 + Use when: (1) 场景一, (2) 场景二... + NOT for: 不适用的场景。 +--- + +# My Skill + +这里是 Agent 执行任务时遵循的具体指令。 +包括步骤、命令模板、注意事项等。 +``` + +**关键字段**： + +| 字段 | 说明 | +|:-----|:-----| +| `name` | Skill 名称，kebab-case | +| `description` | 描述 + 触发条件，Agent 据此判断是否加载 | +| 正文 | 具体操作指令，Agent 加载后按此执行 | + +!!! tip "description 很重要" + Agent 通过 description 判断是否匹配当前任务。写清楚"什么时候用"和"什么时候不用"。 + +## 如何创建新 Skill + +### 1. 创建目录 + +```bash +mkdir -p ~/.openclaw/workspace/skills/my-new-skill +``` + +### 2. 编写 SKILL.md + +```bash +cat > ~/.openclaw/workspace/skills/my-new-skill/SKILL.md << 'EOF' +--- +name: my-new-skill +description: > + 一句话描述。Use when: 触发场景。NOT for: 排除场景。 +--- + +# My New Skill + +## 步骤 + +1. 第一步... +2. 第二步... + +## 注意事项 + +- 注意点一 +- 注意点二 +EOF +``` + +### 3. 添加辅助文件（可选） + +```bash +# 脚本 +mkdir scripts/ +# 参考资料 +mkdir references/ +# 静态资源 +mkdir assets/ +``` + +### 4. 测试 + +创建完成后，Agent 会自动在 `` 列表中看到新 Skill。向 Agent 发送匹配 description 的任务，验证是否能正确触发。 + +## ClawHub — 社区 Skill 市场 + +[ClawHub](https://clawhub.com) 是 OpenClaw 的社区 Skill 市场，可以搜索、安装和发布 Skills。 + +### 搜索 Skill + +```bash +clawhub search "关键词" +``` + +### 安装 Skill + +```bash +clawhub install +``` + +安装后 Skill 会出现在 `~/.local/share/npm/lib/node_modules/openclaw/skills/` 下，Agent 自动可用。 + +### 更新 Skill + +```bash +# 更新所有已安装的 ClawHub skills +clawhub sync + +# 更新指定 skill 到最新版 +clawhub sync +``` + +### 发布 Skill + +将自建 Skill 发布到 ClawHub 分享给社区： + +```bash +clawhub publish ~/.openclaw/workspace/skills/my-skill +``` + +!!! info "两类 Skills 的位置" + - **ClawHub 安装的**: `~/.local/share/npm/lib/node_modules/openclaw/skills/` + - **自建的**: `~/.openclaw/workspace/skills/` + + 两个位置的 Skills 都会出现在 Agent 的 `` 列表中。 + +--- + +
+:material-puzzle:{ .middle } 模块化组装，按需赋能 +
diff --git a/mkdocs.yml b/mkdocs.yml index e63048b..749e7b9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,8 @@ nav: - 语音转文字配置: shared/speech-to-text.md - SiliconFlow 图片生成: shared/siliconflow-image-gen.md - A2A 跨队通信: shared/a2a-setup.md + - Memex 知识管理: shared/memex-knowledge-base.md + - OpenClaw Skills: shared/openclaw-skills.md extra: social: