specmodule 0.3.0__tar.gz → 0.5.0__tar.gz

{specmodule-0.3.0/specmodule.egg-info → specmodule-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.3.0
+Version: 0.5.0
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tickflow-py<0.3,>=0.2.0
+Requires-Dist: tickflow-py<0.4,>=0.3.0
 Provides-Extra: anthropic
 Requires-Dist: anthropic; extra == "anthropic"
 Provides-Extra: openai

{specmodule-0.3.0 → specmodule-0.5.0}/llm/client.py

@@ -136,6 +136,76 @@ def _safe_on_token(on_token: Callable[[str], None] | None, chunk: str) -> None:
         log.exception("on_token 回调异常；已忽略")
 
 
+def _safe_on_thinking(on_thinking: Callable[[str], None] | None, chunk: str) -> None:
+    """调用 on_thinking，回调异常不得影响主流程（同 _safe_on_token）。"""
+    if on_thinking is None or not chunk:
+        return
+    try:
+        on_thinking(chunk)
+    except Exception:
+        log.exception("on_thinking 回调异常；已忽略")
+
+
+class _ThinkTagStripper:
+    """跨 chunk 安全的内联 ``<think>…</think>`` 剥离器。
+
+    部分兼容网关不单设 reasoning 通道，思考文本带标签内联在 content 里。
+    feed() 逐 chunk 喂入，返回 (content_delta, thinking_delta)：标签外增量
+    归 content、标签内增量归 thinking；hold-back 缓冲处理标签自身被 chunk
+    劈开的情况；flush() 在流结束吐出残留（未闭合标签按思考处理）。
+    """
+
+    _OPEN = "<think>"
+    _CLOSE = "</think>"
+
+    def __init__(self) -> None:
+        self._inside = False
+        self._buf = ""      # hold-back：可能是未判定标签前缀的尾部
+
+    def feed(self, chunk: str) -> tuple[str, str]:
+        self._buf += chunk
+        content_parts: list[str] = []
+        thinking_parts: list[str] = []
+        while self._buf:
+            if self._inside:
+                end = self._buf.find(self._CLOSE)
+                if end >= 0:
+                    thinking_parts.append(self._buf[:end])
+                    self._buf = self._buf[end + len(self._CLOSE):]
+                    self._inside = False
+                    continue
+                keep = self._holdback(self._CLOSE)
+            else:
+                start = self._buf.find(self._OPEN)
+                if start >= 0:
+                    content_parts.append(self._buf[:start])
+                    self._buf = self._buf[start + len(self._OPEN):]
+                    self._inside = True
+                    continue
+                keep = self._holdback(self._OPEN)
+            emit = len(self._buf) - keep
+            if emit:
+                (thinking_parts if self._inside else content_parts).append(self._buf[:emit])
+                self._buf = self._buf[emit:]
+            break
+        return "".join(content_parts), "".join(thinking_parts)
+
+    def flush(self) -> tuple[str, str]:
+        """流结束：按当前内/外状态吐出残留 hold-back。"""
+        if not self._buf:
+            return "", ""
+        out = self._buf
+        self._buf = ""
+        return ("", out) if self._inside else (out, "")
+
+    def _holdback(self, tag: str) -> int:
+        """缓冲尾部可能是 tag 真前缀的最大长度（ TagLen-1 向下探）。"""
+        for n in range(min(len(self._buf), len(tag) - 1), 0, -1):
+            if tag.startswith(self._buf[-n:]):
+                return n
+        return 0
+
+
 # ---------------------------------------------------------------------------
 # Anthropic 客户端
 # ---------------------------------------------------------------------------
@@ -235,6 +305,7 @@ class AnthropicClient:
         output_format: dict[str, Any] | None = None,
         notdo: list[str] | None = None,
         on_token: Callable[[str], None] | None = None,
+        on_thinking: Callable[[str], None] | None = None,
         api_params: dict[str, Any] | None = None,
     ) -> LLMResponse:
         """单轮调用入口（harness body 用）。
@@ -242,7 +313,8 @@ class AnthropicClient:
         - ``prompt``：三层渲染后的用户提示词
         - ``model``/``temperature``/``think``：按调用覆盖，缺省回落 config
         - ``output_format``：原生结构化输出（强制 tool-use）
-        - ``on_token``：流式 token 回调（提供时走流式接口）
+        - ``on_token``/``on_thinking``：流式 token/思考增量回调（任一提供即走流式接口；
+          thinking_delta → on_thinking，text_delta → on_token；回调异常不破主流程）
         - ``api_params``：透传给 SDK 的额外参数（已知字段入 kwargs，未知入 extra_body）
         """
         self._require_ready()
@@ -282,8 +354,8 @@ class AnthropicClient:
         _apply_api_params(kwargs, api_params, _KNOWN_ANTHROPIC_PARAMS)
 
         try:
