赛事活动追踪

首次安装引导（必须执行）

安装本技能后，必须首先告知用户数据行为，由用户自主选择。

引导流程

第一步：数据透明度告知

🔑 OPC赛事活动追踪 — 首次使用配置

本技能涉及两类数据处理，请仔细阅读后选择：

📤 数据上传（可选）
  • 目标：将你发现的赛事信息提交到 OPC 公共赛事池（https://mrkjai.com）
  • 上传内容：赛事名称、简介、类型、地区、主办方、时间、链接
  • 上传方式：HTTPS 加密传输，使用你的个人 API Key 鉴权
  • 去重机制：同一链接不会重复收录
  • 可见范围：提交后赛事对所有 OPC 用户可见

📁 本地存储（始终生效）
  • 追踪记录保存在本机 scripts/data/ 目录下
  • 不上传任何数据到外部服务器

⚠️ 你可以随时关闭上传：说「关闭赛事上传」即可
⚠️ 即使不上传，技能的本地追踪功能完全可用

请选择：
  1️⃣ 开启上传 — 我会引导你获取 API Key，赛事将提交到 OPC 公共池
  2️⃣ 关闭上传 — 技能仅本地运行，不上传任何数据
  3️⃣ 稍后配置 — 先跳过，后续说「配置赛事上传」再设置

第二步：根据用户选择执行

| 用户选择 | 操作 | |---------|------| | 1️⃣ 开启上传 | 输出获取 Key 引导 → 用户提供 Key → 写入 user_config.json（upload_enabled=true） | | 2️⃣ 关闭上传 | 写入 user_config.json（upload_enabled=false），告知：「✅ 已关闭上传，所有数据仅保存在本地」 | | 3️⃣ 稍后配置 | 不做修改，告知：「好的，后续说『配置赛事上传』可随时开启」 |

第三步：获取 API Key 引导（仅选项1时执行）

📋 API Key 获取方式：
  1. 打开 https://mrkjai.com
  2. 登录/注册账号
  3. 进入「我的 → 个人集成（API Key）」页面
  4. 复制你的 Key（格式：opc_user_xxx...）
  5. 回到这里，把 Key 发给我

💡 Key 仅保存在本地 scripts/user_config.json，不会上传到任何地方。

运行时检查

每次执行上传操作前，必须检查 upload_enabled 字段：

upload_enabled: true + 有 Key → 正常上传
upload_enabled: false → 跳过上传，仅本地操作
upload_enabled: true + 无 Key → 提示用户设置 Key

触发方式

用户提供赛事链接 + 说"收录"/"加到OPC"/"推到OPC" → 提取+提交到 OPC
用户主动问"有什么赛事" → 展示本地追踪记录
用户主动问"有什么赛事"/"OPC有什么比赛"/"查一下赛事池" → 查询 OPC 赛事池
用户说"查一下AI比赛"/"看看黑客松" → 按条件查询

流程C：查询 OPC 赛事池

用户说「有什么赛事」/「OPC有什么比赛」/「查一下赛事池」
调用 GET /api/events/list 查询 OPC 赛事池
格式化返回结果展示给用户（表格形式）
支持按 type/region/status/keyword/contributor 过滤
支持分页（limit/offset）和排序（sort）

查询示例：

"有什么赛事" → 查全部（默认20条，按发布时间倒序）
"有什么黑客松" → type=hackathon
"上海有什么AI比赛" → region=shanghai + keyword=AI
"报名截止的赛事" → status=open

流程D：定时追踪

用户说"新增信息源" → 追加到 sources.json
用户说"关闭赛事上传"/"关闭上传" → 关闭上传（设置 upload_enabled=false）
用户说"开启赛事上传"/"配置赛事上传" → 开启上传（引导设置 Key）

核心流程

流程A：用户提供链接 → 收录到 OPC

用 WebFetch 抓取链接内容
从页面中提取结构化字段（见下方字段映射表）
展示确认清单，等用户确认
调用 OPC API 提交
同时写入本地 events_history.json

流程B：定时追踪 → 自动抓取+提交

读取 scripts/sources.json，获取所有已启用的信息源
逐个信息源抓取页面内容
调用对应解析器提取结构化字段
与 scripts/events_history.json 比对
新赛事 → 调用 OPC API 提交（使用用户的 API Key）
更新本地历史 JSON + Markdown 记录
输出摘要

OPC API 接口规范

提交接口：POST /api/events/ingest

