道一云七巧套件

概述

使用 scripts/qiqiao_api.py 访问七巧集成中心。脚本只依赖 Python 3 标准库，服务地址已内置。该 Skill 的主要职责是让外部 Agent 选择并执行七巧内部能力，不在本地重复实现七巧内部技能的业务流程。

能力边界：九个命令只覆盖能力发现、只读元数据与业务数据查询、健康检查和文件上传。新增、修改、删除、审批等业务操作的唯一通道是七巧内部技能——内部业务 API 的名称只能来自技能暴露的索引，因此查不到专属技能时应改用更通用的技能继续执行，而不是用命令直接操作业务数据。

前置条件

服务地址固定为 https://qiqiao.do1.com.cn/plus/cgi-bin，无需向用户询问。

脚本默认从用户目录的 ~/.qiqiao/Authorization.md 读取密钥。该文件固定使用以下结构：

# 个人密钥

<!-- 未配置 -->

# 管理员密钥

<!-- 未配置 -->

# 企业ID(corpAB)

<!-- 未配置 -->

个人密钥用于运行平台。管理员密钥（七巧文档中的子管理员密钥／OpenAPI 密钥）用于开发平台。当前 Skill 不提供 userId 参数，不用管理员密钥切换到指定用户身份。根据目标平台向所有命令传 --credential personal 或 --credential admin，不在鉴权失败后静默切换密钥类型。

文件不存在或所需标题下没有密钥时，先向用户索取对应密钥，再创建或更新该文件。保留另一种已配置密钥，只把密钥写在对应一级标题下。用户没有密钥时，按以下入口指引获取：

• 个人密钥、企业ID：登录 https://qy.do1.com.cn/qiqiao2/runtime/，在“头像 → 个人密钥”获取，可刷新重置。
• 管理员密钥：使用管理员账号登录 https://qy.do1.com.cn/qiqiao2/console/，在“低码中心 → OpenAPI”获取。企业ID在“头像-企业ID”获取。

脚本负责读取密钥正文；不要为了检查配置而把已有密钥加载进模型上下文。

路由

每次任务首次访问七巧前，先按前置条件确定本次平台对应的密钥类型，并用该密钥类型运行一次 ability_health；同一任务内连续调用不重复检查，连接或鉴权异常后再检查。随后按以下三层选择目标技能。

直达：用户已指定技能或专家团

满足以下条件时走直达路径：

• 上层垂直 Skill、用户上下文或既有流程已经给出唯一的七巧内部技能或专家团 invokeName；
• 已有的应用、页面、用户等上下文足以启动该能力，或者缺失信息可由其自行获取。

直接通过 tool_call 调用七巧内部的 read 工具读取目标（技能传 type=skill，专家团传 type=expert_group），然后按返回的提示词执行。不要先调用 skill_list、expert_group_list 或 tool_list。

用户口头指定时，常说中文显示名而非调用名称：先用 skill_list --keyword 或 expert_group_list --keyword 核实该能力存在并解析出唯一 invokeName 再读取；多个候选让用户选择；确认查无此能力时转入“发现”。已知应用或页面但目标能力仍不明确，同样不属于直达路径。

发现：目标能力未知

用户只描述业务目标、尚未指定技能或专家团时，技能和专家团一起检索：

1. 根据用户目标和适用平台，同时用 skill_list 和 expert_group_list 传 keyword 查询平台级与官方级能力。
2. 关键词未命中，或命中的能力与用户业务明显不符时，两个列表都改用分页查询浏览全部元数据：以返回的 totalCount 为准逐页取完（size 最大 100），逐条按描述对业务场景的覆盖判定。
3. 任务明显属于某个应用但 applicationId 未知时，用 metadata_list --type APPLICATION 定位应用。
4. 取得 applicationId 后，按需查询该应用的应用级技能与专家团，判定方式与上文相同。
5. 根据显示名称、描述、调用名称、适用平台和级别选择最匹配的能力；多候选会改变行为时让用户选择。
6. 取得唯一 invokeName 后，通过 tool_call 调用七巧内部 read 转入执行：技能传 type=skill，按 skillPrompt 执行；专家团传 type=expert_group，按返回的系统提示词和关联技能清单决定读取哪个技能。

关键词已足以唯一定位时立即停止，不做分页浏览；分页浏览只在关键词未命中或结果不符时进行，选出目标即停。

兜底：没有直接匹配的能力