-            if on_token:
-                content, tool_calls, usage, finish = await self._stream(kwargs, forced_tool, on_token)
+            if on_token or on_thinking:
+                content, tool_calls, usage, finish = await self._stream(kwargs, forced_tool, on_token, on_thinking)
             else:
                 content, tool_calls, usage, finish = await self._nonstream(kwargs, forced_tool)
         except LLMError:
@@ -309,13 +381,22 @@ class AnthropicClient:
         }
         return content, tool_calls, usage, response.stop_reason
 
-    async def _stream(self, kwargs: dict, forced_tool: str | None, on_token) -> tuple:
+    async def _stream(self, kwargs: dict, forced_tool: str | None, on_token, on_thinking) -> tuple:
         content = ""
         tool_calls: list[dict[str, Any]] = []
         async with self._client.messages.stream(**kwargs) as stream:
-            async for text in stream.text_stream:
-                content += text
-                _safe_on_token(on_token, text)
+            async for event in stream:
+                delta = getattr(event, "delta", None)
+                dtype = getattr(delta, "type", None)
+                if dtype == "thinking_delta":
+                    piece = getattr(delta, "thinking", None) or ""
+                    if piece:
+                        _safe_on_thinking(on_thinking, piece)
+                elif dtype == "text_delta":
+                    text = getattr(delta, "text", "") or ""
+                    if text:
+                        content += text
+                        _safe_on_token(on_token, text)
             final = await stream.get_final_message()
         for block in final.content:
             if block.type == "tool_use":
@@ -328,15 +409,36 @@ class AnthropicClient:
         }
         return content, tool_calls, usage, final.stop_reason
 
-    # --- 多轮底层接口（保留供对齐检查 / spec 翻译等 LLM 调用复用） -------------
+    # --- 多轮底层接口（首个正当消费端 = agent 工具循环；spec 翻译 / 对齐检查等 LLM 调用亦复用） -------------
 
     def _convert_messages(self, messages: list[Message]) -> tuple[str | None, list[dict[str, Any]]]:
-        """分离 system 消息并转换其余消息。"""
+        """分离 system 消息并转换其余消息；工具循环形状：assistant+tool_calls →
+        tool_use 内容块，tool 角色 → tool_result 用户消息块（Anthropic 契约）。
+        连续 tool 消息聚合为一条 user 消息（多个 tool_result 块）——Anthropic 要求
+        消息角色交替，逐条拆开会 400（Bedrock 实测）。"""
         system_prompt = None
         api_messages = []
         for msg in messages:
             if msg.role == "system":
                 system_prompt = msg.content
+            elif msg.role == "assistant" and msg.tool_calls:
+                blocks: list[dict[str, Any]] = []
+                if msg.content:
+                    blocks.append({"type": "text", "text": msg.content})
+                for tc in msg.tool_calls:
+                    blocks.append({"type": "tool_use", "id": tc["id"],
+                                   "name": tc["name"], "input": tc.get("arguments", {})})
+                api_messages.append({"role": "assistant", "content": blocks})
+            elif msg.role == "tool":
+                result = {"type": "tool_result", "tool_use_id": msg.tool_call_id or "",
+                          "content": msg.content}
+                last = api_messages[-1] if api_messages else None
+                # 连续 tool 消息并入同一条 user 消息（角色交替契约，见 docstring）
+                if last and last["role"] == "user" and isinstance(last["content"], list) \
+                        and last["content"] and last["content"][0]["type"] == "tool_result":
+                    last["content"].append(result)
+                else:
+                    api_messages.append({"role": "user", "content": [result]})
             else:
                 api_messages.append({"role": msg.role, "content": msg.content})
         return system_prompt, api_messages
@@ -514,6 +616,7 @@ class OpenAIClient:
         output_format: dict[str, Any] | None = None,
         notdo: list[str] | None = None,
         on_token: Callable[[str], None] | None = None,
+        on_thinking: Callable[[str], None] | None = None,
         api_params: dict[str, Any] | None = None,
     ) -> LLMResponse:
         """单轮调用入口（harness body 用）。
@@ -523,6 +626,10 @@ class OpenAIClient:
         - ``think``：reasoning 模型映射为 ``reasoning_effort``（"low"/"medium"/"high"，
           dict 可指定 ``effort``；非 reasoning 模型忽略）
         - ``api_params``：透传给 SDK 的额外参数（已知字段入 kwargs，未知入 extra_body）
+        - ``on_thinking``：思考/推理增量回调（reasoning_content/reasoning 方言 +
+          content 内联 <think> 剥离；Anthropic thinking_delta）；流式/非流式路径均
+          无条件剥离内联 <think> 标签，返回 content 不含思考文本（含仅传 on_token
+          的存量调用）；仅传 on_token 时思考增量静默丢弃；回调异常不破主流程
         """
         self._require_ready()
         model = model or self.config.model
@@ -562,8 +669,8 @@ class OpenAIClient:
         _apply_api_params(kwargs, api_params, _KNOWN_OPENAI_PARAMS)
 
         try:
