MoArk WebSearch Kit — 模力方舟联网搜索一键接入

非官方社区工具包：让 模力方舟 MoArk（Gitee AI）用户在 1 分钟内接入平台自带的联网搜索 API POST /v1/web-search，并可直接把 SKILL.md 放进支持 Agent Skills 的 AI 助手里，让 Agent 学会"联网查证再回答"。

---

一分钟跑通

第 0 步：拿到并填写令牌（还没有的话）：

1. 登录 moark.com 工作台 → 设置 → 访问令牌 → 创建（文档：https://api.moark.com/docs/organization/access-token）
2. 填写令牌，三选一：

   # a) 当前终端临时用
   export MOARK_API_KEY=粘贴你的令牌
   # b) 长期使用：追加到 ~/.zshrc 或 ~/.bashrc 后 source 生效
   echo 'export MOARK_API_KEY=粘贴你的令牌' >> ~/.zshrc && source ~/.zshrc
   # c) 项目方式：复制 examples/.env.example 为 .env 填入（确认 .env 在 .gitignore 里）

3. 验证令牌（200=有效，401=令牌有误）：

   curl -sS -m 15 https://api.moark.com/v1/models -H "Authorization: Bearer ${MOARK_API_KEY}" -o /dev/null -w '%{http_code}\n'

第 1 步：跑通搜索：

curl -sS -X POST https://api.moark.com/v1/web-search \
  -H "Authorization: Bearer ${MOARK_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"query":"模力方舟 MoArk 是什么","summary":true,"count":5}'

返回结构（博查兼容格式）：

{
  "code": 200,
  "data": {
    "webPages": {
      "totalEstimatedMatches": 1618000,
      "value": [
        {
          "name": "网页标题",
          "url": "https://…",
          "snippet": "网页内容简短描述",
          "summary": "正文摘要（请求体 summary=true 时返回）",
          "siteName": "来源站点",
          "datePublished": "发布时间"
        }
      ]
    }
  }
}

这里有三样东西

文件	用途
SKILL.md	Agent Skill：把目录放进支持 SKILL.md 的 AI 助手（如 Claude Code 的 skills 目录、DeepSeek Harness 的 agent preset skills/），Agent 即学会"需要联网事实时调用 moark web-search，并按 [S1][S2] 规范引用来源"
examples/curl.sh	终端一键验证
examples/python_websearch.py	Python 最小接入（仅依赖 requests）
examples/rag_pattern.py	RAG 组合模式：web-search 检索 → 组装带来源的上下文 → chat/completions 生成带 [Sn] 引用的回答（OpenAI SDK 兼容调用）

请求参数速查（POST /v1/web-search）

参数	类型	说明
query	string，必填	搜索关键字或语句
summary	boolean	是否返回正文摘要（强烈建议 true，检索质量显著更高）
count	integer	返回条数（1-8 条建议值，最大 50）
search_recency_filter	string	week / month / semiyear / year，按网页发布时间过滤
search_site_filter	string[]	限定站点搜索（最多 100 个站点）

完整参数与 Schema 以官方为准：GET https://api.moark.com/v1/yaml 返回全量 OpenAPI 定义；另有一族端点 /v1/web-search-v2、/v1/web-search/custom、/v1/web-search/global。

实测踩坑（帮你省下排查时间）

1. 路径是连字符：/v1/web-search 才对；/v1/web_search、/v1/search 全部 404。
2. 模型目录里的 search 模型不可调：GET /v1/models 虽列出它，但 chat/completions 与 /v1/responses 均报「暂不支持该接口」。联网搜索只有 REST 端点这一条路。
3. chat 的 tools 不支持服务端搜索：tools[].type 只接受 function / custom——想联网必须先自己调 web-search 再把结果拼进上下文（见 rag_pattern.py）。
4. 搜索计费独立于模型资源包：调用前建议在控制台确认配额；欠费返回 403 "You do not have enough money or package quota"。
5. 鉴权就是普通 Bearer Token：与 chat/completions 同一把访问令牌，无额外签名。

安全提示

• 令牌一律走环境变量（MOARK_API_KEY），不要把 key 硬编码进代码或提交到任何仓库。
• 本仓库所有示例均从环境变量读取密钥。

免责声明

本项目为社区维护，与模力方舟/Gitee 官方无关。API 行为以官方文档与 GET /v1/yaml 实时定义为准；若官方上线了更优雅的搜索接入方式（如服务端 web_search 工具），请优先采用官方方案。

License

MIT