thatgfsj-code 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to **Thatgfsj Code** are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Planned
+- 实现真实的 provider 工具调用解析（OpenAI `delta.tool_calls`、Anthropic
+  `tool_use` block、Gemini `functionCall`），让已注册的 Tool 真正参与 Agent Loop
+- `install.sh` / `install.ps1` 默认分支自适应（`master` ↔ `main`）
+- 移除 README 中失效的 `git.io/thatgfsj` 短链，全部改回 `raw.githubusercontent.com`
+- MCP 客户端 `this.process?.connected` → `this.process?.stdin?.writable`
+
+---
+
+## [0.2.2] - 2026-07-06
+
+### Added
+- **`/model` / `/provider` REPL 命令**：1.0.4 老版本里这两个交互式切换命令
+  在 0.2.x 系列中曾经被删掉，这次重新实现并对齐新代码结构，并且从
+  `thatgfsj-code@1.0.4` 的 TUI 版本里借鉴并移植了两项核心体验：
+  - `/model` 列出当前 provider 的所有模型（含 `✓` 标记当前选中），输入编号
+    或完整 model id 切换；立即写入 `~/.thatgfsj/config.json` 并通过
+    `AIEngine.updateConfig()` 让下一次流式请求生效。空输入回车保持当前，
+    Ctrl+C 取消。
+  - **历史记录持久化**（借鉴 1.0.4 的 `saveModelToHistory`）：切换过的
+    model id 写入 `~/.thatgfsj/models.json`，下次打开 `/model` 时会在
+    内置列表上方显示「最近使用」段（最多 5 条，按时间排序，可通过 `r1`..`r5`
+    快捷选取，自动 dedup）。
+  - **任意 model id**：输入既不在内置列表也不在历史里的字符串，按自定义模型
+    处理（适合 OpenAI-compatible 中转站 / Ollama 自定义模型名场景）。
+  - `/provider` 列出 9 个支持的 provider，选完自动跟进 `/model` 让用户选
+    新 provider 下的模型；如果新 provider 缺少对应的 API Key 环境变量，会提示
+    用户先 `gfcode init` 或 `export`。
+  - 两个命令都接受带或不带前导 `/`（与 1.0.4 的 `/模型` 老习惯兼容）。
+  - 切换后会把一行 `[system: ... switched to ...]` 注入 `SessionManager`，
+    让 LLM 在下一轮看到变更而不丢失上下文。
+- **`AIEngine.updateConfig()` / `getConfig()`**：暴露给 REPL 内部用，支持
+  在不重启引擎的情况下替换 `model` / `provider` / `baseUrl` / `temperature` /
+  `maxTokens`。
+- **34 个单元 / 冒烟测试**（`tests/`）：npm 内置 `node:test`，覆盖：
+  - `smoke-cli.test.js` — `--version` / `--help` / 子命令空参守卫 / `bash -n`。
+  - `unit-session.test.js` — `SessionManager` 拦截「已中断」、相邻助手去重、
+    `truncate` 保留 system。
+  - `unit-diff.test.js` — `DiffPreview.compare` 边界（unicode / 大输入 / CRLF /
+    空输入）。
+  - `unit-switcher.test.js` — `/model` 的纯 helper（编号 / id 解析）
+    与 `AIEngine.updateConfig` 行为。
+  - **新增** `unit-model-history.test.js` — `~/.thatgfsj/models.json` 的
+    读写、dedup、corrupt-file 容错（`tests` 5 个 case）。
+
+### Fixed
+- **ESM `require()` 报错**：`src/index.ts` 顶层原先使用
+  `require('child_process')` / `require('fs')`，在 `"type": "module"` 项目里
+  直接抛 `ReferenceError: require is not defined`，导致 CLI 在包含 `package.json`
+  的项目目录下完全无法启动。改为 `createRequire(import.meta.url)` 兼容。
+- **`--version` 与 banner 打印老版本号**：`src/index.ts:102` 与
+  `src/repl/output.ts:198` 硬编码 `0.2.0`/`v0.2.0`，而 `package.json` 是 `0.2.1`
+  甚至后续 release。两处都改为从 `package.json` 动态读取。
+- **REPL Ctrl+C 无法退出**：`src/repl/loop.ts` 的全局 SIGINT 处理只打
+  warning，从来不调用 `this.running = false`。新增 `REPLInput.requestCancel()`，
+  在空输入连按两次 Ctrl+C 时正确退出。
+- **`executeTask` 助手消息丢失**：单命令模式下助手回复从来没写回
+  `SessionManager`，导致同名 SessionManager 实例对多轮 prompt 拿不到上下文。
+- **`(this.ai as any).chatStream`** 多余 `any` 强转：`this.ai` 已经过
+  null-check，删掉即可。
+- **`extractToolCalls` 死分支**：`src/core/ai-engine.ts` 中 `if (…includes('tool_use'))
+  return undefined; return undefined;` 等价于永远返回 `undefined`。改为单行
+  `return undefined;` 并添加注释说明当前实际无法解析 tool call（属于已知限制）。
+- **欢迎页 banner 字样写错**：`src/repl/welcome.ts` 顶部仍写着 `Claude Code`，
+  与项目名 `Thatgfsj Code` 不一致。已更正。
+
+### Changed
+- **`init` 命令动态 import 去重**：`src/index.ts:54` 的
+  `await import('./repl/welcome.js')` 与顶部静态 import 重复，删除。
+- **`handleModelSwitch`** 在 `src/index.ts` 中属于死代码（无调用者），删除。
+- **欢迎页标题框宽度自适应**：把 banner 顶部的 `Claude Code ` 换成
+  `Thatgfsj Code ` 后调整间隔符长度，保证盒子保持 62 列对齐。
+
+### Documentation
+- 新增 `DEVELOPMENT.md`：覆盖架构图、构建/测试流程、添加 provider / 命令 / tool
+  的步骤、跨平台注意事项、发布流程。
+- 新增本文件 `CHANGELOG.md`。
+- 更新 `README.md`：替换失效的 `git.io/thatgfsj` 安装链接为 GitHub raw 直链；
+  补上 `gfcode init` 使用示例与所有顶层 / 子命令 flag；附 REPL 内置命令列表
+  以及 Node ≥ 18 的前置条件。
+- `docs/FAQ.md`、`docs/API_KEY_GUIDE.md` 交叉链接到 `DEVELOPMENT.md`。
+
+### Packaging
+- `package.json` 新增 `files`、`engines`、`repository`、`bugs`、`homepage`
+  字段；原先没有 `files` 白名单会导致 `npm publish` 不会自动包含 `dist/`
+  （dist 在 `.gitignore` 里），现在通过显式白名单确保 tarball 包含
+  构建产物与文档。
+- 新增 `scripts.test`、`scripts.test:silent`、`scripts.prepublishOnly`，
+  发布前自动跑测试和 build，防止 release 出错。
+
+### Tests
+- 新增 `tests/` 目录，使用 Node 内置 `node --test` 跑通：
+  - `tests/smoke-cli.test.js` — `dist/index.js --version` / `--help` / `chat`
+    / `explain` / `debug` / `template` 空参守卫；`bash -n install.sh` 语法。
+  - `tests/unit-session.test.js` — `SessionManager` 拦截「已中断」污染、
+    相邻助手消息去重、`truncate` 保留 system。
+  - `tests/unit-diff.test.js` — `DiffPreview.compare` 在相同 / 不同 /
+    空 / unicode / CRLF 输入下的行为。
+
+---
+
+## [0.2.1] - 2026-07-XX
+
+### Fixed
+- REPL 数字小键盘方向键响应（升级到 `@inquirer/input`，不再用 Node `readline`
+  直接 `.question()`）。
+- 流式输出保留完整内容、不再 reset 终端 / 跳顶，用户可滚动查看历史。
+- 修复 AI 输出 `[已中断]` 等污染字符串时反复循环同一段的 bug（`SessionManager`
+  拦截 `已中断` / `think` block，`getMessages()` 做相邻助手去重）。
+
+### Added
+- `src/repl/welcome.ts` Claude Code 风格欢迎页与 `gfcode init` 配置向导。
+- `src/tools/{file,shell,git,search}.ts` 完整工具实现，并通过
+  `ToolRegistry` 注册到 AI Engine。
+- `src/agent/{core,intent,streaming}.ts` Agent Loop、意图识别、流式输出。
+- `src/utils/{diff-preview,memory,project-context}.ts`。
+- `src/mcp/client.ts`：MCP 客户端雏形。
+
+---
+
+## [0.1.0] - initial
+
+- 初版发布：基础 `explain` / `debug` / `chat` / `template` 命令与 REPL 雏形。

