@cotestdev/ai-runner 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/dist/ai-runner/src/runner.d.ts +1 -1
  2. package/dist/ai-runner/src/runner.d.ts.map +1 -1
  3. package/dist/ai-runner/src/runner.js +6 -1
  4. package/dist/ai-runner/src/runner.js.map +1 -1
  5. package/package.json +1 -1
  6. package/src/runner.ts +6 -1
  7. package/tests/agent/test-heal-agent.spec.ts +40 -57
  8. package/dist/agents/heal-agent.d.ts +0 -30
  9. package/dist/agents/heal-agent.d.ts.map +0 -1
  10. package/dist/agents/heal-agent.js +0 -76
  11. package/dist/agents/heal-agent.js.map +0 -1
  12. package/dist/agents/healer.d.ts +0 -73
  13. package/dist/agents/healer.d.ts.map +0 -1
  14. package/dist/agents/healer.js +0 -538
  15. package/dist/agents/healer.js.map +0 -1
  16. package/dist/agents/tools/form.d.ts +0 -22
  17. package/dist/agents/tools/form.d.ts.map +0 -1
  18. package/dist/agents/tools/form.js +0 -134
  19. package/dist/agents/tools/form.js.map +0 -1
  20. package/dist/agents/tools/index.d.ts +0 -13
  21. package/dist/agents/tools/index.d.ts.map +0 -1
  22. package/dist/agents/tools/index.js +0 -33
  23. package/dist/agents/tools/index.js.map +0 -1
  24. package/dist/agents/tools/navigate.d.ts +0 -22
  25. package/dist/agents/tools/navigate.d.ts.map +0 -1
  26. package/dist/agents/tools/navigate.js +0 -74
  27. package/dist/agents/tools/navigate.js.map +0 -1
  28. package/dist/agents/tools/snapshot.d.ts +0 -22
  29. package/dist/agents/tools/snapshot.d.ts.map +0 -1
  30. package/dist/agents/tools/snapshot.js +0 -110
  31. package/dist/agents/tools/snapshot.js.map +0 -1
  32. package/dist/agents/tools/verify.d.ts +0 -34
  33. package/dist/agents/tools/verify.d.ts.map +0 -1
  34. package/dist/agents/tools/verify.js +0 -169
  35. package/dist/agents/tools/verify.js.map +0 -1
  36. package/dist/agents/tools/wait.d.ts +0 -22
  37. package/dist/agents/tools/wait.d.ts.map +0 -1
  38. package/dist/agents/tools/wait.js +0 -104
  39. package/dist/agents/tools/wait.js.map +0 -1
  40. package/dist/agents/types.d.ts +0 -51
  41. package/dist/agents/types.d.ts.map +0 -1
  42. package/dist/agents/types.js +0 -6
  43. package/dist/agents/types.js.map +0 -1
  44. package/dist/ai-runner/src/examples/test-final.d.ts +0 -6
  45. package/dist/ai-runner/src/examples/test-final.d.ts.map +0 -1
  46. package/dist/ai-runner/src/examples/test-final.js +0 -73
  47. package/dist/ai-runner/src/examples/test-final.js.map +0 -1
  48. package/dist/ai-runner/src/examples/test-simple-tools.d.ts +0 -6
  49. package/dist/ai-runner/src/examples/test-simple-tools.d.ts.map +0 -1
  50. package/dist/ai-runner/src/examples/test-simple-tools.js +0 -149
  51. package/dist/ai-runner/src/examples/test-simple-tools.js.map +0 -1
  52. package/dist/ai-runner/src/examples/test-working.d.ts +0 -5
  53. package/dist/ai-runner/src/examples/test-working.d.ts.map +0 -1
  54. package/dist/ai-runner/src/examples/test-working.js +0 -43
  55. package/dist/ai-runner/src/examples/test-working.js.map +0 -1
  56. package/dist/ai-runner/src/examples/v-test-backend-adapter.d.ts +0 -15
  57. package/dist/ai-runner/src/examples/v-test-backend-adapter.d.ts.map +0 -1
  58. package/dist/ai-runner/src/examples/v-test-backend-adapter.js +0 -240
  59. package/dist/ai-runner/src/examples/v-test-backend-adapter.js.map +0 -1
  60. package/dist/core/runner.d.ts +0 -194
  61. package/dist/core/runner.d.ts.map +0 -1
  62. package/dist/core/runner.js +0 -650
  63. package/dist/core/runner.js.map +0 -1
  64. package/dist/index.d.ts +0 -8
  65. package/dist/index.d.ts.map +0 -1
  66. package/dist/index.js +0 -11
  67. package/dist/index.js.map +0 -1
  68. package/dist/types/external.d.ts +0 -6
  69. package/dist/types/external.d.ts.map +0 -1
  70. package/dist/types/external.js +0 -7
  71. package/dist/types/external.js.map +0 -1
  72. package/dist/types/index.d.ts +0 -153
  73. package/dist/types/index.d.ts.map +0 -1
  74. package/dist/types/index.js +0 -26
  75. package/dist/types/index.js.map +0 -1
  76. package/docs/PLAYWRIGHT_MCP_ADAPTER.md +0 -132
  77. package/docs/SCHEMA_EXTRACTION.md +0 -224
