GatherSurf 应用开发文档

这份文档里讲的每个接口，都能在示例工程「选品助手」里找到对应的可运行代码。 新建应用时选「📘 示例工程」就能得到它——那是一个完整能跑的应用，改改就能发布。
工程里还带一份 AGENTS.md，可以直接喂给 AI 让它按你的需求改（见交给 AI 开发）。

这是什么

你可以在 GatherSurf 客户端里开发自己的应用，它和我们自己上架的应用跑在完全同一条路上—— 没有「开发模式特权」，也没有「上架后才有的限制」。这条约束是有意的：否则会出现 「我本地好好的，上架就坏」，而那种问题最难查。

🔎 我想做…

这份文档是按接口组织的，但你脑子里想的多半是一件事。 先在这儿对一下，直接跳到该看的地方。

五分钟跑起来

两条路，选一条。都不需要装任何东西——客户端本身就是开发环境。

路 A：让 AI 写（不用会 JS）

1. 客户端左边 →「✨ AI 开发」→ 右上角「+ 新应用」
2. 填个中文名（比如「代理测速台」），标识只填后半截，前缀是自动加的
3. 用大白话说你要什么：
   「做一个代理测速台：列出我所有代理，点全部测速， 显示延迟和是否可用，能按延迟排序，坏的标红」
4. 它会先问你界面用哪套框架——点一下选就行（不确定就选推荐的那个）
5. 生成完点「▶ 预览运行」——直接跑起来看效果
6. 不满意就接着说：「表格加一列地区」「把测速改成并发 5 个」
7. 满意了点「📦 放进我的开发」，它就成了一个正式应用，可以发布

路 B：自己写

1. 「应用中心」→「🛠 我的开发」→「+ 新建应用」
2. 选「📘 示例工程」——那是一个完整能跑的应用，每个接口都有可点的按钮
3. 点「打开」跑一遍，看哪个接口是你要的
4. 「📂 打开开发目录」，用你惯用的编辑器改 main.js
5. 存盘，回到客户端——会自动重载，不用重启

main.js                                 // 后端
  exports.register = function (host) {
    host.ipc.handle('hello', async () => ({ ok: true, msg: '你好' }));
  };

ui/index.html                           // 界面（是片段，没有 html/body）
  <button id="ab-go">点我</button><div id="ab-out"></div>

ui/app.js                               // 界面逻辑（必须是 IIFE）
  (function () {
    document.getElementById('ab-go').onclick = async () => {
      const r = await gsApp.invoke('hello', {});
      document.getElementById('ab-out').textContent = r.msg;
    };
  })();

交给 AI 开发

示例工程里带了一份 AGENTS.md，是专门写给 AI 读的： 全部接口签名、硬约束、常见错误、怎么改怎么发布，都在里面。

三步

1. 新建应用时选「📘 示例工程」，得到一份能跑的完整代码
2. 点「📂 打开开发目录」，把整个目录（含 AGENTS.md）交给你的 AI
3. 直接说你要什么——「把 1688 换成淘宝」「加一个自动比价提醒」「导出改成 Excel」

可以直接复制的开场白

这是 GatherSurf 客户端的一个应用工程。
先读 AGENTS.md，它写明了全部接口、硬约束和常见错误。
读完后按我的需求改，注意：
  - 不要 require('electron') / require('fs')
  - CSS 每条选择器都要带工程里已有的前缀
  - ui/app.js 必须保持 IIFE
  - 改表结构只能在 ensureSchema() 里往后加版本，不能改已有的
我的需求是：______

目录结构

你的应用/
├─ manifest.json     你是谁、要什么权限、入口在哪
├─ main.js           后端逻辑（主进程）
├─ README.md         必须有，自查会检查
└─ ui/
   ├─ index.html     界面片段（不是完整文档）
   ├─ style.css      样式（每条选择器都要带前缀）
   └─ app.js         界面逻辑（必须是 IIFE）

manifest.json

