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

package/README.en.md

@@ -19,20 +19,22 @@ The exception material follows the C++ Core Guidelines' Error handling section a
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.5
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.7
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.5
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.7
 ```
 
 The desktop app owns the `desktop` profile. If the command-line `add` is rejected, add the plugin in the app settings and use the same pinned npm version. A Git tag install uses the prebuilt `lib/` committed in the repository and runs no build on the target machine; the package has no install script that needs approval.
 
 ### Settings
 
-The plugin page's "C++ Workflow" card is the only entry point and manages file-header tags only: `@file` is always the file name, `@brief` is written by default, and `@author`, `@date`, `@copyright`, `@version` stay off and are written only when they hold a non-empty value; `@param`, `@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. Settings navigation no longer duplicates the form.
+The plugin page's "C++ Workflow" card is the only entry point and manages file-header tags only: `@file` is always the file name, `@brief` is written by default, and `@author`, `@date`, `@copyright`, `@version` stay off and are written only when they hold a non-empty value; `@param` is required for every parameter; `@return` is written by default but may be omitted when the condition is self-evident; `@throws` only when the function throws. The preview follows the switches, saving takes effect on the next skill read, and existing sources are never rewritten. Settings navigation no longer duplicates the form.
+
+If the page still reports that it is not connected to a configuration form after an upgrade, the window is still running the previous client bundle: restart DeepSeek Harness or select "Reload page" on the plugin page. The page retries the connection while open and switches to the editable form as soon as the host serves it; reinstalling is unnecessary. Discard changes, Restore defaults and Save are separate: discard returns to the last value read from the host, restore fills the draft, and only Save writes it.
 
 ## Workspace gate
 

package/README.md

@@ -19,20 +19,22 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.5
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.7
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.5
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.7
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
 
 ### 设置
 
-插件页的「C++ 工程流程」是唯一入口，只管文件头标签：`@file` 固定为文件名，`@brief` 默认写出，`@author`、`@date`、`@copyright`、`@version` 默认关闭且只在填了非空值时才写出；有参数就要求 `@param`，有返回值就要求 `@return`，会抛才要求 `@throws`。预览随开关即时更新，保存后下一次读取技能即生效，已有源码不会被改写。设置导航不再重复放一份。
+插件页的「C++ 工程流程」是唯一入口，只管文件头标签：`@file` 固定为文件名，`@brief` 默认写出，`@author`、`@date`、`@copyright`、`@version` 默认关闭且只在填了非空值时才写出；有参数就要求 `@param`，有返回值默认要求 `@return`（成立条件自明时可省），会抛才要求 `@throws`。预览随开关即时更新，保存后下一次读取技能即生效，已有源码不会被改写。设置导航不再重复放一份。
+
+升级插件后如果这一页仍显示“暂时没有连到配置表单”，说明当前窗口还挂着旧的前端产物：重启 DeepSeek Harness，或在插件页点“重新载入页面”。页面会在打开后自动重试连接，拿到表单就切换为可编辑，不需要重装插件。保存、撤销修改与恢复默认值分三个按钮：撤销只回到最近一次读到的值，恢复默认值只填草稿，点保存才写盘。
 
 ## 工作区门禁
 

package/lib/client.js

