pynanoagent 0.1.0.dev0__py3-none-any.whl

nanoagent/llm/openai_compat.py

@@ -0,0 +1,110 @@
+"""OpenAICompatClient —— 包官方 openai SDK，在 core Message 与 OpenAI message dict 间双向翻译。
+
+兼容任何 OpenAI 风格接口（DeepSeek / Kimi / vLLM / Ollama 等），由 base_url 区分。
+`resolve_model`（读 API key、选 endpoint）在 api 层，不在这里——本客户端只收已解析的 model 名与可选 base_url。
+
+两个易踩的坑（v0.1-design §5.1）：
+① tool_calls 的唯一权威源是 assistant 消息自带的 tool_calls；
+② tool 消息必须带 tool_call_id 且与前一条 assistant 的某个 tool_calls[].id 配对，否则下一轮 400。
+
+`_to_openai` / `_parse_response` 是模块级纯函数：不触发 openai import，可脱离网络逐 case 单测。
+"""
+from __future__ import annotations
+
+import json
+
+from nanoagent.core import LLMResponse, Message, ToolCall
+
+
+def _safe(text):
+    """去掉无法编码的孤立代理项（lone surrogate，如非 UTF-8 locale 下 input() 读坏的中文），
+    避免 openai 请求 json 编码时抛 UnicodeEncodeError。干净字符串原样返回。"""
+    if not isinstance(text, str):
+        return text
+    return text.encode("utf-8", "replace").decode("utf-8")
+
+
+def _to_openai(m: Message) -> dict:
+    """core Message → OpenAI message dict（内容统一过 _safe 净化）。"""
+    if m.role == "tool":
+        # tool 结果消息：必须带 tool_call_id 与前一条 assistant 的调用配对
+        tr = m.tool_result
+        return {
+            "role": "tool",
+            "tool_call_id": tr.call_id if tr else "",
+            "content": _safe(tr.content) if tr else "",
+        }
+    if m.role == "assistant" and m.tool_calls:
+        # 带工具调用的 assistant：arguments 序列化成 JSON 字符串
+        return {
+            "role": "assistant",
+            "content": _safe(m.content) or None,
+            "tool_calls": [
+                {
+                    "id": c.id,
+                    "type": "function",
+                    "function": {
+                        "name": c.name,
+                        "arguments": _safe(json.dumps(c.arguments, ensure_ascii=False)),
+                    },
+                }
+                for c in m.tool_calls
+            ],
+        }
+    # system / user / 纯文本 assistant
+    return {"role": m.role, "content": _safe(m.content)}
+
+
+def _parse_response(resp) -> LLMResponse:
+    """OpenAI 响应对象 → LLMResponse。tool_calls 只取 assistant 消息自带的那份。"""
+    choice = resp.choices[0].message
+    msg = Message(
+        role="assistant",
+        content=choice.content or "",
+        tool_calls=[
+            ToolCall(c.id, c.function.name, json.loads(c.function.arguments or "{}"))
+            for c in (choice.tool_calls or [])
+        ],
+    )
+    u = getattr(resp, "usage", None)
+    usage = (
+        {
+            "prompt_tokens": u.prompt_tokens,
+            "completion_tokens": u.completion_tokens,
+            "total_tokens": u.total_tokens,
+        }
+        if u
+        else {}
+    )
+    return LLMResponse(message=msg, usage=usage)
+
+
+class OpenAICompatClient:
+    """实现 LLMClient 协议（结构化，无需继承）。openai SDK 在此懒加载。
+
+    兼容任何 OpenAI 风格接口，换 model + base_url 即可。例 ：
+      - OpenAI       ：OpenAICompatClient("gpt-4o-mini")
+      - **DeepSeek**  ：OpenAICompatClient("deepseek-chat", base_url="https://api.deepseek.com")
+      - Kimi / vLLM / Ollama 同理（各自的 base_url）。
+    api_key 缺省由 SDK 读 OPENAI_API_KEY；CLI 还支持用 OPENAI_BASE_URL 环境变量切到 DeepSeek 等端点。
+    """
+
+    def __init__(self, model: str, base_url: str | None = None, api_key: str | None = None):
+        from openai import OpenAI  # 重依赖懒加载：仅真正用真实客户端时才需要 openai
+
+        self.model = model
+        opts: dict = {}
+        if base_url:
+            opts["base_url"] = base_url
+        if api_key:
+            opts["api_key"] = api_key
+        self._client = OpenAI(**opts)   # api_key 缺省时由 SDK 读 OPENAI_API_KEY
+
+    def chat(self, messages, tools=None, **kwargs) -> LLMResponse:
+        resp = self._client.chat.completions.create(
+            model=self.model,
+            messages=[_to_openai(m) for m in messages],
+            tools=[t.schema for t in tools] if tools else None,
+            **kwargs,
+        )
+        return _parse_response(resp)

