自定义模式

VJSP 支持创建自定义模式，可根据特定任务或工作流定制 VJSP 的行为。自定义模式分为两种类型：全局模式（可在所有项目中使用）和项目专属模式（仅在当前项目内生效）。

粘性模型：优化工作流效率

所有模式（包括自定义模式）均内置粘性模型功能。这意味着 VJSP 会自动记忆并选中你在某一特定模式下使用的最后一个模型，你可为不同任务配置专属偏好模型，切换模式时，VJSP 会自动匹配对应模型，无需反复重新配置。

自定义模式的核心价值

专业化定制 ：创建针对特定任务的优化模式，例如「文档撰写师」「测试工程师」或「重构专家」。
安全性管控 ：限制模式对敏感文件或指令的访问权限。例如，「代码评审模式」可被配置为只读操作，杜绝误修改风险。
实验性验证 ：在不影响其他模式的前提下，安全地测试不同的提示词与配置组合。

以下介绍 VJSP 中创建和管理自定义模式的操作界面。

自定义模式的核心配置项

自定义模式由多项核心属性定义，理解这些概念可精准定制 VJSP 的行为逻辑。

界面字段 / YAML 配置项	功能概念描述
唯一标识（`slug`）	模式的唯一内部标识符。VJSP 通过该字段识别模式，尤其用于关联模式专属的指令文件。
模式名称（`name`）	模式在 VJSP 用户界面中显示的名称。需具备可读性且表意清晰。
模式描述（`description`）	用于简述模式用途的用户友好型文本，展示在模式选择器界面中。建议简洁明确，突出模式的核心功能。
角色定义（`roleDefinition`）	定义模式的核心身份与专业能力。该文本会被插入到系统提示词的开头，决定 VJSP 在该模式下的行为风格与能力定位。
可用工具集（`groups`）	定义模式允许调用的工具集与文件访问权限，对应工具分类的勾选配置。
适用场景（`whenToUse`）	（可选）为 VJSP 的自动化决策提供依据，尤其适用于模式选择与任务编排，供任务协调器模式调用。
自定义指令（`customInstructions`）	（可选）模式的专属行为准则，嵌入系统提示词末尾，进一步优化 VJSP 运行逻辑。

模式的导入与导出

支持自定义模式的共享、备份与模板化管理。可将任意模式及其关联规则导出为独立可移植的 YAML 文件，并导入至任意项目中使用。

核心功能亮点

配置共享 ：将模式及其配套规则打包为单一文件，轻松实现团队内共享。
便捷备份 ：保存自定义模式的配置信息，避免配置丢失。
项目模板 ：为不同类型的项目创建标准化的模式模板。
灵活迁移 ：轻松在全局配置与项目配置间迁移模式。
标识灵活修改 ：修改导出文件中的模式标识时，无需手动编辑路径

操作流程

模式导出

进入模式配置界面
选中需要导出的目标模式
点击导出模式按钮
选择文件保存路径
VJSP 会将模式的配置信息及关联规则打包为 YAML 文件

模式导入

在模式配置界面点击导入模式按钮
选择待导入的模式 YAML 文件
选择导入级别
- 项目级别： 仅在当前工作区生效（配置保存至 .vjspmodes 文件）
- 全局级别： 在所有项目中生效（配置保存至全局设置）

导入时修改标识

导出模式后，可在 YAML 文件中修改模式标识，再执行导入操作：

导出一个 slug 为 original-mode 的模式
编辑 YAML 文件，将 slug 修改为 new-mode
导入文件，系统会自动更新规则文件路径，适配新标识

自定义模式的创建与配置方法

创建和配置自定义模式有以下三种方式：

方法一：智能生成（推荐）

你可以直接向 VJSP 发送指令，快速创建基础自定义模式。示例指令如下：

创建一个名为「DocumentationWriter」的新模式，仅授予文件读取权限与 Markdown 文件写入权限。

VJSP 会引导用户补充必要信息，并以 YAML 格式生成模式配置。

方法二：提示词标签页配置

打开“模式配置”标签页：点击设置按钮，进入“模式配置”标签页
创建新模式：点击模式标题右侧的新建按钮
填写配置字段：

