@bbki.ng/backend 0.3.20 → 0.4.0

package/.dev.vars.example

@@ -2,3 +2,5 @@
 # Copy this file to .dev.vars and update the values
 
 API_KEY=your-local-dev-api-key
+KIMI_API_KEY=your-kimi-api-key
+ANTHROPIC_API_KEY=your-anthropic-api-key

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # backend
 
+## 0.4.0
+
+### Minor Changes
+
+- 7f7e516: Add coc-master plugin: AI-powered Clash of Clans assistant
+  - Frontend: New `coc-master` plugin with chat UI for player development advice
+  - Backend: New `/coc-master/chat` endpoint using Vercel AI SDK with Kimi (Moonshot AI)
+  - Tools: `getPlayerInfo`, `getClanInfo`, `getCurrentWar` via COC official API
+  - Tools: `getDevelopmentGuide` with built-in knowledge base for upgrade priorities, troop combos, base layouts, etc.
+
+## 0.3.21
+
+### Patch Changes
+
+- 8d26c74: update version color
+
 ## 0.3.20
 
 ### Patch Changes

package/data/coc-wiki-guide.json

@@ -0,0 +1,42 @@
+{
+  "_meta": {
+    "source": "Clash of Clans Community Guide",
+    "version": "1.0.0",
+    "lastUpdated": "2026-04-22",
+    "description": "Strategy guide topics for Clash of Clans development advisor"
+  },
+  "topics": {
+    "升级优先级": {
+      "keywords": ["升级优先级", "升级顺序", "先升什么", "发展路线", "建筑顺序"],
+      "template": "大本升级优先级：实验室 > 兵营 > 训练营 > 法术工厂 > 大本。\n\n防御方面：防空火箭、法师塔、迫击炮优先升级。\n\n资源建筑在防御升级完后再考虑。\n\n核心原则：\n1. 进攻优先于防守——先保证三星能力\n2. 英雄持续升级，不要同时休眠\n3. 城墙可以慢慢来，不要急于一次性升满\n4. 采集器在资源充裕时升级"
+    },
+    "兵种搭配": {
+      "keywords": ["兵种搭配", "流派", "配兵", "用什么兵", "进攻组合", "打法"],
+      "template": "常用流派：\n1. 龙球流（飞龙+气球）：适合7-9本，操作简单，三星率高\n2. 野猪流：适合8-10本，对防御阵要求高\n3. 矿工流：适合10-11本，续航强\n4. 电龙流：适合11本以上，清边要求高\n5. 超级女巫：适合13本以上，推进稳定\n\n选流派原则：\n- 看阵选兵，不要盲目固定一种\n- 先精通一种，再扩展其他\n- 注意援兵和法术的配合"
+    },
+    "防御布局": {
+      "keywords": ["防御布局", "阵型", "怎么摆", "防御阵", "护资源", "护本"],
+      "template": "布局原则：\n1. 防空火箭分散布置，覆盖全图\n2. 法师塔和迫击炮保护资源\n3. 城堡居中，难引兵\n4. 搜空地雷保护防空\n5. 根据常用流派针对性调整\n\n注意事项：\n- 防三优于防两星\n- 陷阱位置要常换\n- 大本外置适合冲杯，内置适合部落战"
+    },
+    "资源管理": {
+      "keywords": ["资源管理", "怎么刷资源", "抢资源", "资源不够", "金币", "圣水", "黑油"],
+      "template": "资源管理建议：\n1. 优先升级采集器到当前大本最高等级\n2. 掠夺时带满兵，保证效率\n3. 护盾期间不要进攻\n4. 联赛币优先买锤子或建筑书\n5. 部落竞赛奖励选择最稀缺的资源\n\n刷资源技巧：\n- 降杯到合适段位，保证对手资源丰富\n- 使用哥布林或超哥快速掠夺\n- 保持护盾，避免被连续掠夺"
+    },
+    "部落战": {
+      "keywords": ["部落战", "战争", "打部落战", "三星技巧", "进攻策略"],
+      "template": "部落战技巧：\n1. 侦察对手阵型，选择克制流派\n2. 清边要彻底，避免大部队跑偏\n3. 法术释放时机关键，提前规划路线\n4. 援兵处理优先，毒药+冰冻组合\n5. 低本打高本时以两星为目标\n\n进阶建议：\n- 模拟攻击前先在友谊战中练习\n- 观察队友进攻，学习不同打法\n- 注意时区，在战争结束前留足时间"
+    },
+    "英雄升级": {
+      "keywords": ["英雄升级", "蛮王", "女王", "咏王", "闰土", "英雄优先级"],
+      "template": "英雄升级顺序：\n1. 蛮王和女王交替升级，保持至少一个可用\n2. 咏王优先升级生命光环\n3. 闰土根据常用流派决定优先级\n4. 升级英雄时尽量使用建筑书或锤子\n5. 联赛期间保持英雄满状态\n\n注意事项：\n- 英雄是进攻核心，不要长期休眠\n- 装备系统可以大幅提升英雄战力\n- 英雄升级成本随等级指数增长"
+    },
+    "法术使用": {
+      "keywords": ["法术", "法术搭配", "狂暴", "冰冻", "毒药", "弹跳"],
+      "template": "法术使用指南：\n1. 狂暴法术配合高伤害单位（如气球、野猪）\n2. 冰冻法术用于锁定关键防御（如地狱塔、投石炮）\n3. 毒药法术处理援兵和英雄\n4. 地震法术开墙或摧毁关键建筑\n5. 弹跳法术让地面部队跨越城墙\n\n通用搭配：\n- 空军：3狂暴 + 3冰冻\n- 地面：2治疗 + 2狂暴 + 1冰冻 + 1毒药"
+    },
+    "装备系统": {
+      "keywords": ["装备", "英雄装备", "技能", "铁匠铺"],
+      "template": "英雄装备建议：\n1. 优先升级常用英雄的装备\n2. 野蛮人之拳和弓箭女皇的巨箭是通用好选择\n3. 装备升级需要矿石，通过突袭和联赛获取\n4. 不同装备适合不同流派，根据主攻方向选择\n5. 铁匠铺升级可解锁更多装备槽位"
+    }
+  }
+}

