@geekbeer/minion 3.52.0 → 3.53.1

package/core/lib/web-extract/recipe-generator.js

@@ -0,0 +1,247 @@
+/**
+ * Cold-path recipe generator.
+ *
+ * Resolution order (first available wins):
+ *   1. Primary LLM plugin (PUT /api/llm/config) — uses claude / gemini / codex
+ *      CLI subprocess via the same plugin contract that runQuickLlmCall does.
+ *      Prompt asks for plain JSON; we extract+parse it.
+ *   2. ANTHROPIC_API_KEY env var — direct Anthropic Messages API with
+ *      tool_use schema enforcement (same fetch pattern as
+ *      core/lib/revision-watcher.js).
+ *   3. Otherwise: throw LLM_UNAVAILABLE so the route layer can surface a 503.
+ *
+ * The model only ever sees cleaned Markdown — never the raw HTML — and only
+ * runs on cold-cache misses, so the cost is bounded.
+ *
+ * Returns:
+ *   {
+ *     pageType: 'article' | 'listing' | 'product' | 'profile' | 'form' | 'other',
+ *     selectors: { fieldName: { selector, attr?, multiple? }, ... },
+ *     extracted: { fieldName: <value already pulled from this page> }
+ *   }
+ */
+
+const { getActivePrimary } = require('../../llm-plugins/lib/active')
+
+const ANTHROPIC_MODEL = 'claude-haiku-4-5-20251001'
+const MAX_TOKENS = 2048
+const PLUGIN_TIMEOUT_MS = 60_000
+
+const TOOL_DESCRIPTION =
+  'Classify the page and propose CSS selectors for the most useful fields. ' +
+  'Also produce the extracted values directly so the caller can verify the recipe.'
+
+const ANTHROPIC_TOOLS = [{
+  name: 'page_extraction',
+  description: TOOL_DESCRIPTION,
+  input_schema: {
+    type: 'object',
+    required: ['page_type', 'selectors', 'extracted'],
+    properties: {
+      page_type: {
+        type: 'string',
+        enum: ['article', 'listing', 'product', 'profile', 'form', 'other'],
+        description: 'High-level classification of the page.',
+      },
+      selectors: {
+        type: 'object',
+        description:
+          'Map of fieldName -> { selector, attr?, multiple? }. Use plain CSS selectors. ' +
+          'attr defaults to "text" (innerText); use "html" or an HTML attribute name to override. ' +
+          'Set multiple=true for list fields. Aim for 3-8 fields covering the page\'s primary content.',
+        additionalProperties: {
+          type: 'object',
+          required: ['selector'],
+          properties: {
+            selector: { type: 'string' },
+            attr: { type: 'string' },
+            multiple: { type: 'boolean' },
+          },
+        },
+      },
+      extracted: {
+        type: 'object',
+        description:
+          'Values extracted from this specific page using the selectors above. ' +
+          'Strings or arrays of strings.',
+      },
+    },
+  },
+}]
+
+const SYSTEM_PROMPT = `You design CSS selector recipes for extracting structured content from web pages.
+
+Given a cleaned Markdown rendering of one page, you must:
+1. Classify the page (article / listing / product / profile / form / other).
+2. Propose 3-8 CSS selectors that capture the page's primary information.
+   - Prefer semantic selectors (article, h1, time[datetime], a[rel="author"]) over class names where possible.
+   - Use class-based selectors only when semantic ones are unavailable.
+   - Avoid fragile attribute selectors like data-react-* or auto-generated hashes.
+3. Fill the "extracted" object with the values pulled from this exact page so the caller can verify your recipe works.
+
+The same recipe will be reused for structurally similar pages, so think about what generalizes.`
+
+async function generateRecipe({ url, cleanedMarkdown, hint }) {
+  const primary = getActivePrimary()
+  if (primary) {
+    return await generateViaPlugin(primary, { url, cleanedMarkdown, hint })
+  }
+  if (process.env.ANTHROPIC_API_KEY) {
+    return await generateViaAnthropicDirect({ url, cleanedMarkdown, hint })
+  }
+  const e = new Error(
+    'No LLM available for cold-path recipe generation. Configure a primary LLM via ' +
+    'PUT /api/llm/config (recommended) or set ANTHROPIC_API_KEY as a fallback.'
+  )
+  e.code = 'LLM_UNAVAILABLE'
+  throw e
+}
+
+async function generateViaPlugin(plugin, { url, cleanedMarkdown, hint }) {
+  const prompt = buildTextPrompt({ url, cleanedMarkdown, hint })
+  const input = {
+    prompt,
+    timeoutMs: PLUGIN_TIMEOUT_MS,
+  }
+  // Claude Code CLI accepts model aliases like 'haiku'. Other plugins ignore this.
+  if (plugin.name === 'claude') input.model = 'haiku'
+
+  let output
+  try {
+    output = await plugin.invoke(input)
+  } catch (err) {
+    const e = new Error(`Primary LLM (${plugin.name}) invoke failed: ${err.message}`)
+    e.code = 'PRIMARY_LLM_FAILED'
+    throw e
+  }
+  if (output.error) {
+    const e = new Error(`Primary LLM (${plugin.name}) returned error: ${output.error.message}`)
+    e.code = 'PRIMARY_LLM_FAILED'
+    throw e
+  }
+
+  const json = extractJson(output.text || '')
+  if (!json) {
+    const e = new Error(
+      `Primary LLM (${plugin.name}) did not return parseable JSON. ` +
+      `Raw output (first 500 chars): ${(output.text || '').slice(0, 500)}`
+    )
+    e.code = 'PRIMARY_LLM_BAD_JSON'
+    throw e
+  }
+  return {
+    pageType: json.page_type || 'other',
+    selectors: json.selectors || {},
+    extracted: json.extracted || {},
+    source: `primary:${plugin.name}`,
+  }
+}
+
+async function generateViaAnthropicDirect({ url, cleanedMarkdown, hint }) {
+  const apiKey = process.env.ANTHROPIC_API_KEY
+  const userParts = [
+    `URL: ${url}`,
+    hint ? `Caller hint: ${hint}` : null,
+    '',
+    '--- Cleaned Markdown (Readability output) ---',
+    cleanedMarkdown || '(empty)',
+  ].filter(Boolean).join('\n')
+
+  const resp = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: ANTHROPIC_MODEL,
+      max_tokens: MAX_TOKENS,
+      system: SYSTEM_PROMPT,
+      tools: ANTHROPIC_TOOLS,
+      tool_choice: { type: 'tool', name: 'page_extraction' },
+      messages: [{ role: 'user', content: userParts }],
+    }),
+  })
+
+  if (!resp.ok) {
+    const text = await resp.text()
+    throw new Error(`Anthropic API error: ${resp.status} ${text}`)
+  }
+
+  const data = await resp.json()
+  const toolUse = (data.content || []).find(block => block.type === 'tool_use' && block.name === 'page_extraction')
+  if (!toolUse || !toolUse.input) {
+    throw new Error('Anthropic API returned no tool_use block for page_extraction')
+  }
+
+  const { page_type, selectors, extracted } = toolUse.input
+  return {
+    pageType: page_type || 'other',
+    selectors: selectors || {},
+    extracted: extracted || {},
+    source: 'anthropic-direct',
+  }
+}
+
+function buildTextPrompt({ url, cleanedMarkdown, hint }) {
+  return [
+    SYSTEM_PROMPT,
+    '',
+    `URL: ${url}`,
+    hint ? `Caller hint: ${hint}` : null,
+    '',
+    'Output ONLY a JSON object — no prose, no explanations, no code fences.',
+    'The JSON must have exactly this shape:',
+    '',
+    '{',
+    '  "page_type": "article" | "listing" | "product" | "profile" | "form" | "other",',
+    '  "selectors": {',
+    '    "<fieldName>": { "selector": "<css>", "attr"?: "<text|html|attribute-name>", "multiple"?: <boolean> }',
+    '  },',
+    '  "extracted": { "<fieldName>": "<string or array of strings>" }',
+    '}',
+    '',
+    'Notes:',
+    '- attr defaults to "text" (innerText). Use "html" or an HTML attribute name to override.',
+    '- Set multiple=true for list fields (returns array).',
+    '- "extracted" must contain the values you actually read from THIS page using those selectors.',
+    '',
+    '--- Cleaned Markdown ---',
+    cleanedMarkdown || '(empty)',
+  ].filter(s => s !== null).join('\n')
+}
+
+/**
+ * Extract a JSON object from arbitrary LLM text. Handles three common shapes:
+ *   1. Raw JSON
+ *   2. Fenced code block (```json ... ``` or ``` ... ```)
+ *   3. Prose with embedded {...} — uses the outermost braces
+ */
+function extractJson(text) {
+  if (!text || typeof text !== 'string') return null
+  const trimmed = text.trim()
+  if (!trimmed) return null
+
+  try { return JSON.parse(trimmed) } catch {}
+
+  const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/)
+  if (fence && fence[1]) {
+    try { return JSON.parse(fence[1].trim()) } catch {}
+  }
+
+  const first = trimmed.indexOf('{')
+  const last = trimmed.lastIndexOf('}')
+  if (first >= 0 && last > first) {
+    try { return JSON.parse(trimmed.slice(first, last + 1)) } catch {}
+  }
+
+  return null
+}
+
+module.exports = {
+  generateRecipe,
+  ANTHROPIC_MODEL,
+  // exported for tests
+  extractJson,
+}

