VJSP AI Code 命令行工具（CLI）

可在终端中通过命令行的纯键盘导航方式，高效完成规划、调试与编码工作。

VJSP 命令行工具采用与IDE扩展插件同源的底层技术，全程可沿用一致的工作流，处理智能体驱动的编码任务。

安装

bash

npm install -g @vjsp/cli

切换至目标工作目录，运行 vjsp 命令：

bash

# 启动交互式对话会话
vjsp

# 以指定模式启动
vjsp --mode architect

# 加载指定工作区启动
vjsp --workspace /path/to/project

# 恢复当前工作区的上一次对话
vjsp --continue

启动命令行工具后，即可选择适配的模型与相关模式，开启新的任务。

升级

执行以下命令升级 VJSP 命令行工具包：

bash

npm update -g @vjsp/cli

VJSP 命令行工具核心能力

无需离开终端，完成代码变更的规划与执行：直接通过命令行编辑项目代码，无需打开集成开发环境（IDE）。
根据工作流任务匹配最优运行模式：支持选择架构设计、智能问答、调试排障、智能调度等官方模式，也可自定义智能体运行模式。
实现任务自动化处理：借助AI辅助编写Shell脚本，完成文件夹内文件批量重命名等各类任务。
通过技能扩展功能边界：基于智能体技能（Agent Skills），为工具赋予领域专业能力，沉淀可复用工作流。

命令行工具参考手册

键盘快捷键

快捷键	功能描述
`Ctrl+C`	退出工具（连续按两次确认退出）
`Ctrl+X`	取消当前执行的任务
`Esc`	流式响应时取消当前任务，或清空输入框内容
`Ctrl+Y`	切换极速执行模式（自动批准所有操作指令）
`Ctrl+R`	恢复任务（仅任务处于待恢复状态时生效）
`!`	进入Shell模式（仅输入框为空时生效）
`↑/↓`	翻阅命令历史记录（仅输入框为空时生效）

内置命令

命令	功能描述	示例
`vjsp`	启动交互式会话
`/mode`	切换运行模式（Architect、Code、Ask、Debug、Orchestrator）	`/mode orchestrator`
`/model`	查看可用模型列表并实现模型切换
`/model list`	列出所有可用的大语言模型
`/model info`	根据模型名称，打印该模型的详细描述信息	`/model info Qwen3-VJSP`
`/model select`	选择并切换至新的大语言模型
`/checkpoint list`	列出所有可用的检查点
`/checkpoint restore`	恢复至指定检查点（该操作具有破坏性）	`/checkpoint restore 41db173a`
`/tasks`	查看任务历史记录
`/tasks search`	根据查询关键词检索任务	`/tasks search bug fix`
`/tasks select`	切换至指定任务	`/tasks select abc123`
`/tasks page`	跳转至任务历史记录的指定页码	`/tasks page 2`
`/tasks next`	翻至任务历史记录下一页
`/tasks prev`	翻至任务历史记录上一页
`/tasks sort`	调整任务历史记录的排序方式	`/tasks sort most-expensive`
`/tasks filter`	对任务历史记录进行筛选	`/tasks filter favorites`
`/config`	打开配置编辑器（与命令 `vjsp config` 功能一致）
`/new`	清空历史状态，启动新的智能体任务
`/help`	列出所有可用命令及使用方法
`/exit`	退出命令行工具

Skills

本命令行工具支持智能体技能能力，该能力以轻量级格式实现，可为AI赋予专业领域知识与标准化工作流，实现功能扩展。

Skill 文件的加载路径分为以下两类：

全局Skill：~/.vjsp/skills/（所有项目均可调用）
项目专属Skill：.vjsp/skills/（仅当前项目可调用）

Skill 的生效范围分为两种类型：

通用型 - 所有运行模式下均生效
模式专属型 - 仅在指定运行模式下加载（如代码开发模式、架构设计模式）

Skill 文件目录结构示例：

