@migor/agentia 0.4.2 → 0.6.0

package/dist/toolkit/prompt.d.ts

@@ -20,9 +20,29 @@ export interface PromptSpec {
     description: string;
     /** 模板化入参 schema；缺省空对象（无参资产） */
     schema?: JsonSchema;
+    /**
+     * 资产版本号（git hash / 'v3' 等）。装配时随能力名收集成 { 能力名: 版本 } 表，
+     * 每次 run 落到 run 根 span 的 `prompts.versions` attribute（engine 拼成 name@ver 逗号串）——
+     * 回答「质量退化是不是换了这个 prompt 资产导致的」。缺省（无版本）则该能力不进表。
+     */
+    version?: string;
 }
 /** 方法装饰器（实例或 static 均可）：登记 prompt spec。返回值 = 资产文本。 */
 export declare function Prompt(spec: PromptSpec): (value: Function, context: CapabilityDecoratorContext) => void;
+/** collectPromptEntries 的产物：菜单工具 + 带版本能力的 name→version 表（最终菜单名口径）。 */
+export interface CollectedPrompts {
+    tools: AgentTool[];
+    /** 带 version 的 @Prompt 的 { 最终菜单名: 版本 }；无版本能力不进表 */
+    versions: Record<string, string>;
+}
+/**
+ * 收集容器实例（+ 其类上的静态方法）里所有 @Prompt，产出 AgentTool[] 与版本表。
+ * 实例方法沿原型链（含继承）；静态方法同样沿构造函数原型链（含继承的父类静态 @Prompt）。
+ *
+ * collectPrompts 是公共面（只回 AgentTool[]，历史形状不动）；装配侧需要版本表，
+ * 故内核收两份 —— module 级 export，不进公共导出面（src/index.ts）。
+ */
+export declare function collectPromptEntries(instance: object): CollectedPrompts;
 /**
  * 收集容器实例（+ 其类上的静态方法）里所有 @Prompt，产出 AgentTool[]。
  * 实例方法沿原型链（含继承）；静态方法同样沿构造函数原型链（含继承的父类静态 @Prompt）。

package/dist/toolkit/prompt.js

@@ -13,14 +13,18 @@ export function Prompt(spec) {
     };
 }
 /**
- * 收集容器实例（+ 其类上的静态方法）里所有 @Prompt，产出 AgentTool[]。
+ * 收集容器实例（+ 其类上的静态方法）里所有 @Prompt，产出 AgentTool[] 与版本表。
  * 实例方法沿原型链（含继承）；静态方法同样沿构造函数原型链（含继承的父类静态 @Prompt）。
+ *
+ * collectPrompts 是公共面（只回 AgentTool[]，历史形状不动）；装配侧需要版本表，
+ * 故内核收两份 —— module 级 export，不进公共导出面（src/index.ts）。
  */
-export function collectPrompts(instance) {
+export function collectPromptEntries(instance) {
     const tools = [];
+    const versions = {};
     // null/undefined/原始值 provider（useValue 合法形态）：无装饰器能力可收，空结果
     if (!isScannableInstance(instance))
-        return tools;
+        return { tools, versions };
     // 传 key 而非捕获的 fn：子类「未装饰地 override」时 spec 继承自父类，
     // 但实现必须取**实例/类上**的（否则会绕开子类实现，与 @Tool 语义不一致）。
     const pushTool = (name, target, key, spec) => {
@@ -30,6 +34,9 @@ export function collectPrompts(instance) {
             inputSchema: spec.schema ?? EMPTY_SCHEMA,
             run: (input) => Reflect.apply(target[key], target, [input]),
         });
+        // 版本表以最终菜单名（capabilityName 校验后的 name）为键；缺省无版本不进表
+        if (spec.version !== undefined)
+            versions[spec.name ?? name] = spec.version;
     };
     // 实例方法（沿原型链）
     const found = scanDecoratedMethods(instance, promptSpecs);
@@ -59,6 +66,13 @@ export function collectPrompts(instance) {
         }
         ctor = Object.getPrototypeOf(ctor);
     }
-    return tools;
+    return { tools, versions };
+}
+/**
+ * 收集容器实例（+ 其类上的静态方法）里所有 @Prompt，产出 AgentTool[]。
+ * 实例方法沿原型链（含继承）；静态方法同样沿构造函数原型链（含继承的父类静态 @Prompt）。
+ */
+export function collectPrompts(instance) {
+    return collectPromptEntries(instance).tools;
 }
 //# sourceMappingURL=prompt.js.map

package/dist/toolkit/prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/toolkit/prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/toolkit/prompt.ts"],"names":[],"mappings":"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"}

