pynanoagent 0.1.0.dev0__py3-none-any.whl

nanoagent/__init__.py

@@ -0,0 +1,24 @@
+"""nanoagent —— 一个核心循环 ~30 行的 ReAct 单 agent 框架。
+
+常用入口：
+
+    from nanoagent import Agent, tool
+
+    @tool
+    def word_count(path: str) -> int:
+        '''统计文本文件的单词数。'''
+        return len(open(path).read().split())
+
+    agent = Agent("gpt-4o-mini", tools=[word_count])
+    print(agent.run("统计 README.md 有多少单词").output)
+
+一次性任务用 Agent.run；多轮对话用 Agent(...).session().send（见 DESIGN §5.6）。
+全部核心契约与数据结构在 ``nanoagent.core``。
+"""
+
+__version__ = "0.1.0.dev0"
+
+from nanoagent.api import Agent, ChatSession
+from nanoagent.tools import tool
+
+__all__ = ["Agent", "ChatSession", "tool", "__version__"]

nanoagent/api.py

@@ -0,0 +1,93 @@
+"""api.py —— 唯一「知道全部模块」的装配层（不在 core 内，可 import 全部）。
+
+把字符串模型名解析成 LLMClient（core 永远只见解析后的客户端），并提供两个平级入口：
+  - Agent       ：一次性任务，每次 run 新建 Context（跨 run 无记忆、相互隔离）；
+  - ChatSession ：多轮对话，复用同一个 Context（带记忆）。
+二者共享同一个无状态 AgentLoop——状态归 Context、编排归 Loop（DESIGN §5.6 / §14.3-Q3）。
+"""
+from __future__ import annotations
+
+import os
+
+from nanoagent.core import AgentLoop, AgentResult, Context, Message
+
+# 内置默认 system prompt（放装配层、不进 core）；Agent(system_prompt=...) 可整体覆盖，传 "" 则不加。
+DEFAULT_SYSTEM_PROMPT = (
+    "你是一个能调用工具完成任务的助手。需要外部信息或操作时，调用合适的工具，"
+    "不要编造工具的返回结果；信息齐了就用自然语言直接回答。"
+    "当你不再需要调用工具、直接给出答复时，本轮任务即视为结束。"
+)
+
+
+# 按模型名前缀自动选 OpenAI 兼容端点：(前缀, base_url, 专属 api_key 环境变量)。
+# 命中则自动配 base_url、并优先读该供应商的 key（没有则回落到 OpenAI SDK 默认的 OPENAI_API_KEY）。
+_PROVIDERS = [
+    ("deepseek", "https://api.deepseek.com", "DEEPSEEK_API_KEY"),
+    ("moonshot", "https://api.moonshot.cn/v1", "MOONSHOT_API_KEY"),
+    ("kimi", "https://api.moonshot.cn/v1", "MOONSHOT_API_KEY"),
+]
+
+
+def _detect_endpoint(model: str):
+    """按模型名前缀推断 (base_url, api_key 环境变量名)；未命中返回 (None, None)＝OpenAI 默认。"""
+    for prefix, base_url, key_env in _PROVIDERS:
+        if model.startswith(prefix):
+            return base_url, key_env
+    return None, None
+
+
+def resolve_model(model):
+    """字符串模型名 → LLMClient；已是 LLMClient 则原样返回。
+
+    自动选端点：模型名以已知前缀开头（如 ``deepseek-chat``）时，自动配好对应 base_url，
+    只需设供应商 key（DeepSeek 用 DEEPSEEK_API_KEY，没有则回落 OPENAI_API_KEY）即可。
+    显式 ``OPENAI_BASE_URL`` 环境变量优先级最高，可覆盖自动判断、接任意自建/未知端点。
+    """
+    if not isinstance(model, str):
+        return model
+    from nanoagent.llm import OpenAICompatClient   # 懒加载：仅用真实客户端时才需 openai
+
+    base_url = os.environ.get("OPENAI_BASE_URL")          # 显式覆盖优先
+    api_key = None
+    if base_url is None:
+        base_url, key_env = _detect_endpoint(model)        # 按模型名自动选端点
+        if key_env:
+            api_key = os.environ.get(key_env)              # 供应商专属 key；None 时 SDK 回落 OPENAI_API_KEY
+    return OpenAICompatClient(model, base_url=base_url, api_key=api_key)
+
+
+class Agent:
+    """一次性任务的入口：每次 run 新建 Context（跨 run 无记忆、相互隔离）。
+
+    「无状态」指跨 run；单次 run 内仍是多轮 ReAct。本类只持有配置（loop + system_prompt）。
+    """
+
+    def __init__(self, model, tools=None, *, system_prompt: str | None = None,
+                 hooks=None, stop=None, max_turns: int = 20):
+        self._loop = AgentLoop(resolve_model(model), tools or [], hooks, stop, max_turns)
+        # None → 用内置默认 prompt；显式 "" 则不加 system 消息
+        self._system = DEFAULT_SYSTEM_PROMPT if system_prompt is None else system_prompt
+
+    def run(self, prompt: str) -> AgentResult:
+        ctx = Context()
+        if self._system:
+            ctx.add(Message(role="system", content=self._system, pinned=True))
+        ctx.add(Message(role="user", content=prompt))
+        return self._loop.run(ctx)
+
+    def session(self) -> "ChatSession":          # 便捷工厂：复用同一个 loop 开个有状态会话（非「包含」ChatSession）
+        return ChatSession(self._loop, self._system)
+
+
+class ChatSession:
+    """多轮对话入口：与 Agent 平级，复用同一个无状态 AgentLoop + 持续累积的同一个 Context。"""
+
+    def __init__(self, loop: AgentLoop, system_prompt: str | None = None):
+        self._loop = loop
+        self.ctx = Context()
+        if system_prompt:
+            self.ctx.add(Message(role="system", content=system_prompt, pinned=True))
+
+    def send(self, prompt: str) -> AgentResult:
+        self.ctx.add(Message(role="user", content=prompt))
+        return self._loop.run(self.ctx)          # 原地增长同一个 ctx