自定义模式创建界面包含名称、标识、保存位置、描述、角色定义、使用场景（可选）、可用工具集、自定义指令等配置项。填写完成后点击创建模式按钮，系统自动以 YAML 格式保存配置。

方法三：手动配置（YAML 与 JSON 格式）

直接编辑配置文件创建或修改自定义模式，支持最大程度的自定义控制，兼容 YAML（推荐）与 JSON 两种格式。

全局模式：编辑 custom_modes.yaml（推荐）或 custom_modes.json 文件。
项目模式：编辑项目根目录下的 .vjspmodes 文件（支持 YAML 或 JSON 格式）。

上述文件均以数组 / 列表结构定义多个自定义模式。

YAML 配置格式（推荐）

YAML 凭借良好的可读性、注释支持和简洁的多行文本语法，成为定义自定义模式的推荐格式。

YAML 示例

yaml

customModes:
  - slug: docs-writer
    name: docs-writer
    description: 专注于技术文档编写与编辑的专业化模式
    roleDefinition: 你是一名擅长撰写清晰规范技术文档的专业写手
    whenToUse: 适用于技术文档的编写与编辑场景
    customInstructions: 撰写文档时需注重内容的清晰性与完整性
    groups:
      - read
      - - edit  # 元组的第一个元素：工具类型
        - fileRegex: \.(md|mdx)$  # 元组的第二个元素：配置对象
          description: 仅支持 Markdown 文件
      - browser
  - slug: another-mode
    name: 其他模式
    # ... 其他配置项

JSON 备选格式

json

{
  "customModes": [
    {
      "slug": "docs-writer",
      "name": "docs-writer",
      "description": "专注于技术文档编写与编辑的专业化模式",
      "roleDefinition": "你是一名擅长撰写清晰规范技术文档的专业写手",
      "whenToUse": "适用于技术文档的编写与编辑场景",
      "customInstructions": "撰写文档时需注重内容的清晰性与完整性",
      "groups": [
        "read",
        ["edit", {"fileRegex": "\\.(md|mdx)$", "description": "仅支持 Markdown 文件"}],
        "browser"
      ]
    }
  ]
}

YAML/JSON 配置项详细说明

`slug`（唯一标识）

用途：模式的唯一标识符
格式要求：必须匹配正则表达式 /^[a-zA-Z0-9-]+$/（仅允许字母、数字和连字符）
使用场景：内部标识，用于命名模式专属规则的文件 / 目录（例如 .vjsp/rules-{slug}/）
配置建议：简洁且表意明确

示例：YAML → slug: docs-writer；JSON → "slug": "docs-writer"

`name`（模式名称）

用途：在 VJSP 界面显示的名称
格式要求：可包含空格与标准大小写格式

示例：YAML → name: DocumentationWriter；JSON → "name": "DocumentationWriter"

`description`（模式描述）

用途：简短的用户友好型描述，展示在模式选择器中
格式要求：简洁精炼，突出模式核心功能
界面展示：该文本将显示在经过重新设计的模式选择器中

示例：YAML → description: 专注于技术文档编写与编辑的专业化模式；JSON → "description": "专注于技术文档编写与编辑的专业化模式"

`roleDefinition`（角色定义）

用途：详细定义模式的角色定位、专业能力与行为风格
生效位置：该文本会被插入到系统提示词的开头

多行文本示例（YAML）

yaml

roleDefinition: >-
  你是一名资深测试工程师，精通以下技能：
  - 编写全面的测试套件
  - 践行测试驱动开发（TDD）流程

单行文本示例（JSON）

json

"roleDefinition": "你是一名擅长撰写清晰规范技术文档的专业写手"

`groups`（可用工具集）

用途：通过数组定义模式可访问的工具组及文件访问限制
支持的工具组：read（读取）、edit（编辑）、browser（浏览）、command（命令执行）、mcp（多智能体协作）
结构说明
- 无限制访问：直接使用字符串（例如 "edit"）
- 受限访问：使用二元元组，格式为 ["工具类型", {配置项}]
edit 工具组的文件限制配置
- fileRegex：正则表达式字符串，用于控制模式可编辑的文件类型
  - YAML 格式：正则特殊字符使用单个反斜杠（例如 \.md$）
  - JSON 格式：反斜杠需双重转义（例如 \\.md$）
- description：可选字段，用于描述限制规则

YAML 配置示例

yaml

