Skip to content

FAQ.zh

Jump to bottom
Z-M-Huang edited this page Mar 15, 2026 · 8 revisions

常见问题

综合

什么是 VCP？

VCP（Vibe Coding Protocol）是一套原则性标准及 Claude Code 插件，用于对 AI 生成的代码强制执行安全、架构和质量规则。它解决了已知的 AI 代码质量问题——包括漏洞率高出 2.74 倍和代码重复率增加 8 倍。

VCP 适合谁使用？

任何使用 AI 编程助手（目前为 Claude Code）并希望 AI 生成的代码安全、架构良好且易于维护的开发者。VCP 尤其适用于：

  • 大规模采用 AI 编程工具的团队
  • 处理敏感数据的项目（PII、支付信息、医疗记录）
  • 对架构完整性有要求的代码库

VCP 能替代代码审查吗？

不能。VCP 可以捕获常见模式并强制执行标准，但无法替代人工判断。可以将其视为额外的自动化审查层，负责处理重复性检查工作。

安装

如何安装 VCP？

完整指南请参见 Getting Started.zh。简要步骤：

/plugin marketplace add Z-M-Huang/vcp
/plugin install vcp@vcp
/vcp-init

可以在 Docker 中使用 VCP 吗？

可以。VCP 提供开箱即用的 Docker 镜像（zhironghuang/vcp:latest），预装 Claude Code、Codex CLI、Gemini CLI、Bun 及所有依赖。快速开始请参阅 Getting Started.zh § Docker 安装，完整文档请参阅 docker/README.md。

需要安装 Bun 吗？

是的。VCP 的 hooks 是由 Bun 直接执行的 TypeScript 文件。没有 Bun，security gate、context injection 和 stop reminder 等 hooks 将无法工作。Skills（由 AI 驱动）不依赖 Bun，仍可正常运行。如果使用 Docker 镜像，Bun 已预装。

/vcp-init 找不到插件路径怎么办？

/vcp-init 会在 ~/.claude/ 下搜索 VCP 标记文件。如果找不到，它会发出警告并省略 pluginRoot 字段。没有 pluginRoot，扫描类 skills 将无法工作——它们会提示你在插件正确安装后重新运行 /vcp-init。

可以不使用 .vcp/config.json 吗？

部分可以：

  • Security gate 无需配置即可工作（拦截所有模式，不忽略任何 CWE）
  • Context injection 回退为仅加载核心规则
  • 扫描类 skills 会提示你运行 /vcp-init 后停止

如需完整功能，请运行 /vcp-init 创建配置文件。

配置

应该启用哪些 scopes？

启用与项目技术栈匹配的 scopes：

项目使用了... 启用
React、Vue、Svelte 或其他前端框架 web-frontend
Express、Django、FastAPI 或其他服务端框架 web-backend
直接数据库交互（SQL、ORM、迁移） database
React Native、Flutter、Swift 或 Kotlin 移动应用 mobile
Electron 或 Tauri 桌面应用 desktop
CLI 工具（commander、yargs、argparse、click、cobra） cli
Dockerfiles、CI/CD 工作流、Terraform、Kubernetes devops

无论 scope 设置如何，核心标准始终生效。

什么时候需要添加合规框架？

仅当项目必须遵守特定法规时：

  • GDPR — 处理欧盟个人数据
  • PCI DSS — 处理支付卡数据
  • HIPAA — 处理受保护的健康信息

不要"以防万一"就添加合规框架——它们会增加大量可能与项目无关的规则覆盖。

如何屏蔽不适用的规则？

将其添加到 .vcp/config.json 的 ignore 数组中：

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

支持三种格式：

  • 标准 ID："core-architecture" — 屏蔽整个标准
  • 规则引用："core-security/rule-3" — 屏蔽单条规则
  • CWE 模式："CWE-798" — 屏蔽 security gate 模式

详情请参见 Configuration.zh。

应该使用什么严重级别阈值？

默认值 "medium" 适用于大多数项目，它会报告 critical、high 和 medium 级别的发现。

  • 使用 "high" 可减少发现数量，仅保留影响较大的问题
  • 使用 "critical" 仅报告最严重的问题
  • 使用 "low" 可获得最大覆盖范围

Skills

/vcp-audit 和 /vcp-pre-commit-review 有什么区别？

  • /vcp-audit 对指定路径（或整个项目）按所有适用标准进行扫描——用于全面的代码审计
  • /vcp-pre-commit-review 仅对已更改的文件按所有适用标准进行扫描，并给出 PASS/BLOCK 判定

使用 /vcp-audit 进行广泛分析。使用 /vcp-pre-commit-review 作为提交前的最终检查。使用 /vcp-audit quick 进行快速发布就绪检查。

什么时候应该使用 /vcp-context？

在以下情况下运行：

  • 在较长的会话中发现 AI 编写的代码忽略了 VCP 规则
  • 上下文压缩后（当 Claude 对之前的对话进行摘要时）
  • 在同一会话中切换到不同的编码任务时

SessionStart hook 会自动注入上下文，但可能受上游 bug 影响。/vcp-context 是可靠的手动备选方案。

为什么 skills 需要 pluginRoot？

Skills 以 AI 指令（SKILL.md）方式执行，而非代码执行。它们无法直接导入 TypeScript 模块。pluginRoot 字段告诉 skills 在哪里找到共享的 TypeScript 模块（resolve-config.ts、generate-context.ts），以便通过 Bash 调用。

Security Gate

Security gate 拦截了我的代码，怎么办？

