@tbox.cn/app-provider-custom 0.1.0

package/AGENTS.md

@@ -0,0 +1,33 @@
+# provider-custom —— 自定义 API 实施落点（AI 集成指引）
+
+本包是**自定义厂商（自定义 API）的 adapter 代码落点**：用户在 AI 构建面板为某服务保存
+「自定义 API」配置（内联声明）后，运行时因供给不在场报 `PROVIDER_NOT_IMPLEMENTED`——
+由 AI 助手按本指引在本包实施 adapter，注册命中后配置即刻转 ok。
+
+## 实施三步
+
+1. **读声明**：`config/integrations.json` 中目标服务（如 `parking.query`）的
+   `provider` 为对象（内联声明：`{ provider, credentialType, configSchema? }`）+
+   `implementation` 字面量——这就是要实现的厂商身份与凭据约定。
+2. **实现 adapter**：在 `src/server/` 新建实现文件，实现该服务对应模块的 Port 接口
+   （接口定义见对应业务模块 `src/server/ports/`；连接参数 = 绑定组 `config`，实例键 =
+   `input.instanceId`）。adapter 工厂签名：
+
+   ```ts
+   const factory: ServiceAdapterFactory = (input) => new MyApiServiceImpl(input);
+   ```
+
+3. **注册**：在 `src/server/index.ts` 的 `register(ctx)` 中调用
+   `ctx.integrations?.registerAdapter('<provider 名>', '<implementation>', factory)`。
+   多个自定义 API 均注册到本包（单包多厂商，注册表双键不关心包边界）。
+
+## 完成判据
+
+- 应用重启后 `PROVIDER_NOT_IMPLEMENTED` 消失（register 命中）；
+- AI 构建面板该服务 chip 由「AI 实施中」转为厂商名、issues 清零。
+
+## 真实厂商接入
+
+对外提供正式 API 的厂商（支付/会员等大规模集成）走官方 provider 包形态：
+manifest `contributes.providers.slots` 声明供给 + 独立包发布——参照
+`modules/provider-mock`（结构样例）与 docs/reference/providers.md。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbox.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @tbox.cn/app-provider-custom
+
+自定义厂商实施落点空包（与 provider-mock 并列的中立空壳）：manifest contributes 全空（零贡献
+合法——descriptor zod 全 default），出厂无任何供给/需求/卡片声明，纯为 AI 实施自定义 API
+adapter 提供**有形代码落点**。闭环机制见 AGENTS.md（SDK 零改动——registerAdapter 命中即转 ok）。
+
+单包多厂商：多个自定义 API 的 adapter 均在此包注册。依赖精确裁剪 = app-sdk + app-contracts
+（不消费领域 Port 类型，无 contracts-mall）；无 client 入口；无 peerDependencies。

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 自定义厂商实施落点空包入口（ai-build D10：空包落点——「声明 → AI 实施 → 面板转 ok」闭环载体）。
+ * 服务端能力经 `./server` 子路径（与官方 provider 包同构）；无 client 入口。
+ */
+declare const providerId = "provider-custom";
+
+export { providerId };

package/dist/index.js

@@ -0,0 +1,5 @@
+// src/index.ts
+var providerId = "provider-custom";
+export {
+  providerId
+};

package/dist/server/index.d.ts

@@ -0,0 +1,40 @@
+import { ServerContext } from '@tbox.cn/app-sdk/server';
+
+/**
+ * 自定义厂商实施落点空包·服务端入口（ai-build D10；单包多厂商——多个自定义 API 的
+ * adapter 均在此包 register，注册表双键不关心包边界）。
+ *
+ * 零贡献合法（manifest contributes 全空——descriptor zod 全 default）：本包出厂无任何
+ * 供给/需求/卡片声明，纯为 AI 实施提供**有形代码落点**。运行时闭环（SDK 零改动）：
+ *   1. 用户在面板为某服务保存内联声明（自定义 API：provider 对象 + implementation 字面量）；
+ *   2. 应用启动解析该绑定 → 供给不在场 → PROVIDER_NOT_IMPLEMENTED（fail-visible）；
+ *   3. AI 按 AGENTS.md 指引在本包实现 adapter（下 factory 工厂签名）并在 register 挂载
+ *      registerAdapter(provider, implementation, factory)；
+ *   4. 重启后 register 命中 → 内联声明即刻转 ok——转变即完成信号（面板 issues 清零）。
+ *
+ * 真实厂商接入（官方 provider 包形态：manifest 槽声明 + 独立包发布）跳转见 AGENTS.md。
+ */
+
+declare const PROVIDER_CUSTOM = "provider-custom";
+/**
+ * adapter 工厂签名示例（真实实施时替换本注释为具体 adapter 注册）：
+ *
+ *   const myApiAdapterFactory: ServiceAdapterFactory = (input) => {
+ *     // input.service        服务 id（如 'parking.query'）
+ *     // input.instanceId     部署实例键（mall 场景 = mallId；通配激活时由框架解析）
+ *     // input.config         绑定组五层合并后的连接参数（面板保存的 baseUrl 等）
+ *     // 返回：实现该服务 Port 的 adapter 实例（模块 src/server/ports 定义）
+ *     return new MyApiServiceImpl(input);
+ *   };
+ *   ctx.integrations?.registerAdapter('my-custom-api', 'my-custom-parking@1', myApiAdapterFactory);
+ */
+declare function register(ctx: ServerContext): void;
+declare const serverModule: {
+    declaration: {
+        moduleId: string;
+    };
+    cards: {};
+    register: typeof register;
+};
+
+export { PROVIDER_CUSTOM, register, serverModule };

