Konsole Kit

目标

• 为 Node 与浏览器提供一致的带标签彩色日志体验，降低调试成本。
• 提供 API 请求/响应、图片转 ASCII、字符 Logo 等附加输出，提升可读性与演示效果。
• 通过可定制的配色与标签策略，方便在团队或多环境间复用同一套输出规范。

使用场景

• 在 CLI 或浏览器 DevTools 中快速区分不同级别的日志，并保留时间戳/标签。
• 记录接口请求与响应，自动输出快照与完整对象，方便排查数据问题。
• 将图片或占位图转换为 ASCII，或在控制台打印项目 Logo 用于 demo/欢迎信息。
• 为监控脚本、SDK、浏览器插件等场景提供统一的日志包装层。

快速开始

npm install konsole-kit

import { konsole, createKonsole } from "konsole-kit";

// 直接使用默认实例
konsole.info("服务已启动", { env: "dev" });

// 创建带标签的自定义实例
const appLog = createKonsole({ label: "api", withTimestamp: true });
appLog.warn("流量激增", { requestId: "r-1001" });

// 可选：替换全局 console，让所有 console.* 都带标签
global.console = createKonsole({ label: "global", withTimestamp: true });
console.log("这条会带标签");
console.error("异常也会带标签");

// TypeScript 版（建议放到 src/global-konsole.d.ts，保证 tsconfig include）
import type { Konsole, KonsoleInstance } from "konsole-kit";
declare global {
  interface Console {
    success: Console["log"];
    logo: Konsole["logo"];
    api: Konsole["api"];
    image: Konsole["image"];
    updateOptions: Konsole["updateOptions"];
    updatePalette: Konsole["updatePalette"];
  }
  interface Window {
    console: Console;
  }
}
export {};

// 代码中直接赋值即可（Node 用 globalThis.console，浏览器用 window.console）
window.console = createKonsole({ label: "Block-AI", withTimestamp: true }) as KonsoleInstance;
window.console.logo("HELLO"); // 不再有 TS 告警

konsole 的方法介绍（包括各种 api 调用和效果）

• 导出：konsole（默认实例）、createKonsole(options?, baseConsole?)、Konsole 类。
• 选项：label（自定义标签）、withTimestamp（默认开启）、theme（默认 "dark"，用于深/浅色标签切换）、palette（覆盖配色，见下方 updatePalette）。
• theme 控制标签默认配色（方法标签、自定义标签、时间戳），可与 palette 叠加覆盖。

方法与参数一览（分表展示）

createKonsole / new Konsole

| 项 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | options | Partial<KonsoleOptions>（label?、withTimestamp?、uppercaseLabel?、palette?） | 否 | 合并默认配置后创建实例 | | baseConsole | Console | 否 | 自定义输出目标，默认全局 console | | 返回 | KonsoleInstance | - | 带代理的实例 |

KonsoleOptions 字段： | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | label | string | 否 | 自定义标签，追加在方法标签后 | | withTimestamp | boolean | 否 | 是否在标签中附加当前时间，默认 true | | uppercaseLabel | boolean | 否 | 是否强制标签大写（当前实现暂未使用，可按需扩展） | | theme | "dark" \| "light" | 否 | 标签主题，影响默认配色（方法标签/自定义标签/时间戳），可与 palette 叠加 | | palette | Partial<Palette> | 否 | 按等级覆盖配色；键为 log / info / success / warn / error / debug，值为 { fg: string; bg: string } |

默认实例 konsole

| 项 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | - | KonsoleInstance | - | 已使用全局 console 创建，直接导入使用 |

基础日志方法：log / info / debug / warn / error / trace

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | ...args | unknown[] | 可空 | 同原生 console 参数，输出时附加标签/时间戳 | | 返回 | void | - | 输出带标签日志 |

success

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | ...args | unknown[] | 可空 | 等价 console.log，使用 success 配色 | | 返回 | void | - | 输出带标签日志 |

api(payload, options?)

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | payload | unknown | 是 | 请求/响应内容，打印快照与对象 | | options.mode | "request" \| "response" | 否 | 默认 "request"，控制标签 REQ/RES | | options.tag | string | 否 | 额外标签，空白忽略 | | 返回 | void | - | 先标签行，后 JSON 快照，再原始对象 |

