@dsh-workbench/shared 0.1.0

package/src/i18n/merge.ts

@@ -0,0 +1,54 @@
+import type { Dictionaries } from './index';
+
+export interface MessagesContribution {
+  readonly unit: string;
+  readonly messages?: Dictionaries | undefined;
+}
+
+function assertSelfConsistent(unit: string, messages: Dictionaries): void {
+  const zhKeys = Object.keys(messages.zh).sort();
+  const enKeys = Object.keys(messages.en).sort();
+  if (zhKeys.length !== enKeys.length || zhKeys.some((key, index) => key !== enKeys[index])) {
+    throw new Error(
+      `套件 ${unit} 的文案两语言不同构：zh ${zhKeys.length} 键 / en ${enKeys.length} 键`,
+    );
+  }
+  for (const [language, dictionary] of [
+    ['zh', messages.zh],
+    ['en', messages.en],
+  ] as const) {
+    for (const [key, value] of Object.entries(dictionary)) {
+      if (value.trim() === '') throw new Error(`套件 ${unit} 的文案 ${language}.${key} 是空的`);
+    }
+  }
+}
+
+export function mergeMessages(
+  base: Dictionaries,
+  contributions: readonly MessagesContribution[],
+): Dictionaries {
+  const zh: Record<string, string> = { ...base.zh };
+  const en: Record<string, string> = { ...base.en };
+  const owner = new Map<string, string>(Object.keys(base.zh).map((key) => [key, '外壳']));
+
+  for (const item of contributions) {
+    const messages = item.messages;
+    if (messages === undefined) continue;
+    assertSelfConsistent(item.unit, messages);
+
+    for (const [key, value] of Object.entries(messages.zh)) {
+      if (!key.startsWith(`${item.unit}.`)) {
+        throw new Error(`套件 ${item.unit} 的文案键必须以 "${item.unit}." 开头：${key}`);
+      }
+      const previous = owner.get(key);
+      if (previous !== undefined) {
+        throw new Error(`文案键冲突：${key} 由 ${previous} 与 ${item.unit} 同时声明`);
+      }
+      owner.set(key, item.unit);
+      zh[key] = value;
+      en[key] = messages.en[key] ?? '';
+    }
+  }
+
+  return { zh, en };
+}

package/src/i18n/zh.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { en } from './en';
+import { zh } from './zh';
+
+function placeholders(text: string): string[] {
+  return [...text.matchAll(/\{(\w+)\}/g)].map((match) => match[1] ?? '').sort();
+}
+
+const zhKeys = Object.keys(zh).sort();
+const enKeys = Object.keys(en).sort();
+
+describe('dictionaries', () => {
+  it('两种语言的键集合完全一致', () => {
+    expect(enKeys).toEqual(zhKeys);
+  });
+
+  it('没有空文案（空值会静默显示成空白）', () => {
+    for (const [language, dictionary] of [['zh', zh], ['en', en]] as const) {
+      for (const [key, value] of Object.entries(dictionary)) {
+        expect(value.trim(), `${language}.${key}`).not.toBe('');
+      }
+    }
+  });
+
+  it('同一个键在两语言里的占位符一致', () => {
+    for (const key of zhKeys) {
+      const zhText = (zh as Record<string, string>)[key] ?? '';
+      const enText = (en as Record<string, string>)[key] ?? '';
+      expect(placeholders(enText), key).toEqual(placeholders(zhText));
+    }
+  });
+
+  it('复数键成对出现（`.one` 必须有 `.other`，否则英文会缺一档）', () => {
+    const oneKeys = zhKeys.filter((key) => key.endsWith('.one'));
+    expect(oneKeys.length).toBeGreaterThan(0);
+    for (const key of oneKeys) {
+      expect(zhKeys, key).toContain(`${key.slice(0, -'.one'.length)}.other`);
+    }
+  });
+});

package/src/i18n/zh.ts

