aasai 0.1.0__tar.gz

aasai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ma-xiaodun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aasai-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: aasai
+Version: 0.1.0
+Summary: A minimal CLI agent
+Author: ma-xiaodun
+License-Expression: MIT
+Project-URL: Homepage, https://gitee.com/ma-xiaodun/ass
+Project-URL: Source, https://gitee.com/ma-xiaodun/ass
+Keywords: ai,agent,cli,tool-calling,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai
+Requires-Dist: pydantic
+Requires-Dist: ipython
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Dynamic: license-file
+
+# aas
+
+一个基于 OpenAI tool-calling 的轻量 CLI 智能体，可通过工具调用读写文件、执行代码。
+
+## 定位
+
+| 是 | 不是 |
+|---|---|
+| 信任 AI、方便第一 | 防备 AI、安全优先 |
+| 一句话提示词 + 通用工具 | 几万字工具定义 + 受限工具 |
+| 极简、单用户、个人工具 | 重武器、多用户、通用产品 |
+
+> 价值在"轻"，不在"功能多"。任何增加重量的优化，都是对它的背叛。
+> 期待被更简单的方案吞噬——被吞噬是成功，不是失败。
+
+## 安装
+
+| 步骤 | 命令 | 说明 |
+|---|---|---|
+| 1 | `pip install pipx` | 装 pipx（已有则跳过） |
+| 2 | `pipx install git+https://gitee.com/ma-xiaodun/ass.git` | 从 Gitee 装 aas + 全部依赖 |
+| 3 | 见下方 | Windows 配置 PATH；macOS/Linux 跳过 |
+
+**Windows 第三步**（在 PowerShell 执行，然后重开终端）：
+
+```powershell
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+[Environment]::SetEnvironmentVariable("Path", $userPath + ";$env:USERPROFILE\.local\bin", "User")
+```
+
+装完在任何目录运行 `aas` 或 `aas --web`。更新用 `pipx upgrade aas`。
+
+## 配置
+
+配置文件为 `~/.aas/config.json`（用户目录，与源码分离）。首次使用前创建：
+
+```json
+{
+  "MODEL": "deepseek-chat",
+  "DEEPSEEK_API_KEY": "你的密钥",
+  "DEEPSEEK_BASE_URL": "https://api.deepseek.com/v1",
+  "DEEPSEEK_MODELS": "deepseek-chat"
+}
+```
+
+- `MODEL`：当前模型名（必设，须在某供应商 `{P}_MODELS` 中登记）
+- 每个供应商三项：`{P}_API_KEY` / `{P}_BASE_URL` / `{P}_MODELS`（模型名逗号分隔）
+- `P` = 供应商名大写、连字符转下划线，如 `ark-plan` → `ARK_PLAN`
+
+## 使用
+
+**终端模式：**
+```bash
+aas
+```
+启动后输入内容对话；`exit` 退出。会话命令：`/new` 新会话、`/list` 列出、`/switch N` 切换、`/model` 切换默认模型。
+
+**Web 界面模式：**
+```bash
+aas --web
+```
+浏览器打开 <http://127.0.0.1:8765>，获得带 Markdown 渲染、流式输出、工具调用可见、会话切换的聊天界面。
+
+## 开发者
+
+```bash
+pip install -e .        # 可编辑安装，改代码即生效
+```
+
+- 配置与会话存于 `~/.aas/`，与源码分离，删除源码不影响数据。
+- 新增工具：新建 `aas/tools/xxx.py` → 在 `aas/tools/__init__.py` 加一行 → 生效。
+- 设计决策遵循 [CONSTITUTION.md](CONSTITUTION.md)。
+
+## 依赖
+
+- Python >= 3.11
+- openai
+- pydantic
+- ipython

aasai-0.1.0/README.md

