Symvanta

用于 Claude Code 的 Symvanta 插件

一步完成设置，让你能够在由 Symvanta 建立索引的代码库中工作。安装此插件后：

• 注册 Symvanta MCP 服务（默认地址为 https://mcp.symvanta.com/mcp，可配置为本地部署版 / 可自托管版，首次连接时通过 OAuth 进行身份验证），因此无需手动编辑 .mcp.json；
• 在每个会话开始时注入固定上下文，引导 Agent 使用 Symvanta 代码图工具，而不是通过 shell 搜索；
• 提供 symvanta 技能，其中包含完整的工具选择矩阵和约定；
• 添加封装常用代码图工作流的斜杠命令。

命令

每个命令都会路由到相应的 Symvanta MCP 工具，因此你无需记住工具名称：

• /symvanta:ask [question]：通过 ask_codebase 回答有关行为的问题（X 如何工作、Y 为什么会发生），并附上文件引用。
• /symvanta:blast [symbol]：编辑某个符号前，检查其影响范围以确保安全。
• /symvanta:trace [symbol]：梳理函数的调用链、调用方和依赖项。
• /symvanta:route [METHOD /path]：查找 HTTP 路由对应的处理程序。
• /symvanta:status：查看连接和索引的健康状况快照（项目、代码仓库、时效性、边数量）。
• /symvanta:architecture：通过 map view:"architecture" 查看高层模块图（Louvain 功能模块、PageRank 枢纽、跨模块耦合关系以及整个代码仓库中起关键作用的函数）。
• /symvanta:scope [symbol or change]：估算变更范围 / 影响，以便在预先评估后确定变更规模（estimate_scope）。
• /symvanta:branch [name | clear]：将此会话的读取固定到已跟踪的功能分支，或清除此固定设置（ref）。
• /symvanta:working-tree：叠加尚未提交的编辑，使代码图反映你尚未推送的更改（ref op:"index_working_tree"）。
• /symvanta:tests [symbol]：查找覆盖某个符号的测试（list_tests_for）。
• /symvanta:recent [path]：查看最近更改的文件和最近提交（history）。
• /symvanta:setup [local]：将 Symvanta 路由配置块写入项目的 CLAUDE.md（指定 local 时写入 CLAUDE.local.md）。重新运行会原位替换标记的配置块。子 Agent 会读取 CLAUDE.md，因此路由配置也会应用到它们。

安装

在 Claude Code 中：

/plugin marketplace add https://symvanta.com/plugin/marketplace.json
/plugin install symvanta@symvanta

首次连接时，按提示使用 OAuth 登录。Symvanta 控制面板中工作区的 Getting Started 页面会显示你账户对应的准确市场 URL。

配置

此插件默认连接到 Symvanta Cloud（https://mcp.symvanta.com/mcp），因此 Cloud 用户无需进行任何配置。若要连接其他 Symvanta 服务，请设置 Symvanta MCP 服务 URL（mcpUrl）插件选项：启用插件时接受或修改该选项，之后也可通过 /plugin 界面（Symvanta -> configure）进行设置。留空则回退到 Cloud 默认地址。

请使用包含 /mcp 路径且不带尾部斜杠的完整端点 URL，例如 https://mcp.your-company.com/mcp。仅提供主机地址或带有尾部斜杠都会导致连接失败。

身份验证。 每个 Symvanta MCP 服务（Cloud、staging 或本地部署版）都会公布自己的 OAuth 端点，因此无论 mcpUrl 指向何处，Claude Code 都会在首次连接时通过 OAuth 为你登录；无需在插件中进行任何配置。本地部署版支持相同的 OAuth 流程：其网关会通过你的 Symvanta cloud / license 完成登录，服务端则会验证签发的令牌。静态 API 密钥 / bearer 令牌身份验证也可用于无头自动化，但需在服务端或你自己的 MCP 设置中配置，而不是在此插件中配置。

更新

/plugin update symvanta@symvanta

然后重启 Claude Code。Claude Code 会在加载时读取插件（包括 hooks/hooks.json），而不是持续读取，因此运行中的会话会继续使用此前加载的版本，直到你重启。在此之前，/plugin update 只会下载更新，不会使其生效。