nanoagent/cli/__init__.py

@@ -0,0 +1 @@
+"""cli/ —— 命令行 REPL。薄封装：重逻辑都在可单测的 api 层。"""

nanoagent/cli/main.py

@@ -0,0 +1,65 @@
+"""命令行入口：`nanoagent` 命令（pyproject [project.scripts] → cli.main:main）。
+
+v0.1 基础版用标准库 input() 做 REPL（prompt-toolkit 的补全 / 历史留作后续打磨）；
+底层是一个 ChatSession，整段对话复用同一个 Context（记得上文）。
+配置：模型读 NANOAGENT_MODEL（默认 gpt-4o-mini）；API key 读 OPENAI_API_KEY；
+切 DeepSeek 等端点用 OPENAI_BASE_URL（如 https://api.deepseek.com）。
+"""
+from __future__ import annotations
+
+import os
+
+from nanoagent import __version__
+
+
+_PROVIDER_KEYS = ("OPENAI_API_KEY", "DEEPSEEK_API_KEY", "MOONSHOT_API_KEY")
+
+
+def _default_model() -> str:
+    """没显式设 NANOAGENT_MODEL 时，按已设的供应商 key 猜默认模型
+    （设了 DEEPSEEK_API_KEY 就用 deepseek-chat，端点会被自动识别，无需再设模型名）。"""
+    explicit = os.environ.get("NANOAGENT_MODEL")
+    if explicit:
+        return explicit
+    if os.environ.get("DEEPSEEK_API_KEY"):
+        return "deepseek-chat"
+    if os.environ.get("MOONSHOT_API_KEY"):
+        return "moonshot-v1-8k"
+    return "gpt-4o-mini"
+
+
+def main() -> None:
+    from prompt_toolkit import PromptSession
+    from nanoagent.api import Agent
+    from nanoagent.tools.builtin import BUILTIN_TOOLS
+
+    model = _default_model()
+    if not any(os.environ.get(k) for k in _PROVIDER_KEYS):
+        print("⚠️  未检测到 API key（设 OPENAI_API_KEY / DEEPSEEK_API_KEY 之一即可）。")
+
+    chat = Agent(model, tools=BUILTIN_TOOLS).session()
+    print(f"nanoagent {__version__} · 模型 {model} — 输入问题开始对话（Ctrl-D / Ctrl-C 退出）")
+
+    # 用 prompt_toolkit 而非 input()：方向键 / 行编辑 / 历史，且正确解码 UTF-8 输入
+    # （input() 在非 UTF-8 locale 下、或按方向键时会把转义序列/坏字节读进字符串，导致请求编码崩溃）。
+    repl = PromptSession()
+    while True:
+        try:
+            prompt = repl.prompt("> ").strip()
+            if not prompt:
+                continue
+            result = chat.send(prompt)
+        except (EOFError, KeyboardInterrupt):     # Ctrl-D / Ctrl-C（等输入或调模型时都算）→ 干净退出
+            print()
+            break
+        except Exception as e:                    # 单轮业务出错只提示、不退出整个 REPL
+            print(f"⚠️  出错：{type(e).__name__}: {e}")
+            continue
+        print(result.output)
+        total = result.usage.get("total_tokens")
+        if total:
+            print(f"  （{result.turns} 轮 · {total} tokens）")
+
+
+if __name__ == "__main__":
+    main()