@@ -0,0 +1,170 @@
+export const zh = {
+  'brand.name': '工作台',
+
+  'toggle.open': '打开侧边栏',
+  'toggle.collapse': '收起侧边栏',
+  'project.label': '切换项目',
+  'workspace.section': '工作区',
+  'project.none': '未选择项目',
+  'project.empty': '还没有项目。用下面的「添加项目」选一个目录。',
+  'project.add': '添加项目…',
+  'session.new': '新会话',
+  'session.new.label': '在当前项目新建会话',
+  'session.empty': '这个项目还没有会话。',
+  'session.noProject': '先添加一个项目。',
+  'session.pinned': '已置顶',
+  'session.actions': '{name} 的操作',
+  'status.idle': '空闲',
+  'status.running': '运行中',
+  'status.waitingApproval': '等待授权',
+  'status.planReview': '等待计划确认',
+  'status.waitingAnswer': '等待回答',
+  'status.completed': '已完成',
+  'status.subagentsRunning.one': '{n} 个子代理运行中',
+  'status.subagentsRunning.other': '{n} 个子代理运行中',
+
+  'time.now': '刚刚',
+  'time.minutes': '{n} 分钟前',
+  'time.hours': '{n} 小时前',
+  'time.days': '{n} 天前',
+
+  'panels.title': '面板模块',
+  'panels.reset': '恢复默认',
+  'panels.enabled': '这个项目已启用',
+  'panels.disabled': '这个项目未启用',
+  'panels.choose': '选择模块',
+  'panels.failed': '改配置失败了，再试一次。',
+  'panels.hintEffect': '停用 = agent 拿不到相关数据',
+  'panels.dragHint': '拖动调整顺序',
+  'panels.unknownStep': '这一层没有套件提供',
+  'panels.labelWithHint': '{label}（{hint}）',
+  'panels.dep.missingPlugin': '⚠ 还没装好',
+  'panels.dep.missingCommands': '⚠ 需要更新',
+  'panels.dep.unchecked': '⚠ 检测不了',
+  'panels.tab.modules': '面板配置',
+  'panels.tab.market': '工作台模块市场',
+  'panels.browseMarket': '浏览模块市场',
+  'panels.noneInstalled': '这些模块要的插件都还没装',
+  'panels.noneInstalledHint': '装好之后它们会回到这里，再由你决定放哪几个上板。',
+  'panels.market.installed': '已装',
+  'panels.market.outdated': '要更新',
+  'panels.market.hasNew': '有新版本',
+  'panels.market.missing': '未装',
+  'panels.market.unchecked': '状态未知',
+  'panels.market.checking': '检测中',
+  'panels.market.sectionInstalled': '已安装',
+  'panels.market.sectionPending': '未安装',
+  'panels.market.sectionShared': '共用依赖',
+  'panels.market.sharedUsedBy': '供 {modules} 使用',
+  'panels.market.listSeparator': '、',
+  'panels.market.sharedMissing': '未装',
+  'panels.market.sharedOutdated': '有新版',
+  'panels.market.sharedUnsatisfied': '版本不对',
+  'panels.market.sharedOk': '已装',
+  'panels.market.versionArrow': '{from} → {to}',
+  'panels.market.lead': '装在这台机器上，所有项目共用。',
+  'panels.market.install': '安装',
+  'panels.market.update': '更新',
+  'panels.market.uninstall': '卸载',
+  'panels.market.installing': '正在安装…',
+  'panels.market.updating': '正在更新…',
+  'panels.market.uninstalling': '正在卸载…',
+  'panels.market.confirmUninstall': '要卸载吗？',
+  'panels.market.confirmUninstallDetail':
+    '卸载后这台机器上就没有它了，所有项目的面板也会把它一起拿掉（绑定与设置不会丢）。',
+  'panels.market.confirmYes': '确定卸载',
+  'panels.market.confirmNo': '取消',
+  'panels.market.failed': '没成功：{reason}',
+  'panels.market.needEnv': '先在启动工作台的终端里设 {env}',
+  'panels.market.noSource': '这个模块没声明怎么装，只能自己动手',
+  'panels.market.badSource': '安装方式没写全，只能自己动手',
+  'panels.market.empty': '暂无可用模块',
+  'panels.market.foot': '装好后到那个项目的面板页勾选它，模块才会出现。',
+  'panels.market.recheck': '重新检查更新',
+  'panels.market.checkUpdates': '检查更新',
+  'panels.market.checkedAt': '最近检查：{time}',
+  'panels.market.justNow': '刚刚',
+  'panels.market.minutesAgo': '{n} 分钟前',
+  'panels.market.hoursAgo': '{n} 小时前',
+  'blocker.fix.install': '帮我安装',
+  'blocker.fix.update': '帮我升级',
+  'blocker.fix.running': '正在执行…',
+  'blocker.fix.failed': '执行失败：',
+  'blocker.retry': '重试',
+  'blocker.retry.running': '重试中…',
+  'blocker.copy': '复制命令',
+  'blocker.market.open': '去模块市场',
+  'blocker.login.title': '需要登录 {platform}',
+  'blocker.login.titleGeneric': '需要登录',
+  'blocker.login.hint': '工作台用你的浏览器登录态；登录一次就行，之后不用再登。',
+  'blocker.login.go': '去登录',
+  'blocker.login.manual': '在终端执行 `opencli coding team-current`，按提示完成登录后重试。',
+  'blocker.forbidden.title': '没有权限访问 {platform}',
+  'blocker.forbidden.titleGeneric': '没有权限',
+  'blocker.forbidden.hint': '账号已登录，但没有这个项目/仓库的权限；申请之后再试。',
+  'blocker.forbidden.open': '打开权限页',
+  'blocker.timeout.hint': '无头浏览器可能没起来，重试一次通常就好。',
+  'blocker.exec.hint': '确认 opencli 已安装且在 PATH 里（which opencli）。',
+  'blocker.unknown.title': '出了点问题',
+  'panels.reading': '正在读取面板配置…',
+  'panels.empty': '面板里还没有模块',
+  'panels.emptyHint': '也可以直接跟 agent 说：「把某个模块加到面板」。',
+  'env.title': '准备工作台',
+  'env.checking': '正在检测运行环境…',
+  'env.installing': '正在安装缺失的依赖…',
+  'env.failed': '还差一步就能用了',
+  'env.elapsed': '已等待 {seconds} 秒',
+  'env.stepFailed.install': '装不上',
+  'env.stepFailed.path': '装了但还找不到',
+  'env.stepFailed.shell': '执行通道不可用',
+  'env.bridge.ok': '已连接',
+  'env.bridge.short': '没连上',
+  'env.bridge.why': '面板的数据要走你浏览器里的登录态：这个通道没连上，模块就取不到数据（不拦路，但先修好它）。',
+  'env.bridge.daemon': '后台服务没起来：正常它会自己起，先在终端跑下面这条命令。',
+  'env.bridge.extension': '浏览器扩展没连上：在 Chrome 应用商店装一次就好（装完回来点「重试」）。已经装过的话，先跑下面这条命令。',
+  'env.bridge.extensionLink': '去 Chrome 应用商店装扩展',
+  'env.bridge.profile': '连上了多个浏览器 profile，但没选默认的那个：先看有哪些（下面这条命令），再选一个。',
+  'env.bridge.stale': '默认的浏览器 profile 已经失效（它记的是上一次的扩展实例）：重新选一个。',
+  'env.bridge.unknown': '没认出是哪种问题：下面原始输出里有 opencli 自己给的步骤。',
+  'env.fix.title': '怎么解决',
+  'env.fix.why': '工作台用它自己那份 opencli（与你在终端里那套分开装，互不影响），这台机器上还没装好它。',
+  'env.fix.whyPath': 'opencli 装上了，但当前环境还找不到它 —— 通常是 PATH 或终端会话的问题。',
+  'env.fix.whyShell': '工作台拿不到执行命令的通道，所以取不了数据 —— 这一步用户自己装不了。',
+  'env.fix.step': '在终端里运行下面这条命令，装好之后点「重试」：',
+  'env.fix.stepPath': '新开一个终端窗口（或确认 npm 的全局 bin 目录在 PATH 里），然后点「重试」。',
+  'env.fix.stepShell': '重启一次工作台（或 dsh）；如果反复出现，说明执行通道没配好。',
+  'env.fix.permission': '权限不够：在命令前加 sudo 重跑，或先把 npm 的全局目录配到你的用户目录。',
+  'env.fix.network': '网络不通：检查网络或代理设置后重试。',
+  'env.fix.details': '详细输出（排障用）',
+  'env.retry': '重试',
+  'env.copyCommand': '复制命令',
+  'env.copied': '已复制',
+  'env.step.opencli': '检测工作台的 opencli',
+  'env.step.codingPlugin': '检测 coding 插件',
+  'env.step.bridge': '检测浏览器通道',
+  'env.step.warm': '预热站点登录态',
+  'env.warm.done': '已预热 {n} 个站点',
+  'env.warm.short': '这次没热上 —— 不影响用，面板第一次读取会自己补',
+  'env.unit.missingPlugin': '这个模块还没装好',
+  'env.unit.missingCommandsHint': '更新之后就能用了。',
+  'env.unit.unchecked': '检测不了：拿不到执行通道',
+  'env.unit.uncheckedHint': '不是这个模块的问题，是执行通道不可用 —— 重启一次工作台再试。',
+  'env.unit.missingCommands': '这个模块的版本旧了',
+  'env.unit.hint': '装好之后点重试；不影响其它模块。',
+  'rightbar.label': '数据面板',
+  'rightbar.expand': '展开数据面板',
+  'rightbar.collapse': '收起数据面板',
+  'rightbar.refresh': '刷新',
+  'rightbar.refreshing': '刷新中…',
+  'rightbar.updatedAt': '更新于 {time}',
+  'rightbar.noProject': '当前会话没有所属项目',
+  'coding.notARepo.title': '这个项目不是 Coding 仓库',
+  'error.unknown': '出错了',
+
+  'board.title': '看板',
+
+  'panel.conversation': '对话',
+  'panels.label': '全局面板',
+} as const;
+
+export type WorkbenchMessages = typeof zh;

