@chengzhao-dev/dsh-cpp-workflow 0.6.8 → 0.6.10

package/README.en.md

@@ -19,20 +19,20 @@ 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.8
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.10
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.8
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.10
 ```
 
 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.
 
 ### Settings
 
-The plugin page's "C++ Workflow" card is the only entry point and manages file-header tags only: `@file` is always the file name, `@brief` is written by default, and `@author`, `@date`, `@copyright`, `@version` stay off and are written only when they hold a non-empty value; `@param` is required for every parameter; `@return` is written by default but may be omitted when the condition is self-evident; `@throws` only when the function throws. The preview follows the switches, saving takes effect on the next skill read, and existing sources are never rewritten. Settings navigation no longer duplicates the form.
+The plugin page's "C++ Workflow" card is the only entry point and manages file-header tags only: `@file` is always the file name, and every file-header, type, and declaration tag is on by default except the fixed `//` body symbol; empty values are skipped. `@param` is required for every parameter; `@return` may be omitted when the condition is self-evident; `@throws` only when the function throws; `@pre`, `@post`, `@retval`, `@tparam`, `@note`, and `@see` are on by default and can be switched off individually. The preview follows the switches, saving takes effect on the next skill read, and existing sources are never rewritten. Settings navigation no longer duplicates the form.
 
 If the page still reports that it is not connected to a configuration form after an upgrade, the window is still running the previous client bundle: restart DeepSeek Harness or select "Reload page" on the plugin page. The page retries the connection while open and switches to the editable form as soon as the host serves it; reinstalling is unnecessary. Discard changes, Restore defaults and Save are separate: discard returns to the last value read from the host, restore fills the draft, and only Save writes it.
 

package/README.md

@@ -19,20 +19,20 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.8
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.10
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.8
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.10
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
 
 ### 设置
 
-插件页的「C++ 工程流程」是唯一入口：注释符号可选 `///` 或 `/** ... */`，页面按注释符号、文件头、类型、函数声明与只读预览分块。`@file` 固定为文件名；`@brief` 默认开启；`@author`、`@date`、`@copyright`、`@version` 默认关闭，空值跳过。函数参数默认要求 `@param`，返回值默认要求 `@return`（成立条件自明时可省），会抛才要求 `@throws`；`@pre`、`@post`、`@retval` 与类型块的 `@tparam`、`@note`、`@see` 默认关闭。函数体固定用 `//`。预览随改动即时更新，保存后下一次读取技能即生效，已有源码不会被改写。设置导航不再重复放一份。
+插件页的「C++ 工程流程」是唯一入口：注释符号可选 `///` 或 `/** ... */`，页面按注释符号、文件头、类型、函数声明与只读预览分块。`@file` 固定为文件名；除它和函数体 `//` 外，文件头、类型与函数声明标签的开关出厂全开，空值跳过。函数参数要求 `@param`，返回值要求 `@return`（成立条件自明时可省），会抛才要求 `@throws`；`@pre`、`@post`、`@retval` 与类型块的 `@tparam`、`@note`、`@see` 也出厂开启，需要时可逐项关掉。函数体固定用 `//`。预览随改动即时更新，保存后下一次读取技能即生效，已有源码不会被改写。设置导航不再重复放一份。
 
 升级插件后如果这一页暂时只显示出厂值，说明当前窗口还挂着旧的前端产物：页脚会显示写入的 `~/.dsh/profiles/<profile>/cordis.patch.yml`，并提示重载；重启 DeepSeek Harness，或在插件页点“重新载入页面”即可编辑，不需要重装插件。页面会在打开后自动重试连接，拿到表单就切换为可编辑。保存、撤销修改与恢复默认值分三个按钮：撤销只回到最近一次读到的值，恢复默认值只填草稿，点保存才写盘。
 

package/lib/client.js