{
  "key": "abc12-erp-sync",        // 你的应用标识，建好不能改
  "name": "ERP 同步",
  "icon": "🚀",                   // emoji 或包内图片路径
  "version": "1.0.0",             // 必须是 x.y.z
  "description": "一句话说明",
  "apiVersion": 1,
  "minClientVersion": "0.3.10",   // 低于这个版本的客户端不给装
  "permissions": ["storage", "db", "http"],
  "http": { "allow": ["api.mycompany.com"] },   // 选填；目标域名固定时建议如实写
  "entry": { "main": "main.js", "ui": "ui/index.html" }
}

权限一览

if (!host.db) return { ok: false, error: '没有 db 权限' };

接口速查表

这张表由平台代码直接生成，和 AI 开发助手拿到的是同一份。 表里没有的方法就是不存在的——写了会拿到 undefined，运行时报 is not a function。

后端接口 host.ipc

平台只调你的一个导出：

exports.register = function register(host) {
  const { ipc, storage, db, log } = host;

  ipc.handle('hello', async (payload) => {
    log('收到', payload);            // 写进客户端日志，调试用
    return { ok: true, msg: '你好' };  // 原样回到界面
  });
};

// 可选，但强烈建议实现
exports.deactivate = function () { /* 停掉你的定时器 */ };

界面 gsApp

const r = await gsApp.invoke('hello', { name: '张三' });
if (r.ok) console.log(r.msg);
else gsApp.toast(r.error, true);

进度事件

长任务不能等跑完才返回——用户会以为卡死了。

// 后端
ipc.send('progress', { i: 3, total: 10, msg: '第 3 步完成' });

// 界面
gsApp.on('progress', (p) => {
  bar.style.width = (p.i / p.total * 100) + '%';
});

文件存储 storage

全部是同步的，不要加 await。

storage.dir()                      // 你的数据目录绝对路径
storage.list()                     // 你存了哪些文件（文件名数组）
storage.read(name)                 // 文本，读不到回 null
storage.write(name, text)          // 原子写（先 .tmp 再 rename）
storage.readJson(name, 默认值)      // 读不到 / 坏了都回默认值
storage.writeJson(name, obj)
storage.remove(name)               // 删除，回 true / false

数据库 db 要付费档位

API

db.query(sql, params)      // 读，返回行数组（有行数上限）
db.exec(sql, params)       // 写，返回 { changes, lastId }
db.tx(fn)                  // 事务，fn 里抛错就整体回滚
db.migrate(list)           // 版本化建表/改表
db.path                    // 数据库文件路径

建表：用 migrate，不要用 CREATE TABLE 硬跑

db.migrate([
  { v: 1, name: '建客户表', up: [
      `CREATE TABLE IF NOT EXISTS customers(
         id     INTEGER PRIMARY KEY AUTOINCREMENT,
         name   TEXT    NOT NULL,
         amount INTEGER NOT NULL DEFAULT 0,   -- 金额用整数「分」
         created_at_ms INTEGER NOT NULL       -- 毫秒,直接存 Date.now()
       )`,
      `CREATE INDEX IF NOT EXISTS idx_customers_at ON customers(at)`,
  ]},
  { v: 2, name: '加备注', up: [`ALTER TABLE customers ADD COLUMN remark TEXT`] },
]);

增删改查

// 参数一律用 ? 占位，不要自己拼字符串。
// 拼字符串的问题不只是注入——名字里有个单引号你的 SQL 就崩了。
const r = db.exec('INSERT INTO customers(name,amount,at) VALUES(?,?,?)',
                  ['张三', 12800, Math.floor(Date.now()/1000)]);
// r.lastId 是自增 id

const rows = db.query('SELECT * FROM customers WHERE amount > ? ORDER BY id DESC LIMIT 50',
                      [10000]);   // ★ 一定要 LIMIT

db.exec('UPDATE customers SET amount=? WHERE id=?', [20000, r.lastId]);
db.exec('DELETE FROM customers WHERE id=?', [r.lastId]);

硬上限

统计：让 SQL 算

const byCity = db.query(`
  SELECT city, COUNT(*) AS n, SUM(amount) AS total
  FROM customers GROUP BY city ORDER BY total DESC LIMIT 20`);

事务

