shellmate-ai 0.1.0__tar.gz → 0.1.2__tar.gz

shellmate_ai-0.1.2/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src *.zsh
+recursive-include src/shellmate/prompts *.md

shellmate_ai-0.1.2/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: shellmate-ai
+Version: 0.1.2
+Summary: An AI assistant for your zsh command line
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langgraph<2.0,>=1.0
+Requires-Dist: langgraph-checkpoint-sqlite<4.0,>=3.0
+Requires-Dist: langchain-openai<2.0,>=1.0
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: rich<14.0,>=13.0
+Dynamic: license-file
+
+# Shellmate
+
+🇨🇳 简体中文 | [🇬🇧 English](README.en.md)
+
+[![PyPI](https://img.shields.io/pypi/v/shellmate-ai?color=blue)](https://pypi.org/project/shellmate-ai/)
+[![Python](https://img.shields.io/pypi/pyversions/shellmate-ai.svg)](https://pypi.org/project/shellmate-ai/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Shellmate 是一个面向 zsh 的命令行 AI 助手。在命令行输入问题后按 **Ctrl-G**，它会结合近期命令历史，用任意 OpenAI 兼容模型（OpenAI、DeepSeek、Qwen 等）给出回答。
+
+## 功能
+
+- **Ctrl-G** 快捷键 — 在命令行输入问题后按 Ctrl-G 提问（空缓冲时只提示先输入问题）
+- 终端内渲染 Markdown（代码高亮、表格、列表）
+- 自动捕获上一条命令及其退出码，失败时在提示符上方提示
+- 命令失败后按 **Ctrl-X** 用管道重跑该命令，让 agent 看**完整报错**再解释
+- 近期命令历史作为上下文
+- OpenAI 兼容协议，支持 OpenAI / DeepSeek / Qwen 等
+- 系统提示词可编辑（`~/.config/shellmate/Agent.md`），默认模板随包下发
+- 内置 DuckDuckGo 网页搜索，无需搜索 API Key
+- 模型与搜索请求前自动脱敏：密钥前缀、高熵 token、`KEY=value`、引号包裹的秘密、Webhook URL、URL 内嵌凭据、`curl -u` / `mysql -pXXX` 等命令行开关
+- 本地 SQLite 保存会话记忆（checkpoint），无需数据库服务
+
+## 安装
+
+需要 Python 3.11+。
+
+```sh
+pip install shellmate-ai   # 或从源码：pip install -e .
+shellmate-ai init          # 创建配置 + Agent 提示词 + zsh 插件 + .zshrc 加载行
+source ~/.zshrc            # 或重开终端
+```
+
+> **注**：安装后命令行工具名为 `shellmate-ai`（与 PyPI 包名一致）。
+
+## 使用
+
+在 zsh 中输入问题，然后按 **Ctrl-G**，agent 会结合近期命令历史回答。空缓冲按 Ctrl-G 不会去猜上一条命令的失败原因，只提示你先输入问题 —— 原因是 zsh 没有"命令执行结束"的钩子，命令的输出在提示符重绘时就已经消失，Shellmate 从未捕获过它。想让 agent 看到真正的报错，用 **Ctrl-X** 重跑该命令，或自己接管道。
+
+| 触发方式 | agent 能看到什么 |
+| --- | --- |
+| Ctrl-G（命令行有输入） | 你的问题 + 近期命令历史 |
+| Ctrl-G（空缓冲） | 什么都不问，只在终端提示"请先输入问题" |
+| Ctrl-X | 重新执行上一条命令，把 stdout+stderr 合并后的输出交给 agent |
+| `cmd 2>&1 \| shellmate-ai explain` | 同上，但要跑哪条命令由你自己决定 |
+| `shellmate-ai explain-last --last-command CMD --last-exit N` | 只有命令和退出码，**没有输出**，适合脚本；模型被明确告知不要编造报错 |
+
+命令失败时（非零退出码），提示符上方会出现提示：按 **Ctrl-X** 会把上一条命令用 `2>&1 | shellmate-ai explain` 重跑，把合并后的输出交给 agent 解释（重跑可能有副作用，所以由你手动触发）。
+
+> **注**：Ctrl-X 任何时候都可用，不限于失败之后；输出过长时只保留末尾 2 万字符。`^X` 同时是 zsh 默认键位的前缀（如 `^X^U` 撤销、`^Xr` 历史搜索），所以 ZLE 会先等待 `KEYTIMEOUT`（默认 0.4 秒）再触发重跑——那些 `^X` 开头的组合键不受影响，觉得迟滞可以自行调小 `KEYTIMEOUT`。另外，绑定 Ctrl-G 会覆盖 zsh 默认的 `send-break`（取消当前命令行）；想找回默认行为，可以执行 `bindkey '^G' send-break`，或给插件换个键位。
+
+```sh
+shellmate-ai ask "刚才的命令为什么失败？"                    # 直接提问
+shellmate-ai ask                                            # 交互式提问
+shellmate-ai ask --history $'ls -la\ngit status' "解释一下"  # 手动传历史
+shellmate-ai ask --thread-id my-task "换个新会话"            # 指定会话 ID
+
+# 把命令输出喂给 Shellmate 解释（管道模式）
+git push origin main 2>&1 | shellmate-ai explain
+tail -200 app.log | shellmate-ai explain "为什么一直报 timeout？"
+
+shellmate-ai explain-last --last-command "make build" --last-exit 2  # 只用命令+退出码解释（无输出）
+shellmate-ai config-path                              # 查看配置路径
+shellmate-ai history-lines                            # 查看历史条数
+```
+
+## 配置
+
+`shellmate-ai init` 会创建 `~/.config/shellmate/config.json` 和 `Agent.md`。在 config.json 中填入 API Key，或用环境变量设置。
+
+`Agent.md` 是系统提示词，可以直接编辑：初始内容来自包内模板 `src/shellmate/prompts/Agent.md`（随 wheel/sdist 一起下发），只在文件不存在时写入，不会覆盖你的修改；改动对新会话生效。
+
+```json
+{
+  "llm": { "base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key": "", "timeout": 60.0 },
+  "shell": { "history_lines": 20 },
+  "search": { "endpoint": "https://html.duckduckgo.com/html/" },
+  "privacy": { "redact_secrets": true, "redact_high_entropy": true, "custom_patterns": [] }
+}
+```
+
+字段约束：`llm.timeout` 大于 0 且不超过 600 秒，`shell.history_lines` 为 1–500，`search.endpoint` 必须是 HTTP(S) URL；`privacy.custom_patterns` 是额外的正则，命中后替换为 `[REDACTED]`；关闭 `privacy.redact_secrets` 会同时停用高熵检测。配置中出现未知字段（含已移除的 `provider`、`output_file`、`checkpoint`）会直接报错并指出字段名，不会被静默忽略。
+
+环境变量会覆盖 JSON 配置：
+
+| 变量 | 覆盖 |
+| --- | --- |
+| `OPENAI_API_KEY` / `SHELLMATE_API_KEY` | `llm.api_key` |
+| `SHELLMATE_BASE_URL` | `llm.base_url` |
+| `SHELLMATE_MODEL` | `llm.model` |
+| `SHELLMATE_THREAD_ID` | `thread_id`（会话记忆 ID，默认 `shellmate-cli-default`） |
+| `SHELLMATE_SEARCH_ENDPOINT` | `search.endpoint` |
+
+CLI 另外会读取 `SHELLMATE_SESSION_ID`（未指定 `--thread-id` 时的会话 ID，由 zsh 插件按窗口设置），以及 `SHELLMATE_HISTORY_TEXT`、`SHELLMATE_LAST_COMMAND`、`SHELLMATE_LAST_EXIT` 作为兜底值 —— 新版插件用 `--history` 参数传历史，另外几个变量只为兼容已安装的旧插件保留。未设置 `HISTFILE` 时，历史文件按 `~/.zsh_history` 读取。
+
+### 运行时文件
+
+| 路径 | 说明 |
+| --- | --- |
+| `~/.config/shellmate/config.json` | 配置，权限 600 |
+| `~/.config/shellmate/Agent.md` | 系统提示词，权限 600，可自由编辑 |
+| `~/.config/shellmate/shellmate.zsh` | zsh 插件，由 `shellmate-ai init` 写入，权限 644 |
+| `~/.config/shellmate/data/checkpoints.sqlite` | 会话记忆，SQLite，目录权限 700 |
+| `~/.zshrc` | 由 `init` 幂等追加 `source ~/.config/shellmate/shellmate.zsh` |
+
+## 架构
+
+Agent 是一个 LangGraph 状态机：
+
+```mermaid
+flowchart TD
+    Start([start]) --> SystemPrompt["system_prompt<br/>加载 Agent.md"]
+    SystemPrompt --> Assistant["assistant<br/>调用模型"]
+    Assistant -->|需要工具| Tools["tools<br/>网页搜索"]
+    Assistant -->|结束| End([end])
+    Tools --> Assistant
+```
+
+- **system_prompt** — 某个会话首次执行时读取可编辑的 `Agent.md`，作为系统提示词写入状态（每个会话一次）
+- **assistant** — 把系统提示词置于最前，仅对会话消息脱敏后调用 OpenAI 兼容模型
+- **tools** — 模型请求联网时执行 DuckDuckGo 搜索
+
+## 项目结构
+
+```text
+src/shellmate/
+├── agent.py           # LangGraph agent + SQLite checkpoint
+├── cli.py             # 命令行入口
+├── config.py          # Pydantic 配置 + 读取包内默认提示词
+├── context.py         # 历史格式化
+├── privacy.py         # 脱敏中间件
+├── zsh_plugin.py      # 内置 zsh 插件（从 shellmate.zsh 数据文件读取）
+├── shellmate.zsh      # zsh 插件（Ctrl-G / Ctrl-X / preexec / precmd）
+├── prompts/
+│   └── Agent.md       # 默认系统提示词模板（init 时写入配置目录）
+└── tools/
+    └── web_search.py  # DuckDuckGo HTML 搜索
+```
+
+## License
+
+[MIT](LICENSE)

shellmate_ai-0.1.2/README.md

@@ -0,0 +1,142 @@
+# Shellmate
+
+🇨🇳 简体中文 | [🇬🇧 English](README.en.md)
+
+[![PyPI](https://img.shields.io/pypi/v/shellmate-ai?color=blue)](https://pypi.org/project/shellmate-ai/)
+[![Python](https://img.shields.io/pypi/pyversions/shellmate-ai.svg)](https://pypi.org/project/shellmate-ai/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Shellmate 是一个面向 zsh 的命令行 AI 助手。在命令行输入问题后按 **Ctrl-G**，它会结合近期命令历史，用任意 OpenAI 兼容模型（OpenAI、DeepSeek、Qwen 等）给出回答。
+
+## 功能
+
+- **Ctrl-G** 快捷键 — 在命令行输入问题后按 Ctrl-G 提问（空缓冲时只提示先输入问题）
+- 终端内渲染 Markdown（代码高亮、表格、列表）
+- 自动捕获上一条命令及其退出码，失败时在提示符上方提示
+- 命令失败后按 **Ctrl-X** 用管道重跑该命令，让 agent 看**完整报错**再解释
+- 近期命令历史作为上下文
+- OpenAI 兼容协议，支持 OpenAI / DeepSeek / Qwen 等
+- 系统提示词可编辑（`~/.config/shellmate/Agent.md`），默认模板随包下发
+- 内置 DuckDuckGo 网页搜索，无需搜索 API Key
+- 模型与搜索请求前自动脱敏：密钥前缀、高熵 token、`KEY=value`、引号包裹的秘密、Webhook URL、URL 内嵌凭据、`curl -u` / `mysql -pXXX` 等命令行开关
+- 本地 SQLite 保存会话记忆（checkpoint），无需数据库服务
+
+## 安装
+
+需要 Python 3.11+。
+
+```sh
+pip install shellmate-ai   # 或从源码：pip install -e .
+shellmate-ai init          # 创建配置 + Agent 提示词 + zsh 插件 + .zshrc 加载行
+source ~/.zshrc            # 或重开终端
+```
+
+> **注**：安装后命令行工具名为 `shellmate-ai`（与 PyPI 包名一致）。
+
+## 使用
+
+在 zsh 中输入问题，然后按 **Ctrl-G**，agent 会结合近期命令历史回答。空缓冲按 Ctrl-G 不会去猜上一条命令的失败原因，只提示你先输入问题 —— 原因是 zsh 没有"命令执行结束"的钩子，命令的输出在提示符重绘时就已经消失，Shellmate 从未捕获过它。想让 agent 看到真正的报错，用 **Ctrl-X** 重跑该命令，或自己接管道。
+
+| 触发方式 | agent 能看到什么 |
+| --- | --- |
+| Ctrl-G（命令行有输入） | 你的问题 + 近期命令历史 |
+| Ctrl-G（空缓冲） | 什么都不问，只在终端提示"请先输入问题" |
+| Ctrl-X | 重新执行上一条命令，把 stdout+stderr 合并后的输出交给 agent |
+| `cmd 2>&1 \| shellmate-ai explain` | 同上，但要跑哪条命令由你自己决定 |
+| `shellmate-ai explain-last --last-command CMD --last-exit N` | 只有命令和退出码，**没有输出**，适合脚本；模型被明确告知不要编造报错 |
+
+命令失败时（非零退出码），提示符上方会出现提示：按 **Ctrl-X** 会把上一条命令用 `2>&1 | shellmate-ai explain` 重跑，把合并后的输出交给 agent 解释（重跑可能有副作用，所以由你手动触发）。
+
+> **注**：Ctrl-X 任何时候都可用，不限于失败之后；输出过长时只保留末尾 2 万字符。`^X` 同时是 zsh 默认键位的前缀（如 `^X^U` 撤销、`^Xr` 历史搜索），所以 ZLE 会先等待 `KEYTIMEOUT`（默认 0.4 秒）再触发重跑——那些 `^X` 开头的组合键不受影响，觉得迟滞可以自行调小 `KEYTIMEOUT`。另外，绑定 Ctrl-G 会覆盖 zsh 默认的 `send-break`（取消当前命令行）；想找回默认行为，可以执行 `bindkey '^G' send-break`，或给插件换个键位。
+
+```sh
+shellmate-ai ask "刚才的命令为什么失败？"                    # 直接提问
+shellmate-ai ask                                            # 交互式提问
+shellmate-ai ask --history $'ls -la\ngit status' "解释一下"  # 手动传历史
+shellmate-ai ask --thread-id my-task "换个新会话"            # 指定会话 ID
+
+# 把命令输出喂给 Shellmate 解释（管道模式）
+git push origin main 2>&1 | shellmate-ai explain
+tail -200 app.log | shellmate-ai explain "为什么一直报 timeout？"
+
+shellmate-ai explain-last --last-command "make build" --last-exit 2  # 只用命令+退出码解释（无输出）
+shellmate-ai config-path                              # 查看配置路径
+shellmate-ai history-lines                            # 查看历史条数
+```
+
+## 配置
+
+`shellmate-ai init` 会创建 `~/.config/shellmate/config.json` 和 `Agent.md`。在 config.json 中填入 API Key，或用环境变量设置。
+
+`Agent.md` 是系统提示词，可以直接编辑：初始内容来自包内模板 `src/shellmate/prompts/Agent.md`（随 wheel/sdist 一起下发），只在文件不存在时写入，不会覆盖你的修改；改动对新会话生效。
+
+```json
+{
+  "llm": { "base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key": "", "timeout": 60.0 },
+  "shell": { "history_lines": 20 },
+  "search": { "endpoint": "https://html.duckduckgo.com/html/" },
+  "privacy": { "redact_secrets": true, "redact_high_entropy": true, "custom_patterns": [] }
+}
+```
+
+字段约束：`llm.timeout` 大于 0 且不超过 600 秒，`shell.history_lines` 为 1–500，`search.endpoint` 必须是 HTTP(S) URL；`privacy.custom_patterns` 是额外的正则，命中后替换为 `[REDACTED]`；关闭 `privacy.redact_secrets` 会同时停用高熵检测。配置中出现未知字段（含已移除的 `provider`、`output_file`、`checkpoint`）会直接报错并指出字段名，不会被静默忽略。
+
+环境变量会覆盖 JSON 配置：
+
+| 变量 | 覆盖 |
+| --- | --- |
+| `OPENAI_API_KEY` / `SHELLMATE_API_KEY` | `llm.api_key` |
+| `SHELLMATE_BASE_URL` | `llm.base_url` |
+| `SHELLMATE_MODEL` | `llm.model` |
+| `SHELLMATE_THREAD_ID` | `thread_id`（会话记忆 ID，默认 `shellmate-cli-default`） |
+| `SHELLMATE_SEARCH_ENDPOINT` | `search.endpoint` |
+
+CLI 另外会读取 `SHELLMATE_SESSION_ID`（未指定 `--thread-id` 时的会话 ID，由 zsh 插件按窗口设置），以及 `SHELLMATE_HISTORY_TEXT`、`SHELLMATE_LAST_COMMAND`、`SHELLMATE_LAST_EXIT` 作为兜底值 —— 新版插件用 `--history` 参数传历史，另外几个变量只为兼容已安装的旧插件保留。未设置 `HISTFILE` 时，历史文件按 `~/.zsh_history` 读取。
+
+### 运行时文件
+
+| 路径 | 说明 |
+| --- | --- |
+| `~/.config/shellmate/config.json` | 配置，权限 600 |
+| `~/.config/shellmate/Agent.md` | 系统提示词，权限 600，可自由编辑 |
+| `~/.config/shellmate/shellmate.zsh` | zsh 插件，由 `shellmate-ai init` 写入，权限 644 |
+| `~/.config/shellmate/data/checkpoints.sqlite` | 会话记忆，SQLite，目录权限 700 |
+| `~/.zshrc` | 由 `init` 幂等追加 `source ~/.config/shellmate/shellmate.zsh` |
+
+## 架构
+
+Agent 是一个 LangGraph 状态机：
+
+```mermaid
+flowchart TD
+    Start([start]) --> SystemPrompt["system_prompt<br/>加载 Agent.md"]
+    SystemPrompt --> Assistant["assistant<br/>调用模型"]
+    Assistant -->|需要工具| Tools["tools<br/>网页搜索"]
+    Assistant -->|结束| End([end])
+    Tools --> Assistant
+```
+
+- **system_prompt** — 某个会话首次执行时读取可编辑的 `Agent.md`，作为系统提示词写入状态（每个会话一次）
+- **assistant** — 把系统提示词置于最前，仅对会话消息脱敏后调用 OpenAI 兼容模型
+- **tools** — 模型请求联网时执行 DuckDuckGo 搜索
+
+## 项目结构
+
+```text
+src/shellmate/
+├── agent.py           # LangGraph agent + SQLite checkpoint
+├── cli.py             # 命令行入口
+├── config.py          # Pydantic 配置 + 读取包内默认提示词
+├── context.py         # 历史格式化
+├── privacy.py         # 脱敏中间件
+├── zsh_plugin.py      # 内置 zsh 插件（从 shellmate.zsh 数据文件读取）
+├── shellmate.zsh      # zsh 插件（Ctrl-G / Ctrl-X / preexec / precmd）
+├── prompts/
+│   └── Agent.md       # 默认系统提示词模板（init 时写入配置目录）
+└── tools/
+    └── web_search.py  # DuckDuckGo HTML 搜索
+```
+
+## License
+
+[MIT](LICENSE)

{shellmate_ai-0.1.0 → shellmate_ai-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shellmate-ai"
-version = "0.1.0"
+version = "0.1.2"
 description = "An AI assistant for your zsh command line"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,10 +9,11 @@ dependencies = [
     "langgraph-checkpoint-sqlite>=3.0,<4.0",
     "langchain-openai>=1.0,<2.0",
     "pydantic>=2.7,<3.0",
+    "rich>=13.0,<14.0",
 ]
 
 [project.scripts]
-shellmate = "shellmate.cli:main"
+shellmate-ai = "shellmate.cli:main"
 
 [build-system]
 requires = ["setuptools>=68"]
@@ -22,4 +23,4 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-shellmate = ["*.zsh"]
+shellmate = ["*.zsh", "prompts/*.md"]

shellmate_ai-0.1.2/src/shellmate/__init__.py

@@ -0,0 +1,9 @@
+"""Shellmate：面向 shell 的 AI 助手。"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("shellmate-ai")
+except PackageNotFoundError:
+    # 未通过 pip/uv 安装（如直接运行源码）时回退到占位版本。
+    __version__ = "0.1.0"

{shellmate_ai-0.1.0 → shellmate_ai-0.1.2}/src/shellmate/agent.py

@@ -77,9 +77,21 @@ class LangGraphAgent:
         return {"messages": [SystemMessage(content=load_system_prompt())]}
 
     def _call_model(self, state: AgentState) -> dict[str, list[AnyMessage]]:
-        """模型节点：在请求边界脱敏，并将新消息交回图状态。"""
-        safe_messages = self.privacy.before_model(state["messages"])
-        response = self.model.invoke(safe_messages)
+        """模型节点：对齐消息顺序、在请求边界脱敏，再调用模型。
+
+        两处必要处理：
+
+        1. ``system_prompt`` 节点是在用户消息之后写入状态的，直接发送会让系统提示词
+           排在用户消息后面；部分 OpenAI 兼容服务会拒绝或忽略这种情况，因此这里把
+           系统提示词提到最前。
+        2. 系统提示词来自用户本地编辑的 ``Agent.md``，属于可信输入，且脱敏规则会破坏
+           其中的命令示例（如 ``KEY=value``），所以不经过脱敏，只有对话消息需要脱敏。
+        """
+        messages = state["messages"]
+        system = [message for message in messages if isinstance(message, SystemMessage)]
+        conversation = [message for message in messages if not isinstance(message, SystemMessage)]
+        safe_messages = self.privacy.before_model(conversation)
+        response = self.model.invoke([*system, *safe_messages])
         return {"messages": [response]}
 
     def _wrap_tool_call(self, request, execute):
@@ -138,5 +150,5 @@ class LangGraphAgent:
         last_message = result["messages"][-1]
         content = last_message.content
         if isinstance(content, str):
-            return content or "(No response content.)"
+            return content or "（模型没有返回内容。）"
         return "\n".join(str(block.get("text", block)) for block in content)

shellmate_ai-0.1.2/src/shellmate/cli.py

@@ -0,0 +1,229 @@
+"""Shellmate 命令行入口，负责解析参数并调用相应模块。"""
+
+from __future__ import annotations
+
+import argparse
+import itertools
+import os
+import sys
+import threading
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+from shellmate import __version__
+from shellmate.agent import AgentError, LangGraphAgent
+from shellmate.config import (
+    AGENT_PROMPT_PATH,
+    CONFIG_PATH,
+    DATA_DIR,
+    ZSH_PLUGIN_PATH,
+    ensure_data_dir,
+    ensure_zsh_plugin,
+    load_config,
+)
+from shellmate.context import ShellContext, read_context, read_zsh_history
+
+# 管道模式输入的最大保留字符数；报错信息通常在输出末尾，故保留尾部。
+_MAX_OUTPUT_CHARS = 20000
+
+
+def _history_text(config, args) -> str:
+    """历史来源优先级：zsh 插件经 --history 传入 > 环境变量 > 历史文件兜底。"""
+    return (
+        getattr(args, "history", "")
+        or os.environ.get("SHELLMATE_HISTORY_TEXT", "")
+        or read_zsh_history(config.shell.history_lines)
+    )
+
+
+def _thread_id(config, args) -> str:
+    """会话 ID 来源优先级：--thread-id > zsh 会话环境变量 > 配置兜底。"""
+    return (
+        getattr(args, "thread_id", None)
+        or os.environ.get("SHELLMATE_SESSION_ID")
+        or config.thread_id
+    )
+
+
+_SPINNER_CHARS = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+
+class _Spinner:
+    """在 stderr 上显示单行动态加载态，退出时清除该行。
+
+    用 ``\\r`` 回到行首再覆盖，不用多行光标移动，避免在 zsh/zle 等环境
+    出现重复或残留。
+    """
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def _run(self) -> None:
+        for char in itertools.cycle(_SPINNER_CHARS):
+            if self._stop.is_set():
+                break
+            sys.stderr.write(f"\r{char} {self._message}")
+            sys.stderr.flush()
+            self._stop.wait(0.08)
+
+    def __enter__(self) -> "_Spinner":
+        self._thread.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self._stop.set()
+        self._thread.join(timeout=1)
+        sys.stderr.write("\r\x1b[K")
+        sys.stderr.flush()
+
+
+def _ask(config, question: str, context: ShellContext, args) -> None:
+    """运行 agent 并打印回答，统一异常处理。
+
+    生成期间在 stderr 显示动态加载态；TTY 下用 rich 一次性渲染 Markdown，
+    非 TTY（管道/重定向）则输出纯 Markdown 文本。
+    """
+    try:
+        agent = LangGraphAgent(config)
+        to_tty = sys.stdout.isatty()
+        if sys.stderr.isatty():
+            with _Spinner(f"正在请求 {config.llm.model} …"):
+                result = agent.ask(question, context, _thread_id(config, args))
+        else:
+            result = agent.ask(question, context, _thread_id(config, args))
+        if to_tty:
+            Console().print(Markdown(result))
+        else:
+            print(result)
+    except (AgentError, ValueError, OSError) as exc:
+        print(f"shellmate-ai: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+def main() -> None:
+    """处理初始化、提问、解释上一条命令与配置查看等子命令。"""
+    parser = argparse.ArgumentParser(prog="shellmate-ai", description="结合当前 shell 会话向 AI 提问")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+    ask_parser = sub.add_parser("ask", help="结合近期命令历史提问")
+    ask_parser.add_argument("question", nargs="*", help="要问的问题；多个词会用空格连接")
+    ask_parser.add_argument("--history", default="", help="近期命令历史，由 zsh 插件传入")
+    ask_parser.add_argument("--thread-id", help="LangGraph 会话 ID，通常由 zsh 传入")
+    explain_parser = sub.add_parser(
+        "explain",
+        help="解释从标准输入读到的命令输出（如 cmd 2>&1 | shellmate-ai explain）",
+    )
+    explain_parser.add_argument("question", nargs="*", help="可选问题；默认总结这段输出")
+    explain_parser.add_argument("--history", default="", help="近期命令历史，由 zsh 插件传入")
+    explain_parser.add_argument("--thread-id", help="LangGraph 会话 ID，通常由 zsh 传入")
+    last_parser = sub.add_parser(
+        "explain-last",
+        help="解释指定的上一条命令及其退出码（需 --last-command/--last-exit，供脚本手动调用）",
+    )
+    last_parser.add_argument("--history", default="", help="近期命令历史，由 zsh 插件传入")
+    last_parser.add_argument("--thread-id", help="LangGraph 会话 ID，通常由 zsh 传入")
+    last_parser.add_argument("--last-command", default="", help="上一条命令，由 zsh 插件传入")
+    last_parser.add_argument("--last-exit", default="", help="上一条命令的退出码，由 zsh 插件传入")
+    sub.add_parser("init", help="创建本地配置、Agent 提示词、数据目录和 zsh 插件")
+    sub.add_parser("config-path", help="打印配置文件路径")
+    sub.add_parser("history-lines", help="打印配置的历史条数")
+    args = parser.parse_args()
+    try:
+        config = load_config()
+    except (ValueError, OSError) as exc:
+        print(f"shellmate-ai: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+    if args.command == "init":
+        ensure_data_dir()
+        zshrc_updated = ensure_zsh_plugin()
+        print(f"已创建或确认配置文件：{CONFIG_PATH}")
+        print(f"已创建或确认 Agent 提示词：{AGENT_PROMPT_PATH}")
+        print(f"已创建或确认数据目录：{DATA_DIR}")
+        print(f"已创建或确认 zsh 插件：{ZSH_PLUGIN_PATH}")
+        if zshrc_updated:
+            print("已在 ~/.zshrc 添加插件加载行，请执行 `source ~/.zshrc` 使其生效。")
+        else:
+            print("~/.zshrc 已包含插件加载行，无需修改。")
+        return
+    if args.command == "config-path":
+        print(CONFIG_PATH)
+        return
+    if args.command == "history-lines":
+        print(config.shell.history_lines)
+        return
+
+    if args.command == "explain-last":
+        # 优先使用插件通过参数传入的值；环境变量仅作为旧版插件的兜底，
+        # 因为导出的环境变量会被之后启动的所有子进程继承。
+        last_command = (args.last_command or os.environ.get("SHELLMATE_LAST_COMMAND", "")).strip()
+        if not last_command:
+            print("shellmate-ai: 没有可解释的上一条命令。", file=sys.stderr)
+            raise SystemExit(1)
+        raw_exit = (args.last_exit or os.environ.get("SHELLMATE_LAST_EXIT", "")).strip()
+        try:
+            exit_code = int(raw_exit)
+        except ValueError:
+            exit_code = None
+        history = _history_text(config, args)
+        context = ShellContext(history=history, last_command=last_command, last_exit_code=exit_code)
+        # zsh 没有 postexec 钩子，命令输出在 precmd 执行时已经消失，插件无法事后捕获，
+        # 这里能给的只有命令本身、退出码和历史。必须明确告诉模型"没有输出"，否则它会
+        # 顺着"解释失败原因"的提问编造一段看起来合理的报错。
+        if exit_code == 0:
+            question = (
+                "解释一下刚才这条命令：它做了什么、有什么副作用或值得注意的地方。"
+                "注意：没有捕获到它的输出，不要假定或编造输出内容；如需确认，请给出"
+                "获取输出的命令（例如 `cmd 2>&1 | shellmate-ai explain`）。"
+            )
+        else:
+            question = (
+                "刚才这条命令失败了，但没有捕获到它的输出，目前只有命令本身和退出码。"
+                "请结合退出码说明最可能的原因、还需要哪些输出才能确认，并给出获取该输出的"
+                "具体命令（例如 `cmd 2>&1 | shellmate-ai explain`）。不要编造具体的报错内容。"
+            )
+        _ask(config, question, context, args)
+        return
+
+    if args.command == "explain":
+        if sys.stdin.isatty():
+            print(
+                "shellmate-ai: explain 需要管道输入，例如：command 2>&1 | shellmate-ai explain",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+        output = sys.stdin.read()
+        if not output.strip():
+            print("shellmate-ai: 标准输入为空。", file=sys.stderr)
+            raise SystemExit(1)
+        output = output[-_MAX_OUTPUT_CHARS:]
+        question = " ".join(args.question).strip() or "解释这段命令输出：发生了什么、是否报错、以及该如何处理。"
+        history = _history_text(config, args)
+        context = ShellContext(history=history, output=output)
+        _ask(config, question, context, args)
+        return
+
+    if args.command != "ask":
+        parser.print_help()
+        return
+
+    if args.question:
+        question = " ".join(args.question).strip()
+    else:
+        try:
+            question = input("向 Shellmate 提问: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nshellmate-ai: 未输入问题。", file=sys.stderr)
+            raise SystemExit(1)
+    if not question:
+        print("shellmate-ai: 未输入问题。", file=sys.stderr)
+        raise SystemExit(1)
+    context = read_context(_history_text(config, args))
+    _ask(config, question, context, args)
+
+
+if __name__ == "__main__":
+    main()