nanoagent/memory/__init__.py

@@ -0,0 +1,9 @@
+"""memory/ —— MemoryBackend 协议的实现。
+
+v0.1 只做 working memory，且 working memory 的真身其实是 Context.messages（对话历史）；
+InMemoryBackend 是 MemoryBackend 契约的最小实现 + 占位，给 v0.2 文件系统 / episodic memory 留接口形状。
+依赖方向：memory 实现 core 的 MemoryBackend 协议（结构化，无需 import core）。
+"""
+from nanoagent.memory.backend import InMemoryBackend
+
+__all__ = ["InMemoryBackend"]

nanoagent/memory/backend.py

@@ -0,0 +1,25 @@
+"""InMemoryBackend —— 进程内 dict 实现，v0.1 working memory 的契约占位。
+
+retrieve 在 v0.1 不做向量 / 语义检索（那是 semantic memory，v0.2+ 基于向量），
+只朴素返回最近写入的 k 个值——契约对、实现简陋，符合「形状定对、实现可最简」。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class InMemoryBackend:
+    """实现 MemoryBackend 协议（store / retrieve / delete），结构化、无需继承。"""
+
+    def __init__(self) -> None:
+        self._store: dict[str, Any] = {}
+
+    def store(self, key: str, value: Any, metadata: dict | None = None) -> None:
+        self._store[key] = value
+
+    def retrieve(self, query: str, k: int = 5) -> list[Any]:
+        # v0.1 无语义检索：返回最近写入的 k 个值
+        return list(self._store.values())[-k:]
+
+    def delete(self, key: str) -> None:
+        self._store.pop(key, None)

nanoagent/strategies/__init__.py

@@ -0,0 +1,14 @@
+"""strategies/ —— core 三个策略 Protocol 的默认实现 + 把策略包成 Hook 的包装器。
+
+三个默认实现都极简：v0.1 默认配置「不带 hook、纯 ReAct」就靠它们退化。
+接线方式不同（DESIGN §5.4）：
+  - ContextStrategy / PermissionStrategy 要被一个 Hook「包」起来才生效
+    （ContextHook 在 before_model、PermissionHook 在 before_tool 调用）；
+  - 停止策略（公开可配的 MaxTurnsStop）是 AgentLoop 的构造参数，不算 hook。
+依赖方向：strategies 依赖 core（实现策略 Protocol、继承 BaseHook），core 不反向依赖。
+"""
+from nanoagent.strategies.context import ContextHook, NoopContext
+from nanoagent.strategies.permission import AllowAll, PermissionHook
+from nanoagent.strategies.stop import MaxTurnsStop
+
+__all__ = ["NoopContext", "ContextHook", "AllowAll", "PermissionHook", "MaxTurnsStop"]

nanoagent/strategies/context.py

@@ -0,0 +1,25 @@
+"""上下文策略：默认 NoopContext（不裁剪）+ 把任意 ContextStrategy 包成 Hook 的 ContextHook。"""
+from __future__ import annotations
+
+from nanoagent.core import BaseHook
+
+
+class NoopContext:
+    """默认上下文策略：不裁剪，view() 恒等于全量历史。"""
+
+    def reduce(self, messages, budget_tokens):
+        return messages
+
+
+class ContextHook(BaseHook):
+    """把一个 ContextStrategy「包」成 Hook：在 before_model 调 reduce、写投影（不碰日志）。
+
+    v0.1 默认不启用（保持纯 ReAct）；显式 Agent(..., hooks=[ContextHook(strategy)]) 才介入。
+    """
+
+    def __init__(self, strategy, budget_tokens: int = 8000):
+        self._s = strategy
+        self._budget = budget_tokens
+
+    def before_model(self, ctx) -> None:
+        ctx.set_view(self._s.reduce(ctx.messages, self._budget))   # 只写 view 投影，绝不改 messages

nanoagent/strategies/permission.py

@@ -0,0 +1,24 @@
+"""权限策略：默认 AllowAll（一律放行）+ 把任意 PermissionStrategy 包成 Hook 的 PermissionHook。"""
+from __future__ import annotations
+
+from nanoagent.core import BaseHook, ToolDecision
+
+
+class AllowAll:
+    """默认权限策略：一律放行。"""
+
+    def check(self, ctx, call) -> ToolDecision:
+        return ToolDecision(allowed=True)
+
+
+class PermissionHook(BaseHook):
+    """把一个 PermissionStrategy「包」成 Hook：在 before_tool 调 check、返回 ToolDecision。
+
+    返回 allowed=False 是软拒绝：loop 只对该次调用回填 denial 消息、让模型换路，不终止整轮。
+    """
+
+    def __init__(self, strategy):
+        self._s = strategy
+
+    def before_tool(self, ctx, call) -> ToolDecision:
+        return self._s.check(ctx, call)

nanoagent/strategies/stop.py

@@ -0,0 +1,18 @@
+"""停止策略：公开可配的 MaxTurnsStop（只看轮数）。
+
+注意：core/loop.py 为不依赖 strategies（§8.1），自带一个等价的私有默认停止 `_MaxTurns`；
+本类是公开、可显式传入 `AgentLoop(stop=MaxTurnsStop(n))` 或被 CompositeStop 组合的版本。
+"""
+from __future__ import annotations
+
+from nanoagent.core import StopReason
+
+
+class MaxTurnsStop:
+    """实现 StopStrategy 协议（结构化，无需继承）。达 max_turns 即停。"""
+
+    def __init__(self, max_turns: int = 20):
+        self.max_turns = max_turns
+
+    def should_stop(self, ctx, turn: int):
+        return StopReason.MAX_TURNS if turn >= self.max_turns else None

nanoagent/tools/__init__.py

@@ -0,0 +1,11 @@
+"""Tool 系统：@tool 装饰器、注册表、签名→OpenAI schema 生成、内置工具。
+
+依赖方向：tools 依赖 core（实现 Tool 协议），core 不反向依赖 tools。
+内置工具在 ``nanoagent.tools.builtin``（按需 import，避免无谓拉起第三方依赖）。
+"""
+
+from nanoagent.tools.decorator import FunctionTool, tool
+from nanoagent.tools.registry import ToolRegistry
+from nanoagent.tools.schema import build_schema
+
+__all__ = ["tool", "FunctionTool", "ToolRegistry", "build_schema"]

nanoagent/tools/builtin.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from nanoagent.tools.decorator import tool
+
+# 第三方/重依赖在函数内部延迟 import，使「import builtin」本身零依赖、可在无网络/未装包时加载。
+
+
+@tool
+def read_file(path: str) -> str:
+    """读取文本文件内容。"""
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+@tool
+def write_file(path: str, content: str) -> str:
+    """把内容写入文本文件，返回确认信息。"""
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+    return f"已写入 {path}（{len(content)} 字符）"
+
+
+@tool
+def list_files(directory: str, pattern: str = "*") -> list:
+    """列出目录下匹配 glob 模式的文件路径。"""
+    import glob
+    import os
+
+    return sorted(glob.glob(os.path.join(directory, pattern)))
+
+
+@tool
+def run_shell(command: str) -> str:
+    """执行 shell 命令，返回 stdout+stderr（v0.1 无沙箱，危险性靠 v0.3 权限策略约束）。"""
+    import subprocess
+
+    proc = subprocess.run(command, shell=True, capture_output=True, text=True)
+    return (proc.stdout + proc.stderr).strip()
+
+
+@tool
+def web_search(query: str, k: int = 5) -> list:
+    """用 DuckDuckGo 检索，返回前 k 条「标题 — 链接」。"""
+    from duckduckgo_search import DDGS
+
+    with DDGS() as ddgs:
+        return [f"{r['title']} — {r['href']}" for r in ddgs.text(query, max_results=k)]
+
+
+BUILTIN_TOOLS = [read_file, write_file, list_files, run_shell, web_search]

nanoagent/tools/decorator.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import inspect
+import re
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from nanoagent.tools.schema import build_schema
+
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+_MAX_NAME = 64
+
+
+def _validate_name(name: str) -> None:
+    """工具名规则：^[a-z][a-z0-9_]*$ 且 ≤64 字符（DESIGN §14.3）。"""
+    if not _NAME_RE.match(name):
+        raise ValueError(f"工具名非法（须匹配 ^[a-z][a-z0-9_]*$）: {name!r}")
+    if len(name) > _MAX_NAME:
+        raise ValueError(f"工具名超过 {_MAX_NAME} 字符: {name!r}")
+
+
+def _first_doc_line(fn: Callable) -> str:
+    doc = inspect.getdoc(fn)
+    if not doc:
+        return ""
+    for line in doc.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+@dataclass
+class FunctionTool:
+    """`@tool` 的产物：满足 core.Tool 协议（name / description / schema + __call__）。"""
+
+    fn: Callable[..., Any]
+    name: str
+    description: str
+    schema: dict
+
+    def __call__(self, **kwargs: Any) -> Any:
+        return self.fn(**kwargs)
+
+
+def tool(
+    fn: Callable | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Any:
+    """把普通函数注册为工具。`@tool` 或 `@tool(name=..., description=...)` 均可。
+
+    名字默认取函数名（强制 ^[a-z][a-z0-9_]*$ 且 ≤64）；描述默认取 docstring 首行；
+    schema 由函数签名 + 类型注解自动生成（见 tools/schema.py）。重名校验在注册表（registry）做。
+    """
+
+    def wrap(f: Callable) -> FunctionTool:
+        t_name = name or f.__name__
+        _validate_name(t_name)
+        desc = description or _first_doc_line(f)
+        return FunctionTool(fn=f, name=t_name, description=desc,
+                            schema=build_schema(f, t_name, desc))
+
+    return wrap(fn) if fn is not None else wrap

nanoagent/tools/registry.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from nanoagent.core import Tool
+
+
+class ToolRegistry:
+    """name -> Tool 的注册表；register 时重名报错（v0.1 不引 namespace 前缀，DESIGN §14.3）。"""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, t: Tool) -> Tool:
+        if t.name in self._tools:
+            raise ValueError(f"工具重名: {t.name!r}")
+        self._tools[t.name] = t
+        return t
+
+    def register_all(self, tools) -> None:
+        for t in tools:
+            self.register(t)
+
+    def get(self, name: str):
+        return self._tools.get(name)
+
+    def all(self) -> list:
+        return list(self._tools.values())
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def __len__(self) -> int:
+        return len(self._tools)

nanoagent/tools/schema.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from typing import Any
+
+# Python 标量类型 → JSON Schema type（v0.1 支持范围，见 v0.1-design.md §4.2 映射表）
+_JSON_PRIMITIVES = {str: "string", int: "integer", float: "number", bool: "boolean"}
+
+
+def _unwrap_optional(tp: Any) -> tuple[Any, bool]:
+    """Optional[X] / Union[X, None] / X | None -> (inner, is_optional)。
+
+    仅在「恰好一个非 None 分支」时解出 inner；其余 Union 原样返回（v0.1 不深挖多分支 Union）。
+    """
+    origin = typing.get_origin(tp)
+    union_type = getattr(types, "UnionType", None)   # PEP 604（3.10+）的 X | Y
+    if origin is typing.Union or (union_type is not None and origin is union_type):
+        args = typing.get_args(tp)
+        non_none = [a for a in args if a is not type(None)]
+        is_optional = len(non_none) < len(args)
+        if len(non_none) == 1:
+            return non_none[0], is_optional
+        return tp, is_optional
+    return tp, False
+
+
+def _json_for(tp: Any) -> dict:
+    """把一个（已解包 Optional 的）Python 类型映射成 JSON Schema 片段。"""
+    if tp in _JSON_PRIMITIVES:
+        return {"type": _JSON_PRIMITIVES[tp]}
+    origin = typing.get_origin(tp) or tp
+    if origin in (list, set, frozenset, tuple):
+        return {"type": "array"}        # v0.1 不展开 items（见 §4.2 优化空间）
+    if origin is dict:
+        return {"type": "object"}
+    return {"type": "string"}           # 兜底：未识别 / 无注解按 string
+
+
+def build_schema(fn: Any, name: str, description: str) -> dict:
+    """从函数签名 + 类型注解生成 OpenAI Function Calling schema。
+
+    无默认值且非 Optional 的参数进 required；类型注解无法解析时整体退化为无类型（全 string）。
+    """
+    sig = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn)
+    except Exception:
+        hints = {}
+    properties: dict[str, dict] = {}
+    required: list[str] = []
+    for pname, param in sig.parameters.items():
+        if pname == "self":
+            continue
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        tp = hints.get(pname)
+        if tp is None:
+            prop, is_optional = {"type": "string"}, False
+        else:
+            inner, is_optional = _unwrap_optional(tp)
+            prop = _json_for(inner)
+        properties[pname] = prop
+        has_default = param.default is not inspect.Parameter.empty
+        if not has_default and not is_optional:
+            required.append(pname)
+    parameters: dict = {"type": "object", "properties": properties}
+    if required:
+        parameters["required"] = required
+    return {
+        "type": "function",
+        "function": {"name": name, "description": description, "parameters": parameters},
+    }

pynanoagent-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: pynanoagent
+Version: 0.1.0.dev0
+Summary: 易于理解、可融入最佳实践、且真正可用的 ReAct 单 agent Python 框架（核心循环 ~30 行）
+Project-URL: Homepage, https://github.com/eastonsuo/nanoagent
+Project-URL: Repository, https://github.com/eastonsuo/nanoagent
+Author: eastonsuo
+License: MIT
+License-File: LICENSE
+Keywords: agent,deepseek,llm,openai,react,tool-calling
+Requires-Python: >=3.9
+Requires-Dist: duckduckgo-search>=6
+Requires-Dist: openai>=1.30
+Requires-Dist: prompt-toolkit>=3
+Requires-Dist: rich>=13
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: import-linter>=2; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: trace
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'trace'
+Description-Content-Type: text/markdown
+
+# nanoagent
+
+> 一个核心循环只有约 30 行、却能通过分阶段引入 harness 工程实践演进为真实可用运行时的 **ReAct 单 agent 框架**。既把 agent 的内部机制讲清楚，也让人能基于它构建自己的 agent 应用。
+
+> **状态：v0.1 基础版已实现**。核心循环 / 工具系统 / LLM 客户端（OpenAI 兼容，含 DeepSeek）/ in-memory memory / 默认策略 / 命令行入口均已落地，`python -m pytest` 61 passed（全程不联网）。**当前可从源码安装运行**（见[快速开始](#快速开始)）；PyPI 发布在即，届时 `pip install pynanoagent`（发布名加 `py` 前缀，导入仍 `import nanoagent`）。设计见 [`docs/DESIGN.md`](docs/DESIGN.md)。
+
+## 这是什么
+
+2026 年的 agent 框架生态有一个结构性空白：**编排类框架**（LangGraph / CrewAI）能让 agent 跑起来，但 context 管理、权限、可观测性往往是后补的，复杂且边界不清；**产品级 agent**（Claude Code / Cursor）harness 成熟却闭源、绑定模型、不可复用。「能让人读懂每一层为什么这样设计、同时又真正可用」的开源框架几乎是空白。
+
+nanoagent 要填的就是这个空白，三个关键词缺一不可：
+
+- **易于理解**：核心层代码量小、抽象少，能在一两小时读完 `core/loop.py` 并真正理解每一轮在做什么。
+- **融入最佳实践**：context engineering、权限校验、熔断、memory 分层、skill 系统等社区已验证的工程实践，分阶段、有解释地引入。
+- **真正可用**：不停在 toy 阶段——目标是 v0.4 能支撑长任务而不崩溃。
+
+## 核心设计原则：Stable Core + Pluggable Strategy
+
+整个项目押在一个切分上：把框架切成**核心层**（过去五年没本质变化、未来数年大概率也不变的部分——LLM 调用、循环、工具调度、数据结构）与**策略层**（随最佳实践演化的部分——怎么管上下文、怎么校验权限、怎么熔断）。核心层一旦定稿就不再改动；引入新最佳实践 = 在策略层新增一个实现，核心层不动。
+
+下图回答：「nanoagent 由哪几层组成、运行时怎样互相调用？」
+
+```mermaid
+flowchart TD
+    user["使用者前端<br/>CLI / bot / 编辑器插件"]
+    api["顶层 API<br/>Agent / ChatSession"]
+
+    subgraph core["核心层 · 数年不变"]
+        loop["AgentLoop<br/>~30 行 ReAct 循环"]
+        data["数据结构 + 契约<br/>Message / Context / Protocol"]
+        hooks["Hook 机制<br/>8 个生命周期点"]
+    end
+
+    subgraph ext["可替换扩展点"]
+        caps["能力实现<br/>LLM / 工具 / Memory"]
+        strat["策略层<br/>上下文 / 权限 / 停止"]
+    end
+
+    user -->|"调用"| api
+    api -->|"组装并运行"| loop
+    loop -->|"读写"| data
+    loop -->|"直接调用"| caps
+    loop -->|"生命周期回调"| hooks
+    hooks -.->|"被策略实现并注入"| strat
+
+    classDef stable fill:#fff0aa
+    class loop,data,hooks stable
+```
+
+**读图要点**：暖黄三块是核心层，数年内不动。注意两种依赖方向的不对称——`AgentLoop` **直接调用**能力实现（LLM / 工具 / Memory 是循环跑起来的必需品，实线），却只**经 Hook 间接触达**策略层（虚线：策略实现某个 Hook 协议、被注入循环的某个生命周期点）。判据很简单：拿掉能力实现层循环就跑不起来，拿掉策略层循环仍能跑（退化成纯 ReAct）。核心层因此既不知道什么是 compaction、也不知道什么是 permission，它只知道「在某个时间点回调一组 hook」——这就是「核心稳定、策略可插拔」能成立的物理机制。
+
+## 路线图
+
+| 版本 | 范围 | 状态 |
+|---|---|---|
+| **v0.1 · Core** | 单 agent + 工具系统 + in-memory memory + 命令行 demo | ✅ 基础版完成（可源码运行，61 单测通过） |
+| v0.2 · Skills + Trace + MCP | Skill 渐进式加载 + OpenTelemetry trace + 文件系统 memory + MCP 工具适配器 | 📋 计划 |
+| v0.3 · Harness | 上下文管理多策略 + 权限系统 + 熔断器 + subagent | 📋 计划 |
+| v0.4 · Eval | 三维度评估框架（独立 repo） | 📋 计划 |
+
+## 快速开始
+
+当前从源码安装（PyPI 发布后可直接 `pip install pynanoagent`，导入名仍 `nanoagent`）：
+
+```bash
+git clone https://github.com/eastonsuo/nanoagent && cd nanoagent
+pip install -e .
+```
+
+**命令行对话**（需一个 OpenAI 兼容的 key）：
+
+```bash
+export OPENAI_API_KEY=sk-...          # OpenAI
+nanoagent
+```
+
+换 **DeepSeek** 等兼容端点：模型名带前缀即自动识别端点，只需给对应 key（无需手设 base_url）：
+
+```bash
+export DEEPSEEK_API_KEY=sk-...        # DeepSeek（没有则回落 OPENAI_API_KEY）
+export NANOAGENT_MODEL=deepseek-chat
+nanoagent
+```
+
+**当库用** —— `@tool` 注册工具，一次性任务用 `Agent.run`、多轮对话用 `Agent(...).session()`：
+
+```python
+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)     # 一次性，跨 run 无记忆
+
+chat = agent.session()                                    # 多轮，记得上文
+chat.send("我叫小明")
+print(chat.send("我叫什么？").output)
+```
+
+## v0.1 已实现
+
+| 层 | 模块 | 内容 |
+|---|---|---|
+| 核心层 · 数年不变 | `core/` | 数据结构 + 能力/策略契约 + 8 点 Hook + `AgentLoop`（~30 行 ReAct 循环）|
+| 能力实现 | `tools/` `llm/` `memory/` | `@tool` + schema 自动生成；OpenAI 兼容客户端（+ 测试用 echo）；in-memory memory |
+| 策略层 · 可插拔 | `strategies/` | 默认 noop / allow-all / max-turns + 把策略包成 Hook |
+| 入口装配 | `api.py` `cli/` | `Agent` / `ChatSession` + 命令行 REPL |
+
+- **可读性**：核心层（非 `__init__`）约 390 行，< 500。
+- **测试**：`python -m pytest` → 61 passed，全程不联网、不需 API key（echo 客户端驱动全链路）。
+- **依赖防线**：`core/` 不 import 任何外层目录——「稳定核心」原则的物理保证（设计 §8.1）。
+- **OpenAI 兼容**：OpenAI / DeepSeek / Kimi / vLLM / Ollama，换模型名或端点即可。
+
+## 文档
+
+- [`docs/DESIGN.md`](docs/DESIGN.md) —— 权威设计文档（14 章）：概念与设计哲学、core/harness 解耦、核心数据结构与接口契约、整体架构、v0.1 详细设计、技术选型、与现有框架对比、风险。**实现细节一律以它为准。**
+
+## 许可证
+
+本项目采用 [MIT License](LICENSE)。

pynanoagent-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,31 @@
+nanoagent/__init__.py,sha256=iwNBj4hIzY5rAaJMUI29SvPuDREenqfhCizzfi0JuxI,721
+nanoagent/api.py,sha256=dLJSxMhgXpSyySY8BZXG0DnSOjJ4pc4u-ZZt7HDlGtM,4545
+nanoagent/cli/__init__.py,sha256=zPNEILUKz3CxuaYnyf4vg2E1R9vCkySSZNdIv61LA7k,86
+nanoagent/cli/main.py,sha256=9AVnDw1zzRvJe3vpihGLJNtdXqx8Dh-jdAWI66WkIWE,2615
+nanoagent/core/__init__.py,sha256=5LR9b8kNlZhGHwn0N_eJV6Y7jZj7-NynqKLOChNNpXM,1301
+nanoagent/core/context.py,sha256=Q_mBXGnrYyeHzzVbZuKZt-DJAjCoVVXjWKk3yFPBIXo,2561
+nanoagent/core/errors.py,sha256=T78xuYd8aPVcdknWOGUVBfJmpioDrVO4jw94crQ1QdQ,502
+nanoagent/core/hooks.py,sha256=pbi97Jzfu_BR4VPXZmrbr9iono05SW5k1F9n07wFVic,2586
+nanoagent/core/loop.py,sha256=9RKrE7inmJLccYBbxD8oZfN-wZX4-q6gW6dqNA-Bjww,5387
+nanoagent/core/message.py,sha256=36Z0pDDLNwJ00a-Y1WF_ImvwWdmsqOQh5KurFp5KVAU,1708
+nanoagent/core/protocols.py,sha256=DHIee8Ojb2wNgI0Cd3DYivd2jZikT1ze9-T99G9Umvs,2413
+nanoagent/core/stop.py,sha256=CFCCJcaqk6xECDOWAkKm0X2YxgFIUqVIoKU373OY7gs,605
+nanoagent/llm/__init__.py,sha256=MEs5zE-sGXdlXMyBCzWrYkFXBV5Eb5JEVGdYSTD5YY8,649
+nanoagent/llm/echo.py,sha256=y9z5DhW8ovv4876mzFiCS3mi3CLE7-KfSoih1C359i4,1060
+nanoagent/llm/openai_compat.py,sha256=2FYbNSMR1eB-MKcZ7fy8HzKycPe6kul3CtoX5mhV5FE,4392
+nanoagent/memory/__init__.py,sha256=5ahtbzNLvUw6gG0WjStx96UaWULmdBRRGAAIjkzUKCM,469
+nanoagent/memory/backend.py,sha256=Fpet1SWf-FxlEbWcnA-0rUIM2TkazsgLqmX6P2GfGBo,931
+nanoagent/strategies/__init__.py,sha256=yFDGsE5OsndDjPuqJLfJlfBDAmul3UHpSw3To5W95r0,892
+nanoagent/strategies/context.py,sha256=lihmPrAB8EZQC0xGy9lT0UTV869nCo-PN5pkE8maOG8,899
+nanoagent/strategies/permission.py,sha256=aR8kTxLKrfdn3drXVRIQxJaVB5VIJMK97CXGPrJHtk4,790
+nanoagent/strategies/stop.py,sha256=-a5oJ3g3VNM2vAOhWZV_9esUoKizUUCd59ZdIUCE6QE,681
+nanoagent/tools/__init__.py,sha256=Oh0vdguDdpO8Ng9vRWF7R4DBf0c8Bzn5ss0qmxaXfb8,515
+nanoagent/tools/builtin.py,sha256=f6mmd_6ZIj8N_qHD8cIUY6nMwOZwcJTXvBDfpKbiVjQ,1504
+nanoagent/tools/decorator.py,sha256=CNT7eFUmkEULg6rOfdwJH33WtoV04qIVs3oO6GioTMA,1923
+nanoagent/tools/registry.py,sha256=qdZbaxAYKu74vX9lwkkV2rkneESws2VIyWlS2bfNrDk,845
+nanoagent/tools/schema.py,sha256=K2lZeHTTEH_vv3k9CxRLiTX3Ra_OIxBiiVmZvZW0Zqk,2888
+pynanoagent-0.1.0.dev0.dist-info/METADATA,sha256=BtmGd0VwBF9HtbVQ6s8thXkfX9H-ElYclgaqFDyLZfU,7659
+pynanoagent-0.1.0.dev0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pynanoagent-0.1.0.dev0.dist-info/entry_points.txt,sha256=HcMrlkgxrt-WpMphpgyfqpb7tvXEAFznb_39VcWakG0,54
+pynanoagent-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=5VL1IPyaZUR2uOprlubLZXyLvOtnUkQWuFpbU7rgzW8,1075
+pynanoagent-0.1.0.dev0.dist-info/RECORD,,

pynanoagent-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pynanoagent-0.1.0.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nanoagent = nanoagent.cli.main:main