package/dist/index.d.ts DELETED
@@ -1,8 +0,0 @@
1
- /**
2
- * ai-runner SDK 主入口
3
- * 提供 AI 驱动的测试运行能力
4
- */
5
- export type { AIHealConfig, ExecutionContext, ExecutionResult, HealContext, HealSummary, HealingDetail, RunStepOptions, VariableBindings } from './types';
6
- export { Runner } from './core/runner';
7
- export type { HealAgentState, HealAgentResult, HealAgentConfig } from './agents/types';
8
- //# sourceMappingURL=index.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAIvC,YAAY,EACV,cAAc,EACd,eAAe,EACf,eAAe,EAChB,MAAM,gBAAgB,CAAC"}
package/dist/index.js DELETED
@@ -1,11 +0,0 @@
1
- "use strict";
2
- /**
3
- * ai-runner SDK 主入口
4
- * 提供 AI 驱动的测试运行能力
5
- */
6
- Object.defineProperty(exports, "__esModule", { value: true });
7
- exports.Runner = void 0;
8
- // 核心类
9
- var runner_1 = require("./core/runner");
10
- Object.defineProperty(exports, "Runner", { enumerable: true, get: function () { return runner_1.Runner; } });
11
- //# sourceMappingURL=index.js.map
package/dist/index.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAeH,MAAM;AACN,wCAAuC;AAA9B,gGAAA,MAAM,OAAA"}
@@ -1,6 +0,0 @@
1
- /**
2
- * 外部类型定义
3
- * 直接从 core-infra 导入
4
- */
5
- export type { ModelConfig, ModelProvider } from '@chen-rmag/core-infra';
6
- //# sourceMappingURL=external.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/types/external.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}
@@ -1,7 +0,0 @@
1
- "use strict";
2
- /**
3
- * 外部类型定义
4
- * 直接从 core-infra 导入
5
- */
6
- Object.defineProperty(exports, "__esModule", { value: true });
7
- //# sourceMappingURL=external.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/types/external.ts"],"names":[],"mappings":";AAAA;;;GAGG"}
@@ -1,153 +0,0 @@
1
- /**
2
- * ai-heal 核心类型定义 (MVP)
3
- * 保持简洁,只包含必要的类型
4
- */
5
- import type { Page, BrowserContext } from 'playwright';
6
- /**
7
- * 变量包装器,支持跨作用域赋值
8
- */
9
- export declare class Ref<T> {
10
- value: T;
11
- constructor(value: T);
12
- get current(): T;
13
- set current(value: T);
14
- }
15
- /**
16
- * AIHeal 配置选项
17
- */
18
- export interface AIHealConfig {
19
- /** 测试用例 ID */
20
- testCaseId: string;
21
- /** 项目 ID */
22
- projectId: string;
23
- /** 手动注入的脚本内容 */
24
- scriptContent?: string;
25
- /** 是否自动保存修复后的脚本 */
26
- enableAutoSave?: boolean;
27
- /** 最大自愈重试次数 */
28
- /** 模型配置 ID(用于加载模型配置) */
29
- modelConfigId?: string;
30
- /** Agent 最大执行步数 */
31
- agentMaxSteps?: number;
32
- /** 是否开启调试模式 */
33
- debugMode?: boolean;
34
- }
35
- /**
36
- * 执行上下文,包含用户的 Playwright 对象
37
- */
38
- export interface ExecutionContext {
39
- context: BrowserContext;
40
- page: Page;
41
- }
42
- /**
43
- * 变量绑定映射
44
- */
45
- export type VariableBindings = Record<string, Ref<any>>;
46
- /**
47
- * runStep 选项
48
- */
49
- export interface RunStepOptions {
50
- /** 步骤描述,用于 AI 理解 */
51
- description: string;
52
- /** 需要传递的变量绑定 */
53
- variables?: VariableBindings;
54
- /** Playwright 上下文对象 */
55
- context?: ExecutionContext;
56
- }
57
- /**
58
- * ReAct 循环步骤记录
59
- */
60
- export interface ReActStep {
61
- /** 步骤序号 */
62
- stepNumber: number;
63
- /** 步骤类型 */
64
- stepType: 'thought' | 'action' | 'observation' | 'reflection';
65
- /** 时间戳 */
66
- timestamp: number;
67
- /** LLM 的思考内容(thought 步骤) */
68
- thought?: string;
69
- /** 工具调用信息(action 步骤) */
70
- toolCall?: {
71
- name: string;
72
- input: any;
73
- };
74
- /** 工具执行结果(observation 步骤) */
75
- toolResult?: {
76
- output: string;
77
- success: boolean;
78
- duration?: number;
79
- };
80
- /** 反思内容(reflection 步骤) */
81
- reflection?: string;
82
- }
83
- /**
84
- * 单次自愈过程的上下文信息
85
- */
86
- export interface HealContext {
87
- /** 时间戳 */
88
- timestamp: number;
89
- /** 步骤描述 */
90
- stepDescription: string;
91
- /** 错误对象 */
92
- error?: Error;
93
- /** 堆栈信息 */
94
- stackTrace?: string;
95
- /** 原始代码 */
96
- originalCode: string;
97
- /** 恢复尝试次数 */
98
- recoveryAttempts: number;
99
- /** 变量快照(执行前) */
100
- variablesBefore: Record<string, any>;
101
- /** 变量快照(执行后) */
102
- variablesAfter: Record<string, any>;
103
- /** 是否成功 */
104
- success: boolean;
105
- /** 自愈耗时 */
106
- healingTime?: number;
107
- /** ReAct 循环详细记录(如果使用了 Agent) */
108
- reactSteps?: ReActStep[];
109
- /** Agent 的推理过程总结 */
110
- reasoning?: string;
111
- /** Agent 执行的总步数 */
112
- agentSteps?: number;
113
- }
114
- /**
115
- * 代码执行结果
116
- */
117
- export interface ExecutionResult {
118
- /** 是否成功 */
119
- success: boolean;
120
- /** 返回值 */
121
- returnValue: any;
122
- /** 局部变量 */
123
- locals: Record<string, any>;
124
- /** 错误信息 */
125
- error?: Error;
126
- }
127
- /**
128
- * 自愈摘要信息
129
- */
130
- export interface HealSummary {
131
- /** 总步骤数 */
132
- totalSteps: number;
133
- /** 自愈成功的步骤数 */
134
- healedSteps: number;
135
- /** 修复后的脚本 */
136
- modifiedScript?: string;
137
- /** 自愈详情列表 */
138
- healingDetails: HealingDetail[];
139
- }
140
- /**
141
- * 单次自愈详情
142
- */
143
- export interface HealingDetail {
144
- /** 步骤描述 */
145
- step: string;
146
- /** 错误信息 */
147
- error: string;
148
- /** 恢复时间 */
149
- recoveryTime: number;
150
- /** LLM 交互次数 */
151
- llmInteractions: number;
152
- }
153
- //# sourceMappingURL=index.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMvD;;GAEG;AACH,qBAAa,GAAG,CAAC,CAAC;IACG,KAAK,EAAE,CAAC;gBAAR,KAAK,EAAE,CAAC;IAE3B,IAAI,OAAO,IAAI,CAAC,CAEf;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,EAEnB;CACF;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe;IACf,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,IAAI,CAAC;CACZ;AAMD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAMxD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oBAAoB;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB;IAChB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,uBAAuB;IACvB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAMD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW;IACX,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,YAAY,CAAC;IAC9D,UAAU;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,GAAG,CAAC;KACZ,CAAC;IACF,6BAA6B;IAC7B,UAAU,CAAC,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW;IACX,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,WAAW;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB;IAChB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,gBAAgB;IAChB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,WAAW;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,oBAAoB;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU;IACV,WAAW,EAAE,GAAG,CAAC;IACjB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,WAAW;IACX,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa;IACb,cAAc,EAAE,aAAa,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe;IACf,eAAe,EAAE,MAAM,CAAC;CACzB"}
@@ -1,26 +0,0 @@
1
- "use strict";
2
- /**
3
- * ai-heal 核心类型定义 (MVP)
4
- * 保持简洁,只包含必要的类型
5
- */
6
- Object.defineProperty(exports, "__esModule", { value: true });
7
- exports.Ref = void 0;
8
- // ============================================================================
9
- // Ref<T>: 变量包装器
10
- // ============================================================================
11
- /**
12
- * 变量包装器,支持跨作用域赋值
13
- */
14
- class Ref {
15
- constructor(value) {
16
- this.value = value;
17
- }
18
- get current() {
19
- return this.value;
20
- }
21
- set current(value) {
22
- this.value = value;
23
- }
24
- }
25
- exports.Ref = Ref;
26
- //# sourceMappingURL=index.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;GAEG;AACH,MAAa,GAAG;IACd,YAAmB,KAAQ;QAAR,UAAK,GAAL,KAAK,CAAG;IAAG,CAAC;IAE/B,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,OAAO,CAAC,KAAQ;QAClB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAVD,kBAUC"}
@@ -1,132 +0,0 @@
1
- # Playwright MCP 工具适配器
2
-
3
- ## 概述
4
-
5
- 这个适配器允许你直接使用 Playwright 官方的 MCP 工具,而不需要手动复制和维护工具代码。
6
-
7
- ## 优势
8
-
9
- 1. **自动同步**:当 Playwright 更新时,自动获得最新的工具和功能
10
- 2. **零维护成本**:不需要手动复制或修改工具代码
11
- 3. **官方支持**:使用 Playwright 官方测试和验证过的工具实现
12
- 4. **完整功能**:自动获得所有官方工具,包括未来的新工具
13
-
14
- ## 使用方法
15
-
16
- ### 方式 1: 使用官方 MCP 工具(推荐)
17
-
18
- ```typescript
19
- import { getOfficialPlaywrightTools } from '@chen-rmag/ai-runner/tools';
20
-
21
- const page = await browser.newPage();
22
- const tools = await getOfficialPlaywrightTools(page);
23
-
24
- // 现在可以将这些工具用于 LangChain Agent
25
- ```
26
-
27
- ### 方式 2: 使用手动维护的工具(向后兼容)
28
-
29
- ```typescript
30
- import { getAllTools } from '@chen-rmag/ai-runner/tools';
31
-
32
- const page = await browser.newPage();
33
- const tools = getAllTools(page);
34
- ```
35
-
36
- ## 工具列表
37
-
38
- 当前可用的官方 MCP 工具包括:
39
-
40
- ### 导航工具 (navigate)
41
- - `browser_navigate` - 导航到 URL
42
- - `browser_navigate_back` - 后退
43
- - `browser_navigate_forward` - 前进
44
-
45
- ### 表单工具 (form)
46
- - `browser_fill` - 填写表单字段
47
- - `browser_set_checked` - 设置复选框状态
48
- - `browser_select_option` - 选择下拉选项
49
-
50
- ### 等待工具 (wait)
51
- - `browser_wait_for_time` - 等待指定时间
52
- - `browser_wait_for_selector` - 等待元素出现
53
- - `browser_wait_for_url` - 等待 URL 匹配
54
-
55
- ### 快照工具 (snapshot)
56
- - `browser_snapshot` - 获取页面可访问性快照
57
- - `browser_screenshot` - 截图
58
-
59
- ### 验证工具 (verify)
60
- - `browser_verify_text` - 验证文本是否存在
61
- - `browser_verify_element` - 验证元素是否存在
62
-
63
- ### 鼠标工具 (mouse)
64
- - `browser_click` - 点击元素
65
- - `browser_hover` - 悬停元素
66
- - `browser_dblclick` - 双击元素
67
-
68
- ### 键盘工具 (keyboard)
69
- - `browser_type` - 输入文本
70
- - `browser_press` - 按键
71
-
72
- ## 迁移指南
73
-
74
- 如果你当前使用的是手动维护的工具,迁移到官方 MCP 工具非常简单:
75
-
76
- ### 之前(手动维护)
77
-
78
- ```typescript
79
- import { getAllTools } from './tools';
80
- const tools = getAllTools(page);
81
- ```
82
-
83
- ### 之后(官方 MCP 工具)
84
-
85
- ```typescript
86
- import { getOfficialPlaywrightTools } from './tools';
87
- const tools = await getOfficialPlaywrightTools(page);
88
- ```
89
-
90
- 只需要:
91
- 1. 将 `getAllTools` 改为 `getOfficialPlaywrightTools`
92
- 2. 添加 `await` 关键字(因为新函数是异步的)
93
- 3. 享受自动更新和零维护!
94
-
95
- ## 技术细节
96
-
97
- ### 适配器工作原理
98
-
99
- 1. **导入官方工具**:直接从 `playwright/lib/mcp/browser/tools/` 导入
100
- 2. **上下文适配**:创建 `MCPContextAdapter` 来模拟 MCP 需要的 context 对象
101
- 3. **响应适配**:创建 `MCPResponseAdapter` 来处理工具返回值
102
- 4. **LangChain 集成**:将 MCP 工具转换为 LangChain `DynamicTool` 格式
103
-
104
- ### 为什么需要适配器?
105
-
106
- Playwright MCP 工具设计用于 MCP 协议,它们需要:
107
- - `context` 对象(包含 page 访问)
108
- - `response` 对象(用于返回结果)
109
- - 特定的参数格式
110
-
111
- 我们的适配器将这些转换为 LangChain 兼容的格式。
112
-
113
- ## 故障排除
114
-
115
- ### 问题:找不到工具模块
116
-
117
- 确保安装了正确版本的 Playwright:
118
-
119
- ```bash
120
- npm install playwright@latest
121
- ```
122
-
123
- ### 问题:工具执行失败
124
-
125
- 检查:
126
- 1. Page 对象是否有效
127
- 2. 工具参数格式是否正确
128
- 3. 查看错误日志获取详细信息
129
-
130
- ## 贡献
131
-
132
- 如果发现问题或有改进建议,欢迎提交 Issue 或 PR!
@@ -1,224 +0,0 @@
1
- # Schema 信息提取 - 详细说明
2
-
3
- ## 问题
4
-
5
- LangChain 的 `DynamicTool` 不直接支持 schema 定义,但如果不在描述中提供输入格式信息,LLM 就不知道如何正确调用工具。
6
-
7
- ## 解决方案
8
-
9
- 通过将 Playwright MCP 工具的 Zod `inputSchema` 转换为人类可读的描述,让 LLM 能够理解工具的正确用法。
10
-
11
- ### 实现原理
12
-
13
- ```typescript
14
- /**
15
- * 将 Zod schema 转换为人类可读的描述
16
- */
17
- function zodSchemaToDescription(schema: any): string {
18
- // 提取 schema 的 shape
19
- const shape = schema.shape;
20
- if (!shape) return '';
21
-
22
- // 遍历每个字段
23
- for (const [key, value] of Object.entries(shape)) {
24
- // 获取类型名称
25
- const typeName = value._def.typeName();
26
-
27
- // 获取描述
28
- const description = value.description;
29
-
30
- // 判断是否可选
31
- const isOptional = typeName === 'ZodOptional';
32
-
33
- // 生成格式化的字段描述
34
- parts.push(` - ${key} (${type}): ${description}`);
35
- }
36
-
37
- return '\n\nInput schema:\n' + parts.join('\n');
38
- }
39
- ```
40
-
41
- ### 示例
42
-
43
- #### 输入(Zod Schema)
44
-
45
- ```typescript
46
- {
47
- shape: {
48
- url: {
49
- _def: { typeName: () => 'ZodString' },
50
- description: 'The URL to navigate to'
51
- },
52
- timeout: {
53
- _def: {
54
- typeName: () => 'ZodOptional',
55
- innerType: { _def: { typeName: () => 'ZodNumber' } }
56
- }
57
- }
58
- }
59
- }
60
- ```
61
-
62
- #### 输出(增强后的描述)
63
-
64
- ```
65
- Navigate to a specified URL
66
-
67
- Input schema:
68
- - url (required): string - The URL to navigate to
69
- - timeout (optional): number
70
- ```
71
-
72
- ### 效果对比
73
-
74
- #### 之前(没有 Schema 信息)
75
-
76
- ```typescript
77
- const tool = new DynamicTool({
78
- name: 'browser_navigate',
79
- description: 'Navigate to a URL', // ❌ LLM 不知道输入格式
80
- func: async (input) => { ... }
81
- });
82
- ```
83
-
84
- **LLM 调用示例**(可能失败):
85
- ```json
86
- {
87
- "tool": "browser_navigate",
88
- "input": "https://example.com" // ✅ 碰巧正确
89
- }
90
- ```
91
-
92
-
93
-
94
- ```json
95
- {
96
- "tool": "browser_navigate",
97
- "input": "goto https://example.com" // ❌ 格式错误
98
- }
99
- ```
100
-
101
- #### 之后(包含 Schema 信息)
102
-
103
- ```typescript
104
- const tool = new DynamicTool({
105
- name: 'browser_navigate',
106
- description: `Navigate to a URL
107
-
108
- Input schema:
109
- - url (required): string - The URL to navigate to`, // ✅ 清晰说明输入格式
110
- func: async (input) => { ... }
111
- });
112
- ```
113
-
114
- **LLM 调用示例**(总是正确):
115
- ```json
116
- {
117
- "tool": "browser_navigate",
118
- "input": "{\"url\": \"https://example.com\"}" // ✅ 正确的 JSON 格式
119
- }
120
- ```
121
-
122
- ### 支持的类型
123
-
124
- | Zod 类型 | 描述 | 示例 |
125
- |---------|------|------|
126
- | `ZodString` | string | `"hello"` |
127
- | `ZodNumber` | number | `123` |
128
- | `ZodBoolean` | boolean | `true` |
129
- | `ZodObject` | object | `{"key": "value"}` |
130
- | `ZodArray` | array | `[1, 2, 3]` |
131
- | `ZodOptional` | 可选字段 | `(optional)` |
132
-
133
- ### 处理复杂 Schema
134
-
135
- #### 嵌套对象
136
-
137
- ```typescript
138
- {
139
- selector: {
140
- _def: { typeName: () => 'ZodString' },
141
- description: 'CSS selector'
142
- },
143
- options: {
144
- _def: {
145
- typeName: () => 'ZodObject',
146
- shape: {
147
- timeout: { _def: { typeName: () => 'ZodNumber' } },
148
- force: { _def: { typeName: () => 'ZodBoolean' } }
149
- }
150
- }
151
- }
152
- }
153
- ```
154
-
155
- **输出**:
156
- ```
157
- Input schema:
158
- - selector (required): string - CSS selector
159
- - options (required): object
160
- ```
161
-
162
- #### 可选字段
163
-
164
- ```typescript
165
- {
166
- url: {
167
- _def: { typeName: () => 'ZodString' },
168
- description: 'The URL'
169
- },
170
- timeout: {
171
- _def: {
172
- typeName: () => 'ZodOptional',
173
- innerType: { _def: { typeName: () => 'ZodNumber' } }
174
- }
175
- }
176
- }
177
- ```
178
-
179
- **输出**:
180
- ```
181
- Input schema:
182
- - url (required): string - The URL
183
- - timeout (optional): number
184
- ```
185
-
186
- ## 使用方法
187
-
188
- 在你的代码中,适配器会自动处理 schema 转换:
189
-
190
- ```typescript
191
- import { getOfficialPlaywrightTools } from '@chen-rmag/ai-runner/tools';
192
-
193
- const tools = await getOfficialPlaywrightTools(page);
194
-
195
- // 工具描述已经包含了 schema 信息
196
- tools.forEach(tool => {
197
- console.log(`工具: ${tool.name}`);
198
- console.log(`描述:\n${tool.description}\n`);
199
- });
200
- ```
201
-
202
- ## 优势
203
-
204
- 1. **自动化**:自动从官方工具提取 schema,无需手动维护
205
- 2. **准确性**:使用官方定义,保证格式正确
206
- 3. **LLM 友好**:清晰的格式说明,提高 LLM 调用成功率
207
- 4. **零维护**:Playwright 更新时自动获得最新 schema
208
-
209
- ## 注意事项
210
-
211
- 1. **描述长度**:复杂的 schema 可能导致描述很长,但这是必要的
212
- 2. **性能影响**:schema 转换只在工具创建时执行一次,运行时无影响
213
- 3. **类型安全**:使用 `any` 类型是因为 Zod schema 结构复杂,实际使用中类型正确
214
-
215
- ## 总结
216
-
217
- 通过自动提取和转换 schema 信息,我们实现了:
218
-
219
- ✅ LLM 能够正确理解工具输入格式
220
- ✅ 提高工具调用成功率
221
- ✅ 零维护成本(自动从官方工具提取)
222
- ✅ 完整的类型信息传递
223
-
224
- 这是连接 Playwright MCP 工具和 LangChain Agent 的关键一环!