@tbox.cn/app-toolkit 0.1.0

package/src/factory.ts

@@ -0,0 +1,297 @@
+import path from 'node:path';
+import { writeAtomic } from './core/fskit.js';
+import { walkManifests as internalsWalk } from './assembly/walk-manifests.js';
+import type { FileCache } from './core/file-cache.js';
+import { createFileCache } from './core/file-cache.js';
+import { resolveContractsForApp, invalidateContractsResolver } from './core/contracts-resolver.js';
+import type { ResolvedContracts } from './core/contracts-resolver.js';
+import { parseModuleDescriptor } from './core/module-schema.js';
+import { loadProviderDetailView, loadProviderServiceDetailView, loadProvidersView } from './views/providers.js';
+import { loadProviderCatalog, loadProviderCatalogRaw } from './assembly/provider-catalog.js';
+import { readIntegrationsStrict, readIntegrationsConfig } from './integrations/read.js';
+import { createWriteCore, type SaveResult, type WriteOptions } from './integrations/write.js';
+import { ensureMockBindings } from './integrations/mock-bindings.js';
+import { evaluateIntegrationServices, type IntegrationServiceIssue, type PredicateContracts } from './integrations/predicate.js';
+import { buildPredicateAssembly } from './integrations/predicate-io.js';
+import { AppToolkitError, contractsNotResolvedMessage } from './core/errors.js';
+import { loadViewSnapshotSync } from './views/context.js';
+import { loadModulesView, loadModuleDetailView } from './views/modules.js';
+import { loadAppView } from './views/app.js';
+import { loadServiceDetailView } from './views/service-detail.js';
+import { loadServiceResolutionsView, loadServiceResolutionDetail } from './views/service-resolutions.js';
+import type { WalkManifestsResult } from './assembly/walk-manifests.js';
+import type {
+  AppIntegrationNode,
+  AppView,
+  ModuleDetailView,
+  ModuleIntegrationNode,
+  ProviderDetail,
+  ProviderServiceDetail,
+  ProvidersView,
+  ServiceDetail,
+  ServiceIntegrationNode,
+  ServiceResolutionDetail,
+  ServiceResolutionsView,
+  ModulesView,
+} from './dto.js';
+
+/**
+ * createAppToolkit（C4 工厂）：22 方法 = 9 读（HTTP 直通）+ 4 写（HTTP 直通）+ 9 迁移面（Internals）。
+ * AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals——
+ * Read+Write = HTTP 直通面 additive 冻结（L1 端点↔方法 1:1，L3 命名镜像：Integration=节点级 /
+ * Config=文件级）；Internals = CLI/doctor/桥消费（自由演进）。
+ *
+ * **门控断言单点（policy at edge）**：求值（2）+ 写（4）+ ensureMockBindings / writeIntegrationsConfig /
+ * evaluateIntegrationServices 入口 assertContractsUsable——strictValidation === false → 503
+ * CONTRACTS_NOT_RESOLVED（message 三分支）；静态方法不门控（永不 503——铁律 #3）；
+ * integrations/ views/ 机制层保持纯函数。
+ *
+ * 并发：进程内写串行（per-factory promise chain）+ 原子写 + 写后本实例缓存即刻失效（D26）。
+ * onApplied（D7）：toolkit 判定「需要重启」（实际落盘且非 dryRun/no-diff）→ 调用一次 +
+ * restartScheduled 回填——通知闭包非控制，执行者恒为宿主 RunManager；CLI 不传恒 false。
+ */
+
+export interface AppToolkitOptions {
+  /** 写成功（实际落盘且非 dryRun/no-diff）→ 调用一次（宿主闭包内防抖/守卫）；CLI 不传恒 false */
+  onApplied?: () => void;
+}
+
+/** ── HTTP 直通面（9 读；L1 镜像律：方法名 = load + URL 资源段）── */
+export interface AppToolkitRead {
+  loadModules(): Promise<ModulesView>;
+  loadModule(moduleId: string): Promise<ModuleDetailView>;
+  loadApp(): Promise<AppView>;
+  loadService(service: string): Promise<ServiceDetail>;
+  loadServiceResolutions(services?: string[]): Promise<ServiceResolutionsView>;
+  loadServiceResolution(service: string): Promise<ServiceResolutionDetail>;
+  loadProviders(): Promise<ProvidersView>;
+  loadProvider(provider: string): Promise<ProviderDetail>;
+  loadProviderService(provider: string, service: string): Promise<ProviderServiceDetail>;
+}
+
+/** ── HTTP 直通面（4 写；body ≡ 文件节点全量替换；DELETE 无 dryRun/无 options）── */
+export interface AppToolkitWrite {
+  writeAppIntegration(
+    node: AppIntegrationNode,
+    o?: { dryRun?: boolean; credentials?: { type: string; values: Record<string, string> }; credentialsByInstance?: Record<string, { type: string; values: Record<string, string> }> },
+  ): Promise<SaveResult>;
+  writeModuleIntegration(moduleId: string, node: ModuleIntegrationNode, o?: { dryRun?: boolean }): Promise<SaveResult>;
+  writeServiceIntegration(
+    service: string,
+    node: ServiceIntegrationNode,
+    o?: { dryRun?: boolean; credentials?: { type: string; values: Record<string, string> }; credentialsByInstance?: Record<string, { type: string; values: Record<string, string> }> },
+  ): Promise<SaveResult>;
+  deleteServiceIntegration(service: string): Promise<SaveResult>;
+}
+
+/** ── Internals（9，非 HTTP 面；L3 宾语消歧：Integration=节点级 / Config=文件级）── */
+export interface AppToolkitInternals {
+  /** 逃生舱：正常路径无需调用（Freshness Contract 自动）；测试/宿主特殊场景 */
+  invalidate(): void;
+  resolveContracts(): Promise<ResolvedContracts>;
+  /** 四产物（枚举零缓存——契约机制载体） */
+  walkManifests(): WalkManifestsResult;
+  parseModuleDescriptor(raw: unknown): ReturnType<typeof parseModuleDescriptor>;
+  /** 富形态（≠ 包级桥源 loadProviderCatalog，双形态有意） */
+  loadProviderCatalogRaw(): ReturnType<typeof loadProviderCatalogRaw>;
+  /** 文件级读（doctor/migrate；宽松透传——strict 校验归门控面） */
+  readIntegrationsConfig(): Promise<Record<string, unknown> | null>;
+  /** 文件级整写（provider-migrate；门控同款） */
+  writeIntegrationsConfig(config: Record<string, unknown>): Promise<void>;
+  ensureMockBindings(): Promise<ReturnType<typeof ensureMockBindings>>;
+  /** 谓词单源（contracts 注入签名；结构化输出） */
+  evaluateIntegrationServices(input: Omit<Parameters<typeof evaluateIntegrationServices>[0], 'contracts'>): Promise<IntegrationServiceIssue[]>;
+}
+
+export type AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals;
+
+export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}): AppToolkit {
+  const cache: FileCache = createFileCache();
+  let writeChain: Promise<unknown> = Promise.resolve();
+
+  const viewCtx = { appDir, cache };
+
+  /** 门控断言（policy at edge）——strictValidation false → 503（message 三分支 N1） */
+  function assertContractsUsable(contracts: ResolvedContracts): void {
+    if (!contracts.strictValidation) {
+      throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
+    }
+  }
+
+  /** 快照（同步——调用方已 await resolveContracts） */
+  function snapshot(contracts: ResolvedContracts) {
+    return loadViewSnapshotSync(viewCtx, contracts);
+  }
+
+  /** 谓词全量 issues（求值轴/写后复查共用——contracts 注入 + buildPredicateAssembly 单源装配，FX-2b：
+   *  与 CLI doctor 规则同装配面——「面板 issues ≡ doctor issues」机制保证） */
+  async function predicateIssues(): Promise<IntegrationServiceIssue[]> {
+    const contracts = await resolveContractsForApp(appDir);
+    const snap = snapshot(contracts);
+    const config = snap.integrations;
+    if (config === null) return [];
+    const predicateContracts: PredicateContracts = {
+      resolveEffectiveService: assertFn(contracts.module.resolveEffectiveService, 'resolveEffectiveService'),
+      buildSupplyLookup: assertFn(contracts.module.buildSupplyLookup, 'buildSupplyLookup'),
+      moduleDomainOf: assertFn(contracts.module.moduleDomainOf, 'moduleDomainOf'),
+      normalizeInstances: assertFn(contracts.module.normalizeInstances, 'normalizeInstances'),
+      RESOURCE_TYPE_IDS: (contracts.module.RESOURCE_TYPE_IDS ?? []) as readonly string[],
+    };
+    const assembly = buildPredicateAssembly(appDir, snap.walk, config, process.env);
+    return evaluateIntegrationServices({
+      contracts: predicateContracts,
+      integrations: config as never,
+      supplies: predicateContracts.buildSupplyLookup(snap.catalog as never) as never,
+      ...assembly,
+    });
+  }
+
+  function assertFn<T>(fn: unknown, name: string): T {
+    if (typeof fn !== 'function') throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, `contracts 求值面 ${name} 缺席（形态异常）`);
+    return fn as T;
+  }
+
+  /** 写串行队列（进程内 last-writer-wins；链式保证单飞） */
+  function enqueue<T>(op: () => Promise<T> | T): Promise<T> {
+    const next = writeChain.then(op, op);
+    writeChain = next.catch(() => undefined);
+    return next;
+  }
+
+  const read = {
+    async loadModules() {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadModulesView(snapshot(contracts));
+    },
+    async loadModule(moduleId: string) {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadModuleDetailView(snapshot(contracts), moduleId);
+    },
+    async loadApp() {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadAppView(snapshot(contracts));
+    },
+    async loadService(service: string) {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadServiceDetailView(snapshot(contracts), service);
+    },
+    async loadServiceResolutions(services?: string[]) {
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      const issues = await predicateIssues();
+      return loadServiceResolutionsView(snapshot(contracts), issues, services);
+    },
+    async loadServiceResolution(service: string) {
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      const issues = await predicateIssues();
+      return loadServiceResolutionDetail(service, snapshot(contracts), issues);
+    },
+    async loadProviders() {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadProvidersView(snapshot(contracts));
+    },
+    async loadProvider(provider: string) {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadProviderDetailView(snapshot(contracts), provider);
+    },
+    async loadProviderService(provider: string, service: string) {
+      const contracts = await resolveContractsForApp(appDir);
+      return loadProviderServiceDetailView(snapshot(contracts), provider, service);
+    },
+  };
+
+  const core = createWriteCore(appDir, {
+    onApplied: options.onApplied,
+    cache,
+  });
+
+  const write = {
+    async writeAppIntegration(node: AppIntegrationNode, o?: WriteOptions) {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      return enqueue(() => core.applyApp(node as Record<string, unknown>, o));
+    },
+    async writeModuleIntegration(moduleId: string, node: ModuleIntegrationNode, o?: WriteOptions) {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      return enqueue(() => core.applyModule(moduleId, node as Record<string, unknown>, o));
+    },
+    async writeServiceIntegration(service: string, node: ServiceIntegrationNode, o?: WriteOptions) {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      return enqueue(() => core.applyService(service, node as Record<string, unknown>, o));
+    },
+    async deleteServiceIntegration(service: string) {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      return enqueue(() => core.deleteService(service));
+    },
+  };
+
+  const internals: AppToolkitInternals = {
+    invalidate() {
+      cache.invalidate();
+      invalidateContractsResolver(appDir);
+    },
+    async resolveContracts() {
+      return resolveContractsForApp(appDir);
+    },
+    walkManifests() {
+      return loadProviderCatalogRawWalk(appDir);
+    },
+    parseModuleDescriptor(raw: unknown) {
+      return parseModuleDescriptor(raw);
+    },
+    loadProviderCatalogRaw() {
+      return loadProviderCatalogRaw(appDir);
+    },
+    async readIntegrationsConfig() {
+      return readIntegrationsConfig(appDir, cache);
+    },
+    async writeIntegrationsConfig(config: Record<string, unknown>) {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      return enqueue(() => coreWriteIntegrationsConfig(appDir, config, cache));
+    },
+    async ensureMockBindings() {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      return enqueue(() => ensureMockBindings(appDir));
+    },
+    async evaluateIntegrationServices(input) {
+      await core.warmup();
+      const contracts = await resolveContractsForApp(appDir);
+      assertContractsUsable(contracts);
+      const predicateContracts: PredicateContracts = {
+        resolveEffectiveService: assertFn(contracts.module.resolveEffectiveService, 'resolveEffectiveService'),
+        buildSupplyLookup: assertFn(contracts.module.buildSupplyLookup, 'buildSupplyLookup'),
+        moduleDomainOf: assertFn(contracts.module.moduleDomainOf, 'moduleDomainOf'),
+        normalizeInstances: assertFn(contracts.module.normalizeInstances, 'normalizeInstances'),
+        RESOURCE_TYPE_IDS: (contracts.module.RESOURCE_TYPE_IDS ?? []) as readonly string[],
+      };
+      return evaluateIntegrationServices({ ...input, contracts: predicateContracts });
+    },
+  };
+
+  function loadProviderCatalogRawWalk(dir: string): WalkManifestsResult {
+    // walkManifests 直通（Internals 面——枚举零缓存契约载体；文件内容经本实例 cache，FX-3/F7）
+    return internalsWalk(dir, cache);
+  }
+
+  return { ...read, ...write, ...internals };
+}
+
+function coreWriteIntegrationsConfig(appDir: string, config: Record<string, unknown>, cache: FileCache): void {
+  const file = path.join(appDir, 'config', 'integrations.json');
+  writeAtomic(file, `${JSON.stringify(config, null, 2)}\n`);
+  cache.invalidate([file]);
+}
+
+export { loadProviderCatalog, loadProviderServiceDetailView, readIntegrationsStrict };

