@tbox.cn/app-module-customer-service 0.1.1

package/src/server/ports/index.ts

@@ -0,0 +1,77 @@
+/**
+ * 客服承接 Port 解析：本地知识库域恒本地装配（与 provider 供给面正交）。
+ * - app-config 服务（integrations v5 modules 节内存源）注入时按 install id 取资源
+ *   （ref 展开已在 resolver 构造期完成——消费端只见直填形状）；
+ * - 无服务/缺资源键 → 占位等值回退（模块单测与未装配环境不破坏，离线零行为变化）。
+ */
+import type {
+  CustomerServiceQueryPort,
+} from '@tbox.cn/app-contracts-mall';
+import { parseMallScope } from '@tbox.cn/app-contracts-mall';
+import type { ServerContext, ModuleResourceResolver, ResolvedResource } from '@tbox.cn/app-sdk/server';
+import { createKnowledgeClient, KNOWLEDGE_PLACEHOLDER_DATASET_IDS } from '@tbox.cn/app-sdk/server';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { EmptyCustomerServiceAdapter, KnowledgeSearchAdapter, type AssistanceKnowledgeConfig } from './local-adapters';
+
+export interface CustomerServicePorts {
+  customerService: CustomerServiceQueryPort;
+}
+
+/** mall-directory 服务消费接口（015 S7：模板注册，deployment.malls 单一来源；模块只依赖此结构类型） */
+export interface MallDirectoryService {
+  contactPhone(mallId: string): string | undefined;
+}
+
+/** 解析模板注入的 mall-directory 服务（未注册 → undefined） */
+function resolveMallDirectory(ctx: ServerContext): MallDirectoryService | undefined {
+  return ctx.services.resolve?.('mall-directory') as MallDirectoryService | undefined;
+}
+
+/** mall scope 的 contactPhone（联系客服卡拨打条目数据源；mallId 显式 reqCtx、目录经 ctx 解析） */
+export function currentContactPhone(reqCtx: RequestContext | undefined, ctx: ServerContext): string | undefined {
+  const mallId = parseMallScope(reqCtx?.attributes)?.mallId;
+  if (!mallId) return undefined;
+  return resolveMallDirectory(ctx)?.contactPhone(mallId);
+}
+
+/** 模块 install id 单源（resolver 键 = .tbox/app.json entry.id / packages/ 目录名——
+ *  与 declaration.moduleId 短名两词汇不同轴） */
+const MODULE_ID = 'module-customer-service';
+
+/**
+ * 占位等值回退（无 app-config 服务/缺资源键时——模块单测与未装配环境不破坏，离线零行为变化）。
+ * 真实 datasetId 由 integrations.json modules 节（create --config-dir 注入）提供；哨兵常量与 smoke R1 共用。
+ */
+const DEFAULT_FAQ_RESOURCE: ResolvedResource = { type: 'knowledge', datasetId: KNOWLEDGE_PLACEHOLDER_DATASET_IDS[0] };
+const DEFAULT_KB_RESOURCE: ResolvedResource = { type: 'knowledge', datasetId: KNOWLEDGE_PLACEHOLDER_DATASET_IDS[1] };
+
+/** 导出供单测（resources 取用语义锚定：缺键回退占位、在场透传） */
+export function resolveAssistanceConfig(ctx: ServerContext, mallId: string | undefined): AssistanceKnowledgeConfig {
+  const resolver = ctx.services.resolve?.('app-config') as ModuleResourceResolver | undefined;
+  const resources = resolver ? resolver(MODULE_ID) : {};
+  if (!resolver) {
+    console.warn(`[customer-service] app-config 服务未注入 mallId=${mallId ?? 'none'}，知识库使用占位 datasetId（召回必然为空）`);
+  } else if (!resources['customer-service-faq-kb']) {
+    console.warn(`[customer-service] app-config 无 customer-service-faq-kb 资源 mallId=${mallId ?? 'none'}，知识库使用占位 datasetId`);
+  }
+  return {
+    faq: resources['customer-service-faq-kb'] ?? DEFAULT_FAQ_RESOURCE,
+    knowledge: resources['knowledge-assistance-kb'] ?? DEFAULT_KB_RESOURCE,
+  };
+}
+
+/**
+ * 解析客服承接 Port 集合（运行期调用；register 只注册不解析——铁律）。
+ * 恒本地知识库装配；TBOX_API_KEY 未配置 → 空 FAQ（静默降级）。
+ */
+export function resolveCustomerServicePorts(reqCtx: RequestContext, ctx: ServerContext): CustomerServicePorts {
+  const mallId = parseMallScope(reqCtx?.attributes)?.mallId;
+  const cfg = resolveAssistanceConfig(ctx, mallId);
+  try {
+    // knowledge client 按调用构造（无热路径缓存诉求——FAQ 检索频次低，构造轻量）
+    return { customerService: new KnowledgeSearchAdapter(createKnowledgeClient(), cfg) };
+  } catch (e) {
+    ctx.logger?.debug(`knowledge 未配置或构造失败，FAQ 空降级：err=${(e as Error).message}`);
+    return { customerService: new EmptyCustomerServiceAdapter() };
+  }
+}

