koishi-plugin-chatluna-studio 1.0.0

package/lib/presets/service.d.ts

@@ -0,0 +1,69 @@
+import { type StudioModelRequestStore } from '../model-request';
+import { type CreatePresetInput, type DeletePresetInput, type PresetRepository, type RenamePresetInput, type SavePresetInput } from './repository';
+import type { PresetDocumentKind, PresetSourceDiagnostic, PresetSourcePath, PresetSourceRange, PresetTemplateExpression, PresetTemplateField } from './types';
+export interface StudioPresetExpression extends PresetTemplateExpression {
+    stableId: string;
+}
+export interface StudioPresetDocument {
+    kind: PresetDocumentKind;
+    fileName: string;
+    displayName?: string;
+    source: string;
+    revision: string;
+    size: number;
+    modifiedAt: string;
+    templateFields: PresetTemplateField[];
+    expressions: StudioPresetExpression[];
+    diagnostics: PresetSourceDiagnostic[];
+}
+export interface ReadStudioPresetInput {
+    kind: PresetDocumentKind;
+    fileName: string;
+}
+export interface StudioPresetDocumentIdentity extends ReadStudioPresetInput {
+    revision: string;
+}
+export type StudioPresetExpressionIdentity = {
+    stableId: string;
+} | {
+    path: PresetSourcePath;
+    range: PresetSourceRange;
+    occurrence: number;
+};
+export interface LocateStudioPresetExpressionInput {
+    document: StudioPresetDocumentIdentity;
+    expression: StudioPresetExpressionIdentity;
+}
+export type StudioPresetLocateFailureCode = 'document-not-found' | 'document-stale' | 'document-identity-unavailable' | 'expression-not-found' | 'request-not-observed' | 'expression-stale' | 'expression-not-observed' | 'expression-ambiguous' | 'expression-unsupported';
+export type LocateStudioPresetExpressionResult = {
+    status: 'matched';
+    recordId: string;
+    evidenceId: string;
+    range: PresetSourceRange;
+} | {
+    status: 'failed';
+    code: StudioPresetLocateFailureCode;
+    message: string;
+    reason?: 'control-tag' | 'template-field';
+};
+export interface StudioPresetServiceOptions {
+    baseDir: string;
+    modelRequests: StudioModelRequestStore;
+    repository?: PresetRepository;
+}
+export declare class StudioPresetService {
+    private readonly options;
+    private readonly repository;
+    constructor(options: StudioPresetServiceOptions);
+    catalog(kind?: PresetDocumentKind): Promise<StudioPresetDocument[]>;
+    read(input: ReadStudioPresetInput): Promise<StudioPresetDocument>;
+    create(input: CreatePresetInput): Promise<StudioPresetDocument>;
+    save(input: SavePresetInput): Promise<StudioPresetDocument>;
+    rename(input: RenamePresetInput): Promise<StudioPresetDocument>;
+    delete(input: DeletePresetInput): Promise<{
+        deleted: true;
+    }>;
+    locateExpression(input: LocateStudioPresetExpressionInput): Promise<LocateStudioPresetExpressionResult>;
+    private present;
+}
+export declare function expressionStableId(expression: Pick<PresetTemplateExpression, 'path' | 'occurrence'>): string;

package/lib/presets/source-document.d.ts

@@ -0,0 +1,2 @@
+import type { PresetDocumentKind, PresetSourceDocument } from './types';
+export declare function parsePresetSourceDocument(kind: PresetDocumentKind, source: string): PresetSourceDocument;

package/lib/presets/types.d.ts

