@faapi/faapi 3.1.0 → 3.2.1

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 配置文件类型
@@ -582,17 +607,28 @@ interface WsContext {
 type WsHandler = (ctx: WsContext) => WsEventHandlers | void;
 
 /**
- * 清理所有 Program 缓存（watch 模式下文件变化时调用）
+ * 清理所有 Program 缓存 + tsconfig 解析缓存（watch 模式下文件变化时调用）
  *
  * 全量清理而非增量清理，理由：
  * - 简单可靠，无状态一致性问题
  * - 跨文件类型引用需要所有文件的 Program 同步更新
+ * - tsconfig 可能变化，需重新读取
  * - dev 模式文件量有限，全量重建在百毫秒级
  */
 declare function invalidateProgramCache(): void;
 /**
  * 为指定文件创建 TypeScript Program（带缓存）
  *
+ * 从 filePath 向上查找最近的 tsconfig.json：
+ * - 找到：用 ts.parseJsonConfigFileContent 解析，取 module / moduleResolution
+ *   覆盖默认值，同时取 parsed.fileNames 作为 program 的 rootNames（让跨文件
+ *   import 的源文件被加载进 program）
+ * - 找不到（如 os.tmpdir() 测试场景）：回退到默认 NodeNext，rootNames 仅包含 filePath
+ *
+ * 加载全部相关文件保证 `resolveTypeReference` 的兜底遍历（找同名声明）能成功，
+ * 修复业务项目用 `moduleResolution: Bundler` + 无扩展名相对导入时跨文件
+ * `import type` 解析失败的问题。
+ *
  * @param filePath 要分析的 .ts 文件绝对路径
  */
 declare function createProgram(filePath: string): ts.Program;
@@ -967,9 +1003,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 +1022,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 +1064,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 +1079,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` 函数