发现结果中没有直接对应用户业务的能力时，这不是任务的终点，也不能改用命令直接操作业务数据：

1. 运行平台任务使用兜底技能 runtime_scenario_official（官方运行端操作场景，覆盖运行端查询、填单、流程、导出、待办办理等操作）：通过 read 读取后，按其 skillPrompt 的指引进一步查找各种元数据，应用、页面、组件、记录的定位链路由技能提示词自带，跟随技能的步骤执行。
2. metadata_list、metadata_get、business_data 等本地命令在技能流程需要补充上下文，或用户直接要求原始元数据与业务数据时使用，定位结果作为技能执行的输入。
3. 开发平台任务没有兜底技能：没有找到符合的专家团或技能时，如实向用户汇报，不用命令直接操作业务数据。

所有业务操作都发生在某个七巧内部技能或专家团之内。

调用失败后重新选择

已选技能或专家团调用失败时，先按错误判断原因：参数、权限、状态类错误按提示修正后在同一能力内重试；错误表明能力与业务不匹配（如提示不支持该操作或场景不符）时，重新进入发现，并直接采用分页浏览按描述判定，从候选中排除已失败的能力。排除后没有新候选时，运行平台任务转入兜底技能，开发平台任务如实向用户汇报。

九个命令

python scripts/qiqiao_api.py --help
python scripts/qiqiao_api.py <command> --help

按职责分组：

用户明确要求查询原始元数据、页面组件业务数据、上传本地文件或检查连接状态时，可直接使用对应命令；形成具体命令前阅读 [API 参考](references/api-reference.md)，只加载当前任务涉及的命令章节。

tool_call：进入技能和业务操作的唯一通道

tool_call 把内部工具名和参数交给七巧路由执行，读取技能、调用业务 API 都经过它。它是七巧唯一的写操作通道，新增、修改、删除、审批等业务操作必须在通过七巧内部技能/专家团执行；不能通过openAPI命令直接操作业务数据。

python scripts/qiqiao_api.py tool_call 
  --tool-name read 
  --arguments '{"type":"skill","invokeName":"目标技能调用名称"}'

toolName 使用目标工具的精确名称，arguments 是符合该工具 inputSchema 的 JSON 字符串（不是 JSON 对象）。四个内部工具的名称稳定，可直接使用：

• read：读取专家团、技能或资源的内容及其关联索引；
• service_fetch：执行技能暴露的内部业务 API，api 名称只能取自技能返回的 [available_tools] 或已读取的资源，不得猜造；
• fetch_lowcode_agent：调用技能关联的 Dify/Coze 等低代码智能体并等待真实回复；
• http_call：调用七巧平台之外的外部 HTTP 接口。

目标工具名称或 inputSchema 未知，或已知契约调用失败且错误表明名称或参数结构可能变化时，先用 tool_list 查询；read、service_fetch 等稳定工具的名称和参数已由当前 Skill 或读取到的七巧内部技能明确提供时，直接执行。

Python 函数、七巧内部工具名、API 名和参数名继续使用其真实名称，例如 cmd_skill_list、service_fetch 和 applicationId，不要为了外部命名风格改写七巧内部契约。

执行七巧内部技能

读取并执行七巧内部技能、提示词资源或智能体资源时，阅读 [七巧内部技能执行](references/internal-skill-execution.md)。该文档说明 read、service_fetch、fetch_lowcode_agent 及 tool_call 的嵌套参数。

结果与边界

• 应用、页面、组件、记录、技能、专家团和资源标识必须来自用户提供的可信上下文或真实查询结果，不得猜造。
• 查询可以直接执行。新增、修改、删除、审批等写操作遵循七巧内部技能或资源规定的确认方式，不得通过直接调用绕过。
• business_data 以用户身份执行数据鉴权，只能使用个人密钥；服务端要求管理员密钥必须传入 userId，而本 Skill 不提供该参数。
• 只在目标工具返回真实成功结果后声明完成；部分成功、等待用户、权限不足或结果不可核验时保留实际状态。
• 瞬态错误只做有限重试；重复失败后依据响应区分密钥、授权、身份、参数、对象不存在或服务端问题。
• 返回 Token 无效时，先确认本次平台对应的 --credential；让用户重新获取对应密钥并更新 Authorization.md 相应标题后重试。不要读取或回显现有密钥来帮助排查。
• 不在回复、日志、Skill 文件或版本库中回显 Bearer 密钥。