在你的机器上运行的内容

该插件会在本地执行简短、易读的 Node 钩子脚本：

• session-start.js：在会话开始时打印一次固定上下文。读取检出目录的 git 远程地址（owner/name），以便告知 Agent 调用 init 并将 repository 设置为该地址，从而将会话绑定到包含此检出目录的项目，而非工作区默认项目。不会向任何地方发送内容。
• augment 钩子系列（默认启用）：五个钩子共用一个核心文件 (lib.js)。每个钩子只能添加上下文，绝不会阻止操作： 任何错误、超时或令牌缺失都会直接放行，且被拦截的工具始终原样运行。每个钩子都会先检查触发它的检出目录是否关联到 Symvanta 项目（每个检出目录每十分钟调用一次 init，并进行记忆化处理）；未关联任何项目的检出目录，或没有远程地址的 git 检出目录，都会让钩子保持静默，因此你在未建立索引的代码库中工作时，不会看到其他代码库的符号。
  • grep-augment.js：在 Grep/Glob 时，查找匹配的已建立索引符号定义（限定在你正在搜索的仓库中，并行查找模式中的最多两个标识符，缓存 60 秒），并将其与原始搜索结果一同添加。
  • edit-augment.js：对代码文件执行 Edit/Write 时，在变更生效前注入被编辑符号的影响范围（上游符号数量、文件、层、跨仓库边以及风险级别）；覆盖现有文件的 Write 会列出被覆盖替换的定义。新文件和非代码文件会保持静默。
  • read-augment.js：每个会话中首次 Read 代码文件时，注入文件的符号骨架（名称、种类、行范围），以及锚定到该文件的任何架构决策记录。重复读取会立即退出。
  • grep-rescue.js：在未找到任何内容的 Grep 后，建议图谱候选项（自动文本／语义搜索），让死胡同变成线索；有结果的 grep 会在解析 stdin 后立即退出，不读取内容，也不访问网络。
  • prompt-augment.js：在轮次开始时，将你消息中符合标识符格式的词元（反引号括起的片段、snake_case、camelCase）解析为已建立索引的定义。普通文本不符合条件，因此对话式提示词会保持静默。

增强器具体读取、发送和写入的内容

调用图谱需要你的 Symvanta MCP 令牌。它们会重复使用你连接时 Claude Code 已存储的令牌，因此无需设置。读取范围有意设得很窄，每个脚本都短小到几分钟内即可审计：

• 它们只从 ~/.claude/.credentials.json 读取 mcpOAuth[<the Symvanta entry>].accessToken（在 macOS 上，Claude Code 会将其存储在登录钥匙串中，服务名为 Claude Code-credentials，因此当文件不存在时，钩子会从那里读取）。绝不会读取你的 Anthropic 令牌 （claudeAiOauth）或任何非 Symvanta 服务的令牌。
• 该令牌只会发送到 Symvanta MCP 服务，也就是签发该令牌的服务。
• 每次查找会有以下内容离开本机：提取出的标识符词项、匹配到的符号名称、相对于仓库的文件路径，以及检出项的 GitHub 远程地址，格式为 owner/name（用于附件检查）。绝不会发送文件内容，也不会发送你的消息文本（提示词钩子最多只会发送两个标识符令牌，而不是提示词）。
• 它们会在 ~/.symvanta/ 下写入本地文件，绝不会上传到任何地方： grep-cache/（60 秒结果缓存，每个键对应一个小文件）、 repo-cache.json（路径到仓库的映射备忘）、 workspace-cache.json（每个检出项的附件备忘，有效期 10 分钟）、 keychain-cache.json（仅限 macOS：钥匙串读取结果的 5 分钟备忘，避免繁忙的会话在每次工具调用时都通过 shell 调用 security）、 read-seen/（每个会话的首次读取标记），以及 grep-augment.log（每次运行写入一行 JSONL：钩子、词项、仓库、匹配数、延迟、缓存命中情况）。此日志用于让 /symvanta:status 显示钩子的运行情况；你可以随时删除这些文件。

开关（更改后请重启 Claude Code）：

