shadowzzh

tools.ts

tools.ts
// MCP 工具定義:每個工具 = 一段對 admin REST 端點的封裝。
// inputSchema 用原始 JSON Schema(不綁 zod,避免 SDK 內建 zod 與 repo zod 版本摩擦)。
import type { ApiClient } from './api.js';
import { BLOCKS, renderBlocksForGuide } from './blocks.js';
import { validateContent } from './validate.js';

export interface Tool {
  name: string;
  description: string;
  inputSchema: {
    type: 'object';
    properties?: Record<string, unknown>;
    required?: string[];
    additionalProperties?: boolean;
  };
  handler: (args: Record<string, unknown>) => Promise<unknown>;
}

const EMPTY = { type: 'object' as const, properties: {}, additionalProperties: false };

/** 從 args 挑出有值的鍵組成 body(省略 undefined/null,''/false/0 保留)。 */
function pick(args: Record<string, unknown>, keys: string[]): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const k of keys) {
    if (args[k] !== undefined && args[k] !== null) out[k] = args[k];
  }
  return out;
}

/**
 * 從 args 取出要插進網址的 id。
 *
 * 原本直接寫 `${idOf(a)}`:args 的型別是 unknown,漏傳 id 時會安靜地打到 `/api/admin/posts/undefined`,
 * 後端回的 404 讀起來像「文章不存在」而不是「呼叫少了參數」。
 */
function idOf(args: Record<string, unknown>): string {
  const { id } = args;
  if (typeof id === 'number' || (typeof id === 'string' && id !== '')) return encodeURIComponent(String(id));
  throw new Error('缺少 id(必須是數字或非空字串)');
}

// i18n 欄位(4 語 × 3 欄)。zh-TW 是來源(存在 title/content/excerpt),這裡是譯文欄。
const I18N_FIELDS = [
  'title_en',
  'content_en',
  'excerpt_en',
  'title_ja',
  'content_ja',
  'excerpt_ja',
  'title_ko',
  'content_ko',
  'excerpt_ko',
  'title_zh_cn',
  'content_zh_cn',
  'excerpt_zh_cn',
] as const;

const POST_WRITE_FIELDS = [
  'title',
  'content',
  'excerpt',
  'category',
  'status',
  'format',
  'layout_type',
  'tags',
  'series_name',
  'series_order',
  'allow_comments',
  'send_newsletter',
  'source_language',
  'slug',
  'excerpt_links',
  ...I18N_FIELDS,
] as const;

const postWriteProps = {
  title: { type: 'string', description: '標題' },
  content: { type: 'string', description: '內文(Markdown)' },
  excerpt: { type: 'string', description: '摘要;省略=NULL' },
  excerpt_links: {
    type: 'object',
    description:
      '摘要裡連到章節的句子,依語系分開:{"zh-TW": [{"text": "正確率只有 38%", "to": "05.4"}], "en": [...]}。' +
      'text 要逐字出現在該語系的摘要裡(找不到的不會顯示);to 是章節編號:第幾個 ## 寫兩位數(05),' +
      '它底下第幾個 ### 再接 .N(05.4)。更新時只換有帶到的語系,帶 [] 刪掉那個語系、整個帶 null 全清。' +
      '簡體那組由 generate_post_zh_cn 從繁體自動轉出來,不必手填。',
    additionalProperties: {
      type: 'array',
      items: {
        type: 'object',
        properties: { text: { type: 'string' }, to: { type: 'string', pattern: '^\\d{2}(\\.\\d{1,2})?$' } },
        required: ['text', 'to'],
      },
    },
  },
  category: { type: 'string', description: '分類名(需已存在於 categories)' },
  status: {
    type: 'string',
    enum: ['draft', 'published', 'scheduled'],
    description: '狀態;建立時預設 draft。scheduled 要一起給 publish_at',
  },
  publish_at: {
    type: 'string',
    description:
      'status=scheduled 時的發佈時間,要在未來。帶時區的 ISO 8601(如 2026-10-28T09:00:00+08:00);不帶時區的當成 UTC',
  },
  format: {
    type: 'string',
    enum: ['markdown', 'mdx'],
    description:
      "內容格式。用到自訂 block(<Note>/<Annot>/<Spoiler>/<BarChart>)或行內 JS {…} → 'mdx';純文字/markdown → 'markdown'(預設)。用 mdx 前務必先讀 koimsurai_authoring_guide(有 <、{ 的跳脫規則)。",
  },
  slug: {
    type: 'string',
    description:
      "網址用的**英文** slug(例 'blog-post-rendering-strategy')。省略時後端會自動從 title_en(沒有就 title)產生。" +
      '文章網址是 /blog/<slug>,所以請給精簡好讀的英文短語(3~8 個詞、全小寫、連字號分隔)。' +
      '⚠ 之後改 slug 沒關係——舊網址會自動 301 到新的,不會斷。',
  },
  layout_type: { type: 'string', description: "版面型別,預設 'record'" },
  tags: { type: 'array', items: { type: 'string' }, description: '標籤名陣列(不存在的會自動建立)' },
  series_name: { type: 'string', description: '系列名(可選)' },
  series_order: { type: 'number', description: '系列內排序(可選)' },
  allow_comments: { type: 'boolean', description: '是否開放留言,預設 true' },
  send_newsletter: {
    type: 'boolean',
    description: '⚠️ 若同時 status=published,會寄電子報給所有訂閱者——請先確認再設 true',
  },
  source_language: {
    type: 'string',
    enum: ['zh-TW', 'zh-CN', 'en', 'ja', 'ko'],
    description: "來源語言(title/content 用哪一語寫的),預設 'zh-TW'。其餘語言放 *_en/*_ja/*_ko/*_zh_cn 欄。",
  },
  ...i18nProps(),
};

