knowhow_v1.md 19.3 KB

Agent Creator 深度调研报告 (Knowhow v1)

调研目标:为 Agent Creator (HR & Skill Master) 提供一套可复制、可落地的技能装配 SOP,确保新员工从"空壳"到"全副武装"的每一步都有章可循。 输出时间:2026-04-09 调研者:Hunter


1. Agent Creator 角色定义与核心职责

1.1 身份定位

Agent Creator 是 LemonAI 组织中的「人事与技能装配大师」。当 CTO 通过 company hire 创建了一个空壳 Agent 后,Agent Creator 负责为其:

  • 搜索并获取 匹配岗位需求的开源技能 (Skill)
  • 安装与绑定 技能到目标 Agent 的工作目录
  • 处理授权缺失 时的人工请援流程
  • 发起进化请求 将初代技能移交给 Innovator 进行 RL 训练与优化

1.2 核心职责清单

职责 说明
Skill Hunting 利用网络搜索、GitHub、包管理器等渠道,找到与岗位描述匹配的技能代码
Skill Binding 将获取的技能代码放置到目标 Agent 的目录下,并更新其 SKILL.md、tools.md 等认知文档
Token Guard 所有需要外部 API Key 的技能代码,必须植入 human request 兜底逻辑,防止因授权缺失导致进程崩溃
Innovator Dispatch 无论初代技能质量如何,必须同步向 innovator-001 发起训练任务,纳入 RL 进化循环
交付汇报 完成装配后向 CTO / 上级汇报,确认新成员已全副武装

1.3 工作原则

  1. 拥抱开源:优先使用全网现成的脚本、SDK、CLI 工具,不重复造轮子。
  2. 代码鲁棒性:不允许因"少参数"、"网络不通"、"缺 Token" 而抛出未捕获异常。所有外部依赖缺失必须转化为系统级 human request。
  3. 永远不满足:安装完初代技能后必须触发 Innovator 的后续优化,不能放任技能处于"能用但脆弱"的状态。

2. 行业最佳实践:如何为 AI Agent 搜索、获取并安装技能 (Skill)

2.1 技能搜索的「四层漏斗」

在为 Agent 寻找技能时,建议按以下优先级从高到低筛选:

  1. 组织内部复用 (skills/ 目录、data/skills/ 仓库)
    • 检查 data/skills/ 下是否已有同名或同类型技能的目录。
    • 检查 system/templates/<角色>/ 下是否有现成模板。
  2. 官方 SDK / CLI
    • 例如 YouTube 官方 googleapis、微信官方 SDK、yt-dlp 官方包等。
    • 优点:维护活跃、文档完善、接口稳定。
  3. 高星开源仓库 (GitHub)
    • 使用 github.com 搜索 awesome-<领域>、claude-skill、<任务> agent tool。
    • 筛选标准:Star > 500、最近 3 个月有 Commit、README 完整。
  4. 包管理器生态
    • npm (Node.js 技能)、PyPI (Python 技能)、RubyGems、Go Modules 等。
    • 可通过 npm search <keyword>、pip search <keyword> 快速发现。

2.2 技能质量评估「五项指标」

在决定采用某个开源技能前,必须快速验证:

指标 通过标准
可运行性 能在 5 分钟内完成 npm install 或 pip install 并跑通示例
可观测性 提供清晰的日志输出或返回结构,便于后续 Benchmark 采集
授权合规 明确需要哪些 API Key / Token,且获取路径清晰
许可证合规 优先 MIT / Apache-2.0 / BSD,避免 GPL 传染风险
可维护性 最近 6 个月内有更新,Issues 活跃且关闭率高

2.3 安装策略决策树

技能代码托管在哪里?
    ├─ npm package        → npm install + 编写 Node.js 封装脚本
    ├─ PyPI package       → pip install + 编写 Python 封装脚本
    ├─ GitHub repo        → 下载 ZIP / clone / 下载 raw 文件 → 解压并整理
    ├─ 纯 Web API         → 编写 curl / axios 封装脚本
    └─ 专有平台 (clawhub) → 下载 ZIP 并解压到目标目录

