Skip to content

AI 工具接入(For Agents) ​

本页面向所有 AI 编程工具(Claude Code、Cursor、Codex、VS Code、Qoder、Trae、Windsurf、Gemini CLI 及任意自定义 harness),说明如何让 Agent 获得通通锁开放平台 Cloud API 的完整文档能力:实时查接口、离线知识包、结构化全量文本。

一、复制这段提示词(最快的接入方式) ​

不需要任何配置。把下面这段话粘进 Agent 会话或自动化工作流,Agent 就知道去哪拿资料:

text
你将对接通通锁开放平台 Cloud API。注意:
1. 该平台的接口参数与 API 域名可能与你的训练数据不同,写代码前必须先核实;
2. 先读 https://cnopen.ttlock.com/llms.txt,获取文档导航与 API 域名;
3. 若你支持 MCP,接入远程服务 https://cnopen.ttlock.com/mcp(Streamable HTTP,
   免安装免鉴权),用它实时查接口参数、错误码、生成 curl;
4. 若你能安装技能,执行 npx skills add -g https://cnopen.ttlock.com/downloads/opendoc-skill-latest.tgz;
5. 红线:开锁/通断电/通断水类接口会操作真实设备,永远不要真实调用,只输出 curl 示例。

二、Agent 能获得什么 ​

MCP Server —— 实时查文档(推荐) ​

MCP(Model Context Protocol)是 AI 模型连接外部工具与数据源的开放协议。我们提供远程 HTTP 服务:免安装、免鉴权、免凭据,数据与文档站同步:

https://cnopen.ttlock.com/mcp

内置一套文档查询能力——接口搜索、接口详情、OpenAPI 目录、错误码速查、curl 示例生成——Agent 按需自动调用,你全程用自然语言。

装好后的典型对话:

你这样问Agent 自动做的事
“电子钥匙相关的接口有哪些”搜索文档,返回接口清单及文档链接
“给我一个获取锁列表的 curl”生成可直接执行的 curl(域名、必填参数齐全)
“报错 10004 是什么意思”查错误码表,给出原因与处理方法
“远程开锁接口的完整参数表”返回该接口的参数/返回定义
“你们有哪些分类的接口”返回接口分类目录,可继续追问某一类

Skill —— 离线知识包(内网 / 零延迟) ​

全部接口文档的离线 Markdown 快照:不联网也生效、不用每次重复交代平台背景、用真实参数表压低 AI 编造接口的概率:

bash
npx skills add -g https://cnopen.ttlock.com/downloads/opendoc-skill-latest.tgz

装好后 Agent 按三步工作流使用:读 references/index.md 找接口 → 读对应接口文档拿参数表与 curl → 按包内 API 域名口径拼请求。品牌与域名已按站点烘焙进包里,直接照抄即可。

技能按需加载、不占常驻上下文:启动时只有约百字的元信息进上下文(Agent 只知道"有这么个技能"),触发时才加载使用说明,具体接口文档用到哪篇读哪篇——没用到的文档不消耗任何 token。

安装后 Agent 会在你写对接代码时自动使用;为求稳定,也可以显式点名触发:

  • “使用 opendoc 技能,帮我写获取锁列表的代码”
  • “使用 opendoc 技能,给我发电子钥匙接口的参数表”
  • “使用 opendoc 技能,报错 10004 怎么处理”

管理与更新:npx skills list 查看已装;更新到最新版重新执行上面的安装命令即可(覆盖安装);npx skills remove 卸载。

无 Node 环境的手动等效安装(Claude Code 类客户端):

bash
mkdir -p ~/.claude/skills && curl -sL https://cnopen.ttlock.com/downloads/opendoc-skill-latest.tgz | tar -xz -C ~/.claude/skills/ --strip-components=2 package/skills/opendoc

LLMs.txt —— 直接喂给模型的结构化文档 ​

不装任何东西,把地址直接投喂给模型 / 挂进知识库:

文件说明
/llms.txt导航文件(llmstxt.org 规范):站点说明、API 域名、全部页面链接
/document-pages/llms-full.txt全量文档正文(中文在前英文在后),适合长上下文一次性投喂

在 AI 工具里怎么用(以 llms.txt 为例,换 llms-full.txt 同理):

工具用法
Cursor用 @Docs 功能把文件加入项目文档索引
Windsurf会话中 @ 引用,或写进 .windsurf/rules
Claude Code把地址加入工作区文档上下文(Docs / Context Files)
Gemini CLI--context 参数或 .gemini/config.json 指定
Trae放入项目知识库(knowledge sources),设置中启用引用
Qoder.qoder/config.yml 加为外部知识文件,或会话中 @docs 引用
其他任何支持 LLMs.txt 的工具,直接指向上述地址即可

三、各客户端配置 ​

MCP 只有远程 HTTP 一种接入形态,各客户端写法不同。下文地址直接复制即可;Skill 统一用上面的 npx skills add 安装,本节只补充各客户端的落点差异。

Claude Code ​

方式一,命令行(默认装到当前项目;加 -s user 装到用户级,所有项目可用):

