@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/capabilities/agent-reach.js

@@ -1,204 +1,119 @@
+/**
+ * agent-reach wrapper —— 上游 Panniantong/Agent-Reach 的薄壳(零渠道知识)。
+ *
+ * 分工(2026-08-22 founder 纠偏「wrapper 不是 router」):
+ *   - 知识(渠道清单/方法签名/setup 指引)→ 上游:agent_reach.channels 注册表 + Channel.check() + guides/
+ *   - 决策(该调哪个渠道哪个方法)      → dsh 里的 LLM(靠本 wrapper 的自描述错误拿清单)
+ *   - 管道(spawn/超时/永不抛错/证据链) → 本文件 + agent-reach-bridge.py,上游加渠道零改动
+ *
+ * 上游设计意图(Channel 基类原话):"After installation, agents call upstream tools directly."
+ *   - python-API 渠道(web.read / v2ex.get_hot_topics / xueqiu.get_stock_quote / youtube.transcribe ...)
+ *     走本文件 reach() 的反射桥
+ *   - 外部 CLI 工具渠道(github→gh / youtube 字幕→yt-dlp 等)由专用 dsh 工具(gotry_github_search /
+ *     gotry_video_subtitle,见 agent-reach-deep.ts)充当执行面;上游无 python API 的不再自行拼命令
+ *
+ * 契约(L4 不变量,与 anything/weather/opensky 同构):
+ *   - 永不抛错;verdict: found / not-installed / needs-setup / error
+ *   - needs-setup 的 setup 文案 = 上游 check() 原话透传,不转述
+ *   - 证据链 [agent-reach:<channel>.<method>@ts]
+ */
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-const ts = ()=>new Date().toISOString();
-const repoRoot = ()=>resolve(import.meta.dirname, '..', '..');
-const venvPython = ()=>resolve(repoRoot(), '.venv/bin/python');
-const bridgeScript = ()=>resolve(import.meta.dirname, 'agent-reach-bridge.py');
+const ts = () => new Date().toISOString();
+const repoRoot = () => resolve(import.meta.dirname, '..', '..');
+const venvPython = () => resolve(repoRoot(), '.venv/bin/python');
+const bridgeScript = () => resolve(import.meta.dirname, 'agent-reach-bridge.py');
 function run(bin, args, timeoutMs) {
-    return new Promise((resolveRun)=>{
-        const child = spawn(bin, args, {
-            env: process.env
-        });
+    return new Promise((resolveRun) => {
+        const child = spawn(bin, args, { env: process.env });
         let stdout = '';
         let stderr = '';
         let err;
-        const timer = setTimeout(()=>{
-            try {
-                child.kill('SIGKILL');
-            } catch  {}
-        }, timeoutMs);
-        child.stdout.on('data', (d)=>{
-            stdout += d.toString();
-        });
-        child.stderr.on('data', (d)=>{
-            stderr += d.toString();
-        });
-        child.on('error', (e)=>{
-            err = e.message;
-        });
-        child.on('close', (code)=>{
-            clearTimeout(timer);
-            resolveRun({
-                code,
-                stdout,
-                stderr,
-                err
-            });
-        });
+        const timer = setTimeout(() => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* ignore */ } }, timeoutMs);
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        child.on('error', (e) => { err = e.message; });
+        child.on('close', (code) => { clearTimeout(timer); resolveRun({ code, stdout, stderr, err }); });
     });
 }