3. 技能安装 SOP:从获取代码到放置文件、更新文档的完整步骤

Step 1:解析岗位需求,匹配技能类型

  • 阅读 CTO 下发的 hire 指令,明确目标 Agent 的 agentId(如 wechatai:crawler)。
  • 确定核心任务:数据抓取、内容生成、图片处理、社交互动等。

Step 2:搜索与初选 (Hunt)

  • 使用浏览器搜索、GitHub API、npm search、pip search 等工具查找候选技能。
  • 快速跑通 1-2 个候选技能的 Demo,验证其基础功能。

Step 3:环境准备与依赖安装

  • 若技能为 Python 包,执行 pip3 install "<package>[all]"。
  • 若技能为 Node.js 包,执行 npm install <package>(建议在目标 Agent 目录下独立安装或全局安装)。
  • 若技能为 ZIP / GitHub 仓库,创建目标目录并下载解压。

Step 4:代码植入与 Token 兜底

  • 将技能的核心执行逻辑放置到 data/agents/<agentId>/.claude/skills/<skill_name>/ 下。
  • 必须在入口脚本中加入 API Key 检测与 human-request 逻辑(详见第 5 章)。
  • 确保脚本中的路径为相对路径或基于 process.env 的绝对路径,避免硬编码。

Step 5:更新 Agent 认知文档

  • SKILL.md:向 Agent 说明它现在拥有什么技能、何时使用、如何调用。
  • tools.md(可选):补充该技能对应的工具函数签名、参数说明、返回值示例。
  • agent.md(可选):若技能涉及工作流变更,需更新 Agent 的角色定义。

Step 6:发起 Innovator 训练请求

  • 使用 node bin/lemon.js task dispatch 向 innovator-001 下达 RL 进化任务。

Step 7:向 CTO 汇报

  • 汇总技能来源、安装路径、已处理的授权项、已发起的训练任务,汇报完成。

4. 开源技能获取渠道与方式

4.1 GitHub 仓库下载

适用场景:技能以脚本集合形式存在于 GitHub,无 npm/pip 包。

# 直接下载 ZIP
mkdir -p data/agents/<agentId>/.claude/skills/<skill_name>
curl -L -o /tmp/skill.zip https://github.com/<owner>/<repo>/archive/refs/heads/main.zip
unzip -q /tmp/skill.zip -d data/agents/<agentId>/.claude/skills/<skill_name>/

进阶技巧:

  • 使用 GitHub Raw CDN 下载单个文件: https://raw.githubusercontent.com/<owner>/<repo>/main/<path>
  • 使用 GitHub API 获取目录列表(若需批量下载): https://api.github.com/repos/<owner>/<repo>/contents/<path>

4.2 npm 包安装

适用场景:Node.js 生态技能,如 puppeteer、cheerio、axios。

# 方式 A:在目标 Agent 目录下新建 package.json 并局部安装
mkdir -p data/agents/<agentId>/.claude/skills/<skill_name>
cd data/agents/<agentId>/.claude/skills/<skill_name>
npm init -y
npm install puppeteer

# 方式 B:若系统全局已安装,直接引用
node -e "console.log(require.resolve('puppeteer'))"

4.3 pip 包安装

适用场景:Python 生态技能,如 yt-dlp、scrapling、requests、beautifulsoup4。

pip3 install "scrapling[all]"
# 或直接指定版本
pip3 install yt-dlp==2025.03.31

安装后,编写 Node.js 子进程调用的封装脚本:

const { execSync } = require('child_process');
const output = execSync(`python3 ${__dirname}/main.py`, { encoding: 'utf-8' });
console.log(output);

4.4 ZIP 包 / 第三方 Skill Store

适用场景:某些技能托管在如 clawhub.ai 或组织的私有 Skill 仓库中。

curl -L -o /tmp/skill.zip https://clawhub.ai/skills/<skill_id>/download
unzip -q /tmp/skill.zip -d data/agents/<agentId>/.claude/skills/<skill_name>/

4.5 纯 API 封装