@@ -0,0 +1,63 @@
+import type { StudioPresetRuntimeSnapshot, StudioPresetRuntimeTemplate, StudioPresetTemplateRole } from '../types';
+export type PresetDocumentKind = 'core' | 'character';
+export type PresetRuntimeSnapshot = StudioPresetRuntimeSnapshot;
+export type PresetRuntimeTemplate = StudioPresetRuntimeTemplate;
+export type PresetTemplateRole = StudioPresetTemplateRole;
+export type PresetSourcePath = readonly (string | number)[];
+export interface PresetSourceRange {
+    start: number;
+    end: number;
+}
+export type PresetTemplateExpressionKind = 'value' | 'control';
+export interface PresetTemplateExpression {
+    path: PresetSourcePath;
+    range: PresetSourceRange;
+    content: string;
+    kind: PresetTemplateExpressionKind;
+    clickable: boolean;
+    occurrence: number;
+}
+export interface PresetTemplateField {
+    path: PresetSourcePath;
+    range: PresetSourceRange;
+    value: string;
+}
+export type PresetSourceDiagnosticCode = 'yaml-parse-error' | 'template-field-not-string';
+export interface PresetSourceDiagnostic {
+    code: PresetSourceDiagnosticCode;
+    message: string;
+    severity: 'error';
+    path?: PresetSourcePath;
+    range?: PresetSourceRange;
+}
+export interface PresetSourceDocument {
+    kind: PresetDocumentKind;
+    source: string;
+    displayName?: string;
+    templateFields: PresetTemplateField[];
+    expressions: PresetTemplateExpression[];
+    diagnostics: PresetSourceDiagnostic[];
+}
+/**
+ * 一次对话轮的归属目标。
+ *
+ * 真实环境里（机器人，会话）就是完整身份，不再有把同一对参与者分到不同记录域的空间概念。
+ */
+export interface PresetRuntimeSessionTarget {
+    botId: string;
+    conversationId: string;
+}
+export type PresetEvidenceMatchResult = {
+    status: 'matched';
+    evidenceId: string;
+    range: PresetSourceRange;
+} | {
+    status: 'stale';
+} | {
+    status: 'not-observed';
+} | {
+    status: 'ambiguous';
+} | {
+    status: 'unsupported';
+    reason: 'control-tag' | 'template-field';
+};