package/src/index.ts

@@ -0,0 +1,137 @@
+// app-toolkit 公开面聚合导出。
+// C2（core 层）：core 七件 + Freshness Contract。C3/C4 依次落 assembly/integrations/views/工厂/DTO。
+// 公开面冻结纪律：本文件导出清单即 DTO 单源契约（additive-only，L2——agtcodingbox import type 消费）。
+
+export {
+  parseModuleDescriptor,
+  moduleDescriptorSchema,
+  SAFE_NAME_PATTERN,
+  pageContribSchema,
+  tabContribSchema,
+  moduleDependencySchema,
+  providerSlotContribSchema,
+  serviceNeedContribSchema,
+  resourceNeedContribSchema,
+} from './core/module-schema.js';
+export type {
+  ModuleDescriptor,
+  CardContrib,
+  ProviderSlotContrib,
+  ServiceNeedContrib,
+  ResourceNeedContrib,
+  ParseModuleResult,
+} from './core/module-schema.js';
+
+export { expandEnvVars } from './core/env-expansion.js';
+export type { EnvExpansionResult } from './core/env-expansion.js';
+
+export {
+  deriveStem,
+  stemToRef,
+  stemToFilePath,
+  readCredentialFile,
+  writeCredentialFile,
+  maskCredentialValues,
+} from './core/credential-format.js';
+export type { CredentialFile, StemInput } from './core/credential-format.js';
+
+export { writeAtomic, ensureDir } from './core/fskit.js';
+
+export { createFileCache } from './core/file-cache.js';
+export type { FileCache } from './core/file-cache.js';
+
+export { resolveContractsForApp, invalidateContractsResolver } from './core/contracts-resolver.js';
+export type { ResolvedContracts } from './core/contracts-resolver.js';
+
+export type { EvaluationExports, ResolvedModule } from './core/contracts-expected.js';
+
+// ── integrations 谓词单源（迁移面；doctor 第 19 条与工厂 evaluateIntegrationServices 共用）──
+export { evaluateIntegrationServices, isControlledInlineProvider, checkInstanceKeys } from './integrations/predicate.js';
+export type {
+  IntegrationServicePredicateInput,
+  IntegrationServiceIssue,
+  PredicateContracts,
+  SupplyLookup,
+} from './integrations/predicate.js';
+// ── 谓词装配单源（FX-2b/F1：CLI doctor 规则与 toolkit 工厂同装配面——双通道 walkManifests）──
+export { buildPredicateAssembly, refToEnvKey } from './integrations/predicate-io.js';
+export type { PredicateAssembly, PredicateIoInputs } from './integrations/predicate-io.js';
+
+// ── assembly 层（目录知识——walkManifests 四产物 + catalog 双形态 + 组合单体装配）──
+export { walkManifests } from './assembly/walk-manifests.js';
+export type { WalkManifestsResult, WalkModuleInfo, WalkCatalog, WalkProviderEntry } from './assembly/walk-manifests.js';
+export { readAppManifest, writeAppManifest, manifestPath } from './assembly/app-manifest.js';
+export type { AppManifest, NpmModuleEntry, ModuleMode } from './assembly/app-manifest.js';
+export { loadProviderCatalog, loadProviderCatalogRaw } from './assembly/provider-catalog.js';
+export type { BridgeProviderCatalog, ProviderServiceSchemas, ProviderServiceSchemasResult } from './assembly/provider-catalog.js';
+
+// ── integrations 层（领域——读/写核心/凭据双工件/mock 绑定）──
+export { readIntegrationsConfig, readIntegrationsStrict } from './integrations/read.js';
+export type { ReadIntegrationsResult } from './integrations/read.js';
+export { createWriteCore, deepEqual } from './integrations/write.js';
+export type { SaveResult, WriteOptions, WriteCoreOptions, WriteCore } from './integrations/write.js';
+export { ensureMockBindings } from './integrations/mock-bindings.js';
+export type { MockBindingsResult } from './integrations/mock-bindings.js';
+export { reconcileOrphanCredentials, credentialArtifactExists } from './integrations/credentials.js';
+export type { AppliedCredential, CredentialInput, OrphanIssue, PlannedCredential } from './integrations/credentials.js';
+
+// ── 错误面（领域 6 码——AppToolkitError；name 字面量约定见 errors.ts）──
+export { AppToolkitError, contractsNotResolvedMessage } from './core/errors.js';
+export type { AppToolkitErrorCode } from './core/errors.js';
+
+// ── views（五投影——静态四轴 + 求值轴；铁律 #3 静态/求值分离由投影结构承载）──
+export { loadModulesView, loadModuleDetailView, moduleDomainKeyOf } from './views/modules.js';
+export { loadAppView } from './views/app.js';
+export { loadServiceDetailView } from './views/service-detail.js';
+export { loadProvidersView, loadProviderDetailView, loadProviderServiceDetailView } from './views/providers.js';
+export { loadServiceResolutionsView, loadServiceResolutionDetail, resolveServiceSummary } from './views/service-resolutions.js';
+export type { ViewContext, ViewSnapshot } from './views/context.js';
+
+// ── 工厂（22 方法 = 9 读 + 4 写 + 9 Internals；门控 policy at edge；写串行）──
+export { createAppToolkit } from './factory.js';
+export type { AppToolkit, AppToolkitRead, AppToolkitWrite, AppToolkitInternals, AppToolkitOptions } from './factory.js';
+
+// ── DTO（api.md §3 字段级单源——28 类型；agtcodingbox/tbox-ai-coding import type 消费）──
+export type {
+  ServiceStatus,
+  BindingLayer,
+  ModulesView,
+  ModuleDeclaration,
+  ServiceDemand,
+  ModuleDetailView,
+  AppView,
+  ServiceDetail,
+  ServiceResolutionsView,
+  ServiceResolutionEntry,
+  ServiceResolution,
+  ServiceResolutionDetail,
+  AppIntegrationNode,
+  ModuleIntegrationNode,
+  ServiceIntegrationNode,
+  ServiceInstanceNode,
+  InlineVendorDeclaration,
+  CredentialValues,
+  ResolvedInstance,
+  ProvidersView,
+  ProviderEntry,
+  ProviderDetail,
+  ProviderServiceDetail,
+  EffectiveBinding,
+  CredentialEcho,
+  ContractsResolution,
+  IntegrationIssue,
+} from './dto.js';
+export { APP_INTEGRATION_NODE_KEYS } from './dto.js';
+export {
+  readAppManifestFull,
+  upsertNpmModule,
+  removeNpmModule,
+  upsertMiniappContainer,
+  updateNpmModule,
+  isValidModuleId,
+  assertValidModuleId,
+} from './assembly/app-manifest.js';
+export type { MiniappContainerEntry, AppManifestFull } from './assembly/app-manifest.js';
+export { collectDeclaredModules, extractModuleIdFromSource } from './assembly/walk-manifests.js';
+export type { DeclaredModuleInfo } from './assembly/walk-manifests.js';
+export { resolveContractsForApp as resolveContractsForAppExport } from './core/contracts-resolver.js';

