sourcery

Sourcery Agent Bundle

用于 Agent 驱动的 Sourcery 安全工作流的混合插件包：一个 MCP 服务（通过 Sourcery 的公开安全 API 提供 12 个工具，并固定 OpenAPI 快照）、两个 Agent Skills，以及适配 Claude Code、Cursor、Codex/ChatGPT、VS Code、Devin、Grok（CLI + Bot）、Amp、Hermes、OpenClaw 和 Rovo Dev CLI 的适配器。该服务以 npm 包 @abyssbugg/sourcery 的形式发布——大多数宿主只需注册 npx -y @abyssbugg/sourcery@latest。各宿主的安装步骤请参见 docs/COMPATIBILITY.md。

已确认内容

Sourcery 当前的文档指出，唯一的公开 API 是面向安全发现项的 Team 计划 REST API。文档中给出的 API 基础 URL 是 https://api.sourcery.ai/api，首个有文档记录的请求是：

curl https://api.sourcery.ai/api/v1/security-issues \
  -H "Authorization: Bearer $SOURCERY_API_KEY"

已验证并固定。 在线 OpenAPI 文档（https://api.sourcery.ai/api/openapi.json）已作为快照提交至 openapi/sourcery-openapi.json：

• 信息：Sourcery API 0.1.0 (OpenAPI 3.1.0)
• 获取时间：2026-09-10
• SHA-256：9fdb45e657a6406c86ea0d0def2963d534e20bec1a9c88f7d62dbc2e6807f877

所有工具和客户端允许列表均由该快照生成。已验证的接口范围恰好包含八个操作：

方法	路径	用途
GET	/v1/security-issues	列出问题（筛选条件 + 游标分页）
GET	/v1/security-issues/stats	按状态和严重性统计数量
GET	/v1/security-issues/{id}	获取单个问题
PATCH	/v1/security-issues	批量更新（最多 100 个 ID）
GET	/v1/security-issue-groups	列出分组（使用相同的筛选条件）
GET	/v1/security-issue-groups/stats	按状态和严重性统计数量
GET	/v1/security-issue-groups/{id}	获取单个分组及其问题
PATCH	/v1/security-issue-groups	批量更新分组（最多 100 个 ID）

为什么要拆分 Sourcery API 与 Git 连接器

Sourcery 的 PR 审查控制目前记录为 GitHub/GitLab 评论或标签命令（review、summary、guide、title、resolve、dismiss、create issue），而非公开 REST 端点。因此，这些操作最好通过 GitHub/GitLab 连接器实现，而 Sourcery 则用于处理安全发现项。

插件包结构

仓库根目录 = 插件根目录。可移植核心（plugin.json + skills/ + mcp.json）遵循 Agent Plugins 1.0.0 标准，Cursor 和 OpenAI（Codex、ChatGPT 桌面应用）可原生加载；其他文件则是针对各宿主的轻量适配器。

sourcery-agent-bundle/
  plugin.json                      # Agent Plugins core manifest
  mcp.json                         # portable stdio wiring -> bin/sourcery
  skills/
    sourcery-triage/SKILL.md       # findings triage workflow
    sourcery-remediate/SKILL.md    # minimal-change fix workflow
  bin/
    sourcery                       # launcher: dist/cli.js when built, else npx @abyssbugg/sourcery
  agents/
    sourcery-triager.md            # read-only triage sub-agent (Claude format)
  .claude-plugin/plugin.json       # Claude Code manifest + userConfig API key
  .mcp.json                        # Claude Code MCP wiring (npx)
  .agents/plugins/marketplace.json # Codex/ChatGPT local marketplace entry
  scripts/
    install-rovodev.sh             # Rovo Dev CLI wiring (mcp.json + skills)
    install-local-hosts.sh         # grok, amp, hermes, openclaw, VS Code, Devin
  examples/
    mcp.http.json                  # remote deployment template
    hooks/                         # optional hooks example (SessionStart echo; not enabled)
  docs/
    COMPATIBILITY.md               # per-host setup matrix
    grok-bot-skill.md              # paste-in skill for Grok Bot
  openapi/
    sourcery-openapi.json          # pinned spec snapshot (SHA-256 above)
  src/                             # TypeScript: MCP server + findings CLI (@abyssbugg/sourcery)
    constants.ts                   # pinned facts: operations, enums, spec hash
  tests/                           # TypeScript tests (constants drift pin, tools, client)
  python/                          # Python reference implementation (server, client, prompts)
    src/sourcery_agent/
    tests/
  package.json                     # npm package manifest (@abyssbugg/sourcery)
  .env.example
  README.md

