@dsh-workbench/module-tools 1.1.13 → 1.1.14-beta.0

package/template-diy/src/host/sample.ts.tpl

@@ -0,0 +1,151 @@
+import type { DshToolDefinition, UnitMountDeps } from '@dsh-workbench/core/contract';
+import {
+  TEXT_OUTPUT,
+  longTaskStepOf,
+  recordOf,
+  sessionIdOf,
+  sessionWorkspace,
+  textOf,
+  type LongTaskBase,
+  type LongTaskRegistry,
+} from '@dsh-workbench/shared/host';
+import { LIST_LIMIT } from '../model/overview';
+import { DECLARED_TOOLS } from '../declared-tools';
+import { FLOW_TARGET, RUN_TASK, headlineOf, sampleFlow } from '../model/flow';
+import { readOverview } from './overview';
+
+export interface StartResult {
+  readonly ok: boolean;
+  readonly runId?: string;
+  readonly status?: string;
+  readonly text?: string;
+  readonly code?: string;
+  readonly message?: string;
+}
+
+
+
+export interface Sample {
+  readonly runs: LongTaskRegistry<LongTaskBase> | undefined;
+  readonly runTool: DshToolDefinition;
+  startFromPayload(payload: unknown): StartResult;
+}
+
+export function createSample(deps: UnitMountDeps): Sample {
+  const flowDefinition = sampleFlow();
+  const actions = deps.flow.createActions();
+
+  actions.register(
+    'read',
+    async (_input, context) => {
+      context.log('读目录');
+      const payload = readOverview(context.workspace, LIST_LIMIT);
+      return { files: payload.files, dirs: payload.dirs, bytes: payload.bytes };
+    },
+    { title: '读目录' },
+  );
+  actions.register(
+    'summarize',
+    async (input) => {
+      const one = recordOf(input);
+      return {
+        text: `${String(one['files'])} 个文件 · ${String(one['dirs'])} 个目录 · ${String(one['bytes'])} 字节`,
+      };
+    },
+    { title: '汇总' },
+  );
+
+  const checked = deps.flow.check(flowDefinition, actions);
+  if (!checked.ok) {
+    throw new Error(
+      `流程定义有问题：${checked.problems.map((one) => `${one.path}: ${one.problem}`).join('；')}`,
+    );
+  }
+
+  const runs = deps.longTasks?.create<LongTaskBase>({
+    key: RUN_TASK,
+    run: async ({ payload, onStep, signal }) => {
+      const path = textOf(recordOf(payload)['path']);
+      const result = await deps.flow.run({
+        flow: flowDefinition,
+        input: { path },
+        actions,
+        signal,
+        runId: `${DECLARED_TOOLS.run.name}-${String(Date.now())}`,
+        workspace: path,
+        onStep: (event) => {
+          onStep(longTaskStepOf(event));
+        },
+      });
+      if (result.status === 'failed') {
+        throw result.error instanceof Error
+          ? result.error
+          : new Error(`流程失败在 ${result.failedStep ?? '未知步骤'}`);
+      }
+      return result;
+    },
+    step: (step) => ({ step: step.text }),
+    outcome: () => ({ step: '完成：读目录 → 汇总' }),
+    stopped: (current) => ({ step: current.step === '' ? '已停止' : `停在「${current.step}」` }),
+    view: (snapshot) => ({
+      status: snapshot.status,
+      step: snapshot.step,
+      steps: snapshot.steps,
+      ...(snapshot.why === undefined ? {} : { why: snapshot.why }),
+    }),
+  });
+
+  const start = (workspace: string, session: string | null): StartResult => {
+    if (runs === undefined) return { ok: false, text: '外壳没有给长任务服务：这一版起不了流程' };
+    const run = runs.start({
+      workspace,
+      target: FLOW_TARGET,
+      payload: { path: workspace },
+      ...(session === null ? {} : { session }),
+    });
+    return { ok: true, runId: run.id, status: run.status, text: headlineOf(run) };
+  };
+
+  const runTool: DshToolDefinition = {
+    name: DECLARED_TOOLS.run.name,
+    description:
+      '跑一遍样板流程（读目录 → 汇总）；只读本机目录，不写平台，不用点头；再传 runId 可只看同一趟。',
+    parameters: {
+      type: 'object',
+      properties: {
+        runId: {
+          type: 'string',
+          description: '填上一次的 runId = 只看那条；不填 = 起一条新的。',
+        },
+      },
+      additionalProperties: false,
+    },
+    output: TEXT_OUTPUT,
+    async execute(raw, exec) {
+      const args = recordOf(raw);
+      const runId = textOf(args['runId']);
+      if (runId !== '') {
+        const snapshot = runs?.snapshot(runId) ?? null;
+        if (snapshot === null) return { ok: false, text: `没有这条 run：${runId}` };
+        return { ok: true, runId, status: snapshot.status, text: headlineOf(snapshot) };
+      }
+      const workspace = sessionWorkspace(exec);
+      if (workspace === null || workspace === '') {
+        return { ok: false, text: '这个会话没有工作区：先打开一个项目再跑。' };
+      }
+      return start(workspace, sessionIdOf(exec));
+    },
+  };
+
+  return {
+    runs,
+    runTool,
+    startFromPayload(payload: unknown): StartResult {
+      const path = textOf(recordOf(payload)['path']);
+      if (path === '') {
+        return { ok: false, code: 'no-path', message: '没告诉我要跑哪个目录', text: '先打开一个项目再跑。' };
+      }
+      return start(path, null);
+    },
+  };
+}