+/** 通用入口:反射调上游任意渠道方法;永不抛错 */
 export async function reach(q) {
     const started = Date.now();
-    const evidence = (state)=>`[agent-reach:${q.channel}.${q.method}@${state === 'found' ? ts() : `${state}@${ts()}`}]`;
-    const base = {
-        channel: q.channel,
-        method: q.method
-    };
+    const evidence = (state) => `[agent-reach:${q.channel}.${q.method}@${state === 'found' ? ts() : `${state}@${ts()}`}]`;
+    const base = { channel: q.channel, method: q.method };
     if (!q.channel || !q.method) {
-        return {
-            ...base,
-            ok: false,
-            verdict: 'error',
-            evidence: evidence('error'),
-            latencyMs: 0,
-            error: 'channel 与 method 必填(渠道/方法清单:先随便调一次,inventory 会带回上游清单)'
-        };
+        return { ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs: 0, error: 'channel 与 method 必填(渠道/方法清单:先随便调一次,inventory 会带回上游清单)' };
     }
     const py = venvPython();
     if (!existsSync(py)) {
-        return {
-            ...base,
-            ok: false,
-            verdict: 'not-installed',
-            evidence: evidence('not-installed'),
-            latencyMs: 0,
-            setup: 'gotry .venv 缺 python——可选依赖未装配。补装:终端跑 npx gotry doctor --fix,或让用户看体检报告 npx gotry doctor'
-        };
+        return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs: 0, setup: 'gotry .venv 缺 python——可选依赖未装配。补装:终端跑 npx @danceiny/gotry doctor --fix,或让用户看体检报告 npx @danceiny/gotry doctor' };
     }
-    const args = Array.isArray(q.args) ? q.args : q.args ? q.args.split(/\s+/).filter(Boolean) : [];
-    const r = await run(py, [
-        bridgeScript(),
-        q.channel,
-        q.method,
-        ...args
-    ], q.timeoutMs ?? 30_000);
+    const args = Array.isArray(q.args) ? q.args : (q.args ? q.args.split(/\s+/).filter(Boolean) : []);
+    const r = await run(py, [bridgeScript(), q.channel, q.method, ...args], q.timeoutMs ?? 30_000);
     const latencyMs = Date.now() - started;
     let parsed = {};
     try {
         parsed = JSON.parse((r.stdout || '').trim().split('\n').filter(Boolean).pop() ?? '{}');
-    } catch  {}
+    }
+    catch { /* 走下面的兜底 */ }
     if (r.err?.includes('ENOENT')) {
-        return {
-            ...base,
-            ok: false,
-            verdict: 'not-installed',
-            evidence: evidence('not-installed'),
-            latencyMs,
-            setup: '.venv/bin/python 不可执行——补装:终端跑 npx gotry doctor --fix'
-        };
+        return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv/bin/python 不可执行——补装:终端跑 npx @danceiny/gotry doctor --fix' };
     }
     if (parsed.ok === true) {
-        return {
-            ...base,
-            ok: true,
-            verdict: 'found',
-            evidence: evidence('found'),
-            latencyMs,
-            data: parsed.data
-        };
+        return { ...base, ok: true, verdict: 'found', evidence: evidence('found'), latencyMs, data: parsed.data };
     }
+    // 上游 agent_reach 包未装(bridge 自己的 exit 3 输出)
     if (parsed.error?.includes('agent_reach 未安装')) {
-        return {
-            ...base,
-            ok: false,
-            verdict: 'not-installed',
-            evidence: evidence('not-installed'),
-            latencyMs,
-            setup: '.venv 缺 agent-reach 包——补装:终端跑 npx gotry doctor --fix'
-        };
+        return { ...base, ok: false, verdict: 'not-installed', evidence: evidence('not-installed'), latencyMs, setup: '.venv 缺 agent-reach 包——补装:终端跑 npx @danceiny/gotry doctor --fix' };
     }
+    // 未知渠道/方法:自描述,附上游清单(不拦 LLM,让它看清单自纠)
     if (r.code === 2) {
         return {
-            ...base,
-            ok: false,
-            verdict: 'error',
-            evidence: evidence('error'),
-            latencyMs,
+            ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs,
             error: parsed.error,
-            inventory: parsed.channels ? {
-                channels: parsed.channels
-            } : {
-                channel: parsed.channel,
-                methods: parsed.methods
-            }
+            inventory: parsed.channels ? { channels: parsed.channels } : { channel: parsed.channel, methods: parsed.methods },
         };
     }
