@tbox.cn/app-template-agent 0.1.0 → 0.7.4

package/apps/server/tests/deployment-loader.test.ts

@@ -0,0 +1,140 @@
+/**
+ * integrations v4 装载链单测（deployment 派生自 integrations——单文件真源；base 精简面）。
+ * 覆盖：投影穿透（attributes 存活）/ 无参考表 → 空平面 + defaultInstanceId 独立在场 /
+ * stale 防线 / buildDefaultMallContext mallId-only 注入 / deploymentFromIntegrations 装配活性。
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+import { loadIntegrations, assertNoStaleDeploymentControlPlane } from '../src/config/integration.js';
+import { deploymentFromIntegrations, buildDefaultMallContext } from '../src/config/deployment.js';
+
+const dir = mkdtempSync(join(tmpdir(), 'tbox-deploy-loader-'));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+function writeConfig(name: string, data: unknown): string {
+  const p = join(dir, name);
+  writeFileSync(p, JSON.stringify(data));
+  return p;
+}
+
+const fullIntegrations = {
+  provider: 'acme',
+  instances: [
+    {
+      id: 'mall-demo',
+      name: '示例商场',
+      attributes: {
+        miniAppId: 'demo-app',
+        contactPhone: '0571-88888888',
+        location: { lat: 30.2741, lon: 120.1551, address: '湖滨示范点' },
+      },
+    },
+  ],
+  defaultInstanceId: 'mall-demo',
+  services: { 'member.account': {} },
+};
+
+describe('loadIntegrations：投影穿透', () => {
+  it('contactPhone/location/miniAppId 经投影存活到 controlPlane（不被 zod strip）', () => {
+    const loaded = loadIntegrations(writeConfig('full.json', fullIntegrations));
+    expect(loaded?.controlPlane.malls[0]).toMatchObject({
+      mallId: 'mall-demo',
+      name: '示例商场',
+      miniAppId: 'demo-app',
+      contactPhone: '0571-88888888',
+      location: { lat: 30.2741, lon: 120.1551, address: '湖滨示范点' },
+    });
+    expect(loaded?.controlPlane.defaultMallId).toBe('mall-demo');
+  });
+
+  it('拼错 attributes 键 → fail-fast（strict——报错含实例 id 与允许键清单）', () => {
+    const p = writeConfig('typo-attr.json', {
+      instances: [{ id: 'm1', name: 'x', attributes: { miniAppid: 'typo' } }],
+      services: {},
+    });
+    expect(() => loadIntegrations(p)).toThrow(/m1.*允许键|允许键.*miniAppId/s);
+  });
+
+  it('无参考表 → 空平面；defaultInstanceId 独立在场 = 动态默认（env 注入形态）', () => {
+    const loaded = loadIntegrations(writeConfig('no-table.json', { provider: 'globex', defaultInstanceId: '42020300520', services: {} }));
+    expect(loaded?.controlPlane.malls).toEqual([]);
+    expect(loaded?.controlPlane.defaultMallId).toBe('42020300520');
+  });
+
+  it('defaultInstanceId 占位 ${DEFAULT_MALL_ID} → 展开后载入；缺 env fail-fast', () => {
+    const p = writeConfig('env-placeholder.json', { defaultInstanceId: '${DEFAULT_MALL_ID}', services: {} });
+    const saved = process.env.DEFAULT_MALL_ID;
+    process.env.DEFAULT_MALL_ID = '1102588';
+    try {
+      expect(loadIntegrations(p)?.controlPlane.defaultMallId).toBe('1102588');
+      delete process.env.DEFAULT_MALL_ID;
+      expect(() => loadIntegrations(p)).toThrow(/DEFAULT_MALL_ID/);
+    } finally {
+      if (saved === undefined) delete process.env.DEFAULT_MALL_ID;
+      else process.env.DEFAULT_MALL_ID = saved;
+    }
+  });
+});
+
+describe('stale 防线（v4：deployments/development.json 含 malls → error 迁移指引）', () => {
+  function writeStaleRoot(name: string, stale: unknown): string {
+    const root = mkdtempSync(join(tmpdir(), `tbox-stale-${name}-`));
+    mkdirSync(join(root, 'config', 'deployments'), { recursive: true });
+    writeFileSync(join(root, 'config', 'deployments', 'development.json'), JSON.stringify(stale));
+    return root;
+  }
+
+  it('mall 家族形态（含 malls 键）→ throw 迁移指引', () => {
+    const root = writeStaleRoot('mall', { malls: [{ mallId: 'm', name: 'n' }], defaultMallId: 'm' });
+    try {
+      expect(() => assertNoStaleDeploymentControlPlane(root)).toThrow(/已并入 config\/integrations\.json/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('非 mall 形态（不含 malls 键）→ 不阻断（support 独立体系零触碰——G1）', () => {
+    const root = writeStaleRoot('other', { someOtherKey: 1 });
+    try {
+      expect(() => assertNoStaleDeploymentControlPlane(root)).not.toThrow();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('buildDefaultMallContext：v4 mallId-only 注入', () => {
+  it('defaultMallId + miniAppId 齐备 → 拼装完整 context；root 优先', () => {
+    const loaded = loadIntegrations(writeConfig('ctx-ok.json', fullIntegrations))!;
+    expect(buildDefaultMallContext(loaded.controlPlane, 'root-app')).toEqual({
+      mall: { mallId: 'mall-demo', miniAppId: 'root-app' },
+    });
+    expect(buildDefaultMallContext(loaded.controlPlane)).toEqual({
+      mall: { mallId: 'mall-demo', miniAppId: 'demo-app' },
+    });
+  });
+
+  it('双缺 miniAppId → mallId-only 注入（v4：不再 warn-refuse 静默失效）', () => {
+    const loaded = loadIntegrations(writeConfig('ctx-nomini.json', { defaultInstanceId: 'm9', services: {} }))!;
+    expect(buildDefaultMallContext(loaded.controlPlane)).toEqual({ mall: { mallId: 'm9' } });
+  });
+
+  it('无 defaultMallId → undefined（不兜底）', () => {
+    const loaded = loadIntegrations(writeConfig('ctx-nodefault.json', { services: {} }))!;
+    expect(buildDefaultMallContext(loaded.controlPlane)).toBeUndefined();
+  });
+});
+
+describe('deploymentFromIntegrations：装配活性', () => {
+  it('assembly 三函数派生自投影控制平面', () => {
+    const loaded = loadIntegrations(writeConfig('asm.json', fullIntegrations))!;
+    const d = deploymentFromIntegrations(loaded);
+    expect(d.controlPlane).toBe(loaded.controlPlane);
+    expect(d.assembly.validateScope({ mall: { mallId: 'mall-demo' } })).toBe(true);
+    expect(d.assembly.validateScope({ mall: { miniAppId: 'a' } })).toBe(false);
+    expect(d.assembly.extractScopeKey({ identity: { userId: 'u', source: 'external' }, attributes: { mall: { mallId: 'mall-demo' } } })).toBe('mall-demo');
+    expect(d.assembly.buildScope({ mall: { mallId: 'mall-demo' } })).toEqual({ mallId: 'mall-demo' });
+  });
+});

package/apps/server/tests/intent-dispatcher.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { createServerContext } from '@tbox.cn/app-sdk/server';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { createAppIntentDispatcher } from '../src/intent-routes.js';
+
+/**
+ * 上下文统一化：意图分发契约锁——引擎 handlerDispatch 第三参 reqCtx 必须透传到
+ * HandlerRegistry.dispatch 第五参（handle 第四参）。断链 = 意图路径恒「缺少运行上下文」
+ * （typecheck 不可见：dispatcher 签名收窄即静默丢参）。
+ */
+describe('createAppIntentDispatcher reqCtx 透传（上下文统一化）', () => {
+  it('handler 第四参收到 dispatcher 第三参原对象（引用级透传）', async () => {
+    const ctx = createServerContext();
+    const reqCtx: RequestContext = {
+      identity: { userId: 'u_intent', source: 'local' },
+      conversationId: 'conv_intent',
+      attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } },
+    };
+    const seen: (RequestContext | undefined)[] = [];
+    ctx.handlers.register({
+      id: 'probe-handler',
+      async handle(_action, _payload, _ctx, received) {
+        seen.push(received);
+        return { cards: [], text: 'ok' };
+      },
+    });
+
+    const dispatch = createAppIntentDispatcher(ctx);
+    await dispatch(
+      { id: 'probe', keywords: ['探针'], handlerId: 'probe-handler', action: 'run' },
+      '探针',
+      reqCtx,
+    );
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toBe(reqCtx);
+  });
+
+  it('无 reqCtx（匿名缺省形态）→ handle 第四参 undefined（不伪造上下文）', async () => {
+    const ctx = createServerContext();
+    const seen: (RequestContext | undefined)[] = [];
+    ctx.handlers.register({
+      id: 'probe-handler',
+      async handle(_action, _payload, _ctx, received) {
+        seen.push(received);
+        return { cards: [], text: 'ok' };
+      },
+    });
+
+    const dispatch = createAppIntentDispatcher(ctx);
+    await dispatch(
+      { id: 'probe', keywords: ['探针'], handlerId: 'probe-handler', action: 'run' },
+      '探针',
+    );
+
+    expect(seen[0]).toBeUndefined();
+  });
+});

