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

package/lib/client.js

@@ -1,4 +1,4 @@
-// 由 scripts/building-client.mjs 生成，请改 src/comment-policy.ts 与 src/client/app.cjs.js。
+// 由 scripts/building-client.mjs 生成，请改 src/comment-policy.ts 与 src/client/*.js。
 window.__ModuleLoader__.load({
   id: "@chengzhao-dev/dsh-cpp-workflow",
   factory: (require) => {
@@ -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,75 +235,81 @@ 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: '恢复出厂值',
-    saved: '已保存，下一次读取技能时生效。',
-    rejected: '保存被拒绝：配置可能已在别处修改，请恢复出厂值后再试。',
+    reset: '撤销修改',
+    defaults: '恢复默认值',
+    restored: '已填入内置默认值，点“保存”后生效。',
+    saved: '已保存到 ~/.dsh/profiles/<profile>/cordis.patch.yml，下一次读取技能时生效。',
+    rejected: '保存被拒绝：配置可能已在别处修改。请先撤销修改，再重新编辑。',
     unsaved: '有未保存的改动',
     loading: '正在读取配置…',
     unavailable: '这个部署没有提供这份配置。',
     unreadable: '当前账户不能修改这份配置。',
-    readOnly: '当前部署没有把可编辑配置传给这个页面，下面显示的是出厂值。',
-    fixed: '跟随文件名',
-    fixedHint: '值由实际文件决定，不写进配置。',
-    emptyValue: '留空则由文件自己写',
-    blankBrief: '留空则文件自述',
-    on: '写出',
-    off: '不写',
+    readOnly: '这个页面暂时没有连到配置表单，下面的值是内置默认值。重启 DeepSeek Harness 后重新打开本页即可编辑。',
+    reload: '重新载入页面',
+    noService: '（configForms 服务未连接）',
   },
   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: 'Restore defaults',
-    saved: 'Saved; the next skill read uses it.',
-    rejected: 'The host rejected the save: the config changed elsewhere. Restore defaults and try again.',
+    reset: 'Discard changes',
+    defaults: 'Restore defaults',
+    restored: 'Built-in defaults are filled in; select Save to apply them.',
+    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…',
     unavailable: 'This deployment does not serve this configuration.',
     unreadable: 'This account cannot edit the configuration.',
-    readOnly: 'This deployment does not pass an editable form to this page; the values below are defaults.',
-    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',
+    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)',
   },
 }
 
@@ -315,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}
@@ -357,7 +384,10 @@ const CSS = `
 .dcw-status{flex:1 1 200px;margin:0;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)}
-@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)}}
+.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}}
 `
 
 function ensureStyles() {
@@ -403,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)),
   )
 }
@@ -521,10 +595,43 @@ function useFormSnapshot(form) {
   return snapshot
 }
 
+// 配置卡片本身：状态机、保存/撤销/恢复默认值，以及组合包条目里的挂点。
+// 分片按 scripts/building-client.mjs 的模块表顺序拼接：shell → text → styles →
+// widgets → form-state → 本文件。分片共享同一个工厂作用域，不要各自 require。
+
+// 宿主组合包 cordis.patch.yml 插入的 profile 条目 id；设置服务按它定位表单。
+const ENTRY_ID = 'cpp-workflow'
+// configForms 可能晚于本插件挂载；页面在首次绘制后短暂重试，拿不到再给手动恢复入口。
+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()
-  const form = props.form
+  // form 由挂点注入；resolveForm 兜住“服务晚到”的部署，拿到后下一次绘制自动接上。
+  const form = props.form || (typeof props.resolveForm === 'function' ? props.resolveForm() : undefined)
   const state = useFormSnapshot(form)
   const initial = React.useMemo(() => normalizeConfig(state.value), [])
   const [draft, setDraft] = React.useState(initial)