your-project/
└── .vjsp/
    ├── skills/               # 当前项目的通用 Skill 目录
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # 当前项目的代码开发模式专属 Skill 目录
        └── linting-rules/
            └── SKILL.md

新增 Skill

创建 Skill 存放目录：
bash
```
mkdir -p ~/.vjsp/skills/api-design
```
1
在该目录下创建 SKILL.md 文件，文件头部需添加 YAML 配置信息：
markdown
```
---
name: api-design
description: REST API 设计最佳实践与规范
---

# API 设计规范
设计REST API时，需遵循以下规范...
```
1
2
3
4
5
6
7
注意：配置中的name字段必须与 Skill 目录名称完全一致。
重启命令行工具会话，新添加的 Skill 即可加载生效。

自定义命令

通过自定义命令，可创建可复用的斜杠命令，执行含参数替换的预定义提示词，便捷简化重复任务，实现工作流标准化。

自定义命令的加载路径分为以下两类：

全局命令：~/.vjsp/commands/（所有项目均可调用）
项目专属命令：.vjsp/commands/（仅当前项目可调用）

自定义命令为简易的 Markdown 文件，文件头部通过 YAML 配置信息定义命令属性。

创建自定义命令

创建命令存放目录：

bash

mkdir -p ~/.vjsp/commands # Windows 系统执行：mkdir %USERPROFILE%\.vjsp\commands

在该目录下创建Markdown文件（示例：component.md）：

markdown

---
description: 创建新的React组件
arguments:
    - ComponentName
---

创建名为$1的React组件，需包含以下内容：
- 规范的TypeScript类型定义
- 基础的组件结构
- 组件导出语句
- 必要时定义简易的属性接口（props interface）

根据项目目录结构，将组件文件存放至对应目录。

在命令行工具会话中调用该自定义命令：
bash
```
/component Button
```
1

YAML 配置项说明

自定义命令支持以下 YAML 头部配置项：

description（可选）：命令描述，将在/help命令中展示
arguments（可选）：命令参数列表，用于生成文档说明
mode（可选）：运行该命令时，自动切换至指定的工具运行模式
model（可选）：运行该命令时，自动切换至指定的大语言模型

参数替换规则

自定义命令支持灵活的参数替换能力，规则如下：

$ARGUMENTS：将所有传入参数以空格拼接后替换
$1, $2, $3 等：按位置匹配单个传入参数，依次替换

参数替换示例：

markdown

---
description: 创建指定内容的文件
arguments:
    - filename
    - content
---

创建名为$1的新文件，文件内容如下：
$2

调用方式：/createfile app.ts "console.log('Hello')"

自动切换模式与模型

自定义命令可配置为运行时自动切换工具模式与大语言模型，示例如下：

markdown

---
description: 执行带覆盖率统计的测试
mode: code
model: anthropic/claude-3-5-sonnet-20241022
---

执行完整的测试套件并生成覆盖率报告，展示所有测试失败的用例。
聚焦失败用例，给出具体的修复建议。

调用/test命令时，工具将自动切换至代码开发模式，并使用配置中指定的大语言模型。

自定义命令示例

初始化项目文档：

markdown

---
description: 分析代码库并生成AGENTS.md文档
mode: code
---

请分析当前代码库，生成AGENTS.md文档，文档需包含以下内容：
1. 构建、代码检查、测试相关命令——重点是单测运行命令
2. 代码风格规范，包括导入规则、格式化要求、类型定义、命名规范

聚焦通过读取项目文件发现的、项目专属的特殊规范与非通用信息。

代码重构：

markdown

---
description: 重构代码以提升代码质量
arguments:
    - filepath
---

对文件$1进行重构，重点优化以下维度：
- 代码可读性
- 运行性能
- 可维护性
- 类型安全性

详细说明所做的修改内容，以及修改对代码质量的提升作用。

命令优先级规则

项目专属命令会覆盖同名的全局命令，支持为单个项目自定义命令行为，同时保留全局层面的默认通用配置。

检查点管理

VJSP 在工作过程中会自动创建检查点，支持将项目恢复至历史任意状态。

