```
├── .github/
├── ISSUE_TEMPLATE/
├── bug_report.yml (300 tokens)
├── feature_request.yml (200 tokens)
├── IFLOW.md (600 tokens)
├── README.md (1700 tokens)
├── README_CN.md (1000 tokens)
├── README_DE.md (2k tokens)
├── README_ES.md (2000 tokens)
├── README_FR.md (2k tokens)
├── README_JA.md (1200 tokens)
├── README_KO.md (1200 tokens)
├── README_RU.md (1900 tokens)
├── assets/
├── example1_EN.jpg
├── iflow-cli.jpg
├── iflow-wechat.jpg
├── iflow_start.jpg
├── login.jpg
├── profile-settings.jpg
├── web-login.jpg
├── docs_cn/
├── changelog.md (1200 tokens)
├── configuration/
├── iflow.md (1300 tokens)
├── iflowignore.md (500 tokens)
├── settings.md (3.6k tokens)
├── examples/
├── basic-usage.md (500 tokens)
├── best-practices.md (700 tokens)
├── hooks.md (3.7k tokens)
├── index.md (600 tokens)
├── keyboard-shortcuts.md (600 tokens)
├── mcp.md (1200 tokens)
├── subagent.md (1500 tokens)
├── subcommand.md (2.2k tokens)
├── workflow.md (600 tokens)
├── features/
├── action.md (1100 tokens)
├── checkpointing.md (500 tokens)
├── ide.md (700 tokens)
├── interactive.md (1100 tokens)
├── memory-import.md (600 tokens)
├── output-style.md (400 tokens)
├── sandbox.md (100 tokens)
├── slash-commands.md (800 tokens)
├── suspending-resuming.md (300 tokens)
├── telemetry.md (1900 tokens)
├── thinking.md (400 tokens)
├── glossary.md (800 tokens)
├── quickstart.md (800 tokens)
├── scenarios.md (1700 tokens)
├── sdk/
├── sdk-android.md (2.2k tokens)
├── sdk-python.md (2.1k tokens)
├── docs_en/
├── changelog.md (2.4k tokens)
├── configuration/
├── iflow.md (2.6k tokens)
├── iflowignore.md (900 tokens)
├── settings.md (6.2k tokens)
├── examples/
├── basic-usage.md (1100 tokens)
├── best-practices.md (1600 tokens)
├── hooks.md (5.8k tokens)
├── index.md (1200 tokens)
├── keyboard-shortcuts.md (1000 tokens)
├── mcp.md (2.1k tokens)
├── subagent.md (2.9k tokens)
├── subcommand.md (3.8k tokens)
├── workflow.md (1400 tokens)
├── features/
├── action.md (1300 tokens)
├── checkpointing.md (1100 tokens)
├── ide.md (1000 tokens)
├── interactive.md (2.5k tokens)
├── memory-import.md (1400 tokens)
├── output-style.md (700 tokens)
├── sandbox.md (200 tokens)
├── slash-commands.md (1700 tokens)
├── suspending-resuming.md (700 tokens)
├── telemetry.md (3.2k tokens)
├── thinking.md (900 tokens)
├── glossary.md (1700 tokens)
├── quickstart.md (1500 tokens)
├── scenarios.md (3.7k tokens)
├── sdk/
├── sdk-android.md (2.7k tokens)
├── sdk-python.md (2.5k tokens)
├── install.sh (3.4k tokens)
├── install_beta.sh (3.4k tokens)
```
## /.github/ISSUE_TEMPLATE/bug_report.yml
```yml path="/.github/ISSUE_TEMPLATE/bug_report.yml"
name: Bug Report
description: Report a bug to help us improve iFlow CLI
labels: ['kind/bug', 'status/need-triage']
body:
- type: markdown
attributes:
value: |
> [!IMPORTANT]
> Thanks for taking the time to fill out this bug report!
>
> Please search **[existing issues](https://github.com/iflow-ai/iflow-cli/issues)** to see if an issue already exists for the bug you encountered.
- type: textarea
id: problem
attributes:
label: What happened?
description: A clear and concise description of what the bug is.
validations:
required: true
- type: textarea
id: expected
attributes:
label: What did you expect to happen?
validations:
required: true
- type: textarea
id: info
attributes:
label: Client information
description: Please paste the full text from the `/about` command run from iFLow CLI. Also include which platform (macOS, Windows, Linux).
value: |
<details>
\`\`\`console
$ iflow /about
# paste output here
\`\`\`
</details>
validations:
required: true
- type: textarea
id: login-info
attributes:
label: Login information
description: Describe how you are logging in (e.g., iFlow Account, API key).
- type: textarea
id: additional-context
attributes:
label: Anything else we need to know?
description: Add any other context about the problem here.
```
## /.github/ISSUE_TEMPLATE/feature_request.yml
```yml path="/.github/ISSUE_TEMPLATE/feature_request.yml"
name: Feature Request
description: Suggest an idea for this project
labels: ['kind/enhancement', 'status/need-triage']
body:
- type: markdown
attributes:
value: |
> [!IMPORTANT]
> Thanks for taking the time to suggest an enhancement!
>
> Please search **[existing issues](https://github.com/iflow-ai/iflow-cli/issues)** to see if a similar feature has already been requested.
- type: textarea
id: feature
attributes:
label: What would you like to be added?
description: A clear and concise description of the enhancement.
validations:
required: true
- type: textarea
id: rationale
attributes:
label: Why is this needed?
description: A clear and concise description of why this enhancement is needed.
validations:
required: true
- type: textarea
id: additional-context
attributes:
label: Additional context
description: Add any other context or screenshots about the feature request here.
```
## /IFLOW.md
# IFLOW.md
This file provides guidance to iFlow Cli when working with code in this repository.
## Project Overview
This repository contains the iFlow CLI, a comprehensive command-line intelligent tool that embeds into your terminal, can analyze your code repository, execute coding tasks, understand your needs across contexts, and improve efficiency by performing various tasks from simple file operations to complex workflow automation.
## Key Features
1. Supports multiple AI models including Kimi K2, Qwen3 Coder, DeepSeek v3, etc.
2. Compatible with OpenAI protocol model providers
3. Integrates with Model Context Protocol (MCP) servers for extended functionality
4. Provides slash commands for meta-level control over the CLI itself
## Repository Structure
- `install.sh` - Installation script for iFlow CLI
- `README*.md` - Documentation in multiple languages
- `assets/` - Images and screenshots
- `i18/` - Internationalized command documentation
- `.git/` - Git repository metadata
## Development Commands
### Installation
```bash
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
### Initialization
For a new project or when first using iFlow CLI in an existing project:
```
iflow
> /init
```
This command will scan your codebase and create/update the IFLOW.md file with project-specific documentation.
## Key Slash Commands
- `/init` - Initialize iFlow CLI with project understanding
- `/memory` - Manage AI's instruction context
- `/tools` - Display available tools
- `/clear` - Clear terminal screen and session history
- `/copy` - Copy last output to clipboard
- `/stats` - Display session statistics
- `/compress` - Replace chat context with summary
- `/chat` - Save and restore conversation history
- `/help` - Display help information
- `/quit` - Exit iFlow CLI
- `/bug` - Submit issue feedback
- `/editor` - Select code editor
- `/mcp` - List MCP servers and tools
- `/theme` - Change visual theme
- `/auth` - Change authentication method
- `/about` - Display version information
- `/extensions` - List active extensions
## At Commands (@)
Include file or directory content in prompts:
- `@<path_to_file_or_directory>` - Inject content into your prompt
## Shell Mode (!)
Execute system shell commands directly:
- `!<shell_command>` - Execute shell command
- `!` - Toggle shell mode
## Architecture Overview
The iFlow CLI is built as a Node.js application that integrates with multiple AI models and MCP servers. The installation script handles:
1. Installing Node.js via nvm if not present
2. Setting up npm global directory
3. Installing the iFlow CLI package
4. Configuring MCP servers in `~/.iflow/settings.json`
The CLI supports multiple languages through the i18 directory structure and provides extensive customization through its various commands and configuration options.
## MCP Servers Configuration
The iFlow CLI integrates with several MCP servers that extend its functionality:
1. sequential-thinking - For complex problem-solving
2. context7 - For library documentation retrieval
3. magic - For UI component generation
4. playwright - For browser automation
These servers are configured in `~/.iflow/settings.json` and can be listed with the `/mcp` command.
## /README.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
**English** | [中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Deutsch](README_DE.md) | [Español](README_ES.md) | [Русский](README_RU.md)
iFlow CLI is a powerful AI assistant that runs directly in your terminal. It seamlessly analyzes code repositories, executes coding tasks, understands context-specific needs, and boosts productivity by automating everything from simple file operations to complex workflows.
[More Tutorials](https://platform.iflow.cn/)
## ✨ Key Features
1. **Free AI Models**: Access powerful and free AI models through the [iFlow open platform](https://platform.iflow.cn/docs/api-mode), including Kimi K2, Qwen3 Coder, DeepSeek v3, and more
2. **Flexible Integration**: Keep your favorite development tools while integrating into existing systems for automation
3. **Natural Language Interaction**: Say goodbye to complex commands, drive AI with everyday conversation, from code development to life assistance
4. **Open Platform**: Install SubAgents and MCP with one click from the [iFlow Open Market](https://platform.iflow.cn/), quickly expand intelligent agents and build your own AI team
## Feature Comparison
| Feature | iFlow Cli | Claude Code | Gemini Cli |
|---------|-----------|-------------|------------|
| Todo Planning | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| Custom Commands | ✅ | ✅ | ✅ |
| Plan Mode | ✅ | ✅ | ❌ |
| Task Tools | ✅ | ✅ | ❌ |
| VS Code Plugin | ✅ | ✅ | ✅ |
| JetBrains Plugin | ✅ | ✅ | ❌ |
| Conversation Recovery | ✅ | ✅ | ❌ |
| Built-in Open Market | ✅ | ❌ | ❌ |
| Memory Auto-compression | ✅ | ✅ | ✅ |
| Multimodal Capability | ✅ | ⚠️ (Limited in China) | ⚠️ (Limited in China) |
| Search | ✅ | ❌ | ⚠️ (Requires VPN) |
| Free | ✅ | ❌ | ⚠️ (Limited Usage) |
| Hook | ✅ | ✅ | ❌ |
| Output Style | ✅ | ✅ | ❌ |
| Thinking | ✅ | ✅ | ❌ |
| Workflow | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ Key Features
* Support 4 running modes: yolo (model has maximum permissions, can perform any operation), accepting edits (model only has file modification permissions), plan mode (plan first, then execute), default (model has no permissions)
* Upgraded subAgent functionality: Transform CLI from general assistant to expert team, providing more professional and accurate advice. Use /agent to see more pre-configured agents
* Upgraded task tool: Effectively compress context length, allowing CLI to complete your tasks more thoroughly. Auto-compression when context reaches 70%
* Integrated with iFlow Open Market: Quickly install useful MCP tools, Subagents, custom instructions and workflows
* Free multimodal model usage: You can also paste images in CLI now (Ctrl+V to paste images)
* Support for conversation history saving and rollback (iflow --resume and /chat commands)
* Support for more useful terminal commands (iflow -h to see more commands)
* VSCode plugin support
* Auto-upgrade: iFlow CLI automatically detects if current version is latest
## 📥 Installation
### System requirements
- Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)
- Hardware: 4GB+ RAM
- Software: Node.js 22+
- Network: Internet connection required for authentication and AI processing
- Shell: Works best in Bash, Zsh or Fish
### Installation Commands
**MAC/Linux/Ubuntu Users**:
* One-click installation command (Recommended)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Using Node.js installation
```shell
npm i -g @iflow-ai/iflow-cli
```
This command automatically installs all necessary dependencies for your terminal.
**Windows Users**:
1. Go to https://nodejs.org/en/download to download the latest Node.js installer
2. Run the installer to install Node.js
3. Restart your terminal: CMD or PowerShell
4. Run `npm install -g @iflow-ai/iflow-cli` to install iFlow CLI
5. Run `iflow` to start iFlow CLI
If you are in China Mainland, you can use the following command to install iFlow CLI:
1. Go to https://cloud.iflow.cn/iflow-cli/nvm-setup.exe to download the latest nvm installer
2. Run the installer to install nvm
3. **Restart your terminal: CMD or PowerShell**
4. Run `nvm node_mirror https://npmmirror.com/mirrors/node/` and `nvm npm_mirror https://npmmirror.com/mirrors/npm/`
5. Run `nvm install 22` to install Node.js 22
6. Run `nvm use 22` to use Node.js 22
7. Run `npm install -g @iflow-ai/iflow-cli` to install iFlow CLI
8. Run `iflow` to start iFlow CLI
## 🗑️ Uninstall
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 Authentication
iFlow offers two authentication options:
1. **Recommended**: Use iFlow's native authentication
2. **Alternative**: Connect via OpenAI-compatible APIs
Choose option 1 to login directly, which will open iFlow account authentication in a web page. After completing authentication, you can use it for free.
If you are in an environment like a server where you cannot open a web page, please use option 2 to login.
To get your API key:
1. Register for an iFlow account
2. Go to your profile settings or click [this direct link](https://iflow.cn/?open=setting)
3. Click "Reset" in the pop-up dialog to generate a new API key
After generating your key, paste it into the terminal prompt to complete setup.
## 🚀 Getting Started
To launch iFlow CLI, navigate to your workspace in the terminal and type:
```shell
iflow
```
### Starting New Projects
For new projects, simply describe what you want to create:
```shell
cd new-project/
iflow
> Create a web-based Minecraft game using HTML
```
### Working with Existing Projects
For existing codebases, begin with the `/init` command to help iFlow understand your project:
```shell
cd project1/
iflow
> /init
> Analyze the requirements according to the PRD document in requirement.md file, and output a technical document, then implement the solution.
```
The `/init` command scans your codebase, learns its structure, and creates an IFLOW.md file with comprehensive documentation.
For a complete list of slash commands and usage instructions, see [here](./i18/en/commands.md).
## 💡 Common Use Cases
iFlow CLI extends beyond coding to handle a wide range of tasks:
### 📊 Information & Planning
```text
> Help me find the best-rated restaurants in Los Angeles and create a 3-day food tour itinerary.
```
```text
> Search for the latest iPhone price comparisons and find the most cost-effective purchase option.
```
### 📁 File Management
```text
> Organize the files on my desktop by file type into separate folders.
```
```text
> Batch download all images from this webpage and rename them by date.
```
### 📈 Data Analysis
```text
> Analyze the sales data in this Excel spreadsheet and generate a simple chart.
```
```text
> Extract customer information from these CSV files and merge them into a unified table.
```
### 👨💻 Development Support
```text
> Analyze the main architectural components and module dependencies of this system.
```
```text
> I'm getting a null pointer exception after my request, please help me find the cause of the problem.
```
### ⚙️ Workflow Automation
```text
> Create a script to periodically backup my important files to cloud storage.
```
```text
> Write a program that downloads stock prices daily and sends me email notifications.
```
*Note: Advanced automation tasks can leverage MCP servers to integrate your local system tools with enterprise collaboration suites.*
## 🔧 Switch to customized model
iFlow CLI can connect to any OpenAI-compatible API. Edit the settings file in `~/.iflow/settings.json` to change the model you use.
Here is a settings demo file:
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "your iflow key",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "your iflow key"
}
```
## 🔄 GitHub Actions
You can also use iFlow CLI in your GitHub Actions workflows with the community-maintained action: [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 Community Communication
If you encounter problems in use, you can directly raise Issues on the github page.
You can also scan the following Wechat group to join the community group for communication and discussion.
### Wechat group
## /README_CN.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | **中文** | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Deutsch](README_DE.md) | [Español](README_ES.md) | [Русский](README_RU.md)
iFlow CLI 是一款直接在终端中运行的强大 AI 助手。它能够无缝分析代码仓库、执行编程任务、理解上下文需求，通过自动化处理从简单的文件操作到复杂的工作流程，全面提升您的工作效率。
[更多使用教程](https://platform.iflow.cn/)
## ✨ 核心特性
1. **免费 AI 模型**：通过 [心流开放平台](https://platform.iflow.cn/docs/api-mode) 访问强大的免费 AI 模型，包括 Kimi K2、Qwen3 Coder、DeepSeek v3 等
2. **灵活集成**：保留你喜欢的开发工具，也可集成到现有系统实现自动化
3. **自然语言交互**：告别复杂命令，用日常对话驱动 AI，从代码开发到生活助理
4. **开放平台**：从[心流开放市场](https://platform.iflow.cn/)中可以一键安装SubAgent和MCP,快速扩展智能体，组建只属于你的AI团队
## 功能对比
| 功能 | iFlow Cli | Claude Code | Gemini Cli |
|------|-----------|---------------------|------------|
| todo规划 | ✅ | ✅ | ❌ |
| subagent | ✅ | ✅ | ❌ |
| 自定义command | ✅ | ✅ | ✅ |
| plan模式 | ✅ | ✅ | ❌ |
| task工具 | ✅ | ✅ | ❌ |
| VS Code 插件 | ✅ | ✅ | ✅ |
| JetBrain 插件 | ✅ | ✅ | ❌ |
| 对话恢复 | ✅ | ✅ | ❌ |
| 内置开放市场 | ✅ | ❌ | ❌ |
| memory自动压缩 | ✅ | ✅ | ✅ |
| 多模态能力 | ✅ | ⚠️（国内模型不支持） | ⚠️（国内模型不支持） |
| 搜索 | ✅ | ❌ | ⚠️（翻墙） |
| 免费 | ✅ | ❌ | ⚠️（次数限制） |
| Hook | ✅ | ✅ | ❌ |
| 输出样式 | ✅ | ✅ | ❌ |
| 思考 | ✅ | ✅ | ❌ |
| 工作流 | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ 核心功能
* 支持4种运行模式：yolo模式（模型拥有最大权限，可执行任何操作）、接受编辑模式（模型仅拥有文件修改权限）、计划模式（先计划后执行）、默认模式（模型无权限）
* 升级subAgent功能：将CLI从通用助手转变为专家团队，提供更专业准确的建议。使用 /agent 查看更多预配置代理
* 升级task工具：有效压缩上下文长度，让CLI更彻底地完成您的任务。当上下文达到70%时自动压缩
* 集成心流开放市场：快速安装有用的MCP工具、Subagents、自定义指令和工作流
* 免费多模态模型使用：现在您也可以在CLI中粘贴图片了（Ctrl+V粘贴图片）
* 支持对话历史保存和回滚（iflow --resume 和 /chat 命令）
* 支持更多有用的终端命令（iflow -h 查看更多命令）
* VSCode插件支持
* 自动升级：iFlow CLI自动检测当前版本是否为最新版本
## 📥 安装
### 系统要求
- 操作系统：macOS 10.15+、Ubuntu 20.04+/Debian 10+，或 Windows 10+（使用 WSL 1、WSL 2 或 Git for Windows）
- 硬件：4GB+ 内存
- 软件：Node.js 22+
- 网络：需要互联网连接用于身份验证和 AI 处理
- Shell：在 Bash、Zsh 或 Fish 中效果最佳
### 安装命令
**MAC/Linux/Ubuntu用户**：
* 一键安装命令(推荐)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* 使用Node.js安装
```shell
npm i -g @iflow-ai/iflow-cli
```
此命令会自动为您的终端安装所有必要的依赖项。
**Windows 用户**：
1. 访问 https://nodejs.org/zh-cn/download 下载最新的 Node.js 安装程序
2. 运行安装程序来安装 Node.js
3. 重启终端：CMD 或 PowerShell
4. 运行 `npm install -g @iflow-ai/iflow-cli` 来安装 iFlow CLI
5. 运行 `iflow` 来启动 iFlow CLI
如果您在中国大陆，可以使用以下命令安装 iFlow CLI：
1. 访问 https://cloud.iflow.cn/iflow-cli/nvm-setup.exe 下载最新的 nvm 安装程序
2. 运行安装程序来安装 nvm
3. **重启终端：CMD 或 PowerShell**
4. 运行 `nvm node_mirror https://npmmirror.com/mirrors/node/` 和 `nvm npm_mirror https://npmmirror.com/mirrors/npm/`
5. 运行 `nvm install 22` 来安装 Node.js 22，稍等片刻
6. 运行 `nvm use 22` 来使用 Node.js 22
7. 运行 `npm install -g @iflow-ai/iflow-cli` 来安装 iFlow CLI
8. 运行 `iflow` 来启动 iFlow CLI
## 🗑️ 卸载
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 身份验证
iFlow Cli提供两种身份验证方式：
1. **推荐方式**：使用 iFlow 原生身份验证
2. **备选方式**：通过 OpenAI 兼容 API 连接
直接选择方式一登录，会在网页唤起iFlow账户认证，完成认证后即可免费使用
如果您在例如服务器这种无法唤起网页的环境使用，请使用方式二登录
获取 API Key的步骤：
1. 注册 iFlow 账户
2. 进入个人设置页面或点击[此直达链接](https://iflow.cn/?open=setting)
3. 在弹出对话框中点击"重置"生成新的 API 密钥
生成密钥后，将其粘贴到终端提示符中即可完成设置。**注意**：在 Windows 的 CMD 或者 PowerShell 中，请点击右键进行粘贴。
## 🚀 快速开始
要启动 iFlow CLI，请在终端中导航到您的工作空间并输入：
```shell
iflow
```
### 创建新项目
对于新项目，只需描述您想要创建的内容：
```shell
cd new-project/
iflow
> 使用 HTML 创建一个基于网页的我的世界游戏
```
### 处理现有项目
对于现有代码库，建议先使用 `/init` 命令帮助 iFlow 理解您的项目：
```shell
cd project1/
iflow
> /init
> 根据 requirement.md 文件中的 PRD 文档分析需求，输出技术文档，然后实现解决方案。
```
`/init` 命令会扫描您的代码库，学习其结构，并创建包含完整文档的 IFLOW.md 文件。
有关斜杠命令的完整列表和使用说明，请查看[这里](./i18/cn/commands.md)。
## 💡 常见使用场景
iFlow CLI 的功能远不止编程，它能处理各种类型的任务：
### 📊 信息查询与规划
```text
> 帮我找到北京评分最高的餐厅，制定一个3天的美食之旅行程。
```
```text
> 搜索最新的 iPhone 价格对比，找到最具性价比的购买方案。
```
### 📁 文件管理
```text
> 将我桌面上的文件按文件类型整理到不同的文件夹中。
```
```text
> 批量下载这个网页上的所有图片，并按日期重命名。
```
### 📈 数据分析
```text
> 分析这个 Excel 表格中的销售数据，生成简单的图表。
```
```text
> 从这些 CSV 文件中提取客户信息，合并成统一的表格。
```
### 👨💻 开发支持
```text
> 分析这个系统的主要架构组件和模块依赖关系。
```
```text
> 我的请求后出现了空指针异常，请帮我找到问题原因。
```
### ⚙️ 工作流自动化
```text
> 创建一个脚本，定期将我的重要文件备份到云存储。
```
```text
> 编写一个程序，每天下载股票价格并发送邮件通知。
```
*注意：高级自动化任务可以利用 MCP 服务器将您的本地系统工具与企业协作套件集成。*
## 🔧 切换自定义模型
iFlow CLI 可以连接任何兼容 OpenAI 的 API。编辑 `~/.iflow/settings.json` 中的设置文件来更改您使用的模型。
以下是设置文件示例：
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "your iflow key",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "your iflow key"
}
```
## 🔄 GitHub Actions
您也可以在 GitHub Actions 工作流中使用社区维护的 action：[iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 社区交流
如果您在使用过程中遇到问题，可以直接在 GitHub 页面上提出 Issues。
您也可以扫描以下微信群二维码加入社区群进行交流讨论。
### 微信群
## /README_DE.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | **Deutsch** | [Español](README_ES.md) | [Русский](README_RU.md)
iFlow CLI ist ein leistungsstarker KI-Assistent, der direkt in Ihrem Terminal läuft. Er analysiert nahtlos Code-Repositories, führt Programmieraufgaben aus, versteht kontextspezifische Anforderungen und steigert die Produktivität durch Automatisierung - von einfachen Dateioperationen bis hin zu komplexen Workflows.
[Weitere Tutorials](https://platform.iflow.cn/)
## ✨ Hauptfunktionen
1. **Kostenlose KI-Modelle**: Zugang zu leistungsstarken und kostenlosen KI-Modellen über die [iFlow Open Platform](https://platform.iflow.cn/docs/api-mode), einschließlich Kimi K2, Qwen3 Coder, DeepSeek v3 und mehr
2. **Flexible Integration**: Behalten Sie Ihre bevorzugten Entwicklungstools bei und integrieren Sie sie in bestehende Systeme für Automatisierung
3. **Natürlichsprachige Interaktion**: Verabschieden Sie sich von komplexen Befehlen, steuern Sie KI mit alltäglicher Konversation, von der Code-Entwicklung bis zur persönlichen Assistenz
4. **Offene Plattform**: Ein-Klick-Installation von SubAgent und MCP aus dem [iFlow Open Market](https://platform.iflow.cn/), erweitern Sie schnell intelligente Agenten und bauen Sie Ihr eigenes KI-Team auf
## Funktionsvergleich
| Funktion | iFlow Cli | Claude Code | Gemini Cli |
|----------|-----------|-------------|------------|
| Todo-Planung | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| Benutzerdefinierte Befehle | ✅ | ✅ | ✅ |
| Plan-Modus | ✅ | ✅ | ❌ |
| Task-Tools | ✅ | ✅ | ❌ |
| VS Code Plugin | ✅ | ✅ | ✅ |
| JetBrains Plugin | ✅ | ✅ | ❌ |
| Gesprächswiederherstellung | ✅ | ✅ | ❌ |
| Integrierter Open Market | ✅ | ❌ | ❌ |
| Automatische Speicherkomprimierung | ✅ | ✅ | ✅ |
| Multimodale Fähigkeiten | ✅ | ⚠️ (Chinesische Modelle nicht unterstützt) | ⚠️ (Chinesische Modelle nicht unterstützt) |
| Suche | ✅ | ❌ | ⚠️ (VPN erforderlich) |
| Kostenlos | ✅ | ❌ | ⚠️ (Begrenzte Nutzung) |
| Hook | ✅ | ✅ | ❌ |
| Ausgabestil | ✅ | ✅ | ❌ |
| Denken | ✅ | ✅ | ❌ |
| Workflow | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ Wichtige Funktionen
* Unterstützung für 4 Betriebsmodi: yolo (Modell mit maximalen Berechtigungen, kann jede Operation ausführen), accepting edits (Modell nur mit Dateien-Bearbeitungsberechtigungen), plan mode (erst planen, dann ausführen), default (Modell ohne Berechtigungen)
* Verbesserte subAgent-Funktionalität. Entwickelt die CLI von einem allgemeinen Assistenten zu einem Expertenteam weiter und bietet professionellere und genauere Beratung. Verwenden Sie /agent, um mehr vorkonfigurierte Agenten zu sehen
* Verbessertes task-Tool. Effiziente Komprimierung der Kontextlänge, sodass die CLI Ihre Aufgaben tiefgreifender erledigen kann. Automatische Komprimierung wenn der Kontext 70% erreicht
* Integration mit dem iFlow Open Market. Schnelle Installation nützlicher MCP-Tools, Subagents, benutzerdefinierter Anweisungen und Workflows
* Kostenlose Nutzung multimodaler Modelle, Sie können auch Bilder in die CLI einfügen (Strg+V zum Einfügen von Bildern)
* Unterstützung für Gesprächsverlauf-Speicherung und Rollback (iflow --resume und /chat Befehle)
* Unterstützung für mehr nützliche Terminal-Befehle (iflow -h für weitere Befehle)
* VSCode Plugin-Unterstützung
* Automatisches Upgrade, iFlow CLI erkennt automatisch, ob die aktuelle Version die neueste ist
## 📥 Installation
### Systemanforderungen
- Betriebssysteme: macOS 10.15+, Ubuntu 20.04+/Debian 10+, oder Windows 10+ (mit WSL 1, WSL 2 oder Git for Windows)
- Hardware: 4GB+ RAM
- Software: Node.js 22+
- Netzwerk: Internetverbindung für Authentifizierung und KI-Verarbeitung erforderlich
- Shell: Funktioniert am besten in Bash, Zsh oder Fish
### Installationsbefehl
**MAC/Linux/Ubuntu-Nutzer**:
* Ein-Klick-Installationsbefehl (Empfohlen)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Installation mit Node.js
```shell
npm i -g @iflow-ai/iflow-cli
```
Dieser Befehl installiert automatisch alle notwendigen Abhängigkeiten für Ihr Terminal.
**Windows-Nutzer**:
1. Gehen Sie zu https://nodejs.org/en/download, um das neueste Node.js-Installationsprogramm herunterzuladen
2. Führen Sie das Installationsprogramm aus, um Node.js zu installieren
3. Starten Sie Ihr Terminal neu: CMD oder PowerShell
4. Führen Sie `npm install -g @iflow-ai/iflow-cli` aus, um iFlow CLI zu installieren
5. Führen Sie `iflow` aus, um iFlow CLI zu starten
Wenn Sie sich in Festlandchina befinden, können Sie den folgenden Befehl verwenden, um iFlow CLI zu installieren:
1. Gehen Sie zu https://cloud.iflow.cn/iflow-cli/nvm-setup.exe, um das neueste nvm-Installationsprogramm herunterzuladen
2. Führen Sie das Installationsprogramm aus, um nvm zu installieren
3. **Starten Sie Ihr Terminal neu: CMD oder PowerShell**
4. Führen Sie `nvm node_mirror https://npmmirror.com/mirrors/node/` und `nvm npm_mirror https://npmmirror.com/mirrors/npm/` aus
5. Führen Sie `nvm install 22` aus, um Node.js 22 zu installieren
6. Führen Sie `nvm use 22` aus, um Node.js 22 zu verwenden
7. Führen Sie `npm install -g @iflow-ai/iflow-cli` aus, um iFlow CLI zu installieren
8. Führen Sie `iflow` aus, um iFlow CLI zu starten
## 🗑️ Deinstallation
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 Authentifizierung
iFlow bietet zwei Authentifizierungsoptionen:
1. **Empfohlen**: Verwenden Sie iFlows native Authentifizierung
2. **Alternative**: Verbindung über OpenAI-kompatible APIs
Wählen Sie Option 1 für die direkte Anmeldung, wodurch die iFlow-Kontoauthentifizierung in einer Webseite geöffnet wird. Nach Abschluss der Authentifizierung können Sie es kostenlos nutzen.
Wenn Sie sich in einer Umgebung wie einem Server befinden, wo Sie keine Webseite öffnen können, verwenden Sie Option 2 für die Anmeldung.
So erhalten Sie Ihren API-Schlüssel:
1. Registrieren Sie sich für ein iFlow-Konto
2. Gehen Sie zu Ihren Profileinstellungen oder klicken Sie auf [diesen direkten Link](https://iflow.cn/?open=setting)
3. Klicken Sie im Pop-up-Dialog auf "Zurücksetzen", um einen neuen API-Schlüssel zu generieren
Nach der Generierung Ihres Schlüssels fügen Sie ihn in die Terminal-Eingabeaufforderung ein, um die Einrichtung abzuschließen.
## 🚀 Erste Schritte
Um iFlow CLI zu starten, navigieren Sie in Ihrem Terminal zu Ihrem Arbeitsbereich und geben Sie ein:
```shell
iflow
```
### Neue Projekte starten
Für neue Projekte beschreiben Sie einfach, was Sie erstellen möchten:
```shell
cd neues-projekt/
iflow
> Erstelle ein webbasiertes Minecraft-Spiel mit HTML
```
### Mit bestehenden Projekten arbeiten
Für bestehende Codebasen beginnen Sie mit dem `/init`-Befehl, um iFlow dabei zu helfen, Ihr Projekt zu verstehen:
```shell
cd projekt1/
iflow
> /init
> Analysiere die Anforderungen gemäß dem PRD-Dokument in der requirement.md-Datei und erstelle ein technisches Dokument, dann implementiere die Lösung.
```
Der `/init`-Befehl scannt Ihre Codebasis, lernt deren Struktur und erstellt eine IFLOW.md-Datei mit umfassender Dokumentation.
Eine vollständige Liste der Slash-Befehle und Nutzungsanweisungen finden Sie [hier](./i18/en/commands.md).
## 💡 Häufige Anwendungsfälle
iFlow CLI geht über das Programmieren hinaus und bewältigt eine Vielzahl von Aufgaben:
### 📊 Information & Planung
```text
> Hilf mir dabei, die bestbewerteten Restaurants in Los Angeles zu finden und eine 3-tägige Food-Tour-Route zu erstellen.
```
```text
> Suche nach den neuesten iPhone-Preisvergleichen und finde die kostengünstigste Kaufoption.
```
### 📁 Dateiverwaltung
```text
> Organisiere die Dateien auf meinem Desktop nach Dateityp in separate Ordner.
```
```text
> Lade alle Bilder von dieser Webseite im Batch herunter und benenne sie nach Datum um.
```
### 📈 Datenanalyse
```text
> Analysiere die Verkaufsdaten in dieser Excel-Tabelle und erstelle ein einfaches Diagramm.
```
```text
> Extrahiere Kundeninformationen aus diesen CSV-Dateien und führe sie in einer einheitlichen Tabelle zusammen.
```
### 👨💻 Entwicklungsunterstützung
```text
> Analysiere die Hauptarchitekturkomponenten und Modulabhängigkeiten dieses Systems.
```
```text
> Ich bekomme eine Null-Pointer-Exception nach meiner Anfrage, bitte hilf mir, die Ursache des Problems zu finden.
```
### ⚙️ Workflow-Automatisierung
```text
> Erstelle ein Skript, um meine wichtigen Dateien regelmäßig in den Cloud-Speicher zu sichern.
```
```text
> Schreibe ein Programm, das täglich Aktienkurse herunterlädt und mir E-Mail-Benachrichtigungen sendet.
```
*Hinweis: Erweiterte Automatisierungsaufgaben können MCP-Server nutzen, um Ihre lokalen Systemtools mit Unternehmens-Kollaborationssuiten zu integrieren.*
## 🔧 Zu einem benutzerdefinierten Modell wechseln
iFlow CLI kann sich mit jeder OpenAI-kompatiblen API verbinden. Bearbeiten Sie die Einstellungsdatei in `~/.iflow/settings.json`, um das von Ihnen verwendete Modell zu ändern.
Hier ist eine Beispiel-Einstellungsdatei:
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "ihr iflow schlüssel",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "ihr iflow schlüssel"
}
```
## 🔄 GitHub Actions
Sie können iFlow CLI auch in Ihren GitHub Actions Workflows mit der von der Community betreuten Action verwenden: [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 Community-Kommunikation
Wenn Sie bei der Nutzung auf Probleme stoßen, können Sie direkt Issues auf der GitHub-Seite erstellen.
Sie können auch den folgenden WeChat-Gruppen-QR-Code scannen, um der Community-Gruppe für Kommunikation und Diskussion beizutreten.
### WeChat-Gruppe
## /README_ES.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Deutsch](README_DE.md) | **Español** | [Русский](README_RU.md)
iFlow CLI es un potente asistente de IA que funciona directamente en tu terminal. Analiza repositorios de código de manera fluida, ejecuta tareas de programación, comprende necesidades específicas del contexto y aumenta la productividad automatizando desde operaciones simples de archivos hasta flujos de trabajo complejos.
[Más Tutoriales](https://platform.iflow.cn/)
## ✨ Características Principales
1. **Modelos de IA Gratuitos**: Accede a modelos de IA potentes y gratuitos a través de la [plataforma abierta iFlow](https://platform.iflow.cn/docs/api-mode), incluyendo Kimi K2, Qwen3 Coder, DeepSeek v3, y más
2. **Integración Flexible**: Mantén tus herramientas de desarrollo favoritas mientras integras en sistemas existentes para automatización
3. **Interacción en Lenguaje Natural**: Despídete de comandos complejos, controla la IA con conversación cotidiana, desde desarrollo de código hasta asistencia personal
4. **Plataforma Abierta**: Instalación con un clic de SubAgent y MCP desde el [mercado abierto iFlow](https://platform.iflow.cn/), expande rápidamente agentes inteligentes y construye tu propio equipo de IA
## Comparación de Características
| Característica | iFlow Cli | Claude Code | Gemini Cli |
|---------------|-----------|-------------|------------|
| Planificación Todo | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| Comandos personalizados | ✅ | ✅ | ✅ |
| Modo plan | ✅ | ✅ | ❌ |
| Herramientas de tarea | ✅ | ✅ | ❌ |
| Plugin VS Code | ✅ | ✅ | ✅ |
| Plugin JetBrains | ✅ | ✅ | ❌ |
| Recuperación de conversación | ✅ | ✅ | ❌ |
| Mercado abierto integrado | ✅ | ❌ | ❌ |
| Compresión automática de memoria | ✅ | ✅ | ✅ |
| Capacidad multimodal | ✅ | ⚠️ (Modelos chinos no soportados) | ⚠️ (Modelos chinos no soportados) |
| Búsqueda | ✅ | ❌ | ⚠️ (VPN requerido) |
| Gratuito | ✅ | ❌ | ⚠️ (Uso limitado) |
| Hook | ✅ | ✅ | ❌ |
| Estilo de salida | ✅ | ✅ | ❌ |
| Pensamiento | ✅ | ✅ | ❌ |
| Flujo de trabajo | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ Características Clave
* Soporte para 4 modos de funcionamiento: yolo (modelo con máximos permisos, puede ejecutar cualquier operación), accepting edits (modelo solo con permisos de edición de archivos), plan mode (planificar primero luego ejecutar), default (modelo sin permisos)
* Funcionalidad subAgent mejorada. Evoluciona la CLI de un asistente generalista a un equipo de expertos, proporcionándote consejos más profesionales y precisos. Usa /agent para ver más agentes preconfigurados
* Herramienta task mejorada. Compresión eficiente de la longitud del contexto, permitiendo que la CLI complete tus tareas más profundamente. Compresión automática cuando el contexto alcanza el 70%
* Integración con el mercado abierto iFlow. Instalación rápida de herramientas MCP útiles, Subagents, instrucciones personalizadas y flujos de trabajo
* Uso gratuito de modelos multimodales, también puedes pegar imágenes en la CLI (Ctrl+V para pegar imágenes)
* Soporte para guardado y retroceso del historial de conversaciones (comandos iflow --resume y /chat)
* Soporte para más comandos de terminal útiles (iflow -h para ver más comandos)
* Soporte para plugin de VSCode
* Actualización automática, iFlow CLI detecta automáticamente si la versión actual es la más reciente
## 📥 Instalación
### Requisitos del Sistema
- Sistemas Operativos: macOS 10.15+, Ubuntu 20.04+/Debian 10+, o Windows 10+ (con WSL 1, WSL 2, o Git for Windows)
- Hardware: 4GB+ de RAM
- Software: Node.js 22+
- Red: Conexión a Internet requerida para autenticación y procesamiento de IA
- Shell: Funciona mejor en Bash, Zsh o Fish
### Comando de instalación
**Usuarios de MAC/Linux/Ubuntu**:
* Comando de instalación con un clic (Recomendado)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Instalación con Node.js
```shell
npm i -g @iflow-ai/iflow-cli
```
Este comando instala automáticamente todas las dependencias necesarias para tu terminal.
**Usuarios de Windows**:
1. Ve a https://nodejs.org/es/download para descargar el instalador de Node.js más reciente
2. Ejecuta el instalador para instalar Node.js
3. Reinicia tu terminal: CMD o PowerShell
4. Ejecuta `npm install -g @iflow-ai/iflow-cli` para instalar iFlow CLI
5. Ejecuta `iflow` para iniciar iFlow CLI
Si estás en China continental, puedes usar el siguiente comando para instalar iFlow CLI:
1. Ve a https://cloud.iflow.cn/iflow-cli/nvm-setup.exe para descargar el instalador de nvm más reciente
2. Ejecuta el instalador para instalar nvm
3. **Reinicia tu terminal: CMD o PowerShell**
4. Ejecuta `nvm node_mirror https://npmmirror.com/mirrors/node/` y `nvm npm_mirror https://npmmirror.com/mirrors/npm/`
5. Ejecuta `nvm install 22` para instalar Node.js 22
6. Ejecuta `nvm use 22` para usar Node.js 22
7. Ejecuta `npm install -g @iflow-ai/iflow-cli` para instalar iFlow CLI
8. Ejecuta `iflow` para iniciar iFlow CLI
## 🗑️ Desinstalación
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 Autenticación
iFlow ofrece dos opciones de autenticación:
1. **Recomendado**: Usar la autenticación nativa de iFlow
2. **Alternativa**: Conectar a través de APIs compatibles con OpenAI
Elige la opción 1 para iniciar sesión directamente, lo que abrirá la autenticación de cuenta iFlow en una página web. Después de completar la autenticación, puedes usarlo gratis.
Si estás en un entorno como un servidor donde no puedes abrir una página web, usa la opción 2 para iniciar sesión.
Para obtener tu clave API:
1. Regístrate para una cuenta de iFlow
2. Ve a la configuración de tu perfil o haz clic en [este enlace directo](https://iflow.cn/?open=setting)
3. Haz clic en "Reset" en el diálogo emergente para generar una nueva clave API
Después de generar tu clave, pégala en el prompt del terminal para completar la configuración.
## 🚀 Primeros Pasos
Para iniciar iFlow CLI, navega a tu espacio de trabajo en el terminal y escribe:
```shell
iflow
```
### Iniciando Nuevos Proyectos
Para proyectos nuevos, simplemente describe lo que quieres crear:
```shell
cd nuevo-proyecto/
iflow
> Crea un juego de Minecraft basado en web usando HTML
```
### Trabajando con Proyectos Existentes
Para bases de código existentes, comienza con el comando `/init` para ayudar a iFlow a entender tu proyecto:
```shell
cd proyecto1/
iflow
> /init
> Analiza los requisitos según el documento PRD en el archivo requirement.md, genera un documento técnico y luego implementa la solución.
```
El comando `/init` escanea tu base de código, aprende su estructura y crea un archivo IFLOW.md con documentación completa.
Para una lista completa de comandos slash e instrucciones de uso, consulta [aquí](./i18/en/commands.md).
## 💡 Casos de Uso Comunes
iFlow CLI va más allá de la programación para manejar una amplia gama de tareas:
### 📊 Información y Planificación
```text
> Ayúdame a encontrar los restaurantes mejor valorados en Los Ángeles y crea un itinerario gastronómico de 3 días.
```
```text
> Busca las últimas comparaciones de precios del iPhone y encuentra la opción de compra más rentable.
```
### 📁 Gestión de Archivos
```text
> Organiza los archivos de mi escritorio por tipo de archivo en carpetas separadas.
```
```text
> Descarga por lotes todas las imágenes de esta página web y renómbralas por fecha.
```
### 📈 Análisis de Datos
```text
> Analiza los datos de ventas en esta hoja de cálculo de Excel y genera un gráfico simple.
```
```text
> Extrae información de clientes de estos archivos CSV y combínalos en una tabla unificada.
```
### 👨💻 Soporte de Desarrollo
```text
> Analiza los componentes arquitectónicos principales y las dependencias de módulos de este sistema.
```
```text
> Estoy obteniendo una excepción de puntero nulo después de mi solicitud, por favor ayúdame a encontrar la causa del problema.
```
### ⚙️ Automatización de Flujos de Trabajo
```text
> Crea un script para hacer copias de seguridad periódicas de mis archivos importantes al almacenamiento en la nube.
```
```text
> Escribe un programa que descargue precios de acciones diariamente y me envíe notificaciones por email.
```
*Nota: Las tareas de automatización avanzadas pueden aprovechar los servidores MCP para integrar las herramientas de tu sistema local con suites de colaboración empresarial.*
## 🔧 Cambiar a modelo personalizado
iFlow CLI puede conectarse a cualquier API compatible con OpenAI. Edita el archivo de configuración en `~/.iflow/settings.json` para cambiar el modelo que usas.
Aquí tienes un archivo de configuración de ejemplo:
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "tu clave de iflow",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "tu clave de iflow"
}
```
## 🔄 GitHub Actions
También puedes usar iFlow CLI en tus flujos de trabajo de GitHub Actions con la acción mantenida por la comunidad: [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 Comunicación de la Comunidad
Si encuentras problemas durante el uso, puedes crear Issues directamente en la página de GitHub.
También puedes escanear el siguiente código QR del grupo de WeChat para unirte al grupo de la comunidad para comunicación y discusión.
### Grupo de WeChat
## /README_FR.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | **Français** | [Deutsch](README_DE.md) | [Español](README_ES.md) | [Русский](README_RU.md)
iFlow CLI est un assistant IA puissant qui s'exécute directement dans votre terminal. Il analyse de manière transparente les dépôts de code, exécute des tâches de programmation, comprend les besoins spécifiques au contexte et améliore la productivité en automatisant tout, des opérations simples sur les fichiers aux flux de travail complexes.
[Plus de Tutoriels](https://platform.iflow.cn/)
## ✨ Fonctionnalités principales
1. **Modèles IA gratuits** : Accédez à des modèles IA puissants et gratuits via la [plateforme ouverte iFlow](https://platform.iflow.cn/docs/api-mode), incluant Kimi K2, Qwen3 Coder, DeepSeek v3, et bien d'autres
2. **Intégration flexible** : Gardez vos outils de développement préférés tout en intégrant dans les systèmes existants pour l'automatisation
3. **Interaction en langage naturel** : Dites adieu aux commandes complexes, pilotez l'IA avec une conversation quotidienne, du développement de code à l'assistance personnelle
4. **Plateforme ouverte** : Installation en un clic de SubAgent et MCP depuis le [marché ouvert iFlow](https://platform.iflow.cn/), étendez rapidement les agents intelligents et construisez votre propre équipe IA
## Comparaison des fonctionnalités
| Fonctionnalité | iFlow Cli | Claude Code | Gemini Cli |
|----------------|-----------|-------------|------------|
| Planification Todo | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| Commandes personnalisées | ✅ | ✅ | ✅ |
| Mode plan | ✅ | ✅ | ❌ |
| Outils de tâche | ✅ | ✅ | ❌ |
| Plugin VS Code | ✅ | ✅ | ✅ |
| Plugin JetBrains | ✅ | ✅ | ❌ |
| Récupération de conversation | ✅ | ✅ | ❌ |
| Marché ouvert intégré | ✅ | ❌ | ❌ |
| Compression mémoire automatique | ✅ | ✅ | ✅ |
| Capacité multimodale | ✅ | ⚠️ (Modèles chinois non supportés) | ⚠️ (Modèles chinois non supportés) |
| Recherche | ✅ | ❌ | ⚠️ (VPN requis) |
| Gratuit | ✅ | ❌ | ⚠️ (Usage limité) |
| Hook | ✅ | ✅ | ❌ |
| Style de sortie | ✅ | ✅ | ❌ |
| Réflexion | ✅ | ✅ | ❌ |
| Flux de travail | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ Fonctionnalités clés
* Support de 4 modes de fonctionnement : yolo (modèle avec permissions maximales, peut exécuter n'importe quelle opération), accepting edits (modèle avec permissions de modification de fichiers uniquement), plan mode (planifier d'abord puis exécuter), default (modèle sans aucune permission)
* Fonctionnalité subAgent améliorée. Fait évoluer le CLI d'un assistant généraliste vers une équipe d'experts, vous fournissant des conseils plus professionnels et précis. Utilisez /agent pour voir plus d'agents préconfigurés
* Outil task amélioré. Compression efficace de la longueur du contexte, permettant au CLI d'accomplir vos tâches plus en profondeur. Compression automatique quand le contexte atteint 70%
* Intégration avec le marché ouvert iFlow. Installation rapide d'outils MCP utiles, de Subagents, d'instructions personnalisées et de flux de travail
* Utilisation gratuite de modèles multimodaux, vous pouvez également coller des images dans le CLI (Ctrl+V pour coller des images)
* Support de la sauvegarde et du retour en arrière de l'historique des conversations (commandes iflow --resume et /chat)
* Support de plus de commandes de terminal utiles (iflow -h pour voir plus de commandes)
* Support du plugin VSCode
* Mise à niveau automatique, iFlow CLI détecte automatiquement si la version actuelle est la plus récente
## 📥 Installation
### Configuration système requise
- Systèmes d'exploitation : macOS 10.15+, Ubuntu 20.04+/Debian 10+, ou Windows 10+ (avec WSL 1, WSL 2, ou Git for Windows)
- Matériel : 4GB+ de RAM
- Logiciel : Node.js 22+
- Réseau : Connexion Internet requise pour l'authentification et le traitement IA
- Shell : Fonctionne mieux avec Bash, Zsh ou Fish
### Commande d'installation
**Utilisateurs MAC/Linux/Ubuntu** :
* Commande d'installation en un clic (Recommandée)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Installation avec Node.js
```shell
npm i -g @iflow-ai/iflow-cli
```
Cette commande installe automatiquement toutes les dépendances nécessaires pour votre terminal.
**Utilisateurs Windows**:
1. Allez sur https://nodejs.org/fr/download pour télécharger le dernier installateur Node.js
2. Exécutez l'installateur pour installer Node.js
3. Redémarrez votre terminal : CMD ou PowerShell
4. Exécutez `npm install -g @iflow-ai/iflow-cli` pour installer iFlow CLI
5. Exécutez `iflow` pour démarrer iFlow CLI
Si vous êtes en Chine continentale, vous pouvez utiliser la commande suivante pour installer iFlow CLI :
1. Allez sur https://cloud.iflow.cn/iflow-cli/nvm-setup.exe pour télécharger le dernier installateur nvm
2. Exécutez l'installateur pour installer nvm
3. **Redémarrez votre terminal : CMD ou PowerShell**
4. Exécutez `nvm node_mirror https://npmmirror.com/mirrors/node/` et `nvm npm_mirror https://npmmirror.com/mirrors/npm/`
5. Exécutez `nvm install 22` pour installer Node.js 22
6. Exécutez `nvm use 22` pour utiliser Node.js 22
7. Exécutez `npm install -g @iflow-ai/iflow-cli` pour installer iFlow CLI
8. Exécutez `iflow` pour démarrer iFlow CLI
## 🗑️ Désinstallation
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 Authentification
iFlow propose deux options d'authentification :
1. **Recommandé** : Utiliser l'authentification native d'iFlow
2. **Alternative** : Se connecter via des API compatibles OpenAI
Choisissez l'option 1 pour vous connecter directement, ce qui ouvrira l'authentification du compte iFlow dans une page web. Après avoir terminé l'authentification, vous pouvez l'utiliser gratuitement.
Si vous êtes dans un environnement comme un serveur où vous ne pouvez pas ouvrir une page web, utilisez l'option 2 pour vous connecter.
Pour obtenir votre clé API :
1. Créez un compte iFlow
2. Allez dans les paramètres de votre profil ou cliquez sur [ce lien direct](https://iflow.cn/?open=setting)
3. Cliquez sur "Reset" dans la boîte de dialogue pour générer une nouvelle clé API
Après avoir généré votre clé, collez-la dans l'invite du terminal pour terminer la configuration.
## 🚀 Prise en main
Pour lancer iFlow CLI, naviguez vers votre espace de travail dans le terminal et tapez :
```shell
iflow
```
### Démarrer de nouveaux projets
Pour de nouveaux projets, décrivez simplement ce que vous voulez créer :
```shell
cd nouveau-projet/
iflow
> Créer un jeu Minecraft basé sur le web en utilisant HTML
```
### Travailler avec des projets existants
Pour des bases de code existantes, commencez par la commande `/init` pour aider iFlow à comprendre votre projet :
```shell
cd projet1/
iflow
> /init
> Analyser les exigences selon le document PRD dans le fichier requirement.md, et produire un document technique, puis implémenter la solution.
```
La commande `/init` scanne votre base de code, apprend sa structure et crée un fichier IFLOW.md avec une documentation complète.
Pour une liste complète des commandes slash et des instructions d'utilisation, voir [ici](./i18/en/commands.md).
## 💡 Cas d'usage courants
iFlow CLI va au-delà du codage pour gérer une large gamme de tâches :
### 📊 Information et planification
```text
> Aide-moi à trouver les restaurants les mieux notés à Los Angeles et créer un itinéraire de tour gastronomique de 3 jours.
```
```text
> Rechercher les dernières comparaisons de prix d'iPhone et trouver l'option d'achat la plus rentable.
```
### 📁 Gestion de fichiers
```text
> Organiser les fichiers de mon bureau par type de fichier dans des dossiers séparés.
```
```text
> Télécharger en lot toutes les images de cette page web et les renommer par date.
```
### 📈 Analyse de données
```text
> Analyser les données de vente dans cette feuille de calcul Excel et générer un graphique simple.
```
```text
> Extraire les informations client de ces fichiers CSV et les fusionner dans un tableau unifié.
```
### 👨💻 Support de développement
```text
> Analyser les principaux composants architecturaux et les dépendances de modules de ce système.
```
```text
> J'obtiens une exception de pointeur null après ma requête, aide-moi à trouver la cause du problème.
```
### ⚙️ Automatisation de flux de travail
```text
> Créer un script pour sauvegarder périodiquement mes fichiers importants vers le stockage cloud.
```
```text
> Écrire un programme qui télécharge les prix des actions quotidiennement et m'envoie des notifications par email.
```
*Note : Les tâches d'automatisation avancées peuvent exploiter les serveurs MCP pour intégrer vos outils système locaux avec les suites de collaboration d'entreprise.*
## 🔧 Basculer vers un modèle personnalisé
iFlow CLI peut se connecter à n'importe quelle API compatible OpenAI. Modifiez le fichier de paramètres dans `~/.iflow/settings.json` pour changer le modèle que vous utilisez.
Voici un exemple de fichier de paramètres :
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "votre clé iflow",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "votre clé iflow"
}
```
## 🔄 GitHub Actions
Vous pouvez également utiliser iFlow CLI dans vos workflows GitHub Actions avec l'action maintenue par la communauté : [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 Communication Communautaire
Si vous rencontrez des problèmes lors de l'utilisation, vous pouvez directement créer des Issues sur la page GitHub.
Vous pouvez également scanner le code QR du groupe WeChat suivant pour rejoindre le groupe communautaire pour la communication et la discussion.
### Groupe WeChat
## /README_JA.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | [中文](README_CN.md) | **日本語** | [한국어](README_KO.md) | [Français](README_FR.md) | [Deutsch](README_DE.md) | [Español](README_ES.md) | [Русский](README_RU.md)
iFlow CLIは、ターミナル上で直接動作する強力なAIアシスタントです。コードリポジトリの分析、コーディングタスクの実行、コンテキストに応じたニーズの理解を行い、シンプルなファイル操作から複雑なワークフローまでを自動化することで生産性を大幅に向上させます。
[その他のチュートリアル](https://platform.iflow.cn/)
## ✨ 主な機能
1. **無料のAIモデル**: [iFlowオープンプラットフォーム](https://platform.iflow.cn/docs/api-mode)を通じて、Kimi K2、Qwen3 Coder、DeepSeek v3などの強力で無料のAIモデルにアクセス可能
2. **柔軟な統合**: お気に入りの開発ツールを維持しながら、既存システムに統合して自動化を実現
3. **自然言語インタラクション**: 複雑なコマンドとはおさらば、日常会話でAIを駆動し、コード開発から日常のアシスタントまで対応
4. **オープンプラットフォーム**: [iFlowオープンマーケット](https://platform.iflow.cn/)からSubAgentとMCPをワンクリックでインストール、インテリジェントエージェントを素早く拡張し、あなただけのAIチームを構築
## 機能対比
| 機能 | iFlow Cli | Claude Code | Gemini Cli |
|------|-----------|-------------|------------|
| Todo計画 | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| カスタムコマンド | ✅ | ✅ | ✅ |
| プランモード | ✅ | ✅ | ❌ |
| タスクツール | ✅ | ✅ | ❌ |
| VS Code プラグイン | ✅ | ✅ | ✅ |
| JetBrains プラグイン | ✅ | ✅ | ❌ |
| 会話復元 | ✅ | ✅ | ❌ |
| 内蔵オープンマーケット | ✅ | ❌ | ❌ |
| メモリ自動圧縮 | ✅ | ✅ | ✅ |
| マルチモーダル機能 | ✅ | ⚠️（中国国内モデル非対応） | ⚠️（中国国内モデル非対応） |
| 検索 | ✅ | ❌ | ⚠️（VPN必要） |
| 無料 | ✅ | ❌ | ⚠️（使用制限あり） |
| Hook | ✅ | ✅ | ❌ |
| 出力スタイル | ✅ | ✅ | ❌ |
| 思考 | ✅ | ✅ | ❌ |
| ワークフロー | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ 重要機能
* 4つの実行モードをサポート：yolo（モデルに最大権限、すべての操作を実行可能）、accepting edits（モデルにファイル変更権限のみ）、plan mode（計画してから実行）、default（モデルに権限なし）
* subAgent機能のアップグレード：CLIを汎用アシスタントから専門チームに進化させ、より専門的で正確なアドバイスを提供。/agentでより多くの事前設定されたエージェントを確認
* taskツールのアップグレード：コンテキスト長を効果的に圧縮し、CLIがより深くタスクを完了できるように。コンテキストが70%に達すると自動圧縮
* iFlowオープンマーケットとの統合：便利なMCPツール、Subagent、カスタム指示、ワークフローを迅速にインストール
* 無料マルチモーダルモデル使用：CLIで画像も貼り付け可能（Ctrl+Vで画像貼り付け）
* 会話履歴保存・ロールバック機能（iflow --resumeと/chatコマンド）
* より便利なターミナルコマンドをサポート（iflow -hでより多くのコマンドを確認）
* VSCodeプラグインサポート
* 自動アップグレード：iFlow CLIが現在のバージョンが最新かを自動検出
## 📥 インストール
### システム要件
- オペレーティングシステム: macOS 10.15+、Ubuntu 20.04+/Debian 10+、またはWindows 10+（WSL 1、WSL 2、またはGit for Windows）
- ハードウェア: 4GB以上のRAM
- ソフトウェア: Node.js 22+
- ネットワーク: 認証とAI処理のためにインターネット接続が必要
- シェル: Bash、Zsh、またはFishで最適に動作
### インストールコマンド
**MAC/Linux/Ubuntuユーザー**:
* ワンクリックインストールコマンド（推奨）
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Node.jsを使用したインストール
```shell
npm i -g @iflow-ai/iflow-cli
```
このコマンドにより、ターミナルに必要な依存関係がすべて自動的にインストールされます。
**Windowsユーザーの方へ**:
1. https://nodejs.org/ja/download にアクセスして最新のNode.jsインストーラーをダウンロードしてください
2. インストーラーを実行してNode.jsをインストールしてください
3. ターミナルを再起動してください：CMDまたはPowerShell
4. `npm install -g @iflow-ai/iflow-cli` を実行してiFlow CLIをインストールしてください
5. `iflow` を実行してiFlow CLIを開始してください
中国本土の場合は、以下のコマンドでiFlow CLIをインストールできます：
1. https://cloud.iflow.cn/iflow-cli/nvm-setup.exe にアクセスして最新のnvmインストーラーをダウンロードしてください
2. インストーラーを実行してnvmをインストールしてください
3. **ターミナルを再起動してください：CMDまたはPowerShell**
4. `nvm node_mirror https://npmmirror.com/mirrors/node/` と `nvm npm_mirror https://npmmirror.com/mirrors/npm/` を実行してください
5. `nvm install 22` を実行してNode.js 22をインストールしてください
6. `nvm use 22` を実行してNode.js 22を使用してください
7. `npm install -g @iflow-ai/iflow-cli` を実行してiFlow CLIをインストールしてください
8. `iflow` を実行してiFlow CLIを開始してください
## 🗑️ アンインストール
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 認証
iFlowでは2つの認証オプションを提供しています：
1. **推奨**: iFlowのネイティブ認証を使用
2. **代替手段**: OpenAI互換APIを通じて接続
オプション1を選択して直接ログインすると、WebページでiFlowアカウント認証が開きます。認証完了後、無料でご利用いただけます。
サーバーなどWebページを開けない環境をご利用の場合は、オプション2でログインしてください。
APIキーを取得するには：
1. iFlowアカウントに登録
2. プロフィール設定に移動するか、[こちらの直接リンク](https://iflow.cn/?open=setting)をクリック
3. ポップアップダイアログで「リセット」をクリックして新しいAPIキーを生成
キーを生成後、ターミナルのプロンプトに貼り付けてセットアップを完了してください。
## 🚀 使い始める
iFlow CLIを起動するには、ターミナルでワークスペースに移動し、以下を入力します：
```shell
iflow
```
### 新しいプロジェクトの開始
新しいプロジェクトの場合は、作成したいものを簡潔に説明してください：
```shell
cd new-project/
iflow
> HTMLを使ってWebベースのMinecraftゲームを作成して
```
### 既存プロジェクトでの作業
既存のコードベースの場合は、`/init`コマンドから始めて、iFlowにプロジェクトを理解させましょう：
```shell
cd project1/
iflow
> /init
> requirement.mdファイルのPRD文書に従って要件を分析し、技術文書を出力してから、ソリューションを実装してください。
```
`/init`コマンドはコードベースをスキャンし、その構造を学習して、包括的なドキュメントを含むIFLOW.mdファイルを作成します。
スラッシュコマンドの完全なリストと使用方法については、[こちら](./i18/en/commands.md)をご覧ください。
## 💡 一般的な使用例
iFlow CLIはコーディングを超えて、幅広いタスクに対応します：
### 📊 情報収集・計画立案
```text
> ロサンゼルスで最も評価の高いレストランを見つけて、3日間のグルメツアーの行程表を作成してください。
```
```text
> 最新のiPhone価格比較を検索して、最もコストパフォーマンスの良い購入オプションを見つけてください。
```
### 📁 ファイル管理
```text
> デスクトップのファイルをファイルタイプ別に整理して、別々のフォルダに分けてください。
```
```text
> このWebページからすべての画像を一括ダウンロードして、日付順にリネームしてください。
```
### 📈 データ分析
```text
> このExcelスプレッドシートの売上データを分析して、シンプルなグラフを生成してください。
```
```text
> これらのCSVファイルから顧客情報を抽出して、統一されたテーブルにマージしてください。
```
### 👨💻 開発サポート
```text
> このシステムの主要なアーキテクチャコンポーネントとモジュール依存関係を分析してください。
```
```text
> リクエスト後にnull pointer exceptionが発生しています。問題の原因を見つけるのを手伝ってください。
```
### ⚙️ ワークフロー自動化
```text
> 重要なファイルを定期的にクラウドストレージにバックアップするスクリプトを作成してください。
```
```text
> 毎日株価をダウンロードして、メール通知を送信するプログラムを書いてください。
```
*注意: 高度な自動化タスクでは、MCPサーバーを活用してローカルシステムツールとエンタープライズコラボレーションスイートを統合できます。*
## 🔧 カスタムモデルへの切り替え
iFlow CLIは任意のOpenAI互換APIに接続できます。使用するモデルを変更するには、`~/.iflow/settings.json`の設定ファイルを編集してください。
設定ファイルのサンプル：
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "あなたのiflowキー",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "あなたのiflowキー"
}
```
## 🔄 GitHub Actions
GitHub ActionsのワークフローでもiFlow CLIをコミュニティがメンテナンスするアクションで使用できます: [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 コミュニティコミュニケーション
使用中に問題が発生した場合は、GitHubページで直接Issuesを作成してください。
また、以下のWeChatグループQRコードをスキャンして、コミュニケーションや議論のためのコミュニティグループに参加することもできます。
### WeChatグループ
## /README_KO.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md) | **한국어** | [Français](README_FR.md) | [Deutsch](README_DE.md) | [Español](README_ES.md) | [Русский](README_RU.md)
iFlow CLI는 터미널에서 직접 실행되는 강력한 AI 어시스턴트입니다. 코드 저장소를 원활하게 분석하고, 코딩 작업을 수행하며, 상황별 요구사항을 이해하고, 간단한 파일 작업부터 복잡한 워크플로우까지 모든 것을 자동화하여 생산성을 향상시킵니다.
[더 많은 튜토리얼](https://platform.iflow.cn/)
## ✨ 주요 기능
1. **무료 AI 모델**: [iFlow 오픈 플랫폼](https://platform.iflow.cn/docs/api-mode)을 통해 Kimi K2, Qwen3 Coder, DeepSeek v3 등 강력하고 무료인 AI 모델에 액세스
2. **유연한 통합**: 좋아하는 개발 도구를 유지하면서 기존 시스템에 통합하여 자동화 구현
3. **자연어 상호작용**: 복잡한 명령어와 작별하고, 일상 대화로 AI를 구동하여 코드 개발부터 생활 어시스턴트까지
4. **오픈 플랫폼**: [iFlow 오픈 마켓](https://platform.iflow.cn/)에서 SubAgent와 MCP를 원클릭으로 설치, 지능형 에이전트를 빠르게 확장하여 나만의 AI 팀 구축
## 기능 비교
| 기능 | iFlow Cli | Claude Code | Gemini Cli |
|------|-----------|-------------|------------|
| Todo 계획 | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| 사용자 정의 명령어 | ✅ | ✅ | ✅ |
| 계획 모드 | ✅ | ✅ | ❌ |
| 작업 도구 | ✅ | ✅ | ❌ |
| VS Code 플러그인 | ✅ | ✅ | ✅ |
| JetBrains 플러그인 | ✅ | ✅ | ❌ |
| 대화 복원 | ✅ | ✅ | ❌ |
| 내장 오픈 마켓 | ✅ | ❌ | ❌ |
| 메모리 자동 압축 | ✅ | ✅ | ✅ |
| 멀티모달 기능 | ✅ | ⚠️ (중국 내 모델 미지원) | ⚠️ (중국 내 모델 미지원) |
| 검색 | ✅ | ❌ | ⚠️ (VPN 필요) |
| 무료 | ✅ | ❌ | ⚠️ (사용 제한) |
| Hook | ✅ | ✅ | ❌ |
| 출력 스타일 | ✅ | ✅ | ❌ |
| 사고 | ✅ | ✅ | ❌ |
| 워크플로우 | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ 주요 기능
* 4가지 실행 모드 지원: yolo(모델에 최대 권한, 모든 작업 수행 가능), accepting edits(모델에 파일 수정 권한만), plan mode(계획 먼저, 실행 나중), default(모델에 권한 없음)
* subAgent 기능 업그레이드: CLI를 일반 어시스턴트에서 전문가 팀으로 진화시켜 보다 전문적이고 정확한 조언 제공. /agent로 더 많은 사전 구성된 에이전트 확인
* task 도구 업그레이드: 컨텍스트 길이를 효과적으로 압축하여 CLI가 작업을 더 깊이 완료할 수 있도록 함. 컨텍스트가 70%에 달하면 자동 압축
* iFlow 오픈 마켓 통합: 유용한 MCP 도구, Subagent, 커스텀 명령어 및 워크플로우를 빠르게 설치
* 무료 멀티모달 모델 사용: CLI에서 이미지도 붙여넣기 가능 (Ctrl+V로 이미지 붙여넣기)
* 대화 기록 저장 및 롤백 지원 (iflow --resume 및 /chat 명령어)
* 더 많은 유용한 터미널 명령어 지원 (iflow -h로 더 많은 명령어 확인)
* VSCode 플러그인 지원
* 자동 업그레이드: iFlow CLI가 현재 버전이 최신인지 자동 감지
## 📥 설치
### 시스템 요구사항
- 운영 체제: macOS 10.15+, Ubuntu 20.04+/Debian 10+, 또는 Windows 10+ (WSL 1, WSL 2, 또는 Git for Windows 사용)
- 하드웨어: 4GB+ RAM
- 소프트웨어: Node.js 22+
- 네트워크: 인증 및 AI 처리를 위한 인터넷 연결 필요
- 셸: Bash, Zsh 또는 Fish에서 최적으로 작동
### 설치 명령어
**MAC/Linux/Ubuntu 사용자**:
* 원클릭 설치 명령어 (권장)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Node.js를 사용한 설치
```shell
npm i -g @iflow-ai/iflow-cli
```
이 명령어는 터미널에 필요한 모든 종속성을 자동으로 설치합니다.
**Windows 사용자**:
1. https://nodejs.org/ko/download 로 이동하여 최신 Node.js 설치 프로그램을 다운로드하세요
2. 설치 프로그램을 실행하여 Node.js를 설치하세요
3. 터미널을 다시 시작하세요: CMD 또는 PowerShell
4. `npm install -g @iflow-ai/iflow-cli`를 실행하여 iFlow CLI를 설치하세요
5. `iflow` 를 실행하여 iFlow CLI를 시작하세요
중국 본토에 계신 경우 다음 명령어를 사용하여 iFlow CLI를 설치할 수 있습니다:
1. https://cloud.iflow.cn/iflow-cli/nvm-setup.exe 로 이동하여 최신 nvm 설치 프로그램을 다운로드하세요
2. 설치 프로그램을 실행하여 nvm을 설치하세요
3. **터미널을 다시 시작하세요: CMD 또는 PowerShell**
4. `nvm node_mirror https://npmmirror.com/mirrors/node/` 와 `nvm npm_mirror https://npmmirror.com/mirrors/npm/`를 실행하세요
5. `nvm install 22`를 실행하여 Node.js 22를 설치하세요
6. `nvm use 22`를 실행하여 Node.js 22를 사용하세요
7. `npm install -g @iflow-ai/iflow-cli`를 실행하여 iFlow CLI를 설치하세요
8. `iflow`를 실행하여 iFlow CLI를 시작하세요
## 🗑️ 제거
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 인증
iFlow는 두 가지 인증 옵션을 제공합니다:
1. **권장**: iFlow의 기본 인증 사용
2. **대안**: OpenAI 호환 API를 통한 연결
옵션 1을 선택하여 직접 로그인하면 웹페이지에서 iFlow 계정 인증이 열립니다. 인증 완료 후 무료로 사용할 수 있습니다.
서버와 같이 웹페이지를 열 수 없는 환경에서는 옵션 2를 사용하여 로그인하세요.
API 키를 얻으려면:
1. iFlow 계정에 가입
2. 프로필 설정으로 이동하거나 [이 직접 링크](https://iflow.cn/?open=setting)를 클릭
3. 팝업 대화상자에서 "재설정"을 클릭하여 새 API 키 생성
키를 생성한 후 터미널 프롬프트에 붙여넣어 설정을 완료하세요.
## 🚀 시작하기
iFlow CLI를 실행하려면 터미널에서 작업 공간으로 이동한 후 다음을 입력하세요:
```shell
iflow
```
### 새 프로젝트 시작
새 프로젝트의 경우 만들고자 하는 것을 간단히 설명하세요:
```shell
cd new-project/
iflow
> HTML을 사용하여 웹 기반 마인크래프트 게임 만들기
```
### 기존 프로젝트 작업
기존 코드베이스의 경우 `/init` 명령어로 시작하여 iFlow가 프로젝트를 이해할 수 있도록 도와주세요:
```shell
cd project1/
iflow
> /init
> requirement.md 파일의 PRD 문서에 따라 요구사항을 분석하고 기술 문서를 출력한 다음 솔루션을 구현하세요.
```
`/init` 명령어는 코드베이스를 스캔하고, 구조를 학습하며, 포괄적인 문서가 포함된 IFLOW.md 파일을 생성합니다.
슬래시 명령어의 전체 목록과 사용 지침은 [여기](./i18/en/commands.md)를 참조하세요.
## 💡 일반적인 사용 사례
iFlow CLI는 코딩을 넘어 다양한 작업을 처리할 수 있습니다:
### 📊 정보 및 계획
```text
> 로스앤젤레스에서 평점이 가장 높은 레스토랑을 찾아서 3일간의 음식 투어 일정을 만들어 주세요.
```
```text
> 최신 아이폰 가격 비교를 검색하고 가장 비용 효율적인 구매 옵션을 찾아주세요.
```
### 📁 파일 관리
```text
> 바탕화면의 파일들을 파일 유형별로 별도 폴더에 정리해 주세요.
```
```text
> 이 웹페이지의 모든 이미지를 일괄 다운로드하고 날짜별로 이름을 변경해 주세요.
```
### 📈 데이터 분석
```text
> 이 Excel 스프레드시트의 판매 데이터를 분석하고 간단한 차트를 생성해 주세요.
```
```text
> 이 CSV 파일들에서 고객 정보를 추출하고 통합 테이블로 병합해 주세요.
```
### 👨💻 개발 지원
```text
> 이 시스템의 주요 아키텍처 구성 요소와 모듈 종속성을 분석해 주세요.
```
```text
> 요청 후 null pointer exception이 발생하고 있습니다. 문제의 원인을 찾아주세요.
```
### ⚙️ 워크플로우 자동화
```text
> 중요한 파일들을 클라우드 스토리지에 주기적으로 백업하는 스크립트를 만들어 주세요.
```
```text
> 매일 주식 가격을 다운로드하고 이메일 알림을 보내는 프로그램을 작성해 주세요.
```
*참고: 고급 자동화 작업은 MCP 서버를 활용하여 로컬 시스템 도구를 엔터프라이즈 협업 도구와 통합할 수 있습니다.*
## 🔧 사용자 정의 모델로 전환
iFlow CLI는 OpenAI 호환 API에 연결할 수 있습니다. `~/.iflow/settings.json`의 설정 파일을 편집하여 사용하는 모델을 변경하세요.
다음은 설정 데모 파일입니다:
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "your iflow key",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "your iflow key"
}
```
## 🔄 GitHub Actions
GitHub Actions 워크플로우에서도 iFlow CLI를 커뮤니티가 유지보수하는 액션으로 사용할 수 있습니다: [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 커뮤니티 소통
사용 중 문제가 발생하면 GitHub 페이지에서 직접 이슈를 생성할 수 있습니다.
다음 WeChat 그룹 QR 코드를 스캔하여 커뮤니케이션과 토론을 위한 커뮤니티 그룹에 참여할 수도 있습니다.
### WeChat 그룹
## /README_RU.md
# 🤖 iFlow CLI
[](https://github.com/Piebald-AI/awesome-gemini-cli)
[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Deutsch](README_DE.md) | [Español](README_ES.md) | **Русский**
iFlow CLI — это мощный ИИ-ассистент, который работает прямо в вашем терминале. Он легко анализирует репозитории кода, выполняет задачи программирования, понимает контекстные потребности и повышает продуктивность, автоматизируя всё — от простых операций с файлами до сложных рабочих процессов.
[Больше Руководств](https://platform.iflow.cn/)
## ✨ Ключевые особенности
1. **Бесплатные ИИ-модели**: Доступ к мощным и бесплатным ИИ-моделям через [открытую платформу iFlow](https://platform.iflow.cn/docs/api-mode), включая Kimi K2, Qwen3 Coder, DeepSeek v3 и другие
2. **Гибкая интеграция**: Сохраняйте свои любимые инструменты разработки, интегрируясь в существующие системы для автоматизации
3. **Взаимодействие на естественном языке**: Попрощайтесь со сложными командами, управляйте ИИ через повседневную беседу, от разработки кода до личного ассистента
4. **Открытая платформа**: Установка SubAgent и MCP одним кликом из [открытого рынка iFlow](https://platform.iflow.cn/), быстро расширяйте интеллектуальных агентов и создавайте свою команду ИИ
## Сравнение функций
| Функция | iFlow Cli | Claude Code | Gemini Cli |
|---------|-----------|-------------|------------|
| Todo планирование | ✅ | ✅ | ❌ |
| SubAgent | ✅ | ✅ | ❌ |
| Пользовательские команды | ✅ | ✅ | ✅ |
| Режим планирования | ✅ | ✅ | ❌ |
| Инструменты задач | ✅ | ✅ | ❌ |
| Плагин VS Code | ✅ | ✅ | ✅ |
| Плагин JetBrains | ✅ | ✅ | ❌ |
| Восстановление разговора | ✅ | ✅ | ❌ |
| Встроенный открытый рынок | ✅ | ❌ | ❌ |
| Автоматическое сжатие памяти | ✅ | ✅ | ✅ |
| Мультимодальные возможности | ✅ | ⚠️ (Китайские модели не поддерживаются) | ⚠️ (Китайские модели не поддерживаются) |
| Поиск | ✅ | ❌ | ⚠️ (Требуется VPN) |
| Бесплатно | ✅ | ❌ | ⚠️ (Ограниченное использование) |
| Hook | ✅ | ✅ | ❌ |
| Стиль вывода | ✅ | ✅ | ❌ |
| Мышление | ✅ | ✅ | ❌ |
| Рабочий процесс | ✅ | ❌ | ❌ |
| SDK | ✅ | ✅ | ❌ |
| ACP | ✅ | ✅ | ✅ |
## ⭐ Ключевые функции
* Поддержка 4 режимов работы: yolo (модель с максимальными разрешениями, может выполнять любые операции), accepting edits (модель только с разрешениями редактирования файлов), plan mode (сначала планировать, затем выполнять), default (модель без разрешений)
* Улучшенная функциональность subAgent. Превращает CLI из универсального помощника в команду экспертов, предоставляя более профессиональные и точные советы. Используйте /agent для просмотра предварительно настроенных агентов
* Улучшенный инструмент task. Эффективное сжатие длины контекста, позволяющее CLI выполнять ваши задачи более глубоко. Автоматическое сжатие при достижении контекстом 70%
* Интеграция с открытым рынком iFlow. Быстрая установка полезных инструментов MCP, Subagents, пользовательских инструкций и рабочих процессов
* Бесплатное использование мультимодальных моделей, вы также можете вставлять изображения в CLI (Ctrl+V для вставки изображений)
* Поддержка сохранения и отката истории разговоров (команды iflow --resume и /chat)
* Поддержка большего количества полезных команд терминала (iflow -h для просмотра дополнительных команд)
* Поддержка плагина VSCode
* Автоматическое обновление, iFlow CLI автоматически определяет, является ли текущая версия последней
## 📥 Установка
### Системные требования
- Операционные системы: macOS 10.15+, Ubuntu 20.04+/Debian 10+, или Windows 10+ (с WSL 1, WSL 2, или Git for Windows)
- Аппаратное обеспечение: 4ГБ+ ОЗУ
- Программное обеспечение: Node.js 22+
- Сеть: Требуется подключение к интернету для аутентификации и обработки ИИ
- Оболочка: Лучше всего работает в Bash, Zsh или Fish
### Команда установки
**Пользователи MAC/Linux/Ubuntu**:
* Команда установки в один клик (Рекомендуется)
```shell
bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
```
* Установка с Node.js
```shell
npm i -g @iflow-ai/iflow-cli
```
Эта команда автоматически устанавливает все необходимые зависимости для вашего терминала.
**Пользователи Windows**:
1. Перейдите на https://nodejs.org/en/download, чтобы скачать последний установщик Node.js
2. Запустите установщик для установки Node.js
3. Перезапустите ваш терминал: CMD или PowerShell
4. Выполните `npm install -g @iflow-ai/iflow-cli` для установки iFlow CLI
5. Выполните `iflow` для запуска iFlow CLI
Если вы находитесь в континентальном Китае, вы можете использовать следующую команду для установки iFlow CLI:
1. Перейдите на https://cloud.iflow.cn/iflow-cli/nvm-setup.exe, чтобы скачать последний установщик nvm
2. Запустите установщик для установки nvm
3. **Перезапустите ваш терминал: CMD или PowerShell**
4. Выполните `nvm node_mirror https://npmmirror.com/mirrors/node/` и `nvm npm_mirror https://npmmirror.com/mirrors/npm/`
5. Выполните `nvm install 22` для установки Node.js 22
6. Выполните `nvm use 22` для использования Node.js 22
7. Выполните `npm install -g @iflow-ai/iflow-cli` для установки iFlow CLI
8. Выполните `iflow` для запуска iFlow CLI
## 🗑️ Удаление
```shell
npm uninstall -g @iflow-ai/iflow-cli
```
## 🔑 Аутентификация
iFlow предлагает два варианта аутентификации:
1. **Рекомендуется**: Использование нативной аутентификации iFlow
2. **Альтернатива**: Подключение через OpenAI-совместимые API
Выберите вариант 1 для прямого входа, что откроет аутентификацию аккаунта iFlow в веб-странице. После завершения аутентификации вы можете использовать его бесплатно.
Если вы находитесь в окружении вроде сервера, где не можете открыть веб-страницу, используйте вариант 2 для входа.
Чтобы получить ваш API-ключ:
1. Зарегистрируйте аккаунт iFlow
2. Перейдите в настройки профиля или нажмите [эту прямую ссылку](https://iflow.cn/?open=setting)
3. Нажмите "Reset" в всплывающем диалоге для генерации нового API-ключа
После генерации ключа вставьте его в приглашение терминала для завершения настройки.
## 🚀 Начало работы
Чтобы запустить iFlow CLI, перейдите в вашу рабочую область в терминале и введите:
```shell
iflow
```
### Создание новых проектов
Для новых проектов просто опишите, что вы хотите создать:
```shell
cd new-project/
iflow
> Создай веб-игру Minecraft используя HTML
```
### Работа с существующими проектами
Для существующих кодовых баз начните с команды `/init`, чтобы помочь iFlow понять ваш проект:
```shell
cd project1/
iflow
> /init
> Проанализируй требования согласно PRD документу в файле requirement.md и выведи техническую документацию, затем реализуй решение.
```
Команда `/init` сканирует вашу кодовую базу, изучает её структуру и создает файл IFLOW.md с подробной документацией.
Полный список слэш-команд и инструкций по использованию смотрите [здесь](./i18/en/commands.md).
## 💡 Типичные случаи использования
iFlow CLI выходит за рамки программирования и может решать широкий спектр задач:
### 📊 Информация и планирование
```text
> Помоги мне найти рестораны с лучшими рейтингами в Москве и создай маршрут гастрономического тура на 3 дня.
```
```text
> Найди последние сравнения цен на iPhone и найди наиболее выгодный вариант покупки.
```
### 📁 Управление файлами
```text
> Организуй файлы на моем рабочем столе по типам файлов в отдельные папки.
```
```text
> Массово скачай все изображения с этой веб-страницы и переименуй их по дате.
```
### 📈 Анализ данных
```text
> Проанализируй данные продаж в этой Excel таблице и создай простую диаграмму.
```
```text
> Извлеки информацию о клиентах из этих CSV файлов и объедини их в единую таблицу.
```
### 👨💻 Поддержка разработки
```text
> Проанализируй основные архитектурные компоненты и зависимости модулей этой системы.
```
```text
> У меня возникает исключение null pointer после запроса, пожалуйста, помоги найти причину проблемы.
```
### ⚙️ Автоматизация рабочих процессов
```text
> Создай скрипт для периодического резервного копирования моих важных файлов в облачное хранилище.
```
```text
> Напиши программу, которая ежедневно загружает цены акций и отправляет мне уведомления по электронной почте.
```
*Примечание: Продвинутые задачи автоматизации могут использовать MCP-серверы для интеграции инструментов вашей локальной системы с корпоративными платформами совместной работы.*
## 🔧 Переключение на пользовательскую модель
iFlow CLI может подключаться к любому OpenAI-совместимому API. Отредактируйте файл настроек в `~/.iflow/settings.json`, чтобы изменить используемую модель.
Вот пример файла настроек:
```json
{
"theme": "Default",
"selectedAuthType": "iflow",
"apiKey": "ваш ключ iflow",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"searchApiKey": "ваш ключ iflow"
}
```
## 🔄 GitHub Actions
Вы также можете использовать iFlow CLI в ваших рабочих процессах GitHub Actions с помощью действия, поддерживаемого сообществом: [iflow-cli-action](https://github.com/iflow-ai/iflow-cli-action)
## 👥 Общение с сообществом
Если у вас возникнут проблемы при использовании, вы можете напрямую создать Issues на странице GitHub.
Вы также можете отсканировать QR-код группы WeChat ниже, чтобы присоединиться к группе сообщества для общения и обсуждения.
### Группа WeChat
## /assets/example1_EN.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/example1_EN.jpg
## /assets/iflow-cli.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/iflow-cli.jpg
## /assets/iflow-wechat.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/iflow-wechat.jpg
## /assets/iflow_start.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/iflow_start.jpg
## /assets/login.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/login.jpg
## /assets/profile-settings.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/profile-settings.jpg
## /assets/web-login.jpg
Binary file available at https://raw.githubusercontent.com/iflow-ai/iflow-cli/refs/heads/main/assets/web-login.jpg
## /docs_cn/changelog.md
---
title: 变更日志
description: iFlow CLI 版本更新历史和变更记录
sidebar_position: 100
---
# 变更日志
> **用途**：记录iFlow CLI的版本更新历史、新功能和重要变更
> **适用场景**：了解版本差异、升级参考、功能追踪
## 版本历史
### v0.3.2 (2025年10月14日)
- 优化互联网搜索文本
- 修复model切换导致的history丢失问题
- 优化模型调用
- 优化工作流安装过程中的压缩格式兼容问题
- 优化修改json文件导致的兼容问题
### v0.3.1 (2025年10月12日)
- 修复模型调用可能导致的异常问题
- 修复工具调用可能导致的异常问题
### v0.3.0 (2025年10月11日)
- **工作流**: 我们在这个版本上新了一个重大功能，工作流。可以参考[工作流](./examples/workflow.md)的介绍使用，也可以直接查看开放平台来直接使用
- 修复了 Shell 输出信息错误和中文乱码问题
- 其他相关体验优化
### v0.2.36 (2025年10月9日)
#### 功能改进
- **解决 Multi Edit 工具调用失败问题**
- **解决 Shell 命令路径空格问题**
- **解决 VS Code 启动问题**
- **提升 Windows 环境下脚本执行成功率**
- **提升 API 调用稳定性**
### v0.2.33 (2025年9月30日)
#### 功能改进
- **闪屏问题修复**: 缓解闪屏问题
- **ACP协议**: ACP相关协议内容修复
### v0.2.32 (2025年9月29日)
#### 功能改进
- **模型支持**: 支持deepssek v3.2模型，/model切换，Qwen3 Coder，Qwen3 max，Qwen3 VL模型全面上新
- **体验优化**: 体验优化，降低闪屏问题
- **问题修复**: 修复xml转义问题
### v0.2.31 (2025年9月28日)
#### 功能改进
- **闪屏问题修复**: 优化执行过程中消息的渲染，极大缓解闪屏问题
- **iFlow SDK**: 优化了ACP协议内容和SDK内容
- **Windows体验优化**: 优化了Windows下粘贴文字、图片、执行任务等多处体验问题
- **/resume命令支持**: slash command中我们增加了/resume命令，支持恢复历史对话
- **恢复历史对话优化**: 修复从历史中resume可能带来的错误问题
- **IDE 插件优化**: 提升IDE插件使用体验
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.30 (2025年9月24日)
#### 功能改进
- **hook支持**: 额外增加四种hook类型，详情参考[hook](./examples/hooks.md)
- **agent升级**: 支持subagent更加完善的工具使用方式，详情参考[agent](./examples/subagent.md)
- **支持模型thinking**: 详情参考[thinking](./features/thinking.md)
### v0.2.29 (2025年9月23日)
#### 功能改进
- **模型修复**: 修复Deepseek V3.1 Terminus模型访问报错问题
- **输出样式支持**: 集成output style功能，详情参考[输出样式](./features/output-style.md)
### v0.2.28 (2025年9月23日)
#### 功能改进
- **模型升级**: 支持Deepseek V3.1 Terminus模型
### v0.2.27 (2025年9月22日)
#### 功能改进
- **功能修复**: 修复中文导致的异常退出问题
### v0.2.26 (2025年9月21日)
#### 功能改进
- **汉化功能**: 汉化功能支持，自动检测终端语言。 /language 也可以切换中英文
- **循环检测升级**: 循环检测升级，更加友好的流程控制
- **中文输入输出**: 更好地适配中文的输入输出
### v0.2.25 (2025年9月18日)
#### 功能改进
- **iFlow SDK**: 支持iFlow SDK，详情参考[SDK](sdk/sdk-python.md)
- **输入框**: 移除输入框左右侧线条，便于复制
### v0.2.24 (2025年9月17日)
#### 功能改进
- **粘贴操作优化**: 修复Windows下多行本文以及图片粘贴的问题
- **输入框优化**: 优化输入框输入一些特殊字符导致的问题，新增shift+enter换行操作
### v0.2.23 (2025年9月16日)
#### 功能改进
- **ACP协议支持**: 支持Zed ACP协议，可以在Zed中接入iFlow CLI
- **历史消息存储**: 修复多模态信息存储历史记录的问题
- **回答风格**: 追加适当建设性反问
- **插件冲突问题**: 修复vscode插件与cli冲突问题
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.22 (2025年9月15日)
#### 功能改进
- **异常退出优化**: 兼容异常退出导致的错误
- **会话恢复优化**: 修复-c, -r之后上下文错误的问题。
- **配置内容**: 增加更多配置内容，例如：是否跳过任务结束检测，详情可以参考[CLI 配置](./configuration/settings.md)
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.21 (2025年9月12日)
#### 功能改进
- **插件升级**: 修复Jetbrains插件连接问题
### v0.2.20 (2025年9月11日)
#### 功能改进
- **登录体验优化**: 带来更好的登录体验
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.18 (2025年9月10日)
#### 功能改进
- **系统提示词升级**: 升级系统提示词，更好地解决用户的问题
- **VSCode插件升级**: 优化VSCode插件，优化整体使用感受
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.17 (2025年9月9日)
#### 功能改进
- **登录模式升级**: 升级心流网页端授权认证，替换之前的iFlow API Key登录
- **优化压缩逻辑**: 升级上下文压缩算法
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.16 (2025年9月8日)
#### 功能改进
- **安装包升级**: 升级安装包体验
### v0.2.15 (2025年9月7日)
#### 功能改进
- **插件升级**: vscode插件升级
### v0.2.13 (2025年9月6日)
#### 功能改进
- **支持更多模型**: 支持Kimi K2 0905模型和Qwen3-max模型
### v0.2.12 (2025年9月5日)
#### 功能改进
- **更多个性化配置**: 例如tokensLimit、compressionTokenThreshold等，详情查看[CLI 配置](./configuration/settings.md)
- **斜杠命令模糊搜索**: 支持斜杠命令模糊搜索
- **快捷键支持**: 新增使用alt + m键切换运行模式
- **已知问题修复**: 修复内存溢出等导致程序崩溃退出的问题
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.11 (2025年9月3日)
#### 功能改进
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.10 (2025年9月2日)
#### 功能改进
- **问题修复**：修复输入问题不显示的bug
### v0.2.9 (2025年9月2日)
#### 功能改进
- **闪屏问题**：修复subagent执行过程导致的闪屏问题
- **写文件问题**：修复write file报错问题
- **vscode插件**：修复在windows系统重开启iflow会打开多个vscode问题
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.8 (2025年9月1日)
#### 功能改进
- **Hooks**：增加Hooks功能，可以参考教程/Hooks文档使用
- **引导式创建Subagent**：用户可在CLI通过/agents install根据提示创建自定义agent
- **压缩逻辑强化**：新增压缩文件恢复能力
- **SubAgent信息折叠和展示**：支持ctrl+r展开SubAgent执行详细信息
- **MCP**：MCP相关体验优化
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.7 (2025年8月28日)
#### 功能改进
- **闪屏问题缓解**：缓解界面闪屏问题，提升用户体验
- **MCP命令修复**：修复mcp add命令在根目录下覆盖配置文件的问题
- **文档格式支持**：新增支持读取doc、excel、pdf文件功能
- **压缩逻辑强化**：强化压缩逻辑，提升压缩效果和性能
- **体验优化**：相关功能体验优化，提升整体使用感受
### v0.2.6 (2025年8月26日)
#### 功能改进
- **命令优化**：优化`/compress`命令，提升压缩效率和用户体验
- **Markdown格式支持**：支持md格式的sub command，提供更丰富的命令文档和帮助信息
- **MCP Client升级**：升级MCP Client，优化调用方式，提升MCP工具的使用体验
- **初始化命令优化**：优化`/init`命令，默认不会读取.iflow文件夹内的内容，已有的IFLOW.md会更新
### v0.2.5 (2025年8月25日)
#### 新功能
- **DeepSeek V3.1模型支持**：新增对DeepSeek V3.1模型的完整支持，提供更强大的推理和代码生成能力
- **交互式演示功能**：新增`/demo`命令，支持交互式体验模式，包括deep-research和头脑风暴
### v0.2.0 (2025年8月21日)
#### 新功能
- **市场支持**：支持市场快速安装MCP、Subagent、Command，所有组件均经过安全认证，放心使用
- **IDE集成**：支持VS Code、JetBrains查看（新版本自动安装）
- **多种运行模式**：支持4种运行模式 - yolo、accepting edits、plan mode、default
- **任务工具升级**：升级task工具，支持Sub Agent并行执行，有效压缩上下文长度，让CLI能够更加深入完成任务
- **多模态支持**：支持多模态，识别手稿，产出代码
- **对话管理**：支持历史对话保存、恢复和回滚（`iflow --resume`、`--continue`、`/chat`命令）
- **丰富终端命令**：支持更多更好用的终端命令（使用`iflow -h`查看更多命令）
- **后台挂起**：支持后台挂起功能（Ctrl+D）
- **自动升级**：自动升级功能，再也不用担心最新功能体验不到
- **Claude Code兼容**：完全兼容Claude Code特性，无切换成本
### v0.1.7 (2025年8月18日)
#### 新功能
- **代理和命令支持**：支持subagent、command功能
- **VS Code插件**：支持VS Code插件（默认安装，不用去市场下载）
- **MCP市场**：支持MCP市场，通过`/mcp online`浏览，MCP工具均安全认证
- **组件市场**：支持sub agents市场、commands市场，通过`/agents online`或`/commands online`浏览
- **快速模型切换**：快速模型切换功能`/model`
- **对话管理**：对话继续`iflow --continue`，对话恢复`iflow --resume`
- **多模态**：支持图片粘贴理解
- **性能优化**：优化整体使用效果
### v0.1.0 (2025年8月1日)
#### 首次发布
- **完全免费的AI模型**：通过iFlow开放平台，模型均集团内部部署，完美适配Kimi-K2、Qwen3 Coder模型，可以使用在C3代码
- **灵活集成**：完整支持OpenAI协议的模型提供商，可以切换成更强大的claude、chatgpt等模型
- **开箱即用**：预配置好的MCP servers
- **直观体验**：比Gemini CLI强，比肩Claude Code的体验
## 反馈和支持
遇到问题或有功能建议？
- **GitHub Issues**：[提交问题](https://github.com/iflow-ai/iflow-cli/issues)
---
**更新说明**：本变更日志按照[语义化版本](https://semver.org/lang/zh-CN/)规范维护。重大更新会在发布前通过社区渠道提前通知。
## /docs_cn/configuration/iflow.md
# 记忆
## 概述
IFLOW.md 是 iFlow CLI 的核心记忆文件，它为 AI 助手提供项目特定的指令上下文和背景信息。与传统的配置文件不同，IFLOW.md 使用自然语言编写，让 AI 能够更好地理解你的项目结构、编码规范和工作流程。对于CLI工作你有任何的说明和约束都可以编写在这个文件当中
### 主要功能
- **上下文提供**：为 AI 提供项目背景、编码规范、架构信息
- **个性化定制**：根据项目特点定制 AI 的行为和响应
- **分级管理**：支持全局、项目和子目录级的分层配置
- **模块化组织**：通过文件导入实现配置的模块化管理
- **记忆保存**：通过 save_memory 功能持久化重要信息
## 文件存储位置和分级设计
IFLOW.md 采用分级系统，按照以下优先级加载（数字越大优先级越高）：
### 1. 全局级别（优先级：低）
```
~/.iflow/IFLOW.md
```
- **作用范围**：所有 iFlow CLI 会话
- **用途**：存储个人偏好、通用编码规范、全局记忆
- **示例内容**：个人编程习惯、常用库偏好、个人信息
### 2. 项目级别（优先级：中）
```
/path/to/your/project/IFLOW.md
```
- **作用范围**：特定项目
- **用途**：项目架构、技术栈、团队规范
- **示例内容**：项目概述、API 文档、部署说明
### 3. 子目录级别（优先级：高）
```
/path/to/your/project/src/IFLOW.md
/path/to/your/project/tests/IFLOW.md
```
- **作用范围**：特定目录及其子目录
- **用途**：模块特定的指令和约定
- **示例内容**：模块说明、特殊测试要求
### 加载机制
iFlow CLI 会从当前工作目录开始，向上搜索到项目根目录和用户主目录，加载所有找到的 IFLOW.md 文件。内容会按照优先级顺序合并，高优先级的内容会覆盖低优先级的内容。
### 自定义文件名
可以通过[配置文件](./settings.md)自定义上下文文件名：
```json
{
"contextFileName": "AGENTS.md"
}
```
或支持多个文件名：
```json
{
"contextFileName": ["IFLOW.md", "AGENTS.md", "CONTEXT.md"]
}
```
## /init 操作详解
`/init` 命令是快速开始的最佳方式，它会自动分析你的项目并生成定制化的 IFLOW.md 文件。
### 执行流程
1. **检查现有文件**：如果当前目录已有 IFLOW.md，会提示不进行修改
2. **创建空文件**：首先创建一个空的 IFLOW.md 文件
3. **项目分析**：扫描项目结构、依赖、配置文件
4. **内容生成**：基于分析结果生成定制化内容
5. **文件填充**：将生成的内容写入 IFLOW.md
### 分析内容
`/init` 命令会分析以下项目特征：
- **技术栈识别**：基于 package.json、requirements.txt 等文件
- **项目结构**：目录布局、关键文件位置
- **构建工具**：webpack、vite、rollup 等配置
- **测试框架**：jest、mocha、pytest 等
- **代码规范**：ESLint、Prettier、Black 等配置
- **文档结构**：README、API 文档等
### 使用示例
```bash
# 在项目根目录执行
$ iflow
> /init
# 输出示例
Empty IFLOW.md created. Now analyzing the project to populate it.
Analyzing project structure...
Generating customized context...
IFLOW.md has been successfully populated with project-specific information.
```
### 生成内容示例
```markdown
# 项目上下文
## 项目概述
这是一个基于 TypeScript + React + Node.js 的全栈应用。
## 技术栈
- 前端：React 18, TypeScript, Vite
- 后端：Node.js, Express, TypeScript
- 数据库：PostgreSQL
- 测试：Jest, React Testing Library
## 项目结构
```
src/
├── components/ # React 组件
├── services/ # API 服务
├── utils/ # 工具函数
└── types/ # TypeScript 类型定义
```
## 开发规范
- 使用 TypeScript 严格模式
- 组件采用函数式写法
- 使用 ESLint + Prettier 代码格式化
- 提交前运行 pre-commit hooks
```
## 模块化管理（导入功能）
IFLOW.md 支持通过 `@` 语法导入其他文件，实现配置的模块化管理。
### 导入语法
```markdown
# 主 IFLOW.md 文件
@./shared/coding-standards.md
@./project-specific/architecture.md
@../global/personal-preferences.md
```
### 支持的路径格式
#### 相对路径
```markdown
@./file.md # 同目录
@../file.md # 父目录
@./components/readme.md # 子目录
```
#### 绝对路径
```markdown
@/absolute/path/to/file.md
```
### 文件组织示例
```
project/
├── IFLOW.md # 主配置文件
├── .iflow/
│ ├── architecture.md # 架构说明
│ ├── coding-style.md # 编码规范
│ └── deployment.md # 部署说明
└── src/
└── IFLOW.md # 源码目录特定配置
```
主 IFLOW.md：
```markdown
# 项目总体配置
@./.iflow/architecture.md
@./.iflow/coding-style.md
@./.iflow/deployment.md
## 项目特定指令
请在处理这个项目时遵循上述架构和编码规范。
```
### 安全特性
1. **循环导入检测**：自动检测并阻止循环引用
2. **路径验证**：确保只能访问允许的目录
3. **深度限制**：防止过深的导入嵌套（默认最大 5 层）
4. **错误处理**：优雅处理文件不存在或权限问题
### 调试导入
使用 `/memory show` 命令查看完整的合并结果和导入树：
```
Memory Files
L project: IFLOW.md
L .iflow/architecture.md
L .iflow/coding-style.md
L .iflow/deployment.md
```
## 实际应用示例
### 1. React 项目示例
```markdown
# React 项目配置
## 项目类型
这是一个现代 React 应用，使用 TypeScript 和 Vite。
## 开发规范
- 优先使用函数组件和 Hooks
- 状态管理使用 Zustand
- 样式使用 Tailwind CSS
- 测试使用 Jest + Testing Library
## 代码风格
- 组件文件使用 PascalCase 命名
- Hook 文件以 use 开头
- 常量使用 UPPER_SNAKE_CASE
- 接口以 I 开头（如 IUser）
## 文件结构约定
```
src/
├── components/ # 可复用组件
├── pages/ # 页面组件
├── hooks/ # 自定义 hooks
├── stores/ # Zustand stores
├── services/ # API 调用
├── types/ # TypeScript 类型
└── utils/ # 工具函数
```
## 特殊要求
- 所有组件必须有 TypeScript 类型声明
- 异步操作使用 React Query
- 路由使用 React Router v6
```
### 2. Node.js 后端项目示例
```markdown
# Node.js 后端项目
## 技术栈
- Framework: Express.js
- Database: PostgreSQL + Prisma ORM
- Authentication: JWT
- Validation: Zod
- Testing: Jest + Supertest
## 架构模式
采用分层架构：Controller -> Service -> Repository -> Database
## API 规范
- RESTful API 设计
- 统一错误处理中间件
- 请求参数验证使用 Zod
- 响应格式：`{ success: boolean, data?: any, error?: string }`
## 安全要求
- 所有路由需要适当的认证和授权
- 敏感信息使用环境变量
- 输入数据必须验证和清理
- 错误信息不暴露内部实现
## 部署配置
- 使用 Docker 容器化
- 环境变量通过 .env 文件管理
- 生产环境使用 PM2 进程管理
```
### 3. 团队协作示例
```markdown
# 团队开发规范
## 代码提交规范
- 使用 Conventional Commits 格式
- 提交前必须通过 lint 和 test
- 每个 PR 必须有代码审查
- 重要变更需要技术方案讨论
## 分支策略
- main: 生产环境代码
- develop: 开发环境代码
- feature/*: 功能分支
- hotfix/*: 紧急修复分支
## 代码审查要点
1. 代码逻辑正确性
2. 性能考虑
3. 安全性检查
4. 测试覆盖度
5. 文档完整性
## 沟通协作
- 重大架构变更先讨论再实现
- 遇到问题及时在群里沟通
- 定期进行技术分享
- 保持代码和文档同步更新
```
## 进阶功能
### 1. 与 /memory 命令配合
```bash
# 查看当前加载的记忆内容
/memory show
# 手动添加记忆
/memory add 这个项目的测试覆盖率要求是 80% 以上
# 刷新记忆（重新加载所有 IFLOW.md 文件）
/memory refresh
```
### 2. 环境变量引用
在 IFLOW.md 中可以引用环境变量：
```markdown
# 项目配置
## 数据库连接
使用环境变量 `$DATABASE_URL` 连接数据库。
## API 配置
API 基础地址：`${API_BASE_URL}`
API 密钥：`$API_SECRET_KEY`
```
### 3. 动态配置
根据不同环境加载不同配置：
```markdown
# 环境相关配置
@./config/development.md
@./config/production.md
## 当前环境
当前运行在 ${NODE_ENV} 环境。
```
## 常见问题和故障排除
### 1. IFLOW.md 不生效
**症状**：修改 IFLOW.md 后 AI 行为没有变化
**排查步骤**：
1. 检查文件位置是否正确
2. 使用 `/memory show` 查看是否被加载
3. 使用 `/memory refresh` 强制重新加载
4. 检查文件权限是否可读
**解决方案**：
```bash
# 查看当前加载的记忆
/memory show
# 重新加载所有记忆文件
/memory refresh
# 检查配置的文件名
# 确保与 contextFileName 设置一致
```
### 2. 优先级冲突
**症状**：不同级别的 IFLOW.md 内容冲突
**解决方案**：
1. 理解加载优先级：子目录 > 项目 > 全局
2. 使用 `/memory show` 查看最终合并结果
3. 在高优先级文件中明确覆盖低优先级设置
### 3. 导入文件失败
**症状**：`@file.md` 语法不工作
**常见原因**：
- 文件路径错误
- 文件不存在
- 循环导入
- 权限问题
**解决方案**：
```bash
# 使用绝对路径测试
@/absolute/path/to/file.md
# 检查文件是否存在
ls -la ./path/to/file.md
# 查看导入树结构
/memory show
```
### 4. 性能问题
**症状**：启动慢或响应延迟
**优化建议**：
1. 减少导入文件数量
2. 避免过深的导入嵌套
3. 删除不必要的内容
4. 使用更具体的配置而非通用配置
### 5. save_memory 不工作
**可能原因**：
- 全局目录 `~/.iflow/` 不存在
- 权限不足
- 磁盘空间不足
**解决方案**：
```bash
# 创建全局配置目录
mkdir -p ~/.iflow
# 检查权限
ls -la ~/.iflow/
# 手动创建文件测试
touch ~/.iflow/IFLOW.md
```
## 最佳实践总结
### 1. 内容组织
- **分层管理**：全局通用设置，项目特定配置，模块局部规则
- **模块化导入**：将大文件拆分为逻辑模块
- **版本控制**：项目级 IFLOW.md 纳入版本控制，全局文件不纳入
### 2. 内容编写
- **使用自然语言**：让 AI 容易理解的描述方式
- **具体明确**：避免模糊的描述，给出具体示例
- **保持更新**：随着项目发展及时更新配置
### 3. 团队协作
- **统一规范**：团队成员使用一致的 IFLOW.md 模板
- **文档同步**：配置变更与代码变更同步进行
- **定期评审**：定期评审和优化 IFLOW.md 内容
### 4. 维护管理
- **定期清理**：删除过时的配置和记忆
- **监控效果**：观察 AI 行为是否符合预期
- **渐进优化**：根据使用效果逐步完善配置
通过合理使用 IFLOW.md，你可以让 iFlow CLI 更好地理解你的项目和需求，从而提供更精准、更有价值的帮助。记住，IFLOW.md 是一个强大的工具，合理配置能够显著提升开发效率和 AI 协作体验。
## /docs_cn/configuration/iflowignore.md
# 忽略项目中的文件
## 概述
`.iflowignore` 是 iFlow CLI 中的文件忽略功能，类似于 Git 的 `.gitignore`。它允许你指定哪些文件和目录在使用 iFlow CLI 工具时应该被忽略。
## 工作原理
当你在项目根目录创建 `.iflowignore` 文件并定义忽略规则后，支持此功能的 iFlow CLI 工具会自动跳过匹配的文件和目录，不会对它们进行处理。
## 支持的工具
以下 iFlow CLI 工具支持 `.iflowignore` 功能：
- `ls` - 目录列举工具
- `read_many_files` - 批量文件读取工具
- `@filename` 语法 - AT命令文件引用
- 其他文件操作相关工具
## 使用方法
### 1. 创建 .iflowignore 文件
在你的项目根目录下创建 `.iflowignore` 文件：
```bash
touch .iflowignore
```
### 2. 添加忽略规则
`.iflowignore` 文件遵循与 `.gitignore` 相同的语法规则：
```bash
# 这是注释行
# 忽略特定文件
secrets.txt
config.json
# 忽略特定目录
build/
dist/
node_modules/
# 使用通配符忽略文件类型
*.log
*.tmp
*.cache
# 使用路径匹配
/root-only-file.txt
src/**/*.test.js
# 否定规则（不忽略）
*.log
!important.log
```
### 3. 语法规则
| 规则 | 说明 | 示例 |
|------|------|------|
| `#` | 注释行 | `# 这是注释` |
| `*` | 匹配任意字符 | `*.log` 匹配所有 .log 文件 |
| `?` | 匹配单个字符 | `file?.txt` 匹配 file1.txt |
| `[]` | 字符集匹配 | `[abc].txt` 匹配 a.txt, b.txt, c.txt |
| `/` 开头 | 根目录相对路径 | `/build/` 只匹配根目录下的 build |
| `/` 结尾 | 仅匹配目录 | `temp/` 只匹配目录，不匹配文件 |
| `!` 开头 | 否定规则 | `!important.log` 不忽略此文件 |
## 实际示例
### 前端项目
```bash
# .iflowignore for React/Vue project
# 构建输出
build/
dist/
.next/
# 依赖
node_modules/
# 日志和缓存
*.log
.cache/
.parcel-cache/
# 环境变量文件
.env.local
.env.production
# 测试覆盖率
coverage/
# IDE 配置（但保留 .vscode）
.idea/
*.swp
*.swo
```
### Node.js 后端项目
```bash
# .iflowignore for Node.js backend
# 运行时文件
*.pid
*.log
logs/
# 依赖和构建
node_modules/
dist/
build/
# 数据库文件
*.db
*.sqlite
# 上传文件目录
uploads/
temp/
# 敏感配置
.env
config/production.json
```
### Python 项目
```bash
# .iflowignore for Python project
# Python 缓存
__pycache__/
*.pyc
*.pyo
*.pyd
# 虚拟环境
venv/
env/
.venv/
# 构建文件
build/
dist/
*.egg-info/
# Jupyter Notebook 检查点
.ipynb_checkpoints/
# 测试和覆盖率
.pytest_cache/
.coverage
htmlcov/
```
## 功能验证
### 测试 ls 工具
```bash
# 使用 iFlow CLI 的 ls 工具查看目录
iflow -p "ls ."
# 被 .iflowignore 忽略的文件不会显示在输出中
# 工具会显示类似 "X 个文件被 iflow-ignored" 的统计信息
```
### 测试文件读取
```bash
# 使用批量文件读取
iflow -p "read_many_files *.txt"
# 被忽略的 .txt 文件会显示 "file is ignored by .iflowignore" 消息
```
### 测试 @ 命令
```bash
# 使用 @ 语法引用文件
iflow -p "@ignored-file.txt"
# 被忽略的文件会显示警告信息并跳过处理
```
## 注意事项
1. **重启生效**：修改 `.iflowignore` 文件后，需要重启 iFlow CLI 会话才能生效
2. **文件位置**：`.iflowignore` 文件必须放在项目根目录
3. **Git 独立**：`.iflowignore` 与 `.gitignore` 是独立的，互不影响
4. **工具支持**：并非所有工具都支持此功能，主要是文件操作相关的工具
## 调试技巧
如果发现忽略规则没有生效：
1. 检查 `.iflowignore` 文件是否在项目根目录
2. 检查文件路径是否正确（相对于项目根目录）
3. 重启 iFlow CLI 会话
4. 使用 `ls` 工具验证忽略效果
## 最佳实践
1. **版本控制**：将 `.iflowignore` 文件提交到 Git，让团队共享忽略规则
2. **分层忽略**：结合 `.gitignore` 使用，`.gitignore` 处理版本控制，`.iflowignore` 处理 AI 工具
3. **定期维护**：随着项目发展，及时更新忽略规则
4. **文档说明**：在项目 README 中说明特殊的忽略规则
通过合理使用 `.iflowignore`，你可以让 iFlow CLI 更专注于处理重要的代码文件，提高工作效率。
## /docs_cn/configuration/settings.md
---
sidebar_position: 0
hide_title: true
---
# CLI 配置
iFlow CLI 提供了丰富的配置选项，您可以通过环境变量、命令行参数和设置文件来定制CLI的行为。下面我们将详细介绍这些配置方式，帮助您打造专属的使用体验。
## 配置层级
iFlow CLI 采用分层配置系统，按照以下优先级顺序生效，优先级高的设置会覆盖低优先级的设置：
1. 应用默认值： CLI 内置的基础配置
2. 用户全局设置： 您的个人默认配置，适用于所有项目
3. 项目专属设置： 特定项目的配置，会覆盖用户设置
4. 系统级设置： 管理员配置，适用于整个系统
5. 命令行参数： 启动时指定的临时配置，优先级最高
## 环境变量配置
iFlow CLI 现在支持通过环境变量进行配置，**所有 `~/.iflow/settings.json` 中的配置项都可以通过 IFLOW_ 前缀的环境变量设置**，避免与其他项目的环境变量冲突。
### 环境变量命名约定
#### IFLOW 前缀规则
**为了避免与其他项目的环境变量冲突，所有环境变量都必须使用 `IFLOW` 或 `iflow` 前缀。**
对于 `settings.json` 中的任何配置项，iFlow 支持以下 4 种环境变量命名约定（按优先级排序）：
1. **IFLOW_前缀的驼峰命名** - `IFLOW_` + settings.json 中的 key 名称（推荐）
2. **IFLOW_前缀的下划线命名** - `IFLOW_` + 大写下划线格式
3. **iflow_前缀的驼峰命名** - `iflow_` + settings.json 中的 key 名称
4. **iflow_前缀的下划线命名** - `iflow_` + 大写下划线格式
#### 命名示例
| settings.json 中的 key | 1. IFLOW_驼峰 | 2. IFLOW_下划线 | 3. iflow_驼峰 | 4. iflow_下划线 |
|----------------------|---------------|----------------|---------------|----------------|
| `apiKey` | `IFLOW_apiKey`| `IFLOW_API_KEY`| `iflow_apiKey`| `iflow_API_KEY`|
| `baseUrl` | `IFLOW_baseUrl`| `IFLOW_BASE_URL`| `iflow_baseUrl`| `iflow_BASE_URL`|
| `modelName` | `IFLOW_modelName`| `IFLOW_MODEL_NAME`| `iflow_modelName`| `iflow_MODEL_NAME`|
| `vimMode` | `IFLOW_vimMode`| `IFLOW_VIM_MODE`| `iflow_vimMode`| `iflow_VIM_MODE`|
| `showMemoryUsage` | `IFLOW_showMemoryUsage`| `IFLOW_SHOW_MEMORY_USAGE`| `iflow_showMemoryUsage`| `iflow_SHOW_MEMORY_USAGE`|
#### 支持的配置项
所有在 `~/.iflow/settings.json` 中的配置项都支持通过环境变量设置，包括但不限于：
- `apiKey` - API 密钥
- `baseUrl` - 基础 URL
- `modelName` - 模型名称
- `vimMode` - Vim 模式开关
- `showMemoryUsage` - 显示内存使用
- `maxSessionTurns` - 最大会话轮数
- `theme` - 主题设置
- 以及 Settings 接口中的所有其他配置项
### 使用方法
#### 方法 1: 使用 IFLOW_前缀的驼峰命名（推荐）
```bash
export IFLOW_apiKey="your_api_key_here"
export IFLOW_baseUrl="https://your-api-url.com/v1"
export IFLOW_modelName="your_model_name"
iflow
```
#### 方法 2: 使用 IFLOW_前缀的下划线命名
```bash
export IFLOW_API_KEY="your_api_key_here"
export IFLOW_BASE_URL="https://your-api-url.com/v1"
export IFLOW_MODEL_NAME="your_model_name"
iflow
```
#### 方法 3: 使用 iflow_前缀（小写）
```bash
export iflow_apiKey="your_api_key_here"
export iflow_baseUrl="https://your-api-url.com/v1"
export iflow_modelName="your_model_name"
iflow
```
#### 方法 4: 一行设置并启动
```bash
IFLOW_apiKey=your_key IFLOW_baseUrl=https://api.example.com/v1 iflow
```
#### 方法 5: 设置更多配置项
```bash
# 所有 settings.json 中的配置都支持 IFLOW_ 前缀
export IFLOW_apiKey="your_api_key_here"
export IFLOW_baseUrl="https://your-api-url.com/v1"
export IFLOW_modelName="your_model_name"
export IFLOW_vimMode="true"
export IFLOW_showMemoryUsage="true"
export IFLOW_maxSessionTurns="50"
export IFLOW_coreTools="read,write,shell,grep"
export IFLOW_theme="dark"
iflow
```
### 配置优先级
配置的完整优先级（从高到低）：
1. **命令行参数** - 如 `iflow --model your-model`
2. **IFLOW 前缀环境变量** - 支持所有 settings.json 中的配置项
- IFLOW_驼峰命名 > IFLOW_下划线命名 > iflow_驼峰命名 > iflow_下划线命名
3. **系统配置文件** - `/etc/iflow-cli/settings.json` 或类似路径
4. **工作区配置文件** - `./iflow/settings.json`
5. **用户配置文件** - `~/.iflow/settings.json`
6. **默认值** - 代码中定义的默认配置
### 实际使用案例
#### OpenAI 兼容 API
```bash
export IFLOW_apiKey="sk-1234567890abcdef"
export IFLOW_baseUrl="https://api.openai.com/v1"
export IFLOW_modelName="gpt-4"
iflow
```
#### 自定义 API 服务
```bash
export IFLOW_API_KEY="your_custom_key"
export IFLOW_BASE_URL="https://your-custom-api.com/v1"
export IFLOW_MODEL_NAME="your-custom-model"
iflow
```
#### 在 CI/CD 环境中使用
```bash
# 在 GitHub Actions 或其他 CI 环境中
export IFLOW_apiKey="${{ secrets.API_KEY }}"
export IFLOW_baseUrl="${{ vars.API_URL }}"
iflow --prompt "Generate documentation"
```
### 环境变量验证
iFlow 会自动检测和验证环境变量：
- 如果检测到有效的环境变量配置，会自动选择 iFlow 认证类型
- 如果没有任何配置，会显示帮助信息指导如何设置
- 错误的配置会显示详细的错误消息
### 安全注意事项
1. **不要在代码中硬编码 API 密钥**
2. **使用 `.env` 文件存储本地开发配置**
3. **在生产环境中使用环境变量或密钥管理服务**
4. **定期轮换 API 密钥**
### 故障排除
#### 优先级问题
如果配置没有按预期工作，检查是否有更高优先级的配置覆盖了环境变量：
1. 检查命令行参数
2. 检查 `~/.iflow/settings.json` 配置文件
3. 检查其他环境变量
#### 认证失败
确保：
1. API 密钥格式正确
2. 基础 URL 可访问
3. 模型名称正确
### 迁移指南
#### 从配置文件迁移到环境变量
如果您之前使用配置文件，可以将设置迁移到环境变量：
```bash
# 将以下内容添加到您的 .bashrc 或 .zshrc
export IFLOW_API_KEY="从 settings.json 中的 apiKey"
export IFLOW_BASE_URL="从 settings.json 中的 baseUrl"
export IFLOW_MODEL_NAME="从 settings.json 中的 modelName"
```
#### 保持向后兼容
现有的所有配置方式继续有效：
- `settings.json` 配置文件
- 原有环境变量（`GEMINI_API_KEY` 等）
- 命令行参数
## 设置文件
通过 `settings.json` 文件，您可以保存常用配置。根据使用场景，可以将文件放置在以下位置：
- **用户设置文件：**
- **位置：** `~/.iflow/settings.json`（`~` 代表您的主目录）
- **作用域：** 个人默认配置，对所有项目生效
- **项目设置文件：**
- **位置：** 项目根目录下的 `.iflow/settings.json`
- **作用域：** 仅对当前项目生效，会覆盖用户全局设置
- **系统设置文件：**
- **位置：** `/etc/iflow-cli/settings.json`（Linux）、`C:\ProgramData\iflow-cli\settings.json`（Windows）或 `/Library/Application Support/iFlowCli/settings.json`（macOS）。也可通过 `IFLOW_CLI_SYSTEM_SETTINGS_PATH` 环境变量自定义路径
- **作用域：** 影响系统所有用户，通常由管理员配置。在企业环境中特别有用，便于统一管理团队配置
**环境变量引用：** 在 `settings.json` 文件中，您可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。这些变量会在加载设置时自动解析。例如，如果有环境变量 `MY_API_TOKEN`，可以在 `settings.json` 中这样使用：`"apiKey": "$MY_API_TOKEN"`。
### 项目中的 `.iflow` 目录
除了项目设置文件外，项目的 `.iflow` 目录还可以包含与 iFlow CLI 操作相关的其他项目特定文件，例如：
- [自定义沙箱配置文件](#沙箱)（如 `.iflow/sandbox-macos-custom.sb`、`.iflow/sandbox.Dockerfile`）。
### `settings.json` 中的可用设置：
- **`selectedAuthType`** (字符串)
- **描述：** 认证类型，用于指定连接API的认证方式。`iflow` 表示使用心流认证，`openai-compatible` 支持任何提供OpenAI协议的模型服务商
- **默认值：** `iflow`
- **示例：** `"selectedAuthType": "api_key"`
- **`apiKey`** (字符串)
- **描述：** API密钥，用于模型调用的身份验证
- **默认值：** 必填
- **示例：** `"apiKey": "sk-xxxxxxxxxxxxxxxxxxxxx"`
- **`baseUrl`** (字符串)
- **描述：** API服务的基础URL地址
- **默认值：** 必填
- **示例：** `"baseUrl": "https://api.xinliu.ai/v1"`
- **`modelName`** (字符串)
- **描述：** 要使用的AI模型名称
- **默认值：** 必填
- **示例：** `"modelName": "Qwen3-Coder"`
- **`contextFileName`**（字符串或字符串数组）：
- **描述：** 上下文文件名（如 `IFLOW.md`、`AGENTS.md`）。可以是单个文件名或文件名列表
- **默认值：** `IFLOW.md`
- **示例：** `"contextFileName": "AGENTS.md"`
- **`bugCommand`**（对象）：
- **描述：** 覆盖 `/bug` 命令的默认 URL。
- **默认值：** `"urlTemplate": "https://github.com/iflow-ai/iflow-cli/issues/new?template=bug_report.yml&title={title}&info={info}"`
- **属性：**
- **`urlTemplate`**（字符串）：可以包含 `{title}` 和 `{info}` 占位符的 URL。
- **示例：**
```json
"bugCommand": {
"urlTemplate": "https://bug.example.com/new?title={title}&info={info}"
}
```
- **`fileFiltering`**（对象）：
- **描述：** 控制 @ 命令和文件发现工具的 git 感知文件过滤行为。
- **默认值：** `"respectGitIgnore": true, "enableRecursiveFileSearch": true`
- **属性：**
- **`respectGitIgnore`**（布尔值）：发现文件时是否遵循 .gitignore 模式。设置为 `true` 时，git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）会自动从 @ 命令和文件列表操作中排除。
- **`enableRecursiveFileSearch`**（布尔值）：在提示中完成 @ 前缀时是否启用在当前树下递归搜索文件名。
- **示例：**
```json
"fileFiltering": {
"respectGitIgnore": true,
"enableRecursiveFileSearch": false
}
```
- **`coreTools`**（字符串数组）：
- **描述：** 允许您指定应该提供给模型的核心工具名称列表。这可以用来限制内置工具集。查看`/tools`命令了解核心工具列表。您还可以为支持的工具指定命令特定限制，如 `ShellTool`。例如，`"coreTools": ["ShellTool(ls -l)"]` 将只允许执行 `ls -l` 命令。
- **默认值：** 所有工具都可供 iFlow CLI使用。
- **示例：** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`。
- **`excludeTools`**（字符串数组）：
- **描述：** 允许您指定应该从CLI中排除的核心工具名称列表。同时列在 `excludeTools` 和 `coreTools` 中的工具会被排除。您还可以为支持的工具指定命令特定限制，如 `ShellTool`。例如，`"excludeTools": ["ShellTool(rm -rf)"]` 将阻止 `rm -rf` 命令。
- **默认值**：不排除任何工具。
- **示例：** `"excludeTools": ["ShellTool", "glob"]`。
- **安全注意：** `excludeTools` 中对 `ShellTool` 的命令特定限制基于简单字符串匹配，可以轻易绕过。此功能**不是安全机制**，不应依赖它来安全执行不受信任的代码。建议使用 `coreTools` 显式选择可以执行的命令。
- **`allowMCPServers`**（字符串数组）：
- **描述：** 允许您指定应该提供给CLI的 MCP 服务器名称列表。这可以用来限制要连接的 MCP 服务器集合。注意，如果设置了 `--allowed-mcp-server-names`，此设置将被忽略。
- **默认值：** 所有 MCP 服务器都可供 iFlow CLI使用。
- **示例：** `"allowMCPServers": ["myPythonServer"]`。
- **安全注意：** 这使用 MCP 服务器名称的简单字符串匹配，可以修改。如果您是系统管理员，希望阻止用户绕过此设置，请考虑在系统设置级别配置 `mcpServers`，这样用户将无法配置自己的任何 MCP 服务器。这不应作为严密的安全机制使用。
- **`excludeMCPServers`**（字符串数组）：
- **描述：** 允许您指定应该从CLI中排除的 MCP 服务器名称列表。同时列在 `excludeMCPServers` 和 `allowMCPServers` 中的服务器会被排除。注意，如果设置了 `--allowed-mcp-server-names`，此设置将被忽略。
- **默认值**：不排除任何 MCP 服务器。
- **示例：** `"excludeMCPServers": ["myNodeServer"]`。
- **安全注意：** 这使用 MCP 服务器名称的简单字符串匹配，可以修改。如果您是系统管理员，希望阻止用户绕过此设置，请考虑在系统设置级别配置 `mcpServers`，这样用户将无法配置自己的任何 MCP 服务器。这不应作为严密的安全机制使用。
- **`autoAccept`**（布尔值）：
- **描述：** 控制 CLI 是否自动接受并执行被认为安全的工具调用（如只读操作），而无需显式用户确认。如果设置为 `true`，CLI 将绕过被认为安全的工具的确认提示。
- **默认值：** `false`
- **示例：** `"autoAccept": true`
- **`theme`**（字符串）：
- **描述：** 设置 iFlow CLI 的视觉主题。
- **默认值：** `"Default"`
- **示例：** `"theme": "GitHub"`
- **`vimMode`**（布尔值）：
- **描述：** 启用或禁用输入编辑的 vim 模式。启用后，输入区域支持 vim 风格的导航和编辑命令，具有 NORMAL 和 INSERT 模式。vim 模式状态显示在页脚中，并在会话间持续。
- **默认值：** `false`
- **示例：** `"vimMode": true`
- **`sandbox`**（布尔值或字符串）：
- **描述：** 控制是否以及如何使用沙箱进行工具执行。如果设置为 `true`，iFlow CLI 使用预构建的 `iflow-cli-sandbox` Docker 镜像。更多信息请参见[沙箱](#沙箱)。
- **默认值：** `false`
- **示例：** `"sandbox": "docker"`
- **`mcpServers`**（对象）：
- **描述：** 配置与一个或多个模型上下文协议（MCP）服务器的连接，用于发现和使用自定义工具。iFlow CLI 尝试连接到每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器暴露同名工具，工具名称将以您在配置中定义的服务器别名为前缀（如 `serverAlias__actualToolName`）以避免冲突。注意，系统可能会从 MCP 工具定义中剥离某些模式属性以保持兼容性。
- **默认值：** 空
- **属性：**
- **`<SERVER_NAME>`**（对象）：命名服务器的服务器参数。
- `command`（字符串，必填）：启动 MCP 服务器要执行的命令。
- `args`（字符串数组，可选）：传递给命令的参数。
- `env`（对象，可选）：为服务器进程设置的环境变量。
- `cwd`（字符串，可选）：启动服务器的工作目录。
- `timeout`（数字，可选）：对此 MCP 服务器请求的超时时间（毫秒）。
- `trust`（布尔值，可选）：信任此服务器并绕过所有工具调用确认。
- `includeTools`（字符串数组，可选）：要从此 MCP 服务器包含的工具名称列表。指定时，只有这里列出的工具才可从此服务器使用（白名单行为）。如果未指定，默认启用服务器的所有工具。
- `excludeTools`（字符串数组，可选）：要从此 MCP 服务器排除的工具名称列表。这里列出的工具将不可用于模型，即使它们由服务器暴露。**注意：** `excludeTools` 优先于 `includeTools` - 如果工具在两个列表中，它将被排除。
- **示例：**
```json
"mcpServers": {
"myPythonServer": {
"command": "python",
"args": ["mcp_server.py", "--port", "8080"],
"cwd": "./mcp_tools/python",
"timeout": 5000,
"includeTools": ["safe_tool", "file_reader"],
},
"myNodeServer": {
"command": "node",
"args": ["mcp_server.js"],
"cwd": "./mcp_tools/node",
"excludeTools": ["dangerous_tool", "file_deleter"]
},
"myDockerServer": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"],
"env": {
"API_KEY": "$MY_API_TOKEN"
}
}
}
```
- **`checkpointing`**（对象）：
- **描述：** 配置检查点功能，允许您保存和恢复对话和文件状态。更多详情请参见[检查点文档](../features/checkpointing.md)。
- **默认值：** `{"enabled": false}`
- **属性：**
- **`enabled`**（布尔值）：为 `true` 时，`/restore` 命令可用。
- **`preferredEditor`**（字符串）：
- **描述：** 指定查看差异时使用的首选编辑器。
- **默认值：** `vscode`
- **示例：** `"preferredEditor": "vscode"`
- **`telemetry`**（对象）
- **描述：** 配置 iFlow CLI 的日志记录和指标收集。更多信息请参见[遥测](../features/telemetry.md)。
- **默认值：** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}`
- **属性：**
- **`enabled`**（布尔值）：是否启用可观测性。
- **`target`**（字符串）：收集的可观测性数据的目标。支持的值为 `local` 和 `gcp`。
- **`otlpEndpoint`**（字符串）：OTLP 导出器的端点。
- **`logPrompts`**（布尔值）：是否在日志中包含用户提示的内容。
- **示例：**
```json
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "http://localhost:16686",
"logPrompts": false
}
```
- **`hideTips`**（布尔值）：
- **描述：** 启用或禁用 CLI 界面中的有用提示。
- **默认值：** `false`
- **示例：**
```json
"hideTips": true
```
- **`hideBanner`**（布尔值）：
- **描述：** 启用或禁用 CLI 界面中的启动横幅（ASCII 艺术 logo）。
- **默认值：** `false`
- **示例：**
```json
"hideBanner": true
```
- **`maxSessionTurns`**（数字）：
- **描述：** 设置会话的最大轮数。如果会话超过此限制，CLI 将停止处理并开始新的聊天。
- **默认值：** `-1`（无限制）
- **示例：**
```json
"maxSessionTurns": 10
```
- **`summarizeToolOutput`**（对象）：
- **描述：** 启用或禁用工具输出的摘要。您可以使用 `tokenBudget` 设置指定摘要的令牌预算。
- 注意：目前只支持 `run_shell_command` 工具。
- **默认值：** `{}`（默认禁用）
- **示例：**
```json
"summarizeToolOutput": {
"run_shell_command": {
"tokenBudget": 2000
}
}
```
- **`disableAutoUpdate`**（布尔值）：
- **描述：** 禁用自动更新，设置为true会禁用自动更新功能
- **默认值：** `false`（默认启动自动更新）
- **示例：**
```json
"disableAutoUpdate": true
```
- **`disableTelemetry`**（布尔值）：
- **描述：** 禁用发送遥测数据（目前只发送接口耗时数据）
- **默认值：** `false`（默认发送）
- **示例：**
```json
"disableTelemetry": true
```
- **`tokensLimit`**（数字）：
- **描述：** 用于设置模型的上下文窗口长度
- **默认值：** 128000
- **示例：**
```json
"tokensLimit": 100000
```
- **`compressionTokenThreshold`**（数字）：
- **描述：** 用于控制自动压缩操作触发的阈值
- **默认值：** 0.8
- **示例：**
```json
"compressionTokenThreshold": 0.8
```
- **`useRipgrep`**（布尔值）：
- **描述：** 是否开启Ripgrep
- **默认值：** true
- **示例：**
```json
"useRipgrep": false
```
- **`skipNextSpeakerCheck`**（布尔值）：
- **描述：** 是否跳过任务结束检测
- **默认值：** true
- **示例：**
```json
"skipNextSpeakerCheck": true
```
- **`shellTimeout`**（数字）
- **描述：** shell工具执行的超时时间，单位毫秒
- **默认值：** 120000
- **示例：**
```json
"shellTimeout": 120000
```
### `settings.json` 示例：
```json
{
"selectedAuthType": "iflow",
"apiKey": "sk-xxx",
"baseUrl": "https://apis.iflow.cn/v1",
"modelName": "Qwen3-Coder",
"theme": "GitHub",
"sandbox": "docker",
"toolDiscoveryCommand": "bin/get_tools",
"toolCallCommand": "bin/call_tool",
"mcpServers": {
"mainServer": {
"command": "bin/mcp_server.py"
},
"anotherServer": {
"command": "node",
"args": ["mcp_server.js", "--verbose"]
}
},
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "http://localhost:4317",
"logPrompts": true
},
"usageStatisticsEnabled": true,
"hideTips": false,
"hideBanner": false,
"maxSessionTurns": 10,
"summarizeToolOutput": {
"run_shell_command": {
"tokenBudget": 100
}
}
}
```
## Shell 历史记录
CLI 保存您运行的 shell 命令历史记录。为了避免不同项目之间的冲突，此历史记录存储在用户主文件夹内的项目特定目录中。
- **位置：** `~/.iflow/tmp/<project_hash>/shell_history`
- `<project_hash>` 是从项目根路径生成的唯一标识符。
- 历史记录存储在名为 `shell_history` 的文件中。
## 命令行参数
在运行CLI时传递的命令行参数，可以覆盖当前会话的其他配置。
- **`--model <model_name>`**（**`-m <model_name>`**）：
- 指定当前会话使用的iFlow模型
- 示例：`npm start -- --model Qwen3-Coder`
- **`--prompt <your_prompt>`**（**`-p <your_prompt>`**）：
- 直接传递提示，以非交互模式运行iFlow CLI
- **`--prompt-interactive <your_prompt>`**（**`-i <your_prompt>`**）：
- 以指定提示启动交互式会话
- 提示在交互式会话内处理
- 不支持stdin管道输入
- 示例：`iflow -i "explain this code"`
- **`--sandbox`**（**`-s`**）：
- 为此会话启用沙箱模式。
- **`--sandbox-image`**：
- 设置沙箱镜像 URI。
- **`--debug`**（**`-d`**）：
- 为此会话启用调试模式，提供更详细的输出。
- **`--all-files`**（**`-a`**）：
- 如果设置，递归包含当前目录内的所有文件作为提示的上下文。
- **`--help`**（或 **`-h`**）：
- 显示关于命令行参数的帮助信息。
- **`--show-memory-usage`**：
- 显示当前内存使用情况。
- **`--yolo`**：
- 启用 YOLO 模式，自动批准所有工具调用。
- **`--telemetry`**：
- 启用[可观测性](../features/telemetry.md)。
- **`--telemetry-target`**：
- 设置可观测性目标。更多信息请参见[可观测性](../features/telemetry.md)。
- **`--telemetry-otlp-endpoint`**：
- 设置可观测性的 OTLP 端点。更多信息请参见[可观测性](../features/telemetry.md)。
- **`--telemetry-log-prompts`**：
- 启用可观测性的提示日志记录。更多信息请参见[可观测性](../features/telemetry.md)。
- **`--checkpointing`**：
- 启用[检查点](../features/checkpointing.md)。
- **`--extensions <extension_name ...>`**（**`-e <extension_name ...>`**）：
- 指定会话要使用的扩展列表。如果未提供，则使用所有可用扩展。
- 使用特殊术语 `iflow -e none` 禁用所有扩展。
- 示例：`iflow -e my-extension -e my-other-extension`
- **`--list-extensions`**（**`-l`**）：
- 列出所有可用扩展并退出。
- **`--proxy`**：
- 设置 CLI 的代理。
- 示例：`--proxy http://localhost:7890`。
- **`--include-directories <dir1,dir2,...>`**（**`--add-dir <dir1,dir2,...>`**）：
- 在工作区中包含额外目录以支持多目录。
- 可以多次指定或作为逗号分隔的值。
- 最多可以添加 5 个目录。
- 示例：`--include-directories /path/to/project1,/path/to/project2` 或 `--add-dir /path/to/project1 --add-dir /path/to/project2`
- **`--version`**：
- 显示 CLI 的版本。
## 上下文文件（分层指令上下文）
虽然不严格来说是 CLI _行为_ 的配置，但上下文文件（默认为 `IFLOW.md`，但可通过 `contextFileName` 设置配置）对于配置提供给 iFlow 模型的 _指令上下文_（也称为"内存"）至关重要。这个强大的功能允许您为 AI 提供项目特定的指令、编码风格指南或任何相关背景信息，使其响应更加贴合您的需求。CLI 包含 UI 元素，如页脚中显示已加载上下文文件数量的指示器，让您了解活动上下文。
- **目的：** 这些 Markdown 文件包含您希望 iFlow 模型在交互过程中了解的指令、指南或上下文。系统设计为分层管理此指令上下文。
### 上下文文件内容示例（如 `IFLOW.md`）
以下是 TypeScript 项目根目录中上下文文件可能包含的概念性示例：
```markdown
# 项目：我的优秀 TypeScript 库
## 通用指令：
- 生成新的 TypeScript 代码时，请遵循现有的编码风格。
- 确保所有新函数和类都有 JSDoc 注释。
- 在适当的地方优先使用函数式编程范式。
- 所有代码应与 TypeScript 5.0 和 Node.js 20+ 兼容。
## 编码风格：
- 使用 2 个空格缩进。
- 接口名称应以 `I` 为前缀（如 `IUserService`）。
- 私有类成员应以下划线为前缀（`_`）。
- 始终使用严格相等（`===` 和 `!==`）。
## 特定组件：`src/api/client.ts`
- 此文件处理所有出站 API 请求。
- 添加新的 API 调用函数时，确保它们包含健壮的错误处理和日志记录。
- 对所有 GET 请求使用现有的 `fetchWithRetry` 实用程序。
## 关于依赖项：
- 除非绝对必要，否则避免引入新的外部依赖项。
- 如果需要新依赖项，请说明原因。
```
此示例演示了如何提供通用项目上下文、特定编码约定，甚至关于特定文件或组件的注释。您的上下文文件越相关和精确，AI 就越能更好地协助您。强烈建议使用项目特定的上下文文件来建立约定和上下文。
- **分层加载和优先级：** CLI 通过从多个位置加载上下文文件（如 `IFLOW.md`）实现了复杂的分层内存系统。来自此列表较低位置（更具体）的文件内容通常会覆盖或补充来自较高位置（更通用）的文件内容。可以使用 `/memory show` 命令检查确切的连接顺序和最终上下文。典型的加载顺序是：
1. **全局上下文文件：**
- 位置：`~/.iflow/<contextFileName>`（如用户主目录中的 `~/.iflow/IFLOW.md`）。
- 作用域：为您的所有项目提供默认指令。
2. **项目根目录和祖先上下文文件：**
- 位置：CLI 在当前工作目录中搜索配置的上下文文件，然后在每个父目录中搜索，直到项目根目录（由 `.git` 文件夹标识）或您的主目录。
- 作用域：提供与整个项目或其重要部分相关的上下文。
3. **子目录上下文文件（上下文相关/本地）：**
- 位置：CLI 还在当前工作目录 _下方_ 的子目录中扫描配置的上下文文件（遵循常见的忽略模式，如 `node_modules`、`.git` 等）。此搜索的广度默认限制为 200 个目录，但可以通过 `settings.json` 文件中的 `memoryDiscoveryMaxDirs` 字段配置。
- 作用域：允许与项目的特定组件、模块或子部分相关的高度特定指令。
- **连接和 UI 指示：** 所有找到的上下文文件的内容都会连接（带有指示其来源和路径的分隔符）并作为系统提示的一部分提供给 iFlow 模型。CLI 页脚显示已加载上下文文件的计数，为您提供关于活动指令上下文的快速视觉提示。
- **导入内容：** 您可以通过使用 `@path/to/file.md` 语法导入其他 Markdown 文件来模块化您的上下文文件。
- **内存管理命令：**
- 使用 `/memory refresh` 强制重新扫描和重新加载所有配置位置的上下文文件。这会更新 AI 的指令上下文。
- 使用 `/memory show` 显示当前加载的组合指令上下文，让您验证 AI 使用的层次结构和内容。
通过理解和利用这些配置层级和上下文文件的分层特性，您可以有效管理 AI 的内存，并根据您的特定需求和项目定制 iFlow CLI 的响应。
## /docs_cn/examples/basic-usage.md
---
title: 基础用法
description: iFlow CLI 的基础操作和核心功能
sidebar_position: 2
---
# 基础用法
> **学习目标**：掌握iFlow CLI的日常开发操作
> **预计时间**：15-20分钟
> **前置要求**：已完成 [快速开始](../quickstart) 设置
本文档介绍 iFlow CLI 的基础操作和核心功能，帮助您快速上手并掌握日常开发中最常用的特性。
## 本文档结构
- [核心命令](#核心命令) - 必掌握的基础命令
- [实际使用示例](#实际使用示例) - 具体场景演示
- [最佳实践](#最佳实践) - 高效使用技巧
- [高级技巧](#高级技巧) - 进阶操作方法
- [故障排除](#常见问题) - 常见问题解决
**相关文档**：
- 🔰 新手入门：[快速开始](../quickstart)
- 🚀 进阶学习：[交互模式](../features/interactive)
- 💡 专家技巧：[最佳实践](./best-practices)
## 核心命令
### 初始化命令
`/init` 命令会自动分析您的代码库并生成项目文档：
```
/init
```
**功能特点：**
- 自动识别项目类型和技术栈
- 生成详细的项目结构文档
- 分析依赖关系和配置文件
- 为后续 AI 交互提供上下文
### 清除上下文
使用 `/clear` 命令可以清空对话历史：
```
/clear
```
**使用场景：**
- 开始新的任务或项目
- 优化性能，减少 token 使用
- 保护隐私，清除敏感信息
- 切换项目上下文
### Shell 命令执行
使用 `!` 前缀可以直接在 iFlow CLI 中执行 shell 命令：
```bash
# 查看文件列表
!ls -la
# 运行测试
!npm test
# 检查 git 状态
!git status
# 安装依赖
!npm install express
```
**优势：**
- 命令输出直接集成到 AI 对话中
- AI 可以分析命令结果并提供建议
- 保持 shell 环境和工作目录上下文
## 实际使用示例
### 示例 1：项目初始化
```
用户: /init
AI: 我来分析您的项目结构...
用户: !npm install
AI: 依赖安装完成。根据您的 package.json，这是一个 React 应用。
需要我帮您检查是否有任何配置问题吗？
```
### 示例 2：调试问题
```
用户: !npm test
❌ TypeError: Cannot read property 'name' of undefined
AI: 我看到测试失败了。让我帮您分析这个错误...
这个错误通常发生在访问未定义对象的属性时。
请检查相关代码中的对象是否正确初始化。
用户: 请帮我检查 src/user.js 文件
AI: 好的，我来查看 src/user.js 文件的内容...
```
### 示例 3：代码审查
```
用户: !git diff HEAD~1
AI: 我看到您在最新提交中修改了用户认证逻辑。
让我为您审查这些更改：
1. 正确添加了输入验证
2. 建议添加错误处理
3. 可以考虑使用更安全的密码哈希方法
```
## 最佳实践
### 1. 充分利用上下文
- 使用 `/init` 为项目建立初始上下文
- 让 AI 了解您的项目结构和技术栈
- 在复杂操作前提供必要的背景信息
### 2. 组合使用命令
```
# 先初始化项目
/init
# 然后执行相关操作
!npm run build
# 如果遇到问题，让 AI 帮助分析
请帮我分析构建失败的原因
```
### 3. 有效的对话管理
- 当切换到新任务时使用 `/clear`
- 保持对话专注于特定问题
- 适时提供代码和文件上下文
### 4. 错误处理最佳实践
```
!command_that_might_fail
# 如果命令失败，立即寻求帮助
这个命令失败了，请帮我分析错误原因并提供解决方案
```
## 高级技巧
### 链式命令执行
```
!git add . && git commit -m "Add new feature" && git push
```
### 环境变量和配置
```
!NODE_ENV=production npm start
```
### 管道操作
```
!ps aux | grep node
!ls -la | head -10
```
## 常见问题
### Q: 命令执行失败时该怎么办？
A: 将错误信息复制给 AI，它可以帮您分析原因并提供解决方案。
### Q: 如何提高 AI 回答的准确性？
A: 使用 `/init` 提供项目上下文，并在提问时包含相关的代码片段和错误信息。
### Q: 什么时候应该使用 `/clear`？
A: 当切换到不同项目、开始新任务，或者对话变得过长影响性能时。
---
## 下一步学习路径
完成基础用法学习后，推荐按以下路径继续深入：
### 🎯 立即可学习
- **[交互模式详解](../features/interactive)** - 掌握图片处理、文件引用等高效交互方式
- **[完整命令参考](../features/slash-commands)** - 了解所有可用的斜杠命令
### 💼 实战应用
- **[最佳实践指南](./best-practices)** - 团队协作和工作流优化
- **[高级配置](../configuration/settings)** - 深度定制和性能调优
### 📚 参考资料
- **[术语词汇表](../glossary)** - 查询专业术语定义
---
**需要帮助？**
- 💬 [社区讨论](https://github.com/iflow-ai/iflow-cli/discussions)
- 🐛 [问题反馈](https://github.com/iflow-ai/iflow-cli/issues)
- 📧 [官方文档](https://docs.iflow.cn/)
## /docs_cn/examples/best-practices.md
---
title: 最佳实践
description: iFlow CLI 在实际项目中的高效使用指南
sidebar_position: 9
---
# 最佳实践
本指南汇总了在实际项目中使用 iFlow CLI 的最佳实践，帮助您最大化 AI 助手的效率，避免常见陷阱。
## 开发工作流程最佳实践
### 1. 项目初始化工作流
```
# 标准项目开始流程
/init # 分析项目结构
!git status # 检查当前状态
请帮我制定这个项目的开发计划
```
**为什么这样做？**
- `/init` 为 AI 提供完整的项目上下文
- Git 状态帮助了解当前开发阶段
- 明确的计划请求获得针对性建议
### 2. 功能开发工作流
```
# 开发新功能的标准流程
/clear # 清除之前的上下文
/init # 重新分析项目
我需要实现[具体功能描述]，请帮我分析需要修改哪些文件
!git checkout -b feature/new-feature
# 根据建议进行开发
!npm test # 测试验证
!git add . && git commit -m "Add new feature"
```
### 3. 调试问题工作流
```
# 遇到问题时的标准流程
!npm test # 复现问题
这是错误信息：[粘贴完整错误]
请帮我分析问题原因并提供解决方案
# 根据建议修复
!npm test # 验证修复
```
## 提问技巧
### 有效的提问方式
**好的提问**：
```
我在实现用户认证功能时遇到了问题。这是我的代码：
[粘贴相关代码]
运行测试时出现以下错误：
[粘贴完整错误信息]
我使用的是 Node.js + Express + JWT，请帮我分析问题并提供解决方案。
```
**不好的提问**：
```
代码不工作，帮我修复一下
```
### 提供上下文的技巧
1. **包含相关代码片段**
2. **提供完整的错误信息**
3. **说明技术栈和环境**
4. **描述预期行为 vs 实际行为**
5. **提及已经尝试的解决方案**
## 代码审查最佳实践
### 使用子代理进行代码审查
```
# 开发完成后的审查流程
@code-reviewer 请审查我刚完成的用户登录功能
# 针对特定文件
@code-reviewer 请重点审查 src/auth.js 的安全性
# 针对特定提交
!git show HEAD
@code-reviewer 请审查这次提交的更改
```
### 安全审查检查清单
在提交代码前，确保检查：
- [ ] 输入验证和消毒
- [ ] 身份验证和授权
- [ ] 敏感信息处理
- [ ] 错误处理和日志记录
- [ ] SQL 注入防护
- [ ] XSS 攻击预防
## 测试驱动开发
### 测试优先的工作流程
```
# TDD 工作流程
我要实现[功能描述]，请先帮我编写测试用例
# 编写测试
!npm test # 运行测试（应该失败）
请帮我实现能通过这些测试的代码
# 实现功能
!npm test # 验证测试通过
@code-reviewer 请审查实现的代码
```
### 测试覆盖率提升
```
!npm run coverage # 检查当前覆盖率
请帮我为覆盖率不足的文件添加测试：
[列出需要测试的文件和函数]
```
## 重构最佳实践
### 安全重构流程
```
# 重构前的准备
!npm test # 确保所有测试通过
!git add . && git commit -m "Pre-refactor checkpoint"
# 开始重构
我想重构这个函数来提高可读性和性能：
[粘贴函数代码]
请提供重构建议，保持相同的功能
# 重构后验证
!npm test # 确保功能不变
@code-reviewer 请审查重构后的代码
```
### 性能优化策略
```
# 性能分析
!npm run benchmark # 运行性能测试
请分析性能瓶颈并提供优化建议
# 实施优化
!npm run benchmark # 对比优化效果
```
## 文档编写最佳实践
### API 文档生成
```
请帮我为这个 API 端点生成 OpenAPI 文档：
[粘贴 API 代码]
格式要求：
- 包含请求/响应示例
- 详细的参数说明
- 错误处理说明
```
### README 文档维护
```
请帮我更新 README.md，包含：
1. 最新的功能介绍
2. 安装和使用说明
3. API 文档链接
4. 贡献指南
基于当前项目结构：
/init
```
## 环境管理
### 多环境配置
```
# 开发环境
!NODE_ENV=development npm start
# 生产环境部署检查
请帮我检查生产环境配置的安全性和性能
[显示配置文件内容]
```
### 依赖管理
```
# 依赖更新
!npm outdated # 检查过期依赖
请分析这些依赖更新的风险和收益
!npm audit # 安全审计
请帮我修复发现的安全漏洞
```
## 故障排除指南
### 常见问题解决
1. **AI 回答不准确**
- 使用 `/clear` 清除不相关上下文
- 提供更多具体信息
- 使用 `/init` 重新建立项目上下文
2. **命令执行失败**
- 检查工作目录是否正确
- 确认依赖是否已安装
- 查看完整错误信息
3. **性能问题**
- 定期使用 `/clear` 清理上下文
- 避免过长的代码粘贴
- 分解复杂问题为小步骤
### 调试技巧
```
# 系统信息收集
!node --version && npm --version && git --version
!pwd && ls -la
# 日志分析
!tail -n 50 logs/app.log
请帮我分析这些日志中的异常模式
```
## 效率提升技巧
### 1. 使用模板和片段
创建常用代码模板：
```
请帮我创建一个 Express.js 路由模板，包含：
- 输入验证
- 错误处理
- 日志记录
- 单元测试
```
### 2. 批量操作
```
# 批量文件处理
请帮我为以下文件添加 TypeScript 类型定义：
!find src -name "*.js" | head -10
```
### 3. 自动化脚本生成
```
请帮我创建一个部署脚本，包含：
1. 代码检查和测试
2. 构建优化
3. 数据库迁移
4. 服务重启
5. 健康检查
```
## 团队协作最佳实践
### 代码规范统一
```
请帮我配置项目的代码规范工具：
- ESLint 配置
- Prettier 配置
- Git hooks 设置
- CI/CD 集成
```
### 知识分享
```
请帮我总结这次功能开发的关键点：
1. 技术选型理由
2. 遇到的主要挑战
3. 解决方案和最佳实践
4. 对团队的建议
生成团队分享文档
```
## 安全最佳实践
### 敏感信息处理
- 永远不要在对话中粘贴真实的 API 密钥、密码或其他敏感信息
- 使用占位符或示例值
- 定期使用 `/clear` 清除可能包含敏感信息的上下文
### 代码安全检查
```
@security-auditor 请检查以下代码的安全性：
[粘贴代码，移除敏感信息]
重点关注：
- 输入验证
- 权限控制
- 数据加密
- 错误处理
```
---
**记住**：好的实践需要持续应用和改进。根据项目特点和团队需求调整这些建议，找到最适合的工作流程！
## /docs_cn/examples/hooks.md
---
title: Hooks
description: 配置 Hooks，允许 iFlow CLI 在特定事件发生时自动执行自定义命令
sidebar_position: 7
---
# Hooks 配置
## 概述
Hooks（钩子）是 iFlow CLI 中的事件驱动机制，允许您在特定的生命周期事件发生时自动执行自定义命令。通过配置 Hooks，您可以实现工具调用前后的自动化处理、环境设置增强、会话停止时的清理操作等功能。
### 主要功能
- **工具调用拦截**：在工具执行前后运行自定义逻辑
- **环境增强**：在会话开始时动态设置环境信息
- **生命周期管理**：在会话或子代理停止时执行清理操作
- **灵活配置**：支持用户级和项目级的分层配置
- **安全控制**：可阻止工具执行或修改工具行为
## Hook 类型
iFlow CLI 支持以下 9 种 Hook 类型：
### 1. PreToolUse Hook
**触发时机**：在工具执行之前
**用途**：
- 验证工具参数
- 设置执行环境
- 记录工具调用日志
- 阻止不安全的操作
**示例配置**：
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "echo 'File edit detected'"
}
]
}
]
}
}
```
### 2. PostToolUse Hook
**触发时机**：在工具执行之后
**用途**：
- 处理工具执行结果
- 清理临时文件
- 发送通知
- 记录执行统计
**示例配置**：
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "write_file",
"hooks": [
{
"type": "command",
"command": "echo 'File operation completed'"
}
]
}
]
}
}
```
### 3. SetUpEnvironment Hook
**触发时机**：会话开始时，环境信息设置阶段
**用途**：
- 动态生成项目信息
- 设置运行时环境变量
- 增强 AI 的上下文信息
- 加载项目特定配置
**示例配置**：
```json
{
"hooks": {
"SetUpEnvironment": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Session environment initialized'"
}
]
}
]
}
}
```
### 4. Stop Hook
**触发时机**：主会话结束时
**用途**：
- 清理会话资源
- 保存会话信息
- 发送会话总结
- 执行清理脚本
**示例配置**：
```json
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Main session ended'"
}
]
}
]
}
}
```
### 5. SubagentStop Hook
**触发时机**：子代理会话结束时
**用途**：
- 清理子代理资源
- 记录子任务执行情况
- 合并子任务结果
- 执行子任务后处理
**示例配置**：
```json
{
"hooks": {
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Subagent task completed'"
}
]
}
]
}
}
```
### 6. SessionStart Hook
**触发时机**：会话开始时（启动、恢复、清理、压缩）
**用途**：
- 初始化会话环境
- 设置日志记录
- 发送会话开始通知
- 执行启动时的预处理
**支持matcher**：是 - 可以根据会话启动来源进行匹配（startup、resume、clear、compress）
**示例配置**：
```json
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "echo 'New session started'"
}
]
}
]
}
}
```
### 7. SessionEnd Hook
**触发时机**：会话正常结束时
**用途**：
- 生成会话总结报告
- 备份会话数据
- 发送会话结束通知
- 执行会话清理操作
**示例配置**：
```json
{
"hooks": {
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "python3 ~/.iflow/hooks/session_report.py",
"timeout": 30
}
]
}
]
}
}
```
### 8. UserPromptSubmit Hook
**触发时机**：用户提交提示词之前，在iFlow处理之前
**用途**：
- 内容过滤和审核
- 提示词预处理和增强
- 阻止不当的用户输入
- 记录用户交互日志
**支持matcher**：是 - 可以根据提示词内容进行匹配
**特殊行为**：可以阻止提示词提交（返回非零退出码）
**示例配置**：
```json
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": ".*sensitive.*",
"hooks": [
{
"type": "command",
"command": "python3 ~/.iflow/hooks/content_filter.py",
"timeout": 10
}
]
}
]
}
}
```
### 9. Notification Hook
**触发时机**：当iFlow向用户发送通知时
**用途**：
- 通知内容记录
- 第三方系统集成
- 通知格式转换
- 自定义通知处理
**支持matcher**：是 - 可以根据通知消息内容进行匹配
**特殊行为**：退出码2不阻止通知，仅将stderr显示给用户
**示例配置**：
```json
{
"hooks": {
"Notification": [
{
"matcher": ".*permission.*",
"hooks": [
{
"type": "command",
"command": "echo 'Permission notification logged' >> ~/.iflow/permission.log"
}
]
}
]
}
}
```
## 配置方式
### 1. 配置层级
Hooks 配置遵循 iFlow CLI 的分层配置系统：
- **用户配置**：`~/.iflow/settings.json`
- **项目配置**：`./.iflow/settings.json`
- **系统配置**：系统级配置文件
高层级的配置会与低层级配置合并，项目配置会补充用户配置。
### 2. 配置格式
在 `settings.json` 文件中添加 `hooks` 配置项：
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "tool_pattern",
"hooks": [
{
"type": "command",
"command": "your_command",
"timeout": 30
}
]
}
],
"PostToolUse": [
{
"matcher": "another_pattern",
"hooks": [
{
"type": "command",
"command": "cleanup_command"
}
]
}
],
"SetUpEnvironment": [
{
"hooks": [
{
"type": "command",
"command": "python ~/.iflow/hooks/env_enhancer.py",
"timeout": 30
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Session ended'"
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "cleanup_subagent.sh"
}
]
}
],
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "echo 'Session initialized'"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "python ~/.iflow/hooks/session_summary.py"
}
]
}
],
"UserPromptSubmit": [
{
"matcher": ".*sensitive.*",
"hooks": [
{
"type": "command",
"command": "python ~/.iflow/hooks/content_filter.py"
}
]
}
],
"Notification": [
{
"matcher": ".*permission.*",
"hooks": [
{
"type": "command",
"command": "logger 'iFlow permission request'"
}
]
}
]
}
}
```
### 3. Hook 配置项说明
每个 Hook 类型包含一个配置数组，每个配置项包含：
#### 通用字段
- **`hooks`** (必需)：Hook 命令数组，每个命令包含：
- **`type`**：命令类型，目前仅支持 `"command"`
- **`command`**：要执行的命令字符串
- **`timeout`**：超时时间（秒），可选，默认无超时
#### 工具相关 Hook（PreToolUse/PostToolUse）专用字段
- **`matcher`**：工具匹配模式，用于指定Hook应该在哪些工具执行时触发
##### 匹配模式
| 匹配模式 | 语法示例 | 说明 |
|---------|---------|------|
| 通配符匹配 | `"*"` 或 `""` | 匹配所有工具（默认行为） |
| 精确匹配 | `"Edit"` | 只匹配名为"Edit"的工具或别名 |
| 正则表达式 | `"Edit\|MultiEdit\|Write"` | 匹配多个工具名或别名 |
| 模式匹配 | `".*_file"` | 匹配以"_file"结尾的工具名 |
| MCP工具匹配 | `"mcp__.*"` | 匹配所有MCP工具 |
| MCP服务器匹配 | `"mcp__github__.*"` | 匹配特定MCP服务器的所有工具 |
##### 匹配规则
- **大小写敏感**：matcher匹配是区分大小写的
- **正则表达式**：包含 `|\\^$.*+?()[]{}` 等字符时自动识别为正则表达式
- **工具别名**：匹配时会同时检查工具名和别名
- **错误处理**：无效的正则表达式会回退到精确匹配模式
##### Hook类型与matcher支持
| Hook类型 | 支持matcher | 说明 |
|----------|-------------|------|
| PreToolUse | ✅ | 可以指定匹配特定工具 |
| PostToolUse | ✅ | 可以指定匹配特定工具 |
| SetUpEnvironment | ❌ | 始终执行，不支持matcher |
| Stop | ❌ | 始终执行，不支持matcher |
| SubagentStop | ❌ | 始终执行，不支持matcher |
| SessionStart | ✅ | 可以根据会话启动来源匹配（startup、resume、clear、compress） |
| SessionEnd | ❌ | 始终执行，不支持matcher |
| UserPromptSubmit | ✅ | 可以根据用户提示词内容匹配 |
| Notification | ✅ | 可以根据通知消息内容匹配 |
##### 常用工具名称参考
| 工具类别 | 实际工具名 | 常用别名 |
|---------|-----------|----------|
| 文件编辑 | `replace` | `Edit`, `edit`, `Write`, `write` |
| 批量编辑 | `multi_edit` | `MultiEdit`, `multiEdit` |
| 文件写入 | `write_file` | `write`, `create`, `save` |
| 文件读取 | `read_file` | `read` |
| Shell执行 | `run_shell_command` | `shell`, `Shell`, `bash`, `Bash` |
| 文件搜索 | `search_file_content` | `grep`, `search` |
| 目录列表 | `list_directory` | `ls`, `list` |
#### 特殊约束
- **SetUpEnvironment Hook**：不支持 `matcher` 字段，对所有会话生效
- **Stop/SubagentStop/SessionEnd Hook**：不支持 `matcher` 字段，在相应生命周期结束时执行
- **UserPromptSubmit Hook**：可通过返回非零退出码阻止提示词提交
- **Notification Hook**：退出码2有特殊含义，不阻止通知显示，仅将stderr内容显示给用户
## 复杂配置示例
### 1. 文件保护 Hook
**Python脚本 (file_protection.py)**：
```python
import json, sys
data = json.load(sys.stdin)
file_path = data.get('tool_input', {}).get('file_path', '')
sensitive_files = ['.env', 'package-lock.json', '.git/']
sys.exit(2 if any(p in file_path for p in sensitive_files) else 0)
```
**功能描述**：在文件编辑操作执行前进行安全检查，阻止对敏感文件的修改操作。
**前置依赖**：
- 系统需要安装 `python3`
- 确保Python能够正常执行并访问标准输入
**具体功能**：
- 监控所有文件编辑操作（Edit、MultiEdit、Write工具）
- 检查目标文件路径是否包含敏感文件（.env、package-lock.json、.git/目录）
- 如果检测到敏感文件，返回退出码2阻止工具执行
- 提供文件操作的安全防护，避免意外修改重要配置文件
**Hook配置**：
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "python3 file_protection.py",
"timeout": 10
}
]
}
]
}
}
```
### 2. TypeScript 代码格式化
**功能描述**：在文件编辑操作完成后自动对TypeScript文件进行代码格式化，确保代码风格的一致性。
**前置依赖**：
- 系统需要安装 `jq` 工具（用于JSON数据处理）
- 需要安装 `prettier` 代码格式化工具（`npm install -g prettier` 或项目本地安装）
- 确保项目中有prettier配置文件或使用默认配置
**具体功能**：
- 监控文件编辑和写入操作（Edit、MultiEdit、write_file工具）
- 从工具参数中提取文件路径信息
- 检查文件是否为TypeScript文件（.ts扩展名）
- 对符合条件的文件自动执行prettier格式化
- 提升代码质量和团队协作效率
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "bash -c 'path=$(jq -r \".tool_input.file_path\"); [[ $path == *.ts ]] && npx prettier --write \"$path\"'",
"timeout": 30
}
]
}
]
}
}
```
### 3. 会话管理与性能监控
**Python脚本 (session_summary.py)**：
```python
import os, datetime, subprocess
session_id = os.environ.get('IFLOW_SESSION_ID', 'unknown')
timestamp = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
summary_dir = os.path.expanduser('~/.iflow/session-summaries')
os.makedirs(summary_dir, exist_ok=True)
try:
git_log = subprocess.check_output(['git', 'log', '--oneline', '-3']).decode().strip()
except:
git_log = 'No git repository'
summary_content = f'# Session Summary\\n\\n**ID:** {session_id}\\n**Time:** {timestamp}\\n\\n**Git Log:**\\n```\\n{git_log}\\n```'
with open(f'{summary_dir}/session-{session_id}.md', 'w') as f:
f.write(summary_content)
```
**功能描述**：在会话结束时自动生成会话总结，在子代理结束时记录性能指标，实现完整的会话生命周期管理。
**前置依赖**：
- 系统需要安装 `python3`
- 需要 `git` 命令（用于获取仓库活动信息）
- 确保有足够的磁盘空间存储会话总结和性能数据
**具体功能**：
- **会话总结生成**：在主会话结束时生成包含会话ID、结束时间、工作目录和近期Git活动的Markdown总结文件
- **性能指标收集**：记录子代理的运行时间、类型、成功状态等性能数据到JSONL格式文件
- **自动目录创建**：自动创建 `~/.iflow/session-summaries` 和 `~/.iflow/metrics` 目录
- **环境变量支持**：利用 `IFLOW_SESSION_ID`、`IFLOW_AGENT_TYPE`、`IFLOW_SUBAGENT_START_TIME` 等环境变量
- **容错处理**：Git命令失败时提供默认值，确保总结生成不被中断
**Hook配置**：
```json
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "python3 session_summary.py",
"timeout": 15
}
]
}
]
}
}
```
### 4. 用户输入内容过滤
**Python脚本 (content_filter.py)**：
```python
import json, sys, re
data = json.load(sys.stdin)
prompt = data.get('prompt', '')
# 检查是否包含敏感信息
sensitive_patterns = [
r'password\s*[=:]\s*\S+',
r'api[_-]?key\s*[=:]\s*\S+',
r'secret\s*[=:]\s*\S+',
r'\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b' # 信用卡号
]
for pattern in sensitive_patterns:
if re.search(pattern, prompt, re.IGNORECASE):
print(f"检测到敏感信息，请移除后重新提交", file=sys.stderr)
sys.exit(1) # 阻止提示词提交
print("内容审核通过")
```
**功能描述**：在用户提交提示词前进行内容过滤，检测并阻止包含敏感信息的输入。
**前置依赖**：
- 系统需要安装 `python3`
- 确保Python的正则表达式模块可用
**具体功能**：
- 监控用户提交的所有提示词内容
- 使用正则表达式检测密码、API密钥、信用卡号等敏感信息
- 如果检测到敏感内容，返回退出码1阻止提示词提交
- 提供清晰的错误信息指导用户修改输入
- 保护用户隐私和数据安全
**Hook配置**：
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python3 content_filter.py",
"timeout": 5
}
]
}
]
}
}
```
### 5. 通知处理与集成
**Bash脚本 (notification_handler.sh)**：
```bash
#!/bin/bash
# 从stdin读取通知信息
notification_data=$(cat)
message=$(echo "$notification_data" | jq -r '.message // "Unknown message"')
timestamp=$(date '+%Y-%m-%d %H:%M:%S')
# 记录到日志文件
echo "[$timestamp] iFlow Notification: $message" >> ~/.iflow/notifications.log
# 如果是权限请求，发送到Slack
if [[ "$message" == *"permission"* ]]; then
curl -X POST -H 'Content-type: application/json' \
--data "{\"text\":\"iFlow Permission Request: $message\"}" \
"$SLACK_WEBHOOK_URL" 2>/dev/null || true
fi
# 如果是错误通知，发送邮件告警
if [[ "$message" == *"error"* ]] || [[ "$message" == *"failed"* ]]; then
echo "iFlow Error: $message" | mail -s "iFlow Alert" admin@company.com 2>/dev/null || true
fi
```
**功能描述**：处理iFlow的通知消息，实现日志记录和第三方系统集成。
**前置依赖**：
- 系统需要安装 `jq`、`curl`、`mail` 命令
- 配置 `SLACK_WEBHOOK_URL` 环境变量
- 配置邮件系统
**具体功能**：
- 捕获所有iFlow通知消息
- 将通知记录到本地日志文件
- 对权限请求类通知自动发送到Slack频道
- 对错误类通知发送邮件告警
- 支持多种通知渠道集成
**Hook配置**：
```json
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "bash ~/.iflow/hooks/notification_handler.sh",
"timeout": 10
}
]
}
]
}
}
```
### 6. Git状态环境增强器
**Python脚本 (git_status.py)**：
```python
import subprocess, os
try:
branch = subprocess.check_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD']).decode().strip()
status = subprocess.check_output(['git', 'status', '--porcelain']).decode().strip()
commit = subprocess.check_output(['git', 'log', '-1', '--oneline']).decode().strip()
print(f'## Git信息\\n\\n**分支:** {branch}\\n**状态:** {"干净" if not status else "有变更"}\\n**最新提交:** {commit}')
except:
print('## Git信息\\n\\n未找到Git仓库')
```
**功能描述**：在会话开始时自动获取并展示当前Git仓库的详细状态信息，为AI提供项目背景上下文。
**前置依赖**：
- 系统需要安装 `python3`
- 需要 `git` 命令和有效的Git仓库
- 确保当前工作目录位于Git仓库中
- 需要对仓库有读取权限
**具体功能**：
- **分支信息获取**：自动识别并显示当前所在的Git分支名称
- **工作目录状态**：检查并显示工作目录中的未提交更改（修改、新增、删除的文件）
- **最新提交信息**：获取并显示最近一次提交的简要信息（哈希值和提交消息）
- **格式化输出**：将Git状态信息格式化为清晰的Markdown格式，便于AI理解项目当前状态
- **状态判断**：自动判断工作目录是否干净，分别显示不同的状态信息
- **增强AI上下文**：帮助AI更好地理解项目的版本控制状态，做出更合适的决策
**Hook配置**：
```json
{
"hooks": {
"SetUpEnvironment": [
{
"hooks": [
{
"type": "command",
"command": "python3 git_status.py",
"timeout": 10
}
]
}
]
}
}
```
## Hook 执行机制
### 1. 执行流程
1. **事件触发**：当相应的生命周期事件发生时
2. **匹配检查**：检查 Hook 配置的匹配条件（如工具名称）
3. **并行执行**：符合条件的 Hook 命令并行执行
4. **结果处理**：收集执行结果和输出
5. **错误处理**：处理执行失败的情况
### 2. 执行环境
Hook 命令在以下环境中执行：
- **工作目录**：当前 iFlow CLI 工作目录
- **环境变量**：继承 iFlow CLI 的环境变量
- **通用特殊变量**：
- `IFLOW_SESSION_ID`：当前会话ID（所有Hook）
- `IFLOW_TRANSCRIPT_PATH`：会话记录文件路径（所有Hook）
- `IFLOW_CWD`：当前工作目录（所有Hook）
- `IFLOW_HOOK_EVENT_NAME`：触发的Hook事件名称（所有Hook）
- **工具相关Hook专用变量**：
- `IFLOW_TOOL_NAME`：当前工具名称（PreToolUse/PostToolUse Hook）
- `IFLOW_TOOL_ARGS`：工具参数的 JSON 字符串（PreToolUse/PostToolUse Hook）
- `IFLOW_TOOL_ALIASES`：工具别名数组的 JSON 字符串（PreToolUse/PostToolUse Hook）
- **会话相关Hook专用变量**：
- `IFLOW_SESSION_SOURCE`：会话启动来源，如startup、resume、clear、compress（SessionStart Hook）
- **用户输入Hook专用变量**：
- `IFLOW_USER_PROMPT`：用户提交的原始提示词内容（UserPromptSubmit Hook）
- **通知Hook专用变量**：
- `IFLOW_NOTIFICATION_MESSAGE`：通知消息内容（Notification Hook）
### 3. 返回值处理
- **可阻塞执行的Hook**：
- **PreToolUse Hook**：返回码非0阻止工具执行，显示错误信息
- **UserPromptSubmit Hook**：返回码非0阻止提示词提交，显示错误信息
- **特殊处理的Hook**：
- **Notification Hook**：
- 返回码0：正常处理，显示标准输出
- 返回码2：不阻止通知显示，仅将stderr内容显示给用户
- 其他返回码：显示警告信息，但不影响通知流程
- **其他 Hook**：
- 返回码不影响主流程
- 错误输出会显示警告信息
- 标准输出会显示给用户
### 4. 超时处理
- 配置了 `timeout` 的 Hook 会在指定时间后终止
- 超时不会中断主流程，但会记录警告
- 未配置超时的 Hook 使用系统默认超时
## 高级功能
### 1. 条件执行
通过在 Hook 脚本中添加条件判断：
```bash
#!/bin/bash
# 只在 Git 仓库中执行
if [ -d ".git" ]; then
echo "在 Git 仓库中执行特殊操作"
# 你的逻辑
fi
```
### 2. 参数传递
Hook 可以通过环境变量接收相关参数：
```python
import os
import json
# 通用环境变量（所有Hook可用）
session_id = os.environ.get('IFLOW_SESSION_ID', '')
hook_event = os.environ.get('IFLOW_HOOK_EVENT_NAME', '')
cwd = os.environ.get('IFLOW_CWD', '')
print(f"会话ID: {session_id}")
print(f"Hook事件: {hook_event}")
print(f"工作目录: {cwd}")
# 工具相关Hook专用变量
if hook_event in ['PreToolUse', 'PostToolUse']:
tool_args = json.loads(os.environ.get('IFLOW_TOOL_ARGS', '{}'))
tool_name = os.environ.get('IFLOW_TOOL_NAME', '')
print(f"工具名称: {tool_name}")
print(f"工具参数: {tool_args}")
# 用户输入Hook专用变量
if hook_event == 'UserPromptSubmit':
user_prompt = os.environ.get('IFLOW_USER_PROMPT', '')
print(f"用户提示词: {user_prompt}")
# 通知Hook专用变量
if hook_event == 'Notification':
notification_message = os.environ.get('IFLOW_NOTIFICATION_MESSAGE', '')
print(f"通知消息: {notification_message}")
# 会话启动Hook专用变量
if hook_event == 'SessionStart':
session_source = os.environ.get('IFLOW_SESSION_SOURCE', '')
print(f"会话启动来源: {session_source}")
```
### 3. 输出处理
Hook 的标准输出会显示给用户：
```bash
#!/bin/bash
echo "INFO: 开始执行预处理"
echo "WARNING: 检测到潜在风险"
echo "ERROR: 操作被阻止" >&2 # 错误输出
exit 1 # 阻止工具执行（仅 PreToolUse Hook）
```
### 4. 配置验证
iFlow CLI 会在启动时验证 Hook 配置：
- 检查 JSON 格式正确性
- 验证必需字段存在
- 检查字段类型和值范围
- 验证 Hook 类型特定约束
## 故障排除
### 1. Hook 不执行
**可能原因**：
- 配置文件格式错误
- 匹配模式不正确
- Hook 脚本路径错误
- 权限不足
**排查步骤**：
1. 检查 `settings.json` 格式
2. 验证 Hook 脚本是否存在且可执行
3. 查看 iFlow CLI 错误日志
4. 使用简单的测试 Hook 验证配置
### 2. Hook 执行失败
**可能原因**：
- 脚本语法错误
- 依赖程序不存在
- 权限不足
- 超时
**排查步骤**：
1. 手动执行 Hook 脚本测试
2. 检查脚本依赖是否安装
3. 增加 Hook 脚本的调试输出
4. 调整超时设置
### 3. 性能问题
**优化建议**：
- 减少不必要的 Hook
- 优化 Hook 脚本性能
- 设置合理的超时时间
- 避免阻塞操作
### 4. 调试技巧
#### 启用详细日志
```bash
export IFLOW_DEBUG=1
iflow
```
#### 创建测试 Hook
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "echo \"Hook 触发: $IFLOW_TOOL_NAME\""
}
]
}
]
}
}
```
#### 输出调试信息
```bash
#!/bin/bash
echo "DEBUG: Hook 开始执行"
echo "DEBUG: 工具名称: $IFLOW_TOOL_NAME"
echo "DEBUG: 工具参数: $IFLOW_TOOL_ARGS"
echo "DEBUG: 当前目录: $(pwd)"
echo "DEBUG: Hook 执行完成"
```
## 安全注意事项
### 1. 脚本安全
- **验证输入**：始终验证从环境变量获取的数据
- **路径检查**：避免路径注入攻击
- **权限最小化**：Hook 脚本使用最小必要权限
### 2. 执行环境
- **沙箱化**：考虑在受限环境中执行 Hook
- **资源限制**：设置合理的超时和资源限制
- **错误隔离**：Hook 错误不应影响主要功能
### 3. 配置安全
- **配置验证**：启动时验证 Hook 配置
- **路径限制**：限制 Hook 脚本的存放路径
- **权限检查**：检查配置文件和脚本权限
## 最佳实践
### 1. 配置管理
- **版本控制**：项目级 Hook 配置纳入版本控制
- **文档说明**：为每个 Hook 添加清晰的说明
- **模块化**：将相关 Hook 逻辑组织到独立脚本中
### 2. 脚本编写
- **错误处理**：添加完善的错误处理逻辑
- **日志记录**：记录 Hook 执行的关键信息
- **性能优化**：避免不必要的重复操作
### 3. 测试验证
- **单元测试**：为 Hook 脚本编写测试
- **集成测试**：测试 Hook 与 iFlow CLI 的集成
- **回归测试**：确保 Hook 更改不影响现有功能
### 4. 监控维护
- **执行监控**：监控 Hook 执行状态和性能
- **定期评审**：定期评审和更新 Hook 配置
- **文档维护**：保持 Hook 文档的及时更新
通过合理配置和使用 Hooks，您可以显著扩展 iFlow CLI 的功能，实现更加智能化和自动化的开发工作流程。Hook 系统提供了强大的扩展能力，让您能够根据具体需求定制 AI 助手的行为。
## /docs_cn/examples/index.md
---
title: 示例与教程
description: 通过实际示例学习如何使用 iFlow CLI
sidebar_position: 1
---
# 示例与教程
## 学习目标
从新手到专家，掌握iFlow CLI的完整技能栈
## 文档结构
渐进式学习路径 + 场景化快速导航
## 用户画像导航
根据您的使用经验，选择合适的学习路径：
### 初学者路径（首次使用）
**目标**：从零开始，30分钟内掌握基础操作
1. **[5分钟快速开始](../quickstart)** - 必读
- 安装配置、运行第一个任务
2. **[基础操作指南](./basic-usage)**
- 核心命令、Shell集成、项目初始化
3. **[交互模式详解](../features/interactive)**
- 文本输入、图片处理、文件引用
**验收标准**：能独立完成项目分析和简单的代码生成任务
### 进阶用户路径（有基础经验）
**目标**：扩展功能，提升工作效率
1. **[MCP扩展系统](../examples/mcp.md)**
- 安装插件、连接外部工具
2. **[子代理配置](../examples/subagent.md)**
- 专业领域助手、任务专门化
3. **[高级功能特性](/cli/features/interactive)**
- 命令大全、内容管理、检查点
**验收标准**：能配置专业化工作环境，处理复杂开发任务
### 专家用户路径（团队使用）
**目标**：优化团队协作，建立最佳实践
1. **[最佳实践指南](./best-practices)**
- 工作流优化、团队协作
2. **[配置管理](/cli/configuration/settings)**
- 高级设置、快捷键定制
**验收标准**：能制定团队规范，解决复杂技术问题
## 场景化快速导航
根据具体需求，快速找到相关文档：
### 按工作场景分类
| 工作场景 | 核心功能 | 推荐文档 | 时间投入 |
|---------|---------|----------|----------|
| **Web开发** | 代码生成、调试、重构 | [基础操作](./basic-usage) | 15分钟 |
| **数据分析** | 文件处理、脚本自动化 | [交互模式](../features/interactive) | 10分钟 |
| **DevOps** | 脚本执行、工具集成 | [MCP扩展](../examples/mcp.md) | 20分钟 |
| **学习研究** | 文档分析、知识整理 | [子代理配置](../examples/subagent.md) | 15分钟 |
| **团队协作** | 规范制定、知识共享 | [最佳实践](./best-practices) | 25分钟 |
### 按技能需求分类
| 我想学会... | 主要内容 | 前置要求 | 文档链接 |
|-------------|----------|----------|----------|
| **基础命令使用** | `/init`、`/clear`、Shell集成 | 完成快速开始 | [基础操作](./basic-usage) |
| **多模态交互** | 图片处理、文件粘贴 | 基础命令 | [交互模式](../features/interactive) |
| **功能扩展** | MCP插件、外部工具 | 基础命令 | [MCP扩展](../examples/mcp.md) |
| **专业化配置** | 领域助手、任务优化 | MCP扩展 | [子代理配置](../examples/subagent.md) |
| **高效工作流** | 团队协作、最佳实践 | 专业化配置 | [最佳实践](./best-practices) |
### 按问题类型分类
| 遇到的问题 | 可能原因 | 解决方案 | 参考文档 |
|------------|----------|----------|----------|
| 安装失败 | Node.js版本、网络问题 | 环境检查 | [快速开始-故障排除](../quickstart#故障排除) |
| 命令不响应 | 网络延迟、token耗尽 | 重置连接 | [基础操作-错误处理](./basic-usage#错误处理最佳实践) |
| 功能受限 | 认证方式、模型限制 | 升级配置 | [配置管理](../configuration/settings) |
| 性能问题 | 上下文过长、插件冲突 | 优化设置 | [最佳实践-性能优化](./best-practices#性能优化) |
## 学习资源地图
```
iFlow CLI 完整技能树
│
├── 核心技能（必掌握）
│ ├── 快速开始 → 5分钟上手
│ ├── 基础操作 → 日常使用
│ └── 交互模式 → 高效交互
│
├── 扩展技能（进阶）
│ ├── MCP系统 → 功能扩展
│ ├── 子代理 → 专业化
│ └── 高级配置 → 定制优化
│
└── 实战技能（专家）
├── 最佳实践 → 工作流优化
├── 团队协作 → 规范制定
└── 故障排除 → 问题解决
```
## 文档使用约定
### 符号说明
- `!command` - iFlow CLI中执行的shell命令
- `/command` - iFlow CLI内置斜杠命令
- `> 输入` - 用户输入示例
- **提示** - 有用的技巧和最佳实践
- **注意** - 重要的警告和限制事项
- 重点标记 - 强烈推荐阅读
- 初学者标记 - 新手适用
- 进阶标记 - 进阶内容
- 专家标记 - 专家级内容
### 时间预估说明
- **阅读时间**：纯阅读文档所需时间
- **实践时间**：跟随教程操作的时间
- **掌握时间**：能熟练应用的总时间
## 下一步建议
### 如果您是第一次使用
从 [快速开始](../quickstart) 开始，这是专门设计的5分钟上手指南
### 如果您已完成快速开始
根据上述用户画像，选择适合的学习路径继续深入
### 如果您遇到具体问题
使用场景化导航表格，快速定位解决方案
---
**获得帮助**：[提交反馈](https://github.com/iflow-ai/iflow-cli/issues) | [社区讨论](https://github.com/iflow-ai/iflow-cli/discussions)
## /docs_cn/examples/keyboard-shortcuts.md
---
sidebar_position: 3
hide_title: true
---
# 键盘快捷键
本文档为您详细介绍在命令行界面中可以使用的各种快捷键，帮助您更高效地与AI进行交互。
## 使用说明
本指南按功能模块分类，每个快捷键都配有详细说明。建议您先熟悉基础快捷键，再逐步掌握高级功能。
## 基础功能快捷键
以下是最常用的基础快捷键，建议优先掌握：
| 快捷键 | 功能说明 | 使用场景 |
| ------ | -------- | -------- |
| `Esc` | 关闭对话框和建议窗口 | 想要取消当前操作时 |
| `Ctrl+C` | 退出应用程序（需按两次确认） | 结束CLI会话 |
| `Ctrl+D` | 输入为空时退出应用（需按两次确认） | 快速退出空白状态 |
| `Ctrl+L` | 清屏 | 界面内容过多时清理屏幕 |
| `Ctrl+S` | 显示完整响应内容，禁用截断 | 查看长回复的完整内容 |
| `Shift+Tab` / `Alt+M` | 切换模式 | 在不同工作模式间快速切换 |
## 调试与显示控制
这些快捷键用于控制界面显示和调试功能：
| 快捷键 | 功能说明 | 适用场景 |
| ------ | -------- | -------- |
| `Ctrl+O` | 切换调试控制台显示 | 开发调试时查看详细信息 |
| `Ctrl+T` | 切换工具描述显示 | 想了解工具功能时 |
| `Ctrl+Y` | 切换自动批准模式（YOLO模式） | 信任所有工具调用时使用 |
## 输入编辑快捷键
### 基础输入操作
| 快捷键 | 功能说明 | 使用技巧 |
|---------------------------------------------------------| -------- | -------- |
| `Enter` | 提交当前输入 | 完成输入后确认发送 |
| `\`（行末）+ `Enter` / `Shift` + `Enter` / `Meta` + `Enter` | 插入换行符 | 输入多行内容时使用 |
| `!` | 输入为空时切换shell模式 | 快速执行系统命令 |
| `Tab` | 自动补全当前建议 | 提高输入效率 |
### 光标移动
| 快捷键 | 功能说明 |
| ------ | -------- |
| `Ctrl+A` / `Home` | 光标移至行首 |
| `Ctrl+E` / `End` | 光标移至行末 |
| `Ctrl+B` / `Left Arrow` | 光标左移一个字符 |
| `Ctrl+F` / `Right Arrow` | 光标右移一个字符 |
| `Ctrl+Left Arrow` / `Meta+Left` / `Meta+B` | 光标左移一个单词 |
| `Ctrl+Right Arrow` / `Meta+Right` / `Meta+F` | 光标右移一个单词 |
### 删除操作
| 快捷键 | 功能说明 |
| ------ | -------- |
| `Ctrl+H` / `Backspace` | 删除光标左侧字符 |
| `Ctrl+D` / `Delete` | 删除光标右侧字符 |
| `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | 删除光标左侧单词 |
| `Meta+Delete` / `Ctrl+Delete` | 删除光标右侧单词 |
| `Ctrl+U` | 删除从光标到行首的内容 |
| `Ctrl+K` | 删除从光标到行末的内容 |
| `Ctrl+C` | 清空输入提示框 |
### 历史记录与剪贴板
| 快捷键 | 功能说明 | 使用提示 |
| ------ | -------- | -------- |
| `Up Arrow` / `Ctrl+P` | 浏览上一条输入历史 | 重复使用之前的命令 |
| `Down Arrow` / `Ctrl+N` | 浏览下一条输入历史 | 在历史记录中导航 |
| `Ctrl+V` | 粘贴剪贴板内容 | 支持文本和图片粘贴 |
| `Ctrl+X` / `Meta+Enter` | 在外部编辑器中打开当前输入 | 编辑长文本时更方便 |
## 建议选择快捷键
当系统显示建议列表时，使用以下快捷键：
| 快捷键 | 功能说明 |
| ------ | -------- |
| `Up Arrow` | 向上浏览建议 |
| `Down Arrow` | 向下浏览建议 |
| `Tab` / `Enter` | 接受选中的建议 |
## 选项选择快捷键
在单选按钮界面中使用：
| 快捷键 | 功能说明 |
| ------ | -------- |
| `Up Arrow` / `k` | 向上移动选择 |
| `Down Arrow` / `j` | 向下移动选择 |
| `Enter` | 确认选择 |
| `1-9` | 直接选择对应数字的选项 |
| 多位数字 | 快速连续按下数字选择大于9的选项 |
## 使用技巧
1. **新手建议**：先掌握 `Ctrl+C`、`Enter`、`Ctrl+L` 等基础快捷键
2. **效率提升**：熟练使用 `Tab` 自动补全和方向键历史记录功能
3. **高级用法**：组合使用 `Ctrl+Y` 自动批准模式可以加速工作流程
4. **调试帮助**：遇到问题时可以使用 `Ctrl+O` 查看调试信息
## 特别说明
- **图片支持**：使用 `Ctrl+V` 可以直接粘贴图片，系统会自动保存并在输入中插入引用
- **外部编辑器**：`Ctrl+X` 可以调用系统默认编辑器，便于编辑长文本
- **安全退出**：`Ctrl+C` 和 `Ctrl+D` 都需要按两次来确认退出，避免误操作
希望这份指南能帮助您更好地使用心流AI CLI！如有疑问，欢迎随时咨询。
## /docs_cn/examples/mcp.md
---
title: MCP
description: 使用模型上下文协议扩展 iFlow CLI 功能
sidebar_position: 4
---
# MCP 扩展系统
> **功能概述**：通过模型上下文协议(MCP)扩展iFlow CLI能力
> **学习时间**：15-20分钟
> **前置要求**：完成基础操作，了解CLI基本使用
## 什么是 MCP
**MCP**（Model Context Protocol，模型上下文协议）是AI领域的"USB接口"，它在大模型和外部工具之间建立标准化连接。
### 核心特点
- **标准化协议**：统一的通信标准，替代碎片化集成
- **安全连接**：可控的双向数据交换
- **功能扩展**：为AI助手添加专业工具能力
- **生态丰富**：社区提供数百种MCP服务器
## 安装 MCP 工具
### 方法一：心流 MCP 市场（推荐）
访问[心流MCP市场](https://platform.iflow.cn/mcp)，搜索并复制安装命令， 在终端执行安装命令：
```bash
# 基本语法
iflow mcp add-json 'server-name' '{JSON配置}'
# 示例：安装Playwright自动化工具
iflow mcp add-json 'playwright' "{\"command\":\"npx\",\"args\":[\"-y\",\"@iflow-mcp/playwright-mcp@0.0.32\"]}"
# 在iFlow CLI中执行（添加!前缀）需要手动刷新mcp列表
!iflow mcp add-json 'playwright' "{\"command\":\"npx\",\"args\":[\"-y\",\"@iflow-mcp/playwright-mcp@0.0.32\"]}"
/mcp refresh
```
以上命令都是在项目层面进行安装，如果确保所有项目都可见，在市场中复制对应的全局安装命令
```bash
iflow mcp add-json --scope user 'server-name' '{JSON配置}'
windows环境下使用转义后的JSON字符串配置
iflow mcp add-json --scope user 'server-name' "{JSON转义配置}"
```
### 方法二：使用 `/mcp online` 安装
在iFlow CLI中执行 `/mcp online`命令可以在线浏览MCP市场，选择合适的MCP进行安装
选中对应的MCP Server后，可以选择在项目范围内安装也可以在用户范围内安装(所有项目都可见)
### 方法三：使用命令行安装（高阶用户）
查看所有MCP命令：
```bash
iflow mcp --help
```
#### 使用 `iflow mcp add-json` 命令安装
适用于有现成配置文件的场景：
```bash
# 基本语法
iflow mcp add-json <name> '<json-config>'
# 示例：天气API服务器
iflow mcp add-json weather-api "{
\"type\": \"stdio\",
\"command\": \"/path/to/weather-cli\",
\"args\": [\"--api-key\", \"abc123\"],
\"env\": {\"CACHE_DIR\": \"/tmp\"}
}"
# 验证安装
iflow mcp get weather-api
```
**配置技巧**：
- 确保JSON格式正确，注意转义字符
- 使用 `--scope user` 添加到全局配置
- 避免服务器名称冲突（系统会自动添加后缀）
#### 使用 `iflow mcp add` 添加标准 stdio 服务器
适用于本地运行的工具：
```bash
# 基本语法
iflow mcp add <name> <command> [args...]
# 示例：本地文件处理工具
iflow mcp add file-manager python3 /path/to/file_manager.py
```
#### 使用 `iflow mcp add --transport sse` 添加SSE 服务器
适用于需要实时通信的Web服务：
```bash
# 基本语法
iflow mcp add --transport sse <name> <url>
# 示例：连接远程API服务
iflow mcp add --transport sse analytics-api https://api.example.com/mcp
# 带认证的连接
iflow mcp add --transport sse secure-api https://api.example.com/mcp --auth-token YOUR_TOKEN
```
#### 使用 `iflow mcp add --transport http` 添加远程 HTTP 服务器
```bash
# 基本语法
iflow mcp add --transport http <name> <url>
# 示例：连接到notion
iflow mcp -transport http notion https://mcp.notion.com/mcp
# 带认证的连接
iflow mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
```
### 方法四：从社区安装
**GitHub MCP服务器库**
- 浏览：[MCP服务器集合](https://github.com/modelcontextprotocol/servers)
- 自建：使用 [MCP SDK](https://modelcontextprotocol.io/quickstart/server)
**第三方市场**
在平台上获取serverConfig配置后，使用 `iflow mcp add-json` 命令安装，确保JSON配置是一个合法的json字符串格式
提示💡：使用第三方 MCP 服务器需要您自担风险 - iFlow CLI 未验证 所有这些服务器的正确性或安全性。 确保您信任正在安装的 MCP 服务器。 在使用可能获取不受信任内容的 MCP 服务器时要特别小心， 因为这些可能会使您面临提示注入风险。
### 方法五：修改配置文件
配置文件相关详情可以参考: [CLI配置文件说明](../configuration/settings.md)
全局/用户范围可用的MCP 服务器在 iFlow 设置文件中配置，位置为 `~/.iflow/settings.json`。配置定义了要连接的 MCP 服务器以及如何调用它们。
项目范围可用的MCP 服务器配置在项目文件夹的 `.iflow/settings.json`位置
#### **`mcpServers`**（对象）：
- **描述：** 配置与一个或多个模型上下文协议（MCP）服务器的连接，用于发现和使用自定义工具。iFlow CLI 尝试连接到每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器暴露同名工具，工具名称将以您在配置中定义的服务器别名为前缀（如 `serverAlias__actualToolName`）以避免冲突。注意，系统可能会从 MCP 工具定义中剥离某些模式属性以保持兼容性。
- **默认值：** 空
- **属性：**
- **`<SERVER_NAME>`**（对象）：命名服务器的服务器参数。
- `command`（字符串，必填）：启动 MCP 服务器要执行的命令。
- `args`（字符串数组，可选）：传递给命令的参数。
- `env`（对象，可选）：为服务器进程设置的环境变量。
- `cwd`（字符串，可选）：启动服务器的工作目录。
- `timeout`（数字，可选）：对此 MCP 服务器请求的超时时间（毫秒）。
- `trust`（布尔值，可选）：信任此服务器并绕过所有工具调用确认。
- `includeTools`（字符串数组，可选）：要从此 MCP 服务器包含的工具名称列表。指定时，只有这里列出的工具才可从此服务器使用（白名单行为）。如果未指定，默认启用服务器的所有工具。
- `excludeTools`（字符串数组，可选）：要从此 MCP 服务器排除的工具名称列表。这里列出的工具将不可用于模型，即使它们由服务器暴露。**注意：** `excludeTools` 优先于 `includeTools` - 如果工具在两个列表中，它将被排除。
#### **示例：**
```json
"mcpServers": {
"myPythonServer": {
"command": "python",
"args": ["mcp_server.py", "--port", "8080"],
"cwd": "./mcp_tools/python",
"timeout": 5000,
"includeTools": ["safe_tool", "file_reader"],
},
"myNodeServer": {
"command": "node",
"args": ["mcp_server.js"],
"cwd": "./mcp_tools/node",
"excludeTools": ["dangerous_tool", "file_deleter"]
},
"myDockerServer": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"],
"env": {
"API_KEY": "$MY_API_TOKEN"
}
}
}
```
## MCP 服务器管理
### 查看已安装的服务器
```bash
# 列出所有MCP服务器
iflow mcp list
# 查看特定服务器详情
iflow mcp get <server-name>
```
### 删除
```bash
# 删除MCP服务器
iflow mcp remove <server-name>
```
### 在iFlow CLI中管理
```bash
/mcp list
```
## 平台兼容性
### 支持平台
- ✅ **macOS**：完全支持
- ✅ **Windows (WSL)**：通过WSL支持
- ✅ **Linux**：原生支持
- ⚠️ **Windows 原生**：部分功能受限
### 配置位置
- **全局配置**：`~/.iflow/mcp/config.json`
- **项目配置**：`{project}/.iflow/mcp.json`
- **Claude Desktop 集成**：自动读取Claude Desktop配置
## 故障排除
### 服务器无法启动
- 检查命令和参数是否正确
- 验证包是否已安装（针对 npm 包）
- 检查超时设置
- 查看 iFlow CLI 中的错误信息
### 连接问题
- 确保服务器支持 MCP 协议
- 检查网络连接（针对远程服务器）
- 验证环境变量设置是否正确
### 性能问题
- 调整超时值
- 检查服务器资源使用情况
- 考虑减少并发 MCP 服务器数量
## 最佳实践
1. **从简单开始**: 在添加自定义服务器之前先使用预配置的服务器
2. **充分测试**: 首先在安全环境中测试新的 MCP 服务器
3. **监控性能**: 关注响应时间和资源使用情况
4. **保持更新**: 定期更新 MCP 服务器包以获得安全性和功能改进
5. **记录更改**: 为团队成员记录自定义配置
## 使用示例
配置 MCP 服务器后，您可以在 iFlow 对话中利用它们的能力：
```
/mcp list
# 显示可用的 MCP 服务器
# 使用增强推理（sequential-thinking 服务器自动激活）
如何优化这个复杂的数据库查询？
# 利用上下文信息（context7 服务器自动激活）
在 Node.js 中实现身份验证的最佳实践是什么？
```
MCP 服务器在后台透明工作，增强 iFlow 的能力，在大多数情况下无需显式调用。
### 安全注意事项
**使用第三方MCP服务器时**：
- ⚠️ 验证服务器来源和可信度
- ⚠️ 审查服务器权限要求
- ⚠️ 注意提示注入攻击风险
- ⚠️ 定期更新服务器版本
**推荐做法**：
- ✅ 优先使用官方和知名开发者的服务器
- ✅ 在测试环境中先验证功能
- ✅ 定期审核已安装的服务器
- ✅ 保持服务器版本更新
## 下一步
完成MCP配置后，建议继续学习：
1. **[子代理配置](../examples/subagent.md)** - 配置专业化AI助手
2. **[最佳实践](../examples/best-practices)** - 工作流优化技巧
3. **[高级配置](../configuration/settings)** - 深度定制设置
---
**获得帮助**：📖 [MCP官方文档](https://modelcontextprotocol.io/) | 🐛 [问题反馈](https://github.com/iflow-ai/iflow-cli/issues)
## /docs_cn/examples/subagent.md
---
title: Sub Agent
description: 配置专业化的 AI 助手来处理特定开发任务
sidebar_position: 5
---
# Sub Agent
> **功能概述**：Sub Agent是iFlow CLI的智能Agent系统，根据任务类型自动选择最合适的专业Agent处理请求。
>
> **学习时间**：10-15分钟
>
> **前置要求**：已安装iFlow CLI，了解基本的斜杠命令使用
## 什么是Sub
Sub Agent是iFlow CLI中的智能分工系统，类似于拥有一个专业团队，每个成员都有自己的专长领域。系统能够根据不同的任务类型自动选择最合适的专业Agent来处理您的请求，确保每个任务都能得到最专业的处理。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 专业化分工 | 每个Sub Agent针对特定领域优化 | 提高任务处理质量 |
| 工具访问控制 | 不同Agent访问不同工具集合 | 安全性和效率兼顾 |
| 智能调度 | 根据任务描述自动选择Agent | 用户无需手动选择 |
| 模型验证 | 自动验证模型兼容性 | 确保最佳性能表现 |
| 动态扩展 | 支持自定义和第三方Agent | 满足个性化需求 |
## 工作原理
### 任务分析与Agent选择
```
用户请求 → 任务分析 → Agent匹配 → 工具授权 → 任务执行
↓
[描述内容] → [领域识别] → [最佳Agent] → [工具集合] → [专业处理]
```
### Agent类型分类
- **开发类Agent**：代码审查、前端开发、后端开发、测试等
- **分析类Agent**：数据分析、性能分析、安全分析等
- **创作类Agent**：文档编写、内容创作、翻译等
- **运维类Agent**：部署管理、监控报警、故障诊断等
## 详细功能说明
### Agent管理
#### 查看可用Agent
| 命令 | 功能 | 说明 |
|------|------|------|
| `/agents list` | 列出本地Agent | 显示已安装的Agent列表 |
| `/agents list desc` | 详细描述 | 显示Agent的详细功能说明 |
| `/agents online` | 在线市场 | 浏览可安装的Agent |
| `/agents install` | 安装向导 | 创建新Agent的引导式安装 |
| `/agents refresh` | 刷新Agent | 从源文件重新加载Agent配置 |
#### Agent市场导航
**在线浏览操作**
| 操作 | 快捷键 | 说明 |
|------|--------|------|
| 向下浏览 | `j` 或 `↓` | 移动到下一个选项 |
| 向上浏览 | `k` 或 `↑` | 移动到上一个选项 |
| 返回上级 | `h` | 返回上级目录 |
| 进入选中项 | `l` 或 `Enter` | 查看详细信息或安装 |
| 退出浏览 | `q` | 退出浏览模式 |
| 刷新列表 | `r` | 重新加载Agent列表 |
```bash
# 进入在线Agent市场
/agents online
```
#### Agent安装管理
**通过CLI命令安装**
```bash
# 添加项目级别的Agent
iflow agent add <agent-name-or-id> --scope project
# 添加用户级别的Agent（全局作用域）
iflow agent add <agent-name-or-id> --scope global
# 实际示例
iflow agent add python-expert --scope project
iflow agent add code-reviewer --scope global
# 其他管理命令
iflow agent list # 列出所有已配置的Agent
iflow agent remove <name> # 移除指定Agent
iflow agent get <name> # 查看Agent详细信息
iflow agent online # 浏览在线Agent市场
```
**重要提醒**：使用第三方Sub Agent时请谨慎选择！确保您信任要安装的Agent配置，特别是那些可能访问敏感数据的Agent。
**引导式安装（推荐）**
使用 `/agents install` 命令启动引导式安装向导，支持三种创建方式：
```bash
# 启动Agent安装向导
/agents install
```
**安装向导功能**：
1. **智能创建模式**：
- **iFlow生成**（推荐）：通过智能引导创建Agent
- **手动配置**：逐步手动配置Agent参数
- **在线仓库**：从在线Agent仓库安装
2. **配置选项**：
- 安装位置选择（项目级别/用户级别）
- 工具权限配置
- MCP服务器访问权限
- 自定义系统提示词
- Agent外观颜色选择
3. **向导导航**：
- 使用方向键 `↑/↓` 或 `j/k` 导航选项
- `Enter` 确认选择
- `Esc` 返回上一步
- `q` 退出向导
**使用示例**：
```bash
# 步骤1：启动安装向导
/agents install
# 步骤2：选择安装位置
→ Project Agent (仅当前项目可用)
User Agent (全局可用)
# 步骤3：选择创建方式
→ Generate with iFlow (recommended)
Manual configuration
From Online Repository
# 步骤4：描述Agent目标（iFlow模式）
Describe your agent goal: 审查代码安全性和最佳实践
# 步骤5：配置工具和权限
Select tools: [✓] Read [✓] Write [✓] Bash [ ] WebFetch
Select MCP servers: [✓] filesystem [✓] git
# 步骤6：预览并确认创建
Agent Type: code-security-reviewer
Description: 专门审查代码安全性和最佳实践的专家Agent
Tools: Read, Write, Bash
Location: Project Agent
```
**手动安装**
1. 创建Agent目录
```bash
mkdir -p ~/.iflow/agents
```
2. 创建自定义Agent
```bash
# 创建新的Agent文件
nano ~/.iflow/agents/my-agent.md
```
3. 重启 CLI 加载新Agent
```bash
iflow
```
**注意** iFlow CLI会使用Task工具调用Sub Agent
### 快速调用功能
#### 使用 $ 符号快速调用
iFlow CLI支持使用 `$` 符号快速调用Sub Agent，类似于 `@` 符号选择文件的方式：
**基本语法**
```bash
{{contextString}}lt;agent-type> <任务描述>
```
**使用示例**
```bash
$code-reviewer 对当前项目进行代码审查
$frontend-developer 创建一个响应式的导航组件
$python-expert 优化这个算法的性能
$data-scientist 分析这个数据集的趋势
```
#### 快速调用特性
| 特性 | 说明 | 优势 |
|------|------|------|
| 智能补全 | 输入 `$` 后显示可用Agent列表 | 快速选择合适Agent |
| 快速执行 | 直接在当前对话中执行 | 无需额外配置步骤 |
| 实时反馈 | 显示Agent执行状态和过程 | 了解任务进展情况 |
| 可视化界面 | 工具调用过程可视化展示 | 提高用户体验 |
| 结果展示 | Agent响应直接显示在对话中 | 无缝集成到工作流 |
#### 使用技巧
1. **快速选择**：输入 `$` 后使用方向键或鼠标选择Agent类型
2. **明确任务**：提供清晰、具体的任务描述
3. **上下文感知**：Agent会自动获取当前项目的上下文信息
4. **工具权限**：Agent根据其配置获得相应的工具访问权限
### 预置Agent类型
#### 内置Agent
| Agent类型 | 功能描述 | 适用场景 |
|----------|----------|----------|
| general-purpose | 通用Agent | 复杂的多步骤任务 |
#### 扩展Agent
更丰富的Agent可以通过心流AI在线市场进行快速安装，包括：
- **代码审查专家**：专门用于代码质量检查
- **前端开发专家**：专注于前端技术和UI开发
- **数据分析专家**：处理数据分析和可视化任务
- **文档编写专家**：专业的技术文档创作
## 使用示例
### 常见使用场景
#### 代码审查
```bash
$code-reviewer 请对当前项目进行全面的代码审查，关注代码质量和最佳实践
```
#### 前端开发
```bash
$frontend-developer 创建一个响应式的用户登录组件，支持表单验证
```
#### 数据分析
```bash
$data-scientist 分析sales_data.csv中的销售趋势，生成可视化图表
```
#### 文档编写
```bash
$doc-writer 为这个API端点编写详细的技术文档和使用示例
```
### Agent协作场景
多个Agent可以在同一个项目中协作工作：
```bash
# 首先进行代码审查
$code-reviewer 检查当前代码的安全性问题
# 然后优化性能
$performance-expert 基于审查结果优化代码性能
# 最后生成文档
$doc-writer 为优化后的代码生成完整文档
```
## 智能模型管理
### 自动模型验证
| 功能 | 说明 | 优势 |
|------|------|------|
| 兼容性检测 | 执行前自动检查模型支持情况 | 避免执行错误 |
| 智能推荐 | 推荐最佳替代模型 | 保证任务质量 |
| 用户选择 | 提供模型选择对话框 | 保持用户控制权 |
| 偏好记忆 | 记住用户的模型选择偏好 | 简化后续操作 |
### 模型切换模式
**交互模式（默认）**
- 显示模型选择对话框
- 用户可以从可用模型列表中选择替代模型
- 支持"一次性"和"永久记住"两种选择
**YOLO模式**
- 自动使用推荐的替代模型
- 显示警告信息说明模型切换情况
- 无需用户干预，快速执行
## 自定义Agent配置
### 配置文件管理
在项目的 `.iflow/agents/` 目录中创建自定义Agent配置：
```markdown
---
agentType: "custom-expert"
systemPrompt: "你是一个自定义领域的专家..."
whenToUse: "当需要处理特定领域任务时使用"
model: "claude-3-5-sonnet-20241022"
allowedTools: ["*"]
proactive: false
---
# Custom Expert Agent
这是一个自定义专家Agent的详细说明...
```
### 配置属性说明
#### 必需属性
| 属性 | 类型 | 说明 |
|------|------|------|
| agentType | 字符串 | Agent的唯一标识符 |
| systemPrompt | 字符串 | Agent的系统提示词 |
| whenToUse | 字符串 | 何时使用此Agent的说明 |
#### 可选属性
| 属性 | 类型 | 说明 | 默认值 |
|------|------|------|-------|
| model | 字符串 | 偏好的AI模型 | - |
| allowedTools | 数组 | 可使用的工具列表 | [] |
| allowedMcps | 数组 | 允许访问的MCP服务器列表 | [] |
| isInheritTools | 布尔值 | 是否继承父级Agent的工具权限 | true |
| isInheritMcps | 布尔值 | 是否继承父级Agent的MCP权限 | true |
| proactive | 布尔值 | 是否主动推荐使用 | false |
| color | 字符串 | UI中的显示颜色 | - |
| name | 字符串 | 显示名称 | agentType |
| description | 字符串 | 简短描述 | - |
**权限继承机制说明**
Sub Agent的工具和MCP权限系统采用继承机制，允许精确控制Agent的能力边界：
**工具继承（isInheritTools）**
- `true`（默认）：继承主Agent的所有工具权限，并额外获得allowedTools中指定的工具
- `false`：仅使用allowedTools中明确指定的工具，不继承任何父级权限
**MCP继承（isInheritMcps）**
- `true`（默认）：继承主Agent对所有MCP服务器的访问权限，并额外获得allowedMcps中指定的服务器
- `false`：仅访问allowedMcps中明确指定的MCP服务器，不继承任何父级权限
**MCP服务器访问控制（allowedMcps）**
- 指定Agent可以访问的MCP（Model Context Protocol）服务器列表
- 用于限制Agent对特定外部服务和API的访问
- 空数组表示不限制MCP服务器访问（继承父级权限）
**权限配置示例**
```markdown
---
agentType: "security-auditor"
systemPrompt: "你是一个安全审计专家..."
whenToUse: "当需要进行安全审计和漏洞检查时使用"
allowedTools: ["Read", "Grep", "Bash"]
allowedMcps: ["security-scanner", "vulnerability-db"]
isInheritTools: false
isInheritMcps: false
---
```
在这个示例中：
- Agent只能使用Read、Grep、Bash三个工具，不继承其他工具权限
- Agent只能访问security-scanner和vulnerability-db两个MCP服务器
- 这种配置确保了安全审计Agent的权限被严格限制在必要范围内
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| Agent不响应 | 模型不兼容或网络问题 | 检查模型设置，确认网络连接 |
| 工具权限错误 | allowedTools配置错误 | 检查Agent配置中的工具权限设置 |
| Agent列表为空 | 配置文件路径错误 | 确认.iflow/agents/目录存在且有配置文件 |
| 快速调用失败 | Agent类型不存在 | 使用/agents list查看可用Agent |
| 模型切换失败 | 目标模型不可用 | 选择其他可用模型或检查配置 |
### 诊断步骤
1. **基础检查**
```bash
/agents list # 查看已安装的Agent
/agents refresh # 刷新Agent配置
```
2. **配置验证**
- 检查`.iflow/agents/`目录是否存在
- 验证配置文件格式是否正确
- 确认Agent类型命名规范
3. **权限验证**
- 检查工具访问权限设置
- 验证模型访问权限
- 确认网络连接状态
4. **日志检查**
```bash
/log # 查看详细日志
/stats # 查看使用统计
```
### 平台兼容性
| 平台 | 支持程度 | 特殊说明 |
|------|----------|----------|
| Windows | 完全支持 | 配置文件路径使用反斜杠 |
| macOS | 完全支持 | 可能需要文件系统权限 |
| Linux | 完全支持 | 依赖系统包管理器 |
## /docs_cn/examples/subcommand.md
---
title: Sub Command
description: 扩展 iFlow CLI 功能，安装和管理来自市场的自定义命令
sidebar_position: 6
---
# Sub Command
> **功能概述**：Sub Command是iFlow CLI的命令扩展系统，可以从在线市场安装和管理专业化的斜杠命令。
> **学习时间**：10-15分钟
> **前置要求**：已安装iFlow CLI，完成身份验证，了解基本的斜杠命令使用
## 什么是Sub Command
Sub Command是iFlow CLI中的命令市场系统，允许您从在线市场安装专业化的斜杠命令来扩展CLI功能。类似于应用商店，您可以浏览、安装、管理各种功能丰富的自定义命令。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 市场化分发 | 从在线市场获取经过验证的命令 | 丰富的功能选择 |
| 即插即用 | 安装后立即可用，无需额外配置 | 简化使用流程 |
| 作用域管理 | 支持项目级和全局级别的命令安装 | 灵活的权限控制 |
| 版本追踪 | 每个命令都有明确的版本信息 | 确保功能稳定性 |
| 社区驱动 | 支持社区贡献和第三方开发 | 持续功能扩展 |
## 工作原理
### 命令市场架构
```
在线市场 → 本地安装 → CLI集成 → 斜杠命令
↓ ↓ ↓ ↓
[命令库] → [TOML配置] → [命令解析] → [功能执行]
```
### 作用域层级
- **全局作用域**：安装到 `~/.iflow/commands/`，所有项目都可使用
- **项目作用域**：安装到 `{project}/.iflow/commands/`，仅当前项目可用
- **优先级规则**：项目级命令优先于全局级命令
## 命令市场管理
### 从开放市场中安装命令
* 进入[命令开放市场](https://platform.iflow.cn/agents)
* 搜索类型选择**指令**
* 挑选心仪的指令
* 点击安装按钮，复制对应的命令
* 在自己的终端安装
### 在CLI中浏览在线市场
| 命令 | 功能 | 说明 |
|------------------------------|------|------|
| `/commands online` | 进入交互式市场 | 浏览、搜索、安装命令 |
| `/commands get <name or id>` | 查看命令详情 | 获取特定命令的详细信息 |
#### 市场导航操作
**交互式浏览快捷键**
| 操作 | 快捷键 | 说明 |
|------|--------|------|
| 向下浏览 | `j` 或 `↓` | 移动到下一个命令 |
| 向上浏览 | `k` 或 `↑` | 移动到上一个命令 |
| 查看详情 | `l` 或 `Enter` | 查看命令详细信息 |
| 安装命令 | `i` | 安装当前选中的命令 |
| 搜索过滤 | `/` | 按名称或分类搜索 |
| 退出浏览 | `q` | 退出市场浏览模式 |
| 刷新列表 | `r` | 重新加载命令列表 |
```bash
# 进入交互式命令市场
/commands online
# 浏览过程中的操作示例
# 1. 使用 j/k 或方向键浏览命令列表
# 2. 按 Enter 查看感兴趣命令的详细信息
# 3. 按 i 键直接安装命令
# 4. 按 / 键搜索特定功能的命令
```
### 查看命令详情
```bash
# 查看特定命令的详细信息
/commands get 123
# 输出示例：
# 📋 Command Details
#
# 🆔 ID: 123
# 📝 Name: code-reviewer
# 📄 Description: 专业代码审查工具，支持多语言代码质量检测
# 📁 Category: Development
# 🤖 Model: claude-3-5-sonnet-20241022
# 🏷️ Tags: code-review, quality, best-practices
# 👤 Author: iflow-community
# 📊 Version: 2
# 👁️ Visibility: public
# 📋 Status: published
#
# 📖 Detail Context:
# 这是一个专业的代码审查助手，可以：
# - 检测代码质量问题
# - 提供最佳实践建议
# - 支持多种编程语言
# - 生成详细的审查报告
#
# 💡 To add this command to your CLI, use: /commands add 123
```
### 安装命令介绍
```bash
# 基本语法
iflow commands add <name or id> [--scope project|global]
# 安装到项目（默认）
iflow commands add 123
iflow commands add 123 --scope project
# 安装到全局
iflow commands add commit --scope global
# 实际示例
iflow commands add 456 --scope project # 代码审查工具
iflow commands add docs --scope global # 通用文档生成工具
# 更多详情查看
iflow commands -h
```
### 查看已安装命令
```bash
# 列出所有已安装的命令
/commands list
/commands show # 别名
/commands local # 别名
# 输出示例：
# Installed commands:
#
# 🌍 Global Commands (2):
# /code-reviewer - 专业代码审查工具，支持多语言代码质量检测
# 📁 /Users/username/.iflow/commands/code-reviewer.toml
#
# /doc-generator - 自动文档生成工具
# 📁 /Users/username/.iflow/commands/doc-generator.toml
#
# 📂 Project Commands (1):
# /project-analyzer - 项目结构分析工具
# 📁 /path/to/project/.iflow/commands/project-analyzer.toml
#
# 💡 Tips:
# • Use /commands online to browse online marketplace
# • Use /commands add <id> to install new commands
# • Use /commands remove <name> to remove commands
# • Use /commands get <id> to view command details
```
### 删除命令
```bash
# 删除项目级命令（默认）
/commands remove <command-name>
/commands remove code-reviewer
# 删除全局命令
/commands remove code-reviewer --scope global
# 别名命令
/commands rm <command-name>
/commands delete <command-name>
# 删除成功示例：
# ✅ Successfully removed command 'code-reviewer' from project scope
# Location: /path/to/project/.iflow/commands/code-reviewer.toml
#
# ⚠️ Please restart the CLI to see changes take effect.
```
## 命令分类与推荐
### 开发工具类
| 命令名称 | ID | 功能描述 | 适用场景 |
|----------|----|-----------|---------|
| **refactor** | 79 | 重构代码，保持功能性的同时改进结构、可读性和可维护性 | 代码优化和结构调整 |
| **implement** | 80 | 智能实现功能特性，完美适配项目架构 | 新功能开发 |
| **test** | 81 | 基于当前上下文智能运行测试并帮助修复失败 | 测试自动化 |
| **scaffold** | 94 | 从模式生成完整功能特性 | 快速原型开发 |
| **fix-imports** | 87 | 重构后修复损坏的导入 | 重构后维护 |
| **fix-todos** | 88 | 智能实现TODO修复 | 任务管理 |
| **format** | 89 | 自动检测并应用项目格式化器 | 代码格式化 |
### 代码质量类
| 命令名称 | ID | 功能描述 | 适用场景 |
|----------|----|-----------|---------|
| **review** | 93 | 多代理分析（安全、性能、质量、架构） | 代码审查 |
| **make-it-pretty** | 90 | 改善可读性而不改变功能 | 代码美化 |
| **remove-comments** | 92 | 清理明显的注释，保留有价值的文档 | 代码清理 |
| **predict-issues** | 91 | 主动问题检测与时间线估算 | 风险预测 |
### 文档工具类
| 命令名称 | ID | 功能描述 | 适用场景 |
|----------|----|-----------|---------|
| **docs** | 84 | 智能文档管理和更新 | 项目文档维护 |
| **contributing** | 82 | 项目贡献准备性完整分析 | 开源项目 |
| **explain-like-senior** | 85 | 高级水平的代码解释和上下文分析 | 代码学习 |
### 安全分析类
| 命令名称 | ID | 功能描述 | 适用场景 |
|----------|----|-----------|---------|
| **security-scan** | 95 | 扩展思考的漏洞分析和修复跟踪 | 安全检查 |
### 实用工具类
| 命令名称 | ID | 功能描述 | 适用场景 |
|----------|----|-----------|---------|
| **commit** | 78 | 分析变更并创建有意义的提交信息 | Git工作流 |
| **cleanproject** | 77 | 清理开发工件同时保留工作代码 | 项目维护 |
| **create-todos** | 83 | 基于分析结果添加上下文TODO注释 | 任务管理 |
| **find-todos** | 86 | 定位和组织开发任务 | 任务跟踪 |
| **session-end** | 96 | 总结和保存会话上下文 | 会话管理 |
## 命令配置文件
### TOML文件结构
安装的命令会在本地生成TOML配置文件：
```toml
# Command: code-reviewer
# Description: 专业代码审查工具，支持多语言代码质量检测
# Category: Development
# Version: 2
# Author: iflow-community
description = "专业代码审查工具，支持多语言代码质量检测"
prompt = """
你是一个专业的代码审查专家。请分析用户提供的代码，从以下方面进行评估：
1. 代码质量和可读性
2. 安全性问题检测
3. 性能优化建议
4. 最佳实践遵循情况
5. 潜在的bug或逻辑错误
请提供具体的改进建议和示例代码。
"""
```
### md文件结构
除了TOML格式，iFlow CLI还支持Markdown格式的配置文件。
```bash
# 创建命令目录
mkdir -p ~/.iflow/commands
# 创建Markdown格式的命令文件
echo "Review this code for security vulnerabilities:" > ~/.iflow/commands/security-review.md
```
也支持添加描述，例如
```markdown
---
description: Create a git commit
---
## Context
- Current git status: !`git status`
- Current git diff (staged and unstaged changes): !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`
## Your task
Based on the above changes, create a single git commit.
```
### 配置文件位置
| 作用域 | 配置路径 | 说明 |
|--------|----------|------|
| 全局 | `~/.iflow/commands/` | 所有项目都可访问 |
| 项目 | `{project}/.iflow/commands/` | 仅当前项目可访问 |
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 命令安装失败 | API密钥未设置或过期 | 重新进行身份验证 |
| 命令不可用 | 未重启CLI加载新配置 | 重启iFlow CLI |
| 权限错误 | 目录权限不足 | 检查文件系统权限 |
| 网络连接失败 | 无法访问命令市场API | 检查网络连接和防火墙设置 |
| 命令冲突 | 同名命令在不同作用域 | 使用 --scope 明确指定 |
### 诊断步骤
1. **连接检查**
```bash
# 测试API连接
/commands online
# 检查身份验证状态
/auth status
```
2. **配置验证**
```bash
# 查看本地命令列表
/commands list
# 检查配置文件
cat ~/.iflow/commands/command-name.toml
```
3. **权限验证**
```bash
# 检查目录权限
ls -la ~/.iflow/commands/
ls -la ./.iflow/commands/
```
4. **日志检查**
```bash
# 查看详细日志
/log
# 查看错误信息
/debug
```
### 清理和重置
```bash
# 清理项目级命令
rm -rf ./.iflow/commands/
# 清理全局命令（谨慎操作）
rm -rf ~/.iflow/commands/
# 重新初始化命令配置
iflow commands init
```
## 安全注意事项
### 使用第三方命令时的安全建议
**验证命令来源**：
- ⚠️ 仅安装来自可信作者的命令
- ⚠️ 检查命令的评分和社区反馈
- ⚠️ 避免安装过于宽泛权限的命令
**命令权限控制**：
- ✅ 优先使用项目作用域安装
- ✅ 定期审核已安装的命令
- ✅ 及时更新命令到最新版本
- ✅ 移除不再使用的命令
## 开发自定义命令
### TOML配置文件完整规范
#### 基础配置结构
```toml
# 命令描述（必需）
description = "命令的简短描述"
# 命令提示词（必需）
prompt = """
发送给AI模型的完整提示词内容
支持多行文本和特殊占位符
"""
```
#### 高级功能特性
##### 1. 参数注入机制
**快捷参数注入**：使用 `{{args}}` 占位符
```toml
description = "代码审查工具"
prompt = """
请审查以下代码并提供改进建议：
{{args}}
重点关注：代码质量、安全性、性能优化。
"""
```
**默认参数处理**：如果不使用 `{{args}}`，系统会自动将用户输入追加到提示词后
```toml
description = "文档生成器"
prompt = """
根据提供的内容生成专业文档。
"""
# 用户输入 "/docs 用户手册" 会变成：
# "根据提供的内容生成专业文档。\n\n/docs 用户手册"
```
##### 2. Shell命令集成
使用 `!{command}` 语法在提示词中执行Shell命令：
```toml
description = "项目分析工具"
prompt = """
当前项目信息：
文件结构：
!{find . -name "*.js" -o -name "*.ts" | head -20}
Git状态：
!{git status --porcelain}
请分析项目状态并提供建议。
"""
```
**安全机制**：
- Shell命令需要通过安全检查
- 支持全局和会话级别的命令白名单
- 危险命令会要求用户确认
##### 3. 提示词处理器链
系统使用处理器链模式处理TOML配置：
| 处理器 | 触发条件 | 功能 |
|--------|----------|------|
| **ShellProcessor** | 包含 `!{...}` | 执行Shell命令并替换输出 |
| **ShorthandArgumentProcessor** | 包含 `{{args}}` | 替换参数占位符 |
| **DefaultArgumentProcessor** | 默认 | 追加用户输入到提示词 |
### 开发环境搭建
#### 目录结构管理
```bash
# 全局命令目录
~/.iflow/commands/
├── my-command.toml
├── code-reviewer.toml
└── project-analyzer.toml
# 项目命令目录
/path/to/project/.iflow/commands/
├── deploy.toml
├── test-runner.toml
└── build-helper.toml
```
#### 路径解析规则
系统使用以下函数获取命令目录：
```typescript
// 全局命令目录
getUserCommandsDir(): string {
return path.join(os.homedir(), '.iflow', 'commands');
}
// 项目命令目录
getProjectCommandsDir(projectRoot: string): string {
return path.join(projectRoot, '.iflow', 'commands');
}
```
#### 文件命名规范
- **基础命名**：`command-name.toml`
- **层级命名**：`parent:child.toml` → 创建嵌套命令结构
- **文件名清理**：非字母数字字符转换为连字符
- **扩展命名空间**：扩展命令自动获得 `[extensionName]` 前缀
### 实战开发示例
#### 示例1：简单信息查询命令
```toml
# ~/.iflow/commands/system-info.toml
description = "显示系统信息摘要"
prompt = """
请执行以下系统检查并提供摘要：
操作系统：!{uname -a}
磁盘使用：!{df -h /}
内存使用：!{free -h}
当前目录：!{pwd}
请分析系统状态并给出建议。
"""
```
使用方式：`/system-info`
#### 示例2：参数化代码生成器
```toml
# ./iflow/commands/generate-component.toml
description = "React组件生成器"
prompt = """
请生成一个React组件，需求如下：
{{args}}
请包含：
1. TypeScript接口定义
2. 完整的组件实现
3. 基础的CSS样式
4. 使用示例
遵循最佳实践和现代React模式。
"""
```
使用方式：`/generate-component 用户登录表单组件`
#### 示例3：复杂项目管理工具
```toml
# ./.iflow/commands/project:status.toml
description = "项目状态全面分析"
prompt = """
项目全面状态报告：
## 代码库状态
Git分支：!{git branch --show-current}
未提交变更：!{git status --porcelain | wc -l}
最近提交：!{git log --oneline -5}
## 依赖状态
Package.json存在：!{test -f package.json && echo "✅ 存在" || echo "❌ 不存在"}
Node模块状态：!{test -d node_modules && echo "✅ 已安装" || echo "❌ 未安装"}
## 代码质量
TypeScript文件数：!{find . -name "*.ts" -o -name "*.tsx" | wc -l}
JavaScript文件数：!{find . -name "*.js" -o -name "*.jsx" | wc -l}
测试文件数：!{find . -name "*.test.*" -o -name "*.spec.*" | wc -l}
请分析项目健康状况并提供改进建议。
"""
```
使用方式：`/project:status`
#### 示例4：动态脚本执行器
```toml
# ~/.iflow/commands/run-with-context.toml
description = "在项目上下文中执行命令"
prompt = """
在当前项目环境中执行指定操作：
项目根目录：!{pwd}
操作内容：{{args}}
执行结果：
!{{{args}}}
请分析执行结果并提供后续建议。
"""
```
使用方式：`/run-with-context npm test`
### 调试和测试指南
#### 配置验证
系统使用Zod进行TOML配置验证：
```typescript
const TomlCommandDefSchema = z.object({
prompt: z.string({
required_error: "The 'prompt' field is required.",
invalid_type_error: "The 'prompt' field must be a string.",
}),
description: z.string().optional(),
});
```
#### 常见错误和解决方案
| 错误类型 | 原因 | 解决方案 |
|----------|------|----------|
| `TOML解析错误` | 语法不正确 | 检查引号、缩进和转义字符 |
| `Schema验证失败` | 缺少必需字段 | 确保包含 `prompt` 字段 |
| `Shell命令被阻止` | 安全策略限制 | 添加到命令白名单或修改安全配置 |
| `命令不显示` | 文件位置错误 | 检查文件路径和重启CLI |
#### 开发工作流
1. **创建TOML文件**
```bash
mkdir -p ./.iflow/commands
touch ./.iflow/commands/my-command.toml
```
2. **编写配置内容**
```toml
description = "测试命令"
prompt = "这是一个测试命令"
```
3. **重启CLI加载新命令**
```bash
# 退出当前会话
/quit
# 重新启动
iflow
```
4. **测试命令功能**
```bash
/my-command 测试参数
```
5. **查看调试信息**
```bash
/log # 查看系统日志
/debug # 启用调试模式
```
## /docs_cn/examples/workflow.md
---
title: Workflow
description: 构建包含agents、commands、MCP工具的完整工作流程
sidebar_position: 8
---
# 工作流
> **功能概述**：Workflow是iFlow CLI中的工作流管理系统，整合agents、commands、IFLOW.md和MCP工具，创建完整的自动化工作流程。
>
> **学习时间**：15-20分钟
>
> **前置要求**：已安装iFlow CLI，完成身份验证，了解agents、commands和MCP的基本使用
## 什么是工作流
工作流将不同的AI能力（agents、commands、MCP工具）组合成完整的工作流程。通过workflow，您可以创建复杂的自动化任务链，实现从代码分析、开发、测试到部署的全流程自动化。
心流开放平台已经预置了大量优秀的工作流，例如小红书发文、深度研究、ppt制作、画流程图等，你可以在心流开放市场中下载安装到本地，再基于您个人独特的需求对工作流进行调整
对于开发者，心流开放平台预置了github spec、bmad、NioPD、ai-dev-task等开发者工作流，欢迎大家使用
## 目录结构
当您安装工作流后，项目目录会按照以下结构组织：
```
项目根目录/
├── .iflow/ # iFlow CLI配置和资源目录
│ ├── agents/ # 智能体配置文件夹
│ │ ├── agent1.md # 具体的agent配置文件
│ │ └── agent2.md # 更多agent配置
│ ├── commands/ # 自定义命令文件夹
│ │ ├── command1.md # 具体的command实现
│ │ └── command2.md # 更多command实现
│ ├── IFLOW.md # 详细的工作流文档和配置
│ └── settings.json # mcp相关配置
├── [项目文件夹]/ # 您的项目文件和代码
└── IFLOW.md # 工作流配置和说明文件
```
**目录说明：**
- `.iflow/` - 存储所有iFlow CLI相关的配置文件和资源
- `agents/` - 包含工作流中使用的智能体配置，每个agent一个md文件
- `commands/` - 存储自定义命令的实现代码，每个command一个md文件
- `IFLOW.md` - 工作流的核心配置文件，定义工作流程、参数和使用说明
- `settings.json` - 工作流所依赖的MCP工具配置和其余iFlow CLI的配置
- `项目文件夹` - 工作流产出的内容所依赖的文件目录结构
## 工作原理
### Workflow架构
```
输入数据 → Workflow引擎 → 步骤编排 → 结果输出
↓ ↓ ↓ ↓
[用户请求] → [流程解析] → [组件调用] → [结果聚合]
↓ ↓
[Agent执行] → [Command执行] → [MCP工具调用]
```
## 安装
1. 浏览[心流开放市场](https://platform.iflow.cn/agents?type=workflows)
2. 浏览并选择希望安装的工作流
3. 点击安装获取安装命令
4. 在终端中执行复制的命令
> 💡 工作流默认是安装在项目级别的，在其他工作目录无法使用
## 使用
首先您可以参考工作流对应的描述使用，一般情况下使用方式有两种：
1. 直接使用自然语言描述您的需求，iFlow CLI会自动调用工作流里的组件完成您的需求
2. 使用工作流内置的斜杠命令触发工作流的流程
## 举例
### AI PPT生成
1. 进入到一个工作文件夹中执行安装命令
```shell
iflow workflow add "ppt-generator-v3-OzctqA"
```
2. 在当前工作文件夹中启动iFlow CLI
```shell
iflow
```
3. 执行斜杠命令制作ppt
```shell
/ppt-generator
```
他会先了解当前的工作目录，了解里面的内容，然后和你不断地交互制作一个优美的ppt
### 流程图绘制
1. 进入到一个工作文件夹中执行安装命令
```shell
iflow workflow add "excalidraw-OzctqA"
```
2. 在当前工作文件夹中启动iFlow CLI
```shell
iflow
```
3. 执行斜杠命令绘制流程图
```shell
/excalidraw 你需要画图的主题
```
4. 在[Excalidraw](https://excalidraw.com/)中打开生成的图像文件
5. 简单微调就可以制作出来一个优美的流程图了
## 上传自己的工作流
当您开发了优秀的工作流并希望分享给其他用户时，需要先将工作流打包上传到心流开放平台。
### 打包工作流
1. **进入工作流根目录**
```bash
cd /path/to/your/workflow/directory
```
2. **打包所有工作流文件**
```bash
zip -r your-workflow-name.zip . -x your-workflow-name.zip
```
这个命令会：
- 压缩当前目录下的所有文件和文件夹（包括 `.iflow` 文件夹、项目文件、`IFLOW.md` 等）
- 包含隐藏文件（如 `.iflow` 目录）
- 排除生成的压缩包本身，避免递归包含
- 解压时保持原始目录结构，不会创建额外的目录层级
3. **验证打包内容**
```bash
unzip -l your-workflow-name.zip
```
### 上传到心流开放平台
1. 访问[心流开放平台](https://platform.iflow.cn/agents?type=workflows)
2. 登录您的账户
3. 点击"上传工作流"按钮
4. 上传您打包好的 `.zip` 文件
5. 填写工作流信息：
- 工作流名称和描述
- 使用说明和示例
- 标签和分类
- 版本信息
6. 提交审核，通过后即可在市场中展示
### 打包注意事项
- 确保 `IFLOW.md` 文件包含完整的工作流说明
- `.iflow/` 目录中的所有配置文件都应该被包含
- 移除任何敏感信息（如API密钥、个人数据等）
- 测试打包后的工作流能否正常安装和运行
- 添加适当的文档和使用示例
### 工作流分享最佳实践
1. **文档完善**：提供详细的使用说明和配置指南
2. **示例丰富**：包含典型的使用场景和输出示例
3. **配置清晰**：明确说明所需的环境配置和依赖
4. **测试充分**：在不同环境下测试工作流的稳定性
5. **持续维护**：及时更新和修复工作流中的问题
## /docs_cn/features/action.md
---
sidebar_position: 7
hide_title: true
---
# GitHub Actions
[iflow-cli-action](https://github.com/marketplace/actions/iflow-cli-action) 提供了基于 [GitHub Actions](https://docs.github.com/zh/actions/get-started/quickstart) 的自动化工作流集成能力. 使用它, 您可以几分钟内将 iFLOW CLI 的 AI 能力集成到 GitHub 代码库中, 使用 AI 去驱动任意自定义的自动化工作流程.
[在 GitHub Actions 市场上查看](https://github.com/marketplace/actions/iflow-cli-action)
## 快速开始
1. 在 [心流个人资料获取页面](https://iflow.cn/?open=setting) 获取您的 iFLOW CLI API 访问密钥.
2. 将访问密钥以 GitHub 仓库密钥的形式添加到您的代码仓库中 (Settings -> Secrets and variables -> Actions -> New repository secret, Secret 密钥名为 `IFLOW_API_KEY`), 👉🏻[了解如何使用 GitHub 仓库密钥](https://docs.github.com/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)).
3. 在您的代码仓库中创建 `.github/workflows/issue-triage.yml` 文件, 并添加以下内容:
```yaml
name: '🏷️ iFLOW CLI Automated Issue Triage'
on:
issues:
types:
- 'opened'
- 'reopened'
issue_comment:
types:
- 'created'
workflow_dispatch:
inputs:
issue_number:
description: 'issue number to triage'
required: true
type: 'number'
concurrency:
group: '${{ github.workflow }}-${{ github.event.issue.number }}'
cancel-in-progress: true
defaults:
run:
shell: 'bash'
permissions:
contents: 'read'
issues: 'write'
statuses: 'write'
jobs:
triage-issue:
if: |-
github.event_name == 'issues' ||
github.event_name == 'workflow_dispatch' ||
(
github.event_name == 'issue_comment' &&
contains(github.event.comment.body, '@iflow-cli /triage') &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
)
timeout-minutes: 5
runs-on: 'ubuntu-latest'
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: 'Run iFlow CLI Issue Triage'
uses: vibe-ideas/iflow-cli-action@main
id: 'iflow_cli_issue_triage'
env:
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
ISSUE_TITLE: '${{ github.event.issue.title }}'
ISSUE_BODY: '${{ github.event.issue.body }}'
ISSUE_NUMBER: '${{ github.event.issue.number }}'
REPOSITORY: '${{ github.repository }}'
with:
api_key: ${{ secrets.IFLOW_API_KEY }}
timeout: "3600"
extra_args: "--debug"
prompt: |
## Role
You are an issue triage assistant. Analyze the current GitHub issue
and apply the most appropriate existing labels. Use the available
tools to gather information; do not ask for information to be
provided.
## Steps
1. Run: `gh label list` to get all available labels.
2. Review the issue title and body provided in the environment
variables: "${ISSUE_TITLE}" and "${ISSUE_BODY}".
3. Classify issues by their kind (bug, enhancement, documentation,
cleanup, etc) and their priority (p0, p1, p2, p3). Set the
labels according to the format `kind/*` and `priority/*` patterns.
4. Apply the selected labels to this issue using:
`gh issue edit "${ISSUE_NUMBER}" --add-label "label1,label2"`
5. If the "status/needs-triage" label is present, remove it using:
`gh issue edit "${ISSUE_NUMBER}" --remove-label "status/needs-triage"`
## Guidelines
- Only use labels that already exist in the repository
- Do not add comments or modify the issue content
- Triage only the current issue
- Assign all applicable labels based on the issue content
- Reference all shell variables as "${VAR}" (with quotes and braces)
- name: 'Post Issue Triage Failure Comment'
if: |-
${{ failure() && steps.iflow_cli_issue_triage.outcome == 'failure' }}
uses: 'actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea'
with:
github-token: '${{ secrets.GITHUB_TOKEN }}'
script: |-
github.rest.issues.createComment({
owner: '${{ github.repository }}'.split('/')[0],
repo: '${{ github.repository }}'.split('/')[1],
issue_number: '${{ github.event.issue.number }}',
body: 'There is a problem with the iFlow CLI issue triaging. Please check the [action logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.'
})
```
这是一个利用 iFLOW CLI Action 对 GitHub issues 内容进行识别, 然后进行自动打标签分类的工作流程, 一但您的代码仓库中有新的 issue 创建, 改工作流就会自动执行. 您也可以 issue 中评论回复 `@iflow-cli /triage` 即可触发该工作流.
## 更多示例使用场景
[Examples](https://github.com/iflow-ai/iflow-cli-action/tree/main/examples) 中提供了完整基于 GitHub issues、GitHub Pull Requests 的自动化工作流程编排文件, 您可以直接拷贝到您代码仓库的 `.github/workflows` 目录中直接使用.
## 最佳实践
### IFLOW.md
在您的仓库根目录中创建一个 IFLOW.md 文件来定义代码风格指南、代码评审标准、项目特定规则。此文件将指导 iFLOW CLI 理解您的项目标准。
### 安全考虑
**永远不要将 API 密钥提交到代码仓库中!**
始终使用 GitHub 密钥（例如, `${{ secrets.IFLOW_API_KEY }}`）而不是在工作流程文件中直接硬编码 iFLOW CLI 的 API 密钥。
### GitHub Actions 使用成本
GitHub Actions 对于个人账号和组织账号均有不同的免费额度, 详情请查阅 [GitHub Actions 的计费文档](https://docs.github.com/zh/billing/concepts/product-billing/github-actions).
## 社区使用案例
- [使用 iflow-cli-action 在 GitHub 与 Qwen3-Coder、Kimi K2 一起快速提升你的生产力](https://shan333.cn/2025/08/16/the-next-level-of-developer-productivity-with-iflow-cli-action/)
> 欢迎提交您的使用案例
## /docs_cn/features/checkpointing.md
---
sidebar_position: 8
hide_title: true
---
# 检查点
> **功能概述**：检查点是iFlow CLI的安全回退系统，在AI工具修改文件前自动保存项目状态快照。
>
> **学习时间**：5-10分钟
>
> **前置要求**：了解基本的Git概念，熟悉文件版本管理
## 什么是检查点
检查点是iFlow CLI提供的安全保障机制，在AI工具修改文件系统之前自动保存项目状态的完整快照。这个功能让您可以安全地实验和应用代码更改，随时可以立即回退到工具运行前的状态，确保您的项目安全。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 自动创建 | AI工具执行前自动保存状态 | 无需手动操作 |
| 完整快照 | 保存文件、对话、工具调用 | 全面的状态恢复 |
| 独立存储 | 不干扰项目Git仓库 | 安全隔离 |
| 即时恢复 | 一键回退到任意检查点 | 快速撤销更改 |
| 本地存储 | 所有数据保存在本地 | 隐私和安全 |
## 工作原理
### 检查点创建流程
```
工具调用 → 权限确认 → 状态快照 → 工具执行 → 检查点完成
↓
[AI请求] → [用户批准] → [文件备份] → [安全执行] → [状态保存]
```
### 快照内容组成
#### 1. Git状态快照
- 在 `~/.iflow/snapshots/<project_hash>` 创建影子Git仓库
- 捕获项目文件的完整状态
- 不干扰项目原有的Git仓库
#### 2. 对话历史
- 保存与AI助手的完整对话记录
- 包括上下文和交互状态
- 支持对话状态的完整恢复
#### 3. 工具调用信息
- 存储即将执行的具体工具调用
- 记录参数和执行上下文
- 支持重新执行或修改调用
### 数据存储位置
| 数据类型 | 存储路径 | 说明 |
|---------|----------|------|
| Git快照 | `~/.iflow/snapshots/<project_hash>` | 影子Git仓库 |
| 对话历史 | `~/.iflow/cache/<project_hash>/checkpoints` | JSON格式文件 |
| 工具调用 | `~/.iflow/cache/<project_hash>/checkpoints` | 调用详情记录 |
## 详细功能说明
### 启用检查点功能
检查点功能默认关闭，可通过以下方式启用：
#### 命令行参数
```bash
# 启用检查点功能
iflow --checkpointing
```
注意！必须要在default mode才能生效
进入iflow 之后使用两下shift + tab切换到default mode
#### 配置文件设置
在 `settings.json` 中添加：
```json
{
"checkpointing": {
"enabled": true
}
```
### 使用检查点
#### 创建检查点
- 检查点在AI工具修改文件前自动创建
- 每个检查点都有唯一的时间戳标识
- 系统会提示检查点创建完成
#### 查看检查点
```bash
# 列出所有检查点
/restore
# 查看检查点详情
/restore <checkpoint-name>
```
#### 恢复检查点
```bash
# 交互式选择检查点
/restore
# 恢复特定检查点
/restore <checkpoint-name>
```
## 使用示例
### 安全的代码修改
```bash
# 1. AI提出修改建议
> 我想重构这个函数以提高性能
# 2. 系统自动创建检查点
[检查点] 正在创建项目状态快照...
[检查点] 快照创建完成: checkpoint_20231215_143022
# 3. AI执行修改
# ... 文件修改操作 ...
# 4. 如需回退
/restore checkpoint_20231215_143022
```
### 实验性更改
```bash
# 尝试大规模重构
> 请帮我重构整个项目架构
# 系统创建检查点后执行
# 如果结果不满意，可以轻松回退
/restore
```
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 检查点创建失败 | 磁盘空间不足或权限问题 | 检查磁盘空间和文件权限 |
| 恢复失败 | 检查点文件损坏 | 使用其他检查点或手动恢复 |
| 检查点列表为空 | 功能未启用或无修改 | 启用功能并进行文件操作 |
| 恢复后文件丢失 | 检查点不完整 | 检查Git仓库状态 |
### 安全注意事项
- **存储空间**：检查点会占用磁盘空间，定期清理旧检查点
- **隐私保护**：检查点包含完整对话历史，注意敏感信息
- **Git冲突**：恢复可能与当前Git状态冲突，需要手动处理
- **大文件处理**：大型项目的检查点可能耗时较长
### 平台兼容性
| 平台 | 支持程度 | 特殊说明 |
|------|----------|----------|
| Windows | 完全支持 | 路径处理自动适配 |
| macOS | 完全支持 | 完整的文件系统支持 |
| Linux | 完全支持 | 原生Git集成 |
## /docs_cn/features/ide.md
---
sidebar_position: 5
hide_title: true
---
# 添加到您的 IDE
了解如何将 iFlow 添加到您喜爱的 IDE
iFlow 无缝集成于流行的集成开发环境（IDE），以增强您的编码工作流程。此集成允许您在您首选的开发环境中直接利用 iFlow 的功能。
## 支持的 IDE
iFlow 目前支持两个主要的 IDE 系列：
- **Visual Studio Code**
- [下载 iFlow VSCode 插件](https://marketplace.visualstudio.com/items?itemName=iflow-cli.iflow-cli-vscode-ide-companion)
- [下载类 VSCode 编辑器插件](https://open-vsx.org/extension/iflow-cli/iflow-cli-vscode-ide-companion)
- 需要 VSCode 1.101.0 或更高版本
- **JetBrains IDEs**
- [下载 iFlow JetBrains 插件](https://cloud.iflow.cn/iflow-cli/iflow-idea-0.0.2.zip)
- 仅支持 2024.1 及以后版本
- **Zed**
- 需要zed 0.201.0版本以上
# 功能
- **快速启动：** 点击 UI 中的 iFlow 按钮
<img src="https://img.alicdn.com/imgextra/i2/O1CN01BimMnx1rjXaZ397V3_!!6000000005667-2-tps-1038-632.png"/>
- **选择上下文：** 编辑器中选定的文本将自动添加到 iFlow 的上下文中
<img src="https://img.alicdn.com/imgextra/i3/O1CN01awbx1X1UaciN8jiqC_!!6000000002534-2-tps-2086-748.png"/>
- **文件感知：** iFlow 可以看到您在编辑器中打开了哪些文件
<img src="https://img.alicdn.com/imgextra/i1/O1CN01CnqGw01pzuVt2hTdI_!!6000000005432-2-tps-2084-742.png"/>
- **连接感知：** 当您在 VSCode 的终端中启动 iFlow 时，iFlow 会自动检测并连接。当连接成功后，iFlow 会在您的终端中显示连接状态"IDE connected"。您也可使用 iFlow 提供的命令"/ide"来手动建立连接
<img src="https://img.alicdn.com/imgextra/i4/O1CN01qVatHO1tHGMhwmN5x_!!6000000005876-2-tps-1867-211.png"/>
<img src="https://img.alicdn.com/imgextra/i4/O1CN01466HGN1zPP6KYrGbW_!!6000000006706-2-tps-1803-582.png"/>
- **关闭连接：** 若您需要关闭连接，请使用 iFlow 提供的命令"/ide"，并选择"Disconnect from IDE"
# 安装
## VS Code
1. 打开 VSCode 请注意版本号至少是 1.101.0
2. 打开插件市场，搜索 iflow
3. 点击安装 iFlow CLI 即可
> :bulb: **提示：** 当您在 VSCode 的终端中启动 iFlow 时，它会自动检测并安装扩展，注意：此功能需要您安装 iflow-cli-vscode-ide-companion-0.1.7及以上版本，若您安装的版本为iflow-cli-vscode-ide-companion-0.1.6级以下，则需要您手动安装。
## JetBrains IDE
1. 打开 JetBrains IDE, 注意仅支持2024.1及以后版本
2. 打开插件市场
3. 安装iFlow
- 点击 JetBrains IDE 顶部右侧的设置图标，打开插件市场
- 搜索iflow
<img src="https://img.alicdn.com/imgextra/i4/O1CN01IkFru21kLzvI66OBO_!!6000000004668-2-tps-1824-1400.png"/>
- 也可以选择从磁盘安装
<img src="https://img.alicdn.com/imgextra/i2/O1CN01SnJDgE1iMnNVVMTTy_!!6000000004399-2-tps-806-778.png"/>
<img src="https://img.alicdn.com/imgextra/i2/O1CN01Qy3p2o1hcXNKAoIZ5_!!6000000004298-2-tps-1410-662.png" />
- 选择 iflow-idea-最新版本号.zip 安装包，安装包在文档上方有对应的下载链接
<img src="https://img.alicdn.com/imgextra/i3/O1CN01Xe4tWg1e59ezJfMgZ_!!6000000003819-2-tps-2268-1156.png" />
- 重启ide
<img src="https://img.alicdn.com/imgextra/i3/O1CN01P7G7MR25EJCZi8BYT_!!6000000007494-2-tps-1324-742.png" />
## Zed 编辑器
1. 打开zed，版本号至少是0.201.0
2. 点击个人头像，选择Settings
<img src="https://intranetproxy.alipay.com/skylark/lark/0/2025/png/21956389/1757998662129-7ee9c926-1920-4afc-b75a-15282f3440b0.png?x-oss-process=image%2Fformat%2Cwebp" />
3. 配置iflow
```bash
"agent_servers": {
"iFlow CLI": {
"command": "iflow",
"args": ["--experimental-acp"]
}
}
```
<img src="https://intranetproxy.alipay.com/skylark/lark/0/2025/png/21956389/1757998738785-b37c17cf-6922-476e-8ad7-157ce1da6121.png?x-oss-process=image%2Fformat%2Cwebp" />
4. 右下角点击agent panel
<img src="https://intranetproxy.alipay.com/skylark/lark/0/2025/png/21956389/1757998696212-5380ea30-6419-479d-a5cf-3a528407fad8.png?x-oss-process=image%2Fformat%2Cwebp" />
5. 创建iFlow CLI对话
<img src="https://intranetproxy.alipay.com/skylark/lark/0/2025/png/21956389/1757998709856-83e955e5-a793-449c-9f8b-b172e41e937e.png?x-oss-process=image%2Fformat%2Cwebp" />
6. 接下来就可以在输入框对话了
## /docs_cn/features/interactive.md
---
sidebar_position: 1
hide_title: true
---
# 交互模式
> **功能概述**：iFlow CLI 提供多种灵活的交互方式，支持文本输入、图片处理、文件引用和智能多模态处理。
>
> **学习时间**：10-15分钟
>
> **前置要求**：已安装并配置iFlow CLI，了解基本命令行操作
## 什么是交互模式
交互模式是iFlow CLI 的核心功能，它允许用户通过多种方式与AI进行自然的对话和协作。系统支持文本、图片、文件引用等多种输入形式，并提供智能的多模态处理能力，让任何模型都能"理解"图片内容。
## 核心特点
| 特点 | 说明 | 平台支持 |
|------|------|----------|
| 多种输入方式 | 文本、图片、文件引用等多种输入形式 | 全平台 |
| 智能多模态处理 | 让任何模型都能"理解"图片内容 | 全平台 |
| 自动内容检测 | 智能识别并处理不同类型的输入内容 | 全平台 |
| 大文本优化 | 自动处理长文本，优化界面显示 | 全平台 |
| 实时响应 | 实时处理用户输入，无需等待 | 全平台 |
## 工作原理
### 输入处理流程
```
用户输入 → 内容类型检测 → 预处理 → 模型适配 → AI响应
↓
[文本/图片/文件] → [自动识别] → [格式优化] → [多模态处理] → [生成回复]
```
### 智能适配机制
- **文本输入**：直接传递给AI模型处理
- **图片输入**：自动检测模型能力，必要时生成图片描述
- **文件引用**：读取文件内容并整合到对话上下文
- **混合输入**：智能组合不同类型的输入内容
## 详细功能说明
### 文本输入
#### 单行文本
直接在命令行界面输入您的问题或指令：
```bash
> 帮我优化这个React组件的性能
```
#### 多行文本输入
支持多种方式输入多行文本：
| 方法 | 操作 | 说明 |
|------|------|------|
| 反斜杠换行 | `\` + `Enter` | 快速创建多行输入 |
| Shift + Enter | `Shift` + `Enter` | 终端配置后可用 |
示例：
```bash
> 请帮我实现一个用户管理系统，包括：\
1. 用户注册和登录功能
2. 用户信息的增删改查
3. 权限管理
4. 数据持久化
```
### 图片处理
#### 支持的图片格式
| 格式 | 扩展名 | 说明 |
|------|--------|------|
| PNG | .png | 高质量图片，支持透明度 |
| JPEG | .jpg, .jpeg | 压缩图片格式 |
| GIF | .gif | 支持动图 |
| WebP | .webp | 现代图片格式 |
| BMP | .bmp | 位图格式 |
#### 图片输入方式
**截图粘贴**
| 平台 | 截图快捷键 | 粘贴快捷键 |
|------|------------|------------|
| Windows | `Win + Shift + S` | `Ctrl + V` |
| macOS | `Cmd + Shift + 4` | `Cmd + V` |
| Linux | `PrtScn` 或其他 | `Ctrl + V` |
操作步骤：
1. 使用系统截图工具截取需要分析的屏幕区域
2. 在iFlow CLI 中按快捷键粘贴
3. 系统自动生成图片占位符并处理
**文件粘贴**
- 在文件管理器中复制图片文件
- 在CLI中使用粘贴快捷键
粘贴后显示效果：
```bash
> [Pasted image #1] 这个界面有什么问题？
```
需要注意的是，原生终端、iTerm 终端以及 IDE 内置终端会强制过滤掉图片的粘贴事件，导致使用平台的原生粘贴快捷键时无法粘贴图片（比如 macOS 使用 `Cmd + V` 粘贴图片无效），此时可以使用 `Ctrl + V` 或 `Shift + Ctrl + V` 绕过这个过滤来粘贴图片。
#### 图片处理示例
```bash
> [Pasted image #1] 请分析这个用户界面的设计问题
> [Pasted image #2] 这两个界面布局哪个更好？
> 帮我根据 [Pasted image #1] 这个设计稿写出对应的CSS代码
```
### 大文本处理
#### 自动检测规则
| 检测项 | 阈值 | 处理方式 |
|--------|------|----------|
| 长文本粘贴 | >800字符 | 生成文本占位符 |
| 长内容显示 | >5000字符 | 截断显示优化 |
| 占位符格式 | - | `[Pasted text #X +Y lines]` |
#### 界面优化特性
- **视觉简洁**：避免长文本在终端中造成滚屏混乱
- **内容完整**：虽然显示被优化，但模型仍能获得完整的原始文本
- **智能截断**：显示前2000个字符和最后2000个字符，中间内容折叠
- **标识清晰**：占位符明确标识文本块的行数，便于识别内容规模
#### 使用示例
```bash
> 请帮我重构这段代码：[Pasted text #1 +45 lines]
> 分析这个日志文件中的错误：[Pasted text #2 +120 lines]
```
#### 操作流程
1. 复制大量文本内容到剪贴板
2. 在CLI中按 `Ctrl/Cmd + V`
3. 系统自动生成占位符并保存原始内容
4. 继续输入您的问题或指令
### 文件引用
#### 引用方式
| 类型 | 语法 | 示例 |
|------|------|------|
| 单个文件 | `@文件路径` | `@src/App.tsx` |
| 目录引用 | `@目录路径` | `@src/components` |
| 多文件 | 空格分隔 | `@file1.ts @file2.ts` |
#### 使用示例
**单文件引用**
```bash
> 帮我优化 @src/components/UserProfile.tsx 这个组件
> 请解释 @docs/api.md 中的API设计思路
```
**目录引用**
```bash
> 分析 @src/utils 目录下的工具函数
> 重构 @src/components 目录的组件结构
```
**多文件引用**
```bash
> 比较 @src/old-component.tsx 和 @src/new-component.tsx 的区别
> 根据 @package.json 和 @tsconfig.json 配置优化项目结构
```
### 智能多模态处理
#### 核心特性
iFlow CLI 的独特之处在于其智能多模态处理机制，让任何模型都能"看懂"图片。
#### 工作原理
**自动图片描述生成**
| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 模型能力检测 | 检测主模型是否支持多模态 |
| 2 | 多模态调用 | 不支持时自动调用多模态模型 |
| 3 | 描述生成 | 生成详细的图片描述信息 |
| 4 | 内容整合 | 将描述传递给主模型处理 |
**描述内容包括**
- 整体布局和构图
- 主要对象和位置关系
- 颜色信息和视觉特征
- 文字内容（完整转录）
- 背景环境和细节特征
#### 注册配置
**心流AI方式登录**
| 项目 | 说明 |
|------|------|
| 推荐选择 | 系统提供的模型都经过优化 |
| 自动处理 | 自动使用 `qwen-vl-max` 生成图片描述 |
| 配置需求 | 无需手动配置，完全自动化 |
**OpenAI兼容方式登录**
| 配置项 | 说明 | 必需 |
|---------|------|------|
| 主模型名称 | 指定主要使用的模型 | 是 |
| 多模态模型 | 用于图片描述生成 | 否 |
| 跳过配置 | 直接发送给主模型 | 否 |
#### 性能说明
| 项目 | 说明 |
|------|--------------------------------------|
| 优势 | 让所有模型都具备图片理解能力 |
| 注意 | 非多模态模型处理图片速度稍慢（因为需要先生成图片描述再输入给主模型理解） |
| 建议 | 频繁多模态需求建议直接使用多模态模型 |
### 键盘快捷键
#### 基础快捷键
| 功能 | 快捷键 | 说明 |
|------|--------|------|
| 取消操作 | `Ctrl/Cmd + C` | 取消当前输入或生成 |
| 退出程序 | `Ctrl/Cmd + D` | 退出CLI会话 |
| 清屏 | `Ctrl/Cmd + L` | 清空终端屏幕 |
| 历史命令 | `↑/↓` | 浏览命令历史 |
#### 输入相关
| 功能 | 快捷键 | 说明 |
|------|--------|------|
| 粘贴内容 | `Ctrl/Cmd + V` | 自动检测图片、文本 |
| 多行输入 | `\` + `Enter` | 反斜杠换行 |
| 多行输入 | `Shift/Option + Enter` | 根据终端配置 |
#### Vim模式
使用 `/vim` 命令启用后支持：
| 操作 | 按键 | 说明 |
|------|------|------|
| 光标移动 | `h/j/k/l` | 左/下/上/右 |
| 删除行 | `dd` | 删除当前行 |
| 删除字符 | `x` | 删除当前字符 |
## 使用示例
### 常见场景
#### UI设计分析
```bash
> [Pasted image #1] 请分析这个登录页面的用户体验问题
```
#### 代码调试
```bash
> [Pasted image #1] 这个错误截图显示的问题如何解决？
```
#### 文件分析
```bash
> 请分析 @src/components/Header.tsx 的性能问题并提供优化建议
```
#### 复杂问题
```bash
> 请帮我实现一个用户管理系统，包括：\
1. 用户注册和登录功能
2. 用户信息的增删改查
3. 权限管理
4. 数据持久化
```
### 最佳实践
#### 图片使用技巧
- **UI设计分析**：截图界面后询问设计改进建议
- **代码调试**：粘贴错误截图快速定位问题
- **文档理解**：上传图表、流程图等复杂图像内容
- **比较分析**：同时粘贴多张图片进行对比
#### 文本处理优化
- **大文件处理**：利用自动占位符功能处理长代码或日志
- **结构化询问**：使用多行输入组织复杂问题
- **上下文引用**：结合 `@` 文件引用提供完整上下文
#### 模型选择建议
- **纯文本任务**：使用文本模型即可，速度更快
- **偶尔图片需求**：继续使用文本模型，自动处理图片
- **频繁多模态**：选择多模态模型以获得最佳体验
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 图片粘贴失败 | 格式不支持或剪贴板无数据 | 检查图片格式，重新截图或复制 |
| 文件引用无效 | 路径错误或文件不存在 | 确认文件路径正确且文件可访问 |
| 多行输入异常 | 终端配置问题 | 尝试不同的换行快捷键组合 |
| 多模态处理错误 | 模型配置不正确 | 检查模型支持情况和配置 |
| 大文本上传失败 | 内容过大或网络问题 | 分段上传或检查网络连接 |
### 诊断步骤
1. **权限检查**
- 确认系统允许CLI访问剪贴板
- 检查文件读取权限
2. **网络连接**
- 确认网络连接正常（多模态处理需要API调用）
- 检查防火墙设置
3. **配置验证**
- 查看错误提示信息
- 根据提示调整操作
- 重启CLI确保配置生效
### 平台兼容性
| 平台 | 支持情况 | 注意事项 |
|------|----------|----------|
| Windows | 完全支持 | 注意路径分隔符 |
| macOS | 完全支持 | 系统权限可能需要授权 |
| Linux | 完全支持 | 依赖系统剪贴板工具 |
## /docs_cn/features/memory-import.md
---
sidebar_position: 3
hide_title: true
---
# 内容导入
> **功能概述**：内容导入是iFlow CLI的模块化内容管理系统，支持通过@文件语法导入外部内容。
>
> **学习时间**：5-10分钟
>
> **前置要求**：了解基本的文件路径概念，熟悉Markdown语法
## 什么是内容导入
内容导入是iFlow CLI提供的模块化内容管理功能，允许您通过 `@file.md` 语法从其他文件导入内容。这个功能让您能够将大型的配置文件拆分为更小、更易管理的组件，实现内容的模块化组织和重复使用。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 模块化管理 | 将大文件拆分为小组件 | 提高可维护性 |
| 路径灵活性 | 支持相对和绝对路径 | 适应不同项目结构 |
| 安全防护 | 内置循环导入检测 | 防止无限递归 |
| 实时处理 | 导入时动态解析内容 | 保持内容同步 |
| 跨项目共享 | 组件可在多项目间重用 | 提高开发效率 |
## 工作原理
### 导入处理流程
```
文件读取 → 路径解析 → 安全检查 → 内容导入 → 递归处理
↓
[@file.md] → [路径计算] → [循环检测] → [内容插入] → [嵌套导入]
```
### 安全机制
- **路径验证**：检查文件路径的合法性和安全性
- **循环检测**：防止文件间的循环引用
- **权限控制**：确保只能访问授权的文件
- **错误恢复**：导入失败时的优雅处理
## 详细功能说明
### 基本语法
使用 `@` 符号后跟您要导入的文件路径：
```markdown
# 主要的配置文件
这是主要内容。
@./components/instructions.md
这里是更多内容。
@./shared/configuration.md
```
### 支持的路径格式
| 路径类型 | 语法示例 | 说明 |
|---------|----------|------|
| 同目录 | `@./file.md` | 从同一目录导入文件 |
| 父目录 | `@../file.md` | 从父目录导入文件 |
| 子目录 | `@./components/file.md` | 从子目录导入文件 |
| 绝对路径 | `@/absolute/path/to/file.md` | 使用绝对路径导入 |
## 使用示例
### 基本导入场景
#### 简单文件导入
```markdown
# 主配置文件
欢迎来到我的项目！
@./getting-started.md
## 功能特性
@./features/overview.md
```
#### 模块化组织
```markdown
# 项目文档结构
项目根目录/
├── IFLOW.md # 主配置文件
├── components/
│ ├── instructions.md # 使用说明组件
│ ├── setup.md # 设置指南组件
│ └── examples.md # 示例代码组件
└── shared/
├── common.md # 公共配置
└── templates.md # 模板文件
```
### 高级导入功能
#### 嵌套导入
导入的文件本身也可以包含导入，创建多层次结构：
```markdown
# main.md
@./header.md
@./content.md
@./footer.md
```
```markdown
# header.md
# 项目标题
@./shared/title.md
@./shared/metadata.md
```
#### 条件性导入
根据不同情况导入不同的配置：
```markdown
# 开发环境配置
@./configs/development.md
# 生产环境配置
@./configs/production.md
```
### 安全防护机制
#### 循环导入检测
系统自动检测并防止文件间的循环引用：
```markdown
# file-a.md
@./file-b.md
# file-b.md
@./file-a.md <!-- 系统会检测到循环引用并阻止 -->
```
**检测机制**：
- 维护导入路径栈
- 检查每个新导入是否已存在于路径中
- 发现循环时立即中止并报告错误
#### 安全限制
| 安全项 | 限制 | 作用 |
|--------|------|------|
| 路径验证 | 只允许授权目录 | 防止访问敏感文件 |
| 深度限制 | 最大5层嵌套 | 防止无限递归 |
| 文件类型 | 仅支持文本文件 | 避免二进制文件问题 |
| 权限检查 | 验证读取权限 | 确保文件可访问 |
#### 错误处理策略
**文件丢失处理**
- 优雅失败，不中断整个导入过程
- 在输出中显示友好的错误注释
- 记录详细错误信息到日志
**权限错误处理**
- 显示适当的权限错误消息
- 提供解决方案建议
- 继续处理其他可用的导入
**格式错误处理**
- 检测文件格式和编码问题
- 提供格式修复建议
- 支持多种文本编码格式
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 导入失败 | 文件路径错误或文件不存在 | 检查文件路径和文件是否存在 |
| 循环引用错误 | 文件间存在相互引用 | 检查并打破循环引用链 |
| 权限被拒绝 | 文件读取权限不足 | 检查文件权限设置 |
| 深度超限 | 嵌套导入层级过深 | 减少嵌套层级或重新组织结构 |
| 编码错误 | 文件编码格式不支持 | 转换文件编码为UTF-8 |
### 诊断步骤
1. **路径验证**
- 确认导入路径语法正确
- 检查相对路径的基准目录
- 验证绝对路径的完整性
2. **文件检查**
- 确认目标文件存在
- 检查文件读取权限
- 验证文件编码格式
3. **结构分析**
- 绘制导入依赖图
- 检查是否存在循环引用
- 计算导入深度层级
4. **日志分析**
- 查看详细错误日志
- 分析导入处理过程
- 识别具体失败点
### 最佳实践
#### 文件组织建议
- **模块化设计**：按功能将内容分解为独立模块
- **层次结构**：建立清晰的目录层次结构
- **命名规范**：使用描述性的文件名和目录名
- **文档说明**：为每个导入模块添加用途说明
#### 维护建议
- **定期检查**：定期检查导入链的完整性
- **版本控制**：将所有导入文件纳入版本控制
- **依赖文档**：维护导入依赖关系文档
- **测试验证**：定期测试导入功能的正确性
### 平台兼容性
| 平台 | 支持程度 | 特殊说明 |
|------|----------|----------|
| Windows | 完全支持 | 路径分隔符自动转换 |
| macOS | 完全支持 | 支持区分大小写的文件系统 |
| Linux | 完全支持 | 完整的POSIX路径支持 |
## /docs_cn/features/output-style.md
---
sidebar_position: 4
hide_title: true
---
# 输出样式
> **功能概述**：输出样式允许您将 iFlow CLI 适配用于软件工程之外的用途，自定义AI助手的行为模式。
>
> **学习时间**：10-15分钟
>
> **前置要求**：已安装并配置iFlow CLI，了解基本配置概念
## 什么是输出样式
输出样式允许您将 iFlow CLI 用作任何类型的任务，同时保持其核心功能，如运行本地脚本、读写文件和跟踪 TODO。
## 内置输出样式
iFlow CLI 的 **默认(Default)** 输出样式是现有的系统提示，旨在帮助您高效完成软件工程任务。
还有两种额外的内置输出样式，专注于提供更详细的解释和帮助您学习：
* **解释性(Explanatory)**：在帮助您完成软件工程任务的过程中提供教育性的"见解"。帮助您理解实现选择和代码库模式。
* **学习(Learning)**：协作式的边做边学模式，iFlow CLI 不仅会在编码时分享"见解"，还会要求您自己贡献小的、战略性的代码片段。iFlow CLI 会在您的代码中添加 `TODO(human)` 标记供您实现。
## 输出样式的工作原理
输出样式直接修改 iFlow CLI 的系统提示。
* 非默认输出样式排除了通常内置在 iFlow CLI 中的特定于代码生成和高效输出的指令（如简洁回应和通过测试验证代码）
* 相反，这些输出样式在系统提示中添加了自己的自定义指令。
## 更改您的输出样式
您可以：
* 运行 `/output-style` 来访问菜单并选择您的输出样式
* 运行 `/output-style [样式]`，如 `/output-style explanatory`，直接切换到某种样式
## 创建自定义输出样式
要在 iFlow 的帮助下设置新的输出样式，运行
`/output-style:new I want an output style that ...`
默认情况下，通过 `/output-style:new` 创建的输出样式作为 markdown 文件保存在用户级别的 `~/.iflow/output-styles` 中，可以跨项目使用。它们具有以下结构：
```markdown
---
name: My Custom Style
description:
A brief description of what this style does, to be displayed to the user
---
# Custom Style Instructions
You are an interactive CLI tool that helps users with software engineering
tasks. [Your custom instructions here...]
## Specific Behaviors
[Define how the assistant should behave in this style...]
```
您也可以创建自己的输出样式 Markdown 文件，并将它们保存在用户级别（`~/.iflow/output-styles`）或项目级别（`.iflow/output-styles`）。
## 与相关功能的比较
### 输出样式 vs. IFLOW.md
输出样式完全去掉了 iFlow CLI 默认系统提示中特定于输出样式的部分。IFLOW.md 不会编辑 iFlow CLI 的默认系统提示。IFLOW.md 将内容作为用户消息添加在 iFlow CLI 默认系统提示之后。
### 输出样式 vs. SubAgent
输出样式直接影响主代理循环，只影响系统提示。SubAgent 被调用来处理特定任务，可以包括额外的设置，如要使用的模型、它们可用的工具以及何时使用代理的一些上下文。
### 输出样式 vs. 自定义斜杠命令
您可以将输出样式视为"存储的系统提示"，将自定义斜杠命令视为"存储的提示"。
## /docs_cn/features/sandbox.md
---
sidebar_position: 6
hide_title: true
---
# 沙箱配置
iFlow CLI 可以在沙箱环境中执行潜在不安全的操作（如 shell 命令和文件修改）以保护您的系统。
沙箱默认禁用，但您可以通过几种方式启用：
- 使用 `--sandbox` 或 `-s` 标志。
- 设置 `IFLOW_SANDBOX` 环境变量。
默认情况下，它使用预构建的 `iflow-cli-sandbox` Docker 镜像。
对于项目特定的沙箱需求，您可以在项目根目录的 `.iflow/sandbox.Dockerfile` 创建自定义 Dockerfile。此 Dockerfile 可以基于基础沙箱镜像：
```dockerfile
FROM iflow-cli-sandbox
# 在这里添加您的自定义依赖项或配置
# 例如：
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config
```
当 `.iflow/sandbox.Dockerfile` 存在时，您可以在运行 iFlow CLI 时使用 `BUILD_SANDBOX` 环境变量自动构建自定义沙箱镜像：
```bash
BUILD_SANDBOX=1 iflow -s
```
## /docs_cn/features/slash-commands.md
---
sidebar_position: 2
hide_title: true
---
# 斜杠命令
> **功能概述**：斜杠命令是iFlow CLI的内置控制系统，提供对各种功能和设置的快速访问。
>
> **学习时间**：15-20分钟
>
> **前置要求**：已安装并启动iFlow CLI，熟悉基本的命令行操作
## 什么是斜杠命令
斜杠命令是以 `/` 开头的特殊指令，用于控制iFlow CLI的行为和配置。这些命令可以在对话过程中随时使用，无需中断当前的工作流程。通过斜杠命令，您可以管理会话状态、配置系统设置、访问工具和获取帮助信息。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 即时执行 | 命令立即生效，无需重启 | 提高工作效率 |
| 上下文保持 | 不会中断当前对话流程 | 保持工作连续性 |
| Tab补全 | 支持命令和参数自动补全 | 减少输入错误 |
| 彩色输出 | 状态信息使用颜色编码 | 提高可读性 |
| 子命令结构 | 复杂命令支持层级结构 | 功能组织清晰 |
## 工作原理
### 命令执行流程
```
用户输入 → 命令解析 → 参数验证 → 功能执行 → 结果反馈
↓
[/command args] → [解析器] → [验证器] → [执行器] → [输出]
```
### 命令分类系统
- **系统管理**：系统信息、配置管理、状态监控
- **会话控制**：对话管理、历史记录、状态保存
- **工具集成**：IDE连接、MCP服务器、扩展管理
- **开发辅助**：项目初始化、调试支持、错误报告
## 详细功能说明
### 系统管理命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `/about` | 系统信息 | 显示CLI版本、操作系统、模型版本等综合信息 |
| `/auth` | 身份验证 | 配置或更改身份验证提供商 |
| `/theme` | 主题设置 | 自定义CLI外观主题 |
| `/model` | 模型切换 | 更改正在使用的AI模型 |
| `/editor` | 编辑器配置 | 配置首选的外部编辑器 |
| `/privacy` | 隐私信息 | 显示隐私通知和数据处理信息 |
### 会话控制命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `/chat` | 对话管理 | 保存、恢复、删除对话检查点 |
| `/clear` | 清屏重置 | 清除屏幕并重置对话历史 |
| `/compress` | 内容压缩 | 使用AI将对话历史压缩为摘要 |
| `/memory` | 内容管理 | 与CLI的内容系统交互 |
| `/restore` | 状态恢复 | 恢复到之前的检查点状态 |
| `/quit` | 退出程序 | 退出CLI会话并显示统计信息 |
### 工具集成命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `/ide` | IDE集成 | 发现和连接到可用的IDE服务器 |
| `/ide-status` | IDE状态 | 查询当前IDE连接状态 |
| `/ide-tool` | IDE工具 | 访问特定的IDE集成工具 |
| `/mcp` | MCP管理 | 管理MCP服务器、工具和身份验证 |
| `/tools` | 工具列表 | 列出所有可用的内置CLI工具 |
| `/extensions` | 扩展管理 | 显示当前活动的扩展及版本 |
### 开发辅助命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `/init` | 项目初始化 | 分析项目并创建定制的配置文件 |
| `/setup-github` | GitHub配置 | 配置GitHub Actions工作流 |
| `/directory` | 目录管理 | 管理工作空间目录以获得项目上下文 |
| `/export` | 导出功能 | 以各种格式导出对话历史 |
| `/copy` | 复制功能 | 将最后的AI响应复制到剪贴板 |
### 监控调试命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `/stats` | 统计信息 | 监控会话使用情况和性能统计 |
| `/log` | 日志位置 | 显示当前会话日志存储位置 |
| `/bug` | 错误报告 | 提交带有系统信息的错误报告 |
| `/help` | 帮助信息 | 打开综合帮助对话框 |
| `/docs` | 文档访问 | 在浏览器中打开完整文档 |
### 特殊功能命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `/vim` | Vim模式 | 切换vim风格按键绑定 |
| `/corgi` | 特殊主题 | 切换柯基主题UI模式（彩蛋） |
| `/commands` | 命令市场 | 管理和安装自定义命令 |
| `/agents` | 代理管理 | 管理个人、项目和内置代理 |
### 常见使用场景
#### 系统配置
```bash
/about # 查看系统信息
/auth # 配置身份验证
/model # 切换AI模型
/theme # 更改主题
```
#### 会话管理
```bash
/chat save project-review # 保存对话检查点
/memory add "项目使用React" # 添加记忆信息
/compress # 压缩对话历史
/clear # 清空会话
```
#### 开发辅助
```bash
/init # 初始化项目配置
/ide # 连接IDE
/mcp list # 查看可用工具
/export clipboard # 导出对话到剪贴板
```
#### 调试支持
```bash
/stats # 查看使用统计
/log # 查看日志位置
/bug "描述问题" # 提交错误报告
/help # 获取帮助
```
## 命令特性
### 智能补全
| 特性 | 说明 | 示例 |
|------|------|------|
| Tab补全 | 自动补全命令和参数 | `/chat` + Tab |
| 参数提示 | 显示可用参数选项 | `/mcp auth` + Tab |
| 历史记录 | 记住常用命令 | 上下箭头浏览 |
### 视觉反馈
| 颜色 | 含义 | 用途 |
|------|------|------|
| 绿色 | 成功/活动 | 命令执行成功 |
| 红色 | 错误/失败 | 错误信息显示 |
| 黄色 | 警告/待处理 | 需要注意的信息 |
| 蓝色 | 信息/说明 | 一般信息显示 |
### 错误处理机制
- **参数验证**：自动验证命令参数的有效性
- **依赖检查**：检查必需的依赖项是否可用
- **网络处理**：网络错误时提供重试建议
- **帮助提示**：错误时自动显示使用帮助
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 命令不识别 | 拼写错误或命令不存在 | 检查拼写，使用 `/help` 查看可用命令 |
| 参数无效 | 参数格式错误 | 查看命令帮助信息，使用Tab补全 |
| 网络连接失败 | 网络问题或服务器不可用 | 检查网络连接，稍后重试 |
| 权限不足 | 缺少必要的系统权限 | 检查文件权限或系统设置 |
| 配置文件错误 | 配置文件格式不正确 | 重新配置或恢复默认设置 |
### 诊断步骤
1. **基础检查**
- 确认命令拼写正确
- 使用 `/help` 查看可用命令
- 检查参数格式
2. **网络连接**
- 验证网络连接正常
- 检查防火墙设置
- 确认服务器可访问
3. **配置验证**
- 使用 `/about` 查看系统状态
- 检查相关配置文件
- 重新运行配置命令
4. **错误排查**
- 查看详细错误信息
- 使用 `/log` 查看日志
- 使用 `/bug` 报告问题
### 平台兼容性
| 平台 | 支持程度 | 特殊注意事项 |
|------|----------|-------------|
| Windows | 完全支持 | 路径使用反斜杠 |
| macOS | 完全支持 | 可能需要系统权限授权 |
| Linux | 完全支持 | 依赖终端环境配置 |
## /docs_cn/features/suspending-resuming.md
---
sidebar_position: 21
hide_title: true
---
# 挂起和恢复
> **功能概述**：iFlow CLI 支持在交互式会话中挂起（暂停）当前任务，并在需要时恢复它。
>
> **学习时间**：5分钟
>
> **前置要求**：熟悉基本的命令行操作，如 `ctrl+z` 和 `fg`。
## 什么是挂起和恢复
在 iFlow CLI 的交互式会话中，您可能需要临时中断当前正在运行的任务，去执行另一个更高优先级的操作。挂起和恢复功能允许您使用标准的终端命令来暂停（挂起）当前的 iFlow 会话，然后在您准备好时再返回（恢复）到原来的地方继续。
这个功能利用了大多数现代 shell（如 bash, zsh）的作业控制（Job Control）能力。
## 核心操作
| 操作 | 命令 | 说明 |
|------|------|------|
| 挂起 | `ctrl+z` | 将当前正在前台运行的 iFlow 进程暂停，并放到后台。 |
| 恢复 | `fg` 或 `fg %<job_number>` | 将一个后台任务重新调回到前台继续运行。`fg` 默认恢复最近一个任务。使用 `fg %1`、`fg %2` 等可以恢复指定的任务。 |
您可以使用 `jobs` 命令查看所有在后台的任务及其编号。
## 工作流程
1. **启动交互式会话**: 运行 `iflow` 进入交互式模式。
2. **执行任务**: 在会话中与 iFlow 交互，例如，运行一个剧本或提出一个问题。
3. **需要中断**: 假设您需要检查另一个文件或运行一个快速的命令，但不想终止当前的 iFlow 会话。
4. **挂起会话**: 按下 `ctrl+z`。iFlow CLI 进程将被暂停，您会返回到您的 shell 提示符。
5. **执行其他任务**: 在 shell 中执行您需要的任何其他命令。
6. **恢复会话**: 当您准备好返回 iFlow 时，输入 `fg` 命令。
7. **继续交互**: 您将回到之前离开的 iFlow 会话中，可以从中断的地方继续。
## 使用场景
- **临时查看信息**: 在与 iFlow 对话时，需要快速查看一个文件的内容或核对一些信息。
- **执行系统命令**: 需要运行一个系统命令（如 `git status` 或 `ls -l`）来获取上下文，以便更好地向 iFlow 提问。
- **多任务处理**: 在一个终端窗口中管理多个任务，而无需为每个任务打开新的终端标签页。
## 示例
假设您正在使用 iFlow 编写代码：
1. **启动 iFlow**:
```bash
iflow
```
您进入了 iFlow 的交互式会话。
2. **开始一个任务**:
```
>>> "写一个 python hello world"
```
iFlow 开始生成代码。
3. **需要检查文件**:
您突然想起需要检查当前目录下是否已经有一个 `hello.py` 文件。
4. **挂起 iFlow**:
按下 `ctrl+z`。
```
zsh: suspended iflow
```
您回到了 zsh (或您的默认 shell) 提示符。
5. **检查文件**:
```bash
ls
```
您看到目录下没有 `hello.py`。
6. **恢复 iFlow**:
输入 `fg`。
```bash
fg
[1] + continued iflow
```
您回到了 iFlow 会话，可以看到 iFlow 恢复之前的历史记录，并正在等待您的下一步指示。
这个功能让 iFlow CLI 的使用更加灵活，能够无缝地融入您现有的命令行工作流中。
## /docs_cn/features/telemetry.md
---
sidebar_position: 20
hide_title: true
---
# 可观测性
> **功能概述**：可观测性是iFlow CLI的监控分析系统，提供性能监控、使用分析和调试支持。
>
> **学习时间**：10-15分钟
>
> **前置要求**：了解基本的JSON配置，熟悉系统监控概念
## 什么是可观测性
可观测性是iFlow CLI提供的监控分析系统，让您能够深入了解CLI的性能表现、运行状态和使用情况。通过启用可观测性功能，您可以获得追踪数据、性能指标和结构化日志，从而更好地监控操作、调试问题和优化使用体验。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 标准化协议 | 基于OpenTelemetry标准构建 | 兼容各种监控后端 |
| 多种数据类型 | 支持追踪、指标、日志三种数据 | 全面的可观测性 |
| 灵活配置 | 支持本地和云端多种输出方式 | 适应不同部署环境 |
| 隐私保护 | 可配置是否记录敏感信息 | 保护用户隐私 |
| 性能优化 | 异步处理，不影响CLI性能 | 无感知监控 |
## 工作原理
### 可观测性数据流
```
CLI操作 → 数据收集 → 数据处理 → 数据输出 → 监控分析
↓
[用户行为] → [追踪记录] → [指标聚合] → [本地/云端] → [性能洞察]
```
### 技术架构
- **数据收集**：基于OpenTelemetry SDK自动收集性能数据
- **数据处理**：结构化处理，支持过滤和聚合
- **数据输出**：支持本地文件、OTLP端点、云服务等多种输出
- **隐私保护**：可配置的数据脱敏和过滤机制
## 详细功能说明
### 配置管理
可观测性功能支持多种灵活的配置方式，主要通过配置文件和环境变量进行管理，CLI标志可以覆盖特定会话的设置。
#### 配置优先级
| 优先级 | 配置方式 | 说明 |
|--------|----------|------|
| 最高 | CLI标志 | 临时覆盖当前会话 |
| 高 | 环境变量 | 全局环境配置 |
| 中 | 项目配置 | `.iflow/settings.json` |
| 低 | 用户配置 | `~/.iflow/settings.json` |
| 最低 | 默认值 | 系统默认设置 |
#### CLI标志参数
| 参数 | 功能 | 示例 |
|------|------|------|
| `--telemetry` / `--no-telemetry` | 启用/禁用可观测性 | `iflow --telemetry` |
| `--telemetry-target <local\|gcp>` | 设置输出目标 | `iflow --telemetry-target local` |
| `--telemetry-otlp-endpoint <URL>` | 设置OTLP端点 | `iflow --telemetry-otlp-endpoint http://localhost:4317` |
| `--telemetry-outfile <path>` | 导出到文件 | `iflow --telemetry-outfile ./metrics.json` |
| `--telemetry-log-prompts` | 记录提示词 | `iflow --telemetry-log-prompts` |
#### 环境变量
| 变量名 | 作用 | 示例 |
|--------|------|------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 设置OTLP导出端点 | `http://localhost:4317` |
#### 默认设置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `telemetry.enabled` | `false` | 默认关闭可观测性 |
| `telemetry.target` | `local` | 本地输出 |
| `telemetry.otlpEndpoint` | `http://localhost:4317` | 本地OTLP端点 |
| `telemetry.logPrompts` | `true` | 记录提示词 |
### 配置示例
#### 本地开发环境
在 `.iflow/settings.json` 中启用本地可观测性：
```json
{
"telemetry": {
"enabled": true,
"target": "gcp"
},
"sandbox": false
}
```
### 导出到文件
您可以将所有可观测性数据导出到本地文件，方便进行详细分析和检查。
只需使用 `--telemetry-outfile` 标志并指定输出文件路径即可开启文件导出功能。注意这个功能需要配合 `--telemetry-target=local` 使用。
```bash
iflow --telemetry --telemetry-target=local --telemetry-outfile=/path/to/telemetry.log "your prompt"
```
## 运行 OTEL 收集器
OTEL 收集器是一个强大的服务，负责接收、处理和导出可观测性数据。
CLI 通过高效的 OTLP/gRPC 协议发送数据。
想了解更多 OTEL 导出器的标准配置？请查看 [官方文档][otel-config-docs] 获取详细信息。
[otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
### 本地部署
使用 `npm run telemetry -- --target=local` 命令可以轻松自动化设置本地可观测性管道，包括自动配置 `.iflow/settings.json` 文件中的必要设置。脚本会帮您安装 `otelcol-contrib`（OpenTelemetry 收集器）和 `jaeger`（用于可视化追踪的 Jaeger UI）。
**使用步骤：**
1. **运行命令**：
在仓库根目录执行以下命令：
```bash
npm run telemetry -- --target=local
```
脚本会自动为您完成以下工作：
- 按需下载 Jaeger 和 OTEL 组件
- 启动本地 Jaeger 实例
- 启动配置好的 OTEL 收集器来接收 iFlow CLI 数据
- 自动在您的工作区设置中启用可观测性
- 退出时自动禁用可观测性
2. **查看追踪**：
打开浏览器访问 **http://localhost:16686** 来使用 Jaeger UI。在这里您可以深入查看 iFlow CLI 操作的详细追踪信息。
3. **检查日志和指标**：
脚本会将 OTEL 收集器的输出（包括日志和指标）保存到 `~/.iflow/tmp/<projectHash>/otel/collector.log`。脚本会提供便捷的查看链接和本地命令来跟踪您的可观测性数据。
4. **停止服务**：
在运行脚本的终端中按 `Ctrl+C` 即可停止 OTEL 收集器和 Jaeger 服务。
## 日志和指标参考
以下部分详细介绍了 iFlow CLI 生成的日志和指标结构，帮助您更好地理解和分析数据。
- 所有日志和指标都包含 `sessionId` 作为通用标识属性。
### 日志
日志记录了特定事件的时间戳信息，iFlow CLI 会记录以下重要事件：
- `iflow_cli.config`：此事件在启动时发生一次，包含 CLI 的配置。
- **属性**：
- `model`（字符串）
- `embedding_model`（字符串）
- `sandbox_enabled`（布尔值）
- `core_tools_enabled`（字符串）
- `approval_mode`（字符串）
- `api_key_enabled`（布尔值）
- `vertex_ai_enabled`（布尔值）
- `code_assist_enabled`（布尔值）
- `log_prompts_enabled`（布尔值）
- `file_filtering_respect_git_ignore`（布尔值）
- `debug_mode`（布尔值）
- `mcp_servers`（字符串）
- `iflow_cli.user_prompt`：此事件在用户提交提示时发生。
- **属性**：
- `prompt_length`
- `prompt`（如果 `log_prompts_enabled` 配置为 `false`，则排除此属性）
- `auth_type`
- `iflow_cli.tool_call`：此事件为每个函数调用发生。
- **属性**：
- `function_name`
- `function_args`
- `duration_ms`
- `success`（布尔值）
- `decision`（字符串："accept"、"reject" 或 "modify"，如果适用）
- `error`（如果适用）
- `error_type`（如果适用）
- `iflow_cli.api_request`：此事件在向 iFlow API 发出请求时发生。
- **属性**：
- `model`
- `request_text`（如果适用）
- `iflow_cli.api_error`：此事件在 API 请求失败时发生。
- **属性**：
- `model`
- `error`
- `error_type`
- `status_code`
- `duration_ms`
- `auth_type`
- `iflow_cli.api_response`：此事件在收到来自 iFlow API 的响应时发生。
- **属性**：
- `model`
- `status_code`
- `duration_ms`
- `error`（可选）
- `input_token_count`
- `output_token_count`
- `cached_content_token_count`
- `thoughts_token_count`
- `tool_token_count`
- `response_text`（如果适用）
- `auth_type`
- `iflow_cli.flash_fallback`：此事件在 iFlow CLI 切换到 flash 作为回退时发生。
- **属性**：
- `auth_type`
- `iflow_cli.slash_command`：此事件在用户执行斜杠命令时发生。
- **属性**：
- `command`（字符串）
- `subcommand`（字符串，如果适用）
### 指标
指标提供了随时间变化的数值化行为测量，iFlow CLI 收集以下关键指标：
- `iflow_cli.session.count`（计数器，整数）：每次 CLI 启动时递增一次。
- `iflow_cli.tool.call.count`（计数器，整数）：计算工具调用次数。
- **属性**：
- `function_name`
- `success`（布尔值）
- `decision`（字符串："accept"、"reject" 或 "modify"，如果适用）
- `iflow_cli.tool.call.latency`（直方图，毫秒）：测量工具调用延迟。
- **属性**：
- `function_name`
- `decision`（字符串："accept"、"reject" 或 "modify"，如果适用）
- `iflow_cli.api.request.count`（计数器，整数）：计算所有 API 请求。
- **属性**：
- `model`
- `status_code`
- `error_type`（如果适用）
- `iflow_cli.api.request.latency`（直方图，毫秒）：测量 API 请求延迟。
- **属性**：
- `model`
- `iflow_cli.token.usage`（计数器，整数）：计算使用的令牌数量。
- **属性**：
- `model`
- `type`（字符串："input"、"output"、"thought"、"cache" 或 "tool"）
- `iflow_cli.file.operation.count`（计数器，整数）：计算文件操作次数。
- **属性**：
- `operation`（字符串："create"、"read"、"update"）：文件操作的类型。
- `lines`（整数，如果适用）：文件中的行数。
- `mimetype`（字符串，如果适用）：文件的 MIME 类型。
- `extension`（字符串，如果适用）：文件的扩展名。
### 云部署环境
对于云部署，请参考以下平台的可观测性集成指南：
#### Google Cloud Platform (GCP)
**配置示例**
```json
{
"telemetry": {
"enabled": true,
"target": "gcp",
"gcpProjectId": "your-project-id",
"gcpServiceAccount": "path/to/service-account.json"
}
}
```
**环境变量设置**
```bash
export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"
```
#### 其他云平台
**AWS集成**
- 支持通过OTLP协议向AWS X-Ray发送追踪数据
- 可配置CloudWatch指标收集
**Azure集成**
- 支持Application Insights集成
- 提供Azure Monitor兼容的数据格式
## 使用示例
### 基本配置启用
#### CLI启动时启用可观测性
```bash
# 启用可观测性并设置本地输出
iflow --telemetry --telemetry-target local
# 启用可观测性并设置OTLP端点
iflow --telemetry --telemetry-otlp-endpoint http://localhost:4317
# 启用可观测性并记录提示词内容
iflow --telemetry --telemetry-log-prompts
```
#### 项目级配置
在项目根目录创建 `.iflow/settings.json`：
```json
{
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "http://localhost:4317",
"logPrompts": true,
"outputFile": "./logs/telemetry.json"
}
}
```
#### 全局用户配置
在 `~/.iflow/settings.json` 中配置：
```json
{
"telemetry": {
"enabled": false,
"target": "local",
"defaultEndpoint": "http://localhost:4317"
}
}
```
### 高级使用场景
#### 性能监控
```bash
# 启用详细性能监控
iflow --telemetry --telemetry-target local --telemetry-outfile performance.log
# 执行任务并监控性能
"请分析这个大型项目"
# 查看性能数据
cat performance.log | jq '.metrics[] | select(.name == "iflow_cli.api.request.latency")'
```
#### 团队协作监控
```bash
# 团队共享OTLP收集器
iflow --telemetry --telemetry-otlp-endpoint http://team-collector:4317
# 设置团队标识
export OTEL_RESOURCE_ATTRIBUTES="team=frontend,project=webapp"
```
#### 调试模式数据收集
```bash
# 启用完整调试可观测性
iflow --telemetry --telemetry-log-prompts --telemetry-outfile debug.log
# 执行问题操作
"执行可能有问题的操作"
# 分析调试数据
grep "error" debug.log | jq .
```
## 故障排除
### 常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 可观测性数据不记录 | 可观测性功能未启用 | 使用 `--telemetry` 标志或配置文件启用 |
| OTLP连接失败 | 端点不可访问或配置错误 | 检查端点URL和网络连接 |
| 文件导出失败 | 磁盘空间不足或权限问题 | 检查磁盘空间和文件写入权限 |
| 数据不完整 | 过滤配置过于严格 | 检查数据过滤和脱敏设置 |
| 性能影响明显 | 可观测性数据量过大 | 调整采样率或减少记录详情 |
### 诊断步骤
#### 1. 基础配置检查
```bash
# 检查当前配置状态
/about
# 查看可观测性相关设置
cat .iflow/settings.json | jq '.telemetry'
# 验证CLI标志是否生效
iflow --help | grep telemetry
```
#### 2. 连接性测试
```bash
# 测试OTLP端点连接
curl -X POST http://localhost:4317/v1/traces -H "Content-Type: application/json" -d '{}'
# 检查本地收集器状态
ps aux | grep otelcol
# 验证网络端口开放
netstat -ln | grep 4317
```
#### 3. 数据验证
```bash
# 检查输出文件内容
tail -f /path/to/telemetry.log
# 验证数据格式
cat telemetry.log | jq '.traces[0]'
# 统计数据量
wc -l telemetry.log
```
#### 4. 性能分析
```bash
# 监控CLI性能
time iflow --telemetry "简单测试命令"
# 检查可观测性开销
iflow --telemetry --telemetry-outfile perf.log "测试" && ls -la perf.log
# 对比开关可观测性性能
time iflow "相同命令" # 无可观测性
time iflow --telemetry "相同命令" # 有可观测性
```
### 数据隐私保护
#### 敏感信息过滤
- **提示词保护**：使用 `--no-telemetry-log-prompts` 禁用提示词记录
- **参数过滤**：自动过滤包含密码、密钥的工具参数
- **路径脱敏**：用户路径信息进行哈希处理
- **内容清理**：自动识别和清理敏感内容
#### 数据存储安全
- **本地存储**：默认数据仅存储在本地文件系统
- **传输加密**：OTLP协议支持TLS加密传输
- **访问控制**：配置文件和日志文件权限控制
- **数据保留**：可配置数据自动清理策略
### 平台兼容性
| 平台 | 支持程度 | 特殊说明 |
|------|----------|----------|
| Windows | 完全支持 | 路径分隔符自动处理，支持PowerShell |
| macOS | 完全支持 | 支持系统级OpenTelemetry集成 |
| Linux | 完全支持 | 原生OpenTelemetry支持，完整容器兼容性 |
### 容器化部署注意事项
- **Docker环境**：需要正确配置网络和卷挂载
- **Kubernetes集成**：支持通过Service Mesh收集数据
- **权限管理**：容器内需要适当的文件系统权限
## /docs_cn/features/thinking.md
---
sidebar_position: 2
hide_title: true
---
# 思考能力
> **功能概述**：思考能力是iFlow CLI的智能推理系统，通过关键词触发让AI进行深度思考，提供更深层次的分析和推理。
>
> **学习时间**：10-15分钟
>
> **前置要求**：已安装并配置iFlow CLI，了解基本的命令行操作
## 什么是思考能力
思考能力是iFlow CLI内置的智能推理增强系统，它通过识别用户输入中的特定关键词来触发AI模型的深度思考模式。当激活时，AI会在给出最终答案前进行内部推理，展示其思考过程，从而提供更准确、更深层次的回答。
## 核心特点
| 特点 | 说明 | 优势 |
|------|------|------|
| 智能关键词识别 | 支持中英文思考触发词 | 自然语言交互 |
| 多层级推理强度 | 5个推理等级：无、普通、中级、高级、超级 | 精准控制思考深度 |
| 实时思考展示 | 显示AI的思考过程 | 增强透明度和可信度 |
| 多模型适配 | 支持OpenAI o1、DeepSeek、GLM-4.5等 | 广泛的模型兼容性 |
| 灵活显示模式 | 完整、紧凑、指示器三种显示模式 | 适应不同使用场景 |
## 工作原理
### 思考触发流程
```
用户输入 → 关键词分析 → 意图识别 → 配置生成 → 模型调用 → 思考展示
↓
[包含思考词] → [正则匹配] → [推理等级] → [token限制] → [深度推理] → [过程可视化]
```
### 推理等级体系
- **none**：无思考模式，直接响应（0 tokens）
- **normal**：基础思考，识别"想想"、"think"等基础词汇（2,000 tokens）
- **hard**：中级思考，识别"再想想"、"think harder"等词汇（4,000 tokens）
- **mega**：高级思考，识别"好好思考"、"think really hard"等词汇（10,000 tokens）
- **ultra**：超级思考，识别"超级思考"、"think super hard"等词汇（32,000 tokens）
## 详细功能说明
### 关键词触发系统
#### 中文触发词
**超级思考（Ultra）**：
- 超级思考、极限思考、深度思考
- 全力思考、超强思考
- 认真仔细思考
**强力思考（Mega）**：
- 强力思考、大力思考、用力思考
- 努力思考、好好思考、仔细思考
**中级思考（Hard）**：
- 再想想、多想想
- 想清楚、想明白、考虑清楚
**基础思考（Normal）**：
- 想想、思考、考虑
#### 英文触发词
**超级思考（Ultra）**：
- `ultrathink`
- `think really super hard`
- `think intensely`
**强力思考（Mega）**：
- `megathink`
- `think really hard`
- `think a lot`
**中级思考（Hard）**：
- `think about it`
- `think more`
- `think harder`
**基础思考（Normal）**：
- `think`
### 思考显示
思考过程会在思考状态指示器中呈现。
```
✻ 思考中...
```
### 模型适配系统
思考能力当前支持混合推理模型目前支持 **glm-4.5** 模型
## 使用示例
### 基础使用
```bash
#
> 深度思考下这个复杂的系统设计问题
```
### 英文使用
```bash
# 超级思考
> ultrathink this complex system design
```
## 最佳实践
### 故障排除
#### 思考未触发
- 检查输入是否包含正确的触发关键词
- 验证使用的模型是否支持思考能力
- 确认环境变量配置是否正确
## 与相关功能的比较
### 思考能力 vs. 普通对话
思考能力在回答前会进行内部推理，而普通对话直接生成回答。思考模式提供更深层次的分析，但消耗更多计算资源。
### 思考能力 vs. SubAgent
思考能力是单个模型的内部推理过程，而SubAgent是调用专门的代理来处理特定任务。思考能力专注于推理深度，SubAgent专注于任务专业性。
## 国际化支持
思考能力完全支持中英文界面显示：
- **中文界面**：显示"思考中"、"展开"、"折叠"等中文提示
- **英文界面**：显示"Thinking"、"expand"、"collapse"等英文提示
- **自动切换**：根据系统语言设置自动显示对应语言界面
通过设置 `LANGUAGE` 环境变量或使用 `/language` 命令可以切换界面语言。
## /docs_cn/glossary.md
---
title: 术语词汇表
description: iFlow CLI 核心概念和术语定义
sidebar_position: 99
---
# 术语词汇表
> **用途**：统一定义iFlow CLI相关的核心概念和术语
> **适用场景**：新用户学习、文档编写参考、术语查询
## 核心概念
### iFlow CLI 基础
| 术语 | 定义 | 示例 |
|------|------|------|
| **iFlow CLI** | 基于终端的AI助手工具，提供代码分析、任务执行等功能 | `iflow` |
| **心流AI** | iFlow CLI的开发团队和服务提供商 | iflow.cn |
| **API密钥** | 用于身份验证的密钥，连接心流AI服务 | 在设置页面生成 |
| **工作空间** | 当前执行iFlow CLI的目录环境 | `cd project/` |
| **MCP** | 模型上下文协议，用于扩展AI能力的服务器系统 | `/mcp`
| **Sub Agent** | 智能Agent系统,适用于执行不同专业的任务 | `/agents`
| **Sub Command** | 命令行扩展 | `/commands`
### 命令系统
| 术语 | 定义 | 示例 |
|------|------|------|
| **斜杠命令** | 以 `/` 开头的iFlow CLI内置控制命令 | `/init`, `/help`, `/clear` |
| **Shell命令** | 以 `!` 开头，在CLI中执行的系统命令 | `!ls`, `!npm install` |
| **@文件引用命令** | 文件引用 @文件路径| `@src/App.tsx`|
| **$subagent执行命令** | 以`$`开头执行某个subagent | 如`$code-reviewer` |
| **自然语言指令** | 直接用中文与AI对话的指令 | `> 分析这个项目结构` |
### 执行模式
| 术语 | 定义 | 示例 |
|------|------|------|
| **yolo** | 默认允许CLI执行所有操作的执行模式 | 使用shift + enter切换模式|
| **plan mode** | CLI会先规划任务，需要手动确认任务后再执行 | 使用shift + enter切换模式|
| **default mode** | 所有操作都需要用户确认的模式 | 使用shift + enter切换模式|
| **accepting edits** | 模型自动执行创建和修改文件的模型，其余操作仍需用户确认 | 使用shift + enter切换模式|
### 交互模式
| 术语 | 定义 | 示例 |
|------|------|------|
| **多行输入** | 使用 `\` 或 `Shift+Enter` 创建的多行文本输入 | `line1 \` `line2` |
| **图片粘贴** | 通过 `Ctrl/Cmd+V` 粘贴图片到CLI中 | `[Pasted image #1]` |
| **文件引用** | 使用 `@` 符号引用文件或目录 | `@src/app.js` |
| **占位符** | 系统为大量内容生成的简化显示标识 | `[Pasted text #1 +45 lines]` |
## 扩展系统
### MCP 相关
| 术语 | 定义 | 示例 |
|------|------|------|
| **MCP** | 模型上下文协议，AI和外部工具间的通信标准 | Model Context Protocol |
| **MCP服务器** | 实现MCP协议的外部工具或服务 | playwright-mcp, file-system-mcp |
| **stdio服务器** | 通过标准输入输出通信的MCP服务器 | 本地Python脚本 |
| **SSE服务器** | 基于Server-Sent Events的MCP服务器 | Web API服务 |
### 代理系统
| 术语 | 定义 | 示例 |
|------|------|------|
| **子代理** | 专门处理特定领域任务的AI助手 | 代码审查代理、文档生成代理 |
| **代理配置** | 定义子代理行为和能力的配置文件 | `.iflow/agents/config.json` |
| **任务分发** | 将复杂任务分配给不同专业代理的机制 | 自动选择合适的代理 |
## 功能特性
### 内存和状态
| 术语 | 定义 | 示例 |
|------|------|------|
| **上下文** | AI助手理解当前对话的背景信息 | 项目结构、历史对话 |
| **内容导入** | 从外部文件导入信息到AI上下文中 | `@README.md` |
| **检查点** | 保存当前会话状态的功能点 | 保存重要对话节点 |
| **会话历史** | 当前对话的完整记录 | 可通过 `/clear` 清除 |
### 高级功能
| 术语 | 定义 | 示例 |
|------|------|------|
| **可观测性** | 系统运行数据的收集和分析功能 | 使用统计、性能监控 |
| **多模态** | 同时处理文本、图片等多种数据类型的能力 | 图片理解、文档分析 |
| **工作流** | 自动化的任务执行序列 | 代码生成→测试→部署 |
## 配置和管理
### 配置文件
| 术语 | 定义 | 位置 |
|------|------|------|
| **全局配置** | 影响所有项目的iFlow CLI设置 | `~/.iflow/settings.json` |
| **项目配置** | 特定项目的iFlow CLI设置 | `{project}/.iflow/config.json` |
| **IFLOW.md** | 项目特定的AI上下文文档 | 项目根目录 |
### 认证方式
| 术语 | 定义 | 特点 |
|------|------|------|
| **iFlow原生认证** | 使用心流AI官方API的认证方式 | 完整功能，推荐使用 |
| **OpenAI兼容API** | 使用OpenAI协议的第三方API | 功能受限，备选方案 |
## 平台和兼容性
### 操作系统
| 术语 | 定义 | 支持状态 |
|------|------|----------|
| **macOS** | 苹果操作系统 | ✅ 完全支持 |
| **Linux** | Linux发行版 | ✅ 完全支持 |
| **Windows** | 微软操作系统 | ✅ 支持 |
| **WSL** | Windows Subsystem for Linux | ✅ 推荐Windows用户使用 |
### 开发环境
| 术语 | 定义 | 要求 |
|------|------|------|
| **Node.js** | JavaScript运行时环境 | 版本22+ |
| **npm** | Node.js包管理器 | 随Node.js安装 |
| **Shell** | 命令行界面环境 | Bash/Zsh/Fish推荐 |
## 使用场景分类
### 按用户类型
| 用户类型 | 定义 | 典型需求 |
|----------|------|----------|
| **初学者** | 首次使用iFlow CLI的用户 | 快速上手、基础操作 |
| **进阶用户** | 有一定使用经验的用户 | 功能扩展、效率提升 |
| **专家用户** | 深度使用和定制的用户 | 团队协作、最佳实践 |
### 按工作场景
| 场景类型 | 定义 | 主要功能 |
|----------|------|----------|
| **Web开发** | 前端/后端开发工作 | 代码生成、调试、重构 |
| **数据分析** | 数据处理和分析工作 | 文件处理、脚本自动化 |
| **DevOps** | 运维和部署工作 | 脚本执行、工具集成 |
| **学习研究** | 学习和研究活动 | 文档分析、知识整理 |
## 常见错误术语
### 容易混淆的概念
| 错误用法 | 正确用法 | 说明 |
|----------|----------|------|
| Claude CLI | iFlow CLI | 正确的产品名称 |
| 心流CLI | iFlow CLI | 使用英文名称更准确 |
| MCP插件 | MCP服务器 | MCP中称为服务器而非插件 |
| 代理人 | 子代理 | 在iFlow CLI中称为子代理 |
| 命令行工具 | 终端AI助手 | 更准确的功能描述 |
## 版本和更新
### 版本术语
| 术语 | 定义 | 示例 |
|------|------|------|
| **稳定版** | 经过充分测试的正式版本 | v1.0.0 |
| **测试版** | 功能完整但需要进一步测试的版本 | v1.1.0-beta |
| **开发版** | 包含最新功能的开发版本 | v1.1.0-alpha |
## 获得帮助
当您在文档中遇到不熟悉的术语时：
1. **首先查阅**：本词汇表
2. **搜索文档**：使用浏览器搜索功能
3. **查看示例**：找到相关的使用示例
4. **寻求帮助**：在GitHub Issues中提问
---
**维护说明**：本词汇表会随着iFlow CLI功能更新而持续维护。如发现术语定义不准确或缺失，请 [提交反馈](https://github.com/iflow-ai/iflow-cli/issues)。
## /docs_cn/quickstart.md
---
sidebar_position: 0
hide_title: true
title: '快速开始'
---
import Controlled from '@/components/Controlled';
<Controlled type="ApiKeyFailureMechanism" hideMsg>
:::info 🔔 重要通知
2025-10-10起，iFlow CLI将统一切换至新的认证方式，届时您需要手动更新API Key。建议使用 /auth 通过iFlow登录，避免服务中断。
:::
</Controlled>
# 快速开始
iFlow CLI 是一款终端AI助手，可以分析代码、执行编程任务、处理文件操作。本指南帮您快速上手核心功能。
> **目标**：5分钟内完成 iFlow CLI 的安装、配置并运行第一个AI辅助任务
> **前置条件**：基本的终端操作经验
> **您将学到**：安装iFlow CLI、设置API密钥、执行基础命令
## 核心概念（30秒了解）
| 术语 | 说明 |
|------|------|
| **iFlow CLI** | 基于终端的AI助手工具 |
| **斜杠命令** | 以 `/` 开头的控制命令（如 `/init`、`/help`） |
| **@** | 文件引用 @文件路径(如`@src/App.tsx`) |
| **$** | 以`$`开头执行某个subagent(如`$code-reviewer`) |
| **Shell命令** | 以 `!` 开头，可在CLI中执行系统命令 |
| **yolo** | 默认允许CLI执行所有操作的执行模式 |
| **MCP** | 模型上下文协议，用于扩展AI能力的服务器系统 |
| **Sub Agent** | 智能Agent系统,适用于执行不同专业的任务 |
| **Sub Command** | 命令行扩展 |
| **context left** | CLI右下角的提示信息，代表模型在对话过程中剩余的上下文长度 |
> 💡 **更多术语**：查看完整的 [术语词汇表](./glossary) 了解所有概念定义
## 第1步：安装（2分钟）
### 系统要求
- Node.js 22+
- 4GB+ 内存
- 互联网连接
### 快速安装
**macOS/Linux**
```shell
# 一键安装脚本，会安装全部所需依赖
bash -c "$(curl -fsSL https://gitee.com/iflow-ai/iflow-cli/raw/main/install.sh)"
# 已有Node.js 22+
npm i -g @iflow-ai/iflow-cli@latest
```
**Windows**
```shell
1. 访问 https://nodejs.org/zh-cn/download 下载最新的 Node.js 安装程序
2. 运行安装程序来安装 Node.js
3. 重启终端：CMD(Windows + r 输入cmd) 或 PowerShell
4. 运行 `npm install -g @iflow-ai/iflow-cli@latest` 来安装 iFlow CLI
5. 运行 `iflow` 来启动 iFlow CLI
```
> **验证安装**：运行 `iflow --version` 确认安装成功
## 第2步：首次设置（1分钟）
### 启动iFlow
```shell
iflow
```
### 选择登录方式
iFlow CLI 支持三种登录方式，不同方式提供的功能有所差异：
#### 🌟 方式一：Login with iFlow 登录（推荐）
**强烈推荐使用 Login with iFlow 方式登录心流平台**，享受最完整的功能体验：
✅ **完整功能支持**
- **WebSearch 服务**：智能网络搜索，获取最新信息
- **WebFetch 服务**：网页内容抓取和分析
- **多模态能力**：内置图像理解等多模态功能
- **工具调用优化**：心流平台提供的模型经过专门优化，工具调用更加精准高效
✅ **最佳使用体验**
- **自动续期**：令牌自动刷新，永不过期
- **无缝连接**：一次授权，持续使用
** Login with iFlow 登录步骤：**
1. 运行 `iflow` 后选择 OLogin with iFlow 登录
2. CLI 会自动打开浏览器跳转到心流平台
3. 完成注册/登录后授权 iFlow CLI
4. 自动返回终端，开始使用
#### 方式二：心流 API Key 登录
> 💡 **适用场景**：服务器环境或无浏览器访问的场景
✅ **功能支持**：与 第一种 登录相同，享受心流平台的完整功能（WebSearch、WebFetch、多模态、工具调用优化等）
⚠️ **注意事项**：API Key 有效期为 7 天，需定期更新
**API Key 登录步骤：**
1. 访问[心流官网](https://iflow.cn/?spm=54878a4d.2ef5001f.0.0.7c1257832yovzX&open=setting)完成注册
2. 在用户设置页面生成 API KEY
3. 在 iFlow CLI 中选择 API Key 登录并输入密钥
#### 方式三：OpenAI Compatible API
> 💡 **适用场景**：使用自有模型服务或其他兼容 OpenAI 协议的服务
⚠️ **功能限制**：
- 不支持 WebSearch 服务
- 不支持 WebFetch 服务
- 不支持心流平台的内置多模态能力
- 无法享受心流平台模型的工具调用优化
**配置步骤：**
1. 选择 "OpenAI Compatible API" 选项
2. 输入服务端点 URL
3. 输入对应的 API Key
### 选择模型
登录成功后，选择一个心仪的大模型就可以开始使用了
## 第3步：运行第一个任务（2分钟）
### 方式A：项目分析
```shell
# 在任意代码项目目录下
cd your-project/
iflow
> /init
> 分析这个项目的结构和主要功能
```
### 方式B：简单任务
```shell
iflow
> 创建一个Python脚本，计算斐波那契数列的前10项
```
### 方式C：Shell命令辅助
```shell
iflow
> !ls -la
> 帮我分析这个目录结构，建议如何整理文件
```
## 自动更新
iFlow CLI在启动时会检测是否有最新版本，会自动更新
### 自动更新失败
此时需要手动更新
```shell
# 更新命令
npm i -g @iflow-ai/iflow-cli to update
# 查看最新版本
iflow -v
```
### 卸载重新安装
手动更新也失败，需要执行卸载并重新安装
```shell
# 卸载
npm uninstall -g @iflow-ai/iflow-cli
# 检查iflow命令是否存在
iflow -v
# 重新安装
npm i -g @iflow-ai/iflow-cli
```
## 常用命令速查
| 命令 | 功能 | 示例 |
|------|------|------|
| `/help` | 查看帮助 | `/help` |
| `/init` | 分析项目结构 | `/init` |
| `/clear` | 清空对话历史 | `/clear` |
| `/exit` | 退出CLI | `/exit` |
| `!命令` | 执行系统命令 | `!npm install` |
## 故障排除
### 安装问题
```shell
# 检查Node.js版本
node --version # 需要 22+
# 检查网络连接
curl -I https://apis.iflow.cn/v1
```
### 认证问题
- 确保API密钥正确复制（无多余空格）
- 检查网络连接是否正常
- 重新生成API密钥并重试
### 命令不响应
- 使用 `Ctrl+C` 中断当前操作
- 运行 `/clear` 清空上下文
- 重启CLI：`/exit` 后重新运行 `iflow`
## 下一步学习
完成快速开始后，推荐按以下顺序深入学习：
1. **[基础用法](./examples/basic-usage)** - 掌握日常使用技巧（10分钟）
2. **[交互模式](./features/interactive)** - 学习高效交互方式（15分钟）
3. **[MCP扩展](./examples/mcp)** - 扩展AI能力（15分钟）
4. **[最佳实践](./examples/best-practices)** - 提升工作效率（20分钟）
> **获得帮助**：遇到问题？查看 [完整文档](./examples/index.md) 或 [提交反馈](https://github.com/iflow-ai/iflow-cli/issues)
## /docs_cn/scenarios.md
---
title: 场景案例
description: 按工作场景和具体需求快速找到解决方案
sidebar_position: 10
---
# 场景案例
> **目标**：按实际工作场景快速找到最佳解决方案
> **适用场景**：有具体任务需求，想快速上手的用户
> **使用方式**：根据工作场景选择对应章节
## 如何使用本文档
### 快速开始（5分钟）
如果你是新用户或需要快速上手，推荐阅读顺序：
1. **确定你的角色** → 查看 [按工作角色分类](#按工作角色分类)
2. **了解基本操作** → 阅读对应角色的"快速上手流程"
3. **配置必要工具** → 参考"推荐配置"部分
4. **开始实践** → 跟随"学习路径"逐步深入
### 根据需求选择阅读路径
| 你的情况 | 推荐阅读路径 | 预计时间 |
|---------|-------------|----------|
| **新用户，想快速上手** | [角色分类](#按工作角色分类) → [学习路径](#学习路径) | 15分钟 |
| **有具体任务要完成** | [任务类型分类](#按任务类型分类) → [解决方案](#解决方案) | 10分钟 |
| **项目不同阶段的需求** | [项目阶段分类](#按项目阶段分类) → [推荐配置](#推荐配置) | 8分钟 |
| **遇到问题需要帮助** | [常见问题快速解决](#常见问题快速解决) | 5分钟 |
| **寻找最佳实践案例** | [成功案例分享](#成功案例分享) | 10分钟 |
## 文档目录
### [按工作角色分类](#按工作角色分类)
- [前端开发者](#前端开发者) - 组件开发、UI调试、响应式设计
- [后端开发者](#后端开发者) - API设计、数据库操作、系统集成
- [数据分析师](#数据分析师) - 数据清洗、统计分析、可视化
- [DevOps工程师](#devops工程师) - 自动化部署、监控告警
### [按任务类型分类](#按任务类型分类)
- [代码分析与重构](#代码分析与重构) - 理解代码结构、发现问题
- [功能开发](#功能开发) - 从需求到完整功能实现
- [问题调试](#问题调试) - 快速定位并修复bug
- [学习新技术](#学习新技术) - 学习编程语言、框架或工具
### [按项目阶段分类](#按项目阶段分类)
- [项目启动阶段](#项目启动阶段) - 技术选型、架构设计
- [开发阶段](#开发阶段) - 功能实现、代码审查
- [测试阶段](#测试阶段) - 功能测试、性能测试
- [部署阶段](#部署阶段) - 环境配置、部署自动化
### [常见问题快速解决](#常见问题快速解决)
- [不知道从哪里开始](#我不知道从哪里开始)
- [功能不够用，需要更多工具](#功能不够用需要更多工具)
- [效率不高，想要更好的工作流](#效率不高想要更好的工作流)
### [成功案例分享](#成功案例分享)
- [Web开发团队效率提升](#案例1web开发团队效率提升)
- [数据分析工作流优化](#案例2数据分析工作流优化)
- [DevOps自动化升级](#案例3devops自动化升级)
## 按工作角色分类
### 前端开发者
> **适用场景**：组件开发、UI调试、响应式设计、性能优化
> **技术栈**：React、Vue、Angular、CSS、HTML、JavaScript/TypeScript
> **预计学习时间**：75分钟
#### 快速上手流程
```bash
# 1. 项目初始化
cd my-react-project
iflow
> /init
# 2. 安装前端相关MCP工具
!iflow mcp add-json 'playwright' '{"command":"npx","args":["-y","@iflow-mcp/playwright-mcp"]}'
# 3. 常用任务示例
> 创建一个响应式的用户卡片组件，支持深色模式
> 帮我优化这个React组件的渲染性能
> 分析当前页面的accessibility问题
```
#### 推荐配置
- **核心功能**：[交互模式图片处理](./features/interactive#图片交互功能)
- **必装工具**：Playwright MCP（UI测试）、Image Tools MCP（图片处理）
- **工作流程**：截图分析 → 代码生成 → 自动测试
#### 学习路径
1. [快速开始](./quickstart) → [基础用法](./examples/basic-usage) (20分钟)
2. [交互模式](./features/interactive) → [MCP扩展](./examples/mcp) (30分钟)
3. [最佳实践](./examples/best-practices) (20分钟)
---
### 后端开发者
> **适用场景**：API设计、数据库操作、性能优化、系统集成
> **技术栈**：Node.js、Python、Java、Go、数据库、微服务架构
> **预计学习时间**：75分钟
#### 快速上手流程
```bash
# 1. API项目分析
cd my-api-project
iflow
> /init
> 分析这个API项目的架构，生成接口文档
# 2. 数据库相关操作
> 根据业务需求设计用户表结构
> 优化这个SQL查询的性能
> 生成数据库迁移脚本
```
#### 推荐配置
- **核心功能**：[Shell命令集成](./examples/basic-usage#shell-命令执行)
- **必装工具**：Database MCP、Git Helper MCP、System Monitor MCP
- **工作流程**：代码分析 → 架构设计 → 测试验证
#### 学习路径
1. [快速开始](./quickstart) → [基础用法](./examples/basic-usage) (20分钟)
2. [MCP扩展](./examples/mcp) → [子代理配置](./examples/subagent) (40分钟)
3. [高级配置](./configuration/settings) (15分钟)
---
### 数据分析师
> **适用场景**：数据清洗、统计分析、可视化、报告生成
> **技术栈**：Python、R、SQL、Jupyter、Excel、Tableau、Power BI
> **预计学习时间**：60分钟
#### 快速上手流程
```bash
# 1. 数据文件分析
iflow
> @data/sales_2024.csv 分析这个销售数据，找出主要趋势
> 生成月度销售报告的Python脚本
> 创建交互式数据可视化图表
```
#### 推荐配置
- **核心功能**：[文件引用处理](./features/interactive#文件引用功能)
- **必装工具**：Excel Processor MCP、PDF Tools MCP、Image Tools MCP
- **工作流程**：数据导入 → 分析处理 → 可视化 → 报告生成
#### 学习路径
1. [快速开始](./quickstart) → [交互模式](./features/interactive) (25分钟)
2. [MCP扩展](./examples/mcp) (20分钟)
3. [最佳实践](./examples/best-practices) (15分钟)
---
### DevOps工程师
> **适用场景**：自动化部署、监控告警、基础设施管理
> **技术栈**：Docker、Kubernetes、CI/CD、监控工具、云平台
> **预计学习时间**：70分钟
#### 快速上手流程
```bash
# 1. 部署脚本优化
iflow
> 分析现有的Docker配置，提出优化建议
> 创建CI/CD流水线配置
> 设计监控告警策略
```
#### 推荐配置
- **核心功能**：[Shell命令执行](./examples/basic-usage#shell-命令执行)
- **必装工具**：System Monitor MCP、Network Tools MCP、Git Helper MCP
- **工作流程**：环境分析 → 脚本生成 → 自动化部署 → 监控配置
#### 学习路径
1. [快速开始](./quickstart) → [基础用法](./examples/basic-usage) (20分钟)
2. [MCP扩展](./examples/mcp) → [可观测性功能](./features/telemetry) (30分钟)
3. [最佳实践](./examples/best-practices) (20分钟)
## 按任务类型分类
### 代码分析与重构
#### 场景描述
需要理解现有代码结构、发现问题、进行重构优化
#### 解决方案
```bash
# 项目全面分析
iflow
> /init
> 分析这个项目的技术债务和潜在问题
> 建议重构策略和优先级
# 特定代码分析
> @src/components/UserProfile.tsx 这个组件有什么可以优化的地方？
> 检查整个项目的安全漏洞
```
#### 相关文档
- [项目初始化](./examples/basic-usage#初始化命令)
- [文件引用](./features/interactive#文件引用功能)
- [最佳实践](./examples/best-practices)
---
### 功能开发
#### 场景描述
从需求出发，完整实现一个新功能
#### 解决方案
```bash
# 需求分析
iflow
> 我需要实现一个用户认证系统，包括注册、登录、密码重置功能
# 分步实现
> 设计数据库表结构
> 生成后端API接口
> 创建前端组件
> 编写测试用例
```
#### 相关文档
- [MCP扩展](./examples/mcp) - 连接数据库和测试工具
- [子代理配置](./examples/subagent) - 专业化开发助手
- [检查点功能](./features/checkpointing) - 保存开发进度
---
### 问题调试
#### 场景描述
代码出现bug，需要快速定位并修复问题
#### 解决方案
```bash
# 错误信息分析
iflow
> !npm test # 运行测试看错误
> 这个错误信息表示什么，如何修复？
# 日志分析
> @logs/error.log 分析这个错误日志，找出问题根因
> 提供解决方案和预防措施
```
#### 相关文档
- [Shell命令执行](./examples/basic-usage#shell-命令执行)
- [最佳实践](./examples/best-practices#错误处理最佳实践)
---
### 学习新技术
#### 场景描述
学习新的编程语言、框架或工具
#### 解决方案
```bash
# 技术学习
iflow
> 我想学习React Hook，请给我一个完整的学习计划
> 解释什么是Docker，并给出实践示例
> 比较Vue和React的优缺点
```
#### 相关文档
- [交互模式](./features/interactive) - 多种学习方式
- [MCP扩展](./examples/mcp) - 连接学习资源
- [子代理配置](./examples/subagent) - 专业导师助手
## 按项目阶段分类
### 项目启动阶段
**主要任务**：技术选型、架构设计、环境搭建
```bash
# 技术选型分析
iflow
> 我要开发一个电商网站，帮我分析技术栈选择
> 比较不同前端框架的优缺点
> 设计整体系统架构
# 项目脚手架
> 创建React + TypeScript + Vite的项目模板
> 配置ESLint和Prettier
> 设置CI/CD流水线
```
**推荐配置**：基础功能 + MCP扩展
---
### 开发阶段
**主要任务**：功能实现、代码审查、问题修复
```bash
# 功能开发
iflow
> 实现用户登录功能
> 创建商品列表组件
> 集成支付接口
# 代码优化
> 审查这个函数的性能
> 重构重复代码
> 添加单元测试
```
**推荐配置**：完整功能 + 专业化代理
---
### 测试阶段
**主要任务**：功能测试、性能测试、安全测试
```bash
# 测试自动化
iflow
> 生成API接口测试用例
> 创建E2E测试脚本
> 分析性能瓶颈
# 安全检查
> 检查代码中的安全漏洞
> 验证用户输入处理
> 分析依赖包安全性
```
**推荐配置**：MCP测试工具 + 安全代理
---
### 部署阶段
**主要任务**：环境配置、部署自动化、监控告警
```bash
# 部署配置
iflow
> 生成Docker配置文件
> 创建Kubernetes部署脚本
> 配置监控告警规则
# 运维脚本
> 创建数据库备份脚本
> 设置日志轮转配置
> 编写健康检查接口
```
**推荐配置**：DevOps工具 + 系统监控
## 常见问题快速解决
### "我不知道从哪里开始"
> **问题症状**：安装了iFlow CLI，但不知道怎么用，从哪里开始学习
> **解决时间**：10分钟
**立即行动**：
1. **快速体验**：运行 `iflow` 然后输入 `> 你好，帮我分析一下当前目录`
2. **确定角色**：在上面的 [按工作角色分类](#按工作角色分类) 中找到你的角色
3. **跟随指引**：按照对应角色的"快速上手流程"开始实践
**进一步学习**：[5分钟快速开始](./quickstart) → [基础用法](./examples/basic-usage)
### "功能不够用，需要更多工具"
> **问题症状**：基础功能无法满足工作需求，需要连接数据库、处理文件等
> **解决时间**：15分钟
**立即行动**：
1. **了解MCP系统**：阅读 [MCP扩展系统](./examples/mcp) 了解可用工具
2. **安装必要工具**：根据你的角色安装推荐的MCP工具
3. **配置专业助手**：设置 [专业化子代理](./examples/subagent) 提升专业能力
**常用工具推荐**：
- 前端：Playwright MCP（UI测试）、Image Tools MCP（图片处理）
- 后端：Database MCP、Git Helper MCP、System Monitor MCP
- 数据：Excel Processor MCP、PDF Tools MCP
- 运维：System Monitor MCP、Network Tools MCP
### "效率不高，想要更好的工作流"
> **问题症状**：能用但效率不高，重复操作多，没有标准化流程
> **解决时间**：20分钟
**立即行动**：
1. **学习最佳实践**：阅读 [最佳实践指南](./examples/best-practices)
2. **优化配置**：参考 [高级设置](./configuration/settings) 调整性能
3. **建立规范**：为团队制定iFlow CLI使用规范
**效率提升技巧**：
- 使用 `/init` 为项目建立上下文，减少重复说明
- 配置常用的MCP工具，避免重复安装
- 建立代码模板和常用命令的快捷方式
### "遇到错误或技术问题"
> **问题症状**：命令执行失败、连接异常、功能不工作
> **解决时间**：5-10分钟
**立即行动**：
1. **检查基础环境**：确认网络连接、API密钥是否正确
2. **查看错误信息**：将完整错误信息复制给iFlow CLI分析
3. **重启尝试**：使用 `/clear` 清空上下文后重试
**获取帮助**：
- [术语词汇表](./glossary) - 查询专业术语
- [GitHub Issues](https://github.com/iflow-ai/iflow-cli/issues) - 报告问题
- [社区讨论](https://github.com/iflow-ai/iflow-cli/discussions) - 经验分享
**常见问题自检**：
- API密钥是否正确设置？
- 网络是否能正常访问？
- 是否使用了最新版本？
## 成功案例分享
### 案例1：Web开发团队效率提升
**背景**：5人React开发团队，代码审查耗时长，重复工作多
**解决方案**：
- 统一配置iFlow CLI + Code Review代理
- 建立代码模板和最佳实践文档
- 自动化测试和部署流程
**效果**：代码审查时间减少60%，bug率降低40%
### 案例2：数据分析工作流优化
**背景**：数据分析师需要处理多种格式数据，生成报告繁琐
**解决方案**：
- 配置Excel/PDF处理MCP工具
- 创建报告生成模板
- 建立数据处理标准流程
**效果**：报告生成时间减少70%，分析准确性提升
### 案例3：DevOps自动化升级
**背景**：运维团队手工操作多，部署容易出错
**解决方案**：
- 部署System Monitor和Network Tools
- 创建标准化部署脚本
- 建立监控告警体系
**效果**：部署成功率提升到99%，故障响应时间减少50%
---
## 下一步学习建议
### 按照你的当前状态选择
**刚开始使用**：
1. 完成 [快速开始](./quickstart) 基础设置
2. 选择你的角色，跟随对应的"快速上手流程"
3. 尝试一个简单的实际项目
**想要提升效率**：
1. 学习 [最佳实践](./examples/best-practices)
2. 配置 [MCP扩展系统](./examples/mcp)
3. 设置 [专业化子代理](./examples/subagent)
**团队使用**：
1. 制定团队使用规范
2. 建立共享的配置和模板
3. 分享成功经验和最佳实践
**深度使用**：
1. 探索 [高级配置](./configuration/settings)
2. 参与 [社区讨论](https://github.com/iflow-ai/iflow-cli/discussions)
3. 贡献你的使用经验和改进建议
### 更多资源
- **完整文档**：[文档索引](./examples/index.md) - 查看所有功能详细说明
- **最佳实践**：[实践指南](./examples/best-practices) - 学习高效使用技巧
- **配置指南**：[设置说明](./configuration/settings) - 个性化定制
- **问题帮助**：[术语词汇表](./glossary) - 查询专业术语
- **社区交流**：[GitHub Discussions](https://github.com/iflow-ai/iflow-cli/discussions) - 经验分享
- **问题反馈**：[GitHub Issues](https://github.com/iflow-ai/iflow-cli/issues) - 报告问题
---
> **提示**：本文档会持续更新，建议收藏以便随时查阅。如果你有好的使用场景或建议，欢迎通过GitHub分享给社区！
## /docs_cn/sdk/sdk-android.md
---
title: Android SDK
description: 基于iFlow CLI SDK搭建你的专属Agent项目
sidebar_position: 8
---
# SDK
## 概述
iFlow Android SDK 是一个用于与 iFlow CLI 进行编程交互的 Android SDK。它通过代理通信协议（ACP）允许开发者构建具有对话、工具执行和任务规划能力的 AI 驱动应用程序。
目前提供 **Android SDK**，支持简单查询和完整的双向客户端进行复杂交互。
## 系统要求
- **Android API**: 21+ (Android 5.0 Lollipop 或更高版本)
- **Kotlin**: 1.8 或更高版本
- **iFlow CLI**: 需通过 WebSocket 访问
## 依赖
添加到你的 `build.gradle`：
```kotlin
dependencies {
// OkHttp 用于 WebSocket
implementation 'com.squareup.okhttp3:okhttp:4.12.0'
// Gson 用于 JSON
implementation 'com.google.code.gson:gson:2.10.1'
// 协程
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
}
```
## 快速开始
### 基础示例
使用 `IFlowClient` 进行基本的对话交互：
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
val options = IFlowOptions()
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("你好,iFlow!")
client.receiveMessages { message ->
when (message) {
is AssistantMessage -> {
println(message.chunk.text)
}
is TaskFinishMessage -> {
return@receiveMessages // 完成
}
}
}
}
```
### 简单查询
最简单的使用方式是通过 `IFlowQuery.query` 函数：
```kotlin
import com.iflow.sdk.query.IFlowQuery
// 简单一键查询
val result = IFlowQuery.query("What is 2 + 2?")
println(result) // "2 + 2 equals 4."
```
## 核心概念
### IFlowClient
`IFlowClient` 是与 iFlow CLI 交互的主要接口，管理 WebSocket 连接的生命周期：
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
// 使用默认配置
val options = IFlowOptions()
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("你的问题")
client.receiveMessages { message ->
// 处理消息
}
}
// 使用自定义配置
val options = IFlowOptions(
url = "ws://localhost:8090/acp?peer=iflow",
timeout = 300_000L, // 5 分钟
permissionMode = PermissionMode.AUTO
)
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("你的问题")
client.receiveMessages { message ->
// 处理消息
}
}
```
### 消息类型
SDK 支持多种消息类型，对应 iFlow 协议的不同响应：
#### AssistantMessage - AI 助手响应
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
fun handleAssistantMessage() {
val options = IFlowOptions()
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("请介绍一下 Kotlin")
client.receiveMessages { message ->
when (message) {
is AssistantMessage -> {
println(message.chunk.text)
}
is TaskFinishMessage -> {
return@receiveMessages
}
}
}
}
}
```
#### ToolCallMessage - 工具调用
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
fun handleToolCalls() {
val options = IFlowOptions(
permissionMode = PermissionMode.MANUAL
)
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("列出当前目录的文件")
client.receiveMessages { message ->
when (message) {
is ToolCallMessage -> {
println("工具调用: ${message.label}")
println("状态: ${message.status}")
// 处理工具确认
if (message.confirmation?.required == true) {
client.approveToolCall(message.id)
}
}
is TaskFinishMessage -> {
return@receiveMessages
}
}
}
}
}
```
#### PlanMessage - 任务计划
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
fun showPlan() {
val options = IFlowOptions()
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("帮我创建一个 Android 项目结构")
client.receiveMessages { message ->
when (message) {
is PlanMessage -> {
println("执行计划：")
message.entries.forEach { entry ->
val statusIcon = if (entry.status == "completed") "✅" else "⏳"
println("$statusIcon [${entry.priority}] ${entry.content}")
}
}
is TaskFinishMessage -> {
return@receiveMessages
}
}
}
}
}
```
#### TaskFinishMessage - 任务完成
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
fun checkCompletion() {
val options = IFlowOptions()
IFlowClient(options).use { client ->
client.connect()
client.sendMessage("计算 1+1")
client.receiveMessages { message ->
when (message) {
is AssistantMessage -> {
print(message.chunk.text)
}
is TaskFinishMessage -> {
println() // 换行
println("任务完成: ${message.stopReason}")
return@receiveMessages
}
}
}
}
}
```
## 常见用例
### 交互式聊天机器人
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
fun chatbot() {
println("iFlow 聊天机器人 (输入 'quit' 退出)")
println("-".repeat(50))
val options = IFlowOptions()
IFlowClient(options).use { client ->
client.connect()
while (true) {
print("\n你: ")
val userInput = readLine() ?: break
if (userInput.lowercase() in listOf("quit", "exit", "q")) {
println("再见！")
break
}
client.sendMessage(userInput)
print("iFlow: ")
client.receiveMessages { message ->
when (message) {
is AssistantMessage -> {
print(message.chunk.text)
}
is TaskFinishMessage -> {
println() // 换行
return@receiveMessages
}
}
}
}
}
}
fun main() {
chatbot()
}
```
### 流式响应处理
```kotlin
import com.iflow.sdk.query.IFlowQuery
fun streamExample() {
// 流式响应
IFlowQuery.queryStream(
text = "解释一下什么是升华现象",
onChunk = { chunk -> print(chunk) },
onComplete = { reason -> println("\n完成!") }
)
}
```
## 高级配置
### 权限模式配置
配置工具调用的权限管理：
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
// 自动批准所有工具
val autoOptions = IFlowOptions(
permissionMode = PermissionMode.AUTO
)
// 每次确认都询问
val manualOptions = IFlowOptions(
permissionMode = PermissionMode.MANUAL
)
// 选择性批准
val selectiveOptions = IFlowOptions(
permissionMode = PermissionMode.SELECTIVE
)
```
### 会话配置
```kotlin
import com.iflow.sdk.IFlowClient
import com.iflow.sdk.IFlowOptions
import com.iflow.sdk.models.*
val options = IFlowOptions(
url = "ws://localhost:8090/acp?peer=iflow",
timeout = 300_000L, // 5 分钟
permissionMode = PermissionMode.AUTO,
fileAccess = true,
fileReadOnly = true,
authMethodId = "iflow",
sessionSettings = SessionSettings(
workingDirectory = "/workspace"
)
)
```
### 文件附件支持
SDK 支持多种文件类型：
- **图片**：PNG, JPG, GIF, WebP, SVG (base64 编码)
- **音频**：MP3, WAV, M4A, OGG, FLAC (base64 编码)
- **文档**：PDF, TXT, 代码文件 (资源链接)
```kotlin
client.sendMessage(
text = "分析这些文件",
files = listOf(
"/path/to/image.png",
"/path/to/audio.mp3",
"/path/to/document.pdf"
)
)
```
### 错误处理
SDK 提供特定的异常类型：
```kotlin
import com.iflow.sdk.query.IFlowQuery
import com.iflow.sdk.exceptions.*
try {
val result = IFlowQuery.query("你好")
println(result)
} catch (e: ConnectionException) {
println("连接失败: ${e.message}")
} catch (e: AuthenticationException) {
println("认证失败: ${e.message}")
} catch (e: TimeoutException) {
println("操作超时: ${e.message}")
} catch (e: IFlowException) {
println("iFlow 错误: ${e.message}")
}
```
## API 参考
### 核心类
| 类名 | 描述 |
|------|------|
| `IFlowClient` | 主客户端类，管理与 iFlow 的连接 |
| `IFlowOptions` | 配置选项类 |
| `IFlowQuery` | 简单查询工具类 |
### IFlowQuery 方法
| 方法 | 描述 |
|------|------|
| `query(text, files, options)` | 发送查询并返回完整响应 |
| `queryStream(text, files, options, onChunk, onToolCall, onComplete, onError)` | 实时流式响应 |
| `querySync(text, files, options)` | 同步版本的 query（阻塞当前线程） |
| `queryBatch(queries, options)` | 并行发送多个查询 |
| `queryWithFile(text, filePath, options)` | 带单个文件附件的查询 |
| `queryCode(prompt, language, options)` | 生成带语言提示的代码 |
| `queryAnalyze(filePath, question, options)` | 分析文件 |
### IFlowClient 方法
| 方法 | 描述 |
|------|------|
| `connect()` | 建立与 iFlow 的连接 |
| `sendMessage(text, files)` | 发送带可选文件的消息 |
| `receiveMessages(callback)` | 接收流式响应 |
| `getMessageChannel()` | 获取消息通道用于接收消息 |
| `interrupt()` | 取消当前生成 |
| `approveToolCall(id, outcome)` | 批准工具调用 |
| `rejectToolCall(id)` | 拒绝工具调用 |
| `disconnect()` | 优雅地关闭连接 |
### 消息类型
| 消息类型 | 描述 | 主要属性 |
|----------|------|----------|
| `AssistantMessage` | AI 助手的文本响应 | `chunk.text` |
| `ToolCallMessage` | 工具执行请求和状态 | `label`, `status`, `confirmation` |
| `PlanMessage` | 结构化任务计划 | `entries` (包含 `content`, `priority`, `status`) |
| `TaskFinishMessage` | 任务完成信号 | `stopReason` |
| `ErrorMessage` | 错误信息 | `message` |
### 配置选项
| 选项 | 类型 | 描述 |
|------|------|------|
| `url` | `String` | WebSocket URL (默认: `ws://localhost:8090/acp?peer=iflow`) |
| `timeout` | `Long` | 超时时间（毫秒，默认: 300000 即 5 分钟） |
| `permissionMode` | `PermissionMode` | 工具调用权限模式 |
| `fileAccess` | `Boolean` | 是否允许文件访问 |
| `fileReadOnly` | `Boolean` | 文件访问是否只读 |
| `authMethodId` | `String` | 认证方法 ID |
| `sessionSettings` | `SessionSettings` | 会话配置 |
### 权限模式
| 模式 | 描述 |
|------|------|
| `PermissionMode.AUTO` | 自动批准所有工具 |
| `PermissionMode.MANUAL` | 每次确认都询问 |
| `PermissionMode.SELECTIVE` | 自动批准某些类型 |
## 架构
SDK 的结构如下：
```
com.iflow.sdk/
├── IFlowClient.kt // 主客户端类
├── IFlowOptions.kt // 配置
├── models/ // 数据类和枚举
├── transport/ // WebSocket 传输 (OkHttp)
├── protocol/ // ACP 协议实现
├── query/ // 简单查询工具
├── exceptions/ // 自定义异常
└── utils/ // JSON 和日志工具
```
## 故障排除
### 连接问题
如果遇到连接错误，请检查：
1. **iFlow 是否已安装**
```bash
iflow --version
```
2. **端口是否被占用**
```bash
# Linux/Mac
lsof -i :8090
# Windows
netstat -an | findstr :8090
```
3. **手动测试连接**
```bash
iflow --experimental-acp --port 8090
```
4. **WebSocket URL 是否正确**
- 默认: `ws://localhost:8090/acp?peer=iflow`
- 确保 URL 格式正确且IP地址和端口可访问
### 超时问题
对于长时间运行的任务，可以增加超时时间：
```kotlin
val options = IFlowOptions(
timeout = 600_000L // 10 分钟超时
)
```
## /docs_cn/sdk/sdk-python.md
---
title: Python SDK
description: 基于iFlow CLI SDK搭建你的专属Agent项目
sidebar_position: 8
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# SDK
## 概述
iFlow CLI SDK 是一个用于与 iFlow CLI 进行编程交互的 SDK。它通过代理通信协议（ACP）允许开发者构建具有对话、工具执行和任务规划能力的 AI 驱动应用程序。
**✨ 核心特性：SDK 自动管理 iFlow 进程 - 无需手动配置！**
## 系统要求
- **Python**: 3.8 或更高版本
- **iFlow CLI**: 0.2.24 或更高版本
- **操作系统**: Windows、macOS、Linux
## 安装
```bash
pip install iflow-cli-sdk
```
## 快速开始
### 基础示例
SDK 会自动检测并启动 iFlow 进程，无需手动配置：
```python
import asyncio
from iflow_sdk import IFlowClient, AssistantMessage, TaskFinishMessage
async def main():
# SDK 自动处理：
# 1. 检测 iFlow 是否已安装
# 2. 启动 iFlow 进程（如果未运行）
# 3. 查找可用端口并建立连接
# 4. 退出时自动清理资源
async with IFlowClient() as client:
await client.send_message("你好，iFlow！")
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(message.chunk.text, end="\n", flush=True)
elif isinstance(message, TaskFinishMessage):
break
asyncio.run(main())
```
### 简单查询
最简单的使用方式是通过 `query` 函数：
```python
from iflow_sdk import query
import asyncio
async def main():
response = await query("法国的首都是哪里？")
print(response) # 输出：法国的首都是巴黎。
asyncio.run(main())
```
## 核心概念
### IFlowClient
`IFlowClient` 是与 iFlow CLI 交互的主要接口，管理 WebSocket 连接的生命周期：
```python
from iflow_sdk import IFlowClient, IFlowOptions
# 使用默认配置（自动管理进程）
async with IFlowClient() as client:
await client.send_message("你的问题")
async for message in client.receive_messages():
# 处理消息
pass
# 使用自定义配置
options = IFlowOptions(
url="ws://localhost:8090/acp", # WebSocket URL
auto_start_process=True, # 自动启动 iFlow
timeout=30.0 # 超时时间（秒）
)
async with IFlowClient(options) as client:
await client.send_message("你的问题")
async for message in client.receive_messages():
# 处理消息
pass
```
### 消息类型
SDK 支持多种消息类型，对应 iFlow 协议的不同响应：
#### AssistantMessage - AI 助手响应
包含AgentInfo支持，可以获取代理的详细信息：
```python
import asyncio
from iflow_sdk import IFlowClient, AssistantMessage, TaskFinishMessage, AgentInfo
async def handle_assistant_message():
async with IFlowClient() as client:
await client.send_message("请介绍一下Python")
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(message.chunk.text, end="\n", flush=True)
# 访问代理信息（如果有）
if message.agent_info:
print(f"代理ID: {message.agent_info.agent_id}")
if message.agent_info.task_id:
print(f"任务ID: {message.agent_info.task_id}")
if message.agent_info.agent_index is not None:
print(f"代理索引: {message.agent_info.agent_index}")
elif isinstance(message, TaskFinishMessage):
break
if __name__ == "__main__":
asyncio.run(handle_assistant_message())
```
#### ToolCallMessage - 工具调用
工具调用消息现在也包含AgentInfo信息和工具名称：
```python
import asyncio
from iflow_sdk import IFlowClient, ToolCallMessage, ToolCallStatus, TaskFinishMessage
async def handle_tool_calls():
async with IFlowClient() as client:
# 注意：这个示例演示如何查看工具调用消息
# iFlow 会要求提供完整路径和内容来创建文件
await client.send_message("列出当前目录的文件")
async for message in client.receive_messages():
if isinstance(message, ToolCallMessage):
print(f"状态: {message.status}")
# 新增：工具名称
if message.tool_name:
print(f"工具名称: {message.tool_name}")
# 访问代理信息
if message.agent_info:
print(f"代理ID: {message.agent_info.agent_id}")
elif isinstance(message, TaskFinishMessage):
break
if __name__ == "__main__":
asyncio.run(handle_tool_calls())
```
#### PlanMessage - 任务计划
```python
import asyncio
from iflow_sdk import IFlowClient, PlanMessage, TaskFinishMessage
async def show_plan():
async with IFlowClient() as client:
await client.send_message("帮我创建一个Python项目结构")
async for message in client.receive_messages():
if isinstance(message, PlanMessage):
print("执行计划：")
for entry in message.entries:
status_icon = "✅" if entry.status == "completed" else "⏳"
print(f"{status_icon} [{entry.priority}] {entry.content}")
elif isinstance(message, TaskFinishMessage):
break
if __name__ == "__main__":
asyncio.run(show_plan())
```
#### TaskFinishMessage - 任务完成
```python
import asyncio
from iflow_sdk import IFlowClient, AssistantMessage, TaskFinishMessage, StopReason
async def check_completion():
async with IFlowClient() as client:
await client.send_message("计算 1+1")
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(message.chunk.text, end="", flush=True)
elif isinstance(message, TaskFinishMessage):
print() # 换行
if message.stop_reason == StopReason.END_TURN:
print("任务正常完成")
elif message.stop_reason == StopReason.MAX_TOKENS:
print("达到最大令牌限制")
break # TaskFinishMessage 表示对话结束
if __name__ == "__main__":
asyncio.run(check_completion())
```
## 常见用例
### 交互式聊天机器人
```python
#!/usr/bin/env python3
import asyncio
from iflow_sdk import IFlowClient, AssistantMessage, TaskFinishMessage
async def chatbot():
print("iFlow 聊天机器人 (输入 'quit' 退出)")
print("-" * 50)
async with IFlowClient() as client:
while True:
user_input = input("\n你: ")
if user_input.lower() in ['quit', 'exit', 'q']:
print("再见！")
break
await client.send_message(user_input)
print("iFlow: ", end="", flush=True)
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(message.chunk.text, end="", flush=True)
elif isinstance(message, TaskFinishMessage):
print() # 换行
break
if __name__ == "__main__":
asyncio.run(chatbot())
```
### 流式响应处理
```python
from iflow_sdk import query_stream
import asyncio
async def stream_example():
prompt = "解释一下什么是升华现象"
# query_stream 返回文本块的异步生成器
async for chunk in query_stream(prompt):
print(chunk, end="", flush=True)
print() # 最后换行
asyncio.run(stream_example())
```
## 高级配置
### 手动进程管理
如果需要手动管理 iFlow 进程：
```python
import asyncio
from iflow_sdk import IFlowClient, IFlowOptions, AssistantMessage, TaskFinishMessage
async def manual_process_example():
# 禁用自动进程管理
options = IFlowOptions(
auto_start_process=False,
url="ws://localhost:8090/acp" # 连接到已存在的 iFlow
)
async with IFlowClient(options) as client:
await client.send_message("你的问题")
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(message.chunk.text, end="", flush=True)
elif isinstance(message, TaskFinishMessage):
break
if __name__ == "__main__":
asyncio.run(manual_process_example())
```
> 注意
> 手动模式需要您单独启动 iFlow：
>```bash
>iflow --experimental-acp --port 8090
>```
### 错误处理
SDK 提供了详细的错误处理机制：
```python
import asyncio
from iflow_sdk import IFlowClient, ConnectionError, TimeoutError, AssistantMessage, TaskFinishMessage
async def error_handling_example():
try:
async with IFlowClient() as client:
await client.send_message("测试")
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(message.chunk.text, end="", flush=True)
elif isinstance(message, TaskFinishMessage):
break
except ConnectionError as e:
print(f"连接错误: {e}")
except TimeoutError as e:
print(f"超时错误: {e}")
except Exception as e:
print(f"未知错误: {e}")
if __name__ == "__main__":
asyncio.run(error_handling_example())
```
### 同步调用
对于需要同步调用的场景：
```python
from iflow_sdk import query_sync, IFlowOptions
# 同步调用，带超时控制
options = IFlowOptions(timeout=30.0)
response = query_sync("你的问题", options=options)
print(response)
```
## API 参考
### 核心类
| 类名 | 描述 |
|------|------|
| `IFlowClient` | 主客户端类，管理与 iFlow 的连接 |
| `IFlowOptions` | 配置选项类 |
| `RawDataClient` | 访问原始协议数据的客户端 |
### 消息类型
| 消息类型 | 描述 | 主要属性 |
|----------|------|----------|
| `AssistantMessage` | AI 助手的文本响应 | `chunk.text`, `agent_id`, `agent_info` |
| `ToolCallMessage` | 工具执行请求和状态 | `label`, `status`, `tool_name`, `agent_info` |
| `PlanMessage` | 结构化任务计划 | `entries` (包含 `content`, `priority`, `status`) |
| `TaskFinishMessage` | 任务完成信号 | `stop_reason` |
### AgentInfo - 代理信息
新增的`AgentInfo`类提供了从iFlow代理ID解析的详细信息：
| 属性 | 类型 | 描述 |
|------|------|------|
| `agent_id` | `str` | 完整的代理ID |
| `agent_index` | `Optional[int]` | 代理在任务中的索引 |
| `task_id` | `Optional[str]` | 任务或实例ID |
| `timestamp` | `Optional[int]` | 创建时间戳 |
#### AgentInfo 使用示例
```python
from iflow_sdk import AgentInfo
# 从代理ID解析信息
agent_id = "subagent-task-abc123-2-1735123456789"
agent_info = AgentInfo.from_agent_id_only(agent_id)
if agent_info:
print(f"代理ID: {agent_info.agent_id}")
print(f"任务ID: {agent_info.task_id}")
print(f"代理索引: {agent_info.agent_index}")
print(f"时间戳: {agent_info.timestamp}")
```
## 故障排除
### 连接问题
如果遇到连接错误，请检查：
1. **iFlow 是否已安装**
```bash
iflow --version
```
2. **端口是否被占用**
```bash
# Linux/Mac
lsof -i :8090
# Windows
netstat -an | findstr :8090
```
3. **手动测试连接**
```bash
iflow --experimental-acp --port 8090
```
### 超时问题
对于长时间运行的任务，可以增加超时时间：
```python
from iflow_sdk import IFlowClient, IFlowOptions
options = IFlowOptions(timeout=600.0) # 10分钟超时
client = IFlowClient(options)
```
### 日志调试
启用详细日志以便调试：
```python
import logging
from iflow_sdk import IFlowClient, IFlowOptions
# 设置日志级别
logging.basicConfig(level=logging.DEBUG)
options = IFlowOptions(log_level="DEBUG")
client = IFlowClient(options)
```
## /docs_en/configuration/iflowignore.md
# .iflowignore
## Overview
`.iflowignore` is a file ignore feature in iFlow CLI, similar to Git's `.gitignore`. It allows you to specify which files and directories should be ignored when using iFlow CLI tools.
## How It Works
When you create a `.iflowignore` file in your project root directory and define ignore rules, iFlow CLI tools that support this feature will automatically skip matching files and directories, without processing them.
## Supported Tools
The following iFlow CLI tools support `.iflowignore` functionality:
- `ls` - Directory listing tool
- `read_many_files` - Batch file reading tool
- `@filename` syntax - AT command file references
- Other file operation related tools
## Usage
### 1. Create .iflowignore File
Create a `.iflowignore` file in your project root directory:
```bash
touch .iflowignore
```
### 2. Add Ignore Rules
The `.iflowignore` file follows the same syntax rules as `.gitignore`:
```bash
# This is a comment line
# Ignore specific files
secrets.txt
config.json
# Ignore specific directories
build/
dist/
node_modules/
# Use wildcards to ignore file types
*.log
*.tmp
*.cache
# Use path matching
/root-only-file.txt
src/**/*.test.js
# Negation rules (do not ignore)
*.log
!important.log
```
### 3. Syntax Rules
| Rule | Description | Example |
|------|------|------|
| `#` | Comment line | `# This is a comment` |
| `*` | Match any characters | `*.log` matches all .log files |
| `?` | Match single character | `file?.txt` matches file1.txt |
| `[]` | Character set matching | `[abc].txt` matches a.txt, b.txt, c.txt |
| `/` at start | Root directory relative path | `/build/` only matches build in root directory |
| `/` at end | Match directories only | `temp/` only matches directories, not files |
| `!` at start | Negation rule | `!important.log` do not ignore this file |
## Practical Examples
### Frontend Project
```bash
# .iflowignore for React/Vue project
# Build output
build/
dist/
.next/
# Dependencies
node_modules/
# Logs and cache
*.log
.cache/
.parcel-cache/
# Environment variable files
.env.local
.env.production
# Test coverage
coverage/
# IDE configuration (but keep .vscode)
.idea/
*.swp
*.swo
```
### Node.js Backend Project
```bash
# .iflowignore for Node.js backend
# Runtime files
*.pid
*.log
logs/
# Dependencies and build
node_modules/
dist/
build/
# Database files
*.db
*.sqlite
# Upload file directories
uploads/
temp/
# Sensitive configuration
.env
config/production.json
```
### Python Project
```bash
# .iflowignore for Python project
# Python cache
__pycache__/
*.pyc
*.pyo
*.pyd
# Virtual environments
venv/
env/
.venv/
# Build files
build/
dist/
*.egg-info/
# Jupyter Notebook checkpoints
.ipynb_checkpoints/
# Testing and coverage
.pytest_cache/
.coverage
htmlcov/
```
## Feature Verification
### Test ls Tool
```bash
# Use iFlow CLI's ls tool to view directory
iflow -p "ls ."
# Files ignored by .iflowignore will not appear in the output
# The tool will show statistics like "X files were iflow-ignored"
```
### Test File Reading
```bash
# Use batch file reading
iflow -p "read_many_files *.txt"
# Ignored .txt files will show "file is ignored by .iflowignore" message
```
### Test @ Command
```bash
# Use @ syntax to reference files
iflow -p "@ignored-file.txt"
# Ignored files will show warning message and skip processing
```
## Important Notes
1. **Restart Required**: After modifying the `.iflowignore` file, you need to restart the iFlow CLI session for changes to take effect
2. **File Location**: The `.iflowignore` file must be placed in the project root directory
3. **Git Independence**: `.iflowignore` and `.gitignore` are independent and do not affect each other
4. **Tool Support**: Not all tools support this feature, mainly file operation related tools
## Debugging Tips
If you find that ignore rules are not taking effect:
1. Check if the `.iflowignore` file is in the project root directory
2. Check if file paths are correct (relative to project root directory)
3. Restart the iFlow CLI session
4. Use the `ls` tool to verify ignore effects
## Best Practices
1. **Version Control**: Commit the `.iflowignore` file to Git so the team can share ignore rules
2. **Layered Ignoring**: Use in combination with `.gitignore` - `.gitignore` handles version control, `.iflowignore` handles AI tools
3. **Regular Maintenance**: Update ignore rules timely as the project evolves
4. **Documentation**: Document special ignore rules in the project README
By properly using `.iflowignore`, you can make iFlow CLI focus more on processing important code files, improving work efficiency.
## /docs_en/features/sandbox.md
---
sidebar_position: 6
hide_title: true
---
# Sandbox Configuration
iFlow CLI can execute potentially unsafe operations (such as shell commands and file modifications) in a sandbox environment to protect your system.
The sandbox is disabled by default, but you can enable it in several ways:
- Use the `--sandbox` or `-s` flag.
- Set the `IFLOW_SANDBOX` environment variable.
By default, it uses the prebuilt `iflow-cli-sandbox` Docker image.
For project-specific sandbox requirements, you can create a custom Dockerfile at `.iflow/sandbox.Dockerfile` in your project root. This Dockerfile can be based on the base sandbox image:
```dockerfile
FROM iflow-cli-sandbox
# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config
```
When `.iflow/sandbox.Dockerfile` exists, you can automatically build a custom sandbox image when running iFlow CLI by using the `BUILD_SANDBOX` environment variable:
```bash
BUILD_SANDBOX=1 iflow -s
```
The content has been capped at 50000 tokens. The user could consider applying other filters to refine the result. The better and more specific the context, the better the LLM can follow instructions. If the context seems verbose, the user can refine the filter using uithub. Thank you for using https://uithub.com - Perfect LLM context for any GitHub repo.