Pythoughts-labs/pythinker-code
GitHub: Pythoughts-labs/pythinker-code
Pythinker-code：终端AI工程代理，助力代码审查与安全。
Stars: 1 | Forks: 0
### 💬 尝试一下
```
# 交互式会话
pythinker
# 一次性提示
pythinker --prompt "summarize this repository and suggest the next test to add"
# 选择特定模型
pythinker --model openai/gpt-5.5
# 内联配置覆盖
pythinker --config '{"default_thinking": true}'
```
## 🏠 使用本地模型（LM Studio & Ollama）
在您的机器上完全运行 Pythinker — 无需 API 密钥，无需云服务。Pythinker 与每个运行时的 OpenAI 兼容 API 通信，因此工具、流、JSON 模式、视觉和 `reasoning_effort` 都与托管提供商相同。
### LM Studio
**1. 设置 LM Studio。**
- 安装 [LM Studio](https://lmstudio.ai/) 并下载至少一个聊天模型。
- 在 LM Studio 应用中，打开模型并 **增加其上下文长度**（齿轮图标 → 上下文长度）。参见下文的 [上下文长度很重要](#context-length-matters)。
- 启动服务器：**开发者 → 状态：运行**（或 `lms server start --port 1234`）。
**2. 连接 Pythinker。**
```
pythinker login --lm-studio
```
这将自动发现 LM Studio 中加载的每个具有聊天功能的模型，将其注册为 `lm-studio/`，并选择上下文最大的一个作为默认值。嵌入模型将被过滤掉。
**3. 使用它。**
```
# 默认 LM Studio 模型
pythinker -p "explain quicksort"
# 特定模型
pythinker -m lm-studio/qwen/qwen3-coder-next -p "write a python http server"
# 交互式外壳，然后使用 /model 切换模型
pythinker
```
**4. 断开连接。**
```
pythinker logout --lm-studio
```
### Ollama
```
# 1. 在一个终端中启动服务器
ollama serve
# 2. 拉取模型
ollama pull llama3.1:8b
# 3. 连接 Pythinker
pythinker login --ollama
# 4. 使用它
pythinker -p "explain monad transformers"
pythinker -m ollama/llama3.1:8b -p "..."
pythinker logout --ollama
```
发现使用 Ollama 的 `/api/tags` 获取模型列表，并使用 `/api/show` 读取每个模型的实际上下文窗口。
### 远程 LM Studio / Ollama（局域网主机或备用端口）
```
pythinker login --lm-studio --base-url http://192.168.1.10:1234/v1
pythinker login --ollama --base-url http://lan-box:11434/v1
```
覆盖设置在您的配置中，并由后续每次运行使用。
### 在交互式 shell 中
与斜杠命令具有相同的连接：
```
/login lm-studio # or /login lmstudio (no dash also accepted)
/login ollama
/logout lm-studio
/logout ollama
/login # opens a chooser; entries 9 and 10 are the local providers
/model lm-studio/google/gemma-4-e4b # switch model mid-session
```
### ⚠️ 上下文长度很重要（一个常见的陷阱）
Pythinker 的代理提示 — 系统指令 + 工具模式 + 技能 + 您的消息 + 最近的历史记录 — 很大。**在您发送第一条消息之前，就有数万个令牌。**
LM Studio 加载的模型默认上下文窗口很小（通常是 `4096`）。如果您针对该窗口开始聊天，您将看到：
```
LLM provider error: Error: The number of tokens to keep from the initial
prompt is greater than the context length (n_keep: 16690 >= n_ctx: 4096).
```
当发生这种情况时，shell 现在会打印一个友好的恢复提示，但**解决方案在 LM Studio 中**：
1. 在 LM Studio 中，在 **聊天** 选项卡中打开模型，并单击 **齿轮/设置** 图标（或 **我的模型 → 编辑**）。
2. 将 **上下文长度** 设置为至少 **`32768`**，如果您的 VRAM 允许，则首选 **`131072`**。*实践经验：64k 仍然会在较长的会话中触发错误；128k 是更安全的底线。*
3. 重新加载模型（LM Studio 会提示您）。
4. 重新启动 Pythinker 以获取新状态（`Ctrl+D` 然后 `pythinker`，或 `pythinker -r ` 以继续）。
**提示**：您设置的上下文越大，模型使用的 VRAM 就越多。如果您遇到 OOM，请尝试较小的量化（例如，Q4_K_M 而不是 Q8_0）或较小的模型变体。
Ollama 为每个请求配置上下文，Pythinker 从 `/api/show` 读取模型的最大值，因此这个陷阱主要与 LM-Studio 有关。
### VRAM 友好的模型选择
本地模型在内存使用方面差异很大。以下是在 16 GB GPU（例如，RTX 5080 移动）上的粗略指南：
| 模型大小 | 量化 | 大约 VRAM | 是否适合 16 GB？ |
|------------|-------|--------------|-------------|
| 2-4 B | Q4-Q8 | 2-4 GB | 是，很容易 |
| 7-8 B | Q4 | 5-6 GB | 是 |
| 7-8 B | Q8 | 8-9 GB | 是 |
| 13-14 B | Q4 | 8-10 GB | 是 |
| 27-31 B | Q4 | 17-20 GB | 紧凑/否 |
| 27-31 B | Q8 | 30-35 GB | 否 |
如果 LM Studio 出现 `Failed to load model` 错误，您已超出 VRAM — 选择较小的模型或较低的量化。
### 环境变量
这些在登录和运行时都覆盖了默认值：
| 变量 | 目的 |
|----------|---------|
| `LM_STUDIO_BASE_URL` | 覆盖 `http://localhost:1234/v1` |
| `LM_STUDIO_API_KEY` | 如果您已在 LM Studio 中启用了令牌身份验证，则设置 |
| `OLLAMA_BASE_URL` | 覆盖 `http://localhost:11434/v1` |
| `OLLAMA_API_KEY` | 很少需要（Ollama 默认不进行身份验证） |
示例：
```
LM_STUDIO_BASE_URL=http://workstation.lan:1234/v1 pythinker -p "..."
```
### 刷新模型列表
如果您在 LM Studio 中加载/卸载模型（或 `ollama pull/rm`），请重新运行登录以刷新：
```
pythinker login --lm-studio # or --ollama
```
（Pythinker 故意不会在后台自动刷新本地提供者 — 登录拥有该状态，因此手动编辑您的配置不会被静默覆盖。）
## 🧩 通过 ACP 集成 IDE
Pythinker 本地支持 [**代理客户端协议**](https://github.com/agentclientprotocol/agent-client-protocol)。将您的 ACP 兼容编辑器指向 `pythinker acp`，您将在 IDE 中获得多会话代理服务器。
ACP 服务器提供：
| 功能 | 描述 |
|---|---|
| 🔑 **终端身份验证** | `pythinker login` 流暴露给 IDE |
| 📂 **会话列表和恢复** | 拾起您上次离开的地方 |
| 🔄 **热模型交换** | 更改正在运行的 ACP 会话中的模型 |
## 🔌 MCP 工具
Pythinker 从持久配置或临时文件加载 [Model Context Protocol](https://modelcontextprotocol.io/) 工具。相同的工具，每个代理 — 无需重写。
### 🛠️ 管理持久 MCP 服务器
```
# 📚 Context7 stdio 服务器（Codex 风格：NAME -- COMMAND）
pythinker mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR-API-KEY
# 已将 MCP 服务器 'context7' 添加到 ~/.pythinker/mcp.json
# 🌐 可流式 HTTP 服务器带有 API 密钥
pythinker mcp add --transport http docs https://example.com/mcp \
--header "API_KEY: your-key"
# 🔐 可流式 HTTP 服务器带有 OAuth
pythinker mcp add --transport http --auth oauth linear https://mcp.linear.app/mcp
# 💻 带有显式传输的 stdio 服务器
pythinker mcp add --transport stdio chrome-devtools -- npx chrome-devtools-mcp@latest
# 📋 列出、授权、测试和删除
pythinker mcp list
pythinker mcp auth linear
pythinker mcp test chrome-devtools
pythinker mcp remove chrome-devtools
```
### 📄 使用临时 MCP 配置文件
```
{
"mcpServers": {
"context7": {
"url": "https://mcp.context7.com/mcp",
"headers": {
"CONTEXT7_API_KEY": "YOUR_API_KEY"
}
},
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}
```
```
pythinker --mcp-config-file /path/to/mcp.json
```
## 🧬 可扩展性
Pythinker 是一个小型、可扩展的运行时 — 不是一个单体。在此基础上构建。
| 扩展点 | 执行的操作 | 查看位置 |
|---|---|---|
| 🤖 **代理和子代理** | YAML 规范定义工具、提示和内置子代理类型 | `src/pythinker_code/agents/` |
| 🎓 **技能** | `/skill:` 在需要时加载可重用指令 | 打包和用户定义 |
| 🌊 **流程** | `/flow:` 执行打包的提示流程 | 打包和用户定义 |
| 🪝 **钩子** | 观察或阻止工具执行；集成策略或自动化 | 钩子事件 API |
| 🧩 **插件** | 可安装的扩展包 | `pythinker plugin` |
## 🏗️ 架构
## 🔐 隐私与遥测
Pythinker 是 **代理框架**，而不是 LLM。您带来自己的 API 密钥
（OpenAI、Anthropic、您本地的 LM Studio 模型等）；您的提示和模型的响应直接在您的终端和您配置的模型提供者之间传递。Pythinker 从不查看、存储或转发它们。
如果您选择加入，Pythinker 可以收集有关代理如何运行的少量 **诊断遥测** 以改进框架本身。它是严格匿名的，从不包括您的提示、模型输出、文件内容、文件路径或任何用户识别数据。两个通道：
| 通道 | 什么到达那里 | 端点 |
|---|---|---|
| **错误**（Sentry 协议）| 未处理的异常和崩溃堆栈跟踪，其中 `site-packages/` 之上的绝对路径重写为 `/` 以防止家目录泄露 | `errors.pythinker.com`（自托管 Bugsink）|
| **跟踪 + 结构化日志**（OpenTelemetry）| 生命周期事件（`session_started`、`started`、`model_switch`）、代理循环跨度（`pythinker.turn` / `pythinker.llm` / `pythinker.tool`）、每个事件的计数器 | `otel.pythinker.com`（自托管 SigNoz）|
### 我们收集的内容
- **生命周期事件**：会话开始、实际使用的命令行标志（仅布尔值）、启动时间、模型名称（仅标识符，例如 `claude-opus-4-7`）、思考模式切换、计划模式切换。
- **代理循环跨度**：转换持续时间、步骤计数、停止原因（`no_tool_calls` / `max_steps` / `error`）、工具名称（`Read`、`Bash`、`Edit`、…）、工具成功/失败、工具持续时间、LLM 调用持续时间、输入/输出令牌 *计数*（数字 — 永远不是内容）。
- **崩溃**：异常类名称、清洗后的堆栈跟踪、库版本。我们**不**发送本地变量值。
- **静态上下文**：pythinker 版本、操作系统家族、Python 版本、终端类型（`TERM_PROGRAM`）、CI 标志（`CI` 环境变量存在）、区域设置。
- **持久的、随机的 `device_id`** 以便我们可以计数“有多少个不同的安装”而不会识别个人。
### 我们永远不会收集的内容
- 您的提示、模型的响应或任何对话内容
- 文件内容、文件路径、工作目录名称或工作区结构
- 您的 API 密钥、OAuth 令牌、环境变量
- 您的真实姓名、电子邮件、IP 地址、主机名（主机名字段在边缘收集器处被删除）
- 工具参数（例如您读取的文件、您运行的命令）
### 关闭遥测
遥测默认开启。要关闭遥测：
```
# 1. 每次调用的 CLI 标志
pythinker --no-telemetry
# 2. 环境变量（在 shell、.env 文件、CI 配置中工作）
export PYTHINKER_DISABLE_TELEMETRY=1
pythinker
# 3. 永久保存在您的配置文件中 (~/.pythinker/config.toml)
[default]
telemetry = false
```
当遥测关闭时，Pythinker 短路 Sentry 初始化、OTel 导出器创建和进程内事件接收器。不会发出网络请求到遥测端点。
### 将遥测指向您自己的基础设施
如果您为团队运营 pythinker 并希望遥测路由到您自己的
SigNoz / Bugsink，请通过环境变量覆盖端点：
```
export PYTHINKER_SENTRY_DSN="https://@your-bugsink.example.com/"
export PYTHINKER_OTEL_ENDPOINT="https://your-otel-collector.example.com"
export PYTHINKER_OTEL_TOKEN=""
```
默认值指向由 pythinker 维护者运营的基础设施，并在您关闭遥测时自动使用。
## 🛠️ 开发
### 🏁 准备工作区
```
git clone https://github.com/Pythoughts-labs/pythinker-code.git
cd pythinker-code
make prepare
```
### 🧰 常用命令
## 🗂️ 项目布局
```
pythinker-code/
├── 📦 src/pythinker_code/ CLI runtime · tools · UIs · ACP · MCP · hooks · plugins · skills · web · vis backends
├── 🧱 packages/
│ ├── pythinker-core/ Provider-agnostic message, tool, and chat-provider abstractions
│ ├── pythinker-host/ Local/remote host filesystem and command execution
│ └── pythinker-code/ Console-script distribution package
├── 🧰 sdks/pythinker-sdk/ Python SDK
└── 🧪 tests/ · tests_e2e/ · tests_ai/ Unit · wire/CLI e2e · AI-driven test suites
```
## 🤝 贡献
贡献受到热烈欢迎 — 错误报告、PR、插件、技能和文档都有帮助。
- 📖 从 `CONTRIBUTING.md` 开始
- 🔐 查看 `SECURITY.md` 以获取负责任的披露
- 📜 查看文档 `AGENTS.md` 以获取代理设计说明
如果 Pythinker 对您有帮助，**在 GitHub 上给一个 ⭐ 是很长的路。**
## 📜 许可证
根据 **Apache-2.0 许可证** 分发。有关完整文本和归属，请参阅 [`LICENSE`](https://github.com/Pythoughts-labs/pythinker-code/blob/main/LICENSE) 和 [`NOTICE`](https://github.com/Pythoughts-labs/pythinker-code/blob/main/NOTICE)。
📝 Zed / JetBrains 的配置
``` { "agent_servers": { "Pythinker Code": { "type": "custom", "command": "pythinker", "args": ["acp"], "env": {} } } } ```
| **▶️ 运行 & 迭代** ``` uv run pythinker # CLI from source make format # format all packages make check # lint + type-check ``` | **🧪 测试** ``` make test # all unit + e2e tests make ai-test # AI-driven tests make test-pythinker-code # CLI only make test-pythinker-core # Core only make test-pythinker-host # Host only make test-pythinker-sdk # SDK only ``` |
| **🌐 前端** ``` make web-back # web backend make web-front # web frontend make vis-back # vis backend make vis-front # vis frontend ``` | **📦 构建** ``` make build # Python packages make build-bin # standalone binary make help # all targets ``` |
**用 ❤️ 为生活在终端的工程师构建。**
[🌐 pythinker.com](https://pythinker.com) ·
[📦 PyPI](https://pypi.org/project/pythinker-code/) ·
[🐙 GitHub](https://github.com/Pythoughts-labs/pythinker-code) ·
[🧩 ACP](https://github.com/agentclientprotocol/agent-client-protocol) ·
[🔌 MCP](https://modelcontextprotocol.io/)
感谢您访问 ✨ Pythinker！查看此 README 不会触发遥测。
标签：AI风险缓解, Petitpotam, SSH爆破, 逆向工具