package/src/server/ports/local-adapters.ts

@@ -0,0 +1,107 @@
+/**
+ * 客服承接本地 Port 实现：FAQ/知识库走 SDK KnowledgeClient（恒本地装配——与 provider
+ * 远程检索面正交；自 shopping-guide 模块迁入，2026-08-31 客服模块拆分）。
+ */
+import type {
+  CustomerServiceQueryPort,
+  FaqEntry,
+  KnowledgeEntry,
+  ShoppingQueryContext,
+} from '@tbox.cn/app-contracts-mall';
+import type { KnowledgeClient, ResolvedResource } from '@tbox.cn/app-sdk/server';
+
+/**
+ * 协助知识资源配置（integrations v5：app-config 服务注入；缺服务/缺资源键 → 占位等值回退）。
+ * customer-service-faq-kb / knowledge-assistance-kb 为模块 manifest contributes.resources 资源 id；
+ * 消费端恒见已展开 ResolvedResource（ref 声明期字段已被 resolver 构造期消解）。
+ */
+export interface AssistanceKnowledgeConfig {
+  faq: ResolvedResource;
+  knowledge: ResolvedResource;
+}
+
+export class KnowledgeSearchAdapter implements CustomerServiceQueryPort {
+  constructor(
+    private readonly knowledge: KnowledgeClient,
+    private readonly cfg: AssistanceKnowledgeConfig,
+  ) {}
+
+  async searchFaq(
+    _ctx: ShoppingQueryContext,
+    query: string,
+    topK?: number,
+  ): Promise<readonly FaqEntry[]> {
+    const results = await this.knowledge.search({
+      // cfg 来源（resolver 展开直填 / 模块占位常量）恒有 datasetId（ResolvedResource 必填字段）
+      datasetId: this.cfg.faq.datasetId,
+      query,
+      topK: topK ?? this.cfg.faq.topK ?? 3,
+      ...(this.cfg.faq.scoreThreshold !== undefined ? { scoreThreshold: this.cfg.faq.scoreThreshold } : {}),
+    });
+    return results.map((hit) => {
+      const parsed = tryParseJsonFaqDoc(hit.content);
+      return {
+        question: parsed?.question ?? query,
+        answer: parsed?.answer ?? summarize(hit.content),
+        ...(hit.originFileName ? { category: hit.originFileName } : {}),
+        relevanceScore: hit.score,
+      };
+    });
+  }
+
+  async searchKnowledge(
+    _ctx: ShoppingQueryContext,
+    query: string,
+    topK?: number,
+  ): Promise<readonly KnowledgeEntry[]> {
+    const results = await this.knowledge.search({
+      datasetId: this.cfg.knowledge.datasetId,
+      query,
+      topK: topK ?? this.cfg.knowledge.topK ?? 3,
+      ...(this.cfg.knowledge.scoreThreshold !== undefined ? { scoreThreshold: this.cfg.knowledge.scoreThreshold } : {}),
+    });
+    return results.map((hit) => ({
+      content: hit.content,
+      score: hit.score,
+      ...(hit.originFileName ? { title: hit.originFileName } : {}),
+    }));
+  }
+}
+
+export class EmptyCustomerServiceAdapter implements CustomerServiceQueryPort {
+  async searchFaq() {
+    return [];
+  }
+  async searchKnowledge() {
+    return [];
+  }
+}
+
+/** 知识库文档若为 {question,answer,...} JSON 结构则解析，否则返回 undefined */
+function tryParseJsonFaqDoc(content: string): { question: string; answer: string } | undefined {
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    if (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      typeof (parsed as Record<string, unknown>).answer === 'string'
+    ) {
+      const doc = parsed as Record<string, unknown>;
+      return {
+        question: typeof doc.question === 'string' ? doc.question : '',
+        answer: doc.answer as string,
+      };
+    }
+  } catch {
+    // 非 JSON，走普通摘要路径
+  }
+  return undefined;
+}
+
+function summarize(content: string): string {
+  return content
+    .replace(/^#+\s+/gm, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 320);
+}

package/src/server/projections/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 客服承接投影：FAQ 卡数据（自 shopping-guide 迁入，2026-08-31 客服模块拆分）。
+ */
+import type { CustomerServiceFaqCardData, FaqEntry } from '@tbox.cn/app-contracts-mall';
+
+/** FAQ 卡答话事实（与原 summaries.faq 同构：整卡数据 JSON 单行，模型转述唯一依据） */
+export function faqSummary(data: CustomerServiceFaqCardData): string {
+  return JSON.stringify(data);
+}
+
+export function projectCustomerServiceFaq(
+  query: string,
+  faqs: readonly FaqEntry[],
+  noResultsReason?: string,
+  contactPhone?: string,
+): CustomerServiceFaqCardData {
+  return {
+    query,
+    faqs: faqs.map((f) => ({
+      question: f.question,
+      answer: f.answer,
+      ...(f.category ? { category: f.category } : {}),
+      relevanceScore: f.relevanceScore,
+    })),
+    ...(contactPhone ? { contactPhone } : {}),
+    ...(noResultsReason ? { noResultsReason } : {}),
+  };
+}

package/src/server/tools/index.ts

@@ -0,0 +1,89 @@
+/**
+ * 客服承接 1 工具（011 K5：D11 字符串化 inputSchema——仅 string / map<string,string>）。
+ * customer-service-faq：FAQ 命中返回知识条目（作答素材——正文直接作答）；无结果同样仅返回
+ * summary（正文如实说明）——客服域零出卡（2026-09-02：联系客服引导卡下线，转人工走正文话术）。
+ * 自 shopping-guide 模块迁入（2026-08-31 客服模块拆分）。
+ */
+import { createTool, requireToolRequestContext } from '@tbox.cn/app-sdk/server';
+import type { ServerContext, ToolExecContextLike } from '@tbox.cn/app-sdk/server';
+import { z } from 'zod';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { mallScopeOrEmpty } from '@tbox.cn/app-contracts-mall';
+import type { ShoppingQueryContext } from '@tbox.cn/app-contracts-mall';
+import { resolveCustomerServicePorts, currentContactPhone, type CustomerServicePorts } from '../ports';
+import { projectCustomerServiceFaq, faqSummary } from '../projections';
+
+export type CustomerServiceToolIds = 'customer-service-faq';
+
+const str = (desc: string) => z.string().describe(desc);
+const optionalStr = (desc: string) => z.string().optional().describe(desc);
+
+/** execute 第二参 → reqCtx（require 变体：缺失即 fail-visible 报错） */
+function reqCtxOf(execCtx: ToolExecContextLike): RequestContext {
+  return requireToolRequestContext(execCtx);
+}
+
+/** 宽松上下文：FAQ/知识库工具不依赖 mall scope——无 mall 时以空 scope 兜底（knowledge 不查 mall）。
+ * 保持无 subjectId（FAQ 域无主体语义），故用 mallScopeOrEmpty 原子而非 toMallQueryContext 组合子。 */
+function toLooseContext(reqCtx: RequestContext) {
+  return {
+    scope: mallScopeOrEmpty(reqCtx),
+    requestContext: reqCtx,
+  } as ShoppingQueryContext;
+}
+
+export function createCustomerServiceTools(_opts: { getCtx: () => ServerContext }) {
+  const exec = <T>(
+    fn: (
+      ports: CustomerServicePorts,
+      ctx: ServerContext,
+      args: Record<string, unknown>,
+      execCtx: ToolExecContextLike,
+    ) => Promise<T>,
+  ) => {
+    return async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const ctx = _opts.getCtx();
+      try {
+        return await fn(resolveCustomerServicePorts(reqCtxOf(execCtx), ctx), ctx, args, execCtx);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[customer-service] tool exec error: ${message}`);
+        return { found: false, message: '暂时无法查询，请稍后再试' } as unknown as T;
+      }
+    };
+  };
+
+  const customerServiceFaq = createTool({
+    id: 'customer-service-faq',
+    description:
+      '客服FAQ：搜索商场常见问题知识（服务政策、会员积分、停车、设施、办事指引等）。命中返回知识条目（作答素材——据此直接作答，重点信息用 **加粗**，步骤类内容分点列出）；无结果返回 summary 未命中说明（正文如实告知，不出卡）。',
+    inputSchema: z.object({
+      query: str('用户问题'),
+      topK: optionalStr('返回条数（字符串，1-5，缺省 3）'),
+    }),
+    execute: exec(async (ports, _ctx, args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      // 入参合法才 clamp（1-5）；缺省/非法 → undefined，由 adapter 侧 cfg.topK ?? 3 兜底（配置生效链）
+      const n = Number(args.topK);
+      const topK = Number.isFinite(n) && n >= 1 ? Math.min(5, n) : undefined;
+      const faqs = await ports.customerService.searchFaq(toLooseContext(reqCtxOf(execCtx)), String(args.query), topK);
+      const data = projectCustomerServiceFaq(
+        String(args.query),
+        faqs,
+        faqs.length === 0 ? '未找到相关常见问题，请尝试人工客服。' : undefined,
+        currentContactPhone(reqCtxOf(execCtx), _opts.getCtx()),
+      );
+      // FAQ 召回结果作为事实注入 summary 供模型流式回复；命中/未命中均零出卡（2026-09-02
+      // 联系客服引导卡下线）——客服域出卡面归零，未命中转人工由正文话术承接（noResultsReason
+      // 仍进 summary 供模型转述，contactPhone 保留作数据面）。
+      return { summary: faqSummary(data) };
+    }),
+  });
+
+  // 客服域零出卡：不挂 withCardEmissionHint（description 不预告出卡——工具契约与预告知句一致）
+  return {
+    customerServiceFaq,
+  } as const;
+}
+
+export type CustomerServiceTools = ReturnType<typeof createCustomerServiceTools>;
+export type CustomerServiceTool = CustomerServiceTools[keyof CustomerServiceTools];

package/tbox.module.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "name": "module-customer-service",
+  "version": "0.1.0",
+  "kind": "business",
+  "risk": {
+    "level": "low",
+    "writeBoundary": "source"
+  },
+  "distribution": {
+    "defaultMode": "codegen"
+  },
+  "contributes": {
+    "handlers": [],
+    "tools": [
+      "customer-service-faq"
+    ],
+    "cards": [
+      {
+        "cardType": "customer-service-faq",
+        "schemaVersion": 1
+      }
+    ],
+    "routes": [],
+    "pages": [],
+    "tabs": [],
+    "actions": [],
+    "resources": [
+      {
+        "id": "customer-service-faq-kb",
+        "type": "knowledge"
+      },
+      {
+        "id": "knowledge-assistance-kb",
+        "type": "knowledge"
+      }
+    ]
+  },
+  "dependencies": {
+    "modules": [
+      {
+        "id": "contracts-mall",
+        "required": true
+      }
+    ]
+  },
+  "env": []
+}

package/tests/cards-render.test.tsx

@@ -0,0 +1,77 @@
+/**
+ * module-customer-service 客户端卡片渲染测试（happy-dom）。
+ * 覆盖：FAQ 手风琴单展开 / referenceUrl 外链历史态放行（静态外链） / 空态 / 拨打客服。
+ * （自 module-shopping-guide tests/cards-render.test.tsx 迁入，2026-08-31 客服拆分）
+ */
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { CustomerServiceFaqCard } from '../src/client/cards';
+
+vi.mock('@tbox.cn/app-sdk/client', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@tbox.cn/app-sdk/client')>();
+  return { ...mod, sendCardAction: vi.fn() };
+});
+
+const mountedRoots = new Set<ReturnType<typeof createRoot>>();
+
+afterEach(() => {
+  for (const root of mountedRoots) {
+    act(() => root.unmount());
+  }
+  mountedRoots.clear();
+  document.body.innerHTML = '';
+});
+
+function render(ui: React.ReactElement) {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(ui);
+  });
+  mountedRoots.add(root);
+  return { host, root };
+}
+
+describe('CustomerServiceFaqCard 手风琴', () => {
+  const faqData = {
+    query: '发票',
+    faqs: [
+      { question: 'Q1', answer: 'A1', relevanceScore: 0.9 },
+      { question: 'Q2', answer: 'A2', relevanceScore: 0.8, referenceUrl: 'https://example.com/x' },
+    ],
+  };
+
+  it('默认展开第 0 条，点击切换单展开', () => {
+    const { host } = render(<CustomerServiceFaqCard data={faqData as never} cardId="c1" isHistory={false} />);
+    const answers = host.querySelectorAll('.cs-faq-item__a');
+    expect(answers.length).toBe(1);
+    const qs = host.querySelectorAll('.cs-faq-item__q');
+    act(() => (qs[1] as HTMLButtonElement).click());
+    expect(host.querySelectorAll('.cs-faq-item__a').length).toBe(1);
+    expect(host.querySelector('.cs-faq-item__a')!.textContent).toContain('A2');
+  });
+
+  it('referenceUrl 渲染「查看来源」外链，历史态仍可点（静态外链放行）', () => {
+    const { host } = render(<CustomerServiceFaqCard data={faqData as never} cardId="c1" isHistory={true} />);
+    const qs = host.querySelectorAll('.cs-faq-item__q');
+    act(() => (qs[1] as HTMLButtonElement).click());
+    const ref = host.querySelector('.cs-faq-item__ref') as HTMLButtonElement;
+    expect(ref).not.toBeNull();
+    expect(ref.disabled).toBe(false);
+  });
+
+  it('空态渲染 noResultsReason；contactPhone 渲染拨打客服', () => {
+    const { host } = render(
+      <CustomerServiceFaqCard data={{ query: 'q', faqs: [], noResultsReason: '未找到相关常见问题' } as never} cardId="c1" isHistory={false} />,
+    );
+    expect(host.querySelector('.cs-empty')!.textContent).toContain('未找到');
+
+    const { host: host2 } = render(
+      <CustomerServiceFaqCard data={{ query: 'q', faqs: faqData.faqs, contactPhone: '0571-88888888' } as never} cardId="c1" isHistory={false} />,
+    );
+    expect(host2.querySelector('.cs-contact-btn')!.textContent).toContain('0571-88888888');
+  });
+});

package/tests/config-merge.test.ts

@@ -0,0 +1,50 @@
+/**
+ * 客服承接资源配置取用语义（integrations v5：app-config 服务 = 模块资源 resolver）。
+ * - 资源在场 → 透传（ref 展开已在 resolver 构造期完成，消费端恒见 ResolvedResource）；
+ * - 缺服务/缺资源键 → 占位等值回退（离线零行为变化；哨兵值与 smoke R1 判定共用）。
+ * （遗留 shim 资源级合并 2 例已随 shopping-guide 迁移退役——2026-09-10 单文件真源同批。）
+ */
+import { describe, expect, it } from 'vitest';
+import type { ServerContext, ModuleResourceResolver, ResolvedResource } from '@tbox.cn/app-sdk/server';
+import { resolveAssistanceConfig } from '../src/server/ports';
+
+const fakeCtx = (resolver: ModuleResourceResolver | undefined): ServerContext =>
+  ({
+    services: { resolve: (key: string) => (key === 'app-config' ? resolver : undefined) },
+    logger: undefined,
+  }) as unknown as ServerContext;
+
+const MODULE_ID = 'module-customer-service';
+
+describe('resolveAssistanceConfig 资源取用（v5 modules 节）', () => {
+  it('app-config 未注册 → 占位回退（faq/mall-knowledge）', () => {
+    const config = resolveAssistanceConfig(fakeCtx(undefined), '1000770');
+    expect(config.faq).toEqual({ type: 'knowledge', datasetId: 'faq' });
+    expect(config.knowledge).toEqual({ type: 'knowledge', datasetId: 'mall-knowledge' });
+  });
+
+  it('资源缺席（resolver 返回 {}）→ 占位回退', () => {
+    const resolver: ModuleResourceResolver = () => ({});
+    const config = resolveAssistanceConfig(fakeCtx(resolver), '1000770');
+    expect(config.faq).toEqual({ type: 'knowledge', datasetId: 'faq' });
+    expect(config.knowledge).toEqual({ type: 'knowledge', datasetId: 'mall-knowledge' });
+  });
+
+  it('资源在场（含 topK/scoreThreshold）→ 透传', () => {
+    const faq: ResolvedResource = { type: 'knowledge', datasetId: 'real-faq', topK: 5, scoreThreshold: 0.5 };
+    const kb: ResolvedResource = { type: 'knowledge', datasetId: 'real-kb' };
+    const resolver: ModuleResourceResolver = (moduleId) =>
+      moduleId === MODULE_ID ? { 'customer-service-faq-kb': faq, 'knowledge-assistance-kb': kb } : {};
+    const config = resolveAssistanceConfig(fakeCtx(resolver), '1000770');
+    expect(config.faq).toEqual(faq);
+    expect(config.knowledge).toEqual(kb);
+  });
+
+  it('resolver 以 install id 键控（其他 moduleId 查询不串扰）', () => {
+    const resolver: ModuleResourceResolver = (moduleId) =>
+      moduleId === MODULE_ID ? { 'customer-service-faq-kb': { type: 'knowledge', datasetId: 'real-faq' } } : {};
+    const config = resolveAssistanceConfig(fakeCtx(resolver), undefined);
+    expect(config.faq.datasetId).toBe('real-faq');
+    expect(config.knowledge.datasetId).toBe('mall-knowledge'); // 缺键回退
+  });
+});

package/tests/customer-service.test.ts

@@ -0,0 +1,136 @@
+/**
+ * 客服承接模块单测：FAQ 工具出参形态（命中/无召回均 summary 零出卡——2026-09-02
+ * 联系客服引导卡下线）、faqPreTool decide 操作型收窄、本地知识库 adapter 配置注入、
+ * 投影 contactPhone。
+ */
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { createServerContext, createToolExecContext } from '@tbox.cn/app-sdk/server';
+import { createCustomerServiceTools } from '../src/server/tools';
+import { KnowledgeSearchAdapter, EmptyCustomerServiceAdapter } from '../src/server/ports/local-adapters';
+import { projectCustomerServiceFaq } from '../src/server/projections';
+
+const testRequestContext = (userId = 'u_1') => ({
+  identity: { userId, source: 'dev' as const },
+  attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } },
+});
+
+describe('customer-service-faq 工具', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // FAQ 命中路径的映射断言在 KnowledgeSearchAdapter 用例覆盖（工具内 knowledge client
+  // 构造依赖平台凭据，命中形态不可离线确定性——无召回分支走 Empty 降级恒可断言）。
+
+  it('FAQ 无召回：零出卡（仅 summary，含 noResultsReason 供正文转述）', async () => {
+    const ctx = createServerContext();
+    const tools = createCustomerServiceTools({ getCtx: () => ctx });
+    const result = (await tools.customerServiceFaq.execute!(
+      { query: '完全不相关的问题xyz' },
+      createToolExecContext(testRequestContext()) as never,
+    )) as { summary: string; cards?: unknown };
+
+    expect(result.cards).toBeUndefined();
+    expect(typeof result.summary).toBe('string');
+    expect(result.summary.length).toBeGreaterThan(0);
+  });
+});
+
+describe('faqPreTool decide：v3 三层门控（政策 run → 操作 skip → 默认 run）', async () => {
+  // decide 是模块内闭包（非导出）——经 serverModule 声明取回判定函数
+  const { serverModule } = await import('../src/server/index');
+  const decide = (serverModule.preTools!['customer-service-faq']!).decide;
+
+  it('操作型诉求（缴纳/我的/余额/进度）→ skip', async () => {
+    for (const text of ['帮我缴纳停车费', '我的停车费是多少', '我的积分余额还有多少', '退款申请进度']) {
+      const d = (await decide!({ text })) as { decision: string; reason?: string };
+      expect(d.decision, text).toBe('skip');
+      expect(d.reason).toContain('操作型');
+    }
+  });
+
+  it('政策型信号优先于操作型子串共存（"停车缴费规则"含"缴费"仍 run）', async () => {
+    for (const text of ['停车缴费规则是什么', '退货政策', '会员权益有哪些', '发票办理条件和流程']) {
+      const d = (await decide!({ text })) as { decision: string; args?: { query: string; topK: string } };
+      expect(d.decision, text).toBe('run');
+      expect(d.args!.query).toBe(text);
+      expect(d.args!.topK).toBe('3');
+    }
+  });
+
+  it('无信号词默认 run（宁多勿漏——FAQ 检索轻量空返无害）', async () => {
+    for (const text of ['积分相关咨询', '你好', '电影院能带外食吗', '宠物能进吗']) {
+      const d = (await decide!({ text })) as { decision: string };
+      expect(d.decision, text).toBe('run');
+    }
+  });
+
+  it('空文本 → skip（回归）', async () => {
+    const d = (await decide!({ text: '   ' })) as { decision: string; reason?: string };
+    expect(d.decision).toBe('skip');
+    expect(d.reason).toBe('空文本');
+  });
+});
+
+describe('KnowledgeSearchAdapter：配置注入', () => {
+  it('datasetId/topK/scoreThreshold 按配置透传（faq/knowledge 各自键）', async () => {
+    const search = vi.fn(async () => [
+      { content: JSON.stringify({ question: '如何开发票', answer: '1F 服务台' }), score: 0.92, originFileName: 'invoice.md' },
+    ]);
+    const adapter = new KnowledgeSearchAdapter({ search } as never, {
+      faq: { datasetId: 'faq-real', topK: 4, scoreThreshold: 0.5 },
+      knowledge: { datasetId: 'kb-real', topK: 2 },
+    });
+    const faqs = await adapter.searchFaq({ scope: { miniAppId: '', mallId: '' } } as never, '怎么开发票');
+    expect(search).toHaveBeenCalledWith(expect.objectContaining({ datasetId: 'faq-real', topK: 4, scoreThreshold: 0.5 }));
+    expect(faqs[0]).toMatchObject({ question: '如何开发票', answer: '1F 服务台', category: 'invoice.md', relevanceScore: 0.92 });
+  });
+
+  it('非 JSON 文档 → 摘要路径（summarize 截断 320）', async () => {
+    const long = '政策'.repeat(400);
+    const search = vi.fn(async () => [{ content: `# 政策说明\n${long}`, score: 0.8 }]);
+    const adapter = new KnowledgeSearchAdapter({ search } as never, {
+      faq: { datasetId: 'faq' },
+      knowledge: { datasetId: 'kb' },
+    });
+    const faqs = await adapter.searchFaq({ scope: { miniAppId: '', mallId: '' } } as never, 'q');
+    expect(faqs[0]!.answer.length).toBeLessThanOrEqual(320);
+  });
+});
+
+describe('EmptyCustomerServiceAdapter：未配置降级', () => {
+  it('searchFaq/searchKnowledge 恒空', async () => {
+    const adapter = new EmptyCustomerServiceAdapter();
+    expect(await adapter.searchFaq({} as never, 'q')).toHaveLength(0);
+    expect(await adapter.searchKnowledge({} as never, 'q')).toHaveLength(0);
+  });
+});
+
+describe('projectCustomerServiceFaq', () => {
+  it('contactPhone 注入（缺省不渲染由组件层保证）', () => {
+    const withPhone = projectCustomerServiceFaq('q', [], undefined, '0571-88888888');
+    expect(withPhone.contactPhone).toBe('0571-88888888');
+    const without = projectCustomerServiceFaq('q', []);
+    expect(without.contactPhone).toBeUndefined();
+  });
+});
+
+describe('faqPreTool routing：词表对齐客服承接面（2026-09-02 扩充回归锁）', async () => {
+  const { selectPreTools } = await import('@tbox.cn/app-sdk/server');
+  const { serverModule: csModule } = await import('../src/server/index');
+  const faqDef = csModule.preTools!['customer-service-faq']!;
+
+  it('营业时间/投诉/客服类问句命中 routing（此前缺口：商场几点开门）', () => {
+    for (const text of ['商场几点开门', '营业时间到几点', '我要投诉', '找客服', '开发票']) {
+      const hit = selectPreTools(text, [faqDef]);
+      expect(hit.map((d) => d.tool.id), text).toContain('customer-service-faq');
+    }
+  });
+
+  it('操作型问句（缴纳停车费）routing 命中但 decide skip——分层语义不回归', async () => {
+    const hit = selectPreTools('帮我缴纳停车费', [faqDef]);
+    expect(hit.map((d) => d.tool.id)).toContain('customer-service-faq');
+    const d = (await faqDef.decide({ text: '帮我缴纳停车费' })) as { decision: string };
+    expect(d.decision).toBe('skip');
+  });
+});