查看检查点

执行/checkpoint list命令，列出所有可用的检查点：

bash

/checkpoint list

命令将展示以下信息：

40位完整的 Git 提交哈希值
相对时间戳（如：5分钟前、2小时前）
自动保存的检查点将标注[auto-saved]

恢复至检查点

通过完整的Git哈希值，将项目恢复至指定检查点：

bash

/checkpoint restore 00d185d5020969752bc9ae40823b9d6a723696e2

⚠️ 警告

检查点恢复为破坏性操作，执行后将产生以下影响：

执行 Git 硬重置，所有未提交的修改将全部丢失
删除该检查点之后的所有对话记录
操作执行后无法撤销

恢复前，请确保已提交或备份所有需要保留的工作内容。

命令别名：可使用/cp作为/checkpoint的简写命令

任务历史管理

可在命令行工具中直接查看、检索、翻阅任务历史记录。

查看任务历史

执行/tasks命令，展示任务历史记录：

bash

/tasks

命令将展示以下信息：

任务编号与任务描述
任务ID（用于任务切换）
相对时间戳
Token 使用量
收藏任务标记（⭐）
分页标识（每页展示10条任务）

检索任务

根据关键词检索指定任务：

bash

/tasks search bug fix
/tasks search implement feature

检索结果将自动按相关性排序。

切换任务

通过任务ID切换至指定任务：

bash

/tasks select abc123

命令将加载该任务的完整对话历史记录，恢复任务上下文。

分页翻阅

翻阅任务历史记录的不同页码：

bash

/tasks page 2      # 跳转至第2页
/tasks next        # 翻至下一页
/tasks prev        # 翻至上一页

任务排序

按不同维度对任务历史记录进行排序：

bash

/tasks sort newest          # 按创建时间从新到旧（默认规则）
/tasks sort oldest          # 按创建时间从旧到新
/tasks sort most-tokens     # 按令牌使用量从多到少
/tasks sort most-relevant   # 按相关性排序（仅检索时生效）

任务筛选

按工作区或收藏状态筛选任务：

bash

/tasks filter current    # 仅展示当前工作区的任务
/tasks filter all        # 展示所有工作区的任务
/tasks filter favorites  # 仅展示收藏的任务
/tasks filter all-tasks  # 展示所有任务（清除筛选条件）

命令别名：可使用/t和/history作为/tasks的简写命令

模型提供商配置参考

VJSP 支持为大语言模型提供商与AI网关配置自有密钥，不同提供商的配置项各有差异。

若需手动编辑配置文件，可执行以下命令：

bash

vjsp config

通过命令行的交互式流程完成配置。

💡 提示

也可在交互式会话中执行/config斜杠命令，与vjsp config命令功能一致。

并行模式

并行模式支持在同一目录下启动多个 VJSP 实例，并行处理任务且无冲突，可按需启动任意数量的实例！任务完成后，所有修改将同步至独立的 Git 分支。

bash

# 前提条件：当前目录需为有效的 Git 仓库

# 交互式模式下，退出时将自动提交分支修改
# 终端1
vjsp --parallel "improve xyz"
# 终端2
vjsp --parallel "improve abc"

# 与自动模式搭配使用，效率更高 🚀
# 终端1
vjsp --parallel --auto "improve xyz"
# 终端2
vjsp --parallel --auto "improve abc"

自动批准配置

开启自动批准功能后，VJSP 命令行工具执行操作时无需用户手动确认。该配置可在交互式模式中逐步配置，也可通过vjsp config命令或直接编辑配置文件~/.vjsp/config.json完成设置。

默认自动批准配置

json