package/eslint.config.js

@@ -6,4 +6,15 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-export default [includeIgnoreFile(path.resolve(__dirname, '.gitignore')), ...cloudflareConfig];
+export default [
+  includeIgnoreFile(path.resolve(__dirname, '.gitignore')),
+  ...cloudflareConfig,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      globals: {
+        KVNamespace: 'readonly',
+      },
+    },
+  },
+];

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@bbki.ng/backend",
-  "version": "0.3.20",
+  "version": "0.4.0",
   "type": "module",
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.71",
     "@simplewebauthn/server": "13.2.2",
+    "ai": "^6.0.168",
     "hono": "^4.10.7",
-    "showdown": "^2.1.0"
+    "showdown": "^2.1.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20251128.0",
@@ -22,7 +25,7 @@
     "prettier": "^3.2.0",
     "typescript": "^5.3.0",
     "wrangler": "^4.58.0",
-    "@bbki.ng/config": "1.0.9"
+    "@bbki.ng/config": "2.0.3"
   },
   "prettier": "@bbki.ng/config/prettier",
   "scripts": {

package/src/config/app.config.ts

@@ -5,6 +5,7 @@ import { cors } from 'hono/cors';
 type Bindings = {
   DB: D1Database;
   API_KEY: string;
+  KIMI_API_KEY: string;
 };
 
 const app = new Hono<{ Bindings: Bindings }>();

package/src/controllers/coc-master/chat.controller.ts

@@ -0,0 +1,107 @@
+import { Context } from 'hono';
+import { convertToModelMessages, stepCountIs, streamText } from 'ai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+
+import {
+  getPlayerInfoTool,
+  getClanInfoTool,
+  getCurrentWarTool,
+  getDevelopmentGuideTool,
+} from './tools';
+
+// Kimi (Moonshot AI) uses OpenAI-compatible API
+const createKimiClient = (apiKey: string) =>
+  createAnthropic({
+    baseURL: 'https://api.kimi.com/coding/v1/',
+    apiKey,
+  });
+
+const SYSTEM_PROMPT = `你是资深《部落冲突》(Clash of Clans) 游戏策略专家。
+
+你的职责是为玩家提供全方位的发展建议，包括但不限于：
+- 村庄升级优先级规划
+- 兵种搭配与流派推荐
+- 防御布局优化建议
+- 部落战策略指导
+- 资源管理与英雄升级规划
+- 根据玩家实际数据给出个性化建议
+
+风格要求：
+- 以资深专家口吻回复，语气严肃、科学、专业
+- 用中文回复
+- 必要时使用列表和分段让建议更易读
+- 如果玩家数据不足，主动询问所需信息
+- 严禁在回复中使用任何 emoji 或表情符号
+- 避免口语化表达，保持学术性与权威性
+- 严禁滥用分割线，避免在任何情况下使用
+- 严禁滥用表格，仅在确实有助于表达时使用表格，并且必须使用 Markdown 格式，且表格内容必须简洁明了，避免冗长复杂的表格设计
+
+其他要求：
+1. 你没有名字，自我介绍时，避免使用第一人称，直接进入主题。
+2. 除了 coc 相关内容，其他任何内容，避免讨论。
+3. 永远不要询问玩家隐私信息，如姓名、年龄、性别等。
+4. 不需要询问玩家的游戏账号信息（如玩家标签），因为工具会自动获取。
+5. 不要询问玩家 TOKEN
+
+你可以使用以下工具获取数据：
+1. getPlayerInfo: 获取玩家个人信息、村庄、英雄、兵种等级等
+2. getClanInfo: 获取部落信息、成员、战争日志
+3. getCurrentWar: 获取当前部落战信息
+4. getDevelopmentGuide: 查询权威发展建议（升级优先级、兵种搭配、防御策略等）
+`;
+
+export const chatController = async (c: Context) => {
+  try {
+    const body = await c.req.json();
+    const { messages, playerTag } = body;
+
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return c.json({ error: 'Messages array is required' }, 400);
+    }
+
+    // Inject player context into system prompt if available
+    let system = SYSTEM_PROMPT;
+    if (playerTag) {
+      system += `\n\n当前服务玩家标签: ${playerTag}`;
+    }
+
+    const kimi = createKimiClient(c.env.KIMI_API_KEY);
+
+    // Default values for tool execution
+    const defaultPlayerTag = playerTag || '';
+    const token = c.env.COC_TOKEN || '';
+    const proxyKey = c.env.PROXY_KEY || 'nshzpldjbm_L';
+    const mergedToken = `${token}:${proxyKey}`;
+
+    console.log('proxy key', proxyKey);
+    console.log(mergedToken);
+
+    const kv = c.env.KV as KVNamespace;
+
+    const modelMessages = await convertToModelMessages(messages);
+
+    const result = streamText({
+      model: kimi('kimi-for-coding'),
+      system,
+      messages: modelMessages,
+      tools: {
+        getPlayerInfo: getPlayerInfoTool(defaultPlayerTag, mergedToken),
+        getClanInfo: getClanInfoTool(mergedToken),
+        getCurrentWar: getCurrentWarTool(mergedToken),
+        getDevelopmentGuide: getDevelopmentGuideTool(kv),
+      },
+      stopWhen: stepCountIs(10),
+    });
+
+    return result.toUIMessageStreamResponse();
+  } catch (error: unknown) {
+    console.error('COC Master chat error:', error);
+    return c.json(
+      {
+        error: 'Internal server error',
+        message: (error as Error).message,
+      },
+      500
+    );
+  }
+};