package/apps/server/tests/tool-runtime.test.ts

@@ -1,9 +1,16 @@
 import { describe, expect, it } from 'vitest';
-import { createServerContext, createSdkToolRuntime } from '@tbox.cn/app-sdk/server';
+import {
+  createServerContext,
+  createSdkToolRuntime,
+  createEngineFromContext,
+  createInMemoryMemoryStore,
+  resolveMemoryStore,
+} from '@tbox.cn/app-sdk/server';
 import { registerAll } from '../src/modules.js';
+import { translateTool } from '../src/tools/translate.js';
 
 describe('tool runtime 宿主装配（自注册闭环）', () => {
-  it('合并模块工具并用同一次加载结果创建卡片 resolver', async () => {
+  it('合并模块工具（v2：无 cardResolver——出卡由工具出参 cards 运行期声明）', async () => {
     const ctx = createServerContext();
     await registerAll(ctx);
 
@@ -14,27 +21,28 @@ describe('tool runtime 宿主装配（自注册闭环）', () => {
     expect(Object.keys(runtime.tools)).toEqual(
       expect.arrayContaining(['getWeather']),
     );
-    expect(runtime.cardResolver.issues).toEqual([]);
-    expect(
-      runtime.cardResolver.resolve('getWeather', {
-        city: '杭州',
-        temp: 28,
-        weather: '晴',
-        humidity: 60,
-      }),
-    ).toEqual({
-      status: 'ready',
-      cardType: 'weather',
-      data: {
-        city: '杭州',
-        temp: 28,
-        weather: '晴',
-        humidity: 60,
-      },
+  });
+
+  it('weather 参考实现：execute 出参携带 cards 声明（顶层答话事实 + cards 数组）', async () => {
+    const ctx = createServerContext();
+    await registerAll(ctx);
+
+    const runtime = await createSdkToolRuntime(ctx, {
+      loadPlugins: async () => ({ tools: {}, references: [] }),
     });
+    const weather = runtime.tools.getWeather as unknown as {
+      execute: (input: { city: string }, context: unknown) => Promise<Record<string, unknown>>;
+    };
+    const out = await weather.execute({ city: '杭州' }, {} as never);
+    // 顶层答话事实
+    expect(out).toMatchObject({ city: '杭州', temp: expect.any(Number), weather: expect.any(String) });
+    // cards 出卡声明（capture 前原始形态：data = 顶层事实本体，不含 cards 键自身）
+    // W7 note 契约：主体+关键事实（城市/天气/温度）
+    const { cards, ...facts } = out;
+    expect(cards).toEqual([{ cardType: 'weather', data: facts, note: `杭州 ${facts.weather} ${facts.temp}℃` }]);
   });
 
-  it('未注册的 tool 不出卡，仅作为模型上下文', async () => {
+  it('未注册的 tool 不进运行时工具集（仅作为模型上下文面之外）', async () => {
     const ctx = createServerContext();
     await registerAll(ctx);
 
@@ -42,8 +50,102 @@ describe('tool runtime 宿主装配（自注册闭环）', () => {
       loadPlugins: async () => ({ tools: {}, references: [] }),
     });
 
-    expect(runtime.cardResolver.resolve('notExistedTool', {})).toEqual({
-      status: 'unbound',
+    expect(runtime.tools.notExistedTool).toBeUndefined();
+  });
+
+  describe('translate 参数规范（D11：string 形态 + 工具内 normalize）', () => {
+    // mastra Tool.execute 为可选 + 双参签名（input, context）——测试经非空断言直调
+    const callExecute = (input: { text: string; targetLang?: string }) =>
+      translateTool.execute!(input, {} as never);
+
+    it('合法 targetLang（zh/en）→ 生效', async () => {
+      const r = await callExecute({ text: '你好', targetLang: 'en' });
+      expect(r).toMatchObject({ targetLang: 'en' });
+      const r2 = await callExecute({ text: 'hello', targetLang: 'zh' });
+      expect(r2).toMatchObject({ targetLang: 'zh' });
+    });
+
+    it('非法 targetLang → 回落自动检测（不抛）', async () => {
+      const r = await callExecute({ text: '你好', targetLang: 'fr' });
+      expect(r).toMatchObject({ targetLang: 'en' }); // 中文输入 → 自动检测回落英文
+      const r2 = await callExecute({ text: 'hello', targetLang: 'xx' });
+      expect(r2).toMatchObject({ targetLang: 'zh' }); // 英文输入 → 自动检测回落中文
+    });
+
+    it('缺省 targetLang → 自动检测', async () => {
+      const r = await callExecute({ text: '你好' });
+      expect(r).toMatchObject({ targetLang: 'en' });
+      const r2 = await callExecute({ text: 'hello' });
+      expect(r2).toMatchObject({ targetLang: 'zh' });
     });
   });
 });
+
+describe('长期记忆装配（017：默认 inmemory 开启 + off 逃生舱）', () => {
+  it('resolveMemoryStore 缺省 → inmemory（默认开启）', () => {
+    const m = resolveMemoryStore({});
+    expect(m.enabled).toBe(true);
+    expect(m.mode).toBe('inmemory');
+    expect(m.store).toBeDefined();
+    expect(m.store!.capabilities).toBeUndefined(); // 缺省全真
+  });
+
+  it('resolveMemoryStore off → 关闭（enabled=false）', () => {
+    const m = resolveMemoryStore({ store: 'off' });
+    expect(m.enabled).toBe(false);
+    expect(m.mode).toBe('off');
+    expect(m.store).toBeUndefined();
+  });
+
+  it('resolveMemoryStore knowledge 无 kbId → warn 回退 inmemory', () => {
+    const m = resolveMemoryStore({ store: 'knowledge' });
+    expect(m.enabled).toBe(true);
+    expect(m.mode).toBe('inmemory');
+  });
+
+  it('resolveMemoryStore knowledge 三件套齐备 → knowledge 模式（2026-09-01 翻转：caps 缺省全 true——平台已发布生产）', () => {
+    const m = resolveMemoryStore({ store: 'knowledge', kbId: 'kb-1', kbDocId: 'doc-1', apiKey: 'k' });
+    expect(m.mode).toBe('knowledge');
+    expect(m.store!.capabilities).toEqual({ save: true, search: true, list: true, delete: true });
+  });
+
+  it('resolveMemoryStore knowledge 缺 kbDocId → warn 回退 inmemory（三缺一）', () => {
+    const m = resolveMemoryStore({ store: 'knowledge', kbId: 'kb-1', apiKey: 'k' });
+    expect(m.mode).toBe('inmemory');
+  });
+
+  it('resolveMemoryStore 非法值 → warn 回退 inmemory', () => {
+    const m = resolveMemoryStore({ store: 'bogus' });
+    expect(m.mode).toBe('inmemory');
+  });
+
+  it('装配态（inmemory）→ 引擎装配链路无异常（chat 完成 + 本地 skills 不受影响）', async () => {
+    const ctx = createServerContext();
+    await registerAll(ctx);
+    const engine = await createEngineFromContext(ctx, {
+      instructions: 'test',
+      model: {} as never,
+      memory: { store: createInMemoryMemoryStore() },
+    });
+    // 触发一轮 chat 使装配链路完整执行（无 runCtx → 匿名 → 零 recall）
+    await engine.chat('t-mem', 'hi', () => {});
+    // 工具名断言在 SDK build-engine 测试覆盖；模板层断言装配链路无异常 + skills 面不受影响
+    expect(engine.listSkills().length).toBeGreaterThan(0);
+  });
+
+  it('off 态 → 引擎无记忆工具装配（零异常 + 零工具）', async () => {
+    const ctx = createServerContext();
+    await registerAll(ctx);
+    const m = resolveMemoryStore({ store: 'off' });
+    const engine = await createEngineFromContext(
+      ctx,
+      {
+        instructions: 'test',
+        model: {} as never,
+        ...(m.enabled && m.store ? { memory: { store: m.store } } : {}),
+      },
+    );
+    await engine.chat('t-mem-off', 'hi', () => {});
+    expect(m.enabled).toBe(false);
+  });
+});

package/apps/server/tsup.config.ts

@@ -9,14 +9,27 @@ export default defineConfig({
   clean: true,
   sourcemap: true,
   // 本地 workspace 源码包（exports 指向 src/*.ts，node 无法直接加载）必须内联：@app/*。
-  // @tbox.cn/{app-sdk,contracts,contracts-mall} 以发布态消费（dist 产物，node 可直载）→ external；
+  // @tbox.cn/{app-sdk,contracts} 以发布态消费（dist 产物，node 可直载）；codegen 平台包经 @app/* 内联；
   // 已发布 npm 的 @tbox.cn/agent-plugin（exports 指向 dist 产物）保持 external。
   noExternal: [/^@app\//],
+  // vite 不进 bundle 的结构防线：静态入口图（entry: index.ts → app.ts 链）任何 vite 引用
+  // （含 dev.ts 误入 entry）在 onResolve 即失败——dev 形态仅存在于 src/dev.ts（tsx 运行）。
+  esbuildPlugins: [
+    {
+      name: 'forbid-vite-in-bundle',
+      setup(build) {
+        build.onResolve({ filter: /^vite(\/|$)/ }, () => ({
+          errors: [
+            { text: 'vite 禁止进入 server bundle：dev 形态走 src/dev.ts（仅 tsx），禁入 tsup entry' },
+          ],
+        }));
+      },
+    },
+  ],
   // 确保不打包 node 内置模块
   external: [
     'express',
     'cors',
-    'ws',
     'path',
     'url',
     'http',

package/config/chat.json

@@ -4,5 +4,8 @@
   "enableTTS": true,
   "enableVoiceInput": true,
   "defaultInputMode": "TEXT",
-  "quickCommands": []
+  "quickCommands": [
+    { "label": "找美食", "query": "帮我找商场里的美食" },
+    { "label": "会员积分", "query": "我的会员积分是多少" }
+  ]
 }

package/config/llm_provider.json

@@ -1,3 +1,5 @@
 {
-  "modelName": "glm-5.1"
+  "modelName": "glm-5.1",
+  "thinking": false,
+  "parallelToolCalls": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.1.0",
+  "version": "0.7.4",
   "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server + packages/module-*。客户端同时跑在浏览器与支付宝小程序 web-view 壳里。",
   "engines": {
     "node": ">=24.0.0 <25.0.0"
@@ -11,9 +11,11 @@
     "!apps/**/dist-ssr",
     "!apps/**/.vite",
     "!apps/**/node_modules",
+    "!apps/**/*.tsbuildinfo",
     "config",
     "packages",
     "!packages/**/node_modules",
+    "!packages/**/*.tsbuildinfo",
     "scripts",
     ".tbox",
     ".gitignore",
@@ -24,28 +26,34 @@
     "README.md",
     "eslint.config.mjs",
     "pnpm-workspace.template.yaml",
+    "pnpm-lock.template.yaml",
     "tsconfig.base.json",
     "LICENSE"
   ],
   "devDependencies": {
-    "eslint": "^9.0.0",
-    "typescript-eslint": "^8.57.2",
-    "eslint-plugin-react-hooks": "^5.2.0"
+    "@tbox.cn/app-sdk": "0.17.0",
+    "eslint": "9.39.5",
+    "typescript-eslint": "8.67.0",
+    "eslint-plugin-react-hooks": "5.2.0",
+    "vite": "6.4.3"
   },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "dev": "pnpm --filter @app/server dev",
-    "build": "pnpm check:workspace && pnpm --filter @app/server build && pnpm --filter @app/client build",
-    "typecheck": "pnpm -r --filter \"@app/*\" typecheck",
-    "test": "pnpm -r --filter \"@app/*\" test",
+    "dev": "pnpm --filter ./apps/server dev",
+    "build": "pnpm check && pnpm --filter ./apps/server build && pnpm --filter ./apps/client build",
+    "build:client": "pnpm check && pnpm --filter ./apps/client build",
+    "typecheck": "pnpm -r --filter \"./{apps,packages}/*\" typecheck",
+    "test": "pnpm -r --filter \"./{apps,packages}/*\" test",
     "lint": "eslint apps packages",
-    "verify": "pnpm typecheck && pnpm test && pnpm lint && pnpm build && pnpm verify:generated",
+    "verify": "pnpm typecheck && pnpm test && pnpm lint && pnpm build && pnpm verify:generated && pnpm check:inspector",
     "verify:generated": "node scripts/verify-generated.mjs",
+    "check": "pnpm check:workspace && pnpm check:inspector",
     "check:workspace": "node scripts/check-workspace.mjs",
-    "plugin:inspect": "pnpm --filter @app/server exec node --import tsx src/cli/plugin-inspect.ts",
-    "plugin:doctor": "pnpm --filter @app/server exec node --import tsx src/cli/plugin-doctor.ts"
+    "check:inspector": "tbox-inspector-check",
+    "plugin:inspect": "pnpm --filter ./apps/server exec node --import tsx src/cli/plugin-inspect.ts",
+    "plugin:doctor": "pnpm --filter ./apps/server exec node --import tsx src/cli/plugin-doctor.ts"
   }
 }

package/packages/contracts-mall/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@app/contracts-mall",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/runtime.ts"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "import": "./src/server/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@tbox.cn/app-contracts-mall": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  },
+  "tboxCodegenShim": true
+}

package/packages/contracts-mall/src/index.ts

@@ -0,0 +1 @@
+export * from '@tbox.cn/app-contracts-mall';

package/packages/contracts-mall/src/runtime.ts

@@ -0,0 +1 @@
+export * from '@tbox.cn/app-contracts-mall';

package/packages/contracts-mall/src/server/index.ts

@@ -0,0 +1 @@
+export * from '@tbox.cn/app-contracts-mall/server';

package/packages/contracts-mall/tsconfig.json

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

package/packages/module-weather/package.json

@@ -15,7 +15,8 @@
     "./client": {
       "types": "./src/client/index.ts",
       "import": "./src/client/index.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"
@@ -25,11 +26,11 @@
     "@tbox.cn/app-contracts": "catalog:"
   },
   "peerDependencies": {
-    "zod": "catalog:",
-    "react": "catalog:"
+    "zod": "3.25.76",
+    "react": "18.3.1"
   },
   "devDependencies": {
-    "@types/react": "catalog:",
-    "typescript": "catalog:"
+    "@types/react": "18.3.31",
+    "typescript": "5.9.3"
   }
 }

package/packages/module-weather/skills/weather-guide/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: weather-guide
+description: 天气查询与穿衣出行建议（调用 getWeather 真实数据）
+metadata:
+  routingTerms: [天气, 穿衣, 温度, 湿度, 出行]
+---
+## 适用意图
+用户询问天气、穿衣建议、出行准备（如"今天穿什么"）时使用本规范。
+
+## 调用工具
+必须调用 getWeather 工具查询真实天气（city 取用户提到的城市），禁止编造温度/天气数据。
+
+## 返回字段说明
+getWeather 返回：temp(温度℃)、weather(天气现象)、humidity(湿度%)。
+
+## 回答组织方式
+1. 先报城市与天气现象、温度、湿度
+2. 再给出穿衣/出行建议（结合温度与天气现象）
+3. 温度 <10℃ 提醒保暖，>30℃ 提醒防晒
+
+## 出卡规则
+getWeather 结果含天气卡：回复末尾另起一行输出 `<agent-ui-cards>` 引用本轮卡片 id，否则用户看不到卡。

package/packages/module-weather/skills/weather-guide/references/dressing-tips.md

@@ -0,0 +1,5 @@
+## 穿衣指数
+- 温度 <10℃：厚外套/羽绒服
+- 10~20℃：夹克/风衣
+- 20~30℃：单衣/薄外套
+- >30℃：短袖，注意防晒

package/packages/module-weather/src/server/cards/weather/meta.ts

@@ -13,7 +13,6 @@ export type WeatherCardData = z.infer<typeof dataSchema>;
 const meta: CardMeta<typeof dataSchema> = {
   cardType: 'weather',
   dataSchema,
-  allowedTools: ['getWeather'],
   displayName: '天气卡片',
   description: '展示某城市的天气数据，含温度、天气状况、湿度',
   sampleData: {

package/packages/module-weather/src/server/index.ts

@@ -1,6 +1,8 @@
 import { weatherTool } from './tool';
 import weatherMeta from './cards/weather/meta';
-import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import { loadModuleSkills } from '@tbox.cn/app-sdk/server';
+import type { LocalSkill, ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import { weatherPreTool } from './pre-tools';
 
 export { weatherTool, weatherMeta };
 
@@ -9,9 +11,33 @@ const cards = {
   weather: weatherMeta,
 } as const;
 
+/**
+ * 模块 skill 声明（009 模块文件化：SKILL.md 目录格式，文件即唯一源）。
+ * - 底层能力：SDK `loadModuleSkills(packageName, import.meta.url)` 单策略定位包根
+ *   （createRequire 包名解析：dev workspace link / 模块 dist / 应用 bundle dist / 发布态
+ *   node_modules 全形态恒命中；失败 warn 可行动 + 恒 resolve []）；
+ * - 顶层 await 加载 → 填回 serverModule.skills 声明式通道（装配端 registerAll 自动注册）；
+ * - 前置：本包 exports 须含 "./package.json"（见 package.json）；
+ * - 生成应用内（codegen 展开）调用名由 CLI 自动改写为 @app/<id>，源码按字面量包名写法。
+ */
+const skills = Object.fromEntries(
+  (await loadModuleSkills('@app/module-weather', import.meta.url)).map((s) => [s.name, s]),
+) satisfies Record<string, LocalSkill>;
+
+/**
+ * 模块前置工具声明（010：key 约定 = toolId，纯数据 + 一个 resolve 函数）。
+ * 装配端 registerServerModules 自动注册（register 内无需代码）。
+ */
+const preTools = {
+  getWeather: weatherPreTool,
+} as const;
+
 /** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
 export const serverModule = {
   cards,
+  skills,
+  preTools,
+  declaration: { moduleId: 'weather' },
   register(ctx: ServerContext): void {
     ctx.tools.register(weatherTool);
     ctx.cards.registerMap(cards);