package/dist/toolkit/skill.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilityDecoratorContext } from './collect.js';
-import type Anthropic from '@anthropic-ai/sdk';
+import type { MessageParam } from '../core/message.js';
 import type { AgentTool, JsonSchema } from '../core/tool.js';
 import type { AgentStopReason } from '../engine/types.js';
 import { SystemPrompt } from '../runtime/systemPrompt.js';
@@ -26,13 +26,13 @@ export interface SkillSpec {
     model?: string;
     maxTokens?: number;
     maxIterations?: number;
-    /** skill 内 ctx.llm() 可调工具：容器 provider token 列表（复用其 @Tool 菜单） */
+    /** skill 内 ctx.llm() 可调工具：容器 provider token 列表，或 `<token>/<能力名>` 能力级路径（只引该 provider 菜单里的单个能力）；缺省 = 无工具纯文本 */
     tools?: string[];
 }
 export interface SkillLlmOptions {
     /** 二选一：直接给 prompt（包成单条 user），或给完整 messages */
     prompt?: string;
-    messages?: Anthropic.MessageParam[];
+    messages?: MessageParam[];
     /** 本次受限子运行的系统提示；SystemPrompt 实例自动打缓存 breakpoint */
     system?: string | SystemPrompt;
     model?: string;

package/dist/toolkit/subagent.d.ts

@@ -28,7 +28,7 @@ export interface SubAgentSpec {
      * 注意：这是裁剪上下文的源头 —— 只写子 agent 完成该任务所需的角色/约束。
      */
     system: string | SystemPrompt | ((task: Record<string, unknown>) => SystemParam | Promise<SystemParam>);
-    /** 子 agent 可调工具：容器 provider token 列表（复用其 @Tool 菜单）；缺省 = 无工具纯文本 */
+    /** 子 agent 可调工具：容器 provider token 列表，或 `<token>/<能力名>` 能力级路径（只引该 provider 菜单里的单个能力）；缺省 = 无工具纯文本 */
     tools?: string[];
     model?: string;
     maxTokens?: number;
@@ -53,6 +53,6 @@ export declare function collectSubAgents(instance: object): SubAgentCapability[]
 /**
  * 把 SubAgentCapability 变成主 agent 菜单里的 AgentTool。
  * run(input, ctx) 需要 ToolRunContext（engine 调用时必有）；手动直调会抛错提示。
- * tools token 列表 → resolveTools() 由装配层给出（该 token 的 @Tool 菜单）。
+ * tools 引用（整片 token / `<token>/<能力名>` 能力级路径）→ resolveTools() 由装配层给出。
  */
 export declare function subagentToTool(capability: SubAgentCapability, resolveTools: () => AgentTool[]): AgentTool;

package/dist/toolkit/subagent.js

@@ -35,7 +35,7 @@ async function resolveSubSystem(spec, task) {
 /**
  * 把 SubAgentCapability 变成主 agent 菜单里的 AgentTool。
  * run(input, ctx) 需要 ToolRunContext（engine 调用时必有）；手动直调会抛错提示。
- * tools token 列表 → resolveTools() 由装配层给出（该 token 的 @Tool 菜单）。
+ * tools 引用（整片 token / `<token>/<能力名>` 能力级路径）→ resolveTools() 由装配层给出。
  */
 export function subagentToTool(capability, resolveTools) {
     const { name, spec } = capability;

package/dist/transport/async.d.ts

@@ -1,4 +1,4 @@
-import type Anthropic from '@anthropic-ai/sdk';
+import type { MessageParam } from '../core/message.js';
 import type { ModelClient } from '../core/tool.js';
 import type { AgentRunResult } from '../engine/types.js';
 import type { RunStatus } from '../core/run.js';
@@ -60,7 +60,7 @@ export interface ResumePendingOptions {
 /** 应用最小调用面（agent 装配无关，避免 run 层向上依赖 toolkit） */
 export interface AppCallable {
     readonly name: string;
-    run(messages: Anthropic.MessageParam[], opts?: RunInvocationOptions): Promise<{
+    run(messages: MessageParam[], opts?: RunInvocationOptions): Promise<{
         run: {
             runId: string;
             status: RunStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/agentia",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。",
   "type": "module",
   "main": "dist/index.js",
@@ -53,13 +53,11 @@
     "e2e:mcp": "npm run build:cli && tsx scripts/e2e-mcp.ts"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.125.0",
     "@biomejs/biome": "^2.5.13",
     "@types/node": "^26.5.1",
     "tsx": "^4.19.0",
     "typescript": "^7.0.2",
     "zod": "^4.6.1"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.124.0"
   }
 }