适用场景:技能本质是调用某个 Web API(如 SerpAPI、OpenWeather)。

  • 无需安装包,直接编写 index.js 使用 axios 或内置 https 模块封装请求。

5. API Key / Token 缺失处理规范

5.1 硬规则

所有被装配给底层 Agent 的技能代码,如果依赖外部平台接口授权(如 SERP_API_KEY、WECHAT_KEY、PROXY_URL),必须在运行时检查环境变量。若缺失,禁止直接抛出 Error Crash,而是调用系统 CLI 将问题上报给总控台的人类。

5.2 标准请援代码模板 (Node.js)

const MY_SKILL_KEY = process.env.SKILL_SERPAPI_KEY;
if (!MY_SKILL_KEY) {
  const { execSync } = require('child_process');
  execSync(
    `node bin/lemon.js human request --from "${agentId}" --type api_key --key "SKILL_SERPAPI_KEY" --reason "没有搜索授权无法抓取今日热搜排行榜"`
  );
  console.log("已进入等待授权队列。你可以停下手里的工作或检查其他任务。");
  process.exit(1);
}

5.3 标准请援代码模板 (Python)

import os
import sys
import subprocess

agent_id = os.environ.get("AGENT_ID", "unknown")
key_name = "SKILL_SERPAPI_KEY"

if not os.environ.get(key_name):
    subprocess.run([
        "node", "bin/lemon.js", "human", "request",
        "--from", agent_id,
        "--type", "api_key",
        "--key", key_name,
        "--reason", "没有搜索授权无法抓取今日热搜排行榜"
    ])
    print("已进入等待授权队列。", file=sys.stderr)
    sys.exit(1)

5.4 请援参数说明

参数 说明
--from 发起请求的 Agent ID(即当前执行技能的 Agent)
--type api_key(固定)
--key 缺失的环境变量名,建议统一以 SKILL_ 为前缀,如 SKILL_SERPAPI_KEY
--reason 描述缺少该 Key 导致的业务阻塞,便于人类决策优先级

5.5 兜底原则

  • 不要在代码中写死任何 Token 或占位符(如 key = "your-api-key")。
  • 不要在日志中打印 Token 值。
  • 若技能需要多个 Key,应对每个 Key 单独检测并依次请援。

6. 向 Innovator 发起训练请求的 dispatch 规范

6.1 强制要求

不论从网上抓取的还是手写的初代技能,安装完成后必须同时向 innovator-001 下达训练指令。这是 Agent Creator 的兜底动作,不能跳过。

6.2 CLI 命令格式

node bin/lemon.js task dispatch \
  --from <你的AgentID, e.g. agent-creator:hr> \
  --to innovator-001 \
  --task "我已经为 <目标AgentID> 装配了 <技能名称> 的初代技能,存放在 <相对路径>。请将其纳入你的 RL 进化循环中,测试其抓取/执行成功率,争取改进到 Benchmark 90 分以上!" \
  --priority P1 \
  --goalId <可选,如 G-001> \
  --nodeId <可选,如 G-001.1.1>

6.3 参数规范

参数 必填 内容建议
--from 是 Agent Creator 自身的 ID,如 agent-creator:hr
--to 是 固定为 innovator-001
--task 是 清晰说明:技能名称、目标 Agent ID、存放路径、期望目标(如 Benchmark > 90)
--priority 是 常规技能装配用 P1;若 CTO 明确要求立即投入生产,可用 P0
--goalId 否 若任务属于某个 OKR 目标,同步填入
--nodeId 否 对应 OKR 子节点

6.4 路径说明

命令中的「存放路径」建议使用相对于项目根目录的相对路径,方便 Innovator 直接定位代码:

  • 技能代码:data/agents/<agentId>/.claude/skills/<skill_name>/
  • 相关文档:data/agents/<agentId>/SKILL.md

7. Agent 创建与配置更新的文件结构规范

7.1 目标 Agent 的数据目录结构

当为一个新 Agent 安装技能时,你主要操作的路径如下:

