# cli_coder

**Repository Path**: hanshu_alan/cli_coder

## Basic Information

- **Project Name**: cli_coder
- **Description**: 一个类似于cursor的辅助编程命令行工具
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-12-16
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cli_coder

这是一个命令行工具，用于管理和AI聊天的内容，实现个人或者团队知识库的积累。

## 目录
- [配置](#配置)
- [运行](#运行)
- [使用方式](#使用方式)
  - [参数--new](#参数--new)
  - [参数--new-with-first-message](#参数--new-with-first-message)
  - [参数--read-action](#参数--read-action)
  - [子命令run-action](#子命令run-action)
  - [公共kb](#公共kb)
- [辅助编程](#辅助编程)
  - [引用别的文件](#引用别的文件)
  - [和AI讨论代码](#和ai讨论代码)
  - [根据提交记录给出建议](#根据提交记录给出建议)
  - [在提示词中生成代码文件](#在提示词中生成代码文件)
  - [collect_all](#collect_all)
  - [with_abilities](#with_abilities)
- [ActionTag使用说明](#actiontag使用说明)
- [沟通与交流](#沟通与交流)

## 配置

```bash
export AI_API_KEY="..." # API token
export AI_SERVER_BASE_URL="https://api.ppinfra.com/v3/openai" 
export AI_MODEL="deepseek/deepseek-r1/community" # deepseek/deepseek-r1/community, deepseek/deepseek-v3
```

## 运行

```bash
bash-3.2$ cli_coder --help
caozongying_cao<zongying_cao@163.com> is the author of cli assistant

Usage: cli_coder [OPTIONS] [COMMAND]

Commands:
  run-action  启用对 output.md 中 <action> 标签的解析与执行
  help        Print this message or the help of the given subcommand(s)

Options:
  -q, --question <QUESTION>        问题
  -l, --long                       长问题
  -n, --new                        开始一个新的提问（不带上之前的历史记录，之前的历史记录会被备份）
  -N, --new-with-first-message     开始一个新的提问，并将第一个用户message写入long_question.md
      --read-action                执行action标签
  -u, --usekb <usekb>              使用指定编号的kb知识来回答问题(可指定多个，用逗号分隔)
  -s, --listkb                     列出所有的kb话题
  -e, --temperature <temperature>  设置回答温度，值为0到2 [default: 0]
  -p, --project                    处理项目相关任务，依赖于配置config.yaml
  -c, --collect_all                当启用项目模式时，是否收集所有包含todo/read的文件（默认只处理第一个）
  -w, --with_abilities <with_abilities>  指定模型具有的能力，多个能力用逗号分隔
  -h, --help                       Print help
  -V, --version                    Print version
bash-3.2$ 
```

## 使用方式

```bash
mkdir ai_kb_db # 创建目录，这个目录可以是任意名字，和AI的聊天记录将以文本文件的形式存在在这个目录下面
cd ai_kb_db
touch .ai_db # 创建一个空白文件作为ai目录的标识

mkdir topic # 聊天记录将存储在名为topic的目录下
cd topic # 进入topic目录，进行这个topic的聊天

# 定义你的智能体
touch .system

# 定义扫描的项目，具体参考`辅助编程`部分
touch config.yml

# 在.system中输入你对智能体的定义，比如：我是一个智能体，回复采用中文，我的任务是帮助用户处理xxx类的工作
# 如果没有创建.system，系统会默认使用"我是一个智能体"来作为智能体的定义

# 从命令行输入简单问题
cli_coder -q 你的问题 # 开始聊天
cat output.md # 查看ai返回的结果

# 从long_question.md中输入长篇问题
cli_coder
cat output.md # 查看ai返回的结果

# 查看聊天历史
cat messages

# 将当前的回复整合到 knowlege base(kb)中，标题为"总结1"
cli_coder -q 整合之前的聊天内容 -t 10000 -k 总结1

# 列出kb中的所有标题
cli_coder -s

# 使用"总结1"（通过cli_coder中列出的序号来选择）来回答这个问题
cli_coder -q 帮我创建一个新的模块 -u 2
cli_coder -q 帮我创建一个新的模块 -u 2,3,5 # 从1.7.0开始，可以支持多个kb编号
```

### 参数--new

`--new` 或 `-n` 参数用于开始一个全新的提问会话。使用此参数时：

1. 不会带入任何之前的历史记录
2. 之前的历史记录会被自动备份到 `messages.bak` 文件中
3. 新的会话将从空白状态开始

#### 使用示例

```bash
# 开始一个全新的提问，不带入历史记录
cli_coder -q "解释Rust的所有权系统" --new

# 或者使用短参数
cli_coder -q "解释Rust的所有权系统" -n
```

#### 使用场景

- 当你想开始一个完全独立的新话题时
- 当之前的历史记录与当前问题无关时
- 当你想避免历史记录对当前回答产生干扰时

### 参数--new-with-first-message

`--new-with-first-message` 或 `-N` 参数用于开始一个新的提问会话，并将历史记录中的第一个用户消息自动写入到 `long_question.md` 文件中。使用此参数时：

1. 不会带入任何之前的历史记录
2. 之前的历史记录会被自动备份到 `messages.bak` 文件中
3. 会从历史记录中提取第一个用户消息，并将其内容写入到 `long_question.md` 文件中
4. 程序执行完成后会自动退出，不会继续执行其他逻辑

#### 使用示例

```bash
# 开始一个新的提问，并将第一个用户消息写入 long_question.md
cli_coder --new-with-first-message

# 或者使用短参数
cli_coder -N
```

#### 使用场景

- 当你想基于之前的某个问题重新开始讨论时
- 当你想将历史记录中的某个问题提取出来作为新的长问题时
- 当你想重新处理之前的问题但不想带入完整的历史记录时

#### 注意事项

- 如果历史记录中没有用户消息，程序会报错并退出
- 此参数执行完成后程序会自动退出，不会继续执行其他逻辑
- 写入 `long_question.md` 后，你可以手动编辑该文件，然后运行 `cli_coder` 来处理这个长问题

### 参数--read-action

`--read-action` 参数用于控制在长问题处理过程中是否执行 `<action>` 标签。默认情况下，系统不会执行action标签，只有当此参数被设置为 `true` 时才会执行。

#### 基本用法
```bash
# 执行long_question.md中的action标签
cli_coder --read-action

# 结合其他参数使用
cli_coder --read-action --project
```

#### 使用场景

- 当你需要在发送问题给AI之前，先执行一些文件操作（如读取文件、搜索内容等）
- 当你希望action标签的执行结果被包含在发送给AI的问题中
- 当你需要在AI回答之前准备一些上下文信息

#### 注意事项

- 此参数仅在处理 `long_question.md` 时有效
- 默认值为 `false`，即不执行action标签
- 如果action标签执行失败，错误信息会被记录到日志中

### 子命令run-action(1.13.0)

`run-action` 子命令用于启用对 `output.md` 文件中 `<action>` 标签的解析与执行。当AI在响应中包含可执行的操作标签时，此子命令可以自动执行这些操作并将结果反馈给AI。

#### 1. 基本用法
```bash
cli_coder run-action
```

#### 2. 执行操作并发送观察结果
```bash
cli_coder run-action --send-observation
```

当使用 `--send-observation` 参数时，系统会将action的运行结果返回给大模型，以便进行后续的交互和决策。

#### 使用场景
- 自动执行文件操作（创建、读取、写入文件）
- 执行系统命令
- 调用外部工具或API

### 公共kb(1.6.0)

- 手动在.ai_db所在的目录下创建common_kb目录
- 将作为公共知识库的内容放在这个目录下
- 使用方式`cli_coder -s`，列出所有的知识内容，公共的内容会排在后面；使用方式还是`cli_coder -u`
- 需要注意的是，`common_kb`和当前私有的`kb`中的文件名不同重复。

## 辅助编程

在config.yml中设置你的项目信息，当运行cli_coder命令时，程序会扫描项目文件夹中的文件，处理包含`// todo: `的文件。
目前只能处理第一个包含todo的文件。
config.yml的定义如下:

```yml
path=[项目的绝对路径]
handle_ext:
    - vue
    - ts
exclude_folders:
    - node_modules
    - target
    - __pycache__
# 为tree_read action提供默认的排除项，多个值用逗号分隔
tree_read_default_excludes: "node_modules,target,.git"
# 为search_for_key action提供默认的排除项，多个值用逗号分隔
search_for_key_default_excludes: "node_modules,target,.git,dist"
# 为search_for_file action提供默认的排除项，多个值用逗号分隔
search_for_file_default_excludes: "node_modules,target,.git,dist"
# 智能体需要了解的知识目录，key为标题，value为路径
knowledges:
    "项目文档": "docs"
    "API文档": "api/docs"
    "设计文档": "design"
# 编译命令，用于compile action
compile_command: "cargo build"
```

#### 配置项说明

- `path`: 项目的绝对路径
- `handle_ext`: 需要处理的文件扩展名列表
- `exclude_folders`: 需要排除的文件夹列表
- `tree_read_default_excludes`: 为 `tree_read` action 提供默认的排除项，多个值用逗号分隔。当在 action 标签中没有指定 `excludes` 属性时，将使用此配置作为默认值
- `search_for_key_default_excludes`: 为 `search_for_key` action 提供默认的排除项，多个值用逗号分隔。当在 action 标签中没有指定 `excludes` 属性时，将使用此配置作为默认值
- `search_for_file_default_excludes`: 为 `search_for_file` action 提供默认的排除项，多个值用逗号分隔。当在 action 标签中没有指定 `excludes` 属性时，将使用此配置作为默认值
- `knowledges`: 智能体需要了解的知识目录配置。key为知识标题，value为路径（支持相对路径和绝对路径）。如果使用相对路径，则相对于 `path` 配置的项目路径。这些知识目录信息会在生成 system message 时，以"## 生成指南"的形式插入到系统消息的靠前位置，帮助智能体了解项目中重要的知识资源位置。
- `compile_command`: 编译命令，用于 `compile` action。当使用 `<compile mode="cmd" />` 标签时，系统会执行此命令来编译项目。如果未配置此字段，系统会返回错误信息。

#### knowledges 配置示例

```yml
knowledges:
    "项目文档": "docs"
    "API文档": "api/docs"
    "设计文档": "design"
    "架构图": "architecture/diagrams"
```

配置后，在生成 system message 时会自动插入以下内容：

```
## 生成指南
- 项目文档: docs
- API文档: api/docs
- 设计文档: design
- 架构图: architecture/diagrams
```

这样智能体就能了解到项目中重要的知识资源位置，在回答问题时可以参考这些目录中的内容。

如果你不想文件中的todo被处理，请加上exclude-ai-todo
```rust
let x = 3; // todo: 重构这个名称 exclude-ai-todo
```

如果想让大模型重构并生成新的代码文件，那么要告诉大模型使用`<file src="{重构的代码地址}" action="createAndWrite">`来包裹重构后的内容。
**重构的代码地址是相对于当前文件的地址**

### 引用别的文件

在todo中，允许引入别的文件，为大模型提供参考。
文件路径相对于config.yml中的path

```vue
// todo: 重构下面的代码，参考{name:file1}
// <file name="file1" src="src/Home.vue" action="read"/>
<span>hello</span>
```

### 和AI讨论代码

在代码中添加`// read: ....`，和AI沟通你的问题，你的问题就放在`// read: `后。
在版本1.8.1之后，标记为read的文件，不再需要commit了

### 根据提交记录给出建议

根据你提供的commit id，生成这次提交中所修改代码的建议。

**使用方法**
在long_question.md中添加commit_id和你关注的要点。

```
请关注token处理相关的变化
<commit_id value="ed03ee94099df82aa7178c71810ca8dc1dc994dc" />
```

运行命令:
```bash
cli_coder -p
```

### long_question处理工程文件（1.11.5）
在长问题的处理中，支持插入<file/>标签来给大模型提供相关文件的内容。
前提:
- 配置了config.yml且配置的项目目录路径
- file.src的路径是相对于config.yml中的项目目录路径

### collect_all(1.12.0)

- 新增 `--collect_all` 或 `-c` 参数，用于控制项目模式下是否收集所有匹配的todo文件
- 默认情况下（未指定该参数），系统只处理第一个包含`// todo:`的文件
- 当启用 `--collect_all` 时，系统会收集并处理所有匹配的todo文件
- 该参数仅在启用 `--project` 或 `-p` 参数时有效

#### example

```
# 只处理第一个todo文件（默认行为）
cli_coder --project

# 处理所有匹配的todo文件
cli_coder --project --collect_all
```

### with_abilities(1.13.0)

- 新增 `--with_abilities` 或 `-w` 参数，用于指定模型具有的能力
- 多个能力用逗号分隔
- **重要：此参数仅在首次会话时（使用 `-n` 或 `--new` 参数）有效**
- 后续的会话中，system_message 会从缓存加载，`with_abilities` 参数会被忽略，因此可以"不用"这个参数
- 如果需要在后续会话中更改 abilities，必须使用 `-n` 参数重新开始一个新会话

#### example

```
# 首次会话：指定模型具有文件操作和代码生成能力
cli_coder -q "帮我重构这个模块" --new --with_abilities "file_operations,code_generation"

# 首次会话：指定多个能力
cli_coder -q "分析这个项目" --new --with_abilities "file_read,file_write,execute_command,code_analysis"

# 后续会话：不需要指定 with_abilities，会使用首次会话时设置的 abilities
cli_coder -q "继续分析这个模块"

# 如果需要更改 abilities，必须使用 --new 重新开始会话
cli_coder -q "重新分析项目" --new --with_abilities "file_read,code_analysis"
```

常见的能力包括：
- `file_read`: 读取指定文件的内容
- `file_write`: 创建或写入文件内容
- `tree_read`: 读取目录结构和内容（支持最大20层深度）
- `search_for_key`: 搜索文件内容中的关键字
- `search_for_file`: 根据关键字搜索文件名或文件夹名
- `compile`: 编译项目

这些能力使得AI助手能够：
- 访问和分析项目中的特定文件
- 生成新的代码文件或修改现有文件
- 浏览项目目录结构以了解整体架构
- 在执行复杂任务时自动获取所需的上下文信息
- 快速定位包含特定关键字的文件
- 根据文件名或文件夹名关键字查找相关文件或目录
- 执行项目编译命令并获取编译结果

## ActionTag使用说明

ActionTag 是用于标识不同类型操作实体的标签系统，遵循 XML 规则定义。通过这些标签，AI助手可以执行文件操作、目录浏览、内容搜索、项目编译等任务。

### 核心定义

- `file`: 用于标识**文件实体**的专属标签
- `tree`: 用于标识**目录实体**的专属标签
- `searchForKey`: 用于在指定路径下搜索包含关键字的专属标签，通常用于快速定位包含目标"关键字"的相关文件
- `searchForFile`: 用于根据关键字查找项目目录下匹配的文件名或文件夹名的专属标签
- `compile`: 用于编译项目的专属标签

### 属性说明

#### file 标签

| 属性名（Attribute） | 含义与规则                                                                 | 约束与示例                          |
|--------------------|----------------------------------------------------------------------------|-------------------------------------|
| `src`              | 定义文件的存储路径，可以是"绝对路径"和"相对路径"                           | 支持绝对路径（如 `/user/docs/report.md`）或相对路径（如 `./data/table.xlsx`），不可省略 |
| `name`             | 定义文件在上下文（如对话、多文件交互场景）中的**唯一引用标识**             | 可选，仅当在上下中需要引用该文件实体名称时;需与其他文件的 `name` 区分，引用格式固定为 `{name:[name]}`（例：`{name:monthly_sales}`） |
| `mode`             | 定义文件的行为; "read":读取文件,"write": 写入文件                          | 可选，如果被设置，那么一定要有"src"属性 | 

**示例**

- 在Action过程中，如果需要读取某个文件，那么在你返回的内容中包含`<file src="..." mode="read" />`
- 在Action过程中，如果需要将内容通过文件实体输出，那么在返回的内容中包含`<file src=".." mode="write">{需要写入文件的内容}</file>`

**注意**：只有在相对路径时，才会自动创建不存在的目录

#### tree 标签

| 属性名（Attribute） | 含义与规则                                                                 | 约束与示例                          |
|--------------------|----------------------------------------------------------------------------|-------------------------------------|
| `src`              | 定义目录的存储路径，用于定位目录位置                                       | 支持绝对路径（如 `/user/docs/`）或相对路径（如 `./data/`），不可省略 |
| `name`             | 定义文件在上下文（如对话、多文件交互场景）中的**唯一引用标识**             | 可选，仅当在上下中需要引用该文件实体名称时;需与其他文件的 `name` 区分，引用格式固定为 `{name:[name]}`（例：`{name:model_tree}`） |
| `mode`             | 定义行为; "read":读取文件                                                  | 必须，只有"read"这一个选项 |

为了安全，默认读取目录的最大深度为20

**示例**

在Action过程中，如果需要读取某个路径下的文件，那么在你生成的内容中包含`<tree src="..." mode="read"/>`

#### searchForKey 标签

| 属性名（Attribute） | 含义与规则                                                                 | 约束与示例                          |
|--------------------|----------------------------------------------------------------------------|-------------------------------------|
| `src`              | 搜索的路径，搜索这个路径下的所有文件                                       | 必须，支持绝对路径或相对路径        |
| `excludes`         | 排除的名称，这个名称可以是文件夹名称或者是文件名称，多个名称用","分割      | 可选，如果不设置，藐视不排除任何内容|
| `keys`             | 搜索的关键字，多个关键字用","分割                                          | 必须                                |
| `match_method`     | 匹配方法，可选项为:exact, startsWith, endsWith，如果不设置，默认为"exact"  | 可选                                |
| `mode`             | 定义行为; "read":执行搜索                                                  | 必须，只有"read"这一个选项          |

**示例**

在Action过程中，如果需要搜索某个路径下的包含"关键字"的文件，那么在你生成的内容中包含`<searchForKey src="src" keys="UserState,Response" match_method="exact" mode="read" />`

#### searchForFile 标签

| 属性名（Attribute） | 含义与规则                                                                 | 约束与示例                          |
|--------------------|----------------------------------------------------------------------------|-------------------------------------|
| `key`              | 搜索的关键字，用于匹配文件名或文件夹名                                     | 必须                                |
| `excludes`         | 排除的名称，这个名称可以是文件夹名称或者是文件名称，多个名称用","分割      | 可选，如果不设置，则使用配置中的search_for_file_default_excludes值 |

**示例**

在Action过程中，如果需要在项目文件夹下搜索文件名或文件夹名中包含"guide"的所有项，那么在你生成的内容中包含`<searchForFile key="guide" />`

#### compile 标签

| 属性名（Attribute） | 含义与规则                                                                 | 约束与示例                          |
|--------------------|----------------------------------------------------------------------------|-------------------------------------|
| `mode`             | 定义行为; "cmd":执行编译命令,"result": 展示编译结果                        | 必须                                |

**示例**

- 在Action过程中，如果需要编译项目，那么在你返回的内容中包含`<compile mode="cmd" />`
- 编译命令需要在config.yml中配置compile_command字段
- 如果没有配置编译命令，系统会返回错误信息
- 编译结果会以`<compile mode="result">...</compile>`的形式返回

## 其它能力
- 在输出信息中包含了当前会话的token消耗总数


## 沟通与交流

[csdn博客](https://blog.csdn.net/firefox1?type=blog)  
[知乎](https://www.zhihu.com/people/cao-zong-ying-58/columns)  
[联系我](mailto:zongying_cao@163.com)