+    // 调用抛错:若上游 check() 给出 warn/off,把上游原话作为 setup 透传
     const checkStatus = parsed.check?.status;
     if (checkStatus === 'warn' || checkStatus === 'off') {
-        return {
-            ...base,
-            ok: false,
-            verdict: 'needs-setup',
-            evidence: evidence('needs-setup'),
-            latencyMs,
-            error: parsed.error,
-            setup: parsed.check?.message
-        };
+        return { ...base, ok: false, verdict: 'needs-setup', evidence: evidence('needs-setup'), latencyMs, error: parsed.error, setup: parsed.check?.message };
     }
-    return {
-        ...base,
-        ok: false,
-        verdict: 'error',
-        evidence: evidence('error'),
-        latencyMs,
-        error: parsed.error ?? r.stderr.slice(0, 200)
-    };
+    return { ...base, ok: false, verdict: 'error', evidence: evidence('error'), latencyMs, error: parsed.error ?? r.stderr.slice(0, 200) };
 }
+/** 读网页:委托上游 WebChannel.read(Jina Reader 后端);供 gotry web 读取工具使用 */
 export async function readUrl(q) {
     if (!/^https?:\/\//.test(q.url.trim())) {
-        return {
-            ok: false,
-            via: 'r.jina.ai-error',
-            evidence: `[agent-reach:web.read@error@${ts()}] 非法 URL(需 http(s)://)`,
-            latencyMs: 0,
-            error: 'url 必须以 http(s):// 开头'
-        };
+        return { ok: false, via: 'r.jina.ai-error', evidence: `[agent-reach:web.read@error@${ts()}] 非法 URL(需 http(s)://)`, latencyMs: 0, error: 'url 必须以 http(s):// 开头' };
     }
-    const r = await reach({
-        channel: 'web',
-        method: 'read',
-        args: [
-            q.url.trim()
-        ],
-        timeoutMs: q.timeoutMs
-    });
+    const r = await reach({ channel: 'web', method: 'read', args: [q.url.trim()], timeoutMs: q.timeoutMs });
     const content = typeof r.data === 'string' ? r.data.slice(0, 8000) : undefined;
+    // 上游 Jina Reader 输出首行 "Title: ...",提取为标题(展示层逻辑,非渠道知识)
     const title = content?.match(/^Title: (.+)$/m)?.[1];
     return {
-        ok: r.ok,
-        via: r.ok ? 'r.jina.ai' : 'r.jina.ai-error',
-        title,
-        content,
-        evidence: r.evidence,
-        latencyMs: r.latencyMs,
-        error: r.error
+        ok: r.ok, via: r.ok ? 'r.jina.ai' : 'r.jina.ai-error',
+        title, content, evidence: r.evidence, latencyMs: r.latencyMs,
+        error: r.error,
     };
 }
+/** 渠道体检:spawn 真 agent-reach doctor,输出原样透传 */
 export async function reachStatus(timeoutMs = 90_000) {
     const started = Date.now();
     const bin = resolve(repoRoot(), '.venv/bin/agent-reach');
     if (!existsSync(bin)) {
-        return {
-            ok: false,
-            via: 'not-installed',
-            evidence: `[agent-reach:doctor@not-installed@${ts()}]`,
-            latencyMs: 0,
-            output: 'Agent Reach 未装配(.venv 缺失)——可选依赖,补装:终端跑 npx gotry doctor --fix;或让助手调 gotry_doctor 看整体体检报告'
-        };
+        return { ok: false, via: 'not-installed', evidence: `[agent-reach:doctor@not-installed@${ts()}]`, latencyMs: 0, output: 'Agent Reach 未装配(.venv 缺失)——可选依赖,补装:终端跑 npx @danceiny/gotry doctor --fix;或让助手调 gotry_doctor 看整体体检报告' };
     }
-    const r = await run(bin, [
-        'doctor'
-    ], timeoutMs);
+    const r = await run(bin, ['doctor'], timeoutMs);
     const output = (r.stdout || r.stderr).trim();
     return {
         ok: !r.err?.includes('ENOENT') && r.code === 0,
         via: 'agent-reach-cli',
         evidence: `[agent-reach:doctor@${ts()}] via .venv/bin/agent-reach`,
         latencyMs: Date.now() - started,
-        output: output.slice(0, 4000)
+        output: output.slice(0, 4000),
     };
 }
