Clawland-AI · caijintaoduolacmeng-star · Jun 4, 2026
@@ -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 <url>` | 从 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
+  }
+}
+```
+
@@ -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。保持友善、具体、建设性，并欢迎新贡献者。
+
@@ -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、环境变量和链接不翻译。
+