ocai-search-agent-skill 0.1.4

package/CURSOR_SETUP.md

@@ -0,0 +1,68 @@
+# Cursor 接入说明（最小可用）
+
+本项目在 Cursor 中使用时，需要两部分：
+
+- MCP server 接入（让 Cursor 能调用采集工具）
+- 规则加载（让 Cursor 按 Skill 逻辑分流）
+
+## 1) 准备环境
+
+在项目根目录执行：
+
+```bash
+./ocai-skill/ocai install-env
+./ocai-skill/ocai doctor
+./ocai-skill/ocai set-token "YOUR_TOKEN"
+```
+
+Windows PowerShell：
+
+```powershell
+.\ocai-skill\ocai.ps1 install-env
+.\ocai-skill\ocai.ps1 doctor
+.\ocai-skill\ocai.ps1 set-token "YOUR_TOKEN"
+```
+
+## 2) 配置 Cursor MCP
+
+在 Cursor 的 MCP 配置中添加一个 server（stdio 模式）：
+
+```json
+{
+  "mcpServers": {
+    "collection-service": {
+      "command": "python",
+      "args": [
+        "ocai-skill/skills/research-collect-orchestrator/mcp/collection_mcp_server.py"
+      ]
+    }
+  }
+}
+```
+
+说明：仓库里已有 `mcp-config.example.json` 可直接参考。
+
+## 3) 规则文件
+
+仓库已包含 Cursor 规则：
+
+- `.cursor/rules/ocai-collection-skill.mdc`
+
+该规则会约束 Cursor：
+
+- 先检查 token，再执行工具
+- 只有明确采集意图才调用 `collect`
+- 查询意图优先使用 `list` / `query`
+
+## 4) 验证是否生效
+
+在 Cursor 对话中测试：
+
+- “帮我查任务名包含‘小米’的任务” -> 应走 `list_tasks_by_name`
+- “帮我采集百度里‘小米 su7 新款’” -> 应走 `collect`
+
+如果没生效，优先检查：
+
+- Python 是否为 3.10+
+- MCP server 路径是否正确
+- token 是否已设置

package/README.md

@@ -0,0 +1,64 @@
+# OCAI Search Agent
+
+这是一个面向 Agent 的采集 Skill 项目，核心由三部分组成：
+
+- `ocai-skill/skills/research-collect-orchestrator/SKILL.md`：交互编排规则
+- `ocai-skill/skills/research-collect-orchestrator/mcp/collection_mcp_server.py`：MCP 服务实现
+- `ocai-skill/ocai`：统一 CLI 入口
+- `ocai-skill/ocai.ps1`：Windows PowerShell CLI 入口
+
+## 3 分钟上手（推荐）
+
+在项目根目录执行：
+
+```bash
+which python && python -V
+./ocai-skill/ocai install-env
+./ocai-skill/ocai doctor
+./ocai-skill/ocai set-token "YOUR_TOKEN"
+./ocai-skill/ocai collect --baidu-word "小米 su7 新款"
+```
+
+## 常用命令
+
+```bash
+# 环境与依赖检查
+./ocai-skill/ocai init
+./ocai-skill/ocai doctor
+
+# token 管理
+./ocai-skill/ocai token-status
+./ocai-skill/ocai set-token "YOUR_TOKEN"
+./ocai-skill/ocai clear-token
+
+# 采集与查询
+./ocai-skill/ocai collect --baidu-word "关键词"
+./ocai-skill/ocai list "任务名称"
+./ocai-skill/ocai query --task-id <32位task_id>
+```
+
+## Windows（PowerShell）用法
+
+在项目根目录执行：
+
+```powershell
+python --version
+.\ocai-skill\ocai.ps1 install-env
+.\ocai-skill\ocai.ps1 doctor
+.\ocai-skill\ocai.ps1 set-token "YOUR_TOKEN"
+.\ocai-skill\ocai.ps1 collect --baidu-word "小米 su7 新款"
+```
+
+## MCP 集成（通用示例）
+
+可参考 `mcp-config.example.json`（使用 stdio 启动，不依赖 Docker）。
+
+## Cursor 使用
+
+可直接参考 `CURSOR_SETUP.md`（包含 MCP 接入、规则文件与验证步骤）。
+
+## 常见问题
+
+- 缺少 `mcp` 依赖：执行 `./ocai-skill/ocai install-env`
+- Python 版本低于 3.10：升级后重试
+- `token_invalid`：执行 `./ocai-skill/ocai set-token "NEW_TOKEN"` 后重试