-
-
-//# sourceURL=ts/capabilities/agent-reach.ts

package/dist/capabilities/anything.js

@@ -1,114 +1,132 @@
+/**
+ * Anything 通用搜索能力层:hbcli → hotel-be Anything 函数。
+ *
+ * 链路(同构 hbcli.ts):
+ *   gotry capabilities/anything.ts
+ *     → spawn hbcli --json search anything <kw> [opts]
+ *       → hotel-be /api/search/anything(httpdispatch 自动注册;httpdispatch 路由面)
+ *         → search/service/geography.go func Anything (mixed 城市+酒店搜索)
+ *
+ * wire 契约(2026-09-07 对齐上游源码;SearchItem = FuzzySearchItem + hotel):
+ *   req  { keyword, contentType?, context.destinationId?, minHotelCount? }
+ *   resp { candidates: [{ type: 'city'|'place'|'hotel',
+ *                         region?:  { id, name:{en,zh,ar}, coordinates:{centerLat,centerLng}, countryCode, … },
+ *                         place?:   { latlngCoordinator },
+ *                         matchScore?, hotel?: { id, name:{en,zh,ar}, star, latlngCoordinator:{google|gaode:{lat,lng} } } }] }
+ *
+ * 三值语义:
+ *   - hit:  命中候选(混合 city/hotel,maybe-coords)
+ *   - miss: hbcli exit 0,但 candidates 为空(查无结果)
+ *   - err:  hbcli exit ≠ 0 或超时(降级,降级产物 标 [实时API:hbcli-anything@error@ts])
+ *
+ * 契约(与 hbcli/weather/opensky 同构,L4 不变量):
+ *   - 永不抛错:网络/超时/解析失败一律降级返回;
+ *   - 证据链标注:成功 [实时API:hbcli-anything@ts];失败 [实时API:hbcli-anything@error@ts];
+ *   - 永不阻塞调用方:周边有 12s 默认超时,LLM 不等。
+ *
+ * 第 7 个能力层(与 hbcli.ts / weather.ts / opensky.ts 平级),data-sources.md §4
+ * Google Place 链路的「酒店-be 中间层」入口。
+ */
 import { spawn } from 'node:child_process';
 import { hbcliBinCandidates } from './hbcli.js';
 function i18nText(v) {
-    if (!v) return '';
-    if (typeof v === 'string') return v;
+    if (!v)
+        return '';
+    if (typeof v === 'string')
+        return v;
     return v.zh || v.en || v.ar || '';
 }
