OCAI Search Agent

这是一个面向 Agent 的采集 Skill 项目，核心包括：

• ocai-skill/skills/research-collect-orchestrator/mcp/collection_mcp_server.py：MCP 服务
• ocai-skill/skills/research-collect-orchestrator/SKILL.md：编排规则源
• ocai-skill/ocai-entry.cjs：跨平台 CLI 入口（npm/npx 默认走它）
• .cursor/rules/ocai-collection-skill.mdc + .cursor/skills/ocai-project-collector/SKILL.md：Cursor 规则
• .claude/skills/ocai-project-collector/SKILL.md + .claude/commands/ocai-cli.md：Claude Code 侧规则与命令说明

产品地址

• OCAI 数据采集平台（登录入口）：https://ocai.opendatasightai.com/app/login?mode=login

从 npm 使用（推荐）

包名：ocai-search-agent-skill。

两种方式（必须区分）

1. 方式 A：npm i ocai-search-agent-skill（推荐，稳定路径）

   • 包安装到业务项目 node_modules
   • ocai-mcp-setup 生成的 args[0] / requirements.txt 通常是项目内稳定路径
   • 适合长期保存 MCP 配置

2. 方式 B：npx -y ocai-search-agent-skill@latest ...（一次性执行，临时缓存）

   • 命令可直接运行，但包不一定持久安装到项目
   • 路径可能落在 ~/.npm/_npx/... 临时目录
   • 清缓存/换机后该路径可能失效，建议最终在目标项目执行一次 npm i 后再重跑向导

npx -y ocai-search-agent-skill@latest init --all 是“执行命令”，不是“安装到项目”。

# 推荐：参数直接跟在包名后（会调用包内 ocai 入口）
npx -y ocai-search-agent-skill@latest init --all

# 同一入口（等价）：显式写子命令
npx -y ocai-search-agent-skill@latest init --all

不要写：npx -p ocai-search-agent-skill@latest init --all，否则 init 会被当成系统命令。

init / doctor 输出说明

• 默认：输出中文“使用提示”（面向人）
• --json-only：仅输出 JSON（给脚本解析）

配置向导（MCP + 规则/Skill 复制）

ocai-mcp-setup 只打印配置指引，不自动改文件。

cd /path/to/your-app
npm i ocai-search-agent-skill
npx -y ocai-search-agent-skill@latest mcp-setup

也可指定项目路径/解释器：

npx -y ocai-search-agent-skill@latest mcp-setup --project /path/to/your-app --python "/your/python"

向导会要求你手动完成

1. 合并 MCP 配置
   • <项目根目录>/.cursor/mcp.json
   • <项目根目录>/.claude/settings.json
2. 复制 Cursor 规则/Skill
   • .cursor/rules/ocai-collection-skill.mdc
   • .cursor/skills/ocai-project-collector/SKILL.md
3. 复制 Claude Code 规则文件（按官方 skills 目录规范）
   • .claude/commands/ocai-cli.md
   • .claude/skills/ocai-project-collector/SKILL.md

复制后请完全重启 Cursor/Claude Code。

向导“本机探测”里应能看到这两条：

• 包内 Claude 命令: .../.claude/commands/ocai-cli.md
• 包内 Claude Skill: .../.claude/skills/ocai-project-collector/SKILL.md

3 分钟上手（npx）

先创建并激活虚拟环境（推荐固定名：ocaiskill）：

# macOS / Linux
python3 -m venv ocaiskill
source ocaiskill/bin/activate

# Windows PowerShell (蓝色窗口)
python -m venv ocaiskill
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
.\ocaiskill\Scripts\Activate.ps1

:: Windows cmd (黑色窗口)
python -m venv ocaiskill
.\ocaiskill\Scripts\activate.bat

激活后再执行：

npx -y ocai-search-agent-skill@latest install-env
npx -y ocai-search-agent-skill@latest init --all
npx -y ocai-search-agent-skill@latest set-token "YOUR_TOKEN"
npx -y ocai-search-agent-skill@latest collect --baidu-word "小米 su7 新款"

仓库开发模式（克隆本仓库时）

./ocai-skill/ocai install-env
./ocai-skill/ocai doctor
./ocai-skill/ocai set-token "YOUR_TOKEN"
./ocai-skill/ocai collect --baidu-word "关键词"

Windows PowerShell：

.\ocai-skill\ocai.ps1 install-env
.\ocai-skill\ocai.ps1 doctor
.\ocai-skill\ocai.ps1 set-token "YOUR_TOKEN"

常用命令（npx）

# 环境
npx -y ocai-search-agent-skill@latest init --all
npx -y ocai-search-agent-skill@latest doctor
npx -y ocai-search-agent-skill@latest install-env

# token
npx -y ocai-search-agent-skill@latest token-status
npx -y ocai-search-agent-skill@latest set-token "YOUR_TOKEN"
npx -y ocai-search-agent-skill@latest clear-token

# 采集/查询
npx -y ocai-search-agent-skill@latest collect --baidu-word "关键词"
npx -y ocai-search-agent-skill@latest collect --url "https://example.com/article"
npx -y ocai-search-agent-skill@latest list "任务名称关键字"
npx -y ocai-search-agent-skill@latest query --task-id <32位任务ID>

通过模型交互（Cursor / Claude）

1. 先激活 ocaiskill 虚拟环境（见上文）
2. 运行配置向导：npx -y ocai-search-agent-skill@latest mcp-setup
3. 按向导复制 .cursor/.claude 的 rules/skills 文件并重启编辑器
4. 进入对话后可直接让模型执行：
   • “帮我查任务名包含小米的任务”（list）
   • “帮我采集百度里小米 su7 新款”（collect）
   • “根据这个 task_id 查询结果：xxxx”（query）

ETARGET / 版本解析失败

若 npx 提示 No matching version found，通常是 registry 镜像未同步：

1. npm config get registry
2. 必要时切回官方源：npm config set registry https://registry.npmjs.org/
3. 再执行：npx -y ocai-search-agent-skill@latest mcp-setup

常见问题

• 缺依赖（如 ModuleNotFoundError: mcp）：先 install-env 再 init --all
• Python 版本低于 3.10：升级到 3.10+（推荐 3.13）后重试
• token_invalid：set-token "NEW_TOKEN" 后按原参数重试