image(source, options?)

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | source | string \| URL | 是 | 图片来源 | | options.width | number | 否 | 输出宽度，默认 48 | | options.height | number | 否 | 输出高度，默认按宽度等比 | | options.fit | "box" \| "width" \| "height" \| "original" \| "none" | 否 | Node 使用 asciify-image 的 fit 选项，默认 width | | options.color | string | 否 | 单色输出时的颜色（浏览器整体着色；Node 作为 HEX -> ANSI 着色） | | options.ansiColor | boolean | 否 | Node 端是否启用依赖库的彩色 ASCII，默认 false | | options.cRatio | number | 否 | 字符宽高比，默认 2 | | options.tag | string | 否 | 额外标签，空白忽略 | | 返回 | Promise<void> | - | 输出 ASCII 文本 |

logo(text, fill?, color?)

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | text | string | 是 | 要渲染的文本 | | fill | string | 否 | 填充字符，仅取首字符，默认 # | | color | string | 否 | CSS/HEX 颜色，可选 | | 返回 | void | - | 输出字符 Logo（浏览器 CSS / Node ANSI） |

updateOptions(next)

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | next | Partial<KonsoleOptions> | 是 | 运行时更新标签/时间戳/大小写/配色 | | 返回 | void | - | 配置立即生效 |

updatePalette(partialPalette)

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | partialPalette | Partial<Palette> | 是 | 运行时覆盖配色，未提供的等级沿用当前配置 | | 返回 | void | - | 配色立即生效 |

基础日志方法

• 在实例上调用时，会代理 baseConsole（默认全局 console）的同名方法并附带标签，包含方法名 + 可选自定义标签 + 可选时间戳；浏览器使用 CSS 背景色，Node 使用 ANSI。不会自动修改全局 console。
• 额外提供 success 方法，配色同 success 等级。

const logger = createKonsole({ label: "web" });
logger.info("配置更新", { user: "Ada" });
logger.debug("状态检查", { flags: ["beta"] });
logger.error("捕获异常", new Error("boom"));

可选的全局替换示例（仅在你希望所有 console.* 都带标签时手动使用）：

import { createKonsole } from "konsole-kit";

global.console = createKonsole({ label: "global", withTimestamp: true });

console.log("这条会带标签");
console.warn("警告同样带标签");

api(payload, options)

• 用于输出接口请求/响应，自动附带 API + REQ/RES 标签，可再加自定义 tag。
• 行为：先打印标签行，再输出格式化快照（JSON 字符串），最后输出原始对象（console.dir）。

logger.api({ url: "/users", method: "GET" }, { mode: "request", tag: "users" });
logger.api({ status: 200, data: [] }, { mode: "response" });

image(source, options)

• 将图片链接/URL 转换为 ASCII 文本（浏览器用 canvas，Node 动态加载 asciify-image），并附带 IMAGE 标签；支持 width/height/fit/color/cRatio/tag。

await logger.image("https://placehold.co/160x100.png?text=Konsole", {
  width: 48,
  tag: "avatar"
});

logo(text, fill?, color?)

• 以字符绘制多行 Logo，fill 控制填充字符（默认 #），color 可选（浏览器 CSS / Node ANSI）。

logger.logo("KONSOLE", "*", "#0ea5e9");

updateOptions / updatePalette

• updateOptions 运行时调整标签、时间戳、主题等；切换 theme 会重置为对应主题的默认配色并叠加已有覆盖。updatePalette 在当前主题基础上增量覆盖颜色，未提供的等级会保留现有样式。
• 创建时也可通过 createKonsole({ palette: { info: { fg: "#0ea5e9" } } }) 传入，或传 theme: "light" 回到浅色标签。

logger.updateOptions({ label: "worker", withTimestamp: false, theme: "light" });
logger.updatePalette({
  warn: { fg: "#92400e", bg: "#fff4e5" },
  error: { fg: "#dc2626", bg: "#ffe4e6" }
});

本地开发

• 需求：Node >= 18，npm install 安装依赖。
• 构建与检查：npm run build（tsup 输出到 dist），npm run typecheck，npm run clean。
• 终端示例（先构建以生成 dist）：npm run terminal:basic（各级日志 + 更新配色 + Logo）、npm run terminal:logo（多组字符 Logo）、npm run terminal:api（API 请求/响应标签与快照）、npm run terminal:image（将本地 terminal/github-logo.png 转为 ASCII）。
• 浏览器示例：npm run web（默认 4173 端口），npm run web:build、npm run web:preview 用于静态产物与预览。