package/mcp-config.example.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "collection-service": {
+      "command": "python",
+      "args": [
+        "ocai-skill/skills/research-collect-orchestrator/mcp/collection_mcp_server.py"
+      ]
+    }
+  }
+}

package/ocai-skill/ocai

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$SCRIPT_DIR/skills/research-collect-orchestrator/scripts/ocai-cli" "$@"

package/ocai-skill/ocai.ps1

@@ -0,0 +1,39 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Get-PythonCommand {
+  if ($env:OCAI_PYTHON) {
+    return @($env:OCAI_PYTHON)
+  }
+
+  if (Get-Command python -ErrorAction SilentlyContinue) {
+    return @("python")
+  }
+
+  if (Get-Command py -ErrorAction SilentlyContinue) {
+    return @("py", "-3")
+  }
+
+  if (Get-Command python3 -ErrorAction SilentlyContinue) {
+    return @("python3")
+  }
+
+  throw "未找到 Python，请先安装 Python 3.10+ 并加入 PATH。"
+}
+
+$scriptPath = Join-Path $PSScriptRoot "skills/research-collect-orchestrator/scripts/ocai_cli.py"
+$reqPath = Join-Path $PSScriptRoot "skills/research-collect-orchestrator/deps/requirements.txt"
+$pythonParts = Get-PythonCommand
+$pythonExe = $pythonParts[0]
+$pythonBaseArgs = @()
+if ($pythonParts.Count -gt 1) {
+  $pythonBaseArgs = $pythonParts[1..($pythonParts.Count - 1)]
+}
+
+if ($args.Count -gt 0 -and $args[0] -eq "install-env") {
+  & $pythonExe @pythonBaseArgs -m pip install -r $reqPath
+  exit $LASTEXITCODE
+}
+
+& $pythonExe @pythonBaseArgs $scriptPath @args
+exit $LASTEXITCODE

package/ocai-skill/scripts/ocai-init.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Python 版本检查（推荐 3.10+）
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "未找到 python3，请先安装 Python 3.10+"
+  exit 1
+fi
+
+python3 - <<'PY'
+import sys
+if sys.version_info < (3, 10):
+    raise SystemExit("当前 Python 版本低于 3.10，请升级后再执行（推荐 3.10+）")
+PY
+
+bash "ocai-skill/skills/research-collect-orchestrator/scripts/ocai-cli" init