package/core/lib/web-extract/url-normalize.js

@@ -0,0 +1,90 @@
+/**
+ * URL normalization for the page recipe cache.
+ *
+ * Two URLs that resolve to the same template + the same DOM fingerprint are
+ * treated as structurally identical and share an extraction recipe. The
+ * template captures the path/query *shape* (with IDs / slugs / pagination
+ * placeholdered out) so the cache hits across e.g.
+ *   /work/proposal/123456?utm_source=foo
+ *   /work/proposal/789012?utm_source=bar&fbclid=...
+ * Tracking params are stripped, remaining query keys are sorted, and known
+ * pagination params keep their key but lose their value.
+ */
+
+const STRIP_QUERY_PARAMS = new Set([
+  'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
+  'fbclid', 'gclid', 'mc_cid', 'mc_eid', 'ref', 'referrer',
+])
+
+const PAGINATION_QUERY_PARAMS = new Set([
+  'page', 'p', 'pagenumber', 'pagenum', 'offset', 'start',
+])
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const HEX32_RE = /^[0-9a-f]{32}$/i
+const ALL_DIGITS_RE = /^\d+$/
+const LONG_ALNUM_RE = /^(?=.*\d)(?=.*[a-zA-Z])[A-Za-z0-9]{20,}$/
+
+function placeholderForSegment(segment) {
+  if (!segment) return segment
+  if (ALL_DIGITS_RE.test(segment)) return ':id'
+  if (UUID_RE.test(segment) || HEX32_RE.test(segment)) return ':uuid'
+  if (LONG_ALNUM_RE.test(segment)) return ':slug'
+  return segment
+}
+
+function normalizeUrl(rawUrl) {
+  let parsed
+  try {
+    parsed = new URL(rawUrl)
+  } catch (err) {
+    throw new Error(`Invalid URL: ${rawUrl}`)
+  }
+
+  // Lowercase host (case-insensitive per RFC 3986)
+  const host = parsed.host.toLowerCase()
+
+  // Path: keep separators, placeholder each segment.
+  const pathSegments = parsed.pathname.split('/').map(seg => seg ? placeholderForSegment(seg) : seg)
+  const templatePath = pathSegments.join('/')
+
+  // Query: filter, sort, and placeholder pagination values.
+  const queryEntries = []
+  for (const [key, value] of parsed.searchParams.entries()) {
+    const lowerKey = key.toLowerCase()
+    if (STRIP_QUERY_PARAMS.has(lowerKey)) continue
+    if (PAGINATION_QUERY_PARAMS.has(lowerKey)) {
+      queryEntries.push([key, ':n'])
+    } else {
+      queryEntries.push([key, value])
+    }
+  }
+  queryEntries.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)
+
+  const templateQuery = queryEntries.length
+    ? '?' + queryEntries.map(([k, v]) => `${k}=${v}`).join('&')
+    : ''
+
+  const template = `${host}${templatePath}${templateQuery}`
+
+  // Canonical URL: original protocol + host + path, query reduced to non-tracking params
+  // (keeping their *real* values so the actual fetch stays correct).
+  const canonical = new URL(parsed.toString())
+  for (const param of [...canonical.searchParams.keys()]) {
+    if (STRIP_QUERY_PARAMS.has(param.toLowerCase())) {
+      canonical.searchParams.delete(param)
+    }
+  }
+  canonical.hash = ''
+
+  return {
+    template,
+    canonicalUrl: canonical.toString(),
+  }
+}
+
+module.exports = {
+  normalizeUrl,
+  STRIP_QUERY_PARAMS,
+  PAGINATION_QUERY_PARAMS,
+}