package/src/controllers/coc-master/tools/get-clan-info.tool.ts

@@ -0,0 +1,27 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+
+import { cocService } from '../../../services/coc.service';
+
+export const getClanInfoTool = (defaultToken: string) =>
+  tool({
+    description: '获取部落详细信息，包括部落等级、成员列表、战争日志、部落描述等',
+    inputSchema: z.object({
+      clanTag: z.string().describe('部落标签，如 #2YJ8QR2Q'),
+      token: z.string().optional().describe('COC Developer API Token。使用当前配置的 Token'),
+    }),
+    execute: async (args: { clanTag: string; token?: string }) => {
+      const tok = args.token || defaultToken;
+      if (!tok) {
+        return JSON.stringify({ error: '缺少 Token，请先在配置中填写' });
+      }
+      try {
+        const data = await cocService.getClan(args.clanTag, tok);
+        return JSON.stringify(data);
+      } catch (error: unknown) {
+        return JSON.stringify({
+          error: (error as Error).message || 'Failed to fetch clan info',
+        });
+      }
+    },
+  });

package/src/controllers/coc-master/tools/get-current-war.tool.ts

@@ -0,0 +1,30 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+
+import { cocService } from '../../../services/coc.service';
+
+export const getCurrentWarTool = (defaultToken: string) =>
+  tool({
+    description: '获取部落当前战争信息',
+    inputSchema: z.object({
+      clanTag: z.string().describe('部落标签'),
+      token: z
+        .string()
+        .optional()
+        .describe('COC Developer API Token。如果未提供，使用 defaultToken'),
+    }),
+    execute: async (args: { clanTag: string; token?: string }) => {
+      const tok = args.token || defaultToken;
+      if (!tok) {
+        return JSON.stringify({ error: '缺少 Token，请先在配置中填写' });
+      }
+      try {
+        const data = await cocService.getCurrentWar(args.clanTag, tok);
+        return JSON.stringify(data);
+      } catch (error: unknown) {
+        return JSON.stringify({
+          error: (error as Error).message || 'Failed to fetch war info',
+        });
+      }
+    },
+  });

