@linxin666/dsh-pet 0.1.1

package/src/routes.ts

@@ -0,0 +1,171 @@
+/**
+ * Pet HTTP routes — the browser half talks to the host through plain
+ * same-origin JSON endpoints (`/api/pet/*`) and loads the whale-girl atlas
+ * from `/pet/whale/*`. The `/plugins/` endpoint only serves client bundles
+ * and RPC domains are platform-registered, so the pet serves its own API
+ * and media — the same pattern as dsh-remote-web-ui's `/api/pair` family.
+ * @module @linxin666/dsh-pet/routes
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { PetService } from './service.ts'
+import type { PetInteraction } from './affinity.ts'
+
+/** Browser-facing base path of the pet API. */
+export const PET_API_PREFIX = '/api/pet'
+
+/** Browser-facing base path of the pet asset routes. */
+export const PET_ASSET_PREFIX = '/pet/whale'
+
+/** Relative (to package root) asset files exposed under the prefix. */
+const ASSET_FILES = [
+  { name: 'spritesheet.webp', mime: 'image/webp' },
+  { name: 'pet.json', mime: 'application/json' },
+] as const
+
+/** Absolute package root, resolved from this module's own location (lib/). */
+export function petPackageRoot(importMetaUrl: string): string {
+  return fileURLToPath(new URL('../', importMetaUrl))
+}
+
+/** Write one JSON response. */
+function json(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+/** Require the method or answer 405. */
+function requireMethod(req: IncomingMessage, res: ServerResponse, method: string): boolean {
+  if (req.method === method) return true
+  json(res, 405, { ok: false, error: 'method-not-allowed' })
+  return false
+}
+
+/** Read a JSON request body (bounded). */
+function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > 64 * 1024) {
+        // Reject first so the error handler can write the 400 response,
+        // then close the connection once the response is flushed.
+        reject(new Error('body-too-large'))
+        queueMicrotask(() => req.destroy())
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (chunks.length === 0) {
+        resolve({})
+        return
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      } catch {
+        reject(new Error('invalid-json'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/** Wrap one async service call as a GET JSON route. */
+function getRoute(path: string, run: () => Promise<unknown>): WebRoute {
+  return {
+    kind: 'exact',
+    path,
+    handler: (req: IncomingMessage, res: ServerResponse): void => {
+      if (!requireMethod(req, res, 'GET')) return
+      run().then((value) => json(res, 200, value), (error) => {
+        json(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      })
+    },
+  }
+}
+
+/** Wrap one async service call as a POST JSON route (body passed through). */
+function postRoute(path: string, run: (body: Record<string, unknown>) => Promise<unknown>): WebRoute {
+  return {
+    kind: 'exact',
+    path,
+    handler: (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+      if (!requireMethod(req, res, 'POST')) return Promise.resolve()
+      return readJsonBody(req).then((body) => {
+        const record = (typeof body === 'object' && body !== null) ? body as Record<string, unknown> : {}
+        return run(record).then(
+          (value) => json(res, 200, value),
+          (error) => {
+            json(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) })
+          },
+        )
+      }, (error) => {
+        json(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      })
+    },
+  }
+}
+
+/** Build the full route family (API + assets) for one service + package root. */
+export function makePetRoutes(deps: { service: PetService; packageRoot: string }): WebRoute[] {
+  const { service, packageRoot } = deps
+  const apiRoutes: WebRoute[] = [
+    getRoute(`${PET_API_PREFIX}/state`, () => service.state()),
+    postRoute(`${PET_API_PREFIX}/interact`, (body) => {
+      const kind = body.kind as PetInteraction | undefined
+      if (kind !== 'pet' && kind !== 'feed') return Promise.reject(new Error('invalid-kind'))
+      return service.interact(kind)
+    }),
+    postRoute(`${PET_API_PREFIX}/set-visible`, (body) => {
+      const visible = body.visible
+      if (typeof visible !== 'boolean') return Promise.reject(new Error('invalid-visible'))
+      return service.setVisible(visible)
+    }),
+    postRoute(`${PET_API_PREFIX}/set-config`, (body) => service.setConfig({
+      ...(typeof body.size === 'number' ? { size: body.size } : {}),
+      ...(typeof body.right === 'number' ? { right: body.right } : {}),
+      ...(typeof body.bottom === 'number' ? { bottom: body.bottom } : {}),
+      ...(typeof body.visible === 'boolean' ? { visible: body.visible } : {}),
+    })),
+    postRoute(`${PET_API_PREFIX}/set-name`, (body) => {
+      const name = body.name
+      if (typeof name !== 'string') return Promise.reject(new Error('invalid-name'))
+      return service.setName(name)
+    }),
+  ]
+
+  const assetRoutes: WebRoute[] = ASSET_FILES.map((file): WebRoute => ({
+    kind: 'exact',
+    path: `${PET_ASSET_PREFIX}/${file.name}`,
+    handler: (req: IncomingMessage, res: ServerResponse): Promise<void> | void => {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405)
+        res.end()
+        return
+      }
+      return readFile(join(packageRoot, 'assets', 'whale', file.name)).then((body) => {
+        res.writeHead(200, {
+          'content-type': file.mime,
+          'content-length': String(body.byteLength),
+          'cache-control': 'no-cache',
+        })
+        if (req.method === 'HEAD') {
+          res.end()
+          return
+        }
+        res.end(body)
+      }, () => {
+        res.writeHead(404)
+        res.end()
+      })
+    },
+  }))
+
+  return [...apiRoutes, ...assetRoutes]
+}

package/src/service.ts

@@ -0,0 +1,389 @@
+/**
+ * Pet host service — the `pet.*` RPC domain. Owns the state machine wiring
+ * (consumes `activity/status` session events and session lifecycle), the
+ * affinity ledger, and the persisted display config. The API gateway maps
+ * this service's methods onto `pet.state` / `pet.interact` /
+ * `pet.setVisible` / `pet.setConfig` for browser consumers.
+ * @module @linxin666/dsh-pet/service
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { Session } from '@deepseek-ai/dsh-session'
+import {
+  applyInteraction,
+  applyTurnReward,
+  defaultAffinityConfig,
+  rankOf,
+  type AffinityConfig,
+  type AffinityState,
+  type PetInteraction,
+} from './affinity.ts'
+import {
+  loadPetPersist,
+  petHomeDir,
+  savePetPersist,
+  DISPLAY_SIZE_MAX,
+  DISPLAY_SIZE_MIN,
+  DISPLAY_INSET_MAX,
+  PET_NAME_MAX_LENGTH,
+  type PetDisplayConfig,
+  type PetPersist,
+} from './persist.ts'
+import {
+  defaultTreatConfig,
+  settleTreatGrants,
+  consumeTreat,
+  type TreatConfig,
+} from './treats.ts'
+import {
+  defaultPetStateConfig,
+  PetStateMachine,
+  type PetStateConfig,
+  type PetStateSnapshot,
+} from './state.ts'
+
+/** Plugin configuration. */
+export interface PetConfig {
+  /** Affinity tuning. */
+  affinity?: Partial<AffinityConfig>
+  /** State machine tuning. */
+  state?: Partial<PetStateConfig>
+  /** Treat economy tuning. */
+  treats?: Partial<TreatConfig>
+  /** Persistence directory override (defaults to $DSH_HOME). */
+  persistDir?: string
+  /** Master switch for the plugin (browser half + host routes). */
+  enabled?: boolean
+}
+
+/**
+ * The pet's settings-namespace section: the display fields and name the web
+ * settings surface edits. `right`/`bottom` are also updated by drag
+ * interactions, which keep the settings document in sync through the service.
+ */
+export interface PetSettingsSection {
+  /** Master switch. */
+  visible: boolean
+  /** Scale of the rendered pet in px (sprite cell height). */
+  size: number
+  /** Horizontal inset from the viewport right edge, px. */
+  right: number
+  /** Vertical inset from the viewport bottom edge, px. */
+  bottom: number
+  /** User-customizable pet display name. */
+  name: string
+  /** Master switch for the plugin (browser half + host routes). */
+  enabled?: boolean
+}
+
+/** Settings namespace of the pet capability. Spelled here rather than imported: the browser half spells the same value. */
+export const PET_SETTINGS_NAMESPACE = 'pet'
+
+/** Snapshot returned by `pet.state`. */
+export interface PetStateView {
+  animation: PetStateSnapshot['animation']
+  bubble?: string
+  phase: PetStateSnapshot['phase']
+  sessionActive: boolean
+  /** Affinity ledger snapshot. */
+  affinity: {
+    points: number
+    rank: string
+    rankEmoji: string
+    pets: number
+    feeds: number
+    turns: number
+    /** True while the pet interaction is inside its cooldown. */
+    petCooldown: boolean
+    /** True while the feed is inside its cooldown. */
+    feedCooldown: boolean
+  }
+  /** Display configuration. */
+  display: PetDisplayConfig
+  /** User-customizable pet display name. */
+  name: string
+  /** Treat (小鱼干) stock snapshot. */
+  treats: {
+    /** Stocked treats now. */
+    stocked: number
+    /** Stock cap. */
+    max: number
+  }
+}
+
+/** Result of `pet.interact`. */
+export interface PetInteractResult {
+  /** Reaction copy bubble. */
+  reaction: string
+  /** Points gained (0 when inside the cooldown). */
+  delta: number
+  /** Full affinity snapshot (same shape as state view). */
+  affinity: PetStateView['affinity']
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    pet: PetService
+  }
+}
+
+/** One session/event guard: only the latest activity snapshot matters. */
+interface ActivityStatusEventLike {
+  phase?: string
+  line?: string
+  phrase?: string
+}
+
+/**
+ * Cordis service exposing the pet RPC domain. Lazy: nothing is scanned or
+ * written until a query or interaction arrives; event listeners update only
+ * in-memory state, and persistence happens on interaction/config changes
+ * plus every completed turn.
+ */
+export class PetService extends Service {
+  static inject: string[] = []
+
+  private readonly machine: PetStateMachine
+  private readonly affinityConfig: AffinityConfig
+  private readonly treatConfig: TreatConfig
+  private readonly persistDir: string
+  private persist: PetPersist
+  private lastTurnRewardAt = 0
+  private enabled: boolean
+  private disposeActivity: (() => void) | undefined
+
+  constructor(ctx: Context, config: PetConfig = {}) {
+    super(ctx, 'pet')
+    this.persistDir = config.persistDir ?? petHomeDir()
+    this.affinityConfig = { ...defaultAffinityConfig, ...(config.affinity ?? {}) }
+    this.treatConfig = { ...defaultTreatConfig, ...(config.treats ?? {}) }
+    this.machine = new PetStateMachine({
+      ...defaultPetStateConfig,
+      ...(config.state ?? {}),
+    })
+    this.persist = loadPetPersist(this.persistDir)
+    this.enabled = config.enabled ?? true
+
+    this.syncActivity()
+  }
+
+  /** Whether the pet service consumes session activity while enabled. */
+  isEnabled(): boolean {
+    return this.enabled
+  }
+
+  /** RPC: current pet state snapshot. */
+  async state(): Promise<PetStateView> {
+    return this.view()
+  }
+
+  /** Current persisted display config (read-only view). */
+  display(): PetDisplayConfig {
+    return { ...this.persist.display }
+  }
+
+  /** Current persisted pet name (read-only view). */
+  petName(): string {
+    return this.persist.name
+  }
+
+  /** Start or stop the session-activity listeners that drive the pet. */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled
+    this.syncActivity()
+  }
+
+  private syncActivity(): void {
+    if (this.disposeActivity !== undefined) {
+      this.disposeActivity()
+      this.disposeActivity = undefined
+    }
+    if (!this.enabled) return
+    this.disposeActivity = (() => {
+      const disposers = [
+        this.ctx.on('session/event', (_session: Session, event: { type: string; data?: unknown }) => {
+          if (event.type !== 'activity/status') return
+          const payload = (event.data ?? {}) as ActivityStatusEventLike
+          if (payload.phase === undefined) return
+          const phase = payload.phase as PetStateSnapshot['phase']
+          // Guard against unknown phases from newer activity trackers.
+          if (!['idle', 'waiting', 'thinking', 'tool', 'done'].includes(phase)) return
+          this.machine.onActivityStatus({
+            phase,
+            ...(typeof payload.line === 'string' ? { line: payload.line } : {}),
+            ...(typeof payload.phrase === 'string' ? { phrase: payload.phrase } : {}),
+          })
+          this.machine.onSessionActive()
+          if (phase === 'done') this.rewardTurn()
+        }),
+        this.ctx.on('session/disposed', () => {
+          this.machine.onSessionDisposed()
+        }),
+      ]
+      return () => { for (const dispose of disposers) dispose() }
+    })()
+  }
+
+  /** RPC: pet or feed the pet. */
+  async interact(kind: PetInteraction): Promise<PetInteractResult> {
+    const nowMs = Date.now()
+    // Feeding consumes a treat: settle the economy first (work + time
+    // output since the last settlement), then gate on the feed cooldown
+    // BEFORE spending stock — a feed inside the cooldown must not burn a
+    // treat for nothing.
+    if (kind === 'feed') this.settleTreats(nowMs)
+    const outcome = applyInteraction(this.persist.affinity, kind, nowMs, this.affinityConfig)
+    if (kind === 'feed' && !outcome.accepted) {
+      return { reaction: outcome.reaction, delta: 0, affinity: this.affinityView(this.persist.affinity) }
+    }
+    if (kind === 'feed') {
+      const consume = consumeTreat(this.persist.treats)
+      if (!consume.ok) {
+        const affinity = this.affinityView(this.persist.affinity)
+        return {
+          reaction: '没有小鱼干了，多陪鲸鱼娘工作一会儿吧～',
+          delta: 0,
+          affinity,
+        }
+      }
+      this.persist = { ...this.persist, treats: consume.ledger }
+    }
+    if (outcome.accepted) {
+      this.persist = { ...this.persist, affinity: outcome.affinity }
+      this.flush()
+    }
+    const affinity = this.affinityView(outcome.affinity)
+    return { reaction: outcome.reaction, delta: outcome.delta, affinity }
+  }
+
+  /** RPC: show or hide the pet. */
+  async setVisible(visible: boolean): Promise<{ ok: true; display: PetDisplayConfig }> {
+    this.persist = { ...this.persist, display: { ...this.persist.display, visible } }
+    this.flush()
+    this.syncSettingsFromPet()
+    return { ok: true, display: this.persist.display }
+  }
+
+  /** RPC: update display config (size / position). Values are clamped to whole pixels. */
+  async setConfig(patch: Partial<PetDisplayConfig>): Promise<{ ok: true; display: PetDisplayConfig }> {
+    const next = { ...this.persist.display, ...patch }
+    next.size = Math.round(Math.min(DISPLAY_SIZE_MAX, Math.max(DISPLAY_SIZE_MIN, next.size)))
+    next.right = Math.round(Math.min(DISPLAY_INSET_MAX, Math.max(0, next.right)))
+    next.bottom = Math.round(Math.min(DISPLAY_INSET_MAX, Math.max(0, next.bottom)))
+    this.persist = { ...this.persist, display: next }
+    this.flush()
+    this.syncSettingsFromPet()
+    return { ok: true, display: this.persist.display }
+  }
+
+  /** RPC: rename the pet (trimmed, 1–20 chars). */
+  async setName(name: string): Promise<{ ok: true; name: string } | { ok: false; error: string }> {
+    const trimmed = name.trim()
+    if (trimmed === '') return { ok: false, error: 'name-empty' }
+    if (trimmed.length > PET_NAME_MAX_LENGTH) return { ok: false, error: 'name-too-long' }
+    this.persist = { ...this.persist, name: trimmed }
+    this.flush()
+    this.syncSettingsFromPet()
+    return { ok: true, name: trimmed }
+  }
+
+  /**
+   * Apply a committed settings section to the persisted display config. Called
+   * by the settings surface on every change; values are clamped exactly like
+   * the setConfig RPC so both write paths converge.
+   * @param section - the resolved settings section.
+   */
+  applySettingsSection(section: PetSettingsSection): void {
+    const next = { ...this.persist.display }
+    next.visible = section.visible && (section.enabled ?? true)
+    next.size = Math.round(Math.min(DISPLAY_SIZE_MAX, Math.max(DISPLAY_SIZE_MIN, section.size)))
+    next.right = Math.round(Math.min(DISPLAY_INSET_MAX, Math.max(0, section.right)))
+    next.bottom = Math.round(Math.min(DISPLAY_INSET_MAX, Math.max(0, section.bottom)))
+    this.persist = { ...this.persist, display: next, name: section.name.trim() }
+    this.flush()
+  }
+
+  /** Mirror the persisted display config into the settings document (best-effort). */
+  private syncSettingsFromPet(): void {
+    const settings = this.ctx.get('settings', false) as { update(ns: string, patch: object): Promise<void> } | undefined
+    if (settings === undefined) return
+    void settings.update(PET_SETTINGS_NAMESPACE, {
+      visible: this.persist.display.visible,
+      size: this.persist.display.size,
+      right: this.persist.display.right,
+      bottom: this.persist.display.bottom,
+      name: this.persist.name,
+    }).catch(() => {
+      // A settings write failure must not break the pet's own persistence.
+    })
+  }
+
+  /** Award the turn reward once per done phase (idempotent per transition). */
+  private rewardTurn(): void {
+    const nowMs = Date.now()
+    // A done phase can repeat while celebrating; only reward the first.
+    if (nowMs - this.lastTurnRewardAt < 5_000) return
+    this.lastTurnRewardAt = nowMs
+    this.persist = { ...this.persist, affinity: applyTurnReward(this.persist.affinity, this.affinityConfig) }
+    this.flush()
+  }
+
+  /**
+   * Settle the treat economy (work + time output since the last
+   * settlement); persists only when treats were actually granted.
+   */
+  private settleTreats(nowMs: number): void {
+    const settlement = settleTreatGrants(
+      this.persist.treats,
+      this.persist.affinity.turns,
+      nowMs,
+      this.treatConfig,
+    )
+    if (settlement.gained > 0) {
+      this.persist = { ...this.persist, treats: settlement.ledger }
+      this.flush()
+    }
+  }
+
+  private view(): PetStateView {
+    const snapshot = this.machine.render()
+    // Time-output treats accrue while the host is idle too; settle on read.
+    this.settleTreats(Date.now())
+    return {
+      animation: snapshot.animation,
+      ...(snapshot.bubble === undefined ? {} : { bubble: snapshot.bubble }),
+      phase: snapshot.phase,
+      sessionActive: snapshot.sessionActive,
+      affinity: this.affinityView(this.persist.affinity),
+      display: { ...this.persist.display },
+      name: this.persist.name,
+      treats: {
+        stocked: this.persist.treats.treats,
+        max: this.treatConfig.maxTreats,
+      },
+    }
+  }
+
+  private affinityView(affinity: AffinityState): PetStateView['affinity'] {
+    const nowMs = Date.now()
+    const rank = rankOf(affinity.points)
+    return {
+      points: affinity.points,
+      rank: rank.name,
+      rankEmoji: rank.emoji,
+      pets: affinity.pets,
+      feeds: affinity.feeds,
+      turns: affinity.turns,
+      petCooldown: nowMs - affinity.lastPetAt < this.affinityConfig.petCooldownMs,
+      feedCooldown: nowMs - affinity.lastFeedAt < this.affinityConfig.feedCooldownMs,
+    }
+  }
+
+  private flush(): void {
+    try {
+      savePetPersist(this.persist, this.persistDir)
+    } catch {
+      // Persistence is best-effort; the in-memory ledger keeps working.
+    }
+  }
+}

