@talent-scout/skills

@talent-scout/skills 是对 OpenClaw 和 ClawHub 暴露的统一 skill 包。它不重写业务逻辑，而是把采集、处理、评估、查询和 cron 管理整理成单一命令面，既适合 OpenClaw agent 调用，也适合本地命令行使用。

ClawHub 发布时不要直接发布 packages/skills。根据 Agent Skills 规范，发布目录名必须与 SKILL.md 的 name 字段一致；因此需要先构建一个合规的 bundle 目录，再发布该 bundle。

从现在开始，skills 也负责 workspace-data/talents.yaml 的生命周期：包内自带默认模板，首次需要写工作区时会自动复制到 workspace-data/，后续命令统一读取这份工作区配置。

角色定位

• 对外，这是唯一应该安装到 OpenClaw/ClawHub 的 skill 入口
• 对内，它只是薄包装，负责调用其他 @talent-scout/* 包

这条边界很重要：真正的采集、身份识别、评分和评估规则都不应该复制进这个包。

开发前提

• Node.js 22+
• pnpm 10+
• openclaw 已安装
• 若要发布到 ClawHub，需要额外安装 clawhub

在仓库根目录安装依赖：

pnpm install

常用命令

pnpm --filter @talent-scout/skills run skill collect
pnpm --filter @talent-scout/skills run skill process
pnpm --filter @talent-scout/skills run skill evaluate
pnpm --filter @talent-scout/skills run skill pipeline
pnpm --filter @talent-scout/skills run skill query shortlist
pnpm --filter @talent-scout/skills run skill query candidate huandu
pnpm --filter @talent-scout/skills run skill query stats
pnpm --filter @talent-scout/skills run skill export workspace
pnpm --filter @talent-scout/skills run skill export workspace --output /tmp/talent-scout.zip
pnpm --filter @talent-scout/skills run skill config request --request "把 openclaw.batch_size 改成 20"
pnpm --filter @talent-scout/skills run skill cron status
pnpm --filter @talent-scout/skills run skill cron sync
pnpm --filter @talent-scout/skills run skill cron disable talent-pipeline
pnpm --filter @talent-scout/skills run skill cron enable talent-pipeline

export workspace 只会把整个 workspace-data/ 打包成 workspace-data.zip，然后把 zip 的绝对路径打印出来并返回给 OpenClaw。这个 skill 不负责把文件发到 Telegram/Slack/Discord；如果你想把压缩包发给终端用户，应该再调用另一个专门负责文件投递的 OpenClaw skill。

config request 不直接改 YAML；它会把 workspace-data/talents.yaml 的相对引用和用户需求拼成一条 channel 消息，再交给 OpenClaw 侧的 AI 去实际修改。这样 skills 只负责路由和上下文，不负责理解具体配置语义，同时避免把本机绝对路径泄露到外部 channel。

这条命令依赖 openclaw message send 对应的 channel 在当前环境里可用。即使传了 --dry-run，OpenClaw 仍然会检查 channel 是否已配置。

如果你想让 config request 自动知道应该发到哪个 IM 目标，可以在 workspace-data/talents.yaml 里提供默认投递目标：

openclaw:
  delivery:
    channel: telegram
    target: '@your-handle'

如果工作区里还没有 workspace-data/talents.yaml，以下命令会先自动从包内模板复制一份：

• collect
• process
• evaluate
• pipeline
• cron *
• export workspace
• config request

代码结构

• SKILL.md: Agent Skills 入口文件
• src/index.ts: 命令分发器
• src/commands.ts: collect/process/evaluate 的薄包装
• src/query.ts: shortlist、candidate、stats 查询
• src/export.ts: workspace-data 打包与 zip 路径返回
• src/config-request.ts: talents.yaml 变更请求消息拼装与发送
• src/cron.ts: OpenClaw cron 控制
• src/renderers.ts: 终端文本渲染
• src/patches.ts: 运行时 skill patch overlay
• src/workspace-config.ts: workspace-data/talents.yaml 初始化与路径解析
• references/: 发布给 skill 消费者的参考文档

设计思想

1. 统一命令面比“包越多越细”更重要

对 OpenClaw 来说，最稳定的使用方式不是让模型自己猜该调用哪个内部包，而是给它一个明确的、长期稳定的 skill 入口。这个包的价值就是把调用面收口。

2. skill 包必须保持轻量

如果评分规则、身份识别逻辑和查询实现都复制到这里，分发看起来方便，维护时就会立刻失控。这里的实现原则是“只编排，不重写”。

3. patch 是运行时增强，不是替代版本发布

workspace-data/skill-patches/ 里的 patch 用来叠加运行经验，而不是偷偷改写正式源码。稳定经验应该回收到正式版本里，再通过 npm/ClawHub 发布。

命令流

flowchart LR
  A[OpenClaw / CLI] --> B[src/index.ts]
  B --> C[commands.ts]
  B --> D[query.ts]
  B --> E[cron.ts]
  C --> F[@talent-scout/data-collector]
  C --> G[@talent-scout/data-processor]
  C --> H[@talent-scout/ai-evaluator]
  D --> H

如何发布到 ClawHub

ClawHub 发布是这个包的特殊职责。根据项目分发设计，推荐在仓库根目录执行：

pnpm add -g clawhub
clawhub login
pnpm --filter @talent-scout/skills run bundle:clawhub
clawhub publish packages/skills/dist/clawhub/chinese-talent-scout

发布时的注意事项：

• 目录名与 SKILL.md 名称必须一致：ClawHub 要求发布目录名与 SKILL.md frontmatter 中的 name 字段一致。仓库的 bundle:clawhub 脚本会把 SKILL.md 中的 name 重写为 chinese-talent-scout（见 packages/skills/SKILL.md），请在 publish 前确认这一点。
• 如果需要自定义 slug：你可以在 clawhub publish 时使用 --slug <slug> 来指定 ClawHub 上的标识（slug），但发布目录名与 SKILL.md 的 name 字段仍需保持一致。
• CI 中的凭据：在 CI 环境中请把 ClawHub 的访问 token 放入仓库 secrets（例如 CLAWHUB_TOKEN），并在发布前用该 token 登录 clawhub。示例步骤（GitHub Actions / 任意 shell）：

# 安装并登录（CI 中请从 secrets 读取 token）
pnpm add -g clawhub
clawhub login --token "$CLAWHUB_TOKEN"

# 构建 bundle 并发布
pnpm --filter @talent-scout/skills run bundle:clawhub
clawhub publish "$PWD/packages/skills/dist/clawhub/chinese-talent-scout"

• 构建失败排查：若 bundle:clawhub 报错（例如 esbuild 无法解析 Playwright/Chromium-bidi 的内部路径），请先在本地运行 pnpm --filter @talent-scout/skills run bundle:clawhub 并根据报错调整打包 external 列表或安装相应依赖。仓库已对部分 Playwright 路径做了 external 处理以避免常见的打包失败。
• 验证发布内容：发布前可以手动检查 packages/skills/dist/clawhub/<skill-name> 下是否包含 SKILL.md、scripts/talent-scout.mjs 和 references/ 等文件。

如果你使用 clawhub sync，请显式限制同步范围，避免把工作区里无关的 skill 一并发布.

这个 bundle 会：

• 复制符合规范的 SKILL.md
• 复制 references/ 和 talents.yaml
• 生成自包含的 scripts/talent-scout.mjs 与 scripts/talent-scout.sh
• 把发布目录名固定为 chinese-talent-scout，与 SKILL.md 的 name 保持一致

如果你希望 ClawHub 上的 slug 使用别的唯一值，可以在 publish 时显式传 --slug，但 bundle 目录名与 SKILL.md 名称仍必须匹配。

如果你使用 clawhub sync，请显式限制同步范围，避免把工作区里无关的 skill 一并发布。

安全与审核说明

• 凭据预期见 references/credentials.md
• 安全边界见 references/security.md
• export workspace 只创建本地 zip，不上传文件
• config request --dry-run 可用于检查实际发出的消息内容

如何在本地 OpenClaw 环境测试

本地测试分成两层。

1. 先验证命令面

直接在仓库里运行：

pnpm --filter @talent-scout/skills run skill pipeline
pnpm --filter @talent-scout/skills run skill query shortlist

这一步验证的是命令编排、文本渲染和对业务包的调用是否正确。

2. 再验证 OpenClaw skill 装载

OpenClaw 会在工作区的 skills/ 目录加载 skill。一个简单的本地测试方式是先构建 bundle，再把 bundle 目录复制或软链接到某个 OpenClaw 工作区中：

pnpm --filter @talent-scout/skills run bundle:clawhub
mkdir -p ~/openclaw-workspace/skills
ln -s "$(pwd)/packages/skills/dist/clawhub/chinese-talent-scout" ~/openclaw-workspace/skills/chinese-talent-scout
cd ~/openclaw-workspace
openclaw

然后开启一个新的 OpenClaw session，使用类似下面的提示词验证 skill 是否被正确装载：

请使用 talent-scout skill 展示当前 shortlist。

请使用 talent-scout skill 把 workspace-data/talents.yaml 里的 cron 同步到 OpenClaw。

请使用 talent-scout skill 导出当前 workspace-data，并告诉我 zip 文件的本地绝对路径。

如果你已经把 skill 发布到 ClawHub，也可以在 OpenClaw 工作区直接执行：

openclaw skills install chinese-talent-scout

什么时候改这个包

• 需要增加新的统一命令或查询入口
• 需要调整 OpenClaw cron 的用户体验
• 需要补充适合 skill 消费者的参考文档

如果你是在改评分、身份识别、采集规则，请回到对应业务包。

相关文档

• ../../docs/06-openclaw.md
• ../../docs/10-distribution.md