@@ -533,11 +640,13 @@ function ConfigPage(props) {
   const [busy, setBusy] = React.useState(false)
   const [message, setMessage] = React.useState('')
   const [tone, setTone] = React.useState('')
+  const [attempt, setAttempt] = React.useState(0)
   const revision = state.revision
   // 快照只有 status / writable / revision；旧版本多出来的 mode 字段已不存在，
   // 再按它判断会把所有可写表单误判成只读。
-  const ready = Boolean(state.status === 'ready' && state.writable)
+  const ready = Boolean(form && state.status === 'ready' && state.writable)
   const status = state.status
+  const missing = !form
 
   React.useEffect(() => {
     if (dirty || state.status !== 'ready') return
@@ -546,6 +655,12 @@ function ConfigPage(props) {
     setDraft(next)
   }, [revision, status, dirty, form, state.value])
 
+  React.useEffect(() => {
+    if (form || attempt >= MAX_FORM_RETRIES || typeof setTimeout !== 'function') return undefined
+    const timer = setTimeout(() => setAttempt((value) => value + 1), FORM_RETRY_MS)
+    return () => clearTimeout(timer)
+  }, [form, attempt])
+
   const update = (patch) => {
     setDraft((current) => ({ ...current, ...patch }))
     setDirty(true)
@@ -553,6 +668,7 @@ function ConfigPage(props) {
     setTone('')
   }
 
+  // 撤销：回到最近一次从宿主读到的值，不写盘。
   const reset = () => {
     setDraft(base)
     setDirty(false)
@@ -560,6 +676,20 @@ function ConfigPage(props) {
     setTone('')
   }
 
+  // 恢复默认值：只填进草稿，点“保存”后才写盘，避免误触直接覆盖已保存的配置。
+  const restoreDefaults = () => {
+    setDraft(normalizeConfig(DEFAULT_CONFIG))
+    setDirty(true)
+    setMessage(s.restored)
+    setTone('')
+  }
+
+  const reload = () => {
+    if (typeof window !== 'undefined' && window.location && typeof window.location.reload === 'function') {
+      window.location.reload()
+    }
+  }
+
   const save = async () => {
     if (!ready || busy) return
     const operations = diffOperations(draft, base)
@@ -573,6 +703,9 @@ function ConfigPage(props) {
         setMessage(s.saved)
         setTone('ok')
       } else {
+        // 被拒时宿主已刷新镜像；把基准对齐到新快照，撤销才不会回到过期值。
+        const fresh = snapshotOf(form)
+        if (fresh && fresh.status === 'ready') setBase(normalizeConfig(fresh.value))
         setMessage(s.rejected)
         setTone('warn')
       }
@@ -587,22 +720,33 @@ 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),
-    ),
-    !editable
+    h('header', { className: 'dcw-head' }, h('h3', { className: 'dcw-title' }, s.heading)),
+    missing
       ? h(
           'div',
-          { className: 'dcw-note', role: 'status' },
+          { className: 'dcw-note', role: 'status', 'data-tone': 'warn' },
           h('span', { className: 'dcw-note-dot' }),
-          h('span', null, s.readOnly),
+          h(
+            'span',
+            null,
+            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),
         )
       : null,
     editable && !ready && status !== 'missing'
@@ -614,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
@@ -704,24 +806,31 @@ function ConfigPage(props) {
           ),
           h('button', { type: 'button', className: 'dcw-btn', onClick: reset, disabled: busy || !dirty }, s.reset),
           h(
-            'p',
-            { className: 'dcw-status', role: 'status', 'data-tone': tone },
-            message || (dirty ? s.unsaved : ''),
+            'button',
+            { type: 'button', className: 'dcw-btn', onClick: restoreDefaults, disabled: busy || !ready },
+            s.defaults,
           ),
+          h('p', { className: 'dcw-status', role: 'status', 'data-tone': tone }, message || (dirty ? s.unsaved : '')),
         )
       : null,
   )
 }
 
-// 组合包 cordis.patch.yml 插入的 profile 条目 id；设置服务按它定位表单。
-const ENTRY_ID = 'cpp-workflow'
-
-function page(ownerProps, form) {
-  return h(ConfigPage, { ...(ownerProps || {}), form })
+function page(ownerProps, form, resolveForm, hasService) {
+  return h(ConfigPage, { ...(ownerProps || {}), form, resolveForm, hasService })
 }
 
 function apply(ctx) {
-  const form = ctx.configForms ? ctx.configForms.get(ENTRY_ID) : undefined
+  // 每次取表单都重新查询服务：宿主可能在本插件之后才挂载 configForms。
+  const resolveForm = () => {
+    if (!ctx.configForms || typeof ctx.configForms.get !== 'function') return undefined
+    try {
+      return ctx.configForms.get(ENTRY_ID)
+    } catch {
+      return undefined
+    }
+  }
+  const hasService = Boolean(ctx.configForms && typeof ctx.configForms.get === 'function')
   const mount = () =>
     ctx.slots.inject('plugins.bundle.config', () =>
       ctx.slots.register(
@@ -730,7 +839,10 @@ function apply(ctx) {
           key: PACKAGE_NAME,
           label: () => t().nav,
         },
-        (ownerProps) => (ownerProps && ownerProps.view === 'summary' ? null : page(ownerProps, form)),
+        (ownerProps) =>
+          ownerProps && ownerProps.view === 'summary'
+            ? null
+            : page(ownerProps, undefined, resolveForm, hasService),
       ),
     )
   if (ctx.configForms && typeof ctx.configForms.whileServed === 'function') {