package/DEVELOPMENT.md

@@ -0,0 +1,286 @@
+# Development Guide — Thatgfsj Code
+
+This document is for contributors / maintainers. End users should read
+[`README.md`](./README.md) instead.
+
+---
+
+## 1. Overview
+
+**Thatgfsj Code** is a Claude Code–style interactive AI coding assistant that
+runs entirely in your terminal. It is written in TypeScript, published as an
+ESM npm package, distributed under MIT, and targets **Node.js ≥ 18**.
+
+The tool exposes:
+
+- A non-interactive single-shot CLI (`gfcode "..."`).
+- An interactive REPL (`gfcode` with no args).
+- Subcommands: `init`, `explain`, `debug`, `chat`, `template`.
+
+The release pipeline is: **bug fix → docs → smoke test → git commit + tag →
+push → GitHub release → `npm publish`**. Everything in `src/` compiles to
+`dist/` via `tsc`; the `package.json` `files` whitelist decides what ships
+in the npm tarball.
+
+---
+
+## 2. Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                         src/index.ts                          │
+│   CLI entry · commander program · subcommand dispatch         │
+│   (init / explain / debug / chat / template / default REPL)  │
+└─────────────────────────┬────────────────────┬───────────────┘
+                          │                    │
+              ┌───────────▼──────────┐ ┌───────▼─────────────┐
+              │   AI Engine + Tools  │ │      REPL Loop       │
+              │ src/core/ai-engine   │ │ src/repl/{loop,...}  │
+              │ src/tools/{file,…}   │ │ @inquirer/input      │
+              └───────────┬──────────┘ └───────┬─────────────┘
+                          │                    │
+              ┌───────────▼────────────────────▼───────────────┐
+              │        Core / Utils / Agent / MCP              │
+              │ src/core/{config,session,types,subagent,…}     │
+              │ src/utils/{diff-preview,memory,project-…}     │
+              │ src/agent/{core,intent,streaming}             │
+              │ src/mcp/client.ts                              │
+              └────────────────────────────────────────────────┘
+```
+
+### Module responsibilities
+
+| Layer     | Files                                        | Job                                                                |
+|-----------|----------------------------------------------|--------------------------------------------------------------------|
+| Entry     | `src/index.ts`                               | commander program, subcommand handlers, REPL bootstrap             |
+| REPL      | `src/repl/{input,output,loop,welcome}.ts`    | interactive prompt, ANSI output, SIGINT, welcome/init wizard       |
+| Core      | `src/core/{ai-engine,config,session,…}.ts`   | AI provider abstraction, config loading, session state            |
+| Tools     | `src/tools/{file,shell,git,search}.ts`       | file I/O, shell exec, git ops, code search                         |
+| Agent     | `src/agent/{core,intent,streaming}.ts`       | intent classification, agent loop, streamed terminal output        |
+| Utils     | `src/utils/{diff-preview,memory,…}.ts`       | side-effect-free helpers                                           |
+| MCP       | `src/mcp/client.ts`                          | Model Context Protocol stdio client                                |
+
+### Data flow on a single prompt
+
+```
+User ──▶ commander ──▶ executeTask(prompt)
+                       │
+                       ├─▶ ConfigManager.load()         (process.env + ~/.thatgfsj/config.json)
+                       │
+                       ├─▶ AIEngine.chatStream(messages) ──▶ provider base URL /v1/chat/completions
+                       │                                  or Anthropic /messages
+                       │                                  or Gemini :generateContent
+                       │
+                       └─▶ process.stdout.write(chunks) ──▶ terminal (scrollable history)
+```
+
+---
+
+## 3. Build & install
+
+### Prerequisites
+
+- Node.js ≥ 18 (project uses native `fetch`, `AbortController`, top-level `await`,
+  `node --test`).
+- npm ≥ 9 (so `npm publish` understands the `files` whitelist).
+- Git (for the install scripts and during release).
+
+### Local development
+
+```bash
+git clone https://github.com/Thatgfsj/thatgfsj-code.git
+cd thatgfsj-code
+npm install
+npm run build           # produces ./dist
+npm test                # node --test tests/
+npm start               # node dist/index.js (interactive REPL)
+npm run dev             # tsc && node dist/index.js
+
+# Optional: link globally so `gfcode` is in your PATH
+npm link
+```
+
+`npm install` after cloning will trigger `prepublishOnly` if you have it
+configured (we do). Always run `npm run build` after editing source so the
+`dist/` matches `src/`.
+
+### Platform notes
+
+- **Windows**: `src/index.ts` invokes `chcp 65001` synchronously before any
+  output to force UTF-8 in the legacy Windows console. Done via
+  `createRequire(import.meta.url)` so it works under `"type": "module"`.
+- **Numeric keypad arrows**: the REPL uses `@inquirer/input` instead of Node's
+  built-in `readline.question()` because the latter doesn't reliably translate
+  numeric-keypad ANSI escape sequences on Windows terminals (Bug #1 history).
+- **Streaming output**: `process.stdout.write` directly, never `rl.question`
+  inside the loop — the latter would reset the terminal and lose scrollback.
+
+---
+
+## 4. Adding a provider
+
+1. Add the env-var map to `src/core/config.ts` (`envKeys`).
+2. Add a `*_MODELS` array to `src/repl/welcome.ts` and wire it through
+   `getModelsForProvider()` and `interactiveSetup()` (numbered choice).
+3. Update `WelcomeScreen.hasApiKey()` in `src/repl/welcome.ts` to include the
+   new env-var name.
+4. If the provider uses a non-OpenAI request format, extend the dispatcher
+   in `src/core/ai-engine.ts::streamRequest`.
+5. Update `docs/API_KEY_GUIDE.md` and `README.md`'s provider list.
+
+No other files should care about the specific provider.
+
+---
+
+## 5. Adding a built-in CLI command
+
+`src/index.ts` is the single `commander` program. Register a new command
+**before** `program.parse(process.argv)`:
+
+```ts
+program
+  .command('foo')
+  .description('...')
+  .argument('<bar>', '...')
+  .action(async (bar) => { /* ... */ });
+```
+
+For REPL-internal slash-style commands (visible only inside the interactive
+loop), add a new `case` to `src/repl/loop.ts::handleCommand`.
+
+### Built-in REPL commands (current)
+
+| Command          | Behavior                                                                         |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `help`           | Show built-in command list                                                       |
+| `exit` / `quit`  | Leave the REPL                                                                   |
+| `clear`          | Clear the screen                                                                 |
+| `context`        | Show the current project context                                                 |
+| `history`        | Show the command history for this session                                         |
+| `tools`          | List registered tools                                                            |
+| `models`         | Read-only listing of the current provider's models                               |
+| `providers`      | Read-only listing of all providers                                               |
+| `/model`         | **Interactive picker — actually switches the active model** for the current provider. Persists to `~/.thatgfsj/config.json` and calls `AIEngine.updateConfig()`. |
+| `/provider`      | **Interactive picker — switches provider + chains into `/model`** for the new one. Warns if the corresponding env-var / saved API key is missing. |
+| `Ctrl+C`         | Aborts the in-flight stream once, exits after two empty-prompt cancels.          |
+
+Both `/model` and `/provider` accept either a numeric index or the exact
+provider/model id; pressing Enter with no input keeps the current value. After
+a switch, `REPLLoop` injects a one-line `[system: ... switched to ...]`
+message into the session so the LLM can see the change in the next turn.
+
+---
+
+## 6. Adding a tool
+
+Tools implement the `Tool` interface declared in `src/core/types.ts`:
+
+```ts
+export interface Tool {
+  name: string;
+  description: string;
+  parameters: ToolParameter[];
+  execute(params: any, ctx: ToolContext): Promise<ToolResult>;
+}
+```
+
+Steps:
+1. Create `src/tools/<name>.ts` exporting a class implementing `Tool`.
+2. Register it in `src/tools/index.ts::getBuiltInTools()` so both the REPL
+   `REPLLoop.init` and `executeTask` pick it up automatically.
+
+> **Known limitation (0.2.2):** `src/core/ai-engine.ts::extractToolCalls`
+> currently returns `undefined`. Tools are registered but never actually
+> invoked from a streamed response. Wiring this up requires parsing each
+> provider's native `tool_calls` delta and is tracked under "Unreleased" in
+> `CHANGELOG.md`. Until then, `ToolRegistry` is a forward-compatible seam.
+
+---
+
+## 7. MCP integration
+
+`src/mcp/client.ts` defines a small stdio MCP client. It spawns a child
+process and exchanges JSON-RPC via newline-delimited messages. The current
+shape is intentionally minimal — see the file for the protocol mapping.
+
+---
+
+## 8. Cross-platform & UX details
+
+- **Encoding**: Windows-only `chcp 65001` in `src/index.ts:9-15`. Skipped
+  silently if it fails.
+- **Color**: `chalk` v5 is ESM-only; the project is `"type": "module"` so
+  this is fine.
+- **Spinner**: `ora` v7 with `dots` spinner; cyan.
+- **History**: local to a single REPL session (not persisted across runs).
+
+---
+
+## 9. Tests
+
+```bash
+npm test                # runs node --test tests/  (full TAP output)
+npm run test:silent     # dot reporter, for noisy CI logs
+```
+
+Tests live in `tests/` and use Node's built-in `node:test` runner — no
+vitest / jest dev-dep. They cover:
+
+- Smoke tests of the compiled `dist/index.js` binary (`--version`, `--help`,
+  subcommand empty-arg guards, `bash -n install.sh`).
+- Boundary tests of pure modules (`SessionManager`, `DiffPreview`,
+  `REPLOutput`) — empty input, unicode, CRLF, very long input.
+- No network. No mocked API keys. No shell-out side-effects other than the
+  install script's `bash -n` parse-check.
+
+CI integration: if you set this up later, run `npm test && npm run build`
+in the job; the `prepublishOnly` script already chains them.
+
+---
+
+## 10. Release process
+
+1. Edit `package.json` `version` (semver).
+2. Add a new section at the top of `CHANGELOG.md`.
+3. `npm test && npm run build` locally — make sure both are green.
+4. `git add -A && git commit -m "release: vX.Y.Z"`
+5. `git tag vX.Y.Z`
+6. `git push origin main --follow-tags`
+7. `gh release create vX.Y.Z --title "vX.Y.Z" --notes-file CHANGELOG.md`
+   (the section for the new version is the top entry; trim if needed).
+8. `npm publish --access public` (a `prepublishOnly` step in `package.json`
+   re-runs tests + build, so you can't accidentally publish a stale build).
+
+### Semver policy
+
+- **patch** (`Z`): bug fixes, docs, refactors, no public API change.
+- **minor** (`Y`): new public command, new provider, new tool.
+- **major** (`X`): breaking change to the CLI surface or the JS API surface
+  (currently no JS API is stable).
+
+---
+
+## 11. Troubleshooting
+
+### `ReferenceError: require is not defined`
+
+You're editing TypeScript and accidentally called `require(...)` outside of a
+`createRequire(import.meta.url)` shim. The project is ESM. Use `import x from 'y'`
+at the top of the file.
+
+### `npm publish` ships no `dist/`
+
+You forgot to run `npm run build` (or the `prepublishOnly` script was
+removed). The `files` whitelist in `package.json` requires the `dist/`
+directory to exist locally when publishing.
+
+### `gfcode --version` shows the wrong number
+
+Edit it in `package.json` only — `src/index.ts` and `src/repl/output.ts` both
+read `VERSION` from `package.json` via `import pkg from '../package.json' …`.
+
+### REPL keypresses / Ctrl+C misbehave on Windows
+
+Make sure you're on Windows Terminal or any TTY that emits ANSI escape
+sequences natively. The legacy `cmd.exe` console has incomplete ANSI
+support — upgrade to Windows Terminal or use PowerShell.

package/README.md

@@ -1,16 +1,20 @@
 # Thatgfsj Code 🤖
 
-你的 CLI 工具
+你的 CLI 工具 - 像 Claude Code 一样使用 AI 编程。
+
+> 当前版本: **0.2.2** · Node.js ≥ 18 · MIT 许可证
 
 ---
 
 ## ⭐ 特性
 
-- 🤖 **AI 对话** - 用自然语言让 AI 帮你写代码
-- 📖 **代码解释** - 通俗易懂地解释代码含义
-- 🔧 **代码调试** - 找出 bug 并给出修复方案
-- 📦 **代码模板** - 快速生成项目代码
-- 💬 **交互模式** - 持续对话，像聊天一样编程
+- 🤖 **AI 对话** — 用自然语言让 AI 帮你写代码
+- 📖 **代码解释** — 通俗易懂地解释代码含义
+- 🔧 **代码调试** — 找出 bug 并给出修复方案
+- 📦 **代码模板** — 快速生成项目代码
+- 💬 **交互模式** — 持续对话，像聊天一样编程
+- 🧰 **内置工具** — 文件读写 / Shell 执行 / Git 操作 / 代码搜索
+- 🚫 **抗污染防御** — `SessionManager` 自动过滤 `[已中断]` 等历史污染
 
 ---
 
@@ -18,83 +22,180 @@
 
 ### 🎯 一键安装（推荐）
 
-**Windows 用户**：复制下面命令，粘贴到 CMD 里回车：
+安装脚本全部托管在 GitHub 上、`install.sh` / `install.ps1` / `install.bat`
+可直接 curl / iwr：
 
-```cmd
-curl -L https://git.io/thatgfsj -o install.bat && install.bat
+**macOS / Linux**：
+
+```bash
+curl -L https://raw.githubusercontent.com/Thatgfsj/thatgfsj-code/main/install.sh | bash
 ```
 
 **Windows (PowerShell)**：
 
 ```powershell
-powershell -c "irm https://git.io/thatgfsj | iex"
+irm https://raw.githubusercontent.com/Thatgfsj/thatgfsj-code/main/install.ps1 | iex
 ```
 