try {
  db.tx(() => {
    const a = db.query('SELECT amount FROM customers WHERE id=?', [from])[0];
    if (a.amount < amt) throw new Error('余额不够');   // 抛错 = 整体回滚
    db.exec('UPDATE customers SET amount=amount-? WHERE id=?', [amt, from]);
    db.exec('UPDATE customers SET amount=amount+? WHERE id=?', [amt, to]);
  });
} catch (e) {
  // 走到这里数据还是转账前的样子
}

什么时候必须用：多条写操作在业务上是一件事。典型是「扣一边、加一边」—— 中间崩了就出现钱凭空消失。示例应用里有个「故意失败（验回滚）」按钮，点一下就能眼见为实。

出网 http

manifest 里只要声明 "http" 权限就能用。域名白名单是选填的 （见下面「域名白名单是选填的」）：

"permissions": ["http"]

// 想告诉用户你会访问哪些地方，就再加这一行（选填）
"http": { "allow": ["api.mycompany.com", "192.168.1.10:8080"] }

三个入口，按你要什么选：

// ① 取 JSON —— 最常用
const r = await http.json('https://api.mycompany.com/orders');
r.data          // ← 解析好的对象在这里
r.status        // 200

// ② 要看状态码 / 响应头，或者对方不一定回 JSON
const r2 = await http.request('https://api.mycompany.com/ping');
r2.status  r2.ok  r2.headers  r2.text

// ③ 和标准 fetch 同签名，需要流式或特殊用法时用
const r3 = await http.fetch('https://api.mycompany.com/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data),
});
const text = await r3.text();

http.allowed()   // 白名单里有哪些域名，可以显示给用户看
http.mode()      // 当前的白名单执行模式

硬上限

★ 写在这儿是因为：撞上了才知道有这个数的话， 错误信息出现时人的第一反应是"我代码写错了"，而不是"我超了上限"。

域名白名单是选填的

窗口 profiles:read profiles:control profiles:write

// profiles:read —— 看
await profiles.list()      // [{ id, customNo, name, group, platform, lastOpenedAt, locked }]
                           //   lastOpenedAt = 秒级时间戳，从没开过是 null（JS 里要 ×1000 才能 new Date）
                           //   locked = true 表示超出套餐配额、这个号打不开（数据还在）
await profiles.get(id)
await profiles.running()   // id 的字符串数组：["p1","p2"]，不是对象数组

// profiles:control —— 操作已有的号
await profiles.open(id)
await profiles.close(id)

// profiles:write —— 改变账号里有什么
await profiles.create({ name, group, platform, proxyId, proxyLine, remark })
await profiles.update(id, { name, group, remark, proxyId })
await profiles.remove(id)                    // 不可逆
await profiles.proxies()                     // 代理库 —— 只要 :read（只是列出来）
await profiles.addProxy({ name, line })       // line = socks5://user:pass@ip:port
await profiles.checkProxy(id)             // → { ok, ip, country, ms, error }；测通不通 + 耗时
                                          //   ★ 只要 profiles:read（它不改任何东西）
await profiles.groups()                      // [{ id, name, count, builtin?, orphan? }] —— 只要 :read
                                          //   ★ 里面有两类不是真分组的行，见下

代理用「一行式」串，别自己拆

await profiles.addProxy({ name: '香港节点', line: 'socks5://user:[email protected]:1080' });

云端负责解析成 type/host/port/user/pass。你自己拆的话，拆法一变两边就不一致—— 而不一致的表现是「代理配了不生效」，查起来很费劲。

页面操作 automation 审核重点看

第一个参数都是窗口（profile）的 id。要先 profiles.open(id)。

await automation.newTab(id, url)          // → { id, url }；只允许 http/https
await automation.tabs(id)                 // → [{ id, url, title }]
await automation.closeTab(id, tabId)      // → { ok, closed } / { ok:false, why }；用完要关
await automation.evaluate(id, 'document.title')   // → 表达式的值本身（不写 return）
await automation.realClick(id, '#su')     // 直接传选择器
await automation.realType(id, '#kw', '文字')
await automation.realClick(id, x, y)      // 也支持坐标（少用，见下）
await automation.realKey(id, 'Enter')
await automation.screenshot(id, {})       // → { ok:true, base64:'…' }
await automation.dwell(id, { scrolls: 4 })        // → { dwelled, scrolls, wander }；拟人停顿

