diff --git a/API.zh-CN.md b/API.zh-CN.md new file mode 100644 index 0000000..a66b2f8 --- /dev/null +++ b/API.zh-CN.md @@ -0,0 +1,130 @@ +# API 与 CLI 参考 + +本文整理 Clawland/PicClaw 当前公开文档中的核心接口和命令，便于中文开发者快速查阅。 + +## CLI 命令 + +| 命令 | 说明 | +| --- | --- | +| `picoclaw onboard` | 初始化配置和工作区 | +| `picoclaw agent -m "..."` | 一次性对话 | +| `picoclaw agent` | 进入交互式 Agent 模式 | +| `picoclaw gateway` | 启动网关模式，包含 channels、cron、edge 和 heartbeat | +| `picoclaw status` | 查看配置状态 | +| `picoclaw cron list` | 列出定时任务 | +| `picoclaw cron add` | 添加定时任务 | +| `picoclaw skills list` | 列出已安装 skills | +| `picoclaw skills install ` | 从 Git 仓库安装 skill | +| `picoclaw skills install-builtin` | 安装全部内置 skills | +| `picoclaw gene list` | 查看本地 genes 及置信度 | +| `picoclaw gene stats` | 查看 gene pool 统计 | +| `picoclaw gene export` | 导出 genes JSON | +| `picoclaw version` | 查看版本 | + +## Edge Server API + +启用 `edge.enabled` 后，PicClaw 会作为 L1 edge node 暴露基础 HTTP API。 + +### `GET /healthz` + +健康检查接口，用于本机探活、容器编排、上游 Fleet 监测。 + +### `GET /api/v1/status` + +返回节点状态，通常包括节点标识、运行状态、心跳信息、gene 统计等摘要信息。具体字段以当前实现为准。 + +### `POST /api/v1/command` + +接收来自上游 Fleet Manager 的命令。适用于远程触发检测、调整阈值、执行预定义 skill 或发送控制指令。 + +## 内置工具 + +| Tool | 说明 | +| --- | --- | +| `read_file` | 读取文件内容 | +| `write_file` | 创建或覆盖文件 | +| `edit_file` | 基于搜索替换修改文件 | +| `append_file` | 追加文件内容 | +| `list_dir` | 列出目录内容 | +| `exec` | 执行 Shell 命令 | +| `spawn` | 启动后台进程 | +| `web_search` | 搜索网页 | +| `web_fetch` | 抓取并提取网页内容 | +| `message` | 通过配置的渠道发送消息 | +| `cron` | 创建或管理定时任务 | +| `report_gene` | 向 Gene Evolution 系统上报经验 | + +## 消息渠道 + +| Channel | 配置项 | 备注 | +| --- | --- | --- | +| Telegram | `token`, `allow_from` | 推荐渠道；配合 Groq 可支持语音消息 | +| Discord | `token`, `allow_from` | 需要启用 MESSAGE CONTENT INTENT | +| QQ | `app_id`, `app_secret` | QQ Open Platform | +| DingTalk | `client_id`, `client_secret` | 钉钉内部应用 | +| Feishu | `app_id`, `app_secret`, `encrypt_key`, `verification_token` | 飞书/Lark bot | +| WhatsApp | `bridge_url` | 通过 WhatsApp bridge | +| MaixCam | `host`, `port` | 直接连接硬件 | + +## Gene Evolution Protocol + +PicClaw 的 CGEP 通过运行经验改进监测策略： + +1. 从传感器数据、memory 和每日记录中提取 signals。 +2. 将 signals 与 gene pool 匹配，把高分 genes 注入 LLM system prompt。 +3. 处理完成后，把经验 solidify 为 capsules。 +4. 成功的新策略可生成 genes。 +5. 高置信度 genes 可发布到 Fleet，供其他节点复用。 + +内置 signal 类型包括： + +- `sensor_error` +- `threshold_breach` +- `cross_sensor_anomaly` +- `new_pattern_detected` +- `response_too_slow` +- `strategy_proven` +- `unknown_situation` +- `time_pattern` + +## 配置片段 + +### Provider + +```json +{ + "providers": { + "openrouter": { + "api_key": "YOUR_API_KEY" + } + } +} +``` + +### Telegram + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "123456:ABC-DEF...", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +### Gene + +```json +{ + "gene": { + "strategy": "balanced", + "auto_publish": true, + "min_confidence": 0.7, + "min_verified_by": 3 + } +} +``` + diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 0000000..139d28a --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,160 @@ +# Clawland 贡献指南 + +本文是 Clawland 组织级贡献指南的中文版本，适用于 `github.com/Clawland-AI` 下的公开仓库。具体仓库可能还有额外要求，提交前请同时阅读目标仓库的 README、CONTRIBUTING 和 PR 模板。 + +## 快速流程 + +1. Fork 目标仓库。 +2. 创建功能分支： + +```bash +git checkout -b feature/my-feature +``` + +3. 完成修改。 +4. 运行测试或构建命令。 +5. 使用清晰的 commit message： + +```bash +git commit -m "feat(agent): add temperature sensor support for SHT40" +``` + +6. Push 分支并创建 Pull Request。 +7. 第一次提交 PR 时，按 CLA bot 提示签署 CLA。 + +## 可以贡献什么 + +### 代码 + +- 修复 bug。 +- 实现 enhancement。 +- 处理 good first issue。 +- 补充测试和 CI。 + +### Skills + +Skill 是教 Agent 掌握领域知识的 Markdown 文件。通常是一个目录，包含 `SKILL.md`，其中有 YAML frontmatter 和正文说明。 + +贡献 skill 时建议包含： + +- 场景说明。 +- 输入/输出格式。 +- 阈值、策略或控制逻辑。 +- 测试数据或模拟脚本。 + +### 硬件套件 + +硬件套件贡献应包含： + +- BOM。 +- 接线图。 +- 驱动脚本。 +- PicClaw skill 配置。 +- 成本分析。 +- 测试报告或可复现实验步骤。 + +### 文档 + +- 改进 README。 +- 编写教程。 +- 翻译核心文档。 +- 修复歧义、过期命令或错别字。 + +### 社区支持 + +- 在 GitHub Discussions 回答问题。 +- 帮助复现和 triage issues。 +- 给 PR 做建设性 review。 + +### Bounty + +公开 bounty 任务需要先在 issue 中表达意愿并等待维护者分配。完成后提交 PR，PR 描述里应引用对应 issue。 + +## Commit 规范 + +Clawland 使用 Conventional Commits： + +```text +type(scope): description +``` + +示例： + +```text +feat(agent): add sub-agent timeout configuration +fix(channels): handle Telegram reconnection on network loss +docs(skills): add weather skill tutorial +chore(ci): update Go version to 1.24 +test(tools): add exec tool safety guard tests +``` + +常用 type： + +- `feat` +- `fix` +- `docs` +- `chore` +- `test` +- `refactor` +- `perf` +- `style` +- `ci` + +## PR 要求 + +- 一个 PR 只解决一个功能或问题。 +- 描述清楚改了什么、为什么改、如何验证。 +- 引用相关 issue。 +- 新功能应补测试。 +- 行为变化应补文档。 +- 尽量控制 PR 规模，较大变更拆成多个 PR。 + +## Code Review + +- PR 至少需要 1 位 Core Maintainer approve。 +- Reviewer 目标是在 72 小时内回应。 +- 反馈应具体、建设性、可执行。 + +## 开发环境 + +### PicClaw + +```bash +git clone https://github.com/Clawland-AI/picclaw.git +cd picclaw +make build +./picclaw status +``` + +### MoltClaw + +```bash +git clone https://github.com/Clawland-AI/moltclaw.git +cd moltclaw +npm install +npm run dev +``` + +### Skills + +```bash +picoclaw skills install /path/to/your-skill +picoclaw agent -m "test your skill functionality" +``` + +## 问题报告 + +提交 issue 时请包含： + +- 复现步骤。 +- 期望行为。 +- 实际行为。 +- 环境信息。 +- 相关日志或截图。 + +安全漏洞不要公开发 issue，请发送邮件到 `security@clawland.dev`。 + +## 行为准则 + +所有贡献者都应遵守 Code of Conduct。保持友善、具体、建设性，并欢迎新贡献者。 + diff --git a/GLOSSARY.zh-CN.md b/GLOSSARY.zh-CN.md new file mode 100644 index 0000000..2f787ea --- /dev/null +++ b/GLOSSARY.zh-CN.md @@ -0,0 +1,42 @@ +# Clawland 术语表 + +本文统一中文文档中的核心术语，避免同一概念被翻译成多个版本。 + +| English | 中文建议 | 说明 | +| --- | --- | --- | +| Agent | Agent / 智能体 | 首次出现可写作“Agent（智能体）”，后续保留 Agent | +| Edge AI | 边缘 AI | 在靠近设备和现场的位置运行 AI | +| Fleet | Fleet / 节点集群 | 多个 Claw 节点的统一管理视角 | +| Skill | Skill / 技能 | Markdown 形式的领域知识包，建议保留英文 Skill | +| Gene | Gene / 策略基因 | CGEP 中可复用的监测或处理策略 | +| Capsule | Capsule / 经验胶囊 | 从运行经验固化出的结构化记录 | +| MessageBus | MessageBus / 消息总线 | 内部模块通信机制 | +| Provider | Provider / 模型服务提供方 | LLM 服务来源 | +| Channel | Channel / 消息渠道 | Telegram、Discord、飞书等接入渠道 | +| Gateway | Gateway / 网关 | 负责汇聚、转发和协调的节点 | +| Edge Server | Edge Server / 边缘服务 | PicClaw 暴露给上游 Fleet 的 HTTP 服务 | +| Heartbeat | 心跳 | 周期性状态上报 | +| Bounty | Bounty / 赏金任务 | 完成后经 review/merge 支付奖励的任务 | +| Contributor Revenue Pool | 贡献者收入池 | 按季度分配给合格贡献者的净收入池 | +| BOM | 物料清单 | 硬件套件所需零件列表 | +| Wiring diagram | 接线图 | 传感器、开发板和供电连接图 | + +## 产品名 + +产品名不翻译： + +- Clawland +- PicClaw +- PicoClaw +- NanoClaw +- MicroClaw +- MoltClaw +- Clawland Fleet + +## 风格约定 + +- 命令、路径、配置项、API endpoint 保持英文原样，例如 `picoclaw gateway`、`~/.picoclaw/config.json`、`GET /healthz`。 +- 产品承诺类描述避免夸张化翻译，优先使用准确、可验证的表达。 +- 技术缩写首次出现时可补充中文解释，例如 LLM（大语言模型）。 +- 代码块、JSON key、环境变量和链接不翻译。 + diff --git a/QUICKSTART.zh-CN.md b/QUICKSTART.zh-CN.md new file mode 100644 index 0000000..03ecce0 --- /dev/null +++ b/QUICKSTART.zh-CN.md @@ -0,0 +1,148 @@ +# Clawland 快速开始 + +本文用 PicClaw 作为入门路径。PicClaw 是 Clawland 的 L1 Edge Agent，适合在 Linux 边缘设备、Raspberry Pi、RISC-V 开发板或普通服务器上运行。 + +## 1. 构建 PicClaw + +```bash +git clone https://github.com/Clawland-AI/picclaw.git +cd picclaw +make build +``` + +构建完成后，二进制文件会出现在 `build/` 目录。也可以运行： + +```bash +make build-all +``` + +这会为 Linux、macOS、amd64、arm64、riscv64 等目标构建产物。 + +## 2. 初始化 + +```bash +picoclaw onboard +``` + +初始化流程会创建本地配置和工作区。默认工作区在： + +```text +~/.picoclaw/ +``` + +## 3. 配置 LLM Provider + +最小配置只需要选择一个 provider 并设置 API key。例如使用 Zhipu： + +```json +{ + "agents": { + "defaults": { + "model": "glm-4.7", + "max_tokens": 8192 + } + }, + "providers": { + "zhipu": { + "api_key": "YOUR_API_KEY" + } + } +} +``` + +支持的 provider 包括 Zhipu、OpenRouter、Anthropic、OpenAI、Gemini、Groq，以及自托管 vLLM endpoint。 + +## 4. 运行 Agent + +一次性提问： + +```bash +picoclaw agent -m "What is 2+2?" +``` + +交互模式： + +```bash +picoclaw agent +``` + +启动网关模式： + +```bash +picoclaw gateway +``` + +网关模式会同时启用消息渠道、cron、edge 心跳和相关后台服务。 + +## 5. 启用 Edge Server + +示例配置： + +```json +{ + "edge": { + "enabled": true, + "port": 9090, + "node_id": "dc-rack-a1", + "node_name": "Datacenter Rack A1", + "cloud_endpoint": "http://nanoclaw:8080", + "cloud_token": "...", + "heartbeat_seconds": 30 + } +} +``` + +启用后，PicClaw 会暴露： + +- `GET /healthz` +- `GET /api/v1/status` +- `POST /api/v1/command` + +并按配置向上游 Fleet Manager 发送心跳。 + +## 6. 安装 Skills + +查看内置 skills： + +```bash +picoclaw skills list +``` + +安装内置 skills： + +```bash +picoclaw skills install-builtin +``` + +从 Git 仓库安装： + +```bash +picoclaw skills install +``` + +## 7. 数据中心监测 Demo + +内置 `datacenter-monitoring` skill 可用于本地模拟： + +```bash +python3 skills/datacenter-monitoring/scripts/mock-sensor.py --all --summary +python3 skills/datacenter-monitoring/scripts/mock-sensor.py --rack A1 --spike +python3 skills/datacenter-monitoring/scripts/mock-sensor.py --rack B2 --fail +``` + +完整部署说明见 PicClaw 仓库中的 `skills/datacenter-monitoring/DEPLOY.md`。 + +## 8. 常见问题 + +### Web search 报 API configuration error + +没有配置 Brave Search API key 时这是正常现象。申请 key 后写入 `tools.web.search.api_key`。 + +### Telegram 提示 getUpdates 冲突 + +同一个 Telegram bot token 只能由一个 `picoclaw gateway` 实例轮询。停止其他实例后重试。 + +### Provider 内容过滤 + +部分模型服务会触发内容过滤。可以换一种表达，或切换到其他 provider/model。 + diff --git a/README.md b/README.md index e1d705d..bfe5c5a 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,14 @@ Source for [clawland-ai.github.io](https://clawland-ai.github.io) — the Clawla Built with [Jekyll](https://jekyllrb.com/) and hosted on [GitHub Pages](https://pages.github.com/). +## Chinese Documentation + +- [中文首页](README.zh-CN.md) +- [快速开始](QUICKSTART.zh-CN.md) +- [API 与 CLI 参考](API.zh-CN.md) +- [贡献指南](CONTRIBUTING.zh-CN.md) +- [术语表](GLOSSARY.zh-CN.md) + ## Local Development ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..2611b19 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,57 @@ +# Clawland 中文文档 + +Clawland 是一个开源 Edge AI Agent 生态，目标是在从 2 美元 MCU 到云服务器的硬件上运行可组合、可学习、可协作的 AI Agent。项目希望用低成本边缘硬件承担监测、巡检、维护和告警等重复工作，让人类负责判断、设计和处置。 + +本文是中文核心文档入口，面向第一次了解 Clawland 的开发者、硬件爱好者和潜在贡献者。 + +## 生态层级 + +| 层级 | 项目 | 语言 | 角色 | +| --- | --- | --- | --- | +| L0 Sensor | MicroClaw | C/Rust | 运行在 ESP32 等 MCU 上的传感器级 Agent | +| L1 Edge | PicClaw | Go | 运行在 10 美元级 Linux 边缘设备上的轻量 Agent | +| L2 Gateway | NanoClaw | Python | 区域网关和本地协调层 | +| L3 Cloud | MoltClaw | TypeScript | 云端 Fleet 管理、多 Agent 路由和编排 | + +## PicClaw 做什么 + +PicClaw 是当前最完整的边缘 Agent 实现。它是一个 Go 单二进制程序，设计目标是低内存、快速启动、易部署。 + +核心能力包括： + +- 连接 LLM Provider，例如 Zhipu、OpenRouter、Anthropic、OpenAI、Gemini、Groq 或兼容 vLLM 的服务。 +- 执行内置工具，例如文件读写、Shell、网页搜索、定时任务、消息发送和 Gene 上报。 +- 接入消息渠道，例如 Telegram、Discord、QQ、钉钉、飞书、WhatsApp 和 MaixCam。 +- 通过 Gene Evolution Protocol 从运行经验中沉淀策略。 +- 通过 Edge Server 向上游 Fleet 汇报节点状态和心跳。 + +## 快速入口 + +- [快速开始](QUICKSTART.zh-CN.md) +- [API 与 CLI 参考](API.zh-CN.md) +- [贡献指南](CONTRIBUTING.zh-CN.md) +- [术语表](GLOSSARY.zh-CN.md) + +## 典型场景 + +| 场景 | 示例 | +| --- | --- | +| 数据中心巡检 | 机柜温度、烟雾、水浸、设备异常告警 | +| 水产养殖 | 溶氧、pH、温度、浊度监测，夜间增氧告警 | +| 温室管理 | 土壤湿度、温湿度、光照、CO2 趋势分析 | +| 冷链合规 | 温度、GPS、4G 上报和合规记录 | +| 设备维护 | 振动、电流、温度等预测性维护信号 | + +## Build to Earn + +Clawland 的贡献者机制包含两部分： + +- Bounty：完成公开赏金任务并通过 review/merge 后获得一次性奖励。 +- Contributor Revenue Pool：合格贡献者按季度分享 20% 的净产品收入池。 + +具体规则以 Clawland 组织仓库中的贡献指南和收入分享协议为准。 + +## License + +不同子项目使用不同许可证。软件项目通常使用 Apache 2.0 或 MIT，硬件设计使用 CERN-OHL-S，Fleet 相关组件可能使用 BSL 1.1。提交贡献前请查看目标仓库的 LICENSE。 + diff --git a/index.md b/index.md index 3d8115e..0e7de06 100644 --- a/index.md +++ b/index.md @@ -31,6 +31,8 @@ Core contributors share 20% of product revenue. [Learn more →](https://github. ## Links - [GitHub Organization](https://github.com/Clawland-AI) +- [中文文档](README.zh-CN.md) +- [中文快速开始](QUICKSTART.zh-CN.md) - [Contributing Guide](https://github.com/Clawland-AI/.github/blob/main/CONTRIBUTING.md) - [Governance](https://github.com/Clawland-AI/.github/blob/main/GOVERNANCE.md) - [Discussions](https://github.com/orgs/Clawland-AI/discussions) diff --git a/src/pages/index.astro b/src/pages/index.astro index 63fd1ee..aea5451 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -1,5 +1,5 @@ --- -const title = "Clawland 鈥?Edge AI Agents for $10 Hardware"; +const title = "Clawland - Edge AI Agents for $10 Hardware"; --- @@ -7,7 +7,7 @@ const title = "Clawland 鈥?Edge AI Agents for $10 Hardware"; {title} - +