package/src/controllers/coc-master/tools/get-development-guide.tool.ts

@@ -0,0 +1,22 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+
+import { cocWikiService } from '../../../services/cocWiki.service';
+
+export const getDevelopmentGuideTool = (kv: KVNamespace) =>
+  tool({
+    description:
+      '查询权威发展建议，包括升级优先级、兵种搭配、防御策略、资源管理、部落战技巧、英雄升级规划等',
+    inputSchema: z.object({
+      topic: z
+        .string()
+        .describe(
+          '查询主题，如"升级优先级"、"兵种搭配"、"防御布局"、"资源管理"、"部落战"、"英雄升级"'
+        ),
+      townHallLevel: z.number().optional().describe('当前大本等级，用于提供针对性建议'),
+    }),
+    execute: async (args: { topic: string; townHallLevel?: number }) => {
+      const result = await cocWikiService.query(kv, args.topic, args.townHallLevel);
+      return JSON.stringify(result);
+    },
+  });

package/src/controllers/coc-master/tools/get-player-info.tool.ts

@@ -0,0 +1,34 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+
+import { cocService } from '../../../services/coc.service';
+
+export const getPlayerInfoTool = (defaultPlayerTag: string, defaultToken: string) =>
+  tool({
+    description: '获取玩家个人信息、村庄、英雄、兵种等级、法术等级、成就等详细数据',
+    inputSchema: z.object({
+      playerTag: z
+        .string()
+        .optional()
+        .describe('玩家标签，如 #2P0J9PY8G。如果未提供，使用当前配置的玩家标签'),
+      token: z
+        .string()
+        .optional()
+        .describe('COC Developer API Token。如果未提供，使用 defaultToken'),
+    }),
+    execute: async (args: { playerTag?: string; token?: string }) => {
+      const tag = args.playerTag || defaultPlayerTag;
+      const tok = args.token || defaultToken;
+      if (!tag || !tok) {
+        return JSON.stringify({ error: '缺少玩家标签或 Token，请先在配置中填写' });
+      }
+      try {
+        const data = await cocService.getPlayer(tag, tok);
+        return JSON.stringify(data);
+      } catch (error: unknown) {
+        return JSON.stringify({
+          error: (error as Error).message || 'Failed to fetch player info',
+        });
+      }
+    },
+  });

package/src/controllers/coc-master/tools/index.ts

