@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/index.ts

@@ -0,0 +1,392 @@
+// Models
+export { type BookConfig, type Platform, type Genre, type BookStatus, type FanficMode, BookConfigSchema, PlatformSchema, GenreSchema, BookStatusSchema, FanficModeSchema, normalizePlatformId, normalizePlatformOrOther } from "./models/book.js";
+export { type ChapterMeta, type ChapterStatus, ChapterMetaSchema, ChapterStatusSchema } from "./models/chapter.js";
+export { type ProjectConfig, type LLMConfig, type NotifyChannel, type DetectionConfig, type QualityGates, type FoundationConfig, type WritingConfig, type AgentLLMOverride, type InputGovernanceMode, ProjectConfigSchema, LLMConfigSchema, AgentLLMOverrideSchema, DetectionConfigSchema, QualityGatesSchema, FoundationConfigSchema, WritingConfigSchema, InputGovernanceModeSchema } from "./models/project.js";
+export { type CurrentState, type ParticleLedger, type PendingHooks, type PendingHook, type LedgerEntry } from "./models/state.js";
+export { type GenreProfile, type ParsedGenreProfile, GenreProfileSchema, parseGenreProfile } from "./models/genre-profile.js";
+export { type BookRules, type ParsedBookRules, BookRulesSchema, parseBookRules, tryParseBookRulesFrontmatter } from "./models/book-rules.js";
+export { type DetectionHistoryEntry, type DetectionStats } from "./models/detection.js";
+export { type StyleProfile } from "./models/style-profile.js";
+export { type LengthCountingMode, type LengthNormalizeMode, type LengthSpec, type LengthTelemetry, type LengthWarning, LengthCountingModeSchema, LengthNormalizeModeSchema, LengthSpecSchema, LengthTelemetrySchema, LengthWarningSchema } from "./models/length-governance.js";
+export {
+  type RuntimeStateLanguage,
+  type StateManifest,
+  type HookStatus,
+  type HookRecord,
+  type HooksState,
+  type ChapterSummaryRow,
+  type ChapterSummariesState,
+  type CurrentStateFact,
+  type CurrentStateState,
+  type CurrentStatePatch,
+  type HookOps,
+  type NewHookCandidate,
+  type RuntimeStateDelta,
+  RuntimeStateLanguageSchema,
+  StateManifestSchema,
+  HookStatusSchema,
+  HookRecordSchema,
+  HooksStateSchema,
+  ChapterSummaryRowSchema,
+  ChapterSummariesStateSchema,
+  CurrentStateFactSchema,
+  CurrentStateStateSchema,
+  CurrentStatePatchSchema,
+  HookOpsSchema,
+  NewHookCandidateSchema,
+  RuntimeStateDeltaSchema,
+} from "./models/runtime-state.js";
+export {
+  type ChapterMemo,
+  type ChapterIntent,
+  type ContextSource,
+  type ContextPackage,
+  type RuleLayerScope,
+  type RuleLayer,
+  type OverrideEdge,
+  type ActiveOverride,
+  type RuleStackSections,
+  type RuleStack,
+  type ChapterTrace,
+  ChapterMemoSchema,
+  ChapterIntentSchema,
+  ContextSourceSchema,
+  ContextPackageSchema,
+  RuleLayerScopeSchema,
+  RuleLayerSchema,
+  OverrideEdgeSchema,
+  ActiveOverrideSchema,
+  RuleStackSectionsSchema,
+  RuleStackSchema,
+  ChapterTraceSchema,
+} from "./models/input-governance.js";
+export { PlannerAgent, type PlanChapterInput, type PlanChapterOutput } from "./agents/planner.js";
+export {
+  ComposerAgent,
+  composeGovernedChapter,
+  type ComposeChapterInput,
+  type ComposeChapterOutput,
+} from "./agents/composer.js";
+export {
+  PLANNER_MEMO_SYSTEM_PROMPT,
+  PLANNER_MEMO_USER_TEMPLATE,
+  buildPlannerUserMessage,
+  buildGoldenOpeningGuidance,
+  type PlannerUserMessageInput,
+} from "./agents/planner-prompts.js";
+export {
+  gatherPlanningMaterials,
+  type PlanningMaterials,
+} from "./utils/planning-materials.js";
+export {
+  buildProxyFetchInit,
+  fetchWithProxy,
+  resolveProxyUrl,
+} from "./utils/proxy-fetch.js";
+export { assertSafeBookId, deriveBookIdFromTitle, isSafeBookId } from "./utils/book-id.js";
+export { safeChildPath } from "./utils/path-safety.js";
+export {
+  AutomationModeSchema,
+  type AutomationMode,
+  normalizeAutomationMode,
+} from "./interaction/modes.js";
+export {
+  InteractionIntentTypeSchema,
+  type InteractionIntentType,
+  InteractionRequestSchema,
+  type InteractionRequest,
+} from "./interaction/intents.js";
+export {
+  ExecutionStatusSchema,
+  ExecutionStateSchema,
+  InteractionEventSchema,
+  type ExecutionStatus,
+  type ExecutionState,
+  type InteractionEvent,
+  isTerminalExecutionStatus,
+} from "./interaction/events.js";
+export {
+  BookCreationDraftSchema,
+  DraftRoundSchema,
+  PendingDecisionSchema,
+  InteractionMessageSchema,
+  InteractionSessionSchema,
+  type BookCreationDraft,
+  type DraftRound,
+  type PendingDecision,
+  type InteractionMessage,
+  type InteractionSession,
+  bindActiveBook,
+  clearCreationDraft,
+  clearPendingDecision,
+  updateAutomationMode,
+  updateCreationDraft,
+  appendInteractionMessage,
+  appendInteractionEvent,
+  BookSessionSchema,
+  GlobalSessionSchema,
+  type BookSession,
+  type GlobalSession,
+  createBookSession,
+  appendBookSessionMessage,
+} from "./interaction/session.js";
+export {
+  resolveProjectSessionPath,
+  createProjectSession,
+  loadProjectSession,
+  persistProjectSession,
+  resolveSessionActiveBook,
+  loadGlobalSession,
+  persistGlobalSession,
+} from "./interaction/project-session-store.js";
+export {
+  loadBookSession,
+  persistBookSession,
+  listBookSessions,
+  renameBookSession,
+  deleteBookSession,
+  migrateBookSession,
+  createAndPersistBookSession,
+  SessionAlreadyMigratedError,
+} from "./interaction/book-session-store.js";
+export {
+  appendManualSessionMessages,
+  appendTranscriptEvent,
+  sessionsDir,
+  readTranscriptEvents,
+  nextTranscriptSeq,
+  transcriptPath,
+  legacyBookSessionPath,
+} from "./interaction/session-transcript.js";
+export {
+  cleanRestoredAgentMessages,
+  committedMessageEvents,
+  deriveBookSessionFromTranscript,
+  restoreAgentMessagesFromTranscript,
+} from "./interaction/session-transcript-restore.js";
+export {
+  MessageEventSchema,
+  RequestCommittedEventSchema,
+  RequestFailedEventSchema,
+  RequestStartedEventSchema,
+  SessionCreatedEventSchema,
+  SessionMetadataUpdatedEventSchema,
+  TranscriptEventSchema,
+} from "./interaction/session-transcript-schema.js";
+export type {
+  TranscriptEvent,
+  MessageEvent,
+  RequestCommittedEvent,
+  RequestFailedEvent,
+  RequestStartedEvent,
+  SessionCreatedEvent,
+  SessionMetadataUpdatedEvent,
+} from "./interaction/session-transcript-schema.js";
+export { routeInteractionRequest } from "./interaction/request-router.js";
+export {
+  routeNaturalLanguageIntent,
+  type NaturalLanguageRoutingContext,
+} from "./interaction/nl-router.js";
+export {
+  processProjectInteractionInput,
+  processProjectInteractionRequest,
+} from "./interaction/project-control.js";
+export { createInteractionToolsFromDeps } from "./interaction/project-tools.js";
+export { buildExportArtifact, writeExportArtifact } from "./interaction/export-artifact.js";
+export {
+  normalizeTruthFileName,
+  classifyTruthAuthority,
+  type TruthAuthority,
+} from "./interaction/truth-authority.js";
+export {
+  executeEditTransaction,
+  planEditTransaction,
+  type EditRequest,
+  type EditExecutionDeps,
+  type ExecutedEditTransaction,
+  type PlannedEditTransaction,
+} from "./interaction/edit-controller.js";
+export {
+  runInteractionRequest,
+  type InteractionRuntimeTools,
+  type InteractionRuntimeResult,
+} from "./interaction/runtime.js";
+export {
+  parseDraftDirectives,
+  createDirectiveStreamFilter,
+  type ParsedDraftResponse,
+} from "./interaction/draft-directive-parser.js";
+
+export {
+  SHORT_FICTION_DEFAULT_CHAPTERS,
+  SHORT_FICTION_MIN_CHAPTERS,
+  SHORT_FICTION_MAX_CHAPTERS,
+  SHORT_FICTION_DEFAULT_CHARS_PER_CHAPTER,
+  SHORT_FICTION_MIN_CHARS_PER_CHAPTER,
+  SHORT_FICTION_MAX_CHARS_PER_CHAPTER,
+  ShortFictionOutlineAgent,
+  ShortFictionOutlineReviewerAgent,
+  ShortFictionOutlineReviserAgent,
+  ShortFictionWriterAgent,
+  ShortFictionDraftReviewerAgent,
+  ShortFictionDraftReviserAgent,
+  ShortFictionPackagingAgent,
+  parseShortFictionBatchDraft,
+  validateShortFictionDraftForFinal,
+  renderShortFictionDraftMarkdown,
+  type ShortFictionOutline,
+  type ShortFictionBatchDraft,
+  type ShortFictionChapter,
+  type ShortFictionSalesPackage,
+  type ShortFictionReference,
+} from "./agents/short-fiction.js";
+export {
+  generateShortFictionCover,
+  runShortFictionProduction,
+  extractResponsesImageBase64,
+  resolveCoverApiKey,
+  type ShortFictionCoverOptions,
+  type ShortFictionCoverResult,
+  type ShortFictionRunOptions,
+  type ShortFictionRunResult,
+  type ShortFictionRunRuntimes,
+} from "./pipeline/short-fiction-runner.js";
+
+// Agent (pi-agent integration)
+export * from "./agent/index.js";
+
+// LLM
+export { createLLMClient, chatCompletion, chatWithTools, createStreamMonitor, PartialResponseError, type LLMClient, type LLMResponse, type LLMMessage, type ToolDefinition, type ToolCall, type AgentMessage, type ChatWithToolsResult, type StreamProgress, type OnStreamProgress } from "./llm/provider.js";
+export {
+  SERVICE_PRESETS,
+  SERVICE_TO_PI_PROVIDER,
+  resolveServicePreset,
+  resolveServiceProviderFamily,
+  resolveServicePiProvider,
+  resolveServiceModelsBaseUrl,
+  guessServiceFromBaseUrl,
+  listModelsForService,
+  listServicesWithModelCount,
+  type ServicePreset,
+  type ModelInfo,
+} from "./llm/service-presets.js";
+export { resolveServiceModel, type ResolvedModel } from "./llm/service-resolver.js";
+export { loadSecrets, saveSecrets, getServiceApiKey, type SecretsFile } from "./llm/secrets.js";
+export {
+  COVER_PROVIDER_PRESETS,
+  coverSecretKey,
+  resolveCoverProviderPreset,
+  type CoverProviderId,
+  type CoverProviderPreset,
+} from "./llm/cover-providers.js";
+export { migrateConfig, type MigrationResult } from "./llm/config-migration.js";
+export { getAllEndpoints, getEndpoint, type InkosEndpoint, type InkosModel, type EndpointGroup } from "./llm/providers/index.js";
+export { probeModelsFromUpstream, type ProbedModel } from "./llm/providers/probe.js";
+
+// Agents
+export { BaseAgent, type AgentContext } from "./agents/base.js";
+export { ArchitectAgent, type ArchitectOutput } from "./agents/architect.js";
+export { WriterAgent, type WriteChapterInput, type WriteChapterOutput, type TokenUsage } from "./agents/writer.js";
+export { LengthNormalizerAgent, type NormalizeLengthInput, type NormalizeLengthOutput } from "./agents/length-normalizer.js";
+export { ContinuityAuditor, type AuditResult, type AuditIssue } from "./agents/continuity.js";
+export { ReviserAgent, DEFAULT_REVISE_MODE, type ReviseOutput, type ReviseMode } from "./agents/reviser.js";
+export { PolisherAgent, type PolishChapterInput, type PolishChapterOutput } from "./agents/polisher.js";
+export { RadarAgent, type RadarResult, type RadarRecommendation } from "./agents/radar.js";
+export { FanqieRadarSource, QidianRadarSource, TextRadarSource, type RadarSource, type PlatformRankings, type RankingEntry } from "./agents/radar-source.js";
+export { readGenreProfile, readBookRules, listAvailableGenres, getBuiltinGenresDir } from "./agents/rules-reader.js";
+export { buildWriterSystemPrompt, buildGoldenOpeningDiscipline } from "./agents/writer-prompts.js";
+export { analyzeAITells, type AITellResult, type AITellIssue } from "./agents/ai-tells.js";
+export { analyzeSensitiveWords, type SensitiveWordResult, type SensitiveWordMatch } from "./agents/sensitive-words.js";
+export { detectAIContent, type DetectionResult } from "./agents/detector.js";
+export { analyzeStyle } from "./agents/style-analyzer.js";
+export { analyzeDetectionInsights } from "./agents/detection-insights.js";
+export { validatePostWrite, detectParagraphLengthDrift, detectParagraphShapeWarnings, detectDuplicateTitle, type PostWriteViolation } from "./agents/post-write-validator.js";
+export { ChapterAnalyzerAgent, type AnalyzeChapterInput, type AnalyzeChapterOutput } from "./agents/chapter-analyzer.js";
+export { parseWriterOutput, parseCreativeOutput, type ParsedWriterOutput, type CreativeOutput } from "./agents/writer-parser.js";
+export { buildSettlerSystemPrompt, buildSettlerUserPrompt } from "./agents/settler-prompts.js";
+export { parseSettlementOutput, type SettlementOutput } from "./agents/settler-parser.js";
+export { parseSettlerDeltaOutput, type SettlerDeltaOutput } from "./agents/settler-delta-parser.js";
+export { FanficCanonImporter, type FanficCanonOutput } from "./agents/fanfic-canon-importer.js";
+export { getFanficDimensionConfig, FANFIC_DIMENSIONS, type FanficDimensionConfig } from "./agents/fanfic-dimensions.js";
+export { buildFanficCanonSection, buildCharacterVoiceProfiles, buildFanficModeInstructions } from "./agents/fanfic-prompt-sections.js";
+export * from "./prompts/index.js";
+
+// Utils
+export { isNewLayoutBook } from "./utils/outline-paths.js";
+export { fetchUrl, searchWeb } from "./utils/web-search.js";
+export { filterHooks, filterSummaries, filterSubplots, filterEmotionalArcs, filterCharacterMatrix } from "./utils/context-filter.js";
+export { extractPOVFromOutline, filterMatrixByPOV, filterHooksByPOV } from "./utils/pov-filter.js";
+export { ConsolidatorAgent } from "./agents/consolidator.js";
+export { MemoryDB, type Fact, type StoredSummary } from "./state/memory-db.js";
+export { StateValidatorAgent } from "./agents/state-validator.js";
+export { loadRuntimeStateSnapshot, buildRuntimeStateArtifacts, saveRuntimeStateSnapshot, loadNarrativeMemorySeed, loadSnapshotCurrentStateFacts, type RuntimeStateArtifacts, type NarrativeMemorySeed } from "./state/runtime-state-store.js";
+export { splitChapters, type SplitChapter } from "./utils/chapter-splitter.js";
+export { countChapterLength, resolveLengthCountingMode, formatLengthCount, buildLengthSpec, isOutsideSoftRange, isOutsideHardRange, chooseNormalizeMode, type LengthLanguage } from "./utils/length-metrics.js";
+export { createLogger, createStderrSink, createJsonLineSink, nullSink, type Logger, type LogSink, type LogLevel, type LogEntry } from "./utils/logger.js";
+export { loadProjectConfig, GLOBAL_CONFIG_DIR, GLOBAL_ENV_PATH, isApiKeyOptionalForEndpoint } from "./utils/config-loader.js";
+export { resolveEffectiveLLMConfig, type EffectiveLLMConfigResult, type EffectiveLLMDiagnostics, type LLMConfigCliOverrides, type LLMConfigMode, type LLMConsumer, type LLMValueSource } from "./utils/effective-llm-config.js";
+export { loadLLMEnvLayers, mergeEnvMaps, studioIgnoredEnv, cliOverlayEnv, legacyEnv, type LLMEnvLayers, type LLMEnvMap } from "./utils/llm-env.js";
+export { computeAnalytics, type AnalyticsData, type TokenStats } from "./utils/analytics.js";
+export {
+  collectStaleHookDebt,
+  evaluateHookAdmission,
+  classifyHookDisposition,
+  type HookAdmissionCandidate,
+  type HookAdmissionDecision,
+  type HookDisposition,
+} from "./utils/hook-governance.js";
+export { arbitrateRuntimeStateDeltaHooks, type HookArbiterDecision } from "./utils/hook-arbiter.js";
+export { analyzeHookHealth } from "./utils/hook-health.js";
+
+// Pipeline
+export { PipelineRunner, type PipelineConfig, type ChapterPipelineResult, type DraftResult, type PlanChapterResult, type ComposeChapterResult, type ReviseResult, type TruthFiles, type BookStatusInfo, type ImportChaptersInput, type ImportChaptersResult, type TokenUsageSummary } from "./pipeline/runner.js";
+export { Scheduler, type SchedulerConfig } from "./pipeline/scheduler.js";
+export { runAgentLoop, AGENT_TOOLS as AGENT_TOOLS, type AgentLoopOptions } from "./pipeline/agent.js";
+export { detectChapter, detectAndRewrite, loadDetectionHistory, type DetectChapterResult, type DetectAndRewriteResult } from "./pipeline/detection-runner.js";
+
+// State
+export { StateManager } from "./state/manager.js";
+export { bootstrapStructuredStateFromMarkdown } from "./state/state-bootstrap.js";
+export { renderCurrentStateProjection, renderHooksProjection, renderChapterSummariesProjection } from "./state/state-projections.js";
+export { applyRuntimeStateDelta, type RuntimeStateSnapshot } from "./state/state-reducer.js";
+export { validateRuntimeState, type RuntimeStateValidationIssue } from "./state/state-validator.js";
+
+// Notify
+export { dispatchNotification, dispatchWebhookEvent, type NotifyMessage } from "./notify/dispatcher.js";
+export type { TelegramConfig } from "./notify/telegram.js";
+export type { FeishuConfig } from "./notify/feishu.js";
+export type { WechatWorkConfig } from "./notify/wechat-work.js";
+export type { WebhookConfig, WebhookEvent, WebhookPayload } from "./notify/webhook.js";
+
+export async function sendTelegram(
+  config: import("./notify/telegram.js").TelegramConfig,
+  message: string,
+): Promise<void> {
+  const transport = await import("./notify/telegram.js");
+  await transport.sendTelegram(config, message);
+}
+
+export async function sendFeishu(
+  config: import("./notify/feishu.js").FeishuConfig,
+  title: string,
+  text: string,
+): Promise<void> {
+  const transport = await import("./notify/feishu.js");
+  await transport.sendFeishu(config, title, text);
+}
+
+export async function sendWechatWork(
+  config: import("./notify/wechat-work.js").WechatWorkConfig,
+  text: string,
+): Promise<void> {
+  const transport = await import("./notify/wechat-work.js");
+  await transport.sendWechatWork(config, text);
+}
+
+export async function sendWebhook(
+  config: import("./notify/webhook.js").WebhookConfig,
+  payload: import("./notify/webhook.js").WebhookPayload,
+): Promise<void> {
+  const transport = await import("./notify/webhook.js");
+  await transport.sendWebhook(config, payload);
+}