package/core/routes/web.js

@@ -0,0 +1,94 @@
+/**
+ * Web Page Extraction (experimental — v3.53.0)
+ *
+ * Endpoints:
+ *   POST /api/web/extract       - Fetch a URL and return structured JSON
+ *   GET  /api/web/recipes       - List cached recipes (debug)
+ *   DELETE /api/web/recipes/:template/:fingerprint - Drop a recipe
+ *
+ * The extract endpoint runs Playwright + Readability + an Anthropic Haiku
+ * recipe-generation step in this minion process, returning only structured
+ * JSON to the caller. Designed to keep large DOM payloads off the main
+ * Claude Code chat session that issued the request.
+ *
+ * Marked experimental: response shape may change.
+ */
+
+const { verifyToken } = require('../lib/auth')
+const { extract } = require('../lib/web-extract')
+const pageRecipeStore = require('../stores/page-recipe-store')
+
+const REQUEST_TIMEOUT_MS = 60_000
+
+async function webRoutes(fastify) {
+  fastify.post('/api/web/extract', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const body = request.body || {}
+    const { url, hint } = body
+
+    if (!url || typeof url !== 'string') {
+      reply.code(400)
+      return { success: false, error: 'url (string) is required' }
+    }
+    try {
+      new URL(url)
+    } catch {
+      reply.code(400)
+      return { success: false, error: 'url is not a valid URL' }
+    }
+
+    try {
+      const result = await Promise.race([
+        extract({ url, hint: typeof hint === 'string' ? hint : null }),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('extract timeout')), REQUEST_TIMEOUT_MS)),
+      ])
+      return { success: true, ...result }
+    } catch (err) {
+      if (
+        err.code === 'PLAYWRIGHT_UNAVAILABLE' ||
+        err.code === 'LLM_UNAVAILABLE' ||
+        err.code === 'ANTHROPIC_KEY_MISSING'
+      ) {
+        reply.code(503)
+        return { success: false, error: err.message, code: err.code }
+      }
+      if (err.code === 'PRIMARY_LLM_FAILED' || err.code === 'PRIMARY_LLM_BAD_JSON') {
+        reply.code(502)
+        return { success: false, error: err.message, code: err.code }
+      }
+      request.log.error({ err }, '[web/extract] failed')
+      reply.code(500)
+      return { success: false, error: err.message || String(err) }
+    }
+  })
+
+  // Debug helpers — list / delete cached recipes.
+  fastify.get('/api/web/recipes', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+    const recipes = pageRecipeStore.listAll({ limit: 200 })
+    return { success: true, experimental: true, recipes }
+  })
+
+  fastify.delete('/api/web/recipes', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+    const { template, fingerprint } = request.query || {}
+    if (!template || !fingerprint) {
+      reply.code(400)
+      return { success: false, error: 'template and fingerprint query params are required' }
+    }
+    const removed = pageRecipeStore.remove({ urlTemplate: template, domFingerprint: fingerprint })
+    return { success: true, removed }
+  })
+}
+
+module.exports = { webRoutes }

