pawnlogic 1.1__tar.gz

pawnlogic-1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PawnLogic Contributors
+
+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.

pawnlogic-1.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: pawnlogic
+Version: 1.1
+Summary: A fully autonomous terminal AI agent — multi-model routing, persistent memory, real tool execution
+Author-email: john0123412 <junjohn05@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/john0123412/PawnLogic
+Project-URL: Repository, https://github.com/john0123412/PawnLogic
+Project-URL: Issues, https://github.com/john0123412/PawnLogic/issues
+Project-URL: Changelog, https://github.com/john0123412/PawnLogic/blob/main/CHANGELOG.md
+Keywords: ai-agent,llm,ctf,cli,autonomous,multi-model,security,pwn
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: prompt_toolkit>=3.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: anthropic>=0.40
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# 🤖 PawnLogic
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.1-blue.svg)](config/paths.py)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20WSL2-lightgrey.svg)]()
+
+> **A fully autonomous terminal AI agent** — multi-model routing, persistent memory, real tool execution, and session management. Built for developers and security researchers.
+
+## ⚡ Quick Start
+
+```bash
+git clone https://github.com/john0123412/PawnLogic.git && cd PawnLogic
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+python main.py   # first run launches the API configuration wizard
+```
+
+Global `pawn` command:
+```bash
+chmod +x pawn.sh && ln -sf "$(pwd)/pawn.sh" ~/.local/bin/pawn
+```
+
+## Key Capabilities
+
+| Capability | Description |
+|-----------|-------------|
+| 🔀 **Dynamic Provider System** | Built-in DeepSeek / OpenAI / Anthropic + add any OpenAI-compatible API via `/provider` |
+| 🧠 **Persistent Memory** | SQLite session history, RAG knowledge base, cross-session full-text search |
+| 🛠️ **Real Tool Execution** | Shell, code sandbox (8 languages), web fetch, file ops, Docker containers |
+| 👁️ **Vision** | Feed screenshots to `gpt-4o` or `claude-sonnet` for analysis |
+| 📋 **Spec-Driven Planning** | Agent outputs `<plan>` XML before every action — no blind execution |
+| 💬 **Session Management** | Tag, search, link, and export conversations with `/chat` commands |
+| 🔐 **CTF / Pwn Toolchain** | GDB automation, ROP chain building, libc leak resolution, Docker isolation |
+
+## Supported Models
+
+| Provider | Aliases | Best For |
+|----------|---------|----------|
+| DeepSeek | `ds-v4-flash` `ds-v4-pro` | Fast default, flagship reasoning |
+| OpenAI | `gpt-4o` `gpt-4.1` `o3` | Vision, code, complex reasoning |
+| Anthropic | `claude-sonnet` `claude-haiku` | Balanced, fast low-cost |
+
+Custom providers added via `/provider fetch` appear automatically in `/model` and Tab completion.
+
+## Provider Management
+
+```bash
+/provider              # open interactive TUI panel
+/provider add <name> <base_url> <ENV_KEY> [anthropic]
+/provider fetch <name> # auto-discover models with interactive multi-select
+/provider list         # show all providers and key status
+/provider test <model> # test connectivity
+```
+
+All keys are stored in `~/.pawnlogic/.env`. Provider configs (no keys) go to `~/.pawnlogic/custom_providers.json`.
+
+## Quick Command Reference
+
+```bash
+/model [alias]          # switch model
+/mode                   # toggle USER / DEV output mode
+/chat find <keyword>    # full-text search across all sessions
+/think <prompt>         # single deep-reasoning turn
+/compact                # summarize + clear context
+/undo [n]               # roll back last n turns
+/deep                   # switch to deep mode (32k tokens, 50 iter)
+/init_project           # initialize GSD engineering pipeline
+/pwnenv                 # check CTF toolchain integrity
+/keys                   # show API key status for all providers
+```
+
+## MCP Tool Integration
+
+```bash
+cp mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
+# edit mcp_configs.json, add TAVILY_API_KEY= etc. to ~/.pawnlogic/.env
+python main.py   # MCP servers load automatically
+```
+
+Supported MCP servers: **Tavily** (search), **Playwright** (browser automation), **Filesystem** (file bridge).
+
+## Data Layout
+
+All runtime data and API keys are stored in `~/.pawnlogic/` — **never in the project directory**.
+
+```
+~/.pawnlogic/
+├── .env                    # ALL API keys (LLM providers + MCP tools)
+├── custom_providers.json   # user-added provider configs (no keys)
+├── mcp_configs.json        # MCP server declarations
+├── pawn.db                 # sessions, messages, knowledge base
+├── global_skills.md        # GSA skill archive
+├── workspace/              # per-session working directories
+└── logs/                   # audit logs
+```
+
+The project directory contains no secrets and is safe to commit or share.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| **README.md** | This page |
+| **README_CN.md** | 中文版 |
+| **GUIDE_EN.md** | Full reference — commands, architecture, FAQ |
+| **GUIDE_CN.md** | 完整参考手册 — 命令、架构、常见问题 |
+| **CHANGELOG.md** | Version history and release notes |
+| **CONTRIBUTING.md** | How to contribute, add providers, run tests |
+| **SECURITY.md** | Vulnerability reporting policy |
+
+## Support
+
+- **GitHub**: [github.com/john0123412/PawnLogic](https://github.com/john0123412/PawnLogic)
+- **Issues**: GitHub Issues for bugs and feature requests

pawnlogic-1.1/README.md

@@ -0,0 +1,115 @@
+# 🤖 PawnLogic
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.1-blue.svg)](config/paths.py)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20WSL2-lightgrey.svg)]()
+
+> **A fully autonomous terminal AI agent** — multi-model routing, persistent memory, real tool execution, and session management. Built for developers and security researchers.
+
+## ⚡ Quick Start
+
+```bash
+git clone https://github.com/john0123412/PawnLogic.git && cd PawnLogic
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+python main.py   # first run launches the API configuration wizard
+```
+
+Global `pawn` command:
+```bash
+chmod +x pawn.sh && ln -sf "$(pwd)/pawn.sh" ~/.local/bin/pawn
+```
+
+## Key Capabilities
+
+| Capability | Description |
+|-----------|-------------|
+| 🔀 **Dynamic Provider System** | Built-in DeepSeek / OpenAI / Anthropic + add any OpenAI-compatible API via `/provider` |
+| 🧠 **Persistent Memory** | SQLite session history, RAG knowledge base, cross-session full-text search |
+| 🛠️ **Real Tool Execution** | Shell, code sandbox (8 languages), web fetch, file ops, Docker containers |
+| 👁️ **Vision** | Feed screenshots to `gpt-4o` or `claude-sonnet` for analysis |
+| 📋 **Spec-Driven Planning** | Agent outputs `<plan>` XML before every action — no blind execution |
+| 💬 **Session Management** | Tag, search, link, and export conversations with `/chat` commands |
+| 🔐 **CTF / Pwn Toolchain** | GDB automation, ROP chain building, libc leak resolution, Docker isolation |
+
+## Supported Models
+
+| Provider | Aliases | Best For |
+|----------|---------|----------|
+| DeepSeek | `ds-v4-flash` `ds-v4-pro` | Fast default, flagship reasoning |
+| OpenAI | `gpt-4o` `gpt-4.1` `o3` | Vision, code, complex reasoning |
+| Anthropic | `claude-sonnet` `claude-haiku` | Balanced, fast low-cost |
+
+Custom providers added via `/provider fetch` appear automatically in `/model` and Tab completion.
+
+## Provider Management
+
+```bash
+/provider              # open interactive TUI panel
+/provider add <name> <base_url> <ENV_KEY> [anthropic]
+/provider fetch <name> # auto-discover models with interactive multi-select
+/provider list         # show all providers and key status
+/provider test <model> # test connectivity
+```
+
+All keys are stored in `~/.pawnlogic/.env`. Provider configs (no keys) go to `~/.pawnlogic/custom_providers.json`.
+
+## Quick Command Reference
+
+```bash
+/model [alias]          # switch model
+/mode                   # toggle USER / DEV output mode
+/chat find <keyword>    # full-text search across all sessions
+/think <prompt>         # single deep-reasoning turn
+/compact                # summarize + clear context
+/undo [n]               # roll back last n turns
+/deep                   # switch to deep mode (32k tokens, 50 iter)
+/init_project           # initialize GSD engineering pipeline
+/pwnenv                 # check CTF toolchain integrity
+/keys                   # show API key status for all providers
+```
+
+## MCP Tool Integration
+
+```bash
+cp mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
+# edit mcp_configs.json, add TAVILY_API_KEY= etc. to ~/.pawnlogic/.env
+python main.py   # MCP servers load automatically
+```
+
+Supported MCP servers: **Tavily** (search), **Playwright** (browser automation), **Filesystem** (file bridge).
+
+## Data Layout
+
+All runtime data and API keys are stored in `~/.pawnlogic/` — **never in the project directory**.
+
+```
+~/.pawnlogic/
+├── .env                    # ALL API keys (LLM providers + MCP tools)
+├── custom_providers.json   # user-added provider configs (no keys)
+├── mcp_configs.json        # MCP server declarations
+├── pawn.db                 # sessions, messages, knowledge base
+├── global_skills.md        # GSA skill archive
+├── workspace/              # per-session working directories
+└── logs/                   # audit logs
+```
+
+The project directory contains no secrets and is safe to commit or share.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| **README.md** | This page |
+| **README_CN.md** | 中文版 |
+| **GUIDE_EN.md** | Full reference — commands, architecture, FAQ |
+| **GUIDE_CN.md** | 完整参考手册 — 命令、架构、常见问题 |
+| **CHANGELOG.md** | Version history and release notes |
+| **CONTRIBUTING.md** | How to contribute, add providers, run tests |
+| **SECURITY.md** | Vulnerability reporting policy |
+
+## Support
+
+- **GitHub**: [github.com/john0123412/PawnLogic](https://github.com/john0123412/PawnLogic)
+- **Issues**: GitHub Issues for bugs and feature requests

pawnlogic-1.1/config/__init__.py

@@ -0,0 +1,47 @@
+"""
+config/__init__.py — 向后兼容入口
+
+外部代码 `from config import X` 或 `import config; config.X` 无需任何修改。
+"""
+from .providers import (
+    PROVIDERS, MODELS, DEFAULT_MODEL, VISION_PRIORITY,
+    NAMING_MODEL_CHAIN, CUSTOM_PROVIDERS_PATH,
+    get_api_config, get_api_format, get_provider_config,
+    validate_api_key, list_configured_models,
+    get_best_vision_model, list_vision_models,
+    load_custom_providers, save_custom_provider, remove_custom_provider,
+    is_fast_model, find_fast_peer,
+)
+from .tiers import TIER_LOW, TIER_MID, TIER_DEEP, TIER_MAX
+from .security import (
+    READ_BLACKLIST, WRITE_BLACKLIST, DANGEROUS_PATTERNS,
+    smart_truncate, user_friendly_error,
+)
+from .sandbox import SANDBOX_LANGS, DOCKER_IMAGES, BROWSER_CONFIG, USER_AGENTS
+from .phases import AGENT_PHASES
+from .paths import (
+    VERSION, SESSIONS_DIR, DB_PATH, GLOBAL_SKILLS_PATH,
+    SKILLS_DIR, LOG_DIR, WORKSPACE_DIR, WORKSPACE_ROOT,
+)
+
+# ── 向后兼容：DYNAMIC_CONFIG / NORMAL_CONFIG ──────────────
+# 这两个可变 dict 由 main.py 在运行时修改（/mid /deep /low 等命令）。
+# 保留在此处以兼容所有 `from config import DYNAMIC_CONFIG` 的调用。
+DYNAMIC_CONFIG: dict = dict(TIER_MID)
+NORMAL_CONFIG:  dict = dict(TIER_MID)
+
+# ── 向后兼容：WEB_STRATEGY ────────────────────────────────
+WEB_STRATEGY = {
+    "jina_base":     "https://r.jina.ai/",
+    "use_pandoc":    True,
+    "timeout":       20,
+    "max_html_read": 600_000,
+}
+
+# ── 向后兼容：USER_MODE / QUIET_MODE ─────────────────────
+# 这两个标志现在由 core.state 管理。
+# 保留模块级变量以兼容 `import config; config.QUIET_MODE = True` 的写法。
+# 注意：直接赋值此处的变量不会影响 core.state.state，
+# 推荐新代码使用 `from core.state import state`。
+USER_MODE: bool = False
+QUIET_MODE: bool = False

pawnlogic-1.1/config/paths.py

@@ -0,0 +1,17 @@
+"""config/paths.py — 路径与版本常量
+
+版本号唯一定义处。全局通过 `from config import VERSION` 读取。
+升级时只需修改此处。
+"""
+from pathlib import Path
+
+# ── 唯一版本号定义 ──────────────────────────────────────
+VERSION = "1.1"
+
+SESSIONS_DIR       = Path.home() / ".pawnlogic" / "sessions"
+DB_PATH            = Path.home() / ".pawnlogic" / "pawn.db"
+GLOBAL_SKILLS_PATH = Path.home() / ".pawnlogic" / "global_skills.md"
+SKILLS_DIR         = Path(__file__).resolve().parent.parent / "skills"
+LOG_DIR            = Path.home() / ".pawnlogic" / "logs"
+WORKSPACE_DIR      = str(Path.home() / ".pawnlogic" / "workspace")
+WORKSPACE_ROOT     = str(Path.home() / ".pawnlogic")

pawnlogic-1.1/config/phases.py

@@ -0,0 +1,40 @@
+"""config/phases.py — MoE 动态工具裁剪专家路由表"""
+
+AGENT_PHASES: dict[str, list[str]] = {
+    "RECON": [
+        "pwn_env", "list_dir", "find_files", "read_file", "inspect_binary",
+        "pwn_timed_debug",
+        "search_skills",
+        "check_service",
+    ],
+    "VULN_DEV": [
+        "pwn_cyclic", "pwn_disasm", "pwn_rop", "pwn_libc", "pwn_one_gadget", "run_shell",
+        "pwn_timed_debug",
+    ],
+    "EXPLOIT": [
+        "write_file", "patch_file", "run_code", "pwn_debug", "pwn_timed_debug",
+        "run_interactive", "run_shell",
+        "run_code_docker", "pwn_container",
+        "tool_install_package",
+        "docker_prune_resources",
+    ],
+    "GENERAL": [
+        "read_file", "write_file", "patch_file", "run_shell", "web_search", "fetch_url",
+        "pwn_timed_debug",
+        "run_code_docker", "pwn_container",
+        "tool_install_package",
+        "docker_prune_resources",
+        "bump_skill",
+        "search_skills",
+        "check_service",
+    ],
+    "WEB_PEN": [
+        "web_fetch", "web_click", "web_screenshot", "web_select", "web_type", "web_navigate",
+        "web_search", "fetch_url",
+        "read_file", "write_file",
+        "run_shell",
+        "bump_skill",
+        "search_skills",
+        "check_service",
+    ],
+}

pawnlogic-1.1/config/providers.py

@@ -0,0 +1,271 @@
+"""
+config/providers.py — API Provider 与模型注册表
+
+所有 API Key 通过环境变量注入，代码中无任何硬编码凭证。
+"""
+import os
+import json
+from pathlib import Path
+
+PROVIDERS: dict[str, dict] = {
+    "deepseek": {
+        "base_url":    "https://api.deepseek.com/v1/chat/completions",
+        "api_key_env": "DEEPSEEK_API_KEY",
+        "label":       "DeepSeek",
+        "api_format":  "openai",
+    },
+    "openai": {
+        "base_url":    "https://api.openai.com/v1/chat/completions",
+        "api_key_env": "OPENAI_API_KEY",
+        "label":       "OpenAI",
+        "api_format":  "openai",
+    },
+    "anthropic": {
+        "base_url":    "https://api.anthropic.com/v1/messages",
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "label":       "Anthropic (Claude)",
+        "api_format":  "anthropic",
+    },
+}
+
+MODELS: dict[str, dict] = {
+    "ds-v4-flash": {
+        "id":        "deepseek-v4-flash",
+        "provider":  "deepseek",
+        "desc":      "DeepSeek V4 Flash — 默认主力，快速低成本",
+        "color":     "\033[32m",
+        "vision":    False,
+        "reasoning": True,   # 返回 reasoning_content，必须回传
+    },
+    "ds-v4-pro": {
+        "id":        "deepseek-v4-pro",
+        "provider":  "deepseek",
+        "desc":      "DeepSeek V4 Pro — 旗舰推理",
+        "color":     "\033[92m",
+        "vision":    False,
+        "reasoning": True,
+    },
+    "gpt-4o": {
+        "id":        "gpt-4o",
+        "provider":  "openai",
+        "desc":      "OpenAI GPT-4o — 视觉+多模态",
+        "color":     "\033[97m",
+        "vision":    True,
+        "reasoning": False,
+    },
+    "gpt-4.1": {
+        "id":        "gpt-4.1",
+        "provider":  "openai",
+        "desc":      "OpenAI GPT-4.1 — 代码与指令跟随",
+        "color":     "\033[37m",
+        "vision":    False,
+        "reasoning": False,
+    },
+    "o3": {
+        "id":        "o3",
+        "provider":  "openai",
+        "desc":      "OpenAI o3 — 复杂推理",
+        "color":     "\033[96m",
+        "vision":    False,
+        "reasoning": False,  # OpenAI o系列推理内部化，不暴露 reasoning_content 字段
+    },
+    "claude-sonnet": {
+        "id":        "claude-sonnet-4-6",
+        "provider":  "anthropic",
+        "desc":      "Claude Sonnet 4.6 — 均衡主力",
+        "color":     "\033[95m",
+        "vision":    True,
+        "reasoning": False,  # Anthropic 格式走独立路径，不经过 sanitizer
+    },
+    "claude-haiku": {
+        "id":        "claude-haiku-4-5-20251001",
+        "provider":  "anthropic",
+        "desc":      "Claude Haiku 4.5 — 快速低成本",
+        "color":     "\033[35m",
+        "vision":    True,
+        "reasoning": False,
+    },
+}
+
+DEFAULT_MODEL = "ds-v4-flash"
+
+NAMING_MODEL_CHAIN: list = [
+    "claude-haiku",
+    "ds-v4-flash",
+    "gpt-4.1",
+]
+
+VISION_PRIORITY = ["gpt-4o", "claude-sonnet"]
+
+CUSTOM_PROVIDERS_PATH = Path.home() / ".pawnlogic" / "custom_providers.json"
+
+
+def _normalize_url(raw: str, api_format: str = "openai") -> str:
+    """Ensure base_url ends with the correct chat endpoint path."""
+    raw = raw.rstrip("/")
+    if raw.endswith("/chat/completions") or raw.endswith("/messages"):
+        return raw
+    suffix = "/messages" if api_format == "anthropic" else "/chat/completions"
+    if raw.endswith("/v1"):
+        return raw + suffix
+    return raw + "/v1" + suffix
+
+
+_FAST_KEYWORDS = {"flash", "haiku", "mini", "turbo", "lite"}
+
+
+def is_fast_model(model_alias: str) -> bool:
+    """Return True if the model id contains a fast-tier keyword."""
+    mid = MODELS.get(model_alias, {}).get("id", model_alias).lower()
+    return any(k in mid for k in _FAST_KEYWORDS)
+
+
+def find_fast_peer(model_alias: str) -> str | None:
+    """
+    Given a pro-tier model alias, return the alias of a fast-tier model
+    from the same provider that has a valid API key.
+    Returns None if no fast peer is found.
+    """
+    m = MODELS.get(model_alias)
+    if not m:
+        return None
+    provider = m.get("provider", "")
+    for alias, cfg in MODELS.items():
+        if cfg.get("provider") != provider:
+            continue
+        if not is_fast_model(alias):
+            continue
+        ok, _ = validate_api_key(alias)
+        if ok:
+            return alias
+    return None
+
+
+def get_api_config(model_alias: str) -> tuple[str, str]:
+    """返回 (base_url, api_key)。Key 从环境变量读取，永不硬编码。"""
+    m    = MODELS.get(model_alias, MODELS[DEFAULT_MODEL])
+    prov = PROVIDERS.get(m["provider"], list(PROVIDERS.values())[0])
+    key  = os.getenv(prov["api_key_env"], "")
+    fmt  = prov.get("api_format", "openai")
+    return _normalize_url(prov["base_url"], fmt), key
+
+
+def get_api_format(model_alias: str) -> str:
+    """返回 'openai' 或 'anthropic'。"""
+    m    = MODELS.get(model_alias, MODELS[DEFAULT_MODEL])
+    prov = PROVIDERS.get(m["provider"], {})
+    return prov.get("api_format", "openai")
+
+
+def get_provider_config(model_alias: str) -> dict:
+    """返回完整 provider 配置字典。"""
+    m    = MODELS.get(model_alias, MODELS[DEFAULT_MODEL])
+    prov = PROVIDERS.get(m["provider"], list(PROVIDERS.values())[0])
+    key  = os.getenv(prov["api_key_env"], "")
+    fmt  = prov.get("api_format", "openai")
+    return {
+        "base_url":   _normalize_url(prov["base_url"], fmt),
+        "api_key":    key,
+        "api_format": fmt,
+        "label":      prov.get("label", ""),
+    }
+
+
+def validate_api_key(model_alias: str) -> tuple[bool, str]:
+    """检查指定模型的 Key 是否已正确配置。返回 (ok, missing_env_var)。"""
+    _, key = get_api_config(model_alias)
+    if not key:
+        m    = MODELS.get(model_alias, MODELS[DEFAULT_MODEL])
+        prov = PROVIDERS.get(m["provider"], {})
+        return False, prov.get("api_key_env", "")
+    return True, ""
+
+
+def list_configured_models() -> list[str]:
+    """返回所有已配置 Key 的模型别名列表。"""
+    return [alias for alias in MODELS if validate_api_key(alias)[0]]
+
+
+def get_best_vision_model() -> tuple[str | None, str | None, str | None]:
+    """按优先级找到第一个已配置 Key 的视觉模型。"""
+    for alias in VISION_PRIORITY:
+        m = MODELS.get(alias)
+        if not m or not m.get("vision"):
+            continue
+        url, key = get_api_config(alias)
+        if key:
+            return alias, url, key
+    return None, None, None
+
+
+def list_vision_models() -> list[str]:
+    """返回所有标记了 vision=True 的模型别名。"""
+    return [alias for alias, m in MODELS.items() if m.get("vision")]
+
+
+def load_custom_providers() -> None:
+    """从 custom_providers.json 加载用户自定义 provider，合并进 PROVIDERS/MODELS。"""
+    # Reload .env so keys added after startup (e.g. via wizard) are available
+    try:
+        from dotenv import load_dotenv
+        _env = Path.home() / ".pawnlogic" / ".env"
+        if _env.exists():
+            load_dotenv(_env, override=True)
+    except ImportError:
+        pass
+    if not CUSTOM_PROVIDERS_PATH.exists():
+        return
+    try:
+        data = json.loads(CUSTOM_PROVIDERS_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        return
+    for name, prov in data.get("providers", {}).items():
+        if name not in PROVIDERS:
+            prov.setdefault("api_format", "openai")
+            PROVIDERS[name] = prov
+    for alias, model in data.get("models", {}).items():
+        if alias not in MODELS:
+            model.setdefault("color", "\033[37m")
+            model.setdefault("vision", False)
+            MODELS[alias] = model
+
+
+def save_custom_provider(name: str, prov_cfg: dict, models_cfg: dict) -> None:
+    """将自定义 provider 持久化到 custom_providers.json（不含 Key）。"""
+    CUSTOM_PROVIDERS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data: dict = {"providers": {}, "models": {}}
+    if CUSTOM_PROVIDERS_PATH.exists():
+        try:
+            data = json.loads(CUSTOM_PROVIDERS_PATH.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    data["providers"][name] = prov_cfg
+    data["models"].update(models_cfg)
+    CUSTOM_PROVIDERS_PATH.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+
+def remove_custom_provider(name: str) -> bool:
+    """从 JSON 文件删除自定义 provider。返回是否成功。"""
+    if not CUSTOM_PROVIDERS_PATH.exists():
+        return False
+    try:
+        data = json.loads(CUSTOM_PROVIDERS_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        return False
+    if name not in data.get("providers", {}):
+        return False
+    del data["providers"][name]
+    to_remove = [a for a, m in data.get("models", {}).items()
+                 if m.get("provider") == name]
+    for a in to_remove:
+        del data["models"][a]
+    CUSTOM_PROVIDERS_PATH.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    return True
+
+
+# 模块加载时自动读取自定义 provider
+load_custom_providers()