-            if on_token:
-                content, tool_calls, usage, finish = await self._stream(kwargs, on_token)
+            if on_token or on_thinking:
+                content, tool_calls, usage, finish = await self._stream(kwargs, on_token, on_thinking)
             else:
                 content, tool_calls, usage, finish = await self._nonstream(kwargs)
         except LLMError:
@@ -576,6 +683,11 @@ class OpenAIClient:
         response = await self._client.chat.completions.create(**kwargs)
         choice = response.choices[0]
         content = choice.message.content or ""
+        # 内联 <think> 剥离与流式路径对齐：完整文本过一遍剥离器，返回 content 不含思考文本
+        stripper = _ThinkTagStripper()
+        c_text, _ = stripper.feed(content)
+        tail_c, _ = stripper.flush()
+        content = c_text + tail_c
         tool_calls: list[dict[str, Any]] = []
         if choice.message.tool_calls:
             for tc in choice.message.tool_calls:
@@ -590,7 +702,7 @@ class OpenAIClient:
         }
         return content, tool_calls, usage, choice.finish_reason
 
-    async def _stream(self, kwargs: dict, on_token) -> tuple:
+    async def _stream(self, kwargs: dict, on_token, on_thinking) -> tuple:
         kwargs["stream"] = True
         # stream_options 仅官方 OpenAI 必然支持；兼容接口（base_url 非空）省略以免被拒
         if not self.config.base_url:
@@ -599,6 +711,7 @@ class OpenAIClient:
         tool_calls: list[dict[str, Any]] = []
         usage: dict[str, int] = {}
         finish: str | None = None
+        stripper = _ThinkTagStripper()
         stream = await self._client.chat.completions.create(**kwargs)
         async for chunk in stream:
             if chunk.usage:
@@ -609,11 +722,26 @@ class OpenAIClient:
             if not chunk.choices:
                 continue
             delta = chunk.choices[0].delta
+            # 思考增量：DeepSeek/Kimi 的 reasoning_content，部分网关用 reasoning；
+            # 无原生通道时由 <think> 剥离器从 content 转移（见下）
+            reasoning = getattr(delta, "reasoning_content", None) or getattr(delta, "reasoning", None)
+            if reasoning:
+                _safe_on_thinking(on_thinking, reasoning)
             if delta.content:
-                content += delta.content
-                _safe_on_token(on_token, delta.content)
+                c_delta, t_delta = stripper.feed(delta.content)
+                content += c_delta        # 返回值用剥离后文本（思考不泄入 JSON 输出）
+                if c_delta:
+                    _safe_on_token(on_token, c_delta)
+                if t_delta:
+                    _safe_on_thinking(on_thinking, t_delta)
             if chunk.choices[0].finish_reason:
                 finish = chunk.choices[0].finish_reason
+        tail_c, tail_t = stripper.flush()
+        if tail_c:
+            content += tail_c
+            _safe_on_token(on_token, tail_c)
+        if tail_t:
+            _safe_on_thinking(on_thinking, tail_t)
         return content, tool_calls, usage, finish
 
     # --- 多轮底层接口 -------------------------------------------------------
@@ -764,6 +892,7 @@ class RoutingClient:
         output_format: dict[str, Any] | None = None,
         notdo: list[str] | None = None,
         on_token: Callable[[str], None] | None = None,
+        on_thinking: Callable[[str], None] | None = None,
         api_params: dict[str, Any] | None = None,
     ) -> LLMResponse:
         """单轮调用(harness body 入口),按调用模型路由。"""
@@ -776,6 +905,7 @@ class RoutingClient:
             output_format=output_format,
             notdo=notdo,
             on_token=on_token,
+            on_thinking=on_thinking,
             api_params=api_params,
         )
 

{specmodule-0.3.0 → specmodule-0.5.0}/module_harness/__init__.py

@@ -38,6 +38,7 @@ from .infra.events import (
     PromptRendered,
     LlmCallStarted,
     LlmToken,
+    LlmThinking,
     LlmCallCompleted,
     OutputValidated,
     ImageSaved,
@@ -104,7 +105,7 @@ from .infra.store import (
 )
 # cli 层（CLI 实现，非库面）
 from .cli.command import Command, CommandConfig
-from .cli.entry import ModuleEntry, discover_modules
+from .cli.entry import ModuleEntry, TemplateSpec, discover_modules
 from .cli.loader import ModuleLoader, ModuleManifestError, ModuleRequirementError
 
 # 模块对象绑定（`from module_harness import store / submodule / query` 可用；
@@ -131,6 +132,7 @@ __all__ = [
     "PromptRendered",
     "LlmCallStarted",
     "LlmToken",
+    "LlmThinking",
     "LlmCallCompleted",
     "OutputValidated",
     "ImageSaved",
@@ -198,6 +200,7 @@ __all__ = [
     "check_resume_compat_from_run",
     # 模块入口（roadmap Phase 0：CLI 使用）
     "ModuleEntry",
+    "TemplateSpec",
     "discover_modules",
     # 共享查询层（roadmap Phase 0：CLI/MCP/Web 复用）
     "ReviewEntry",