package/src/state.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import {
+  animationForPhase,
+  defaultPetStateConfig,
+  PetStateMachine,
+  rowOf,
+  type PetAnimation,
+} from './state.ts'
+
+describe('animationForPhase', () => {
+  it('maps each activity phase onto the animation contract', () => {
+    expect(animationForPhase('thinking')).toBe('running')
+    expect(animationForPhase('tool')).toBe('running-right')
+    expect(animationForPhase('waiting')).toBe('waiting')
+    expect(animationForPhase('done')).toBe('jumping')
+    expect(animationForPhase('idle')).toBe('idle')
+  })
+})
+
+describe('PetStateMachine', () => {
+  it('celebrates for celebrateMs after done, then settles to idle', () => {
+    let now = 1_000_000
+    const machine = new PetStateMachine({ celebrateMs: 2400 }, () => now)
+    machine.onSessionActive()
+    machine.onActivityStatus({ phase: 'done', line: '完成' })
+    expect(machine.render().animation).toBe('jumping')
+    now += 2399
+    expect(machine.render().animation).toBe('jumping')
+    now += 2
+    expect(machine.render().animation).toBe('idle')
+  })
+
+  it('shows the phrase bubble when present, else the line', () => {
+    const machine = new PetStateMachine(defaultPetStateConfig, () => 1_000)
+    machine.onActivityStatus({ phase: 'thinking', phrase: '查资料中', line: 'tool: grep' })
+    expect(machine.render().bubble).toBe('查资料中')
+    machine.onActivityStatus({ phase: 'thinking', line: 'tool: grep' })
+    expect(machine.render().bubble).toBe('tool: grep')
+    machine.onActivityStatus({ phase: 'waiting' })
+    expect(machine.render().bubble).toBeUndefined()
+  })
+
+  it('resets on session dispose', () => {
+    const machine = new PetStateMachine(defaultPetStateConfig, () => 1_000)
+    machine.onSessionActive()
+    machine.onActivityStatus({ phase: 'done' })
+    machine.onSessionDisposed()
+    const s = machine.render()
+    expect(s.sessionActive).toBe(false)
+    expect(s.animation).toBe('idle')
+    expect(s.phase).toBe('idle')
+  })
+
+  it('keeps every animation on a known spritesheet row', () => {
+    const animations: readonly PetAnimation[] = [
+      'idle', 'running-right', 'running-left', 'waving', 'jumping',
+      'failed', 'waiting', 'running', 'review',
+    ]
+    for (const animation of animations) {
+      const row = rowOf(animation)
+      expect(row).toBeGreaterThanOrEqual(0)
+      expect(row).toBeLessThanOrEqual(8)
+    }
+  })
+})