tavern-harness 0.1.0

package/src/core/stats.ts

@@ -0,0 +1,91 @@
+import { db } from '../db/database';
+import type { ChatMessage } from '../types/models';
+import { checkAchievementUnlocks } from './achievements';
+
+// ============================================================
+// 生涯统计（append-only）与工具函数
+// ============================================================
+
+interface StatsDelta {
+  inputTokens: number;
+  outputTokens: number;
+  rounds: number;
+  npcRounds?: { npcId: number; npcName: string; rounds: number };
+}
+
+/** 消息产生后累计到生涯统计（服务器关闭也不丢失：已持久化消息带 usage） */
+export async function accumulateStats(delta: StatsDelta, sessionId: number | null, _npcId: number | null): Promise<void> {
+  if (delta.inputTokens <= 0 && delta.outputTokens <= 0 && delta.rounds <= 0) return;
+  const stats = (await db.careerStats.get(1)) ?? { id: 1, inputTokens: 0, outputTokens: 0, totalRounds: 0 };
+  await db.careerStats.put({
+    ...stats,
+    inputTokens: stats.inputTokens + delta.inputTokens,
+    outputTokens: stats.outputTokens + delta.outputTokens,
+    totalRounds: stats.totalRounds + delta.rounds,
+  });
+  if (delta.npcRounds && delta.npcRounds.rounds > 0) {
+    const existing = await db.careerNpcStats.get(delta.npcRounds.npcId);
+    if (existing) {
+      await db.careerNpcStats.update(delta.npcRounds.npcId, {
+        rounds: existing.rounds + delta.npcRounds.rounds,
+      });
+    } else {
+      await db.careerNpcStats.add({
+        npcId: delta.npcRounds.npcId,
+        npcName: delta.npcRounds.npcName,
+        rounds: delta.npcRounds.rounds,
+      });
+    }
+  }
+  void sessionId;
+
+  // 成就检测（基于累计 Token 数）
+  await checkAchievementUnlocks();
+}
+
+export async function getCareerStats() {
+  const stats = (await db.careerStats.get(1)) ?? { id: 1, inputTokens: 0, outputTokens: 0, totalRounds: 0 };
+  const npcStats = await db.careerNpcStats.toArray();
+  const sessions = await db.sessions.count();
+  return { ...stats, npcStats, sessionCount: sessions };
+}
+
+export async function resetCareerStats(): Promise<void> {
+  await db.careerStats.put({ id: 1, inputTokens: 0, outputTokens: 0, totalRounds: 0 });
+  await db.careerNpcStats.clear();
+}
+
+
+/** 从消息内容剥离思考标签，用于列表预览 */
+function stripThinking(content: string): string {
+  return content
+    .replace(/<thinking>[\s\S]*?<\/thinking>/g, '')
+    .replace(/\b(?:thinking|reasoning|思考)\s*[:\-＝=][\s\S]*?(?=\n\s*(?:<\/?(?:thinking|reasoning|think)>|\S))/gi, '')
+    .replace(/<\/?(?:thinking|reasoning|think)>/gi, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function sessionPreviewText(content: string, maxLength = 60): string {
+  const stripped = stripThinking(content).replace(/\s+/g, ' ').trim();
+  return stripped.length > maxLength ? stripped.slice(0, maxLength) + '…' : stripped;
+}
+
+// ============================================================
+// 消息指标（tokens/s 估算）
+// ============================================================
+
+export function estimateTokensFromChars(chars: number): number {
+  return Math.max(1, Math.round(chars / 3.8));
+}
+
+export function formatMetrics(m: Pick<ChatMessage, 'latencyMs' | 'tokensPerSec' | 'promptTokens' | 'completionTokens'>): string {
+  const parts: string[] = [];
+  if (m.latencyMs != null) parts.push(`⏱️ ${m.latencyMs}ms`);
+  if (m.tokensPerSec != null) parts.push(`⚡ ${m.tokensPerSec.toFixed(1)} t/s`);
+  if (m.promptTokens > 0 || m.completionTokens > 0) {
+    parts.push(`📥 ${m.promptTokens}`);
+    parts.push(`📤 ${m.completionTokens}`);
+  }
+  return parts.join(' | ');
+}

package/src/core/strings.ts

@@ -0,0 +1,19 @@
+export function trimEdgeNewlines(text: string): string {
+  return text.replace(/^(?:\r?\n)+|(?:\r?\n)+$/g, '');
+}
+
+export function idToKey(id: string): string {
+  return id.replace(/-([a-z])/g, (_, character: string) => character.toUpperCase());
+}
+
+export function prettyJson(text: string): string {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+
+export function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/core/toolDefinitions.ts

@@ -0,0 +1,400 @@
+import type { ChatCompletionTool } from '../types/models';
+
+export const MAX_TOOL_CALL_DEPTH = 10;
+export const MAX_TOOL_CALLS_PER_TURN = 20;
+export const MAX_IDENTICAL_TOOL_CALLS = 3;
+export const MAX_CONSECUTIVE_TOOL_FAILURES = 3;
+export const NEW_TOPIC_MARKER = '开始新话题';
+
+export const BUILTIN_TOOL_NAMES = [
+  'run_shell_script',
+  'roll_dice',
+  'file_read',
+  'file_write',
+  'file_edit',
+  'create_skill',
+  'update_skill',
+  'delete_skill',
+  'get_tavern_info',
+  'get_character_info',
+  'get_lorebook_info',
+  'file_display',
+  'create_character',
+  'update_character',
+  'delete_character',
+  'create_conversation',
+  'create_lorebook',
+  'update_lorebook',
+  'delete_lorebook',
+] as const;
+
+const fn = (name: string, description: string, parameters: Record<string, unknown>): ChatCompletionTool => ({
+  type: 'function',
+  function: { name, description, parameters },
+});
+
+export const BUILTIN_TOOLS: ChatCompletionTool[] = [
+  fn(
+    'run_shell_script',
+    'Execute commands through the controlled local command service to process files, run code, or perform system operations on the user\'s machine. This is not an OS sandbox.',
+    {
+      type: 'object',
+      properties: {
+        script: {
+          type: 'string',
+          maxLength: 8000,
+          description: 'Local command script (max 20 commands). Supports newlines, &&, ||, and ;. Allowlisted commands run directly; every other command requires user confirmation. Pipes, redirects, and expansion are unsupported. Lines starting with # are ignored. Non-interactive only.',
+        },
+      },
+      required: ['script'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'roll_dice',
+    'Roll dice for tabletop RPG. Supports expressions like d20, 2d6, 3d10+2. Natural 20 / natural 1 on a single d20 are reported as critical success/failure.',
+    {
+      type: 'object',
+      properties: {
+        expression: {
+          type: 'string',
+          description: "Dice expression, e.g. 'd20', '2d6', '3d10+2'",
+        },
+      },
+      required: ['expression'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'file_read',
+    'Read an existing text file from the current conversation workspace.',
+    {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path inside the current conversation workspace. Absolute paths and parent traversal are rejected. The file must exist.',
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'file_write',
+    'Create, overwrite, or append to a file in the current conversation workspace.',
+    {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path inside the current conversation workspace. Absolute paths and parent traversal are rejected. public link is read-only in normal sessions.',
+        },
+        content: {
+          type: 'string',
+          description: 'File content as a string.',
+        },
+        append: {
+          type: 'boolean',
+          description: 'Append to existing file instead of overwriting.',
+        },
+      },
+      required: ['path', 'content'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'file_edit',
+    'Replace exact text in an existing file. Prefer this over file_write for small code changes.',
+    {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path inside the current conversation workspace. Absolute paths and parent traversal are rejected. The file must exist. The public link is read-only in normal sessions.',
+        },
+        old_text: {
+          type: 'string',
+          minLength: 1,
+          description: 'Exact text to replace, including whitespace and indentation.',
+        },
+        new_text: {
+          type: 'string',
+          description: 'Replacement text. Use an empty string to delete old_text.',
+        },
+        expected_replacements: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          default: 1,
+          description: 'Required number of exact matches. Defaults to 1.',
+        },
+      },
+      required: ['path', 'old_text', 'new_text'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'create_skill',
+    'Create a new generated skill (tool) usable by characters. The skill is defined by a declarative execution schema. New skill is NOT enabled for any character until you enable it via update_character.',
+    {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          pattern: '^[a-z][a-z0-9_]*$',
+          minLength: 3,
+          maxLength: 40,
+          description: 'Lowercase snake_case skill name, 3-40 chars',
+        },
+        description: { type: 'string', maxLength: 500 },
+        parameters: {
+          type: 'object',
+          description: 'JSON Schema parameter object (must be type: object with properties)',
+        },
+        execution: {
+          type: 'object',
+          description: getExecutionDescription(),
+          additionalProperties: false,
+          required: ['type'],
+          properties: executionProperties(),
+        },
+      },
+      required: ['name', 'description', 'parameters', 'execution'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'update_skill',
+    'Update an existing generated skill (name, description, parameters or execution). Requires user confirmation. Built-in skills are protected.',
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Existing skill name' },
+        new_name: { type: 'string', pattern: '^[a-z][a-z0-9_]*$', minLength: 3, maxLength: 40 },
+        description: { type: 'string', maxLength: 500 },
+        parameters: { type: 'object' },
+        execution: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['type'],
+          properties: executionProperties(),
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'delete_skill',
+    'Delete a generated skill. Requires user confirmation. Built-in skills cannot be deleted.',
+    {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'get_tavern_info',
+    'Read-only snapshot of the tavern: characters, Lorebooks, skills and career statistics.',
+    {
+      type: 'object',
+      properties: {
+        fields: {
+          type: 'array',
+          items: { type: 'string', enum: ['characters', 'lorebooks', 'skills', 'career_stats'] },
+          minItems: 1,
+          uniqueItems: true,
+          description: 'Fields to include',
+        },
+      },
+      required: ['fields'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'get_character_info',
+    'Get the details of a character card by name.',
+    {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Existing character name' } },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'get_lorebook_info',
+    'Get the details of a Lorebook by name.',
+    {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Existing Lorebook name' } },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'file_display',
+    'Display any file from the current workspace to the user in a popup. Useful for inspecting existing files, reviewing generated output (reports, dashboards, images, HTML pages), or browsing the workspace content. Only shows the file in the UI — it does NOT return the file content; use file_read to actually read the content.',
+    {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path inside the current workspace. Must exist.',
+        },
+        title: {
+          type: 'string',
+          description: 'Optional popup title. Defaults to the file name.',
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'create_character',
+    'Create a new character (NPC) in the tavern. The character becomes available for NPC or group sessions.',
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string', minLength: 1, maxLength: 40 },
+        greeting: { type: 'string', minLength: 1, maxLength: 1000, description: 'First message the character says' },
+        alternate_greetings: { type: 'array', items: { type: 'string', maxLength: 1000 }, description: 'Optional alternative greetings; one is picked at random when a chat starts' },
+        prompt: { type: 'string', minLength: 1, maxLength: 4000, description: 'Persona / system prompt' },
+      },
+      required: ['name', 'greeting', 'prompt'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'update_character',
+    'Update an existing character. Requires user confirmation. Built-in characters are protected (cannot delete, but can be updated with care).',
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Existing character name' },
+        new_name: { type: 'string', maxLength: 40 },
+        greeting: { type: 'string', maxLength: 1000 },
+        alternate_greetings: { type: 'array', items: { type: 'string', maxLength: 1000 }, description: 'Replace the full list of alternate greetings' },
+        prompt: { type: 'string', maxLength: 4000 },
+        enable_skills: { type: 'array', items: { type: 'string' }, description: 'Skill names to enable (must exist)' },
+        disable_skills: { type: 'array', items: { type: 'string' }, description: 'Skill names to disable' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'delete_character',
+    'Delete a character. Requires user confirmation. Built-in characters are protected and cannot be deleted.',
+    {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'create_conversation',
+    'Create a new conversation. The player is always included automatically; you only need to specify the characters to add, plus optional Lorebook, speaking order, random-order switch, mention-only mode, and user persona.',
+    {
+      type: 'object',
+      properties: {
+        title: { type: 'string', maxLength: 60, description: 'Conversation name' },
+        participants: {
+          type: 'array',
+          items: { type: 'string' },
+          minItems: 1,
+          maxItems: 5,
+          uniqueItems: true,
+          description: 'Character names to add to the conversation. The player is included automatically.',
+        },
+        world_book: { type: 'string', description: 'Optional Lorebook name' },
+        speaking_order: {
+          type: 'array',
+          items: { type: 'string' },
+          uniqueItems: true,
+          description: "Optional fixed speaking order. Use character names plus 'user' for the player.",
+        },
+        user_persona: { type: 'string', description: 'Optional character name used as the user persona' },
+        random_order: { type: 'boolean', default: false, description: 'Whether to randomize speaking order each round' },
+        mention_only_mode: { type: 'boolean', default: false, description: 'In group chats, require characters to pass speaking control by @mentioning another character. Useful for reasoning games and other scenarios that require strict turn control.' },
+        enable_greeting: {
+          type: 'boolean',
+          default: true,
+          description: 'Whether to seed an opening greeting. In group chats, only the first non-user speaker greets; if the user goes first, no greeting is added.',
+        },
+      },
+      required: ['participants'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'create_lorebook',
+    'Create a Lorebook (world-building text appended to character personas).',
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string', minLength: 1, maxLength: 60 },
+        content: { type: 'string', minLength: 1, maxLength: 10000, description: 'World-building plain text' },
+      },
+      required: ['name', 'content'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'update_lorebook',
+    'Update a Lorebook. Requires user confirmation.',
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        new_name: { type: 'string', maxLength: 60 },
+        content: { type: 'string', maxLength: 10000 },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+  fn(
+    'delete_lorebook',
+    'Delete a Lorebook. Requires user confirmation. Unlinks from all sessions.',
+    {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
+];
+
+function executionProperties(): Record<string, unknown> {
+  return {
+    type: { type: 'string', enum: ['template', 'http_get', 'javascript', 'file_read', 'file_write', 'shell'] },
+    template: { type: 'string', description: 'template type: result template with {{param}} placeholders' },
+    url: { type: 'string', description: "http_get type: public https URL with {{param}} placeholders" },
+    code: { type: 'string', maxLength: 20000, description: "javascript type: JS code. Reads 'input' (args object), assigns JSON-safe 'result'. Supports async/await. Injected helpers: await $read(path)->string, $write(path, content), $append(path, content), $list()->[paths]. Helper paths must be relative to the current session workspace; absolute paths and parent traversal (..) are rejected." },
+    path: { type: 'string', description: 'file_read/file_write: relative path inside the private generated_skill_workspace' },
+    content: { type: 'string', description: 'file_write: text content with {{param}} placeholders' },
+    json_content: { type: 'object', description: 'file_write: JSON content, interpolated recursively' },
+    append: { type: 'boolean', description: 'file_write: append instead of overwrite' },
+    append_newline: { type: 'boolean', description: 'file_write: insert newline between appended records (JSONL)' },
+    script: { type: 'string', maxLength: 8000, description: 'shell type: local commands; non-allowlisted commands require user confirmation' },
+  };
+}
+
+function getExecutionDescription(): string {
+  return [
+    'Declarative implementation of the skill. One of:',
+    '- template: `{template: "As of {{date}}, the price is {{price}}"}`, placeholders interpolated from args',
+    '- http_get: `{url: "https://public.example.com/api?q={{q}}"}`, public HTTPS hostname required',
+    '- javascript: `{code: "result = { sum: input.a + input.b }"}`, reads `input`, assigns JSON-safe `result`; supports async/await and can persist game state via `await $read/$write/$append/$list`. These helpers only accept relative paths in the current session workspace; absolute paths and `..` are rejected',
+    '- file_read: `{path: "notes.md"}` — read a file from sandbox_workspace/ through the required local workspace service (100KB cap)',
+    '- file_write: `{path: "notes.jsonl", json_content: {...}, append: true, append_newline: true}` — write to sandbox_workspace/ through the required local workspace service',
+    '- shell: commands executed as REAL local commands via an optional controlled service (node sandbox-server.mjs); this is not OS-isolated. Supports newlines, &&, ||, and ; (max 20 commands), but not pipes, redirects, or expansion. Simple non-executing utilities, jq, and bc are allowlisted; command launchers, tools with exec/plugin hooks, and every other command require user confirmation',
+  ].join(' ');
+}
+
+/** 默认内置技能名列表（酒馆老板默认启用全部内置技能） */
+export const ALL_BUILTIN_TOOL_NAMES = [...BUILTIN_TOOL_NAMES];

package/src/core/tools/builtinTools.ts

@@ -0,0 +1,38 @@
+import { translate } from '../i18n';
+
+// ============================================================
+// roll_dice — 与 App 的 DiceRoller 一致
+// ============================================================
+
+const DICE_RE = /^(\d*)d(\d+)([+-]\d+)?$/;
+
+export function rollDice(expression: string): string {
+  const expr = expression.trim() || '1d20';
+  const m = expr.match(DICE_RE);
+  if (!m) return `ERROR: Invalid dice expression "${expression}", e.g. d20, 2d6, 3d10+2`;
+
+  const count = m[1] ? parseInt(m[1], 10) : 1;
+  const sides = parseInt(m[2], 10);
+  const modifier = m[3] ? parseInt(m[3], 10) : 0;
+
+  if (count < 1 || count > 100) return 'ERROR: Dice count must be 1-100';
+  if (sides < 2 || sides > 10000) return 'ERROR: Dice sides must be 2-10000';
+  if (Math.abs(modifier) > 1000000) return 'ERROR: Modifier too large';
+
+  const rolls: number[] = [];
+  for (let i = 0; i < count; i++) {
+    rolls.push(1 + Math.floor(Math.random() * sides));
+  }
+  const sum = rolls.reduce((a, b) => a + b, 0);
+  const total = sum + modifier;
+
+  let critical = '';
+  if (count === 1 && sides === 20) {
+    if (rolls[0] === 20) critical = translate('tool.diceCrit20');
+    else if (rolls[0] === 1) critical = translate('tool.diceCrit1');
+  }
+
+  const parts = [rolls.join(', ')];
+  if (modifier !== 0) parts.push(`${modifier > 0 ? '+' : ''}${modifier}`);
+  return translate('tool.diceRoll', { expr, rolls: parts.join('] '), total, crit: critical });
+}