@tbox.cn/app-toolkit 0.2.0 → 0.4.0

package/src/integrations/write.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import Ajv from 'ajv';
 import { resolveContractsForApp } from '../core/contracts-resolver.js';
+import { stemToFilePath } from '../core/credential-format.js';
 import type { FileCache } from '../core/file-cache.js';
 import { writeAtomic } from '../core/fskit.js';
 import { SAFE_NAME_PATTERN } from '../core/module-schema.js';
@@ -36,8 +37,9 @@ import { AppToolkitError } from '../core/errors.js';
  *  7 严格整文档校验（contracts parseIntegrationsConfig——触发 = !noDiff ∥ 有凭据输入）
  *  8 凭据工件落盘（**后置于校验通过**——防「凭据已写 + zod 拒绝」不一致态；
  *    dryRun → writeCredentialArtifacts 零写盘 + existsSync 预览）
- *  9 finalize：written = integrations 实写 ∥ 凭据实写（**D-B2**）；files 分列两类路径；
- *    restartScheduled = written && onApplied（凭据影响 boot 装配——重启正当）；写后缓存失效
+ *  9 finalize（D35）：planned = 将触碰（files 预览单源——dryRun 响应 ≡ 同 body 真实写，files 逐字对称）；
+ *    written = 实写（!dryRun 派生，D-B2）；restartScheduled = written && onApplied（凭据影响 boot 装配——
+ *    重启正当）；写后缓存失效
  * 归一化：N1 模块节点 {} → 删 domains[键]；N3 服务节点 {} 不归一化（显式通配激活 = 合法 TIER0 态）；
  * N2 已随 ?instance= 退役。dryRun（PUT only）：复读完整管线不落盘不排程。
  * DELETE：节点移除 + 孤儿凭据写后对账（覆盖 DELETE 与 PUT 替换两类来源，只报告不清理——D9）。
@@ -245,11 +247,13 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
     appliedCredentials: AppliedCredential[],
     issues: IntegrationServiceIssue[],
     dryRun: boolean | undefined,
-    credentialsWritten: boolean,
   ): SaveResult {
-    // D-B2：written ⟺ 任一文件实写；files 分列（integrations.json + 凭据路径）；
-    // restartScheduled 跟随 written（凭据文件影响 boot 装配——重启正当）
-    const integrationsWritten = !dryRun && next !== null;
+    // D35 双轴派生：planned = 将触碰（files 预览单源——dryRun 响应 ≡ 同 body 真实写，files 逐字对称）；
+    // written = 实际落盘（!dryRun 派生——D-B2）；restartScheduled 跟随 written（凭据文件影响 boot 装配——重启正当）
+    const integrationsPlanned = next !== null;
+    const credentialsPlanned = appliedCredentials.length > 0;
+    const integrationsWritten = !dryRun && integrationsPlanned;
+    const credentialsWritten = !dryRun && credentialsPlanned;
     if (integrationsWritten) {
       writeAtomic(join(appDir, INTEGRATIONS_FILE), `${JSON.stringify(next, null, 2)}\n`);
       cache?.invalidate([join(appDir, INTEGRATIONS_FILE)]);
@@ -258,8 +262,8 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
     const restartScheduled = written && onApplied !== undefined;
     if (restartScheduled) onApplied?.();
     const files: string[] = [];
-    if (integrationsWritten) files.push(INTEGRATIONS_FILE);
-    if (credentialsWritten) files.push(...appliedCredentials.map((a) => `config/credentials/${a.stem}.json`));
+    if (integrationsPlanned) files.push(INTEGRATIONS_FILE);
+    if (credentialsPlanned) files.push(...appliedCredentials.map((a) => stemToFilePath(a.stem)));
     return {
       written,
       restartScheduled,
@@ -361,7 +365,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       const dryRun = writeOpts.dryRun === true;
       const applied = writeCredentialArtifacts(appDir, plan, dryRun);
       issues.push(...registryCheck(next));
-      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun, !dryRun && plan.length > 0);
+      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun);
     },
 
     applyModule(moduleId: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
@@ -417,7 +421,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       }
       runStrictValidation(next, issues, `domains.${domainKey}.`);
       issues.push(...registryCheck(next));