const tab = await automation.newTab(id, url);
await automation.evaluate(id, expr, { tabId: tab.id });
await automation.realType(id, '#kw', '文字', { tabId: tab.id });

// 先探一次，用探到的
const sel = await automation.evaluate(id, `(() => {
  for (const el of document.querySelectorAll('input,textarea')) {
    const b = el.getBoundingClientRect();
    if (b.width > 60 && b.height > 16 && el.id) return '#' + el.id;
  }
  return '';
})()`);
await automation.realType(id, sel, '指纹浏览器');

const r = await automation.runSteps(id, [
  { op: 'goto', url: 'https://example.com' },
  { op: 'waitForSelector', selector: 'h1' },
  { op: 'evaluate', code: 'return document.title' },
]);
if (!r.ok) return { ok: false, error: r.error };   // ← 失败不抛异常，必须自己判 .ok
r.results     // 每一步一个对象：[{ op, ok, value, error }, ...]
r.vars        // 流程里 saveTo 存下来的变量

{ op:'evaluate', code:'return document.querySelectorAll(".result").length' }

实操：开窗口 → 上 1688 → 搜商品 → 落库

前面几节讲单个接口怎么用，这一节是它们串起来长什么样——真实业务里你要写的就是这种流程。

七步

1. 选窗口——没指定就用第一个。真实应用里应该让用户选或按分组轮换， 闷头用第一个在多账号场景下会一直用同一个号
2. 确保它开着——已经开着就跳过，重复开会走一遍完整启动，白等好几秒
3. 直接拼搜索 URL 开标签页，不去首页点搜索框——能用 URL 表达的意图就别用点击表达， 少一步就少一个会坏的地方
4. 轮询等商品渲染出来（见下）
5. evaluate 在页面里抓数据
6. 截图存证
7. 一个事务批量写进数据库

let found = 0;
for (let i = 0; i < 20; i++) {
  found = await automation.evaluate(pid,
    `document.querySelectorAll('[class*="offer"]').length`);
  if (found > 0) break;
  await new Promise(r => setTimeout(r, 700));
}
if (!found) return { ok:false, error:'页面上没找到商品 —— 可能要登录、被风控、或者改版了' };

try {
  tabId = (await automation.newTab(pid, url)).id;
  // …中途任何一个 return 分支…
} finally {
  if (tabId) await automation.closeTab(pid, tabId);
}

evaluate 里的代码跑在页面里

const items = await automation.evaluate(pid, `
  (function () {
    var out = [];
    document.querySelectorAll('[class*="offer-item"]').forEach(function (c) {
      var t = c.querySelector('[class*="title"]');
      if (t) out.push({ title: t.innerText.trim() });
    });
    return out;      // ★ 必须能 JSON 序列化
  })()`);

批量写库用一个事务

db.tx(() => {
  for (const it of items) db.exec('INSERT INTO offers(...) VALUES(?,?,?)', [...]);
});

十条分十次提交 = 磁盘同步十次，慢一个数量级。

文件选择 files:pick

const f = await files.pickOpen({
  title: '选一个 CSV',
  filters: [{ name: '表格', extensions: ['csv', 'xlsx'] }],
});
if (!f) return;                       // 用户点了取消，不是错误
f.name; f.size; f.path; f.bytes;      // bytes 是 Buffer

await files.pickSave({ title: '导出', defaultPath: 'out.csv' }, buffer);

写界面的三条约束

0. 先用平台组件，别从零写样式

平台提供一套 gs- 开头的组件类，直接用类名即可，不用自己写这些样式。 它们跟随客户端主题，和宿主界面天然一致。

类清单

按钮

布局

数据展示

表单

标记与提示

1. HTML 是片段，不是完整文档

不要写 <html> / <head> / <body>。它直接挂进宿主界面。

2. CSS 每条选择器都要带前缀

规则只有一条：ui/style.css 里每条规则、逗号分隔的每一段， 第一个选择器都必须以 .你的前缀- 开头。

.abc-wrap { }                ✅
.abc-wrap .title { }         ✅ 后代选择器 —— 已经被前缀圈在自己的子树里
.abc-btn:hover { }           ✅ 伪类
@media (max-width:600px){ .abc-wrap { } }   ✅ 媒体查询里照样要带
@keyframes abc-fade { }      ✅ 动画名建议也带前缀（避免和别人重名）