| 项目 | 值 | |------|-----| | 方法 | POST | | 路径 | /api/events/ingest | | 域名 | 从 user_config.json 读取 api_base，默认 https://mrkjai.com | | Content-Type | application/json; charset=utf-8 | | 鉴权 | Header X-API-Key: {api_key} |

必填字段

| 字段 | 类型 | 限制 | 说明 | |------|------|------|------| | title | string | 1-120 字符 | 赛事名称 | | summary | string | 1-300 字符 | 一句话描述 | | type | enum | 见下方 | 赛事类型 | | region | enum | 见下方 | 地区 | | organizer | string | 1-100 字符 | 主办方 | | publishedAt | string | ISO 8601 | 赛事发布/开始时间 | | deadlineAt | string | ISO 8601 | 报名截止时间，必须晚于 publishedAt | | externalUrl | string | 合法 URL | 赛事详情页 URL，去重键 |

选填字段

| 字段 | 类型 | 限制 | |------|------|------| | tags | string[] | 最多 8 个 |

枚举值

type：startup(创业大赛) / hackathon(黑客松) / design(设计比赛) / academic(学术竞赛) / summit(行业峰会)

region：online(线上) / beijing / shanghai / hangzhou / shenzhen / national(全国) / overseas(海外)

返回码

| code | 含义 | |------|------| | created | 成功收录 | | exists | externalUrl 已存在（幂等） | | unauthenticated | 缺 X-API-Key | | invalid_key | Key 无效 | | key_revoked | Key 已撤销 | | validation_error | 字段校验失败 | | internal_error | 服务器异常 |

查询接口：GET /api/events/list

| 项目 | 值 | |------|-----| | 方法 | GET | | 路径 | /api/events/list | | 鉴权 | Header X-API-Key: {api_key}（同 ingest，同一个 key） |

Query 参数（全部可选）：

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | type | enum | — | startup / hackathon / design / academic / summit | | region | enum | — | online / beijing / shanghai / hangzhou / shenzhen / national / overseas | | status | enum | — | fresh(7天内新发布) / open(报名中) / closing(3天内截止) / ended(已截止) | | keyword | string | — | 模糊搜索 title/summary/organizer | | contributor | string | — | 贡献者账号名（精确匹配） | | limit | int 1-100 | 20 | 每页条数 | | offset | int ≥0 | 0 | 跳过条数 | | sort | enum | published_desc | published_desc / deadline_asc / deadline_desc / created_desc |

响应格式：

