FAQ / 排错

提交与审核

提交报「desc 超限」

简介按码点计 ≤ 20 字（中英文都算 1）；这是市场卡片等宽展示的硬约束，删到 20 字内再提交。

提交报 409（id 冲突）

id 对既有目录与待审队列全库查重。换一个 id；上架后 id 不可改（它是用户本地服务器配置 id）。

id 能用大写字母吗

网页提交表单按 ^[a-z0-9][a-z0-9-]*$ 校验（小写字母/数字/短横线，字母或数字开头）。服务端虽更宽，但按表单口径准备最稳，避免后续通道不兼容。

提交报「服务不可达」但我的服务明明开着

提交时服务端会从公网现场 POST 一次你的 URL（空 body，5 秒超时，返回 200/405 即通）。自查：① 是不是只有内网/本机能访问；② https 证书链是否完整（手机端校验更严）；③ 是否把健康检查实现成了只接受 GET（要接受 POST）；④ 响应是否 5 秒内返回。

带 token 提交直接被拒

设计如此：目录永不存 token。需要鉴权的服务，用户安装后在 app 里自填 token（每个请求带 Authorization: Bearer），目录里 server.token 留空。

限流 429

单 IP 每分钟 3 次提交、队列上限 100 条。自检通过后再提交，别用提交当调试。

网页提交和 app 内提交有什么区别

网页表单只支持 byo（自带服务器）包；declarative 剧本包走 app 内对话提交（AI 收集 + 复述确认 + confirm:true 才提交）。两条通道的审核标准一致。

安装与调用（用户侧现象 → 排查）

安装报 MARKET_SERVER_UNREACHABLE

app 对你的 URL 做健康检查（空 POST，200/405 即存活）没通过。配置会保留，修好后用户重试即可。重点查：公网 https 直连（请求从用户设备发出，不是我们转发）、证书链、防火墙、健康检查响应速度。

装上了但工具没出现 / 数量不对

真实工具清单以安装后 tools/list 发现为准（目录里的 toolPreview 只是展示）。另外两类工具会被静默剔除：命中保留黑名单的（sms.read / pay.query / identity.read / a2a.message / contact.read / call.log / location.read）与 level=write 的（只读先行，write 不挂出）。

我刚改了服务器的工具清单，用户怎么没变

重新「启用」一次（或重装）会重新发现并热挂载；日常更新服务不需要重新上架。

目录显示的还是旧信息

app 侧目录缓存 1 小时（market.refresh 距上次成功拉取 <1h 直接回缓存，force 可绕过）。

工具响应 5 秒 / 30 秒就断

app 侧连接超时 5s、读取超时 30s。长任务不要同步等：先立即返回任务受理结果，提供查询进度的第二个工具。

我的服务想返回 SSE 流

可以：响应为 data: {...} 行的 text/event-stream 也会被解析；纯 JSON 同样支持，二选一。

返回错误怎么给 AI

tools/call 返回 result.isError: true + 文本说明；错误文案走统一分类（16 类，见开发规范 · 四），不要自造格式。

能力与边界

能不能做写操作 / 支付 / 发消息类工具

当前版本只挂出只读工具（write 有独立授权闸，规划中）。涉及敏感数据的保留名能力（短信/支付/身份/通讯录/通话/位置）永远不对外部工具开放。

能把工具的 UI 挂进 app 吗

可以：目录条目 ui 填入口 URL，用户把工具钉到侧边栏后点击直接打开该页面；不填则点击回填聊天输入框。

你们帮我托管服务器吗

当前不托管（工具跑在你自己的服务器上）。托管在路线图远期；近期规划：声明式工具（零代码 HTTP 转发）、write 工具开放。

报错 → 自查 → 找谁

先按表自查；自查过不去的，按「找谁」这列走，别在原地重试。