+/** hotel-be Latlng:{lat,lng};google/gaode 双源取先非零者 */
 function latlngOf(coord) {
-    for (const src of [
-        coord?.google,
-        coord?.gaode
-    ]){
+    for (const src of [coord?.google, coord?.gaode]) {
         const lat = typeof src?.lat === 'number' ? src.lat : undefined;
         const lng = typeof src?.lng === 'number' ? src.lng : undefined;
-        if (lat !== undefined && lng !== undefined && (lat !== 0 || lng !== 0)) return {
-            latitude: lat,
-            longitude: lng
-        };
+        if (lat !== undefined && lng !== undefined && (lat !== 0 || lng !== 0))
+            return { latitude: lat, longitude: lng };
     }
     return {};
 }
 function sh(cmd, args, opts) {
     const ctrl = new AbortController();
-    const timer = setTimeout(()=>{
+    const timer = setTimeout(() => {
         ctrl.abort();
+        // AbortSignal on spawn 会发 SIGTERM;对于不响应 SIGTERM 的子进程,需要在外部再发一次 SIGKILL。
+        // Node 不能直接通过 AbortController 拿 child pid,所以需要借助外部变量保存 child。
     }, opts.timeoutMs);
     let child = null;
     let killTimer = null;
-    return new Promise((resolve)=>{
+    return new Promise((resolve) => {
         child = spawn(cmd, args, {
             env: opts.env,
             cwd: process.cwd(),
-            signal: ctrl.signal
+            signal: ctrl.signal,
         });
         let stdout = '';
         let stderr = '';
         let error;
         let killed = false;
-        child.stdout?.on('data', (d)=>{
-            stdout += d.toString();
-        });
-        child.stderr?.on('data', (d)=>{
-            stderr += d.toString();
-        });
-        child.on('error', (e)=>{
-            error = e.message.slice(0, 200);
-        });
-        child.on('close', (code)=>{
+        child.stdout?.on('data', (d) => { stdout += d.toString(); });
+        child.stderr?.on('data', (d) => { stderr += d.toString(); });
+        child.on('error', (e) => { error = e.message.slice(0, 200); });
+        child.on('close', (code) => {
             clearTimeout(timer);
-            if (killTimer) clearTimeout(killTimer);
-            resolve({
-                code: killed ? -2 : code ?? -1,
-                stdout,
-                stderr,
-                error
-            });
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({ code: killed ? -2 : (code ?? -1), stdout, stderr, error });
         });
-        ctrl.signal.addEventListener('abort', ()=>{
-            if (!child) return;
+        // Abort 后 500ms 内若子进程仍活,发 SIGKILL 强杀。
+        ctrl.signal.addEventListener('abort', () => {
+            if (!child)
+                return;
             try {
                 child.kill('SIGTERM');
-            } catch  {}
-            killTimer = setTimeout(()=>{
+            }
+            catch { /* ignore */ }
+            killTimer = setTimeout(() => {
                 try {
                     child?.kill('SIGKILL');
-                } catch  {}
+                }
+                catch { /* ignore */ }
             }, 500);
         });
     });
 }
+/** --json 必须在子命令前(cli.ts 全局旗标预扫描只认子命令前位置;JSON 错误也走结构化 stderr) */
 function buildArgs(keyword, q) {
-    const args = [
-        '--json',
-        'search',
-        'anything',
-        keyword
-    ];
-    if (q.contentType) args.push('--content-type', q.contentType);
-    if (q.parentDestinationId !== undefined) args.push('--destination-id', String(q.parentDestinationId));
+    const args = ['--json', 'search', 'anything', keyword];
+    if (q.contentType)
+        args.push('--content-type', q.contentType);
+    if (q.parentDestinationId !== undefined)
+        args.push('--destination-id', String(q.parentDestinationId));
     return args;
 }
+/** 旧版 CLI 无 search anything 子命令时的可行动升级指引(issue #195:裸 unknown command 读起来像工具坏了) */
 function upgradeHint(stderr) {
-    return /unknown command/i.test(stderr) ? 'hbcli 版本过旧(无 search anything 子命令)——请升级:hbcli update,或重跑 npx gotry setup' : null;
+    return /unknown command/i.test(stderr)
+        ? 'hbcli 版本过旧(无 search anything 子命令)——请升级:hbcli update,或重跑 npx @danceiny/gotry setup'
+        : null;
 }
+/** Anything 通用搜索 — 任何搜索失败走降级;不抛错 */
 export async function anythingSearch(q) {
     const started = Date.now();
     const ts = new Date().toISOString();
     const kw = (q.keyword ?? '').trim();
     if (!kw) {
         return {
-            ok: false,
-            via: 'hbcli-anything-error',
+            ok: false, via: 'hbcli-anything-error',
             evidence: `[实时API:hbcli-anything@error@${ts}] keyword empty`,
-            latencyMs: Date.now() - started,
-            verdict: 'error',
-            error: 'keyword is required'
+            latencyMs: Date.now() - started, verdict: 'error',
+            error: 'keyword is required',
         };
     }
     const args = buildArgs(kw, q);
+    // spawn 级失败(ENOENT)按已知安装位回退(hbcli.ts callHbcliJson 同款);其余失败无重试意义
     const candidates = hbcliBinCandidates(q.hbcliBin ?? 'hbcli');
-    let r = {
-        code: -1,
-        stdout: '',
-        stderr: ''
-    };
-    for(let i = 0; i < candidates.length; i++){
-        r = await sh(candidates[i], args, {
-            timeoutMs: q.timeoutMs ?? 12_000,
-            env: process.env
-        });
-        if (!(r.error && i < candidates.length - 1)) break;
+    let r = { code: -1, stdout: '', stderr: '' };
+    for (let i = 0; i < candidates.length; i++) {
+        r = await sh(candidates[i], args, { timeoutMs: q.timeoutMs ?? 12_000, env: process.env });
+        if (!(r.error && i < candidates.length - 1))
+            break;
     }
     const latencyMs = Date.now() - started;
     if (r.error || r.code !== 0) {
@@ -119,7 +137,7 @@ export async function anythingSearch(q) {
             evidence: `[实时API:hbcli-anything@error@${ts}] ${raw}`,
             latencyMs,
             verdict: 'error',
-            error: upgradeHint(r.stderr) ?? raw
+            error: upgradeHint(r.stderr) ?? raw,
         };
     }
     let data;
@@ -127,18 +145,18 @@ export async function anythingSearch(q) {
         const jStart = r.stdout.indexOf('{') >= 0 ? r.stdout.indexOf('{') : r.stdout.indexOf('[');
         const json = jStart >= 0 ? r.stdout.slice(jStart) : r.stdout;
         data = JSON.parse(json);
-    } catch  {
+    }
+    catch {
         return {
-            ok: false,
-            via: 'hbcli-anything-error',
+            ok: false, via: 'hbcli-anything-error',
             evidence: `[实时API:hbcli-anything@error@${ts}] parse failed`,
             latencyMs,
             verdict: 'error',
-            error: 'failed to parse hbcli output as JSON'
+            error: 'failed to parse hbcli output as JSON',
         };
     }
     const rawItems = data.candidates ?? [];
-    const hits = rawItems.map((it)=>{
+    const hits = rawItems.map((it) => {
         const region = it.region ?? {};
         const hotel = it.hotel ?? {};
         const isHotel = it.type === 'hotel' || Boolean(hotel.id);
@@ -146,27 +164,23 @@ export async function anythingSearch(q) {
         const placeCoords = latlngOf(it.place?.latlngCoordinator);
         const center = region.coordinates ?? {};
         return {
-            type: isHotel ? 'hotel' : it.type === 'place' ? 'place' : 'city',
+            type: (isHotel ? 'hotel' : (it.type === 'place' ? 'place' : 'city')),
             name: i18nText(hotel.name) || i18nText(region.name) || '?',
             score: it.matchScore,
             latitude: hotelCoords.latitude ?? placeCoords.latitude ?? (typeof center.centerLat === 'number' ? center.centerLat : undefined),
             longitude: hotelCoords.longitude ?? placeCoords.longitude ?? (typeof center.centerLng === 'number' ? center.centerLng : undefined),
-            destinationId: hotel.destinationId !== undefined ? String(hotel.destinationId) : region.id !== undefined ? String(region.id) : undefined,
+            destinationId: hotel.destinationId !== undefined ? String(hotel.destinationId) : (region.id !== undefined ? String(region.id) : undefined),
             hotelId: hotel.id !== undefined ? String(hotel.id) : undefined,
-            star: typeof hotel.star === 'number' && hotel.star > 0 ? hotel.star : undefined
+            star: typeof hotel.star === 'number' && hotel.star > 0 ? hotel.star : undefined,
         };
     });
     const verdict = hits.length > 0 ? 'hit' : 'miss';
     return {
-        ok: true,
-        via: 'hbcli-anything',
+        ok: true, via: 'hbcli-anything',
         evidence: `[实时API:hbcli-anything@${ts}] ${hits.length}/${rawItems.length} candidates`,
         latencyMs,
         verdict,
         hits,
-        totalCandidates: rawItems.length
+        totalCandidates: rawItems.length,
     };
 }
-
-
-//# sourceURL=ts/capabilities/anything.ts