{
	"autoApproval": {
		"enabled": true,
		"read": {
			"enabled": true,
			"outside": false
		},
		"write": {
			"enabled": true,
			"outside": false,
			"protected": false
		},
		"execute": {
			"enabled": true,
			"allowed": ["npm", "git", "pnpm"],
			"denied": ["rm -rf", "sudo"]
		},
		"browser": {
			"enabled": false
		},
		"mcp": {
			"enabled": true
		},
		"mode": {
			"enabled": true
		},
		"subtasks": {
			"enabled": true
		},
		"question": {
			"enabled": false,
			"timeout": 60
		},
		"retry": {
			"enabled": true,
			"delay": 10
		},
		"todo": {
			"enabled": true
		}
	}
}

配置项说明：

read：文件读取操作的自动批准配置
- outside：是否允许读取工作区外的文件
write：文件写入操作的自动批准配置
- outside：是否允许写入文件至工作区外
- protected：是否允许修改受保护文件（如package.json）
execute：命令执行操作的自动批准配置
- allowed：允许执行的命令匹配规则列表（如["npm", "git"]）
- denied：禁止执行的命令匹配规则列表（优先级高于允许规则）
browser：浏览器操作的自动批准配置
mcp：MCP工具调用的自动批准配置
mode：工具模式切换的自动批准配置
subtasks：子任务创建的自动批准配置
question：后续问题回复的自动批准配置
retry：API 请求重试的自动批准配置
todo：待办列表更新的自动批准配置

命令批准匹配规则

execute.allowed与execute.denied列表支持层级化的命令匹配规则，规则如下：

基础命令："git" 匹配所有git子命令（如git status、git commit、git push）
命令+子命令："git status" 匹配所有 git status 相关命令（如git status --short、git status -v）
完整命令："git status --short" 仅匹配该精确命令

匹配规则示例：

json

{
	"execute": {
		"enabled": true,
		"allowed": [
			"npm", // 允许所有 npm 命令
			"git status", // 允许所有 git status 相关命令
			"ls -la" // 仅允许精确执行"ls -la"命令
		],
		"denied": [
			"git push --force" // 即使允许 git 命令，仍禁止该精确命令
		]
	}
}

交互式模式

未添加--auto参数运行 VJSP 时，默认进入交互式模式，该模式专为用户与工具的控制台交互式协作设计。

交互式模式下，工具执行未配置自动批准的操作时，将向用户发起批准请求，用户可先审核操作内容再确认执行，也可选择将该操作添加至自动批准列表。

交互式命令批准

交互式模式下，命令批准请求将展示层级化的操作选项，示例如下：

[!] 需手动确认操作：
> ✓ 执行命令 (y)
  ✓ 始终允许执行所有git命令 (1)
  ✓ 始终允许执行git status相关命令 (2)
  ✓ 始终允许执行git status --short --branch精确命令 (3)
  ✗ 拒绝执行 (n)

选择任意「始终允许」选项后，将执行以下操作：

批准并执行当前命令
将该命令的匹配规则添加至配置文件的execute.allowed列表
后续匹配该规则的命令将自动批准执行

通过该方式，无需手动编辑配置文件，即可逐步完善自动批准规则。

自主模式（非交互式）

自主模式支持 VJSP 在 CI/CD 流水线等自动化环境中运行，无需人工交互。

bash

# 以自主模式运行，并传入任务提示词
vjsp --auto "Implement feature X"

# 以自主模式运行，通过管道传入任务提示词
echo "Fix the bug in app.ts" | vjsp --auto

# 以自主模式运行，设置超时时间（单位：秒）
vjsp --auto "Run tests" --timeout 300

# 以自主模式运行，输出JSON格式结果（便于结构化解析）
vjsp --auto --json "Implement feature X"

自主模式运行特性

添加--auto参数进入自主模式后，工具将呈现以下特性：

无人工交互：所有操作批准请求均根据配置自动处理
自动批准/拒绝：根据自动批准配置，自动判定操作是否允许执行
后续问题自动响应：工具将自动向AI发送指令，要求其自主决策回复后续问题
任务完成自动退出：任务完成或超时后，命令行工具将自动退出

JSON输出模式

搭配使用--json与--auto参数，工具将输出结构化的 JSON 格式结果，替代默认的终端交互界面，适用于工具的程序化集成与结果解析。

bash

