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.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -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