package/lib/record-store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 证据记录行库的共享机制。OneBot 调试记录与模型请求记录都按行持久化，两者的
+ * 「作用域摘要 + 按最旧回收」和「串行写入队列」语义完全一致，差异只在记录类型与过滤谓词；
+ * 这些机制放在这里，内存适配器、数据库适配器与两个 Store 共用同一份实现。
+ */
+export interface StudioRecordScopeSummary {
+    /** 作用域内下一个可用序号；不因回收或清理而回退。 */
+    nextSequence: number;
+    recordCount: number;
+    /** 全部记录完整持久化内容的字节数之和。 */
+    totalBytes: number;
+    earliestSequence?: number;
+}
+export interface StudioRecordCapacityLimits {
+    maxRecords: number;
+    maxBytes: number;
+}
+/**
+ * 作用域行索引：只保存每行的序号与体积。容量统计与回收决策只需要这两列，缓存后追加
+ * 就不必回表统计，否则「一次追加一行」会换来「一次追加扫一遍元数据」。
+ * 每个作用域只有一个适配器实例在写，索引因此可以作为权威值维护。
+ */
+export declare class ScopeRowIndex {
+    private rows;
+    private nextSequence;
+    reset(rows: Array<{
+        sequence: number;
+        bytes: number;
+    }>, persistedNextSequence: number): void;
+    put(sequence: number, bytes: number, nextSequence?: number): void;
+    has(sequence: number): boolean;
+    clear(nextSequence: number): void;
+    /** 从最旧开始试算，返回需要一并删除的最大序号；索引在删除成功后才由 dropThrough 收敛。 */
+    resolveCutoff(limits: StudioRecordCapacityLimits): number | undefined;
+    dropThrough(cutoff: number): void;
+    readNextSequence(): number;
+    summary(): StudioRecordScopeSummary;
+    private totalBytes;
+}
+export interface StudioRecordRowsQuery {
+    order: 'asc' | 'desc';
+    limit: number;
+}
+interface StudioRecordRow {
+    id: string;
+    sequence: number;
+}
+/**
+ * 进程内记录行库。内存持久化模式与数据库不可用时的降级路径共用这一份语义，
+ * 容量与回收决策复用 ScopeRowIndex，因此与数据库适配器给出一致的摘要。
+ */
+export declare class InMemoryRecordRows<Record extends StudioRecordRow, Query extends StudioRecordRowsQuery> {
+    private matches;
+    private bodies;
+    private index;
+    constructor(matches: (record: Record, query: Query) => boolean);
+    summarize(): Promise<StudioRecordScopeSummary>;
+    append(record: Record, bytes: number, nextSequence: number): Promise<StudioRecordScopeSummary>;
+    find(recordId: string): Promise<Record | undefined>;
+    replace(record: Record, bytes: number): Promise<StudioRecordScopeSummary>;
+    query(query: Query): Promise<Record[]>;
+    /**
+     * 只读出记录的一部分。投影先在存有的行上执行，再拷贝投影结果，因此读取路径不需要的子树
+     * （模型请求的请求体与响应原文）既不会被深拷贝，也不会被交给调用方。
+     */
+    queryProjected<Projected>(query: Query, project: (record: Record) => Projected): Promise<Projected[]>;
+    private select;
+    reclaim(limits: StudioRecordCapacityLimits): Promise<StudioRecordScopeSummary>;
+    clear(nextSequence: number): Promise<StudioRecordScopeSummary>;
+}
+/**
+ * 串行写入队列。所有写入都排在首次恢复之后并依次执行，读取等待同一条队列稳定，
+ * 因此读取总能看到已提交状态，而 append 仍可以同步返回记录。
+ */
+export declare class SerialWriteQueue {
+    private ready;
+    private queue;
+    constructor(ready: Promise<void>);
+    /** 队列任务可能在等待期间继续追加（例如 append 之后的容量回收），必须等到队列稳定。 */
+    settle(): Promise<void>;
+    /** 写入失败不能变成未处理的 Promise 拒绝：证据落盘是旁路能力，不应影响调用方。 */
+    push(task: () => Promise<void>): void;
+    run<T>(task: () => Promise<T>): Promise<T>;
+}
+export {};

package/lib/types.d.ts

