Skip to content

AGENT-GUIDE.md

Latest commit

 

History

History
138 lines (90 loc) · 6.42 KB

AGENT-GUIDE.md

File metadata and controls

138 lines (90 loc) · 6.42 KB
Raw

Agent 指南：如何读懂和执行本仓库的用例

给人类读者

本合集的所有用例都采用统一的 Markdown 结构（所需技能 → 如何设置 → 实用建议）。这种一致性不仅方便你阅读，也让 AI 智能体可以理解并辅助执行设置步骤。

使用方式：把你感兴趣的用例文件发给你的 OpenClaw（或其他 AI 智能体），让它参考本文件来帮你完成安装和配置。Agent 会识别哪些代码块该执行、哪些是参考示例、哪些凭证需要你提供。

注意：这是一个实验性的辅助方式，复杂用例仍建议你通读全文后再操作。以下内容是写给 Agent 的技术细节，你无需继续阅读。

以下内容面向 AI 智能体

入口在 AGENTS.md：那里有执行协议（Reading Protocol）和人机分工协议（如何替用户算出"最小必要人工 + 时点"并做二次指导）。本文件是补充细则——用例文件结构与代码块执行规则。先读 AGENTS.md，再用本文件查细节。

本仓库收录了 50 个经过验证的真实用例（以 OpenClaw 术语写就，可被任何 agent 复用）。每个用例文件遵循统一的格式约定，你只需学习一次，即可理解并执行所有用例。

用例文件结构

每个 usecases/*.md 文件都遵循以下结构（细节可能因用例而异，但大框架一致）：

# 用例标题                     ← 用例名称
> 含国内适配：XX / YY          ← 可选，表示有国内替代方案
简短描述（2-3 句话）            ← 痛点和解决方案概述

## 它能做什么                   ← 功能清单，了解这个用例的能力边界
## 所需技能                     ← ⚠️ 必须先完成这里的安装，再执行后续步骤
## 如何设置                     ← 核心操作步骤，按顺序执行
## 实用建议                     ← 踩坑经验，执行前建议阅读
## 相关链接                     ← 参考资料和工具仓库

---                             ← 分隔线
## 中国用户适配                 ← 可选，国内平台替代方案

如何执行一个用例

第一步：读懂前置条件

  1. 先看 "所需技能" 章节，确认需要安装哪些 skill
  2. 查看是否需要特殊环境（Docker、Python、特定硬件等）
  3. 查看是否需要 API Key 或账号注册

第二步：识别代码块类型

代码块是否应该执行，取决于 语言标记 + 所在章节：

代码块标记 在"所需技能"或"如何设置"内 在"实用建议"或其他章节内
```bash 执行：在终端运行 不执行：仅作参考（调试技巧、替代命令等）
```text / ```txt 发送给 OpenClaw（提示词） 不执行：通常是输出示例
```json 写入配置文件（上方会说明路径） 不执行：通常是格式示例
```sql 执行：数据库初始化/建表语句 不执行：仅作查询示例
```python 保存为 .py 并执行 不执行：仅作参考
```yaml / ```markdown 按上下文判断 通常是模板/展示

简单规则：只执行"所需技能"和"如何设置"两个章节内的代码块。其他章节的代码块一律视为参考，不执行。

第三步：按顺序执行

  1. 按 "如何设置" 章节的步骤编号顺序执行
  2. 每步执行后确认结果正常再进入下一步
  3. 如果某步提到"试一试：..."——这是验证点，执行它来确认前面的配置生效

第四步：处理凭证

  • $VARIABLE_NAME 或 ${VARIABLE_NAME} = 环境变量，需要用户提供真实值
  • 带 YOUR_ 前缀的占位符（如 YOUR_API_KEY）= 需要替换为真实值
  • 永远不要在配置文件中硬编码凭证，使用环境变量或 .env 文件

特殊情况处理

含国内适配的用例

如果用例底部有 ## 中国用户适配 章节：

  • 国内用户优先按适配章节操作（替代工具、替代 API、替代推送渠道）
  • 适配章节通常会标注哪些国际方案在国内不可用及原因

国内原创用例（文件名 cn- 开头）

这些用例专为国内生态设计（飞书/钉钉/企业微信/小红书等），没有国际版本对应。直接按步骤执行即可。

多方案用例

有些用例提供多个方案（如"方案一/方案二/方案三"），通常按难度或功能递进排列。选择适合你环境的方案即可，不需要全部执行。

需要付费服务的步骤

部分用例依赖付费 API 或订阅服务。文中通常会标注费用信息。如果你在测试阶段：

  • 优先使用免费额度或沙箱环境
  • 标注为"付费"的步骤可以先跳过，不影响理解整体流程

用例质量信号

以下信号帮助你判断用例的可靠程度：

信号 含义
引用了高 star 开源项目（1000+） 依赖成熟可靠
有 clawhub install 命令 使用官方技能市场，安装简单
有具体的效果数据（成本、耗时、输出示例） 作者实际验证过
"实用建议"中提到具体踩坑经验 来自真实使用
明确标注了限制和不适用场景 作者诚实，信息可信
技能 star 数 < 100 或未标注 需谨慎评估，建议先用非关键场景测试

用例分类速查

文件名模式 类型 示例
cn-*.md 国内原创 cn-feishu-ai-assistant.md
含 ## 中国用户适配 国际+国内适配 earnings-tracker.md
其他 纯国际用例 daily-reddit-digest.md

常见问题

Q: 代码块中的注释是中文还是英文？ A: 注释为中文，代码和命令为英文。这是本仓库的统一约定。

Q: 提示词（text 代码块）应该用中文还是英文发送？ A: 默认保留英文原文效果最佳。如果用例提供了中文版提示词，通常在"中国用户适配"章节中。

Q: 执行某步报错了怎么办？ A: 先看"实用建议"章节是否提到了这个问题。如果没有，检查前置条件是否满足、环境变量是否设置、网络是否通畅。

Q: 如何判断用例是否过时？ A: 查看"相关链接"中引用的工具仓库是否仍在维护（最近 push 时间）。如果引用的技能已下架或 API 已变更，该用例可能需要更新。