package/src/integrations/credentials.ts

@@ -0,0 +1,153 @@
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { deriveStem, readCredentialFile, stemToFilePath, writeCredentialFile } from '../core/credential-format.js';
+
+/**
+ * 凭据双工件·写端（C3-4 credentials；FX-1c 拆分——F3 定序）：
+ * credentials / credentialsByInstance（body 唯一非文件字段）→ **纯派生 plan（零 I/O）**
+ * → 消费方（write.ts）ref 回填节点（先于 no-diff 判定）→ 严格校验通过后 `writeCredentialArtifacts`
+ * 落盘（dryRun → 零写盘 + existsSync 预览）。同 stem 已在场 → 重写 + overwrote:true。
+ * 孤儿凭据 = **写后对账**（扫描文件全量 credentialRef 引用 vs 凭据目录全集 →
+ * ORPHANED_CREDENTIAL warning——统一覆盖 DELETE 与 PUT 替换两类来源，只报告不自动清理，D9）。
+ */
+
+export interface CredentialInput {
+  type: string;
+  values: Record<string, string>;
+}
+
+export interface AppliedCredential {
+  stem: string;
+  ref: string;
+  overwrote: boolean;
+}
+
+/** 凭据工件计划项（纯派生产物——stem/ref 确定性；input 供落盘/校验消费） */
+export interface PlannedCredential {
+  /** 实例级（credentialsByInstance）时在场；应用/服务级根凭据缺席 */
+  instanceId?: string;
+  stem: string;
+  ref: string;
+  input: CredentialInput;
+}
+
+export interface OrphanIssue {
+  severity: 'warning';
+  code: 'ORPHANED_CREDENTIAL';
+  service?: string;
+  instance?: string;
+  message: string;
+}
+
+/** 应用级凭据计划（app 写路径）：stem = `${provider}-global` / `${provider}-${instanceId}-global`——纯派生零 I/O */
+export function planAppCredentialArtifacts(
+  provider: string,
+  credentials?: CredentialInput,
+  credentialsByInstance?: Record<string, CredentialInput>,
+): PlannedCredential[] {
+  const plan: PlannedCredential[] = [];
+  if (credentials) {
+    const stem = deriveStem({ provider });
+    plan.push({ stem, ref: `secret://${stem}`, input: credentials });
+  }
+  for (const [instanceId, input] of Object.entries(credentialsByInstance ?? {})) {
+    const stem = deriveStem({ provider, instanceId });
+    plan.push({ instanceId, stem, ref: `secret://${stem}`, input });
+  }
+  return plan;
+}
+
+/** 服务级凭据计划（service 写路径）：stem = `${provider}-${service}` / `${provider}-${instanceId}-${domain}`——纯派生零 I/O */
+export function planServiceCredentialArtifacts(
+  provider: string,
+  service: string,
+  domain: string,
+  credentials?: CredentialInput,
+  credentialsByInstance?: Record<string, CredentialInput>,
+): PlannedCredential[] {
+  const plan: PlannedCredential[] = [];
+  if (credentials) {
+    const stem = deriveStem({ provider, service });
+    plan.push({ stem, ref: `secret://${stem}`, input: credentials });
+  }
+  for (const [instanceId, input] of Object.entries(credentialsByInstance ?? {})) {
+    const stem = deriveStem({ provider, instanceId, domain });
+    plan.push({ instanceId, stem, ref: `secret://${stem}`, input });
+  }
+  return plan;
+}
+
+/** 凭据工件落盘（F3 第 8 步——消费方保证已于严格校验通过后调用）；
+ *  dryRun → 零写盘，overwrote = existsSync 预览（「将创建工件」语义）。 */
+export function writeCredentialArtifacts(
+  appDir: string,
+  plan: readonly PlannedCredential[],
+  dryRun: boolean,
+): AppliedCredential[] {
+  return plan.map((p) => ({
+    stem: p.stem,
+    ref: p.ref,
+    overwrote: dryRun
+      ? existsSync(join(appDir, stemToFilePath(p.stem)))
+      : writeCredentialFile(appDir, p.stem, p.input),
+  }));
+}
+
+/** 凭据工件在场探测（dryRun 预览与对账共用） */
+export function credentialArtifactExists(appDir: string, stem: string): boolean {
+  return existsSync(join(appDir, stemToFilePath(stem)));
+}
+
+/** 全文件 credentialRef 引用收集（integrations.json 深扫描——secret:// 前缀值） */
+function collectRefs(value: unknown, out: Set<string>): void {
+  if (typeof value === 'string') {
+    if (value.startsWith('secret://')) out.add(value.slice('secret://'.length));
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) collectRefs(v, out);
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const v of Object.values(value)) collectRefs(v, out);
+  }
+}
+
+/** 孤儿凭据写后对账（D9）：凭据目录全集 − integrations.json 全量引用 = 孤儿（只报告不清理） */
+export function reconcileOrphanCredentials(appDir: string): OrphanIssue[] {
+  const credentialsDir = join(appDir, 'config', 'credentials');
+  const referenced = new Set<string>();
+  const integrationsFile = join(appDir, 'config', 'integrations.json');
+  if (existsSync(integrationsFile)) {
+    try {
+      collectRefs(JSON.parse(readFileSync(integrationsFile, 'utf8')), referenced);
+    } catch {
+      /* 坏文件 → 引用集为空（孤儿对账按现状目录全集报告） */
+    }
+  }
+  const issues: OrphanIssue[] = [];
+  if (!existsSync(credentialsDir)) return issues;
+  let stems: string[] = [];
+  try {
+    stems = readdirSync(credentialsDir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -'.json'.length));
+  } catch {
+    return issues;
+  }
+  for (const stem of stems.sort()) {
+    if (referenced.has(stem)) continue;
+    // 掩码读侧验证：孤儿报告只提文件位（零真值——CredentialEcho 红线同源）
+    const content = readCredentialFile(appDir, stem);
+    void content;
+    issues.push({
+      severity: 'warning',
+      code: 'ORPHANED_CREDENTIAL',
+      message: `config/credentials/${stem}.json 不再被引用（凭据文件保留，可手动清理）`,
+    });
+  }
+  return issues;
+}
+
+/** stem → 文件相对路径（对账测试用透出） */
+export function credentialFilePath(stem: string): string {
+  return stemToFilePath(stem);
+}