@@ -19,9 +19,9 @@ window.__ModuleLoader__.load({
 const HEADER_TAGS = ['brief', 'author', 'date', 'copyright', 'version'];
 /** 函数声明标签：开关决定是否要求写出。 */
 const CONTRACT_TAGS = ['param', 'returns', 'throws'];
-/** 函数声明里默认关闭的补充标签。 */
+/** 函数声明里出厂开启的补充标签。 */
 const FUNCTION_EXTRA_TAGS = ['pre', 'post', 'retval'];
-/** 类型标签：默认关闭，函数模板共用同一组键。 */
+/** 类型标签：出厂开启，函数模板共用同一组键。 */
 const TYPE_TAGS = ['tparam', 'note', 'see'];
 /** 全部可选标签，快照与测试按它排序。 */
 const EXTRA_TAGS = ['note', 'see', 'pre', 'post', 'tparam', 'retval'];
@@ -49,23 +49,25 @@ const TAG_LABEL = {
 const SAMPLE_BRIEF = '<一句话说明本文件>';
 /** 预览里的示例文件名：只是占位符，不对应任何工程的真实文件。 */
 const SAMPLE_FILE = '<文件名>';
-/** 出厂配置：声明用 `///`，文件头只留 @file 与 @brief，契约标签全开，其余关闭。 */
+/**
+ * 出厂配置：声明用 `///`，除 @file 与函数体 // 外全部开启；空值仍不写文件头。
+ */
 const DEFAULT_CONFIG = {
     commentStyle: 'slash',
     brief: { enabled: true, value: '' },
-    author: { enabled: false, value: '' },
-    date: { enabled: false, value: '' },
-    copyright: { enabled: false, value: '' },
-    version: { enabled: false, value: '' },
+    author: { enabled: true, value: '' },
+    date: { enabled: true, value: '' },
+    copyright: { enabled: true, value: '' },
+    version: { enabled: true, value: '' },
     param: true,
     returns: true,
     throws: true,
-    note: false,
-    see: false,
-    pre: false,
-    post: false,
-    tparam: false,
-    retval: false,
+    note: true,
+    see: true,
+    pre: true,
+    post: true,
+    tparam: true,
+    retval: true,
 };
 /**
  * 宿主把 volatile 字段交给插件时给的是可读写单元（`.get()`），设置页快照给的是普通值；
@@ -236,28 +238,36 @@ const STRINGS = {
   zh: {
     nav: 'C++ 工程流程',
     heading: '文档注释',
+    lede: '文件头、类型与函数声明各自决定默认写入哪些标签；预览随改动即时更新。',
     style: '注释符号',
+    styleHint: '声明用哪种注释；函数体始终用 //。',
     bodyRow: '函数体',
-    bodyPlaceholder: '函数体：固定 //',
+    bodyPlaceholder: '固定 //',
     header: '文件头',
+    headerHint: '开关打开后填写内容；空值不会写进文件。',
     type: '类型',
+    typeHint: '类型块与函数模板里的补充标签。',
     declaration: '函数声明',
+    declarationHint: '函数契约与前置、后置条件。',
     preview: '预览',
+    previewHint: '代码块随开关和输入即时更新。',
     filePlaceholder: '跟随文件名',
     briefPlaceholder: '文件摘要：留空则各文件自写',
-    authorPlaceholder: '作者署名：默认不写',
-    datePlaceholder: '日期：默认不写',
-    copyrightPlaceholder: '版权：默认不写',
-    versionPlaceholder: '版本：默认不写',
-    paramPlaceholder: '参数：默认使用',
-    returnPlaceholder: '返回值：默认使用',
-    throwsPlaceholder: '异常：默认使用',
-    prePlaceholder: '前置条件：默认不使用',
-    postPlaceholder: '后置条件：默认不使用',
-    retvalPlaceholder: '返回值枚举：默认不使用',
-    tparamPlaceholder: '模板参数：默认不使用',
-    notePlaceholder: '补充：默认不使用',
-    seePlaceholder: '参见：默认不使用',
+    authorPlaceholder: '作者署名',
+    datePlaceholder: '日期',
+    copyrightPlaceholder: '版权',
+    versionPlaceholder: '版本',
+    paramPlaceholder: '逐项说明参数',
+    returnPlaceholder: '说明返回值',
+    throwsPlaceholder: '列出可能抛出的异常',
+    prePlaceholder: '前置条件',
+    postPlaceholder: '后置条件',
+    retvalPlaceholder: '按枚举值说明返回值',
+    tparamPlaceholder: '说明模板参数',
+    notePlaceholder: '补充说明',
+    seePlaceholder: '相关接口',
+    styleSlashExample: '/// @brief 定义棋盘。',
+    styleBlockExample: '/** @brief 定义棋盘。 */',
     save: '保存',
     reset: '撤销修改',
     defaults: '恢复默认值',
@@ -275,28 +285,36 @@ const STRINGS = {
   en: {
     nav: 'C++ Workflow',
     heading: 'Doxygen comments',
+    lede: 'The file header, types, and declarations each decide which tags are written by default; the preview updates as you edit.',
     style: 'Comment symbol',
+    styleHint: 'Symbol for declarations; function bodies always use //.',
     bodyRow: 'Body',
-    bodyPlaceholder: 'Function bodies: always //',
+    bodyPlaceholder: 'Always //',
     header: 'File header',
+    headerHint: 'Turn a tag on, then fill in its value; empty values are not written.',
     type: 'Types',
+    typeHint: 'Extra tags for type blocks and function templates.',
     declaration: 'Function declarations',
+    declarationHint: 'Function contracts plus pre- and postconditions.',
     preview: 'Preview',
+    previewHint: 'The code block updates as you toggle switches and type.',
     filePlaceholder: 'Follows the file name',
     briefPlaceholder: 'File summary: leave empty for each file',
-    authorPlaceholder: 'Author: off by default',
-    datePlaceholder: 'Date: off by default',
-    copyrightPlaceholder: 'Copyright: off by default',
-    versionPlaceholder: 'Version: off by default',
-    paramPlaceholder: 'Parameters: on by default',
-    returnPlaceholder: 'Return value: on by default',
-    throwsPlaceholder: 'Exceptions: on by default',
-    prePlaceholder: 'Preconditions: off by default',
-    postPlaceholder: 'Postconditions: off by default',
-    retvalPlaceholder: 'Named return values: off by default',
-    tparamPlaceholder: 'Template parameters: off by default',
-    notePlaceholder: 'Notes: off by default',
-    seePlaceholder: 'See also: off by default',
+    authorPlaceholder: 'Author',
+    datePlaceholder: 'Date',
+    copyrightPlaceholder: 'Copyright',
+    versionPlaceholder: 'Version',
+    paramPlaceholder: 'Describe each parameter',
+    returnPlaceholder: 'Describe the return value',
+    throwsPlaceholder: 'List exceptions that may be thrown',
+    prePlaceholder: 'Precondition',
+    postPlaceholder: 'Postcondition',
+    retvalPlaceholder: 'Describe a named return value',
+    tparamPlaceholder: 'Describe template parameters',
+    notePlaceholder: 'Additional notes',
+    seePlaceholder: 'Related interfaces',
+    styleSlashExample: '/// @brief Defines the board.',
+    styleBlockExample: '/** @brief Defines the board. */',
     save: 'Save',
     reset: 'Discard changes',
     defaults: 'Restore defaults',
@@ -326,68 +344,65 @@ const STYLE_ID = 'dsh-cpp-workflow-settings'
 
 // 外观只用宿主变量与两档中性色；没有变量时回落到浅色主题的一组合法颜色。
 const CSS = `
-.dcw-page{--dcw-fg:var(--dsw-alias-label-primary,#1f2328);--dcw-muted:var(--dsw-alias-label-secondary,#69707d);--dcw-faint:var(--dsw-alias-label-tertiary,#8a919c);--dcw-border:var(--dsw-alias-border-l2,rgba(31,35,40,.14));--dcw-bg1:var(--dsw-alias-bg-layer-1,#fff);--dcw-bg2:var(--dsw-alias-bg-layer-2,rgba(31,35,40,.035));--dcw-accent:var(--dsw-alias-brand-primary,#2f6fed);--dcw-danger:var(--dsw-alias-state-error-primary,#c0392b);color:var(--dcw-fg);max-width:760px;padding:2px 0 12px;font-size:13px;line-height:1.6}
-.dcw-head{margin:0 0 14px}
-.dcw-eyebrow{margin:0 0 4px;color:var(--dcw-muted);font-size:11.5px;letter-spacing:.02em}
-.dcw-title{margin:0 0 6px;font-size:16px;font-weight:620;letter-spacing:.005em}
-.dcw-lede{margin:0;color:var(--dcw-muted);font-size:12.5px;line-height:1.65;max-width:64ch}
+.dcw-page{--dcw-fg:var(--dsw-alias-label-primary,#1f2328);--dcw-muted:var(--dsw-alias-label-secondary,#69707d);--dcw-faint:var(--dsw-alias-label-tertiary,#8a919c);--dcw-border:var(--dsw-alias-border-l2,rgba(31,35,40,.14));--dcw-bg1:var(--dsw-alias-bg-layer-1,#fff);--dcw-bg2:var(--dsw-alias-bg-layer-2,rgba(31,35,40,.035));--dcw-accent:var(--dsw-alias-brand-primary,#2f6fed);--dcw-danger:var(--dsw-alias-state-error-primary,#c0392b);--dcw-success:var(--dsw-alias-state-success-primary,#1a7f37);color:var(--dcw-fg);max-width:760px;padding:2px 0 12px;font-size:13px;line-height:1.6}
+.dcw-head{margin:0 0 16px}
+.dcw-title{margin:0 0 6px;font-size:17px;font-weight:620;letter-spacing:.005em}
+.dcw-lede{margin:0;color:var(--dcw-muted);font-size:12.5px;line-height:1.65;max-width:66ch}
 .dcw-note{display:flex;gap:8px;align-items:center;margin:12px 0 0;padding:9px 11px;border:1px solid var(--dcw-border);border-radius:8px;background:var(--dcw-bg2);color:var(--dcw-muted);font-size:12px;line-height:1.55}
 .dcw-note[data-tone="warn"]{color:var(--dcw-danger);border-color:color-mix(in srgb,var(--dcw-danger) 35%,transparent)}
 .dcw-note-dot{flex:none;width:6px;height:6px;border-radius:50%;background:currentColor;opacity:.55}
-.dcw-card{margin:14px 0 0;border:1px solid var(--dcw-border);border-radius:10px;background:var(--dcw-bg1);overflow:hidden}
-.dcw-card-head{display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 10px;padding:11px 14px 9px;border-bottom:1px solid var(--dcw-border);background:var(--dcw-bg2)}
-.dcw-card-title{margin:0;font-size:12.5px;font-weight:620;letter-spacing:.01em}
-.dcw-card-hint{margin:0;color:var(--dcw-muted);font-size:11.5px;line-height:1.5}
-.dcw-row{display:grid;grid-template-columns:84px 40px minmax(0,1fr);align-items:center;gap:8px 12px;padding:8px 14px;border-top:1px solid var(--dcw-border)}
-.dcw-row:first-of-type{border-top:0}
-.dcw-row-label{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;color:var(--dcw-fg)}
-.dcw-row-style{grid-template-columns:84px minmax(0,1fr)}
-.dcw-row-style .dcw-segmented{grid-column:2}
-.dcw-lock{display:inline-flex;align-items:center;justify-content:center;width:26px;height:26px;border:1px dashed var(--dcw-border);border-radius:6px;background:var(--dcw-bg2);color:var(--dcw-muted)}
-.dcw-segmented{display:inline-flex;padding:2px;border:1px solid var(--dcw-border);border-radius:8px;background:var(--dcw-bg2);justify-self:start}
-.dcw-segment{height:26px;padding:0 12px;border:0;border-radius:6px;background:transparent;color:var(--dcw-muted);font:inherit;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;cursor:pointer}
-.dcw-segment:hover:enabled{color:var(--dcw-fg)}
-.dcw-segment[aria-pressed="true"]{background:var(--dcw-bg1);color:var(--dcw-fg);box-shadow:0 1px 2px rgba(0,0,0,.12)}
-.dcw-segment:focus-visible{outline:2px solid var(--dcw-accent);outline-offset:1px}
-.dcw-segment:disabled{opacity:.45;cursor:default}
-.dcw-switch{position:relative;display:inline-flex;align-items:center;flex:none;width:34px;height:20px;cursor:pointer}
+.dcw-note-code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px;opacity:.8;margin-left:6px}
+.dcw-note-action{margin-left:auto;flex:none;padding:3px 10px;border:1px solid currentColor;border-radius:6px;background:transparent;color:inherit;font:inherit;font-size:11.5px;cursor:pointer;white-space:nowrap}
+.dcw-note-action:hover{background:var(--dcw-bg1)}
+.dcw-card{margin:14px 0 0;border:1px solid var(--dcw-border);border-radius:12px;background:var(--dcw-bg1);overflow:hidden}
+.dcw-card-head{padding:12px 16px 10px;border-bottom:1px solid var(--dcw-border);background:var(--dcw-bg2)}
+.dcw-card-title{margin:0;font-size:13px;font-weight:620;letter-spacing:.01em}
+.dcw-card-hint{margin:2px 0 0;color:var(--dcw-muted);font-size:11.5px;line-height:1.5}
+.dcw-card-body{padding:0}
+.dcw-row{display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:center;gap:2px 14px;min-height:48px;padding:10px 16px;border-top:1px solid var(--dcw-border)}
+.dcw-card-body>.dcw-row:first-child{border-top:0}
+.dcw-row-main{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dcw-row-label{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12.5px;color:var(--dcw-fg)}
+.dcw-row-hint{color:var(--dcw-muted);font-size:11.5px;line-height:1.5}
+.dcw-row-value .dcw-input{grid-column:1/-1;margin-top:8px}
+.dcw-fixed-value{color:var(--dcw-muted);font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12.5px;white-space:nowrap}
+.dcw-row-flag,.dcw-row-value{cursor:pointer}
+.dcw-style-options{display:grid;grid-template-columns:1fr 1fr;gap:10px;padding:14px 16px}
+.dcw-style-option{display:flex;flex-direction:column;align-items:flex-start;gap:6px;padding:12px 14px;border:1px solid var(--dcw-border);border-radius:10px;background:var(--dcw-bg1);color:var(--dcw-fg);font:inherit;text-align:left;cursor:pointer}
+.dcw-style-option:hover:enabled{border-color:color-mix(in srgb,var(--dcw-fg) 30%,transparent)}
+.dcw-style-option[aria-checked="true"]{border-color:var(--dcw-accent);background:color-mix(in srgb,var(--dcw-accent) 7%,var(--dcw-bg1));box-shadow:inset 0 0 0 1px var(--dcw-accent)}
+.dcw-style-option:focus-visible{outline:2px solid var(--dcw-accent);outline-offset:2px}
+.dcw-style-option:disabled{opacity:.5;cursor:default}
+.dcw-style-symbol{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:13px;font-weight:620}
+.dcw-style-example{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px;line-height:1.55;color:var(--dcw-muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:100%}
+.dcw-switch{position:relative;display:inline-flex;align-items:center;flex:none;width:40px;height:22px;cursor:pointer}
 .dcw-switch input{position:absolute;inset:0;margin:0;opacity:0;cursor:pointer}
-.dcw-track{position:absolute;inset:0;border-radius:999px;background:color-mix(in srgb,var(--dcw-fg) 18%,transparent);transition:background .16s ease}
-.dcw-knob{position:absolute;top:2px;left:2px;width:16px;height:16px;border-radius:50%;background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.25);transition:transform .16s ease}
+.dcw-track{position:absolute;inset:0;border-radius:999px;background:color-mix(in srgb,var(--dcw-fg) 20%,transparent);transition:background .16s ease}
+.dcw-knob{position:absolute;top:2px;left:2px;width:18px;height:18px;border-radius:50%;background:var(--dsw-alias-bg-layer-1,#fff);box-shadow:0 1px 2px rgba(0,0,0,.28);transition:transform .16s ease}
 .dcw-switch input:checked + .dcw-track{background:var(--dcw-accent)}
-.dcw-switch input:checked + .dcw-track .dcw-knob{transform:translateX(14px)}
+.dcw-switch input:checked + .dcw-track .dcw-knob{transform:translateX(18px)}
 .dcw-switch input:focus-visible + .dcw-track{outline:2px solid var(--dcw-accent);outline-offset:2px}
 .dcw-switch input:disabled + .dcw-track{opacity:.4}
 .dcw-switch input:disabled{cursor:default}
-.dcw-state{color:var(--dcw-faint);font-size:11.5px;min-width:28px}
-.dcw-input{flex:1 1 220px;min-width:0;height:28px;padding:0 9px;border:1px solid var(--dcw-border);border-radius:6px;background:transparent;color:var(--dcw-fg);font:inherit;font-size:12.5px}
+.dcw-input{width:100%;min-width:0;height:36px;padding:0 11px;border:1px solid var(--dcw-border);border-radius:8px;background:var(--dcw-bg1);color:var(--dcw-fg);font:inherit;font-size:12.5px}
 .dcw-input::placeholder{color:var(--dcw-faint)}
-.dcw-input:focus{outline:none;border-color:var(--dcw-accent);box-shadow:0 0 0 3px color-mix(in srgb,var(--dcw-accent) 18%,transparent)}
-.dcw-input:disabled{background:var(--dcw-bg2);color:var(--dcw-faint)}
-.dcw-flags{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:0 16px;padding:4px 14px 8px}
-.dcw-flag{display:flex;flex-direction:column;gap:3px;padding:7px 0}
-.dcw-flag .dcw-row-label{padding-top:0;display:flex;align-items:center;gap:8px;justify-content:space-between}
-.dcw-card>summary{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:11px 14px;cursor:pointer;list-style:none}
-.dcw-card details>summary::-webkit-details-marker{display:none}
-.dcw-card details>summary::marker{content:''}
-.dcw-card>summary:hover{background:var(--dcw-bg2)}
-.dcw-chevron{transition:transform .16s ease;color:var(--dcw-muted)}
-.dcw-card[open] .dcw-chevron{transform:rotate(90deg)}
-.dcw-preview{margin:0;padding:11px 14px 13px;border-top:1px solid var(--dcw-border);overflow-x:auto;background:var(--dcw-bg2);font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;line-height:1.7;white-space:pre;color:var(--dcw-fg)}
-.dcw-actions{display:flex;flex-wrap:wrap;align-items:center;gap:10px;margin-top:14px;padding:11px 2px 4px;border-top:1px solid var(--dcw-border)}
-.dcw-btn{height:30px;padding:0 13px;border:1px solid var(--dcw-border);border-radius:7px;background:var(--dcw-bg1);color:var(--dcw-fg);font:inherit;font-size:12.5px;cursor:pointer}
+.dcw-input:focus{outline:none;border-color:var(--dcw-accent);box-shadow:0 0 0 3px color-mix(in srgb,var(--dcw-accent) 16%,transparent)}
+.dcw-input:disabled{opacity:.55}
+.dcw-preview{margin:0;border-top:1px solid var(--dcw-border)}
+.dcw-preview-head{display:flex;align-items:center;gap:7px;padding:8px 14px;border-bottom:1px solid var(--dcw-border);background:var(--dcw-bg2);color:var(--dcw-muted);font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11.5px}
+.dcw-preview-dot{width:6px;height:6px;border-radius:50%;background:var(--dcw-faint)}
+.dcw-preview-body{margin:0;padding:12px 14px 14px;overflow-x:auto;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;line-height:1.7;white-space:pre;color:var(--dcw-fg)}
+.dcw-actions{display:flex;flex-wrap:wrap;align-items:center;gap:10px;margin-top:16px;padding:12px 0 4px;border-top:1px solid var(--dcw-border)}
+.dcw-btn{height:32px;padding:0 14px;border:1px solid var(--dcw-border);border-radius:8px;background:var(--dcw-bg1);color:var(--dcw-fg);font:inherit;font-size:12.5px;cursor:pointer}
 .dcw-btn:hover:enabled{border-color:color-mix(in srgb,var(--dcw-fg) 32%,transparent)}
 .dcw-btn:focus-visible{outline:2px solid var(--dcw-accent);outline-offset:1px}
 .dcw-btn:disabled{opacity:.45;cursor:default}
 .dcw-btn-primary{background:var(--dcw-accent);border-color:transparent;color:var(--dsw-alias-label-primary-foreground,#fff)}
 .dcw-btn-primary:hover:enabled{filter:brightness(1.06)}
-.dcw-status{flex:1 1 200px;margin:0;color:var(--dcw-muted);font-size:12px}
+.dcw-status{flex:1 1 180px;margin:0;min-height:20px;color:var(--dcw-muted);font-size:12px}
 .dcw-status[data-tone="warn"]{color:var(--dcw-danger)}
-.dcw-status[data-tone="ok"]{color:var(--dsw-alias-state-success-primary,#1a7f37)}
-.dcw-note-code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px;opacity:.8;margin-left:6px}
-.dcw-note-action{margin-left:auto;flex:none;padding:3px 10px;border:1px solid currentColor;border-radius:6px;background:transparent;color:inherit;font:inherit;font-size:11.5px;cursor:pointer;white-space:nowrap}
-.dcw-note-action:hover{background:var(--dcw-bg1)}
-@media (max-width:640px){.dcw-row,.dcw-row-style{grid-template-columns:1fr 40px}.dcw-row-label{grid-column:1/-1}.dcw-row-style .dcw-segmented{grid-column:1/-1}}
+.dcw-status[data-tone="ok"]{color:var(--dcw-success)}
+@media (max-width:520px){.dcw-style-options{grid-template-columns:1fr}.dcw-row{grid-template-columns:minmax(0,1fr) auto}.dcw-row-value .dcw-input{grid-column:1/-1}}
 `
 
 function ensureStyles() {
@@ -401,7 +416,7 @@ function ensureStyles() {
 
 function Switch(props) {
   return h(
-    'span',
+    'label',
     { className: 'dcw-switch' },
     h('input', {
       type: 'checkbox',
@@ -414,131 +429,123 @@ function Switch(props) {
   )
 }
 
-function LockIcon() {
-  return h(
-    'svg',
-    { width: 12, height: 12, viewBox: '0 0 16 16', 'aria-hidden': 'true', focusable: 'false' },
-    h('path', {
-      fill: 'currentColor',
-      d: 'M8 1a3 3 0 0 0-3 3v2H4.5A1.5 1.5 0 0 0 3 7.5v5A1.5 1.5 0 0 0 4.5 14h7a1.5 1.5 0 0 0 1.5-1.5v-5A1.5 1.5 0 0 0 11.5 6H11V4a3 3 0 0 0-3-3Zm2 5H6V4a2 2 0 1 1 4 0v2Z',
-    }),
-  )
-}
-
-function Chevron() {
-  return h(
-    'svg',
-    { className: 'dcw-chevron', width: 12, height: 12, viewBox: '0 0 16 16', 'aria-hidden': 'true', focusable: 'false' },
-    h('path', { fill: 'currentColor', d: 'M6 3.5 10.5 8 6 12.5 4.9 11.4 8.3 8 4.9 4.6Z' }),
-  )
-}
-
-/** 五个区块统一用默认展开的 details，标题在摘要行。 */
+/** 设置页的分组卡片：标题下一句说明，正文按行排控件。 */
 function Section(props) {
   return h(
-    'details',
-    { className: 'dcw-card', open: true },
-    h('summary', null, h('span', { className: 'dcw-card-title' }, props.title), h(Chevron)),
-    props.children,
+    'section',
+    { className: 'dcw-card' },
+    h(
+      'div',
+      { className: 'dcw-card-head' },
+      h('h4', { className: 'dcw-card-title' }, props.title),
+      props.hint ? h('p', { className: 'dcw-card-hint' }, props.hint) : null,
+    ),
+    h('div', { className: 'dcw-card-body' }, props.children),
   )
 }
 
-/** 文件头可填写的一行：标签、开关、文本框。 */
+/** 文件头可填写的一行：标题与开关一行，输入框整行在下；关闭时收起输入框。 */
 function ValueRow(props) {
   const entry = props.entry
   return h(
     'div',
-    { className: 'dcw-row' },
-    h('div', { className: 'dcw-row-label' }, TAG_LABEL[props.tag]),
+    {
+      className: 'dcw-row dcw-row-value',
+      onClick: (event) => {
+        if (props.disabled) return
+        if (event.target.closest('.dcw-switch, .dcw-input')) return
+        props.onChange({ ...entry, enabled: !entry.enabled })
+      },
+    },
+    h(
+      'div',
+      { className: 'dcw-row-main' },
+      h('span', { className: 'dcw-row-label' }, TAG_LABEL[props.tag]),
+    ),
     h(Switch, {
       label: TAG_LABEL[props.tag],
       checked: entry.enabled,
       disabled: props.disabled,
       onChange: (enabled) => props.onChange({ ...entry, enabled }),
     }),
-    h('input', {
-      className: 'dcw-input',
-      type: 'text',
-      value: entry.value,
-      placeholder: props.placeholder,
-      disabled: props.disabled || !entry.enabled,
-      'aria-label': `${TAG_LABEL[props.tag]} 的值`,
-      onChange: (event) => props.onChange({ ...entry, value: event.target.value }),
-    }),
+    entry.enabled
+      ? h('input', {
+          className: 'dcw-input',
+          type: 'text',
+          value: entry.value,
+          placeholder: props.placeholder,
+          disabled: props.disabled,
+          'aria-label': `${TAG_LABEL[props.tag]} 的值`,
+          onChange: (event) => props.onChange({ ...entry, value: event.target.value }),
+        })
+      : null,
   )
 }
 
-/** 只有开关的标签行；右侧框显示该标签的作用，不进入配置。 */
+/** 只有开关的标签行；说明放在标题下面，不再放一个不可用的假输入框。 */
 function FlagRow(props) {
   return h(
     'div',
-    { className: 'dcw-row' },
-    h('div', { className: 'dcw-row-label' }, TAG_LABEL[props.tag]),
+    {
+      className: 'dcw-row dcw-row-flag',
+      onClick: (event) => {
+        if (props.disabled) return
+        if (event.target.closest('.dcw-switch, .dcw-input')) return
+        props.onChange(!props.checked)
+      },
+    },
+    h(
+      'div',
+      { className: 'dcw-row-main' },
+      h('span', { className: 'dcw-row-label' }, TAG_LABEL[props.tag]),
+      props.hint ? h('span', { className: 'dcw-row-hint' }, props.hint) : null,
+    ),
     h(Switch, {
       label: TAG_LABEL[props.tag],
       checked: props.checked,
       disabled: props.disabled,
       onChange: props.onChange,
     }),
-    h('input', {
-      className: 'dcw-input',
-      type: 'text',
-      value: '',
-      placeholder: props.placeholder,
-      disabled: true,
-      readOnly: true,
-      tabIndex: -1,
-      'aria-label': props.placeholder,
-    }),
   )
 }
 
-/** 值由文件或语法固定的行：中间锁，右侧框给出固定值。 */
+/** 值由文件或语法固定的行：右侧写成普通文本，不放锁图标。 */
 function LockRow(props) {
   return h(
     'div',
-    { className: 'dcw-row dcw-row-lock' },
-    h('div', { className: 'dcw-row-label' }, props.label),
-    h('span', { className: 'dcw-lock', title: props.placeholder }, h(LockIcon)),
-    h('input', {
-      className: 'dcw-input',
-      type: 'text',
-      value: '',
-      placeholder: props.placeholder,
-      disabled: true,
-      readOnly: true,
-      tabIndex: -1,
-      'aria-label': props.placeholder,
-    }),
+    { className: 'dcw-row dcw-row-fixed' },
+    h(
+      'div',
+      { className: 'dcw-row-main' },
+      h('span', { className: 'dcw-row-label' }, props.label),
+    ),
+    h('span', { className: 'dcw-fixed-value' }, props.value),
   )
 }
 
-/** 两种声明注释符号；按钮本身可用键盘切换。 */
+/** 两种声明注释符号：两张等宽卡片，上面符号、下面示例。 */
 function StyleRow(props) {
   const options = [
-    { value: 'slash', label: '///' },
-    { value: 'block', label: '/** */' },
+    { value: 'slash', symbol: '///', example: props.slashExample },
+    { value: 'block', symbol: '/** */', example: props.blockExample },
   ]
   return h(
     'div',
-    { className: 'dcw-row dcw-row-style' },
-    h('div', { className: 'dcw-row-label' }, props.label),
-    h(
-      'div',
-      { className: 'dcw-segmented', role: 'group', 'aria-label': props.label },
-      options.map((option) =>
-        h(
-          'button',
-          {
-            key: option.value,
-            type: 'button',
-            className: 'dcw-segment',
-            'aria-pressed': props.value === option.value ? 'true' : 'false',
-            disabled: props.disabled,
-            onClick: () => props.onChange(option.value),
-          },
-          option.label,
-        ),
+    { className: 'dcw-style-options', role: 'radiogroup', 'aria-label': props.label },
+    options.map((option) =>
+      h(
+        'button',
+        {
+          key: option.value,
+          type: 'button',
+          role: 'radio',
+          'aria-checked': props.value === option.value ? 'true' : 'false',
+          className: 'dcw-style-option',
+          disabled: props.disabled,
+          onClick: () => props.onChange(option.value),
+        },
+        h('span', { className: 'dcw-style-symbol' }, option.symbol),
+        h('span', { className: 'dcw-style-example' }, option.example),
       ),
     ),
   )
@@ -548,8 +555,13 @@ function Preview(props) {
   const s = props.strings
   return h(
     Section,
-    { title: s.preview },
-    h('pre', { className: 'dcw-preview' }, previewText(props.config, SAMPLE_FILE)),
+    { title: s.preview, hint: s.previewHint },
+    h(
+      'div',
+      { className: 'dcw-preview' },
+      h('div', { className: 'dcw-preview-head' }, h('span', { className: 'dcw-preview-dot' }), SAMPLE_FILE),
+      h('pre', { className: 'dcw-preview-body' }, previewText(props.config, SAMPLE_FILE)),
+    ),
   )
 }
 
@@ -661,9 +673,11 @@ function ConfigPage(props) {
     return () => clearTimeout(timer)
   }, [form, attempt])
 
+  // 脏标记按与已保存值的差集算：把开关关了又开回原值时，页面不该再说“有未保存的改动”。
   const update = (patch) => {
-    setDraft((current) => ({ ...current, ...patch }))
-    setDirty(true)
+    const next = { ...draft, ...patch }
+    setDraft(next)
+    setDirty(diffOperations(next, base).length > 0)
     setMessage('')
     setTone('')
   }
@@ -678,8 +692,9 @@ function ConfigPage(props) {
 
   // 恢复默认值：只填进草稿，点“保存”后才写盘，避免误触直接覆盖已保存的配置。
   const restoreDefaults = () => {
-    setDraft(normalizeConfig(DEFAULT_CONFIG))
-    setDirty(true)
+    const next = normalizeConfig(DEFAULT_CONFIG)
+    setDraft(next)
+    setDirty(diffOperations(next, base).length > 0)
     setMessage(s.restored)
     setTone('')
   }
@@ -720,21 +735,26 @@ function ConfigPage(props) {
   const editable = Boolean(form)
   const disabled = !ready
 
-  /** 一个标签一行：中间开关，右侧框给默认值或占位说明。 */
+  /** 一个标签一行：标题与说明，右侧开关。 */
   const flag = (tag, checked) =>
     h(FlagRow, {
       key: tag,
       tag,
       checked,
       disabled,
-      placeholder: s[FLAG_PLACEHOLDER[tag]],
+      hint: s[FLAG_PLACEHOLDER[tag]],
       onChange: (value) => update({ [tag]: value }),
     })
 
   return h(
     'div',
     { className: 'dcw-page' },
-    h('header', { className: 'dcw-head' }, h('h3', { className: 'dcw-title' }, s.heading)),
+    h(
+      'header',
+      { className: 'dcw-head' },
+      h('h3', { className: 'dcw-title' }, s.heading),
+      h('p', { className: 'dcw-lede' }, s.lede),
+    ),
     missing
       ? h(
           'div',
@@ -759,19 +779,21 @@ function ConfigPage(props) {
       : null,
     h(
       Section,
-      { title: s.style },
+      { title: s.style, hint: s.styleHint },
       h(StyleRow, {
         label: s.style,
         value: draft.commentStyle,
         disabled,
+        slashExample: s.styleSlashExample,
+        blockExample: s.styleBlockExample,
         onChange: (value) => update({ commentStyle: value }),
       }),
-      h(LockRow, { label: s.bodyRow, placeholder: s.bodyPlaceholder }),
+      h(LockRow, { label: s.bodyRow, value: s.bodyPlaceholder }),
     ),
     h(
       Section,
-      { title: s.header },
-      h(LockRow, { label: TAG_LABEL.file, placeholder: s.filePlaceholder }),
+      { title: s.header, hint: s.headerHint },
+      h(LockRow, { label: TAG_LABEL.file, value: s.filePlaceholder }),
       ...HEADER_TAGS.map((tag) =>
         h(ValueRow, {
           key: tag,
@@ -783,10 +805,10 @@ function ConfigPage(props) {
         }),
       ),
     ),
-    h(Section, { title: s.type }, ...TYPE_TAGS.map((tag) => flag(tag, draft[tag]))),
+    h(Section, { title: s.type, hint: s.typeHint }, ...TYPE_TAGS.map((tag) => flag(tag, draft[tag]))),
     h(
       Section,
-      { title: s.declaration },
+      { title: s.declaration, hint: s.declarationHint },
       ...[...CONTRACT_TAGS, ...FUNCTION_EXTRA_TAGS].map((tag) => flag(tag, draft[tag])),
     ),
     h(Preview, { config: draft, strings: s }),

package/lib/comment-policy.js

@@ -12,9 +12,9 @@
 export const HEADER_TAGS = ['brief', 'author', 'date', 'copyright', 'version'];
 /** 函数声明标签：开关决定是否要求写出。 */
 export const CONTRACT_TAGS = ['param', 'returns', 'throws'];
-/** 函数声明里默认关闭的补充标签。 */
+/** 函数声明里出厂开启的补充标签。 */
 export const FUNCTION_EXTRA_TAGS = ['pre', 'post', 'retval'];
-/** 类型标签：默认关闭，函数模板共用同一组键。 */
+/** 类型标签：出厂开启，函数模板共用同一组键。 */
 export const TYPE_TAGS = ['tparam', 'note', 'see'];
 /** 全部可选标签，快照与测试按它排序。 */
 export const EXTRA_TAGS = ['note', 'see', 'pre', 'post', 'tparam', 'retval'];
@@ -42,23 +42,25 @@ export const TAG_LABEL = {
 export const SAMPLE_BRIEF = '<一句话说明本文件>';
 /** 预览里的示例文件名：只是占位符，不对应任何工程的真实文件。 */
 export const SAMPLE_FILE = '<文件名>';
-/** 出厂配置：声明用 `///`，文件头只留 @file 与 @brief，契约标签全开，其余关闭。 */
+/**
+ * 出厂配置：声明用 `///`，除 @file 与函数体 // 外全部开启；空值仍不写文件头。
+ */
 export const DEFAULT_CONFIG = {
     commentStyle: 'slash',
     brief: { enabled: true, value: '' },
-    author: { enabled: false, value: '' },
-    date: { enabled: false, value: '' },
-    copyright: { enabled: false, value: '' },
-    version: { enabled: false, value: '' },
+    author: { enabled: true, value: '' },
+    date: { enabled: true, value: '' },
+    copyright: { enabled: true, value: '' },
+    version: { enabled: true, value: '' },
     param: true,
     returns: true,
     throws: true,
-    note: false,
-    see: false,
-    pre: false,
-    post: false,
-    tparam: false,
-    retval: false,
+    note: true,
+    see: true,
+    pre: true,
+    post: true,
+    tparam: true,
+    retval: true,
 };
 /**
  * 宿主把 volatile 字段交给插件时给的是可读写单元（`.get()`），设置页快照给的是普通值；

package/lib/index.js

@@ -27,10 +27,14 @@ import { normalizeConfig, snapshotText } from './comment-policy.js';
 export const name = 'dsh-cpp-workflow';
 export const inject = ['skills'];
 // 设置页保存的标签开关；字段即时生效，改配置不必重装插件。
-const HeaderTag = Schema.object({
-    enabled: Schema.boolean().default(false).volatile(),
-    value: Schema.string().default('').volatile(),
-});
+// 每个文件头标签各建一个对象：四个标签共用一个 Schema 实例时，volatile 叶子会撞在同一条路径上，
+// 保存 @author 会被宿主拒绝或写到别的标签。
+function headerTag() {
+    return Schema.object({
+        enabled: Schema.boolean().default(true).volatile(),
+        value: Schema.string().default('').volatile(),
+    });
+}
 export const Config = Schema.object({
     // 声明注释符号：`///` 或 Doxygen 块注释；缺省值由 comment-policy 兜底。
     commentStyle: Schema.string().default('slash').volatile(),
@@ -38,19 +42,19 @@ export const Config = Schema.object({
         enabled: Schema.boolean().default(true).volatile(),
         value: Schema.string().default('').volatile(),
     }),
-    author: HeaderTag,
-    date: HeaderTag,
-    copyright: HeaderTag,
-    version: HeaderTag,
+    author: headerTag(),
+    date: headerTag(),
+    copyright: headerTag(),
+    version: headerTag(),
     param: Schema.boolean().default(true).volatile(),
     returns: Schema.boolean().default(true).volatile(),
     throws: Schema.boolean().default(true).volatile(),
-    note: Schema.boolean().default(false).volatile(),
-    see: Schema.boolean().default(false).volatile(),
-    pre: Schema.boolean().default(false).volatile(),
-    post: Schema.boolean().default(false).volatile(),
-    tparam: Schema.boolean().default(false).volatile(),
-    retval: Schema.boolean().default(false).volatile(),
+    note: Schema.boolean().default(true).volatile(),
+    see: Schema.boolean().default(true).volatile(),
+    pre: Schema.boolean().default(true).volatile(),
+    post: Schema.boolean().default(true).volatile(),
+    tparam: Schema.boolean().default(true).volatile(),
+    retval: Schema.boolean().default(true).volatile(),
 });
 const PROVIDER = 'dsh-cpp-workflow';
 const RANK = 550;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "写 C++ 源码、配 CMake、用 Clang 构建；头文件用 /// Doxygen 文档注释，函数体用 // 分段说明，文件头标签可在设置里改。",
   "type": "module",
   "main": "./lib/index.js",

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

@@ -32,7 +32,7 @@ class Board {
 - 不写尚未发生的用法、方案对比与取舍论证、广告句。
 - 纯数据结构不写「只保存…，不拥有…，不含…」这类否定式边界；这些由成员类型和所有权表达。
 - 领域尺寸不写进类型注释：格子数由 `cells_` 的声明表达，棋盘边长由 `kBoardRows`、`kBoardCols` 表达。
-- 枚举与只承载数据的结构体：第一句是名词短语，写这个取值表示什么；需要条件时用 `///<` 补一句可核实的条件。
+- 枚举与只承载数据的结构体：第一句是名词短语，写这个取值表示什么；行尾 `///<` 的两种句式见「枚举项与 `struct` 短字段：两种句式」。
 
 ### 构造函数与析构函数：先写标签，再写职责
 
@@ -62,12 +62,21 @@ GameResult result_ = GameResult::kInProgress;
 
 `board_` 这类名字已经说明存放对象的成员不写「对局棋盘」；`cells_` 不写「存储…」这种把声明读一遍的句子，但上一行要先说它是棋盘格子数组，再补轴向、哨兵和改写次序。`clang-format` 不会把行尾注释搬到上一行，位置由本规则和检查器保证。
 
+### 枚举项与 `struct` 短字段：两种句式
+
+枚举项与只承载数据的 `struct` 短字段用行尾 `///<`，同一枚举各行的 `///<` 对齐。只写两种句式：
+
+- 语义本身已经完整：`///< 空格子。`
+- 语义之外还要补一条能核实的条件或结果：`///< 非法参数：传入空棋盘格子类型。`
+
+冒号用全角 `：`；冒号前写类别，冒号后写说明，两侧都不能为空。禁止空冒号（`///< 落子成功：。`）、禁止用逗号把类别和说明连起来（`///< 传入空棋盘格子类型，非法参数。`）、禁止把说明写在类别前面。同一枚举要么每一项都写 `///<`，要么都不写；都写时两种句式可以混用。
+
 ### 函数：两段式契约
 
 有参数或有返回值的函数写两段：第一段写结果、失败方式或检查项；第二段按签名把标签写齐。
 
 1. 第一段：普通函数写正常返回什么、失败时返回什么或抛什么；布尔查询与 `operator==` 写「检查…是否…」。
-2. 第二段：每个参数一条 `@param`；有返回值默认写 `@return`，成立条件已由函数名与返回类型说清时可省略；会抛才写 `@throws`；`@pre`、`@post`、`@retval`、`@tparam`、`@note`、`@see` 默认不写，确有需要时再打开。
+2. 第二段：每个参数一条 `@param`；有返回值默认写 `@return`，成立条件已由函数名与返回类型说清时可省略；会抛才写 `@throws`；`@pre`、`@post`、`@retval`、`@tparam`、`@note`、`@see` 出厂开关打开；只在确有需要时写，不需要可在设置里关掉。
 
 ```cpp
 /// 检查坐标能否落子，不修改棋盘。
@@ -133,7 +142,7 @@ GameResult result_ = GameResult::kInProgress;
 
 ### 文件头
 
-每个手写源文件开头写一段 doxygen 文件头：第一行写 `@file <文件名>`，第二行写 `@brief` 一句话说明这个文件定义或实现什么，用一行空注释隔开后，只写本文件自己的组成部分或边界。`@file` 的参数必须与文件名逐字相同，检查器会核对。`@brief` 默认写出；`@author`、`@date`、`@copyright`、`@version` 默认不写，只有插件配置里打开并填了非空值才写出，作者、年份和变更史不写进源码。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
+每个手写源文件开头写一段 doxygen 文件头：第一行写 `@file <文件名>`，第二行写 `@brief` 一句话说明这个文件定义或实现什么，用一行空注释隔开后，只写本文件自己的组成部分或边界。`@file` 的参数必须与文件名逐字相同，检查器会核对。`@brief` 始终写出；`@author`、`@date`、`@copyright`、`@version` 的开关出厂打开，只有填了非空值才写出，空值整条省略；作者、年份和变更史按团队约定填写，不填就不出现在源码里。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
 
 ```cpp
 /// @file board.h

package/skills/developing-cpp/references/declaration-order.md

@@ -41,6 +41,14 @@ class TaskTable {
 - 用户声明的特殊成员函数集中放第 4 组；`= default` 也写出来，读者才知道是故意默认。
 - 不要把数据成员插在函数之间；数据成员永远在最后一组。
 
+### 其他函数的组内次序
+
+Google、LLVM、OpenCV 都没有规定这一组内部的次序；本工作流补上：
+
+- 谓词 `Is` / `Has` / `Can`，然后 `Get`，然后普通函数按使用先后，最后是 `friend` 函数。
+- `friend` 不放在这一组开头，也不单放在类的最前面，不强制放进 `private`。
+- `friend` 类型仍跟其他类型放在一起，和 `friend` 函数不是同一组。
+
 ## 命名空间作用域的头文件
 
 文件槽位与守卫名以 `references/file-template.md` 为准；本节只看命名空间作用域内的排列顺序。

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

@@ -54,7 +54,7 @@
 - 默认用花括号初始化：`int count{};`、`std::vector<int> values{1, 2, 3};`。只有需要对比、`auto` 推导或赋值语义时用 `=`；`name = {{` 只用于多行聚合常量表，单个对象和空初始化仍写 `count{}`；不要用 `()` 初始化普通对象。
 - 类声明顺序：public → protected → private；类型与别名 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
 - 用户声明的拷贝/移动/析构函数在头文件声明、在 `.cpp` 定义；只有零参数且默认实现足够时才写 `= default`。
-- 查询成员函数标尾部 `const`；返回结果对象的 API 加 `[[nodiscard]]`，不要给所有非 `void` 函数机械添加。
+- 查询成员函数标尾部 `const`；返回结果对象的 API 加 `[[nodiscard]]`，不要给所有非 `void` 函数机械添加。标注位置与 `friend` 的例外见 `references/types.md`「`[[nodiscard]]`」。
 - 所有权优先 `std::unique_ptr`；没有共享所有权的理由时不用 `std::shared_ptr`。禁止裸 `new` / `delete`。
 - 禁止 C 风格强制转换；用 `static_cast`、`const_cast`、`reinterpret_cast`、`std::bit_cast`，并让 `clang-tidy` 的 `google-readability-casting` 兜底。
 - `.cpp` 里不需要外部引用的 `constexpr` 直接放具名命名空间；仅一个函数使用时才用函数内 `static constexpr`；函数和类型仍放匿名命名空间。
@@ -77,7 +77,7 @@
 - 混合优先级算术加显式括号，消除 `readability-math-missing-parentheses`。
 - 内建整数默认用 `int`；需要确定宽度时用 `<cstdint>` 的 `std::int32_t`、`std::int64_t` 等（可省略 `std::` 前缀），可能到 2^31 的值用 64 位；`std::size_t` / `std::ptrdiff_t` 只用于大小和指针差。不要用无符号类型表达「这个值不会为负」。
 - 封闭状态码用 `enum class`；底层类型默认 `int`，只有确实需要缩小存储时才写固定底层类型并说明理由。枚举值总是带作用域：`OrderResult::kSuccess`。
-- 枚举的尾随注释要么全写要么全不写；语义结果写在最前，`///<` 对齐。
+- 枚举的尾随注释要么全写要么全不写；两种句式与禁止项见 `references/comments.md`「枚举项与 `struct` 短字段：两种句式」。
 - 浮点不用 `==` 比较计算结果；按量纲给容差，金额用最小货币单位的整数。
 - 数值宽度、符号、枚举、强类型、`const` 成员和下标访问的完整规则见 `references/types.md`；初始化、RAII、移动和模板见 `references/language.md`。
 

package/skills/developing-cpp/references/project-design.md

@@ -18,6 +18,15 @@
 - 同一底层类型承载不同含义（米/秒、行/列）且容易混用时，用轻量强类型包装。
 - 不为每个名词造类；只有出现行为、不变量或独立变化原因时才升级为 `class`。
 
+### 取值的边界
+
+- 封闭取值一次列全。格子的取值是空、X、O；不要把 X 和 O 做成不含空的棋子，再用空值表示空格。
+- 位置是行和列，不是格子的另一种取值。胜负、轮到谁、已下过的序列属于棋盘或对局，不要塞进位置类型。
+- 有不变量的格子用公开构造的类，默认是空，X 或 O 至多写入一次。私有构造函数只留给必须经过工厂才能建立的对象，不用来表达三种取值，也不用来藏起行和列。
+- 一次写入能区分的失败都放进结果枚举。传入空取值是结果项，不抛异常。
+- 只由某一个类型产生的结果枚举嵌在该类型里：格子的写入结果和对局的写入结果取值不同，不合成命名空间里的一个 `PlaceResult`。
+- 尺寸是某个类型的事实时，写成该类型的 `static constexpr`，例如 `Board::kRowCount`；不要再造一个只做 `static_cast<std::size_t>` 的别名常量。
+
 ## 封闭状态与结果
 
 - 状态用连续取值的 `enum class`：`kPending`、`kActive`、`kDone`。

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

@@ -62,14 +62,16 @@ std::array<TaskState, kItemCount> items_{};
 - 枚举值只在类型作用域内可见：`TaskState::kPending`，不写 `kPending`。
 - 与整数之间不发生隐式转换；需要编号时写 `static_cast<int>(state)`，只用于输出或既有接口。
 - 同类型值可以比较和赋值；不能参与算术。
-- 需要固定布局时写底层类型：`enum class TaskState : std::uint8_t { kPending, kActive, kDone };`
+- 需要固定布局时写底层类型。编号要在头文件里直接读到，就逐个写出来，不靠第一项默认为 0：`enum class TaskState : std::uint8_t { kPending = 0, kActive = 1, kDone = 2 };`
 
 约定：
 
 - 新代码用 `enum class`；unscoped `enum` 只用于兼容 C 接口，不作为默认写法。
 - 封闭状态码默认写 `: std::uint8_t`；普通枚举用默认底层类型。
-- 枚举值的行尾注释要么全写要么全不写；语义结果写在最前，`///<` 对齐。
+- 枚举值的行尾注释要么全写要么全不写；两种句式与禁止项见 `references/comments.md`「枚举项与 `struct` 短字段：两种句式」。
 - 需要“编号”与“名字”两套表示时，写显式映射函数，例如 `TaskStateToName` / `TaskStateFromName`，不要在枚举和整数之间来回隐式转换。
+- 编号按“失败优先”排：空状态或前置条件失败为 0，业务失败随后，成功放在最后。读取端因此可以先判 0，再决定是否继续。
+- 编号只用于输出和既有接口；要从编号找回名字，仍走显式映射函数，不拿编号做算术。
 
 ## 强类型包装
 
@@ -111,6 +113,8 @@ class TaskBoard {
 
 - 只给“结果携带信息、忽略会出错”的函数：查询型 `const` 成员与返回结果对象的 API。
 - 不给所有非 `void` 函数机械添加；标注的价值来自稀缺。
+- 写法位置：`[[nodiscard]]` 在返回类型前面，然后才是 `static` 或 `constexpr`；参数列表之后才是 `const`、`override`、`noexcept`。
+- 类内 `friend` 不加 `[[nodiscard]]`：Clang 拒绝 `[[nodiscard]] friend`、`friend [[nodiscard]]` 和参数列表后的 `[[nodiscard]]`。不要再猜下一种写法。
 - 有意丢弃时写 `static_cast<void>(result)`，不要为此全局关闭警告。
 - 测试里验证“必须处理结果”时，同时验证忽略能被编译器发现。
 

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

@@ -2,7 +2,7 @@
 // 只读注释审计：按 references/comments.md 的硬规则检查 C/C++ 源文件。
 //
 // 检查项：Doxygen 文件头、注释行宽度、标签、注释与声明的贴合、
-// 类型注释存在性、成员功能清单、设计论证（方案对比）、否定式边界、领域尺寸、谓词首句、@param 完整性、枚举成员注释一致性、数据成员主注释位置。
+// 类型注释存在性、成员功能清单、设计论证（方案对比）、否定式边界、领域尺寸、谓词首句、@param 完整性、枚举成员注释一致性、枚举行尾句式、数据成员主注释位置。
 // 不重写任何文件。
 //
 // 用法：
@@ -482,6 +482,22 @@ export function checkText(text, options = {}) {
     index = body
   }
 
+  for (let index = 0; index < lines.length; index += 1) {
+    const marker = lines[index].indexOf('///<')
+    if (marker === -1) continue
+    const content = lines[index].slice(marker + 4).trim().replace(/。$/, '').trim()
+    const colon = content.indexOf('：')
+    if (colon !== -1) {
+      if (content.slice(colon + 1).trim() === '') {
+        add(index + 1, 'enum-trailing-empty', '行尾注释冒号后为空：写「类别：说明」，冒号两侧都不能为空')
+      }
+      continue
+    }
+    if (/[，,]/.test(content)) {
+      add(index + 1, 'enum-trailing-comma', '行尾注释用逗号连接类别与说明：改成「类别：说明」，类别在前')
+    }
+  }
+
   for (let index = 0; index < lines.length; index += 1) {
     const trimmed = lines[index].trim()
     if (trimmed.startsWith('//') || trimmed.startsWith('///') || !/\bnoexcept\b/.test(trimmed)) continue

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

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