groups:
  - read
  - - edit
    - fileRegex: \.(js|ts)$
      description: 仅支持 JS/TS 文件
  - command

JSON 配置示例

json

"groups": [
  "read",
  ["edit", {"fileRegex": "\\.(js|ts)$", "description": "仅支持 JS/TS 文件"}],
  "command"
]

`whenToUse`（适用场景）（可选）

用途：为 VJSP 的自动化决策提供指导，主要用于模式自动选择与任务编排
格式要求：字符串，描述模式的理想适用场景或任务类型
使用场景：供 VJSP 内部调用，不显示在界面中

示例：YAML → whenToUse: 该模式适用于 Python 代码重构场景；JSON → "whenToUse": "该模式适用于 Python 代码重构场景"

`customInstructions`（自定义指令）（可选）

用途：定义模式的额外行为准则
生效位置：该文本会被添加到系统提示词的末尾

多行文本示例（YAML）

yaml

customInstructions: |-
  编写测试代码时需遵循以下规范：
  - 使用 describe/it 代码块组织测试用例
  - 为测试用例添加表意明确的描述信息

单行文本示例（JSON）

json

"customInstructions": "撰写文档时需注重概念阐释与示例补充"

YAML 格式的优势

YAML 成为自定义模式推荐格式的核心优势如下：

可读性强：基于缩进的层级结构更符合人类阅读习惯
支持注释：允许通过 # 开头的行添加注释，便于为模式配置添加说明
多行字符串优化：通过 |（字面量块）或 >（折叠块）语法，轻松实现简洁的多行文本配置
语法简洁：相比 JSON 减少了大量标点符号，降低语法错误概率
编辑器兼容性佳：主流代码编辑器均提供完善的 YAML 语法高亮与校验功能

JSON 格式仍被完全支持，但通过界面或智能生成创建的新模式，默认采用 YAML 格式。

向 YAML 格式迁移

全局模式

当满足以下条件时，custom_modes.json 会自动迁移为 custom_modes.yaml：

VJSP 启动时
存在 custom_modes.json 文件
尚未创建 custom_modes.yaml 文件

迁移过程中会保留原始 JSON 文件，以便必要时回滚。

项目模式（.vjspmodes 文件）

项目专属配置文件不会在启动时自动迁移
VJSP 可同时读取 YAML 或 JSON 格式的 .vjspmodes 文件
通过界面编辑 JSON 格式文件时，会自动转换为 YAML 格式
手动转换时，可直接向 VJSP 发送指令，请求协助完成配置格式重构

通过文件 / 目录配置模式专属指令

可通过工作区内的专属文件或目录为自定义模式配置指令，实现配置的规范化管理与版本控制。

推荐方法：目录配置（`.vjsp/rules-{mode-slug}/`）

plaintext

.
├── .vjsp/
│   └── rules-docs-writer/  # 示例：对应 slug 为 "docs-writer" 的模式
│       ├── 01-style-guide.md
│       └── 02-formatting.txt
└── ... (其他项目文件)

备选方法：单一文件配置（.vjsprules-{mode-slug}）

plaintext

.
├── .vjsprules-docs-writer  # 示例：对应 slug 为 "docs-writer" 的模式
└── ... (其他项目文件)

规则目录的作用域

全局模式：规则文件存储在 ~/.vjsp/rules-{slug}/ 目录下
项目模式：规则文件存储在 {workspace}/.vjsp/rules-{slug}/ 目录下

优先级规则：若目录配置与文件配置同时存在，目录配置优先生效。目录内的文件会被递归读取，并按字母顺序拼接生效。

配置优先级规则

模式配置的生效优先级从高到低依次为：

项目级别模式配置
全局级别模式配置
默认模式配置

重要提示：当 .vjspmodes 文件与全局设置中存在相同 slug 的模式时，项目级别配置会完全覆盖全局级别配置的所有属性。

覆盖默认模式

创建与 VJSP 内置模式标识（slug）相同的自定义模式，即可覆盖内置模式的配置。

全局覆盖示例

yaml

customModes:
  - slug: code  # 与默认「代码模式」的 slug 一致
    name: CodeGlobal
    roleDefinition: 你是一名具备全局配置约束的软件工程师
    whenToUse: 该全局覆盖版代码模式适用于 JS/TS 开发任务
    customInstructions: 专注于项目专属的 JS/TS 开发工作
    groups:
      - read
      - - edit
        - fileRegex: \.(js|ts)$
          description: 仅支持 JS/TS 文件

