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

package/README.en.md

@@ -19,17 +19,21 @@ 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.5.4
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.0
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.4
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.0
 ```
 
 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 and the "C++ Workflow" section under Settings share one page for file-header tags: `@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`, `@return`, `@throws` are required by default. The preview follows the switches, saving takes effect on the next skill read, and existing sources are never rewritten.
+
 ## Workspace gate
 
 Only one condition must hold before either skill appears: walking up from the current directory to the Git root, the path contains `.agents/skills/cpp-workflow-project/SKILL.md`.
@@ -103,9 +107,11 @@ npm ci
 npm test              # build, three-skill structural check, gate/environment/schema/comment tests
 npm run test:matrix   # real build matrix: 4 templates x 5 standards
 npm run pack:check    # inspect the npm package contents
+npm run ci            # replay the Ubuntu CI job: install, test, package check
+npm run ci:full       # ci plus the standard matrix; needs a POSIX host
 ```
 
-Source lives in `src/`; `npm run build` writes `lib/`. The structural check is `scripts/checking-skill-links.mjs`. Tests do not invoke a local compiler; the environment checks use fixed version strings. The standard matrix needs `cmake`, `ninja`, `perl`, and `clang++` (or the compiler named by `CXX`) on a POSIX host such as WSL, Linux, or macOS.
+Source lives in `src/`; `npm run build` writes `lib/`. The structural check is `scripts/checking-skill-links.mjs`. Tests do not invoke a local compiler; the environment checks use fixed version strings. The standard matrix needs `cmake`, `ninja`, `perl`, and `clang++` (or the compiler named by `CXX`) on a POSIX host such as WSL, Linux, or macOS. On Windows, run `npm run ci` first, then run `npm run ci:full` from WSL inside the checkout.
 
 ## License
 

package/README.md

@@ -19,17 +19,21 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.4
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.0
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.4
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.0
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
 
+### 设置
+
+插件页与设置导航里的「C++ 工程流程」共用一页，只管文件头标签：`@file` 固定为文件名，`@brief` 默认写出，`@author`、`@date`、`@copyright`、`@version` 默认关闭且只在填了非空值时才写出；`@param`、`@return`、`@throws` 默认要求。预览随开关即时更新，保存后下一次读取技能即生效，已有源码不会被改写。
+
 ## 工作区门禁
 
 一个会话里只需要满足一件事，技能就会出现：从当前目录向上、停在 git 根，沿途有 `.agents/skills/cpp-workflow-project/SKILL.md`。
@@ -103,9 +107,11 @@ npm ci
 npm test              # 构建、三技能结构检查、门禁/环境/schema/注释测试
 npm run test:matrix   # 四套模板 × 五档标准的真实构建矩阵
 npm run pack:check    # 核对 npm 包内容