@@ -0,0 +1,79 @@
+# aas
+
+一个基于 OpenAI tool-calling 的轻量 CLI 智能体，可通过工具调用读写文件、执行代码。
+
+## 定位
+
+| 是 | 不是 |
+|---|---|
+| 信任 AI、方便第一 | 防备 AI、安全优先 |
+| 一句话提示词 + 通用工具 | 几万字工具定义 + 受限工具 |
+| 极简、单用户、个人工具 | 重武器、多用户、通用产品 |
+
+> 价值在"轻"，不在"功能多"。任何增加重量的优化，都是对它的背叛。
+> 期待被更简单的方案吞噬——被吞噬是成功，不是失败。
+
+## 安装
+
+| 步骤 | 命令 | 说明 |
+|---|---|---|
+| 1 | `pip install pipx` | 装 pipx（已有则跳过） |
+| 2 | `pipx install git+https://gitee.com/ma-xiaodun/ass.git` | 从 Gitee 装 aas + 全部依赖 |
+| 3 | 见下方 | Windows 配置 PATH；macOS/Linux 跳过 |
+
+**Windows 第三步**（在 PowerShell 执行，然后重开终端）：
+
+```powershell
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+[Environment]::SetEnvironmentVariable("Path", $userPath + ";$env:USERPROFILE\.local\bin", "User")
+```
+
+装完在任何目录运行 `aas` 或 `aas --web`。更新用 `pipx upgrade aas`。
+
+## 配置
+
+配置文件为 `~/.aas/config.json`（用户目录，与源码分离）。首次使用前创建：
+
+```json
+{
+  "MODEL": "deepseek-chat",
+  "DEEPSEEK_API_KEY": "你的密钥",
+  "DEEPSEEK_BASE_URL": "https://api.deepseek.com/v1",
+  "DEEPSEEK_MODELS": "deepseek-chat"
+}
+```
+
+- `MODEL`：当前模型名（必设，须在某供应商 `{P}_MODELS` 中登记）
+- 每个供应商三项：`{P}_API_KEY` / `{P}_BASE_URL` / `{P}_MODELS`（模型名逗号分隔）
+- `P` = 供应商名大写、连字符转下划线，如 `ark-plan` → `ARK_PLAN`
+
+## 使用
+
+**终端模式：**
+```bash
+aas
+```
+启动后输入内容对话；`exit` 退出。会话命令：`/new` 新会话、`/list` 列出、`/switch N` 切换、`/model` 切换默认模型。
+
+**Web 界面模式：**
+```bash
+aas --web
+```
+浏览器打开 <http://127.0.0.1:8765>，获得带 Markdown 渲染、流式输出、工具调用可见、会话切换的聊天界面。
+
+## 开发者
+
+```bash
+pip install -e .        # 可编辑安装，改代码即生效
+```
+
+- 配置与会话存于 `~/.aas/`，与源码分离，删除源码不影响数据。
+- 新增工具：新建 `aas/tools/xxx.py` → 在 `aas/tools/__init__.py` 加一行 → 生效。
+- 设计决策遵循 [CONSTITUTION.md](CONSTITUTION.md)。
+
+## 依赖
+
+- Python >= 3.11
+- openai
+- pydantic
+- ipython

aasai-0.1.0/aas/__init__.py

@@ -0,0 +1 @@
+"""aas 智能体包。"""

aasai-0.1.0/aas/agent.py

