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

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.5
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.1
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.5
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.1
 ```
 
 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`.

package/README.md

@@ -19,17 +19,21 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.5
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.1
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.5
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.1
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
 
+### 设置
+
+插件页与设置导航里的「C++ 工程流程」共用一页，只管文件头标签：`@file` 固定为文件名，`@brief` 默认写出，`@author`、`@date`、`@copyright`、`@version` 默认关闭且只在填了非空值时才写出；`@param`、`@return`、`@throws` 默认要求。预览随开关即时更新，保存后下一次读取技能即生效，已有源码不会被改写。
+
 ## 工作区门禁
 
 一个会话里只需要满足一件事，技能就会出现：从当前目录向上、停在 git 根，沿途有 `.agents/skills/cpp-workflow-project/SKILL.md`。

package/lib/client.js

@@ -0,0 +1,757 @@
+// 由 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',
+};
+/** 预览里的示例摘要：用户没填 @brief 时用它，避免预览出现空标签。 */
+const SAMPLE_BRIEF = '定义井字棋棋盘、格子坐标与格子类型。';
+/** 出厂配置：文件头只留 @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');
+    // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
+    const briefIndex = header.indexOf('/// @brief');
+    if (briefIndex !== -1)
+        header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
+    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: '文件头',
+    headerHint: '每个手写源文件开头的一段 ///；带值的标签填写后写出，@brief 留空由文件自述。',
+    contract: '函数契约',
+    contractHint: '声明注释里的参数与失败方式；关闭后不再要求写出这些标签。',
+    extra: '更多标签',
+    extraHint: '默认关闭；需要时在单个函数上补写。',
+    file: '@file',
+    fixed: '自动',
+    fileHint: '固定为当前文件名，不参与配置。',
+    briefHint: '一句话说明本文件定义或实现什么；留空则由每个文件自己写。',
+    authorHint: '作者署名；留空不写。',
+    dateHint: '创建或修改日期；留空不写。',
+    copyrightHint: '版权声明；留空不写。',
+    versionHint: '文件版本号；留空不写。',
+    emptyValue: '留空不写',
+    briefEmpty: '留空则由文件自述',
+    preview: '预览',
+    previewHint: '示例文件名 board.h；预览随开关即时更新。',
+    save: '保存',
+    reset: '重置',
+    saved: '已保存，下一次读取技能时生效。',
+    rejected: '宿主拒绝了这次保存：配置可能已在别处修改，请重置后再试。',
+    unsaved: '有未保存的改动。',
+    loading: '正在读取配置…',
+    unreadable: '当前账户不能修改这份配置。',
+    readOnly: '此处只显示出厂值。要修改配置，请到「插件」页打开 dsh-cpp-workflow 的配置卡片。',
+    openSettings: '打开插件配置',
+    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',
+    headerHint: 'The /// block at the top of every hand-written source; value tags are written only when filled.',
+    contract: 'Function contract',
+    contractHint: 'Parameter and failure tags in declaration comments; turning one off stops requiring it.',
+    extra: 'More tags',
+    extraHint: 'Off by default; add them per function when needed.',
+    file: '@file',
+    fixed: 'Auto',
+    fileHint: 'Always the current file name; not configurable.',
+    briefHint: 'One sentence about what this file defines; leave empty and each file writes its own.',
+    authorHint: 'Author credit; left empty, omitted.',
+    dateHint: 'Creation or change date; left empty, omitted.',
+    copyrightHint: 'Copyright notice; left empty, omitted.',
+    versionHint: 'File version; left empty, omitted.',
+    emptyValue: 'Empty means omit',
+    briefEmpty: 'Empty: the file writes its own',
+    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.',
+    openSettings: 'Open plugin settings',
+    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 = {
+  label: 'var(--dsw-alias-label-primary, inherit)',
+  muted: 'var(--dsw-alias-label-secondary, #6b7280)',
+  faint: 'var(--dsw-alias-label-tertiary, #8b93a1)',
+  line: 'var(--dsw-alias-border-l2, rgba(127, 127, 127, 0.24))',
+  surface: 'var(--dsw-alias-bg-layer-2, rgba(127, 127, 127, 0.06))',
+  field: 'var(--dsw-alias-bg-layer-1, rgba(127, 127, 127, 0.04))',
+  brand: 'var(--dsw-alias-brand-primary, #4f6bed)',
+  mono: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+}
+
+const hintStyle = () => ({ margin: '2px 0 0', fontSize: 12, lineHeight: 1.55, color: palette.muted })
+const labelCellStyle = () => ({
+  padding: '10px 0',
+  fontFamily: palette.mono,
+  fontSize: 12.5,
+  lineHeight: '20px',
+  color: palette.label,
+  whiteSpace: 'nowrap',
+  borderBottom: `1px solid ${palette.line}`,
+})
+const controlCellStyle = () => ({
+  padding: '10px 0',
+  minWidth: 0,
+  borderBottom: `1px solid ${palette.line}`,
+})
+const gridStyle = () => ({ display: 'grid', gridTemplateColumns: '92px minmax(0, 1fr)', columnGap: 14 })
+
+function Toggle(props) {
+  return h(
+    'button',
+    {
+      type: 'button',
+      role: 'switch',
+      'aria-checked': Boolean(props.checked),
+      'aria-label': props.label,
+      disabled: Boolean(props.disabled),
+      onClick: () => props.onChange(!props.checked),
+      style: {
+        flex: 'none',
+        width: 34,
+        height: 20,
+        padding: 0,
+        border: 0,
+        borderRadius: 999,
+        position: 'relative',
+        cursor: props.disabled ? 'default' : 'pointer',
+        opacity: props.disabled ? 0.5 : 1,
+        background: props.checked ? palette.brand : 'var(--dsw-alias-bg-layer-4, rgba(127, 127, 127, 0.35))',
+        transition: 'background-color 0.15s ease',
+      },
+    },
+    h('span', {
+      'aria-hidden': 'true',
+      style: {
+        position: 'absolute',
+        top: 2,
+        left: props.checked ? 16 : 2,
+        width: 16,
+        height: 16,
+        borderRadius: '50%',
+        background: '#fff',
+        boxShadow: '0 1px 2px rgba(0, 0, 0, 0.25)',
+        transition: 'left 0.15s ease',
+      },
+    }),
+  )
+}
+
+function TagRow(props) {
+  const s = props.strings
+  return [
+    h('div', { key: `${props.tag}-label`, style: labelCellStyle() }, props.label),
+    h(
+      'div',
+      { key: `${props.tag}-control`, style: controlCellStyle() },
+      h(
+        'div',
+        { style: { display: 'flex', alignItems: 'center', gap: 10, minHeight: 22, flexWrap: 'wrap' } },
+        props.control,
+      ),
+      props.hint ? h('p', { style: hintStyle() }, props.hint) : null,
+    ),
+  ]
+}
+
+function ValueRow(props) {
+  const s = props.strings
+  return h(TagRow, {
+    tag: props.tag,
+    label: TAG_LABEL[props.tag],
+    strings: s,
+    hint: props.hint,
+    control: [
+      h(Toggle, {
+        key: 'toggle',
+        label: props.label || TAG_LABEL[props.tag],
+        checked: props.entry.enabled,
+        disabled: props.disabled,
+        onChange: (enabled) => !props.disabled && props.onChange({ ...props.entry, enabled }),
+      }),
+      h('input', {
+        key: 'input',
+        type: 'text',
+        value: props.entry.value,
+        placeholder: props.tag === 'brief' ? s.briefEmpty : s.emptyValue,
+        disabled: props.disabled || !props.entry.enabled,
+        'aria-label': TAG_LABEL[props.tag],
+        onChange: (event) => props.onChange({ ...props.entry, value: event.target.value }),
+        style: {
+          flex: '1 1 180px',
+          minWidth: 0,
+          maxWidth: 320,
+          fontSize: 13,
+          padding: '4px 8px',
+          borderRadius: 6,
+          border: `1px solid ${palette.line}`,
+          background: props.entry.enabled && !props.disabled ? palette.field : 'transparent',
+          color: props.entry.enabled ? 'inherit' : palette.muted,
+          fontFamily: palette.mono,
+        },
+      }),
+    ],
+  })
+}
+
+function FlagRow(props) {
+  return h(TagRow, {
+    tag: props.tag,
+    label: TAG_LABEL[props.tag],
+    strings: props.strings,
+    hint: props.hint,
+    control: h(Toggle, {
+      label: TAG_LABEL[props.tag],
+      checked: Boolean(props.checked),
+      disabled: props.disabled,
+      onChange: (value) => !props.disabled && props.onChange(value),
+    }),
+  })
+}
+
+function Preview(props) {
+  const s = props.strings
+  return h(
+    'section',
+    { 'aria-label': s.preview, style: { marginTop: 20 } },
+    h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600, color: palette.label } }, s.preview),
+    h('p', { style: hintStyle() }, s.previewHint),
+    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',
+          color: palette.label,
+        },
+      },
+      previewText(props.config, SAMPLE_FILE),
+    ),
+  )
+}
+
+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 header = [
+    { tag: 'brief', hint: s.briefHint },
+    { tag: 'author', hint: s.authorHint },
+    { tag: 'date', hint: s.dateHint },
+    { tag: 'copyright', hint: s.copyrightHint },
+    { tag: 'version', hint: s.versionHint },
+  ]
+  const contractHints = { param: TAG_TEXT.param, returns: TAG_TEXT.returns, throws: TAG_TEXT.throws }
+  const extraHints = { note: TAG_TEXT.note, see: TAG_TEXT.see, pre: TAG_TEXT.pre, post: TAG_TEXT.post, tparam: TAG_TEXT.tparam, retval: TAG_TEXT.retval }
+
+  return h(
+    'div',
+    { style: { display: 'flex', flexDirection: 'column', padding: '4px 0 12px', maxWidth: 720, color: palette.label } },
+    h('h3', { style: { margin: '0 0 4px', fontSize: 15, fontWeight: 600 } }, s.title),
+    h('p', { style: hintStyle() }, s.intro),
+    !editable
+      ? h(
+          'div',
+          { style: { display: 'flex', alignItems: 'center', gap: 10, flexWrap: 'wrap', marginTop: 8 } },
+          h('p', { role: 'status', style: { ...hintStyle(), margin: 0 } }, s.readOnly),
+          props.openPluginPage
+            ? h('button', { type: 'button', onClick: props.openPluginPage, style: secondaryButton(true) }, s.openSettings)
+            : null,
+        )
+      : null,
+    editable && !ready && status !== 'missing'
+      ? h('p', { role: 'status', style: hintStyle() }, status === 'loading' ? s.loading : s.unreadable)
+      : null,
+    h(
+      'section',
+      { style: { marginTop: 18 } },
+      h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600 } }, s.header),
+      h('p', { style: hintStyle() }, s.headerHint),
+      h(
+        'div',
+        { role: 'group', 'aria-label': s.header, style: { ...gridStyle(), marginTop: 8 } },
+        h(
+          'div',
+          { key: 'file-label', style: labelCellStyle() },
+          s.file,
+        ),
+        h(
+          'div',
+          { key: 'file-control', style: controlCellStyle() },
+          h(
+            'div',
+            { style: { display: 'flex', alignItems: 'center', gap: 10, minHeight: 22 } },
+            h(
+              'span',
+              {
+                style: {
+                  fontSize: 12,
+                  lineHeight: '20px',
+                  padding: '0 8px',
+                  borderRadius: 999,
+                  border: `1px solid ${palette.line}`,
+                  color: palette.muted,
+                },
+              },
+              s.fixed,
+            ),
+            h('code', { style: { fontSize: 12.5, fontFamily: palette.mono, color: palette.muted } }, SAMPLE_FILE),
+          ),
+          h('p', { style: hintStyle() }, s.fileHint),
+        ),
+        ...header.flatMap(({ tag, hint }) =>
+          h(ValueRow, {
+            key: tag,
+            tag,
+            hint,
+            strings: s,
+            disabled: !editable,
+            entry: draft[tag],
+            onChange: (entry) => update({ [tag]: entry }),
+          }),
+        ),
+      ),
+    ),
+    h(
+      'section',
+      { style: { marginTop: 20 } },
+      h('h4', { style: { margin: '0 0 4px', fontSize: 13, fontWeight: 600 } }, s.contract),
+      h('p', { style: hintStyle() }, s.contractHint),
+      h(
+        'div',
+        { role: 'group', 'aria-label': s.contract, style: { ...gridStyle(), marginTop: 8 } },
+        ...CONTRACT_TAGS.flatMap((tag) =>
+          h(FlagRow, {
+            key: tag,
+            tag,
+            hint: contractHints[tag],
+            strings: s,
+            disabled: !editable,
+            checked: draft[tag],
+            onChange: (value) => update({ [tag]: value }),
+          }),
+        ),
+      ),
+    ),
+    h(
+      'section',
+      { style: { marginTop: 20, paddingTop: 12, borderTop: `1px solid ${palette.line}` } },
+      h(
+        'details',
+        {},
+        h(
+          'summary',
+          { style: { cursor: 'pointer', fontSize: 13, fontWeight: 600, listStylePosition: 'inside' } },
+          s.extra,
+        ),
+        h('p', { style: hintStyle() }, s.extraHint),
+        h(
+          'div',
+          { role: 'group', 'aria-label': s.extra, style: { ...gridStyle(), marginTop: 8 } },
+          ...EXTRA_TAGS.flatMap((tag) =>
+            h(FlagRow, {
+              key: tag,
+              tag,
+              hint: extraHints[tag],
+              strings: s,
+              disabled: !editable,
+              checked: draft[tag],
+              onChange: (value) => update({ [tag]: value }),
+            }),
+          ),
+        ),
+      ),
+    ),
+    h(Preview, { config: draft, strings: s }),
+    editable
+      ? h(
+          'div',
+          {
+            style: {
+              display: 'flex',
+              alignItems: 'center',
+              gap: 10,
+              marginTop: 18,
+              paddingTop: 12,
+              borderTop: `1px solid ${palette.line}`,
+              flexWrap: 'wrap',
+            },
+          },
+          h(
+            'button',
+            {
+              type: 'button',
+              onClick: save,
+              disabled: busy || !editableReady || !dirty,
+              style: primaryButton(dirty && editableReady && !busy),
+            },
+            s.save,
+          ),
+          h(
+            'button',
+            {
+              type: 'button',
+              onClick: reset,
+              disabled: busy || !dirty,
+              style: secondaryButton(dirty && !busy),
+            },
+            s.reset,
+          ),
+          h('p', { role: 'status', style: { ...hintStyle(), margin: 0, flex: '1 1 220px' } }, message || (dirty ? s.unsaved : '')),
+        )
+      : null,
+  )
+}
+
+function primaryButton(enabled) {
+  return {
+    fontSize: 13,
+    lineHeight: '20px',
+    padding: '5px 14px',
+    borderRadius: 6,
+    border: '1px solid transparent',
+    background: enabled ? palette.brand : 'var(--dsw-alias-bg-layer-3, rgba(127, 127, 127, 0.2))',
+    color: enabled ? '#fff' : palette.muted,
+    cursor: enabled ? 'pointer' : 'default',
+  }
+}
+
+function secondaryButton(enabled) {
+  return {
+    fontSize: 13,
+    lineHeight: '20px',
+    padding: '5px 14px',
+    borderRadius: 6,
+    border: `1px solid ${palette.line}`,
+    background: 'transparent',
+    color: enabled ? palette.label : palette.muted,
+    cursor: enabled ? 'pointer' : 'default',
+  }
+}
+
+function page(ownerProps, openPluginPage) {
+  const props = ownerProps || {}
+  return h(ConfigPage, { ...props, openPluginPage })
+}
+
+function apply(ctx) {
+  let openPluginPage
+  try {
+    const navigation = typeof ctx.get === 'function' ? ctx.get('pluginNavigation') : undefined
+    if (navigation && typeof navigation.openBundle === 'function') {
+      openPluginPage = () => navigation.openBundle(PACKAGE_NAME)
+    }
+  } catch {}
+  ctx.slots.inject('settings.section', () =>
+    ctx.slots.register(
+      {
+        name: 'settings.section',
+        id: 'cpp-workflow',
+        order: 60,
+        label: () => t().nav,
+      },
+      (ownerProps) => page(ownerProps, openPluginPage),
+    ),
+  )
+  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, undefined)),
+    ),
+  )
+}
+
+module.exports = {
+  name: PACKAGE_NAME,
+  inject: ['slots'],
+  apply,
+  ConfigPage,
+  diffOperations,
+  previewText,
+}
+
+    return module.exports
+  },
+})

package/lib/comment-policy.js

@@ -0,0 +1,183 @@
+/**
+ * 注释标签策略：设置页的预览、技能快照与检查器参数共用这一份。
+ *
+ * 配置只描述「写注释时默认带哪些标签」，不描述写法本身；写法在
+ * `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',
+};
+/** 预览里的示例摘要：用户没填 @brief 时用它，避免预览出现空标签。 */
+export const SAMPLE_BRIEF = '定义井字棋棋盘、格子坐标与格子类型。';
+/** 出厂配置：文件头只留 @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');
+    // 预览是示例：@brief 开着但用户没填句子时，用示例文件自己的摘要顶替。
+    const briefIndex = header.indexOf('/// @brief');
+    if (briefIndex !== -1)
+        header[briefIndex] = `/// @brief ${SAMPLE_BRIEF}`;
+    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.5",
-  "description": "C++11–C++23 工程流程技能包：源码四步、CMake 三步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
+  "version": "0.6.1",
+  "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,8 @@
   },
   "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",
@@ -79,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

@@ -17,7 +17,7 @@
 /// @file board.h
 /// @brief 定义井字棋棋盘、格子坐标与格子类型。
 ///
-/// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与清空棋盘。
+/// 棋盘保存九个棋盘格子的状态，提供查询、落子与清空棋盘。
 ```
 
 文件头只介绍这个文件里有什么，不写作者和变更史，也不把读者指去另一个文件。

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) 要求写意图与理由。阶段注释写的就是这两类信息。
 
@@ -119,13 +119,13 @@ GameResult result_ = GameResult::kInProgress;
 
 ### 文件头
 
-每个手写源文件开头写一段 doxygen 文件头：第一行 `/// @file <文件名>`，第二行 `/// @brief` 一句话说明这个文件定义或实现什么，用一行 `///` 隔开后，只写本文件自己的组成部分或边界。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
+每个手写源文件开头写一段 doxygen 文件头：第一行 `/// @file <文件名>`，第二行 `/// @brief` 一句话说明这个文件定义或实现什么，用一行 `///` 隔开后，只写本文件自己的组成部分或边界。`@file` 的参数必须与文件名逐字相同，检查器会核对。`@brief` 默认写出；`@author`、`@date`、`@copyright`、`@version` 默认不写，只有插件配置里打开并填了非空值才写出，作者、年份和变更史不写进源码。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
 
 ```cpp
 /// @file board.h
 /// @brief 定义井字棋棋盘、格子坐标与格子类型。
 ///
-/// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与清空棋盘。
+/// 棋盘保存九个棋盘格子的状态，提供查询、落子与清空棋盘。
 ```
 
 - C++ 源文件用以上格式；CMake 用 `#`，YAML/JSON 用 `#`。
@@ -142,6 +142,7 @@ GameResult result_ = GameResult::kInProgress;
 - `.clang-format`、`.clang-tidy`、`.clangd`、CMake 的配置项旁边写「为什么这样设」，不写「这一项是什么」；配置注释贴在被解释的键上方。
 - 禁止：大段表格、装饰图案、表情；外部资料路径、跨仓库引用、团队流程；注释掉的代码；注释元叙述（「其余内容见某处」「两处不重复」）。
 - `///`、`@param`、横幅不进入 `.qmd`、YAML、CSS。
+- C++ 源文件的说明性注释一律 `///`，实现区不与 `//` 混用；`//` 只留给文件头横幅边框与被引用的配置行。
 
 ## 润色：删复述，统一句式
 

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

@@ -25,7 +25,9 @@ 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', '@details', '@author', '@since', '@todo', '@date', '@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/
@@ -40,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') {
@@ -61,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') {
@@ -220,7 +229,13 @@ export function checkText(text, options = {}) {
   if (firstContent !== -1 && (BANNER.test(firstTrimmed) || hasDoxyHeader)) {
     const own = options.fileName ? options.fileName.split(/[\\/]/).pop() : ''
     const bannerHeader = BANNER.test(firstTrimmed)
-    if (hasDoxyHeader && !DOXY_BRIEF.test((lines[firstContent + 1] ?? '').trim())) {
+    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) {
@@ -247,6 +262,7 @@ 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 的标签表改写`)
       }
     }
@@ -429,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`。
 
 ## 正反例指针