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

package/lib/client.js

@@ -8,8 +8,8 @@ window.__ModuleLoader__.load({
 /**
  * 注释标签策略：设置页的预览、技能快照与检查器参数共用这一份。
  *
- * 配置只描述「写注释时默认带哪些标签」，不描述写法本身；写法在
- * `skills/developing-cpp/references/comments.md`。设置页保存的值由宿主
+ * 配置只描述「写注释时默认带哪些标签、声明用哪种注释符号」，不描述写法本身；
+ * 写法在 `skills/developing-cpp/references/comments.md`。设置页保存的值由宿主
  * 写回插件 Config，服务端 `apply(ctx, config)` 用它生成本页快照与检查器参数。
  *
  * 这份文件被 `tsc` 编进 `lib/comment-policy.js`，打包客户端半侧时再内联进
@@ -17,29 +17,16 @@ 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'];
 /** 只有用户主动填了非空值才放行的隐私标签。 */
 const PRIVACY_TAGS = ['author', 'date', 'copyright', 'version'];
-/** 标签说明：设置页逐行显示，用作行的辅助文字。 */
-const TAG_TEXT = {
-    brief: '一句话说明这个文件定义或实现什么',
-    author: '只在用户填了非空值时写出',
-    date: '只在用户填了非空值时写出',
-    copyright: '只在用户填了非空值时写出',
-    version: '只在用户填了非空值时写出',
-    param: '函数参数的含义、范围或所有权',
-    returns: '返回值的条件；返回类型自明时可以省略',
-    throws: '抛出的异常类型与条件；不抛异常的函数不写',
-    note: '调用方需要注意的补充说明',
-    see: '相关函数、类型或文档',
-    pre: '调用前必须成立的条件',
-    post: '调用后保证成立的条件',
-    tparam: '模板参数',
-    retval: '特定返回值的含义',
-};
 /** 开关型标签在设置页的标题。 */
 const TAG_LABEL = {
     file: '@file',
@@ -62,8 +49,9 @@ const TAG_LABEL = {
 const SAMPLE_BRIEF = '<一句话说明本文件>';
 /** 预览里的示例文件名：只是占位符，不对应任何工程的真实文件。 */
 const SAMPLE_FILE = '<文件名>';
-/** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
+/** 出厂配置：声明用 `///`，文件头只留 @file 与 @brief，契约标签全开，其余关闭。 */
 const DEFAULT_CONFIG = {
+    commentStyle: 'slash',
     brief: { enabled: true, value: '' },
     author: { enabled: false, value: '' },
     date: { enabled: false, value: '' },
@@ -99,12 +87,16 @@ function flag(value, fallback) {
     const plain = unwrap(value);
     return typeof plain === 'boolean' ? plain : fallback;
 }
+/** 声明符号只认两档；未知值回到 `///`。 */
+function commentStyleOf(raw) {
+    return unwrap(raw) === 'block' ? 'block' : 'slash';
+}
 /**
  * 把宿主给的值补齐成完整配置；缺字段、旧版本或手工改坏的配置都回到出厂值。
  */
 function normalizeConfig(raw) {
     const source = raw && typeof raw === 'object' ? raw : {};
-    const config = {};
+    const config = { commentStyle: commentStyleOf(source.commentStyle) };
     for (const tag of HEADER_TAGS) {
         const entry = source[tag] && typeof source[tag] === 'object' ? source[tag] : {};
         config[tag] = {
@@ -117,59 +109,85 @@ function normalizeConfig(raw) {
     }
     return config;
 }
+/** 一行声明注释：`/// 内容` 或块注释里的 ` * 内容`。 */
+function declarationLine(style, content) {
+    return style === 'block' ? ` * ${content}` : `/// ${content}`;
+}
+/** 文件头后面的说明行：块注释里空行写成 ` *`。 */
+function separatorLine(style) {
+    return style === 'block' ? ' *' : '///';
+}
 /**
- * 按配置渲染文件头；`@file` 始终是传入的文件名。
+ * 按配置渲染文件头；`@file` 始终是传入的文件名，块注释按 Doxygen 结构分行。
  */
 function renderFileHeader(raw, fileName) {
     const config = normalizeConfig(raw);
     const name = text(fileName) || SAMPLE_FILE;
-    const lines = [`/// @file ${name}`];
+    const lines = [`@file ${name}`];
     if (config.brief.enabled) {
-        lines.push(config.brief.value ? `/// @brief ${config.brief.value}` : '/// @brief');
+        lines.push(config.brief.value ? `@brief ${config.brief.value}` : '@brief');
     }
     for (const tag of ['author', 'date', 'copyright', 'version']) {
         if (config[tag].enabled && config[tag].value)
-            lines.push(`/// @${tag} ${config[tag].value}`);
+            lines.push(`@${tag} ${config[tag].value}`);
+    }
+    if (config.commentStyle === 'block') {
+        return ['/**', ...lines.map((line) => ` * ${line}`), ' */'];
     }
-    return lines;
+    return lines.map((line) => `/// ${line}`);
 }
 /**
  * 设置页的预览：文件头 + 一段函数注释，只显示当前配置会写出的标签。
+ * 返回值里的 `header` 已按声明符号排好，`contract` 是每行标签的正文。
  */
 function previewParts(raw, sampleName) {
     const config = normalizeConfig(raw);
     const header = renderFileHeader(config, sampleName || SAMPLE_FILE);
     // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
-    const briefIndex = header.indexOf('/// @brief');
-    if (briefIndex !== -1)
-        header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
+    const briefIndex = header.findIndex((line) => /@brief$/.test(line.trim()));
+    if (briefIndex !== -1) {
+        header[briefIndex] = header[briefIndex].replace(/@brief$/, `@brief ${SAMPLE_BRIEF}`);
+    }
     const contract = [];
     if (config.param)
-        contract.push('/// @param row 目标行号。');
+        contract.push('@param row 目标行号。');
     if (config.returns)
-        contract.push('/// @return 放置成功时为 true。');
+        contract.push('@return 放置成功时为 true。');
     if (config.throws)
-        contract.push('/// @throws std::out_of_range 行号越界时抛出。');
-    const declaration = '[[nodiscard]] bool Place(int row, int column);';
-    return { header, contract, declaration };
+        contract.push('@throws std::out_of_range 行号越界时抛出。');
+    return { header, contract, declaration: '[[nodiscard]] bool Place(int row, int column);' };
 }
 /**
  * 设置页预览的纯文本形式；客户端半侧用同一份实现渲染 `<pre>`。
+ * 块注释的每个内容行前加 ` * `，首尾各占一行。
  */
 function previewText(raw, sampleName) {
-    const { header, contract, declaration } = previewParts(raw, sampleName);
-    const lines = [...header, '///', '/// 放置成功时返回 true；行号越界或目标格子已占时返回 false。'];
+    const config = normalizeConfig(raw);
+    const { header, contract, declaration } = previewParts(config, sampleName);
+    const style = config.commentStyle;
+    const summary = '放置成功时返回 true；行号越界或目标格子已占时返回 false。';
+    if (style === 'block') {
+        const body = [declarationLine(style, summary)];
+        if (contract.length > 0) {
+            body.push(separatorLine(style), ...contract.map((line) => declarationLine(style, line)));
+        }
+        return [...header, '/**', ...body, ' */', declaration].join('\n');
+    }
+    const lines = [...header, separatorLine(style), declarationLine(style, summary)];
     if (contract.length > 0)
-        lines.push('///', ...contract);
+        lines.push(separatorLine(style), ...contract.map((line) => declarationLine(style, line)));
     lines.push(declaration);
     return lines.join('\n');
 }
 /**
- * 检查器参数：隐私标签要显式放行，@brief 被关掉时跳过摘要检查。
+ * 检查器参数：隐私标签要显式放行，@brief 被关掉时跳过摘要检查，
+ * 声明符号切到块注释时让检查器按块注释收口。
  */
 function checkerArgs(raw) {
     const config = normalizeConfig(raw);
     const args = [];
+    if (config.commentStyle === 'block')
+        args.push('--comment-style', 'block');
     if (!config.brief.enabled)
         args.push('--no-brief');
     for (const tag of PRIVACY_TAGS) {
@@ -180,10 +198,11 @@ function checkerArgs(raw) {
 }
 /**
  * 技能快照：`get()` 把它接在技能正文末尾，让代理看到当前 profile 的标签开关。
+ * 只写一行，列出声明符号、开启与关闭的标签，避免正文膨胀。
  */
 function snapshotText(raw) {
     const config = normalizeConfig(raw);
-    const on = [];
+    const on = ['@file'];
     const off = [];
     for (const tag of HEADER_TAGS) {
         const entry = config[tag];
@@ -193,17 +212,15 @@ function snapshotText(raw) {
         else
             off.push(TAG_LABEL[tag]);
     }
-    const contract = CONTRACT_TAGS.filter((tag) => config[tag]).map((tag) => TAG_LABEL[tag]);
-    const extra = EXTRA_TAGS.filter((tag) => config[tag]).map((tag) => TAG_LABEL[tag]);
-    const allowed = PRIVACY_TAGS.filter((tag) => config[tag].enabled && config[tag].value);
-    const head = `## 当前注释配置（profile）\n\n`;
-    const body = [
-        `- 文件头：@file 固定为文件名；开启 ${on.join('、') || '无'}；关闭 ${off.join('、') || '无'}。`,
-        `- 函数契约：${contract.length > 0 ? contract.join('、') : '不要求'}。`,
-        `- 更多标签：${extra.length > 0 ? `可选 ${extra.join('、')}` : '未启用'}。`,
-        `- 检查器放行：${allowed.length > 0 ? allowed.join('、') : '无'}（隐私标签只有填了非空值才放行）。`,
-    ];
-    return head + body.join('\n');
+    for (const tag of [...CONTRACT_TAGS, ...EXTRA_TAGS]) {
+        if (config[tag])
+            on.push(TAG_LABEL[tag]);
+        else
+            off.push(TAG_LABEL[tag]);
+    }
+    const style = config.commentStyle === 'block' ? '/** ... */' : '///';
+    const line = `- 声明符号：${style}（函数体固定 //）；开启 ${on.join('、')}；关闭 ${off.join('、') || '无'}。`;
+    return `## 当前注释配置（profile）\n\n${line}`;
 }
 
 
@@ -218,29 +235,34 @@ const PACKAGE_NAME = '@chengzhao-dev/dsh-cpp-workflow'
 const STRINGS = {
   zh: {
     nav: 'C++ 工程流程',
-    eyebrow: '文档注释',
-    title: '注释默认带哪些标签',
-    intro: '这里只决定代理新写注释时的默认值。源码里已有的注释不会被改写；保存后，下一次读取技能时生效。',
+    heading: '文档注释',
+    style: '注释符号',
+    bodyRow: '函数体',
+    bodyPlaceholder: '函数体：固定 //',
     header: '文件头',
-    headerHint: '每个手写源文件开头的 /// 注释块。',
-    briefHint: '一句话说明这个文件定义或实现什么。留空时，每个文件自己写。',
-    authorHint: '作者署名。默认不写；打开并填写后才写进文件头。',
-    dateHint: '创建或最后修改日期。默认不写。',
-    copyrightHint: '版权声明。默认不写。',
-    versionHint: '文件版本号。默认不写。',
-    paramHint: '函数参数的含义、范围或所有权。',
-    returnHint: '返回值在什么条件下成立。返回类型自明时可以省略。',
-    throwsHint: '抛出的异常类型与条件。不抛异常的函数不写。',
-    contractHint: '函数声明的注释里必须交代的参数与失败信息。',
-    extra: '更多标签',
-    extraHint: '默认关闭，需要时在单个函数上补写。',
+    type: '类型',
+    declaration: '函数声明',
     preview: '预览',
-    previewHint: '按当前开关生成，文件名用占位符表示。',
+    filePlaceholder: '跟随文件名',
+    briefPlaceholder: '文件摘要：留空则各文件自写',
+    authorPlaceholder: '作者署名：默认不写',
+    datePlaceholder: '日期：默认不写',
+    copyrightPlaceholder: '版权：默认不写',
+    versionPlaceholder: '版本：默认不写',
+    paramPlaceholder: '参数：默认使用',
+    returnPlaceholder: '返回值：默认使用',
+    throwsPlaceholder: '异常：默认使用',
+    prePlaceholder: '前置条件：默认不使用',
+    postPlaceholder: '后置条件：默认不使用',
+    retvalPlaceholder: '返回值枚举：默认不使用',
+    tparamPlaceholder: '模板参数：默认不使用',
+    notePlaceholder: '补充：默认不使用',
+    seePlaceholder: '参见：默认不使用',
     save: '保存',
     reset: '撤销修改',
     defaults: '恢复默认值',
     restored: '已填入内置默认值，点“保存”后生效。',
-    saved: '已保存，下一次读取技能时生效。',
+    saved: '已保存到 ~/.dsh/profiles/<profile>/cordis.patch.yml，下一次读取技能时生效。',
     rejected: '保存被拒绝：配置可能已在别处修改。请先撤销修改，再重新编辑。',
     unsaved: '有未保存的改动',
     loading: '正在读取配置…',
@@ -249,38 +271,37 @@ const STRINGS = {
     readOnly: '这个页面暂时没有连到配置表单，下面的值是内置默认值。重启 DeepSeek Harness 后重新打开本页即可编辑。',
     reload: '重新载入页面',
     noService: '（configForms 服务未连接）',
-    fixed: '跟随文件名',
-    fixedHint: '值由实际文件决定，不写进配置。',
-    emptyValue: '留空则由文件自己写',
-    blankBrief: '留空则文件自述',
-    on: '写出',
-    off: '不写',
   },
   en: {
     nav: 'C++ Workflow',
-    eyebrow: 'Doxygen comments',
-    title: 'Which tags comments carry by default',
-    intro: 'These defaults apply to comments the agent writes from now on. Existing sources are never rewritten; saving takes effect on the next skill read.',
+    heading: 'Doxygen comments',
+    style: 'Comment symbol',
+    bodyRow: 'Body',
+    bodyPlaceholder: 'Function bodies: always //',
     header: 'File header',
-    headerHint: 'The /// block at the top of each hand-written source file.',
-    briefHint: 'One sentence saying what the file defines or implements. Leave the value to each file.',
-    authorHint: 'Author name. Off by default; written only when filled.',
-    dateHint: 'Created or last modified date. Off by default.',
-    copyrightHint: 'Copyright notice. Off by default.',
-    versionHint: 'File version. Off by default.',
-    paramHint: 'Meaning, range, or ownership of a parameter.',
-    returnHint: 'When the returned value holds. Optional when the type is self-evident.',
-    throwsHint: 'Exception type and condition. Omitted when the function does not throw.',
-    contractHint: 'Parameters and failure information every function comment must carry.',
-    extra: 'More tags',
-    extraHint: 'Off by default; add them per function when needed.',
+    type: 'Types',
+    declaration: 'Function declarations',
     preview: 'Preview',
-    previewHint: 'Generated from the switches above; the file name is a placeholder.',
+    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',
     save: 'Save',
     reset: 'Discard changes',
     defaults: 'Restore defaults',
     restored: 'Built-in defaults are filled in; select Save to apply them.',
-    saved: 'Saved; the next skill read uses it.',
+    saved: 'Saved to ~/.dsh/profiles/<profile>/cordis.patch.yml; the next skill read uses it.',
     rejected: 'The host rejected the save: the config changed elsewhere. Discard your changes and edit again.',
     unsaved: 'Unsaved changes',
     loading: 'Reading configuration…',
@@ -289,12 +310,6 @@ const STRINGS = {
     readOnly: 'This page is not connected to a configuration form yet; the values below are built-in defaults. Restart DeepSeek Harness, then reopen this page to edit.',
     reload: 'Reload page',
     noService: ' (the configForms service is not connected)',
-    fixed: 'Follows the file name',
-    fixedHint: 'Derived from the file itself, never stored in the config.',
-    emptyValue: 'Leave empty and each file writes its own',
-    blankBrief: 'Leave empty for each file',
-    on: 'Write',
-    off: 'Omit',
   },
 }
 
@@ -323,14 +338,18 @@ const CSS = `
 .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:88px minmax(0,1fr);gap:2px 14px;padding:9px 14px;border-top:1px solid var(--dcw-border)}
+.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);padding-top:3px}
-.dcw-row-control{display:flex;flex-wrap:wrap;align-items:center;gap:6px 10px;min-width:0}
-.dcw-row-hint{flex-basis:100%;margin:0;color:var(--dcw-muted);font-size:11.5px;line-height:1.55}
-.dcw-row-fixed .dcw-row-control{gap:8px}
-.dcw-static{display:inline-flex;align-items:center;gap:6px;height:26px;padding:0 9px;border:1px dashed var(--dcw-border);border-radius:6px;background:var(--dcw-bg2);color:var(--dcw-muted);font-size:12px}
-.dcw-static svg{flex:none;opacity:.7}
+.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-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}
@@ -368,7 +387,7 @@ const CSS = `
 .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{grid-template-columns:1fr;gap:4px}.dcw-row-label{padding-top:0}.dcw-flags{grid-template-columns:1fr}.dcw-flag:nth-child(2){border-top:1px solid var(--dcw-border)}}
+@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}}
 `
 
 function ensureStyles() {
@@ -414,78 +433,122 @@ function Chevron() {
   )
 }
 
-const HINT_KEY = {
-  brief: 'briefHint',
-  author: 'authorHint',
-  date: 'dateHint',
-  copyright: 'copyrightHint',
-  version: 'versionHint',
-  param: 'paramHint',
-  returns: 'returnHint',
-  throws: 'throwsHint',
+/** 五个区块统一用默认展开的 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,
+  )
 }
 
+/** 文件头可填写的一行：标签、开关、文本框。 */
 function ValueRow(props) {
-  const s = props.strings
   const entry = props.entry
   return h(
     'div',
     { className: 'dcw-row' },
     h('div', { className: 'dcw-row-label' }, TAG_LABEL[props.tag]),
-    h(
-      'div',
-      { className: 'dcw-row-control' },
-      h(Switch, {
-        label: TAG_LABEL[props.tag],
-        checked: entry.enabled,
-        disabled: props.disabled,
-        onChange: (enabled) => props.onChange({ ...entry, enabled }),
-      }),
-      h('span', { className: 'dcw-state', 'aria-hidden': 'true' }, entry.enabled ? s.on : s.off),
-      h('input', {
-        className: 'dcw-input',
-        type: 'text',
-        value: entry.value,
-        placeholder: props.tag === 'brief' ? s.blankBrief : s.emptyValue,
-        disabled: props.disabled || !entry.enabled,
-        'aria-label': `${TAG_LABEL[props.tag]} 的值`,
-        onChange: (event) => props.onChange({ ...entry, value: event.target.value }),
-      }),
-      h('p', { className: 'dcw-row-hint' }, s[HINT_KEY[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 }),
+    }),
+  )
+}
+
+/** 只有开关的标签行；右侧框显示该标签的作用，不进入配置。 */
+function FlagRow(props) {
+  return h(
+    'div',
+    { className: 'dcw-row' },
+    h('div', { className: 'dcw-row-label' }, TAG_LABEL[props.tag]),
+    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 Flag(props) {
+/** 值由文件或语法固定的行：中间锁，右侧框给出固定值。 */
+function LockRow(props) {
   return h(
     'div',
-    { className: 'dcw-flag' },
+    { 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,
+    }),
+  )
+}
+
+/** 两种声明注释符号；按钮本身可用键盘切换。 */
+function StyleRow(props) {
+  const options = [
+    { value: 'slash', label: '///' },
+    { value: 'block', label: '/** */' },
+  ]
+  return h(
+    'div',
+    { className: 'dcw-row dcw-row-style' },
+    h('div', { className: 'dcw-row-label' }, props.label),
     h(
       'div',
-      { className: 'dcw-row-label' },
-      TAG_LABEL[props.tag],
-      h(Switch, {
-        label: TAG_LABEL[props.tag],
-        checked: props.checked,
-        disabled: props.disabled,
-        onChange: props.onChange,
-      }),
+      { 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,
+        ),
+      ),
     ),
-    h('p', { className: 'dcw-row-hint' }, props.hint || ''),
   )
 }
 
 function Preview(props) {
   const s = props.strings
   return h(
-    'section',
-    { className: 'dcw-card', 'aria-label': s.preview },
-    h(
-      'div',
-      { className: 'dcw-card-head' },
-      h('h4', { className: 'dcw-card-title' }, s.preview),
-      h('p', { className: 'dcw-card-hint' }, s.previewHint),
-    ),
+    Section,
+    { title: s.preview },
     h('pre', { className: 'dcw-preview' }, previewText(props.config, SAMPLE_FILE)),
   )
 }
@@ -542,6 +605,28 @@ const ENTRY_ID = 'cpp-workflow'
 const FORM_RETRY_MS = 500
 const MAX_FORM_RETRIES = 20
 
+/** 文件头可填写标签的占位文字；顺序与 HEADER_TAGS 一致。 */
+const HEADER_PLACEHOLDER = {
+  brief: 'briefPlaceholder',
+  author: 'authorPlaceholder',
+  date: 'datePlaceholder',
+  copyright: 'copyrightPlaceholder',
+  version: 'versionPlaceholder',
+}
+
+/** 只有开关的标签按区块取占位文字。 */
+const FLAG_PLACEHOLDER = {
+  param: 'paramPlaceholder',
+  returns: 'returnPlaceholder',
+  throws: 'throwsPlaceholder',
+  pre: 'prePlaceholder',
+  post: 'postPlaceholder',
+  retval: 'retvalPlaceholder',
+  tparam: 'tparamPlaceholder',
+  note: 'notePlaceholder',
+  see: 'seePlaceholder',
+}
+
 function ConfigPage(props) {
   const s = t()
   ensureStyles()
@@ -635,16 +720,21 @@ 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]],
+      onChange: (value) => update({ [tag]: value }),
+    })
+
   return h(
     'div',
     { className: 'dcw-page' },
-    h(
-      'header',
-      { className: 'dcw-head' },
-      h('p', { className: 'dcw-eyebrow' }, s.eyebrow),
-      h('h3', { className: 'dcw-title' }, s.title),
-      h('p', { className: 'dcw-lede' }, s.intro),
-    ),
+    h('header', { className: 'dcw-head' }, h('h3', { className: 'dcw-title' }, s.heading)),
     missing
       ? h(
           'div',
@@ -656,11 +746,7 @@ function ConfigPage(props) {
             s.readOnly,
             props.hasService === false ? h('span', { className: 'dcw-note-code' }, s.noService) : null,
           ),
-          h(
-            'button',
-            { type: 'button', className: 'dcw-note-action', onClick: reload },
-            s.reload,
-          ),
+          h('button', { type: 'button', className: 'dcw-note-action', onClick: reload }, s.reload),
         )
       : null,
     editable && !ready && status !== 'missing'
@@ -672,78 +758,36 @@ function ConfigPage(props) {
         )
       : null,
     h(
-      'section',
-      { className: 'dcw-card', 'aria-labelledby': 'dcw-header-title' },
-      h(
-        'div',
-        { className: 'dcw-card-head' },
-        h('h4', { className: 'dcw-card-title', id: 'dcw-header-title' }, s.header),
-        h('p', { className: 'dcw-card-hint' }, s.headerHint),
-      ),
-      h(
-        'div',
-        { className: 'dcw-row dcw-row-fixed' },
-        h('div', { className: 'dcw-row-label' }, TAG_LABEL.file),
-        h(
-          'div',
-          { className: 'dcw-row-control' },
-          h('span', { className: 'dcw-static' }, h(LockIcon), s.fixed),
-          h('p', { className: 'dcw-row-hint' }, s.fixedHint),
-        ),
-      ),
+      Section,
+      { title: s.style },
+      h(StyleRow, {
+        label: s.style,
+        value: draft.commentStyle,
+        disabled,
+        onChange: (value) => update({ commentStyle: value }),
+      }),
+      h(LockRow, { label: s.bodyRow, placeholder: s.bodyPlaceholder }),
+    ),
+    h(
+      Section,
+      { title: s.header },
+      h(LockRow, { label: TAG_LABEL.file, placeholder: s.filePlaceholder }),
       ...HEADER_TAGS.map((tag) =>
         h(ValueRow, {
           key: tag,
           tag,
-          strings: s,
           entry: draft[tag],
           disabled,
+          placeholder: s[HEADER_PLACEHOLDER[tag]],
           onChange: (entry) => update({ [tag]: entry }),
         }),
       ),
     ),
+    h(Section, { title: s.type }, ...TYPE_TAGS.map((tag) => flag(tag, draft[tag]))),
     h(
-      'section',
-      { className: 'dcw-card', 'aria-labelledby': 'dcw-contract-title' },
-      h(
-        'div',
-        { className: 'dcw-card-head' },
-        h('h4', { className: 'dcw-card-title', id: 'dcw-contract-title' }, s.contract),
-        h('p', { className: 'dcw-card-hint' }, s.contractHint),
-      ),
-      h(
-        'div',
-        { className: 'dcw-flags' },
-        ...CONTRACT_TAGS.map((tag) =>
-          h(Flag, {
-            key: tag,
-            tag,
-            checked: draft[tag],
-            disabled,
-            hint: s[HINT_KEY[tag]],
-            onChange: (value) => update({ [tag]: value }),
-          }),
-        ),
-      ),
-    ),
-    h(
-      'details',
-      { className: 'dcw-card' },
-      h('summary', null, h('span', { className: 'dcw-card-title' }, s.extra), h(Chevron)),
-      h('p', { className: 'dcw-card-hint', style: { margin: '0 14px 2px' } }, s.extraHint),
-      h(
-        'div',
-        { className: 'dcw-flags' },
-        ...EXTRA_TAGS.map((tag) =>
-          h(Flag, {
-            key: tag,
-            tag,
-            checked: draft[tag],
-            disabled,
-            onChange: (value) => update({ [tag]: value }),
-          }),
-        ),
-      ),
+      Section,
+      { title: s.declaration },
+      ...[...CONTRACT_TAGS, ...FUNCTION_EXTRA_TAGS].map((tag) => flag(tag, draft[tag])),
     ),
     h(Preview, { config: draft, strings: s }),
     editable