-**macOS / Linux**：
+**Windows (CMD)**：
 
-```bash
-curl -sL https://git.io/thatgfsj | bash
+```cmd
+curl -L https://raw.githubusercontent.com/Thatgfsj/thatgfsj-code/main/install.bat -o install.bat && install.bat
 ```
 
+> ⚠️ 旧版本 README 里出现的 `https://git.io/thatgfsj` 短链已失效（GitHub 在 2022
+> 年下线了 `git.io`），请使用上面的原始 GitHub 链接。
+
 安装过程会自动完成：
-1. 检查/安装 Node.js
-2. 下载代码
-3. 安装依赖
-4. 配置命令
-5. 引导设置 API Key
+1. 检查/安装 Node.js（≥ 18）
+2. 下载代码 / 链接 npm 全局命令
+3. 安装依赖并构建 `dist/`
+4. 引导你设置 API Key
 
 ---
 
 ## 📖 使用方法
 
-安装完成后，在终端里直接用：
+安装完成后，在终端里直接用 `gfcode`（或 `thatgfsj`，两个 bin 都指向同一入口）：
 
 ```bash
 # 交互模式（推荐）
 gfcode
 
-# 让 AI 帮你写代码
+# 让 AI 帮你写代码（单命令模式，自动流式输出）
 gfcode "写一个 Python 的 Hello World"
+gfcode -m Qwen/Qwen2.5-32B-Instruct "重构 src/index.ts"
 
-# 解释代码
+# 解释代码:直接传字符串,或 -f 指定文件
 gfcode explain "const add = (a, b) => a + b;"
+gfcode explain -f src/index.ts
 
-# 调试代码
+# 调试代码:可附加 -e 错误信息
 gfcode debug "你的代码"
+gfcode debug -f src/foo.ts -e "TypeError: x is not a function"
 
-# 问答
+# 问答（带当前项目上下文）
 gfcode chat "怎么用 Node.js 写 API?"
 
 # 生成代码模板
-gfcode template react -n MyButton
+gfcode template react -n MyButton -o ./components
 ```
 