nanoagent/core/__init__.py

@@ -0,0 +1,48 @@
+"""核心层 —— 数年不变的稳定部分。
+
+本包不得 import 任何外层目录（strategies / tools / llm / memory / cli / api）：
+依赖只能从外层指向 core（见 DESIGN §4.1、§8.1，CI 用 import-linter / grep 守）。
+策略 Protocol（ContextStrategy / PermissionStrategy / StopStrategy）属契约、放本包；
+它们的实现属 strategies/。
+"""
+
+from nanoagent.core.message import LLMResponse, Message, ToolCall, ToolResult
+from nanoagent.core.stop import StopReason
+from nanoagent.core.context import AgentResult, Context
+from nanoagent.core.hooks import BaseHook, Hook, ToolDecision
+from nanoagent.core.protocols import (
+    ContextStrategy,
+    LLMClient,
+    MemoryBackend,
+    PermissionStrategy,
+    StopStrategy,
+    Tool,
+)
+from nanoagent.core.errors import FatalError, NanoAgentError
+from nanoagent.core.loop import AgentLoop
+
+__all__ = [
+    # 数据结构
+    "ToolCall",
+    "ToolResult",
+    "Message",
+    "LLMResponse",
+    "Context",
+    "AgentResult",
+    "AgentLoop",
+    "StopReason",
+    # Hook
+    "ToolDecision",
+    "Hook",
+    "BaseHook",
+    # 能力 / 策略契约
+    "LLMClient",
+    "Tool",
+    "MemoryBackend",
+    "ContextStrategy",
+    "PermissionStrategy",
+    "StopStrategy",
+    # 异常
+    "NanoAgentError",
+    "FatalError",
+]

nanoagent/core/context.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from nanoagent.core.message import Message
+from nanoagent.core.stop import StopReason
+
+
+@dataclass
+class Context:
+    """一次 agent 运行的上下文。
+
+    messages 是 append-only 事件日志（完整历史，策略不得删改）；
+    view() 才是真正发给 LLM 的消息——v0.1 等于全量，v0.3 由上下文策略投影裁剪。
+    """
+
+    messages: list[Message] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    usage: dict[str, int] = field(default_factory=dict)   # 跨轮累计 token（熔断/显示用量的唯一入口）
+    summary: str | None = None                            # v0.1 占位：承载 v0.3 压缩摘要产物
+    _rendered: list[Message] | None = field(default=None, repr=False)  # before_model 写入的裁剪视图
+
+    def add(self, message: Message) -> None:
+        self.messages.append(message)
+        self._rendered = None             # 历史变了，作废旧投影，下次 view() 回落到全量
+
+    def add_usage(self, usage: dict[str, int]) -> None:
+        for k, v in usage.items():
+            self.usage[k] = self.usage.get(k, 0) + v
+
+    def view(self) -> list[Message]:
+        """真正发给 LLM 的消息。v0.1：identity=全量历史。
+        v0.3：before_model 里的上下文策略调用 set_view() 写入裁剪结果。"""
+        return self._rendered if self._rendered is not None else self.messages
+
+    def set_view(self, messages: list[Message]) -> None:
+        """由 before_model 的上下文策略调用，提交本轮发给模型的投影（不改 messages）。"""
+        self._rendered = messages
+
+
+@dataclass
+class AgentResult:
+    """一次 agent 运行的最终结果。"""
+
+    context: Context
+    stop_reason: StopReason
+    turns: int = 0                                        # 实际执行轮数（供 CLI 显示「N 轮」）
+    usage: dict[str, int] = field(default_factory=dict)   # 跨轮累计 token（供 CLI 显示用量）
+
+    @property
+    def output(self) -> str:
+        # 回扫最后一条「有内容的 assistant 文本」，避免在 MAX_TURNS（末条是工具结果）
+        # 或权限拒绝（末条是 denial）时把非答复内容误当成输出。
+        for m in reversed(self.context.messages):
+            if m.role == "assistant" and m.content:
+                return m.content
+        return "" if self.stop_reason is StopReason.DONE else f"[未完成：{self.stop_reason.value}]"