+npm run ci            # 复现 Ubuntu CI：安装、测试、打包检查
+npm run ci:full       # 在 ci 之上再跑标准矩阵，需 POSIX 宿主
 ```
 
-源码在 `src/`，`npm run build` 生成 `lib/`。结构检查在 `scripts/checking-skill-links.mjs`；测试不调用本机编译器，环境检查用固定版本字符串。标准矩阵需要 POSIX 宿主上的 `cmake`、`ninja`、`perl` 和 `clang++`（或 `CXX` 指定的编译器），在 WSL/Linux/macOS 上运行。
+源码在 `src/`，`npm run build` 生成 `lib/`。结构检查在 `scripts/checking-skill-links.mjs`；测试不调用本机编译器，环境检查用固定版本字符串。标准矩阵需要 POSIX 宿主上的 `cmake`、`ninja`、`perl` 和 `clang++`（或 `CXX` 指定的编译器），在 WSL/Linux/macOS 上运行。Windows 上先跑 `npm run ci`，再从 WSL 进入仓库跑 `npm run ci:full`。
 
 ## 许可
 

package/lib/client.js

@@ -0,0 +1,570 @@
+// 由 scripts/building-client.mjs 生成，请改 src/comment-policy.ts 与 src/client/app.cjs.js。
+window.__ModuleLoader__.load({
+  id: "@chengzhao-dev/dsh-cpp-workflow",
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+
+/**
+ * 注释标签策略：设置页的预览、技能快照与检查器参数共用这一份。
+ *
+ * 配置只描述「写注释时默认带哪些标签」，不描述写法本身；写法在
+ * `skills/developing-cpp/references/comments.md`。设置页保存的值由宿主
+ * 写回插件 Config，服务端 `apply(ctx, config)` 用它生成本页快照与检查器参数。
+ *
+ * 这份文件被 `tsc` 编进 `lib/comment-policy.js`，打包客户端半侧时再内联进
+ * `lib/client.js`，所以只能依赖纯函数，不要引入 Node 或 React。
+ */
+/** 文件头标签。 */
+const HEADER_TAGS = ['brief', 'author', 'date', 'copyright', 'version'];
+/** 函数契约标签：开关决定是否要求写出。 */
+const CONTRACT_TAGS = ['param', 'returns', 'throws'];
+/** 折叠在「更多标签」里的可选标签：默认关闭。 */
+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 = {
+    brief: '@brief',
+    author: '@author',
+    date: '@date',
+    copyright: '@copyright',
+    version: '@version',
+    param: '@param',
+    returns: '@return',
+    throws: '@throws',
+    note: '@note',
+    see: '@see',
+    pre: '@pre',
+    post: '@post',
+    tparam: '@tparam',
+    retval: '@retval',
+};
+/** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
+const DEFAULT_CONFIG = {
+    brief: { enabled: true, value: '' },
+    author: { enabled: false, value: '' },
+    date: { enabled: false, value: '' },
+    copyright: { enabled: false, value: '' },
+    version: { enabled: false, value: '' },
+    param: true,
+    returns: true,
+    throws: true,
+    note: false,
+    see: false,
+    pre: false,
+    post: false,
+    tparam: false,
+    retval: false,
+};
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function flag(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+/**
+ * 把宿主给的值补齐成完整配置；缺字段、旧版本或手工改坏的配置都回到出厂值。
+ */
+function normalizeConfig(raw) {
+    const source = raw && typeof raw === 'object' ? raw : {};
+    const config = {};
+    for (const tag of HEADER_TAGS) {
+        const entry = source[tag] && typeof source[tag] === 'object' ? source[tag] : {};
+        config[tag] = {
+            enabled: flag(entry.enabled, DEFAULT_CONFIG[tag].enabled),
+            value: text(entry.value),
+        };
+    }
+    for (const tag of [...CONTRACT_TAGS, ...EXTRA_TAGS]) {
+        config[tag] = flag(source[tag], DEFAULT_CONFIG[tag]);
+    }
+    return config;
+}
+/**
+ * 按配置渲染文件头；`@file` 始终是传入的文件名。
+ */
+function renderFileHeader(raw, fileName) {
+    const config = normalizeConfig(raw);
+    const name = text(fileName) || 'board.h';
+    const lines = [`/// @file ${name}`];
+    if (config.brief.enabled) {
+        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}`);
+    }
+    return lines;
+}
+/**
+ * 设置页的预览：文件头 + 一段函数注释，只显示当前配置会写出的标签。
+ */
+function previewParts(raw, sampleName) {
+    const config = normalizeConfig(raw);
+    const header = renderFileHeader(config, sampleName || 'board.h');
+    const contract = [];
+    if (config.param)
+        contract.push('/// @param position 目标行列坐标。');
+    if (config.returns)
+        contract.push('/// @return 放置成功时为 true。');
+    if (config.throws)
+        contract.push('/// @throws std::out_of_range 坐标越界时抛出。');
+    const declaration = '[[nodiscard]] bool PlaceCell(CellPosition position, CellType cell_type);';
+    return { header, contract, declaration };
+}
+/**
+ * 设置页预览的纯文本形式；客户端半侧用同一份实现渲染 `<pre>`。
+ */
+function previewText(raw, sampleName) {
+    const { header, contract, declaration } = previewParts(raw, sampleName);
+    const lines = [...header, '///', '/// 放置成功返回 true；坐标越界或目标已占时返回 false。'];
+    if (contract.length > 0)
+        lines.push('///', ...contract);
+    lines.push(declaration);
+    return lines.join('\n');
+}
+/**
+ * 检查器参数：隐私标签要显式放行，@brief 被关掉时跳过摘要检查。
+ */
+function checkerArgs(raw) {
+    const config = normalizeConfig(raw);
+    const args = [];
+    if (!config.brief.enabled)
+        args.push('--no-brief');
+    for (const tag of PRIVACY_TAGS) {
+        if (config[tag].enabled && config[tag].value)
+            args.push('--allow-tag', tag);
+    }
+    return args;
+}
+/**
+ * 技能快照：`get()` 把它接在技能正文末尾，让代理看到当前 profile 的标签开关。
+ */
+function snapshotText(raw) {
+    const config = normalizeConfig(raw);
+    const on = [];
+    const off = [];
+    for (const tag of HEADER_TAGS) {
+        const entry = config[tag];
+        const label = entry.value ? `${TAG_LABEL[tag]} ${entry.value}` : TAG_LABEL[tag];
+        if (entry.enabled)
+            on.push(label);
+        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');
+}
+
+
+// 客户端半侧：设置导航里的「C++ 工程流程」页与插件页的配置卡片共用同一个组件。
+// 标签策略在本文件上方内联（由 scripts/building-client.mjs 从 src/comment-policy.js
+// 拼进来），所以预览、默认值与服务端快照永远同源；这里只做表单与排版。
+const React = require('react')
+const h = React.createElement
+
+const PACKAGE_NAME = '@chengzhao-dev/dsh-cpp-workflow'
+const SAMPLE_FILE = 'board.h'
+
+const STRINGS = {
+  zh: {
+    nav: 'C++ 工程流程',
+    title: '文档注释',
+    intro: '文件头与函数契约默认写出哪些 Doxygen 标签。配置只影响代理写注释的默认值，不改已有源码。',
+    header: '文件头',
+    contract: '函数契约',
+    extra: '更多标签',
+    extraHint: '默认关闭；需要时在单个函数上补写。',
+    file: '@file',
+    fileHint: '固定为当前文件名，不参与配置。',
+    emptyValue: '留空则由每个文件自己写',
+    on: '写出',
+    off: '不写',
+    preview: '预览',
+    previewHint: '示例文件名 board.h；预览随开关即时更新。',
+    save: '保存',
+    reset: '重置',
+    saved: '已保存，下一次读取技能时生效。',
+    rejected: '宿主拒绝了这次保存：配置可能已在别处修改，请重置后再试。',
+    unsaved: '有未保存的改动。',
+    loading: '正在读取配置…',
+    unreadable: '当前账户不能修改这份配置。',
+    readOnly: '此处只显示出厂值。要修改配置，请到「插件」页打开 dsh-cpp-workflow 的配置卡片。',
+    noForm: '这个入口没有可写表单，配置在插件页修改。',
+  },
+  en: {
+    nav: 'C++ Workflow',
+    title: 'Documentation comments',
+    intro: 'Which Doxygen tags the agent writes by default. This changes defaults only; existing sources are untouched.',
+    header: 'File header',
+    contract: 'Function contract',
+    extra: 'More tags',
+    extraHint: 'Off by default; add them per function when needed.',
+    file: '@file',
+    fileHint: 'Always the current file name; not configurable.',
+    emptyValue: 'Leave empty and each file writes its own',
+    on: 'Write',
+    off: 'Omit',
+    preview: 'Preview',
+    previewHint: 'Sample name board.h; the preview follows the switches.',
+    save: 'Save',
+    reset: 'Reset',
+    saved: 'Saved; the next skill read uses it.',
+    rejected: 'The host rejected the save: the config changed elsewhere. Reset and try again.',
+    unsaved: 'Unsaved changes.',
+    loading: 'Reading configuration…',
+    unreadable: 'This account cannot edit the configuration.',
+    readOnly: 'Showing factory defaults. Edit the dsh-cpp-workflow card on the Plugins page.',
+    noForm: 'This entry has no writable form; edit it on the Plugins page.',
+  },
+}
+
+function language() {
+  const value = typeof navigator !== 'undefined' && navigator.language ? navigator.language : 'zh'
+  return String(value).toLowerCase().startsWith('zh') ? 'zh' : 'en'
+}
+
+function t() {
+  return STRINGS[language()]
+}
+
+const palette = {
+  muted: 'var(--dsw-text-tertiary, #6b7280)',
+  line: 'var(--dsw-border-subtle, rgba(127, 127, 127, 0.24))',
+  surface: 'var(--dsw-surface-raised, rgba(127, 127, 127, 0.06))',
+  mono: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+}
+
+function rowStyle(extra) {
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 10,
+    padding: '7px 0',
+    borderBottom: `1px solid ${palette.line}`,
+    ...extra,
+  }
+}
+
+function hintStyle() {
+  return { margin: '2px 0 0', fontSize: 12, lineHeight: 1.5, color: palette.muted }
+}
+
+function Switch(props) {
+  return h(
+    'label',
+    { style: { display: 'inline-flex', alignItems: 'center', gap: 8, cursor: props.disabled ? 'default' : 'pointer', minWidth: 132 } },
+    h('input', {
+      type: 'checkbox',
+      checked: Boolean(props.checked),
+      disabled: Boolean(props.disabled),
+      onChange: (event) => props.onChange(event.target.checked),
+      style: { margin: 0 },
+    }),
+    h('span', { style: { fontSize: 13, fontFamily: palette.mono } }, props.label),
+  )
+}
+
+function HeaderTagRow(props) {
+  const s = props.strings
+  const entry = props.entry
+  return h(
+    'div',
+    { style: rowStyle({ flexWrap: 'wrap' }) },
+    h('div', { style: { flex: '1 1 280px', minWidth: 0 } },
+      h(Switch, {
+        label: TAG_LABEL[props.tag],
+        checked: entry.enabled,
+        onChange: (enabled) => props.onChange({ ...entry, enabled }),
+      }),
+      h('p', { style: hintStyle() }, TAG_TEXT[props.tag] || ''),
+    ),
+    h('input', {
+      type: 'text',
+      value: entry.value,
+      placeholder: s.emptyValue,
+      disabled: !entry.enabled,
+      'aria-label': `${TAG_LABEL[props.tag]} value`,
+      onChange: (event) => props.onChange({ ...entry, value: event.target.value }),
+      style: {
+        flex: '1 1 220px',
+        minWidth: 0,
+        fontSize: 13,
+        padding: '5px 8px',
+        borderRadius: 6,
+        border: `1px solid ${palette.line}`,
+        background: entry.enabled ? 'transparent' : palette.surface,
+        color: 'inherit',
+      },
+    }),
+  )
+}
+
+function Preview(props) {
+  const s = props.strings
+  const text = previewText(props.config, SAMPLE_FILE)
+  return h(
+    'section',
+    { 'aria-label': s.preview, style: { marginTop: 18 } },
+    h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600 } }, s.preview),
+    h('p', { style: hintStyle() }, s.previewHint),
+    h(
+      'pre',
+      {
+        style: {
+          margin: '8px 0 0',
+          padding: '10px 12px',
+          borderRadius: 8,
+          background: palette.surface,
+          border: `1px solid ${palette.line}`,
+          overflowX: 'auto',
+          fontSize: 12.5,
+          lineHeight: 1.65,
+          fontFamily: palette.mono,
+          whiteSpace: 'pre',
+        },
+      },
+      text,
+    ),
+  )
+}
+
+function diffOperations(draft, base) {
+  const operations = []
+  for (const key of Object.keys(DEFAULT_CONFIG)) {
+    const next = JSON.stringify(draft[key])
+    const previous = JSON.stringify(base[key])
+    if (next !== previous) operations.push({ op: 'set', path: [key], value: draft[key] })
+  }
+  return operations
+}
+
+function ConfigPage(props) {
+  const s = t()
+  const form = props.form
+  const initial = React.useMemo(() => normalizeConfig(form && form.state ? form.state.value : undefined), [])
+  const [draft, setDraft] = React.useState(initial)
+  const [base, setBase] = React.useState(initial)
+  const [dirty, setDirty] = React.useState(false)
+  const [busy, setBusy] = React.useState(false)
+  const [message, setMessage] = React.useState('')
+  const revision = form && form.state ? form.state.revision : undefined
+  const ready = Boolean(form && form.state && form.state.status === 'ready' && form.state.writable && form.state.mode === 'host')
+  const status = form && form.state ? form.state.status : 'missing'
+
+  React.useEffect(() => {
+    if (dirty || !form || !form.state || form.state.status !== 'ready') return
+    const next = normalizeConfig(form.state.value)
+    setBase(next)
+    setDraft(next)
+  }, [revision, status, dirty, form])
+
+  const update = (patch) => {
+    setDraft((current) => ({ ...current, ...patch }))
+    setDirty(true)
+    setMessage('')
+  }
+
+  const reset = () => {
+    setDraft(base)
+    setDirty(false)
+    setMessage('')
+  }
+
+  const save = async () => {
+    if (!ready || busy) return
+    const operations = diffOperations(draft, base)
+    if (operations.length === 0) return
+    setBusy(true)
+    try {
+      const accepted = await form.mutate(operations, revision)
+      if (accepted) {
+        setBase(draft)
+        setDirty(false)
+        setMessage(s.saved)
+      } else {
+        setMessage(s.rejected)
+      }
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : String(error))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const editable = Boolean(form)
+  const editableReady = editable && ready
+  const headerTags = ['brief', 'author', 'date', 'copyright', 'version']
+
+  return h(
+    'div',
+    { style: { display: 'flex', flexDirection: 'column', gap: 4, padding: '4px 0 12px', maxWidth: 720 } },
+    h('h3', { style: { margin: '0 0 2px', fontSize: 15, fontWeight: 600 } }, s.title),
+    h('p', { style: hintStyle() }, s.intro),
+    !editable
+      ? h('p', { role: 'status', style: { ...hintStyle(), color: 'inherit', marginTop: 8 } }, s.readOnly)
+      : null,
+    editable && !ready && status !== 'missing'
+      ? h('p', { role: 'status', style: hintStyle() }, status === 'loading' ? s.loading : s.unreadable)
+      : null,
+    h(
+      'fieldset',
+      { style: { margin: '14px 0 0', padding: 0, border: 0 } },
+      h('legend', { style: { padding: 0, fontSize: 13, fontWeight: 600 } }, s.header),
+      h(
+        'div',
+        { style: rowStyle() },
+        h(Switch, { label: s.file, checked: true, disabled: true, onChange: () => {} }),
+        h('p', { style: { ...hintStyle(), margin: 0 } }, s.fileHint),
+      ),
+      ...headerTags.map((tag) =>
+        h(HeaderTagRow, {
+          key: tag,
+          tag,
+          strings: s,
+          entry: draft[tag],
+          onChange: (entry) => update({ [tag]: entry }),
+        }),
+      ),
+    ),
+    h(
+      'fieldset',
+      { style: { margin: '18px 0 0', padding: 0, border: 0 } },
+      h('legend', { style: { padding: 0, fontSize: 13, fontWeight: 600 } }, s.contract),
+      h(
+        'div',
+        { style: { display: 'flex', flexWrap: 'wrap', gap: '6px 18px', padding: '8px 0 2px' } },
+        ...CONTRACT_TAGS.map((tag) =>
+          h(
+            'div',
+            { key: tag, style: { flex: '1 1 180px', minWidth: 180 } },
+            h(Switch, {
+              label: TAG_LABEL[tag],
+              checked: draft[tag],
+              onChange: (value) => update({ [tag]: value }),
+            }),
+            h('p', { style: hintStyle() }, TAG_TEXT[tag]),
+          ),
+        ),
+      ),
+    ),
+    h(
+      'details',
+      { style: { marginTop: 16, paddingTop: 10, borderTop: `1px solid ${palette.line}` } },
+      h('summary', { style: { cursor: 'pointer', fontSize: 13, fontWeight: 600 } }, s.extra),
+      h('p', { style: hintStyle() }, s.extraHint),
+      h(
+        'div',
+        { style: { display: 'flex', flexWrap: 'wrap', gap: '6px 18px', paddingTop: 4 } },
+        ...EXTRA_TAGS.map((tag) =>
+          h(
+            'div',
+            { key: tag, style: { flex: '1 1 180px', minWidth: 180 } },
+            h(Switch, {
+              label: TAG_LABEL[tag],
+              checked: draft[tag],
+              onChange: (value) => update({ [tag]: value }),
+            }),
+          ),
+        ),
+      ),
+    ),
+    h(Preview, { config: draft, strings: s }),
+    editable
+      ? h(
+          'div',
+          { style: { display: 'flex', alignItems: 'center', gap: 10, marginTop: 16, flexWrap: 'wrap' } },
+          h(
+            'button',
+            {
+              type: 'button',
+              onClick: save,
+              disabled: busy || !editableReady || !dirty,
+              style: { fontSize: 13, padding: '6px 14px', borderRadius: 6, cursor: 'pointer' },
+            },
+            s.save,
+          ),
+          h(
+            'button',
+            {
+              type: 'button',
+              onClick: reset,
+              disabled: busy || !dirty,
+              style: { fontSize: 13, padding: '6px 14px', borderRadius: 6, cursor: 'pointer' },
+            },
+            s.reset,
+          ),
+          h('p', { role: 'status', style: { ...hintStyle(), margin: 0, flex: '1 1 220px' } }, message || (dirty ? s.unsaved : '')),
+        )
+      : null,
+  )
+}
+
+function page(ownerProps, titled) {
+  const props = ownerProps || {}
+  return h(ConfigPage, { ...props, titled })
+}
+
+function apply(ctx) {
+  ctx.slots.inject('settings.section', () =>
+    ctx.slots.register(
+      {
+        name: 'settings.section',
+        id: 'cpp-workflow',
+        order: 60,
+        label: () => t().nav,
+      },
+      (ownerProps) => page(ownerProps, true),
+    ),
+  )
+  ctx.slots.inject('plugins.bundle.config', () =>
+    ctx.slots.register(
+      {
+        name: 'plugins.bundle.config',
+        key: PACKAGE_NAME,
+        label: () => t().nav,
+      },
+      (ownerProps) => (ownerProps && ownerProps.view === 'summary' ? null : page(ownerProps, false)),
+    ),
+  )
+}
+
+module.exports = {
+  name: PACKAGE_NAME,
+  inject: ['slots'],
+  apply,
+  ConfigPage,
+  diffOperations,
+  previewText,
+}
+
+    return module.exports
+  },
+})

package/lib/comment-policy.js

@@ -0,0 +1,177 @@
+/**
+ * 注释标签策略：设置页的预览、技能快照与检查器参数共用这一份。
+ *
+ * 配置只描述「写注释时默认带哪些标签」，不描述写法本身；写法在
+ * `skills/developing-cpp/references/comments.md`。设置页保存的值由宿主
+ * 写回插件 Config，服务端 `apply(ctx, config)` 用它生成本页快照与检查器参数。
+ *
+ * 这份文件被 `tsc` 编进 `lib/comment-policy.js`，打包客户端半侧时再内联进
+ * `lib/client.js`，所以只能依赖纯函数，不要引入 Node 或 React。
+ */
+/** 文件头标签。 */
+export const HEADER_TAGS = ['brief', 'author', 'date', 'copyright', 'version'];
+/** 函数契约标签：开关决定是否要求写出。 */
+export const CONTRACT_TAGS = ['param', 'returns', 'throws'];
+/** 折叠在「更多标签」里的可选标签：默认关闭。 */
+export const EXTRA_TAGS = ['note', 'see', 'pre', 'post', 'tparam', 'retval'];
+/** 只有用户主动填了非空值才放行的隐私标签。 */
+export const PRIVACY_TAGS = ['author', 'date', 'copyright', 'version'];
+/** 标签说明：设置页逐行显示，用作行的辅助文字。 */
+export const TAG_TEXT = {
+    brief: '一句话说明这个文件定义或实现什么',
+    author: '只在用户填了非空值时写出',
+    date: '只在用户填了非空值时写出',
+    copyright: '只在用户填了非空值时写出',
+    version: '只在用户填了非空值时写出',
+    param: '函数参数的含义、范围或所有权',
+    returns: '返回值的条件；返回类型自明时可以省略',
+    throws: '抛出的异常类型与条件；不抛异常的函数不写',
+    note: '调用方需要注意的补充说明',
+    see: '相关函数、类型或文档',
+    pre: '调用前必须成立的条件',
+    post: '调用后保证成立的条件',
+    tparam: '模板参数',
+    retval: '特定返回值的含义',
+};
+/** 开关型标签在设置页的标题。 */
+export const TAG_LABEL = {
+    brief: '@brief',
+    author: '@author',
+    date: '@date',
+    copyright: '@copyright',
+    version: '@version',
+    param: '@param',
+    returns: '@return',
+    throws: '@throws',
+    note: '@note',
+    see: '@see',
+    pre: '@pre',
+    post: '@post',
+    tparam: '@tparam',
+    retval: '@retval',
+};
+/** 出厂配置：文件头只留 @file 与 @brief，契约标签全开，隐私标签全关。 */
+export const DEFAULT_CONFIG = {
+    brief: { enabled: true, value: '' },
+    author: { enabled: false, value: '' },
+    date: { enabled: false, value: '' },
+    copyright: { enabled: false, value: '' },
+    version: { enabled: false, value: '' },
+    param: true,
+    returns: true,
+    throws: true,
+    note: false,
+    see: false,
+    pre: false,
+    post: false,
+    tparam: false,
+    retval: false,
+};
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function flag(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+/**
+ * 把宿主给的值补齐成完整配置；缺字段、旧版本或手工改坏的配置都回到出厂值。
+ */
+export function normalizeConfig(raw) {
+    const source = raw && typeof raw === 'object' ? raw : {};
+    const config = {};
+    for (const tag of HEADER_TAGS) {
+        const entry = source[tag] && typeof source[tag] === 'object' ? source[tag] : {};
+        config[tag] = {
+            enabled: flag(entry.enabled, DEFAULT_CONFIG[tag].enabled),
+            value: text(entry.value),
+        };
+    }
+    for (const tag of [...CONTRACT_TAGS, ...EXTRA_TAGS]) {
+        config[tag] = flag(source[tag], DEFAULT_CONFIG[tag]);
+    }
+    return config;
+}
+/**
+ * 按配置渲染文件头；`@file` 始终是传入的文件名。
+ */
+export function renderFileHeader(raw, fileName) {
+    const config = normalizeConfig(raw);
+    const name = text(fileName) || 'board.h';
+    const lines = [`/// @file ${name}`];
+    if (config.brief.enabled) {
+        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}`);
+    }
+    return lines;
+}
+/**
+ * 设置页的预览：文件头 + 一段函数注释，只显示当前配置会写出的标签。
+ */
+export function previewParts(raw, sampleName) {
+    const config = normalizeConfig(raw);
+    const header = renderFileHeader(config, sampleName || 'board.h');
+    const contract = [];
+    if (config.param)
+        contract.push('/// @param position 目标行列坐标。');
+    if (config.returns)
+        contract.push('/// @return 放置成功时为 true。');
+    if (config.throws)
+        contract.push('/// @throws std::out_of_range 坐标越界时抛出。');
+    const declaration = '[[nodiscard]] bool PlaceCell(CellPosition position, CellType cell_type);';
+    return { header, contract, declaration };
+}
+/**
+ * 设置页预览的纯文本形式；客户端半侧用同一份实现渲染 `<pre>`。
+ */
+export function previewText(raw, sampleName) {
+    const { header, contract, declaration } = previewParts(raw, sampleName);
+    const lines = [...header, '///', '/// 放置成功返回 true；坐标越界或目标已占时返回 false。'];
+    if (contract.length > 0)
+        lines.push('///', ...contract);
+    lines.push(declaration);
+    return lines.join('\n');
+}
+/**
+ * 检查器参数：隐私标签要显式放行，@brief 被关掉时跳过摘要检查。
+ */
+export function checkerArgs(raw) {
+    const config = normalizeConfig(raw);
+    const args = [];
+    if (!config.brief.enabled)
+        args.push('--no-brief');
+    for (const tag of PRIVACY_TAGS) {
+        if (config[tag].enabled && config[tag].value)
+            args.push('--allow-tag', tag);
+    }
+    return args;
+}
+/**
+ * 技能快照：`get()` 把它接在技能正文末尾，让代理看到当前 profile 的标签开关。
+ */
+export function snapshotText(raw) {
+    const config = normalizeConfig(raw);
+    const on = [];
+    const off = [];
+    for (const tag of HEADER_TAGS) {
+        const entry = config[tag];
+        const label = entry.value ? `${TAG_LABEL[tag]} ${entry.value}` : TAG_LABEL[tag];
+        if (entry.enabled)
+            on.push(label);
+        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');
+}

package/lib/index.js

@@ -21,9 +21,35 @@
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import Schema from '@deepseek-ai/schemastery';
 import { isCppWorkflowWorkspace } from './workspace.js';
+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(),
+});
+export const Config = Schema.object({
+    brief: Schema.object({
+        enabled: Schema.boolean().default(true).volatile(),
+        value: Schema.string().default('').volatile(),
+    }),
+    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(),
+});
 const PROVIDER = 'dsh-cpp-workflow';
 const RANK = 550;
 const KNOWN_SKILLS = new Set(['building-cpp', 'configuring-cmake', 'developing-cpp']);
@@ -150,7 +176,7 @@ async function listSkills(options = {}) {
     candidates.sort((a, b) => a.name.localeCompare(b.name));
     return candidates;
 }
-async function getSkill(candidate, options = {}) {
+async function getSkill(candidate, options = {}, commentConfig = undefined) {
     if (options.signal?.aborted)
         return undefined;
     if (!candidate || candidate.provider !== PROVIDER)
@@ -190,13 +216,18 @@ async function getSkill(candidate, options = {}) {
         resourceBase: { kind: 'directory', path: resolved },
         path: path.join(resolved, 'SKILL.md'),
         ...(candidate.metadata ? { metadata: candidate.metadata } : {}),
-        content: body.trim(),
+        // 标签开关只跟注释技能有关，另两个技能的正文保持原样。
+        content: candidate.name === 'developing-cpp'
+            ? `${body.trim()}\n\n${snapshotText(commentConfig)}`
+            : body.trim(),
     };
 }
-export function apply(ctx) {
+export function apply(ctx, config = undefined) {
+    // 配置决定注释标签的默认集合；快照随每次 get() 读出，改配置立即生效。
+    const resolved = normalizeConfig(config);
     ctx.skills.registerProvider(() => ({
         name: PROVIDER,
         list: listSkills,
-        get: getSkill,
+        get: (candidate, options) => getSkill(candidate, options, resolved),
     }));
 }

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "C++ Workflow",
-    "description": "Four source steps, three CMake steps, and three build steps for C++11–C++23 projects (C++23 by default), checked against the environment the project declares."
+    "description": "Write C++ sources, configure CMake, and build with Clang; /// Doxygen comments, with file-header tags you can set in Settings."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "C++ 工程流程",
-    "description": "用源码四步、CMake 三步与构建三步推进 C++11–C++23 工程（默认 C++23），并在项目声明的环境组合里核对构建与 clang 工具链。"
+    "description": "写 C++ 源码、配 CMake、用 Clang 构建；文档注释统一为 /// Doxygen，文件头标签可在设置里改。"
   }
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.5.4",
-  "description": "C++11–C++23 工程流程技能包：源码四步、CMake 三步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
+  "version": "0.6.0",
+  "description": "写 C++ 源码、配 CMake、用 Clang 构建；文档注释统一为 /// Doxygen，文件头标签可在设置里改。 · Write C++ sources, configure CMake, and build with Clang; /// Doxygen comments, with file-header tags you can change in Settings.",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
@@ -28,11 +29,17 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    },
     "catalog": {
       "category": "skill",
       "summary": {
-        "zh": "按项目声明的环境组合，推进 C++11–C++23 源码与构建流程",
-        "en": "Advance C++11–C++23 source and build work with a project-declared environment"
+        "zh": "写 C++ 源码、配 CMake、用 Clang 构建；文档注释统一为 /// Doxygen，文件头标签可在设置里改。",
+        "en": "Write C++ sources, configure CMake, and build with Clang; /// Doxygen comments, with file-header tags you can set in Settings."
       },
       "capabilities": [
         "skills"
@@ -41,8 +48,10 @@
   },
   "icon": "./icon.svg",
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node scripts/checking-skill-links.mjs && node skills/building-cpp/scripts/checking-encoding.mjs --quiet && node scripts/checking-github-workflows.mjs && node --test tests/*.test.mjs",
+    "build": "tsc -p tsconfig.json && node scripts/building-client.mjs",
+    "test": "npm run build && node scripts/building-client.mjs --check && node scripts/checking-skill-links.mjs && node skills/building-cpp/scripts/checking-encoding.mjs --quiet && node scripts/checking-github-workflows.mjs && node --test tests/*.test.mjs",
+    "ci": "npm ci && npm test && npm run pack:check",
+    "ci:full": "npm run ci && npm run test:matrix",
     "check:encoding": "node skills/building-cpp/scripts/checking-encoding.mjs",
     "check:workflows": "node scripts/checking-github-workflows.mjs",
     "test:matrix": "bash scripts/checking-standard-matrix.sh",
@@ -77,6 +86,9 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-skill": ">=0.2.0-rc.1 <0.3.0-0"
   },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-skill": ">=0.2.0-rc.1 <0.3.0-0",
     "@types/node": "^22.20.5",

package/skills/developing-cpp/examples/comments-declaration.md

@@ -14,11 +14,10 @@
 **好**：
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// board.h - 定义井字棋棋盘、格子坐标与格子类型。
-//
-// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与整盘清空。
-//===----------------------------------------------------------------------===//
+/// @file board.h
+/// @brief 定义井字棋棋盘、格子坐标与格子类型。
+///
+/// 棋盘保存九个棋盘格子的状态，提供查询、落子与清空棋盘。
 ```
 
 文件头只介绍这个文件里有什么，不写作者和变更史，也不把读者指去另一个文件。
