678 lines
27 KiB
Markdown
678 lines
27 KiB
Markdown
# 技能作为分支（Skills as Branches）
|
||
|
||
## 概述
|
||
|
||
本文档涵盖**功能技能（feature skills）**——通过 git 分支合并（branch merge）添加能力的技能。这是最复杂的技能类型，也是扩展 NanoClaw 的主要方式。
|
||
|
||
NanoClaw 共有四种技能类型。完整分类请参阅 [CONTRIBUTING.md](../CONTRIBUTING.md)：
|
||
|
||
| 类型 | 位置 | 工作原理 |
|
||
|------|----------|-------------|
|
||
| **功能型（Feature）**（本文档） | `.claude/skills/` + `skill/*` 分支 | SKILL.md 包含指令；代码位于分支上，通过 `git merge` 应用 |
|
||
| **工具型（Utility）** | `.claude/skills/<name>/` 包含代码文件 | 自包含工具；代码在技能目录中，安装时复制到位 |
|
||
| **操作型（Operational）** | `main` 上的 `.claude/skills/` | 纯指令工作流（setup、debug、update） |
|
||
| **容器型（Container）** | `container/skills/` | 运行时加载到代理容器内部 |
|
||
|
||
---
|
||
|
||
功能技能以 git 分支的形式分发在上游仓库中。应用一个技能就是一次 `git merge`。更新核心也是一次 `git merge`。一切都是标准 git 操作。
|
||
|
||
这取代了之前的 `skills-engine/` 系统（三路文件合并、`.nanoclaw/` 状态、清单文件、重放、备份/恢复），改用纯 git 操作和 Claude 进行冲突解决。
|
||
|
||
## 工作原理
|
||
|
||
### 仓库结构
|
||
|
||
上游仓库 (`nanocoai/nanoclaw`) 维护以下内容：
|
||
|
||
- `main` — 核心 NanoClaw（不含技能代码）
|
||
- `skill/discord` — main + Discord 集成
|
||
- `skill/telegram` — main + Telegram 集成
|
||
- `skill/slack` — main + Slack 集成
|
||
- `skill/gmail` — main + Gmail 集成
|
||
- 等等。
|
||
|
||
每个技能分支包含该技能的所有代码改动：新增文件、修改的源文件、更新的 `package.json` 依赖项、`.env.example` 新增内容——一切。没有清单文件，没有结构化操作，没有单独的 `add/` 和 `modify/` 目录。
|
||
|
||
### 技能发现与安装
|
||
|
||
技能分为两类：
|
||
|
||
**操作型技能**（位于 `main`，始终可用）：
|
||
- `/setup`、`/debug`、`/update-nanoclaw`、`/customize`、`/update-skills`
|
||
- 这些是纯指令的 SKILL.md 文件——没有代码改动，只有工作流
|
||
- 位于 `main` 上的 `.claude/skills/`，对每个用户立即可用
|
||
|
||
**功能型技能**（在市场（marketplace）中，按需安装）：
|
||
- `/add-discord`、`/add-telegram`、`/add-slack`、`/add-gmail` 等。
|
||
- 每个都有一套 SKILL.md 安装指令和对应的 `skill/*` 分支代码
|
||
- 位于市场仓库 (`nanocoai/nanoclaw-skills`) 中
|
||
|
||
用户永远不会直接与市场交互。操作型技能 `/setup` 和 `/customize` 透明地处理插件安装：
|
||
|
||
```bash
|
||
# Claude 在后台运行此命令——用户不可见
|
||
claude plugin install nanoclaw-skills@nanoclaw-skills --scope project
|
||
```
|
||
|
||
技能在 `claude plugin install` 之后热加载（hot-loaded）——无需重启。这意味着 `/setup` 可以安装市场插件，然后立即运行任何功能技能，全部在一个会话（session）中完成。
|
||
|
||
### 选择性技能安装
|
||
|
||
`/setup` 询问用户想要哪些频道，然后只提供相关技能：
|
||
|
||
1. "你想用哪些消息频道？" → Discord、Telegram、Slack、WhatsApp
|
||
2. 用户选择 Telegram → Claude 安装插件并运行 `/add-telegram`
|
||
3. Telegram 设置完成后："想为 Telegram 添加 Agent Swarm 支持？" → 提供 `/add-telegram-swarm`
|
||
4. "想启用社区技能？" → 安装社区市场插件
|
||
|
||
依赖技能（例如 `telegram-swarm` 依赖 `telegram`）仅在其父技能安装后才提供。`/customize` 在安装后的添加操作中遵循相同模式。
|
||
|
||
### 市场配置
|
||
|
||
NanoClaw 的 `.claude/settings.json` 注册了官方市场：
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"nanoclaw-skills": {
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "nanocoai/nanoclaw-skills"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
市场仓库使用 Claude Code 的插件结构：
|
||
|
||
```
|
||
nanocoai/nanoclaw-skills/
|
||
.claude-plugin/
|
||
marketplace.json # 插件目录
|
||
plugins/
|
||
nanoclaw-skills/ # 捆绑所有官方技能的单一插件
|
||
.claude-plugin/
|
||
plugin.json # 插件清单
|
||
skills/
|
||
add-discord/
|
||
SKILL.md # 安装指令；步骤 1 是 "merge the branch"
|
||
add-telegram/
|
||
SKILL.md
|
||
add-slack/
|
||
SKILL.md
|
||
...
|
||
```
|
||
|
||
多个技能捆绑在一个插件中——安装 `nanoclaw-skills` 使所有功能技能立即可用。单独技能不需要单独安装。
|
||
|
||
每个 SKILL.md 告诉 Claude 在第 1 步合并相应的技能分支，然后引导交互式设置（环境变量、机器人创建等）。
|
||
|
||
### 应用技能
|
||
|
||
用户运行 `/add-discord`（通过市场发现）。Claude 按照 SKILL.md 操作：
|
||
|
||
1. `git fetch upstream skill/discord`
|
||
2. `git merge upstream/skill/discord`
|
||
3. 交互式设置（创建机器人、获取 token、配置环境变量等）
|
||
|
||
或手动操作：
|
||
|
||
```bash
|
||
git fetch upstream skill/discord
|
||
git merge upstream/skill/discord
|
||
```
|
||
|
||
### 应用多个技能
|
||
|
||
```bash
|
||
git merge upstream/skill/discord
|
||
git merge upstream/skill/telegram
|
||
```
|
||
|
||
Git 处理组合（composition）。如果两个技能修改了相同的行，那就是真实的冲突，由 Claude 解决。
|
||
|
||
### 更新核心
|
||
|
||
```bash
|
||
git fetch upstream main
|
||
git merge upstream/main
|
||
```
|
||
|
||
由于技能分支保持与 main 向前合并（参见 CI 部分），用户已合并的技能改动和上游改动之间有正确的公共祖先。
|
||
|
||
### 检查技能更新
|
||
|
||
之前合并过技能分支的用户可以检查更新。对于每个 `upstream/skill/*` 分支，检查该分支是否有不在用户 HEAD 中的提交：
|
||
|
||
```bash
|
||
git fetch upstream
|
||
for branch in $(git branch -r | grep 'upstream/skill/'); do
|
||
# 检查用户是否在某个时间点合并过此技能
|
||
merge_base=$(git merge-base HEAD "$branch" 2>/dev/null) || continue
|
||
# 检查技能分支是否有超出用户已有的新提交
|
||
if ! git merge-base --is-ancestor "$branch" HEAD 2>/dev/null; then
|
||
echo "$branch 有可用更新"
|
||
fi
|
||
done
|
||
```
|
||
|
||
这不需要任何状态——它使用 git 历史来确定之前合并了哪些技能以及它们是否有新提交。
|
||
|
||
此逻辑可通过两种方式使用：
|
||
- 内置于 `/update-nanoclaw` 中——合并 main 后可选择性检查技能更新
|
||
- 独立的 `/update-skills` ——独立检查和合并技能更新
|
||
|
||
### 冲突解决
|
||
|
||
在任何合并步骤中，可能出现冲突。Claude 解决它们——读取冲突文件，理解双方的意图，并生成正确的结果。这就是分支方案能够大规模可行的原因：以前需要人工判断的冲突解决现已自动化。
|
||
|
||
### 技能依赖
|
||
|
||
一些技能依赖其他技能。例如 `skill/telegram-swarm` 需要 `skill/telegram`。依赖技能分支从其父技能分支派生，而不是从 `main` 派生。
|
||
|
||
这意味着 `skill/telegram-swarm` 包含 telegram 的所有改动加上自己的新增内容。当用户合并 `skill/telegram-swarm` 时，他们同时获得两者——无需单独合并 telegram。
|
||
|
||
依赖关系隐含在 git 历史中——`git merge-base --is-ancestor` 判断一个技能分支是否为另一个的祖先。不需要单独的依赖文件。
|
||
|
||
### 卸载技能
|
||
|
||
```bash
|
||
# 找到合并提交
|
||
git log --merges --oneline | grep discord
|
||
|
||
# 回退它
|
||
git revert -m 1 <merge-commit>
|
||
```
|
||
|
||
这会创建一个新的提交来撤销该技能的改动。Claude 可以处理整个流程。
|
||
|
||
如果用户在合并后修改了技能的代码（在之上做了自定义改动），回退可能会冲突——Claude 会解决它。
|
||
|
||
如果用户之后想重新应用技能，他们需要先回退之前回退的提交（git 将已回退的改动视为"已应用并已撤销"）。Claude 也会处理这个问题。
|
||
|
||
## CI：保持技能分支最新
|
||
|
||
每次推送到 `main` 时运行一个 GitHub Action：
|
||
|
||
1. 列出所有 `skill/*` 分支
|
||
2. 对每个技能分支，将 `main` 合并进去（向前合并，而非变基）
|
||
3. 对合并结果运行构建和测试
|
||
4. 如果测试通过，推送更新后的技能分支
|
||
5. 如果技能失败（冲突、构建错误、测试失败），打开 GitHub issue 进行手动解决
|
||
|
||
**为什么用向前合并而非变基（rebase）：**
|
||
- 无需 force-push——保留了已合并该技能的用户的历史
|
||
- 用户可以重新合并技能分支以获取技能更新（bug 修复、改进）
|
||
- Git 在整个合并图中有正确的公共祖先
|
||
|
||
**为什么这具有可扩展性：**即使有几百个技能和每天几次 main 提交，CI 成本也微不足道。Haiku 模型速度快且便宜。一两年以前不可行的方法现在因为 Claude 可以大规模解决冲突而变得实用。
|
||
|
||
## 安装流程
|
||
|
||
### 新用户（推荐）
|
||
|
||
1. 在 GitHub 上 Fork `nanocoai/nanoclaw`（点击 Fork 按钮）
|
||
2. 克隆你的 fork：
|
||
```bash
|
||
git clone https://github.com/<you>/nanoclaw.git
|
||
cd nanoclaw
|
||
```
|
||
3. 运行 Claude Code：
|
||
```bash
|
||
claude
|
||
```
|
||
4. 运行 `/setup`——Claude 处理依赖项、认证、容器设置、服务配置，并在不存在时添加 `upstream` 远程
|
||
|
||
推荐 fork 是因为它为用户提供了一个远程仓库来推送自定义内容。仅克隆可用于试用，但没有远程备份。
|
||
|
||
### 从克隆迁移的现有用户
|
||
|
||
之前运行了 `git clone https://github.com/nanocoai/nanoclaw.git` 且有本地自定义内容的用户：
|
||
|
||
1. 在 GitHub 上 Fork `nanocoai/nanoclaw`
|
||
2. 重新路由远程仓库：
|
||
```bash
|
||
git remote rename origin upstream
|
||
git remote add origin https://github.com/<you>/nanoclaw.git
|
||
git push --force origin main
|
||
```
|
||
需要 `--force` 是因为新 fork 的 main 是上游最新版，但用户想要他们可能落后的版本。fork 刚刚创建，所以没有可丢失的内容。
|
||
3. 此后，`origin` = 用户的 fork，`upstream` = nanocoai/nanoclaw
|
||
|
||
### 从旧技能引擎迁移的现有用户
|
||
|
||
之前通过 `skills-engine/` 系统应用技能的用户在文件树中有技能代码，但没有链接到技能分支的合并提交。Git 不知道这些改动来自技能，因此在其之上合并技能分支会产生冲突或重复。
|
||
|
||
**对于今后的新技能：**正常合并技能分支即可。没有问题。
|
||
|
||
**对于现有的旧引擎技能**，有两种迁移路径：
|
||
|
||
**方案 A：逐技能重新应用（保留你的 fork）**
|
||
1. 对于每个旧引擎技能：识别并回退旧改动，然后重新合并技能分支
|
||
2. Claude 协助识别需要回退的内容并解决所有冲突
|
||
3. 自定义修改（非技能改动）被保留
|
||
|
||
**方案 B：全新开始（最干净）**
|
||
1. 从上游创建新的 fork
|
||
2. 合并你想要的技能分支
|
||
3. 手动重新应用你的自定义（非技能）改动
|
||
4. Claude 通过比较旧 fork 和新 fork 来帮助识别自定义改动
|
||
|
||
两种情况都需要：
|
||
- 删除 `.nanoclaw/` 目录（不再需要）
|
||
- `skills-engine/` 代码将在所有技能迁移后从上游移除
|
||
- `/update-skills` 仅跟踪通过分支合并应用的技能——旧引擎技能不会出现在更新检查中
|
||
|
||
## 用户工作流
|
||
|
||
### 自定义改动
|
||
|
||
用户直接在其 main 分支上进行自定义改动。这是标准的 fork 工作流——他们的 `main` 就是他们的定制版本。
|
||
|
||
```bash
|
||
# 进行改动
|
||
vim src/config.ts
|
||
git commit -am "将触发词改为 @Bob"
|
||
git push origin main
|
||
```
|
||
|
||
自定义改动、技能和核心更新共存于他们的 main 分支上。Git 在每一步合并时处理三路合并，因为它可以通过合并历史追溯公共祖先。
|
||
|
||
### 应用技能
|
||
|
||
在 Claude Code 中运行 `/add-discord`（通过市场插件发现），或手动操作：
|
||
|
||
```bash
|
||
git fetch upstream skill/discord
|
||
git merge upstream/skill/discord
|
||
# 按照设置指令进行配置
|
||
git push origin main
|
||
```
|
||
|
||
如果用户在合并技能分支时落后于上游 main，合并可能会同时引入一些核心改动（因为技能分支是向前合并了 main 的）。这通常没问题——他们得到一个兼容的版本。
|
||
|
||
### 更新核心
|
||
|
||
```bash
|
||
git fetch upstream main
|
||
git merge upstream/main
|
||
git push origin main
|
||
```
|
||
|
||
这与现有 `/update-nanoclaw` 技能的合并路径相同。
|
||
|
||
### 更新技能
|
||
|
||
运行 `/update-skills` 或让 `/update-nanoclaw` 在核心更新后检查。对于每个有新提交的先前合并的技能分支，Claude 会提出合并更新的建议。
|
||
|
||
### 向上游贡献
|
||
|
||
想要向上游提交 PR 的用户：
|
||
|
||
```bash
|
||
git fetch upstream main
|
||
git checkout -b my-fix upstream/main
|
||
# 进行改动
|
||
git push origin my-fix
|
||
# 从 my-fix 创建 PR 到 nanocoai/nanoclaw:main
|
||
```
|
||
|
||
标准的 fork 贡献工作流。他们的自定义改动保留在 main 上，不会泄露到 PR 中。
|
||
|
||
## 贡献技能
|
||
|
||
以下流程适用于**功能技能**（基于分支）。对于工具型技能（自包含工具）和容器型技能，贡献者直接向 `.claude/skills/<name>/` 或 `container/skills/<name>/` 添加文件的 PR——无需分支提取。所有技能类型请参见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
|
||
|
||
### 贡献者流程（功能技能）
|
||
|
||
1. Fork `nanocoai/nanoclaw`
|
||
2. 从 `main` 创建分支
|
||
3. 进行代码改动（新的频道文件、修改的集成点、更新的 package.json、.env.example 新增内容等）
|
||
4. 向 `main` 提交 PR
|
||
|
||
贡献者提交一个普通的 PR——他们不需要了解技能分支或市场仓库。他们只需进行代码改动并提交。
|
||
|
||
### 维护者流程
|
||
|
||
当技能 PR 被审查和批准后：
|
||
|
||
1. 从 PR 的提交创建一个 `skill/<name>` 分支：
|
||
```bash
|
||
git fetch origin pull/<PR_NUMBER>/head:skill/<name>
|
||
git push origin skill/<name>
|
||
```
|
||
2. Force-push 到贡献者的 PR 分支，将其替换为一个单独的提交，将贡献者添加到 `CONTRIBUTORS.md`（移除所有代码改动）
|
||
3. 将精简后的 PR 合并到 `main`（仅包含贡献者添加）
|
||
4. 将技能的 SKILL.md 添加到市场仓库 (`nanocoai/nanoclaw-skills`)
|
||
|
||
这样：
|
||
- 贡献者获得合并荣誉（其 PR 被合并）
|
||
- 他们由维护者自动添加到 CONTRIBUTORS.md 中
|
||
- 技能分支从其工作中创建
|
||
- `main` 保持干净（无技能代码）
|
||
- 贡献者只需要做一件事：提交含有代码改动的 PR
|
||
|
||
**注意：**来自 fork 的 GitHub PR 默认选中"允许维护者编辑"，因此维护者可以推送到贡献者的 PR 分支。
|
||
|
||
### 技能 SKILL.md
|
||
|
||
贡献者可以选择提供 SKILL.md（在 PR 中或单独提供）。它放入市场仓库并包含：
|
||
|
||
1. 前置信息（名称、描述、触发器）
|
||
2. 步骤 1：合并技能分支
|
||
3. 步骤 2-N：交互式设置（创建机器人、获取 token、配置环境变量、验证）
|
||
|
||
如果贡献者未提供 SKILL.md，维护者将根据 PR 编写一个。
|
||
|
||
## 社区市场
|
||
|
||
任何人都可以使用技能分支维护自己的 fork 和自己的市场仓库。这实现了社区驱动的技能生态系统，无需对上游仓库的写入权限。
|
||
|
||
### 工作原理
|
||
|
||
社区贡献者：
|
||
|
||
1. 维护 NanoClaw 的一个 fork（例如 `alice/nanoclaw`）
|
||
2. 在其 fork 上使用自定义技能创建 `skill/*` 分支
|
||
3. 创建一个市场仓库（例如 `alice/nanoclaw-skills`），带有 `.claude-plugin/marketplace.json` 和插件结构
|
||
|
||
### 添加社区市场
|
||
|
||
如果社区贡献者受信任，他们可以提交 PR 将其市场添加到 NanoClaw 的 `.claude/settings.json`：
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"nanoclaw-skills": {
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "nanocoai/nanoclaw-skills"
|
||
}
|
||
},
|
||
"alice-nanoclaw-skills": {
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "alice/nanoclaw-skills"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
合并后，所有 NanoClaw 用户自动发现社区市场以及官方市场。
|
||
|
||
### 安装社区技能
|
||
|
||
`/setup` 和 `/customize` 询问用户是否想启用社区技能。如果是，Claude 通过 `claude plugin install` 安装社区市场插件：
|
||
|
||
```bash
|
||
claude plugin install alice-skills@alice-nanoclaw-skills --scope project
|
||
```
|
||
|
||
社区技能热加载并立即可用——无需重启。依赖技能仅在其先决条件满足后才提供（例如，社区 Telegram 附加组件仅在 Telegram 安装后提供）。
|
||
|
||
用户也可以通过 `/plugin` 手动浏览和安装社区插件。
|
||
|
||
### 该系统的特性
|
||
|
||
- **无需审批把关。**任何人都可以在其 fork 上创建技能，无需许可。要列入自动发现的市场才需要批准。
|
||
- **多个市场共存。**用户在 `/plugin` 中看到来自所有受信任市场的技能。
|
||
- **社区技能使用相同的合并模式。**SKILL.md 只是指向不同的远程仓库：
|
||
```bash
|
||
git remote add alice https://github.com/alice/nanoclaw.git
|
||
git fetch alice skill/my-cool-feature
|
||
git merge alice/skill/my-cool-feature
|
||
```
|
||
- **用户也可以手动添加市场。**即使未列入 settings.json，用户也可以运行 `/plugin marketplace add alice/nanoclaw-skills` 来发现任何来源的技能。
|
||
- **CI 是每个 fork 独立的。**每个社区维护者运行自己的 CI 以保持其技能分支向前合并。他们可以使用与上游仓库相同的 GitHub Action。
|
||
|
||
## 风味（Flavors）
|
||
|
||
风味是 NanoClaw 的精选 fork——为特定用例量身定制的技能、自定义改动和配置的组合（例如，"NanoClaw for Sales"、"NanoClaw Minimal"、"NanoClaw for Developers"）。
|
||
|
||
### 创建风味
|
||
|
||
1. Fork `nanocoai/nanoclaw`
|
||
2. 合并你想要的技能
|
||
3. 进行自定义改动（触发词、提示词、集成等）
|
||
4. 你的 fork 的 `main` 就是风味
|
||
|
||
### 安装风味
|
||
|
||
在 `/setup` 期间，在任何配置发生之前向用户提供风味选择。设置技能从仓库读取 `flavors.yaml`（随上游发布，始终最新）并呈现选项：
|
||
|
||
AskUserQuestion: "从风味开始还是默认 NanoClaw？"
|
||
- 默认 NanoClaw
|
||
- NanoClaw for Sales — Gmail + Slack + CRM（由 alice 维护）
|
||
- NanoClaw Minimal — 仅 Telegram，轻量级（由 bob 维护）
|
||
|
||
如果选择了风味：
|
||
|
||
```bash
|
||
git remote add <风味名称> https://github.com/alice/nanoclaw.git
|
||
git fetch <风味名称> main
|
||
git merge <风味名称>/main
|
||
```
|
||
|
||
然后设置过程正常继续（依赖项、认证、容器、服务）。
|
||
|
||
**此选择仅在全新 fork 时提供**——当用户的 main 与上游 main 匹配或接近且没有本地提交时。如果 `/setup` 检测到显著的本地改动（在现有安装上重新运行 setup），它会跳过风味选择，直接进入配置。
|
||
|
||
安装后，用户的 fork 有三个远程仓库：
|
||
- `origin` — 其 fork（推送自定义内容到此）
|
||
- `upstream` — `nanocoai/nanoclaw`（核心更新）
|
||
- `<风味名称>` — 风味 fork（风味更新）
|
||
|
||
### 更新风味
|
||
|
||
```bash
|
||
git fetch <风味名称> main
|
||
git merge <风味名称>/main
|
||
```
|
||
|
||
风味维护者保持其 fork 更新（合并上游、更新技能）。用户以与获取核心更新相同的方式获取风味更新。
|
||
|
||
### 风味注册表
|
||
|
||
`flavors.yaml` 位于上游仓库中：
|
||
|
||
```yaml
|
||
flavors:
|
||
- name: NanoClaw for Sales
|
||
repo: alice/nanoclaw
|
||
description: Gmail + Slack + CRM 集成，每日流水线摘要
|
||
maintainer: alice
|
||
|
||
- name: NanoClaw Minimal
|
||
repo: bob/nanoclaw
|
||
description: 仅 Telegram，无容器开销
|
||
maintainer: bob
|
||
```
|
||
|
||
任何人都可以提交 PR 来添加自己的风味。该文件在 `/setup` 运行时可本地使用，因为它是克隆仓库的一部分。
|
||
|
||
### 可发现性
|
||
|
||
- **设置期间**——风味选择作为初始设置流程的一部分提供
|
||
- **`/browse-flavors` 技能**——随时读取 `flavors.yaml` 并呈现选项
|
||
- **GitHub 主题**——风味 fork 可以标记 `nanoclaw-flavor` 标签以便搜索
|
||
- **Discord / 网站**——社区精选列表
|
||
|
||
## 迁移
|
||
|
||
从旧技能引擎到分支的迁移已完成。所有功能技能现在位于 `skill/*` 分支上，技能引擎已移除。
|
||
|
||
### 技能分支
|
||
|
||
| 分支 | 基准 | 描述 |
|
||
|--------|------|-------------|
|
||
| `skill/whatsapp` | `main` | WhatsApp 频道 |
|
||
| `skill/telegram` | `main` | Telegram 频道 |
|
||
| `skill/slack` | `main` | Slack 频道 |
|
||
| `skill/discord` | `main` | Discord 频道 |
|
||
| `skill/gmail` | `main` | Gmail 频道 |
|
||
| `skill/voice-transcription` | `skill/whatsapp` | OpenAI Whisper 语音转录 |
|
||
| `skill/image-vision` | `skill/whatsapp` | 图片附件处理 |
|
||
| `skill/pdf-reader` | `skill/whatsapp` | PDF 附件阅读 |
|
||
| `skill/local-whisper` | `skill/voice-transcription` | 本地 whisper.cpp 转录 |
|
||
| `skill/ollama-tool` | `main` | Ollama MCP 服务器用于本地模型 |
|
||
| `skill/apple-container` | `main` | Apple Container 运行时 |
|
||
| `skill/reactions` | `main` | WhatsApp 表情反应 |
|
||
|
||
### 已移除的内容
|
||
|
||
- `skills-engine/` 目录（整个引擎）
|
||
- `scripts/apply-skill.ts`、`scripts/uninstall-skill.ts`、`scripts/rebase.ts`
|
||
- `scripts/fix-skill-drift.ts`、`scripts/validate-all-skills.ts`
|
||
- `.github/workflows/skill-drift.yml`、`.github/workflows/skill-pr.yml`
|
||
- 技能目录中的所有 `add/`、`modify/`、`tests/` 和 `manifest.yaml`
|
||
- `.nanoclaw/` 状态目录
|
||
|
||
操作型技能（`setup`、`debug`、`update-nanoclaw`、`customize`、`update-skills`）保留在 main 的 `.claude/skills/` 中。
|
||
|
||
## 变更内容
|
||
|
||
### README 快速入门
|
||
|
||
之前：
|
||
```bash
|
||
git clone https://github.com/nanocoai/NanoClaw.git
|
||
cd NanoClaw
|
||
claude
|
||
```
|
||
|
||
之后：
|
||
```
|
||
1. 在 GitHub 上 Fork nanocoai/nanoclaw
|
||
2. git clone https://github.com/<you>/nanoclaw.git
|
||
3. cd nanoclaw
|
||
4. claude
|
||
5. /setup
|
||
```
|
||
|
||
### 设置技能 (`/setup`)
|
||
|
||
设置流程的更新：
|
||
|
||
- 检查 `upstream` 远程是否存在；如果不存在则添加：`git remote add upstream https://github.com/nanocoai/nanoclaw.git`
|
||
- 检查 `origin` 是否指向用户的 fork（而非 nanocoai）。如果指向 nanocoai，引导他们完成 fork 迁移。
|
||
- **安装市场插件：**`claude plugin install nanoclaw-skills@nanoclaw-skills --scope project`——使所有功能技能可用（热加载，无需重启）
|
||
- **询问要添加哪些频道：**呈现频道选项（Discord、Telegram、Slack、WhatsApp、Gmail），为选中的频道运行相应的 `/add-*` 技能
|
||
- **提供依赖技能：**频道设置后，提供相关附加组件（例如 Telegram 后的 Agent Swarm、WhatsApp 后的语音转录）
|
||
- **可选启用社区市场：**询问用户是否想要社区技能，同时安装这些市场插件
|
||
|
||
### `.claude/settings.json`
|
||
|
||
市场配置，使官方市场自动注册：
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"nanoclaw-skills": {
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "nanocoai/nanoclaw-skills"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### main 上的技能目录
|
||
|
||
`main` 上的 `.claude/skills/` 目录仅保留操作型技能（setup、debug、update-nanoclaw、customize、update-skills）。功能技能（add-discord、add-telegram 等）位于市场仓库中，通过 `/setup` 或 `/customize` 期间的 `claude plugin install` 安装。
|
||
|
||
### 技能引擎移除
|
||
|
||
以下内容可以移除：
|
||
|
||
- `skills-engine/`——整个目录（应用、合并、重放、状态、备份等）
|
||
- `scripts/apply-skill.ts`
|
||
- `scripts/uninstall-skill.ts`
|
||
- `scripts/fix-skill-drift.ts`
|
||
- `scripts/validate-all-skills.ts`
|
||
- `.nanoclaw/`——状态目录
|
||
- 所有技能目录中的 `add/` 和 `modify/` 子目录
|
||
- main 上 `.claude/skills/` 中的功能技能 SKILL.md 文件（它们现在位于市场中）
|
||
|
||
操作型技能（`setup`、`debug`、`update-nanoclaw`、`customize`、`update-skills`）保留在 main 的 `.claude/skills/` 中。
|
||
|
||
### 新的基础设施
|
||
|
||
- **市场仓库** (`nanocoai/nanoclaw-skills`)——绑定所有功能技能的 SKILL.md 文件的单一 Claude Code 插件
|
||
- **CI GitHub Action**——每次推送到 `main` 时将 `main` 向前合并到所有 `skill/*` 分支，使用 Claude (Haiku) 解决冲突
|
||
- **`/update-skills` 技能**——使用 git 历史检查并应用技能分支更新
|
||
- **`CONTRIBUTORS.md`**——追踪技能贡献者
|
||
|
||
### 更新技能 (`/update-nanoclaw`)
|
||
|
||
采用基于分支的方法后更新技能变得更简单。旧的技能引擎需要在合并核心更新后重放所有已应用的技能——这整步消失了。技能改动已经在用户的 git 历史中，所以 `git merge upstream/main` 直接就能使用。
|
||
|
||
**保持不变的内容：**
|
||
- 预检（干净的工作树、upstream 远程）
|
||
- 备份分支 + 标签
|
||
- 预览（git log、git diff、文件分桶）
|
||
- 合并/拣选/变基选项
|
||
- 冲突预览（dry-run 合并）
|
||
- 冲突解决
|
||
- 构建 + 测试验证
|
||
- 回滚指令
|
||
|
||
**移除的内容：**
|
||
- 技能重放步骤（旧技能引擎需要在核心更新后重新应用技能）
|
||
- 重新运行结构化操作（npm 依赖项、env 变量——这些现在是 git 历史的一部分）
|
||
|
||
**新增的内容：**
|
||
- 末尾的可选步骤："检查技能更新？"，运行 `/update-skills` 逻辑
|
||
- 它检查任何先前合并的技能分支是否有新提交（bug 修复、技能本身的改进——不仅仅是来自 main 的向前合并）
|
||
|
||
**为什么核心更新后用户不需要重新合并技能：**
|
||
当用户合并了一个技能分支时，这些改动成为其 git 历史的一部分。当他们之后合并 `upstream/main` 时，git 执行普通的三路合并——其文件树中的技能改动不受影响，只引入核心改动。向前合并 CI 确保技能分支保持与最新 main 兼容，但这是为新用户全新应用技能准备的。已经合并了该技能的现有用户不需要做任何事。
|
||
|
||
用户只有在技能本身被更新时（不仅仅是向前合并了 main）才需要重新合并技能分支。`/update-skills` 检查会检测到这一点。
|
||
|
||
## Discord 公告
|
||
|
||
### 致现有用户
|
||
|
||
> **技能现在是 git 分支**
|
||
>
|
||
> 我们简化了 NanoClaw 中技能的工作方式。技能现在是你可以合并进来的 git 分支，而非自定义技能引擎。
|
||
>
|
||
> **这对你意味着什么：**
|
||
> - 应用技能：`git fetch upstream skill/discord && git merge upstream/skill/discord`
|
||
> - 更新核心：`git fetch upstream main && git merge upstream/main`
|
||
> - 检查技能更新：`/update-skills`
|
||
> - 不再有 `.nanoclaw/` 状态目录或技能引擎
|
||
>
|
||
> **我们现在推荐 fork 而非克隆。**这给你一个远程仓库来推送自定义内容。
|
||
>
|
||
> **如果你目前有带本地改动的克隆**，迁移到 fork：
|
||
> 1. 在 GitHub 上 Fork `nanocoai/nanoclaw`
|
||
> 2. 运行：
|
||
> ```
|
||
> git remote rename origin upstream
|
||
> git remote add origin https://github.com/<you>/nanoclaw.git
|
||
> git push --force origin main
|
||
> ```
|
||
> 即使你非常落后也可以——只需推送当前状态。
|
||
>
|
||
> **如果你之前通过旧系统应用了技能**，代码改动已经在你的工作树中——无需重做。你可以删除 `.nanoclaw/` 目录。未来的技能和更新使用基于分支的方法。
|
||
>
|
||
> **发现技能：**技能现在通过 Claude Code 的插件市场可用。在 Claude Code 中运行 `/plugin` 浏览和安装可用技能。
|
||
|
||
### 致技能贡献者
|
||
|
||
> **贡献技能**
|
||
>
|
||
> 贡献一个技能：
|
||
> 1. Fork `nanocoai/nanoclaw`
|
||
> 2. 从 `main` 创建分支并进行代码改动
|
||
> 3. 提交一个普通的 PR
|
||
>
|
||
> 就这样。我们将从你的 PR 创建 `skill/<name>` 分支，将你添加到 CONTRIBUTORS.md，并将 SKILL.md 添加到市场。CI 自动保持技能分支与 `main` 向前合并，使用 Claude 解决任何冲突。
|
||
>
|
||
> **想运行你自己的技能市场？**在你的 fork 上维护技能分支并创建一个市场仓库。提交 PR 将其添加到 NanoClaw 的自动发现市场中——或者用户可以通过 `/plugin marketplace add` 手动添加。
|