nanoagent/core/errors.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+
+class NanoAgentError(Exception):
+    """nanoagent 所有框架级异常的基类。"""
+
+
+class FatalError(NanoAgentError):
+    """不可恢复的框架错误，直接上抛、不被吞。
+
+    与「工具内业务异常」相对：工具异常会被 AgentLoop._invoke 转成
+    ToolResult(is_error=True) 喂回模型 self-heal（DESIGN §5.5、§14.3）；
+    FatalError 表示框架本身处于不应继续的状态，_emit / _invoke 都不得吞它。
+    """

nanoagent/core/hooks.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from nanoagent.core.context import Context
+from nanoagent.core.message import LLMResponse, ToolCall, ToolResult
+from nanoagent.core.stop import StopReason
+
+
+@dataclass
+class ToolDecision:
+    """before_tool 的返回：是否放行一次工具调用。"""
+
+    allowed: bool = True
+    reason: str = ""
+
+
+class Hook(Protocol):
+    """Agent 生命周期钩子。所有 harness 能力都经此注入。
+
+    8 个生命周期点中只有 before_tool 有返回值（ToolDecision），因为只有它需要
+    影响核心循环的控制流；其余 7 个是纯观察 / 副作用点。
+
+    on_start 在整个 run 起始 emit 一次；before_turn 每轮 emit。
+    before_compact 为 v0.3 上下文压缩预留：v0.1 的 AgentLoop 不 emit 它（无压缩），
+    与 DESIGN §5.1.1 的占位字段同属「v0.1 声明、暂不驱动」。
+    """
+
+    def on_start(self, ctx: Context) -> None:
+        """整个 run 开始时（仅一次）。"""
+
+    def before_turn(self, ctx: Context) -> None:
+        """每一轮 turn 开始前。"""
+
+    def before_model(self, ctx: Context) -> None:
+        """调用 LLM 前。上下文管理策略在此介入（set_view）。"""
+
+    def after_model(self, ctx: Context, response: LLMResponse) -> None:
+        """LLM 返回后。"""
+
+    def before_compact(self, ctx: Context) -> None:
+        """上下文压缩前（v0.3 启用；v0.1 不 emit）。"""
+
+    def before_tool(self, ctx: Context, call: ToolCall) -> ToolDecision:
+        """执行工具前。权限校验策略在此介入，可拒绝调用。"""
+
+    def after_tool(self, ctx: Context, call: ToolCall, result: ToolResult) -> None:
+        """工具执行后。"""
+
+    def on_stop(self, ctx: Context, reason: StopReason) -> None:
+        """循环结束时。"""
+
+
+class BaseHook:
+    """8 个生命周期点的空实现。使用者继承它，只覆盖关心的点。"""
+
+    def on_start(self, ctx: Context) -> None: ...
+    def before_turn(self, ctx: Context) -> None: ...
+    def before_model(self, ctx: Context) -> None: ...
+    def after_model(self, ctx: Context, response: LLMResponse) -> None: ...
+    def before_compact(self, ctx: Context) -> None: ...
+    def before_tool(self, ctx: Context, call: ToolCall) -> ToolDecision:
+        return ToolDecision(allowed=True)   # 默认放行，对齐 v0.1 allow-all
+    def after_tool(self, ctx: Context, call: ToolCall, result: ToolResult) -> None: ...
+    def on_stop(self, ctx: Context, reason: StopReason) -> None: ...