{
  "ok": true,
  "data": {
    "items": [{ "id", "title", "summary", "type", "region", "organizer",
                "publishedAt", "deadlineAt", "externalUrl", "tags",
                "contributor", "createdAt", "updatedAt" }],
    "total": 38,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

错误码：同 ingest（unauthenticated / invalid_key / key_revoked / validation_error / internal_error）

字段提取规则

从页面内容推断字段

| 抓取内容 | API 字段 | 推断规则 | |----------|---------|---------| | 页面 h1 / title | title | 去站点后缀、清理空白 | | meta description / 首个 p | summary | 截断到 300 字符 | | 主办方/承办方文本 | organizer | 截断到 100 字符 | | 比赛开始时间 | publishedAt | 转 ISO 8601；找不到用当前时间 | | 报名截止时间 | deadlineAt | 转 ISO 8601；找不到传 publishedAt + 30 天 | | 详情页 URL | externalUrl | 原样传，用于去重 | | 关键词/分类 | tags | 取前 8 个 |

type 推断

含"黑客松/hackathon/编程马拉松" → hackathon
含"创业/路演/business plan/startup" → startup
含"设计/UI/UX/品牌/visual" → design
含"数学/建模/学术/ACM/科研" → academic
含"峰会/summit/conference/大会" → summit
都匹配不到 → hackathon（默认）

region 推断

含"线上/online/远程" → online
含"北京" → beijing
含"上海" → shanghai
含"杭州" → hangzhou
含"深圳" → shenzhen
含"全国/中国" → national
含"海外/国外/overseas" → overseas
都没匹配 → online（默认）

重要规则

deadlineAt 抓不到时传 publishedAt + 30 天，summary 里注明"长期有效"
title 或 organizer 抓不到 → 直接告诉用户缺失，不瞎猜
同一 externalUrl 重复提交是幂等的（接口返回 exists）
publishedAt 不要设为未来时间

执行命令

# 追踪模式（默认）：抓取信息源 + 提交到 OPC
python3 track_events.py

# 查询模式：查 OPC 赛事池已有数据
python3 track_events.py query

# 查询 + 过滤：只看黑客松
python3 track_events.py query --type hackathon

# 查询 + 过滤 + 分页：上海地区，AI关键词，5条
python3 track_events.py query --region shanghai --keyword AI --limit 5

# 查询 + 排序：按报名截止时间升序
python3 track_events.py query --sort deadline_asc

信息源管理

配置文件：scripts/sources.json

用户新增信息源时，追加到 sources 数组：

{
  "id": "唯一标识",
  "name": "显示名称",
  "url": "抓取地址",
  "type": "forum_post | official_page | rss | api | campaign_page",
  "category": "OPC赛事 | AI赛事 | 创业大赛 | 独立开发者",
  "organizer": "主办方",
  "enabled": true,
  "notes": "备注"
}

新增信息源后，在 scripts/track_events.py 的 PARSERS 字典注册对应解析函数。

已配置信息源

| ID | 名称 | URL | 类型 | 状态 | |----|------|-----|------|------| | trae_forum | TRAE AI 创造力大赛 | https://forum.trae.cn/t/topic/28826 | forum_post | ✅ | | workbuddy_super_individual | WorkBuddy 超级个体大赛 | https://www.codebuddy.cn/events/super-individual | campaign_page | ✅ |

数据存储

| 文件 | 安装后路径 | 用途 | |------|---------|------| | user_config.json | scripts/user_config.json | 用户 API Key + 上传开关配置（勿提交到公开仓库） | | sources.json | scripts/sources.json | 信息源配置 | | events_history.json | scripts/events_history.json | 历史赛事记录（自动生成） | | 赛事记录.md | scripts/data/赛事记录.md | 人类可读记录（自动生成） |

数据透明度声明

本技能遵循最小权限和透明原则：

| 行为 | 是否上传 | 目标服务器 | 用户控制 | |------|---------|----------|---------| | 本地追踪（抓取赛事信息） | ❌ 仅本地 | — | 始终生效 | | 赛事提交到 OPC 赛事池 | ✅ 可选 | https://mrkjai.com | upload_enabled 字段控制 | | 查询 OPC 赛事池 | ✅ 发起 GET 请求 | https://mrkjai.com | 需要 API Key |

user_config.json 完整结构：

{
  "api_key": "opc_user_xxx...",
  "api_base": "https://mrkjai.com",
  "upload_enabled": true,
  "configured_at": "2026-06-22T17:00:00+08:00"
}

upload_enabled: true → 新发现的赛事自动提交到 OPC 公共池
upload_enabled: false → 所有功能仅在本地运行，不发送任何赛事数据
可随时说「关闭赛事上传」或「开启赛事上传」切换

sources-mgmt.md — 信息源添加规范
api-spec.md — OPC API 完整对接文档（可复制给其他 AI）

开源发布注意事项

⚠️ 安全提醒

scripts/user_config.json 包含用户 API Key，切勿提交到公开仓库
建议在 .gitignore 中添加：scripts/user_config.json 和 scripts/data/
scripts/events_history.json 和 scripts/last_run_summary.json 是运行时产物，也不应提交

开源适配清单

| 检查项 | 状态 | |--------|------| | 无硬编码绝对路径 | ✅ DATA_DIR 改为相对路径 | | 无真实 API Key | ✅ user_config.json 已清空 | | Python 路径通用化 | ✅ 执行命令改为 python3 | | 勿提交运行时产物 | ✅ .gitignore 已建议 |

📝 版本迭代记录

| 版本 | 日期 | 更新内容摘要 | 操作人 | |------|------|------------|--------| | v1.0 | 2026-06-22 | 创建技能（WebSearch 方案） | Kyle | | v1.1 | 2026-06-22 | 升级脚本化抓取 + JSON历史比对 | Kyle | | v2.0 | 2026-06-22 | 重大升级：集成 OPC API 提交 + 安装引导获取 Key + 用户链路 | Kyle | | v2.1 | 2026-06-22 | 开源适配：清空真实 Key、路径通用化、添加 .gitignore 建议 | Kyle | | v2.2 | 2026-06-22 | 新增赛事查询功能：GET /api/events/list + query 模式 + 表格格式化 | Kyle | | v2.3 | 2026-06-22 | 安全修复：清空泄露 Key + 新增 upload_enabled 开关 + 首次安装数据透明度告知 | Kyle |