.wrap { }                    ❌ 裸类
button { }                   ❌ 客户端里每一个按钮都会被改掉
#panel { }                   ❌ id 是全局的
* { margin:0 }               ❌ 一句 reset 就能毁掉整个客户端界面
.abc-a, .navbar { }          ❌ 逗号后面那段也要带
.gs-btn { background:red }   ❌ 平台组件只能用，不能改

用第三方框架：平台已经内置了三个

在 manifest.json 里声明一句就能用，应用不带任何框架文件：

{
  "key": "abc-demo",
  "ui": { "framework": "bootstrap5" },
  ...
}

<!-- 声明了 bootstrap5 之后，直接这么写 -->
<div class="card"><div class="card-body">
  <button class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#m1">打开</button>
</div></div>

<!-- 无类名框架（milligram / daft）连 class 都不用 -->
<h2>标题</h2>
<form><input type="text"><button>提交</button></form>
<table>…</table>

{ "key": "abc-bulk-run", "uiPrefix": "abrun", … }

要用内置以外的框架

可以，但要先做"作用域包装"。原样引入会被自查拦下 —— 这类框架第一件事就是重置全局：*{box-sizing:border-box}、 body{margin:0}、h1~h6 的字号…… 应用界面和客户端共用同一个文档，这些规则会命中宿主的元素， 把整个客户端的排版改掉，而且是装了这个应用的所有人都受影响。

做法：把框架的每一条规则前面加上你自己的一个容器类， HTML 里再套一层这个容器。

/* ❌ 原样 —— 自查会拦 */
*,::before,::after { box-sizing: border-box }
body { margin: 0 }
.btn-primary { ... }

/* ✅ 每条前面加 .abc-bs */
.abc-bs *, .abc-bs ::before, .abc-bs ::after { box-sizing: border-box }
.abc-bs body { margin: 0 }        /* 匹配不到东西，无害 */
.abc-bs .btn-primary { ... }

<!-- HTML 里套一层，里面照常写框架的类 -->
<div class="abc-bs">
  <div class="card"><div class="card-body">
    <button class="btn btn-primary">确定</button>
  </div></div>
</div>

包装可以让工具做，不用手改几千行：

# Sass：一行搞定
.abc-bs { @import "bootstrap/scss/bootstrap"; }

# PostCSS
postcss bootstrap.css --use postcss-prefix-selector \
  --postcss-prefix-selector.prefix ".abc-bs" -o scoped.css

前缀由 key 推导（每段首字母）。CSS 标识符不能以数字开头， 所以数字开头的会自动补一个 a：8d7dk-example → a8e。 自查会告诉你该用哪个前缀。

3. app.js 必须是 IIFE

(function () {
  'use strict';
  // 你的代码
})();

不包一层的话，你的 let out = ... 会挂到 window 上，和宿主或别的应用撞名—— 而撞名的表现是「另一个应用的变量莫名其妙变了」，最难查的那种。

开发者 ID 与 app_key

发第一个应用之前，先在「应用中心 → 我的开发」注册一个开发者 ID（API 里的字段名是 devHandle）。 它会成为你所有应用的前缀，和 npm 的 @scope、Docker 的用户名、 VS Code 的 publisher 是同一个东西。

你注册的开发者 ID    smartmob
应用标识的后半截     sourcing        ← 只能小写字母/数字/连字符
                ↓
最终的 app_key      smartmob-sourcing

为什么必须带前缀

app_key 不只是个名字，它同时是三样东西：

所以两个开发者都建了个叫 report 的应用会互相覆盖， 而且是静默覆盖——B 的客户端装上 A 的代码，没有任何报错。前缀就是防这个的。

命名建议

规则：3–20 个字符，小写字母开头，只能用小写字母、数字、连字符； 连字符不能连用也不能结尾。official gathersurf admin 这类保留词注册不了——它们会被用来冒充官方。

变量与接口命名

你的应用内部想怎么写都行，我们不检查。但下面这套是平台自己在用的， 照着来的好处是：你的代码和文档、示例工程、以及将来 AI 帮你改的代码，长得是一套。