@@ -1,4 +1,4 @@
-// 由 scripts/building-client.mjs 生成，请改 src/comment-policy.ts 与 src/client/app.cjs.js。
+// 由 scripts/building-client.mjs 生成，请改 src/comment-policy.ts 与 src/client/*.js。
 window.__ModuleLoader__.load({
   id: "@chengzhao-dev/dsh-cpp-workflow",
   factory: (require) => {
@@ -79,11 +79,25 @@ const DEFAULT_CONFIG = {
     tparam: false,
     retval: false,
 };
+/**
+ * 宿主把 volatile 字段交给插件时给的是可读写单元（`.get()`），设置页快照给的是普通值；
+ * 两种形状都要按同一个值读取。
+ */
+function unwrap(value) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        typeof value.get === 'function') {
+        return value.get();
+    }
+    return value;
+}
 function text(value) {
-    return typeof value === 'string' ? value.trim() : '';
+    const plain = unwrap(value);
+    return typeof plain === 'string' ? plain.trim() : '';
 }
 function flag(value, fallback) {
-    return typeof value === 'boolean' ? value : fallback;
+    const plain = unwrap(value);
+    return typeof plain === 'boolean' ? plain : fallback;
 }
 /**
  * 把宿主给的值补齐成完整配置；缺字段、旧版本或手工改坏的配置都回到出厂值。
@@ -223,14 +237,18 @@ const STRINGS = {
     preview: '预览',
     previewHint: '按当前开关生成，文件名用占位符表示。',
     save: '保存',
-    reset: '恢复出厂值',
+    reset: '撤销修改',
+    defaults: '恢复默认值',
+    restored: '已填入内置默认值，点“保存”后生效。',
     saved: '已保存，下一次读取技能时生效。',
-    rejected: '保存被拒绝：配置可能已在别处修改，请恢复出厂值后再试。',
+    rejected: '保存被拒绝：配置可能已在别处修改。请先撤销修改，再重新编辑。',
     unsaved: '有未保存的改动',
     loading: '正在读取配置…',
     unavailable: '这个部署没有提供这份配置。',
     unreadable: '当前账户不能修改这份配置。',
-    readOnly: '当前部署没有把可编辑配置传给这个页面，下面显示的是出厂值。',
+    readOnly: '这个页面暂时没有连到配置表单，下面的值是内置默认值。重启 DeepSeek Harness 后重新打开本页即可编辑。',
+    reload: '重新载入页面',
+    noService: '（configForms 服务未连接）',
     fixed: '跟随文件名',
     fixedHint: '值由实际文件决定，不写进配置。',
     emptyValue: '留空则由文件自己写',
@@ -259,14 +277,18 @@ const STRINGS = {
     preview: 'Preview',
     previewHint: 'Generated from the switches above; the file name is a placeholder.',
     save: 'Save',
-    reset: 'Restore defaults',
+    reset: 'Discard changes',
+    defaults: 'Restore defaults',
+    restored: 'Built-in defaults are filled in; select Save to apply them.',
     saved: 'Saved; the next skill read uses it.',
-    rejected: 'The host rejected the save: the config changed elsewhere. Restore defaults and try again.',
+    rejected: 'The host rejected the save: the config changed elsewhere. Discard your changes and edit again.',
     unsaved: 'Unsaved changes',
     loading: 'Reading configuration…',
     unavailable: 'This deployment does not serve this configuration.',
     unreadable: 'This account cannot edit the configuration.',
-    readOnly: 'This deployment does not pass an editable form to this page; the values below are defaults.',
+    readOnly: 'This page is not connected to a configuration form yet; the values below are built-in defaults. Restart DeepSeek Harness, then reopen this page to edit.',
+    reload: 'Reload page',
+    noService: ' (the configForms service is not connected)',
     fixed: 'Follows the file name',
     fixedHint: 'Derived from the file itself, never stored in the config.',
     emptyValue: 'Leave empty and each file writes its own',
@@ -343,6 +365,9 @@ const CSS = `
 .dcw-status{flex:1 1 200px;margin:0;color:var(--dcw-muted);font-size:12px}
 .dcw-status[data-tone="warn"]{color:var(--dcw-danger)}
 .dcw-status[data-tone="ok"]{color:var(--dsw-alias-state-success-primary,#1a7f37)}
+.dcw-note-code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px;opacity:.8;margin-left:6px}
+.dcw-note-action{margin-left:auto;flex:none;padding:3px 10px;border:1px solid currentColor;border-radius:6px;background:transparent;color:inherit;font:inherit;font-size:11.5px;cursor:pointer;white-space:nowrap}
+.dcw-note-action:hover{background:var(--dcw-bg1)}
 @media (max-width:640px){.dcw-row{grid-template-columns:1fr;gap:4px}.dcw-row-label{padding-top:0}.dcw-flags{grid-template-columns:1fr}.dcw-flag:nth-child(2){border-top:1px solid var(--dcw-border)}}
 `
 
@@ -468,36 +493,88 @@ function Preview(props) {
 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] })
+    const next = draft[key]
+    const previous = base[key]
+    if (next !== null && typeof next === 'object') {
+      // 文件头字段整体不是 volatile，宿主只接受叶子路径（brief.enabled / brief.value）。
+      const before = previous !== null && typeof previous === 'object' ? previous : {}
+      for (const field of Object.keys(next)) {
+        if (JSON.stringify(next[field]) !== JSON.stringify(before[field])) {
+          operations.push({ op: 'set', path: [key, field], value: next[field] })
+        }
+      }
+      continue
+    }
+    if (JSON.stringify(next) !== JSON.stringify(previous)) {
+      operations.push({ op: 'set', path: [key], value: next })
+    }
   }
   return operations
 }
 
+function snapshotOf(form) {
+  if (!form) return { status: 'missing', writable: false }
+  if (typeof form.getSnapshot === 'function') return form.getSnapshot()
+  return form.state || { status: 'missing', writable: false }
+}
+
+// 宿主的 ConfigFormController 是可订阅的外部存储；旧调用方仍可能直接给 form.state。
+function useFormSnapshot(form) {
+  const [snapshot, setSnapshot] = React.useState(() => snapshotOf(form))
+  React.useEffect(() => {
+    if (!form || typeof form.subscribe !== 'function' || typeof form.getSnapshot !== 'function') {
+      setSnapshot(snapshotOf(form))
+      return undefined
+    }
+    setSnapshot(form.getSnapshot())
+    return form.subscribe(() => setSnapshot(form.getSnapshot()))
+  }, [form])
+  return snapshot
+}
+
+// 配置卡片本身：状态机、保存/撤销/恢复默认值，以及组合包条目里的挂点。
+// 分片按 scripts/building-client.mjs 的模块表顺序拼接：shell → text → styles →
+// widgets → form-state → 本文件。分片共享同一个工厂作用域，不要各自 require。
+
+// 宿主组合包 cordis.patch.yml 插入的 profile 条目 id；设置服务按它定位表单。
+const ENTRY_ID = 'cpp-workflow'
+// configForms 可能晚于本插件挂载；页面在首次绘制后短暂重试，拿不到再给手动恢复入口。
+const FORM_RETRY_MS = 500
+const MAX_FORM_RETRIES = 20
+
 function ConfigPage(props) {
   const s = t()
   ensureStyles()
-  const form = props.form
-  const initial = React.useMemo(() => normalizeConfig(form && form.state ? form.state.value : undefined), [])
+  // form 由挂点注入；resolveForm 兜住“服务晚到”的部署，拿到后下一次绘制自动接上。
+  const form = props.form || (typeof props.resolveForm === 'function' ? props.resolveForm() : undefined)
+  const state = useFormSnapshot(form)
+  const initial = React.useMemo(() => normalizeConfig(state.value), [])
   const [draft, setDraft] = React.useState(initial)
   const [base, setBase] = React.useState(initial)
   const [dirty, setDirty] = React.useState(false)
   const [busy, setBusy] = React.useState(false)
   const [message, setMessage] = React.useState('')
   const [tone, setTone] = React.useState('')
-  const revision = form && form.state ? form.state.revision : undefined
+  const [attempt, setAttempt] = React.useState(0)
+  const revision = state.revision
   // 快照只有 status / writable / revision；旧版本多出来的 mode 字段已不存在，
   // 再按它判断会把所有可写表单误判成只读。
-  const ready = Boolean(form && form.state && form.state.status === 'ready' && form.state.writable)
-  const status = form && form.state ? form.state.status : 'missing'
+  const ready = Boolean(form && state.status === 'ready' && state.writable)
+  const status = state.status
+  const missing = !form
 
   React.useEffect(() => {
-    if (dirty || !form || !form.state || form.state.status !== 'ready') return
-    const next = normalizeConfig(form.state.value)
+    if (dirty || state.status !== 'ready') return
+    const next = normalizeConfig(state.value)
     setBase(next)
     setDraft(next)
-  }, [revision, status, dirty, form])
+  }, [revision, status, dirty, form, state.value])
+
+  React.useEffect(() => {
+    if (form || attempt >= MAX_FORM_RETRIES || typeof setTimeout !== 'function') return undefined
+    const timer = setTimeout(() => setAttempt((value) => value + 1), FORM_RETRY_MS)
+    return () => clearTimeout(timer)
+  }, [form, attempt])
 
   const update = (patch) => {
     setDraft((current) => ({ ...current, ...patch }))
@@ -506,6 +583,7 @@ function ConfigPage(props) {
     setTone('')
   }
 
+  // 撤销：回到最近一次从宿主读到的值，不写盘。
   const reset = () => {
     setDraft(base)
     setDirty(false)
@@ -513,6 +591,20 @@ function ConfigPage(props) {
     setTone('')
   }
 
+  // 恢复默认值：只填进草稿，点“保存”后才写盘，避免误触直接覆盖已保存的配置。
+  const restoreDefaults = () => {
+    setDraft(normalizeConfig(DEFAULT_CONFIG))
+    setDirty(true)
+    setMessage(s.restored)
+    setTone('')
+  }
+
+  const reload = () => {
+    if (typeof window !== 'undefined' && window.location && typeof window.location.reload === 'function') {
+      window.location.reload()
+    }
+  }
+
   const save = async () => {
     if (!ready || busy) return
     const operations = diffOperations(draft, base)
@@ -526,6 +618,9 @@ function ConfigPage(props) {
         setMessage(s.saved)
         setTone('ok')
       } else {
+        // 被拒时宿主已刷新镜像；把基准对齐到新快照，撤销才不会回到过期值。
+        const fresh = snapshotOf(form)
+        if (fresh && fresh.status === 'ready') setBase(normalizeConfig(fresh.value))
         setMessage(s.rejected)
         setTone('warn')
       }
@@ -550,12 +645,22 @@ function ConfigPage(props) {
       h('h3', { className: 'dcw-title' }, s.title),
       h('p', { className: 'dcw-lede' }, s.intro),
     ),
-    !editable
+    missing
       ? h(
           'div',
-          { className: 'dcw-note', role: 'status' },
+          { className: 'dcw-note', role: 'status', 'data-tone': 'warn' },
           h('span', { className: 'dcw-note-dot' }),
-          h('span', null, s.readOnly),
+          h(
+            'span',
+            null,
+            s.readOnly,
+            props.hasService === false ? h('span', { className: 'dcw-note-code' }, s.noService) : null,
+          ),
+          h(
+            'button',
+            { type: 'button', className: 'dcw-note-action', onClick: reload },
+            s.reload,
+          ),
         )
       : null,
     editable && !ready && status !== 'missing'
@@ -657,35 +762,55 @@ function ConfigPage(props) {
           ),
           h('button', { type: 'button', className: 'dcw-btn', onClick: reset, disabled: busy || !dirty }, s.reset),
           h(
-            'p',
-            { className: 'dcw-status', role: 'status', 'data-tone': tone },
-            message || (dirty ? s.unsaved : ''),
+            'button',
+            { type: 'button', className: 'dcw-btn', onClick: restoreDefaults, disabled: busy || !ready },
+            s.defaults,
           ),
+          h('p', { className: 'dcw-status', role: 'status', 'data-tone': tone }, message || (dirty ? s.unsaved : '')),
         )
       : null,
   )
 }
 
-function page(ownerProps) {
-  return h(ConfigPage, ownerProps || {})
+function page(ownerProps, form, resolveForm, hasService) {
+  return h(ConfigPage, { ...(ownerProps || {}), form, resolveForm, hasService })
 }
 
 function apply(ctx) {
-  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)),
-    ),
-  )
+  // 每次取表单都重新查询服务：宿主可能在本插件之后才挂载 configForms。
+  const resolveForm = () => {
+    if (!ctx.configForms || typeof ctx.configForms.get !== 'function') return undefined
+    try {
+      return ctx.configForms.get(ENTRY_ID)
+    } catch {
+      return undefined
+    }
+  }
+  const hasService = Boolean(ctx.configForms && typeof ctx.configForms.get === 'function')
+  const mount = () =>
+    ctx.slots.inject('plugins.bundle.config', () =>
+      ctx.slots.register(
+        {
+          name: 'plugins.bundle.config',
+          key: PACKAGE_NAME,
+          label: () => t().nav,
+        },
+        (ownerProps) =>
+          ownerProps && ownerProps.view === 'summary'
+            ? null
+            : page(ownerProps, undefined, resolveForm, hasService),
+      ),
+    )
+  if (ctx.configForms && typeof ctx.configForms.whileServed === 'function') {
+    ctx.effect(() => ctx.configForms.whileServed([ENTRY_ID], mount), 'dsh-cpp-workflow: 配置挂点')
+  } else {
+    mount()
+  }
 }
 
 module.exports = {
   name: PACKAGE_NAME,
-  inject: ['slots'],
+  inject: ['slots', 'configForms'],
   apply,
   ConfigPage,
   diffOperations,

package/lib/comment-policy.js

@@ -72,11 +72,25 @@ export const DEFAULT_CONFIG = {
     tparam: false,
     retval: false,
 };
+/**
+ * 宿主把 volatile 字段交给插件时给的是可读写单元（`.get()`），设置页快照给的是普通值；
+ * 两种形状都要按同一个值读取。
+ */
+function unwrap(value) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        typeof value.get === 'function') {
+        return value.get();
+    }
+    return value;
+}
 function text(value) {
-    return typeof value === 'string' ? value.trim() : '';
+    const plain = unwrap(value);
+    return typeof plain === 'string' ? plain.trim() : '';
 }
 function flag(value, fallback) {
-    return typeof value === 'boolean' ? value : fallback;
+    const plain = unwrap(value);
+    return typeof plain === 'boolean' ? plain : fallback;
 }
 /**
  * 把宿主给的值补齐成完整配置；缺字段、旧版本或手工改坏的配置都回到出厂值。

package/lib/index.js

@@ -223,11 +223,11 @@ async function getSkill(candidate, options = {}, commentConfig = undefined) {
     };
 }
 export function apply(ctx, config = undefined) {
-    // 配置决定注释标签的默认集合；快照随每次 get() 读出，改配置立即生效。
-    const resolved = normalizeConfig(config);
+    // 配置对象由宿主在 volatile 保存时原地更新，所以每次 get() 都重新读取，
+    // 不能在这里缓存成一份快照，否则设置页改了标签开关，技能正文仍是旧值。
     ctx.skills.registerProvider(() => ({
         name: PROVIDER,
         list: listSkills,
-        get: (candidate, options) => getSkill(candidate, options, resolved),
+        get: (candidate, options) => getSkill(candidate, options, normalizeConfig(config)),
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "写 C++ 源码、配 CMake、用 Clang 构建；头文件用 /// Doxygen 文档注释，函数体用 // 分段说明，文件头标签可在设置里改。 · Write C++ sources, configure CMake, and build with Clang; /// Doxygen on declarations, // section notes in bodies, and configurable file-header tags.",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,7 +32,9 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-slots"
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
       ]
     },
     "catalog": {

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

@@ -67,7 +67,7 @@ GameResult result_ = GameResult::kInProgress;
 有参数或有返回值的函数写两段：第一段写结果、失败方式或检查项；第二段按签名把标签写齐。
 
 1. 第一段：普通函数写正常返回什么、失败时返回什么或抛什么；布尔查询与 `operator==` 写「检查…是否…」。
-2. 第二段：每个参数一条 `@param`；有返回值就写 `@return`；会抛才写 `@throws`。
+2. 第二段：每个参数一条 `@param`；有返回值默认写 `@return`，成立条件已由函数名与返回类型说清时可省略；会抛才写 `@throws`。
 
 ```cpp
 /// 检查坐标能否落子，不修改棋盘。
@@ -78,9 +78,9 @@ GameResult result_ = GameResult::kInProgress;
 [[nodiscard]] PlaceCellResult CheckPlaceable(CellPosition position, CellType cell_type) const;
 ```
 
-- 布尔查询与 `operator==`：第一句写「检查…是否…」；`@return` 只写「什么情况下为 true」，再补一句「不检查什么」。条件简单也要写，「名字已经说明」不构成省略理由。
+- 布尔查询与 `operator==`：第一句写「检查…是否…」；`@return` 只写「什么情况下为 true」，再补一句「不检查什么」。`Is`、`Has` 开头的名字与 `bool` 返回类型已经把成立条件说清时可省略 `@return`，不为了形式补一句同义反复。
 - `@param` 每个参数都写，写范围、单位或所有权，不写「索引」这类同义反复；没有参数就不写空的 `@param`。
-- `@return` 每个非 `void`、非构造、非析构的函数都写，写返回值怎么读或失败时返回什么；不要用「见上」或重复第一段。
+- `@return` 默认写，写返回值怎么读或失败时返回什么；返回类型与函数名已把条件说清时可省略，不要用「见上」或重复第一段。
 - `@throws` 必须与 `references/exceptions.md` 一致；不抛异常的函数不写。
 - 私有函数同样写契约，不能默认调用者知道前置条件；输出参数标 `[out]`，既读又写标 `[in,out]`。
 

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

@@ -14,7 +14,7 @@
 - 头文件只就地定义大约 10 行以内的短函数；更长或需要完整定义的普通函数只在 `.cpp` 定义，模板和 `constexpr` 例外。
 - 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立 invariant 时，才在声明注释里写清抛出的异常类型；越界用 `std::out_of_range`，前置条件被破坏用 `std::logic_error`，只有调用方必须区分时才新增派生类型；Debug/Release 的抛出条件相同。消息句式见 `references/exceptions.md` 的「消息」节。
 - 一次操作有多种必须区分的正常结果时，用 `enum class` 返回（如落子：成功、越界、类型非法、已占），不用 `bool` 把原因压掉；成功还需要附带数据时再考虑 `std::expected` 或结果结构，成功无数据时不用。纯查询谓词仍用 `bool`，不要把 `IsEmpty` 改成三态。
-- 声明注释按 `references/comments.md` 的四节写：写作只写声明里看不出的事实——类型注释的名词短语（纯数据与枚举一句，类只在不变量不重复领域尺寸时加第二段）、特殊成员的标签与后置条件（例如 `默认构造函数：得到空棋盘、每个格子都是 kEmpty`）、函数注释的第一句结果或失败方式或检查项与契约。有参数就每个参数一条 `@param`，有返回值就写 `@return`，会抛才写 `@throws`；构造、析构和 `void` 无参数函数写两段后置条件，不写空标签。数据成员的主注释放在声明上一行并用 `///`，先说明这个成员是什么，再用全角冒号补名字和类型看不出的轴向、哨兵、所有权与改写时机，行尾不写补充；布局定文件头、位置与行尾；排版定符号、宽度与标签；润色删复述。类型注释不罗列成员功能、不写领域尺寸、不写方案对比与设计论证；全项目的风格理由写进项目文档，不写进注释。
+- 声明注释按 `references/comments.md` 的四节写：写作只写声明里看不出的事实——类型注释的名词短语（纯数据与枚举一句，类只在不变量不重复领域尺寸时加第二段）、特殊成员的标签与后置条件（例如 `默认构造函数：得到空棋盘、每个格子都是 kEmpty`）、函数注释的第一句结果或失败方式或检查项与契约。有参数就每个参数一条 `@param`，有返回值默认写 `@return`（成立条件自明时可省），会抛才写 `@throws`；构造、析构和 `void` 无参数函数写两段后置条件，不写空标签。数据成员的主注释放在声明上一行并用 `///`，先说明这个成员是什么，再用全角冒号补名字和类型看不出的轴向、哨兵、所有权与改写时机，行尾不写补充；布局定文件头、位置与行尾；排版定符号、宽度与标签；润色删复述。类型注释不罗列成员功能、不写领域尺寸、不写方案对比与设计论证；全项目的风格理由写进项目文档，不写进注释。
 - `std::format` 用于组合消息；声明里不要承诺 `std::print`（C++23）。
 
 ## 情况