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

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

package/lib/client.js

@@ -58,7 +58,9 @@ const TAG_LABEL = {
     retval: '@retval',
 };
 /** 预览里的示例摘要：用户没填 @brief 时用它，避免预览出现空标签。 */
-const SAMPLE_BRIEF = '定义井字棋棋盘、格子坐标与格子类型。';
+const SAMPLE_BRIEF = '<一句话说明本文件>';
+/** 预览里的示例文件名：只是占位符，不对应任何工程的真实文件。 */
+const SAMPLE_FILE = '<文件名>';
 /** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
 const DEFAULT_CONFIG = {
     brief: { enabled: true, value: '' },
@@ -105,7 +107,7 @@ function normalizeConfig(raw) {
  */
 function renderFileHeader(raw, fileName) {
     const config = normalizeConfig(raw);
-    const name = text(fileName) || 'board.h';
+    const name = text(fileName) || SAMPLE_FILE;
     const lines = [`/// @file ${name}`];
     if (config.brief.enabled) {
         lines.push(config.brief.value ? `/// @brief ${config.brief.value}` : '/// @brief');
@@ -121,19 +123,19 @@ function renderFileHeader(raw, fileName) {
  */
 function previewParts(raw, sampleName) {
     const config = normalizeConfig(raw);
-    const header = renderFileHeader(config, sampleName || 'board.h');
+    const header = renderFileHeader(config, sampleName || SAMPLE_FILE);
     // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
     const briefIndex = header.indexOf('/// @brief');
     if (briefIndex !== -1)
         header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
     const contract = [];
     if (config.param)
-        contract.push('/// @param position 目标行列坐标。');
+        contract.push('/// @param row 目标行号。');
     if (config.returns)
         contract.push('/// @return 放置成功时为 true。');
     if (config.throws)
-        contract.push('/// @throws std::out_of_range 坐标越界时抛出。');
-    const declaration = '[[nodiscard]] bool PlaceCell(CellPosition position, CellType cell_type);';
+        contract.push('/// @throws std::out_of_range 行号越界时抛出。');
+    const declaration = '[[nodiscard]] bool Place(int row, int column);';
     return { header, contract, declaration };
 }
 /**
@@ -141,7 +143,7 @@ function previewParts(raw, sampleName) {
  */
 function previewText(raw, sampleName) {
     const { header, contract, declaration } = previewParts(raw, sampleName);
-    const lines = [...header, '///', '/// 放置成功返回 true；坐标越界或目标已占时返回 false。'];
+    const lines = [...header, '///', '/// 放置成功时返回 true；行号越界或目标格子已占时返回 false。'];
     if (contract.length > 0)
         lines.push('///', ...contract);
     lines.push(declaration);
@@ -193,27 +195,28 @@ function snapshotText(raw) {
 // 客户端半侧：设置导航里的「C++ 工程流程」页与插件页的配置卡片共用同一个组件。
 // 标签策略在本文件上方内联（由 scripts/building-client.mjs 从 src/comment-policy.js
 // 拼进来），所以预览、默认值与服务端快照永远同源；这里只做表单与排版。
+//
+// 版式参照 VS Code 设置页：左侧标签与说明、右侧控件，行间细分隔线；
+// 修改过默认值的行在标签前加一个圆点，底部固定一条保存栏。
 const React = require('react')
 const h = React.createElement
 
 const PACKAGE_NAME = '@chengzhao-dev/dsh-cpp-workflow'
-const SAMPLE_FILE = 'board.h'
 
 const STRINGS = {
   zh: {
     nav: 'C++ 工程流程',
     title: '文档注释',
-    intro: '文件头与函数契约默认写出哪些 Doxygen 标签。配置只影响代理写注释的默认值，不改已有源码。',
+    intro: '设置文件头与函数声明注释里默认写出的 Doxygen 标签；改动影响之后写出的注释，已有源码保持原样。',
     header: '文件头',
-    headerHint: '每个手写源文件开头的一段 ///；带值的标签填写后写出，@brief 留空由文件自述。',
+    headerHint: '每个手写源文件开头的一段 /// 注释。',
     contract: '函数契约',
-    contractHint: '声明注释里的参数与失败方式；关闭后不再要求写出这些标签。',
+    contractHint: '函数声明注释里要求的参数与失败信息。',
     extra: '更多标签',
-    extraHint: '默认关闭；需要时在单个函数上补写。',
+    extraHint: '需要时在单个函数上补写。',
     file: '@file',
-    fixed: '自动',
-    fileHint: '固定为当前文件名，不参与配置。',
-    briefHint: '一句话说明本文件定义或实现什么；留空则由每个文件自己写。',
+    fileHint: '取自当前文件名。',
+    briefHint: '一句话说明这个文件定义或实现什么；留空则由文件自述。',
     authorHint: '作者署名；留空不写。',
     dateHint: '创建或修改日期；留空不写。',
     copyrightHint: '版权声明；留空不写。',
@@ -221,7 +224,7 @@ const STRINGS = {
     emptyValue: '留空不写',
     briefEmpty: '留空则由文件自述',
     preview: '预览',
-    previewHint: '示例文件名 board.h；预览随开关即时更新。',
+    previewHint: '按当前开关生成；文件名以占位符表示。',
     save: '保存',
     reset: '重置',
     saved: '已保存，下一次读取技能时生效。',
@@ -229,24 +232,23 @@ const STRINGS = {
     unsaved: '有未保存的改动。',
     loading: '正在读取配置…',
     unreadable: '当前账户不能修改这份配置。',
-    readOnly: '此处只显示出厂值。要修改配置，请到「插件」页打开 dsh-cpp-workflow 的配置卡片。',
+    readOnly: '此处显示出厂值；修改在「插件」页的配置卡片里进行。',
     openSettings: '打开插件配置',
-    noForm: '这个入口没有可写表单，配置在插件页修改。',
+    modified: '与出厂值不同',
   },
   en: {
     nav: 'C++ Workflow',
     title: 'Documentation comments',
-    intro: 'Which Doxygen tags the agent writes by default. This changes defaults only; existing sources are untouched.',
+    intro: 'Choose the Doxygen tags written by default in file headers and declaration comments. Changes affect new comments; existing sources stay as they are.',
     header: 'File header',
-    headerHint: 'The /// block at the top of every hand-written source; value tags are written only when filled.',
+    headerHint: 'The /// block at the top of every hand-written source.',
     contract: 'Function contract',
-    contractHint: 'Parameter and failure tags in declaration comments; turning one off stops requiring it.',
+    contractHint: 'Parameter and failure tags required in declaration comments.',
     extra: 'More tags',
-    extraHint: 'Off by default; add them per function when needed.',
+    extraHint: 'Add them per function when needed.',
     file: '@file',
-    fixed: 'Auto',
-    fileHint: 'Always the current file name; not configurable.',
-    briefHint: 'One sentence about what this file defines; leave empty and each file writes its own.',
+    fileHint: 'Taken from the current file name.',
+    briefHint: 'One sentence about what this file defines; leave empty and the file writes its own.',
     authorHint: 'Author credit; left empty, omitted.',
     dateHint: 'Creation or change date; left empty, omitted.',
     copyrightHint: 'Copyright notice; left empty, omitted.',
@@ -254,7 +256,7 @@ const STRINGS = {
     emptyValue: 'Empty means omit',
     briefEmpty: 'Empty: the file writes its own',
     preview: 'Preview',
-    previewHint: 'Sample name board.h; the preview follows the switches.',
+    previewHint: 'Generated from the switches; the file name is a placeholder.',
     save: 'Save',
     reset: 'Reset',
     saved: 'Saved; the next skill read uses it.',
@@ -262,9 +264,9 @@ const STRINGS = {
     unsaved: 'Unsaved changes.',
     loading: 'Reading configuration…',
     unreadable: 'This account cannot edit the configuration.',
-    readOnly: 'Showing factory defaults. Edit the dsh-cpp-workflow card on the Plugins page.',
+    readOnly: 'Factory values are shown here; edit them on the Plugins page.',
     openSettings: 'Open plugin settings',
-    noForm: 'This entry has no writable form; edit it on the Plugins page.',
+    modified: 'Differs from the factory value',
   },
 }
 
@@ -280,7 +282,6 @@ function t() {
 const palette = {
   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))',
@@ -288,115 +289,143 @@ const palette = {
   mono: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
 }
 
-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 })
+const descriptionStyle = () => ({ margin: '2px 0 0', fontSize: 12, lineHeight: 1.55, color: palette.muted })
+const sectionTitleStyle = () => ({ margin: '0 0 2px', fontSize: 13, fontWeight: 600, color: palette.label })
+
+function Section(props) {
+  return h(
+    'section',
+    {
+      style: {
+        marginTop: props.first ? 16 : 22,
+        paddingTop: props.first ? 0 : 14,
+        borderTop: props.first ? 'none' : `1px solid ${palette.line}`,
+      },
+    },
+    h('h4', { style: sectionTitleStyle() }, props.title),
+    props.description ? h('p', { style: descriptionStyle() }, props.description) : null,
+    h('div', { style: { marginTop: 6 } }, props.children),
+  )
+}
+
+function Row(props) {
+  return h(
+    'div',
+    {
+      style: {
+        display: 'grid',
+        gridTemplateColumns: 'minmax(0, 1fr) minmax(160px, 240px)',
+        columnGap: 24,
+        alignItems: 'start',
+        padding: '10px 0',
+        borderBottom: `1px solid ${palette.line}`,
+      },
+    },
+    h(
+      'div',
+      { style: { minWidth: 0 } },
+      h(
+        'div',
+        { style: { display: 'flex', alignItems: 'center', gap: 6, minHeight: 20 } },
+        props.modified
+          ? h('span', {
+              key: 'dot',
+              title: props.modifiedLabel,
+              'aria-label': props.modifiedLabel,
+              style: { width: 6, height: 6, borderRadius: '50%', background: palette.brand, flex: 'none' },
+            })
+          : null,
+        h('span', { style: { fontSize: 13, lineHeight: '20px', color: palette.label, fontFamily: props.mono ? palette.mono : 'inherit' } }, props.label),
+      ),
+      props.description ? h('p', { style: descriptionStyle() }, props.description) : null,
+    ),
+    h(
+      'div',
+      { style: { display: 'flex', alignItems: 'center', justifyContent: 'flex-end', gap: 8, minHeight: 20 } },
+      props.control,
+    ),
+  )
+}
 
-function Toggle(props) {
+function Checkbox(props) {
   return h(
     'button',
     {
       type: 'button',
-      role: 'switch',
+      role: 'checkbox',
       'aria-checked': Boolean(props.checked),
       'aria-label': props.label,
       disabled: Boolean(props.disabled),
       onClick: () => props.onChange(!props.checked),
       style: {
         flex: 'none',
-        width: 34,
-        height: 20,
+        width: 16,
+        height: 16,
         padding: 0,
-        border: 0,
-        borderRadius: 999,
-        position: 'relative',
+        borderRadius: 4,
+        border: `1px solid ${props.checked ? palette.brand : palette.line}`,
+        background: props.checked ? palette.brand : 'transparent',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
         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',
+        opacity: props.disabled ? 0.55 : 1,
+        transition: 'background-color 0.12s ease, border-color 0.12s 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',
-      },
-    }),
-  )
-}
-
-function TagRow(props) {
-  const s = props.strings
-  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,
+      'svg',
+      { width: 11, height: 11, viewBox: '0 0 12 12', 'aria-hidden': 'true' },
+      h('path', {
+        d: 'M2.6 6.3 5 8.7l4.4-5.2',
+        fill: 'none',
+        stroke: '#fff',
+        strokeWidth: 1.7,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+        opacity: props.checked ? 1 : 0,
+      }),
     ),
-  ]
+  )
 }
 
 function ValueRow(props) {
   const s = props.strings
-  return h(TagRow, {
-    tag: props.tag,
+  const entry = props.entry
+  return h(Row, {
     label: TAG_LABEL[props.tag],
-    strings: s,
-    hint: props.hint,
+    mono: true,
+    description: props.hint,
+    modified: props.modified,
+    modifiedLabel: s.modified,
     control: [
-      h(Toggle, {
-        key: 'toggle',
-        label: props.label || TAG_LABEL[props.tag],
-        checked: props.entry.enabled,
+      h(Checkbox, {
+        key: 'check',
+        label: TAG_LABEL[props.tag],
+        checked: entry.enabled,
         disabled: props.disabled,
-        onChange: (enabled) => !props.disabled && props.onChange({ ...props.entry, enabled }),
+        onChange: (enabled) => props.onChange({ ...entry, enabled }),
       }),
       h('input', {
         key: 'input',
         type: 'text',
-        value: props.entry.value,
+        value: entry.value,
         placeholder: props.tag === 'brief' ? s.briefEmpty : s.emptyValue,
-        disabled: props.disabled || !props.entry.enabled,
+        disabled: props.disabled || !entry.enabled,
         'aria-label': TAG_LABEL[props.tag],
-        onChange: (event) => props.onChange({ ...props.entry, value: event.target.value }),
+        onChange: (event) => props.onChange({ ...entry, value: event.target.value }),
         style: {
-          flex: '1 1 180px',
+          width: '100%',
           minWidth: 0,
-          maxWidth: 320,
           fontSize: 13,
-          padding: '4px 8px',
-          borderRadius: 6,
+          lineHeight: '18px',
+          padding: '3px 7px',
+          borderRadius: 4,
           border: `1px solid ${palette.line}`,
-          background: props.entry.enabled && !props.disabled ? palette.field : 'transparent',
-          color: props.entry.enabled ? 'inherit' : palette.muted,
+          background: entry.enabled && !props.disabled ? palette.field : 'transparent',
+          color: entry.enabled ? 'inherit' : palette.muted,
           fontFamily: palette.mono,
+          boxSizing: 'border-box',
         },
       }),
     ],
@@ -404,16 +433,17 @@ function ValueRow(props) {
 }
 
 function FlagRow(props) {
-  return h(TagRow, {
-    tag: props.tag,
+  return h(Row, {
     label: TAG_LABEL[props.tag],
-    strings: props.strings,
-    hint: props.hint,
-    control: h(Toggle, {
+    mono: true,
+    description: props.hint,
+    modified: props.modified,
+    modifiedLabel: props.strings.modified,
+    control: h(Checkbox, {
       label: TAG_LABEL[props.tag],
       checked: Boolean(props.checked),
       disabled: props.disabled,
-      onChange: (value) => !props.disabled && props.onChange(value),
+      onChange: (value) => props.onChange(value),
     }),
   })
 }
@@ -422,16 +452,16 @@ function Preview(props) {
   const s = props.strings
   return h(
     'section',
-    { '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),
+    { 'aria-label': s.preview, style: { marginTop: 22, paddingTop: 14, borderTop: `1px solid ${palette.line}` } },
+    h('h4', { style: sectionTitleStyle() }, s.preview),
+    h('p', { style: descriptionStyle() }, s.previewHint),
     h(
       'pre',
       {
         style: {
           margin: '8px 0 0',
           padding: '10px 12px',
-          borderRadius: 8,
+          borderRadius: 6,
           background: palette.surface,
           border: `1px solid ${palette.line}`,
           overflowX: 'auto',
@@ -442,7 +472,7 @@ function Preview(props) {
           color: palette.label,
         },
       },
-      previewText(props.config, SAMPLE_FILE),
+      previewText(props.config),
     ),
   )
 }
@@ -457,6 +487,10 @@ function diffOperations(draft, base) {
   return operations
 }
 
+function isModified(key, draft) {
+  return JSON.stringify(draft[key]) !== JSON.stringify(DEFAULT_CONFIG[key])
+}
+
 function ConfigPage(props) {
   const s = t()
   const form = props.form
@@ -511,133 +545,97 @@ function ConfigPage(props) {
   }
 
   const editable = Boolean(form)
-  const editableReady = editable && ready
-  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 }
+  const headerHints = {
+    brief: s.briefHint,
+    author: s.authorHint,
+    date: s.dateHint,
+    copyright: s.copyrightHint,
+    version: s.versionHint,
+  }
 
   return h(
     'div',
-    { 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),
+    { style: { display: 'flex', flexDirection: 'column', padding: '2px 0 8px', maxWidth: 760, color: palette.label } },
+    h('h3', { style: { margin: '0 0 2px', fontSize: 15, fontWeight: 600 } }, s.title),
+    h('p', { style: descriptionStyle() }, s.intro),
     !editable
       ? h(
           'div',
-          { style: { display: 'flex', alignItems: 'center', gap: 10, flexWrap: 'wrap', marginTop: 8 } },
-          h('p', { role: 'status', style: { ...hintStyle(), margin: 0 } }, s.readOnly),
+          {
+            role: 'status',
+            style: {
+              display: 'flex',
+              alignItems: 'center',
+              gap: 10,
+              flexWrap: 'wrap',
+              marginTop: 10,
+              padding: '8px 10px',
+              borderRadius: 6,
+              background: palette.surface,
+              border: `1px solid ${palette.line}`,
+            },
+          },
+          h('p', { style: { ...descriptionStyle(), margin: 0, flex: '1 1 200px' } }, 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)
+      ? h('p', { role: 'status', style: descriptionStyle() }, status === 'loading' ? s.loading : s.unreadable)
       : null,
     h(
-      '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',
-        { 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 }),
-          }),
-        ),
+      Section,
+      { title: s.header, description: s.headerHint, first: true },
+      h(Row, {
+        label: s.file,
+        mono: true,
+        description: s.fileHint,
+        control: null,
+      }),
+      ...HEADER_TAGS.map((tag) =>
+        h(ValueRow, {
+          key: tag,
+          tag,
+          hint: headerHints[tag],
+          strings: s,
+          disabled: !editable,
+          modified: editable && isModified(tag, draft),
+          entry: draft[tag],
+          onChange: (entry) => update({ [tag]: entry }),
+        }),
       ),
     ),
     h(
-      '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',
-        { 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 }),
-          }),
-        ),
+      Section,
+      { title: s.contract, description: s.contractHint },
+      ...CONTRACT_TAGS.map((tag) =>
+        h(FlagRow, {
+          key: tag,
+          tag,
+          hint: TAG_TEXT[tag],
+          strings: s,
+          disabled: !editable,
+          modified: editable && isModified(tag, draft),
+          checked: draft[tag],
+          onChange: (value) => update({ [tag]: value }),
+        }),
       ),
     ),
     h(
-      'section',
-      { style: { marginTop: 20, paddingTop: 12, borderTop: `1px solid ${palette.line}` } },
-      h(
-        '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 }),
-            }),
-          ),
-        ),
+      Section,
+      { title: s.extra, description: s.extraHint },
+      ...EXTRA_TAGS.map((tag) =>
+        h(FlagRow, {
+          key: tag,
+          tag,
+          hint: TAG_TEXT[tag],
+          strings: s,
+          disabled: !editable,
+          modified: editable && isModified(tag, draft),
+          checked: draft[tag],
+          onChange: (value) => update({ [tag]: value }),
+        }),
       ),
     ),
     h(Preview, { config: draft, strings: s }),
@@ -649,7 +647,7 @@ function ConfigPage(props) {
               display: 'flex',
               alignItems: 'center',
               gap: 10,
-              marginTop: 18,
+              marginTop: 20,
               paddingTop: 12,
               borderTop: `1px solid ${palette.line}`,
               flexWrap: 'wrap',
@@ -660,8 +658,8 @@ function ConfigPage(props) {
             {
               type: 'button',
               onClick: save,
-              disabled: busy || !editableReady || !dirty,
-              style: primaryButton(dirty && editableReady && !busy),
+              disabled: busy || !ready || !dirty,
+              style: primaryButton(dirty && ready && !busy),
             },
             s.save,
           ),
@@ -675,7 +673,7 @@ function ConfigPage(props) {
             },
             s.reset,
           ),
-          h('p', { role: 'status', style: { ...hintStyle(), margin: 0, flex: '1 1 220px' } }, message || (dirty ? s.unsaved : '')),
+          h('p', { role: 'status', style: { ...descriptionStyle(), margin: 0, flex: '1 1 200px' } }, message || (dirty ? s.unsaved : '')),
         )
       : null,
   )
@@ -685,8 +683,8 @@ function primaryButton(enabled) {
   return {
     fontSize: 13,
     lineHeight: '20px',
-    padding: '5px 14px',
-    borderRadius: 6,
+    padding: '4px 12px',
+    borderRadius: 4,
     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,
@@ -698,8 +696,8 @@ function secondaryButton(enabled) {
   return {
     fontSize: 13,
     lineHeight: '20px',
-    padding: '5px 14px',
-    borderRadius: 6,
+    padding: '4px 12px',
+    borderRadius: 4,
     border: `1px solid ${palette.line}`,
     background: 'transparent',
     color: enabled ? palette.label : palette.muted,

package/lib/comment-policy.js

@@ -51,7 +51,9 @@ export const TAG_LABEL = {
     retval: '@retval',
 };
 /** 预览里的示例摘要：用户没填 @brief 时用它，避免预览出现空标签。 */
-export const SAMPLE_BRIEF = '定义井字棋棋盘、格子坐标与格子类型。';
+export const SAMPLE_BRIEF = '<一句话说明本文件>';
+/** 预览里的示例文件名：只是占位符，不对应任何工程的真实文件。 */
+export const SAMPLE_FILE = '<文件名>';
 /** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
 export const DEFAULT_CONFIG = {
     brief: { enabled: true, value: '' },
@@ -98,7 +100,7 @@ export function normalizeConfig(raw) {
  */
 export function renderFileHeader(raw, fileName) {
     const config = normalizeConfig(raw);
-    const name = text(fileName) || 'board.h';
+    const name = text(fileName) || SAMPLE_FILE;
     const lines = [`/// @file ${name}`];
     if (config.brief.enabled) {
         lines.push(config.brief.value ? `/// @brief ${config.brief.value}` : '/// @brief');
@@ -114,19 +116,19 @@ export function renderFileHeader(raw, fileName) {
  */
 export function previewParts(raw, sampleName) {
     const config = normalizeConfig(raw);
-    const header = renderFileHeader(config, sampleName || 'board.h');
+    const header = renderFileHeader(config, sampleName || SAMPLE_FILE);
     // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
     const briefIndex = header.indexOf('/// @brief');
     if (briefIndex !== -1)
         header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
     const contract = [];
     if (config.param)
-        contract.push('/// @param position 目标行列坐标。');
+        contract.push('/// @param row 目标行号。');
     if (config.returns)
         contract.push('/// @return 放置成功时为 true。');
     if (config.throws)
-        contract.push('/// @throws std::out_of_range 坐标越界时抛出。');
-    const declaration = '[[nodiscard]] bool PlaceCell(CellPosition position, CellType cell_type);';
+        contract.push('/// @throws std::out_of_range 行号越界时抛出。');
+    const declaration = '[[nodiscard]] bool Place(int row, int column);';
     return { header, contract, declaration };
 }
 /**
@@ -134,7 +136,7 @@ export function previewParts(raw, sampleName) {
  */
 export function previewText(raw, sampleName) {
     const { header, contract, declaration } = previewParts(raw, sampleName);
-    const lines = [...header, '///', '/// 放置成功返回 true；坐标越界或目标已占时返回 false。'];
+    const lines = [...header, '///', '/// 放置成功时返回 true；行号越界或目标格子已占时返回 false。'];
     if (contract.length > 0)
         lines.push('///', ...contract);
     lines.push(declaration);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "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",

package/skills/building-cpp/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 ## 适用场景
 
-管 `environment.json`、`running-build.sh`、`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/`、构建命令、编译数据库、CTest 和运行。`CMakeLists.txt` 与 `cmake/` 下的 target、属性、标准和模块由 `configuring-cmake` 负责；本技能只读它们来配置和检查，不在这一步改 target 图。函数体、类型、命名、异常和源码注释只开 `developing-cpp`。
+本技能处理环境声明、构建入口与工具配置：`environment.json`、`running-build.sh`、`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/`、构建命令、编译数据库、CTest 和运行。`CMakeLists.txt` 与 `cmake/` 下的 target、属性、标准和模块由 `configuring-cmake` 负责；本技能只读它们来配置和检查，不在这一步改 target 图。函数体、类型、命名、异常和源码注释只开 `developing-cpp`。
 
 一次改动同时碰到源码和构建文件时，先打开 `developing-cpp` 定行为、边界与实现；需要新增或移动源文件、改库与程序的边界、补测试 target 时，转到 `configuring-cmake` 把文件写进 CMake；最后回到本技能做定工具配置与通过检查。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开本技能的「通过检查」。
 
@@ -26,7 +26,7 @@ metadata:
 | 增量修正 | 用户点了一条工具配置、一条诊断或一个入口脚本错误 | 先判断属于定构建还是定工具配置，只改那一处，不动无关 target 和配置 |
 | 整段重构 | 新工程、新阶段、换环境组合，或第一次接构建 | 同样三步；先确认 target 与标准已由 configuring-cmake 写好，再改工具文件，最后跑完整检查 |
 
-共同不变量：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用增量修正；发现环境轴、编译器、构建目录或 target 契约需要改，退回整段，并转 `configuring-cmake`。
+两种走法共用这些约束：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用增量修正；发现环境轴、编译器、构建目录或 target 契约需要改，退回整段，并转 `configuring-cmake`。
 
 ## 步骤
 

package/skills/configuring-cmake/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 ## 适用场景
 
-管 `CMakeLists.txt`、`cmake/` 下的模块、`target_*` 命令、目标属性、include 与链接边界、输出目录、共享库运行时路径、`FetchContent`、preset 与安装导出。函数体、类型、命名、异常和源码注释只开 `developing-cpp`；配置完成后要跑构建、格式化、静态检查或入口脚本时开 `building-cpp`。
+本技能处理 CMake 文件与 target 契约：`CMakeLists.txt`、`cmake/` 模块、`target_*` 命令、目标属性、include 与链接边界、输出目录、共享库运行时路径、`FetchContent`、preset 与安装导出。函数体、类型、命名、异常和源码注释只开 `developing-cpp`；配置完成后要跑构建、格式化、静态检查或入口脚本时开 `building-cpp`。
 
 一次改动同时碰到源码和 CMake 时先开 `developing-cpp` 定行为与边界，再用本技能把源文件、库和程序写进 target，最后到 `building-cpp` 跑检查。只改一个 target 的 include、链接或标准时走增量修正；新工程、新组件、换语言标准或抽公共函数时走整段重构。
 
@@ -22,7 +22,7 @@ metadata:
 | 增量修正 | 一个 target 的 include、链接、标准、输出目录或一条属性不对 | 先读现有 `CMakeLists.txt`，只改这一处，不动无关 target 和全局设置 |
 | 整段重构 | 新工程、新组件、抽公共函数、换语言标准或整理目录 | 同样三步；先定 target 图与标准，再定模块与函数，最后跑完整检查 |
 
-共同不变量：不发明项目没有声明的 target、标准、编译器或目录；不覆盖已有 `CMakeLists.txt`；不用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料；不写 `file(GLOB ...)`；不把 `main()` 编进库；库与程序不下载依赖，只有测试需要时调用 `LinkSettings_FetchGoogleTest`。后一步发现前一步没做完，退回那一步。
+两种走法共用这些约束：不发明项目没有声明的 target、标准、编译器或目录；不覆盖已有 `CMakeLists.txt`；不用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料；不写 `file(GLOB ...)`；不把 `main()` 编进库；库与程序不下载依赖，只有测试需要时调用 `LinkSettings_FetchGoogleTest`。后一步发现前一步没做完，退回那一步。
 
 ## 步骤
 

package/skills/developing-cpp/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 ## 适用场景
 
-管 `.h` / `.hpp` / `.cpp` / `.cc` 里换一台机器也不会改的内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。文件槽位与守卫以 `references/file-template.md` 为准；排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文采用 C++ Core Guidelines 的 Error handling，作为开发阶段的源码指导；它不进入插件运行时。`CMakeLists.txt` 与 `cmake/` 开 `configuring-cmake`；`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 开 `building-cpp`。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `configuring-cmake` 把文件写进 CMake，再开 `building-cpp` 定工具配置并通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
+本技能处理换一台机器也不会改的源码内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。文件槽位与守卫以 `references/file-template.md` 为准；排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文取自 C++ Core Guidelines 的 Error handling，只约束开发期的源码，不进入插件运行时。`CMakeLists.txt` 与 `cmake/` 开 `configuring-cmake`；`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 开 `building-cpp`。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `configuring-cmake` 把文件写进 CMake，再开 `building-cpp` 定工具配置并通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
 
 存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令。没有项目技能时门禁不会放出本技能，不要猜项目约定。
 
@@ -22,7 +22,7 @@ metadata:
 | 增量修正 | 用户点了一个函数、一条诊断或一个文件 | 沿本技能步骤走，只改判为不合格的那一处，其余保持原样 |
 | 整段重构 | 新工程、新阶段、用户没点名范围，或改动跨过库与程序的边界 | 同样四步；第 1、2 步先定删留，不动函数体；第 3、4 步才改代码 |
 
-共同不变量：不发明阶段表和用户请求里没有的行为、类型和命令；只改注释或格式时不改可观察行为；不覆盖已有源码；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步，不在当前步补结构。拿不准先用增量修正；做到一半发现边界被打破，退回整段重构，从被打破的那一步重走。
+两种走法共用这些约束：不发明阶段表和用户请求里没有的行为、类型和命令；只改注释或格式时不改可观察行为；不覆盖已有源码；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步，不在当前步补结构。拿不准先用增量修正；做到一半发现边界被打破，退回整段重构，从被打破的那一步重走。
 
 ## 步骤
 

package/skills/developing-cpp/references/comments.md

@@ -129,20 +129,19 @@ GameResult result_ = GameResult::kInProgress;
 ```
 
 - C++ 源文件用以上格式；CMake 用 `#`，YAML/JSON 用 `#`。
-- 超过约 200 行的文件用章节横幅分组，组名是读者要跳转的锚点；一个文件不超过 8 个横幅。
+- 超过约 200 行的文件用空行分成几节，每节的说明写在一行 `///` 上，不画装饰线。
 - 文件头 3–7 行；`@file` 与 `@brief` 各占一行，后面只写本文件的范围与组成，不写实现步骤、作者和变更史。
 
-## 排版：符号、宽度、横幅与标签
+## 排版：符号、宽度与标签
 
-- 行宽跟项目 `.clang-format` 的 `ColumnLimit` 走（Google 基线是 80 列，中文按两列计）；横幅与列宽同宽，不另设数字。
-- 横幅宽度等于 `ColumnLimit`：`//===` 起头、`===//` 收尾，中间补 `-`；章节横幅同一格式。
+- 行宽跟项目 `.clang-format` 的 `ColumnLimit` 走（Google 基线是 80 列，中文按两列计）。
 - 行尾注释与代码之间空两格；`///<` 只接在枚举项和 `struct` 短字段声明行尾。
 - `@param`、`@return`、`@throws` 标签保持英文；`@param` 后先写参数名，再写一句。
 - `TODO:` 后先写定位（阶段名或 issue 号），再写一个短横线，再写动作；不写 `TODO(某人)`，不写没有动作的 TODO。
 - `.clang-format`、`.clang-tidy`、`.clangd`、CMake 的配置项旁边写「为什么这样设」，不写「这一项是什么」；配置注释贴在被解释的键上方。
 - 禁止：大段表格、装饰图案、表情；外部资料路径、跨仓库引用、团队流程；注释掉的代码；注释元叙述（「其余内容见某处」「两处不重复」）。
-- `///`、`@param`、横幅不进入 `.qmd`、YAML、CSS。
-- C++ 源文件的说明性注释一律 `///`，实现区不与 `//` 混用；`//` 只留给文件头横幅边框与被引用的配置行。
+- `///` 与 `@param` 不进入 `.qmd`、YAML、CSS。
+- C++ 源文件的说明性注释一律 `///`，实现区不与 `//` 混用；`//` 只留给 `// NOLINTNEXTLINE(...)` 这类工具指令。
 
 ## 润色：删复述，统一句式
 

package/skills/developing-cpp/references/google-cpp-style.md

@@ -98,5 +98,5 @@ Google 原文不使用 C++ 异常；本工作流只在开发阶段的源码指
 ## 注释
 
 - 注释写意图、契约、取舍，不复述代码。
-- 文件头、章节横幅、声明注释、实现注释、配置注释的格式见 `references/comments.md`。
+- 文件头、声明注释、实现注释与配置注释的格式见 `references/comments.md`。
 - TODO 统一写 `// TODO: <阶段或 issue> - <要做什么>`；不要写 `@todo`、`FIXME` 或只有「参考」没有动作的占位。

package/skills/developing-cpp/scripts/checking-comments.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 // 只读注释审计：按 references/comments.md 的硬规则检查 C/C++ 源文件。
 //
-// 检查项：文件头横幅、横幅宽度、注释行宽度、Doxygen 标签、注释与声明的贴合、
+// 检查项：Doxygen 文件头、注释行宽度、标签、注释与声明的贴合、
 // 类型注释存在性、成员功能清单、设计论证（方案对比）、否定式边界、领域尺寸、谓词首句、@param 完整性、枚举成员注释一致性、数据成员主注释位置。
 // 不重写任何文件。
 //
 // 用法：
-//   node checking-comments.mjs [--root DIR] [--width N] [--banner-width N] [--no-header] [--json] [--quiet]
+//   node checking-comments.mjs [--root DIR] [--width N] [--no-header] [--json] [--quiet]
 //
 // 退出码：0 无问题，1 发现问题，2 用法或读取错误。
 import { readdirSync, readFileSync, statSync } from 'node:fs'
@@ -28,7 +28,6 @@ const SKIP_DIR = new Set([
 const STATIC_FORBIDDEN_TAGS = ['@returns', '@details', '@since', '@todo']
 const PRIVACY_TAGS = ['@author', '@date', '@copyright', '@version']
 const FORBIDDEN_TAGS = [...STATIC_FORBIDDEN_TAGS, ...PRIVACY_TAGS]
-const BANNER = /^\/\/=+-+=+\/\/$/
 const DOXY_FILE = /^\/\/\/\s*@file\s+\S/
 const DOXY_BRIEF = /^\/\/\/\s*@brief\s+\S/
 const MEMBER_LIST = /提供[^。]{0,40}、[^。]{0,40}(的功能|的能力|的接口)|功能[:：]/
@@ -42,12 +41,12 @@ const DECL_KEYWORDS = /^(class|struct|union|enum|namespace|using|typedef|templat
 
 function usage(message) {
   if (message) process.stderr.write(`错误：${message}\n`)
-  process.stderr.write('用法：node checking-comments.mjs [--root DIR] [--width N] [--banner-width N] [--no-header] [--no-brief] [--allow-tag TAG] [--json] [--quiet]\n')
+  process.stderr.write('用法：node checking-comments.mjs [--root DIR] [--width N] [--no-header] [--no-brief] [--allow-tag TAG] [--json] [--quiet]\n')
   return EXIT.usage
 }
 
 function parseArgs(argv) {
-  const options = { root: undefined, width: 80, bannerWidth: 80, widthExplicit: false, bannerWidthExplicit: false, requireHeader: true, requireBrief: true, allowTags: new Set(), json: false, quiet: false }
+  const options = { root: undefined, width: 80, widthExplicit: false, requireHeader: true, requireBrief: true, allowTags: new Set(), json: false, quiet: false }
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]
     if (arg === '--root') {
@@ -57,10 +56,6 @@ function parseArgs(argv) {
       options.width = Number(argv[index + 1])
       options.widthExplicit = true
       index += 1
-    } else if (arg === '--banner-width') {
-      options.bannerWidth = Number(argv[index + 1])
-      options.bannerWidthExplicit = true
-      index += 1
     } else if (arg === '--no-header') {
       options.requireHeader = false
     } else if (arg === '--no-brief') {
@@ -80,10 +75,8 @@ function parseArgs(argv) {
       throw new Error(`未知参数 ${arg}`)
     }
   }
-  for (const key of ['width', 'bannerWidth']) {
-    if (!Number.isInteger(options[key]) || options[key] < 40) {
-      throw new Error(`--${key} 需要不小于 40 的整数`)
-    }
+  if (!Number.isInteger(options.width) || options.width < 40) {
+    throw new Error('--width 需要不小于 40 的整数')
   }
   return options
 }
@@ -208,7 +201,6 @@ function classMemberLines(lines) {
 /** 检查一段文本，返回问题列表；每个问题带 1 起始的行号。 */
 export function checkText(text, options = {}) {
   const width = options.width ?? 80
-  const bannerWidth = options.bannerWidth ?? 80
   const requireHeader = options.requireHeader ?? true
   const lines = text.split(/\r?\n/)
   const issues = []
@@ -223,13 +215,12 @@ export function checkText(text, options = {}) {
     doxyHeaderEnd = firstContent
     while (doxyHeaderEnd + 1 < lines.length && lines[doxyHeaderEnd + 1].trim().startsWith('///')) doxyHeaderEnd += 1
   }
-  if (requireHeader && firstContent !== -1 && !BANNER.test(firstTrimmed) && !hasDoxyHeader) {
+  if (requireHeader && firstContent !== -1 && !hasDoxyHeader) {
     add(firstContent + 1, 'header-missing', '文件开头缺少文件头：写 /// @file <文件名>，下一行写 /// @brief')
   }
-  if (firstContent !== -1 && (BANNER.test(firstTrimmed) || hasDoxyHeader)) {
+  if (firstContent !== -1 && hasDoxyHeader) {
     const own = options.fileName ? options.fileName.split(/[\\/]/).pop() : ''
-    const bannerHeader = BANNER.test(firstTrimmed)
-    if (hasDoxyHeader && own) {
+    if (own) {
       const declared = /@file\s+(\S+)/.exec(lines[firstContent].trim())
       if (declared && declared[1] !== own) {
         add(firstContent + 1, 'header-file-name', `文件头写的是 ${declared[1]}，本文件是 ${own}：@file 必须等于文件名`)
@@ -240,7 +231,7 @@ export function checkText(text, options = {}) {
     }
     for (let index = firstContent + 1; index < lines.length; index += 1) {
       const trimmed = lines[index].trim()
-      if (bannerHeader ? BANNER.test(trimmed) || !trimmed.startsWith('//') : !trimmed.startsWith('///')) break
+      if (!trimmed.startsWith('///')) break
       const names = trimmed.match(/\b[A-Za-z0-9_-]+\.(?:h|hpp|cpp|cc)\b/g) ?? []
       const fileMatches = trimmed.match(/@file\s+(\S+)/)
       const namesToCheck = fileMatches ? names.filter((name) => name !== fileMatches[1]) : names
@@ -254,11 +245,6 @@ export function checkText(text, options = {}) {
   for (let index = 0; index < lines.length; index += 1) {
     const line = lines[index]
     const trimmed = line.trim()
-    if (BANNER.test(trimmed)) {
-      const actual = displayWidth(trimmed)
-      if (actual !== bannerWidth) add(index + 1, 'banner-width', `横幅宽度 ${actual} 列，应为 ${bannerWidth} 列`)
-      continue
-    }
     if (trimmed.startsWith('///') || (trimmed.startsWith('//') && !trimmed.startsWith('//!'))) {
       if (displayWidth(trimmed) > width) add(index + 1, 'comment-width', `注释行 ${displayWidth(trimmed)} 列，超过 ${width} 列`)
       for (const tag of FORBIDDEN_TAGS) {
@@ -453,7 +439,6 @@ function main(argv) {
   const columnLimit = readColumnLimit(root)
   if (columnLimit !== undefined) {
     if (!options.widthExplicit) options.width = columnLimit
-    if (!options.bannerWidthExplicit) options.bannerWidth = columnLimit
   }
   let files
   try {

package/skills/developing-cpp/steps/03-declaration.md

@@ -24,7 +24,7 @@
 
 **异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `std::out_of_range`」这样的具体类型，不要只写「可能抛异常」，也不要给每个参数错误都新建类型。类型选择见 `references/exceptions.md`。
 
-**注释**：声明注释用 `///` 写中文散文，只写调用方需要知道的；实现细节留给 `.cpp`。`@param`、`@return`、`@throws` 要么全写要么全不写，标识符和标签保持英文。文件头默认写 `@file` 与 `@brief` 两行，`@file` 必须与文件名相同；作者、日期、版权、版本默认不写。标签开关在插件设置页，技能正文末尾附带当前配置的快照。写完运行 `node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>`；关闭 `@brief` 时加 `--no-brief`，配置里打开了隐私标签并填了值时加 `--allow-tag <标签>`。横幅、标签、参数完整性、成员清单与设计论证由脚本兜底。文件头、章节横幅和 TODO 的格式见 `references/comments.md`。
+**注释**：声明注释用 `///` 写中文散文，只写调用方需要知道的；实现细节留给 `.cpp`。`@param`、`@return`、`@throws` 要么全写要么全不写，标识符和标签保持英文。文件头默认写 `@file` 与 `@brief` 两行，`@file` 必须与文件名相同；作者、日期、版权、版本默认不写。标签开关在插件设置页，技能正文末尾附带当前配置的快照。写完运行 `node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>`；关闭 `@brief` 时加 `--no-brief`，配置里打开了隐私标签并填了值时加 `--allow-tag <标签>`。文件头、标签、参数完整性、成员清单与设计论证由脚本兜底。文件头与 TODO 的格式见 `references/comments.md`。
 
 ## 正反例指针
 

package/skills/developing-cpp/steps/04-implementation.md

@@ -9,7 +9,7 @@
 - 函数保持短小；一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不要用注释把长函数切成几段。
 - 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段，不用大段叙述。
 - `.cpp` 的第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。包含顺序见 `references/google-cpp-style.md`；文件槽位见 `references/file-template.md`。
-- `.cpp` / `.cc` 里，重要函数按空行分阶段，每个阶段上方写一句 `//`：写边界、失败后果或为什么停在这里，不把下一行的条件翻译一遍。`IsWin` 这种单行函数不配注释；只写删掉会让下一次修改得到错误结果、而代码本身看不出的内容，变更史留给提交说明。
+- `.cpp` / `.cc` 里，重要函数按空行分阶段，每个阶段上方写一句 `///`：写边界、失败后果或为什么停在这里，不把下一行的条件翻译一遍。`IsWin` 这种单行函数不配注释；只写删掉会让下一次修改得到错误结果、而代码本身看不出的内容，变更史留给提交说明。
 - 错误处理：失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。Debug 与 Release 用同一套返回值与抛出条件，只有诊断详略不同。两种模式都要守的 invariant 用 `Check`（项目保留时），只在开发期做的自检用 `DebugCheck`；没有这两个宏就分别用 `assert` 与 `std::terminate`。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。消息按 `Type::Function: 条件 (值); 限度` 组织，见 `references/exceptions.md` 的「消息」节。
 - 声明 `noexcept` 前核对函数体：出现 `at()` 或其他可能抛出的调用就去掉。越界用 `at()` 抛 `std::out_of_range`，这个函数就不能标 `noexcept`。
 - 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。