package/src/integrations/mock-bindings.ts

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { walkManifests } from '../assembly/walk-manifests.js';
+import { writeAtomic } from '../core/fskit.js';
+
+/**
+ * mock 槽绑定生成器（自 CLI mock-bindings.ts 迁入；provider 拆包 F3 收敛 · B 方案；integrations v4 零拓扑形态）：
+ * 应用内 config/integrations.json 缺席时，从已装模块 manifest 的 local:true 槽派生全槽 mock 绑定。
+ *
+ * 语义边界（零改动迁移）：
+ * - 缺席即跳过、永不覆盖（在场文件 = 用户/素材真源，生成器零侵入）；
+ * - 只绑 local:true 槽（真厂商 provider 永不自动绑定）；
+ * - sync 不触发（add = 新事实进入体系，sync = 状态重放）。
+ * 迁移顺带修复：writeFileSync → writeAtomic（原子写；H5）。
+ * 模块发现改 walkManifests（单源——CLI listLocalModules 并入）。
+ */
+
+export interface MockBindingsResult {
+  generated: boolean;
+  reason: 'in-place' | 'no-local-slots' | 'generated';
+  /** 本次生成（或在场文件阻断时的空集）涉及的 local 槽服务名 */
+  services: string[];
+}
+
+export function ensureMockBindings(appDir: string): MockBindingsResult {
+  const file = join(appDir, 'config', 'integrations.json');
+  if (existsSync(file)) {
+    return { generated: false, reason: 'in-place', services: [] };
+  }
+  const slots: Array<{ service: string; provider: string; implementation: string }> = [];
+  for (const mod of walkManifests(appDir).modules) {
+    for (const slot of mod.descriptor.contributes.providers?.slots ?? []) {
+      if (slot.local !== true) continue;
+      slots.push({ service: slot.service, provider: slot.provider, implementation: slot.implementation });
+    }
+  }
+  if (slots.length === 0) {
+    return { generated: false, reason: 'no-local-slots', services: [] };
+  }
+  const services: Record<string, unknown> = {};
+  const vendors = new Set(slots.map((s) => s.provider));
+  if (vendors.size === 1) {
+    // 单一 local 厂商 → terse：root.provider 继承 + 空槽对象（instances 缺席 = 通配激活）
+    const [vendor] = vendors;
+    for (const s of slots) services[s.service] = {};
+    writeAtomic(file, `${JSON.stringify({ provider: vendor, services }, null, 2)}\n`);
+  } else {
+    // 异构兜底：逐槽双字段（显式绑定组——无 root 继承位；同样零拓扑）
+    for (const s of slots) {
+      services[s.service] = { provider: s.provider, implementation: s.implementation };
+    }
+    writeAtomic(file, `${JSON.stringify({ services }, null, 2)}\n`);
+  }
+  return { generated: true, reason: 'generated', services: slots.map((s) => s.service).sort() };
+}