拦截消息会告诉你：

  1. 触发了哪个 CWE
  2. 模式检测到了什么
  3. 应该怎么做

常见修复方法：

  • CWE-798（硬编码密钥）： 将密钥移到环境变量中
  • CWE-89（SQL 注入）： 使用参数化查询代替字符串拼接
  • CWE-95（代码注入）： 不要将变量传递给 eval——寻找替代方案
  • CWE-79（XSS）： 使用 .textContent 代替 .innerHTML，或先进行清洗

可以针对特定 CWE 禁用 security gate 吗？

可以，将该 CWE 添加到 .vcp/config.json 的 ignore 列表中：

"ignore": ["CWE-798"]

这会禁用该 CWE 下的所有模式。无法单独禁用某个 CWE 内的特定模式。

Security gate 拦截了合法代码，这是误报吗？

Security gate 使用正则表达式模式匹配，可能产生误报。如果代码确实安全：

  1. 将该特定 CWE 添加到 ignore 列表
  2. 考虑提交 issue 以改进检测模式

扫描类 skills（/vcp-audit）提供更深入的 AI 驱动分析，能更好地理解上下文并区分安全模式和危险模式。

标准

标准是如何加载的？

标准在运行时通过 HTTP 从 VCP GitHub 仓库获取。清单文件（manifest.json）提供索引，各标准文件按需获取。这意味着 skills 始终使用最新发布的标准。

可以使用自定义标准吗？

目前不支持。VCP 标准发布在仓库中并在运行时获取。自定义标准支持可能在未来版本中添加。

为什么标准位于可变分支上？

在 1.0 之前的开发阶段，标准从 main 分支获取，以便快速更新。到 v1.0 时，标准将固定到带标签的发布版本以确保稳定性。

Dev Buddy

什么是 Dev Buddy？

Dev Buddy 是一个用于多 AI pipeline 编排的 Claude Code 插件。它协调多个 AI agent 通过结构化 pipeline 进行功能开发和 bug 修复，使用基于任务的执行机制防止阶段跳过。

Dev Buddy 和 VCP 是什么关系？

它们是同一 marketplace 中的独立插件。VCP 执行代码标准（扫描、security gate）。Dev Buddy 编排开发工作流（需求、规划、评审、实现）。你可以使用其中一个或两个都使用。

Dev Buddy 支持哪些 AI provider？

三种类型：

  • Subscription —— 你现有的 Claude Code 订阅（默认，无需 API 密钥）
  • API —— 任何 Claude API 兼容的端点（需要 API 密钥）
  • CLI —— 外部 CLI 工具如 Codex CLI（需要安装该工具）

详情请参见 AI Provider Presets。

可以不用付费 API 密钥使用 Dev Buddy 吗？

可以。默认配置仅使用 anthropic-subscription（你的 Claude Code 订阅）。不需要额外的 API 密钥。API 和 CLI preset 是可选的，用于添加第三方评审者。

如何添加 Codex 作为评审者？

  1. 从你的 provider 安装 CLI 工具（例如 OpenAI Codex 使用 npm install -g @openai/codex —— 请查阅你的 provider 文档获取正确的安装包和安装方法）。
  2. 通过 Web 门户或 CLI 添加 CLI preset： 
    /dev-buddy-config
    添加类型为 cli、命令名称以及包含 {model}、{prompt}、{output_file} 和 {schema_path} 占位符的参数模板的 preset。
  3. 更新 pipeline 配置，在 plan-review 或 code-review 阶段引用该 preset。

.vcp/task/ 文件是什么？

Dev Buddy 在 pipeline 执行期间在项目根目录创建 .vcp/task/ 目录。包含：

  • pipeline-tasks.json —— Pipeline 状态和配置快照
  • user-story/ —— 需求和验收标准（多文件目录）
  • plan/ —— 实现计划（多文件目录）
  • rca-{provider}-{model}-{N}-v{V}.json —— 根因分析输出（仅 bug 修复）
  • plan-review-{system_prompt}-{provider}-{model}-{N}.json —— 计划评审结果
  • impl-result.json —— 实现结果
  • code-review-{system_prompt}-{provider}-{model}-{N}.json —— 代码评审结果
  • pipeline-tasks.json —— Pipeline 状态（由 orchestrator 创建）
  • analysis-*.json —— 专家分析文件（仅功能开发）

Pipeline 重置时会清理这些文件。建议将 .vcp/task/ 添加到 .gitignore。

如何重置卡住的 pipeline？

如果 pipeline 卡住：

  1. 使用 TaskList() 检查任务状态（需要活跃的 pipeline 团队）
  2. 检查 .vcp/task/ 中的工件文件
  3. 重置 pipeline： 
    bun "${CLAUDE_PLUGIN_ROOT}/scripts/orchestrator.ts" reset
    然后启动新的 pipeline 运行。

可以自定义 pipeline 阶段吗？

可以。编辑 ~/.vcp/dev-buddy.json 或使用 Web 门户（/dev-buddy-config）来：

  • 添加或移除评审阶段
  • 更改每个阶段使用的 AI 模型
  • 更换 provider（例如使用 Codex 作为最终关卡）
  • 调整 max_iterations 修复/重新评审循环限制

完整 schema 请参见 Dev Buddy 配置。

VCP Repository | Report a Problem | Propose a Standard | Apache License 2.0 | English | 中文

VCP Wiki

Guides

VCP Plugin

Dev Buddy Plugin

MCP Doc Plugin

Standards

Project

VCP Wiki (中文)

指南

VCP 插件

Dev Buddy 插件

MCP Doc 插件

标准

项目

Clone this wiki locally