package/src/index.ts

@@ -0,0 +1,33 @@
+export * from './api/blocker-table';
+export * from './api/blocker';
+export * from './api/context-ref';
+export * from './api/dsh-client';
+export * from './api/dsh';
+export * from './api/facts';
+export * from './api/host-write';
+export * from './api/long-task';
+export * from './api/unit-board';
+export * from './api/unit';
+export * from './api/workbench-client';
+export * from './api/workbench-contract';
+export * from './components/ApprovalDetail';
+export * from './components/CardHead';
+export * from './components/ChoiceGroup';
+export * from './components/LongTaskRow';
+export * from './components/MockStrip';
+export * from './components/ResourceStates';
+export * from './components/SaveBar';
+export * from './components/StateDot';
+export * from './components/board-module';
+export * from './components/icons';
+export * from './config/constants';
+export * from './config/storage';
+export * from './i18n/en';
+export * from './i18n/index';
+export * from './i18n/merge';
+export * from './i18n/zh';
+export * from './lib/blocker-action';
+export * from './lib/busy';
+export * from './lib/react';
+export * from './lib/text';
+export * from './lib/ui';

package/src/lib/blocker-action.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { blockerActionLabel, blockerPending } from './blocker-action';
+
+const t = (key: string): string => `«${key}»`;
+
+const RETRY = { kind: 'retry', label: '重试' } as const;
+const LOGIN = { kind: 'open-url', label: '去登录', url: 'https://cmdb.example/login', inline: true } as const;
+const COPY = { kind: 'copy', label: '复制命令', text: 'opencli cmdb envs' } as const;
+const FIX = { kind: 'run-fix', label: '帮我安装', unit: 'cmdb', fix: 'install' } as const;
+
+const idle = { retrying: false, running: null, copied: null } as const;
+
+describe('阻断态那颗按钮说什么', () => {
+  it('★ 忙的时候「重试」自己说「重试中…」（用户点的就是它）', () => {
+    expect(blockerActionLabel(RETRY, { ...idle, retrying: true }, t)).toBe('«blocker.retry.running»');
+  });
+
+  it('不忙就是原文（不假装忙）', () => {
+    expect(blockerActionLabel(RETRY, idle, t)).toBe('重试');
+  });
+
+  it('★ 忙的不是重试本身（安装在路上）→ 「重试」不许跟着说「重试中…」', () => {
+    expect(blockerActionLabel(RETRY, { ...idle, running: '帮我安装' }, t)).toBe('重试');
+    expect(blockerActionLabel(LOGIN, { ...idle, retrying: true }, t)).toBe('去登录');
+  });
+
+  it('安装在路上 → 那颗说「正在执行…」', () => {
+    expect(blockerActionLabel(FIX, { ...idle, running: '帮我安装' }, t)).toBe('«blocker.fix.running»');
+  });
+
+  it('复制成功那一下说「已复制」', () => {
+    expect(blockerActionLabel(COPY, { ...idle, copied: 'opencli cmdb envs' }, t)).toBe('«env.copied»');
+  });
+
+  it('★ 忙 = 卡片在刷 || 本地动作在跑（少算一半，按钮就又哑了）', () => {
+    expect(blockerPending(true, null)).toBe(true);
+    expect(blockerPending(false, '帮我安装')).toBe(true);
+    expect(blockerPending(false, null)).toBe(false);
+  });
+});