nanoagent/core/loop.py

@@ -0,0 +1,111 @@
+"""AgentLoop —— 全项目的心脏：把 core 契约编排成约 30 行的 ReAct 循环。
+
+主体只含 ReAct 主干（推理 → 工具 → 回填），不含任何具体策略代码——harness 行为都在
+`_emit` / `_gate` / `stop.should_stop` 背后（这条定性规则是硬的，「~30 行」是它的标尺）。
+
+依赖防线（§8.1）：本模块属 core，只 import core 自身的子模块，绝不 import strategies/llm/tools/...。
+默认停止用 core 内置的 `_MaxTurns`（公开可配的 `MaxTurnsStop` 在 strategies/，由 api 或用户显式传入），
+以免 core 反向依赖 strategies。
+"""
+from __future__ import annotations
+
+import json
+
+from nanoagent.core.context import AgentResult, Context
+from nanoagent.core.errors import FatalError
+from nanoagent.core.hooks import ToolDecision
+from nanoagent.core.message import Message, ToolCall, ToolResult
+from nanoagent.core.stop import StopReason
+
+
+class _MaxTurns:
+    """core 内置默认停止：达 max_turns 即停。等价于 strategies.MaxTurnsStop，
+    放 core 是为了让 AgentLoop 不依赖 strategies（§8.1）。"""
+
+    def __init__(self, max_turns: int):
+        self.max_turns = max_turns
+
+    def should_stop(self, ctx: Context, turn: int):
+        return StopReason.MAX_TURNS if turn >= self.max_turns else None
+
+
+def _stringify(value) -> str:
+    """工具返回值 → str（无损：str 原样、其余 json.dumps 兜底）。core 绝不截断（那是 v0.3 ContextStrategy 的事）。"""
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, ensure_ascii=False, default=str)
+    except Exception:
+        return str(value)
+
+
+def _denial_message(call: ToolCall, reason: str) -> Message:
+    """被拒工具调用 → role=tool 且 call_id 配对的消息，保证 OpenAI tool_call/tool 配对完整（否则下一轮 400）。"""
+    return Message(
+        role="tool",
+        tool_result=ToolResult(call.id, content=f"调用被拒绝：{reason}", is_error=True),
+    )
+
+
+class AgentLoop:
+    """约 30 行的 ReAct 核心循环。无状态：状态全在传入的 Context 里。"""
+
+    def __init__(self, llm, tools, hooks=None, stop=None, max_turns: int = 20):
+        self.llm = llm
+        self.tools = {t.name: t for t in tools}
+        self.hooks = hooks or []
+        self.stop = stop or _MaxTurns(max_turns)      # 默认 max-turns；保持 noop 纯 ReAct
+
+    def run(self, ctx: Context) -> AgentResult:
+        self._emit("on_start", ctx)                          # 整个 run 起始一次
+        turn = 0
+        while True:
+            reason = self.stop.should_stop(ctx, turn)        # 轮次 / 预算 / 成本统一在此判定
+            if reason is not None:
+                self._emit("on_stop", ctx, reason)
+                return AgentResult(ctx, reason, turn, ctx.usage)
+
+            self._emit("before_turn", ctx)                   # 每一轮 turn 开始
+            self._emit("before_model", ctx)                  # 上下文策略在此 set_view()
+            response = self.llm.chat(ctx.view(), tools=list(self.tools.values()))
+            self._emit("after_model", ctx, response)
+            ctx.add(response.message)
+            ctx.add_usage(response.usage)
+
+            if not response.message.tool_calls:              # 终态：模型不再调工具
+                self._emit("on_stop", ctx, StopReason.DONE)
+                return AgentResult(ctx, StopReason.DONE, turn + 1, ctx.usage)
+
+            for call in response.message.tool_calls:
+                decision = self._gate(ctx, call)             # before_tool：软拒绝 → continue
+                if not decision.allowed:
+                    ctx.add(_denial_message(call, decision.reason))
+                    continue
+                result = self._invoke(call)
+                self._emit("after_tool", ctx, call, result)
+                ctx.add(Message(role="tool", tool_result=result))
+            turn += 1
+
+    # —— 辅助函数（不铺进主体；harness 行为都在这背后）——
+
+    def _emit(self, point: str, *args) -> None:
+        for h in self.hooks:
+            getattr(h, point)(*args)                         # 调每个 hook 的同名方法；v0.1 不吞异常，直接上抛
+
+    def _gate(self, ctx: Context, call: ToolCall) -> ToolDecision:
+        for h in self.hooks:                                 # deny-first：第一个拒绝者说了算
+            d = h.before_tool(ctx, call)
+            if d is not None and not d.allowed:
+                return d
+        return ToolDecision(allowed=True)                    # 无 hook / 全放行 → 默认放行
+
+    def _invoke(self, call: ToolCall) -> ToolResult:
+        if call.name not in self.tools:                      # 模型可能幻觉工具名 → 喂回错误而非抛
+            return ToolResult(call.id, content=f"unknown tool: {call.name}", is_error=True)
+        try:
+            value = self.tools[call.name](**call.arguments)
+            return ToolResult(call.id, content=_stringify(value))
+        except FatalError:
+            raise                                            # 框架级致命错误：上抛，不喂回
+        except Exception as e:                                # 工具业务异常：转 is_error 喂回模型 self-heal
+            return ToolResult(call.id, content=f"{type(e).__name__}: {e}", is_error=True)