package/core/stores/page-recipe-store.js

@@ -0,0 +1,143 @@
+/**
+ * Page Recipe Store (SQLite, experimental — v3.53.0)
+ *
+ * Backs POST /api/web/extract. See core/lib/web-extract/extractor.js for the
+ * orchestrator that decides hot vs cold paths.
+ */
+
+const { getDb } = require('../db')
+
+const MAX_FAIL_COUNT = 3
+
+function find({ urlTemplate, domFingerprint }) {
+  const db = getDb()
+  const row = db.prepare(`
+    SELECT url_template, dom_fingerprint, selectors_json, page_type,
+           hit_count, fail_count, last_verified_at, created_at
+    FROM page_recipes
+    WHERE url_template = ? AND dom_fingerprint = ?
+  `).get(urlTemplate, domFingerprint)
+  if (!row) return null
+  return parseRow(row)
+}
+
+function findByTemplate(urlTemplate) {
+  const db = getDb()
+  const rows = db.prepare(`
+    SELECT url_template, dom_fingerprint, selectors_json, page_type,
+           hit_count, fail_count, last_verified_at, created_at
+    FROM page_recipes
+    WHERE url_template = ?
+    ORDER BY last_verified_at DESC NULLS LAST, created_at DESC
+  `).all(urlTemplate)
+  return rows.map(parseRow)
+}
+
+function upsert({ urlTemplate, domFingerprint, selectors, pageType }) {
+  const db = getDb()
+  const json = JSON.stringify(selectors || {})
+  const now = new Date().toISOString()
+  db.prepare(`
+    INSERT INTO page_recipes (url_template, dom_fingerprint, selectors_json, page_type, hit_count, fail_count, last_verified_at, created_at)
+    VALUES (?, ?, ?, ?, 0, 0, ?, ?)
+    ON CONFLICT(url_template, dom_fingerprint) DO UPDATE SET
+      selectors_json = excluded.selectors_json,
+      page_type = excluded.page_type,
+      fail_count = 0,
+      last_verified_at = excluded.last_verified_at
+  `).run(urlTemplate, domFingerprint, json, pageType || null, now, now)
+  return find({ urlTemplate, domFingerprint })
+}
+
+function incrementHit({ urlTemplate, domFingerprint }) {
+  const db = getDb()
+  db.prepare(`
+    UPDATE page_recipes
+    SET hit_count = hit_count + 1
+    WHERE url_template = ? AND dom_fingerprint = ?
+  `).run(urlTemplate, domFingerprint)
+}
+
+function setLastVerified({ urlTemplate, domFingerprint }) {
+  const db = getDb()
+  db.prepare(`
+    UPDATE page_recipes
+    SET last_verified_at = ?, fail_count = 0
+    WHERE url_template = ? AND dom_fingerprint = ?
+  `).run(new Date().toISOString(), urlTemplate, domFingerprint)
+}
+
+/**
+ * Increment fail count. Returns true if the recipe was deleted (>= MAX_FAIL_COUNT).
+ */
+function incrementFail({ urlTemplate, domFingerprint }) {
+  const db = getDb()
+  const row = db.prepare(`
+    SELECT fail_count FROM page_recipes
+    WHERE url_template = ? AND dom_fingerprint = ?
+  `).get(urlTemplate, domFingerprint)
+  if (!row) return false
+  const next = (row.fail_count || 0) + 1
+  if (next >= MAX_FAIL_COUNT) {
+    remove({ urlTemplate, domFingerprint })
+    return true
+  }
+  db.prepare(`
+    UPDATE page_recipes
+    SET fail_count = ?
+    WHERE url_template = ? AND dom_fingerprint = ?
+  `).run(next, urlTemplate, domFingerprint)
+  return false
+}
+
+function remove({ urlTemplate, domFingerprint }) {
+  const db = getDb()
+  const result = db.prepare(`
+    DELETE FROM page_recipes
+    WHERE url_template = ? AND dom_fingerprint = ?
+  `).run(urlTemplate, domFingerprint)
+  return result.changes > 0
+}
+
+function listAll({ limit = 100 } = {}) {
+  const db = getDb()
+  const rows = db.prepare(`
+    SELECT url_template, dom_fingerprint, selectors_json, page_type,
+           hit_count, fail_count, last_verified_at, created_at
+    FROM page_recipes
+    ORDER BY last_verified_at DESC NULLS LAST, created_at DESC
+    LIMIT ?
+  `).all(limit)
+  return rows.map(parseRow)
+}
+
+function parseRow(row) {
+  let selectors = {}
+  try {
+    selectors = JSON.parse(row.selectors_json || '{}')
+  } catch {
+    selectors = {}
+  }
+  return {
+    url_template: row.url_template,
+    dom_fingerprint: row.dom_fingerprint,
+    selectors,
+    page_type: row.page_type,
+    hit_count: row.hit_count,
+    fail_count: row.fail_count,
+    last_verified_at: row.last_verified_at,
+    created_at: row.created_at,
+  }
+}
+
+module.exports = {
+  find,
+  findByTemplate,
+  upsert,
+  incrementHit,
+  incrementFail,
+  setLastVerified,
+  remove,
+  listAll,
+  MAX_FAIL_COUNT,
+}