package/tests/skill.test.ts

@@ -0,0 +1,48 @@
+/**
+ * 客服承接文件 skill 装配验收——loadModuleSkills 经 workspace link 解析包根 skills/，
+ * 声明式通道填回 serverModule.skills；routingTerms 与导购域不相交（政策词归客服域）。
+ */
+import { describe, expect, it } from 'vitest';
+import { serverModule } from '../src/server/index';
+
+type LoadedSkill = { name: string; description: string; routingTerms: string[]; instructions: string };
+
+describe('customer-service skills 装配', () => {
+  const skills = ((serverModule as { skills?: Record<string, LoadedSkill> }).skills ?? {});
+
+  it('skills 含 customer-service（frontmatter name + 目录名一致）', () => {
+    expect(Object.keys(skills)).toContain('customer-service');
+    expect(skills['customer-service']!.description.length).toBeGreaterThan(0);
+    expect(skills['customer-service']!.instructions).toContain('客服');
+  });
+
+  it('routingTerms 域内词齐备且不含导购词（门店/楼层归导购域）', () => {
+    expect(skills['customer-service']!.routingTerms).toEqual([
+      '客服',
+      '退换货',
+      '退货',
+      '退款',
+      '售后',
+      '发票',
+      '投诉',
+      '服务政策',
+      '营业时间',
+      '开门',
+      '关门',
+      '开闭店',
+    ]);
+    expect(skills['customer-service']!.routingTerms.some((t) => t.includes('门店') || t.includes('楼层'))).toBe(false);
+  });
+
+  it('SOP 含承接链与跨域直调（单轮单 skill 注入下的自含协作）', () => {
+    expect(skills['customer-service']!.instructions).toContain('客服域零出卡');
+    expect(skills['customer-service']!.instructions).toContain('customer-service-faq');
+    expect(skills['customer-service']!.instructions).toContain('queryParkingFee');
+    expect(skills['customer-service']!.instructions).toContain('queryPoints');
+  });
+
+  it('SOP 含商场基础信息场景（营业时间不编造：无收录正文如实说明）', () => {
+    expect(skills['customer-service']!.instructions).toContain('商场基础信息');
+    expect(skills['customer-service']!.instructions).toContain('不按常识编造营业时间');
+  });
+});