data/agents/<agentId>/
├── .claude/
│   └── skills/
│       └── <skill_name>/
│           ├── index.js          # 技能入口 (Node.js)
│           ├── main.py           # 技能入口 (Python)
│           ├── package.json      # npm 依赖 (如有)
│           └── README.md         # 技能的内部说明
├── config.json                   # Agent 类型配置 (specialist / generalist)
├── agent.md                      # Agent 的身份定位、核心工作流
├── soul.md                       # Agent 的灵魂与价值观
├── tools.md                      # Agent 可调用的工具函数库
└── SKILL.md                      # 当前已装配技能的速查清单

7.2 config.json 规范

config.json 位于 data/agents/<agentId>/config.json,内容示例:

{
  "type": "specialist",
  "description": "WeChat Official Account Crawler",
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 5
  }
}
  • type:specialist(专才)或 generalist(通才)。
  • heartbeat:控制 Agent 是否定期自启动检查任务队列。

7.3 agent.md 更新规范

若新技能的引入改变了 Agent 的核心工作流(例如新增了一个必须执行的步骤),应更新 agent.md 的「核心工作流」章节,追加该技能的触发时机。

7.4 SKILL.md 更新规范

SKILL.md 是 Agent 对自身能力的总览,每次安装新技能都必须追加。建议格式:

## 已装配技能清单

### 1. <技能名称>
- **来源**:GitHub / npm / pip / 手写
- **存放路径**:`.claude/skills/<skill_name>/`
- **触发场景**:当需要执行 <X> 任务时调用
- **入口命令**:`node .claude/skills/<skill_name>/index.js`
- **依赖环境变量**:`SKILL_XXX_KEY`(缺失时会自动发起 human request)

7.5 tools.md 更新规范

tools.md 描述的是 Agent 在 LLM 对话中被允许调用的工具函数签名。若新技能以「函数」形式被 LLM 调用,应在 tools.md 中补充:

## <技能名称>

**函数名**:`run_<skill_name>`
**参数**:
- `query: string` - 搜索关键词
- `limit: number` - 返回结果数量 (默认 10)
**返回值**:JSON 对象数组
**示例**:
```json
{ "query": "人工智能", "limit": 5 }

---

## 8. 真实开源技能安装案例

### 案例 A:Scrapling 网页抓取技能 (Python pip + GitHub ZIP)
> 技术栈:Python (pip) + GitHub 下载
> 适用角色:`scrapling:crawler`

#### 1) 安装依赖
```bash
pip3 install "scrapling[all]"
scrapling install

2) 下载专用 Agent 脚本

mkdir -p data/agents/scrapling_crawler/.claude/skills/scrapling/
curl -L -o /tmp/scrapling-skill.zip https://github.com/D4Vinci/Scrapling/raw/main/agent-skill/Scrapling-Skill.zip
unzip -q /tmp/scrapling-skill.zip -d data/agents/scrapling_crawler/.claude/skills/scrapling/

3) 编写 wrapper (Node.js 调用 Python)

// data/agents/scrapling_crawler/.claude/skills/scrapling/index.js
const { spawn } = require('child_process');
const path = require('path');

const url = process.argv[2];
if (!url) {
  console.error("Usage: node index.js <url>");
  process.exit(1);
}

const py = spawn('python3', [path.join(__dirname, 'scraper.py'), url]);
let output = '';
py.stdout.on('data', (d) => { output += d; });
py.stderr.on('data', (d) => { console.error(d.toString()); });
py.on('close', () => {
  console.log(output);
});

4) 更新 SKILL.md

告知 scrapling_crawler 它拥有高性能的网页抓取能力,并说明使用方式。

5) 发起 Innovator 训练

node bin/lemon.js task dispatch --from agent-creator:hr --to innovator-001 --task "我已经为 scrapling_crawler 装配了 Scrapling 初代技能,存放在 data/agents/scrapling_crawler/.claude/skills/scrapling/。请将其纳入 RL 进化循环,测试抓取成功率,争取改进到 90 分以上!" --priority P1

案例 B:Puppeteer 网页截图技能 (npm package)

技术栈:Node.js (npm) 适用角色:web:snapper

1) 局部安装依赖