package/src/lib/blocker-action.ts

@@ -0,0 +1,28 @@
+export type BlockerLabelTranslate = (key: string) => string;
+
+export interface BlockerActionShape {
+  readonly kind: string;
+  readonly label: string;
+  readonly text?: string | undefined;
+}
+
+export interface BlockerLabelState {
+  readonly retrying: boolean;
+  readonly running: string | null;
+  readonly copied: string | null;
+}
+
+export function blockerPending(busy: boolean, running: string | null): boolean {
+  return busy || running !== null;
+}
+
+export function blockerActionLabel(
+  action: BlockerActionShape,
+  state: BlockerLabelState,
+  t: BlockerLabelTranslate,
+): string {
+  if (action.kind === 'retry' && state.retrying) return t('blocker.retry.running');
+  if (state.running === action.label) return t('blocker.fix.running');
+  if (action.kind === 'copy' && state.copied === action.text) return t('env.copied');
+  return action.label;
+}

package/src/lib/busy.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { holdBusy } from './busy';
+
+describe('holdBusy', () => {
+  it('这一轮忙刚开了头：还要按住，剩下的时长报出来（计时器按它收尾）', () => {
+    expect(holdBusy(1000, 1000, 500)).toEqual({ visible: true, releaseInMs: 500 });
+    expect(holdBusy(1000, 1200, 500)).toEqual({ visible: true, releaseInMs: 300 });
+    expect(holdBusy(1000, 1499, 500)).toEqual({ visible: true, releaseInMs: 1 });
+  });
+
+  it('★ 差一毫秒还按住，正好到点就放 —— 下限是"至少看这么久"', () => {
+    expect(holdBusy(1000, 1499, 500).visible).toBe(true);
+    expect(holdBusy(1000, 1500, 500)).toEqual({ visible: false, releaseInMs: 0 });
+  });
+
+  it('慢读（本来就超过下限）一下都不多按：真实时长说了算', () => {
+    expect(holdBusy(1000, 7000, 500)).toEqual({ visible: false, releaseInMs: 0 });
+  });
+
+  it('没开过这一轮忙 → 什么都不按（挂载第一帧、enabled=false 的那些读者）', () => {
+    expect(holdBusy(null, 1000, 500)).toEqual({ visible: false, releaseInMs: 0 });
+  });
+
+  it('时钟倒退（now 比开头还早）按"刚开头"算，不出现负的剩余时长', () => {
+    expect(holdBusy(1000, 900, 500)).toEqual({ visible: true, releaseInMs: 500 });
+  });
+});

