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

package/README.en.md

@@ -19,20 +19,20 @@ 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.6
 ```
 
 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.6
 ```
 
 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.
 
 ## Workspace gate
 

package/README.md

@@ -19,20 +19,20 @@
 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.6
 ```
 
 同版本的 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.6
 ```
 
 桌面应用独占 `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`。预览随开关即时更新，保存后下一次读取技能即生效，已有源码不会被改写。设置导航不再重复放一份。
 
 ## 工作区门禁
 

package/lib/client.js

@@ -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;
 }
 /**
  * 把宿主给的值补齐成完整配置；缺字段、旧版本或手工改坏的配置都回到出厂值。
@@ -468,36 +482,69 @@ 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
+}
+
 function ConfigPage(props) {
   const s = t()
   ensureStyles()
   const form = props.form
-  const initial = React.useMemo(() => normalizeConfig(form && form.state ? form.state.value : 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 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(state.status === 'ready' && state.writable)
+  const status = state.status
 
   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])
 
   const update = (patch) => {
     setDraft((current) => ({ ...current, ...patch }))
@@ -666,26 +713,36 @@ function ConfigPage(props) {
   )
 }
 
-function page(ownerProps) {
-  return h(ConfigPage, ownerProps || {})
+// 组合包 cordis.patch.yml 插入的 profile 条目 id；设置服务按它定位表单。
+const ENTRY_ID = 'cpp-workflow'
+
+function page(ownerProps, form) {
+  return h(ConfigPage, { ...(ownerProps || {}), form })
 }
 
 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)),
-    ),
-  )
+  const form = ctx.configForms ? ctx.configForms.get(ENTRY_ID) : undefined
+  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, form)),
+      ),
+    )
+  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.6",
   "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）。
 
 ## 情况