@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/lib/settings-panels.mjs

@@ -0,0 +1,816 @@
+/**
+ * settings-panels.mjs —— 能力包「声明式设置页」聚合层（0.2 契约，2026-09-30）
+ *
+ * ## 它解决什么
+ * 用户诉求：**能力包是插拔式的** —— 装了就在设置里出现它那一页，没装就不出现；
+ * 不要再把所有字段挤在一个 Argent 页里。落地方式分三层（详见
+ * `docs/能力包设置页契约.md`）：
+ *   ① pack 侧**声明**：`verticals/<id>/manifest.json` 的可选字段 `settingsPanel`
+ *      （或数组 `settingsPanels`）；无 vertical 的引擎级能力写在注册表
+ *      `capabilities.<c>.pack.settingsPanel`。**能力包不需要自带客户端 bundle**。
+ *   ② host 侧**聚合**（本模块）：把「声明 + 是否已装 + 是否启用 + 字段当前值」读成一份稳定 JSON；
+ *      `GET /api/argent-gateway/settings-panels` 与 `scripts/argent-catalog.mjs` 都消费它。
+ *   ③ 客户端**渲染**：按 catalog 生成页签，只渲染 **installed === true** 的面板。
+ *      ⇒「未安装即不显示」由数据决定，不靠前端 if 名单（前端写名单一定会漂移）。
+ *
+ * ## 两条设计红线
+ * 1. **不改判据来源**：字段值的读法只有四种（config / env / json-from-env / roles-from-gateway），
+ *    写入口只允许**已存在的宿主端点**（形状约束）。本模块**不新建**密钥存储、
+ *    不写 `~/.dsh/settings.yaml`、不发明第二份真相。
+ * 2. **密码字段绝不出明文**：`type: "password"` 只回 `configured` 与 `masked`，
+ *    `value` 恒为空串（即便声明方写错也不泄）。
+ *
+ * ## 0.2 续做（2026-10-01）
+ * · **面板级档位 `panel.minPlan`**：不写就用「绑定能力里最低的那个 minPlan」派生
+ *   （注册表 `capabilities.<c>.minPlan` 是唯一档位表，**不新建第二份**）；
+ *   账号档位够不够由**服务端**（host 端点 / 仓库脚本）算成 `planGated` 布尔 —— 客户端仍然零名单。
+ *   账号档位**取不到时不做任何过滤**（与 `assertFeishuAllowed` 同口径：宁可放行，不误锁）。
+ * · **字段级档位 `field.minPlan`**（同日晚补）：与面板级**同一条档位链、同一个 planRank**，
+ *   只是粒度更细（"这一页 pro 就有，但其中某个字段要 enterprise"）。过滤同样在**服务端**：
+ *   被滤字段从 `panels[].fields[]` 里整个消失，只在 `hiddenByPlan[]` 留一条 `kind: 'field'`
+ *   的原因，面板上的 `fieldsHiddenByPlan` 给个计数。声明必须**比面板级更严**，否则报
+ *   `field-minplan-unreachable`（不可达声明 = 死代码，不静默）。
+ * · **受控 env 写入器**（契约 §11）：`scope: vertical|user` 的字段原本只读，现在可以在
+ *   **显式开关**（`ARGENT_ENV_WRITER=1`）打开后受控写入 —— 目标路径**只由声明推导**
+ *   （请求体里不带任何路径）、写前备份、写后读回、审计 JSONL、只落 `~/.dsh/argent/**`。
+ *
+ * 模块是**只读 + 纯函数**（除了读文件），无副作用 ⇒ 可以用假 HOME / 夹具仓库离线单测
+ * （`scripts/tests/settings-panels.test.mjs`）。真正的写入在 `scripts/argent-env-write.mjs`
+ * （单独一个脚本，写盘/备份/审计/读回都在那里；本模块只负责"能不能写、写到哪"）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve as resolvePath, sep } from 'node:path'
+import { resolveDataDir } from './argent-datadir.mjs'
+
+// ── 契约枚举（客户端与文档必须与这里一致）────────────────────────────
+/** 字段类型：text 文本框 ｜ password 密码框（只回掩码）｜ switch 开关 ｜ select 下拉。 */
+export const FIELD_TYPES = ['text', 'password', 'switch', 'select']
+/** 值作用域：vertical = 该业务线的 env 目录；user = 数据目录根（跨业务线共用）。 */
+export const FIELD_SCOPES = ['vertical', 'user']
+/**
+ * 只读取值来源：
+ *   · config = `~/.dsh/argent/config.json`
+ *   · env    = env 文件（目录按 scope）
+ *   · json   = `pathFromEnv` 指向的 JSON（路径只来自 env）
+ *   · roles  = `~/.dsh/argent/gateway.json` 的角色装配状态（只读摘要；给"入口=角色"的能力用）
+ */
+export const READ_SOURCES = ['config', 'env', 'json', 'roles']
+/** env 写入器的宿主端点（形状必须在 {@link WRITE_ENDPOINT_PREFIX} 内）。 */
+export const ENV_WRITE_ENDPOINT = '/api/argent-state/env'
+/** env 写入器的显式开关：**默认关闭**（不开就只读，端点也会 403）。 */
+export const ENV_WRITER_ENV = 'ARGENT_ENV_WRITER'
+/** 可写的 env 文件名形状：只允许 `<名>.env`，不得含路径分隔符/上跳。 */
+export const ENV_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.env$/
+/**
+ * 允许被面板字段写入的宿主端点**形状**（不是名单）。
+ *
+ * 为什么不用名单：名单会把各业务线的端点名写进引擎文件 —— 既触发
+ * `verticals/_engine-words.json` 门禁（引擎文件不得含业务词），又意味着"每加一个业务线就要改引擎"。
+ * 契约改成形状约束：只允许**本机 Argent 自己的配置端点**（`/api/argent-state/` 前缀、相对路径、
+ * 不带查询串），业务线在 `verticals/<id>/manifest.json` 里指名具体端点。
+ * 安全性由两层兜底：① 形状（禁止外链/穿越）；② 端点自身的校验（如 config 端点的 CONFIG_KEYS 白名单）。
+ * 不满足形状 ⇒ 该字段自动降级为只读（客户端渲染只读徽章，不发出请求）。
+ */
+export const WRITE_ENDPOINT_PREFIX = '/api/argent-state/'
+export function isAllowedWriteEndpoint(ep) {
+  const s = String(ep || '')
+  return s.startsWith(WRITE_ENDPOINT_PREFIX) && !s.includes('//') && !s.includes('?') && !s.includes('..')
+}
+
+const str = (v, d = '') => (v === null || v === undefined ? d : String(v))
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** 注册表里的档位序列（`entitlements.planTiers`；缺省 free < pro < enterprise）。 */
+export function planTiers(registryDoc) {
+  const t = ((registryDoc || {}).entitlements || {}).planTiers
+  return Array.isArray(t) && t.length ? t.map((x) => str(x)) : ['free', 'pro', 'enterprise']
+}
+
+/** 档位排序（**未知/缺失 → -1**：比最低档还低 ⇒ 保守不放行）。 */
+export function planRank(plan, tiers) {
+  const i = (Array.isArray(tiers) ? tiers : []).indexOf(str(plan))
+  return i < 0 ? -1 : i
+}
+
+/** env 写入器是否打开（**默认关闭**：显式 `ARGENT_ENV_WRITER=1` 才算开）。 */
+export function isEnvWriterEnabled(env) {
+  return str((env || {}).ARGENT_ENV_WRITER).trim() === '1'
+}
+
+/** 掩码：与 host 侧 `maskSecret` 同口径（短串整体打码，绝不回明文）。 */
+export function maskSecret(v) {
+  const s = str(v)
+  if (!s) return ''
+  if (s.length <= 8) return '******'
+  return s.slice(0, 3) + '****' + s.slice(-3)
+}
+
+// ── ① 声明解析（pack 侧）─────────────────────────────────────────────
+/**
+ * 归一化单个字段。返回 `{ field, errors }`；`errors` 为空即合法。
+ * 合法形状：`{ key, label, type?, env?, scope?, placeholder?, hint?, options?, minPlan?, bind? }`
+ *   · `key`   —— 面板内唯一（也是客户端表单的键）
+ *   · `minPlan` —— **字段级档位**（可选）：账号档位低于它 ⇒ 服务端把该字段从载荷里滤掉
+ *     （进 `hiddenByPlan[]`）。与面板级**同口径**：档位序列读注册表 `entitlements.planTiers`，
+ *     比较用同一个 {@link planRank}，**不新建第二份档位表**；账号档位取不到 ⇒ 不过滤。
+ *     刻意**不从能力派生**（字段没有"绑定能力"这回事；面板级才是派生口径）。
+ *   · `bind.read`  —— `{ from: 'config'|'env'|'json', key?, pathFromEnv?, mode? }`（缺省按 type/env 推断）
+ *   · `bind.write` —— `{ endpoint, field? }`（endpoint 必须在 WRITE_ENDPOINTS 白名单内，否则降级只读）
+ */
+export function normalizeField(raw, ctx = {}) {
+  const errors = []
+  const where = `${ctx.panelId || '?'}#${str(raw && raw.key) || '?'}`
+  if (!isObj(raw)) return { field: null, errors: [{ panel: ctx.panelId || '', code: 'field-not-object', message: `${where} 不是对象` }] }
+  const key = str(raw.key).trim()
+  if (!key) errors.push({ panel: ctx.panelId || '', code: 'field-key-missing', message: `${where} 缺 key` })
+  const label = str(raw.label).trim()
+  if (!label) errors.push({ panel: ctx.panelId || '', code: 'field-label-missing', message: `${where} 缺 label（用户看不懂字段名 ⇒ 配不对）` })
+  const type = str(raw.type, 'text').trim() || 'text'
+  if (!FIELD_TYPES.includes(type)) errors.push({ panel: ctx.panelId || '', code: 'field-type-unknown', message: `${where} type=${type} 不在 ${FIELD_TYPES.join('|')}` })
+  const scope = str(raw.scope, 'vertical').trim() || 'vertical'
+  if (!FIELD_SCOPES.includes(scope)) errors.push({ panel: ctx.panelId || '', code: 'field-scope-unknown', message: `${where} scope=${scope} 不在 ${FIELD_SCOPES.join('|')}` })
+  const options = Array.isArray(raw.options) ? raw.options.map((o) => str(o)).filter(Boolean) : []
+  if (type === 'select' && !options.length) errors.push({ panel: ctx.panelId || '', code: 'field-select-no-options', message: `${where} select 必须给 options` })
+  // 字段级档位：档位序列与面板级**同一份**（注册表 planTiers）；不在册 ⇒ 报错（不静默忽略，
+  // 否则"我明明写了 minPlan 却没生效"根本查不出来）。
+  const tiers = planTiers(ctx.registry)
+  const rawMin = str(raw.minPlan).trim()
+  if (rawMin && !tiers.includes(rawMin)) {
+    errors.push({ panel: ctx.panelId || '', code: 'field-minplan-unknown', message: `${where} minPlan=${rawMin} 不在注册表 planTiers（${tiers.join('|')}）内` })
+  }
+  const minPlan = rawMin && tiers.includes(rawMin) ? rawMin : ''
+  const env = str(raw.env).trim()
+  // envFile：env 字段写入哪个文件（**相对**名，如 `fulfillment.env`）。不声明 ⇒ 该字段只读
+  //（绝不猜路径 —— 这是写入器"拒绝任意路径"的第一道口子）。
+  const envFile = str(raw.envFile).trim()
+  if (envFile && !ENV_FILE_RE.test(envFile)) {
+    errors.push({ panel: ctx.panelId || '', code: 'field-envfile-invalid', message: `${where} envFile=${envFile} 形状非法（只允许 <名>.env，不含路径分隔符/上跳）——该字段会渲染为只读` })
+  }
+  const bind = isObj(raw.bind) ? raw.bind : null
+  if (!env && !bind) errors.push({ panel: ctx.panelId || '', code: 'field-no-source', message: `${where} 既没有 env 也没有 bind ⇒ 不知道该读哪里` })
+  const read = isObj(bind && bind.read) ? bind.read : null
+  const from = read ? str(read.from, '').trim() : ''
+  if (read && !READ_SOURCES.includes(from)) errors.push({ panel: ctx.panelId || '', code: 'field-read-source-unknown', message: `${where} bind.read.from=${from} 不在 ${READ_SOURCES.join('|')}` })
+  if (read && from === 'json' && !str(read.pathFromEnv).trim()) errors.push({ panel: ctx.panelId || '', code: 'field-json-needs-env', message: `${where} bind.read.from=json 必须给 pathFromEnv（路径只能来自 env，不接任意路径）` })
+  let write = null
+  if (isObj(bind && bind.write)) {
+    const endpoint = str(bind.write.endpoint).trim()
+    const payloadKey = str(bind.write.field).trim() || key   // 请求体字段名（缺省用字段 key）
+    if (!isAllowedWriteEndpoint(endpoint)) {
+      errors.push({ panel: ctx.panelId || '', code: 'field-write-endpoint-not-allowed', message: `${where} bind.write.endpoint=${endpoint} 不符合写入口形状（须为 ${WRITE_ENDPOINT_PREFIX}* 的相对路径且无查询串）——该字段会渲染为只读` })
+    } else {
+      write = { endpoint, field: payloadKey }
+    }
+  }
+  const field = {
+    key, label, type, scope,
+    env: env || (read && from === 'env' ? str(read.key) : ''),
+    envFile: ENV_FILE_RE.test(envFile) ? envFile : '',
+    placeholder: str(raw.placeholder),
+    hint: str(raw.hint),
+    options,
+    minPlan,
+    read: read ? { from, key: str(read.key), pathFromEnv: str(read.pathFromEnv), mode: str(read.mode, 'keys') } : null,
+    write,
+  }
+  return { field, errors }
+}
+
+/**
+ * 归一化一个面板声明。`ctx.source` 记录声明位置（排障用），`ctx.vertical` 由声明位置补齐。
+ * 合法形状：`{ id, title, order?, capability?, vertical?, hint?, fields: [...] }`
+ */
+export function normalizePanel(raw, ctx = {}) {
+  const errors = []
+  const id = str(raw && raw.id).trim()
+  const title = str(raw && raw.title).trim()
+  if (!isObj(raw)) return { panel: null, errors: [{ panel: '', code: 'panel-not-object', message: `settingsPanel 不是对象（来源 ${ctx.source || '?'}）` }] }
+  if (!id) errors.push({ panel: '', code: 'panel-id-missing', message: `settingsPanel 缺 id（来源 ${ctx.source || '?'}）` })
+  if (!title) errors.push({ panel: id, code: 'panel-title-missing', message: `面板 ${id} 缺 title（页签上要显示）` })
+  const fields = []
+  const rawFields = Array.isArray(raw.fields) ? raw.fields : []
+  if (!rawFields.length) errors.push({ panel: id, code: 'panel-no-fields', message: `面板 ${id} 没有 fields` })
+  const seen = new Set()
+  for (const rf of rawFields) {
+    // registry 要传下去：字段级 minPlan 的合法性判据 = 注册表 planTiers（与面板级同一份）
+    const r = normalizeField(rf, { panelId: id, registry: ctx.registry })
+    errors.push(...r.errors)
+    if (!r.field) continue
+    if (seen.has(r.field.key)) { errors.push({ panel: id, code: 'field-key-duplicate', message: `面板 ${id} 字段 key 重复：${r.field.key}` }); continue }
+    seen.add(r.field.key)
+    fields.push(r.field)
+  }
+  // 面板可绑**一个**能力（`capability`）或**一组**能力（`capabilities`）：
+  // 业务线级面板（一个业务线常常横跨多个能力包）⇒ 用"任一已装即显示"的语义，
+  // 避免"只装了 invoice 就看不到飞书表配置"这种自相矛盾的插拔行为。
+  const caps = (Array.isArray(raw.capabilities) ? raw.capabilities : []).map((c) => str(c).trim()).filter(Boolean)
+  const one = str(raw.capability).trim()
+  if (one && !caps.includes(one)) caps.unshift(one)
+  const panel = {
+    id, title,
+    order: Number.isFinite(Number(raw.order)) ? Number(raw.order) : 100,
+    vertical: str(raw.vertical, ctx.vertical || '').trim(),
+    capabilities: caps,
+    hint: str(raw.hint),
+    source: str(ctx.source),
+    fields,
+  }
+  // 面板级档位：显式声明的 minPlan 必须在注册表 planTiers 内；不声明则由**绑定能力的 minPlan**
+  // 派生（`capabilities.<c>.minPlan` 是唯一档位表）。派生失败（没绑能力/能力不在册）⇒ 不设门槛。
+  const tiers = planTiers(ctx.registry)
+  const declaredMin = str(raw.minPlan).trim()
+  if (declaredMin && !tiers.includes(declaredMin)) {
+    errors.push({ panel: id, code: 'panel-minplan-unknown', message: `面板 ${id} 的 minPlan=${declaredMin} 不在注册表 planTiers（${tiers.join('|')}）内` })
+  }
+  let minPlan = ''
+  let minPlanSource = ''
+  if (declaredMin && tiers.includes(declaredMin)) {
+    minPlan = declaredMin
+    minPlanSource = 'declared'
+  } else if (!declaredMin) {
+    const capDoc = (ctx.registry && ctx.registry.capabilities) || {}
+    const got = caps.map((c) => str((capDoc[c] || {}).minPlan)).filter((p) => tiers.includes(p))
+    if (got.length) {
+      // 「任一已装即显示」⇒ 取**最低**档：账号够其中一个能力，这一页就有用
+      minPlan = got.reduce((a, b) => (tiers.indexOf(b) < tiers.indexOf(a) ? b : a))
+      minPlanSource = 'derived'
+    }
+  }
+  panel.minPlan = minPlan
+  panel.minPlanSource = minPlanSource
+  // 字段级档位必须比面板级**更严**，否则那条声明**永远不可达**（面板先被滤掉了，字段级根本轮不到）
+  // —— 不可达声明按"死代码"处理：报错，不静默（本仓库在 dsh-restart.sh 的 exit 之后吃过同款亏）。
+  if (fields.some((f) => f.minPlan)) {
+    const panelRank = minPlan ? planRank(minPlan, tiers) : -1
+    for (const f of fields) {
+      if (!f.minPlan) continue
+      if (planRank(f.minPlan, tiers) <= panelRank) {
+        errors.push({
+          panel: id, code: 'field-minplan-unreachable',
+          message: `面板 ${id} 字段 ${f.key} 的 minPlan=${f.minPlan} 不高于面板级（${minPlan || '不限'}）⇒ 该声明永远不可达（要它有意义就得比面板级更严；否则删掉）`,
+        })
+      }
+    }
+  }
+  if (!caps.length && !panel.vertical) errors.push({ panel: id, code: 'panel-no-binding', message: `面板 ${id} 既没绑能力也没绑业务线 ⇒ 无法判定是否已安装` })
+  return { panel, errors }
+}
+
+/** 从业务线 manifest 取面板声明（`settingsPanel` 单数 或 `settingsPanels` 数组，两者都认）。 */
+export function panelsFromVerticalManifest(man, verticalId, registryDoc) {
+  const out = []
+  const raw = man && man.settingsPanels
+  const list = Array.isArray(raw) ? raw : (isObj(man && man.settingsPanel) ? [man.settingsPanel] : [])
+  for (const r of list) out.push(normalizePanel(r, { source: `verticals/${verticalId}/manifest.json`, vertical: verticalId, registry: registryDoc }))
+  return out
+}
+
+/** 从注册表能力包取面板声明（`capabilities.<c>.pack.settingsPanel`，引擎级/无 vertical 的能力用）。 */
+export function panelsFromRegistry(doc) {
+  const out = []
+  for (const [cap, spec] of Object.entries((doc && doc.capabilities) || {})) {
+    if (!isObj(spec)) continue
+    const pack = isObj(spec.pack) ? spec.pack : {}
+    const raw = pack.settingsPanels
+    const list = Array.isArray(raw) ? raw : (isObj(pack.settingsPanel) ? [pack.settingsPanel] : [])
+    for (const r of list) {
+      // 注册表位置天然知道自己是哪个能力 ⇒ 面板没显式声明时自动绑定（安装判定按能力走）
+      const rawOne = isObj(r) && !r.capability && !Array.isArray(r.capabilities) ? { ...r, capability: cap } : r
+      out.push(normalizePanel(rawOne, { source: `capabilities.${cap}.pack.settingsPanel`, vertical: '', registry: doc }))
+    }
+  }
+  return out
+}
+
+/** 声明合并：同一 id 出现两次 ⇒ 记错误（不静默取其一，两份真相必须先吵出来）。 */
+export function mergeDeclaredPanels(batches) {
+  const panels = []
+  const errors = []
+  const byId = new Map()
+  for (const { panel, errors: errs } of batches) {
+    errors.push(...errs)
+    if (!panel) continue
+    if (byId.has(panel.id)) {
+      errors.push({ panel: panel.id, code: 'panel-id-duplicate', message: `面板 id 重复：${panel.id}（${byId.get(panel.id).source} 与 ${panel.source}）` })
+      continue
+    }
+    // 面板未显式声明 capability 时：业务线 manifest 只挂一个能力 ⇒ 用它（否则按业务线判定）
+    if (!Array.isArray(panel.capabilities)) panel.capabilities = []
+    byId.set(panel.id, panel)
+    panels.push(panel)
+  }
+  panels.sort((a, b) => (a.order - b.order) || a.id.localeCompare(b.id))
+  return { panels, errors }
+}
+
+/**
+ * 声明汇总（唯一的"读声明"入口）：业务线 manifest + 注册表能力包 ⇒ 归一化 + 合并。
+ * `buildPanelsDoc`（读）与 `collectEnvWriteTargets`（写白名单）**共用**它 ——
+ * 读写两套各读一遍声明，迟早会漂。返回 `{ panels, errors }`（panels = **全部声明**，未按装/档位过滤）。
+ */
+export function gatherDeclaredPanels(opts = {}) {
+  const doc = opts.registryDoc || {}
+  const errors = []
+  const batches = []
+  const vroot = join(opts.root || '.', 'verticals')
+  for (const vid of listDir(vroot)) {
+    let man = null
+    try { man = JSON.parse(readFileSync(join(vroot, vid, 'manifest.json'), 'utf-8')) } catch { continue }
+    const b = panelsFromVerticalManifest(man, vid, doc)
+    // 该业务线的能力清单（manifest.capabilities）——面板只挂一个能力时自动绑定，安装判定更准
+    const caps = (Array.isArray(man.capabilities) ? man.capabilities : []).map((c) => str(c && c.id)).filter(Boolean)
+    for (const one of b) {
+      if (!one.panel.capabilities.length && caps.length === 1) one.panel.capabilities = [caps[0]]
+    }
+    batches.push(...b)
+  }
+  batches.push(...panelsFromRegistry(doc))
+  const merged = mergeDeclaredPanels(batches)
+  errors.push(...merged.errors)
+  return { panels: merged.panels, errors }
+}
+
+// ── ② 安装 / 启用判定 ────────────────────────────────────────────────
+/** 装机清单：`<dshHome>/argent/install.json`（安装器写入；开发机常常没有 ⇒ 不能当唯一判据）。 */
+export function readInstallJson(dataDir) {
+  try { return JSON.parse(readFileSync(join(dataDir, 'install.json'), 'utf-8')) } catch { return null }
+}
+
+/**
+ * 「已购」事实（针对性安装，2026-10-09）—— 从 `install.json#entitlement` 读（服务端 install-ticket
+ * 的 `entitlement` 块，安装器原样落盘）。
+ *
+ * ⛔ 这不是判定，是**转述服务端说过的话**：本函数不做任何档位比较、不猜、不补默认值。
+ *   · 清单里**没有** `entitlement`（旧装机 / 安装器未落盘）⇒ `known=false`（未知），
+ *     调用方**只能**退回"未装即不显示 + 未开通"，**不得**据此报红或冒"缺件"；
+ *   · `mode==='plan'` ⇒ 该账号**没有**被按购买裁剪（= 按套餐下发，既有客户形态），
+ *     `granted` 里没有的能力**不是"未购"**，只是该档位本来就没有 ⇒ 一律算"未开通"；
+ *   · `mode==='explicit'` ⇒ `granted` 就是"已购 ∩ 套餐允许"，不在里面的 = **未购**。
+ */
+export function readEntitlement(installJson) {
+  const e = isObj(installJson) && isObj(installJson.entitlement) ? installJson.entitlement : null
+  if (!e) return { known: false, mode: '', granted: [], entitled: null, withheld: [] }
+  const mode = str(e.mode)
+  const granted = Array.isArray(e.granted) ? e.granted.map(str).filter(Boolean) : []
+  return {
+    known: mode === 'plan' || mode === 'explicit',
+    mode,
+    granted,
+    entitled: Array.isArray(e.entitled) ? e.entitled.map(str).filter(Boolean) : null,
+    // withheld = 套餐允许但未购（服务端点名）。⛔ 只用于如实显示"未购"，**不是**错误清单。
+    withheld: Array.isArray(e.withheld) ? e.withheld.map((w) => str(isObj(w) ? w.id : w)).filter(Boolean) : [],
+    planAllowed: Array.isArray(e.planAllowed) ? e.planAllowed.map(str).filter(Boolean) : [],
+  }
+}
+
+/**
+ * 某个能力包的「已购」三态：`true` 已购 / `false` 未购 / `null` 未知（⛔ 未知**不是**未购）。
+ *
+ * 判据优先级：
+ *   ① 有服务端已购清单且 `mode==='explicit'` ⇒ 以 `granted` 为准（权威）；
+ *   ② `mode==='plan'` ⇒ 该账号未被裁剪 ⇒ 档位够就是"已购"，档位不够是"未开通"（**不称未购**）；
+ *   ③ 无清单 ⇒ `null`，由调用方按"未开通"中性呈现。
+ * 多能力面板（`capabilities:[...]`）取**任一**命中即可（与 `detectInstall` 的多能力口径一致）。
+ */
+export function entitlementOfPanel(caps, ctx) {
+  const ent = ctx.entitlement || { known: false }
+  const list = (Array.isArray(caps) ? caps : []).map(str).filter(Boolean)
+  if (!list.length) return null
+  if (ent.known && ent.mode === 'explicit') return list.some((c) => ent.granted.includes(c))
+  if (ent.known && ent.mode === 'plan') return null   // 未裁剪 ⇒ "未购"这个概念不适用（见 doc.entitlement.note）
+  return null
+}
+
+/** 目录下的条目名（不存在 ⇒ 空数组）。 */
+function listDir(dir) {
+  try { return readdirSync(dir).filter((d) => !d.startsWith('.')) } catch { return [] }
+}
+
+/**
+ * 能力是否「已安装」。判据分两级（返回值带 `source`/`detail` 供排障与验收）：
+ *
+ *  ① **权威来源**：`install.json` 里有非空 capabilities ⇒ 以它为准（客户机装机记录；
+ *     有记录但**不含**该能力 ⇒ 未安装，不再看线索 —— 权威说了算）。
+ *  ② **正面证据**（没有任何 install.json 的开发机/老装机形态，按强度取第一条命中）：
+ *     · 该能力声明的技能至少装了一个（`~/.dsh/skills/<skill>`）
+ *     · 该能力声明的 preset 至少装了一个（`~/.dsh/.agent-presets/<preset>`）
+ *     · 能力包缓存存在（`~/.dsh/argent/packs-cache/<cap>-<版本>/PACK.json`）
+ *  全不命中 ⇒ 未安装，并给出最可能的原因（"应有技能 xxx 一个都没装"）——
+ *  **这就是"未装即不显示"的判据**：没有正面证据，能力包的设置页就不会出现。
+ */
+export function detectInstall(cap, pack, ctx) {
+  const home = ctx.home
+  const dataDir = ctx.dataDir
+  const skills = (pack.skills || []).map((s) => str(s).replace(/^skills\//, '')).filter(Boolean)
+  const presets = (pack.presets || []).map((s) => str(s).split('/').pop()).filter(Boolean)
+  const install = ctx.installJson || null
+  // 装机清单两种形态都认：安装器写 `[{id, version, …}]`，手写夹具/手工记录常写 `["full", …]`。
+  // （2026-10-01 修：只认对象形态时，`{"capabilities":["daily-report"]}` 会被当成"没有记录"⇒ 静默落到线索兜底）
+  const recorded = install && Array.isArray(install.capabilities)
+    ? install.capabilities.map((c) => str(c && typeof c === 'object' ? c.id : c)).filter(Boolean)
+    : []
+  if (recorded.length) {
+    const hit = recorded.includes(cap)
+    return { installed: hit, source: 'install.json', detail: hit ? 'install.json 已登记' : 'install.json 未登记该能力' }
+  }
+  const installedSkills = ctx.installedSkills || listDir(join(home, '.dsh', 'skills'))
+  const hitSkills = skills.filter((s) => installedSkills.includes(s))
+  if (hitSkills.length) return { installed: true, source: 'skills', detail: `已装技能 ${hitSkills.join('、')}` }
+  const installedPresets = ctx.installedPresets || listDir(join(home, '.dsh', '.agent-presets'))
+  const hitPresets = presets.filter((p) => installedPresets.includes(p))
+  if (hitPresets.length) return { installed: true, source: 'presets', detail: `已装 preset ${hitPresets.join('、')}` }
+  const cache = listDir(join(dataDir, 'packs-cache'))
+  const hitCache = cache.filter((d) => d.startsWith(`${cap}-`))
+  if (hitCache.length) return { installed: true, source: 'packs-cache', detail: `包缓存 ${hitCache.slice(-1)[0]}` }
+  if (skills.length) return { installed: false, source: 'skills', detail: `技能一个都没装（应有：${skills.join('、')}）` }
+  if (presets.length) return { installed: false, source: 'presets', detail: `preset 一个都没装（应有：${presets.join('、')}）` }
+  return { installed: false, source: 'none', detail: '没有任何安装证据' }
+}
+
+/**
+ * 能力是否「启用」：已安装 + 它声明的流程**不是全被暂停**。
+ * 暂停判据与 `flow-trigger.sh` 同源：注册表 `trigger.pauseSwitch`（业务线命名空间）
+ * 与 `trigger.pauseSwitchLegacy`（迁移期兼容名），在数据目录下存在任一即暂停。
+ */
+export function detectEnabled(cap, flows, ctx) {
+  const mine = Object.entries(flows || {}).filter(([, f]) => isObj(f) && str(f.capability) === cap)
+  const dataDir = ctx.dataDir
+  const paused = []
+  for (const [fid, f] of mine) {
+    const t = isObj(f.trigger) ? f.trigger : {}
+    const cands = [str(t.pauseSwitch), str(t.pauseSwitchLegacy)].filter(Boolean)
+    const hit = cands.find((rel) => existsSync(join(dataDir, rel)))
+    if (hit) paused.push({ flow: fid, switch: hit })
+  }
+  const allPaused = mine.length > 0 && paused.length === mine.length
+  return { enabled: !allPaused, flows: mine.map(([fid]) => fid), pausedFlows: paused }
+}
+
+// ── ③ 字段取值（只读）────────────────────────────────────────────────
+
+/** 解析一个目录下所有 `*.env`（`KEY=VALUE`；同名 KEY 按文件名排序取第一个）。 */
+export function parseEnvDir(dir) {
+  const map = new Map()
+  for (const name of listDir(dir).filter((n) => n.endsWith('.env')).sort()) {
+    let text = ''
+    try { text = readFileSync(join(dir, name), 'utf-8') } catch { continue }
+    for (const line of text.split('\n')) {
+      const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line)
+      if (!m) continue
+      let v = m[2].trim()
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1)
+      if (!map.has(m[1])) map.set(m[1], { value: v, file: name })
+    }
+  }
+  return map
+}
+
+/**
+ * `from: "config"` 里**由 host 投影**（不在 config.json 原文里）的键。
+ *
+ * 为什么需要它：`GET /api/argent-state/config` 是这些值的**唯一出处**（它算 `…Configured` /
+ * `…Masked` / `…Count` 这类派生键）。聚合器是**仓库侧离线**脚本，读不到端点的
+ * 计算结果 ⇒ 只能标 `deferred: true`，由**客户端渲染时**用一次 `GET /api/argent-state/config` 补齐。
+ * 这里刻意**不重写**投影公式（第二份真相必然漂移）：聚合器只做 best-effort 回显 + 明确标注。
+ */
+export const PROJECTED_KEY_SUFFIXES = ['Configured', 'Masked', 'Count']
+/** 该 config 键是否由 host 端点投影（不在 config.json 原文里）。 */
+export const isProjectedConfigKey = (key) => PROJECTED_KEY_SUFFIXES.some((suf) => String(key || '').endsWith(suf))
+
+/** 字段在 env 里的作用域目录。 */
+function envDirFor(field, panel, ctx) {
+  return field.scope === 'user'
+    ? ctx.dataDir
+    : join(ctx.dataDir, 'verticals', panel.vertical || '_unknown', 'env')
+}
+
+/**
+ * `from: "roles"` 的取值来源：`~/.dsh/argent/gateway.json` 的角色表（**只读**摘要）。
+ * 给"入口 = 角色会话"的能力（如 HR 办公）用：它没有可配置参数，但「入口装没装、开没开」
+ * 是用户真正关心的事实。**只读**：角色/ Bot 凭据的写入口是网关的角色端点，不是本契约。
+ */
+export function readGatewayRoles(ctx) {
+  if (!ctx._gatewayRoles) {
+    try {
+      const doc = JSON.parse(readFileSync(join(ctx.dataDir, 'gateway.json'), 'utf-8'))
+      ctx._gatewayRoles = Array.isArray(doc.roles) ? doc.roles : []
+    } catch { ctx._gatewayRoles = [] }
+  }
+  return ctx._gatewayRoles
+}
+
+/**
+ * env 字段的写入目标（**只由声明推导**，请求体里永远不带路径）。
+ * 路径规则：`scope: vertical` ⇒ `<dataDir>/verticals/<业务线>/env/<envFile>`；
+ *          `scope: user`     ⇒ `<dataDir>/<envFile>`。
+ * 四道口子（任一不满足 ⇒ 该字段只读，不猜、不放宽）：
+ *   ① 声明了 `envFile` 且形状合法（`<名>.env`，无路径分隔符/上跳）；
+ *   ② scope=vertical 时必须知道业务线（面板声明里补的 `vertical`）；
+ *   ③ 拼出来的绝对路径必须**落在数据目录内**（防穿越）；
+ *   ④ 数据目录必须是绝对路径（相对路径无从校验 ⇒ 拒绝）。
+ */
+export function resolveEnvWriteTarget(panel, field, ctx) {
+  const file = str(field.envFile).trim()
+  if (!file) return { ok: false, error: '该字段没声明 envFile ⇒ 不允许写入（不猜路径）' }
+  if (!ENV_FILE_RE.test(file)) return { ok: false, error: `envFile=${file} 形状非法（只允许 <名>.env）` }
+  const rawDir = str(ctx.dataDir)
+  // ④ 必须是**绝对路径**：相对路径会跟着 cwd 走，"在数据目录内"的校验就失去意义 ⇒ 拒绝
+  if (!rawDir || !rawDir.startsWith('/')) return { ok: false, error: '数据目录不是绝对路径 ⇒ 拒绝写入' }
+  const root = resolvePath(rawDir)
+  let base
+  if (field.scope === 'user') {
+    base = root
+  } else {
+    const v = str(panel.vertical).trim()
+    if (!v || /[\\/]|\.\./.test(v)) return { ok: false, error: '面板没绑（或绑了非法）业务线 ⇒ 不知道写哪个 env 目录' }
+    base = join(root, 'verticals', v, 'env')
+  }
+  const abs = resolvePath(join(base, file))
+  if (!(abs === root || abs.startsWith(root + sep))) return { ok: false, error: '解析出的路径不在数据目录内 ⇒ 拒绝' }
+  return { ok: true, path: abs, rel: abs.slice(root.length + 1), envFile: file }
+}
+
+/**
+ * env 写入器的**白名单**：`<面板 id>::<字段 key>` → 目标文件。
+ * 这是写入器唯一的合法性来源 —— 请求体只带这个复合键与值，**不带路径**。
+ * @returns {{targets: Map<string, object>, errors: Array}} errors = 因声明问题**没有**写目标的 env 字段
+ */
+export function collectEnvWriteTargets(opts = {}) {
+  const home = opts.home
+  // 库函数只认调用方给的 `home`（宿主 env 由调用方解析后经 `opts.dataDir` 传入）；
+  // 默认值仍取自**内核判据**（`env: {}` = 不做环境覆盖），不在这里拼第二份 ~/.dsh/argent。
+  const dataDir = opts.dataDir || resolveDataDir({ env: {}, home }).dir
+  const ctx = { home, dataDir }
+  const gathered = opts.panels ? { panels: opts.panels, errors: [] } : gatherDeclaredPanels(opts)
+  const targets = new Map()
+  const errors = []
+  for (const p of gathered.panels) {
+    for (const f of p.fields || []) {
+      if (!f.env) continue                       // 不是 env 字段：不归写入器管
+      const t = resolveEnvWriteTarget(p, f, ctx)
+      if (!t.ok) { if (f.envFile) errors.push({ panel: p.id, field: f.key, code: 'env-target-unresolved', message: `${p.id}::${f.key} 写目标不可用：${t.error}` }); continue }
+      targets.set(`${p.id}::${f.key}`, {
+        panelId: p.id, panelTitle: p.title, field: f.key, label: f.label, type: f.type,
+        env: f.env, scope: f.scope, vertical: p.vertical, path: t.path, rel: t.rel, envFile: t.envFile,
+      })
+    }
+  }
+  return { targets, errors }
+}
+
+/**
+ * 解析字段当前值 → `{ configured, value, masked, from, file, note }`。
+ * 规则（与文档逐条对应）：
+ *   · password ⇒ 只回 configured + masked（value 恒空）
+ *   · switch   ⇒ value 为布尔
+ *   · text/select ⇒ value 为字符串（截断 200 字）
+ *   · `read.from: json` ⇒ 读 `pathFromEnv` 指向的 JSON（路径只认 env，不接任意路径）
+ */
+export function resolveFieldValue(field, panel, ctx) {
+  const read = field.read
+  const from = read ? read.from : (field.env ? 'env' : '')
+  const out = { configured: false, value: '', masked: '', from: from || 'none', file: '', note: '' }
+  let raw
+  if (from === 'config') {
+    const cfg = ctx.config || {}
+    const key = read.key || field.key
+    raw = cfg[key]
+    out.from = `config.json:${key}`
+    if (isProjectedConfigKey(key)) {
+      out.deferred = true
+      out.note = '该键由 host 的 GET /api/argent-state/config 投影（config.json 原文里没有）⇒ 渲染时以端点值为准'
+    }
+  } else if (from === 'json') {
+    const envName = read.pathFromEnv
+    const dir = envDirFor(field, panel, ctx)
+    ctx._envCache = ctx._envCache || new Map()
+    if (!ctx._envCache.has(dir)) ctx._envCache.set(dir, parseEnvDir(dir))
+    const path = (ctx._envCache.get(dir).get(envName) || {}).value || ''
+    if (!path) { out.note = `env ${envName} 未配置（拿不到文件路径）`; return finish(field, out, undefined) }
+    let doc = null
+    try { doc = JSON.parse(readFileSync(path, 'utf-8')) } catch { out.note = `读不到 ${path}`; return finish(field, out, undefined) }
+    const keys = isObj(doc) ? Object.keys(doc) : (Array.isArray(doc) ? doc.map((x) => str(x && x.id || x)) : [])
+    raw = keys.length ? `${keys.length} 个：${keys.slice(0, 12).join('、')}${keys.length > 12 ? ' …' : ''}` : ''
+    out.from = `${envName}=${path}`
+    out.file = path
+  } else if (from === 'roles') {
+    // 会话入口装配状态（gateway.json）——只读摘要，给"入口 = 某条线的持久会话"的能力用
+    const role = (read && read.key) || field.key
+    const hit = readGatewayRoles(ctx).find((r) => str(r && r.role) === role)
+    out.from = `gateway.json:${role}`
+    out.file = 'gateway.json'
+    if (!hit) {
+      // W7.6（2026-10-14）：原文指向「Argent 能力」页的「角色」页签 —— 该页签已删除
+      // （角色 = DSH preset，Argent 侧不再复述角色清单）⇒ 改指**配置本体**与官方预设区。
+      out.note = `gateway.json 里没有 ${role} 这条会话入口（在网关配置 gateway.json#roles 里补齐；`
+        + '角色 = DSH 预设，见 设置 →「Agent 预设」）'
+      return finish(field, out, undefined)
+    }
+    raw = `已装配（自主接单：${hit.autonomous === false ? '关' : '开'} · Bot：${hit.botAppId ? '已配' : '未配'}`
+      + `${Array.isArray(hit.skills) && hit.skills.length ? ` · 技能 ${hit.skills.length} 个` : ''}）`
+  } else if (from === 'env') {
+    const name = (read && read.key) || field.env
+    const dir = envDirFor(field, panel, ctx)
+    ctx._envCache = ctx._envCache || new Map()
+    if (!ctx._envCache.has(dir)) ctx._envCache.set(dir, parseEnvDir(dir))
+    const envMap = ctx._envCache.get(dir)
+    const hit = envMap.get(name)
+    raw = hit ? hit.value : undefined
+    out.file = hit ? hit.file : ''
+    out.from = `env:${name}`
+  } else {
+    out.note = '没有声明取值来源'
+    return finish(field, out, undefined)
+  }
+  return finish(field, out, raw)
+}
+
+function finish(field, out, raw) {
+  if (field.type === 'switch') {
+    out.value = raw === true || raw === 'true' || raw === '1' || raw === 1
+    out.configured = out.value === true
+    return out
+  }
+  if (field.type === 'password') {
+    // 声明方可直接把 read.key 指向布尔投影（如 `feishuAppSecretConfigured`）⇒ 只认"配没配"
+    if (typeof raw === 'boolean') { out.configured = raw; out.masked = ''; out.value = ''; return out }
+    const s = str(raw)
+    out.configured = !!s
+    out.masked = maskSecret(s)
+    out.value = ''   // 红线：密码字段绝不回明文
+    return out
+  }
+  const s = str(raw)
+  out.configured = !!s
+  out.value = s.length > 200 ? `${s.slice(0, 200)}…` : s
+  return out
+}
+
+// ── ④ 汇总入口 ───────────────────────────────────────────────────────
+
+/**
+ * 账号档位从哪来（**只认本机已有的权威记录**，不联网、不问服务端）：
+ *   ① `opts.accountPlan`（调用方显式给：CLI `--plan` / 测试夹具）
+ *   ② env `ARGENT_ACCOUNT_PLAN`（运维/隔离测试用）
+ *   ③ `~/.dsh/argent/install.json#plan`（安装器记录的**服务端套餐**，客户机形态）
+ *   ④ 都拿不到 ⇒ `known: false` ⇒ **不做任何档位过滤**（与 assertFeishuAllowed 同口径：
+ *      查不到就放行，宁可多显示一页，也不要把付费客户锁在门外；真正的授权判定在服务端）。
+ */
+export function resolveAccountPlan(opts = {}) {
+  const explicit = str(opts.accountPlan).trim()
+  if (explicit) return { value: explicit, source: 'arg', known: true }
+  const fromEnv = str((opts.env || {}).ARGENT_ACCOUNT_PLAN).trim()
+  if (fromEnv) return { value: fromEnv, source: 'env', known: true }
+  const fromInstall = str((opts.installJson || {}).plan).trim()
+  if (fromInstall) return { value: fromInstall, source: 'install.json', known: true }
+  return { value: '', source: 'unknown', known: false }
+}
+
+/**
+ * 产出面板聚合文档（`GET /api/argent-gateway/settings-panels` 与 catalog 的共同数据源）。
+ * @param {{root:string, home:string, dataDir?:string, registryDoc:object, env?:object,
+ *          accountPlan?:string, envWriter?:boolean}} opts
+ *   root = 仓库根（读 verticals/）；home = 用户家目录（读 skills/presets）；dataDir = `~/.dsh/argent`；
+ *   accountPlan = 账号档位（缺省按 {@link resolveAccountPlan} 自己找）；envWriter = 覆盖写入器开关。
+ */
+export function buildPanelsDoc(opts) {
+  const home = opts.home
+  const dataDir = opts.dataDir || resolveDataDir({ env: {}, home }).dir   // 同 collectEnvWriteTargets：默认值来自内核
+  const doc = opts.registryDoc || {}
+  const ctx = {
+    home, dataDir,
+    env: opts.env || process.env,
+    installJson: readInstallJson(dataDir),
+    config: (() => { try { return JSON.parse(readFileSync(join(dataDir, 'config.json'), 'utf-8')) } catch { return {} } })(),
+  }
+  ctx.entitlement = readEntitlement(ctx.installJson)
+  const tiers = planTiers(doc)
+  const account = resolveAccountPlan({ accountPlan: opts.accountPlan, env: ctx.env, installJson: ctx.installJson })
+  const envWriter = opts.envWriter === undefined ? isEnvWriterEnabled(ctx.env) : !!opts.envWriter
+  const gathered = gatherDeclaredPanels({ root: opts.root, registryDoc: doc })
+  const errors = [...gathered.errors]
+  const envTargets = collectEnvWriteTargets({ panels: gathered.panels, dataDir }).targets
+  const packOf = (cap) => {
+    const spec = (doc.capabilities || {})[cap]
+    return isObj(spec) && isObj(spec.pack) ? spec.pack : {}
+  }
+  const hiddenByPlan = []
+  const panels = gathered.panels.map((p) => {
+    // 安装判定：绑了能力 ⇒ **任一已装即已装**（并在 evidence 里给出每个能力的证据）；
+    // 没绑能力（纯业务线面板）⇒ 按业务线 id 自身证据判。
+    const caps = p.capabilities.length ? p.capabilities : [p.vertical]
+    const per = caps.filter(Boolean).map((cap) => {
+      const d = detectInstall(cap, packOf(cap), ctx)
+      return { capability: cap, ...d }
+    })
+    const hit = per.find((x) => x.installed) || null
+    const install = hit
+      ? { installed: true, source: hit.source, detail: `${hit.capability}：${hit.detail}` }
+      : { installed: false, source: (per[0] || {}).source || 'none', detail: per.map((x) => `${x.capability}：${x.detail}`).join('；') || '没有任何安装证据' }
+    const run = { enabled: false, flows: [], pausedFlows: [] }
+    for (const cap of caps) {
+      const r = detectEnabled(cap, doc.flows, ctx)
+      run.flows.push(...r.flows)
+      run.pausedFlows.push(...r.pausedFlows)
+      if (r.enabled) run.enabled = true
+    }
+    // 档位闸门：**服务端算成布尔**（客户端只认 planGated，仍然零档位名单）。
+    // 账号档位未知（known=false）⇒ 一律不放闸（planGated=false）。
+    const gated = !!(account.known && p.minPlan) && planRank(account.value, tiers) < planRank(p.minPlan, tiers)
+    if (gated) {
+      hiddenByPlan.push({
+        kind: 'panel',
+        id: p.id, title: p.title, minPlan: p.minPlan,
+        reason: `账号档位 ${account.value}（来自 ${account.source}）低于该面板要求的 ${p.minPlan}`,
+      })
+    }
+    // 字段级档位（契约 §11，2026-10-01）：与面板级**同一条链、同一个 planRank**，只是粒度更细。
+    // 被滤掉的字段**从载荷里整个消失**（客户端只认服务端给的 fields[]，不做任何判定 ⇒ 零名单），
+    // 同时在 hiddenByPlan[] 里给一条 `kind: 'field'` 的原因（页面上不占位，排障说得清）。
+    // 面板自身已被滤掉时不再为它的字段记条目：整页都不出现，逐字段列出来只是噪音。
+    let fieldsHiddenByPlan = 0
+    const fields = []
+    for (const f of p.fields) {
+      if (!gated && account.known && f.minPlan && planRank(account.value, tiers) < planRank(f.minPlan, tiers)) {
+        fieldsHiddenByPlan += 1
+        hiddenByPlan.push({
+          kind: 'field', panel: p.id, panelTitle: p.title,
+          field: f.key, label: f.label, minPlan: f.minPlan,
+          reason: `账号档位 ${account.value}（来自 ${account.source}）低于该字段要求的 ${f.minPlan}`,
+        })
+        continue
+      }
+      const v = resolveFieldValue(f, p, ctx)
+      // 写入口：① 声明里显式给的既有端点；② env 字段 + 写入器已开 + 目标可解析 ⇒ 走受控 env 写入器
+      let write = f.write
+      let writeNote = ''
+      if (!write && f.env) {
+        const t = envTargets.get(`${p.id}::${f.key}`)
+        // 顺序有讲究：先看"有没有合法写目标"（声明问题，与开关无关），再看开关是否打开 ——
+        // 否则用户会看到"写入器没开"这种**误导性**原因（其实是这个字段永远不可写）。
+        if (!t) writeNote = '该字段没有可用的 env 写目标（声明里缺 envFile 或路径不合法）'
+        else if (!envWriter) writeNote = `env 写入器默认关闭（${ENV_WRITER_ENV}=1 并重启 dsh 后可改）`
+        else write = { endpoint: ENV_WRITE_ENDPOINT, field: `${p.id}::${f.key}`, envTarget: t.rel }
+      }
+      // 注意：**不回** `minPlan`（字段对象里不带档位信息）—— 客户端拿到的永远是"已经滤好的清单"，
+      // 这样"客户端零档位名单"才是一条可断言的性质，而不是"约定前端别用"。
+      fields.push({
+        key: f.key, label: f.label, type: f.type, env: f.env, scope: f.scope, envFile: f.envFile,
+        placeholder: f.placeholder, hint: f.hint, options: f.options,
+        readonly: !write,
+        write,
+        // 只读原因（客户端渲染小字；不改判定，判定就在上面的 write）
+        writeNote,
+        // readKey：客户端补齐 deferred 值时按这个键去 host 端点取（`from` 只给排障看，不做解析）
+        readKey: f.read ? (f.read.key || '') : '',
+        configured: v.configured, value: v.value, masked: v.masked, from: v.from, file: v.file, note: v.note,
+        // deferred=true ⇒ 聚合器读不到（host 投影键），客户端用 GET /api/argent-state/config 补齐
+        deferred: !!v.deferred,
+      })
+    }
+    // 已购三态（true 已购 / false 未购 / null 未知）。⛔ null ≠ 未购；未购/未装都**不是异常、不是缺件**，
+    // 呈现口径一律是"未开通"（见 doc.entitlement.note 与本文件 note）。算一次，别在下面重复调 4 遍。
+    const entitled = entitlementOfPanel(p.capabilities, ctx)
+    return {
+      id: p.id, title: p.title, order: p.order,
+      vertical: p.vertical, capabilities: p.capabilities, hint: p.hint, source: p.source,
+      minPlan: p.minPlan, minPlanSource: p.minPlanSource, planGated: gated,
+      installed: install.installed, installSource: install.source, installDetail: install.detail,
+      installEvidence: per,
+      entitled,
+      // 四态汇总（给人看的标签，判定仍看 installed/entitled 两个事实）：
+      // 已开通 / 已购·未装 / 已装·未购 / 未开通（后三者**都不是异常**）
+      state: !install.installed
+        ? (entitled === true ? '已购·未装' : '未开通')
+        : (entitled === false ? '已装·未购' : '已开通'),
+      enabled: install.installed ? run.enabled : false,
+      flows: [...new Set(run.flows)], pausedFlows: run.pausedFlows,
+      fields,
+      // 因档位被滤掉的字段**数量**（服务端算好的事实；客户端据此只显示一句"另有 n 项不显示"）
+      fieldsHiddenByPlan,
+    }
+  })
+  return {
+    ok: errors.length === 0,
+    generatedAt: new Date().toISOString(),
+    panels,
+    plan: { value: account.value, source: account.source, known: account.known, tiers,
+      note: account.known ? '' : '拿不到账号档位（无 --plan / ARGENT_ACCOUNT_PLAN / install.json.plan）⇒ 不做档位过滤' },
+    entitlement: { ...ctx.entitlement,
+      note: '已购事实来自 install.json#entitlement（服务端 install-ticket 原样落盘），本文件只转述、不做档位比较。'
+        + 'mode=plan ⇒ 该账号**未**按购买裁剪（既有客户形态）⇒ 没有"未购"这个概念，未下发的能力一律显示"未开通"；'
+        + 'mode=explicit ⇒ granted 之外的能力即"未购"。known=false（旧装机没有这一块）⇒ 一律按"未开通"中性呈现。'
+        + '⛔ 未购 / 未装都**不是异常、不是缺件**，任何呈现都不得报红。' },
+    envWriter: { enabled: envWriter, switch: ENV_WRITER_ENV, endpoint: ENV_WRITE_ENDPOINT,
+      targets: [...envTargets.keys()] },
+    hiddenByPlan,
+    errors,
+    note: '能力包设置页契约：面板由 verticals/<id>/manifest.json#settingsPanel(s) 或 capabilities.<c>.pack.settingsPanel 声明；'
+      + 'installed=false 的面板客户端**不渲染**（未装即不显示）；planGated=true 的面板、以及字段级 minPlan 不够的字段，'
+      + '都由**服务端**按账号档位滤掉（客户端零名单；被滤的面板/字段在 hiddenByPlan[] 里给原因）；'
+      + '值只读、只来自 config/env/json/roles；env 字段在 ' + ENV_WRITER_ENV + '=1 时走受控写入器（写前备份 + 写后读回 + 审计），'
+      + '非 env 字段只复用既有端点。'
+      + '⚠️ 呈现口径（2026-10-09）：未装（installed=false）与未购（entitled=false）**都不是异常、不是缺件**，'
+      + '只是"未开通"；二者只影响"显不显示"，绝不产生错误标记。',
+  }
+}