项目专属覆盖示例

yaml

customModes:
  - slug: code  # 与默认「代码模式」的 slug 一致
    name: CodeProject
    roleDefinition: 你是一名适配本项目需求的软件工程师
    whenToUse: 该项目专属代码模式适用于本项目的 Python 开发任务
    customInstructions: 代码需严格遵循 PEP8 规范并添加类型注解
    groups:
      - read
      - - edit
        - fileRegex: \.py$
          description: 仅支持 Python 文件
      - command

自定义模式中的正则表达式使用指南

正则表达式（fileRegex 配置项）可实现对文件编辑权限的精细化管控。

💡 提示

让 VJSP 帮你生成正则表达式

无需手动编写复杂正则，可直接向 VJSP 发送指令。

生成一个匹配 JavaScript 文件但排除测试文件的正则表达式

生成后，需根据 YAML/JSON 格式要求调整转义字符（YAML 用单反斜杠，JSON 用双反斜杠）。

`fileRegex` 核心规则

JSON 格式转义要求：字符串中的反斜杠（\）需双重转义（例如 \\.md$）
YAML 格式转义要求：非引号包裹的字符串中，正则特殊字符使用单反斜杠即可（例如 \.md$）
路径匹配规则：正则表达式匹配的是相对于工作区根目录的完整文件路径
大小写敏感性：默认区分大小写
有效性校验：无效正则表达式会触发「无效正则表达式模式」错误提示

常用正则表达式示例

YAML 格式表达式	JSON 格式表达式	匹配范围	排除范围
`\.md$`	`"\\.md$"`	`readme.md`、`docs/guide.md`	`script.js`、`readme.md.bak`
`^src/.*`	`"^src/.*"`	`src/app.js`、`src/components/button.tsx`	`lib/utils.js`、`test/src/mock.js`
`\.(css scss)$`	`"\\.(css scss)$"`	`styles.css`、`theme.scss`	`styles.less`、`styles.css.map`
`docs/.*\.md$`	`"docs/.*\\.md$"`	`docs/guide.md`、`docs/api/reference.md`	`guide.md`、`src/docs/notes.md`
`^(?!.*(test spec))\.(js ts)$`	`"^(?!.*(test spec))\\.(js ts)$"`	`app.js`、`utils.ts`	`app.test.js`、`utils.spec.js`

正则表达式核心语法说明

\.：匹配一个字面量句点（YAML 格式：\.；JSON 格式：\\.）
$：匹配字符串的末尾
^：匹配字符串的开头
.*：匹配任意字符（换行符除外）零次或多次
(a|b)：匹配 a 或 b
(?!...)：负向预查，排除匹配内容

错误处理机制

当模式尝试编辑不符合 fileRegex 规则的文件时，系统会抛出 FileRestrictionError 错误，错误信息包含以下内容：

模式名称
允许的文件匹配规则
规则描述（若配置）
尝试访问的文件路径
被拦截的工具类型

配置示例

基础版「文档撰写师」模式（YAML）

yaml

customModes:
  - slug: docs-writer
    name: 📝 文档撰写师
    description: 专注于技术文档编写与编辑
    roleDefinition: 你是一名擅长撰写清晰规范技术文档的专业技术写手
    groups:
      - read
      - - edit
        - fileRegex: \.md$
          description: 仅支持 Markdown 文件
    customInstructions: 撰写文档时需注重内容的清晰性与示例的实用性

带文件限制的「测试工程师」模式（YAML）

yaml

customModes:
  - slug: test-engineer
    name: 🧪 测试工程师
    description: 专注于测试套件的编写与维护
    roleDefinition: 你是一名专注于代码质量保障的测试工程师
    whenToUse: 适用于测试用例编写、测试失败调试、测试覆盖率优化场景
    groups:
      - read
      - - edit
        - fileRegex: \.(test|spec)\.(js|ts)$
          description: 仅支持测试文件
      - command

「安全评审」模式（YAML）

yaml