package/ocai-skill/skills/research-collect-orchestrator/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: unified-research-collection
+description: Interactively orchestrate MCP web collection using `collect` tool. Use when the user requests to crawl/collect/extract structured data from URLs or platform keywords.
+---
+
+# Collection Orchestration (Interactive)
+
+## 目标
+
+这是一个“交互式采集任务流”的 Skill：只有在用户明确要求采集/抓取/提取等时才会下发任务并按固定频率查询；如果用户不要求采集，则优先做“任务列表查询/已有 taskId 结果查询”，否则只给出采集建议并等待用户确认。
+
+## Step 0：Token 检查与临时存储（必做）
+
+1. 调用 MCP 工具 `get_token_status`。
+2. 如果 `has_token=false`：
+   - 提示用户先在你们平台完成登录，生成当前密钥 token。
+   - 请用户把 token 提供给对话（或在参数里输入）。
+   - 调用 MCP 工具 `set_token(token)` 把 token 临时写入文件。
+3. 在后续调用中如果任一工具返回 `error=token_invalid`：
+   - 立刻向用户索要新的 token。
+   - 调用 `set_token(token)` 写入临时文件。
+   - **保持本次任务的同一组** `task_urls` / `ai_fields` / `poll_interval_sec` / `poll_attempts` 以及 `task_max_page` 不变，重新执行当前分支（可能是 `collect` / `list_tasks_by_name` / `query_success_task_data`）。
+
+## 环境准备（降低上手难度）
+
+为了避免工具调用失败（如 `ModuleNotFoundError`），请在 MCP Server 运行的同一个 Python 环境里安装依赖。
+推荐 Python 版本：`3.10+`。
+
+先确认当前解释器（避免装到错误环境）：
+
+```bash
+which python && python -V
+```
+
+统一推荐安装命令（在项目根目录执行）：
+
+```bash
+./ocai-skill/ocai install-env
+./ocai-skill/ocai doctor
+```
+
+如果你确实要手动安装，也可以在目标环境执行（把环境名按实际替换）：
+
+```bash
+conda run -n <your-env> pip install -r ocai-skill/skills/research-collect-orchestrator/deps/requirements.txt
+```
+
+如果你不确定环境名，请先在对话里告诉用户“你的 Cursor/MCP 是用哪个 conda 环境运行的”，然后把对应命令展示出来。
+
+## 快速开始（复制即用）
+
+在项目根目录按顺序执行：
+
+```bash
+./ocai-skill/ocai install-env
+./ocai-skill/ocai doctor
+./ocai-skill/ocai init
+./ocai-skill/ocai set-token "YOUR_TOKEN"
+./ocai-skill/ocai collect --baidu-word "小米 su7 新款"
+./ocai-skill/ocai list "任务名称"
+./ocai-skill/ocai query --task-id <32位task_id>
+```
+
+## 常见问题排查
+
+- `ModuleNotFoundError: No module named 'mcp'`
+  - 先执行：`./ocai-skill/ocai install-env`
+  - 再检查：`./ocai-skill/ocai init`
+- `token_invalid`
+  - 重新设置：`./ocai-skill/ocai set-token "NEW_TOKEN"`
+  - 然后按原参数重试同一条命令
+- `python: command not found` 或版本过低
+  - 安装 Python 3.10+，并重新确认：`which python && python -V`
+
+## Step 1：识别输入类型（URL or 关键词）
+
+- 若用户直接输入了 URL：用它作为 `task_urls`。
+- 若用户输入的是“百度/平台关键词/主题”（例如“百度里习近平的内容”）：
+  - 判断是否是“要采集/抓取/提取/下发任务”的意图；
+  - 若需要入口页类型（百度新闻/百度百科/百度搜索），向用户做最少追问或采用默认（百度新闻检索页）。
+
+## Step 2：判断用户是否“要采集”
+
+当用户语句中出现任意命令词：`采集/抓取/提取/入库/下发/抓取正文/结构化`，则进入 Step 3。
+否则进入 Step 4（任务查询/建议采集）。
+
+## Step 3：下发采集任务并等待查询（固定查询：6 秒一次，查询 10 次）
+
+1. 组装 `ai_fields`
+   - 用户指定字段：按用户字段构造
+   - 否则使用默认字段：`title`/`publish_time`/`content`/`author`
+2. 调用 MCP 工具 `collect`
+   - `task_max_page`：默认 `10`（如用户说“最多 N 页”就改成 N）
+   - `poll_interval_sec = 6`
+   - `poll_attempts = 10`
+3. MCP Server 会在内部按固定频率轮询任务状态：
+   - 若在窗口内完成：返回 `status=completed` 与 `data.items`
+   - 若窗口结束仍未完成：返回 `status=collecting`、包含 `task_id` 和当前进度
+4. 如果返回 `status=collecting`：
+   - 提示用户“任务已下发到系统内正在采集中”
+   - 告知用户可以登录平台用 `task_id` 查进度/查看结果
+
+## Step 4：任务查询/建议采集（非采集意图）
+
+如果用户没有出现采集命令词（即用户并未明确要求采集/抓取/提取）：
+1. 若用户在问“任务列表/任务名称包含/查询任务/task/page”：
+   - 从输入提取 `task_name`
+   - 调用 MCP 工具 `list_tasks_by_name` 返回匹配到的 `records`
+2. 若用户提供 `task_id`，并且是在请求“返回结果/查询数据/success-task-data/采集结果”：
+   - 调用 MCP 工具 `query_success_task_data` 返回字段还原后的 `items`
+3. 否则（用户未明确要查具体结果，也未明确要采集）：
+   - 将输入尽量转成可采集的入口页 URL（如百度检索页）
+   - 不调用 MCP `collect`（因此不会触发 insert，也不会产生新的采集任务）
+   - 返回“我可以帮你采集”的建议与需要用户确认的信息：
+     - 建议采集入口 URL
+     - 建议的默认字段（title/publish_time/content/author，或用户指定字段）
+   - 请用户明确回复一次“采集/抓取/提取/下发/结构化”（或直接使用 `/ocai-cli` 命令）后，才进入 Step 3 真正下发任务
+
+## 默认值与字段模板
+
+- `task_max_page = 10`
+- `is_use_proxy = false`
+- 默认 `ai_fields`：
+  - `title`（type_code `10`）
+  - `publish_time`（type_code `40`）
+  - `content`（type_code `10`）
+  - `author`（type_code `10`）
+
+## 运行 MCP Server（给 MCP 客户端用）
+
+- stdio（本地）：`bash skills/research-collect-orchestrator/scripts/run_collection_server.sh`
+- HTTP/SSE：`bash skills/research-collect-orchestrator/scripts/run_collection_server.sh --host 0.0.0.0 --port 11900`
+
+## 参考
+
+- 输出协议：`docs/reference.md`