# 标准自主模式，展示终端交互界面
vjsp --auto "Fix the bug"

# 自主模式，输出JSON格式结果
vjsp --auto --json "Fix the bug"

# 结合管道输入，输出JSON格式结果
echo "Implement feature X" | vjsp --auto --json

使用要求：

--json参数必须与--auto参数搭配使用
结果将输出至标准输出流（stdout），为结构化 JSON 格式，便于解析
适用于 CI/CD 流水线与各类自动化工作流

自主模式的自动批准规则

自主模式将严格遵循自动批准配置，未配置自动批准的操作将被禁止执行。

自主模式的后续问题处理

自主模式下，当 AI 发起后续问题时，工具将自动发送以下响应指令：

"当前流程运行于非交互式自主模式，用户无法参与决策，请自主完成决策并继续执行。"

该指令将引导 AI 在无人工输入的情况下，自主推进任务。

退出码说明

0：执行成功（任务完成）
124：执行超时（任务超出设定的时间限制）
1：执行失败（工具初始化或任务执行过程中出现错误）

CI/CD集成示例

yaml

# GitHub Actions 集成示例
- name: 运行VJSP
  run: |
      echo "Implement the new feature" | vjsp --auto --timeout 600

会话续传

使用--continue（或简写-c）参数，恢复当前工作区的上一次对话会话：

bash

# 恢复当前工作区的最近一次任务
vjsp --continue
vjsp -c

该功能特性如下：

自动识别当前工作区的最近一次任务
加载该任务的完整对话历史记录
支持从任务中断处继续执行
不可与--auto模式或任务提示词参数同时使用
若当前工作区无历史任务，将抛出错误并退出

工作流示例：

bash

# 启动新任务
vjsp
# > 输入任务提示词："Create a REST API"
# ... 执行任务操作 ...
# 执行/exit命令退出工具

# 后续需继续完成该任务时
vjsp --continue
# 工具将恢复对话历史，可直接继续执行任务

使用限制：

不可与--auto模式搭配使用
不可与任务提示词参数同时使用
仅当前工作区存在历史任务时生效

VJSP AI Code 命令行工具（CLI） ​

安装 ​

升级 ​

VJSP 命令行工具核心能力 ​

命令行工具参考手册 ​

键盘快捷键 ​

内置命令 ​

Skills ​

新增 Skill ​

自定义命令 ​

创建自定义命令 ​

YAML 配置项说明 ​

参数替换规则 ​

自动切换模式与模型 ​

自定义命令示例 ​

命令优先级规则 ​

检查点管理 ​

查看检查点 ​

恢复至检查点 ​

任务历史管理 ​

查看任务历史 ​

检索任务 ​

切换任务 ​

分页翻阅 ​

任务排序 ​

任务筛选 ​

模型提供商配置参考 ​

并行模式 ​

自动批准配置 ​

默认自动批准配置 ​

命令批准匹配规则 ​

交互式模式 ​

交互式命令批准 ​

自主模式（非交互式） ​

自主模式运行特性 ​

JSON输出模式 ​

自主模式的自动批准规则 ​

自主模式的后续问题处理 ​

退出码说明 ​

CI/CD集成示例 ​

会话续传 ​

VJSP AI Code 命令行工具（CLI）

安装

升级

VJSP 命令行工具核心能力

命令行工具参考手册

键盘快捷键

内置命令

Skills

新增 Skill

自定义命令

创建自定义命令

YAML 配置项说明

参数替换规则

自动切换模式与模型

自定义命令示例

命令优先级规则

检查点管理

查看检查点

恢复至检查点

任务历史管理

查看任务历史

检索任务

切换任务

分页翻阅

任务排序

任务筛选

模型提供商配置参考

并行模式

自动批准配置

默认自动批准配置

命令批准匹配规则

交互式模式

交互式命令批准

自主模式（非交互式）

自主模式运行特性

JSON输出模式

自主模式的自动批准规则

自主模式的后续问题处理

退出码说明

CI/CD集成示例

会话续传