工具

• sourcery_security_snapshot：按状态/严重性统计数量，并返回第一页活跃问题——可从这里开始了解问题分流概况。
• sourcery_list_findings：列出问题，可使用 repository_ids、issue_types、statuses、search、limit、cursor。
• sourcery_get_finding：获取单个问题（完整记录，包括源代码片段和依赖关系图）。
• sourcery_get_security_counts：按状态和严重性汇总统计数量。
• sourcery_bulk_update_findings：批量更改状态/严重性（≤100 个 ID；SOLVED 由扫描器管理，因此会被拒绝）。
• sourcery_list_groups、sourcery_get_group、sourcery_get_group_counts、sourcery_bulk_update_groups：为问题分组提供相同功能。
• sourcery_build_fix_prompt：根据发现项构建 Sourcery 风格的最小改动 Agent 提示词；DEPENDENCY 路径使用 fixed_versions + manifest_file_path 并呈现依赖链。
• sourcery_capabilities：说明已验证的接口范围、规范固定信息和枚举值。
• sourcery_api_request：仅允许访问八个已验证操作的兼容桥接工具。

CLI

npx -y @abyssbugg/sourcery@latest snapshot                          # counts + first page of active findings
npx -y @abyssbugg/sourcery@latest list --status ACTIVE --limit 50   # filterable list
npx -y @abyssbugg/sourcery@latest get 1234                          # one finding in full
npx -y @abyssbugg/sourcery@latest fix-prompt 1234                   # minimal-change agent prompt

在已启用的插件宿主中，bin/sourcery 会运行相同的 CLI（优先使用本地构建的 dist/cli.js，否则回退到 npx）。在任何查询命令后添加 --json，即可用于脚本编写。

设置

要求：Node 20+。大多数宿主会直接注册 MCP 服务：

export SOURCERY_API_KEY='...'
npx -y @abyssbugg/sourcery@latest        # stdio MCP server (no args)
npx -y @abyssbugg/sourcery@latest http   # Streamable HTTP (127.0.0.1:8765/mcp)

或者将其安装为插件包——每个宿主只需一步（详情见 docs/COMPATIBILITY.md）：

宿主	快速开始
Claude Code	claude --plugin-dir . — 启用时会提示输入 API 密钥
Cursor	将仓库软链接到 ~/.cursor/plugins/local/，然后重新加载
Codex CLI / ChatGPT 桌面版	codex plugin marketplace add ./
ChatGPT 网页版	在 HTTPS 后运行 npx -y @abyssbugg/sourcery@latest http，然后通过开发者模式添加
VS Code / Grok / Amp / Hermes / OpenClaw	scripts/install-local-hosts.sh（幂等；注册插件、MCP 和技能）
Devin	通过安装程序创建技能链接；运行 devin plugins install --local . 安装完整插件
Grok Bot	粘贴 docs/grok-bot-skill.md 中的技能
Rovo Dev CLI	scripts/install-rovodev.sh

关于开发和测试，请参阅 Python 参考实现（其测试套件也可用于检查插件包打包），并运行 npm test 执行 TypeScript 测试套件。该服务基于官方 MCP TypeScript SDK（@modelcontextprotocol/sdk）构建。

重新生成固定快照

当 Sourcery 发布规范变更时：

curl -sS --fail -o openapi/sourcery-openapi.json https://api.sourcery.ai/api/openapi.json
shasum -a 256 openapi/sourcery-openapi.json   # update SPEC_SHA256 in src/constants.ts (+ python/src/sourcery_agent/constants.py, README/docs)
npm test                                      # tests/constants.spec.ts fails on drift

Sourcery 的 PR 审查命令（review、summary、guide、title、resolve、dismiss、create issue）仍然是 GitHub/GitLab 评论或标签命令——请通过 Git 提供商连接器实现这些命令，而不是调用 Sourcery REST API。