package/ocai-skill/skills/research-collect-orchestrator/deps/requirements.txt

@@ -0,0 +1,7 @@
+python-dotenv>=1.0.0
+mcp[cli]>=1.0.0
+httpx>=0.27.0
+uvicorn[standard]>=0.29.0
+fastapi>=0.111.0
+starlette>=0.37.0
+sse-starlette>=1.6.0

package/ocai-skill/skills/research-collect-orchestrator/docs/reference.md

@@ -0,0 +1,54 @@
+# Collection Orchestrator Reference (Interactive)
+
+## 输入
+
+- 自然语言请求（可能包含 URL，或包含“平台关键词/主题”但未给 URL）
+- 可包含采集字段需求（可选）
+- 可包含最大页数/是否需要代理（可选）
+
+## 必须的 Token 流程
+
+1. 调用 MCP 工具 `get_token_status`
+2. 若 `has_token=false`：提示用户先在你们平台登录获取 token
+3. 调用 MCP 工具 `set_token(token)` 把 token 临时写入服务端文件
+
+## 依赖安装（建议先做）
+
+在运行你的 MCP Server 的同一个 Python 环境里安装依赖：
+推荐 Python 版本：`3.10+`。
+
+```bash
+python3 -m pip install -r skills/research-collect-orchestrator/deps/requirements.txt
+```
+
+如果在工具调用时报 `ModuleNotFoundError`，直接把报错对应的包安装命令输出给用户。
+
+## 调用 MCP 工具 `collect`
+
+- 工具：`collect(task_urls, ai_fields, poll_interval_sec, poll_attempts, task_max_page, is_use_proxy, ...)`
+- `api_key`：在你的实现里是可选的；缺省会从 `COLLECTION_AUTH_TOKEN` 或 token 文件读取
+
+### 默认值
+
+- `task_max_page = 10`
+- `poll_interval_sec = 6`
+- `poll_attempts = 10`
+- 默认 `ai_fields`：`title(10)`, `publish_time(40)`, `content(10)`, `author(10)`
+
+### 输出状态
+
+- `success=false`：失败（常见 `token_missing` / `token_invalid` / HTTP 错误）
+- `status=completed`：已完成，返回 `data.items`
+- `status=collecting`：轮询窗口内未完成，返回 `task_id/progress`，提示用户任务已下发并可到系统内查看
+
+## 非采集意图的快速回填
+
+- 如果用户并未要求“采集/抓取/提取”，但希望你返回信息：
+  - 若在问“任务列表/任务名称包含/查询 task/page”：调用 `list_tasks_by_name` 返回 `records`
+  - 若在问“taskId 的数据/返回结果/success-task-data”：调用 `query_success_task_data` 返回 `items`
+  - 否则：不调用 MCP `collect`（因此不会触发 insert），返回“建议的采集入口 URL 与字段”，并请用户确认是否需要采集
+
+## 查询工具（不会 insert）
+
+- `list_tasks_by_name(task_name, page_num, per_page_record_count, ...)`：按任务名称条件查询任务列表
+- `query_success_task_data(task_id, url_type_code, page_num, max_items, ...)`：查询已有任务的采集结果