# Supply your own token instead (dashboard -> Settings -> MCP connection ->
# regenerate gives a Passport mcp:read token); the credentials file is then
# never read:
export SYMVANTA_MCP_TOKEN="<token>"

# Turn the whole family off (no reads, no network on any tool call):
export SYMVANTA_AUGMENT=off        # the legacy SYMVANTA_GREP_AUGMENT=off also works

# Or turn off individual hooks:
export SYMVANTA_EDIT_AUGMENT=off   # Edit/Write blast radius
export SYMVANTA_READ_AUGMENT=off   # first-read skeleton + ADRs
export SYMVANTA_GREP_RESCUE=off    # empty-grep suggestions
export SYMVANTA_PROMPT_AUGMENT=off # prompt term lookup

你也可以从 hooks/hooks.json 中删除任意钩子的配置块，以彻底移除该钩子。

Bash 和所有未配置上述钩子的工具都会照常运行。所有代码导航都通过 HTTPS 经由 Symvanta MCP 服务完成，并受 OAuth 保护。没有遥测，也没有后台进程。

Grep/Glob 增强器的工作原理

每个关卡在失败时都会安全地回退到相同的直通路径；无论直通还是成功，最终都会进入“Grep 正常运行”状态：钩子只能添加上下文，绝不会阻止搜索，也不会导致搜索失败或延迟。SYMVANTA_GREP_AUGMENT=off 会在读取或发送任何内容之前直接短路。

flowchart TD
    A["Agent runs Grep or Glob"] --> B{{"Claude Code fires the PreToolUse hook"}}
    B --> D{"SYMVANTA_GREP_AUGMENT = off?"}
    D -->|yes| RUN["Grep/Glob runs normally; results unchanged"]
    D -->|no, default| TX["Extract up to 2 identifiers from the pattern; derive the repo from the search path"]
    TX --> CACHE{"Fresh 60s cache hit?"}
    CACHE -->|yes| F["Format matching definitions as additionalContext"]
    CACHE -->|no| TOK["Token: SYMVANTA_MCP_TOKEN, else the stored Symvanta token from ~/.claude/.credentials.json (macOS: login Keychain)"]
    TOK --> C["quick_lookup per term, in parallel, repo-scoped, hard cap 1.5s; falls back to locate mode:symbol"]

    subgraph cloud["Symvanta cloud (only the search TERMs leave your machine)"]
        C --> M["mcp.symvanta.com"]
        M --> DB[("Code graph in Postgres")]
        DB --> M
    end

    C --> OK{"Token valid and matches, in time?"}
    OK -->|no, error, or timeout| LOG["Append one line to ~/.symvanta/grep-augment.log"]
    OK -->|yes| CW["Cache for 60s"] --> F
    F --> EM["Emit JSON to Claude Code"] --> LOG
    LOG --> RUN
    RUN --> O["Agent sees its grep results PLUS the Symvanta definitions, then reaches for find_node / relate / ask_codebase"]

卸载

/plugin uninstall symvanta@symvanta
/plugin marketplace remove symvanta

目录结构

.claude-plugin/plugin.json   manifest + MCP server registration
hooks/hooks.json             SessionStart + augment family wiring (PreToolUse, PostToolUse, UserPromptSubmit)
hooks/session-start.js       standing-context injector
hooks/lib.js                 shared augment core (auth, transport, cache, log)
hooks/grep-augment.js        Grep/Glob definition augmenter
hooks/edit-augment.js        Edit/Write blast-radius augmenter
hooks/read-augment.js        first-read file skeleton + ADR augmenter
hooks/grep-rescue.js         empty-grep graph suggestions (PostToolUse)
hooks/prompt-augment.js      prompt identifier lookup (UserPromptSubmit)
hooks/augment-stats.js       local activity summary for /symvanta:status
commands/                    slash commands (ask, blast, trace, route, status, architecture, scope, branch, working-tree, tests, recent)
skills/symvanta/SKILL.md     tool decision matrix and conventions
scripts/                     sync-skill.mjs (SKILL from source) + check-tool-prefixes.mjs (CI guard)

许可证

MIT