@@ -0,0 +1,102 @@
+"""智能体运行时：工具调用循环。"""
+from __future__ import annotations
+
+import json
+
+from aas.context import compact_context, truncate
+from aas.display import Display, TerminalDisplay
+from aas.provider import get_client_and_model
+from aas.tools import TOOL_DEFINITIONS, _TOOLS
+
+SYSTEM_PROMPT = "你是一个有用的助手，可以使用工具完成任务。"
+MAX_TURNS = 30
+
+# ── 工具执行 ──────────────────────────────────────
+
+def _run_tool(tc: dict, display: Display) -> str:
+    name = tc["function"]["name"]
+    try:
+        args = json.loads(tc["function"]["arguments"])
+    except json.JSONDecodeError as e:
+        return f"错误：参数 JSON 解析失败 — {e}"
+    func = _TOOLS.get(name)
+    if func is None:
+        return f"错误：未知工具 {name}"
+    display.tool_call(name, tc["function"]["arguments"])
+    try:
+        result = func(**args)
+    except Exception as e:
+        return f"错误：工具执行失败 — {e}"
+    return truncate(str(result))
+
+
+# ── 流式解析 ──────────────────────────────────────
+
+def _stream_parse(client, model, messages: list, display: Display) -> dict:
+    stream = client.chat.completions.create(
+        model=model, messages=messages, tools=TOOL_DEFINITIONS, stream=True
+    )
+    content = ""
+    reasoning = ""
+    tool_calls: list[dict] = []
+    for chunk in stream:
+        delta = chunk.choices[0].delta
+        if delta.content:
+            content += delta.content
+            display.delta(delta.content)
+        reasoning_chunk = getattr(delta, "reasoning_content", None)
+        if reasoning_chunk:
+            reasoning += reasoning_chunk
+            display.thinking(reasoning_chunk)
+        if delta.tool_calls:
+            for tc_chunk in delta.tool_calls:
+                idx = tc_chunk.index
+                while len(tool_calls) <= idx:
+                    tool_calls.append(
+                        {"id": "", "type": "function", "function": {"name": "", "arguments": ""}}
+                    )
+                if tc_chunk.id:
+                    tool_calls[idx]["id"] = tc_chunk.id
+                if tc_chunk.function is not None:
+                    if tc_chunk.function.name:
+                        tool_calls[idx]["function"]["name"] = tc_chunk.function.name
+                    if tc_chunk.function.arguments:
+                        tool_calls[idx]["function"]["arguments"] += tc_chunk.function.arguments
+    return {"content": content, "tool_calls": tool_calls, "reasoning": reasoning}
+
+
+def _run_tool_calls(tool_calls: list[dict], display: Display, messages: list) -> None:
+    for tc in tool_calls:
+        name = tc["function"]["name"]
+        result = _run_tool(tc, display)
+        display.tool_result(name, str(result))
+        messages.append({"role": "tool", "tool_call_id": tc["id"], "content": str(result)})
+
+
+# ── 主循环 ────────────────────────────────────────
+
+def run_agent(user_input: str, messages: list, display: Display | None = None) -> list:
+    display = display or TerminalDisplay()
+    messages = [*messages, {"role": "user", "content": user_input}]
+    client, model = get_client_and_model()
+
+    for _ in range(MAX_TURNS):
+        messages = compact_context(messages)
+        msg = _stream_parse(client, model, messages, display)
+        if not msg["tool_calls"]:
+            display.flush()
+            messages.append({"role": "assistant", "content": msg["content"]})
+            return messages
+
+        assistant = {
+            "role": "assistant",
+            "content": msg["content"],
+            "tool_calls": msg["tool_calls"],
+        }
+        if msg.get("reasoning"):
+            assistant["reasoning_content"] = msg["reasoning"]
+        messages.append(assistant)
+        _run_tool_calls(msg["tool_calls"], display, messages)
+
+    display.notice("\n已达到最大工具调用轮数，停止。")
+    return messages

aasai-0.1.0/aas/commands.py