customModes:
  - slug: security-review
    name: 🔒 安全评审专家
    description: 只读模式下的代码安全分析与漏洞评估
    roleDefinition: 你是一名专注于代码漏洞检测的安全专家
    whenToUse: 适用于代码安全评审与漏洞评估场景
    customInstructions: |-
      评审时需重点关注以下风险点：
      - 输入验证缺陷
      - 认证与授权漏洞
      - 数据泄露风险
      - 注入攻击隐患
    groups:
      - read
      - browser

故障排查

常见问题

模式未显示：创建或导入模式后，需重启 IDE 窗口使其生效
正则表达式无效：使用在线正则测试工具验证表达式有效性后再配置
优先级混淆：牢记同标识的项目模式会完全覆盖全局模式
YAML 语法错误：使用空格（而非制表符）缩进，并通过工具校验语法正确性

YAML 配置技巧

缩进是核心：YAML 依赖缩进（空格）定义层级结构
键值对格式：键名后必须紧跟冒号与空格（例如 slug: my-mode）
列表项格式：列表项以连字符加空格开头（例如 - read）
语法校验：使用在线 YAML 校验工具或编辑器内置校验功能

自定义模式 ​

粘性模型：优化工作流效率 ​

自定义模式的核心价值 ​

自定义模式的核心配置项 ​

模式的导入与导出 ​

核心功能亮点 ​

操作流程 ​

导入时修改标识 ​

自定义模式的创建与配置方法 ​

方法一：智能生成（推荐） ​

方法二：提示词标签页配置 ​

方法三：手动配置（YAML 与 JSON 格式） ​

YAML 配置格式（推荐） ​

YAML 示例 ​

JSON 备选格式 ​

YAML/JSON 配置项详细说明 ​

slug（唯一标识） ​

name（模式名称） ​

description（模式描述） ​

roleDefinition（角色定义） ​

groups（可用工具集） ​

whenToUse（适用场景）（可选） ​

customInstructions（自定义指令）（可选） ​

YAML 格式的优势 ​

向 YAML 格式迁移 ​

全局模式 ​

项目模式（.vjspmodes 文件） ​

通过文件 / 目录配置模式专属指令 ​

推荐方法：目录配置（.vjsp/rules-{mode-slug}/） ​

备选方法：单一文件配置（.vjsprules-{mode-slug}） ​

规则目录的作用域 ​

配置优先级规则 ​

覆盖默认模式 ​

全局覆盖示例 ​

项目专属覆盖示例 ​

自定义模式中的正则表达式使用指南 ​

fileRegex 核心规则 ​

常用正则表达式示例 ​

正则表达式核心语法说明 ​

错误处理机制 ​

配置示例 ​

基础版「文档撰写师」模式（YAML） ​

带文件限制的「测试工程师」模式（YAML） ​

「安全评审」模式（YAML） ​

故障排查 ​

常见问题 ​

YAML 配置技巧 ​

自定义模式

粘性模型：优化工作流效率

自定义模式的核心价值

自定义模式的核心配置项

模式的导入与导出

核心功能亮点

操作流程

导入时修改标识

自定义模式的创建与配置方法

方法一：智能生成（推荐）

方法二：提示词标签页配置

方法三：手动配置（YAML 与 JSON 格式）

YAML 配置格式（推荐）

YAML 示例

JSON 备选格式

YAML/JSON 配置项详细说明

`slug`（唯一标识）

`name`（模式名称）

`description`（模式描述）

`roleDefinition`（角色定义）

`groups`（可用工具集）

`whenToUse`（适用场景）（可选）

`customInstructions`（自定义指令）（可选）

YAML 格式的优势

向 YAML 格式迁移

全局模式

项目模式（.vjspmodes 文件）

通过文件 / 目录配置模式专属指令

推荐方法：目录配置（`.vjsp/rules-{mode-slug}/`）

备选方法：单一文件配置（.vjsprules-{mode-slug}）

规则目录的作用域

配置优先级规则

覆盖默认模式

全局覆盖示例

项目专属覆盖示例

自定义模式中的正则表达式使用指南

`fileRegex` 核心规则

常用正则表达式示例

正则表达式核心语法说明

错误处理机制

配置示例

基础版「文档撰写师」模式（YAML）

带文件限制的「测试工程师」模式（YAML）

「安全评审」模式（YAML）

故障排查

常见问题

YAML 配置技巧