IDE 集成（VSCode）

即将上线： VSCode 扩展正在内测，功能已基本完整，预计近期发布到 Marketplace。如有兴趣提前体验，可下载 VSIX 手动安装，或在 GitHub Issues 关注发布动态。

Cogna VSCode 扩展（扩展 ID：xaclabs.cogna）把完整的 Cogna 工作流嵌入编辑器，让你在写代码的同时就能看到接口兼容性问题，而不是等到 CI 失败才知道出了问题。

安装

方式一：VSCode Marketplace（推荐）

扩展发布后，在 VSCode 的扩展面板中搜索 Cogna 或直接通过扩展 ID 安装：

xaclabs.cogna

或点击 Marketplace 页面 安装。

方式二：手动安装 VSIX

适合离线环境或希望提前体验：

1. 从 GitHub Releases 下载 .vsix 文件
2. 在 VSCode 中打开命令面板（Ctrl/Cmd + Shift + P）
3. 输入 「Extensions: Install from VSIX…」，选择下载的文件

前置条件

扩展本身不包含 Cogna 运行时，需要先在系统中安装 CLI：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/cogna-dev/cogna/v0.1.0/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/cogna-dev/cogna/v0.1.0/install.ps1 | iex

安装完成后验证：

cogna --version

快速上手

安装扩展后，打开一个包含 cogna.yaml 的项目目录：

1. VSCode 侧边栏会出现 Cogna 图标面板
2. 点击 「Build」 构建索引（首次构建需要一点时间）
3. 构建完成后，点击 「Diff」 查看变更
4. 点击 「Check」 执行策略检查
5. 违规问题会以波浪线形式标注在对应源文件中，悬停可查看规则说明

功能详解

一键运行完整工作流

扩展在 VSCode 侧边栏提供按钮，顺序执行 build → diff → check 三个步骤：

• Build：触发 cogna build，更新本地索引，读取 dist/bundle.json
• Diff：触发 cogna diff，对比当前版本与基线版本的接口变化，写入 dist/diff.json
• Check：触发 cogna check，对变更执行策略合规检查，写入 dist/check.sarif.json

每个步骤的进度和日志会实时显示在输出面板（输出 → Cogna）中。

内联诊断（Diagnostics）

策略检查完成后，扩展会读取 dist/check.sarif.json，将所有违规条目以 VSCode Problems 的方式展示：

• 在 Problems 面板（Ctrl/Cmd + Shift + M）中集中列出所有问题
• 在源文件对应行高亮标注波浪线，悬停查看违规规则名称和简要说明
• 点击问题条目直接跳转到具体位置

这样你在写代码时就能实时感知接口兼容性风险，而不需要等到 CI 阶段。

自动打开规则文档

每条违规结果都包含一个 helpUri，指向对应的策略规则文档页面。开启 cogna.autoOpenPolicyDocs 后，点击违规条目会自动在浏览器中打开文档，帮助你快速理解：

• 这条规则是什么含义
• 为什么这个变更被标记为问题
• 如何修复或通过合理理由豁免

保存时自动分析

开启 cogna.runOnSave 后，每次保存文件时扩展会自动触发完整的 build → diff → check 流程，Problems 面板随时保持最新状态。

适合：开发节奏快、频繁提交的场景。不适合：大型仓库（构建时间较长时会影响编辑体验），建议手动触发。

配置选项

在 VSCode 的 settings.json 中可以配置以下选项：

示例配置（.vscode/settings.json）：

{
  "cogna.cliPath": "/usr/local/bin/cogna",
  "cogna.workingDirectory": "${workspaceFolder}",
  "cogna.runOnSave": false,
  "cogna.autoOpenPolicyDocs": true
}

团队共享配置： 把 .vscode/settings.json 提交到版本库，确保团队成员的扩展行为一致。注意 cliPath 如果使用绝对路径，不同操作系统可能需要不同配置，建议保持 "cogna" 默认值，依赖系统 PATH。

与其他工具的配合

与 CLI 配合

扩展底层直接调用本地 CLI，两者完全兼容：

• 在终端手动执行 cogna build 后，扩展可以直接读取已有的 dist/ 产物，无需重新构建
• 在扩展中触发的操作，其输出产物（dist/diff.json、dist/check.sarif.json）也可以被 CLI 或 CI 继续使用

与 MCP 配合

扩展执行 cogna build 后，你可以同时启动 MCP 服务，让 GitHub Copilot（或其他 AI 工具）查询当前仓库的接口事实：

cogna mcp serve --stdio

在 .vscode/mcp.json 中配置即可。详见 AI 查询（MCP）。

常见问题

扩展找不到 cogna 命令

检查 cogna 是否在 PATH 中：

which cogna    # macOS / Linux
where cogna    # Windows

若不在 PATH，在 settings.json 中配置完整路径：

{
  "cogna.cliPath": "/usr/local/bin/cogna"
}

诊断结果不更新

诊断来自 dist/check.sarif.json，需要重新运行 Check 才会刷新。如已开启 cogna.runOnSave，检查保存时是否有构建错误（查看输出面板）。

项目根目录没有 cogna.yaml

打开 VSCode 命令面板，输入 「Cogna: Init」，或在终端执行 cogna init。

相关文档

• 快速开始
• CLI 参考
• AI 查询（MCP）
• SARIF 集成
• 内置策略规则
• 持续集成