-      return finalize(next, [], issues, writeOpts.dryRun, false);
+      return finalize(next, [], issues, writeOpts.dryRun);
     },
 
     applyService(service: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
@@ -474,7 +478,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       const dryRun = writeOpts.dryRun === true;
       const applied = writeCredentialArtifacts(appDir, plan, dryRun);
       issues.push(...registryCheck(next));
-      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun, !dryRun && plan.length > 0);
+      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun);
     },
 
     deleteService(service: string): SaveResult {

package/src/views/app.ts

@@ -1,6 +1,6 @@
 import type { AppView, ServiceDemand } from '../dto.js';
 import { APP_INTEGRATION_NODE_KEYS } from '../dto.js';
-import { moduleOccupiedServices, type ViewSnapshot } from './context.js';
+import { moduleOccupiedServices, resolveServiceDisplay, type ViewSnapshot } from './context.js';
 
 /**
  * 应用静态投影（views/app；C4；FX-1c B10——root 节点投影修；v4.4 D29——services 双端点同型）。
@@ -14,9 +14,13 @@ import { moduleOccupiedServices, type ViewSnapshot } from './context.js';
 
 export function loadAppView(snapshot: ViewSnapshot): AppView {
   const occupied = moduleOccupiedServices(snapshot.walk);
+  // 平台条目展示名走链（B1）：词汇 meta > demand meta > id——title 恒发（id 兜底内聚）
   const services: ServiceDemand[] = snapshot.walk.vocabulary
     .filter((s) => !occupied.has(s))
-    .map((s) => ({ service: s, required: false }));
+    .map((s) => {
+      const display = resolveServiceDisplay(snapshot.walk, s);
+      return { service: s, title: display.title, ...(display.description !== undefined ? { description: display.description } : {}), required: false };
+    });
   const config = snapshot.integrations;
   let integration: AppView['integration'] = null;
   if (config) {

package/src/views/context.ts

@@ -65,3 +65,23 @@ export function suppliedByVendors(catalog: WalkCatalog, service: string): string
   }
   return vendors.sort();
 }
+
+/** 服务展示名解析结果（title 恒有值——id 兜底内聚） */
+export interface ServiceDisplay {
+  title: string;
+  description?: string;
+}
+
+/**
+ * 服务展示名单源（B1）：词汇 meta（slotMeta——contracts-mall 词汇锁保证 mall 域覆盖）
+ * > demand meta（catalog.services——域外槽兜底；首声明聚合）> service id。逐字段回落——
+ * 词汇条目仅含 description 时 demand title 仍可达（外部契约包部分 meta 前向容错）。
+ * 四视图唯一消费点（/modules/:m services、/app 平台条目、/services/:s、/providers/:p services）。
+ */
+export function resolveServiceDisplay(walk: WalkManifestsResult, service: string): ServiceDisplay {
+  const vocab = walk.slotMeta[service];
+  const demand = walk.catalog.services[service];
+  const title = vocab?.title ?? demand?.title ?? service;
+  const description = vocab?.description ?? demand?.description;
+  return { title, ...(description !== undefined ? { description } : {}) };
+}

package/src/views/integration-schemas.ts

@@ -1,21 +1,32 @@
-import type { LayerIntegrationSchemas } from '../dto.js';
+import type { IntegrationFieldRegistryView, LayerIntegrationSchemas, ServiceIntegrationSchemas } from '../dto.js';
 import { isSupplied, type ViewSnapshot } from './context.js';
-import { readSchemaRef } from './providers.js';
-import { moduleDomainWritable, providerFootprint, resolveDomainBinding } from '../integrations/domain-binding.js';
+import { resolveServiceConfigSchema } from './providers.js';
+import { domainOfService, moduleDomainWritable, providerFootprint, resolveDomainBinding } from '../integrations/domain-binding.js';
+import { isControlledInlineProvider } from '../integrations/predicate.js';
 
 /**
- * 层级 config schema 计算视图（v4.4 D32——静态轴富化，零 contracts 求值）。
- * config 表单结构三形态同源（P10）：槽级组合单体（providers.ts）/ 层级内嵌（本文件——
- * /app、/modules/:m include）/ 供给轴批量（providers.ts include——切换态）。
+ * 层级/服务级 config schema 计算视图（v4.4 D32——静态轴富化，零 contracts 求值；v4.7 D38 服务级）。
+ * config 表单结构四形态同源（P10）：槽级组合单体（providers.ts）/ 层级内嵌（本文件——
+ * /app、/modules/:m include）/ 供给轴批量（providers.ts include——切换态）/ 服务级生效绑定
+ * （本文件 loadServiceIntegrationSchemas——/services/:s include）。
  *
  * 计算规则（D32 裁决）：禁交集——config 五层浅合并下「部分服务认识的字段」合法（谓词 #7
  * 并集键集同依据）；禁合成单一 schema——required/title 冲突的有损代数；产物 = 扁平映射，
  * 分组归客户端纯呈现。层级 schema = 表单引导**非写入门禁**（P16——写路径校验权威恒在谓词
  * #7 键集 + ajv 凭据链；root 级口径差：#7 = 引用厂商并集，表单 = 层生效厂商单厂商作用域）。
+ *
+ * v4.6（D36/D37 additive 精化）：**原始投影**（loadApp/loadModuleIntegrationSchemas）原样保留
+ * 为诊断面 / registry 输入；**消费投影** = buildIntegrationFieldRegistry（字段级合并代数
+ * R1/R2/R3 服务端单源，conflict 折叠 schema:null）；**轴向假想绑定** = formProviderOf
+ * （override ?? 实际解析——双投影同源同口径，formViews 装配层一次计算两投影）。
+ * 单源三锚：层级 schema 计算 = resolveLayerIntegrationSchemas / 生效厂商解析 = formProviderOf /
+ * 合并代数 = buildIntegrationFieldRegistry。
  */
 
-/** 核心纯函数：显式作用域（provider null → 整字段 null；services 逐项 serviceSchemas 复合键 +
- *  readSchemaRef——既有解析路径零新读；供给在场未声明 = null，mock 合法） */
+/** 核心纯函数：显式作用域（provider null → 整字段 null；services 逐项 resolveServiceConfigSchema
+ *  复合解析——v4.7 D38 收口，零新读取路径；供给在场未声明 = null，mock 合法） */
+export function resolveLayerIntegrationSchemas(snapshot: ViewSnapshot, provider: string, services: readonly string[]): LayerIntegrationSchemas;
+export function resolveLayerIntegrationSchemas(snapshot: ViewSnapshot, provider: string | null, services: readonly string[]): LayerIntegrationSchemas | null;
 export function resolveLayerIntegrationSchemas(
   snapshot: ViewSnapshot,
   provider: string | null,
@@ -24,30 +35,192 @@ export function resolveLayerIntegrationSchemas(
   if (provider === null) return null;
   const out: LayerIntegrationSchemas['services'] = {};
   for (const s of services) {
-    const entry = snapshot.walk.serviceSchemas[`${provider}\u0000${s}`];
-    out[s] = { configSchema: entry ? readSchemaRef(snapshot.appDir, entry.packageDir, entry.configSchema) : null };
+    out[s] = { configSchema: resolveServiceConfigSchema(snapshot, provider, s) };
   }
   return { provider, services: out };
 }
 
-/** app 级 loader：生效厂商 = root.provider（非空字符串，缺席 → 整字段 null——D32「未绑定」）；
- *  作用域 = 该厂商供给足迹全量（≠ AppView.services——root.config 流向包括模块服务在内的所有服务） */
-export function loadAppIntegrationSchemas(snapshot: ViewSnapshot): LayerIntegrationSchemas | null {
-  const p = (snapshot.integrations as { provider?: unknown } | null)?.provider;
-  const provider = typeof p === 'string' && p.length > 0 ? p : null;
-  if (provider === null) return null;
-  return resolveLayerIntegrationSchemas(snapshot, provider, providerFootprint(snapshot.catalog, provider));
+// ── v4.6 D36/D37：合并代数助手（内联——深相等判定基）──
+
+/** 稳定序列化（键序归一——R2 深相等 / R1 签名比较统一基；数组保序、对象键 sort） */
+function stableSerialize(v: unknown): string {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v ?? null) as string;
+  if (Array.isArray(v)) return `[${v.map(stableSerialize).join(',')}]`;
+  const keys = Object.keys(v as Record<string, unknown>).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableSerialize((v as Record<string, unknown>)[k])}`).join(',')}}`;
 }
 
-/** module 级 loader：仅 writable 单域；生效厂商 = resolveDomainBinding（D32/R4 单源）；
- *  作用域 = demand ∩ 该厂商供给；多域/零域/共享键/未绑定 → 整字段 null（表单降级 = ExtraFields） */
-export function loadModuleIntegrationSchemas(snapshot: ViewSnapshot, moduleId: string): LayerIntegrationSchemas | null {
+/** enum 缺席哨兵（≠ 任何实际集签名——混布必不等） */
+const NO_ENUM = '\u0000no-enum';
+
+/** enum 集签名（去重排序——序不敏感） */
+function enumSig(sub: Record<string, unknown>): string {
+  const e = sub.enum;
+  if (!Array.isArray(e)) return NO_ENUM;
+  return `[${[...new Set(e.map(stableSerialize))].sort().join(',')}]`;
+}
+
+/** 顶层 type 签名（数组形态序敏感——严格全等）；非对象（含布尔子 schema）/ type 缺席 → null（R3） */
+function typeSig(sub: unknown): string | null {
+  if (!sub || typeof sub !== 'object' || Array.isArray(sub)) return null;
+  const t = (sub as Record<string, unknown>).type;
+  return t === undefined ? null : stableSerialize(t);
+}
+
+/** D36 合并代数单点（R1/R2/R3——唯一扩展点；保守降级：不可调和 → null，客户端 RawJson 保真） */
+function mergeFieldSources(sources: ReadonlyArray<{ subschema: unknown }>): object | null {
+  const sigs = sources.map((s) => typeSig(s.subschema));
+  if (sigs.some((s) => s === null) || new Set(sigs).size > 1) return null; // R3：非对象/type 缺席/type 不等
+  if (sigs[0] === '"object"') {
+    // R2：全源稳定序列化深相等 → 首源；异构 → null
+    const first = stableSerialize(sources[0].subschema);
+    return sources.every((s) => stableSerialize(s.subschema) === first) ? (sources[0].subschema as object) : null;
+  }
+  // R1：标量型——enum 集全等（含双无哨兵）→ 首源；不等/混布 → null
+  const es = new Set(sources.map((s) => enumSig(s.subschema as Record<string, unknown>)));
+  return es.size === 1 ? (sources[0].subschema as object) : null;
+}
+
+/** D36 registry 构造（纯函数——消费 resolveLayerIntegrationSchemas 产物，禁旁路直取 serviceSchemas）。
+ *  fields 收集零过滤（布尔/非对象子 schema 入列，判定全权归 mergeFieldSources——S8 互证等式由
+ *  收集定义结构性闭合）；schemaless 仅 configSchema === null（布尔/畸形整 schema 防御跳过——
+ *  不入 schemaless、零参与聚合；D32 运行时畸形，非契约面）。 */
+export function buildIntegrationFieldRegistry(
+  layer: LayerIntegrationSchemas,
+  o?: { unsupplied?: string[] },
+): IntegrationFieldRegistryView {
+  const schemaless: string[] = [];
+  let additionalPropertiesAllowed = true;
+  const buckets = new Map<string, Array<{ service: string; subschema: unknown; required: boolean }>>();
+  for (const [service, entry] of Object.entries(layer.services)) {
+    // 插入序 = scope 遍历序（app 字母序 / module demand 序）——fields 首声明序由此保证
+    const schema = entry.configSchema;
+    if (schema === null) {
+      schemaless.push(service);
+      continue;
+    }
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) continue;
+    const s = schema as Record<string, unknown>;
+    if (s.additionalProperties === false) additionalPropertiesAllowed = false;
+    const props = s.properties;
+    if (!props || typeof props !== 'object' || Array.isArray(props)) continue; // ≡ 谓词 collectPropertyKeys 守卫
+    const required = Array.isArray(s.required) ? s.required : [];
+    for (const key of Object.keys(props)) {
+      const bucket = buckets.get(key) ?? [];
+      bucket.push({ service, subschema: (props as Record<string, unknown>)[key], required: required.includes(key) });
+      buckets.set(key, bucket);
+    }
+  }
+  const fields: IntegrationFieldRegistryView['fields'] = [];
+  for (const [key, sources] of buckets) {
+    fields.push({
+      key,
+      schema: mergeFieldSources(sources),
+      sources: sources.map(({ service, required }) => ({ service, required })),
+    });
+  }
+  return {
+    provider: layer.provider,
+    schemaless,
+    unsupplied: [...(o?.unsupplied ?? [])],
+    additionalPropertiesAllowed,
+    fields,
+  };
+}
+
+/** D37 生效厂商解析单源（实际/假想同径）：override（非空串）?? 实际解析。
+ *  空串归一（I3）单点；module 轴 D34 不可写/不在册 → null（override 不豁免——预览服务于保存）。 */
+export function formProviderOf(
+  axis: 'app' | 'module',
+  snapshot: ViewSnapshot,
+  moduleId?: string,
+  override?: string,
+): string | null {
+  const ovr = typeof override === 'string' && override.length > 0 ? override : undefined;
+  if (axis === 'app') {
+    if (ovr !== undefined) return ovr;
+    const p = (snapshot.integrations as { provider?: unknown } | null)?.provider;
+    return typeof p === 'string' && p.length > 0 ? p : null;
+  }
   const mod = snapshot.walk.modules.find((m) => m.id === moduleId);
   if (!mod) return null; // 视图已先行 404，此处防御
   const w = moduleDomainWritable(snapshot.walk, mod);
-  if (!w.writable) return null;
-  const provider = resolveDomainBinding(snapshot.integrations, w.domainKey).provider;
-  if (provider === null) return null;
+  if (!w.writable) return null; // D34 不豁免
+  if (ovr !== undefined) return ovr;
+  return resolveDomainBinding(snapshot.integrations, w.domainKey).provider;
+}
+
+/** D36/D37 表单层双投影（I1：同源同口径一次计算——双取单算 by construction） */
+export interface LayerFormViews {
+  integrationSchemas: LayerIntegrationSchemas | null;
+  integrationFieldRegistry: IntegrationFieldRegistryView | null;
+}
+
+/** 防御双 null（module 不在册/不可写/未绑定、app 未绑定——F3） */
+const NULL_FORM_VIEWS: LayerFormViews = { integrationSchemas: null, integrationFieldRegistry: null };
+
+/** app 轴装配：scope = 供给足迹全量（≠ AppView.services——root.config 流向包括模块服务在内的所有服务）；
+ *  unsupplied 恒 []（结构性：足迹 ⊆ 供给）。未知厂商/零足迹 → 非 null 空集（镜像 D32 mock 语义）。 */
+export function loadAppFormViews(snapshot: ViewSnapshot, appProvider?: string): LayerFormViews {
+  const provider = formProviderOf('app', snapshot, undefined, appProvider);
+  if (provider === null) return NULL_FORM_VIEWS;
+  const layer = resolveLayerIntegrationSchemas(snapshot, provider, providerFootprint(snapshot.catalog, provider));
+  return { integrationSchemas: layer, integrationFieldRegistry: buildIntegrationFieldRegistry(layer) };
+}
+
+/** module 轴装配：仅 writable 单域（D34）；scope = demand ∩ 该厂商供给；unsupplied 同点派生
+ *  （demand − 供给，Set 去重保序——manifest demand 不去重防御）。 */
+export function loadModuleFormViews(snapshot: ViewSnapshot, moduleId: string, moduleProvider?: string): LayerFormViews {
+  const provider = formProviderOf('module', snapshot, moduleId, moduleProvider);
+  const mod = snapshot.walk.modules.find((m) => m.id === moduleId);
+  if (provider === null || !mod) return NULL_FORM_VIEWS;
   const demand = (mod.descriptor.contributes.services ?? []).map((s) => s.service);
-  return resolveLayerIntegrationSchemas(snapshot, provider, demand.filter((s) => isSupplied(snapshot.catalog, provider, s)));
+  const supplied = (s: string): boolean => isSupplied(snapshot.catalog, provider, s);
+  const layer = resolveLayerIntegrationSchemas(snapshot, provider, demand.filter(supplied));
+  return {
+    integrationSchemas: layer,
+    integrationFieldRegistry: buildIntegrationFieldRegistry(layer, {
+      unsupplied: [...new Set(demand.filter((s) => !supplied(s)))],
+    }),
+  };
+}
+
+/** app 级 loader（v4.6 委托化——签名零改动，公开面保持；假想态归 loadAppFormViews override 参） */
+export function loadAppIntegrationSchemas(snapshot: ViewSnapshot): LayerIntegrationSchemas | null {
+  return loadAppFormViews(snapshot).integrationSchemas;
+}
+
+/** module 级 loader（v4.6 委托化——同上；多域/零域/共享键/未绑定 → 整字段 null，表单降级 = ExtraFields） */
+export function loadModuleIntegrationSchemas(snapshot: ViewSnapshot, moduleId: string): LayerIntegrationSchemas | null {
+  return loadModuleFormViews(snapshot, moduleId).integrationSchemas;
+}
+
+/** 服务级 loader（v4.7 D38）：四分支穷举（node.provider = 文件 services[s].provider 逐字原值；
+ *  实例层无条件排除——node 级口径）；非空三分支归约一次复合解析。
+ *  ① undefined/'' → resolveDomainBinding 域级联（域 + root 双缺 → 整字段 null）
+ *  ② 非空 string → bare：catalog miss（未知厂商/未供给）→ configSchema:null 不 404（富化非门控）
+ *  ③ 受控内联（isControlledInlineProvider 单源）→ 名 = p.provider；catalog 复合键 > p.configSchema ref
+ *     （H9 逃逸 400 照抛——readInlineSchema 共享路径）
+ *  ④ 其余（null/数组/原始值/坏对象）→ 整字段 null（≡ 谓词 #5 INLINE_PROVIDER_INVALID 同判——
+ *     不放行域级联，防错误 schema 污染坏节点） */
+export function loadServiceIntegrationSchemas(
+  snapshot: ViewSnapshot,
+  service: string,
+): ServiceIntegrationSchemas | null {
+  const p = (snapshot.integrations as { services?: Record<string, { provider?: unknown }> } | null)
+    ?.services?.[service]?.provider;
+  if (p === undefined || p === '') {
+    const binding = resolveDomainBinding(snapshot.integrations, domainOfService(service));
+    return binding.provider === null
+      ? null
+      : { provider: binding.provider, configSchema: resolveServiceConfigSchema(snapshot, binding.provider, service) };
+  }
+  if (typeof p === 'string') {
+    return { provider: p, configSchema: resolveServiceConfigSchema(snapshot, p, service) };
+  }
+  if (isControlledInlineProvider(p)) {
+    const decl = p as { provider: string; configSchema?: string };
+    return { provider: decl.provider, configSchema: resolveServiceConfigSchema(snapshot, decl.provider, service, decl.configSchema) };
+  }
+  return null;
 }

package/src/views/modules.ts

@@ -1,7 +1,7 @@
 import type { ModuleDeclaration, ModuleDetailView, ProviderBinding, ServiceDemand } from '../dto.js';
 import { AppToolkitError } from '../core/errors.js';
 import { moduleDomainWritable, resolveDomainBinding } from '../integrations/domain-binding.js';
-import type { ViewSnapshot } from './context.js';
+import { resolveServiceDisplay, type ViewSnapshot } from './context.js';
 
 /**
  * 需求轴/模块静态投影（views/modules；C4）。静态端点结构性零求值（铁律 #3——
@@ -9,18 +9,34 @@ import type { ViewSnapshot } from './context.js';
  * v4.4 D34：domainKeys/providerBindings/configEditable 显式化；integration 仅单域
  * （writable）时在场——多域/零域/共享键无单键落点；多域回退兜底键机器拆除
  * （派生统一 = domainOfService 去重集合，moduleDomainWritable 单源）。
+ * 2026-09-16 双缺陷批：loadModulesView 排除 provider 家族包（供给/实施载体非可配置
+ * 业务模块）——walk 声明集与 loadModuleDetailView 不变（装包仍合法，详情保持 200）。
  */
 
-/** GET /modules：纯模块清单（demand 不在——卡片展开 = GET /modules/:m） */
+/** 家族名归一（cli deriveModuleId 同源语义——依赖方向禁 import，故内联）：
+ *  `@tbox.cn/app-provider-x` / `@app/provider-y` / `provider-z` → `provider-*` */
+function familyName(s: string): string {
+  return s.replace(/^@tbox\.cn\/app-/, '').replace(/^@[^/]+\//, '');
+}
+
+/** provider 家族包判定（模块清单排除供给/实施载体；生态三先例同源：stage 排除判定 /
+ *  guard-vendor-neutrality「provider-* 包」/ cli deriveModuleId 家族推导）。install id 与
+ *  包名 basename 双查 = 防 .tbox/app.json 登记漂移纵深；命名而非结构（provider-custom 零贡献
+ *  空壳与「零贡献合法」形态不可结构区分）；未来收敛 = manifest 显式角色标记（届时整体退场）。 */
+function isProviderFamily(mod: { id: string; pkg: string }): boolean {
+  return familyName(mod.id).startsWith('provider-') || familyName(mod.pkg).startsWith('provider-');
+}
+
+/** GET /modules：纯模块清单（demand 不在——卡片展开 = GET /modules/:m；provider 家族包不在清单） */
 export function loadModulesView(snapshot: ViewSnapshot): { modules: ModuleDeclaration[] } {
   const modules: ModuleDeclaration[] = snapshot.walk.modules
+    .filter((mod) => !isProviderFamily(mod))
     .map((mod) => ({
       id: mod.id,
       name: mod.descriptor.name,
-      // 模块级 title/description：manifest 无模块级 meta 字段（demand meta 属 per-service）——
-      // 一期回退 install id / 空描述（UI 侧按词汇表或 demand meta 增强）
-      title: mod.descriptor.name,
-      description: '',
+      // 模块 meta（B1 additive）：manifest title/description——兜底 name / ''（视图层灌值）
+      title: mod.descriptor.title ?? mod.descriptor.name,
+      description: mod.descriptor.description ?? '',
     }))
     .sort((a, b) => a.id.localeCompare(b.id));
   return { modules };
@@ -32,12 +48,16 @@ export function loadModuleDetailView(snapshot: ViewSnapshot, moduleId: string):
   if (!mod) {
     throw new AppToolkitError('MODULE_NOT_FOUND', 404, `模块 ${moduleId} 非已装模块`);
   }
-  const services: ServiceDemand[] = (mod.descriptor.contributes.services ?? []).map((need) => ({
-    service: need.service,
-    ...(need.title ? { title: need.title } : {}),
-    ...(need.description ? { description: need.description } : {}),
-    required: need.optional === false,
-  }));
+  const services: ServiceDemand[] = (mod.descriptor.contributes.services ?? []).map((need) => {
+    // 展示名单源走链（B1）：词汇 meta > demand meta > id——词汇主源防 manifest demand 漂移
+    const display = resolveServiceDisplay(snapshot.walk, need.service);
+    return {
+      service: need.service,
+      title: display.title,
+      ...(display.description !== undefined ? { description: display.description } : {}),
+      required: need.optional === false,
+    };
+  });
   const w = moduleDomainWritable(snapshot.walk, mod);
   const domains = (snapshot.integrations as { domains?: Record<string, unknown> } | null)?.domains ?? {};
   // integration = domains[换算键] 节点原值（D21 编辑预填源）；未配置 = null；多域/零域/共享键 = null（D34）
@@ -46,5 +66,14 @@ export function loadModuleDetailView(snapshot: ViewSnapshot, moduleId: string):
     const binding = resolveDomainBinding(snapshot.integrations, d);
     return { domain: d, effective: binding.provider, layer: binding.layer };
   });
-  return { domainKeys: [...w.domainKeys], integration, providerBindings, configEditable: w.writable, services };
+  return {
+    // 模块 meta（B1 additive）——兜底与 /modules 同语义
+    title: mod.descriptor.title ?? mod.descriptor.name,
+    description: mod.descriptor.description ?? '',
+    domainKeys: [...w.domainKeys],
+    integration,
+    providerBindings,
+    configEditable: w.writable,
+    services,
+  };
 }

