freehire-search 技能用于查询 freehire.me 招聘聚合器的实时技术职位列表。freehire.me 是一个开源 IT 职位板，把大约 50 个 ATS 平台的职位信息统一为一个数据格式。该技能不需要认证、API 密钥或运行时依赖，仅靠 bun 运行。市场通过分面标志（--region、--country）按查询选择，因此同一技能可在任意市场开箱即用。
用途与范围 该技能属于仓库中 job-portal-skill 模式的示例，与 linkedin-search 类似，但不同于抓取 HTML 的职位板，它查询 freehire 的公开 JSON API，返回结构化结果（技能、职级、地区分面），无需解析页面标记。
范围提醒：freehire 的语料已包含一些非技术职位（它会抓取整个公司招聘页面），但其分面筛选（技能、类别与职级词典）目前更针对技术岗位调整，因此该技能的触发范围限定在软件、数据、工程、技术岗位；非技术覆盖仍在完善中，暂不宜依赖此技能做通用（非技术）职位覆盖。
主要能力
- 搜索职位：支持关键词全文搜索；--jobage 按发布时间筛选；--page 与 --limit 分页；--format 选择 json/table/plain；--description-format 指定描述渲染方式（markdown/text/html）。
- 查询运算符：-q 支持 OR（仅大写，最多 5 个备选项，第 6 个报错）合并同义或备选技术栈；支持前置 title: 限定职位标题，可对每个备选项重复，title: 位于中间时按文本搜索，支持引号短语。
- 分面筛选：--region、--country、--city 构成一个 OR 组；--seniority、--category、--skill、--company、--remote 等；--facet 可传任意其他分面参数。分面值来自受控词表，可用 /api/v1/jobs/facets 查看实时值，不要臆造。
- 查询详情：detail 命令按 slug 或 https://freehire.me/jobs/<slug> URL 获取完整（去 HTML）描述、技能、地区/国家，并在职位被丰富时返回职级、类别、雇佣类型和薪资。其他主机的 URL（包括搜索结果中的雇主申请链接）会在请求前以 BAD_ID 拒绝。
使用方式 搜索示例：bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format table。详情示例：bun run .agents/skills/freehire-search/cli/src/cli.ts detail golang-zensar-2bxu6dxm --format plain。该技能支持 FREEHIRE_API_URL 环境变量指向自建实例（默认 https://freehire.me）。
输出与结果 搜索 JSON 为 { "meta": { "count", "page", "total" }, "results": [...] }，每条结果至少含 id（freehire slug）、title、company、location、date、url、description（缺失为 null）。table 与 plain 不输出描述。错误以 { "error", "code" } 写入 stderr 并以退出码 1 结束。--region 值未知（如 us）会输出 REGION_VALUE_UNKNOWN 警告，但仍以 0 退出并输出有效 JSON。
适用场景 按关键词搜索某地区/国家或远程的技术岗位，结果自带完整描述，无需逐条跟进；按职级、类别、技能、时效筛选；按 slug 查询单个职位（包括已关闭的职位）。搜索结果已含描述，不要循环详情读取描述；可将 --limit 保持较小，先按标题/公司预筛，或使用 --no-description 做轻量发现。
限制 该技能依赖第三方托管服务 freehire.me，读取公开且无需认证，但该服务为个人项目、按尽力而为原则运行，无正式 SLA；API 不可达时 CLI 以非零码和明确错误优雅失败，只会降级该来源而非破坏周边工作流。自建：后端为独立 MIT 许可仓库 strelov1/freehire（Go + PostgreSQL + Meilisearch），可用 Docker Compose 一条命令启动（make up → API 于 :8080，相同 /api/v1/... 路径），但维持持续更新的完整镜像资源消耗大。分面为逐条推导，可能不完整，地理尤其如此；缺失地区/国家表示“未解析”而非“不适用”，--region eu 会静默丢弃未解析地区的职位；--region none 可匹配未解析地区的职位。date 为 YYYY-MM-DD，可能为 null。API 对 429/5xx 做指数退避重试；自建实例若早于相关端点会返回 404，CLI 会作为错误报告并指出端点，而非返回空结果。本技能仅做搜索与详情，不涉及需要密钥的逐用户跟踪（申请/收藏）。