/** 4 語 × 3 欄的 i18n 屬性。zh-TW 是來源(存 title/content/excerpt);這裡放各譯文語言。 */
function i18nProps(): Record<string, { type: 'string'; description: string }> {
  const langLabel: Record<string, string> = { en: '英文', ja: '日文', ko: '韓文', zh_cn: '簡體中文' };
  const fieldLabel: Record<string, string> = { title: '標題', content: '內文', excerpt: '摘要' };
  const out: Record<string, { type: 'string'; description: string }> = {};
  for (const lang of ['en', 'ja', 'ko', 'zh_cn'] as const) {
    for (const field of ['title', 'content', 'excerpt'] as const) {
      const zhcnNote = lang === 'zh_cn' ? ';簡體通常改用 generate_post_zh_cn 自動轉,不必手填' : '';
      out[`${field}_${lang}`] = {
        type: 'string',
        description: `${langLabel[lang]}${fieldLabel[field]}(譯文,可選)${zhcnNote}`,
      };
    }
  }
  return out;
}

// 完整撰寫指南——寫一篇文章前先讀。目標:Agent 一次產出結構完整、格式正確、可直接發布的文章。
const AUTHORING_GUIDE = `# koimsurai 文章撰寫指南(給 AI)

寫「一篇完整文章」前先讀這份。目標:一次到位——結構完整、格式正確、站長只要審不用大改。

## 1. 動手前
- 先 koimsurai_list_categories 看現有分類,用既有的(或明確跟站長確認要新分類)。
- 先 status='draft'。發布交給站長(審過再 set_post_status 或 send_newsletter)。
- 不確定該用哪個 block/忘記語法 → \`koimsurai_list_blocks\`(結構化目錄,比翻這份指南快)。
- **送出前一定先跑 \`koimsurai_validate_mdx\`**:MDX 編譯失敗在前台是**靜默退回 markdown**(讀者會看到裸露的標籤原始碼),而 create/update 仍回 success——不驗就沒人知道寫壞了。

## 2. 文章欄位(create_post 參數)
- **title**:想要副標就用全形冒號分隔「主標:副標」,前端自動把冒號後段渲染成副標。
  例:關掉翻譯器,程式卻關不掉:一個躺了兩年的 thread_local 死鎖
- **excerpt**:會渲染成文章開頭的「00 摘要」框 → 寫 2~4 句**真正的重點摘要**,不是複製第一段。
- **excerpt_links**:摘要裡幾句關鍵的話連到它所在的章節(讀者滑過時右邊目錄那一章會亮、點了跳過去)。
  一篇挑 4~9 句就好,每個語系各一組;格式見 create_post 的參數說明。
- **category**:必須是已存在的分類名。
- **tags**:3~5 個;不存在的會自動建立。
- **format**:用到下面「自訂 block / 圖表 / 行內 JS」→ 'mdx';純文字 → 'markdown'(預設)。
- **status**:預設 draft。

## 3. 內文格式(純 markdown,兩種 format 都能用)
- 標題 \`##\` \`###\`(自動生 TOC 錨點,hover 出 #)
- 程式碼 \`\`\`語言 …\`\`\`(自動 shiki 高亮 + emoji 語言標頭 + 行號 + 複製鈕;超過 15 行自動「展開程式碼」收合)
- Mermaid 圖 \`\`\`mermaid …\`\`\`
- **GitHub 彩色提示框**(善用,別通篇純引用 \`>\`):
  \`> [!NOTE]\` 藍|\`> [!TIP]\` 綠|\`> [!IMPORTANT]\` 紫|\`> [!WARNING]\` 琥珀|\`> [!CAUTION]\` 紅
  ⚠ **不支援自訂標題**(標題固定顯示型別名)。\`[!NOTE]\` 要**單獨一行**,內容寫在下一行起——
  在同一行接字(\`> [!NOTE] 我還沒開 CSP\`)那串字會被併進內文,讀起來會怪。正確:
  \`> [!NOTE]\` 換行 \`> 其實我到現在還沒開 CSP——這個 eval 目前是可控的…\`
- 表格 / 清單 / 粗體 / 行內連結(行內連結自動有 hover 預覽卡)
- 圖片:先呼叫 \`koimsurai_upload_image\`(path / url / base64 三擇一)拿到 \`/uploads/…\` url,再用 \`![說明](url)\` 引用。別直接貼外部熱連結。

## 4. MDX 自訂 block(**只在 format='mdx'**)

完整結構化目錄(含 props / 何時用)可隨時呼叫 \`koimsurai_list_blocks\` 取得。

${renderBlocksForGuide()}

其他:行內算式(在文章裡求值,少用)\`今天 {new Date().getFullYear()} 年\`。
**圖表怎麼挑**:精確的技術圖(流程/時序/狀態/ER/架構)一律用 \`\`\`mermaid 圍籬——有工具列(切配色、縮放平移、全螢幕、下載 SVG/PNG)。只有「概念草圖/比喻」且節點少、或想要手繪風時才用 <Sketch>。

⚠️ mermaid 支援的圖表是 flowchart / sequenceDiagram / stateDiagram / classDiagram / erDiagram / xychart 六類。gantt、pie、mindmap、timeline、journey、gitGraph **不會渲染**。方向寫在語法裡(\`flowchart LR\`),沒有讀者端切換。
mermaid 可用 frontmatter 預設外觀,例如手繪風:\`\`\`mermaid 後接 \`---\` / \`config:\` / \`  look: handDrawn\` / \`  theme: dark\` / \`---\`。

## 5. ⚠️ MDX 的坑(format='mdx' 一定遵守,寫錯會編譯失敗)
在**一般段落文字**裡,\`<\` 和 \`{\` 會被當成 JSX/表達式 → 編譯失敗(會退回醜醜的純文字)。
- 要寫字面的角括號/大括號/泛型/JSON/指令 → **一律包反引號變 inline code**:
  ✅ \`Vec<String>\`、\`{ "key": 1 }\`、\`a < b\`、\`npm run <script>\`
  ❌ 正文直接寫 Vec<String> 或 { "key": 1 }
- 程式碼區塊 \`\`\` 裡的一切都安全,不用跳脫。
- 不需要自訂 block/行內 JS → 直接 format='markdown',完全沒這個坑。

### ⚠️ CJK 的粗體/斜體會靜默失效(markdown 與 mdx 都會)
CommonMark 判斷 \`**\` 能不能當「起始」標記,看的是前後字元:**後面接標點時,前面必須是空白或標點**。
CJK 的 \`『』《》「」()\` 全都算標點,所以夾在中日韓文字裡很容易踩到——**不會報錯,只會把星號原樣印出來**,
\`validate_mdx\` 也驗不出來(語法本身合法)。實測(用本專案的 @mdx-js/mdx):

  ❌ \`の**『老人と海』**です\`            ← \`**\` 前是「の」後是「『」→ 不成立,星號外露
  ❌ \`**《老人と海》(노인과 바다)**가\`   ← 收尾 \`**\` 前是「)」後是韓文助詞 → 整個粗體失效
  ✅ \`**ヨルシカ**の『老人と海』です\`     ← 讓 \`**\` 貼著文字,標點留在外面
  ✅ \`… **《老人と海》(노인과 바다)**, 바로 …\`  ← 收尾 \`**\` 後面接標點

安全寫法:**粗體的頭尾都貼著「文字」而不是標點**,或讓緊鄰的外側是空白/標點。
日文的作品名用 \`『』\`、中文用 \`《》\` 本來就有強調效果,不必再加粗體——這是最省事的解法。
翻譯多語系時要**逐語系重看這一條**:同一句中文版正常、日文/韓文版可能就壞了(助詞位置不同)。

## 6. 多語系(i18n)——站台支援 5 語(zh-TW 來源/zh-CN/en/ja/ko)
- **來源**:title/content/excerpt 即來源語言(預設 zh-TW;非繁中寫的用 source_language 指定)。
- **簡體 zh-CN**:別手翻。建立/更新繁體後呼叫 \`koimsurai_generate_post_zh_cn\`(OpenCC 自動繁→簡)即可。
- **英/日/韓 en/ja/ko**:要出多語就翻好填進對應欄位(create_post / update_post 都能帶)——
  \`title_en\`/\`content_en\`/\`excerpt_en\`、\`title_ja\`/\`content_ja\`/\`excerpt_ja\`、\`title_ko\`/\`content_ko\`/\`excerpt_ko\`。
  - content_* 與來源共用同一 format(全篇一種);自訂 block/程式碼區塊照用,第 5 點的 MDX 跳脫規則一樣要守。
  - 某語譯文留空 → 前端該語自動 fallback 回來源,不會壞頁。可先發繁體、之後再 update_post 補譯文。
- 只想單發繁體 → 這段整段略過。

## 7. 一次寫好的檢查清單
1) 分類存在 2) title 決定要不要副標(冒號) 3) excerpt 是真的重點摘要
4) 內文穿插彩色 alert / 程式碼 / 圖表,別通篇純引用 5) format='mdx' 的話正文 \`<\`/\`{\` 都跳脫了
6) tags 3~5 7) status='draft' 交站長審 8) 要多語?zh-CN 用 generate 工具、en/ja/ko 填譯文欄
9) **跑過 koimsurai_validate_mdx 且 errors 為空**(多語系的話每個 content_* 都要驗)`;

