Configuration.zh

配置

VCP 通过项目根目录中的 .vcp/config.json 文件进行配置。该文件由 /vcp-init 创建，供所有 VCP skill 和 hook 读取。

使用 /vcp-config 可通过自然语言命令查看和修改配置（例如 /vcp-config ignore core-architecture、/vcp-config enable database scope）。支持的完整命令列表请参阅 Skills Reference.zh。

全局配置

VCP 支持在 ~/.vcp/config.json 中设置全局配置，提供机器级常量和默认值。该文件在首次运行 /vcp-init 时创建。

文件位置

~/.vcp/config.json

Schema

https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp-global.schema.json

字段 (Fields)

standards_url（必填）

VCP 标准清单的 URL，指向根 manifest.json 文件。

"standards_url": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/standards/manifest.json"

pluginRoot（必填）

VCP 插件安装目录的绝对路径。

"pluginRoot": "/home/user/.claude/plugins/vcp"

debug（可选）

启用诊断日志，输出到项目根目录的 .vcp/vcp.log 文件。设为 true 时，所有 hook 会写入带时间戳的日志条目，记录检查内容和决策结果。设为 false（默认值）时不生成日志文件。

"debug": false

使用 /vcp-config global set debug true 启用，或直接编辑 ~/.vcp/config.json。

defaults（可选）

机器级默认值。运行时只应用 severity 和 ignore —— 项目未指定 severity 时使用全局默认值，ignore 条目与项目列表合并（取并集）。scopes 和 compliance 默认值仅在 /vcp-init 创建新项目配置时作为起始点使用，运行时不会应用，因为两者在 .vcp/config.json 中都是必填字段。

"defaults": {
  "severity": "medium",
  "scopes": {
    "web-frontend": false,
    "web-backend": false,
    "database": false
  },
  "compliance": [],
  "ignore": []
}

完整示例

{
  "$schema": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp-global.schema.json",
  "standards_url": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/standards/manifest.json",
  "pluginRoot": "/home/user/.claude/plugins/vcp",
  "debug": false,
  "defaults": {
    "severity": "high",
    "scopes": {
      "web-frontend": true,
      "web-backend": true,
      "database": false,
      "mobile": false,
      "desktop": false,
      "cli": false,
      "devops": false
    },
    "compliance": ["gdpr"],
    "ignore": ["CWE-117"]
  }
}

配置解析

VCP 从两个来源解析配置：全局配置（~/.vcp/config.json）提供机器级常量和默认值，项目配置（.vcp/config.json）提供项目级覆盖。

字段 (Field)	解析顺序 (Resolution Order)	说明 (Notes)
standards_url	项目 → 全局 → 不可用	项目配置可覆盖全局标准 URL
pluginRoot	项目 → 全局 → 不可用	项目配置优先（由 /vcp-init 设置）
severity	项目 → 全局默认值 → "medium"	两处均未指定时回退到硬编码的 "medium"
scopes	项目完全覆盖	不合并 —— 项目配置完全替换全局默认值
compliance	项目完全覆盖	不合并 —— 项目配置完全替换全局默认值
ignore	全局默认值 + 项目取并集	唯一会合并的字段 —— 合并两个列表

重要： ignore 是唯一会合并的字段。如果全局配置有 ["CWE-117"]，项目配置有 ["core-architecture"]，最终的忽略列表为 ["CWE-117", "core-architecture"]。

Schema

配置遵循以下 JSON schema：

https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp.schema.json

字段 (Fields)

version（必填）

固定为 "1.0"。

"version": "1.0"

standards_url（可选）

VCP 标准清单的 URL。指定后会覆盖全局配置中的 standards_url。

"standards_url": "https://raw.githubusercontent.com/your-fork/vcp/custom-branch/standards/manifest.json"

通常不需要设置。 大多数项目应使用全局配置中的 standards_url，而非按项目单独设置。仅在需要将特定项目固定到自定义标准分支或 fork 时才覆盖此字段。

scopes（必填）

声明项目适用的 VCP 作用域的对象。每个作用域启用核心标准之外的额外标准。

"scopes": {
  "web-frontend": true,
  "web-backend": true,
  "database": false
}

作用域 (Scope)	启用的标准 (Standards Enabled)	适用场景 (When to Use)
web-frontend	前端安全、结构、性能、无障碍访问	项目包含客户端 Web 代码（React、Vue、Svelte 等）
web-backend	后端安全、结构、数据访问、API 设计、实时通信、缓存	项目包含服务端 Web 代码（Express、Django、FastAPI 等）
database	数据库加密、schema 安全	项目直接与数据库交互
mobile	移动安全、平台配置	项目面向移动平台（React Native、Flutter、Swift、Kotlin）
desktop	桌面应用安全	项目构建桌面应用（Electron、Tauri）
cli	CLI 安全与质量	项目是命令行工具
devops	容器、CI/CD、IaC、Kubernetes 安全	项目包含基础设施/部署配置

