Clawland-AI · SUNNY-Fu-ai · May 14, 2026
@@ -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/).
 
+## Documentation Languages
+
+- [English home page](./index.md)
+- [Chinese README](./README.zh-CN.md)
+- [中文快速开始](./src/pages/zh/quick-start.md)
+- [中文贡献指南](./src/pages/zh/contributing.md)
+- [中文 API 概览](./src/pages/zh/api.md)
+
 ## Local Development
 
 ```bash

@@ -0,0 +1,29 @@
+# Clawland 文档站
+
+这是 [clawland-ai.github.io](https://clawland-ai.github.io) 的源码仓库，用来承载 Clawland 项目的公开文档、快速开始、贡献说明和 API 概览。
+
+Clawland 是一个面向边缘设备的开源 AI Agent 生态。它让从 2 美元微控制器到云服务器的硬件都能运行不同层级的 Agent，用低成本硬件承担监测、巡检、告警和自动化运维任务。
+
+## 中文文档入口
+
+- [中文首页](./src/pages/zh/index.md)
+- [快速开始](./src/pages/zh/quick-start.md)
+- [贡献指南](./src/pages/zh/contributing.md)
+- [API 概览](./src/pages/zh/api.md)
+
+## 本地开发
+
+本仓库包含 Astro 站点配置：
+
+```bash
+npm install
+npm run dev
+```
+
+打开开发服务器输出的本地地址即可预览。
+
+旧版 Jekyll 说明仍保留在英文 README 中；如果项目后续统一到 Astro，建议以 `package.json` 中的脚本为准。
+
+## 许可证
+
+文档内容使用 CC BY-SA 4.0 授权。
@@ -11,6 +11,8 @@ Clawland is an open-source ecosystem of AI Agents that run on hardware from $2 m
 
 ## Quick Start
 
+中文文档: [中文首页](./src/pages/zh/index.md) / [快速开始](./src/pages/zh/quick-start.md) / [贡献指南](./src/pages/zh/contributing.md) / [API 概览](./src/pages/zh/api.md)
+
 ### Choose Your Agent
 
 | If you have... | Use... | Get started |

@@ -1,13 +1,13 @@
 ---
-const title = "Clawland 鈥?Edge AI Agents for $10 Hardware";
+const title = "Clawland - Edge AI Agents for $10 Hardware";
 ---
 
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>{title}</title>
-  <meta name="description" content="Open-source AI Agents running on hardware from $2 MCUs to cloud servers. Build to Earn 鈥?20% revenue share for contributors." />
+  <meta name="description" content="Open-source AI Agents running on hardware from $2 MCUs to cloud servers. Build to Earn with a 20% revenue share for contributors." />
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body { font-family: system-ui, -apple-system, sans-serif; background: #0a0a0a; color: #e5e5e5; }
@@ -29,38 +29,39 @@ const title = "Clawland 鈥?Edge AI Agents for $10 Hardware";
 <body>
   <div class="hero">
     <h1>Clawland</h1>
-    <p>Open-source AI Agents running on $10 hardware. Replace human monitoring jobs at 1/100th the cost. Build to Earn 鈥?contributors share 20% of revenue.</p>
+    <p>Open-source AI Agents running on $10 hardware. Replace human monitoring jobs at 1/100th the cost. Build to Earn: contributors share 20% of revenue.</p>
     <div class="cta">
       <a href="https://github.com/Clawland-AI" class="primary">View on GitHub</a>
       <a href="https://github.com/Clawland-AI/.github/blob/main/CONTRIBUTING.md" class="secondary">Start Contributing</a>
+      <a href="/zh/" class="secondary">中文文档</a>
     </div>
   </div>
 
   <div class="agents">
     <div class="agent-card">
       <h3>PicoClaw</h3>
       <p>Ultra-lightweight Go agent. &lt;10MB RAM, runs on $10 RISC-V boards.</p>
-      <p class="meta">Go 路 Edge L1 路 Apache 2.0</p>
+      <p class="meta">Go / Edge L1 / Apache 2.0</p>
     </div>
     <div class="agent-card">
       <h3>MoltClaw</h3>
       <p>Full-featured TypeScript cloud gateway. Multi-agent routing and orchestration.</p>
-      <p class="meta">TypeScript 路 Cloud L3 路 Apache 2.0</p>
+      <p class="meta">TypeScript / Cloud L3 / Apache 2.0</p>
     </div>
     <div class="agent-card">
       <h3>NanoClaw</h3>
       <p>Mid-weight Python agent. Rich ecosystem, runs on Raspberry Pi.</p>
-      <p class="meta">Python 路 Gateway L2 路 Apache 2.0</p>
+      <p class="meta">Python / Gateway L2 / Apache 2.0</p>
     </div>
     <div class="agent-card">
       <h3>MicroClaw</h3>
       <p>MCU-level micro agent. &lt;1MB RAM, runs on $2 ESP32 boards.</p>
-      <p class="meta">C/Rust 路 Sensor L0 路 Apache 2.0</p>
+      <p class="meta">C/Rust / Sensor L0 / Apache 2.0</p>
     </div>
   </div>
 
   <footer>
-    <p>&copy; 2026 Clawland-AI 路 "Let $10 hardware + AI Agents do the watching, so humans can do the thinking."</p>
+    <p>&copy; 2026 Clawland-AI / "Let $10 hardware + AI Agents do the watching, so humans can do the thinking."</p>
   </footer>
 </body>
-</html>
+</html>
@@ -0,0 +1,81 @@
+---
+title: "Clawland API 概览"
+description: "Clawland Fleet 与 Edge API 的中文概览。"
+---
+
+# API 概览
+
+本页是 Clawland 核心 API 的中文概览，帮助贡献者理解各类接口的职责边界。具体字段以各仓库中的代码、OpenAPI 文件或 README 为准。
+
+## 分层关系
+
+Clawland 通常可以理解为三层：
+
+- Edge Node：PicClaw、NanoClaw 或 MicroClaw 运行在设备侧，负责读取传感器、执行命令、上报状态。
+- Fleet Manager：云端或局域网服务，负责注册节点、接收 heartbeat、下发命令、聚合事件。
+- Dashboard / Integrations：面向操作员、业务系统或第三方工具的可视化与集成层。
+
+## 常见接口类型
+
+| 接口 | 方向 | 作用 |
+|---|---|---|
+| Health | 外部到服务 | 判断服务是否存活，适合负载均衡或监控探针 |
+| Status | 外部到 Edge | 获取节点当前状态、版本、运行时间和传感器摘要 |
+| Message | Edge 与 Fleet 双向 | 传递普通事件、日志、传感器数据或系统消息 |
+| Command | Fleet 到 Edge | 下发重启、切换模式、控制继电器、采样等命令 |
+| Heartbeat | Edge 到 Fleet | 周期性报告节点在线、负载、最后采样时间和异常 |
+| Event | Edge 到 Fleet | 上报告警、阈值触发、设备故障或业务事件 |
+
+## Edge API 建议语义
+
+典型 Edge API 可以包含：
+
+```http
+GET /api/health
+GET /api/status
+POST /api/message
+POST /api/command
+```
+
+建议原则：
+
+- `GET /api/health` 只返回轻量健康信息，不依赖慢外部服务。
+- `GET /api/status` 返回更完整的节点状态，可以包含传感器摘要。
+- `POST /api/message` 用于一般消息或事件，不应用来执行高风险命令。
+- `POST /api/command` 需要明确命令类型、参数、幂等 ID 和执行状态。
+
+## Fleet API 建议语义
+
+Fleet Manager 侧通常需要：
+
+- 节点注册：记录 node id、agent 类型、版本、能力和标签。
+- Heartbeat 接收：更新在线状态、最后上报时间和运行指标。
+- 命令队列：保存待执行命令，等待节点轮询或通过长连接下发。
+- 事件聚合：把告警、传感器异常和设备故障统一进入事件流。
+- 查询接口：给 Dashboard 或外部系统读取节点状态、命令状态和历史事件。
+
+## 错误处理
+
+API 应该返回结构化错误，至少包含：
+
+- `code`：稳定的机器可读错误码
+- `message`：面向开发者的简短说明
+- `request_id`：用于排查日志
+
+高风险命令应优先设计成可重试、可审计、可回滚或有超时保护。
+
+## 安全边界
+
+- 不在仓库中提交生产密钥、token、私有 URL 或真实客户数据。
+- 命令接口默认不应开放到公网。
+- 设备控制类命令要有权限、审计和失败保护。
+- 对外示例应使用 mock、sample 或 redacted 数据。
+
+## 给贡献者的建议
+
+提交 API 相关 PR 时，请同时附上：
+
+- 请求/响应示例
+- 错误场景
+- 最小测试或 curl 验收命令
+- 对现有接口兼容性的说明
@@ -0,0 +1,78 @@
+---
+title: "Clawland 贡献指南"
+description: "中文贡献流程：选任务、留言认领、提交计划、实现、验证和 PR。"
+---
+
+# 贡献指南
+
+Clawland 欢迎代码、文档、skill、测试、硬件设计和示例项目等多种贡献。为了减少重复劳动，请先确认任务状态，再开始实现。
+
+## 贡献流程
+
+1. 找到一个 issue、Bounty Board 任务或文档缺口。
+2. 阅读对应仓库的 README、许可证和已有 PR。
+3. 在 issue 或讨论区留言，说明你想做的范围。
+4. 如果是赏金任务，在 48 小时内补充简短实现计划。
+5. Fork 仓库，创建分支并提交改动。
+6. 运行测试或最小验证。
+7. 开 PR，引用 issue 或 Bounty Board 条目。
+
+## 认领任务时写什么
+
+好的认领留言应该具体，而不是只写“我想做”。建议包含：
+
+- 任务名称或 issue 编号
+- 你准备改的模块
+- 交付物
+- 测试方式
+- 预计时间
+
+示例：
+
+```text
+I would like to work on the Chinese Documentation Translation bounty.
+Plan:
+- Add README.zh-CN.md and Chinese pages for Quick Start, Contributing, and API overview.
+- Keep the translation natural and technical, not machine-literal.
+- Update navigation links from the English docs.
+- Validate with npm run build.
+```
+
+## PR 描述模板
+
+```text
+## Summary
+- Add ...
+- Update ...
+
+## Validation
+- npm run build
+- Checked links ...
+
+## Bounty
+References the Clawland Bounty Board item: ...
+```
+
+## 收益和赏金
+
+Clawland 的赏金任务通常会在 Bounty Board 或 issue 中列出金额和验收方式。一般流程是：
+
+1. 在 issue 留言确认任务仍可做。
+2. 提交计划，避免与其他贡献者重复。
+3. 完成实现并开 PR。
+4. 维护者 review、要求修改或合并。
+5. PR 被接受后按项目说明处理付款。
+
+请注意：赏金不是只开 PR 就自动付款，通常需要维护者确认范围、审核质量并合并。
+
+## 代码质量原则
+
+- 保持 PR 小而聚焦。
+- 不要混入无关格式化。
+- 为新逻辑补测试或说明验证方式。
+- 不提交密钥、账号、生产配置或私有数据。
+- 文档翻译要使用自然、准确的中文，不要逐词机翻。
+
+## 沟通原则
+
+维护者最需要看到的是可验证的结果。写清楚你做了什么、如何验证、还有哪些边界没有覆盖，就能显著降低 review 成本。
@@ -0,0 +1,46 @@
+---
+title: "Clawland 中文文档"
+description: "Clawland 边缘 AI Agent 生态的中文文档入口。"
+---
+
+# Clawland 中文文档
+
+**用低成本硬件构建边缘 AI Agent，并通过开源贡献获得回报。**
+
+Clawland 是一个开源边缘 AI Agent 生态，目标是让从 2 美元微控制器到云服务器的设备都能承担监测、巡检、告警和自动化控制任务。它把不同成本、性能和运行位置的硬件组织成一套分层 Agent 系统，让开发者可以从小型传感器节点一路扩展到云端 Fleet Manager。
+
+## 适合谁
+
+- 想把 AI Agent 部署到真实硬件上的开发者
+- 想做传感器监测、农业水产、冷链、设备巡检或安全看护的团队
+- 想通过开源任务、赏金任务和长期贡献参与 Clawland 生态的人
+- 想用 Go、TypeScript、Python、C 或 Rust 构建边缘系统的人
+
+## 文档导航
+
+- [快速开始](./quick-start/)：选择 Agent、安装仓库、跑通最小示例。
+- [贡献指南](./contributing/)：了解如何选任务、提交 PR、参与赏金和收入共享。
+- [API 概览](./api/)：了解 Fleet、Edge、Message、Status 和 Health 等核心接口的职责。
+
+## Agent 家族
+
+| Agent | 适合硬件 | 主要语言 | 典型用途 |
+|---|---|---|---|
+| PicClaw | 约 10 美元 RISC-V 板 | Go | 轻量边缘节点、传感器网关、本地控制 |
+| NanoClaw | Raspberry Pi / 单板机 | Python | 区域网关、复杂数据处理、Python 生态集成 |
+| MicroClaw | ESP32 等 MCU | C / Rust | 超低成本传感器节点、MQTT 上报、OTA |
+| MoltClaw | 云服务器或 Mac mini | TypeScript | Fleet Manager、云端路由、仪表盘和编排 |
+
+## 贡献与收益
+
+Clawland 的 Build to Earn 模式鼓励开发者通过 issue、PR、文档、硬件设计和 skill 贡献参与生态。公开赏金任务通常会在 Bounty Board 或 GitHub issue 中说明范围、验收方式和支付路径。参与前建议先在对应 issue 留言确认任务仍可认领，再提交计划和 PR。
+
+## 下一步
+
+第一次参与建议按这个顺序走：
+
+1. 读 [快速开始](./quick-start/)。
+2. 选择一个与你熟悉语言匹配的 Agent。
+3. 在 GitHub 上查看 good first issue 或 Bounty Board。
+4. 留言说明你要做的范围和 48 小时内的实现计划。
+5. 提交小而完整的 PR，并附测试或验收说明。