package/inkos/packages/core/src/interaction/book-session-store.ts

@@ -0,0 +1,226 @@
+import { readdir, unlink } from "node:fs/promises";
+import { createBookSession } from "./session.js";
+import type { BookSession } from "./session.js";
+import {
+  appendTranscriptEvents,
+  legacyBookSessionPath,
+  readTranscriptEvents,
+  sessionsDir,
+  transcriptPath,
+} from "./session-transcript.js";
+import {
+  migrateLegacyBookSessionToTranscript,
+  readLegacyBookSession,
+} from "./session-transcript-legacy.js";
+import { deriveBookSessionFromTranscript } from "./session-transcript-restore.js";
+
+/**
+ * 从 messages 数组里取第一条 user 消息，裁剪成 ≤20 字的单行字符串。
+ * 用于把用户首条提问作为会话标题。
+ */
+export function extractFirstUserMessageTitle(messages: unknown): string | null {
+  if (!Array.isArray(messages)) return null;
+  for (const message of messages) {
+    if (!message || typeof message !== "object") continue;
+    if ((message as { role?: unknown }).role !== "user") continue;
+    const content = (message as { content?: unknown }).content;
+    if (typeof content !== "string") return null;
+    const oneLine = content.trim().replace(/\s+/g, " ");
+    if (oneLine.length === 0) return null;
+    return oneLine.length > 20 ? `${oneLine.slice(0, 20)}…` : oneLine;
+  }
+  return null;
+}
+
+export class SessionAlreadyMigratedError extends Error {
+  constructor(sessionId: string, currentBookId: string) {
+    super(`Session "${sessionId}" is already bound to book "${currentBookId}"`);
+    this.name = "SessionAlreadyMigratedError";
+  }
+}
+
+export async function loadBookSession(
+  projectRoot: string,
+  sessionId: string,
+): Promise<BookSession | null> {
+  const transcriptSession = await deriveBookSessionFromTranscript(projectRoot, sessionId);
+  if (transcriptSession) return transcriptSession;
+
+  const legacySession = await readLegacyBookSession(projectRoot, sessionId);
+  if (!legacySession) return null;
+
+  await migrateLegacyBookSessionToTranscript(projectRoot, legacySession);
+  return await deriveBookSessionFromTranscript(projectRoot, sessionId) ?? legacySession;
+}
+
+async function appendSessionCreatedEvent(
+  projectRoot: string,
+  session: BookSession,
+): Promise<void> {
+  await appendTranscriptEvents(projectRoot, session.sessionId, ({ events, nextSeq }) => {
+    if (events.some((event) => event.type === "session_created")) return [];
+    return [{
+      type: "session_created",
+      version: 1,
+      sessionId: session.sessionId,
+      seq: nextSeq,
+      timestamp: session.createdAt,
+      bookId: session.bookId,
+      title: session.title,
+      createdAt: session.createdAt,
+      updatedAt: session.updatedAt,
+    }];
+  });
+}
+
+async function appendSessionMetadataUpdatedEvent(
+  projectRoot: string,
+  sessionId: string,
+  metadata: {
+    readonly bookId?: string | null;
+    readonly title?: string | null;
+    readonly updatedAt: number;
+  },
+): Promise<void> {
+  await appendTranscriptEvents(projectRoot, sessionId, ({ nextSeq }) => [{
+    type: "session_metadata_updated",
+    version: 1,
+    sessionId,
+    seq: nextSeq,
+    timestamp: metadata.updatedAt,
+    updatedAt: metadata.updatedAt,
+    ...("bookId" in metadata ? { bookId: metadata.bookId } : {}),
+    ...("title" in metadata ? { title: metadata.title } : {}),
+  }]);
+}
+
+export async function persistBookSession(
+  projectRoot: string,
+  session: BookSession,
+): Promise<void> {
+  const events = await readTranscriptEvents(projectRoot, session.sessionId);
+  if (events.length === 0) {
+    if (session.messages.length === 0) {
+      await appendSessionCreatedEvent(projectRoot, session);
+      return;
+    }
+    await migrateLegacyBookSessionToTranscript(projectRoot, session);
+    return;
+  }
+
+  await appendSessionMetadataUpdatedEvent(projectRoot, session.sessionId, {
+    bookId: session.bookId,
+    title: session.title,
+    updatedAt: session.updatedAt,
+  });
+}
+
+export interface BookSessionSummary {
+  readonly sessionId: string;
+  readonly bookId: string | null;
+  readonly title: string | null;
+  readonly messageCount: number;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+export async function listBookSessions(
+  projectRoot: string,
+  bookId: string | null,
+): Promise<ReadonlyArray<BookSessionSummary>> {
+  const dir = sessionsDir(projectRoot);
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const sessionIds = new Set<string>();
+  for (const file of files) {
+    if (file.endsWith(".jsonl")) {
+      sessionIds.add(file.slice(0, -".jsonl".length));
+    } else if (file.endsWith(".json")) {
+      sessionIds.add(file.slice(0, -".json".length));
+    }
+  }
+
+  const summaries = await Promise.all(
+    [...sessionIds].map(async (sessionId): Promise<BookSessionSummary | null> => {
+      try {
+        const session = await loadBookSession(projectRoot, sessionId);
+        if (!session || session.bookId !== bookId) return null;
+
+        return {
+          sessionId: session.sessionId,
+          bookId: session.bookId,
+          title: session.title,
+          messageCount: session.messages.length,
+          createdAt: session.createdAt,
+          updatedAt: session.updatedAt,
+        };
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  return summaries
+    .filter((summary): summary is BookSessionSummary => summary !== null)
+    .sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+export async function renameBookSession(
+  projectRoot: string,
+  sessionId: string,
+  title: string,
+): Promise<BookSession | null> {
+  const session = await loadBookSession(projectRoot, sessionId);
+  if (!session) return null;
+  const updatedAt = Date.now();
+  await appendSessionMetadataUpdatedEvent(projectRoot, sessionId, { title, updatedAt });
+  return loadBookSession(projectRoot, sessionId);
+}
+
+export async function deleteBookSession(
+  projectRoot: string,
+  sessionId: string,
+): Promise<void> {
+  await Promise.all([
+    unlink(transcriptPath(projectRoot, sessionId)).catch(() => undefined),
+    unlink(legacyBookSessionPath(projectRoot, sessionId)).catch(() => undefined),
+  ]);
+}
+
+export async function migrateBookSession(
+  projectRoot: string,
+  sessionId: string,
+  newBookId: string,
+): Promise<BookSession | null> {
+  const session = await loadBookSession(projectRoot, sessionId);
+  if (!session) return null;
+  if (session.bookId !== null) {
+    throw new SessionAlreadyMigratedError(sessionId, session.bookId);
+  }
+
+  await appendSessionMetadataUpdatedEvent(projectRoot, sessionId, {
+    bookId: newBookId,
+    updatedAt: Date.now(),
+  });
+  return loadBookSession(projectRoot, sessionId);
+}
+
+export async function createAndPersistBookSession(
+  projectRoot: string,
+  bookId: string | null,
+  sessionId?: string,
+): Promise<BookSession> {
+  // 如果指定了 sessionId 且对应文件已存在，视为幂等操作直接返回（支持"用户发消息时才持久化 draft"流程）
+  if (sessionId) {
+    const existing = await loadBookSession(projectRoot, sessionId);
+    if (existing) return existing;
+  }
+  const session = createBookSession(bookId, sessionId);
+  await appendSessionCreatedEvent(projectRoot, session);
+  return session;
+}