@@ -0,0 +1,4 @@
+export { getPlayerInfoTool } from './get-player-info.tool';
+export { getClanInfoTool } from './get-clan-info.tool';
+export { getCurrentWarTool } from './get-current-war.tool';
+export { getDevelopmentGuideTool } from './get-development-guide.tool';

package/src/controllers/coc-master/wiki-sync.controller.ts

@@ -0,0 +1,46 @@
+import { Context } from 'hono';
+
+import { cocWikiDataImporter } from '../../services/cocWikiDataImporter.service';
+
+/**
+ * Trigger manual sync of COC Wiki external data into KV cache.
+ * In production this could be protected by an API key or run on a Cron Trigger.
+ */
+export const wikiSyncController = async (c: Context) => {
+  try {
+    const kv = c.env.KV as KVNamespace;
+    if (!kv) {
+      return c.json({ error: 'KV namespace not bound' }, 500);
+    }
+
+    const result = await cocWikiDataImporter.sync(kv);
+
+    if (!result.success) {
+      return c.json(
+        {
+          success: false,
+          message: 'Sync completed with errors',
+          details: result,
+        },
+        502
+      );
+    }
+
+    return c.json({
+      success: true,
+      message: 'COC Wiki data synced successfully',
+      details: result,
+    });
+  } catch (error) {
+    console.error('COC Wiki sync error:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    return c.json(
+      {
+        success: false,
+        error: 'Internal server error',
+        message,
+      },
+      500
+    );
+  }
+};

package/src/controllers/plugins/list.controller.ts

@@ -1,5 +1,7 @@
 import { Context } from 'hono';
 