核心标准（安全、架构、质量、错误处理、测试、依赖管理、根因分析）始终启用，不受作用域设置影响。

compliance（必填）

项目适用的合规框架数组。如不适用任何框架则留空。

"compliance": ["gdpr", "pci-dss"]

值 (Value)	启用的标准 (Standard Enabled)
"gdpr"	GDPR 与 CCPA/CPRA —— 数据删除、留存、同意、PII 处理
"pci-dss"	PCI DSS v4.0 —— 令牌化、卡号脱敏、CDE 隔离
"hipaa"	HIPAA —— PHI 加密、审计日志、留存、最小必要原则
"accessibility"	无障碍合规 —— ADA、Section 508/504、EAA、PSBAR、AODA、ACA、EN 301 549、WCAG 合规映射

frameworks（可选）

项目中检测到的框架名称数组。/vcp-dependency-check 据此确定要检查的包生态系统。

"frameworks": ["react", "express", "postgresql"]

exclude（可选）

扫描时跳过的路径 glob 模式数组。无论此设置如何，node_modules/** 和 .git/** 始终被排除。

"exclude": [
  "node_modules/**",
  "dist/**",
  "build/**",
  "coverage/**",
  "*.min.js"
]

severity（可选）

报告结果的最低严重性阈值。仅包含达到或超过此级别的发现。

"severity": "medium"

值 (Value)	报告内容 (Reports)
"critical"	仅严重
"high"	严重 + 高
"medium"（默认）	严重 + 高 + 中
"low"	所有发现

ignore（可选）

要抑制的条目数组。支持三种格式：

"ignore": [
  "core-architecture",
  "core-security/rule-3",
  "CWE-798"
]

格式 (Format)	示例 (Example)	效果 (Effect)
标准 ID	"core-architecture"	抑制整个标准 —— 该标准的所有规则都不检查
规则引用	"core-security/rule-3"	抑制特定标准中的单条规则
CWE 模式	"CWE-798"	禁用安全门禁中对应 CWE 的实时拦截模式

重要： 当安全相关标准或合规标准被抑制时，skill 会显示警告：

警告：关键安全发现被 ignore 配置抑制。请审查 .vcp/config.json 中的 ignore 列表。

大多数项目应以空的 ignore 列表开始。仅在有明确且合理的理由时才添加条目。

pluginRoot（可选）

VCP 插件安装目录的绝对路径。由 /vcp-init 自动设置 —— 不应手动编辑。

"pluginRoot": "/home/user/.claude/plugins/vcp"

此路径在使用前由所有 skill 验证：

• 必须是绝对路径
• 必须包含 /.claude/（Windows 上为 \.claude\）
• 不得包含 shell 元字符
• 必须包含标记文件 lib/vcp-context-core.ts

完整示例

{
  "$schema": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp.schema.json",
  "version": "1.0",
  "scopes": {
    "web-frontend": true,
    "web-backend": true,
    "database": true
  },
  "compliance": ["gdpr", "pci-dss"],
  "frameworks": ["react", "express", "postgresql", "prisma"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "coverage/**",
    "migrations/**"
  ],
  "severity": "medium",
  "ignore": [
    "core-architecture/rule-5"
  ],
  "pluginRoot": "/home/user/.claude/plugins/vcp"
}

忽略过滤的工作原理

在处理之前，全局配置 defaults.ignore 和项目 .vcp/config.json 中 ignore 字段的条目会被合并（取并集），形成最终的忽略列表。

忽略条目在三个层级被处理：

1. 标准级过滤（在 resolve-config.ts 中）—— 匹配忽略条目的整个标准会在 skill 获取之前从适用标准列表中移除。这意味着该标准的规则根本不会被加载。

2. 规则级过滤（在 skill 和 vcp-context-core.ts 中）—— 类似 "core-security/rule-3" 的单条规则引用在规则提取后被过滤。标准仍会加载，但特定规则被抑制。

3. CWE 级过滤（在 security-gate.ts 中）—— 类似 "CWE-798" 的 CWE 模式会禁用安全门禁 hook 中对应的实时拦截模式。

版本控制

.vcp/config.json 应提交到仓库，以确保所有团队成员使用相同的配置。pluginRoot 字段因机器而异，但会在运行 /vcp-init 时解析。