@@ -0,0 +1,91 @@
+"""斜杠命令处理：/new /list /switch /model，经 Display 输出（终端/Web 统一可见）。
+
+命令反馈不再直接 print，而是走 Display 协议——Web 模式经 SSE 推给浏览器，
+终端模式打印到 stdout。单一执行路径（宪法硬约束）。
+"""
+from __future__ import annotations
+
+from aas.display import Display
+from aas.history import (
+    load as load_history,
+    save as save_history,
+    current_id,
+    set_current,
+    list_sessions,
+    new_session,
+)
+from aas.agent import SYSTEM_PROMPT
+from aas.context import compact_context
+from aas.provider import list_models, resolve_provider, set_default_model, get_default_model
+
+
+def handle(cmd: str, messages: list, display: Display) -> tuple[list, bool]:
+    """处理斜杠命令。返回 (新消息列表, 是否已处理需继续)。
+
+    display 用于输出命令反馈；命令处理与显示层解耦。
+    """
+    cmd = cmd.strip().lower()
+    if cmd == "/help":
+        display.notice("\n可用命令：")
+        display.notice("  /new      新建会话")
+        display.notice("  /list     列出所有会话")
+        display.notice("  /switch N 切换到会话 N")
+        display.notice("  /model    查看/切换默认模型")
+        display.notice("  /compact  压缩对话历史（LLM 摘要）")
+        display.notice("  /help     显示此帮助")
+        display.notice("  exit      退出")
+        return messages, True
+    if cmd == "/new":
+        sid = new_session()
+        display.notice(f"\n已新建会话 {sid}（清空消息）")
+        return [{"role": "system", "content": SYSTEM_PROMPT}], True
+    if cmd == "/compact":
+        display.notice("\n正在压缩对话历史（LLM 摘要）…")
+        try:
+            new_messages = compact_context(messages, llm=True)
+            if new_messages == messages:
+                display.notice("\n压缩未产生变化（可能失败或已精简）")
+            else:
+                save_history(current_id(), new_messages)
+                display.notice("\n压缩完成，历史已精简为摘要。")
+            return new_messages, True
+        except Exception as e:
+            display.notice(f"\n压缩失败：{e}")
+            return messages, True
+    if cmd == "/list":
+        current = current_id()
+        for s in list_sessions():
+            mark = " ← 当前" if s == current else ""
+            display.notice(f"  会话 {s}{mark}")
+        return messages, True
+    if cmd.startswith("/switch"):
+        parts = cmd.split()
+        if len(parts) == 2 and parts[1].isdigit():
+            sid = parts[1]
+            all_ids = list_sessions()
+            if sid in all_ids:
+                set_current(sid)
+                display.notice(f"\n已切换到会话 {sid}")
+                return load_history(sid) or [{"role": "system", "content": SYSTEM_PROMPT}], True
+            display.notice(f"\n会话 {sid} 不存在（可用 /list 查看）")
+            return messages, True
+        display.notice("\n用法：/switch <会话号>")
+        return messages, True
+    if cmd.startswith("/model"):
+        parts = cmd.split()
+        if len(parts) == 1:
+            display.notice(f"\n当前模型：{get_default_model()}")
+            display.notice(f"可用模型：{'、'.join(list_models())}")
+            display.notice("用法：/model <模型名>（持久保存到 config.json）")
+            return messages, True
+        if len(parts) > 2:
+            display.notice("\n用法：/model <模型名>")
+            return messages, True
+        token = parts[1]
+        if resolve_provider(token) is None:
+            display.notice(f"\n模型不存在：{token}（可用：{'、'.join(list_models())}）")
+            return messages, True
+        set_default_model(token)
+        display.notice(f"\n已切换默认模型：{token}（已保存到 config.json，重启后保留）")
+        return messages, True
+    return messages, False

aasai-0.1.0/aas/compact_prompt.md

@@ -0,0 +1,49 @@
+你正在对一个 AI 编程助手的对话历史做结构化压缩。
+你的输出会替换对话，压缩后模型应能无缝继续工作。
+
+压缩不是降采样式摘要（那会丢核心思想），而是两层并行：
+① 事实层——原样照抄，不转述、不诠释、不"优化措辞"；
+② 提炼层——在事实之上做受控抽象，把隐含的结构提炼出来。两层分开放，不混。
+
+事实层（原样照抄）：
+- 文件路径、文件名
+- 错误信息、堆栈跟踪、测试输出、关键执行结果
+- 已修改文件的具体变更、关键代码片段
+- 必须遵守硬约束
+- 用户提出但尚未响应的请求
+
+提炼层（基于上述事实，执行三个动作，不脱离事实外推）：
+- 析微：把纠缠的问题拆成基本命题，挑明对话里隐含但从未明说的前提与约束
+- 取骨：剥离一次性细节，提取"内容会变而结构不变"的内核——这件事的骨架是什么
+- 溯源：把分散的踩坑与决策归因到根本前提，而非罗列表面现象
+
+判断什么该留：若不知道某条，后续决策会不会改变？会变就留，不变才删。
+
+严格按此格式输出：
+
+## 已完成
+[逐条列出已改的文件、已完成的功能]
+
+## 当前状态
+[正在进行的任务及进度]
+
+## 用户约束
+[用户明说的硬约束、边界条件、不能违反的规则——原样照抄用户措辞]
+
+## 相关文件
+[本次工作涉及的文件路径清单——纯路径，不含代码内容]
+
+## 关键事实
+[错误信息、代码片段、配置变更、执行结果等，原样照抄。不含文件清单——已单列]
+
+## 问题骨架
+[析微+取骨+溯源的产物：当前问题拆解后的基本命题、不变的结构内核、踩坑与决策的根本原因]
+
+## 避坑
+[试过但不通的路、被否定的假设、中途发现的约束——让接续者不重蹈覆辙]
+
+## 待办
+[模型自己的下一步计划]
+
+## 用户未决
+[用户提过但还没处理的请求——原样照抄用户措辞，避免下一轮遗漏]

