hob-bot 1.2.0 → 1.4.0

package/server/src/usage-prices.ts

@@ -0,0 +1,165 @@
+// 模型单价：默认从 models.dev 拉，一天最多更新一次；存在 HOB_HOME/usage-prices.json，拉不到就用上次的。
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { TokenPrice } from "../../shared/types.ts";
+
+const SOURCE = "https://models.dev/api.json";
+const FILE = "usage-prices.json";
+const DAY = 24 * 3600 * 1000;
+/** 失败后这么久不再试：价格表本来就一天更新一次，失败时别让每次打开页面都等一次超时。 */
+const RETRY = 10 * 60 * 1000;
+const TIMEOUT = 10_000;
+
+/** 模型厂商自己那一家：同一个模型 id 出现在多个服务商里时优先它。 */
+const VENDOR_PROVIDERS = new Set(["openai", "anthropic", "deepseek", "google", "xai", "mistral", "zhipuai", "moonshotai"]);
+
+/** HOB_HOME/usage-prices.json：拉到的单价 + 上次更新和上次尝试的时间。 */
+interface PriceFile {
+  fetchedAt: string | null;
+  attemptAt: string | null;
+  error: string | null;
+  prices: Record<string, TokenPrice>;
+}
+
+const EMPTY: PriceFile = { fetchedAt: null, attemptAt: null, error: null, prices: {} };
+
+function readFile(home: string): PriceFile {
+  const path = join(home, FILE);
+  if (!existsSync(path)) return EMPTY;
+  try {
+    const stored = JSON.parse(readFileSync(path, "utf8")) as Partial<PriceFile>;
+    const prices = stored.prices && typeof stored.prices === "object" ? stored.prices : {};
+    return {
+      fetchedAt: typeof stored.fetchedAt === "string" ? stored.fetchedAt : null,
+      attemptAt: typeof stored.attemptAt === "string" ? stored.attemptAt : null,
+      error: typeof stored.error === "string" ? stored.error : null,
+      prices: Object.fromEntries(Object.entries(prices).filter(([, price]) => isPrice(price))),
+    };
+  } catch {
+    return EMPTY;
+  }
+}
+
+function isPrice(value: unknown): value is TokenPrice {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const price = value as Record<string, unknown>;
+  return ["input", "output", "cacheRead", "cacheWrite"].every((key) => typeof price[key] === "number" && Number.isFinite(price[key]) && (price[key] as number) >= 0);
+}
+
+/** 用户填的单价：四项都是大于等于 0 的数字，不合法说清哪一项。 */
+export function checkPrice(raw: unknown): TokenPrice {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("单价要填四项：输入、输出、缓存读、缓存写。");
+  const input = raw as Record<string, unknown>;
+  const names: Record<keyof TokenPrice, string> = { input: "输入", output: "输出", cacheRead: "缓存读", cacheWrite: "缓存写" };
+  const out = {} as TokenPrice;
+  for (const key of Object.keys(names) as (keyof TokenPrice)[]) {
+    const value = input[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      throw new Error(`「${names[key]}」的单价要填大于等于 0 的数字（美元 / 百万 token）。`);
+    }
+    out[key] = Number(value.toFixed(6));
+  }
+  return out;
+}
+
+function failureReason(error: unknown): string {
+  if (error instanceof Error) {
+    if (error.name === "TimeoutError" || error.name === "AbortError") return "请求超时";
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * models.dev 的整份数据 → 模型 id → 单价。
+ * 同一个模型 id 在多个服务商里都有时，优先模型厂商自己那家（`canonical_model_id` 指回自己，或 id 在厂商名单里）。
+ */
+export function indexPrices(raw: unknown): Record<string, TokenPrice> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("返回的不是服务商列表");
+  const candidates = new Map<string, { vendor: boolean; price: TokenPrice }[]>();
+  for (const [providerId, provider] of Object.entries(raw as Record<string, unknown>)) {
+    const models = (provider as { models?: unknown } | null)?.models;
+    if (!models || typeof models !== "object" || Array.isArray(models)) continue;
+    for (const [modelId, model] of Object.entries(models as Record<string, unknown>)) {
+      const cost = (model as { cost?: unknown } | null)?.cost as Record<string, unknown> | null | undefined;
+      if (!cost || typeof cost.input !== "number" || typeof cost.output !== "number") continue;
+      const canonical = (model as { canonical_model_id?: unknown }).canonical_model_id;
+      const vendor = (typeof canonical === "string" && canonical.split("/")[0] === providerId) || VENDOR_PROVIDERS.has(providerId);
+      const price: TokenPrice = {
+        input: cost.input,
+        output: cost.output,
+        cacheRead: typeof cost.cache_read === "number" ? cost.cache_read : 0,
+        cacheWrite: typeof cost.cache_write === "number" ? cost.cache_write : 0,
+      };
+      const list = candidates.get(modelId) ?? [];
+      list.push({ vendor, price });
+      candidates.set(modelId, list);
+    }
+  }
+  const prices: Record<string, TokenPrice> = Object.fromEntries([...candidates].map(([modelId, list]) => [modelId, (list.find((item) => item.vendor) ?? list[0]).price]));
+  if (!Object.keys(prices).length) throw new Error("返回里没有模型价格");
+  return prices;
+}
+
+/**
+ * 价格表：一天最多更新一次；拉不到就留着上次的，并把原因写下来给页面显示。
+ * `fetchImpl` 和 `now` 只为测试注入（不连真实网络）。
+ */
+export class UsagePrices {
+  private file: PriceFile;
+  private loading?: Promise<void>;
+
+  constructor(private readonly options: { home: string; fetchImpl?: typeof fetch; now?: () => number }) {
+    this.file = readFile(options.home);
+  }
+
+  private get now(): number {
+    return this.options.now?.() ?? Date.now();
+  }
+
+  /** 需要更新时拉一次（同一时刻只拉一次）；要更新时会把结果写进 HOB_HOME。 */
+  async ensure(): Promise<void> {
+    this.loading ??= this.refresh().finally(() => {
+      this.loading = undefined;
+    });
+    await this.loading;
+  }
+
+  /** 现在用的价格和上次更新的状态。 */
+  table(): { fetchedAt: string | null; error: string | null; prices: Record<string, TokenPrice> } {
+    return { fetchedAt: this.file.fetchedAt, error: this.file.error, prices: this.file.prices };
+  }
+
+  private async refresh(): Promise<void> {
+    const now = this.now;
+    const fetchedAt = this.file.fetchedAt ? Date.parse(this.file.fetchedAt) : 0;
+    if (now - fetchedAt < DAY) return;
+    const attemptAt = this.file.attemptAt ? Date.parse(this.file.attemptAt) : 0;
+    if (attemptAt > fetchedAt && now - attemptAt < RETRY) return;
+    try {
+      this.file = { fetchedAt: new Date(now).toISOString(), attemptAt: new Date(now).toISOString(), error: null, prices: indexPrices(await this.fetchSource()) };
+    } catch (error) {
+      this.file = { ...this.file, attemptAt: new Date(now).toISOString(), error: failureReason(error) };
+    }
+    this.write();
+  }
+
+  private async fetchSource(): Promise<unknown> {
+    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(SOURCE, { signal: AbortSignal.timeout(TIMEOUT), headers: { accept: "application/json" } });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("返回的不是有效 JSON");
+    }
+  }
+
+  private write(): void {
+    const path = join(this.options.home, FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(this.file, null, 2)}\n`);
+    renameSync(tmp, path);
+  }
+}

package/server/src/usage.ts

@@ -0,0 +1,281 @@
+// 消耗：不另外记账，直接从会话文件里 assistant 消息的 usage 统计（见 docs/architecture.md“消耗”）。
+import { createReadStream, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { 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 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 jobId of readDir(join(home, "jobs"))) {
+      const file = join(home, "jobs", jobId, "worker.jsonl");
+      if (!existsSync(file)) continue;
+      // 没有缓存时才读 job.json：任务的所属助手建好就不变
+      const cached = this.files.get(file);
+      const job = cached ? undefined : this.options.store.job(jobId);
+      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: "要给用户看的文件（绝对路径）" })),
+      result: Type.String({ description: "完整结果，按这个顺序写：结论；做了什么；验证了什么、怎么验证的；没验证或不确定的；需要用户决定的。带上数据、链接和文件路径，写给派活的助手。" }),
+      files: Type.Optional(Type.Array(Type.String(), { description: "交给助手的文件（绝对路径），比如要给用户看的图。" })),
     }),
     execute: async (_id, params: any) => {
       // 不认识的结果不能当成已完成：退回让模型重新调用
@@ -46,38 +45,30 @@ export function registerAskTool(runtime: HobRuntime, jobId: string): ToolDefinit
   return {
     name: "ask_user",
     label: "询问用户",
-    description: "在对话里出选择题卡片（2 到 3 个选项），等用户选，返回用户的选择。用于用户定的规则要求先确认的事，或发送、删除、付费这类撤不回的事。",
-    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: "选项文字" }),
         }),
         { description: "2 到 3 个选项", minItems: 2, maxItems: 3 },
       ),
-      remember: Type.Optional(Type.String({ description: "同类事以后可以不再问时，填这类事的简称（如「清理临时目录」）；卡片会多一个「以后直接做」的选项。" })),
     }),
     execute: async (_id, params: any) => {
       const labels: { label: string }[] = Array.isArray(params.options) ? params.options : [];
       if (labels.length < 2 || labels.length > 3) {
         return { content: [{ type: "text" as const, text: "选项要 2 到 3 个。" }], details: undefined, isError: true };
       }
-      const remember = typeof params.remember === "string" ? params.remember.trim() : "";
-      if (remember && labels.length > 2) {
-        return { content: [{ type: "text" as const, text: "带 remember 时最多给 2 个选项。" }], details: undefined, isError: true };
-      }
       const options: ApprovalOption[] = labels.map((option, index) => ({
         key: (["A", "B", "C"] as const)[index],
         label: String(option.label),
       }));
-      if (remember) options.push({ key: "C", label: `以后「${remember}」直接做`, always: true });
       const answer = await runtime.jobs.askQuestion(jobId, {
         title: String(params.title),
         ...(params.detail ? { detail: String(params.detail) } : {}),
         options,
-        ...(remember ? { ruleText: remember } : {}),
       });
       // 用户可能没选给出的选项，而是自己写了一段：answer 已经是回给模型的整句
       return ok(answer);
@@ -91,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/skills.ts

@@ -15,6 +15,8 @@ export interface SkillsView {
   skills: SkillView[];
   loreActive: boolean;
   loreUrl: string | null;
+  /** Lore 目录没取到的原因；其他技能照常列出。 */
+  loreError?: string;
 }
 
 export interface ImportSkill {
@@ -42,7 +44,7 @@ export interface SkillImportResult {
  */
 export interface AssistantSkill {
   name: string; // 目录名：小写字母、数字、连字符
-  title: string; // 界面上显示的名字，如「网关每日巡检」
+  title: string; // 界面上显示的名字，如「每周周报」
   description: string; // 一句话：什么时候用
   path: string; // SKILL.md 的绝对路径（预览用）
   version: number; // 每次修补 +1，旧版在 skills/<name>/.history/<版本>/

package/shared/types.ts

@@ -227,7 +227,7 @@ export interface Assistant {
   pinned: boolean; // 左栏顶部大头像
   hidden: boolean; // 收起的助手
   notify: boolean; // 需要确认时通知我
-  instructions: string; // 补充说明：用户可直接编辑的自定义指令，这个助手特有的做法写这里
+  instructions: string; // 补充说明：用户可直接编辑该助手需要知道的专属事实
   /** 这个助手用哪些模型；缺省全部跟随设置 → 模型 */
   models?: {
     conversation?: ModelPick; // 不填 = 跟随全局的对话模型
@@ -247,6 +247,7 @@ export type RouterActivity = { state: "thinking" | "tool"; label: string };
 export interface AssistantSummary extends Assistant {
   last?: { text: string; at: Iso }; // 对话最后一条（列表第二行）
   unread: number; // 未读条数（>0 时大头像右上角橙点）
+  readAt?: Iso; // 上次看这个助手的时间：之前结束的任务不再挂完成/受阻标记
   busy: boolean; // Router 正在回复（在跑的任务不算，任务状态看任务卡）
   activity?: RouterActivity | null;
 }
@@ -367,6 +368,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;
@@ -391,6 +398,8 @@ export interface Job {
   modelReason?: string; // 换了模型的原因，如「需要看图，换成了 X」
   inputs?: string[]; // 交给任务的附件（绝对路径）
   routineId?: string; // 由定时触发
+  sediment?: SedimentStatus; // 在原任务中沉淀技能，不改变任务状态
+  skills?: string[]; // 派活时交给任务的本助手技能
   skillsUsed?: string[]; // 这次读过的本助手技能（AssistantSkill.name）
   delegationId?: string; // 转交回合创建的任务
   /** 续做前每一轮结束时的样子（第 0 轮起）。对话里前面几张任务卡照它显示，最后一张跟着任务实时变 */
@@ -548,6 +557,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，这里只放不敏感的） */
@@ -564,6 +645,8 @@ export interface Settings {
   push: PushSettings;
   /** 知识库二期：向量模型（Key 在 secrets.json 的 embedding）；缺省 = 关闭，只按关键词查 */
   knowledge?: { embedding: EmbeddingSettings };
+  /** 消耗：按模型改过的单价；没改过的模型用 models.dev 的价格 */
+  usage?: UsageSettings;
 }
 
 /** 设置 → 知识库：向量模型，照图像生成的做法（兼容接口的地址 + 模型，Key 单独存）。 */
@@ -688,6 +771,7 @@ export interface Bootstrap {
 }
 
 export type HobEvent =
+  | { type: "rules" }
   | { type: "desktop-control"; screen: string; taken: boolean }
   | { type: "desktop-screens"; screens: DesktopScreen[] }
   | ({ type: "page-live" } & PageLive)
@@ -696,7 +780,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 }