package/src/views/providers.ts

@@ -2,7 +2,7 @@ import type { ProviderDetail, ProviderEntry, ProviderServiceDetail, ProvidersVie
 import { AppToolkitError } from '../core/errors.js';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import type { ViewSnapshot } from './context.js';
+import { resolveServiceDisplay, type ViewSnapshot } from './context.js';
 
 /**
  * 供给轴投影（views/providers；C4）。供给关系三切片（P5）：
@@ -21,6 +21,9 @@ export function loadProvidersView(snapshot: ViewSnapshot): ProvidersView {
       provider,
       local: entries.every((e) => e.local === true),
       owner: entries[0].owner,
+      // 厂商展示元数据（B1 walk 层传播——首条目 = 首声明，与 owner 同语义）
+      ...(entries[0].title ? { title: entries[0].title } : {}),
+      ...(entries[0].description ? { description: entries[0].description } : {}),
     });
   }
   return { providers: providers.sort((a, b) => a.provider.localeCompare(b.provider)) };
@@ -40,12 +43,15 @@ export function loadProviderDetailView(snapshot: ViewSnapshot, provider: string,
       bucket.implementations.push({ implementation: entry.implementation, credentialType: entry.credentialType });
     }
   }
+  // 服务展示名走链（B1）：词汇 meta > demand meta > id（title 恒发）
+  for (const [service, bucket] of Object.entries(services)) {
+    const display = resolveServiceDisplay(snapshot.walk, service);
+    bucket.title = display.title;
+    if (display.description !== undefined) bucket.description = display.description;
+  }
   if (include?.has('integrationSchemas')) {
     for (const [service, bucket] of Object.entries(services)) {
-      const schemaEntry = snapshot.walk.serviceSchemas[`${provider}\u0000${service}`];
-      bucket.integrationSchemas = {
-        configSchema: schemaEntry ? readSchemaRef(snapshot.appDir, schemaEntry.packageDir, schemaEntry.configSchema) : null,
-      };
+      bucket.integrationSchemas = { configSchema: resolveServiceConfigSchema(snapshot, provider, service) };
     }
   }
   const entries = Object.values(impls);
@@ -53,6 +59,9 @@ export function loadProviderDetailView(snapshot: ViewSnapshot, provider: string,
     provider,
     local: entries.every((e) => e.local === true),
     owner: entries[0].owner,
+    // 厂商展示元数据（B1 walk 层传播——首条目透传）
+    ...(entries[0].title ? { title: entries[0].title } : {}),
+    ...(entries[0].description ? { description: entries[0].description } : {}),
     services,
   };
 }
@@ -95,22 +104,15 @@ export function loadProviderServiceDetailView(
     implementations.push({ implementation: configured[service]?.implementation ?? `${provider}-inline@1`, credentialType: inlineDeclaration.credentialType });
   }
 
-  // integrationSchemas：catalog schema（复合键）优先；内联声明 configSchema 引用应用 config/schemas/
-  // （路径约束 H9——resolve 落 config/schemas/ 内 + realpath 复核，违例 400）
-  // v4.4 F5 消重：schema 表取自 snapshot.walk（原 walkManifests(appDir) 重复全量目录扫描）；
-  // v4.4 D33：credentialSchema 删净（结构归 GET /credential-types——组合单体纯 config）
-  let configSchema: object | null = null;
-  const schemaEntry = snapshot.walk.serviceSchemas[`${provider}\u0000${service}`];
-  if (schemaEntry) {
-    configSchema = readSchemaRef(snapshot.appDir, schemaEntry.packageDir, schemaEntry.configSchema);
-  } else if (inlineDeclaration) {
-    // 内联声明 schema 解析：引用文件在 integrations 节点（provider.configSchema）——
-    // 形状同 config/schemas/ 约束（路径来源 = 节点声明，由服务端读应用侧）
-    const inlineSchemaRef = (inline as { configSchema?: string } | undefined)?.configSchema;
-    if (typeof inlineSchemaRef === 'string') {
-      configSchema = readInlineSchema(snapshot.appDir, inlineSchemaRef);
-    }
-  }
+  // integrationSchemas：schema 解析收口 resolveServiceConfigSchema 单源（v4.7 D38——catalog 复合键 >
+  // 内联 ref，等价重构 O6/O7/O15 零改动即证）；内联 ref 来源 = 节点声明（provider.configSchema，
+  // 仅受控内联声明匹配本厂商名时）；路径约束 H9——resolve 落 config/schemas/ 内 + realpath 复核，违例 400
+  const configSchema = resolveServiceConfigSchema(
+    snapshot,
+    provider,
+    service,
+    inlineDeclaration ? (inline as { configSchema?: string } | undefined)?.configSchema : undefined,
+  );
 
   return {
     provider,
@@ -120,6 +122,22 @@ export function loadProviderServiceDetailView(
   };
 }
 
+/** per-(provider, service) schema 复合解析单源（v4.7 D38）：catalog 复合键（多 impl 声明序首个）
+ *  > 内联 ref（readInlineSchema 保持私有——H9 双钉子不扩暴露）；miss / 未声明 / 文件缺失 → null。
+ *  views 层 \u0000 复合键唯一消费点（组合单体 / 供给轴批量 / 层级核心 / 服务级 include 同源）。
+ *  （D36 registry 批若需跨包消费再升 index 导出——additive 零成本） */
+export function resolveServiceConfigSchema(
+  snapshot: ViewSnapshot,
+  provider: string,
+  service: string,
+  inlineRef?: string,
+): object | null {
+  const entry = snapshot.walk.serviceSchemas[`${provider}\u0000${service}`];
+  if (entry) return readSchemaRef(snapshot.appDir, entry.packageDir, entry.configSchema);
+  if (typeof inlineRef === 'string') return readInlineSchema(snapshot.appDir, inlineRef);
+  return null;
+}
+
 /** catalog schema 引用读取（相对包根；缺席 → null——SCHEMA_FILE_MISSING 归谓词 #6）。
  *  v4.4 导出共享：层级内嵌（integration-schemas.ts）/ 凭据结构清单（credential-types.ts）同源消费。 */
 export function readSchemaRef(_appDir: string, packageDir: string, ref: string | undefined): object | null {

package/src/views/service-detail.ts

@@ -1,7 +1,7 @@
 import type { ServiceDetail } from '../dto.js';
 import { AppToolkitError } from '../core/errors.js';
 import { isKnownService } from '../integrations/read.js';
-import { suppliedByVendors, type ViewSnapshot } from './context.js';
+import { resolveServiceDisplay, suppliedByVendors, type ViewSnapshot } from './context.js';
 
 /**
  * 服务静态单体投影（views/service-detail；C4）。求值数据不在此（→ /service-resolutions/:service）。
@@ -17,10 +17,12 @@ export function loadServiceDetailView(snapshot: ViewSnapshot, service: string):
   }
   // integration = 文件 services[s] 逐字原值（编辑预填源 D21）；无声明 = null
   const integration = (configured[service] as ServiceDetail['integration'] | undefined) ?? null;
+  // 展示名单源走链（B1）：词汇 meta > demand meta > id——替换 demand 直拼（恒有值）
+  const display = resolveServiceDisplay(snapshot.walk, service);
   return {
     service,
-    ...(demand?.title ? { title: demand.title } : { title: service }),
-    ...(demand?.description ? { description: demand.description } : {}),
+    title: display.title,
+    ...(display.description !== undefined ? { description: display.description } : {}),
     required: demand ? !demand.optional : false,
     // defaults 唯一落位（manifest 预填）
     defaults: demand ? demand.defaults.map((d) => ({ ...d })) : [],