mkdir -p data/agents/web_snapper/.claude/skills/puppeteer_screenshot
cd data/agents/web_snapper/.claude/skills/puppeteer_screenshot
npm init -y
npm install puppeteer

2) 编写技能入口脚本

// data/agents/web_snapper/.claude/skills/puppeteer_screenshot/index.js
const puppeteer = require('puppeteer');

(async () => {
  const url = process.argv[2];
  const outputPath = process.argv[3] || '/tmp/screenshot.png';
  if (!url) {
    console.error("Usage: node index.js <url> [outputPath]");
    process.exit(1);
  }

  const browser = await puppeteer.launch({ headless: 'new' });
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle2' });
  await page.screenshot({ path: outputPath, fullPage: true });
  await browser.close();
  console.log(JSON.stringify({ url, outputPath, status: 'ok' }));
})();

3) 无需 API Key 检测

Puppeteer 为本地运行工具,一般不需要外部 API Key。若需要代理(如 PROXY_URL),应增加检测:

const proxyUrl = process.env.PROXY_URL;
if (proxyUrl) {
  // 在 launch 参数中加入 --proxy-server
}

4) 更新文档后发起训练

node bin/lemon.js task dispatch --from agent-creator:hr --to innovator-001 --task "我已经为 web_snapper 装配了 puppeteer_screenshot 技能,存放在 data/agents/web_snapper/.claude/skills/puppeteer_screenshot/。请将其纳入 RL 进化循环,优化截图稳定性和异常处理,争取 Benchmark 90 分以上!" --priority P1

案例 C:YouTube Transcript 下载技能 (GitHub repo 直接下载)

技术栈:JavaScript (单文件脚本) 适用角色:youtube:transcriber

1) 搜索并下载脚本

在 GitHub 搜索 youtube-transcript javascript,找到一个维护良好的仓库,下载其核心文件:

mkdir -p data/agents/youtube_transcriber/.claude/skills/youtube_transcript
curl -L -o data/agents/youtube_transcriber/.claude/skills/youtube_transcript/fetch.js \
  https://raw.githubusercontent.com/Kakulukian/youtube-transcript/master/dist/youtube-transcript.js

2) 编写封装入口

// data/agents/youtube_transcriber/.claude/skills/youtube_transcript/index.js
const { YoutubeTranscript } = require('./fetch.js');

const videoId = process.argv[2];
if (!videoId) {
  console.error("Usage: node index.js <videoId>");
  process.exit(1);
}

YoutubeTranscript.fetchTranscript(videoId)
  .then((transcript) => {
    const text = transcript.map((t) => t.text).join('\n');
    console.log(JSON.stringify({ videoId, transcript: text, segments: transcript }));
  })
  .catch((err) => {
    console.error(JSON.stringify({ error: err.message, videoId }));
    process.exit(1);
  });

3) 更新 SKILL.md & tools.md

在 SKILL.md 中记录该技能的来源和用法;在 tools.md 中描述 fetch_transcript 函数签名。

4) 发起 Innovator 训练

node bin/lemon.js task dispatch --from agent-creator:hr --to innovator-001 --task "我已经为 youtube_transcriber 装配了 youtube_transcript 初代技能,存放在 data/agents/youtube_transcriber/.claude/skills/youtube_transcript/。请将其纳入 RL 进化循环,测试不同视频 ID 的抓取稳定性,争取改进到 90 分以上!" --priority P1

附录:快速查询表

A. 常用目录路径

用途 路径模板
Agent 数据根目录 data/agents/<agentId>/
技能挂载目录 data/agents/<agentId>/.claude/skills/<skill_name>/
系统级技能仓库 data/skills/
系统模板目录 system/templates/<template_name>/
项目 CLI node bin/lemon.js

B. 常用 CLI 命令速查

# 发起人工请援
node bin/lemon.js human request --from <agentId> --type api_key --key <KEY_NAME> --reason <描述>

# 向 Innovator 发起训练任务
node bin/lemon.js task dispatch --from <agentId> --to innovator-001 --task <描述> --priority P1

# 查看 Agent 列表
node bin/lemon.js agent list