nanoagent/core/message.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCall:
+    """模型发起的一次工具调用请求。"""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class ToolResult:
+    """一次工具执行的结果。"""
+
+    call_id: str
+    content: str          # 工具返回值经字符串化后的内容（core 只做无损 str()，不截断）
+    is_error: bool = False
+    raw_bytes: int = 0    # v0.1 占位：content 字节数，供 v0.3 策略判断是否需清理
+    elided: bool = False  # v0.1 占位：v0.3 上下文策略可据此把旧工具结果剔出视图（数据仍留 messages）
+
+
+@dataclass
+class Message:
+    """对话中的一条消息。一旦 add 进 Context 即视为不可变事件，策略不得删改它。"""
+
+    role: str             # "system" | "user" | "assistant" | "tool"
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_result: ToolResult | None = None
+    # ↓ 以下为 v0.3 上下文工程预留的「抓手」，v0.1 仅填充、绝不消费（见 DESIGN §5.1.1）
+    pinned: bool = False               # True=裁剪策略不得丢弃（如 system / 关键决策）
+    ephemeral: bool = False            # True=可被工具结果清理策略优先移出视图
+    token_estimate: int | None = None  # 由上下文策略按需回填，供按预算截断/熔断判定
+
+
+@dataclass
+class LLMResponse:
+    """一次 LLM 调用的返回。assistant 消息自带的 tool_calls 即本轮工具调用（唯一权威源）。"""
+
+    message: Message
+    usage: dict[str, int] = field(default_factory=dict)   # 本轮 token 统计