@@ -0,0 +1,270 @@
+import type { StudioEvidenceCompositionKind, StudioEvidenceKind } from './evidence-kind';
+export type StudioPersistenceMode = 'memory' | 'database';
+export interface StudioPersistenceStatus {
+    mode: StudioPersistenceMode;
+    available: boolean;
+    persisted: boolean;
+    message?: string;
+}
+/** 工作室外观：颜色模式、强调色、毛玻璃与头像来源，由插件全局配置统一控制。 */
+export interface StudioAppearance {
+    enableStudioFrostedGlass: boolean;
+    studioColorMode: 'auto' | 'light' | 'dark';
+    studioAccentColor: string;
+    /** 开启时列表与详情向 QQ 头像 CDN 取真实头像；关闭时只用首字母色块，不发起外部请求。 */
+    studioUseQQAvatars: boolean;
+}
+/**
+ * 可预期的领域业务拒绝：参数不合法、实体不存在、游标过期这类由领域规则主动作出的判定。
+ *
+ * 它存在的唯一理由是让上层能把「领域说不」与「实现出错」分开：Console 端点把领域拒绝的消息
+ * 原样透出给前端，而基础设施故障（数据库不可用）与内部不变量违背不属于此类，应继续抛普通 `Error`。
+ */
+export declare class StudioDomainError extends Error {
+    constructor(message: string);
+}
+export declare class StudioModelRequestCursorExpiredError extends StudioDomainError {
+    readonly earliestCursor?: number | undefined;
+    readonly code: "cursor_expired";
+    constructor(message: string, earliestCursor?: number | undefined);
+}
+export type StudioModelRequestStatus = 'pending' | 'success' | 'error';
+export type StudioModelResponseBodyStatus = 'pending' | 'complete' | 'unavailable' | 'error';
+export type StudioModelResponseBodyFormat = 'json' | 'text' | 'sse';
+export type StudioModelRequestAttribution = 'attributed' | 'unattributed';
+export interface StudioModelRequestError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    traceId: string;
+}
+export interface StudioChatLunaRequestError {
+    code?: number;
+    message?: string;
+    originMessage?: string;
+    isTimeout?: boolean;
+}
+/**
+ * 一条模型请求归属到的真实 OneBot 会话。
+ *
+ * 名称随请求一起快照，而不是读取时再查目录：群名与昵称会变，而记录要能复盘当时的现场；
+ * 会话被解散或机器人下线后，目录里也已经查不到它们。
+ */
+export interface StudioModelRequestEntities {
+    platform?: string;
+    botId?: string;
+    botName?: string;
+    conversationId?: string;
+    conversationName?: string;
+    conversationType?: StudioConversationType;
+    guildId?: string;
+    userId?: string;
+    userName?: string;
+}
+/** 私聊与群聊是真实 OneBot 会话的全部形态；频道等其他平台概念不在本插件范围内。 */
+export type StudioConversationType = 'private' | 'group';
+export type StudioPresetDocumentKind = 'core' | 'character';
+export type StudioPresetTemplateRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface StudioPresetRuntimeTemplate {
+    path: readonly (string | number)[];
+    role: StudioPresetTemplateRole;
+    template: string;
+}
+export interface StudioPresetRuntimeSnapshot {
+    kind: StudioPresetDocumentKind;
+    presetName: string;
+    capturedAt: string;
+    source?: string;
+    templates: readonly StudioPresetRuntimeTemplate[];
+}
+export interface StudioPresetRuntimeSnapshotSummary {
+    kind: StudioPresetDocumentKind;
+    presetName: string;
+    capturedAt: string;
+    templateCount: number;
+}
+export type StudioModelRequestVariableStatus = 'observed' | 'stale' | 'not-observed' | 'ambiguous' | 'unsupported';
+export interface StudioModelRequestVariable {
+    id: string;
+    name: string;
+    presetKind: StudioPresetDocumentKind;
+    presetName: string;
+    path: readonly (string | number)[];
+    occurrence: number;
+    status: StudioModelRequestVariableStatus;
+    value?: string;
+    evidenceId?: string;
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * 一条模型请求记录被共享模型证据投影读出的计数。
+ *
+ * 两个字段都是投影派生事实，与模型请求对话视图、模型请求轨迹使用完全相同的消息边界和工具展平规则。
+ * 原始请求体的字段数与模型名称不属于这里：它们不是协议事实，见 StudioModelRequestDetail。
+ */
+export interface StudioModelEvidenceCounts {
+    requestMessageCount: number;
+    toolDefinitionCount: number;
+}
+export interface StudioModelRequestUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+    totalTokens?: number;
+    ttftMs?: number;
+    totalMs?: number;
+    tps?: number;
+    estimated?: boolean;
+    source: 'chatluna-usage' | 'response';
+}
+export interface StudioModelRequestRecord {
+    id: string;
+    sequence: number;
+    createdAt: string;
+    status: StudioModelRequestStatus;
+    durationMs: number;
+    method?: string;
+    url?: string;
+    provider?: string;
+    model?: string;
+    headers?: Record<string, string>;
+    attribution: StudioModelRequestAttribution;
+    entities: StudioModelRequestEntities;
+    requestBodyAvailable: boolean;
+    requestBody?: unknown;
+    responseBodyStatus: StudioModelResponseBodyStatus;
+    responseBodyFormat?: StudioModelResponseBodyFormat;
+    responseStatus?: number;
+    responseBodyRaw?: string;
+    responseBodyError?: string;
+    interactionId?: string;
+    chatlunaRequestId?: string;
+    presetSnapshots?: readonly StudioPresetRuntimeSnapshot[];
+    usage?: StudioModelRequestUsage;
+    error?: StudioModelRequestError;
+    chatlunaError?: StudioChatLunaRequestError;
+}
+export type StudioModelRequestListItem = Omit<StudioModelRequestRecord, 'requestBody' | 'responseBodyRaw' | 'presetSnapshots'> & {
+    presetSnapshotSummaries?: readonly StudioPresetRuntimeSnapshotSummary[];
+};
+export type StudioModelRequestDetail = StudioModelRequestRecord & {
+    /** 原始请求体的顶层键数量。这是原始 JSON 事实而不是投影产物；请求体未采集或不是对象时缺省。 */
+    requestBodyKeyCount?: number;
+    /** 共享模型证据投影派生的计数。请求体未采集时缺省，采集到但不是对象时两项均为 0。 */
+    evidenceCounts?: StudioModelEvidenceCounts;
+    variables: readonly StudioModelRequestVariable[];
+};
+export interface GetStudioModelRequestRecordsInput {
+    attribution?: StudioModelRequestAttribution;
+    botId?: string;
+    conversationId?: string;
+    interactionId?: string;
+    model?: string;
+    errorsOnly?: boolean;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    beforeSequence?: number;
+    beforeCreatedAt?: string;
+    beforeId?: string;
+}
+export interface StudioModelRequestCapacity {
+    recordCount: number;
+    totalBytes: number;
+    maxRecords: number;
+    maxBytes: number;
+}
+export interface StudioModelRequestRecordsPage<T extends StudioModelRequestListItem = StudioModelRequestListItem> {
+    records: T[];
+    hasMore: boolean;
+    nextCursor?: number;
+    nextCreatedAt?: string;
+    nextId?: string;
+    earliestCursor?: number;
+    capacity: StudioModelRequestCapacity;
+}
+/**
+ * 轨迹账本的行种类：一维基础证据种类，外加视图特有的请求边界行。
+ *
+ * 请求边界不是证据，而是「一次模型请求从这里开始」的结构标记；
+ * 隐藏全部证据种类后仍要能看出有哪些请求，因此它不并入基础证据种类。
+ */
+export type StudioModelRequestTrajectoryKind = StudioEvidenceKind | 'request';
+export interface StudioModelRequestTrajectoryRow {
+    id: string;
+    index: number;
+    kind: StudioModelRequestTrajectoryKind;
+    preview: string;
+    /** 模型证据投影身份。请求边界行没有对应的原始模型证据，因此不带此字段。 */
+    evidenceId?: string;
+    callId?: string;
+    toolName?: string;
+    variableId?: string;
+    variableName?: string;
+    variablePresetName?: string;
+    variableStatus?: StudioModelRequestVariableStatus;
+    variableValue?: string;
+    source?: 'request' | 'response';
+    durationMs?: number;
+    startedAt?: string;
+    requestId?: string;
+    status?: StudioModelRequestStatus;
+}
+/** 请求组成项的种类：基础证据种类的子集加工具交互聚合，聚合成员由证据种类 module 声明。 */
+export type StudioModelRequestPromptKind = StudioEvidenceCompositionKind;
+export interface StudioModelRequestPromptCompositionItem {
+    kind: StudioModelRequestPromptKind;
+    /** 点击组成分段时定位的轨迹行身份；变量片段使用变量证据身份。 */
+    evidenceId: string;
+    characters: number;
+    variableId?: string;
+    variableName?: string;
+    requestId?: string;
+}
+export interface StudioModelRequestTrajectory {
+    mode: 'request' | 'conversation';
+    conversationId?: string;
+    records: readonly StudioModelRequestListItem[];
+    rows: readonly StudioModelRequestTrajectoryRow[];
+    promptComposition: readonly StudioModelRequestPromptCompositionItem[];
+    complete: boolean;
+}
+export interface GetStudioModelRequestRecordInput {
+    recordId: string;
+}
+export interface ClearStudioModelRequestRecordsResult {
+    cleared: number;
+}
+/**
+ * 记录读取的归属范围。
+ *
+ * 全部记录住在同一个记录库里，范围只是一道归属过滤：真实环境没有互相隔离的记录域，
+ * 「未归属」也不是另一个库，而是采集时无法判定是哪一个会话在请求模型的那些记录。
+ */
+export type StudioModelRequestScope = {
+    scope: 'all' | 'attributed' | 'unattributed';
+};
+export type ListStudioModelRequestRecordsInput = StudioModelRequestScope & GetStudioModelRequestRecordsInput;
+export type ReadStudioModelRequestRecordInput = GetStudioModelRequestRecordInput;
+export type ReadStudioModelRequestTrajectoryInput = {
+    recordId: string;
+    mode: 'request' | 'conversation';
+};
+/** 筛选下拉的可选值，由记录库里已经出现过的机器人、会话与模型聚合而成。 */
+export interface StudioModelRequestFacets {
+    bots: readonly {
+        id: string;
+        name?: string;
+        platform?: string;
+    }[];
+    conversations: readonly {
+        id: string;
+        name?: string;
+        type?: StudioConversationType;
+        botId?: string;
+    }[];
+    models: readonly string[];
+}

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "koishi-plugin-chatluna-studio",
+  "description": "在 Koishi 控制台中查看 ChatLuna 真实模型请求并编辑预设",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#client/*": "./client/*"
+  },
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "homepage": "https://github.com/Sor85/koishi-plugin-chatluna-studio",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sor85/koishi-plugin-chatluna-studio.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "shx rm -rf lib dist",
+    "build": "yarn clean && yarn build:server && yarn build:client",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "build:server": "yarn build:types && tsup src/index.ts --format cjs --out-dir lib --clean false",
+    "watch:server": "node scripts/watch-server.mjs",
+    "build:client": "yarn build:css && vite build",
+    "build:css": "node scripts/build-css.mjs",
+    "typecheck": "vue-tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "yarn test && yarn typecheck && yarn build"
+  },
+  "keywords": [
+    "chatbot",
+    "chatluna",
+    "koishi",
+    "onebot",
+    "preset"
+  ],
+  "koishi": {
+    "browser": true,
+    "public": [
+      "dist"
+    ],
+    "description": {
+      "zh": "查看 ChatLuna 真实模型请求并编辑预设"
+    },
+    "service": {
+      "required": [
+        "console"
+      ],
+      "optional": [
+        "database"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@koishijs/plugin-console": "^5.30.11",
+    "koishi": "^4.18.10",
+    "koishi-plugin-chatluna": "*"
+  },
+  "peerDependenciesMeta": {
+    "koishi-plugin-chatluna": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.9",
+    "@koishijs/console": "^5.30.11",
+    "codemirror": "^6.0.2",
+    "fast-xml-parser": "^5.3.6",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@koishijs/client": "^5.30.11",
+    "@koishijs/core": "^4.18.10",
+    "@koishijs/plugin-console": "^5.30.11",
+    "@tabler/icons-vue": "^3.45.0",
+    "@tailwindcss/cli": "^4.3.3",
+    "@types/node": "^24.0.0",
+    "@vitejs/plugin-vue": "^6.0.2",
+    "@vueuse/core": "^14.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "koishi": "^4.18.10",
+    "postcss": "8.5.19",
+    "reka-ui": "^2.10.1",
+    "shx": "^0.4.0",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.1.11",
+    "tsup": "^8.0.0",
+    "typescript": "5.7.2",
+    "vite": "^6.0.0",
+    "vitest": "^3.2.4",
+    "vue": "^3.5.21",
+    "vue-tsc": "^3.0.0"
+  },
+  "packageManager": "yarn@4.15.0"
+}