一句话规则

IPC 通道名为什么是 模块:动作

goods:list      goods:star     goods:remove
collect:start   collect:stop   collect:state
win:create      win:remove     win:proxies

好处是按模块前缀就能一眼看全一个功能有哪些动作， 而 listGoods / starGoods / removeGoods 这种在长列表里是散的。 示例工程 main.js 里三十来个 handler 就是这么排的，翻一下就知道意思。

名字要说清"是什么"，不是"有多短"

数据库表与字段

用 host.db 建表时的规范。这不是洁癖——SQL 有它自己的规矩， 按 JS 的习惯写会被语言本身咬。

为什么数据库不用驼峰

SQL 会把不加引号的标识符折叠大小写。你写 createdAt， 存进去可能变成 createdat；想保住大小写就得每一处都写引号， 少一处就是运行时报错。所以：

数据库列   snake_case     created_at_ms, goods_id, price_cents
    ↓ 取出来的那一刻转一次
JS 代码    camelCase      createdAt,  goodsId,  priceCents

转换点只放一个地方——就是你查询函数返回的那个对象。出了那个函数，全应用都是驼峰。

// ✓ 手写投影，一处转换
function listGoods() {
  // host.db 是同步的，不要加 await
  const rows = host.db.query(
    'SELECT id, title, price_cents, created_at_ms FROM goods ORDER BY id DESC LIMIT 200');
  return rows.map(r => ({
    id: r.id, title: r.title,
    priceCents: r.price_cents,      // ← 转换只发生在这里
    createdAtMs: r.created_at_ms,
  }));
}

// ✗ 直接把库里的行吐出去 —— 下划线会漏得整个应用到处都是
function listGoods() {
  return host.db.query('SELECT * FROM goods');   // 而且没有 LIMIT
}

时间戳：你的库用毫秒，我们的云端用秒

你可能会注意到这个不一致，这里说清楚——不是两套标准，是同一条原则： 在写入的那一侧做零转换。

Date.now() 给的就是毫秒，time.time() 给的就是秒。 各自直存，就没有转换，也就没有转错的机会。

而且这两个库不会碰面——应用拿不到我们云端的时间戳 （profiles.list() 只回 id / 窗口号 / 名字 / 分组 / 平台）， 所以不存在"两种单位混进同一列"的风险。真正致命的从来是那个，不是选哪个单位。

字段规范

建表走 migrate()，不要直接 exec

建表和加列都放进 migrate()。它按版本号记账：跑过的版本下次启动时整条跳过， 所以你可以在 register() 里无条件调用，不用自己判断"表建过没有"。

host.db.migrate([
  {
    v: 1,
    name: 'create_goods',
    up: [`
      CREATE TABLE IF NOT EXISTS goods (
        id            INTEGER PRIMARY KEY AUTOINCREMENT,
        keyword       TEXT    NOT NULL,
        title         TEXT    NOT NULL,
        shop_name     TEXT,
        price_cents   INTEGER NOT NULL DEFAULT 0,   -- 整数分，不用浮点
        is_starred    INTEGER NOT NULL DEFAULT 0,   -- 布尔：0/1
        source_url    TEXT,
        created_at_ms INTEGER NOT NULL,             -- Date.now()，毫秒
        updated_at_ms INTEGER NOT NULL
      )`,
      // 查得多的列建索引 —— 上千行之后，没索引的模糊搜会肉眼可见地卡
      `CREATE INDEX IF NOT EXISTS idx_goods_keyword ON goods(keyword)`,
    ],
  },
  // 后来要加列，加一个新版本，不要改 v:1 的内容
  { v: 2, name: 'goods_add_note', up: [`ALTER TABLE goods ADD COLUMN note TEXT`] },
]);

返回 { from, to }——两个值相等表示这次什么都没跑。

插入、更新、删除用 exec(sql, params)；查询用 query(sql, params)； 一批写操作包进 tx(fn)。

外部接口：这是什么 / 怎么开

除了「在客户端里开发应用」，还有第二条路：用你自己的语言、你自己的进程驱动 GatherSurf。 客户端在本机开了一个 HTTP 服务，你用 Python、Node、Go、curl——什么都行。