package/dist/server/index.js

@@ -0,0 +1,15 @@
+// src/server/index.ts
+var PROVIDER_CUSTOM = "provider-custom";
+function register(ctx) {
+  void ctx;
+}
+var serverModule = {
+  declaration: { moduleId: "provider-custom" },
+  cards: {},
+  register
+};
+export {
+  PROVIDER_CUSTOM,
+  register,
+  serverModule
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tbox.cn/app-provider-custom",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "自定义厂商实施落点空包（中立空壳）：内联声明（自定义 API）的 adapter 代码落点——AI 按 AGENTS.md 指引实施，registerAdapter 命中即转 ok。单包多厂商。",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    }
+  },
+  "dependencies": {
+    "@tbox.cn/app-sdk": "0.17.0",
+    "@tbox.cn/app-contracts": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10",
+    "tsup": "8.5.1"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tests",
+    "tbox.module.json",
+    "tsconfig.json",
+    "tsup.config.ts",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * 自定义厂商实施落点空包入口（ai-build D10：空包落点——「声明 → AI 实施 → 面板转 ok」闭环载体）。
+ * 服务端能力经 `./server` 子路径（与官方 provider 包同构）；无 client 入口。
+ */
+export const providerId = 'provider-custom';

package/src/server/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 自定义厂商实施落点空包·服务端入口（ai-build D10；单包多厂商——多个自定义 API 的
+ * adapter 均在此包 register，注册表双键不关心包边界）。
+ *
+ * 零贡献合法（manifest contributes 全空——descriptor zod 全 default）：本包出厂无任何
+ * 供给/需求/卡片声明，纯为 AI 实施提供**有形代码落点**。运行时闭环（SDK 零改动）：
+ *   1. 用户在面板为某服务保存内联声明（自定义 API：provider 对象 + implementation 字面量）；
+ *   2. 应用启动解析该绑定 → 供给不在场 → PROVIDER_NOT_IMPLEMENTED（fail-visible）；
+ *   3. AI 按 AGENTS.md 指引在本包实现 adapter（下 factory 工厂签名）并在 register 挂载
+ *      registerAdapter(provider, implementation, factory)；
+ *   4. 重启后 register 命中 → 内联声明即刻转 ok——转变即完成信号（面板 issues 清零）。
+ *
+ * 真实厂商接入（官方 provider 包形态：manifest 槽声明 + 独立包发布）跳转见 AGENTS.md。
+ */
+import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+
+export const PROVIDER_CUSTOM = 'provider-custom';
+
+/**
+ * adapter 工厂签名示例（真实实施时替换本注释为具体 adapter 注册）：
+ *
+ *   const myApiAdapterFactory: ServiceAdapterFactory = (input) => {
+ *     // input.service        服务 id（如 'parking.query'）
+ *     // input.instanceId     部署实例键（mall 场景 = mallId；通配激活时由框架解析）
+ *     // input.config         绑定组五层合并后的连接参数（面板保存的 baseUrl 等）
+ *     // 返回：实现该服务 Port 的 adapter 实例（模块 src/server/ports 定义）
+ *     return new MyApiServiceImpl(input);
+ *   };
+ *   ctx.integrations?.registerAdapter('my-custom-api', 'my-custom-parking@1', myApiAdapterFactory);
+ */
+export function register(ctx: ServerContext): void {
+  // 挂点：多个自定义 API 的 adapter 均在此注册（见上方签名示例）。
+  void ctx;
+}
+
+export const serverModule = {
+  declaration: { moduleId: 'provider-custom' },
+  cards: {},
+  register,
+} satisfies ServerModule;

package/tbox.module.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "name": "provider-custom",
+  "version": "0.1.0",
+  "kind": "business",
+  "risk": {
+    "level": "low",
+    "writeBoundary": "source"
+  },
+  "distribution": {
+    "defaultMode": "codegen"
+  },
+  "contributes": {
+    "handlers": [],
+    "tools": [],
+    "cards": [],
+    "routes": [],
+    "pages": [],
+    "tabs": [],
+    "providers": {
+      "slots": []
+    },
+    "services": []
+  },
+  "dependencies": {
+    "modules": []
+  },
+  "env": []
+}

package/tests/provider-custom.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { providerId } from '../src/index';
+import { serverModule } from '../src/server/index';
+
+describe('provider-custom 空包（D10 落点）', () => {
+  it('serverModule 形状：moduleId + 空 cards + register 可调用', () => {
+    expect(serverModule.declaration.moduleId).toBe('provider-custom');
+    expect(serverModule.cards).toEqual({});
+    expect(typeof serverModule.register).toBe('function');
+    expect(providerId).toBe('provider-custom');
+  });
+
+  it('register 零贡献：调用不抛（mock ctx 无 integrations 挂点）', () => {
+    const ctx = {} as never;
+    expect(() => serverModule.register(ctx)).not.toThrow();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src", "tests"]
+}

package/tsup.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    'server/index': 'src/server/index.ts',
+  },
+  format: ['esm'],
+  target: 'node20',
+  platform: 'node',
+  outDir: 'dist',
+  clean: true,
+  sourcemap: false,
+  // dts worker 以命令行式传参会撞 TS5074(incremental 需单文件 emit 或 tsBuildInfoFile);
+  // 声明产物一次性构建无需增量——仅 dts 关闭,typecheck 的增量缓存不受影响。
+  dts: { compilerOptions: { incremental: false } },
+  external: ['@tbox.cn/app-sdk', '@tbox.cn/app-contracts', 'zod'],
+});