package/template-diy/src/host.ts.tpl

@@ -1,84 +1,106 @@
-import { readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import type { HostContext, UnitModuleFace, UnitRegistry } from '@dsh-workbench/core/contract';
-import type { OverviewFile, OverviewPayload } from './model/overview';
+import type { DshToolRegistry, UnitModuleFace } from '@dsh-workbench/core/contract';
+import {
+  defineUnitHostPlugin,
+  factOfRoute,
+  recordOf,
+  textOf,
+  writeApprovalOf,
+} from '@dsh-workbench/shared/host';
+import { DECLARED_TOOLS } from './declared-tools';
+import { RUN_RESOURCE } from './model/flow';
+import { NOTE_RESOURCE, NOTES_ROUTE, UNIT_ID } from './model/notes';
+import { PREFS_RESOURCE, PREFS_ROUTE, applyPrefs, prefsOf } from './model/prefs';
+import { createNotes } from './host/notes';
+import { createSample } from './host/sample';
+import { overviewAnswer } from './host/overview';
+
+export { readOverview } from './host/overview';
 
-const UNIT_ID = '__UNIT__';
 const PLUGIN_ID = '__NAME__';
-const DEFAULT_LIMIT = 5;
-const MAX_LIMIT = 50;
 
 export const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
 
 export type RouteHandler = (search: URLSearchParams) => Promise<unknown> | unknown;
 
-export function readOverview(path: string, limit: number): OverviewPayload {
-  const entries = readdirSync(path, { withFileTypes: true });
-  const files: OverviewFile[] = [];
-  let dirs = 0;
-  let bytes = 0;
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      dirs += 1;
-      continue;
-    }
-    if (!entry.isFile()) continue;
-    const info = statSync(join(path, entry.name));
-    bytes += info.size;
-    files.push({ name: entry.name, bytes: info.size, mtime: new Date(info.mtimeMs).toISOString() });
-  }
-  files.sort((a, b) => b.bytes - a.bytes || a.name.localeCompare(b.name));
-  return { path, files: files.length, dirs, bytes, largest: files.slice(0, limit) };
-}
-
-function searchParam(search: URLSearchParams, name: string): string | undefined {
-  const raw = search.get(name);
-  return raw === null || raw === '' ? undefined : raw;
-}
-
-function limitOf(search: URLSearchParams): number {
-  const raw = searchParam(search, 'limit');
-  if (raw === undefined) return DEFAULT_LIMIT;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return DEFAULT_LIMIT;
-  return Math.min(MAX_LIMIT, Math.max(1, Math.trunc(parsed)));
+function pathOf(search: URLSearchParams): string {
+  return search.get('path') ?? '';
 }
 
 const face: UnitModuleFace = {
   unit: UNIT_ID,
-  mount: () => ({
-    routes: {
-      [OVERVIEW_ROUTE]: async (search: URLSearchParams) => {
-        const target = searchParam(search, 'path');
-        if (target === undefined) {
-          return { ok: false, error: { code: 'no-path', message: '没告诉我要看哪个目录' } };
+  mount: (deps) => {
+    const sample = createSample(deps);
+    const notes = createNotes(deps);
+    const storeAt = (workspace: string) => deps.store.for(UNIT_ID, workspace === '' ? null : workspace);
+
+    return {
+      routes: {
+        [OVERVIEW_ROUTE]: (search: URLSearchParams) => overviewAnswer(search),
+        [NOTES_ROUTE]: (search: URLSearchParams) => {
+          const path = pathOf(search);
+          if (path === '') {
+            return { ok: false, error: { code: 'no-path', message: '没告诉我要看哪个目录' } };
+          }
+          return { ok: true, notes: notes.list(path) };
+        },
+        [PREFS_ROUTE]: (search: URLSearchParams) => ({
+          ok: true,
+          prefs: prefsOf(storeAt(search.get('workspace') ?? pathOf(search))),
+        }),
+      },
+      prefs: {
+        resource: PREFS_RESOURCE,
+        handle: (payload: unknown) => {
+          const body = recordOf(payload);
+          const workspace = textOf(body['workspace']) || textOf(body['path']);
+          if (workspace === '') {
+            return { ok: false, error: { code: 'no-workspace', message: '没告诉我要存到哪个工作区' } };
+          }
+          return { ok: true, ...applyPrefs(storeAt(workspace), payload) };
+        },
+      },
+      registerTools: () => {
+        const tools = deps.ctx.get<DshToolRegistry>('tools');
+        if (tools === undefined) {
+          deps.logger?.warn?.(`[${UNIT_ID}] 外壳没有提供 tools 服务：这两把工具注册不进去`);
+          return [];
         }
-        try {
-          return { ok: true, ...readOverview(target, limitOf(search)) };
-        } catch (error) {
-          return {
-            ok: false,
-            error: {
-              code: 'overview-unreadable',
-              message: error instanceof Error ? error.message : String(error),
-            },
-          };
+        return [tools.register(sample.runTool), tools.register(notes.tool)];
+      },
+      actions: [
+        {
+          resource: RUN_RESOURCE,
+          handle: (payload: unknown) => sample.startFromPayload(payload),
+        },
+        {
+          resource: NOTE_RESOURCE,
+          handle: (payload: unknown) => notes.handle(payload),
+        },
+      ],
+      factsOf: (call: { readonly source: string }) => {
+        if (call.source === DECLARED_TOOLS.addNote.name || call.source === NOTE_RESOURCE) {
+          return [factOfRoute(NOTES_ROUTE)];
         }
+        if (call.source === PREFS_RESOURCE) return [factOfRoute(PREFS_ROUTE)];
+        if (call.source === DECLARED_TOOLS.run.name) return [];
+        return undefined;
       },
-    },
-    registerTools: () => [],
-  }),
+      ...writeApprovalOf({
+        tools: [DECLARED_TOOLS.addNote.name],
+        reason: '会往这个模块的笔记里加一条',
+        question: { zh: '把这条笔记写进去吗？', en: 'Write this note?' },
+        fallback: { zh: '只写本模块的笔记文件，不动平台', en: 'Writes only this module’s notes file' },
+        detail: { zh: '新增 1 条笔记', en: 'Add 1 note' },
+      }),
+      ...(sample.runs === undefined ? {} : { longTasks: sample.runs }),
+    };
+  },
 };
 
-export const name = PLUGIN_ID;
+const plugin = defineUnitHostPlugin({ name: PLUGIN_ID, unit: UNIT_ID, face });
 
-export const inject = ['workbenchUnits'];
+export const name = plugin.name;
 
-export function apply(ctx: HostContext): void {
-  const units = ctx.get<UnitRegistry>('workbenchUnits');
-  if (units === undefined) {
-    ctx.logger?.warn?.(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这个模块装不进来`);
-    return;
-  }
-  ctx.effect(() => units.register(face), `${PLUGIN_ID}: 注册 ${UNIT_ID}`);
-}
+export const inject = plugin.inject;
+
+export const apply = plugin.apply;

package/template-diy/src/messages.ts.tpl

@@ -10,6 +10,20 @@ export const messages = {
     '__UNIT__.largest': '最大的几个文件',
     '__UNIT__.fileUnit': ' 个文件',
     '__UNIT__.dirUnit': ' 个目录',
+    '__UNIT__.network': '网络不通，没发出去',
+    '__UNIT__.runSample': '跑一遍样板流程',
+    '__UNIT__.runHint': '点一下上面那颗钮：读目录 → 汇总，会在这张卡里出现一条长任务行',
+    '__UNIT__.stopLabel': '停止任务',
+    '__UNIT__.stopAsk': '确认停止',
+    '__UNIT__.stepsTitle': '步骤',
+    '__UNIT__.notesLabel': '模块笔记',
+    '__UNIT__.notesHint': '写一句就存进这个项目自己的模块文件夹；agent 的写工具走同一份数据，要你点头',
+    '__UNIT__.notePlaceholder': '记一句（200 字以内）',
+    '__UNIT__.noteSave': '存一条',
+    '__UNIT__.notesEmpty': '还没有笔记：写一句存进去，刷新后它还在',
+    '__UNIT__.prefsLabel': '最大的几个文件',
+    '__UNIT__.prefsHint': '这个选择按项目存（刷新还在）；只影响卡片显示，不改读到的数据',
+    '__UNIT__.prefsUnit': ' 个',
   },
   en: {
     '__UNIT__.cardTitle': 'Directory overview',
@@ -22,5 +36,19 @@ export const messages = {
     '__UNIT__.largest': 'Largest files',
     '__UNIT__.fileUnit': ' files',
     '__UNIT__.dirUnit': ' dirs',
+    '__UNIT__.network': 'Network is down: nothing was sent',
+    '__UNIT__.runSample': 'Run the sample flow',
+    '__UNIT__.runHint': 'Hit the button above: read directory → summarize; a long-task row appears in this card',
+    '__UNIT__.stopLabel': 'Stop task',
+    '__UNIT__.stopAsk': 'Confirm stop',
+    '__UNIT__.stepsTitle': 'Steps',
+    '__UNIT__.notesLabel': 'Module notes',
+    '__UNIT__.notesHint': 'Saved to this project’s own module folder; the agent’s write tool uses the same data and needs your nod',
+    '__UNIT__.notePlaceholder': 'One line (up to 200 chars)',
+    '__UNIT__.noteSave': 'Save note',
+    '__UNIT__.notesEmpty': 'No notes yet: write one and it survives a refresh',
+    '__UNIT__.prefsLabel': 'Largest files shown',
+    '__UNIT__.prefsHint': 'Stored per project (survives refresh); affects display only, not the data',
+    '__UNIT__.prefsUnit': '',
   },
 };

package/template-diy/src/model/__tests__/flow.test.ts.tpl

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { headlineOf, runIsLive, sampleFlow, type SampleRun } from '../flow';
+
+const run = (over: Partial<SampleRun> = {}): SampleRun => ({
+  id: 'run-1',
+  status: 'running',
+  step: '',
+  steps: [],
+  ...over,
+});
+
+describe('样板流程的模型', () => {
+  it('两步：先读目录、再汇总，步骤 id 就是动作名', () => {
+    const flow = sampleFlow();
+    expect(flow.steps.map((step) => ('action' in step ? step.action : 'sub'))).toEqual(['read', 'summarize']);
+    expect(flow.target).toEqual({ $ref: 'in.path' });
+  });
+
+  it('只有 running / needs-login 算还在跑', () => {
+    expect(runIsLive(run())).toBe(true);
+    expect(runIsLive(run({ status: 'needs-login' }))).toBe(true);
+    expect(runIsLive(run({ status: 'ok' }))).toBe(false);
+    expect(runIsLive(run({ status: 'failed' }))).toBe(false);
+    expect(runIsLive(run({ status: 'stopped' }))).toBe(false);
+  });
+
+  it('标题按五态与当前步骤说人话', () => {
+    expect(headlineOf(run())).toBe('样板流程正在跑');
+    expect(headlineOf(run({ step: '读目录' }))).toBe('样板流程：读目录');
+    expect(headlineOf(run({ status: 'ok' }))).toBe('样板流程跑完了');
+    expect(headlineOf(run({ status: 'failed' }))).toBe('样板流程失败');
+    expect(headlineOf(run({ status: 'stopped' }))).toBe('样板流程已停止');
+    expect(headlineOf(run({ status: 'needs-login' }))).toBe('样板流程要登录');
+  });
+});

package/template-diy/src/model/__tests__/notes.test.ts.tpl

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { addNoteOf, noteProblemOf, notesOf } from '../notes';
+
+describe('notesOf', () => {
+  it('没存过就是空数组', () => {
+    expect(notesOf(null)).toEqual([]);
+    expect(notesOf({ nope: true })).toEqual([]);
+  });
+
+  it('只认完整的条目，坏的丢掉；最多留 20 条', () => {
+    const raw = [
+      { id: 'a', text: '一', at: '2026-01-01T00:00:00.000Z' },
+      { id: 'b', text: '缺 at' },
+      ...Array.from({ length: 30 }, (_unused, index) => ({
+        id: `n${String(index)}`,
+        text: `第 ${String(index)} 条`,
+        at: '2026-01-01T00:00:00.000Z',
+      })),
+    ];
+    const notes = notesOf(raw);
+    expect(notes).toHaveLength(20);
+    expect(notes[0]?.id).toBe('a');
+    expect(notes[19]?.id).toBe('n18');
+  });
+});
+
+describe('noteProblemOf', () => {
+  it('空 / 只有空白 / 超长都点名叫原因', () => {
+    expect(noteProblemOf('   ')).toContain('写点什么');
+    expect(noteProblemOf(undefined)).toContain('一句话');
+    expect(noteProblemOf('x'.repeat(201))).toContain('200');
+    expect(noteProblemOf('x'.repeat(200))).toBeUndefined();
+  });
+});
+
+describe('addNoteOf', () => {
+  it('新条目排最前，超过 20 条丢最旧', () => {
+    const old = Array.from({ length: 20 }, (_unused, index) => ({
+      id: `old-${String(index)}`,
+      text: '旧',
+      at: '2026-01-01T00:00:00.000Z',
+    }));
+    const { note, notes } = addNoteOf(old, '  新的一条  ', '2026-02-02T00:00:00.000Z', 'new');
+    expect(note.text).toBe('新的一条');
+    expect(notes[0]).toEqual(note);
+    expect(notes).toHaveLength(20);
+    expect(notes.some((one) => one.id === 'old-19')).toBe(false);
+  });
+});

package/template-diy/src/model/{overview.test.ts.tpl → __tests__/overview.test.ts.tpl}

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { formatBytes, overviewStateOf } from './overview';
+import { formatBytes, overviewStateOf } from '../overview';
 
 describe('overviewStateOf', () => {
   it('待机就是待机', () => {

package/template-diy/src/model/__tests__/prefs.test.ts.tpl

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_PREFS,
+  LIMIT_MAX,
+  LIMIT_MIN,
+  PREF_FILE,
+  applyPrefs,
+  prefsOf,
+  type PrefStore,
+} from '../prefs';
+
+function memoryStore(initial: Record<string, unknown> = {}): PrefStore & { readonly files: Map<string, unknown> } {
+  const files = new Map<string, unknown>(Object.entries(initial));
+  return {
+    files,
+    read: (name) => files.get(name) ?? null,
+    write: (name, value) => {
+      files.set(name, value);
+    },
+    remove: (name) => {
+      files.delete(name);
+    },
+  };
+}
+
+describe('prefsOf', () => {
+  it('没存过 / 存坏了都回默认', () => {
+    expect(prefsOf(memoryStore())).toEqual(DEFAULT_PREFS);
+    expect(prefsOf(memoryStore({ [PREF_FILE]: { limit: 999 } }))).toEqual(DEFAULT_PREFS);
+    expect(prefsOf(memoryStore({ [PREF_FILE]: { limit: 'abc' } }))).toEqual(DEFAULT_PREFS);
+  });
+
+  it('存过的合法值读得回来', () => {
+    expect(prefsOf(memoryStore({ [PREF_FILE]: { limit: 10 } })).limit).toBe(10);
+  });
+});
+
+describe('applyPrefs', () => {
+  it('写进去并回整份新偏好', () => {
+    const store = memoryStore();
+    expect(applyPrefs(store, { limit: 20 })).toEqual({ prefs: { limit: 20 } });
+    expect(store.files.get(PREF_FILE)).toEqual({ limit: 20 });
+  });
+
+  it('越界 / 不是整数 / 没有 limit 都会抛，且不写', () => {
+    const store = memoryStore();
+    expect(() => applyPrefs(store, { limit: LIMIT_MAX + 1 })).toThrow('只认');
+    expect(() => applyPrefs(store, { limit: LIMIT_MIN - 1 })).toThrow('只认');
+    expect(() => applyPrefs(store, { limit: 1.5 })).toThrow('只认');
+    expect(() => applyPrefs(store, {})).toThrow('没有 limit');
+    expect(store.files.has(PREF_FILE)).toBe(false);
+  });
+
+  it('reset 删文件回默认', () => {
+    const store = memoryStore({ [PREF_FILE]: { limit: 10 } });
+    expect(applyPrefs(store, { reset: true })).toEqual({ prefs: DEFAULT_PREFS });
+    expect(store.files.has(PREF_FILE)).toBe(false);
+  });
+});

package/template-diy/src/model/flow.ts.tpl

@@ -0,0 +1,47 @@
+import type { FlowDefinition } from '@dsh-workbench/core/contract';
+import type { LongTaskStatus } from '@dsh-workbench/shared';
+
+export const FLOW_TARGET = 'sample';
+export const RUN_TASK = '__UNIT__-sample';
+export const RUN_RESOURCE = '__UNIT__-run';
+
+export interface SampleRun {
+  readonly id: string;
+  readonly status: LongTaskStatus;
+  readonly step: string;
+  readonly steps: readonly string[];
+  readonly why?: string | undefined;
+}
+
+export function sampleFlow(): FlowDefinition {
+  return {
+    id: 'sample',
+    title: '读目录 → 汇总',
+    target: { $ref: 'in.path' },
+    steps: [
+      { id: 'read', title: '读目录', action: 'read' },
+      {
+        id: 'summarize',
+        title: '汇总',
+        action: 'summarize',
+        with: {
+          files: { $ref: 'steps.read.files' },
+          dirs: { $ref: 'steps.read.dirs' },
+          bytes: { $ref: 'steps.read.bytes' },
+        },
+      },
+    ],
+  };
+}
+
+export function headlineOf(run: SampleRun): string {
+  if (run.status === 'ok') return '样板流程跑完了';
+  if (run.status === 'failed') return '样板流程失败';
+  if (run.status === 'stopped') return '样板流程已停止';
+  if (run.status === 'needs-login') return '样板流程要登录';
+  return run.step === '' ? '样板流程正在跑' : `样板流程：${run.step}`;
+}
+
+export function runIsLive(run: SampleRun): boolean {
+  return run.status === 'running' || run.status === 'needs-login';
+}

package/template-diy/src/model/notes.ts.tpl

@@ -0,0 +1,52 @@
+export const UNIT_ID = '__UNIT__';
+export const NOTE_FILE = 'notes.json';
+export const NOTES_ROUTE = `${UNIT_ID}/notes`;
+export const NOTE_RESOURCE = `${UNIT_ID}-add-note`;
+export const NOTE_TEXT_MAX = 200;
+export const NOTE_LIMIT = 20;
+
+export interface Note {
+  readonly id: string;
+  readonly text: string;
+  readonly at: string;
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+export function notesOf(raw: unknown): Note[] {
+  if (!Array.isArray(raw)) return [];
+  const notes: Note[] = [];
+  for (const one of raw) {
+    const value = recordOf(one);
+    if (typeof value['id'] !== 'string' || typeof value['text'] !== 'string') continue;
+    if (typeof value['at'] !== 'string') continue;
+    notes.push({ id: value['id'], text: value['text'], at: value['at'] });
+    if (notes.length >= NOTE_LIMIT) break;
+  }
+  return notes;
+}
+
+export function noteProblemOf(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return '笔记要是一句话';
+  const text = raw.trim();
+  if (text === '') return '写点什么再存';
+  const length = [...text].length;
+  if (length > NOTE_TEXT_MAX) return `最多 ${String(NOTE_TEXT_MAX)} 字，这条有 ${String(length)} 字`;
+  return undefined;
+}
+
+export function addNoteOf(
+  notes: readonly Note[],
+  text: string,
+  at: string,
+  id: string,
+): { readonly note: Note; readonly notes: Note[] } {
+  const note: Note = { id, text: text.trim(), at };
+  return { note, notes: [note, ...notes].slice(0, NOTE_LIMIT) };
+}
+
+export function noteIdOf(at: string, seed: string | number): string {
+  return `${at}-${String(seed)}`;
+}

package/template-diy/src/model/overview.ts.tpl

@@ -32,7 +32,9 @@ export interface OverviewInput {
   readonly error: Failure | undefined;
 }
 
-export const LIST_LIMIT = 5;
+import { LIMIT_DEFAULT } from './prefs';
+
+export const LIST_LIMIT = LIMIT_DEFAULT;
 
 const KB = 1024;