yimo-kit 0.1.0__py3-none-any.whl
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.
- yimo/__init__.py +26 -0
- yimo/kit/__init__.py +98 -0
- yimo/kit/ai/__init__.py +110 -0
- yimo/kit/ai/_internal/__init__.py +27 -0
- yimo/kit/ai/_internal/failover.py +535 -0
- yimo/kit/ai/_internal/pool.py +526 -0
- yimo/kit/ai/_internal/rerank_transport.py +137 -0
- yimo/kit/ai/_internal/retry_after.py +51 -0
- yimo/kit/ai/_internal/sdk_client.py +463 -0
- yimo/kit/ai/_internal/service_base.py +115 -0
- yimo/kit/ai/_internal/types.py +28 -0
- yimo/kit/ai/agent/__init__.py +127 -0
- yimo/kit/ai/agent/approval.py +66 -0
- yimo/kit/ai/agent/errors.py +128 -0
- yimo/kit/ai/agent/loop.py +643 -0
- yimo/kit/ai/agent/mcp.py +278 -0
- yimo/kit/ai/agent/registry.py +203 -0
- yimo/kit/ai/agent/session.py +150 -0
- yimo/kit/ai/agent/skill.py +370 -0
- yimo/kit/ai/agent/types.py +161 -0
- yimo/kit/ai/chat_service.py +724 -0
- yimo/kit/ai/decision/__init__.py +57 -0
- yimo/kit/ai/decision/decima.py +853 -0
- yimo/kit/ai/decision/laya.py +552 -0
- yimo/kit/ai/embedding_service.py +198 -0
- yimo/kit/ai/exceptions.py +109 -0
- yimo/kit/ai/image_service.py +84 -0
- yimo/kit/ai/messages.py +105 -0
- yimo/kit/ai/model_builder.py +121 -0
- yimo/kit/ai/model_client.py +62 -0
- yimo/kit/ai/profiles.py +577 -0
- yimo/kit/ai/rerank_service.py +136 -0
- yimo/kit/ai/runner.py +1127 -0
- yimo/kit/common_kit.py +221 -0
- yimo/kit/config/__init__.py +44 -0
- yimo/kit/config/kit_config.py +210 -0
- yimo/kit/config/log_config.py +171 -0
- yimo/kit/crawl/__init__.py +71 -0
- yimo/kit/crawl/article_io.py +325 -0
- yimo/kit/crawl/article_models.py +172 -0
- yimo/kit/crawl/deepseek_kit.py +673 -0
- yimo/kit/crawl/web_article_kit.py +638 -0
- yimo/kit/crawl/wx_article_kit.py +692 -0
- yimo/kit/db/__init__.py +101 -0
- yimo/kit/db/audit.py +625 -0
- yimo/kit/db/base_db_kit.py +1265 -0
- yimo/kit/db/crud.py +423 -0
- yimo/kit/db/engine.py +235 -0
- yimo/kit/db/exceptions.py +45 -0
- yimo/kit/db/models/__init__.py +33 -0
- yimo/kit/db/models/base.py +56 -0
- yimo/kit/db/mysql_kit.py +348 -0
- yimo/kit/db/pg_kit.py +442 -0
- yimo/kit/db/query.py +338 -0
- yimo/kit/db/session.py +85 -0
- yimo/kit/db/sqlite_kit.py +462 -0
- yimo/kit/db/transaction.py +109 -0
- yimo/kit/docs/__init__.py +34 -0
- yimo/kit/docs/anydoc_kit.py +490 -0
- yimo/kit/docs/docx_kit.py +895 -0
- yimo/kit/docs/md2doc_kit.py +1801 -0
- yimo/kit/docs/mineru_kit.py +1497 -0
- yimo/kit/docs/rc_docparser_kit.py +654 -0
- yimo/kit/file_kit.py +518 -0
- yimo/kit/license_kit.py +533 -0
- yimo/kit/redis_kit.py +392 -0
- yimo_kit-0.1.0.dist-info/METADATA +1673 -0
- yimo_kit-0.1.0.dist-info/RECORD +70 -0
- yimo_kit-0.1.0.dist-info/WHEEL +4 -0
- yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
yimo/kit/ai/agent/mcp.py
ADDED
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
# date: 2026-11-10
|
|
21
|
+
"""MCP 客户端隔离层(fastmcp 只允许出现在本文件)。
|
|
22
|
+
|
|
23
|
+
对外只暴露自有类型:``McpConnection`` / ``McpToolAdapter``;连接、传输
|
|
24
|
+
推断、结果解析都在本文件内完成,将来换回裸 ``mcp`` SDK 只改这里。
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import asyncio
|
|
28
|
+
import json
|
|
29
|
+
from contextlib import AsyncExitStack
|
|
30
|
+
from dataclasses import dataclass
|
|
31
|
+
from typing import Any
|
|
32
|
+
|
|
33
|
+
try:
|
|
34
|
+
from fastmcp import Client
|
|
35
|
+
from fastmcp.client.transports import StdioTransport, StreamableHttpTransport
|
|
36
|
+
except ImportError as exc: # pragma: no cover - 仅缺依赖环境触发
|
|
37
|
+
raise ImportError(
|
|
38
|
+
"yimo.kit.ai.agent 需要可选依赖,请安装:pip install yimo-kit[agent]"
|
|
39
|
+
) from exc
|
|
40
|
+
|
|
41
|
+
from yimo.kit.ai.agent.errors import McpConnectionError, ToolExecutionError
|
|
42
|
+
from yimo.kit.ai.agent.types import McpServerConfig, ToolResult, ToolSpec
|
|
43
|
+
from yimo.kit.config.log_config import get_default_logger
|
|
44
|
+
|
|
45
|
+
__all__ = ["McpConnection", "McpToolAdapter"]
|
|
46
|
+
|
|
47
|
+
logger = get_default_logger(__name__)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _size_kb(base64_data: str) -> float:
|
|
51
|
+
"""估算 base64 数据解码后的 KB 数(只用于占位符,不要求精确)。"""
|
|
52
|
+
return len(base64_data) * 3 / 4 / 1024
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _extract_result(result: Any) -> ToolResult:
|
|
56
|
+
"""把 MCP ``CallToolResult`` 收敛为文本(E4 降级规则)。
|
|
57
|
+
|
|
58
|
+
图片 / 音频只放占位符,绝不把 base64 塞进上下文;结构化结果追加
|
|
59
|
+
JSON 文本;``is_error`` 原样透传,由模型自行纠正。
|
|
60
|
+
"""
|
|
61
|
+
pieces: list[str] = []
|
|
62
|
+
for block in getattr(result, "content", None) or []:
|
|
63
|
+
block_type = getattr(block, "type", None)
|
|
64
|
+
if block_type == "text":
|
|
65
|
+
text = getattr(block, "text", "")
|
|
66
|
+
if isinstance(text, str) and text:
|
|
67
|
+
pieces.append(text)
|
|
68
|
+
elif block_type in ("image", "audio"):
|
|
69
|
+
mime = getattr(block, "mime_type", None) or f"{block_type}/*"
|
|
70
|
+
data = getattr(block, "data", "") or ""
|
|
71
|
+
pieces.append(f"[{block_type}: {mime}, {_size_kb(data):.1f}KB]")
|
|
72
|
+
elif block_type == "resource":
|
|
73
|
+
resource = getattr(block, "resource", None)
|
|
74
|
+
text = getattr(resource, "text", None) if resource is not None else None
|
|
75
|
+
if isinstance(text, str) and text:
|
|
76
|
+
pieces.append(text)
|
|
77
|
+
else:
|
|
78
|
+
uri = getattr(resource, "uri", "?") if resource is not None else "?"
|
|
79
|
+
pieces.append(f"[resource: {uri}]")
|
|
80
|
+
else:
|
|
81
|
+
pieces.append(f"[{block_type or 'unknown'} content]")
|
|
82
|
+
|
|
83
|
+
structured = getattr(result, "structured_content", None)
|
|
84
|
+
if structured is None:
|
|
85
|
+
structured = getattr(result, "structuredContent", None)
|
|
86
|
+
if structured is not None:
|
|
87
|
+
try:
|
|
88
|
+
pieces.append(json.dumps(structured, ensure_ascii=False))
|
|
89
|
+
except (TypeError, ValueError):
|
|
90
|
+
pieces.append(str(structured))
|
|
91
|
+
|
|
92
|
+
if not pieces:
|
|
93
|
+
data = getattr(result, "data", None)
|
|
94
|
+
if data is not None:
|
|
95
|
+
if isinstance(data, str):
|
|
96
|
+
pieces.append(data)
|
|
97
|
+
else:
|
|
98
|
+
try:
|
|
99
|
+
pieces.append(json.dumps(data, ensure_ascii=False))
|
|
100
|
+
except (TypeError, ValueError):
|
|
101
|
+
pieces.append(str(data))
|
|
102
|
+
|
|
103
|
+
is_error = bool(
|
|
104
|
+
getattr(result, "is_error", False) or getattr(result, "isError", False)
|
|
105
|
+
)
|
|
106
|
+
return ToolResult(
|
|
107
|
+
content="\n".join(pieces) if pieces else "(空结果)", is_error=is_error
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
@dataclass(frozen=True)
|
|
112
|
+
class McpToolAdapter:
|
|
113
|
+
"""单个 MCP 工具到 ``ToolSpec`` + callable 的适配器。"""
|
|
114
|
+
|
|
115
|
+
spec: ToolSpec
|
|
116
|
+
raw_name: str
|
|
117
|
+
connection: "McpConnection"
|
|
118
|
+
|
|
119
|
+
async def __call__(self, arguments: dict[str, Any]) -> ToolResult:
|
|
120
|
+
return await self.connection.call_tool(self.raw_name, arguments)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
class McpConnection:
|
|
124
|
+
"""一个 MCP server 的连接(生命周期由 Agent 的 async with 管理)。"""
|
|
125
|
+
|
|
126
|
+
def __init__(self, config: McpServerConfig, *, client: Any = None) -> None:
|
|
127
|
+
self._config: McpServerConfig = config
|
|
128
|
+
# client 仅供测试注入(如 fastmcp 的 in-memory server)
|
|
129
|
+
self._client: Any = client
|
|
130
|
+
self._stack: AsyncExitStack | None = None
|
|
131
|
+
self._tools: list[Any] = []
|
|
132
|
+
|
|
133
|
+
@property
|
|
134
|
+
def config(self) -> McpServerConfig:
|
|
135
|
+
return self._config
|
|
136
|
+
|
|
137
|
+
def _build_client(self) -> Any:
|
|
138
|
+
config = self._config
|
|
139
|
+
if config.transport == "http":
|
|
140
|
+
transport = StreamableHttpTransport(
|
|
141
|
+
config.url or "", headers=config.headers
|
|
142
|
+
)
|
|
143
|
+
else:
|
|
144
|
+
transport = StdioTransport(
|
|
145
|
+
command=config.command or "",
|
|
146
|
+
args=list(config.args),
|
|
147
|
+
env=config.env,
|
|
148
|
+
cwd=config.cwd,
|
|
149
|
+
keep_alive=config.keep_alive,
|
|
150
|
+
)
|
|
151
|
+
return Client(
|
|
152
|
+
transport,
|
|
153
|
+
name=config.name,
|
|
154
|
+
timeout=config.call_timeout,
|
|
155
|
+
init_timeout=config.connect_timeout,
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
async def open(self) -> None:
|
|
159
|
+
"""建立连接并发现工具。
|
|
160
|
+
|
|
161
|
+
Raises:
|
|
162
|
+
McpConnectionError: 连接 / 握手 / 工具发现失败或超时。
|
|
163
|
+
"""
|
|
164
|
+
if self._stack is not None:
|
|
165
|
+
return
|
|
166
|
+
stack = AsyncExitStack()
|
|
167
|
+
try:
|
|
168
|
+
client = (
|
|
169
|
+
self._client if self._client is not None else self._build_client()
|
|
170
|
+
)
|
|
171
|
+
async with asyncio.timeout(self._config.connect_timeout):
|
|
172
|
+
await stack.enter_async_context(client)
|
|
173
|
+
self._tools = list(await client.list_tools())
|
|
174
|
+
except TimeoutError:
|
|
175
|
+
await stack.aclose()
|
|
176
|
+
raise McpConnectionError(
|
|
177
|
+
f"MCP server {self._config.name!r} 连接超时"
|
|
178
|
+
f"({self._config.connect_timeout:g}s)"
|
|
179
|
+
)
|
|
180
|
+
except Exception as exc: # noqa: BLE001 - 协议/网络异常统一降级
|
|
181
|
+
await stack.aclose()
|
|
182
|
+
raise McpConnectionError(
|
|
183
|
+
f"MCP server {self._config.name!r} 连接失败: "
|
|
184
|
+
f"{type(exc).__name__}: {exc}"
|
|
185
|
+
) from exc
|
|
186
|
+
self._stack = stack
|
|
187
|
+
self._client = client
|
|
188
|
+
logger.info(
|
|
189
|
+
f"MCP server {self._config.name!r} 已连接,发现 {len(self._tools)} 个工具"
|
|
190
|
+
)
|
|
191
|
+
|
|
192
|
+
async def close(self) -> None:
|
|
193
|
+
"""关闭连接(幂等)。"""
|
|
194
|
+
stack, self._stack = self._stack, None
|
|
195
|
+
if stack is not None:
|
|
196
|
+
try:
|
|
197
|
+
await stack.aclose()
|
|
198
|
+
except Exception as exc: # noqa: BLE001 - 关闭阶段失败不影响退出
|
|
199
|
+
logger.warning(
|
|
200
|
+
f"MCP server {self._config.name!r} 关闭失败: "
|
|
201
|
+
f"{type(exc).__name__}: {exc}"
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
async def __aenter__(self) -> "McpConnection":
|
|
205
|
+
await self.open()
|
|
206
|
+
return self
|
|
207
|
+
|
|
208
|
+
async def __aexit__(self, *exc_info: object) -> None:
|
|
209
|
+
await self.close()
|
|
210
|
+
|
|
211
|
+
def adapters(self) -> list[McpToolAdapter]:
|
|
212
|
+
"""把已发现的工具适配为统一 ToolSpec + callable。"""
|
|
213
|
+
adapters: list[McpToolAdapter] = []
|
|
214
|
+
for tool in self._tools:
|
|
215
|
+
raw_name = getattr(tool, "name", None)
|
|
216
|
+
if not isinstance(raw_name, str) or not raw_name:
|
|
217
|
+
logger.warning(
|
|
218
|
+
f"MCP server {self._config.name!r} 返回了无名工具,已跳过"
|
|
219
|
+
)
|
|
220
|
+
continue
|
|
221
|
+
description = getattr(tool, "description", None)
|
|
222
|
+
if not isinstance(description, str) or not description.strip():
|
|
223
|
+
description = raw_name
|
|
224
|
+
logger.warning(
|
|
225
|
+
f"MCP 工具 {self._config.name}.{raw_name} 缺少描述,"
|
|
226
|
+
"模型可能不会选中它"
|
|
227
|
+
)
|
|
228
|
+
schema = getattr(tool, "input_schema", None)
|
|
229
|
+
if schema is None:
|
|
230
|
+
schema = getattr(tool, "inputSchema", None)
|
|
231
|
+
if not isinstance(schema, dict):
|
|
232
|
+
schema = {}
|
|
233
|
+
name = (
|
|
234
|
+
f"{self._config.name}__{raw_name}"
|
|
235
|
+
if self._config.tool_prefix
|
|
236
|
+
else raw_name
|
|
237
|
+
)
|
|
238
|
+
adapters.append(
|
|
239
|
+
McpToolAdapter(
|
|
240
|
+
spec=ToolSpec(
|
|
241
|
+
name=name,
|
|
242
|
+
description=description.strip(),
|
|
243
|
+
input_schema=schema,
|
|
244
|
+
),
|
|
245
|
+
raw_name=raw_name,
|
|
246
|
+
connection=self,
|
|
247
|
+
)
|
|
248
|
+
)
|
|
249
|
+
return adapters
|
|
250
|
+
|
|
251
|
+
async def call_tool(self, raw_name: str, arguments: dict[str, Any]) -> ToolResult:
|
|
252
|
+
"""调用工具;工具级错误以 ``is_error=True`` 返回,不抛异常。"""
|
|
253
|
+
if self._client is None or self._stack is None:
|
|
254
|
+
raise McpConnectionError(f"MCP server {self._config.name!r} 尚未连接")
|
|
255
|
+
try:
|
|
256
|
+
result = await self._client.call_tool(
|
|
257
|
+
raw_name,
|
|
258
|
+
arguments,
|
|
259
|
+
timeout=self._config.call_timeout,
|
|
260
|
+
raise_on_error=False,
|
|
261
|
+
)
|
|
262
|
+
except TimeoutError:
|
|
263
|
+
return ToolResult(
|
|
264
|
+
content=f"[timeout after {self._config.call_timeout:g}s]",
|
|
265
|
+
is_error=True,
|
|
266
|
+
)
|
|
267
|
+
except Exception as exc: # noqa: BLE001 - 协议异常统一转为工具错误
|
|
268
|
+
message = str(exc).lower()
|
|
269
|
+
if "timed out" in message:
|
|
270
|
+
return ToolResult(
|
|
271
|
+
content=f"[timeout after {self._config.call_timeout:g}s]",
|
|
272
|
+
is_error=True,
|
|
273
|
+
)
|
|
274
|
+
raise ToolExecutionError(
|
|
275
|
+
f"MCP 工具 {self._config.name}.{raw_name} 调用失败: "
|
|
276
|
+
f"{type(exc).__name__}: {exc}"
|
|
277
|
+
) from exc
|
|
278
|
+
return _extract_result(result)
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
# date: 2026-11-10
|
|
21
|
+
"""工具注册表:名称去重、schema 清洗、按名调用。
|
|
22
|
+
|
|
23
|
+
循环只认 ``ToolSpec`` + callable,不认工具来源;MCP / skill / 本地函数
|
|
24
|
+
都适配成同一对。
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import hashlib
|
|
28
|
+
import re
|
|
29
|
+
from collections.abc import Awaitable, Callable, Iterable, Sequence
|
|
30
|
+
from dataclasses import dataclass
|
|
31
|
+
from typing import Any, Literal
|
|
32
|
+
|
|
33
|
+
from yimo.kit.ai.agent.errors import ToolExecutionError, ToolNotFoundError
|
|
34
|
+
from yimo.kit.ai.agent.types import ToolResult, ToolSpec
|
|
35
|
+
from yimo.kit.config.log_config import get_default_logger
|
|
36
|
+
|
|
37
|
+
__all__ = [
|
|
38
|
+
"RegisteredTool",
|
|
39
|
+
"ToolRegistry",
|
|
40
|
+
"clean_schema",
|
|
41
|
+
"sanitize_tool_name",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
logger = get_default_logger(__name__)
|
|
45
|
+
|
|
46
|
+
ToolHandler = Callable[[dict[str, Any]], Awaitable[ToolResult]]
|
|
47
|
+
ToolKind = Literal["local", "mcp_tool", "skill_read", "skill_script"]
|
|
48
|
+
|
|
49
|
+
# OpenAI 工具名约束:[A-Za-z0-9_-],最长 64
|
|
50
|
+
_INVALID_NAME_CHARS = re.compile(r"[^A-Za-z0-9_-]")
|
|
51
|
+
_MAX_TOOL_NAME_LEN = 64
|
|
52
|
+
|
|
53
|
+
# 严格厂商校验会拒绝的 JSON Schema 元字段
|
|
54
|
+
_DROPPED_SCHEMA_KEYS = frozenset({"$schema", "$id", "title"})
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def sanitize_tool_name(name: str) -> str:
|
|
58
|
+
"""清洗工具名:非法字符替换为 ``_``,超长时截断并追加哈希。"""
|
|
59
|
+
cleaned = _INVALID_NAME_CHARS.sub("_", name.strip())
|
|
60
|
+
if not cleaned:
|
|
61
|
+
cleaned = "tool"
|
|
62
|
+
if len(cleaned) > _MAX_TOOL_NAME_LEN:
|
|
63
|
+
digest = hashlib.sha1(cleaned.encode("utf-8")).hexdigest()[:8]
|
|
64
|
+
cleaned = f"{cleaned[: _MAX_TOOL_NAME_LEN - 9]}_{digest}"
|
|
65
|
+
return cleaned
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def clean_schema(schema: Any) -> dict[str, Any] | None:
|
|
69
|
+
"""递归清洗 JSON Schema。
|
|
70
|
+
|
|
71
|
+
- 删除 ``$schema`` / ``$id`` / ``title``;
|
|
72
|
+
- 顶层必须是 ``type="object"``,否则返回 None(调用方不注册该工具);
|
|
73
|
+
- ``oneOf`` / ``anyOf`` / ``allOf`` 保留,v1 不做自动降级。
|
|
74
|
+
"""
|
|
75
|
+
if not isinstance(schema, dict):
|
|
76
|
+
return None
|
|
77
|
+
cleaned = _clean_node(schema)
|
|
78
|
+
if not isinstance(cleaned, dict) or cleaned.get("type") != "object":
|
|
79
|
+
return None
|
|
80
|
+
return cleaned
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _clean_node(node: Any) -> Any:
|
|
84
|
+
if isinstance(node, dict):
|
|
85
|
+
return {
|
|
86
|
+
key: _clean_node(value)
|
|
87
|
+
for key, value in node.items()
|
|
88
|
+
if key not in _DROPPED_SCHEMA_KEYS
|
|
89
|
+
}
|
|
90
|
+
if isinstance(node, list):
|
|
91
|
+
return [_clean_node(item) for item in node]
|
|
92
|
+
return node
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
@dataclass(frozen=True)
|
|
96
|
+
class RegisteredTool:
|
|
97
|
+
"""注册表条目:声明 + 执行器 + 来源。"""
|
|
98
|
+
|
|
99
|
+
spec: ToolSpec
|
|
100
|
+
handler: ToolHandler
|
|
101
|
+
kind: ToolKind = "local"
|
|
102
|
+
approval_target: str | None = None
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
class ToolRegistry:
|
|
106
|
+
"""工具注册表(非线程安全,单 Agent 实例内使用)。"""
|
|
107
|
+
|
|
108
|
+
def __init__(self) -> None:
|
|
109
|
+
self._tools: dict[str, RegisteredTool] = {}
|
|
110
|
+
|
|
111
|
+
def register(
|
|
112
|
+
self,
|
|
113
|
+
spec: ToolSpec,
|
|
114
|
+
handler: ToolHandler,
|
|
115
|
+
*,
|
|
116
|
+
kind: ToolKind = "local",
|
|
117
|
+
approval_target: str | None = None,
|
|
118
|
+
replace: bool = False,
|
|
119
|
+
) -> None:
|
|
120
|
+
"""注册单个工具。
|
|
121
|
+
|
|
122
|
+
Raises:
|
|
123
|
+
ValueError: 名称重复且未指定 ``replace=True``。
|
|
124
|
+
"""
|
|
125
|
+
name = sanitize_tool_name(spec.name)
|
|
126
|
+
existing = self._tools.get(name)
|
|
127
|
+
if existing is not None and not replace:
|
|
128
|
+
raise ValueError(
|
|
129
|
+
f"工具名重复: {name}"
|
|
130
|
+
f"(已有来源 {existing.kind},本次来源 {kind})"
|
|
131
|
+
)
|
|
132
|
+
schema = clean_schema(spec.input_schema)
|
|
133
|
+
if schema is None:
|
|
134
|
+
logger.warning(
|
|
135
|
+
f"工具 {name} 的 input_schema 缺失或不是 object,已跳过注册"
|
|
136
|
+
)
|
|
137
|
+
return
|
|
138
|
+
self._tools[name] = RegisteredTool(
|
|
139
|
+
spec=ToolSpec(
|
|
140
|
+
name=name,
|
|
141
|
+
description=spec.description.strip() or name,
|
|
142
|
+
input_schema=schema,
|
|
143
|
+
),
|
|
144
|
+
handler=handler,
|
|
145
|
+
kind=kind,
|
|
146
|
+
approval_target=approval_target,
|
|
147
|
+
)
|
|
148
|
+
|
|
149
|
+
def register_many(
|
|
150
|
+
self,
|
|
151
|
+
entries: Iterable[tuple[ToolSpec, ToolHandler]],
|
|
152
|
+
*,
|
|
153
|
+
kind: ToolKind = "local",
|
|
154
|
+
) -> None:
|
|
155
|
+
"""批量注册(单个失败即抛出,不做部分回滚)。"""
|
|
156
|
+
for spec, handler in entries:
|
|
157
|
+
self.register(spec, handler, kind=kind)
|
|
158
|
+
|
|
159
|
+
def specs(self) -> list[ToolSpec]:
|
|
160
|
+
"""按注册顺序返回全部工具声明。"""
|
|
161
|
+
return [entry.spec for entry in self._tools.values()]
|
|
162
|
+
|
|
163
|
+
def names(self) -> list[str]:
|
|
164
|
+
"""按注册顺序返回全部工具名。"""
|
|
165
|
+
return list(self._tools)
|
|
166
|
+
|
|
167
|
+
def get(self, name: str) -> RegisteredTool:
|
|
168
|
+
"""按名取条目。
|
|
169
|
+
|
|
170
|
+
Raises:
|
|
171
|
+
ToolNotFoundError: 工具未注册。
|
|
172
|
+
"""
|
|
173
|
+
entry = self._tools.get(name)
|
|
174
|
+
if entry is None:
|
|
175
|
+
raise ToolNotFoundError(f"未注册的工具: {name}")
|
|
176
|
+
return entry
|
|
177
|
+
|
|
178
|
+
async def call(self, name: str, arguments: dict[str, Any]) -> ToolResult:
|
|
179
|
+
"""调用工具;handler 异常统一包装为 ``ToolExecutionError``。"""
|
|
180
|
+
entry = self.get(name)
|
|
181
|
+
try:
|
|
182
|
+
result = await entry.handler(arguments)
|
|
183
|
+
except ToolExecutionError:
|
|
184
|
+
raise
|
|
185
|
+
except Exception as exc: # noqa: BLE001 - 工具异常统一转为 Agent 异常
|
|
186
|
+
raise ToolExecutionError(
|
|
187
|
+
f"工具 {name} 执行失败: {type(exc).__name__}: {exc}"
|
|
188
|
+
) from exc
|
|
189
|
+
if isinstance(result, ToolResult):
|
|
190
|
+
return result
|
|
191
|
+
if isinstance(result, str):
|
|
192
|
+
return ToolResult(content=result)
|
|
193
|
+
raise ToolExecutionError(f"工具 {name} 返回了非法结果类型: {type(result)!r}")
|
|
194
|
+
|
|
195
|
+
def __contains__(self, name: object) -> bool:
|
|
196
|
+
return name in self._tools
|
|
197
|
+
|
|
198
|
+
def __len__(self) -> int:
|
|
199
|
+
return len(self._tools)
|
|
200
|
+
|
|
201
|
+
def entries(self) -> Sequence[RegisteredTool]:
|
|
202
|
+
"""只读条目快照(供 Agent 合并注册表)。"""
|
|
203
|
+
return tuple(self._tools.values())
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
# date: 2026-11-10
|
|
21
|
+
"""内存会话窗口:消息累积 + 轮数/字符截断。
|
|
22
|
+
|
|
23
|
+
只做内存窗口管理:不持久化、不跨会话召回、不做摘要(摘要需要额外模型
|
|
24
|
+
调用,v1 不引入隐式成本)。
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import json
|
|
28
|
+
from typing import Any
|
|
29
|
+
|
|
30
|
+
from yimo.kit.ai.messages import AssistantMessage, Message, ToolCall
|
|
31
|
+
|
|
32
|
+
__all__ = ["Session"]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class Session:
|
|
36
|
+
"""一次对话的消息窗口。
|
|
37
|
+
|
|
38
|
+
Args:
|
|
39
|
+
system_prompt: 系统提示;为 None 时不插入 system 消息
|
|
40
|
+
max_rounds: 保留的最近用户轮数;None 不限制
|
|
41
|
+
max_chars: 保留消息的总字符上限;None 不限制。超限时从最旧轮开始丢,
|
|
42
|
+
system 消息永不丢;单轮超限时保留该轮(不能拆散工具调用配对)
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
def __init__(
|
|
46
|
+
self,
|
|
47
|
+
system_prompt: str | None = None,
|
|
48
|
+
*,
|
|
49
|
+
max_rounds: int | None = 20,
|
|
50
|
+
max_chars: int | None = None,
|
|
51
|
+
) -> None:
|
|
52
|
+
if max_rounds is not None and max_rounds < 1:
|
|
53
|
+
raise ValueError("max_rounds 必须 >= 1")
|
|
54
|
+
if max_chars is not None and max_chars < 1:
|
|
55
|
+
raise ValueError("max_chars 必须 >= 1")
|
|
56
|
+
self._system_prompt: str | None = system_prompt or None
|
|
57
|
+
self._max_rounds: int | None = max_rounds
|
|
58
|
+
self._max_chars: int | None = max_chars
|
|
59
|
+
self._messages: list[Message] = []
|
|
60
|
+
if self._system_prompt:
|
|
61
|
+
self._messages.append({"role": "system", "content": self._system_prompt})
|
|
62
|
+
|
|
63
|
+
# ------------------------------------------------------------------
|
|
64
|
+
# 写入
|
|
65
|
+
# ------------------------------------------------------------------
|
|
66
|
+
|
|
67
|
+
def add_user(self, text: str) -> None:
|
|
68
|
+
"""追加一条用户消息。"""
|
|
69
|
+
self._messages.append({"role": "user", "content": text})
|
|
70
|
+
|
|
71
|
+
def add_assistant(
|
|
72
|
+
self, text: str | None, tool_calls: list[ToolCall] | None = None
|
|
73
|
+
) -> None:
|
|
74
|
+
"""追加一条助手消息(可同时携带工具调用)。"""
|
|
75
|
+
message: AssistantMessage = {"role": "assistant", "content": text}
|
|
76
|
+
if tool_calls:
|
|
77
|
+
message["tool_calls"] = list(tool_calls)
|
|
78
|
+
self._messages.append(message)
|
|
79
|
+
|
|
80
|
+
def add_tool(self, tool_call_id: str, text: str) -> None:
|
|
81
|
+
"""追加一条工具结果消息。"""
|
|
82
|
+
self._messages.append(
|
|
83
|
+
{"role": "tool", "content": text, "tool_call_id": tool_call_id}
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
def clear(self) -> None:
|
|
87
|
+
"""清空对话,仅保留 system 消息。"""
|
|
88
|
+
self._messages = []
|
|
89
|
+
if self._system_prompt:
|
|
90
|
+
self._messages.append({"role": "system", "content": self._system_prompt})
|
|
91
|
+
|
|
92
|
+
# ------------------------------------------------------------------
|
|
93
|
+
# 读取
|
|
94
|
+
# ------------------------------------------------------------------
|
|
95
|
+
|
|
96
|
+
def messages(self) -> list[Message]:
|
|
97
|
+
"""返回截断后的消息副本(system 始终保留在最前)。"""
|
|
98
|
+
system: list[Message] = []
|
|
99
|
+
body: list[Message] = []
|
|
100
|
+
for message in self._messages:
|
|
101
|
+
if message["role"] == "system":
|
|
102
|
+
system.append(message)
|
|
103
|
+
else:
|
|
104
|
+
body.append(message)
|
|
105
|
+
|
|
106
|
+
groups = _split_rounds(body)
|
|
107
|
+
if self._max_rounds is not None and len(groups) > self._max_rounds:
|
|
108
|
+
groups = groups[-self._max_rounds :]
|
|
109
|
+
|
|
110
|
+
if self._max_chars is not None:
|
|
111
|
+
kept = _flatten(groups)
|
|
112
|
+
total = sum(_message_chars(message) for message in system + kept)
|
|
113
|
+
while groups and total > self._max_chars and len(groups) > 1:
|
|
114
|
+
dropped = groups.pop(0)
|
|
115
|
+
total -= sum(_message_chars(message) for message in dropped)
|
|
116
|
+
|
|
117
|
+
return [dict(message) for message in system + _flatten(groups)]
|
|
118
|
+
|
|
119
|
+
def __len__(self) -> int:
|
|
120
|
+
return len(self._messages)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def _split_rounds(messages: list[Message]) -> list[list[Message]]:
|
|
124
|
+
"""按 user 消息切轮;第一条 user 之前的内容单独成组。"""
|
|
125
|
+
groups: list[list[Message]] = []
|
|
126
|
+
current: list[Message] = []
|
|
127
|
+
for message in messages:
|
|
128
|
+
if message["role"] == "user" and current:
|
|
129
|
+
groups.append(current)
|
|
130
|
+
current = []
|
|
131
|
+
current.append(message)
|
|
132
|
+
if current:
|
|
133
|
+
groups.append(current)
|
|
134
|
+
return groups
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _flatten(groups: list[list[Message]]) -> list[Message]:
|
|
138
|
+
return [message for group in groups for message in group]
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _message_chars(message: Message) -> int:
|
|
142
|
+
"""消息字符数:正文 + 工具调用参数的 JSON 长度。"""
|
|
143
|
+
total = len(message.get("content") or "")
|
|
144
|
+
tool_calls: Any = message.get("tool_calls")
|
|
145
|
+
if tool_calls:
|
|
146
|
+
try:
|
|
147
|
+
total += len(json.dumps(tool_calls, ensure_ascii=False))
|
|
148
|
+
except (TypeError, ValueError):
|
|
149
|
+
total += len(str(tool_calls))
|
|
150
|
+
return total
|