mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
Merge branch 'main' into mcp-tools-support
This commit is contained in:
yuchou87
+302
@@ -0,0 +1,302 @@
|
||||
# Contributing to PicoClaw
|
||||
|
||||
Thank you for your interest in contributing to PicoClaw! This project is a community-driven effort to build the lightweight and versatile personal AI assistant. We welcome contributions of all kinds: bug fixes, features, documentation, translations, and testing.
|
||||
|
||||
PicoClaw itself was substantially developed with AI assistance — we embrace this approach and have built our contribution process around it.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Ways to Contribute](#ways-to-contribute)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Making Changes](#making-changes)
|
||||
- [AI-Assisted Contributions](#ai-assisted-contributions)
|
||||
- [Pull Request Process](#pull-request-process)
|
||||
- [Branch Strategy](#branch-strategy)
|
||||
- [Code Review](#code-review)
|
||||
- [Communication](#communication)
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
We are committed to maintaining a welcoming and respectful community. Be kind, constructive, and assume good faith. Harassment or discrimination of any kind will not be tolerated.
|
||||
|
||||
---
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
- **Bug reports** — Open an issue using the bug report template.
|
||||
- **Feature requests** — Open an issue using the feature request template; discuss before implementing.
|
||||
- **Code** — Fix bugs or implement features. See the workflow below.
|
||||
- **Documentation** — Improve READMEs, docs, inline comments, or translations.
|
||||
- **Testing** — Run PicoClaw on new hardware, channels, or LLM providers and report your results.
|
||||
|
||||
For substantial new features, please open an issue first to discuss the design before writing code. This prevents wasted effort and ensures alignment with the project's direction.
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Fork** the repository on GitHub.
|
||||
2. **Clone** your fork locally:
|
||||
```bash
|
||||
git clone https://github.com/<your-username>/picoclaw.git
|
||||
cd picoclaw
|
||||
```
|
||||
3. Add the upstream remote:
|
||||
```bash
|
||||
git remote add upstream https://github.com/sipeed/picoclaw.git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Go 1.25 or later
|
||||
- `make`
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
make build # Build binary (runs go generate first)
|
||||
make generate # Run go generate only
|
||||
make check # Full pre-commit check: deps + fmt + vet + test
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
make test # Run all tests
|
||||
go test -run TestName -v ./pkg/session/ # Run a single test
|
||||
go test -bench=. -benchmem -run='^$' ./... # Run benchmarks
|
||||
```
|
||||
|
||||
### Code Style
|
||||
|
||||
```bash
|
||||
make fmt # Format code
|
||||
make vet # Static analysis
|
||||
make lint # Full linter run
|
||||
```
|
||||
|
||||
All CI checks must pass before a PR can be merged. Run `make check` locally before pushing to catch issues early.
|
||||
|
||||
---
|
||||
|
||||
## Making Changes
|
||||
|
||||
### Branching
|
||||
|
||||
Always branch off `main` and target `main` in your PR. Never push directly to `main` or any `release/*` branch:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
git checkout -b your-feature-branch
|
||||
```
|
||||
|
||||
Use descriptive branch names, e.g. `fix/telegram-timeout`, `feat/ollama-provider`, `docs/contributing-guide`.
|
||||
|
||||
### Commits
|
||||
|
||||
- Write clear, concise commit messages in English.
|
||||
- Use the imperative mood: "Add retry logic" not "Added retry logic".
|
||||
- Reference the related issue when relevant: `Fix session leak (#123)`.
|
||||
- Keep commits focused. One logical change per commit is preferred.
|
||||
- For minor cleanups or typo fixes, squash them into a single commit before opening a PR.
|
||||
- Refer to https://www.conventionalcommits.org/zh-hans/v1.0.0/
|
||||
|
||||
### Keeping Up to Date
|
||||
|
||||
Rebase your branch onto upstream `main` before opening a PR:
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI-Assisted Contributions
|
||||
|
||||
PicoClaw was built with substantial AI assistance, and we fully embrace AI-assisted development. However, contributors must understand their responsibilities when using AI tools.
|
||||
|
||||
### Disclosure Is Required
|
||||
|
||||
Every PR must disclose AI involvement using the PR template's **🤖 AI Code Generation** section. There are three levels:
|
||||
|
||||
| Level | Description |
|
||||
|---|---|
|
||||
| 🤖 Fully AI-generated | AI wrote the code; contributor reviewed and validated it |
|
||||
| 🛠️ Mostly AI-generated | AI produced the draft; contributor made significant modifications |
|
||||
| 👨💻 Mostly Human-written | Contributor led; AI provided suggestions or none at all |
|
||||
|
||||
Honest disclosure is expected. There is no stigma attached to any level — what matters is the quality of the contribution.
|
||||
|
||||
### You Are Responsible for What You Submit
|
||||
|
||||
Using AI to generate code does not reduce your responsibility as the contributor. Before opening a PR with AI-generated code, you must:
|
||||
|
||||
- **Read and understand** every line of the generated code.
|
||||
- **Test it** in a real environment (see the Test Environment section of the PR template).
|
||||
- **Check for security issues** — AI models can generate subtly insecure code (e.g., path traversal, injection, credential exposure). Review carefully.
|
||||
- **Verify correctness** — AI-generated logic can be plausible-sounding but wrong. Validate the behavior, not just the syntax.
|
||||
|
||||
PRs where it is clear the contributor has not read or tested the AI-generated code will be closed without review.
|
||||
|
||||
### AI-Generated Code Quality Standards
|
||||
|
||||
AI-generated contributions are held to the **same quality bar** as human-written code:
|
||||
|
||||
- It must pass all CI checks (`make check`).
|
||||
- It must be idiomatic Go and consistent with the existing codebase style.
|
||||
- It must not introduce unnecessary abstractions, dead code, or over-engineering.
|
||||
- It must include or update tests where appropriate.
|
||||
|
||||
### Security Review
|
||||
|
||||
AI-generated code requires extra security scrutiny. Pay special attention to:
|
||||
|
||||
- File path handling and sandbox escapes (see commit `244eb0b` for a real example)
|
||||
- External input validation in channel handlers and tool implementations
|
||||
- Credential or secret handling
|
||||
- Command execution (`exec.Command`, shell invocations)
|
||||
|
||||
If you are unsure whether a piece of AI-generated code is safe, say so in the PR — reviewers will help.
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### Before Opening a PR
|
||||
|
||||
- [ ] Run `make check` and ensure it passes locally.
|
||||
- [ ] Fill in the PR template completely, including the AI disclosure section.
|
||||
- [ ] Link any related issue(s) in the PR description.
|
||||
- [ ] Keep the PR focused. Avoid bundling unrelated changes together.
|
||||
|
||||
### PR Template Sections
|
||||
|
||||
The PR template asks for:
|
||||
|
||||
- **Description** — What does this change do and why?
|
||||
- **Type of Change** — Bug fix, feature, docs, or refactor.
|
||||
- **AI Code Generation** — Disclosure of AI involvement (required).
|
||||
- **Related Issue** — Link to the issue this addresses.
|
||||
- **Technical Context** — Reference URLs and reasoning (skip for pure docs PRs).
|
||||
- **Test Environment** — Hardware, OS, model/provider, and channels used for testing.
|
||||
- **Evidence** — Optional logs or screenshots demonstrating the change works.
|
||||
- **Checklist** — Self-review confirmation.
|
||||
|
||||
### PR Size
|
||||
|
||||
Prefer small, reviewable PRs. A PR that changes 200 lines across 5 files is much easier to review than one that changes 2000 lines across 30 files. If your feature is large, consider splitting it into a series of smaller, logically complete PRs.
|
||||
|
||||
---
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
### Long-Lived Branches
|
||||
|
||||
- **`main`** — the active development branch. All feature PRs target `main`. The branch is protected: direct pushes are not permitted, and at least one maintainer approval is required before merging.
|
||||
- **`release/x.y`** — stable release branches, cut from `main` when a version is ready to ship. These branches are more strictly protected than `main`.
|
||||
|
||||
### Requirements to Merge into `main`
|
||||
|
||||
A PR can only be merged when all of the following are satisfied:
|
||||
|
||||
1. **CI passes** — All GitHub Actions workflows (lint, test, build) must be green.
|
||||
2. **Reviewer approval** — At least one maintainer has approved the PR.
|
||||
3. **No unresolved review comments** — All review threads must be resolved.
|
||||
4. **PR template is complete** — Including AI disclosure and test environment.
|
||||
|
||||
### Who Can Merge
|
||||
|
||||
Only maintainers can merge PRs. Contributors cannot merge their own PRs, even if they have write access.
|
||||
|
||||
### Merge Strategy
|
||||
|
||||
We use **squash merge** for most PRs to keep the `main` history clean and readable. Each merged PR becomes a single commit referencing the PR number, e.g.:
|
||||
|
||||
```
|
||||
feat: Add Ollama provider support (#491)
|
||||
```
|
||||
|
||||
If a PR consists of multiple independent, well-separated commits that tell a clear story, a regular merge may be used at the maintainer's discretion.
|
||||
|
||||
### Release Branches
|
||||
|
||||
When a version is ready, maintainers cut a `release/x.y` branch from `main`. After that point:
|
||||
|
||||
- **New features are not backported.** The release branch receives no new functionality after it is cut.
|
||||
- **Security fixes and critical bug fixes are cherry-picked.** If a fix in `main` qualifies (security vulnerability, data loss, crash), maintainers will cherry-pick the relevant commit(s) onto the affected `release/x.y` branch and issue a patch release.
|
||||
|
||||
If you believe a fix in `main` should be backported to a release branch, note it in the PR description or open a separate issue. The decision rests with the maintainers.
|
||||
|
||||
Release branches have stricter protections than `main` and are never directly pushed to under any circumstances.
|
||||
|
||||
---
|
||||
|
||||
## Code Review
|
||||
|
||||
### For Contributors
|
||||
|
||||
- Respond to review comments within a reasonable time. If you need more time, say so.
|
||||
- When you update a PR in response to feedback, briefly note what changed (e.g., "Updated to use `sync.RWMutex` as suggested").
|
||||
- If you disagree with feedback, engage respectfully. Explain your reasoning; reviewers can be wrong too.
|
||||
- Do not force-push after a review has started — it makes it harder for reviewers to see what changed. Use additional commits instead; the maintainer will squash on merge.
|
||||
|
||||
### For Reviewers
|
||||
|
||||
Review for:
|
||||
|
||||
1. **Correctness** — Does the code do what it claims? Are there edge cases?
|
||||
2. **Security** — Especially for AI-generated code, tool implementations, and channel handlers.
|
||||
3. **Architecture** — Is the approach consistent with the existing design?
|
||||
4. **Simplicity** — Is there a simpler solution? Does this add unnecessary complexity?
|
||||
5. **Tests** — Are the changes covered by tests? Are existing tests still meaningful?
|
||||
|
||||
Be constructive and specific. "This could have a race condition if two goroutines call this concurrently — consider using a mutex here" is better than "this looks wrong".
|
||||
|
||||
|
||||
### Reviewer List
|
||||
Once your PR is submitted, you can reach out to the assigned reviewers listed in the following table.
|
||||
|
||||
|Function| Reviewer|
|
||||
|--- |--- |
|
||||
|Provider|@yinwm |
|
||||
|Channel |@yinwm |
|
||||
|Agent |@lxowalle|
|
||||
|Tools |@lxowalle|
|
||||
|SKill ||
|
||||
|MCP ||
|
||||
|Optimization|@lxowalle|
|
||||
|Security||
|
||||
|AI CI |@imguoguo|
|
||||
|UX ||
|
||||
|Document||
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
- **GitHub Issues** — Bug reports, feature requests, design discussions.
|
||||
- **GitHub Discussions** — General questions, ideas, community conversation.
|
||||
- **Pull Request comments** — Code-specific feedback.
|
||||
- **Wechat&Discord** — We will invite you when you have at least one merged PR
|
||||
|
||||
When in doubt, open an issue before writing code. It costs little and prevents wasted effort.
|
||||
|
||||
---
|
||||
|
||||
## A Note on the Project's AI-Driven Origin
|
||||
|
||||
PicoClaw's architecture was substantially designed and implemented with AI assistance, guided by human oversight. If you find something that looks odd or over-engineered, it may be an artifact of that process — opening an issue to discuss it is always welcome.
|
||||
|
||||
We believe AI-assisted development done responsibly produces great results. We also believe humans must remain accountable for what they ship. These two beliefs are not in conflict.
|
||||
|
||||
Thank you for contributing!
|
||||
@@ -0,0 +1,303 @@
|
||||
# 参与贡献 PicoClaw
|
||||
|
||||
感谢你对 PicoClaw 的关注！本项目是一个社区驱动的开源项目，目标是构建 轻量灵活,人人可用 的个人AI助手。我们欢迎一切形式的贡献：Bug 修复、新功能、文档、翻译和测试。
|
||||
|
||||
PicoClaw 本身在很大程度上是借助 AI 辅助开发的——我们拥抱这种方式，并围绕它构建了贡献流程。
|
||||
|
||||
## 目录
|
||||
|
||||
- [行为准则](#行为准则)
|
||||
- [贡献方式](#贡献方式)
|
||||
- [快速开始](#快速开始)
|
||||
- [开发环境配置](#开发环境配置)
|
||||
- [提交修改](#提交修改)
|
||||
- [AI 辅助贡献](#ai-辅助贡献)
|
||||
- [Pull Request 流程](#pull-request-流程)
|
||||
- [分支策略](#分支策略)
|
||||
- [代码审查](#代码审查)
|
||||
- [沟通渠道](#沟通渠道)
|
||||
|
||||
---
|
||||
|
||||
## 行为准则
|
||||
|
||||
我们致力于维护一个友好、互相尊重的社区环境。请保持善意、建设性的态度，并善意地理解他人。任何形式的骚扰或歧视均不被接受。
|
||||
|
||||
---
|
||||
|
||||
## 贡献方式
|
||||
|
||||
- **Bug 反馈** — 使用 Bug 报告模板提交 Issue。
|
||||
- **功能建议** — 使用功能请求模板提交 Issue，建议在开始实现前先进行讨论。
|
||||
- **代码贡献** — 修复 Bug 或实现新功能，参见下方工作流程。
|
||||
- **文档改进** — 完善 README、文档、代码注释或翻译。
|
||||
- **测试与验证** — 在新硬件、新渠道或新 LLM 提供商上运行 PicoClaw 并反馈结果。
|
||||
|
||||
对于较大的新功能，请先提交 Issue 讨论设计方案，再动手写代码。这能避免无效投入，也确保与项目方向保持一致。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 在 GitHub 上 **Fork** 本仓库。
|
||||
2. 将你的 Fork **克隆**到本地：
|
||||
```bash
|
||||
git clone https://github.com/<你的用户名>/picoclaw.git
|
||||
cd picoclaw
|
||||
```
|
||||
3. 添加上游远程仓库：
|
||||
```bash
|
||||
git remote add upstream https://github.com/sipeed/picoclaw.git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 开发环境配置
|
||||
|
||||
### 前置依赖
|
||||
|
||||
- Go 1.25 或更高版本
|
||||
- `make`
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
make build # 构建二进制文件（会先执行 go generate）
|
||||
make generate # 仅执行 go generate
|
||||
make check # 完整的提交前检查：deps + fmt + vet + test
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
make test # 运行所有测试
|
||||
go test -run TestName -v ./pkg/session/ # 运行单个测试
|
||||
go test -bench=. -benchmem -run='^$' ./... # 运行基准测试
|
||||
```
|
||||
|
||||
### 代码风格
|
||||
|
||||
```bash
|
||||
make fmt # 格式化代码
|
||||
make vet # 静态分析
|
||||
make lint # 完整的 lint 检查
|
||||
```
|
||||
|
||||
所有 CI 检查通过后 PR 才能被合并。推送代码前请先在本地运行 `make check`，提前发现问题。
|
||||
|
||||
---
|
||||
|
||||
## 提交修改
|
||||
|
||||
### 分支管理
|
||||
|
||||
始终从 `main` 分支切出，并在 PR 中以 `main` 为目标分支。不要直接向 `main` 或任何 `release/*` 分支推送代码：
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
git checkout -b 你的功能分支名
|
||||
```
|
||||
|
||||
请使用描述性的分支名，例如：`fix/telegram-timeout`、`feat/ollama-provider`、`docs/contributing-guide`。
|
||||
|
||||
### Commit 规范
|
||||
|
||||
- 使用英文撰写清晰、简洁的 commit 信息。
|
||||
- 使用祈使句：写 "Add retry logic"，而不是 "Added retry logic"。
|
||||
- 有关联 Issue 时请引用：`Fix session leak (#123)`。
|
||||
- 保持 commit 专注，每个 commit 只做一件事。
|
||||
- 对于小的清理或拼写修正，提 PR 前请将其合并为一个 commit。
|
||||
- 按照 https://www.conventionalcommits.org/zh-hans/v1.0.0/ 规范来撰写
|
||||
|
||||
### 保持与上游同步
|
||||
|
||||
提 PR 前，请将你的分支变基到上游 `main`：
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI 辅助贡献
|
||||
|
||||
PicoClaw 在很大程度上借助 AI 辅助开发，我们完全拥抱这种开发方式。但贡献者必须清楚地了解自己在使用 AI 工具时所承担的责任。
|
||||
|
||||
### 必须披露 AI 使用情况
|
||||
|
||||
每个 PR 都必须通过 PR 模板中的 **🤖 AI 代码生成** 部分披露 AI 参与情况，共分三个级别：
|
||||
|
||||
| 级别 | 说明 |
|
||||
|---|---|
|
||||
| 🤖 完全由 AI 生成 | AI 编写代码，贡献者负责审查和验证 |
|
||||
| 🛠️ 主要由 AI 生成 | AI 起草，贡献者做了较大修改 |
|
||||
| 👨💻 主要由人工编写 | 贡献者主导，AI 仅提供辅助或未使用 AI |
|
||||
|
||||
我们期望你诚实填写。三种级别均可接受，没有任何歧视——重要的是贡献的质量。
|
||||
|
||||
### 你对提交的代码负全责
|
||||
|
||||
使用 AI 生成代码并不能减轻你作为贡献者的责任。在提交含有 AI 生成代码的 PR 之前，你必须：
|
||||
|
||||
- **逐行阅读并理解**生成的代码。
|
||||
- **在真实环境中测试**（参见 PR 模板中的测试环境部分）。
|
||||
- **检查安全问题** — AI 模型可能生成存在安全隐患的代码（如路径穿越、注入攻击、凭据泄露等），请仔细审查。
|
||||
- **验证正确性** — AI 生成的逻辑可能听起来合理但实际上是错误的，请验证行为，而不仅仅是语法。
|
||||
|
||||
如果明显可以看出贡献者没有阅读或测试 AI 生成的代码，该 PR 将被直接关闭，不予审查。
|
||||
|
||||
### AI 生成代码的质量标准
|
||||
|
||||
AI 生成的代码与人工编写的代码遵循**相同的质量要求**：
|
||||
|
||||
- 必须通过所有 CI 检查（`make check`）。
|
||||
- 必须符合 Go 惯用写法，并与现有代码库的风格保持一致。
|
||||
- 不得引入不必要的抽象、死代码或过度设计。
|
||||
- 须在适当的地方包含或更新测试。
|
||||
|
||||
### 安全审查
|
||||
|
||||
AI 生成的代码需要格外仔细的安全审查。请特别关注以下方面：
|
||||
|
||||
- 文件路径处理与沙箱逃逸（项目历史中的 commit `244eb0b` 就是真实案例）
|
||||
- channel 处理器和 tool 实现中的外部输入校验
|
||||
- 凭据或密钥的处理
|
||||
- 命令执行（`exec.Command`、shell 调用等）
|
||||
|
||||
如果你不确定某段 AI 生成代码是否安全，请在 PR 中说明——审查者会帮助判断。
|
||||
|
||||
---
|
||||
|
||||
## Pull Request 流程
|
||||
|
||||
### 提 PR 前的检查
|
||||
|
||||
- [ ] 在本地运行 `make check` 并确认通过。
|
||||
- [ ] 完整填写 PR 模板，包括 AI 披露部分。
|
||||
- [ ] 在 PR 描述中关联相关 Issue。
|
||||
- [ ] 保持 PR 专注，避免将不相关的修改混在一起。
|
||||
|
||||
### PR 模板各部分说明
|
||||
|
||||
PR 模板要求填写：
|
||||
|
||||
- **描述** — 这个改动做了什么，为什么要做？
|
||||
- **变更类型** — Bug 修复、新功能、文档或重构。
|
||||
- **AI 代码生成** — AI 参与情况披露（必填）。
|
||||
- **关联 Issue** — 此 PR 解决的 Issue 链接。
|
||||
- **技术背景** — 参考链接和设计理由（纯文档类 PR 可跳过）。
|
||||
- **测试环境** — 用于测试的硬件、操作系统、模型/提供商和渠道。
|
||||
- **验证证据** — 可选的日志或截图，用于证明改动有效。
|
||||
- **检查清单** — 自我审查确认。
|
||||
|
||||
### PR 规模
|
||||
|
||||
请尽量提交小而易于审查的 PR。一个涉及 5 个文件共 200 行改动的 PR，远比涉及 30 个文件共 2000 行改动的 PR 容易审查。如果你的功能较大，可以考虑将其拆分为一系列逻辑完整的小 PR。
|
||||
|
||||
---
|
||||
|
||||
## 分支策略
|
||||
|
||||
### 长期分支
|
||||
|
||||
- **`main`** — 活跃开发分支。所有功能 PR 均以 `main` 为目标。该分支受保护：禁止直接推送，合并前必须获得至少一名维护者的批准。
|
||||
- **`release/x.y`** — 稳定发布分支，在某个版本准备发布时从 `main` 切出。这些分支的保护级别高于 `main`。
|
||||
|
||||
### 合并到 `main` 的前提条件
|
||||
|
||||
PR 必须同时满足以下所有条件，才能被合并：
|
||||
|
||||
1. **CI 全部通过** — 所有 GitHub Actions 工作流（lint、test、build）均为绿色。
|
||||
2. **获得审查者批准** — 至少一名维护者已批准该 PR。
|
||||
3. **无未解决的审查意见** — 所有审查讨论线程均已关闭。
|
||||
4. **PR 模板填写完整** — 包括 AI 披露和测试环境信息。
|
||||
|
||||
### 谁可以合并
|
||||
|
||||
只有维护者才能合并 PR。贡献者不能合并自己的 PR，即使拥有写权限也不行。
|
||||
|
||||
### 合并策略
|
||||
|
||||
为保持 `main` 历史清晰可读，我们对大多数 PR 使用 **Squash Merge**。每个合并的 PR 变为一个包含 PR 编号的单独 commit，例如：
|
||||
|
||||
```
|
||||
feat: Add Ollama provider support (#491)
|
||||
```
|
||||
|
||||
如果一个 PR 包含多个独立、结构清晰、能讲述完整故事的 commit，维护者可视情况使用普通 merge。
|
||||
|
||||
### Release 分支
|
||||
|
||||
当某个版本准备就绪时，维护者会从 `main` 切出 `release/x.y` 分支。此后：
|
||||
|
||||
- **新功能不会被回溯（backport）。** Release 分支切出后，不再接收任何新功能。
|
||||
- **安全修复和关键 Bug 修复会被 cherry-pick 进来。** 若 `main` 上的某个修复属于安全漏洞、数据丢失或崩溃类问题，维护者会将相关 commit cherry-pick 到受影响的 `release/x.y` 分支，并发布补丁版本。
|
||||
|
||||
如果你认为 `main` 上的某个修复应该被回溯到某个 release 分支，请在 PR 描述中注明，或单独开一个 Issue 说明。最终决定由维护者做出。
|
||||
|
||||
Release 分支的保护级别高于 `main`，在任何情况下均不允许直接推送。
|
||||
|
||||
---
|
||||
|
||||
## 代码审查
|
||||
|
||||
### 对贡献者的建议
|
||||
|
||||
- 在合理时间内回复审查意见。如果需要更多时间，请告知。
|
||||
- 更新 PR 以响应反馈时，简要说明改动内容（例如："按建议改用了 `sync.RWMutex`"）。
|
||||
- 如果你不同意某条反馈，请礼貌地阐述你的理由——审查者也可能有判断失误的时候。
|
||||
- 审查开始后请不要 force push——这会让审查者难以追踪变化。请使用额外的 commit，维护者在合并时会进行 squash。
|
||||
|
||||
### 对审查者的建议
|
||||
|
||||
审查重点：
|
||||
|
||||
1. **正确性** — 代码是否实现了其声称的功能？是否存在边界情况？
|
||||
2. **安全性** — 对 AI 生成代码、tool 实现和 channel 处理器尤其需要关注。
|
||||
3. **架构** — 实现方式是否与现有设计一致？
|
||||
4. **简洁性** — 是否有更简单的方案？是否引入了不必要的复杂度？
|
||||
5. **测试** — 改动是否有测试覆盖？现有测试是否仍然有意义？
|
||||
|
||||
请给出建设性且具体的反馈。"如果两个 goroutine 同时调用这个函数可能会有竞态条件，建议在这里加一个 mutex" 远比 "这里看起来有问题" 更有帮助。
|
||||
|
||||
### 审查者列表
|
||||
提交对应PR后，可以参考下表联系对应的审查人员沟通
|
||||
|
||||
|Function| Reviewer|
|
||||
|--- |--- |
|
||||
|Provider|@yinwm |
|
||||
|Channel |@yinwm |
|
||||
|Agent |@lxowalle|
|
||||
|Tools |@lxowalle|
|
||||
|SKill ||
|
||||
|MCP ||
|
||||
|Optimization|@lxowalle|
|
||||
|Security||
|
||||
|AI CI |@imguoguo|
|
||||
|UX ||
|
||||
|Document||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 沟通渠道
|
||||
|
||||
- **GitHub Issues** — Bug 报告、功能建议、设计讨论。
|
||||
- **GitHub Discussions** — 一般性问题、想法交流、社区讨论。
|
||||
- **Pull Request 评论** — 与具体代码相关的反馈。
|
||||
- **Wechat&Discord** — 当你有至少一个已合并的PR后，我们会邀请你加入开发者交流群
|
||||
|
||||
有疑问时，请先开 Issue 讨论，再动手写代码。这几乎没有成本，却能避免大量无效投入。
|
||||
|
||||
---
|
||||
|
||||
## 关于本项目的 AI 驱动起源
|
||||
|
||||
PicoClaw 的架构在人工监督下，经由 AI 辅助完成了大量设计和实现工作。如果你发现某处看起来奇怪或过度设计，这可能是该过程留下的痕迹——欢迎提 Issue 讨论。
|
||||
|
||||
我们相信，负责任地使用 AI 辅助开发能产生优秀的成果。我们同样相信，人类必须对自己提交的内容负责。这两点并不矛盾。
|
||||
|
||||
感谢你的贡献！
|
||||
+116
-342
@@ -14,7 +14,8 @@
|
||||
<a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
|
||||
</p>
|
||||
|
||||
**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
|
||||
**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
@@ -42,14 +43,15 @@
|
||||
|
||||
> [!CAUTION]
|
||||
> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明**
|
||||
> * **无加密货币 (NO CRYPTO):** PicoClaw **没有** 发行任何官方代币、Token 或虚拟货币。所有在 `pump.fun` 或其他交易平台上的相关声称均为 **诈骗**。
|
||||
> * **官方域名:** 唯一的官方网站是 **[picoclaw.io](https://picoclaw.io)**，公司官网是 **[sipeed.com](https://sipeed.com)**。
|
||||
> * **警惕:** 许多 `.ai/.org/.com/.net/...` 后缀的域名被第三方抢注，请勿轻信。
|
||||
> * **注意:** picoclaw正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在1.0正式版发布前，请不要将其部署到生产环境中
|
||||
> * **注意:** picoclaw最近合并了大量PRs，近期版本可能内存占用较大(10~20MB)，我们将在功能较为收敛后进行资源占用优化.
|
||||
|
||||
>
|
||||
> - **无加密货币 (NO CRYPTO):** PicoClaw **没有** 发行任何官方代币、Token 或虚拟货币。所有在 `pump.fun` 或其他交易平台上的相关声称均为 **诈骗**。
|
||||
> - **官方域名:** 唯一的官方网站是 **[picoclaw.io](https://picoclaw.io)**，公司官网是 **[sipeed.com](https://sipeed.com)**。
|
||||
> - **警惕:** 许多 `.ai/.org/.com/.net/...` 后缀的域名被第三方抢注，请勿轻信。
|
||||
> - **注意:** picoclaw正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在1.0正式版发布前，请不要将其部署到生产环境中
|
||||
> - **注意:** picoclaw最近合并了大量PRs，近期版本可能内存占用较大(10~20MB)，我们将在功能较为收敛后进行资源占用优化.
|
||||
|
||||
## 📢 新闻 (News)
|
||||
|
||||
2026-02-16 🎉 PicoClaw 在一周内突破了12K star! 感谢大家的关注！PicoClaw 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](docs/picoclaw_community_roadmap_260216.md), 期待你的参与！
|
||||
|
||||
2026-02-13 🎉 **PicoClaw 在 4 天内突破 5000 Stars！** 感谢社区的支持！由于正值中国春节假期，PR 和 Issue 涌入较多，我们正在利用这段时间敲定 **项目路线图 (Roadmap)** 并组建 **开发者群组**，以便加速 PicoClaw 的开发。
|
||||
@@ -69,12 +71,12 @@
|
||||
|
||||
🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由“人机回环 (Human-in-the-loop)”微调。
|
||||
|
||||
| | OpenClaw | NanoBot | **PicoClaw** |
|
||||
| --- | --- | --- | --- |
|
||||
| **语言** | TypeScript | Python | **Go** |
|
||||
| **RAM** | >1GB | >100MB | **< 10MB** |
|
||||
| **启动时间**</br>(0.8GHz core) | >500s | >30s | **<1s** |
|
||||
| **成本** | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板**</br>**低至 $10** |
|
||||
| | OpenClaw | NanoBot | **PicoClaw** |
|
||||
| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
|
||||
| **语言** | TypeScript | Python | **Go** |
|
||||
| **RAM** | >1GB | >100MB | **< 10MB** |
|
||||
| **启动时间**</br>(0.8GHz core) | >500s | >30s | **<1s** |
|
||||
| **成本** | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板**</br>**低至 $10** |
|
||||
|
||||
<img src="assets/compare.jpg" alt="PicoClaw" width="512">
|
||||
|
||||
@@ -101,9 +103,12 @@
|
||||
</table>
|
||||
|
||||
### 📱 在手机上轻松运行
|
||||
|
||||
picoclaw 可以将你10年前的老旧手机废物利用，变身成为你的AI助理！快速指南:
|
||||
|
||||
1. 先去应用商店下载安装Termux
|
||||
2. 打开后执行指令
|
||||
|
||||
```bash
|
||||
# 注意: 下面的v0.1.1 可以换为你实际看到的最新版本
|
||||
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
|
||||
@@ -111,19 +116,17 @@ chmod +x picoclaw-linux-arm64
|
||||
pkg install proot
|
||||
termux-chroot ./picoclaw-linux-arm64 onboard
|
||||
```
|
||||
然后跟随下面的“快速开始”章节继续配置picoclaw即可使用！
|
||||
|
||||
然后跟随下面的“快速开始”章节继续配置picoclaw即可使用！
|
||||
<img src="assets/termux.jpg" alt="PicoClaw" width="512">
|
||||
|
||||
|
||||
|
||||
|
||||
### 🐜 创新的低占用部署
|
||||
|
||||
PicoClaw 几乎可以部署在任何 Linux 设备上！
|
||||
|
||||
* $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手。
|
||||
* $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维。
|
||||
* $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控。
|
||||
- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手。
|
||||
- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维。
|
||||
- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控。
|
||||
|
||||
[https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4](https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4)
|
||||
|
||||
@@ -253,15 +256,14 @@ picoclaw onboard
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
|
||||
|
||||
**3. 获取 API Key**
|
||||
|
||||
* **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
|
||||
* **网络搜索** (可选): [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月)
|
||||
- **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
|
||||
- **网络搜索** (可选): [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月)
|
||||
|
||||
> **注意**: 完整的配置模板请参考 `config.example.json`。
|
||||
|
||||
@@ -278,260 +280,28 @@ picoclaw agent -m "2+2 等于几？"
|
||||
|
||||
## 💬 聊天应用集成 (Chat Apps)
|
||||
|
||||
通过 Telegram, Discord, 钉钉或企业微信与您的 PicoClaw 对话。
|
||||
|
||||
| 渠道 | 设置难度 |
|
||||
| --- | --- |
|
||||
| **Telegram** | 简单 (仅需 token) |
|
||||
| **Discord** | 简单 (bot token + intents) |
|
||||
| **QQ** | 简单 (AppID + AppSecret) |
|
||||
| **钉钉 (DingTalk)** | 中等 (应用凭证) |
|
||||
| **企业微信 (WeCom)** | 中等 (企业ID + Webhook配置) |
|
||||
|
||||
<details>
|
||||
<summary><b>Telegram</b> (推荐)</summary>
|
||||
|
||||
**1. 创建机器人**
|
||||
|
||||
* 打开 Telegram，搜索 `@BotFather`
|
||||
* 发送 `/newbot`，按照提示操作
|
||||
* 复制 token
|
||||
|
||||
**2. 配置**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
> 从 Telegram 上的 `@userinfobot` 获取您的用户 ID。
|
||||
|
||||
**3. 运行**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
**1. 创建机器人**
|
||||
|
||||
* 前往 [https://discord.com/developers/applications](https://discord.com/developers/applications)
|
||||
* Create an application → Bot → Add Bot
|
||||
* 复制 bot token
|
||||
|
||||
**2. 开启 Intents**
|
||||
|
||||
* 在 Bot 设置中，开启 **MESSAGE CONTENT INTENT**
|
||||
* (可选) 如果计划基于成员数据使用白名单，开启 **SERVER MEMBERS INTENT**
|
||||
|
||||
**3. 获取您的 User ID**
|
||||
|
||||
* Discord 设置 → Advanced → 开启 **Developer Mode**
|
||||
* 右键点击您的头像 → **Copy User ID**
|
||||
|
||||
**4. 配置**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"discord": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"],
|
||||
"mention_only": false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
**5. 邀请机器人**
|
||||
|
||||
* OAuth2 → URL Generator
|
||||
* Scopes: `bot`
|
||||
* Bot Permissions: `Send Messages`, `Read Message History`
|
||||
* 打开生成的邀请 URL，将机器人添加到您的服务器
|
||||
|
||||
**6. 运行**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
**1. 创建机器人**
|
||||
|
||||
* 前往 [QQ 开放平台](https://q.qq.com/#)
|
||||
* 创建应用 → 获取 **AppID** 和 **AppSecret**
|
||||
|
||||
**2. 配置**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"qq": {
|
||||
"enabled": true,
|
||||
"app_id": "YOUR_APP_ID",
|
||||
"app_secret": "YOUR_APP_SECRET",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
> 将 `allow_from` 设为空以允许所有用户，或指定 QQ 号以限制访问。
|
||||
|
||||
**3. 运行**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>钉钉 (DingTalk)</b></summary>
|
||||
|
||||
**1. 创建机器人**
|
||||
|
||||
* 前往 [开放平台](https://open.dingtalk.com/)
|
||||
* 创建内部应用
|
||||
* 复制 Client ID 和 Client Secret
|
||||
|
||||
**2. 配置**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"dingtalk": {
|
||||
"enabled": true,
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"client_secret": "YOUR_CLIENT_SECRET",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
> 将 `allow_from` 设为空以允许所有用户，或指定 ID 以限制访问。
|
||||
|
||||
**3. 运行**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>企业微信 (WeCom)</b></summary>
|
||||
|
||||
PicoClaw 支持两种企业微信集成方式：
|
||||
|
||||
**选项1: 智能机器人 (WeCom Bot)** - 设置更简单，支持群聊
|
||||
**选项2: 自建应用 (WeCom App)** - 功能更丰富，支持主动推送消息
|
||||
|
||||
详见 [企业微信自建应用配置指南](docs/wecom-app-configuration.md)。
|
||||
|
||||
**快速设置 - 智能机器人：**
|
||||
|
||||
**1. 创建机器人**
|
||||
|
||||
* 前往企业微信管理后台 → 群聊 → 添加群机器人
|
||||
* 复制 Webhook URL (格式: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
|
||||
|
||||
**2. 配置**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"wecom": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
|
||||
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
|
||||
"webhook_host": "0.0.0.0",
|
||||
"webhook_port": 18793,
|
||||
"webhook_path": "/webhook/wecom",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**快速设置 - 自建应用：**
|
||||
|
||||
**1. 创建应用**
|
||||
|
||||
* 前往企业微信管理后台 → 应用管理 → 创建应用
|
||||
* 复制 **AgentId** 和 **Secret**
|
||||
* 前往"我的企业"页面，复制 **CorpID**
|
||||
|
||||
**2. 配置接收消息**
|
||||
|
||||
* 在应用详情页，点击"接收消息" → "设置API"
|
||||
* 设置 URL 为 `http://your-server:18792/webhook/wecom-app`
|
||||
* 生成 **Token** 和 **EncodingAESKey**
|
||||
|
||||
**3. 配置**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"wecom_app": {
|
||||
"enabled": true,
|
||||
"corp_id": "wwxxxxxxxxxxxxxxxx",
|
||||
"corp_secret": "YOUR_CORP_SECRET",
|
||||
"agent_id": 1000002,
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
|
||||
"webhook_host": "0.0.0.0",
|
||||
"webhook_port": 18792,
|
||||
"webhook_path": "/webhook/wecom-app",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**4. 运行**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
|
||||
```
|
||||
|
||||
> **注意**: 自建应用需要开放 18792 端口用于接收 Webhook 回调。生产环境建议使用反向代理配置 HTTPS。
|
||||
|
||||
</details>
|
||||
PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
|
||||
|
||||
### 核心渠道
|
||||
|
||||
| 渠道 | 设置难度 | 特性说明 | 文档链接 |
|
||||
| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| **Telegram** | ⭐ 简单 | 推荐，支持语音转文字，长轮询无需公网 | [查看文档](docs/channels/telegram/README.zh.md) |
|
||||
| **Discord** | ⭐ 简单 | Socket Mode，支持群组/私信，Bot 生态成熟 | [查看文档](docs/channels/discord/README.zh.md) |
|
||||
| **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](docs/channels/slack/README.zh.md) |
|
||||
| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](docs/channels/qq/README.zh.md) |
|
||||
| **钉钉 (DingTalk)** | ⭐⭐ 中等 | Stream 模式无需公网，企业办公首选 | [查看文档](docs/channels/dingtalk/README.zh.md) |
|
||||
| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)和自建应用(API) | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) |
|
||||
| **飞书 (Feishu)** | ⭐⭐⭐ 较难 | 企业级协作，功能丰富 | [查看文档](docs/channels/feishu/README.zh.md) |
|
||||
| **Line** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](docs/channels/line/README.zh.md) |
|
||||
| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](docs/channels/onebot/README.zh.md) |
|
||||
| **MaixCam** | ⭐ 简单 | 专为 AI 摄像头设计的硬件集成通道 | [查看文档](docs/channels/maixcam/README.zh.md) |
|
||||
|
||||
## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> 加入 Agent 社交网络
|
||||
|
||||
只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
|
||||
|
||||
**阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai)
|
||||
\*\*阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai)
|
||||
|
||||
## ⚙️ 配置详解
|
||||
|
||||
@@ -567,7 +337,6 @@ PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md`
|
||||
- Check my email for important messages
|
||||
- Review my calendar for upcoming events
|
||||
- Check the weather forecast
|
||||
|
||||
```
|
||||
|
||||
Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。
|
||||
@@ -580,22 +349,23 @@ Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具
|
||||
# Periodic Tasks
|
||||
|
||||
## Quick Tasks (respond directly)
|
||||
|
||||
- Report current time
|
||||
|
||||
## Long Tasks (use spawn for async)
|
||||
|
||||
- Search the web for AI news and summarize
|
||||
- Check email and report important messages
|
||||
|
||||
```
|
||||
|
||||
**关键行为：**
|
||||
|
||||
| 特性 | 描述 |
|
||||
| --- | --- |
|
||||
| **spawn** | 创建异步子 Agent，不阻塞主心跳进程 |
|
||||
| **独立上下文** | 子 Agent 拥有独立上下文，无会话历史 |
|
||||
| 特性 | 描述 |
|
||||
| ---------------- | ---------------------------------------- |
|
||||
| **spawn** | 创建异步子 Agent，不阻塞主心跳进程 |
|
||||
| **独立上下文** | 子 Agent 拥有独立上下文，无会话历史 |
|
||||
| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
|
||||
| **非阻塞** | spawn 后，心跳继续处理下一个任务 |
|
||||
| **非阻塞** | spawn 后，心跳继续处理下一个任务 |
|
||||
|
||||
#### 子 Agent 通信原理
|
||||
|
||||
@@ -625,35 +395,34 @@ Agent 读取 HEARTBEAT.md
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
| 选项 | 默认值 | 描述 |
|
||||
| --- | --- | --- |
|
||||
| `enabled` | `true` | 启用/禁用心跳 |
|
||||
| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) |
|
||||
| 选项 | 默认值 | 描述 |
|
||||
| ---------- | ------ | ---------------------------- |
|
||||
| `enabled` | `true` | 启用/禁用心跳 |
|
||||
| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) |
|
||||
|
||||
**环境变量:**
|
||||
|
||||
* `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
|
||||
* `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
|
||||
- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
|
||||
- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
|
||||
|
||||
### 提供商 (Providers)
|
||||
|
||||
> [!NOTE]
|
||||
> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。
|
||||
|
||||
| 提供商 | 用途 | 获取 API Key |
|
||||
| --- | --- | --- |
|
||||
| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM (智谱直连) | [bigmodel.cn](bigmodel.cn) |
|
||||
| `openrouter(待测试)` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic(待测试)` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai(待测试)` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek(待测试)` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM (通义千问) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM (Cerebras 直连) | [cerebras.ai](https://cerebras.ai) |
|
||||
| 提供商 | 用途 | 获取 API Key |
|
||||
| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
|
||||
| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM (智谱直连) | [bigmodel.cn](bigmodel.cn) |
|
||||
| `openrouter(待测试)` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic(待测试)` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai(待测试)` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek(待测试)` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM (通义千问) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM (Cerebras 直连) | [cerebras.ai](https://cerebras.ai) |
|
||||
|
||||
### 模型配置 (model_list)
|
||||
|
||||
@@ -668,25 +437,25 @@ Agent 读取 HEARTBEAT.md
|
||||
|
||||
#### 📋 所有支持的厂商
|
||||
|
||||
| 厂商 | `model` 前缀 | 默认 API Base | 协议 | 获取 API Key |
|
||||
|------|-------------|---------------|------|--------------|
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取密钥](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取密钥](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取密钥](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取密钥](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取密钥](https://console.groq.com) |
|
||||
| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取密钥](https://platform.moonshot.cn) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取密钥](https://dashscope.console.aliyun.com) |
|
||||
| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取密钥](https://build.nvidia.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需密钥） |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取密钥](https://openrouter.ai/keys) |
|
||||
| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |
|
||||
| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取密钥](https://cerebras.ai) |
|
||||
| **火山引擎** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取密钥](https://console.volcengine.com) |
|
||||
| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | 自定义 | 仅 OAuth |
|
||||
| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
|
||||
| 厂商 | `model` 前缀 | 默认 API Base | 协议 | 获取 API Key |
|
||||
| ------------------- | ----------------- | --------------------------------------------------- | --------- | ----------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取密钥](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取密钥](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取密钥](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取密钥](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取密钥](https://console.groq.com) |
|
||||
| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取密钥](https://platform.moonshot.cn) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取密钥](https://dashscope.console.aliyun.com) |
|
||||
| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取密钥](https://build.nvidia.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需密钥） |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取密钥](https://openrouter.ai/keys) |
|
||||
| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |
|
||||
| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取密钥](https://cerebras.ai) |
|
||||
| **火山引擎** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取密钥](https://console.volcengine.com) |
|
||||
| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | 自定义 | 仅 OAuth |
|
||||
| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
|
||||
|
||||
#### 基础配置示例
|
||||
|
||||
@@ -720,6 +489,7 @@ Agent 读取 HEARTBEAT.md
|
||||
#### 各厂商配置示例
|
||||
|
||||
**OpenAI**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "gpt-5.2",
|
||||
@@ -729,6 +499,7 @@ Agent 读取 HEARTBEAT.md
|
||||
```
|
||||
|
||||
**智谱 AI (GLM)**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "glm-4.7",
|
||||
@@ -738,6 +509,7 @@ Agent 读取 HEARTBEAT.md
|
||||
```
|
||||
|
||||
**DeepSeek**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "deepseek-chat",
|
||||
@@ -747,6 +519,7 @@ Agent 读取 HEARTBEAT.md
|
||||
```
|
||||
|
||||
**Anthropic (使用 OAuth)**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "claude-sonnet-4.6",
|
||||
@@ -754,9 +527,11 @@ Agent 读取 HEARTBEAT.md
|
||||
"auth_method": "oauth"
|
||||
}
|
||||
```
|
||||
|
||||
> 运行 `picoclaw auth login --provider anthropic` 来设置 OAuth 凭证。
|
||||
|
||||
**Ollama (本地)**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "llama3",
|
||||
@@ -765,6 +540,7 @@ Agent 读取 HEARTBEAT.md
|
||||
```
|
||||
|
||||
**自定义代理/API**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "my-custom-model",
|
||||
@@ -802,6 +578,7 @@ Agent 读取 HEARTBEAT.md
|
||||
旧的 `providers` 配置格式**已弃用**，但为向后兼容仍支持。
|
||||
|
||||
**旧配置（已弃用）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
@@ -820,6 +597,7 @@ Agent 读取 HEARTBEAT.md
|
||||
```
|
||||
|
||||
**新配置（推荐）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
@@ -844,7 +622,7 @@ Agent 读取 HEARTBEAT.md
|
||||
|
||||
**1. 获取 API key 和 base URL**
|
||||
|
||||
* 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
|
||||
- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
|
||||
|
||||
**2. 配置**
|
||||
|
||||
@@ -866,7 +644,6 @@ Agent 读取 HEARTBEAT.md
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
**3. 运行**
|
||||
@@ -946,30 +723,29 @@ picoclaw agent -m "你好"
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## CLI 命令行参考
|
||||
|
||||
| 命令 | 描述 |
|
||||
| --- | --- |
|
||||
| `picoclaw onboard` | 初始化配置和工作区 |
|
||||
| `picoclaw agent -m "..."` | 与 Agent 对话 |
|
||||
| `picoclaw agent` | 交互式聊天模式 |
|
||||
| `picoclaw gateway` | 启动网关 (Gateway) |
|
||||
| `picoclaw status` | 显示状态 |
|
||||
| `picoclaw cron list` | 列出所有定时任务 |
|
||||
| `picoclaw cron add ...` | 添加定时任务 |
|
||||
| 命令 | 描述 |
|
||||
| ------------------------- | ------------------ |
|
||||
| `picoclaw onboard` | 初始化配置和工作区 |
|
||||
| `picoclaw agent -m "..."` | 与 Agent 对话 |
|
||||
| `picoclaw agent` | 交互式聊天模式 |
|
||||
| `picoclaw gateway` | 启动网关 (Gateway) |
|
||||
| `picoclaw status` | 显示状态 |
|
||||
| `picoclaw cron list` | 列出所有定时任务 |
|
||||
| `picoclaw cron add ...` | 添加定时任务 |
|
||||
|
||||
### 定时任务 / 提醒 (Scheduled Tasks)
|
||||
|
||||
PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
|
||||
|
||||
* **一次性提醒**: "Remind me in 10 minutes" (10分钟后提醒我) → 10分钟后触发一次
|
||||
* **重复任务**: "Remind me every 2 hours" (每2小时提醒我) → 每2小时触发
|
||||
* **Cron 表达式**: "Remind me at 9am daily" (每天上午9点提醒我) → 使用 cron 表达式
|
||||
- **一次性提醒**: "Remind me in 10 minutes" (10分钟后提醒我) → 10分钟后触发一次
|
||||
- **重复任务**: "Remind me every 2 hours" (每2小时提醒我) → 每2小时触发
|
||||
- **Cron 表达式**: "Remind me at 9am daily" (每天上午9点提醒我) → 使用 cron 表达式
|
||||
|
||||
任务存储在 `~/.picoclaw/workspace/cron/` 中并自动处理。
|
||||
|
||||
@@ -983,7 +759,7 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
|
||||
|
||||
用户群组：
|
||||
|
||||
Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
|
||||
Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
|
||||
|
||||
<img src="assets/wechat.png" alt="PicoClaw" width="512">
|
||||
|
||||
@@ -997,6 +773,7 @@ Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
|
||||
|
||||
1. 在 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (每月 2000 次免费查询)
|
||||
2. 添加到 `~/.picoclaw/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
@@ -1013,11 +790,8 @@ Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 遇到内容过滤错误 (Content Filtering Errors)
|
||||
|
||||
某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。
|
||||
@@ -1030,10 +804,10 @@ Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
|
||||
|
||||
## 📝 API Key 对比
|
||||
|
||||
| 服务 | 免费层级 | 适用场景 |
|
||||
| --- | --- | --- |
|
||||
| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
|
||||
| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 |
|
||||
| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
|
||||
| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
|
||||
| **Cerebras** | 提供免费层级 | 极速推理 (Llama, Qwen 等) |
|
||||
| 服务 | 免费层级 | 适用场景 |
|
||||
| ---------------- | -------------- | ----------------------------- |
|
||||
| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
|
||||
| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 |
|
||||
| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
|
||||
| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
|
||||
| **Cerebras** | 提供免费层级 | 极速推理 (Llama, Qwen 等) |
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 141 KiB After Width: | Height: | Size: 141 KiB |
@@ -10,6 +10,7 @@ import (
|
||||
"os"
|
||||
"os/signal"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/sipeed/picoclaw/pkg/agent"
|
||||
@@ -121,8 +122,17 @@ func gatewayCmd() {
|
||||
agentLoop.SetChannelManager(channelManager)
|
||||
|
||||
var transcriber *voice.GroqTranscriber
|
||||
if cfg.Providers.Groq.APIKey != "" {
|
||||
transcriber = voice.NewGroqTranscriber(cfg.Providers.Groq.APIKey)
|
||||
groqAPIKey := cfg.Providers.Groq.APIKey
|
||||
if groqAPIKey == "" {
|
||||
for _, mc := range cfg.ModelList {
|
||||
if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey != "" {
|
||||
groqAPIKey = mc.APIKey
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
if groqAPIKey != "" {
|
||||
transcriber = voice.NewGroqTranscriber(groqAPIKey)
|
||||
logger.InfoC("voice", "Groq voice transcription enabled")
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# 钉钉
|
||||
|
||||
钉钉是阿里巴巴的企业通讯平台，在中国职场中广受欢迎。它采用流式 SDK 来维持持久连接。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"dingtalk": {
|
||||
"enabled": true,
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"client_secret": "YOUR_CLIENT_SECRET",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ------------- | ------ | ---- | -------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用钉钉频道 |
|
||||
| client_id | string | 是 | 钉钉应用的 Client ID |
|
||||
| client_secret | string | 是 | 钉钉应用的 Client Secret |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 前往 [钉钉开放平台](https://open.dingtalk.com/)
|
||||
2. 创建一个企业内部应用
|
||||
3. 从应用设置中获取 Client ID 和 Client Secret
|
||||
4. 配置OAuth和事件订阅(如需要)
|
||||
5. 将 Client ID 和 Client Secret 填入配置文件中
|
||||
@@ -0,0 +1,35 @@
|
||||
# Discord
|
||||
|
||||
Discord 是一个专为社区设计的免费语音、视频和文本聊天应用。PicoClaw 通过 Discord Bot API 连接到 Discord 服务器，支持接收和发送消息。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"discord": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"],
|
||||
"mention_only": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ------------ | ------ | ---- | -------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用 Discord 频道 |
|
||||
| token | string | 是 | Discord 机器人 Token |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
| mention_only | bool | 否 | 是否仅响应提及机器人的消息 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 前往 [Discord 开发者门户](https://discord.com/developers/applications) 创建一个新的应用
|
||||
2. 启用 Intents:
|
||||
- Message Content Intent
|
||||
- Server Members Intent
|
||||
3. 获取 Bot Token
|
||||
4. 将 Bot Token 填入配置文件中
|
||||
5. 邀请机器人加入服务器并授予必要权限(例如发送消息、读取消息历史等)
|
||||
@@ -0,0 +1,37 @@
|
||||
# 飞书
|
||||
|
||||
飞书（国际版名称：Lark）是字节跳动旗下的企业协作平台。它通过事件驱动的 Webhook 同时支持中国和全球市场。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"feishu": {
|
||||
"enabled": true,
|
||||
"app_id": "cli_xxx",
|
||||
"app_secret": "xxx",
|
||||
"encrypt_key": "",
|
||||
"verification_token": "",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ------------------ | ------ | ---- | -------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用飞书频道 |
|
||||
| app_id | string | 是 | 飞书应用的 App ID(以cli\_开头) |
|
||||
| app_secret | string | 是 | 飞书应用的 App Secret |
|
||||
| encrypt_key | string | 否 | 事件回调加密密钥 |
|
||||
| verification_token | string | 否 | 用于Webhook事件验证的Token |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 前往 [飞书开放平台](https://open.feishu.cn/)创建应用程序
|
||||
2. 获取 App ID 和 App Secret
|
||||
3. 配置事件订阅和Webhook URL
|
||||
4. 设置加密(可选,生产环境建议启用)
|
||||
5. 将 App ID、App Secret、Encrypt Key 和 Verification Token(如果启用加密) 填入配置文件中
|
||||
@@ -0,0 +1,41 @@
|
||||
# Line
|
||||
|
||||
PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的支持。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"line": {
|
||||
"enabled": true,
|
||||
"channel_secret": "YOUR_CHANNEL_SECRET",
|
||||
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
|
||||
"webhook_host": "0.0.0.0",
|
||||
"webhook_port": 18791,
|
||||
"webhook_path": "/webhook/line",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| -------------------- | ------ | ---- | ------------------------------------------ |
|
||||
| enabled | bool | 是 | 是否启用 LINE Channel |
|
||||
| channel_secret | string | 是 | LINE Messaging API 的 Channel Secret |
|
||||
| channel_access_token | string | 是 | LINE Messaging API 的 Channel Access Token |
|
||||
| webhook_host | string | 是 | Webhook 监听的主机地址 (通常为 0.0.0.0) |
|
||||
| webhook_port | int | 是 | Webhook 监听的端口 (默认为 18791) |
|
||||
| webhook_path | string | 是 | Webhook 的路径 (默认为 /webhook/line) |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 前往 [LINE Developers Console](https://developers.line.biz/console/) 创建一个服务提供商和一个 Messaging API Channel
|
||||
2. 获取 Channel Secret 和 Channel Access Token
|
||||
3. 配置Webhook:
|
||||
- Line要求Webhook必须使用HTTPS协议，因此需要部署一个支持HTTPS的服务器，或者使用反向代理工具如ngrok将本地服务器暴露到公网
|
||||
- 将 Webhook URL 设置为 `https://your-domain.com/webhook/line`
|
||||
- 启用 Webhook 并验证 URL
|
||||
4. 将 Channel Secret 和 Channel Access Token 填入配置文件中
|
||||
@@ -0,0 +1,31 @@
|
||||
# MaixCam
|
||||
|
||||
MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的通道。它采用 TCP 套接字实现双向通信，支持边缘 AI 部署场景。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"maixcam": {
|
||||
"enabled": true,
|
||||
"server_address": "0.0.0.0:8899",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| -------------- | ------ | ---- | -------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用 MaixCam 频道 |
|
||||
| server_address | string | 是 | TCP 服务器监听地址和端口 |
|
||||
| allow_from | array | 否 | 设备ID白名单，空表示允许所有设备 |
|
||||
|
||||
## 使用场景
|
||||
|
||||
MaixCam 通道使 PicoClaw 能够作为边缘设备的 AI 后端运行：
|
||||
|
||||
- **智能监控** ：MaixCAM 发送图像帧，PicoClaw 通过视觉模型进行分析
|
||||
- **物联网控制** ：设备发送传感器数据，PicoClaw 协调响应
|
||||
- **离线AI** ：在本地网络部署 PicoClaw 实现低延迟推理
|
||||
@@ -0,0 +1,31 @@
|
||||
# OneBot
|
||||
|
||||
OneBot 是一个面向 QQ 机器人的开放协议标准，为多种 QQ 机器人实现（例如 go-cqhttp、Mirai）提供了统一的接口。它使用 WebSocket 进行通信。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"onebot": {
|
||||
"enabled": true,
|
||||
"ws_url": "ws://localhost:8080",
|
||||
"access_token": "",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ------------ | ------ | ---- | -------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用 OneBot 频道 |
|
||||
| ws_url | string | 是 | OneBot 服务器的 WebSocket URL |
|
||||
| access_token | string | 否 | 连接 OneBot 服务器的访问令牌 |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 部署一个 OneBot 兼容的实现(例如napcat)
|
||||
2. 配置 OneBot 实现以启用 WebSocket 服务并设置访问令牌(如果需要)
|
||||
3. 将 WebSocket URL 和访问令牌填入配置文件中
|
||||
@@ -0,0 +1,32 @@
|
||||
# QQ
|
||||
|
||||
PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"qq": {
|
||||
"enabled": true,
|
||||
"app_id": "YOUR_APP_ID",
|
||||
"app_secret": "YOUR_APP_SECRET",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ---------- | ------ | ---- | -------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用 QQ Channel |
|
||||
| app_id | string | 是 | QQ 机器人应用的 App ID |
|
||||
| app_secret | string | 是 | QQ 机器人应用的 App Secret |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 前往 [QQ 开放平台](https://q.qq.com/) 创建一个机器人
|
||||
2. 通过仪表盘获取 App ID 和 App Secret
|
||||
3. 开启机器人沙箱模式, 将用户和群添加到沙箱中
|
||||
4. 将 App ID 和 App Secret 填入配置文件中
|
||||
@@ -0,0 +1,33 @@
|
||||
# Slack
|
||||
|
||||
Slack 是全球领先的企业级即时通讯平台。PicoClaw 采用 Slack 的 Socket Mode 实现实时双向通信，无需配置公开的 Webhook 端点。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"slack": {
|
||||
"enabled": true,
|
||||
"bot_token": "xoxb-...",
|
||||
"app_token": "xapp-...",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ---------- | ------ | ---- | -------------------------------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用 Slack 频道 |
|
||||
| bot_token | string | 是 | Slack 机器人的 Bot User OAuth Token (以 xoxb- 开头) |
|
||||
| app_token | string | 是 | Slack 应用的 Socket Mode App Level Token (以 xapp- 开头) |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 前往 [Slack API](https://api.slack.com/) 创建一个新的 Slack 应用
|
||||
2. 启用 Socket Mode 并获取 App Level Token
|
||||
3. 添加 Bot Token Scopes(例如`chat:write`、`im:history`等)
|
||||
4. 安装应用到工作区并获取 Bot User OAuth Token
|
||||
5. 将 Bot Token 和 App Token 填入配置文件中
|
||||
@@ -0,0 +1,33 @@
|
||||
# Telegram
|
||||
|
||||
Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、通过 Groq Whisper 进行语音转录以及内置命令处理器。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
|
||||
"allow_from": ["123456789"],
|
||||
"proxy": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ---------- | ------ | ---- | --------------------------------------------------------- |
|
||||
| enabled | bool | 是 | 是否启用 Telegram 频道 |
|
||||
| token | string | 是 | Telegram 机器人 API Token |
|
||||
| allow_from | array | 否 | 用户ID白名单，空表示允许所有用户 |
|
||||
| proxy | string | 否 | 连接 Telegram API 的代理 URL (例如 http://127.0.0.1:7890) |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 在 Telegram 中搜索 `@BotFather`
|
||||
2. 发送 `/newbot` 命令并按照提示创建新机器人
|
||||
3. 获取 HTTP API Token
|
||||
4. 将 Token 填入配置文件中
|
||||
5. (可选) 配置 `allow_from` 以限制允许互动的用户 ID (可通过 `@userinfobot` 获取 ID)
|
||||
@@ -0,0 +1,47 @@
|
||||
# 企业微信自建应用
|
||||
|
||||
企业微信自建应用是指企业在企业微信中创建的应用，主要用于企业内部使用。通过企业微信自建应用，企业可以实现与员工的高效沟通和协作，提高工作效率。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"wecom_app": {
|
||||
"enabled": true,
|
||||
"corp_id": "wwxxxxxxxxxxxxxxxx",
|
||||
"corp_secret": "YOUR_CORP_SECRET",
|
||||
"agent_id": 1000002,
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
|
||||
"webhook_host": "0.0.0.0",
|
||||
"webhook_port": 18792,
|
||||
"webhook_path": "/webhook/wecom-app",
|
||||
"allow_from": [],
|
||||
"reply_timeout": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ---------------- | ------ | ---- | ---------------------------------------- |
|
||||
| corp_id | string | 是 | 企业 ID |
|
||||
| corp_secret | string | 是 | 应用程序密钥 |
|
||||
| agent_id | int | 是 | 应用程序代理 ID |
|
||||
| token | string | 是 | 回调验证令牌 |
|
||||
| encoding_aes_key | string | 是 | 43 字符 AES 密钥 |
|
||||
| webhook_host | string | 否 | HTTP 服务器绑定地址 |
|
||||
| webhook_port | int | 否 | HTTP 服务器端口（默认：18792） |
|
||||
| webhook_path | string | 否 | Webhook 路径（默认：/webhook/wecom-app） |
|
||||
| allow_from | array | 否 | 用户 ID 白名单 |
|
||||
| reply_timeout | int | 否 | 回复超时时间（秒） |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/)
|
||||
2. 进入“应用管理” -> “创建应用”
|
||||
3. 获取企业 ID (CorpID) 和应用 Secret
|
||||
4. 在应用设置中配置“接收消息”，获取 Token 和 EncodingAESKey
|
||||
5. 设置回调 URL 为 `http://<your-server-ip>:<port>/webhook/wecom-app`
|
||||
6. 将 CorpID, Secret, AgentID 等信息填入配置文件
|
||||
@@ -0,0 +1,41 @@
|
||||
# 企业微信机器人
|
||||
|
||||
企业微信机器人是企业微信提供的一种快速接入方式，可以通过 Webhook URL 接收消息。
|
||||
|
||||
## 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"wecom": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
|
||||
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
|
||||
"webhook_host": "0.0.0.0",
|
||||
"webhook_port": 18793,
|
||||
"webhook_path": "/webhook/wecom",
|
||||
"allow_from": [],
|
||||
"reply_timeout": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 描述 |
|
||||
| ---------------- | ------ | ---- | -------------------------------------------- |
|
||||
| token | string | 是 | 签名验证代币 |
|
||||
| encoding_aes_key | string | 是 | 用于解密的 43 字符 AES 密钥 |
|
||||
| webhook_url | string | 是 | 用于发送回复的企业微信群聊机器人 Webhook URL |
|
||||
| webhook_host | string | 否 | HTTP 服务器绑定地址（默认：0.0.0.0） |
|
||||
| webhook_port | int | 否 | HTTP 服务器端口（默认：18793） |
|
||||
| webhook_path | string | 否 | Webhook 端点路径（默认：/webhook/wecom） |
|
||||
| allow_from | array | 否 | 用户 ID 白名单（空值 = 允许所有用户） |
|
||||
| reply_timeout | int | 否 | 回复超时时间（单位：秒，默认值：5） |
|
||||
|
||||
## 设置流程
|
||||
|
||||
1. 在企业微信群中添加机器人
|
||||
2. 获取 Webhook URL
|
||||
3. (如需接收消息) 在机器人配置页面设置接收消息的 API 地址（回调地址）以及 Token 和 EncodingAESKey
|
||||
4. 将相关信息填入配置文件
|
||||
@@ -191,15 +191,15 @@ func TestShellTool_WorkingDir_OutsideWorkspace(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
workspace := filepath.Join(root, "workspace")
|
||||
outsideDir := filepath.Join(root, "outside")
|
||||
if err := os.MkdirAll(workspace, 0755); err != nil {
|
||||
if err := os.MkdirAll(workspace, 0o755); err != nil {
|
||||
t.Fatalf("failed to create workspace: %v", err)
|
||||
}
|
||||
if err := os.MkdirAll(outsideDir, 0755); err != nil {
|
||||
if err := os.MkdirAll(outsideDir, 0o755); err != nil {
|
||||
t.Fatalf("failed to create outside dir: %v", err)
|
||||
}
|
||||
|
||||
tool := NewExecTool(workspace, true)
|
||||
result := tool.Execute(context.Background(), map[string]interface{}{
|
||||
result := tool.Execute(context.Background(), map[string]any{
|
||||
"command": "pwd",
|
||||
"working_dir": outsideDir,
|
||||
})
|
||||
@@ -218,13 +218,13 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
workspace := filepath.Join(root, "workspace")
|
||||
secretDir := filepath.Join(root, "secret")
|
||||
if err := os.MkdirAll(workspace, 0755); err != nil {
|
||||
if err := os.MkdirAll(workspace, 0o755); err != nil {
|
||||
t.Fatalf("failed to create workspace: %v", err)
|
||||
}
|
||||
if err := os.MkdirAll(secretDir, 0755); err != nil {
|
||||
if err := os.MkdirAll(secretDir, 0o755); err != nil {
|
||||
t.Fatalf("failed to create secret dir: %v", err)
|
||||
}
|
||||
os.WriteFile(filepath.Join(secretDir, "secret.txt"), []byte("top secret"), 0644)
|
||||
os.WriteFile(filepath.Join(secretDir, "secret.txt"), []byte("top secret"), 0o644)
|
||||
|
||||
// symlink lives inside the workspace but resolves to secretDir outside it
|
||||
link := filepath.Join(workspace, "escape")
|
||||
@@ -233,7 +233,7 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
|
||||
}
|
||||
|
||||
tool := NewExecTool(workspace, true)
|
||||
result := tool.Execute(context.Background(), map[string]interface{}{
|
||||
result := tool.Execute(context.Background(), map[string]any{
|
||||
"command": "cat secret.txt",
|
||||
"working_dir": link,
|
||||
})
|
||||
|
||||
Reference in New Issue
Block a user