aasai-0.1.0/aas/context.py

@@ -0,0 +1,126 @@
+"""上下文管理：确定性截断 + LLM 摘要 的统一入口。
+
+agent（主循环自动）与 commands（/compact 手动）都从这里取压缩能力，
+避免命令模块反向依赖编排核心。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from aas.provider import get_client_and_model
+
+MAX_CONTEXT_CHARS = 300_000
+
+# ── 上下文压缩：确定性纯函数 ──────────────────────
+
+_CTX_TOOL_CONTENT_LIMIT = 800
+_HOT_TOOL_TURNS = 3
+_WARM_TOOL_TURNS = 7
+
+
+def truncate(text: str, max_chars: int = 30000) -> str:
+    """超长文本统一截断：保留头/中/尾 40%/20%/40%，并明确标注截断。
+
+    agent 工具结果与上下文压缩共用此函数，截断策略单一来源。
+    """
+    if len(text) <= max_chars:
+        return text
+    head_n = int(max_chars * 0.4)
+    middle_n = int(max_chars * 0.2)
+    tail_n = max_chars - head_n - middle_n
+    middle_start = (len(text) - middle_n) // 2
+    return (
+        f"{text[:head_n]}\n"
+        f"\n[... 截断 {len(text) - max_chars:,} 字符，保留头/中/尾各 40%/20/40% ...]\n\n"
+        f"{text[middle_start:middle_start + middle_n]}\n"
+        f"\n[... 截断继续 ...]\n\n"
+        f"{text[-tail_n:]}"
+    )
+
+
+def _total_chars(messages: list) -> int:
+    """上下文字符量：content + reasoning_content（工具轮思维链真实参与上下文）。"""
+    return sum(
+        (len(m.get("content", "")) if isinstance(m.get("content"), str) else 0)
+        + (len(m.get("reasoning_content", "")) if isinstance(m.get("reasoning_content"), str) else 0)
+        for m in messages
+    )
+
+
+def _placeholder(text: str) -> str:
+    """冷层占位：首行（含路径/操作标识）+ 压缩标记。"""
+    first = text.split("\n", 1)[0][:200]
+    return f"[已压缩，原 {len(text)} 字符] {first}"
+
+
+def _compact_tools(messages: list) -> list:
+    """按轮次年龄分层 tool 消息：热全保留 / 温截断 / 冷占位。"""
+    users_seen = 0
+    out = []
+    for m in reversed(messages):
+        if m.get("role") == "user":
+            users_seen += 1
+        elif (
+            m.get("role") == "tool"
+            and isinstance(m.get("content"), str)
+            and len(m["content"]) > _CTX_TOOL_CONTENT_LIMIT
+        ):
+            age = users_seen
+            if age >= _HOT_TOOL_TURNS + _WARM_TOOL_TURNS:
+                m = {**m, "content": _placeholder(m["content"])}
+            elif age >= _HOT_TOOL_TURNS:
+                m = {**m, "content": truncate(m["content"], _CTX_TOOL_CONTENT_LIMIT)}
+        out.append(m)
+    out.reverse()
+    return out
+
+
+def compact_deterministic(messages: list, max_chars: int) -> list:
+    """超限时仅分层压缩 tool 消息，不自动丢对话轮（兜底由用户 /compact）。"""
+    if _total_chars(messages) <= max_chars:
+        return messages
+    return _compact_tools(messages)
+
+
+# ── 上下文压缩：LLM 摘要 ──────────────────────────
+
+_COMPACT_PROMPT = (Path(__file__).parent / "compact_prompt.md").read_text("utf-8")
+
+
+def _llm_summarize(client, model: str, messages: list) -> str:
+    payload = json.dumps(messages, ensure_ascii=False)
+    resp = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": _COMPACT_PROMPT},
+            {"role": "user", "content": payload},
+        ],
+    )
+    return resp.choices[0].message.content or ""
+
+
+def compact_llm(messages: list) -> list:
+    """LLM 语义摘要压缩。失败返回原样。"""
+    try:
+        client, resolved_model = get_client_and_model()
+        reply = _llm_summarize(client, resolved_model, messages)
+        if not reply:
+            return messages
+        system = [m for m in messages if m.get("role") == "system"]
+        return system + [{"role": "assistant", "content": reply}]
+    except Exception:
+        return messages
+
+
+# ── 对外统一入口 ──────────────────────────────────
+
+def compact_context(messages: list, *, llm: bool = False) -> list:
+    """上下文压缩统一入口。
+
+    llm=False：确定性纯函数压缩（零成本，自动触发）
+    llm=True：LLM 语义摘要压缩（有成本，手动触发）
+    """
+    if llm:
+        return compact_llm(messages)
+    return compact_deterministic(messages, MAX_CONTEXT_CHARS)

aasai-0.1.0/aas/display.py

@@ -0,0 +1,69 @@
+"""显示接口：agent 循环通过它通知显示层，自身不渲染。
+
+编排层（agent.py）只产生事件；显示层决定如何呈现（终端直接打印、未来 Web 推送）。
+当前终端实现保持流式打字机效果；工具调用/返回以摘要显示，不刷屏。
+"""
+from __future__ import annotations
+
+import sys
+from typing import Protocol
+
+# 工具调用/返回摘要最大字符数：完整内容仍喂给模型，显示层只展示摘要
+_MAX_SUMMARY = 200
+
+
+def _summary(text: str, limit: int = _MAX_SUMMARY) -> str:
+    """压缩空白并截断为单行摘要；超长保留头尾 + 长度提示。"""
+    text = " ".join(text.split())
+    if len(text) <= limit:
+        return text
+    head_n = limit // 2
+    return f"{text[:head_n]}…（共 {len(text)} 字符）…{text[-head_n:]}"
+
+
+class Display(Protocol):
+    """显示协议：delta/thinking/tool_call/tool_result/notice/flush 六类事件。"""
+
+    def delta(self, token: str) -> None: ...
+    def thinking(self, token: str) -> None: ...
+    def tool_call(self, name: str, arguments: str) -> None: ...
+    def tool_result(self, name: str, content: str) -> None: ...
+    def notice(self, text: str) -> None: ...
+    def flush(self) -> None: ...
+
+
+class TerminalDisplay(Display):
+    """终端实现：流式打字机 + 工具调用/返回摘要。"""
+
+    def __init__(self, stream=None) -> None:
+        self._stream = stream or sys.stdout
+
+    def delta(self, token: str) -> None:
+        """流式内容增量：保持打字机效果（不换行、立即 flush）。"""
+        self._stream.write(token)
+        self._stream.flush()
+
+    def thinking(self, token: str) -> None:
+        """思考内容增量：弱化色显示，不换行、立即 flush。"""
+        self._stream.write(f"\033[90m{token}\033[0m")
+        self._stream.flush()
+
+    def tool_call(self, name: str, arguments: str) -> None:
+        """工具被调用：显示工具名与参数摘要。"""
+        self._stream.write(f"\n\n◈ 调用工具 {name}({_summary(arguments)})\n")
+        self._stream.flush()
+
+    def tool_result(self, name: str, content: str) -> None:
+        """工具返回：显示结果摘要（截断，避免大输出刷屏）。"""
+        self._stream.write(f"◈ {name} 返回：{_summary(content)}\n")
+        self._stream.flush()
+
+    def notice(self, text: str) -> None:
+        """非流式提示消息（如达到最大轮数）。"""
+        self._stream.write(text + "\n")
+        self._stream.flush()
+
+    def flush(self) -> None:
+        """一段输出结束：换行。"""
+        self._stream.write("\n")
+        self._stream.flush()