怎么开启

1. 客户端 →「设置」→「本地自动化 API」→ 打开
2. 同一页能看到你的 token（就是账号级的 API token）
3. 服务地址固定 http://127.0.0.1:48090，只监听本机

30 秒跑通

先探活（这一个不要 token）

curl http://127.0.0.1:48090/gs/v1/health

Python

import os, requests

BASE  = "http://127.0.0.1:48090/gs/v1"
TOKEN = os.environ["GS_TOKEN"]          # ★ 别写死在代码里
H = {"X-GS-Token": TOKEN}

# 1. 建一个号
r = requests.post(f"{BASE}/profiles", headers=H, json={
    "name": "测试号",
    "group": "默认分组",
    "proxyLine": "socks5://user:[email protected]:1080",   # 可选
}).json()
pid = r["data"]["id"]

# 2. 开窗口 —— 返回 CDP 地址，接下来用 playwright/puppeteer 接管
r = requests.post(f"{BASE}/profiles/{pid}/launch", headers=H, json={}).json()
cdp = r["data"]["automation"]["cdpWs"]
print("CDP:", cdp)

# 3. 用 playwright 接上去
from playwright.sync_api import sync_playwright
with sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(cdp)
    page = browser.contexts[0].new_page()
    page.goto("https://httpbin.org/ip")
    print(page.content()[:200])

# 4. 关掉
requests.post(f"{BASE}/profiles/{pid}/shutdown", headers=H, json={})

Node

const BASE = 'http://127.0.0.1:48090/gs/v1';
const H = { 'X-GS-Token': process.env.GS_TOKEN, 'Content-Type': 'application/json' };
const api = async (method, path, body) => {
  const r = await fetch(BASE + path, { method, headers: H,
    body: body ? JSON.stringify(body) : undefined });
  const j = await r.json();
  if (!j.ok) throw new Error(`${path} 失败: ${j.error?.message || r.status}`);
  return j.data;
};

const { id } = await api('POST', '/profiles', { name: '测试号' });
const { automation } = await api('POST', `/profiles/${id}/launch`, {});
console.log('CDP:', automation.cdpWs);

// 用 puppeteer 接管
const puppeteer = require('puppeteer-core');
const b = await puppeteer.connect({ browserWSEndpoint: automation.cdpWs });
const p = await b.newPage();
await p.goto('https://httpbin.org/ip');
console.log((await p.content()).slice(0, 200));

await api('POST', `/profiles/${id}/shutdown`, {});

成功：{ "ok": true,  "data": { … } }
失败：{ "ok": false, "error": { "code": "forbidden", "message": "人话" } }

自测台：下载与用法

本地 API 自测台是一个外部工具——零依赖 Node，带界面，附全部源码。 它按第三方开发者的视角写成：只用这一页公开的接口，不碰任何内部约定。 两个用途：先跑一遍看接口通不通，以及当成可以直接抄的调用范例。

它能做什么

下载

https://api.gathersurf.com/download/tool/gs-api-test  ·  查版本和校验值：/manifest

这个地址永远指向最新版（会 302 跳到就近的下载节点），所以不用记版本号。 下载后建议核一下 sha256 跟 manifest 对不对得上—— 这工具要你把 token 粘进去，值得多花那 5 秒：

shasum -a 256 gs-api-test.zip                # macOS / Linux
certutil -hashfile gs-api-test.zip SHA256    # Windows

怎么跑

需要 Node 18 以上（node -v 看一眼），解压后在目录里：

node gs-api-test.js      # 起界面，浏览器开 http://127.0.0.1:48099
node e2e.js              # 或者不看界面，直接跑一遍端到端场景

界面打开后把 token 粘进去就能点。★ token 只存在这个 Node 进程的内存里， 不写文件、不进日志——关掉进程就没了，所以每次起来都要重新粘。

接口清单

服务自身

环境（号）

指纹

Cookie

批量

批量接口都返回逐条结果：{ total, succeeded, results:[{id, ok, error?}] }—— 部分失败不会让整批失败，你能准确知道是哪几个没成。

代理

分组 / 标签 / 回收站

内核

常用配方

代理池自动体检，坏的打标签