package/src/lib/busy.ts

@@ -0,0 +1,11 @@
+export interface BusyHold {
+  readonly visible: boolean;
+  readonly releaseInMs: number;
+}
+
+export function holdBusy(since: number | null, now: number, floorMs: number): BusyHold {
+  if (since === null) return { visible: false, releaseInMs: 0 };
+  const elapsed = Math.max(0, now - since);
+  const left = floorMs - elapsed;
+  return left <= 0 ? { visible: false, releaseInMs: 0 } : { visible: true, releaseInMs: left };
+}

package/src/lib/react.test.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { describe, expect, it } from 'vitest';
+import { Fragment, h, useCallback, useEffect, useMemo, useRef, useState } from './react';
+
+describe('react 入口', () => {
+  it('h 就是 React.createElement（同一个引用，不是包装）', () => {
+    expect(h).toBe(React.createElement);
+  });
+
+  it('h 造出真正的 React 元素', () => {
+    const element = h('div', { className: 'x' }, 'hi') as { type: string; props: Record<string, unknown> };
+    expect(element.type).toBe('div');
+    expect(element.props.className).toBe('x');
+    expect(element.props.children).toBe('hi');
+    expect(React.isValidElement(element)).toBe(true);
+  });
+
+  it('Fragment 与 hooks 都是 React 自己的', () => {
+    expect(Fragment).toBe(React.Fragment);
+    expect(useState).toBe(React.useState);
+    expect(useEffect).toBe(React.useEffect);
+    expect(useMemo).toBe(React.useMemo);
+    expect(useCallback).toBe(React.useCallback);
+    expect(useRef).toBe(React.useRef);
+  });
+});