// 圖片 mime ↔ 副檔名(後端用「原始檔名的副檔名」決定存檔 ext、用 mimetype 判斷是否算 thumbhash)。
const EXT_MIME: Record<string, string> = {
  png: 'image/png',
  jpg: 'image/jpeg',
  jpeg: 'image/jpeg',
  gif: 'image/gif',
  webp: 'image/webp',
  svg: 'image/svg+xml',
  avif: 'image/avif',
  bmp: 'image/bmp',
};
const MIME_EXT: Record<string, string> = {
  'image/png': 'png',
  'image/jpeg': 'jpg',
  'image/gif': 'gif',
  'image/webp': 'webp',
  'image/svg+xml': 'svg',
  'image/avif': 'avif',
  'image/bmp': 'bmp',
};
function extOf(name: string): string {
  return /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase() ?? '';
}

/** 從 path / url / data(base64) 三擇一解析出圖片 bytes + 檔名 + mimetype。 */
async function resolveImage(a: {
  path?: string;
  url?: string;
  data?: string;
  filename?: string;
}): Promise<{ bytes: Uint8Array; filename: string; mime: string }> {
  let bytes: Uint8Array;
  let name = a.filename;
  let mime: string | undefined;

  if (a.path) {
    const { readFile } = await import('node:fs/promises');
    const { basename } = await import('node:path');
    bytes = new Uint8Array(await readFile(a.path));
    name ??= basename(a.path);
  } else if (a.url) {
    const res = await fetch(a.url);
    if (!res.ok) throw new Error(`下載圖片失敗 (${res.status}):${a.url}`);
    bytes = new Uint8Array(await res.arrayBuffer());
    // `?? ''` 再 `||`:空字串(沒有 content-type、網址以 / 結尾)也當成沒有。
    mime = (res.headers.get('content-type')?.split(';')[0]?.trim() ?? '') || undefined;
    name ??= (new URL(a.url).pathname.split('/').pop() ?? '') || 'image';
  } else if (a.data) {
    const m = /^data:([^;]+);base64,(.*)$/s.exec(a.data.trim());
    mime = m ? m[1] : mime;
    bytes = new Uint8Array(Buffer.from(m ? m[2] : a.data.trim(), 'base64'));
    name ??= 'image';
  } else {
    throw new Error('請提供 path、url 或 data(base64)其中之一');
  }

  // 確保檔名有副檔名(後端靠它決定存檔 ext);沒有就用 mimetype 推。
  if (!extOf(name)) {
    const ext = (mime ? MIME_EXT[mime.toLowerCase()] : undefined) ?? 'png';
    name = `${name}.${ext}`;
  }
  // mimetype 沒拿到就用副檔名推(後端只看 starts_with('image/') 決定 thumbhash)。
  mime ??= EXT_MIME[extOf(name)] || 'application/octet-stream';
  return { bytes, filename: name, mime };
}

