hob-bot 1.3.0 → 1.5.0

package/server/src/usage.ts

@@ -0,0 +1,291 @@
+// 消耗：不另外记账，直接从会话文件里 assistant 消息的 usage 统计（见 docs/architecture.md“消耗”）。
+import { createReadStream, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { TokenPrice, UsageAssistant, UsageModelPrice, UsagePrices, UsageRow, UsageSource, UsageView } from "../../shared/types.ts";
+import type { SettingsStore } from "./settings.ts";
+import type { Store } from "./store.ts";
+import type { UsagePrices as PriceTable } from "./usage-prices.ts";
+
+/** 一条 assistant 消息的用量；日志按毫秒记，归到哪一天按设置的时区算。 */
+interface UsageRecord {
+  at: number;
+  provider: string;
+  model: string;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** 一个会话文件：大小和修改时间没变就不重读，变长时只读追加的那一段。 */
+interface CachedFile {
+  size: number;
+  mtimeMs: number;
+  offset: number; // 已读到的字节位置（只到最后一个完整换行，半行留着下次读）
+  records: UsageRecord[];
+  assistantId: string;
+  assistantName: string;
+  source: UsageSource;
+}
+
+interface Target {
+  file: string;
+  assistantId: string;
+  assistantName: string;
+  source: UsageSource;
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** 一行会话记录 → 用量；不是带用量字段的 assistant 消息就返回 undefined。 */
+function recordOf(line: string): UsageRecord | undefined {
+  let entry: { type?: unknown; timestamp?: unknown; message?: any };
+  try {
+    entry = JSON.parse(line) as typeof entry;
+  } catch {
+    return undefined; // 半行（进程被杀）跳过
+  }
+  if (entry?.type !== "message") return undefined;
+  const message = entry.message;
+  if (message?.role !== "assistant") return undefined;
+  const provider = typeof message.provider === "string" ? message.provider : "";
+  const model = typeof message.model === "string" ? message.model : "";
+  if (!provider || !model) return undefined;
+  const at = typeof message.timestamp === "number" ? message.timestamp : Date.parse(String(message.timestamp ?? entry.timestamp ?? ""));
+  if (!Number.isFinite(at)) return undefined;
+  const usage = message.usage ?? {};
+  return {
+    at,
+    provider,
+    model,
+    input: num(usage.input),
+    output: num(usage.output),
+    cacheRead: num(usage.cacheRead),
+    cacheWrite: num(usage.cacheWrite),
+  };
+}
+
+/** 从 start 字节起读完整的行，返回下一次从这里接着读的字节位置和用量。 */
+async function readUsage(file: string, start: number): Promise<{ offset: number; records: UsageRecord[] }> {
+  const records: UsageRecord[] = [];
+  let pending: Buffer = Buffer.alloc(0);
+  let read = start;
+  for await (const chunk of createReadStream(file, { start })) {
+    const buffer = chunk as Buffer;
+    read += buffer.length;
+    pending = pending.length ? Buffer.concat([pending, buffer]) : buffer;
+    let from = 0;
+    for (let at = pending.indexOf(0x0a); at !== -1; at = pending.indexOf(0x0a, from)) {
+      const line = pending.toString("utf8", from, at);
+      from = at + 1;
+      const record = recordOf(line);
+      if (record) records.push(record);
+    }
+    pending = pending.subarray(from);
+  }
+  return { offset: read - pending.length, records };
+}
+
+/** 时间戳 → 设置时区下的日期（同一小时里的本地日期一样，按时段记一下省掉重复的时区换算）。 */
+function dayKeyer(timezone: string): (at: number) => string {
+  const format = new Intl.DateTimeFormat("sv-SE", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit" });
+  const memo = new Map<number, string>();
+  return (at) => {
+    const hour = Math.floor(at / 3_600_000);
+    const hit = memo.get(hour);
+    if (hit) return hit;
+    const day = format.format(new Date(at));
+    memo.set(hour, day);
+    return day;
+  };
+}
+
+function readDir(path: string): string[] {
+  return existsSync(path) ? readdirSync(path) : [];
+}
+
+/** 所有任务的会话目录：在的助手和归档的助手都算。 */
+function jobSessionDirs(home: string): string[] {
+  const out: string[] = [];
+  const roots = [
+    ...readDir(join(home, "assistants")).map((id) => join(home, "assistants", id, "jobs")),
+    ...readDir(join(home, "archive", "assistants")).map((folder) => join(home, "archive", "assistants", folder, "jobs")),
+  ];
+  for (const root of roots) for (const id of readDir(root)) out.push(join(root, id));
+  return out;
+}
+
+function readJson(path: string): Record<string, unknown> | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function modelPrice(id: string, table: Record<string, TokenPrice>, overrides: Record<string, TokenPrice>): UsageModelPrice | null {
+  const custom = Object.hasOwn(overrides, id) ? overrides[id] : undefined;
+  const base = Object.hasOwn(table, id) ? table[id] : undefined;
+  if (custom && base) return { price: custom, custom: true, default: base };
+  if (custom) return { price: custom, custom: true };
+  return base ? { price: base, custom: false } : null;
+}
+
+/**
+ * 消耗统计：扫出全部会话文件（助手对话、归档助手的对话、任务的会话），按文件缓存解析结果。
+ * 第一次扫描是异步流式读，不阻塞其他请求。
+ */
+export class UsageService {
+  private files = new Map<string, CachedFile>();
+  private assistants = new Map<string, UsageAssistant>();
+  private scanning?: Promise<void>;
+  /** 读过几次会话文件（文件没变时不该再读，测试用它看这条） */
+  reads = 0;
+
+  constructor(
+    private readonly options: {
+      home: string;
+      store: Store;
+      settings: SettingsStore;
+      prices: PriceTable;
+    },
+  ) {}
+
+  /** 启动后先扫一遍；服务不等它。 */
+  warmup(): void {
+    void this.scan().catch(() => {});
+  }
+
+  async view(): Promise<UsageView> {
+    await this.scan();
+    const timezone = this.options.settings.settings.general.timezone;
+    const dayOf = dayKeyer(timezone);
+    const rows = new Map<string, UsageRow>();
+    for (const file of this.files.values()) {
+      for (const record of file.records) {
+        const day = dayOf(record.at);
+        const key = [day, file.assistantId, file.source, record.provider, record.model].join("\u0000");
+        let row = rows.get(key);
+        if (!row) {
+          row = { day, assistantId: file.assistantId, source: file.source, provider: record.provider, model: record.model, requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+          rows.set(key, row);
+        }
+        row.requests += 1;
+        row.input += record.input;
+        row.output += record.output;
+        row.cacheRead += record.cacheRead;
+        row.cacheWrite += record.cacheWrite;
+      }
+    }
+    return {
+      timezone,
+      rows: [...rows.values()].sort((a, b) => a.day.localeCompare(b.day) || a.assistantId.localeCompare(b.assistantId) || a.source.localeCompare(b.source) || a.model.localeCompare(b.model)),
+      assistants: [...this.assistants.values()],
+      prices: await this.prices(),
+    };
+  }
+
+  /** 一个模型现在的单价（`PUT /api/usage/price` 的返回用）。 */
+  async priceOf(model: string): Promise<UsageModelPrice | null> {
+    await this.options.prices.ensure();
+    return modelPrice(model, this.options.prices.table().prices, this.options.settings.settings.usage?.prices ?? {});
+  }
+
+  private async priceTable(): Promise<Record<string, UsageModelPrice>> {
+    const table = this.options.prices.table().prices;
+    const overrides = this.options.settings.settings.usage?.prices ?? {};
+    const models: Record<string, UsageModelPrice> = {};
+    for (const id of new Set([...Object.keys(table), ...Object.keys(overrides)])) {
+      const price = modelPrice(id, table, overrides);
+      if (price) models[id] = price;
+    }
+    return models;
+  }
+
+  private async prices(): Promise<UsagePrices> {
+    await this.options.prices.ensure();
+    const { fetchedAt, error } = this.options.prices.table();
+    return { updatedAt: fetchedAt, error, models: await this.priceTable() };
+  }
+
+  private async scan(): Promise<void> {
+    this.scanning ??= this.doScan().finally(() => {
+      this.scanning = undefined;
+    });
+    await this.scanning;
+  }
+
+  private async doScan(): Promise<void> {
+    const home = this.options.home;
+    const seen = new Set<string>();
+    const assistants = new Map<string, UsageAssistant>();
+    for (const id of readDir(join(home, "assistants"))) {
+      const file = join(home, "assistants", id, "router.jsonl");
+      if (!existsSync(file)) continue;
+      const name = this.options.store.assistant(id)?.name ?? id;
+      assistants.set(id, { id, name, archived: false });
+      await this.sync({ file, assistantId: id, assistantName: name, source: "chat" }, seen);
+    }
+    const archiveRoot = join(home, "archive", "assistants");
+    for (const folder of readDir(archiveRoot)) {
+      const file = join(archiveRoot, folder, "router.jsonl");
+      if (!existsSync(file)) continue;
+      // 归档目录名是 <助手 id>-<归档时间>，id 从归档里的档案读
+      const profile = readJson(join(archiveRoot, folder, "profile.json"));
+      const id = typeof profile?.id === "string" && profile.id ? profile.id : folder;
+      const name = typeof profile?.name === "string" && profile.name ? profile.name : id;
+      if (!assistants.has(id)) assistants.set(id, { id, name, archived: true });
+      await this.sync({ file, assistantId: id, assistantName: name, source: "chat" }, seen);
+    }
+    for (const jobDir of jobSessionDirs(home)) {
+      const file = join(jobDir, "worker.jsonl");
+      if (!existsSync(file)) continue;
+      const cached = this.files.get(file);
+      const job = cached ? undefined : this.options.store.job(basename(jobDir));
+      const assistantId = cached?.assistantId ?? job?.assistantId;
+      if (!assistantId) continue;
+      const live = this.options.store.assistant(assistantId);
+      const name = cached?.assistantName ?? job?.assistantName ?? live?.name ?? assistantId;
+      if (!assistants.has(assistantId)) assistants.set(assistantId, { id: assistantId, name, archived: !live });
+      await this.sync({ file, assistantId, assistantName: name, source: "job" }, seen);
+    }
+    for (const file of [...this.files.keys()]) if (!seen.has(file)) this.files.delete(file);
+    this.assistants = assistants;
+  }
+
+  private async sync(target: Target, seen: Set<string>): Promise<void> {
+    seen.add(target.file);
+    let stat;
+    try {
+      stat = statSync(target.file);
+    } catch {
+      this.files.delete(target.file);
+      return;
+    }
+    const cached = this.files.get(target.file);
+    const usable = cached && cached.assistantId === target.assistantId && cached.source === target.source;
+    if (usable && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return;
+    // 会话文件只往后写：变长时接着上次的位置读，否则整份重读
+    const appendFrom = usable && stat.size > cached.size ? cached.offset : 0;
+    let parsed;
+    try {
+      parsed = await readUsage(target.file, appendFrom);
+    } catch {
+      return; // 读不了就留着上次的记录，不当成 0
+    }
+    this.reads += 1;
+    let records = parsed.records;
+    if (appendFrom && cached) records = [...cached.records, ...parsed.records];
+    this.files.set(target.file, {
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      offset: parsed.offset,
+      records,
+      assistantId: target.assistantId,
+      assistantName: target.assistantName,
+      source: target.source,
+    });
+  }
+}

package/server/src/worker-tools.ts

@@ -13,14 +13,13 @@ export function registerReportTool(runtime: HobRuntime, jobId: string): ToolDefi
   return {
     name: "report",
     label: "提交结果",
-    description: "任务结束时调用一次，提交结果。",
-    promptSnippet: "任务结束必须调用 report 提交结果。",
+    description: "交结果。做完了、做不下去了，或者要用户拍板时调用。",
     parameters: Type.Object({
       outcome: Type.Unsafe<"done" | "stuck" | "need_approval">(
-        Type.String({ description: "done 做完 / stuck 做不下去（写明缺什么）/ need_approval 需要用户拍板" }),
+        Type.String({ description: "done 要的结果拿到了；stuck 要的结果没拿到（做不下去或没做完），写明做到哪、缺什么；need_approval 要用户拍板才能往下做，写明要定什么。" }),
       ),
       result: Type.String({ description: "完整结果，按这个顺序写：结论；做了什么；验证了什么、怎么验证的；没验证或不确定的；需要用户决定的。带上数据、链接和文件路径，写给派活的助手。" }),
-      files: Type.Optional(Type.Array(Type.String(), { description: "交给助手的文件（绝对路径），比如要给用户看的图" })),
+      files: Type.Optional(Type.Array(Type.String(), { description: "交给助手的文件（绝对路径），比如要给用户看的图。" })),
     }),
     execute: async (_id, params: any) => {
       // 不认识的结果不能当成已完成：退回让模型重新调用
@@ -46,11 +45,10 @@ export function registerAskTool(runtime: HobRuntime, jobId: string): ToolDefinit
   return {
     name: "ask_user",
     label: "询问用户",
-    description: "问你的助手，等它回复：它会自己答，或者去问用户。用于用户定的规则要求先确认的事，或发送、删除、付费这类撤不回的事。其他拿不准的不问，按合理的假设做下去，把假设写进 result。",
-    promptSnippet: "规则要求执行前确认的事，执行前必须调用 ask_user。",
+    description: "问你的助手，等它回复。它能答的会直接答，要用户定的会去问用户。",
     parameters: Type.Object({
       title: Type.String({ description: "问题，一句话" }),
-      detail: Type.Optional(Type.String({ description: "补充说明，写清后果" })),
+      detail: Type.Optional(Type.String({ description: "补充说明，写清后果。" })),
       options: Type.Array(
         Type.Object({
           label: Type.String({ description: "选项文字" }),
@@ -84,8 +82,7 @@ export function registerImageTool(runtime: HobRuntime, jobId: string): ToolDefin
     name: "generate_image",
     label: "生成图片",
     description:
-      "按文字描述生成一张图片，返回图片的绝对路径（存在任务工作目录）。要把图给用户看，就把这个路径放进 report 的 files。",
-    promptSnippet: "生成图片用 generate_image；要给用户看就把它放进 report 的 files。",
+      "按文字描述生成一张图片，返回图片的绝对路径（存在任务工作目录）。要给用户看，就把路径放进 report 的 files。",
     parameters: Type.Object({
       prompt: Type.String({ description: "要画什么，越具体越好" }),
       size: Type.Optional(

package/shared/types.ts

@@ -225,9 +225,11 @@ export interface Assistant {
   prop?: CustomProp;
   primary: boolean; // 只有 hob 为 true
   pinned: boolean; // 左栏顶部大头像
+  /** 置顶区里的位置：小的在前，拖动头像换位置时改它；没排过的排在排过的后面，再按创建时间 */
+  pinOrder?: number;
   hidden: boolean; // 收起的助手
   notify: boolean; // 需要确认时通知我
-  instructions: string; // 补充说明：用户可直接编辑的自定义指令，这个助手特有的做法写这里
+  instructions: string; // 补充说明：用户可直接编辑该助手需要知道的专属事实
   /** 这个助手用哪些模型；缺省全部跟随设置 → 模型 */
   models?: {
     conversation?: ModelPick; // 不填 = 跟随全局的对话模型
@@ -275,16 +277,40 @@ export interface RoutineRun {
   tokens?: number; // 技能二期：输入加输出 token
 }
 
+export interface RoutineCheck {
+  script: string; // 到点先跑的 bash 脚本：没有输出就跳过这一次
+  then: "notify" | "job"; // 有输出时：notify 把输出作为提醒发到对话；job 带着输出开始任务
+}
+
+export interface RoutineChecks {
+  total: number; // 检查了几次
+  hits: number; // 触发了几次
+  failing?: string; // 最近一次失败的原因，下次成功就清掉
+  lastAt?: Iso; // 上次检查的时间
+}
+
+/** 定时到点（或点「立即运行」）这一次的结果。 */
+export interface RoutineTick {
+  outcome: "job" | "notify" | "quiet" | "failed"; // job 开了任务；notify 已发到对话；quiet 没变化；failed 检查失败
+  job?: Job;
+  reason?: string; // failed 时的原因
+}
+
 export interface Routine {
   id: string;
   assistantId: string;
   name: string; // 如 "每日简报"
   instruction: string; // 要做什么
-  schedules: string[]; // cron 表达式，如 "0 9 * * *"；可多个（"再加一个"）
+  schedules: string[]; // cron 表达式（如 "0 9 * * *"）或具体时间（如 "2026-11-08T09:00"）；可多个（"再加一个"）
   active: boolean;
   createdAt: Iso;
   runs: RoutineRun[]; // 最近 20 次，新的在前
   skill?: string; // 绑定这个助手自己的技能（AssistantSkill.name）：每次执行按它做
+  check?: RoutineCheck; // 到点先跑脚本，多数时候没变化就不开任务
+  checks?: RoutineChecks; // 检查计数和最近一次失败的原因
+  once?: boolean; // 做成一次就停：没有检查脚本的跑完就停，有检查的第一次有输出就停
+  stoppedAt?: Iso; // 上次停下的时间
+  stopReason?: "hit" | "finished"; // hit=按 once 停了；finished=所有执行时间都跑完了
 }
 
 export interface Delegation {
@@ -368,6 +394,12 @@ export interface JobsPage {
   hasMore: boolean;
 }
 
+export type SedimentStatus =
+  | { status: "running" }
+  | { status: "saved"; name: string; title: string; version: number; updated: boolean }
+  | { status: "empty"; reason: string }
+  | { status: "failed"; reason: string };
+
 export interface Job {
   id: string; // "t-" + 4 位以上
   assistantId: string;
@@ -392,6 +424,8 @@ export interface Job {
   modelReason?: string; // 换了模型的原因，如「需要看图，换成了 X」
   inputs?: string[]; // 交给任务的附件（绝对路径）
   routineId?: string; // 由定时触发
+  sediment?: SedimentStatus; // 在原任务中沉淀技能，不改变任务状态
+  skills?: string[]; // 派活时交给任务的本助手技能
   skillsUsed?: string[]; // 这次读过的本助手技能（AssistantSkill.name）
   delegationId?: string; // 转交回合创建的任务
   /** 续做前每一轮结束时的样子（第 0 轮起）。对话里前面几张任务卡照它显示，最后一张跟着任务实时变 */
@@ -549,6 +583,78 @@ export interface PushSettings {
   email: string;
 }
 
+/** 每百万 token 的单价（美元），四项。 */
+export interface TokenPrice {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** 设置 → 消耗：按模型改过的单价，键是模型 id（服务商 id 是用户自己起的，价格按模型 id 对）。 */
+export interface UsageSettings {
+  prices: Record<string, TokenPrice>;
+}
+
+/** 用量的来源：助手自己的对话 / 任务的会话。 */
+export type UsageSource = "chat" | "job";
+
+/** GET /api/usage 的一行：按天 × 助手 × 来源 × 服务商 × 模型汇总；day 是设置时区下的日期。 */
+export interface UsageRow {
+  day: string; // 2026-11-06
+  assistantId: string;
+  source: UsageSource;
+  provider: string;
+  model: string;
+  requests: number; // assistant 消息条数
+  input: number; // 没命中缓存的输入 token
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** 有会话文件的助手（归档的也算），「按助手」一节用它的名字。 */
+export interface UsageAssistant {
+  id: string;
+  name: string;
+  archived: boolean;
+}
+
+/** 一个模型现在的单价：改过的是自定，default 是价格表里的默认值（恢复默认和对比用）。 */
+export interface UsageModelPrice {
+  price: TokenPrice;
+  custom: boolean;
+  default?: TokenPrice;
+}
+
+/** 价格表：默认单价从 models.dev 拉，一天最多更新一次。 */
+export interface UsagePrices {
+  updatedAt: Iso | null; // 价格表拉到的时间；从没拉到过为 null
+  error: string | null; // 这次更新价格表失败的原因；成功为 null
+  models: Record<string, UsageModelPrice>; // 键是模型 id
+}
+
+/** GET /api/usage：按天、助手、来源、服务商、模型分组的明细 + 价格；前端自己汇总。 */
+export interface UsageView {
+  timezone: string;
+  rows: UsageRow[];
+  assistants: UsageAssistant[];
+  prices: UsagePrices;
+}
+
+/** PUT /api/usage/price：改一个模型的单价，price 为 null 就恢复默认。 */
+export interface UsagePricePatch {
+  revision: number;
+  model: string;
+  price: TokenPrice | null;
+}
+
+/** PUT /api/usage/price：新 revision 的整份设置 + 这个模型现在的单价（既没价格表也没自定时为 null）。 */
+export interface UsagePriceSaved {
+  settings: SettingsFile;
+  price: UsageModelPrice | null;
+}
+
 export interface Settings {
   general: GeneralSettings;
   /** 服务商（Key 在 secrets.json，这里只放不敏感的） */
@@ -565,6 +671,8 @@ export interface Settings {
   push: PushSettings;
   /** 知识库二期：向量模型（Key 在 secrets.json 的 embedding）；缺省 = 关闭，只按关键词查 */
   knowledge?: { embedding: EmbeddingSettings };
+  /** 消耗：按模型改过的单价；没改过的模型用 models.dev 的价格 */
+  usage?: UsageSettings;
 }
 
 /** 设置 → 知识库：向量模型，照图像生成的做法（兼容接口的地址 + 模型，Key 单独存）。 */
@@ -698,7 +806,6 @@ export type HobEvent =
   | { type: "item"; assistantId: string; item: Item } // 新条目，或按 id 替换
   | { type: "delta"; assistantId: string; itemId: string; text: string } // 流式追加到 assistant 条目
   | { type: "job"; job: Job }
-  | { type: "sediment-finished"; jobId: string }
   | { type: "delegation"; delegation: Delegation }
   | { type: "job_step"; jobId: string; step: JobStep } // 新的一步，或按 id 替换（输出流式更新、跑完补结果）
   | { type: "router-activity"; assistantId: string; activity: RouterActivity | null }