@faapi/faapi 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -322,6 +322,31 @@ interface AgentConfig {
      * 默认值由 Phase 3.x 的 @faapi/agent 插件定义（如 3）。
      */
     maxAgentDepth?: number;
+    /**
+     * 启用 tracing 的全局默认值（默认 true）
+     *
+     * 开启时 `agent.run()` / `agent.stream()` 返回的 `result.trace` /
+     * `chunk.traceEvent` 填充结构化调用明细（按轮次组织的 LLM 调用、tool 调用、
+     * sub-agent 嵌套调用事件,含 timing 与 token 用量）。
+     *
+     * 三层覆盖优先级：`AgentRunOptions.enableTracing` > agent 自身配置 >
+     * 此全局配置 > 默认 `true`。
+     *
+     * 业务方在生产主路径（高 QPS 端点）显式设 `false` 关闭以零开销运行：
+     *
+     * ```ts
+     * import type { FaapiConfig } from '@faapi/faapi';
+     * export default {
+     *   agent: {
+     *     enableTracing: false,
+     *     llms: { openai: { provider: 'openai', apiKey: '...', models: { 'gpt-4o': {} } } },
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     *
+     * 详见 `@faapi/agent` 的 [trace](../../agent/src/trace.md) 文档。
+     */
+    enableTracing?: boolean;
 }
 /**
  * faapi 配置文件类型
@@ -967,9 +992,9 @@ interface ToolPathMeta {
  * 返回 [AgentCore](../ast/extractAgentMetadata.md) 字段(name / description /
  * systemPrompt / tools / agents / model / maxTurns),**不含** `filePath` / `hasRun`。
  *
- * skill fallback:先查 [skillRegistry](./skillRegistry.ts) 的 `getSkill`,
- * 命中返回 skill 元数据(运行时业务方动态注册的 DB-driven skill);
- * 未命中查文件 registry。
+ * 仅查文件 registry（编译期 `faapi-agents.js` 产物来源）。**不 fallback 到
+ * [skillRegistry](./skillRegistry.ts)**——skill 与 agent 职责正交不耦合,
+ * skill 由业务方 plugin 内部使用,不参与 agent 查询链路。
  *
  * 用于 LLM-facing 场景(`agents` 参数注入、`asTool` 描述、
  * `resolveAgentTools` / `resolveSubAgents` 解析)。
@@ -986,11 +1011,10 @@ declare function getAgent(name: string): AgentCore | undefined;
  * 额外含 `filePath` / `hasRun`,供 `@faapi/agent` 子包 `loadAgentModule`
  * 加载 handler.js 执行自定义 `run` 函数。
  *
- * **不 fallback 到 skillRegistry**——DB skill 无源文件,不走 `loadAgentModule`。
  * 调用方需先判断 `entry?.hasRun` 再决定是否加载 handler.js。
  *
  * @param name agent 名
- * @returns `AgentMetadata` 或 `undefined`（未注册 / DB skill 无文件）
+ * @returns `AgentMetadata` 或 `undefined`（未注册）
  */
 declare function getAgentEntry(name: string): AgentMetadata | undefined;
 /**
@@ -1029,9 +1053,7 @@ interface AgentToolDescriptor {
  *
  * agent 必须显式声明用哪些 tool，显式优于隐式。
  *
- * skill fallback:通过 [getAgent](#getAgent) 自动发现 DB-driven skill,
- * skill 的 `tools` 字段同样会被解析。DB skill 引用的 tool 必须在 toolRegistry
- * 注册（文件型 tool 或未来 DB-driven tool）。
+ * 通过 [getAgent](#getAgent) 查询文件型 agent,不 fallback 到 skillRegistry。
  *
  * `tools` 中未在 toolRegistry 找到的 tool 名静默跳过（tool 可选可用，不强制存在）。
  *
@@ -1046,10 +1068,10 @@ declare function resolveAgentTools(name: string): ToolMetadata[];
  * 解析 agent 可调用的子 agent 集合
  *
  * 读 `agent.agents` 字段（[extractAgentMetadata](../ast/extractAgentMetadata.md)
- * 提取的 `config.agents` 字面量列表），按名查找已注册 agent。
+ * 提取的 `config.agents` 字面量列表），按名查找已注册文件型 agent。
  *
- * skill fallback:通过 [getAgent](#getAgent) 自动发现 DB-driven skill。
- * 父 agent 可以在 `agents` 列表里引用 DB skill 名,递归调用走相同链路。
+ * 不 fallback 到 skillRegistry——skill 不参与 sub-agent 递归,
+ * 父 agent 的 `agents` 列表只能引用文件型 agent 名。
  *
  * 返回 `AgentCore[]`(LLM-facing 字段,供 `@faapi/agent` 子包包装为
  * `AgentToolDescriptor` 发给 LLM)。加载 sub-agent handler.js 执行 `run` 函数

package/dist/index.js

@@ -1350,53 +1350,27 @@ function getTool(name) {
   return registry.get(name);
 }
 
-// src/injection/skillRegistry.ts
-var registry2 = /* @__PURE__ */ new Map();
-function hydrateSkillRegistry(skills) {
-  const next = /* @__PURE__ */ new Map();
-  for (const skill of skills) {
-    next.set(skill.name, skill);
-  }
-  registry2 = next;
-}
-function clearSkillRegistry() {
-  registry2 = /* @__PURE__ */ new Map();
-}
-function upsertSkill(core) {
-  registry2.set(core.name, core);
-}
-function removeSkill(name) {
-  registry2.delete(name);
-}
-function getSkill(name) {
-  return registry2.get(name);
-}
-function listSkills() {
-  return Array.from(registry2.values());
-}
-
 // src/injection/agentRegistry.ts
-var registry3 = /* @__PURE__ */ new Map();
+var registry2 = /* @__PURE__ */ new Map();
 function hydrateAgentRegistry(agents) {
   const next = /* @__PURE__ */ new Map();
   for (const agent of agents) {
     next.set(agent.name, agent);
   }
-  registry3 = next;
+  registry2 = next;
 }
 function clearAgentRegistry() {
-  registry3 = /* @__PURE__ */ new Map();
+  registry2 = /* @__PURE__ */ new Map();
 }
 function getAgent(name) {
-  return getSkill(name) ?? registry3.get(name);
+  return registry2.get(name);
 }
 function getAgentEntry(name) {
-  return registry3.get(name);
+  return registry2.get(name);
 }
 function listAgents() {
   const merged = /* @__PURE__ */ new Map();
-  for (const agent of registry3.values()) merged.set(agent.name, agent);
-  for (const skill of listSkills()) merged.set(skill.name, skill);
+  for (const agent of registry2.values()) merged.set(agent.name, agent);
   return Array.from(merged.values());
 }
 function resolveAgentTools(name) {
@@ -1422,6 +1396,31 @@ function resolveSubAgents(name) {
   return result;
 }
 
+// src/injection/skillRegistry.ts
+var registry3 = /* @__PURE__ */ new Map();
+function hydrateSkillRegistry(skills) {
+  const next = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    next.set(skill.name, skill);
+  }
+  registry3 = next;
+}
+function clearSkillRegistry() {
+  registry3 = /* @__PURE__ */ new Map();
+}
+function upsertSkill(core) {
+  registry3.set(core.name, core);
+}
+function removeSkill(name) {
+  registry3.delete(name);
+}
+function getSkill(name) {
+  return registry3.get(name);
+}
+function listSkills() {
+  return Array.from(registry3.values());
+}
+
 // src/loader/loadAgentModule.ts
 import fs6 from "fs";