package/docs/api-reference.md

@@ -696,6 +696,72 @@ PUT `/api/email/inbox/:id` body:
 
 Note: 既読メールは受信後90日で自動削除される。未読メールは保持される。
 
+### Web Page Extraction 🧪 (experimental, v3.53.0〜)
+
+Web ページの読み取り・要約・情報抽出をミニオン内のサブプロセスで完結させ、メインの Claude Code セッションには結果 JSON だけを返すための実験的 API。Playwright MCP で DOM 全体がチャットに流れ込みトークン肥大化を起こす問題への対処として導入。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/web/extract` | URL を抽出済み JSON に変換 (タイトル・本文・主要構造化データ) |
+| GET  | `/api/web/recipes` | キャッシュされたレシピ一覧 (debug) |
+| DELETE | `/api/web/recipes?template=...&fingerprint=...` | レシピを削除 |
+
+**前提条件 (LLM の解決順):**
+1. **primary LLM プラグインが設定されていればそれを使用** (推奨)。`PUT /api/llm/config` で `claude` 等を primary に指定すると、CLI の認証情報 (`~/.claude/.credentials.json`) がそのまま使われる。API キーの別途設定は不要。
+2. primary 未設定で `ANTHROPIC_API_KEY` シークレットが設定されていれば、そちらを fallback として使用 (Anthropic Messages API の tool_use で JSON Schema を強制)。
+3. どちらもなければ 503 (`LLM_UNAVAILABLE`) を返す。
+
+その他の前提:
+- ホスト上で `npx playwright install chromium` を実行済みであること (未実行の場合 503 が返る)
+
+**`POST /api/web/extract` リクエスト:**
+```json
+{
+  "url": "https://example.com/article/123",
+  "hint": "本文と著者を抽出してほしい (任意, 抽出フィールドのヒント)"
+}
+```
+
+**レスポンス (success):**
+```json
+{
+  "success": true,
+  "experimental": true,
+  "url": "https://example.com/article/123",
+  "finalUrl": "https://example.com/article/123",
+  "statusCode": 200,
+  "recipeMode": "cold",
+  "recipeId": "example.com/article/:id#abc123def456",
+  "pageType": "article",
+  "title": "...",
+  "content": "Markdown 本文...",
+  "structured": { "title": "...", "author": "...", "publishedAt": "..." },
+  "selectors": { "title": { "selector": "h1" }, "author": { "selector": "a[rel=author]" } }
+}
+```
+
+**動作:**
+- 初回アクセス (cold): Playwright でレンダリング → Readability で本文抽出 → Anthropic Haiku でセレクタ生成 → SQLite (`page_recipes`) に保存 → セレクタで再抽出して返却
+- 2回目以降 (hot): URL 正規化・テンプレート化 → DOM フィンガープリントで保存済みレシピを照合 → セレクタで抽出のみ (LLM 呼び出しなし)
+- セルフヒール: hot 実行で空結果が返ったら `fail_count++`、3回失敗で破棄して次回 cold 再生成
+
+**URL 正規化ルール:**
+- `utm_*` `fbclid` `gclid` `ref` 等のトラッキングクエリは除去
+- `page` `p` `offset` 等のページネーション値は `:n` プレースホルダ化
+- パスセグメントは数値→`:id`、UUID→`:uuid`、20文字以上の英数字→`:slug` に置換
+- 例: `https://www.lancers.jp/work/proposal/123456?utm_source=foo&page=2` → `lancers.jp/work/proposal/:id?page=:n`
+
+**エラー:**
+- 401: APIトークン不正
+- 400: URL 欠落・不正
+- 502: primary LLM 呼び出し失敗 (`PRIMARY_LLM_FAILED`) / 返却 JSON が parse 不能 (`PRIMARY_LLM_BAD_JSON`)
+- 503: Playwright 未インストール (`PLAYWRIGHT_UNAVAILABLE`) / LLM 未設定 (`LLM_UNAVAILABLE`)
+- 500: 抽出失敗 (タイムアウト等)
+
+**注意 (experimental):**
+- レスポンス形状・URL 正規化ルール・キャッシュスキーマは予告なく変更される可能性がある
+- 認証付きページ (ログイン必須) は対応外。Cookie や対話的操作が必要な場合は Playwright MCP を使用すること
+
 ### Commands
 
 | Method | Endpoint | Description |