+> `--stream` / `--no-auto` / `-m` 接受任意命令并对当次调用生效；`-i` 强制进入 REPL。
+> 详细 flag 见 [`DEVELOPMENT.md`](./DEVELOPMENT.md) 第 5 节。
+
+### REPL 内置命令
+
+进入交互模式（直接运行 `gfcode`）后，可以输入下列命令（带或不带前导 `/` 都行）：
+
+| 命令           | 作用                                                |
+| -------------- | --------------------------------------------------- |
+| `help`         | 显示所有内置命令                                    |
+| `exit`         | 退出 REPL                                           |
+| `clear`        | 清屏                                                |
+| `context`      | 显示当前项目上下文                                  |
+| `history`      | 显示本次会话的命令历史                              |
+| `tools`        | 列出已注册的工具（file / shell / git / search）     |
+| `models`       | 只读地列出当前 provider 的可用模型                  |
+| `providers`    | 只读地列出支持的 provider                           |
+| `/model`       | **交互式切换当前 provider 下的模型**，立即生效并持久化到 `~/.thatgfsj/config.json` |
+| `/provider`    | **交互式切换 provider**，切换后自动跟进选模型       |
+| `Ctrl+C`       | 单次：停止当前流式生成；空输入连续两次退出 REPL     |
+
+#### `/model` / `/provider` 示例
+
+```
+> /model
+🤖 /model — 切换模型 (provider: siliconflow)
+
+  最近使用:
+  r1. Qwen/Qwen2.5-32B-Instruct
+  r2. Pro/moonshotai/Kimi-K2.5
+
+  内置模型:
+   1. Qwen2.5-7B (推荐)             Qwen/Qwen2.5-7B-Instruct  ✓
+   2. Qwen2.5-32B                   Qwen/Qwen2.5-32B-Instruct
+   3. Qwen2.5-72B                   Qwen/Qwen2.5-72B-Instruct
+   4. Kimi-K2.5 (私有)              Pro/moonshotai/Kimi-K2.5
+   5. DeepSeek-V3                   Pro/deepseek-ai/DeepSeek-V3
+   …
+
+输入编号 (r1-r2 / 1-10)、完整 model id、或任意自定义 id。回车保持当前。
+model > r2
+✅ 模型已切换为: Pro/moonshotai/Kimi-K2.5  (Pro/moonshotai/Kimi-K2.5)
+
+# 也可以直接粘一个自定义 model id(适合 OpenAI-compatible 中转/Ollama):
+model > my-custom-fine-tune
+✅ 模型已切换为: my-custom-fine-tune  (自定义)
+```
+
+`/provider` 的工作流类似，但会让你先选 9 个提供商之一（SiliconFlow /
+MiniMax / OpenAI / Anthropic / Gemini / Kimi / DeepSeek / ERNIE / Ollama），
+然后自动跟进模型选择。如果新 provider 缺少对应的环境变量，会提示先
+`gfcode init` 或手动 `export`。
+
+切换过的 model 会写入 `~/.thatgfsj/models.json` 历史文件,下次打开
+`/model` 时按时间倒序展示在「最近使用」段。
+
 ---
 
 ## ❓ 常见问题
 
 ### Q: 安装后命令找不到？
 
