cortico 0.1.0

package/src/worlds/websearch/ENV_PROMPT.md

@@ -0,0 +1 @@
+

package/src/worlds/websearch/brave-client.ts

@@ -0,0 +1,261 @@
+/**
+ * BraveClient:Brave Search API的最小客户端(docs/Brave_Search_API.md)。
+ * 按 web_search 工具的 mode 分派到不同端点,统一映射成"带编号来源的证据"
+ * (title/url/snippet)。retry/timeout骨架:429/5xx/超时退避重试,其余错误直抛。
+ */
+import type { Logger } from '../../core/types.ts';
+import { nullLogger } from '../../core/util.ts';
+
+export type SearchMode = 'auto' | 'answer' | 'links' | 'news' | 'images' | 'videos';
+export type Freshness = 'any' | 'day' | 'week' | 'month' | 'year';
+type SafeSearch = 'off' | 'moderate' | 'strict';
+
+interface BraveResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+interface BraveSearchOptions {
+  mode: SearchMode;
+  fresh: Freshness;
+  /** 期望条数(1-6,由工具层校验范围) */
+  n: number;
+}
+
+interface BraveSearchOutcome {
+  /** 实际打的端点(answer遇OPTION_NOT_IN_PLAN会降级到web/search,这里如实标注) */
+  endpoint: string;
+  results: BraveResult[];
+}
+
+export interface BraveClientConfig {
+  apiKey: string;
+  country: string;
+  searchLang: string;
+  uiLang: string;
+  safesearch: SafeSearch;
+  timeoutMs: number;
+}
+
+export class BraveApiError extends Error {
+  status: number;
+  code?: string;
+  constructor(message: string, status: number, code?: string) {
+    super(message);
+    this.name = 'BraveApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+const BASE_URL = 'https://api.search.brave.com/res/v1';
+/** HTTP 429 的有限退避间隔。 */
+const RETRY_DELAYS_MS = [1000, 3000];
+
+const FRESH_MAP: Record<Freshness, string | undefined> = {
+  any: undefined,
+  day: 'pd',
+  week: 'pw',
+  month: 'pm',
+  year: 'py',
+};
+
+/** 去掉<strong>高亮标记、压缩空白、按长度截断(工具描述承诺"精简") */
+function cleanText(s: unknown, max = 220): string {
+  const t = (typeof s === 'string' ? s : '').replace(/<\/?strong>/g, '').replace(/\s+/g, ' ').trim();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+
+interface RawWebResult { title?: string; url?: string; description?: string }
+interface WebSearchResponse { web?: { results?: RawWebResult[] } }
+interface NewsSearchResponse { results?: RawWebResult[] }
+interface RawVideoResult extends RawWebResult { video?: { duration?: string; publisher?: string } }
+interface VideoSearchResponse { results?: RawVideoResult[] }
+interface RawImageResult { title?: string; url?: string; source?: string; properties?: { url?: string } }
+interface ImageSearchResponse { results?: RawImageResult[] }
+interface RawGrounding { url?: string; title?: string; snippets?: string[] }
+interface LlmContextResponse {
+  grounding?: { generic?: RawGrounding[] };
+  sources?: Record<string, { title?: string }>;
+}
+
+export class BraveClient {
+  private readonly cfg: BraveClientConfig;
+  private readonly log: Logger;
+
+  constructor(cfg: BraveClientConfig, log: Logger = nullLogger()) {
+    this.cfg = cfg;
+    this.log = log;
+  }
+
+  async search(q: string, opts: BraveSearchOptions): Promise<BraveSearchOutcome> {
+    const mode = opts.mode === 'auto' ? 'links' : opts.mode;
+    switch (mode) {
+      case 'answer':
+        try {
+          return { endpoint: 'llm/context', results: await this.llmContext(q, opts.n, opts.fresh) };
+        } catch (e) {
+          if (e instanceof BraveApiError && e.code === 'OPTION_NOT_IN_PLAN') {
+            this.log.warn('llm/context不在套餐内,降级web/search');
+            return {
+              endpoint: 'web/search (llm/context not in plan)',
+              results: await this.webSearch(q, opts.n, opts.fresh),
+            };
+          }
+          throw e;
+        }
+      case 'news':
+        return { endpoint: 'news/search', results: await this.newsSearch(q, opts.n, opts.fresh) };
+      case 'images':
+        return { endpoint: 'images/search', results: await this.imageSearch(q, opts.n) };
+      case 'videos':
+        return { endpoint: 'videos/search', results: await this.videoSearch(q, opts.n, opts.fresh) };
+      case 'links':
+      default:
+        return { endpoint: 'web/search', results: await this.webSearch(q, opts.n, opts.fresh) };
+    }
+  }
+
+
+  private async webSearch(q: string, n: number, fresh: Freshness): Promise<BraveResult[]> {
+    const p = this.commonParams(q, n, fresh);
+    p.set('text_decorations', 'false');
+    p.set('spellcheck', 'true');
+    const data = await this.get<WebSearchResponse>('web/search', p);
+    const items = data.web?.results ?? [];
+    return items.map((r) => ({ title: cleanText(r.title), url: String(r.url ?? ''), snippet: cleanText(r.description) }));
+  }
+
+  private async newsSearch(q: string, n: number, fresh: Freshness): Promise<BraveResult[]> {
+    const p = this.commonParams(q, n, fresh);
+    p.set('spellcheck', 'true');
+    const data = await this.get<NewsSearchResponse>('news/search', p);
+    const items = data.results ?? [];
+    return items.map((r) => ({ title: cleanText(r.title), url: String(r.url ?? ''), snippet: cleanText(r.description) }));
+  }
+
+  private async videoSearch(q: string, n: number, fresh: Freshness): Promise<BraveResult[]> {
+    const p = this.commonParams(q, n, fresh);
+    p.set('spellcheck', 'true');
+    const data = await this.get<VideoSearchResponse>('videos/search', p);
+    const items = data.results ?? [];
+    return items.map((r) => {
+      const extra = [r.video?.duration, r.video?.publisher].filter(Boolean).join(' · ');
+      const desc = cleanText(r.description);
+      return {
+        title: cleanText(r.title),
+        url: String(r.url ?? ''),
+        snippet: [desc, extra].filter(Boolean).join(' — '),
+      };
+    });
+  }
+
+  private async imageSearch(q: string, n: number): Promise<BraveResult[]> {
+    // Image Search 将 safesearch 归一为 off 或 strict，不发送 moderate。
+    const p = new URLSearchParams();
+    p.set('q', q);
+    p.set('country', this.cfg.country);
+    p.set('search_lang', this.cfg.searchLang);
+    p.set('count', String(n));
+    p.set('safesearch', this.cfg.safesearch === 'off' ? 'off' : 'strict');
+    p.set('spellcheck', 'true');
+    const data = await this.get<ImageSearchResponse>('images/search', p);
+    const items = data.results ?? [];
+    return items.map((r) => {
+      const snippet = [
+        r.source ? `source: ${r.source}` : '',
+        r.properties?.url ? `image: ${r.properties.url}` : '',
+      ].filter(Boolean).join(' · ');
+      return { title: cleanText(r.title), url: String(r.url ?? ''), snippet };
+    });
+  }
+
+  /** 为 LLM 提供 grounding 上下文，通过结果数、token 与 URL 上限约束响应规模。 */
+  private async llmContext(q: string, n: number, fresh: Freshness): Promise<BraveResult[]> {
+    const p = new URLSearchParams();
+    p.set('q', q);
+    p.set('country', this.cfg.country);
+    p.set('search_lang', this.cfg.searchLang);
+    p.set('count', '8');
+    p.set('maximum_number_of_urls', String(Math.min(Math.max(n, 1), 5)));
+    p.set('maximum_number_of_tokens', '2048');
+    p.set('context_threshold_mode', 'balanced');
+    const fr = FRESH_MAP[fresh];
+    if (fr) p.set('freshness', fr);
+    const data = await this.get<LlmContextResponse>('llm/context', p);
+    const generic = data.grounding?.generic ?? [];
+    const sources = data.sources ?? {};
+    return generic.slice(0, n).map((g) => {
+      const url = String(g.url ?? '');
+      const title = cleanText(g.title || sources[url]?.title || url, 120);
+      const snippet = cleanText((g.snippets ?? []).slice(0, 3).join(' … '), 260);
+      return { title, url, snippet };
+    });
+  }
+
+
+  private commonParams(q: string, n: number, fresh: Freshness): URLSearchParams {
+    const p = new URLSearchParams();
+    p.set('q', q);
+    p.set('country', this.cfg.country);
+    p.set('search_lang', this.cfg.searchLang);
+    p.set('ui_lang', this.cfg.uiLang);
+    p.set('count', String(n));
+    p.set('safesearch', this.cfg.safesearch);
+    const fr = FRESH_MAP[fresh];
+    if (fr) p.set('freshness', fr);
+    return p;
+  }
+
+  /** GET + 鉴权头 + 超时 + 429/5xx/超时退避重试;其余错误(含OPTION_NOT_IN_PLAN)直抛 */
+  private async get<T>(path: string, params: URLSearchParams): Promise<T> {
+    const url = `${BASE_URL}/${path}?${params.toString()}`;
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+      if (attempt > 0) {
+        const delay = RETRY_DELAYS_MS[attempt - 1];
+        this.log.warn(`Brave请求重试 #${attempt},等待${delay}ms`, { path, err: String(lastErr) });
+        await new Promise((r) => setTimeout(r, delay));
+      }
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), this.cfg.timeoutMs);
+      try {
+        const res = await fetch(url, {
+          headers: {
+            Accept: 'application/json',
+            'Accept-Encoding': 'gzip',
+            'X-Subscription-Token': this.cfg.apiKey,
+          },
+          signal: ac.signal,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+          let code: string | undefined;
+          try {
+            code = (JSON.parse(text) as { error?: { code?: string } })?.error?.code;
+          } catch {
+            /* 坏JSON body,code留空 */
+          }
+          const err = new BraveApiError(`Brave API ${res.status}${code ? ` (${code})` : ''}`, res.status, code);
+          if (res.status === 429 || res.status >= 500) {
+            lastErr = err;
+            continue;
+          }
+          throw err;
+        }
+        return JSON.parse(text) as T;
+      } catch (e) {
+        if (e instanceof BraveApiError && e.status !== 429 && e.status < 500) throw e;
+        // 网络错误/超时(AbortError)/可重试的BraveApiError
+        lastErr = e;
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    if (lastErr instanceof BraveApiError) throw lastErr;
+    throw new BraveApiError(`Brave请求失败(重试${RETRY_DELAYS_MS.length}次后放弃): ${String(lastErr)}`, 0);
+  }
+}

package/src/worlds/websearch/config.ts

@@ -0,0 +1,75 @@
+import type { ConfigGroup } from '../../core/types.ts';
+import type { BraveClientConfig } from './brave-client.ts';
+
+/** World 自有配置的默认值;启用状态由部署装配配置决定。 */
+export const WEBSEARCH_DEFAULTS = {
+  enabled: false,
+  /** 结果地区(ISO 2位);中文场景默认CN */
+  country: 'CN',
+  searchLang: 'zh-hans',
+  uiLang: 'zh-CN',
+  safesearch: 'moderate' as BraveClientConfig['safesearch'],
+  timeoutMs: 20000,
+} as const;
+
+/** 本 World 需要的密钥的环境变量名(core 不认识这个名字) */
+export const WEBSEARCH_SECRET = 'BRAVE_API_KEY';
+
+/** 本 World 声明的可调项:搜哪个地区、用什么语言、多久超时 */
+export const WEBSEARCH_CONFIG_GROUP: ConfigGroup = {
+  id: 'world:websearch',
+  owner: 'world:websearch',
+  schema: {
+    type: 'object',
+    title: 'WebSearch · 检索偏好',
+    description: 'Brave Search 的地区与语言;改完重启生效(客户端构造时固定)。',
+    properties: {
+      'worlds.websearch.country': {
+        type: 'string',
+        title: '结果地区',
+        'x-hot': false,
+        description: 'ISO 两位国家码,如 CN / US。',
+      },
+      'worlds.websearch.searchLang': {
+        type: 'string',
+        title: '搜索语言',
+        'x-hot': false,
+        description: '如 zh-hans。',
+      },
+      'worlds.websearch.uiLang': {
+        type: 'string',
+        title: '响应语言',
+        'x-hot': false,
+        description: '如 zh-CN。',
+      },
+      'worlds.websearch.safesearch': {
+        type: 'string',
+        title: '安全搜索',
+        enum: ['off', 'moderate', 'strict'],
+        'x-hot': false,
+        description: '过滤强度。',
+      },
+      'worlds.websearch.timeoutMs': {
+        type: 'integer',
+        title: '请求超时',
+        minimum: 1000,
+        maximum: 120_000,
+        multipleOf: 1000,
+        'x-scale': 1000,
+        'x-suffix': 's',
+        'x-hot': false,
+        description: '单次搜索请求的超时。',
+      },
+    },
+  },
+};
+
+/** config.json 的 `worlds.websearch` 节。全部在构造时读走,改完重启 World 生效。 */
+export interface WebSearchConfigSection {
+  enabled: boolean;
+  country: string;
+  searchLang: string;
+  uiLang: string;
+  safesearch: BraveClientConfig['safesearch'];
+  timeoutMs: number;
+}

package/src/worlds/websearch/definition.ts

@@ -0,0 +1,20 @@
+import type { WorldDefinition } from '../../world.ts';
+import type { BraveClientConfig } from './brave-client.ts';
+import { type WebSearchConfigSection, WEBSEARCH_DEFAULTS, WEBSEARCH_SECRET } from './config.ts';
+import { WebSearchWorld } from './world.ts';
+
+
+export const WEBSEARCH: WorldDefinition<WebSearchConfigSection> = {
+  id: 'websearch',
+  label: 'WebSearch',
+  defaults: () => ({ ...WEBSEARCH_DEFAULTS }),
+  create: (ctx) =>
+    new WebSearchWorld({
+      apiKey: ctx.secret(WEBSEARCH_SECRET),
+      country: ctx.cfg.country,
+      searchLang: ctx.cfg.searchLang,
+      uiLang: ctx.cfg.uiLang,
+      safesearch: ctx.cfg.safesearch,
+      timeoutMs: ctx.cfg.timeoutMs,
+    }),
+};

package/src/worlds/websearch/world.ts

@@ -0,0 +1,171 @@
+/**
+ * WebSearch 是仅提供请求/响应工具的 World。
+ * 它不提供环境提示词或事件;搜索结果不落事件库且不参与异步投递。
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { ConfigGroup, World, WorldHost, WorldConsoleDecl, ToolDef } from '../../core/types.ts';
+import {
+  BraveClient,
+  type BraveClientConfig,
+  type Freshness,
+  type SearchMode,
+} from './brave-client.ts';
+import { WEBSEARCH_DEFAULTS, WEBSEARCH_SECRET, WEBSEARCH_CONFIG_GROUP } from './config.ts';
+
+const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
+
+
+
+
+interface WebSearchWorldConfig {
+  /** Brave Search API key(装配层按 WEBSEARCH_SECRET 取给它);空串=工具存在但每次调用都提示未配置 */
+  apiKey: string;
+  country?: string;
+  searchLang?: string;
+  uiLang?: string;
+  safesearch?: BraveClientConfig['safesearch'];
+  timeoutMs?: number;
+}
+
+const MODES: SearchMode[] = ['auto', 'answer', 'links', 'news', 'images', 'videos'];
+const FRESHNESS: Freshness[] = ['any', 'day', 'week', 'month', 'year'];
+const N_MIN = 1;
+const N_MAX = 6;
+const N_DEFAULT = 4;
+const Q_MIN = 1;
+const Q_MAX = 240;
+
+/** 每次有结果都附上：外部平台有自己的内容规则，照搬检索结果可能导致账号被封 */
+const PLATFORM_RISK_WARNING =
+  '⚠ Before posting any of this into QQ or other external platforms: make sure it doesn\'t violate that platform\'s rules (illegal, explicit, violent, infringing, etc.) — sharing content that does can get the account banned. Paraphrase and use judgment.';
+
+export class WebSearchWorld implements World {
+  readonly id = 'websearch';
+
+  private readonly client: BraveClient | null;
+
+  constructor(cfg: WebSearchWorldConfig) {
+    this.client = cfg.apiKey
+      ? new BraveClient({
+          apiKey: cfg.apiKey,
+          country: cfg.country ?? 'CN',
+          searchLang: cfg.searchLang ?? 'zh-hans',
+          uiLang: cfg.uiLang ?? 'zh-CN',
+          safesearch: cfg.safesearch ?? 'moderate',
+          timeoutMs: cfg.timeoutMs ?? 20000,
+        })
+      : null;
+  }
+
+  /** 变量表为空；模板留空时，该 World 不进入前缀。 */
+  envPromptVars(): Record<string, string> {
+    return {};
+  }
+
+  /** 控制台里露出什么:密钥有没有配好 + 自己的检索偏好旋钮 */
+  console(): WorldConsoleDecl {
+    return {
+      // 一条链路:密钥。没配 = 灰(部署没填,不是运行出错);工具照旧在,调用会自己说明。
+      lamps: [this.client
+        ? { label: '密钥', state: 'online' as const, hint: '已配置' }
+        : { label: '密钥', state: 'offline' as const, hint: '未配置' }],
+      badges: [
+        this.client
+          ? { label: '密钥', value: '已配置', tone: 'on' as const }
+          : { label: '密钥', value: '未配置(工具仍在,调用会提示)', tone: 'off' as const },
+      ],
+      config: [WEBSEARCH_CONFIG_GROUP],
+      promptDocs: [
+        {
+          key: 'worlds.websearch.envPrompt',
+          title: 'WebSearch · 环境提示词',
+          description: '搜索工具 World 的可选常驻环境;留空时不进入系统前缀。',
+          path: ENV_PROMPT_FILE,
+          role: 'envPrompt',
+        },
+      ],
+    };
+  }
+
+  async start(_host: WorldHost): Promise<void> {
+  }
+
+  async stop(): Promise<void> {
+  }
+
+  tools(): ToolDef[] {
+    return [this.webSearchTool()];
+  }
+
+  private webSearchTool(): ToolDef {
+    return {
+      name: 'web_search',
+      description:
+        'Search the public internet for recent or uncertain information. Returns concise, numbered evidence with sources. Default to calling it once.',
+      tags: ['read'],
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          q: {
+            type: 'string',
+            minLength: Q_MIN,
+            maxLength: Q_MAX,
+            description:
+              'Focused search query. Keep key names, dates and platforms; do not paste whole chat logs or private info.',
+          },
+          mode: {
+            type: 'string',
+            enum: MODES,
+            default: 'auto',
+            description:
+              '"answer" for evidence to answer a question; "links" for web pages; others search that content type.',
+          },
+          fresh: {
+            type: 'string',
+            enum: FRESHNESS,
+            default: 'any',
+          },
+          n: {
+            type: 'integer',
+            minimum: N_MIN,
+            maximum: N_MAX,
+            default: N_DEFAULT,
+          },
+        },
+        required: ['q'],
+      },
+      handler: async (args) => {
+        const client = this.client;
+        if (!client) return '[tool failed] web search is not configured (missing BRAVE_API_KEY)';
+
+        const q = typeof args.q === 'string' ? args.q.trim() : '';
+        if (q.length < Q_MIN) return '[bad input] q must not be empty';
+
+        const mode: SearchMode = MODES.includes(args.mode as SearchMode) ? (args.mode as SearchMode) : 'auto';
+        const fresh: Freshness = FRESHNESS.includes(args.fresh as Freshness) ? (args.fresh as Freshness) : 'any';
+        const n =
+          args.n !== undefined && args.n !== null
+            ? Math.min(N_MAX, Math.max(N_MIN, Math.trunc(Number(args.n)) || N_DEFAULT))
+            : N_DEFAULT;
+
+        try {
+          const { endpoint, results } = await client.search(q.slice(0, Q_MAX), { mode, fresh, n });
+          if (results.length === 0) return `(no results for "${q}")`;
+
+          const lines = [`web_search: "${q}" · ${endpoint} · ${results.length} result(s)`, ''];
+          results.forEach((r, i) => {
+            lines.push(`${i + 1}. ${r.title || '(untitled)'}`, `   ${r.url}`);
+            if (r.snippet) lines.push(`   ${r.snippet}`);
+            lines.push('');
+          });
+          lines.push(PLATFORM_RISK_WARNING);
+          return lines.join('\n').trimEnd();
+        } catch (e) {
+          return `[search failed] ${e instanceof Error ? e.message : String(e)}`;
+        }
+      },
+    };
+  }
+}