@linxin666/dsh-pet 0.1.14 → 0.1.16

package/src/event-projection.ts

@@ -0,0 +1,128 @@
+/**
+ * Official session event projection — pure. Maps the durable DSH session
+ * vocabulary onto the pet's visual phases and carries an optional completed-
+ * turn reward for the ledger. Holds no state of its own; callers keep a
+ * {@link ProjectionRuntime} per session and feed events in arrival order.
+ * @module @linxin666/dsh-pet/event-projection
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { PetStateInput } from './state.ts'
+
+/** Runtime shape of the optional legacy activity event. */
+export interface ActivityStatusEventLike {
+  phase?: string
+  line?: string
+  phrase?: string
+}
+
+/** Per-session facts needed to project the official event stream. */
+export interface ProjectionRuntime {
+  activeTools: Set<string>
+  officialEventsSeen: boolean
+  stepHadFailure: boolean
+}
+
+/** One official event projection, optionally carrying a completed turn reward. */
+export interface PetActivityTransition {
+  input: PetStateInput
+  completedTurn?: number
+}
+
+/** Fresh projection runtime for a newly seen session. */
+export function emptyProjectionRuntime(): ProjectionRuntime {
+  return { activeTools: new Set(), officialEventsSeen: false, stepHadFailure: false }
+}
+
+/** Keep tool names readable inside the compact status bubble. */
+function displayToolName(name: string): string {
+  const compact = name.replace(/\s+/g, ' ').trim() || '工具'
+  return compact.length <= 24 ? compact : `${compact.slice(0, 21)}...`
+}
+
+/** Whether a legacy phase is part of the pet's supported vocabulary. */
+export function isActivityPhase(phase: string): phase is PetStateInput['phase'] {
+  return ['idle', 'waiting', 'thinking', 'tool', 'review', 'done', 'failed'].includes(phase)
+}
+
+/**
+ * Project the durable DSH session vocabulary into the pet's visual phases.
+ * Unknown and log-only events do not disturb the last meaningful activity.
+ */
+export function projectOfficialEvent(
+  event: SessionEvent,
+  runtime: ProjectionRuntime,
+): PetActivityTransition | undefined {
+  switch (event.type) {
+    case 'turn/start':
+      runtime.activeTools.clear()
+      runtime.stepHadFailure = false
+      return { input: { phase: 'waiting', line: '准备开始' } }
+    case 'step/start':
+      runtime.activeTools.clear()
+      runtime.stepHadFailure = false
+      return { input: { phase: 'waiting', line: '等待模型响应' } }
+    case 'assistant/chunk': {
+      const { chunk } = event.data
+      if (chunk.type === 'reasoning-delta' && chunk.text.length > 0) {
+        return { input: { phase: 'thinking', line: '正在思考' } }
+      }
+      if (chunk.type === 'text-delta' && chunk.text.length > 0) {
+        return { input: { phase: 'review', line: '整理回复中' } }
+      }
+      return undefined
+    }
+    case 'assistant/message':
+      return { input: { phase: 'review', line: '整理回复中' } }
+    case 'tool/call':
+      runtime.activeTools.add(String(event.data.callId))
+      return {
+        input: {
+          phase: 'tool',
+          line: `正在使用 ${displayToolName(event.data.name)}`,
+        },
+      }
+    case 'tool/result': {
+      const block = event.data.message.content[0]
+      runtime.activeTools.delete(String(event.data.message.source.callId))
+      runtime.stepHadFailure ||= event.data.error !== undefined || block.isError === true
+      if (runtime.activeTools.size > 0) {
+        return {
+          input: {
+            phase: 'tool',
+            line: `还有 ${runtime.activeTools.size} 个工具运行中`,
+          },
+        }
+      }
+      return runtime.stepHadFailure
+        ? { input: { phase: 'failed', line: '工具执行失败' } }
+        : { input: { phase: 'thinking', line: '处理工具结果' } }
+    }
+    case 'turn/end': {
+      runtime.activeTools.clear()
+      switch (event.data.reason.kind) {
+        case 'completed':
+          return {
+            input: { phase: 'done', line: '完成啦' },
+            completedTurn: event.data.turn,
+          }
+        case 'error':
+          return { input: { phase: 'failed', line: '执行失败' } }
+        case 'max-tokens':
+          return { input: { phase: 'failed', line: '达到输出上限' } }
+        case 'interrupted':
+          return { input: { phase: 'failed', line: '执行意外中断' } }
+        case 'blocked':
+          return { input: { phase: 'waiting', line: '等待继续' } }
+        case 'aborted':
+          return { input: { phase: 'idle', line: '已停止' } }
+        default:
+          // TurnEndReasonMap is merge-extensible; a newer ending must not
+          // leave the pet showing stale in-progress work.
+          return { input: { phase: 'idle' } }
+      }
+    }
+    default:
+      return undefined
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { makePetSettingsSchema } from './index.ts'
+
+describe('makePetSettingsSchema', () => {
+  it('resolves the selected pet and display defaults from an empty section', () => {
+    const schema = makePetSettingsSchema('whale-girl')
+    expect(schema({})).toMatchObject({
+      petId: 'whale-girl',
+      visible: true,
+      size: 160,
+      right: 24,
+      bottom: 20,
+      enabled: true,
+    })
+  })
+
+  it('accepts any petId string so a removed pet cannot brick the namespace', () => {
+    // The service clamps the value against the registry; the schema must
+    // never reject a stale stored selection outright.
+    const schema = makePetSettingsSchema('whale-girl')
+    expect(schema({ petId: 'dragon' }).petId).toBe('dragon')
+  })
+})

package/src/index.ts

@@ -1,9 +1,13 @@
 /**
  * dsh-pet host half — mounts the pet service and its HTTP routes. The
- * browser half (the `./client` entry) renders the whale-girl companion and
- * drives it through the same-origin `/api/pet/*` JSON endpoints plus the
- * `/pet/whale/*` media route. Install via `dsh plugin --profile web add
- * link:<dsh-web-ui>/packages/dsh-pet`; the cordis.patch.yml inserts this plugin row.
+ * browser half (the './client' entry) renders the selected pet and drives it
+ * through the same-origin '/api/pet/*' JSON endpoints plus the '/pet/<id>/*'
+ * media route. The host builds the multi-pet registry once at startup from
+ * the package assets, the hatch-pet custom pets directory, and composed
+ * config entries; adding a pet means dropping a manifest + atlas into one of
+ * those sources, never touching host or client code. Install via
+ * 'dsh plugin --profile web add link:<dsh-web-ui>/packages/dsh-pet'; the
+ * cordis.patch.yml inserts this plugin row.
  * @module @linxin666/dsh-pet
  */
 
@@ -12,19 +16,15 @@ import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-sett
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import z from 'schemastery'
 import { PetService, PET_SETTINGS_NAMESPACE, type PetConfig, type PetSettingsSection } from './service.ts'
-import { makePetRoutes, petPackageRoot } from './routes.ts'
-import {
-  DEFAULT_PET_NAME,
-  DISPLAY_INSET_MAX,
-  DISPLAY_SIZE_MAX,
-  DISPLAY_SIZE_MIN,
-  PET_NAME_MAX_LENGTH,
-} from './persist.ts'
+import { makePetRoutes } from './routes.ts'
+import { loadPetRegistry, petPackageRoot } from './registry.ts'
+import { DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN } from './persist.ts'
 
 export { PetService } from './service.ts'
 export type {
   PetConfig,
   PetInteractResult,
+  PetSettingsSection,
   PetStateView,
 } from './service.ts'
 export {
@@ -61,6 +61,9 @@ export {
 } from './treats.ts'
 export type { TreatConfig, TreatLedger, TreatSettlement } from './treats.ts'
 export {
+  DEFAULT_PET_ID,
+  DEFAULT_PET_NAME,
+  PET_NAME_MAX_LENGTH,
   defaultDisplayConfig,
   emptyPersist,
   loadPetPersist,
@@ -68,10 +71,31 @@ export {
   savePetPersist,
 } from './persist.ts'
 export type { PetDisplayConfig, PetPersist } from './persist.ts'
+export {
+  DEFAULT_FRAME_COUNTS,
+  DEFAULT_PET_CELL,
+  DEFAULT_PET_COLUMNS,
+  DEFAULT_PET_ROW_COUNT,
+  DEFAULT_TRACK_PATTERNS,
+  PET_ROW_ORDER,
+  codexPetsDir,
+  loadPetRegistry,
+  petEntryView,
+  petPackageRoot,
+  resolvePetManifest,
+} from './registry.ts'
+export type {
+  PetDefinition,
+  PetEntry,
+  PetManifest,
+  PetRegistry,
+  PetRegistryOptions,
+  PetTrackDef,
+  PetTrackOverride,
+} from './registry.ts'
 
 export {
   makePetRoutes,
-  petPackageRoot,
   PET_API_PREFIX,
   PET_ASSET_PREFIX,
 } from './routes.ts'
@@ -82,43 +106,57 @@ export const name = 'pet'
 /** Services required before the pet can mount its surfaces. */
 export const inject = ['webServer']
 
-/** Settings section schema: the display fields and name the web settings surface edits. */
-export const PET_SETTINGS_SCHEMA = z.object({
-  visible: z.boolean().default(true),
-  size: z.number().step(1).min(DISPLAY_SIZE_MIN).max(DISPLAY_SIZE_MAX).default(160),
-  right: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(24),
-  bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
-  name: z.string().min(1).max(PET_NAME_MAX_LENGTH).pattern(/\S/).default(DEFAULT_PET_NAME),
-  enabled: z.boolean().default(true),
-})
+/**
+ * Settings section schema: pet selection and display fields the web settings
+ * surface edits. petId is a plain string on purpose: the service clamps the
+ * resolved value against the registry, so a stored selection that points at
+ * a removed pet cannot invalidate the section (a strict union would refuse
+ * the whole registration). The settings card renders the actual registry
+ * choices itself from '/api/pet/pets'.
+ */
+export function makePetSettingsSchema(fallbackPetId: string) {
+  return z.object({
+    visible: z.boolean().default(true),
+    size: z.number().step(1).min(DISPLAY_SIZE_MIN).max(DISPLAY_SIZE_MAX).default(160),
+    right: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(24),
+    bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
+    petId: z.string().default(fallbackPetId),
+    enabled: z.boolean().default(true),
+  })
+}
 
 /** Register the pet service and its API + asset routes on the context. */
 export function apply(ctx: Context, config: PetConfig = {}): void {
-  const service = new PetService(ctx, config)
+  const registry = config.registry
+    ?? loadPetRegistry({
+      packageRoot: petPackageRoot(import.meta.url),
+      ...(config.pets === undefined ? {} : { extra: config.pets }),
+    })
+  const service = new PetService(ctx, { ...config, registry })
 
-  // The settings surface edits the display config through the `pet`
-  // namespace. The composition `base` starts as the persisted pet.json
-  // values (clamped to schema bounds), so an empty user layer resolves to
-  // exactly what the pet already shows — a fresh deployment never
-  // overwrites a customized layout, and reset re-inherits it. Runtime drag
-  // interactions mirror back into the settings document through the service
-  // (see syncSettingsFromPet), keeping both views consistent.
+  // The settings surface edits the pet selection + display config through
+  // the 'pet' namespace. The composition 'base' starts as the persisted
+  // pet.json values (clamped to schema bounds), so an empty user layer
+  // resolves to exactly what the pet already shows — a fresh deployment
+  // never overwrites a customized layout, and reset re-inherits it. Runtime
+  // drag interactions mirror back into the settings document through the
+  // service (see syncSettingsFromPet), keeping both views consistent.
   let current: () => PetSettingsSection = () => base
   const base: PetSettingsSection = {
     visible: service.display().visible,
     size: service.display().size,
     right: service.display().right,
     bottom: service.display().bottom,
-    name: service.petName(),
+    petId: service.selectedPetId(),
     enabled: config.enabled ?? true,
   }
   // The browser half talks to the pet through same-origin JSON endpoints and
-  // loads the atlas from the pet's own media route (RPC domains are
-  // platform-registered, so the pet serves its own API — the same pattern as
-  // dsh-remote-web-ui's /api/pair family). The routes are registered while
-  // the plugin is enabled; toggling the setting off makes the pet API
-  // disappear until it is re-enabled.
-  const routes = makePetRoutes({ service, packageRoot: petPackageRoot(import.meta.url) })
+  // loads each pet's atlas from the registry's own media route (RPC domains
+  // are platform-registered, so the pet serves its own API — the same
+  // pattern as dsh-remote-web-ui's /api/pair family). The routes are
+  // registered while the plugin is enabled; toggling the setting off makes
+  // the pet API disappear until it is re-enabled.
+  const routes = makePetRoutes({ service })
   let disposeRoutes: (() => void) | undefined
   const syncRoutes = (): void => {
     const enabled = current().enabled ?? true
@@ -135,14 +173,20 @@ export function apply(ctx: Context, config: PetConfig = {}): void {
       disposeRoutes = undefined
     }
   }
-  installSettingsSection(ctx, settingsNamespace(PET_SETTINGS_NAMESPACE), PET_SETTINGS_SCHEMA, base, {
-    setSource: (source) => { current = source },
-    onChange: () => {
-      const section = current()
-      service.applySettingsSection(section)
-      service.setEnabled(section.enabled ?? true)
-      syncRoutes()
+  installSettingsSection(
+    ctx,
+    settingsNamespace(PET_SETTINGS_NAMESPACE),
+    makePetSettingsSchema(service.selectedPetId()),
+    base,
+    {
+      setSource: (source) => { current = source },
+      onChange: () => {
+        const section = current()
+        service.applySettingsSection(section)
+        service.setEnabled(section.enabled ?? true)
+        syncRoutes()
+      },
     },
-  })
+  )
   syncRoutes()
 }

package/src/ledger.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import { defaultTreatConfig } from './treats.ts'
+import { defaultAffinityConfig } from './affinity.ts'
+import { emptyPersist } from './persist.ts'
+import { PetLedger } from './ledger.ts'
+
+describe('PetLedger', () => {
+  it('settles the economy on completed turns (work treat per 3 turns)', () => {
+    const ledger = new PetLedger(emptyPersist())
+    const n = 1_000_000
+    ledger.rewardTurn('s1', 1, n)
+    ledger.rewardTurn('s1', 2, n + 1)
+    ledger.rewardTurn('s1', 3, n + 2)
+    expect(ledger.snapshot.affinity.turns).toBe(3)
+    expect(ledger.snapshot.treats.treats).toBe(1)
+    expect(ledger.takeDirty()).toBe(true)
+  })
+
+  it('rewards each completed turn once per session (idempotent)', () => {
+    const ledger = new PetLedger(emptyPersist())
+    const n = 1_000_000
+    expect(ledger.rewardTurn('s1', 3, n)).toBe(true)
+    // A duplicate delivery of the same turn must not double count.
+    expect(ledger.rewardTurn('s1', 3, n + 1)).toBe(false)
+    expect(ledger.snapshot.affinity.turns).toBe(1)
+  })
+
+  it('a read of the view does not mark dirty (no settle on read)', () => {
+    const ledger = new PetLedger(emptyPersist())
+    ledger.affinityView(1_000_000)
+    expect(ledger.takeDirty()).toBe(false)
+  })
+
+  it('feed consumes a treat and applies the feed reward', () => {
+    const ledger = new PetLedger(emptyPersist())
+    const n = 1_000_000
+    ledger.rewardTurn('s1', 1, n)
+    ledger.rewardTurn('s1', 2, n + 1)
+    ledger.rewardTurn('s1', 3, n + 2)
+    expect(ledger.snapshot.treats.treats).toBe(1)
+    const res = ledger.interact('feed', n + 10)
+    expect(res.delta).toBe(defaultAffinityConfig.feedReward)
+    expect(ledger.snapshot.treats.treats).toBe(0)
+    expect(ledger.snapshot.affinity.feeds).toBe(1)
+  })
+
+  it('refuses a feed on an empty stock without burning anything', () => {
+    const ledger = new PetLedger(emptyPersist())
+    const res = ledger.interact('feed', 1_000_000)
+    expect(res.delta).toBe(0)
+    expect(res.reaction).toContain('没有小鱼干')
+    expect(ledger.snapshot.affinity.feeds).toBe(0)
+    // The empty-stock feed still marks dirty because the first settlement
+    // starts the time clock, mirroring the service-level behavior.
+    expect(ledger.takeDirty()).toBe(true)
+  })
+
+  it('exposes the treat stock cap and display/pet/name setters', () => {
+    const ledger = new PetLedger(emptyPersist())
+    expect(ledger.treatMax).toBe(defaultTreatConfig.maxTreats)
+    ledger.setDisplay({ ...ledger.snapshot.display, visible: false })
+    ledger.setPetId('otter')
+    ledger.setPetName('otter', '泡泡')
+    expect(ledger.snapshot.display.visible).toBe(false)
+    expect(ledger.snapshot.petId).toBe('otter')
+    expect(ledger.snapshot.names).toEqual({ otter: '泡泡' })
+    expect(ledger.takeDirty()).toBe(true)
+  })
+})

package/src/ledger.ts

@@ -0,0 +1,190 @@
+/**
+ * Pet affinity economy (ledger) — composes the pure affinity and treats
+ * modules with the cooldown/dedup bookkeeping and emits updated persistence
+ * snapshots, marking dirty so the owning facade decides when to flush. Read
+ * paths (view) no longer settle the economy; settlements happen on explicit
+ * economic events: completed-turn rewards (official or legacy) and feeds.
+ * @module @linxin666/dsh-pet/ledger
+ */
+
+import {
+  applyInteraction,
+  affinityViewOf,
+  applyTurnReward,
+  defaultAffinityConfig,
+  type AffinityConfig,
+  type PetAffinityView,
+  type PetInteraction,
+} from './affinity.ts'
+import {
+  consumeTreat,
+  defaultTreatConfig,
+  settleTreatGrants,
+  type TreatConfig,
+} from './treats.ts'
+import type { PetDisplayConfig, PetPersist } from './persist.ts'
+
+/** Tuning overrides for the affinity economy. */
+export interface LedgerConfig {
+  affinity?: Partial<AffinityConfig>
+  treats?: Partial<TreatConfig>
+}
+
+/** Result of one ledger interaction (the shape the pet RPC returns). */
+export interface LedgerInteractionResult {
+  /** Reaction copy bubble. */
+  reaction: string
+  /** Points gained (0 when inside the cooldown). */
+  delta: number
+  /** Full affinity snapshot (same shape as the state view). */
+  affinity: PetAffinityView
+}
+
+/**
+ * Holds the current persistence snapshot and all economy bookkeeping. Every
+ * mutating call flags takeDirty so the facade persists exactly once per
+ * batch of changes; read methods (snapshot, affinityView) never write.
+ */
+export class PetLedger {
+  private readonly affinityConfig: AffinityConfig
+  private readonly treatConfig: TreatConfig
+  private current: PetPersist
+  /** Completed turns already rewarded, per session (turn numbers are per-session). */
+  private rewardedTurns = new Map<string, number>()
+  private lastLegacyTurnRewardAt = 0
+  private dirty = false
+
+  constructor(persist: PetPersist, config: LedgerConfig = {}) {
+    this.affinityConfig = { ...defaultAffinityConfig, ...(config.affinity ?? {}) }
+    this.treatConfig = { ...defaultTreatConfig, ...(config.treats ?? {}) }
+    this.current = persist
+  }
+
+  /** Affinity cooldown/rank tuning (read-only). */
+  get affinity(): AffinityConfig {
+    return this.affinityConfig
+  }
+
+  /** The current persistence snapshot (trade a copy when mutating). */
+  get snapshot(): PetPersist {
+    return this.current
+  }
+
+  /** Stock cap reported to clients. */
+  get treatMax(): number {
+    return this.treatConfig.maxTreats
+  }
+
+  /** Consume the pending-write flag if any mutation occurred. */
+  takeDirty(): boolean {
+    const was = this.dirty
+    this.dirty = false
+    return was
+  }
+
+  /** Replace the display block (clamping stays a caller concern). */
+  setDisplay(display: PetDisplayConfig): void {
+    this.current = { ...this.current, display }
+    this.dirty = true
+  }
+
+  /** Replace the selected pet id (validation stays a caller concern). */
+  setPetId(petId: string): void {
+    if (this.current.petId === petId) return
+    this.current = { ...this.current, petId }
+    this.dirty = true
+  }
+
+  /** Replace one pet's display name (validation stays a caller concern). */
+  setPetName(petId: string, name: string): void {
+    this.current = { ...this.current, names: { ...this.current.names, [petId]: name } }
+    this.dirty = true
+  }
+
+  /**
+   * Settle the treat economy (work + time output since the last settlement).
+   * A zero-gain first settlement still starts the time clock (anchor write),
+   * which is how the 30-minute time output can ever accrue. Returns true when
+   * the in-memory ledger changed and should be persisted.
+   */
+  settleTreats(nowMs: number): boolean {
+    const settlement = settleTreatGrants(
+      this.current.treats,
+      this.current.affinity.turns,
+      nowMs,
+      this.treatConfig,
+    )
+    if (settlement.ledger === this.current.treats) return false
+    this.current = { ...this.current, treats: settlement.ledger }
+    this.dirty = true
+    return true
+  }
+
+  /**
+   * Award the completed-turn reward once per session+turn (idempotent) and
+   * run the treat settlement that work output feeds. Returns true when the
+   * snapshot changed.
+   */
+  rewardTurn(sessionId: string, turn: number, nowMs: number): boolean {
+    const last = this.rewardedTurns.get(sessionId) ?? 0
+    if (turn <= last) return false
+    this.rewardedTurns.set(sessionId, turn)
+    let changed = this.applyTurnReward()
+    if (this.settleTreats(nowMs)) changed = true
+    return changed
+  }
+
+  /** Preserve turn rewards for installations that only emit legacy activity. */
+  rewardLegacyTurn(nowMs: number): boolean {
+    // A legacy done snapshot may repeat during the celebration window.
+    if (nowMs - this.lastLegacyTurnRewardAt < 5_000) return false
+    this.lastLegacyTurnRewardAt = nowMs
+    let changed = this.applyTurnReward()
+    if (this.settleTreats(nowMs)) changed = true
+    return changed
+  }
+
+  private applyTurnReward(): boolean {
+    this.current = {
+      ...this.current,
+      affinity: applyTurnReward(this.current.affinity, this.affinityConfig),
+    }
+    this.dirty = true
+    return true
+  }
+
+  /**
+   * Pet or feed the pet. Feeding settles first, then gates on the feed
+   * cooldown before spending stock — a feed inside the cooldown must not burn
+   * a treat for nothing.
+   */
+  interact(kind: PetInteraction, nowMs: number): LedgerInteractionResult {
+    if (kind === 'feed') this.settleTreats(nowMs)
+    const outcome = applyInteraction(this.current.affinity, kind, nowMs, this.affinityConfig)
+    if (kind === 'feed' && !outcome.accepted) {
+      return { reaction: outcome.reaction, delta: 0, affinity: this.affinityView(nowMs) }
+    }
+    if (kind === 'feed') {
+      const consume = consumeTreat(this.current.treats)
+      if (!consume.ok) {
+        return {
+          reaction: '没有小鱼干了，多陪我工作一会儿吧～',
+          delta: 0,
+          affinity: this.affinityView(nowMs),
+        }
+      }
+      this.current = { ...this.current, treats: consume.ledger }
+      this.dirty = true
+    }
+    if (outcome.accepted) {
+      this.current = { ...this.current, affinity: outcome.affinity }
+      this.dirty = true
+    }
+    return { reaction: outcome.reaction, delta: outcome.delta, affinity: this.affinityView(nowMs) }
+  }
+
+  /** Current affinity view for the RPC snapshot. */
+  affinityView(nowMs: number): PetAffinityView {
+    return affinityViewOf(this.current.affinity, nowMs, this.affinityConfig)
+  }
+}