-**A**: 重启终端，然后运行 `gfcode`
+**A**: 重启终端，然后运行 `gfcode`。Windows 上确认 PowerShell / CMD 已重新加载 `%PATH%`。
 
 ### Q: 怎么配置 API Key？
 
-**A**: 运行 `gfcode init`，按提示选择并输入 API Key
+**A**: 运行 `gfcode init`，按提示选择提供商、粘贴 key、挑选模型。也可以直接设置环境变量
+（`SILICONFLOW_API_KEY` / `OPENAI_API_KEY` / `MINIMAX_API_KEY` /
+`ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `KIMI_API_KEY` / `DEEPSEEK_API_KEY` /
+`ERNIE_API_KEY`），或者把配置写到 `~/.thatgfsj/config.json`。
 
 ### Q: 哪个 Provider 最好？
 
-**A**: 新手推荐 **SiliconFlow**（性价比高，国产）
+**A**: 新手推荐 **SiliconFlow**（性价比高，国产），可选用 Qwen2.5 / Kimi-K2.5 / DeepSeek-V3 等模型。
+
+### Q: `--version` 显示老版本号？
+
+**A**: 升级到 0.2.2+，版本号现在从 `package.json` 动态读取，CI / re-install 都会自动同步。
+
+### Q: 启动瞬间报错 `ReferenceError: require is not defined`？
+
+**A**: 那是 0.2.1 之前的 bug，0.2.2 已经修复（使用 `createRequire(import.meta.url)` 兼容）。
+
+更多问题 → [`docs/FAQ.md`](./docs/FAQ.md)。
 
 ---
 
 ## 📚 文档
 
-- [API Key 获取教程](./docs/API_KEY_GUIDE.md)
-- [常见问题 FAQ](./docs/FAQ.md)
+- [DEVELOPMENT.md](./DEVELOPMENT.md) — 架构 / 构建 / 扩展 / 发布（贡献者必读）
+- [CHANGELOG.md](./CHANGELOG.md) — 每次版本的变更说明
+- [docs/API_KEY_GUIDE.md](./docs/API_KEY_GUIDE.md) — 9 个 Provider 的 API Key 获取教程
+- [docs/FAQ.md](./docs/FAQ.md) — 详细 FAQ
+
+---
+
+## 🧪 本地自检
+
+```bash
+npm install
+npm test          # node --test tests/
+npm run build
+node dist/index.js --version
+```
 
 ---
 
 ## 🤝 问题反馈
 
-有问题？去 GitHub 提 Issue：  
+有问题？去 GitHub 提 Issue：
+
 https://github.com/Thatgfsj/thatgfsj-code/issues
+
+---
+
+## 📜 License
+
+MIT © Thatgfsj

package/dist/core/ai-engine.d.ts

@@ -11,6 +11,16 @@ export declare class AIEngine {
     private config;
     private tools;
     constructor(config: AIConfig);
+    /**
+     * Replace the active configuration at runtime.
+     * Used by the REPL `/model` / `/provider` commands — the next streamed
+     * request will pick up the new model / baseUrl / provider.
+     */
+    updateConfig(config: AIConfig): void;
+    /**
+     * Inspect a snapshot of the active configuration (read-only).
+     */
+    getConfig(): Readonly<AIConfig>;
     /**
      * Register tools for function calling
      */
@@ -43,6 +53,13 @@ export declare class AIEngine {
     private parseResponse;
     /**
      * Extract tool calls from response content
+     *
+     * NOTE: 当前为占位实现,实际不会从流式内容中解析工具调用。这意味着
+     * `chatStream` 内的 `if (response.tool_calls ...)` 分支永远不会进入,
+     * 已注册的 `Tool` 不会被调用,Agent 等价于一个聊天客户端。这是有意为之的
+     * 局限性 — 真实工具调用解析需要每个提供商走 JSON mode / native tool_calls
+     * 流(chunks 里的 `delta.tool_calls` 已被 `extractChunkText` 丢弃)。
+     * 修复此问题需要更大的重构,不属于 0.2.2 patch 的范围。
      */
     private extractToolCalls;
     /**