{"id":11216,"library":"koishi","title":"Koishi Chatbot Framework","description":"Koishi is an extensible, cross-platform chatbot framework for Node.js, currently at version 4.18.11. It facilitates the development of intelligent bots that can operate across various chat platforms like Discord and Telegram. The project maintains a rapid release cadence, with frequent patch and minor updates, ensuring timely integration of new features and bug fixes. A core differentiator is its reliance on the Satori Protocol for cross-platform interoperability, standardizing message parsing and event handling. Koishi emphasizes extensibility through a robust plugin system and a declarative command-line interface, enabling developers to build complex bot functionalities with a modular approach. It ships with full TypeScript support, providing strong typing for better developer experience and code maintainability.","status":"active","version":"4.18.11","language":"javascript","source_language":"en","source_url":"https://github.com/koishijs/koishi","tags":["javascript","bot","chatbot","discord","telegram","cordis","framework","typescript"],"install":[{"cmd":"npm install koishi","lang":"bash","label":"npm"},{"cmd":"yarn add koishi","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Koishi is designed for ES modules; CommonJS `require` might lead to issues in modern setups. Use named imports for core classes.","wrong":"const Koishi = require('koishi')","symbol":"Koishi","correct":"import { Koishi } from 'koishi'"},{"note":"The `Context` class is fundamental for creating plugins and managing application scope.","symbol":"Context","correct":"import { Context } from 'koishi'"},{"note":"The `h` function is used for creating message elements with a JSX-like syntax, enabling rich message formatting across platforms.","symbol":"h","correct":"import { h } from 'koishi'"},{"note":"Schema is used for defining plugin configurations and ensuring type safety and validation.","symbol":"Schema","correct":"import { Schema } from 'koishi'"}],"quickstart":{"code":"import { Context, Schema, h, Koishi } from 'koishi';\n// In a real project, you would import and configure an adapter like:\n// import '@koishijs/adapter-discord';\n\n// Define a simple plugin\nclass MyHelloPlugin extends Context.Plugin {\n  static schema = Schema.object({\n    greeting: Schema.string().default('Hello').description('The greeting message.')\n  });\n\n  constructor(ctx: Context, config: { greeting: string }) {\n    super(ctx, config);\n\n    // Register a command\n    ctx.command('greet <target:string>', 'Greets someone')\n      .action(({ session }, target) => {\n        if (!target) return 'Please tell me who to greet!';\n        // Use h (Hyperscript) for rich message formatting, if supported by adapter\n        return h('message', [\n          h('text', `${config.greeting}, `),\n          h('at', { id: session?.userId || 'unknown' }), // Placeholder for @mention\n          h('text', ` ${target}! `)\n        ]);\n      });\n\n    // Register a simple listener\n    ctx.on('message', (session) => {\n      if (session.content === 'ping') {\n        session.send('pong');\n      }\n    });\n\n    ctx.logger.info('MyHelloPlugin loaded!');\n  }\n}\n\nasync function main() {\n  const app = new Koishi({\n    prefix: '.', // Command prefix\n    port: 8080, // WebUI port, if enabled\n    // The `plugins` object is where you configure adapters and other plugins.\n    // For this quickstart, we'll define a dummy adapter for demonstration.\n    // In a real app, you'd install and configure e.g., `@koishijs/adapter-discord`.\n    plugins: {\n      'my-hello-plugin': { // Directly add the plugin to the config\n        greeting: 'Hey there'\n      }\n      // Example of an actual adapter config (uncomment and replace with real token/platform):\n      // '@koishijs/adapter-discord': {\n      //   token: process.env.DISCORD_TOKEN || 'YOUR_DISCORD_BOT_TOKEN',\n      //   intents: 32767 // Or specific intents\n      // }\n    }\n  });\n\n  // Manually register the plugin class (usually done via `app.plugin()` or config)\n  app.plugin(MyHelloPlugin);\n\n  try {\n    await app.start();\n    console.log('Koishi application started. Listening for commands.');\n    console.log('Try to run a command like \".greet World\" if an adapter is configured and connected.');\n  } catch (error) {\n    console.error('Failed to start Koishi:', error);\n    console.warn('Ensure you have installed and configured at least one adapter (e.g., @koishijs/adapter-discord) ' +\n                 'and provided a valid token in the plugins config if you want to connect to a chat platform.');\n  }\n}\n\nmain();","lang":"typescript","description":"This quickstart demonstrates how to initialize a Koishi application, register a custom plugin, define a command, and set up a simple message listener. It highlights the use of `Context` for plugin development, `Schema` for configuration, and `h` for message formatting. A note on adapter configuration is included for a fully functional bot."},"warnings":[{"fix":"Review adapter and plugin code to align with Satori Protocol v1.2/v1.3 changes, especially for event data structures (`subsubtype` removal, `id` to `sn`) and internal routing paths.","message":"The Satori Protocol received significant updates in Koishi 4.18.5 (v1.2) and 4.18.11 (v1.3), which include breaking changes. Specifically, the `subsubtype` field was removed from events, and event `id` fields were renamed to `sn`. Internal routing protocol names were also renamed from `satori` to `internal`.","severity":"breaking","affected_versions":">=4.18.5"},{"fix":"Update existing command definitions and alias usages, replacing underscores with hyphens. Test command parsing thoroughly after upgrading.","message":"In Koishi 4.17.12, command aliases with arguments were fixed, and command names containing underscores (`_`) are now uniformly replaced with hyphens (`-`) and support fuzzy matching. This might alter the expected behavior or recognition of existing commands and their aliases.","severity":"gotcha","affected_versions":">=4.17.12"},{"fix":"Review any direct `minato` database interactions, especially those touching `_fields` or schema definitions, and adjust according to `minato`'s latest documentation.","message":"Version 4.18.10 includes a refactor of `_fields` in `minato`. If your application directly interacts with `minato`'s database layer at a low level or relies on internal `_fields` behavior, this could be a breaking change.","severity":"breaking","affected_versions":">=4.18.10"},{"fix":"Remove any usage of `event.subsubtype` from your event handlers. Refer to Satori Protocol documentation for updated event structures.","message":"The `subsubtype` field was removed from Satori events in version 4.18.11.","severity":"deprecated","affected_versions":">=4.18.11"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Migrate your project to use ES module `import`/`export` syntax. Ensure your `package.json` has `\"type\": \"module\"`.","cause":"Attempting to use CommonJS `require()` syntax in an ES module project (e.g., Node.js with `\"type\": \"module\"` or `.mjs` files). Koishi is primarily ESM-focused.","error":"ReferenceError: require is not defined"},{"fix":"Ensure the command or listener is invoked in a context where a valid `session` object with a connected adapter is available. Check that your Koishi instance has at least one adapter configured and successfully connected to a platform.","cause":"Attempting to send a message from a `session` object where `session.send` is undefined, often because the session is not associated with a valid adapter or the event context does not support sending messages.","error":"TypeError: Cannot read properties of undefined (reading 'send')"}],"ecosystem":"npm"}