@@ -310,11 +309,10 @@ Standard: Latest
 **好**：
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// board.h - 棋盘状态与规则判断
-//
-// 定义 Board 的查询、落子与整盘清空。
-//===----------------------------------------------------------------------===//
+/// @file board.h
+/// @brief 棋盘状态与规则判断。
+///
+/// 定义 Board 的查询、落子与清空棋盘。
 ```
 
 变更史进提交说明，外部资料进文档，团队流程进规范文件；注释只写这个文件或这个类型自己的内容，不把读者指去别的文件。

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

@@ -82,7 +82,7 @@ GameResult result_ = GameResult::kInProgress;
 
 ### 实现：阶段边界与为什么
 
-`.cpp` / `.cc` 里，重要函数按空行分段，每一段上方写一句 `//`。句子写边界、失败后果或为什么停在这里，不把下一行条件翻译一遍；`IsWin` 这种单行函数不配注释。只写删掉会让下一次修改得到错误结果、而代码本身看不出的内容。
+`.cpp` / `.cc` 里，重要函数按空行分段，每一段上方写一句 `///`。句子写边界、失败后果或为什么停在这里，不把下一行条件翻译一遍；`IsWin` 这种单行函数不配注释。只写删掉会让下一次修改得到错误结果、而代码本身看不出的内容。
 
 大型工程的共识是解释意图而不是逐步翻译：[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Implementation_Comments) 要求注释解释代码在做什么，不描述代码本身；[LLVM Coding Standards](https://www.llvm.org/docs/CodingStandards.html#commenting) 要求写意图与理由。阶段注释写的就是这两类信息。
 
@@ -100,7 +100,7 @@ GameResult result_ = GameResult::kInProgress;
 
 | 层 | 行数 | 第一句 | 写什么 |
 | --- | --- | --- | --- |
-| 文件头 | 3–6 | 文件名 - 这个文件定义或实现什么 | 本文件由哪几部分组成 |
+| 文件头 | 3–7 | `@file` 文件名 + `@brief` 一句话 | 本文件由哪几部分组成 |
 | 类型注释 | 2–14 | 名词短语：这个类型或取值是什么 | 只有类的不变量 |
 | 特殊成员 | 1–3 | 标签（默认/拷贝/移动构造函数、析构函数） | 后置条件或职责 |
 | 函数注释 | 3–10 | 正常返回什么、失败时返回或抛什么、检查什么 | 参数与失败方式 |
@@ -109,29 +109,28 @@ GameResult result_ = GameResult::kInProgress;
 
 ## 布局：放在哪一层、哪一行
 
-- `///` 只给声明：头文件里的类型、函数、枚举值、公开与私有数据成员。数据成员的主注释写在上一行；行尾 `///<` 只用于枚举项和 `struct` 的短字段。调用方和 Doxygen 从这里取契约。
-- `//` 给实现：函数体内的阶段与边界说明、局部变量、文件头横幅、配置文件的说明。
-- 不给局部变量和函数体里的语句写 `///`；文件头也不写成 `///`，否则编辑器会把它挂到紧随其后的第一个声明上。
-- 判断看一句话写的是「调用方要遵守的承诺」还是「维护者要知道的写法」：前者用 `///`，后者用 `//`。
+- `///` 给声明与文件头：头文件里的类型、函数、枚举值、公开与私有数据成员，以及文件头的 `@file`/`@brief` 块。数据成员的主注释写在上一行；行尾 `///<` 只用于枚举项和 `struct` 的短字段。调用方和 Doxygen 从这里取契约。
+- `///` 也给实现：函数体内的阶段与边界说明、局部变量，一律用 `///`，不混 `//`。
+- `//` 只留给工具指令与别种文件：`// NOLINTNEXTLINE(...)`、`#endif  // MACRO` 这类要被工具读取的标记，以及 CMake、YAML 等非 C++ 文件。
+- 判断看位置：声明写契约，实现写理由，两者都用 `///`；`//` 不再表示「实现注释」。
 - 位置固定：文件头在最上方；类型注释紧贴类型声明；特殊成员（构造、析构、拷贝与移动）排在其他函数之前；函数注释紧贴函数声明；数据成员的主注释紧贴声明上一行，不写行尾补充。
 - 类数据成员（含私有）的主注释用 `///`；行尾 `///<` 只给枚举项和 `struct` 的短字段。
 - 注释和它说明的声明之间不留空行；同一个声明块内，空行只用来分组。
 
 ### 文件头
 
-每个手写源文件开头写一段文件头：第一行是「文件名 - 本文件定义或实现什么」，后面只写本文件自己的组成部分或边界。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
+每个手写源文件开头写一段 doxygen 文件头：第一行 `/// @file <文件名>`，第二行 `/// @brief` 一句话说明这个文件定义或实现什么，用一行 `///` 隔开后，只写本文件自己的组成部分或边界。`@file` 的参数必须与文件名逐字相同，检查器会核对。`@brief` 默认写出；`@author`、`@date`、`@copyright`、`@version` 默认不写，只有插件配置里打开并填了非空值才写出，作者、年份和变更史不写进源码。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// board.h - 定义井字棋棋盘、格子坐标与格子类型。
-//
-// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与整盘清空。
-//===----------------------------------------------------------------------===//
+/// @file board.h
+/// @brief 定义井字棋棋盘、格子坐标与格子类型。
+///
+/// 棋盘保存九个棋盘格子的状态，提供查询、落子与清空棋盘。
 ```
 
-- C++ 用 `//`，CMake 用 `#`，YAML/JSON 用 `#` 或 `//`。
+- C++ 源文件用以上格式；CMake 用 `#`，YAML/JSON 用 `#`。
 - 超过约 200 行的文件用章节横幅分组，组名是读者要跳转的锚点；一个文件不超过 8 个横幅。
-- 文件头 3–6 行；第一行点文件名，后面只写本文件的范围与组成，不写实现步骤、作者和变更史。
+- 文件头 3–7 行；`@file` 与 `@brief` 各占一行，后面只写本文件的范围与组成，不写实现步骤、作者和变更史。
 
 ## 排版：符号、宽度、横幅与标签
 
@@ -143,6 +142,7 @@ GameResult result_ = GameResult::kInProgress;
 - `.clang-format`、`.clang-tidy`、`.clangd`、CMake 的配置项旁边写「为什么这样设」，不写「这一项是什么」；配置注释贴在被解释的键上方。
 - 禁止：大段表格、装饰图案、表情；外部资料路径、跨仓库引用、团队流程；注释掉的代码；注释元叙述（「其余内容见某处」「两处不重复」）。
 - `///`、`@param`、横幅不进入 `.qmd`、YAML、CSS。
+- C++ 源文件的说明性注释一律 `///`，实现区不与 `//` 混用；`//` 只留给文件头横幅边框与被引用的配置行。
 
 ## 润色：删复述，统一句式
 

package/skills/developing-cpp/references/file-template.md

@@ -46,11 +46,10 @@
 5. `#endif  // MACRO`
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// thing_table.h - 定义 ThingTable 与它用到的状态。
-//
-// 头文件放常量、枚举、结构体与类声明。
-//===----------------------------------------------------------------------===//
+/// @file thing_table.h
+/// @brief 定义 ThingTable 与它用到的状态。
+///
+/// 头文件放常量、枚举、结构体与类声明。
 
 #ifndef PROJECT_PATH_FILE_H_
 #define PROJECT_PATH_FILE_H_
@@ -99,9 +98,8 @@ class ThingTable {
 4. 命名空间与定义
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// thing_table.cpp - 实现 ThingTable 的添加与查询。
-//===----------------------------------------------------------------------===//
+/// @file thing_table.cpp
+/// @brief 实现 ThingTable 的添加与查询。
 
 #include "project/path/thing.h"
 

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

@@ -25,8 +25,12 @@ const SKIP_DIR = new Set([
   '.tmp', 'temp', 'third_party', 'third-party', 'external', 'vendor', 'deps', 'cmake-build-debug',
   'cmake-build-release', '.vs', '.idea',
 ])
-const FORBIDDEN_TAGS = ['@returns', '@brief', '@details', '@author', '@since', '@todo', '@date', '@file', '@copyright', '@version']
+const STATIC_FORBIDDEN_TAGS = ['@returns', '@details', '@since', '@todo']
+const PRIVACY_TAGS = ['@author', '@date', '@copyright', '@version']
+const FORBIDDEN_TAGS = [...STATIC_FORBIDDEN_TAGS, ...PRIVACY_TAGS]
 const BANNER = /^\/\/=+-+=+\/\/$/
+const DOXY_FILE = /^\/\/\/\s*@file\s+\S/
+const DOXY_BRIEF = /^\/\/\/\s*@brief\s+\S/
 const MEMBER_LIST = /提供[^。]{0,40}、[^。]{0,40}(的功能|的能力|的接口)|功能[:：]/
 const RATIONALE = /而不是|而非|代价.{0,4}忽略|只留一份|与其|比.{0,12}更|更(?:安全|快|清楚|直接|好写|难写)/
 const FORWARD_REF = /(?:留在|归|交给|由)\s*`?[A-Z][A-Za-z0-9_]*`?/
@@ -38,12 +42,12 @@ const DECL_KEYWORDS = /^(class|struct|union|enum|namespace|using|typedef|templat
 
 function usage(message) {
   if (message) process.stderr.write(`错误：${message}\n`)
-  process.stderr.write('用法：node checking-comments.mjs [--root DIR] [--width N] [--banner-width N] [--no-header] [--json] [--quiet]\n')
+  process.stderr.write('用法：node checking-comments.mjs [--root DIR] [--width N] [--banner-width N] [--no-header] [--no-brief] [--allow-tag TAG] [--json] [--quiet]\n')
   return EXIT.usage
 }
 
 function parseArgs(argv) {
-  const options = { root: undefined, width: 80, bannerWidth: 80, widthExplicit: false, bannerWidthExplicit: false, requireHeader: true, json: false, quiet: false }
+  const options = { root: undefined, width: 80, bannerWidth: 80, widthExplicit: false, bannerWidthExplicit: false, requireHeader: true, requireBrief: true, allowTags: new Set(), json: false, quiet: false }
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]
     if (arg === '--root') {
@@ -59,6 +63,13 @@ function parseArgs(argv) {
       index += 1
     } else if (arg === '--no-header') {
       options.requireHeader = false
+    } else if (arg === '--no-brief') {
+      options.requireBrief = false
+    } else if (arg === '--allow-tag') {
+      const value = argv[index + 1]
+      if (!value) throw new Error('--allow-tag 需要标签名，例如 author')
+      options.allowTags.add(value.replace(/^@/, ''))
+      index += 1
     } else if (arg === '--json') {
       options.json = true
     } else if (arg === '--quiet') {
@@ -205,16 +216,35 @@ export function checkText(text, options = {}) {
   const inClass = classMemberLines(lines)
 
   const firstContent = lines.findIndex((line) => line.trim() !== '')
-  if (requireHeader && firstContent !== -1 && !BANNER.test(lines[firstContent].trim())) {
-    add(firstContent + 1, 'header-missing', '文件开头缺少文件头横幅（//===...===//）')
+  const firstTrimmed = firstContent === -1 ? '' : lines[firstContent].trim()
+  const hasDoxyHeader = DOXY_FILE.test(firstTrimmed)
+  let doxyHeaderEnd = -1
+  if (hasDoxyHeader) {
+    doxyHeaderEnd = firstContent
+    while (doxyHeaderEnd + 1 < lines.length && lines[doxyHeaderEnd + 1].trim().startsWith('///')) doxyHeaderEnd += 1
+  }
+  if (requireHeader && firstContent !== -1 && !BANNER.test(firstTrimmed) && !hasDoxyHeader) {
+    add(firstContent + 1, 'header-missing', '文件开头缺少文件头：写 /// @file <文件名>，下一行写 /// @brief')
   }
-  if (firstContent !== -1 && BANNER.test(lines[firstContent].trim())) {
+  if (firstContent !== -1 && (BANNER.test(firstTrimmed) || hasDoxyHeader)) {
     const own = options.fileName ? options.fileName.split(/[\\/]/).pop() : ''
+    const bannerHeader = BANNER.test(firstTrimmed)
+    if (hasDoxyHeader && own) {
+      const declared = /@file\s+(\S+)/.exec(lines[firstContent].trim())
+      if (declared && declared[1] !== own) {
+        add(firstContent + 1, 'header-file-name', `文件头写的是 ${declared[1]}，本文件是 ${own}：@file 必须等于文件名`)
+      }
+    }
+    if (hasDoxyHeader && options.requireBrief !== false && !DOXY_BRIEF.test((lines[firstContent + 1] ?? '').trim())) {
+      add(firstContent + 2, 'header-brief', '文件头第二行缺少 /// @brief 一句话说明')
+    }
     for (let index = firstContent + 1; index < lines.length; index += 1) {
       const trimmed = lines[index].trim()
-      if (BANNER.test(trimmed) || !trimmed.startsWith('//')) break
+      if (bannerHeader ? BANNER.test(trimmed) || !trimmed.startsWith('//') : !trimmed.startsWith('///')) break
       const names = trimmed.match(/\b[A-Za-z0-9_-]+\.(?:h|hpp|cpp|cc)\b/g) ?? []
-      for (const name of names) {
+      const fileMatches = trimmed.match(/@file\s+(\S+)/)
+      const namesToCheck = fileMatches ? names.filter((name) => name !== fileMatches[1]) : names
+      for (const name of namesToCheck) {
         if (name !== own) add(index + 1, 'header-cross-file', `文件头提到了别的源文件 ${name}：只介绍本文件，删掉跨文件句子`)
       }
       if (/\bapps\//.test(trimmed)) add(index + 1, 'header-cross-file', '文件头指向了另一个目录：只介绍本文件')
@@ -232,12 +262,17 @@ export function checkText(text, options = {}) {
     if (trimmed.startsWith('///') || (trimmed.startsWith('//') && !trimmed.startsWith('//!'))) {
       if (displayWidth(trimmed) > width) add(index + 1, 'comment-width', `注释行 ${displayWidth(trimmed)} 列，超过 ${width} 列`)
       for (const tag of FORBIDDEN_TAGS) {
+        if (options.allowTags?.has(tag.slice(1))) continue
         if (trimmed.includes(tag)) add(index + 1, 'forbidden-tag', `禁止使用 ${tag}，按 references/comments.md 的标签表改写`)
       }
     }
   }
 
   for (let index = 0; index < lines.length; index += 1) {
+    if (doxyHeaderEnd !== -1 && index <= doxyHeaderEnd) {
+      index = doxyHeaderEnd
+      continue
+    }
     if (!lines[index].trim().startsWith('///')) continue
     if (lines[index].trim().startsWith('///<')) continue
     const start = index
@@ -410,6 +445,11 @@ function main(argv) {
   }
   if (options.help) return usage()
   const root = options.root ? path.resolve(options.root) : process.cwd()
+  try {
+    statSync(root)
+  } catch {
+    return usage(`根目录不存在或无法读取：${root}`)
+  }
   const columnLimit = readColumnLimit(root)
   if (columnLimit !== undefined) {
     if (!options.widthExplicit) options.width = columnLimit

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

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