添加中文文档
This commit is contained in:
148
CONTRIBUTING.zh-CN.md
Normal file
148
CONTRIBUTING.zh-CN.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 贡献指南
|
||||
|
||||
## 开始之前
|
||||
|
||||
1. **检查是否已有相关工作。** 开始前先搜索已有的 PR 和 Issue：
|
||||
```bash
|
||||
gh pr list --repo nanocoai/nanoclaw --search "<你的功能>"
|
||||
gh issue list --repo nanocoai/nanoclaw --search "<你的功能>"
|
||||
```
|
||||
如果已有相关的 PR 或 Issue，请在其基础上推进，而不是重复劳动。
|
||||
|
||||
2. **检查理念一致性。** 阅读 [README.md 中的理念章节](README.md#philosophy)。源代码改动应仅限于 90% 以上用户都需要的功能。Skills 可以小众一些，但仍应具备超出单用户场景的通用性。
|
||||
|
||||
3. **一个 PR 只做一件事。** 每个 PR 只做一件事——修复一个 bug、添加一个 skill、做一项简化。不要在同一个 PR 中混杂无关的改动。
|
||||
|
||||
## 源代码改动
|
||||
|
||||
**接受：** Bug 修复、安全修复、简化、减少代码。
|
||||
|
||||
**不接受：** 新功能、新能力、兼容性适配、功能增强。这些应通过 skill 实现。
|
||||
|
||||
## Skills
|
||||
|
||||
NanoClaw 使用 [Claude Code skills](https://code.claude.com/docs/en/skills)——带可选附属文件的 Markdown 文件，用于教会 Claude 如何完成某项任务。NanoClaw 中有四种类型的 skill，各有不同用途。
|
||||
|
||||
### 为什么用 skill？
|
||||
|
||||
每个用户都应该拥有简洁、最小化的代码，只包含他们真正需要的功能。Skill 让用户可以有选择地为自己的 fork 添加功能，而不必继承他们不需要的功能代码。
|
||||
|
||||
### Skill 类型
|
||||
|
||||
#### 1. 功能 Skill（基于分支）
|
||||
|
||||
通过合并 Git 分支来为 NanoClaw 添加能力。SKILL.md 包含设置说明；实际代码位于 `skill/*` 分支上。
|
||||
|
||||
**位置：** `.claude/skills/`（仅在 `main` 分支上有说明文档），代码在 `skill/*` 分支
|
||||
|
||||
**示例：** `/add-telegram`、`/add-slack`、`/add-discord`、`/add-gmail`
|
||||
|
||||
**工作方式：**
|
||||
1. 用户执行 `/add-telegram`
|
||||
2. Claude 按照 SKILL.md 操作：fetch 并合并 `skill/telegram` 分支
|
||||
3. Claude 引导完成交互式设置（环境变量、Bot 创建等）
|
||||
|
||||
**贡献功能 skill：**
|
||||
1. Fork `nanocoai/nanoclaw`，基于 `main` 创建分支
|
||||
2. 进行代码改动（新增文件、修改源码、更新 `package.json` 等）
|
||||
3. 在 `.claude/skills/<name>/` 中添加 SKILL.md，包含设置说明——第一步应该是合并该分支
|
||||
4. 提交 PR。我们会基于你的工作创建 `skill/<name>` 分支
|
||||
|
||||
参考 `/add-telegram` 作为范例。完整系统设计见 [docs/skills-as-branches.md](docs/skills-as-branches.md)。
|
||||
|
||||
#### 2. 工具 Skill（含代码文件）
|
||||
|
||||
独立的工具，在 SKILL.md 之外还附带代码文件。SKILL.md 告诉 Claude 如何安装该工具；代码位于 skill 目录本身（如 `scripts/` 子目录中）。
|
||||
|
||||
**位置：** `.claude/skills/<name>/`，包含附属文件
|
||||
|
||||
**示例：** `/claw`（Python CLI，位于 `scripts/claw`）
|
||||
|
||||
**与功能 skill 的关键区别：** 无需合并分支。代码是自包含在 skill 目录中的，安装时复制到目标位置。
|
||||
|
||||
**规范：**
|
||||
- 将代码放在单独的文件中，不要内联在 SKILL.md 里
|
||||
- 使用 `${CLAUDE_SKILL_DIR}` 引用 skill 目录中的文件
|
||||
- SKILL.md 包含安装说明、使用文档和故障排除
|
||||
|
||||
#### 3. 操作 Skill（纯指令）
|
||||
|
||||
不涉及代码改动的流程和指南。SKILL.md 就是整个 skill——Claude 按照指令完成某项任务。
|
||||
|
||||
**位置：** `.claude/skills/`（在 `main` 分支上）
|
||||
|
||||
**示例：** `/setup`、`/debug`、`/customize`、`/update-nanoclaw`、`/update-skills`
|
||||
|
||||
**规范：**
|
||||
- 纯指令——没有代码文件，没有分支合并
|
||||
- 使用 `AskUserQuestion` 进行交互式提示
|
||||
- 这些 skill 保留在 `main` 分支上，所有用户始终可用
|
||||
|
||||
#### 4. 容器 Skill（Agent 运行时）
|
||||
|
||||
在 agent 容器内部运行的 skill，而非在宿主机上运行。这些 skill 教会容器内的 agent 如何使用工具、格式化输出或执行任务。容器启动时，它们会被同步到每个 agent group 的 `.claude/skills/` 目录中。
|
||||
|
||||
**位置：** `container/skills/<name>/`
|
||||
|
||||
**示例：** `agent-browser`（网页浏览）、`capabilities`（/capabilities 命令）、`status`（/status 命令）、`slack-formatting`（Slack mrkdwn 语法）
|
||||
|
||||
**关键区别：** 这些 skill 不由用户在宿主机上调用。它们由容器内的 Claude Code 加载，影响 agent 的行为方式。
|
||||
|
||||
**规范：**
|
||||
- 遵循相同的 SKILL.md + frontmatter 格式
|
||||
- 使用 `allowed-tools` frontmatter 来限定工具权限范围
|
||||
- 保持专注——agent 的上下文窗口由所有容器 skill 共享
|
||||
|
||||
### SKILL.md 格式
|
||||
|
||||
所有 skill 都遵循 [Claude Code skills 标准](https://code.claude.com/docs/en/skills)：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: 这个 skill 做什么以及何时使用。
|
||||
---
|
||||
|
||||
这里是说明...
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- SKILL.md 保持在 **500 行以内**——将细节移到单独的参考文件中
|
||||
- `name`：小写字母、数字和连字符，最多 64 个字符
|
||||
- `description`：必填——Claude 据此判断何时调用该 skill
|
||||
- 将代码放在单独的文件中，不要内联在 Markdown 中
|
||||
- 所有可用的 frontmatter 字段见 [skills 标准](https://code.claude.com/docs/en/skills)
|
||||
|
||||
## 测试
|
||||
|
||||
在提交前，在一个全新 clone 的环境中测试你的贡献。对于 skill，要完整地跑一遍端到端流程并验证其正常工作。
|
||||
|
||||
## Pull Request
|
||||
|
||||
### 提交前
|
||||
|
||||
1. **关联相关 Issue。** 如果你的 PR 解决了某个未关闭的 Issue，在描述中加入 `Closes #123`，这样合并后 Issue 会自动关闭。
|
||||
2. **充分测试。** 亲自运行该功能。对于 skill，在全新 clone 中测试。
|
||||
3. **检查安装专属文件。** 创建 PR 前，确认 diff 中没有安装专属文件（参见 CLAUDE.md 中的 PR Hygiene 章节）。
|
||||
4. **勾选正确的选项框。** 在 PR 模板中进行选择，标签会根据你的选择自动应用：
|
||||
|
||||
| 选项框 | 标签 |
|
||||
|--------|------|
|
||||
| 功能 Skill | `PR: Skill` + `PR: Feature` |
|
||||
| 工具 Skill | `PR: Skill` |
|
||||
| 操作/容器 Skill | `PR: Skill` |
|
||||
| 修复 | `PR: Fix` |
|
||||
| 简化 | `PR: Refactor` |
|
||||
| 文档 | `PR: Docs` |
|
||||
|
||||
### PR 描述
|
||||
|
||||
保持简洁。删除不适用的模板章节。描述应包含：
|
||||
|
||||
- **是什么**——PR 添加或改动了什么
|
||||
- **为什么**——动机是什么
|
||||
- **如何实现**——简要说明实现方式
|
||||
- **如何测试**——你做了什么来验证它能正常工作
|
||||
- **如何使用**——用户如何调用（针对 skill）
|
||||
|
||||
不要堆砌文字。几句清晰的话比冗长的段落更好。
|
||||
Reference in New Issue
Block a user