+
-PicoClaw: Ultra-Efficient AI Assistant in Go
+PicoClaw: Ultra-Efficient AI Assistant in Go
-$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！
- +$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！
-
-
+
+ 
-SipeedIO-black?style=flat&logo=x&logoColor=white){kind=icon}
+
-
-
+
+
| @@ -37,7 +40,19 @@ |
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..f2c9bf7
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,719 @@
+
+
+
+
+
|
+
+ |
+
+
+ |
+
+
+## 🦾 演示
+
+### 🛠️ 标准助手工作流
+
+🧩 全栈工程师模式 |
+🗂️ 日志与规划管理 |
+🔎 网络搜索与学习 |
+
|---|---|---|
|
+
|
+
|
+
| 开发 • 部署 • 扩展 | +日程 • 自动化 • 记忆 | +发现 • 洞察 • 趋势 | +
加入 Agent 社交网络
+
+只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
+
+**阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai**](https://clawdchat.ai)
+
+## ⚙️ 配置详解
+
+配置文件路径: `~/.picoclaw/config.json`
+
+### 工作区布局 (Workspace Layout)
+
+PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
+
+```
+~/.picoclaw/workspace/
+├── sessions/ # 对话会话和历史
+├── memory/ # 长期记忆 (MEMORY.md)
+├── state/ # 持久化状态 (最后一次频道等)
+├── cron/ # 定时任务数据库
+├── skills/ # 自定义技能
+├── AGENTS.md # Agent 行为指南
+├── HEARTBEAT.md # 周期性任务提示词 (每 30 分钟检查一次)
+├── IDENTITY.md # Agent 身份设定
+├── SOUL.md # Agent 灵魂/性格
+├── TOOLS.md # 工具描述
+└── USER.md # 用户偏好
+
+```
+
+### 心跳 / 周期性任务 (Heartbeat)
+
+PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+
+```
+
+Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。
+
+#### 使用 Spawn 的异步任务
+
+对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：
+
+```markdown
+# 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 拥有独立上下文，无会话历史 |
+| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
+| **非阻塞** | spawn 后，心跳继续处理下一个任务 |
+
+#### 子 Agent 通信原理
+
+```
+心跳触发 (Heartbeat triggers)
+ ↓
+Agent 读取 HEARTBEAT.md
+ ↓
+对于长任务: spawn 子 Agent
+ ↓ ↓
+继续下一个任务 子 Agent 独立工作
+ ↓ ↓
+所有任务完成 子 Agent 使用 "message" 工具
+ ↓ ↓
+响应 HEARTBEAT_OK 用户直接收到结果
+
+```
+
+子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。
+
+**配置：**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+
+```
+
+| 选项 | 默认值 | 描述 |
+| --- | --- | --- |
+| `enabled` | `true` | 启用/禁用心跳 |
+| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) |
+
+**环境变量:**
+
+* `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) |
+| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) |
+
+
+
+## 🐛 疑难解答 (Troubleshooting)
+
+### 网络搜索提示 "API 配置问题"
+
+如果您尚未配置搜索 API Key，这是正常的。PicoClaw 会提供手动搜索的帮助链接。
+
+启用网络搜索：
+
+1. 在 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (每月 2000 次免费查询)
+2. 添加到 `~/.picoclaw/config.json`:
+```json
+{
+ "tools": {
+ "web": {
+ "search": {
+ "api_key": "YOUR_BRAVE_API_KEY",
+ "max_results": 5
+ }
+ }
+ }
+}
+
+```
+
+
+
+### 遇到内容过滤错误 (Content Filtering Errors)
+
+某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。
+
+### Telegram bot 提示 "Conflict: terminated by other getUpdates"
+
+这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `picoclaw gateway` 进程在运行。
+
+---
+
+## 📝 API Key 对比
+
+| 服务 | 免费层级 | 适用场景 |
+| --- | --- | --- |
+| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
+| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 |
+| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
+| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
\ No newline at end of file
+
+