package/src/lib/react.ts

@@ -0,0 +1,16 @@
+import type * as ReactTypes from 'react';
+
+const react = require('react') as typeof ReactTypes;
+
+export const h = react.createElement;
+
+export const Fragment = react.Fragment;
+
+export const useState = react.useState;
+export const useEffect = react.useEffect;
+export const useMemo = react.useMemo;
+export const useCallback = react.useCallback;
+export const useRef = react.useRef;
+export const useSyncExternalStore = react.useSyncExternalStore;
+
+export type { ReactNode, CSSProperties, ChangeEvent } from 'react';

package/src/lib/text.test.ts

@@ -0,0 +1,92 @@
+import { execFileSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+import { excerpt, parseJsonLoose, quoteShellArg, tailLines } from './text';
+
+function shellSees(value: string): string {
+  return execFileSync('/bin/sh', ['-c', `printf '%s' ${quoteShellArg(value)}`], {
+    encoding: 'utf8',
+  });
+}
+
+describe('quoteShellArg', () => {
+  it('普通值原样往返', () => {
+    expect(shellSees('example-monorepo')).toBe('example-monorepo');
+  });
+
+  it('含空格的路径不被拆成两个参数', () => {
+    expect(shellSees('/Volumes/My Projects/app')).toBe('/Volumes/My Projects/app');
+  });
+
+  it('单引号被正确转义（否则就是注入面）', () => {
+    expect(shellSees("it's")).toBe("it's");
+  });
+
+  it('shell 元字符按字面量传递', () => {
+    for (const raw of ['$(whoami)', '`id`', 'a; rm -rf /', 'a && b', '*', '"double"', '\\n']) {
+      expect(shellSees(raw), raw).toBe(raw);
+    }
+  });
+});
+
+describe('tailLines', () => {
+  it('取末尾若干行并去掉首尾空行', () => {
+    expect(tailLines('\n a \n b \n', 2)).toBe('a \n b');
+  });
+
+  it('行数不够时全给', () => {
+    expect(tailLines('only', 6)).toBe('only');
+  });
+
+  it('空输入给空串', () => {
+    expect(tailLines(undefined, 3)).toBe('');
+    expect(tailLines('   ', 3)).toBe('');
+  });
+});
+
+describe('parseJsonLoose', () => {
+  it('干净 JSON 直接解析', () => {
+    expect(parseJsonLoose('{"a":1}')).toEqual({ a: 1 });
+    expect(parseJsonLoose('[1,2]')).toEqual([1, 2]);
+  });
+
+  it('前面有噪音时从第一个结构符开始解析', () => {
+    expect(parseJsonLoose('正在检查更新…\n[{"code":2133}]')).toEqual([{ code: 2133 }]);
+    expect(parseJsonLoose('warn: x\n{"ok":true}')).toEqual({ ok: true });
+  });
+
+  it('尾部有噪音时截到最后闭合符', () => {
+    expect(parseJsonLoose('[1,2]\n完成')).toEqual([1, 2]);
+  });
+
+  it('解析不出来给 undefined，让调用方报 coding-bad-output', () => {
+    expect(parseJsonLoose('')).toBeUndefined();
+    expect(parseJsonLoose('not json at all')).toBeUndefined();
+    expect(parseJsonLoose('[1,2')).toBeUndefined();
+  });
+});
+
+describe('excerpt', () => {
+  it('剥掉图片语法（它没有文字信息）', () => {
+    expect(excerpt('![picture](/api/project/1/files/2/imagePreview)', 80)).toBe('');
+  });
+
+  it('链接只留可见文字，标记符号压平', () => {
+    expect(excerpt('见 [设计稿](https://x/y) 与 **重点**', 80)).toBe('见 设计稿 与 重点');
+  });
+
+  it('压平换行与多余空白，模板正文变成一行', () => {
+    expect(excerpt('\n【复现步骤】\n\n\n【预期结果】\n', 80)).toBe('【复现步骤】 【预期结果】');
+  });
+
+  it('超长时按字符截断并加省略号', () => {
+    const long = '一二三四五六七八九十'.repeat(10);
+    const out = excerpt(long, 12);
+    expect(out.endsWith('…')).toBe(true);
+    expect(out.length).toBe(13);
+  });
+
+  it('空输入给空串', () => {
+    expect(excerpt(undefined, 20)).toBe('');
+    expect(excerpt('   ', 20)).toBe('');
+  });
+});

package/src/lib/text.ts

@@ -0,0 +1,46 @@
+export function quoteShellArg(value: unknown): string {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+export function tailLines(text: string | null | undefined, lines = 6): string {
+  const all = String(text ?? '')
+    .trim()
+    .split('\n');
+  return all.slice(-lines).join('\n');
+}
+
+export function parseJsonLoose(text: string | null | undefined): unknown {
+  const raw = String(text ?? '').trim();
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    const starts = [raw.indexOf('['), raw.indexOf('{')].filter((index) => index >= 0);
+    if (starts.length === 0) return undefined;
+    const from = Math.min(...starts);
+    const open = raw[from];
+    const close = open === '[' ? ']' : '}';
+    const to = raw.lastIndexOf(close);
+    if (to <= from) return undefined;
+    try {
+      return JSON.parse(raw.slice(from, to + 1)) as unknown;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/g;
+const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
+const MARKDOWN_MARKS = /[*`_>#]/g;
+
+export function excerpt(text: string | null | undefined, limit = 80): string {
+  const flat = String(text ?? '')
+    .replace(MARKDOWN_IMAGE, ' ')
+    .replace(MARKDOWN_LINK, '$1')
+    .replace(MARKDOWN_MARKS, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (flat.length <= limit) return flat;
+  return `${flat.slice(0, limit).trimEnd()}…`;
+}