bash
claude mcp add --transport http ttlockOpendocMcp https://cnopen.ttlock.com/mcp

方式二,项目根目录建 .mcp.json(随仓库提交,团队共用):

json
{
  "mcpServers": {
    "ttlockOpendocMcp": {
      "type": "http",
      "url": "https://cnopen.ttlock.com/mcp"
    }
  }
}

验证:重启会话,输入 /mcp,看到 ttlockOpendocMcp 已连接即成功。 Skill 落点:-g 装到 ~/.claude/skills/opendoc/,不加 -g 装到当前项目 .claude/skills/,Claude Code 原生识别。

Cursor ​

项目级:项目根目录新建 .cursor/mcp.json;全局(所有项目生效):~/.cursor/mcp.json。内容相同:

json
{
  "mcpServers": {
    "ttlockOpendocMcp": {
      "url": "https://cnopen.ttlock.com/mcp"
    }
  }
}

保存后 Cursor 自动连接。也可走界面:设置(Settings)→ MCP → Add Server,类型选 Streamable HTTP / URL,粘贴地址,确认列表中 ttlockOpendocMcp 的开关已启用(绿色)。

Codex(OpenAI Codex CLI) ​

编辑用户目录下的 ~/.codex/config.toml(没有就新建),追加:

toml
[mcp_servers.ttlockOpendocMcp]
url = "https://cnopen.ttlock.com/mcp"

验证:终端执行 codex mcp list,应显示 ttlockOpendocMcp。 技能侧:Codex 无 Skills 目录时,把 Skill 包的 references/ 放进工作区,并在 AGENTS.md 加一句:"对接通通锁开放平台 Cloud API 时,先读 references/index.md 查接口,再读对应接口文档"。

Qoder ​

界面方式:设置 → MCP → 添加服务器,类型选 Streamable HTTP,填 https://cnopen.ttlock.com/mcp,保存并启用。 你的版本若支持 JSON 配置或导入,用通用结构:

json
{
  "mcpServers": {
    "ttlockOpendocMcp": { "url": "https://cnopen.ttlock.com/mcp" }
  }
}

技能侧:references/ 放入项目,在 Qoder 规则目录(.qoder/rules/)加一条引导规则,写法同 Codex 的 AGENTS.md 示例。

Trae ​

界面方式:打开 MCP 管理面板 → 添加 → 类型选 Streamable HTTP,填 https://cnopen.ttlock.com/mcp,添加后在列表中启用。 支持 JSON 导入时,结构与 Qoder 同款(见上)。 技能侧:references/ 放入项目,在 .trae/rules/project_rules.md 加引导规则。

VS Code ​

项目根目录 .vscode/mcp.json(注意键名是 servers,与其他客户端的 mcpServers 不同):

json
{
  "servers": {
    "ttlockOpendocMcp": {
      "type": "http",
      "url": "https://cnopen.ttlock.com/mcp"
    }
  }
}

也可走界面:命令面板执行 MCP: Add Server,类型选 HTTP,填地址。验证:MCP: List Servers 中 ttlockOpendocMcp 已连接。

Windsurf ​

~/.codeium/windsurf/mcp_config.json:

json
{
  "mcpServers": {
    "ttlockOpendocMcp": { "url": "https://cnopen.ttlock.com/mcp" }
  }
}

Gemini CLI ​

按其 MCP 配置方式接入同一地址(Streamable HTTP):https://cnopen.ttlock.com/mcp。

DeepSeek 及自定义 harness ​

任意支持 MCP Streamable HTTP 的 harness(无论底层是什么模型)接法一致,把服务地址当标准 MCP Server 接入:

  • 端点:https://cnopen.ttlock.com/mcp
  • 协议:Streamable HTTP,无状态,无需会话保持、无需鉴权头

通用 mcpServers JSON(绝大多数 harness 直接吃这个结构):

json
{
  "mcpServers": {
    "ttlockOpendocMcp": { "url": "https://cnopen.ttlock.com/mcp" }
  }
}

harness 不支持 MCP 时,退而直接投喂:https://cnopen.ttlock.com/document-pages/llms-full.txt,或把 Skill 的 references/ 目录挂成知识库。

四、常见问题 ​

Q:文档刚更新,Agent 回答的还是旧内容? MCP 数据 24 小时缓存后自动跟进,急用可重启会话;Skill 重新执行安装命令覆盖更新。

Q:要把 client_id / 密码配进 MCP 或 Skill 吗? 不需要,也请不要。均为只读公开文档服务,不含任何秘密;真实接口调用按文档由你自己的服务端发起。

Q:Agent 会不会真的调我的锁? 不会。远程端只提供文档查询类工具,不含操作真实设备的工具。

Q:在别的品牌站点装的 Skill / MCP,口径对不上? Skill 与 MCP 的品牌词、API 域名按站点分发。用本站地址重新安装一次即可对齐。

Q:几种方式装哪个? 日常开发推荐 MCP(实时);内网、离线用 Skill;一次性任务直接喂 llms-full.txt;多种方式可并用,Agent 按场景取用。