export function makeTools(api: ApiClient): Tool[] {
  return [
    // ── 撰寫指南 ────────────────────────────────────────────────
    {
      name: 'koimsurai_authoring_guide',
      description:
        '取得 koimsurai 文章撰寫指南(欄位慣例、可用 block、彩色 alert、MDX 語法坑、檢查清單)。' +
        '寫「一篇完整文章」前先呼叫這個,尤其要用 format=mdx / 圖表 / 自訂 block 時。',
      inputSchema: EMPTY,
      handler: () => Promise.resolve(AUTHORING_GUIDE),
    },

    // ── 圖片上傳 ────────────────────────────────────────────────
    {
      name: 'koimsurai_upload_image',
      description:
        '上傳圖片到後台(storage/uploads),回傳可直接放進文章的相對 URL 與 markdown。' +
        '來源三擇一:path(MCP server 本機檔案路徑)/ url(遠端圖片,下載後轉存)/ data(base64,可含 data: 前綴)。' +
        '回傳 url 形如 /uploads/YYYY/MM/xxx.png#th=…(#th 是模糊佔位 thumbhash,原樣保留即可)。文章裡用 ![alt](url) 引用。',
      inputSchema: {
        type: 'object',
        properties: {
          path: { type: 'string', description: '本機圖片檔案路徑(三擇一)' },
          url: { type: 'string', description: '遠端圖片 URL,會下載後上傳(三擇一)' },
          data: { type: 'string', description: '圖片 base64,可含 data:image/…;base64, 前綴(三擇一)' },
          filename: {
            type: 'string',
            description: '檔名(決定副檔名)。path/url 可省略自動推斷;data 建議提供以帶正確副檔名',
          },
          alt: { type: 'string', description: '圖片替代文字,用於回傳的 markdown ![alt](url)' },
        },
        additionalProperties: false,
      },
      handler: async (a) => {
        const { bytes, filename, mime } = await resolveImage(a);
        const result = await api.uploadFile<{
          url: string;
          filename: string;
          thumbhash?: string | null;
        }>('/api/admin/upload', bytes, filename, mime);
        const alt = typeof a.alt === 'string' ? a.alt : '';
        return {
          url: result.url,
          filename: result.filename,
          thumbhash: result.thumbhash ?? null,
          markdown: `![${alt}](${result.url})`,
        };
      },
    },

    // ── 文章 CRUD ──────────────────────────────────────────────
    {
      name: 'koimsurai_list_posts',
      description: '列出後台文章(含草稿)。可依狀態/關鍵字過濾、分頁。回 AdminPostsResponse。',
      inputSchema: {
        type: 'object',
        properties: {
          status: {
            type: 'string',
            enum: ['published', 'draft', 'scheduled', 'trashed'],
            description: '省略=全部(不含回收桶)',
          },
          search: { type: 'string', description: '標題/內文關鍵字' },
          page: { type: 'number', description: '頁碼,預設 1' },
          limit: { type: 'number', description: '每頁筆數,預設由後端決定' },
        },
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('GET', '/api/admin/posts', {
          query: { status: a.status, search: a.search, page: a.page, limit: a.limit },
        }),
    },
    {
      name: 'koimsurai_get_post',
      description: '讀單篇文章完整內容(含全部 i18n 欄位與 tags)。回 AdminPostDetailResponse。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number', description: '文章 id' } },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('GET', `/api/admin/posts/${idOf(a)}`),
    },
    {
      name: 'koimsurai_list_blocks',
      description:
        '列出所有可用的 MDX 自訂 block(結構化目錄:名稱/何時用/props/範例/坑)。' +
        '寫 format=mdx 的文章、不確定該用哪個 block 或忘記語法時查這個,比翻整份指南快。',
      inputSchema: {
        type: 'object',
        properties: {
          category: {
            type: 'string',
            enum: ['prose', 'code', 'data', 'media', 'layout', 'interactive'],
            description:
              '只列某一類(省略=全部)。prose 文字表達|code 程式碼|data 數據視覺化|media 圖與影片|layout 結構編排|interactive 讀者互動',
          },
        },
        additionalProperties: false,
      },
      handler: (a) => {
        const cat = typeof a.category === 'string' ? a.category : undefined;
        const list = cat ? BLOCKS.filter((b) => b.category === cat) : BLOCKS;
        return Promise.resolve({ count: list.length, blocks: list });
      },
    },
    {
      name: 'koimsurai_validate_mdx',
      description:
        '⭐ 驗證文章內容(**建議 create_post / update_post 前一定先跑**)。' +
        '會真的跑一次 MDX 編譯 + 檢查未知 block、alert 語法、手打編號、裸網址清單、外部熱連結。' +
        '重要:MDX 編譯失敗在前台是**靜默退回 markdown**(讀者看到裸露的標籤原始碼),而 create/update 仍回 success ' +
        '——不先驗就不會有人知道寫壞了。回 { ok, summary, errors, warnings, hints },errors 非空就別送出。',
      inputSchema: {
        type: 'object',
        properties: {
          content: { type: 'string', description: '要驗的文章內文(也可拿來驗某個語系的譯文)' },
          format: { type: 'string', enum: ['markdown', 'mdx'], description: "內容格式,預設 'mdx'" },
        },
        required: ['content'],
        additionalProperties: false,
      },
      handler: (a) =>
        validateContent(
          typeof a.content === 'string' ? a.content : '',
          typeof a.format === 'string' ? a.format : 'mdx',
        ),
    },
    {
      name: 'koimsurai_create_post',
      description:
        '建立文章。title/content 必填,其餘可選。預設 status=draft(不會直接公開)。' +
        '⭐ 寫「完整文章」前先呼叫 koimsurai_authoring_guide(副標/摘要/彩色 alert/自訂 block/MDX 坑/檢查清單)。' +
        '⭐ format=mdx 時,送出前先用 koimsurai_validate_mdx 驗過(編譯失敗會靜默退回 markdown,這裡仍會回 success)。' +
        'title 用「主標:副標」冒號分隔會自動出副標;excerpt 會變成開頭的「00 摘要」框,excerpt_links 讓其中幾句連到章節。' +
        "用到 <Note>/<Annot>/<Spoiler>/<BarChart> 或行內 JS → format='mdx'。" +
        '多語系:zh-CN 用 generate_post_zh_cn 自動轉;en/ja/ko 填 title_en/content_en…等譯文欄(見指南第 6 點)。' +
        '注意 send_newsletter=true 且 published 會寄電子報。',
      inputSchema: {
        type: 'object',
        properties: postWriteProps,
        required: ['title', 'content'],
        additionalProperties: false,
      },
      handler: (a) => api.request('POST', '/api/admin/posts', { body: pick(a, [...POST_WRITE_FIELDS]) }),
    },
    {
      name: 'koimsurai_update_post',
      description:
        '更新文章。只送想改的欄位(其餘不動)。id 必填。改到 mdx 內文時,送出前先用 koimsurai_validate_mdx 驗過。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number', description: '文章 id' }, ...postWriteProps },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('PUT', `/api/admin/posts/${idOf(a)}`, { body: pick(a, [...POST_WRITE_FIELDS]) }),
    },
    {
      name: 'koimsurai_set_post_status',
      description: '只改文章狀態(draft ⇄ published),不動內容。發布請優先用這個。',
      inputSchema: {
        type: 'object',
        properties: {
          id: { type: 'number' },
          status: { type: 'string', enum: ['draft', 'published'] },
        },
        required: ['id', 'status'],
        additionalProperties: false,
      },
      handler: (a) => api.request('PATCH', `/api/posts/${idOf(a)}/status`, { body: { status: a.status } }),
    },
    {
      name: 'koimsurai_delete_post',
      description:
        '把文章丟進回收桶(讀者看不到,30 天後自動刪掉,期間可用 koimsurai_restore_post 還原)。' +
        '⚠️ permanent=true 才永久刪除(連同 post_tags,不可復原),而且只對已經在回收桶裡的文章有效——請先確認。',
      inputSchema: {
        type: 'object',
        properties: {
          id: { type: 'number' },
          permanent: { type: 'boolean', description: 'true:從回收桶永久刪除' },
        },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('DELETE', `/api/admin/posts/${idOf(a)}`, {
          query: { permanent: a.permanent === true ? 'true' : undefined },
        }),
    },
    {
      name: 'koimsurai_restore_post',
      description: '從回收桶還原文章,回到丟之前的狀態(原本是排程的會回到草稿)。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number' } },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('POST', `/api/admin/posts/${idOf(a)}/restore`),
    },
    {
      name: 'koimsurai_generate_post_zh_cn',
      description: '由繁體來源自動生成該篇的簡體(zh-CN)欄位(opencc Tw2s)。id 必填。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number' } },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('POST', `/api/admin/posts/${idOf(a)}/generate-zh-cn`),
    },

    // ── 統計與健康 ─────────────────────────────────────────────
    {
      name: 'koimsurai_site_stats',
      description: '後台總覽:文章數/已發布/草稿/本月新文/留言數/本週留言/瀏覽數。',
      inputSchema: EMPTY,
      handler: () => api.request('GET', '/api/admin/stats'),
    },
    {
      name: 'koimsurai_vitals_stats',
      description: '前端 Core Web Vitals 聚合(LCP/CLS/INP/FCP/TTFB 的 count/p75/rating 分佈)。',
      inputSchema: {
        type: 'object',
        properties: { days: { type: 'number', description: '回看天數,預設 7' } },
        additionalProperties: false,
      },
      handler: (a) => api.request('GET', '/api/vitals/stats', { query: { days: a.days }, auth: false }),
    },
    {
      name: 'koimsurai_health',
      description: '後端健康檢查(回 OK)。用來確認服務在跑。',
      inputSchema: EMPTY,
      handler: () => api.request('GET', '/api/health', { auth: false }),
    },

    // ── 分類 ──────────────────────────────────────────────────
    {
      name: 'koimsurai_list_categories',
      description: '列出所有分類(含各分類文章數 post_count)。',
      inputSchema: EMPTY,
      handler: () => api.request('GET', '/api/admin/categories'),
    },
    {
      name: 'koimsurai_create_category',
      description: '建立分類。name 必填;slug 省略時由 name 生成。',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: '分類名(同時是資料鍵:文章的 category 存的就是它)' },
          description: { type: 'string' },
          slug: { type: 'string' },
          short_description: { type: 'string' },
          name_en: { type: 'string', description: '英文顯示名(可選;不影響資料鍵)' },
          name_ja: { type: 'string', description: '日文顯示名(可選)' },
          name_ko: { type: 'string', description: '韓文顯示名(可選)' },
          name_zh_cn: { type: 'string', description: '簡中顯示名(可選)' },
          short_description_en: { type: 'string', description: '英文簡述(可選;分類 tooltip 用)' },
          short_description_ja: { type: 'string', description: '日文簡述(可選;分類 tooltip 用)' },
          short_description_ko: { type: 'string', description: '韓文簡述(可選;分類 tooltip 用)' },
          short_description_zh_cn: { type: 'string', description: '簡中簡述(可選;分類 tooltip 用)' },
          description_en: { type: 'string', description: '英文描述(可選)' },
          description_ja: { type: 'string', description: '日文描述(可選)' },
          description_ko: { type: 'string', description: '韓文描述(可選)' },
          description_zh_cn: { type: 'string', description: '簡中描述(可選)' },
        },
        required: ['name'],
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('POST', '/api/admin/categories', {
          body: pick(a, [
            'name',
            'description',
            'slug',
            'short_description',
            'name_en',
            'name_ja',
            'name_ko',
            'name_zh_cn',
            'short_description_en',
            'short_description_ja',
            'short_description_ko',
            'short_description_zh_cn',
            'description_en',
            'description_ja',
            'description_ko',
            'description_zh_cn',
          ]),
        }),
    },
    {
      name: 'koimsurai_update_category',
      description: '更新分類。id 必填,其餘只送要改的。',
      inputSchema: {
        type: 'object',
        properties: {
          id: { type: 'number' },
          name: { type: 'string' },
          description: { type: 'string' },
          slug: { type: 'string' },
          short_description: { type: 'string' },
          name_en: { type: 'string', description: '英文顯示名(可選;不影響資料鍵)' },
          name_ja: { type: 'string', description: '日文顯示名(可選)' },
          name_ko: { type: 'string', description: '韓文顯示名(可選)' },
          name_zh_cn: { type: 'string', description: '簡中顯示名(可選)' },
          short_description_en: { type: 'string', description: '英文簡述(可選;分類 tooltip 用)' },
          short_description_ja: { type: 'string', description: '日文簡述(可選;分類 tooltip 用)' },
          short_description_ko: { type: 'string', description: '韓文簡述(可選;分類 tooltip 用)' },
          short_description_zh_cn: { type: 'string', description: '簡中簡述(可選;分類 tooltip 用)' },
          description_en: { type: 'string', description: '英文描述(可選)' },
          description_ja: { type: 'string', description: '日文描述(可選)' },
          description_ko: { type: 'string', description: '韓文描述(可選)' },
          description_zh_cn: { type: 'string', description: '簡中描述(可選)' },
        },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('PUT', `/api/admin/categories/${idOf(a)}`, {
          body: pick(a, [
            'name',
            'description',
            'slug',
            'short_description',
            'name_en',
            'name_ja',
            'name_ko',
            'name_zh_cn',
            'short_description_en',
            'short_description_ja',
            'short_description_ko',
            'short_description_zh_cn',
            'description_en',
            'description_ja',
            'description_ko',
            'description_zh_cn',
          ]),
        }),
    },
    {
      name: 'koimsurai_delete_category',
      description: '⚠️ 刪除分類(不影響文章本身的 category 字串)。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number' } },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('DELETE', `/api/admin/categories/${idOf(a)}`),
    },

    // ── 標籤 ──────────────────────────────────────────────────
    {
      name: 'koimsurai_list_tags',
      description: '列出所有標籤(含使用篇數 post_count)。',
      inputSchema: EMPTY,
      handler: () => api.request('GET', '/api/admin/tags'),
    },
    {
      name: 'koimsurai_create_tag',
      description: '建立標籤。name 必填。',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: '標籤名(同時是資料鍵:文章的標籤關聯與前台篩選都比對它)' },
          name_en: { type: 'string', description: '英文顯示名(可選;不影響資料鍵)' },
          name_ja: { type: 'string', description: '日文顯示名(可選)' },
          name_ko: { type: 'string', description: '韓文顯示名(可選)' },
          name_zh_cn: { type: 'string', description: '簡中顯示名(可選)' },
          short_description_en: { type: 'string', description: '英文簡述(可選;分類 tooltip 用)' },
          short_description_ja: { type: 'string', description: '日文簡述(可選;分類 tooltip 用)' },
          short_description_ko: { type: 'string', description: '韓文簡述(可選;分類 tooltip 用)' },
          short_description_zh_cn: { type: 'string', description: '簡中簡述(可選;分類 tooltip 用)' },
          description_en: { type: 'string', description: '英文描述(可選)' },
          description_ja: { type: 'string', description: '日文描述(可選)' },
          description_ko: { type: 'string', description: '韓文描述(可選)' },
          description_zh_cn: { type: 'string', description: '簡中描述(可選)' },
        },
        required: ['name'],
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('POST', '/api/admin/tags', {
          body: pick(a, ['name', 'name_en', 'name_ja', 'name_ko', 'name_zh_cn']),
        }),
    },
    {
      name: 'koimsurai_update_tag',
      description: '重新命名標籤 / 補多語系顯示名。id + name 必填。',
      inputSchema: {
        type: 'object',
        properties: {
          id: { type: 'number' },
          name: { type: 'string', description: '標籤名(同時是資料鍵)' },
          name_en: { type: 'string', description: '英文顯示名(可選;不影響資料鍵)' },
          name_ja: { type: 'string', description: '日文顯示名(可選)' },
          name_ko: { type: 'string', description: '韓文顯示名(可選)' },
          name_zh_cn: { type: 'string', description: '簡中顯示名(可選)' },
        },
        required: ['id', 'name'],
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('PUT', `/api/admin/tags/${idOf(a)}`, {
          body: pick(a, ['name', 'name_en', 'name_ja', 'name_ko', 'name_zh_cn']),
        }),
    },
    {
      name: 'koimsurai_delete_tag',
      description: '⚠️ 刪除標籤(連同 post_tags 關聯)。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number' } },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('DELETE', `/api/admin/tags/${idOf(a)}`),
    },

    // ── 碎念 thoughts ─────────────────────────────────────────
    {
      name: 'koimsurai_create_thought',
      description:
        '發一則碎念(短想法 feed)。content 必填;refUrl 給連結會自動抓 OG 卡片。verb 是前台「Koimsurai 看了/讀了…」的動詞(存 key,五個語系各自翻)。',
      inputSchema: {
        type: 'object',
        properties: {
          content: { type: 'string' },
          refUrl: { type: 'string', description: '附帶連結(可選,會 unfurl)' },
          verb: {
            type: 'string',
            enum: ['watched', 'read', 'listened', 'played', 'shared'],
            description: '動詞(可選);分享連結用 shared',
          },
        },
        required: ['content'],
        additionalProperties: false,
      },
      handler: (a) => api.request('POST', '/api/admin/thoughts', { body: pick(a, ['content', 'refUrl', 'verb']) }),
    },
    {
      name: 'koimsurai_update_thought',
      description: '更新碎念。id 必填;clearRef=true 可清掉原本的連結卡片;verb 給空字串是拿掉動詞。',
      inputSchema: {
        type: 'object',
        properties: {
          id: { type: 'number' },
          content: { type: 'string' },
          refUrl: { type: 'string' },
          clearRef: { type: 'boolean' },
          verb: { type: 'string', enum: ['', 'watched', 'read', 'listened', 'played', 'shared'] },
        },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) =>
        api.request('PUT', `/api/admin/thoughts/${idOf(a)}`, {
          body: pick(a, ['content', 'refUrl', 'clearRef', 'verb']),
        }),
    },
    {
      name: 'koimsurai_delete_thought',
      description: '⚠️ 刪除碎念。',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'number' } },
        required: ['id'],
        additionalProperties: false,
      },
      handler: (a) => api.request('DELETE', `/api/admin/thoughts/${idOf(a)}`),
    },

    // ── gallery ───────────────────────────────────────────────
    {
      name: 'koimsurai_gallery_sync',
      description:
        '觸發 NAS 相簿同步:掃來源 → 產 webp(1920/400)+ EXIF + thumbhash → 寫 manifest。' +
        '耗時(視新增照片數),同時只跑一個。',
      inputSchema: EMPTY,
      handler: () => api.request('POST', '/api/admin/gallery/sync'),
    },
  ];
}