proxies = requests.get(f"{BASE}/proxies", headers=H).json()["data"]["proxies"]
for px in proxies:
    r = requests.post(f"{BASE}/proxies/{px['id']}/check", headers=H,
                      json={"timeoutMs": 8000}).json()["data"]
    if not r["alive"]:
        # 打个标签，人工再看
        requests.patch(f"{BASE}/proxies/{px['id']}", headers=H,
                       json={"tags": px.get("tags", []) + ["失效"]})
    print(px["id"], "✓" if r["alive"] else "✗", r.get("ip", r.get("error")))

一个号一条代理，批量建

lines = open("proxies.txt").read().split()
for i, line in enumerate(lines, 1):
    chk = requests.post(f"{BASE}/proxies/check", headers=H, json={"line": line}).json()["data"]
    if not chk["alive"]:
        print(f"跳过第 {i} 条：{chk['error']}"); continue      # ★ 先验再建，别建一堆废号
    requests.post(f"{BASE}/profiles", headers=H, json={
        "name": f"号-{i}-{chk['country']}", "proxyLine": line,
        "basedOnIP": True,     # 按出口 IP 收口语言/时区，避免地理矛盾
    })

把一个号的指纹复制到另一个账号

# 账号 A 导出
fp = requests.get(f"{BASE}/profiles/{pid}/export", headers=H).json()["data"]
json.dump(fp, open("fp.json", "w"))

# 账号 B（换 token）导入 —— 还原出同一指纹
fp = json.load(open("fp.json"))
requests.post(f"{BASE}/profiles/import", headers=H2, json={"fingerprint": fp, "name": "还原号"})

批量开号跑任务，控制并发

ids = [p["id"] for p in profiles[:10]]
r = requests.post(f"{BASE}/profiles/batch/launch", headers=H,
                  json={"ids": ids, "intervalMs": 2000}).json()["data"]
print(f"{r['succeeded']}/{r['total']} 开成功")
for x in r["results"]:
    if not x["ok"]: print("  失败:", x["id"], x.get("error"))
    else:           print("  CDP:", x["automation"]["cdpWs"])

# … 跑你的任务 …

requests.post(f"{BASE}/profiles/batch/shutdown", headers=H, json={"ids": ids})

规范自查

⚙设置 →「规范自查」。自查不过就打不了包——不是为了卡你， 是这些问题在上传后同样会被拒，而原因本来在本地就知道。

自查只覆盖机器能判定的部分。权限是不是最小、错误处理够不够，要人看—— 自查通过不代表一定能上架。

三种发布

发出去的代码是加密的

只要走云端分发（团队 / 公开上架），用户装到本地的包里， .js .html .css .json .md .txt 在磁盘上是密文。 成员打开应用目录看到的是二进制，复制走也跑不了。

✗ const tpl = fs.readFileSync(path.join(__dirname,'tpl.html'),'utf8')
✓ const tpl = require('./tpl.js').html        ← 走 require
✓ const cfg = require('./config.json')        ← require 认 .json

授权管理 —— 谁能装你的应用

发布到团队之后，在「我的开发 → ⚙ 设置 → 🔑 授权管理」里按对方的注册邮箱发授权。 被授权的账号不必是你的团队成员——可以是任何 GatherSurf 账号。

上架审核

提交后进队列，我们人工看。审核期间你已经上架的老版本不受影响—— 用户照常用旧版，新版单独排队。

我们会看什么

• 权限是不是最小——要了 automation 但其实用不上？
• 出网白名单合不合理——有没有写成通配？要往哪发数据？
• 代码本身——审核界面能直接看包里每个文件，声明和实现不一致会被发现
  （我们审的是你上传的明文原件；加密是在审核通过之后才做的， 所以加密不会妨碍审核，也不会让审核变慢）

结果怎么通知你

• 客户端里主动弹提示，侧栏「应用中心」上打角标
• 卡片上留一行状态；点「详情」能看到完整审核记录——提交过几次、每次的驳回理由
• 提交时可以留联系邮箱，审核人会把结果发到这个邮箱

⚠ 避坑速查

这些都是真出过问题的，共同点是不报错—— 所以事后特别难查，而写的时候顺手避开几乎不花时间。