nanoagent/core/protocols.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from nanoagent.core.context import Context
+from nanoagent.core.hooks import ToolDecision
+from nanoagent.core.message import LLMResponse, Message, ToolCall
+from nanoagent.core.stop import StopReason
+
+
+class LLMClient(Protocol):
+    """LLM 客户端契约，统一 OpenAI / Anthropic / 本地模型。
+
+    v0.1 只要求 chat（同步、整段返回）。流式（chat_stream）是 v0.2 的预留扩展：
+    届时新增一个 StreamingLLMClient 协议、由 REPL 旁路直接调用，不改 core
+    （见 DESIGN §14.3 REPL 流式输出）。
+    """
+
+    def chat(
+        self,
+        messages: list[Message],
+        tools: list[Tool] | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        ...
+
+
+class Tool(Protocol):
+    """工具契约。用户日常用 @tool 装饰器，框架内部按此协议处理。"""
+
+    name: str
+    description: str
+    schema: dict          # OpenAI Function Calling 的 JSON Schema
+
+    def __call__(self, **kwargs: Any) -> Any:
+        ...
+
+
+class MemoryBackend(Protocol):
+    """Memory 契约，working / episodic / semantic 三层均符合此接口。"""
+
+    def store(self, key: str, value: Any, metadata: dict | None = None) -> None:
+        ...
+
+    def retrieve(self, query: str, k: int = 5) -> list[Any]:
+        ...
+
+    def delete(self, key: str) -> None:
+        ...
+
+
+# —— 以下三个是「策略 Protocol」：契约属 core，实现属 strategies/（见 DESIGN §5.4 归属规则）。
+#    core 依赖 core 内的协议不违反单向依赖。
+
+class ContextStrategy(Protocol):
+    """上下文管理策略，由 before_model hook 调用。
+
+    只读 messages（完整日志）、产出裁剪后的 message 列表，再由 hook 写进
+    ctx.set_view()——物理上无法破坏历史。产出列表须保持 tool_calls↔tool_result
+    配对完整（删工具结果须连带删其 tool_call）。
+    """
+
+    def reduce(self, messages: list[Message], budget_tokens: int) -> list[Message]:
+        ...
+
+
+class PermissionStrategy(Protocol):
+    """权限校验策略，由 before_tool hook 调用。"""
+
+    def check(self, ctx: Context, call: ToolCall) -> ToolDecision:
+        ...
+
+
+class StopStrategy(Protocol):
+    """停止条件策略，由 AgentLoop 每轮检查。"""
+
+    def should_stop(self, ctx: Context, turn: int) -> StopReason | None:
+        ...

nanoagent/core/stop.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class StopReason(Enum):
+    """agent loop 的退出原因（DESIGN §2.2、§5.1）。
+
+    只有 DONE 表示「任务自然完成」；其余三个都是「被迫终止」。
+    DONE 在模型不再调工具时产生；MAX_TURNS / DENIED / BUDGET 统一经每轮
+    轮首的 StopStrategy.should_stop 产生。
+    """
+
+    DONE = "done"            # 模型不再调工具，任务完成
+    MAX_TURNS = "max_turns"  # 达到最大轮数
+    DENIED = "denied"        # 被权限策略终止
+    BUDGET = "budget"        # 被熔断器终止

nanoagent/llm/__init__.py

@@ -0,0 +1,13 @@
+"""llm/ —— LLMClient 协议的两个实现。
+
+- EchoClient：不联网的测试基石，按预设脚本返回 LLMResponse。
+- OpenAICompatClient：包官方 openai SDK，做 core Message ↔ OpenAI dict 双向翻译。
+
+依赖方向：llm 依赖 core（实现 LLMClient 协议），core 不反向依赖 llm。
+openai 是重依赖，仅在 OpenAICompatClient.__init__ 内懒加载——
+故仅 import 本包不会触发 openai，EchoClient 与双向转换函数都可脱离 openai 单测。
+"""
+from nanoagent.llm.echo import EchoClient
+from nanoagent.llm.openai_compat import OpenAICompatClient
+
+__all__ = ["EchoClient", "OpenAICompatClient"]

nanoagent/llm/echo.py

@@ -0,0 +1,24 @@
+"""EchoClient —— 测试基石：不联网，按预设脚本返回 LLMResponse。
+
+预设脚本可造出「第一轮返回带 tool_calls 的 assistant、第二轮返回纯文本」的序列，
+从而在不联网下测出 loop 的「调工具 → 回填 → 再推理 → DONE」完整路径（DESIGN §5.2 / v0.1-design §5.2）。
+"""
+from __future__ import annotations
+
+from nanoagent.core import LLMResponse, Message
+
+
+class EchoClient:
+    """实现 LLMClient 协议（结构化，无需继承）。不联网。"""
+
+    def __init__(self, script: list[LLMResponse] | None = None):
+        self._script = list(script or [])     # 预设的若干轮响应，按序弹出
+
+    def chat(self, messages, tools=None, **kwargs) -> LLMResponse:
+        if self._script:
+            return self._script.pop(0)         # 有脚本：按序返回预设响应
+        last = messages[-1].content if messages else ""
+        return LLMResponse(
+            message=Message(role="assistant", content=f"echo: {last}"),
+            usage={"total_tokens": 1},
+        )