@chengzhao-dev/dsh-cpp-workflow 0.6.0 → 0.6.1

package/README.en.md

@@ -19,13 +19,13 @@ The exception material follows the C++ Core Guidelines' Error handling section a
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.1
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.1
 ```
 
 The desktop app owns the `desktop` profile. If the command-line `add` is rejected, add the plugin in the app settings and use the same pinned npm version. A Git tag install uses the prebuilt `lib/` committed in the repository and runs no build on the target machine; the package has no install script that needs approval.

package/README.md

@@ -19,13 +19,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.1
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.1
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。

package/lib/client.js

@@ -57,6 +57,8 @@ const TAG_LABEL = {
     tparam: '@tparam',
     retval: '@retval',
 };
+/** 预览里的示例摘要：用户没填 @brief 时用它，避免预览出现空标签。 */
+const SAMPLE_BRIEF = '定义井字棋棋盘、格子坐标与格子类型。';
 /** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
 const DEFAULT_CONFIG = {
     brief: { enabled: true, value: '' },
@@ -120,6 +122,10 @@ function renderFileHeader(raw, fileName) {
 function previewParts(raw, sampleName) {
     const config = normalizeConfig(raw);
     const header = renderFileHeader(config, sampleName || 'board.h');
+    // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
+    const briefIndex = header.indexOf('/// @brief');
+    if (briefIndex !== -1)
+        header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
     const contract = [];
     if (config.param)
         contract.push('/// @param position 目标行列坐标。');
@@ -199,14 +205,21 @@ const STRINGS = {
     title: '文档注释',
     intro: '文件头与函数契约默认写出哪些 Doxygen 标签。配置只影响代理写注释的默认值，不改已有源码。',
     header: '文件头',
+    headerHint: '每个手写源文件开头的一段 ///；带值的标签填写后写出，@brief 留空由文件自述。',
     contract: '函数契约',
+    contractHint: '声明注释里的参数与失败方式；关闭后不再要求写出这些标签。',
     extra: '更多标签',
     extraHint: '默认关闭；需要时在单个函数上补写。',
     file: '@file',
+    fixed: '自动',
     fileHint: '固定为当前文件名，不参与配置。',
-    emptyValue: '留空则由每个文件自己写',
-    on: '写出',
-    off: '不写',
+    briefHint: '一句话说明本文件定义或实现什么；留空则由每个文件自己写。',
+    authorHint: '作者署名；留空不写。',
+    dateHint: '创建或修改日期；留空不写。',
+    copyrightHint: '版权声明；留空不写。',
+    versionHint: '文件版本号；留空不写。',
+    emptyValue: '留空不写',
+    briefEmpty: '留空则由文件自述',
     preview: '预览',
     previewHint: '示例文件名 board.h；预览随开关即时更新。',
     save: '保存',
@@ -217,6 +230,7 @@ const STRINGS = {
     loading: '正在读取配置…',
     unreadable: '当前账户不能修改这份配置。',
     readOnly: '此处只显示出厂值。要修改配置，请到「插件」页打开 dsh-cpp-workflow 的配置卡片。',
+    openSettings: '打开插件配置',
     noForm: '这个入口没有可写表单，配置在插件页修改。',
   },
   en: {
@@ -224,14 +238,21 @@ const STRINGS = {
     title: 'Documentation comments',
     intro: 'Which Doxygen tags the agent writes by default. This changes defaults only; existing sources are untouched.',
     header: 'File header',
+    headerHint: 'The /// block at the top of every hand-written source; value tags are written only when filled.',
     contract: 'Function contract',
+    contractHint: 'Parameter and failure tags in declaration comments; turning one off stops requiring it.',
     extra: 'More tags',
     extraHint: 'Off by default; add them per function when needed.',
     file: '@file',
+    fixed: 'Auto',
     fileHint: 'Always the current file name; not configurable.',
-    emptyValue: 'Leave empty and each file writes its own',
-    on: 'Write',
-    off: 'Omit',
+    briefHint: 'One sentence about what this file defines; leave empty and each file writes its own.',
+    authorHint: 'Author credit; left empty, omitted.',
+    dateHint: 'Creation or change date; left empty, omitted.',
+    copyrightHint: 'Copyright notice; left empty, omitted.',
+    versionHint: 'File version; left empty, omitted.',
+    emptyValue: 'Empty means omit',
+    briefEmpty: 'Empty: the file writes its own',
     preview: 'Preview',
     previewHint: 'Sample name board.h; the preview follows the switches.',
     save: 'Save',
@@ -242,6 +263,7 @@ const STRINGS = {
     loading: 'Reading configuration…',
     unreadable: 'This account cannot edit the configuration.',
     readOnly: 'Showing factory defaults. Edit the dsh-cpp-workflow card on the Plugins page.',
+    openSettings: 'Open plugin settings',
     noForm: 'This entry has no writable form; edit it on the Plugins page.',
   },
 }
@@ -256,84 +278,152 @@ function t() {
 }
 
 const palette = {
-  muted: 'var(--dsw-text-tertiary, #6b7280)',
-  line: 'var(--dsw-border-subtle, rgba(127, 127, 127, 0.24))',
-  surface: 'var(--dsw-surface-raised, rgba(127, 127, 127, 0.06))',
+  label: 'var(--dsw-alias-label-primary, inherit)',
+  muted: 'var(--dsw-alias-label-secondary, #6b7280)',
+  faint: 'var(--dsw-alias-label-tertiary, #8b93a1)',
+  line: 'var(--dsw-alias-border-l2, rgba(127, 127, 127, 0.24))',
+  surface: 'var(--dsw-alias-bg-layer-2, rgba(127, 127, 127, 0.06))',
+  field: 'var(--dsw-alias-bg-layer-1, rgba(127, 127, 127, 0.04))',
+  brand: 'var(--dsw-alias-brand-primary, #4f6bed)',
   mono: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
 }
 
-function rowStyle(extra) {
-  return {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 10,
-    padding: '7px 0',
-    borderBottom: `1px solid ${palette.line}`,
-    ...extra,
-  }
-}
-
-function hintStyle() {
-  return { margin: '2px 0 0', fontSize: 12, lineHeight: 1.5, color: palette.muted }
-}
+const hintStyle = () => ({ margin: '2px 0 0', fontSize: 12, lineHeight: 1.55, color: palette.muted })
+const labelCellStyle = () => ({
+  padding: '10px 0',
+  fontFamily: palette.mono,
+  fontSize: 12.5,
+  lineHeight: '20px',
+  color: palette.label,
+  whiteSpace: 'nowrap',
+  borderBottom: `1px solid ${palette.line}`,
+})
+const controlCellStyle = () => ({
+  padding: '10px 0',
+  minWidth: 0,
+  borderBottom: `1px solid ${palette.line}`,
+})
+const gridStyle = () => ({ display: 'grid', gridTemplateColumns: '92px minmax(0, 1fr)', columnGap: 14 })
 
-function Switch(props) {
+function Toggle(props) {
   return h(
-    'label',
-    { style: { display: 'inline-flex', alignItems: 'center', gap: 8, cursor: props.disabled ? 'default' : 'pointer', minWidth: 132 } },
-    h('input', {
-      type: 'checkbox',
-      checked: Boolean(props.checked),
+    'button',
+    {
+      type: 'button',
+      role: 'switch',
+      'aria-checked': Boolean(props.checked),
+      'aria-label': props.label,
       disabled: Boolean(props.disabled),
-      onChange: (event) => props.onChange(event.target.checked),
-      style: { margin: 0 },
+      onClick: () => props.onChange(!props.checked),
+      style: {
+        flex: 'none',
+        width: 34,
+        height: 20,
+        padding: 0,
+        border: 0,
+        borderRadius: 999,
+        position: 'relative',
+        cursor: props.disabled ? 'default' : 'pointer',
+        opacity: props.disabled ? 0.5 : 1,
+        background: props.checked ? palette.brand : 'var(--dsw-alias-bg-layer-4, rgba(127, 127, 127, 0.35))',
+        transition: 'background-color 0.15s ease',
+      },
+    },
+    h('span', {
+      'aria-hidden': 'true',
+      style: {
+        position: 'absolute',
+        top: 2,
+        left: props.checked ? 16 : 2,
+        width: 16,
+        height: 16,
+        borderRadius: '50%',
+        background: '#fff',
+        boxShadow: '0 1px 2px rgba(0, 0, 0, 0.25)',
+        transition: 'left 0.15s ease',
+      },
     }),
-    h('span', { style: { fontSize: 13, fontFamily: palette.mono } }, props.label),
   )
 }
 
-function HeaderTagRow(props) {
+function TagRow(props) {
   const s = props.strings
-  const entry = props.entry
-  return h(
-    'div',
-    { style: rowStyle({ flexWrap: 'wrap' }) },
-    h('div', { style: { flex: '1 1 280px', minWidth: 0 } },
-      h(Switch, {
-        label: TAG_LABEL[props.tag],
-        checked: entry.enabled,
-        onChange: (enabled) => props.onChange({ ...entry, enabled }),
-      }),
-      h('p', { style: hintStyle() }, TAG_TEXT[props.tag] || ''),
+  return [
+    h('div', { key: `${props.tag}-label`, style: labelCellStyle() }, props.label),
+    h(
+      'div',
+      { key: `${props.tag}-control`, style: controlCellStyle() },
+      h(
+        'div',
+        { style: { display: 'flex', alignItems: 'center', gap: 10, minHeight: 22, flexWrap: 'wrap' } },
+        props.control,
+      ),
+      props.hint ? h('p', { style: hintStyle() }, props.hint) : null,
     ),
-    h('input', {
-      type: 'text',
-      value: entry.value,
-      placeholder: s.emptyValue,
-      disabled: !entry.enabled,
-      'aria-label': `${TAG_LABEL[props.tag]} value`,
-      onChange: (event) => props.onChange({ ...entry, value: event.target.value }),
-      style: {
-        flex: '1 1 220px',
-        minWidth: 0,
-        fontSize: 13,
-        padding: '5px 8px',
-        borderRadius: 6,
-        border: `1px solid ${palette.line}`,
-        background: entry.enabled ? 'transparent' : palette.surface,
-        color: 'inherit',
-      },
+  ]
+}
+
+function ValueRow(props) {
+  const s = props.strings
+  return h(TagRow, {
+    tag: props.tag,
+    label: TAG_LABEL[props.tag],
+    strings: s,
+    hint: props.hint,
+    control: [
+      h(Toggle, {
+        key: 'toggle',
+        label: props.label || TAG_LABEL[props.tag],
+        checked: props.entry.enabled,
+        disabled: props.disabled,
+        onChange: (enabled) => !props.disabled && props.onChange({ ...props.entry, enabled }),
+      }),
+      h('input', {
+        key: 'input',
+        type: 'text',
+        value: props.entry.value,
+        placeholder: props.tag === 'brief' ? s.briefEmpty : s.emptyValue,
+        disabled: props.disabled || !props.entry.enabled,
+        'aria-label': TAG_LABEL[props.tag],
+        onChange: (event) => props.onChange({ ...props.entry, value: event.target.value }),
+        style: {
+          flex: '1 1 180px',
+          minWidth: 0,
+          maxWidth: 320,
+          fontSize: 13,
+          padding: '4px 8px',
+          borderRadius: 6,
+          border: `1px solid ${palette.line}`,
+          background: props.entry.enabled && !props.disabled ? palette.field : 'transparent',
+          color: props.entry.enabled ? 'inherit' : palette.muted,
+          fontFamily: palette.mono,
+        },
+      }),
+    ],
+  })
+}
+
+function FlagRow(props) {
+  return h(TagRow, {
+    tag: props.tag,
+    label: TAG_LABEL[props.tag],
+    strings: props.strings,
+    hint: props.hint,
+    control: h(Toggle, {
+      label: TAG_LABEL[props.tag],
+      checked: Boolean(props.checked),
+      disabled: props.disabled,
+      onChange: (value) => !props.disabled && props.onChange(value),
     }),
-  )
+  })
 }
 
 function Preview(props) {
   const s = props.strings
-  const text = previewText(props.config, SAMPLE_FILE)
   return h(
     'section',
-    { 'aria-label': s.preview, style: { marginTop: 18 } },
-    h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600 } }, s.preview),
+    { 'aria-label': s.preview, style: { marginTop: 20 } },
+    h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600, color: palette.label } }, s.preview),
     h('p', { style: hintStyle() }, s.previewHint),
     h(
       'pre',
@@ -349,9 +439,10 @@ function Preview(props) {
           lineHeight: 1.65,
           fontFamily: palette.mono,
           whiteSpace: 'pre',
+          color: palette.label,
         },
       },
-      text,
+      previewText(props.config, SAMPLE_FILE),
     ),
   )
 }
@@ -421,74 +512,127 @@ function ConfigPage(props) {
 
   const editable = Boolean(form)
   const editableReady = editable && ready
-  const headerTags = ['brief', 'author', 'date', 'copyright', 'version']
+  const header = [
+    { tag: 'brief', hint: s.briefHint },
+    { tag: 'author', hint: s.authorHint },
+    { tag: 'date', hint: s.dateHint },
+    { tag: 'copyright', hint: s.copyrightHint },
+    { tag: 'version', hint: s.versionHint },
+  ]
+  const contractHints = { param: TAG_TEXT.param, returns: TAG_TEXT.returns, throws: TAG_TEXT.throws }
+  const extraHints = { note: TAG_TEXT.note, see: TAG_TEXT.see, pre: TAG_TEXT.pre, post: TAG_TEXT.post, tparam: TAG_TEXT.tparam, retval: TAG_TEXT.retval }
 
   return h(
     'div',
-    { style: { display: 'flex', flexDirection: 'column', gap: 4, padding: '4px 0 12px', maxWidth: 720 } },
-    h('h3', { style: { margin: '0 0 2px', fontSize: 15, fontWeight: 600 } }, s.title),
+    { style: { display: 'flex', flexDirection: 'column', padding: '4px 0 12px', maxWidth: 720, color: palette.label } },
+    h('h3', { style: { margin: '0 0 4px', fontSize: 15, fontWeight: 600 } }, s.title),
     h('p', { style: hintStyle() }, s.intro),
     !editable
-      ? h('p', { role: 'status', style: { ...hintStyle(), color: 'inherit', marginTop: 8 } }, s.readOnly)
+      ? h(
+          'div',
+          { style: { display: 'flex', alignItems: 'center', gap: 10, flexWrap: 'wrap', marginTop: 8 } },
+          h('p', { role: 'status', style: { ...hintStyle(), margin: 0 } }, s.readOnly),
+          props.openPluginPage
+            ? h('button', { type: 'button', onClick: props.openPluginPage, style: secondaryButton(true) }, s.openSettings)
+            : null,
+        )
       : null,
     editable && !ready && status !== 'missing'
       ? h('p', { role: 'status', style: hintStyle() }, status === 'loading' ? s.loading : s.unreadable)
       : null,
     h(
-      'fieldset',
-      { style: { margin: '14px 0 0', padding: 0, border: 0 } },
-      h('legend', { style: { padding: 0, fontSize: 13, fontWeight: 600 } }, s.header),
+      'section',
+      { style: { marginTop: 18 } },
+      h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600 } }, s.header),
+      h('p', { style: hintStyle() }, s.headerHint),
       h(
         'div',
-        { style: rowStyle() },
-        h(Switch, { label: s.file, checked: true, disabled: true, onChange: () => {} }),
-        h('p', { style: { ...hintStyle(), margin: 0 } }, s.fileHint),
-      ),
-      ...headerTags.map((tag) =>
-        h(HeaderTagRow, {
-          key: tag,
-          tag,
-          strings: s,
-          entry: draft[tag],
-          onChange: (entry) => update({ [tag]: entry }),
-        }),
+        { role: 'group', 'aria-label': s.header, style: { ...gridStyle(), marginTop: 8 } },
+        h(
+          'div',
+          { key: 'file-label', style: labelCellStyle() },
+          s.file,
+        ),
+        h(
+          'div',
+          { key: 'file-control', style: controlCellStyle() },
+          h(
+            'div',
+            { style: { display: 'flex', alignItems: 'center', gap: 10, minHeight: 22 } },
+            h(
+              'span',
+              {
+                style: {
+                  fontSize: 12,
+                  lineHeight: '20px',
+                  padding: '0 8px',
+                  borderRadius: 999,
+                  border: `1px solid ${palette.line}`,
+                  color: palette.muted,
+                },
+              },
+              s.fixed,
+            ),
+            h('code', { style: { fontSize: 12.5, fontFamily: palette.mono, color: palette.muted } }, SAMPLE_FILE),
+          ),
+          h('p', { style: hintStyle() }, s.fileHint),
+        ),
+        ...header.flatMap(({ tag, hint }) =>
+          h(ValueRow, {
+            key: tag,
+            tag,
+            hint,
+            strings: s,
+            disabled: !editable,
+            entry: draft[tag],
+            onChange: (entry) => update({ [tag]: entry }),
+          }),
+        ),
       ),
     ),
     h(
-      'fieldset',
-      { style: { margin: '18px 0 0', padding: 0, border: 0 } },
-      h('legend', { style: { padding: 0, fontSize: 13, fontWeight: 600 } }, s.contract),
+      'section',
+      { style: { marginTop: 20 } },
+      h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600 } }, s.contract),
+      h('p', { style: hintStyle() }, s.contractHint),
       h(
         'div',
-        { style: { display: 'flex', flexWrap: 'wrap', gap: '6px 18px', padding: '8px 0 2px' } },
-        ...CONTRACT_TAGS.map((tag) =>
-          h(
-            'div',
-            { key: tag, style: { flex: '1 1 180px', minWidth: 180 } },
-            h(Switch, {
-              label: TAG_LABEL[tag],
-              checked: draft[tag],
-              onChange: (value) => update({ [tag]: value }),
-            }),
-            h('p', { style: hintStyle() }, TAG_TEXT[tag]),
-          ),
+        { role: 'group', 'aria-label': s.contract, style: { ...gridStyle(), marginTop: 8 } },
+        ...CONTRACT_TAGS.flatMap((tag) =>
+          h(FlagRow, {
+            key: tag,
+            tag,
+            hint: contractHints[tag],
+            strings: s,
+            disabled: !editable,
+            checked: draft[tag],
+            onChange: (value) => update({ [tag]: value }),
+          }),
         ),
       ),
     ),
     h(
-      'details',
-      { style: { marginTop: 16, paddingTop: 10, borderTop: `1px solid ${palette.line}` } },
-      h('summary', { style: { cursor: 'pointer', fontSize: 13, fontWeight: 600 } }, s.extra),
-      h('p', { style: hintStyle() }, s.extraHint),
+      'section',
+      { style: { marginTop: 20, paddingTop: 12, borderTop: `1px solid ${palette.line}` } },
       h(
-        'div',
-        { style: { display: 'flex', flexWrap: 'wrap', gap: '6px 18px', paddingTop: 4 } },
-        ...EXTRA_TAGS.map((tag) =>
-          h(
-            'div',
-            { key: tag, style: { flex: '1 1 180px', minWidth: 180 } },
-            h(Switch, {
-              label: TAG_LABEL[tag],
+        'details',
+        {},
+        h(
+          'summary',
+          { style: { cursor: 'pointer', fontSize: 13, fontWeight: 600, listStylePosition: 'inside' } },
+          s.extra,
+        ),
+        h('p', { style: hintStyle() }, s.extraHint),
+        h(
+          'div',
+          { role: 'group', 'aria-label': s.extra, style: { ...gridStyle(), marginTop: 8 } },
+          ...EXTRA_TAGS.flatMap((tag) =>
+            h(FlagRow, {
+              key: tag,
+              tag,
+              hint: extraHints[tag],
+              strings: s,
+              disabled: !editable,
               checked: draft[tag],
               onChange: (value) => update({ [tag]: value }),
             }),
@@ -500,14 +644,24 @@ function ConfigPage(props) {
     editable
       ? h(
           'div',
-          { style: { display: 'flex', alignItems: 'center', gap: 10, marginTop: 16, flexWrap: 'wrap' } },
+          {
+            style: {
+              display: 'flex',
+              alignItems: 'center',
+              gap: 10,
+              marginTop: 18,
+              paddingTop: 12,
+              borderTop: `1px solid ${palette.line}`,
+              flexWrap: 'wrap',
+            },
+          },
           h(
             'button',
             {
               type: 'button',
               onClick: save,
               disabled: busy || !editableReady || !dirty,
-              style: { fontSize: 13, padding: '6px 14px', borderRadius: 6, cursor: 'pointer' },
+              style: primaryButton(dirty && editableReady && !busy),
             },
             s.save,
           ),
@@ -517,7 +671,7 @@ function ConfigPage(props) {
               type: 'button',
               onClick: reset,
               disabled: busy || !dirty,
-              style: { fontSize: 13, padding: '6px 14px', borderRadius: 6, cursor: 'pointer' },
+              style: secondaryButton(dirty && !busy),
             },
             s.reset,
           ),
@@ -527,12 +681,45 @@ function ConfigPage(props) {
   )
 }
 
-function page(ownerProps, titled) {
+function primaryButton(enabled) {
+  return {
+    fontSize: 13,
+    lineHeight: '20px',
+    padding: '5px 14px',
+    borderRadius: 6,
+    border: '1px solid transparent',
+    background: enabled ? palette.brand : 'var(--dsw-alias-bg-layer-3, rgba(127, 127, 127, 0.2))',
+    color: enabled ? '#fff' : palette.muted,
+    cursor: enabled ? 'pointer' : 'default',
+  }
+}
+
+function secondaryButton(enabled) {
+  return {
+    fontSize: 13,
+    lineHeight: '20px',
+    padding: '5px 14px',
+    borderRadius: 6,
+    border: `1px solid ${palette.line}`,
+    background: 'transparent',
+    color: enabled ? palette.label : palette.muted,
+    cursor: enabled ? 'pointer' : 'default',
+  }
+}
+
+function page(ownerProps, openPluginPage) {
   const props = ownerProps || {}
-  return h(ConfigPage, { ...props, titled })
+  return h(ConfigPage, { ...props, openPluginPage })
 }
 
 function apply(ctx) {
+  let openPluginPage
+  try {
+    const navigation = typeof ctx.get === 'function' ? ctx.get('pluginNavigation') : undefined
+    if (navigation && typeof navigation.openBundle === 'function') {
+      openPluginPage = () => navigation.openBundle(PACKAGE_NAME)
+    }
+  } catch {}
   ctx.slots.inject('settings.section', () =>
     ctx.slots.register(
       {
@@ -541,7 +728,7 @@ function apply(ctx) {
         order: 60,
         label: () => t().nav,
       },
-      (ownerProps) => page(ownerProps, true),
+      (ownerProps) => page(ownerProps, openPluginPage),
     ),
   )
   ctx.slots.inject('plugins.bundle.config', () =>
@@ -551,7 +738,7 @@ function apply(ctx) {
         key: PACKAGE_NAME,
         label: () => t().nav,
       },
-      (ownerProps) => (ownerProps && ownerProps.view === 'summary' ? null : page(ownerProps, false)),
+      (ownerProps) => (ownerProps && ownerProps.view === 'summary' ? null : page(ownerProps, undefined)),
     ),
   )
 }

package/lib/comment-policy.js

@@ -50,6 +50,8 @@ export const TAG_LABEL = {
     tparam: '@tparam',
     retval: '@retval',
 };
+/** 预览里的示例摘要：用户没填 @brief 时用它，避免预览出现空标签。 */
+export const SAMPLE_BRIEF = '定义井字棋棋盘、格子坐标与格子类型。';
 /** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
 export const DEFAULT_CONFIG = {
     brief: { enabled: true, value: '' },
@@ -113,6 +115,10 @@ export function renderFileHeader(raw, fileName) {
 export function previewParts(raw, sampleName) {
     const config = normalizeConfig(raw);
     const header = renderFileHeader(config, sampleName || 'board.h');
+    // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
+    const briefIndex = header.indexOf('/// @brief');
+    if (briefIndex !== -1)
+        header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
     const contract = [];
     if (config.param)
         contract.push('/// @param position 目标行列坐标。');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "写 C++ 源码、配 CMake、用 Clang 构建；文档注释统一为 /// Doxygen，文件头标签可在设置里改。 · Write C++ sources, configure CMake, and build with Clang; /// Doxygen comments, with file-header tags you can change in Settings.",
   "type": "module",
   "main": "./lib/index.js",