@tbox.cn/app-toolkit 0.5.0 → 0.6.0

package/src/dto.ts

@@ -38,6 +38,9 @@ export interface ModuleDeclaration {
   /** 展示名（v7 词汇统一：manifest name ?? id——恒有值） */
   name: string;
   description: string;
+  /** 隐藏模块（additive——manifest hidden === true 时携带；默认清单已过滤，本字段仅供
+   *  ?includeHidden=true 可见时徽标呈现） */
+  hidden?: boolean;
 }
 
 /** 服务需求声明（模块 demand 单元 / 平台服务条目——v4.4 D29 双端点同型；defaults 唯一落位 ServiceDetail） */
@@ -58,11 +61,17 @@ export interface ModuleDetailView {
   name: string;
   /** B1 additive：模块 meta 描述（manifest description；兜底 ''） */
   description: string;
+  /** 隐藏模块（additive——manifest hidden === true 时携带；详情恒 200 不受清单过滤影响，
+   *  本字段仅供面板徽标呈现） */
+  hidden?: boolean;
   /** v6 所有权模型：模块归属服务（declare.owns 展平，排序；零归属 = []）——
    *  v5 domainKeys 退役（破坏性更名；面板 presence-detection 双读义务见 api.md §3） */
   ownedServices: string[];
-  /** modules[install id] 集成位原值（provider/config；resources 不投影）；未配置 = null */
+  /** modules[install id] 集成位原值（provider/config；resources 不投影——见 resources 字段）；未配置 = null */
   integration: ModuleIntegrationNode | null;
+  /** 模块资源只读镜像（N2 读半边——写侧 resources 恒保全；含 ref 台账展开态 resolvedDatasetId）；
+   *  无模块键/无资源节 = null */
+  resources?: ModuleResourcesEcho | null;
   /** v6 单数化（v5 providerBindings[] 退役）：模块级厂商绑定解析（resolveModuleBinding 单源；
    *  单值作用于全部 ownedServices） */
   binding: ModuleBinding | null;
@@ -147,14 +156,17 @@ export interface ServiceDetail extends ServiceDemand {
    *  绑定无可计算 schema / 含 schema；malformed 节点 → null——不放行域级联） */
   integrationSchemas?: ServiceIntegrationSchemas | null;
   /** G 批：include=integrationFieldRegistry 服务轴注册表（loadServiceFieldRegistry——
-   *  四分支链推导复用 D38；fields = 该 schema 全部字段带 global 旗标；null 语义镜像 D38） */
+   *  四分支链推导复用 D38；fields = 该 schema 全部字段带 global 旗标；null 语义镜像 D38。
+   *  v5.1 D39：serviceProvider 轴参 = 假想重定向——仅表单投影按 X 计算，带非空轴参时
+   *  registry 恒非 null（豁免链③不镜像实际态 null）；同构 ≡ PUT 改写 provider 后实读） */
   integrationFieldRegistry?: IntegrationFieldRegistryView | null;
 }
 
 /** 服务级生效绑定 schema（v4.7 D38 静态轴富化——零 contracts，永不 503；实例层无条件排除：
  *  node 级口径 ≠ resolution 默认实例口径，api.md §4.4 注） */
 export interface ServiceIntegrationSchemas {
-  /** 生效厂商：显式（含内联声明名）?? modules[ownerOf].provider ?? root.provider */
+  /** 生效厂商：显式（含内联声明名）?? modules[ownerOf].provider ?? root.provider；
+   *  v5.1 D39：serviceProvider 轴参在场时 = 假想短路值（非链解析产物） */
   provider: string;
   /** catalog 复合键（多 impl 声明序首个）> 内联 ref；miss（未知厂商/未供给/内联缺 ref）→ null（富化非门控） */
   configSchema: object | null;
@@ -244,6 +256,26 @@ export interface ModuleIntegrationNode {
  *  （键集外 400；resources 恒随既有节点保全）+ views/modules 投影（GET ≡ PUT，三同构）） */
 export const MODULE_INTEGRATION_NODE_KEYS = ['provider', 'config'] as const;
 
+/** 模块资源回显（只读投影——N2 读半边：写侧仍仅 provider/config，resources 恒保全）。
+ *  原值文件镜像（L1）+ ref 台账展开态：`ref` 在场且同目录 knowledge.json 命中时
+ *  `resolvedDatasetId` = 台账 datasetId（镜像 SDK resolveKnowledge 展开语义），未命中/台账缺失 = null。
+ *  路径锚定边界：视图恒读 `<appDir>/config/`（与 toolkit readIntegrationsConfig 同源——
+ *  `TBOX_INTEGRATIONS_FILE` 为 SDK 运行时逃生舱，视图不跟随，既有分叉）。 */
+export interface ModuleResourceEcho {
+  type: 'knowledge';
+  /** 文件原值直填 datasetId（与 ref 互斥使用——并存时 SDK 侧 datasetId 优先） */
+  datasetId?: string;
+  /** 文件原值 ref（台账引用——knowledge.json knowledge_bases 键） */
+  ref?: string;
+  /** 展开态：datasetId 直填时 = 该值；ref 命中台账 = 台账 datasetId；ref 未命中/台账缺失 = null */
+  resolvedDatasetId: string | null;
+  topK?: number;
+  scoreThreshold?: number;
+}
+
+/** modules[install id].resources 只读镜像（键 = 资源 id；无模块键/无资源 = null） */
+export type ModuleResourcesEcho = Record<string, ModuleResourceEcho>;
+
 /** services[s] 整节点 */
 export interface ServiceIntegrationNode {
   /** 对象 = 自定义 API（仅槽级，P2） */

package/src/factory.ts

@@ -45,7 +45,8 @@ import type {
  * createAppToolkit（C4 工厂；v4.4——24 方法 = 11 读（含 credentials/credential-types 双端点）
  * + 4 写 + 9 迁移面；loadApp/loadModule/loadProvider 增 include 选项；v4.6——loadApp/loadModule
  * += 轴向假想绑定选项（appProvider/moduleProvider，D37）；表单双投影经 formViews 单点装配；
- * v4.7——loadService 增 include 选项（服务级生效绑定 schema 单体））。
+ * v4.7——loadService 增 include 选项（服务级生效绑定 schema 单体）；v5.1 D39——loadService
+ * += serviceProvider 轴参（服务轴向假想绑定，三轴收口））。
  * AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals——
  * Read+Write = HTTP 直通面 additive 冻结（L1 端点↔方法 1:1，L3 命名镜像：Integration=节点级 /
  * Config=文件级）；Internals = CLI/doctor/桥消费（自由演进）。
@@ -98,9 +99,10 @@ function validateInclude(kind: keyof typeof INCLUDE_WHITELIST, include?: string[
 const FORM_INCLUDE_KEYS = ['integrationSchemas', 'integrationFieldRegistry'] as const;
 
 /** v4.6 D37 轴参严检（400 先于 404——镜像输入校验先行）：非空轴参需与表单 include 键同现；
- *  缺席/空串 ≡ 按实际配置解析（I3——不触发严检）；错轴参数由壳层按名读取，天然静默忽略。 */
+ *  缺席/空串 ≡ 按实际配置解析（I3——不触发严检）；错轴参数由壳层按名读取，天然静默忽略。
+ *  v5.1 D39：联合类型 += serviceProvider（service 轴同律）。 */
 function assertAxisProviderUsable(
-  paramName: 'appProvider' | 'moduleProvider',
+  paramName: 'appProvider' | 'moduleProvider' | 'serviceProvider',
   value: string | undefined,
   include: ReadonlySet<string>,
 ): void {
@@ -119,13 +121,16 @@ function assertAxisProviderUsable(
  *  **双键契约（v7 词汇统一）**：资源路径参数双键寻址（id 优先、唯一展示名兜底——resolve-key
  *  单点；多命中 404 带候选）；query 过滤参数（loadServiceResolutions services?）恒 id-only。 */
 export interface AppToolkitRead {
-  loadModules(): Promise<ModulesView>;
+  /** GET /modules：hidden 模块默认过滤（includeHidden = true 可见——对齐 ?dryRun 布尔参数先例） */
+  loadModules(o?: { includeHidden?: boolean }): Promise<ModulesView>;
   /** v4.6 D37：moduleProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现）。
    *  moduleId = 双键（id 优先、唯一展示名兜底）。 */
   loadModule(moduleId: string, o?: { include?: string[]; moduleProvider?: string }): Promise<ModuleDetailView>;
   /** v4.6 D37：appProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现） */
   loadApp(o?: { include?: string[]; appProvider?: string }): Promise<AppView>;
-  loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail>;
+  /** v5.1 D39：serviceProvider = 服务轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include
+   *  键同现）——假想重定向仅表单双投影，integration/suppliedBy/defaults 恒实际态（I2） */
+  loadService(service: string, o?: { include?: string[]; serviceProvider?: string }): Promise<ServiceDetail>;
   loadServiceResolutions(services?: string[]): Promise<ServiceResolutionsView>;
   loadServiceResolution(service: string): Promise<ServiceResolutionDetail>;
   loadProviders(): Promise<ProvidersView>;
@@ -242,9 +247,9 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
   }
 
   const read = {
-    async loadModules() {
+    async loadModules(o?: { includeHidden?: boolean }) {
       const contracts = await resolveContractsForApp(appDir);
-      return loadModulesView(snapshot(contracts));
+      return loadModulesView(snapshot(contracts), o);
     },
     // v4.4 D31：门控与内嵌分离——静态方法零门控分支；include=serviceResolutions 按
     // evaluation && strictValidation 双条件装配（<0.9/形态异常 → null，永不 503——技术方案 §2.4：
@@ -291,18 +296,21 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
     },
     // v4.7 D38：include 镜像 loadModule 三段式——① 输入校验 400 先于 404 ② 视图 ③ 静态富化（永不 503）
     // G 批：service 轴 += integrationFieldRegistry（loadServiceFieldRegistry——D38 四分支链复用）
-    async loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail> {
+    // v5.1 D39：loadService += serviceProvider 轴参（三段式序对齐 loadModule——①' 严检先于 resolveContracts，
+    //   即先于 404 也先于 503；I1 双投影同源一次计算经单源链透传）
+    async loadService(service: string, o?: { include?: string[]; serviceProvider?: string }): Promise<ServiceDetail> {
       const include = validateInclude('service', o?.include);
+      assertAxisProviderUsable('serviceProvider', o?.serviceProvider, include); // ①' D39 轴参严检（先于 404）
       const contracts = await resolveContractsForApp(appDir);
       const snap = snapshot(contracts); // 单快照——detail 与 include 装配共享
       // 双键寻址（v7）：id 优先、唯一展示名兜底 → 真实 service id（404 面）
       const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
       const view = loadServiceDetailView(snap, serviceId);
       if (include.has('integrationSchemas')) {
-        view.integrationSchemas = loadServiceIntegrationSchemas(snap, serviceId);
+        view.integrationSchemas = loadServiceIntegrationSchemas(snap, serviceId, o?.serviceProvider);
       }
       if (include.has('integrationFieldRegistry')) {
-        view.integrationFieldRegistry = loadServiceFieldRegistry(snap, serviceId);
+        view.integrationFieldRegistry = loadServiceFieldRegistry(snap, serviceId, o?.serviceProvider);
       }
       return view;
     },

package/src/index.ts

@@ -129,6 +129,8 @@ export type {
   ServiceResolutionDetail,
   AppIntegrationNode,
   ModuleIntegrationNode,
+  ModuleResourceEcho,
+  ModuleResourcesEcho,
   ServiceIntegrationNode,
   ServiceInstanceNode,
   InlineVendorDeclaration,

package/src/integrations/write.ts

@@ -261,6 +261,10 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       cache?.invalidate([join(appDir, INTEGRATIONS_FILE)]);
     }
     const written = integrationsWritten || credentialsWritten;
+    // 孤儿凭据写后对账（api.md §4.13 承诺追平——「覆盖 DELETE 与 PUT 替换两类来源」；三 PUT 写路径
+    // finalize 单点收口，未来第四写方法自动继承）。dryRun（written 蕴含 !dryRun）与 no-diff
+    // （finalize 前短路 return）天然跳过；applyModule modules 节无凭据键——对账恒零新增，无害捎带。
+    if (written) issues.push(...reconcileOrphanCredentials(appDir));
     const restartScheduled = written && onApplied !== undefined;
     if (restartScheduled) onApplied?.();
     const files: string[] = [];

package/src/views/context.ts

@@ -19,6 +19,8 @@ export interface ViewSnapshot {
   catalog: WalkCatalog;
   integrations: Record<string, unknown> | null;
   contracts: ResolvedContracts;
+  /** 文件读原语透传（可选——resources 台账惰性读等 stat 指纹缓存消费；缺席 = 调用方直读） */
+  cache?: FileCache;
 }
 
 /** 读取视图输入快照（每方法调用独立——Freshness Contract 单位 = 方法调用） */
@@ -27,14 +29,14 @@ export async function loadViewSnapshot(ctx: ViewContext): Promise<ViewSnapshot>
   const integrations = await readIntegrationsConfig(ctx.appDir, ctx.cache);
   const { resolveContractsForApp } = await import('../core/contracts-resolver.js');
   const contracts = await resolveContractsForApp(ctx.appDir);
-  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts };
+  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts, ...(ctx.cache ? { cache: ctx.cache } : {}) };
 }
 
 /** 同步快照（调用方已持有 contracts 时——避免重复解析） */
 export function loadViewSnapshotSync(ctx: ViewContext, contracts: ResolvedContracts): ViewSnapshot {
   const walk = walkManifests(ctx.appDir, ctx.cache);
   const integrations = readIntegrationsConfig(ctx.appDir, ctx.cache);
-  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts };
+  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts, ...(ctx.cache ? { cache: ctx.cache } : {}) };
 }
 
 /** 模块占用服务集（v6——demand ∪ supply ∪ owns：归属模型下「平台服务」= 无主服务；

package/src/views/integration-schemas.ts

@@ -229,11 +229,22 @@ function serviceLevelBindingProvider(snapshot: ViewSnapshot, service: string): s
  *  ③ 受控内联（isControlledInlineProvider 单源）→ 名 = p.provider；catalog 复合键 > p.configSchema ref
  *     （H9 逃逸 400 照抛——readInlineSchema 共享路径）
  *  ④ 其余（null/数组/原始值/坏对象）→ 整字段 null（≡ 谓词 #5 INLINE_PROVIDER_INVALID 同判——
- *     不放行域级联，防错误 schema 污染坏节点） */
+ *     不放行域级联，防错误 schema 污染坏节点）
+ *  v5.1 D39：serviceProvider = 服务轴向假想绑定（缺席/空串 ≡ 按实际解析——I3 归一单点在此头部，
+ *  registry 侧不重复归一）；非空轴参 → 短路 bare 解析（镜像 formProviderOf「输入替换非分支复制」先例：
+ *  任一原分支改写 provider 为 X 后实读都进 bare 分支，同构承诺 by construction）。短路在节点读取之前——
+ *  豁免链三分支（D39 与 D38 四分支的有意分歧：预览与坏文件解耦）：malformed（分支④）不污染假想 /
+ *  内联 ref 不读取（假想态无 H9 逃逸 400；catalog 命中的 manifest 声明路径照读，与节点声明的
+ *  用户可控路径不同性）/ 全链未绑定时假想仍非 null（服务轴恒可写，无 module 轴零归属对应物）。 */
 export function loadServiceIntegrationSchemas(
   snapshot: ViewSnapshot,
   service: string,
+  serviceProvider?: string,
 ): ServiceIntegrationSchemas | null {
+  const ovr = typeof serviceProvider === 'string' && serviceProvider.length > 0 ? serviceProvider : undefined;
+  if (ovr !== undefined) {
+    return { provider: ovr, configSchema: resolveServiceConfigSchema(snapshot, ovr, service) };
+  }
   const p = (snapshot.integrations as { services?: Record<string, { provider?: unknown }> } | null)
     ?.services?.[service]?.provider;
   if (p === undefined || p === '') {
@@ -255,12 +266,15 @@ export function loadServiceIntegrationSchemas(
 /** G 批：服务轴字段注册表（D38 四分支链复用——消费 loadServiceIntegrationSchemas 单源；
  *  伪层 {provider, services: {[s]: {configSchema}}} → buildIntegrationFieldRegistry——
  *  fields = 该 schema 全部字段带 global 旗标；configSchema null → schemaless=[service]
- *  非 null 空集；schemas 整体 null（全链未绑定/坏节点）→ registry null——镜像 D38 语义） */
+ *  非 null 空集；schemas 整体 null（全链未绑定/坏节点）→ registry null——镜像 D38 语义）。
+ *  v5.1 D39：serviceProvider = 服务轴向假想绑定，纯透传（I1 单源——归一与短路都在链函数头部；
+ *  轴参仅重定向表单层投影，global 旗标全量透传语义不变）。 */
 export function loadServiceFieldRegistry(
   snapshot: ViewSnapshot,
   service: string,
+  serviceProvider?: string,
 ): IntegrationFieldRegistryView | null {
-  const schemas = loadServiceIntegrationSchemas(snapshot, service);
+  const schemas = loadServiceIntegrationSchemas(snapshot, service, serviceProvider);
   if (schemas === null) return null;
   const layer: LayerIntegrationSchemas = {
     provider: schemas.provider,

package/src/views/modules.ts

@@ -1,4 +1,6 @@
-import type { ModuleDeclaration, ModuleBinding, ModuleDetailView, ServiceDemand } from '../dto.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ModuleDeclaration, ModuleBinding, ModuleDetailView, ModuleResourceEcho, ModuleResourcesEcho, ServiceDemand } from '../dto.js';
 import { AppToolkitError } from '../core/errors.js';
 import { moduleOwnershipWritable, resolveModuleBinding } from '../integrations/module-binding.js';
 import { resolveServiceDisplay, type ViewSnapshot } from './context.js';
@@ -8,11 +10,62 @@ import { resolveServiceDisplay, type ViewSnapshot } from './context.js';
  * 无 resolution/issues/contracts 键，永不 503）。
  * v6 所有权模型：ownedServices（declare.owns 展平）/ binding 单数（resolveModuleBinding）/
  * configEditable = owns>0（moduleOwnershipWritable 单源）；integration = modules[install id]
- * 集成位投影（provider/config；resources 不投影——N2）。v5 domainKeys/providerBindings 退役。
+ * 集成位投影（provider/config；resources 走独立只读字段，见投影 resourcesOf——N2 读半边）。
+ * v5 domainKeys/providerBindings 退役。
  * 2026-09-16 双缺陷批：loadModulesView 排除 provider 家族包（供给/实施载体非可配置
  * 业务模块）——walk 声明集与 loadModuleDetailView 不变（装包仍合法，详情保持 200）。
  */
 
+/** knowledge.json 台账路径（与 toolkit readIntegrationsConfig 同源锚定 appDir/config/——
+ *  TBOX_INTEGRATIONS_FILE 为 SDK 运行时逃生舱，视图不跟随，既有分叉见 dto ModuleResourceEcho 注） */
+const KNOWLEDGE_REGISTRY_FILE = join('config', 'knowledge.json');
+
+/**
+ * modules[install id].resources 只读投影（N2 读半边；文件镜像 L1 + ref 台账展开态）：
+ * - 无模块键/无资源节 → null（DTO null 语义：无资源 ≠ 空表）；
+ * - `datasetId` 直填 → resolvedDatasetId = 该值（镜像 SDK resolveKnowledge：并存时 datasetId 优先）；
+ * - `ref` → 同目录 knowledge.json 台账命中 = 台账 datasetId；未命中/台账缺失/解析失败 = null
+ *   （镜像 SDK resolveKnowledge miss-warn 降级语义，资源缺席走模块占位回退）；
+ * - 非 knowledge 型资源（未来 additive）原样透传 type，resolvedDatasetId = null。
+ */
+function resourcesOf(snapshot: ViewSnapshot, moduleId: string, modulesNode: Record<string, unknown>): ModuleResourcesEcho | null {
+  const raw = modulesNode[moduleId] as { resources?: Record<string, unknown> } | undefined;
+  const resources = raw?.resources;
+  if (!resources || typeof resources !== 'object' || Array.isArray(resources)) return null;
+  const registryPath = join(snapshot.appDir, KNOWLEDGE_REGISTRY_FILE);
+  // 台账惰性读（stat 指纹缓存；缺席/坏文件 = 空表——展开态 null，与 SDK loadKnowledgeRegistry fail-soft 同语义）
+  let bases: Record<string, { datasetId?: unknown }> = {};
+  if (existsSync(registryPath)) {
+    try {
+      const parsed = (snapshot.cache?.read(registryPath, (raw: string) => JSON.parse(raw) as unknown) ?? JSON.parse(readFileSync(registryPath, 'utf8'))) as {
+        knowledge_bases?: Record<string, { datasetId?: unknown }>;
+      };
+      bases = parsed.knowledge_bases ?? {};
+    } catch {
+      bases = {};
+    }
+  }
+  const out: ModuleResourcesEcho = {};
+  for (const [id, spec] of Object.entries(resources)) {
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) continue;
+    const s = spec as Record<string, unknown>;
+    const type = s.type === 'knowledge' ? 'knowledge' : String(s.type ?? 'knowledge');
+    const direct = typeof s.datasetId === 'string' && s.datasetId !== '' ? s.datasetId : undefined;
+    const ref = typeof s.ref === 'string' && s.ref !== '' ? s.ref : undefined;
+    const resolved = direct ?? (ref !== undefined && typeof bases[ref]?.datasetId === 'string' ? (bases[ref].datasetId as string) : null);
+    const echo: ModuleResourceEcho = {
+      type: type as ModuleResourceEcho['type'],
+      ...(direct !== undefined ? { datasetId: direct } : {}),
+      ...(ref !== undefined ? { ref } : {}),
+      resolvedDatasetId: resolved,
+      ...(typeof s.topK === 'number' ? { topK: s.topK } : {}),
+      ...(typeof s.scoreThreshold === 'number' ? { scoreThreshold: s.scoreThreshold } : {}),
+    };
+    out[id] = echo;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
 /** 家族名归一（cli deriveModuleId 同源语义——依赖方向禁 import，故内联）：
  *  `@tbox.cn/app-provider-x` / `@app/provider-y` / `provider-z` → `provider-*` */
 function familyName(s: string): string {
@@ -27,15 +80,21 @@ 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[] } {
+/** GET /modules：纯模块清单（demand 不在——卡片展开 = GET /modules/:m；provider 家族包不在清单；
+ *  hidden 模块默认过滤——includeHidden = true 可见并携带 hidden: true 徽标） */
+export function loadModulesView(
+  snapshot: ViewSnapshot,
+  opts: { includeHidden?: boolean } = {},
+): { modules: ModuleDeclaration[] } {
   const modules: ModuleDeclaration[] = snapshot.walk.modules
     .filter((mod) => !isProviderFamily(mod))
+    .filter((mod) => opts.includeHidden === true || mod.descriptor.hidden !== true)
     .map((mod) => ({
       id: mod.id,
       // v7 词汇统一：name = 展示名（manifest name；兜底 id——恒有值）
       name: mod.descriptor.name ?? mod.descriptor.id,
       description: mod.descriptor.description ?? '',
+      ...(mod.descriptor.hidden === true ? { hidden: true } : {}),
     }))
     .sort((a, b) => a.id.localeCompare(b.id));
   return { modules };
@@ -75,9 +134,12 @@ export function loadModuleDetailView(snapshot: ViewSnapshot, moduleId: string):
     // v7 词汇统一：name = 展示名（兜底与 /modules 同语义——manifest name ?? id）
     name: mod.descriptor.name ?? mod.descriptor.id,
     description: mod.descriptor.description ?? '',
+    ...(mod.descriptor.hidden === true ? { hidden: true } : {}),
     // v6：ownedServices（declare.owns 展平排序）——N13：展示名走 resolveServiceDisplay 链，不重复携带
     ownedServices: w.ownedServices,
     integration,
+    // 模块资源只读镜像（N2 读半边——knowledge.json 台账 ref 展开态随行）
+    resources: resourcesOf(snapshot, moduleId, modulesNode),
     binding: { provider: binding.provider, layer: binding.layer },
     configEditable: w.writable,
     services,

package/tests/module-resources.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { createAppToolkit, type AppToolkit } from '../src/factory.js';
+import { invalidateContractsResolver } from '../src/core/contracts-resolver.js';
+import { MODULE_INTEGRATION_NODE_KEYS } from '../src/dto.js';
+import type { ModuleDetailView } from '../src/dto.js';
+import { createTempApp, writeFakeContractsPackage, linkContracts, writeAppFile, type TempApp } from './demo-app.js';
+
+/**
+ * 模块资源只读投影矩阵（N2 读半边）：GET /modules/:m `resources` 四态（直填 datasetId /
+ * ref 命中台账 / ref 未命中（台账缺失·坏文件·键 miss 同归 null）/ 无 modules 节 = null）
+ * + 写侧保全不变量（MODULE_INTEGRATION_NODE_KEYS 白名单不变——resources 不进写位）。
+ * 展开语义镜像 SDK resolveKnowledge：datasetId 直填优先、ref 台账命中/miss-warn 降级。
+ */
+
+interface Harness {
+  app: TempApp;
+  tk: AppToolkit;
+}
+
+/** 自足基座：module-cs（declare.resources 声明对齐真实客服 manifest）+ integrations + 可选台账 */
+function resourcesHarness(integrations: object, knowledge: object | null): Harness {
+  const app = createTempApp('tbox-res-');
+  invalidateContractsResolver();
+  const store = join(app.appDir, 'contracts');
+  writeFakeContractsPackage(store, { version: '0.9.0' });
+  linkContracts(app.appDir, store, { subdir: 'apps/server' });
+  mkdirSync(join(app.appDir, 'packages', 'module-cs'), { recursive: true });
+  writeAppFile(
+    app.appDir,
+    'packages/module-cs/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      id: 'module-cs',
+      version: '0.1.0',
+      kind: 'business',
+      declare: {
+        owns: [],
+        consumes: [],
+        resources: [
+          { id: 'customer-service-faq-kb', type: 'knowledge' },
+          { id: 'knowledge-assistance-kb', type: 'knowledge' },
+        ],
+      },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  writeAppFile(app.appDir, 'config/integrations.json', JSON.stringify(integrations));
+  if (knowledge !== null) {
+    writeAppFile(app.appDir, 'config/knowledge.json', JSON.stringify(knowledge));
+  }
+  const tk = createAppToolkit(app.appDir);
+  return { app, tk };
+}
+
+const FAQ_DIRECT = {
+  provider: 'mock',
+  modules: {
+    'module-cs': {
+      resources: { 'customer-service-faq-kb': { type: 'knowledge', datasetId: '20260101direct00000000000001', topK: 5, scoreThreshold: 0.5 } },
+    },
+  },
+};
+
+const FAQ_REF = {
+  provider: 'mock',
+  modules: {
+    'module-cs': {
+      resources: { 'customer-service-faq-kb': { type: 'knowledge', ref: 'customer-service-faq-generic' } },
+    },
+  },
+};
+
+const KB_REGISTRY = {
+  version: '1.0',
+  knowledge_bases: {
+    'customer-service-faq-generic': { datasetId: '20260921999def645305kQj02050918', retrieve_config: { topK: 5, scoreThreshold: 0.5 } },
+  },
+};
+
+async function detailOf(h: Harness): Promise<ModuleDetailView> {
+  return h.tk.loadModule('module-cs');
+}
+
+describe('module resources 只读投影（N2 读半边）', () => {
+  it('T1 直填 datasetId：resolvedDatasetId = 原值（无台账读取依赖）', async () => {
+    const h = resourcesHarness(FAQ_DIRECT, null); // 台账缺失——直填态不受影响
+    const v = await detailOf(h);
+    expect(v.resources).not.toBeNull();
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      datasetId: '20260101direct00000000000001',
+      resolvedDatasetId: '20260101direct00000000000001',
+      topK: 5,
+      scoreThreshold: 0.5,
+    });
+    h.app.dispose();
+  });
+
+  it('T2 ref 命中台账：resolvedDatasetId = 台账 datasetId；文件原值 ref 保留', async () => {
+    const h = resourcesHarness(FAQ_REF, KB_REGISTRY);
+    const v = await detailOf(h);
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      ref: 'customer-service-faq-generic',
+      resolvedDatasetId: '20260921999def645305kQj02050918',
+    });
+    h.app.dispose();
+  });
+
+  it('T3 ref 未命中键：resolvedDatasetId = null（原值 ref 保留）', async () => {
+    const h = resourcesHarness(FAQ_REF, { knowledge_bases: { 'other-kb': { datasetId: 'x' } } });
+    const v = await detailOf(h);
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      ref: 'customer-service-faq-generic',
+      resolvedDatasetId: null,
+    });
+    h.app.dispose();
+  });
+
+  it('T3b 台账文件缺失 / 坏 JSON：同归 resolvedDatasetId = null（fail-soft 镜像 SDK）', async () => {
+    const missing = resourcesHarness(FAQ_REF, null);
+    expect((await detailOf(missing)).resources!['customer-service-faq-kb']?.resolvedDatasetId).toBeNull();
+    missing.app.dispose();
+
+    const broken = resourcesHarness(FAQ_REF, KB_REGISTRY);
+    writeAppFile(broken.app.appDir, 'config/knowledge.json', '{not-json');
+    expect((await detailOf(broken)).resources!['customer-service-faq-kb']?.resolvedDatasetId).toBeNull();
+    broken.app.dispose();
+  });
+
+  it('T4 无 modules 节 / 模块键无 resources：resources = null（null 语义：无资源 ≠ 空表）', async () => {
+    const noModules = resourcesHarness({ provider: 'mock' }, null);
+    expect((await detailOf(noModules)).resources).toBeNull();
+    noModules.app.dispose();
+
+    const noResourcesKey = resourcesHarness({ provider: 'mock', modules: { 'module-cs': { config: { k: 1 } } } }, KB_REGISTRY);
+    expect((await detailOf(noResourcesKey)).resources).toBeNull();
+    noResourcesKey.app.dispose();
+  });
+
+  it('T5 写侧保全不变量：MODULE_INTEGRATION_NODE_KEYS 白名单恒不含 resources（N2 写半边不变）', () => {
+    expect(MODULE_INTEGRATION_NODE_KEYS).toEqual(['provider', 'config']);
+  });
+});

package/tests/module-schema.test.ts

@@ -128,6 +128,20 @@ describe('module-schema（descriptor zod 单源）', () => {
     }
   });
 
+  it('hidden 展示元数据：boolean 可选（true/false 通过、缺席合法、非 boolean 拒——清单过滤语义归视图层）', () => {
+    const hidden = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: true });
+    expect(hidden.ok).toBe(true);
+    if (hidden.ok) expect(hidden.value.hidden).toBe(true);
+    const unhidden = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: false });
+    expect(unhidden.ok).toBe(true);
+    if (unhidden.ok) expect(unhidden.value.hidden).toBe(false);
+    const absent = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
+    expect(absent.success).toBe(true);
+    if (absent.success) expect(absent.data.hidden).toBeUndefined();
+    const bad = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: 'yes' });
+    expect(bad.ok).toBe(false);
+  });
+
   // ── v7 词汇统一：legacy 四象限矩阵（旧态/半迁移定向拒；v7 两形态放行）──
 
   it('v7 legacy ①：v6 旧态（name 标识 + title 展示、无 id）→ 定向拒 + legacy 标志 + 双键指引', () => {