+import { safeParseJSON } from '../../utils';
+
 export const listPlugins = async (c: Context) => {
   try {
     const { results } = await c.env.DB.prepare(
@@ -9,7 +11,12 @@ export const listPlugins = async (c: Context) => {
 
     return c.json({
       status: 'success',
-      data: results,
+      data: results.map((p: { dependencies: string }) => ({
+        ...p,
+        dependencies:
+          safeParseJSON<{ dependencies: string[] }>(p.dependencies, { dependencies: [] })
+            ?.dependencies || [],
+      })),
     });
   } catch (error: Error | unknown) {
     return c.json(

package/src/controllers/streaming/list.controller.ts

@@ -6,9 +6,11 @@ export const listStreaming = async (c: Context) => {
     // 'before' - fetch records older than this ID (for pagination / next page)
     // 'after' - fetch records newer than this ID (for polling / new messages)
     // 'offset' - number of records to fetch (default: 8, max: 100)
+    // 'type' - optional filter by type (note, article, link, image, ci)
     const before = c.req.query('before');
     const after = c.req.query('after');
     const offset = Math.min(parseInt(c.req.query('offset') || '8', 10), 100);
+    const type = c.req.query('type');
 
     let results;
 
@@ -18,10 +20,11 @@ export const listStreaming = async (c: Context) => {
         `SELECT id, author, content, type, created_at as createdAt
          FROM streaming
          WHERE created_at < (SELECT created_at FROM streaming WHERE id = ?)
+         ${type ? 'AND type = ?' : ''}
          ORDER BY created_at DESC
          LIMIT ?`
       )
-        .bind(before, offset)
+        .bind(...(type ? [before, type, offset] : [before, offset]))
         .all();
       results = cursorResults;
     } else if (after) {
@@ -31,10 +34,11 @@ export const listStreaming = async (c: Context) => {
         `SELECT id, author, content, type, created_at as createdAt
          FROM streaming
          WHERE created_at > (SELECT created_at FROM streaming WHERE id = ?)
+         ${type ? 'AND type = ?' : ''}
          ORDER BY created_at ASC
          LIMIT ?`
       )
-        .bind(after, offset)
+        .bind(...(type ? [after, type, offset] : [after, offset]))
         .all();
       results = cursorResults;
     } else {
@@ -42,10 +46,11 @@ export const listStreaming = async (c: Context) => {
       const { results: recentResults } = await c.env.DB.prepare(
         `SELECT id, author, content, type, created_at as createdAt
          FROM streaming
+         ${type ? 'WHERE type = ?' : ''}
          ORDER BY created_at DESC
          LIMIT ?`
       )
-        .bind(offset)
+        .bind(...(type ? [type, offset] : [offset]))
         .all();
       results = recentResults;
     }

package/src/index.ts

@@ -1,14 +1,15 @@
 import app from './config/app.config';
-
 import { commentRouter } from './routes/comment.routes';
 import { streamingRouter } from './routes/streaming.routes';
 import { postsRouter } from './routes/posts.routes';
 import { pluginsRouter } from './routes/plugins.routes';
+import { cocMasterRouter } from './routes/coc-master.routes';
 
 app.route('comment', commentRouter);
 app.route('streaming', streamingRouter);
 app.route('posts', postsRouter);
 app.route('plugins', pluginsRouter);
+app.route('coc-master', cocMasterRouter);
 
 app.get('/', c => {
   return c.text('Hello Hono!');

package/src/routes/coc-master.routes.ts

@@ -0,0 +1,11 @@
+import { Hono } from 'hono';
+
+import { chatController } from '../controllers/coc-master/chat.controller';
+import { wikiSyncController } from '../controllers/coc-master/wiki-sync.controller';
+
+const cocMasterRouter = new Hono();
+
+cocMasterRouter.post('/chat', chatController);
+cocMasterRouter.post('/wiki/sync', wikiSyncController);
+
+export { cocMasterRouter };

package/src/routes/comment.routes.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+
 import { addComment } from '../controllers/comment/add.controller';
 
 const commentRouter = new Hono();

package/src/services/coc.service.ts

@@ -0,0 +1,65 @@
+import type { Clan, ClanMember, ClanWar, ClanWarLog, Player } from '../types/coc';
+
+const COC_API_BASE = 'http://47.106.33.249:3000/v1';
+
+/**
+ * Clash of Clans API Service
+ *
+ * COC API requires a developer token for authentication.
+ * The token is provided by the player and passed via Authorization header.
+ */
+export class CocService {
+  private async fetchCoc<T>(endpoint: string, token: string): Promise<T> {
+    const [t, k] = token.split(':');
+    const response = await fetch(`${COC_API_BASE}${endpoint}`, {
+      headers: {
+        Authorization: `Bearer ${t}`,
+        'X-Proxy-Key': k,
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => 'Unknown error');
+      throw new Error(`COC API error (${response.status}): ${errorText}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /** Normalize player tag (ensure # prefix and URL encoding) */
+  private normalizeTag(tag: string): string {
+    const withHash = tag.startsWith('#') ? tag : `#${tag}`;
+    return encodeURIComponent(withHash);
+  }
+
+  /**
+   * Get player information including village, heroes, troops, spells, etc.
+   * @see https://developer.clashofclans.com/#/documentation
+   */
+  async getPlayer(playerTag: string, token: string): Promise<Player> {
+    return this.fetchCoc<Player>(`/players/${this.normalizeTag(playerTag)}`, token);
+  }
+
+  /** Get clan information by clan tag */
+  async getClan(clanTag: string, token: string): Promise<Clan> {
+    return this.fetchCoc<Clan>(`/clans/${this.normalizeTag(clanTag)}`, token);
+  }
+
+  /** Get clan war log */
+  async getClanWarLog(clanTag: string, token: string): Promise<ClanWarLog> {
+    return this.fetchCoc<ClanWarLog>(`/clans/${this.normalizeTag(clanTag)}/warlog`, token);
+  }
+
+  /** Get current war information for a clan */
+  async getCurrentWar(clanTag: string, token: string): Promise<ClanWar> {
+    return this.fetchCoc<ClanWar>(`/clans/${this.normalizeTag(clanTag)}/currentwar`, token);
+  }
+
+  /** Get clan members */
+  async getClanMembers(clanTag: string, token: string): Promise<ClanMember[]> {
+    return this.fetchCoc<ClanMember[]>(`/clans/${this.normalizeTag(clanTag)}/members`, token);
+  }
+}
+
+export const cocService = new CocService();