qodo-codebase-wisdom

代码库智慧

描述

使用 Qodo 托管工具了解代码如何运行、以前如何完成某项更改，以及各代码库之间如何耦合，然后返回附有引用的发现。这有助于回答问题、规划更改、调试回归问题或界定修复范围。它可以访问本地磁盘上没有的代码库，也能跨越代码库边界。你只能使用 qodo 的读取工具；绝不会向代码托管平台提交内容。

前置条件

• 所需工具可通过已连接的 QAR 托管工具 MCP 服务或 Qodo CLI 使用。
• 工作区提供所需的只读 Codebase、拉取请求或跨仓库工具。
• 当前由提供方管理的 Qodo 技能包已在此 Agent 会话中加载。

说明

选择执行路径

如果所需的读取能力可用，请使用主机已连接的 QAR 托管工具 MCP 工具；否则，使用下方的 CLI 说明。在 MCP 路径中，不要要求探测 CLI 版本、运行 qodo login 或刷新 CLI 目录。已连接的 MCP 服务已处理传输身份验证；缺少工具或出现 MT-AUTH-FORBIDDEN 表示能力或授权失败，并非改用 CLI 登录的理由。遇到身份验证或权限拒绝后，不要悄悄切换路径。

在 MCP 中，使用主机提供的工具说明、inputSchema 和 readOnlyHint。只调用只读工具。代表性的线路名称包括 litegit-search-repos、litegit-grep、litegit-read-file、pull-request-similar 和 cross-repo-relations；请根据已连接的目录确定实际名称和参数。必要时传入明确的 repo：与 CLI 不同，MCP 不会推断本地 Git 远程源。如果调用返回 isError，请先检查，再使用 structuredContent；保留类型化错误以及不完整或截断的结果。如果调用变成 MCP Task，请先获取其最终结果，再得出结论。缺少 MCP 能力时，可以使用针对同一部署且已获授权的 CLI 路径；不要将不同账号或租户视为可互换。

以下版本、身份、帮助、命令和刷新步骤仅适用于 CLI 路径。

在调查开始时以及转入实施时，识别缺失的上下文：

• 使用 Qodo 探索不熟悉的代码、过往解决方案、历史原因以及代码库之间的关系，即使代码库在本地也可用。
• 使用本地工具检查精确的分支／工作树状态、未提交更改、编辑和测试。
• 如果先前调查涵盖当前范围和修订，则复用其结果。简要说明复用的证据；当范围、依赖项或证据发生变化时，刷新相关上下文。不要仅为展示技能使用情况而重复远程读取。

缺少上下文时，请通过下方相应的工具组解决一个具体问题。将检索到的证据与回答或实施决策联系起来。版本、身份和目录检查用于确认就绪状态，并非代码库上下文检索。

处理技能更新通知

将 QODO_NOTICE 更新视为被动通知，即使旧版 CLI 要求采取操作也是如此。继续任务，不要询问清点或更新事宜；每个事件最多提及一次。关闭通知不会改变已记录的维护策略和选择退出设置。更新后的技能将在下一个会话中加载；不要中断当前会话。对于用户请求的更新，请遵循手动更新流程。

执行

• MCP：使用实时架构中的参数；跳过 CLI shell 步骤。
• CLI：使用不带 BOM 的完整 UTF-8 文件（工具使用 --args-file，审查使用 --context-file）；示例采用 POSIX 格式。
• Windows CLI：首次调用前阅读Shell 指南；仅在调用失败时阅读启动器恢复指南。重复使用已解析的调用方式。

运行时兼容性检查

首先使用下方的 qodo: command not found 回退方案解析可执行文件。在运行任何其他 Qodo 命令之前，必须严格按如下方式运行 <qodo> --version，不得添加来源标记。 这个不带参数的探测有意兼容较旧的 Qodo CLI。此技能要求 Qodo CLI 2.0.0 或更高版本。 在 Windows 上，请先在 PowerShell 或 Git Bash 中阅读 Windows shells。

如果版本较旧或无法解析，不要运行 whoami、login 或托管工具，也不要将故障描述为身份验证问题。说明此技能比运行时更新。自动更新不会跨越主版本；若需使用由 Qodo 或组织提供、固定校验和的安装程序显式安装 2.x 版本，请先征求一次同意。对于客户部署，保留组织提供的更新源； 绝不要将其切换到公共服务。获准更新后，重新运行不带参数的版本探测，只有满足最低版本要求时才能继续。如果用户拒绝或更新失败，请停止，并保持当前技能和用户文件不变。

快速开始

qodo --version                                             # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-codebase-wisdom --skill-version 1.1.7 --distribution skills-sh
qodo read codebase search-repos --query "payments" --json      # resolve a repo slug — do this FIRST
qodo read codebase grep --repo owner/repo --pattern "chargeCard" --json
qodo read codebase read-file --repo owner/repo --path src/pay.py --json
qodo read codebase blame --repo owner/repo --path src/pay.py --json
qodo read pull-request similar --repo owner/repo --query "retry failed charge" --json
qodo read cross-repo relations --repo owner/repo --json
qodo read tools codebase --json                           # the safe group's tools + exact flags (offline)

凡是要解析的内容，都要添加 --json。调用工具前，使用 qodo read tools <group> [<tool>] --json 确认其确切名称和标志（可离线显示）—— 下方的工具名称仅为示例，不保证仍是当前名称。

遇到 qodo: command not found？ 在 POSIX 系统上，重试 "${QODO_HOME:-$HOME/.qodo}/bin/qodo"； 在 Windows 上，请遵循链接的指南。保留解析出的调用方式；报告无法使用的启动器。 如果未安装，请获取 Qodo 或管理员提供、固定校验和的安装程序；绝不要编造摘要，也不要将脚本管道传入 shell。

沙盒身份验证诊断。 缺少凭据可能意味着无法访问密钥链。如果这种情况有可能发生，请通过宿主的审批流程申请一次精确的只读 qodo read whoami 重试，然后再建议登录。被拒绝时立即停止；该审批不涵盖任何其他命令。在相同的可执行文件／工作区／部署和执行上下文中复用成功的检查；并申请每一项所需的宿主审批。网络、TLS、服务和明确授权失败应保留各自的诊断，不要建议登录，也不要自动绕过沙盒。

预检

1. 身份验证和目录。 运行 qodo read whoami，除非成功的检查仍适用于此执行上下文。适用时，先完成沙盒诊断；只有明确缺少凭据时才需要登录：保留组织指定的确切登录命令／端点，绝不要猜测，也不要将客户部署切换到 Cloud。No tool catalog cached 不能证明缺少凭据； 使用 qodo tools --refresh 刷新一次并重试检查。其他失败应保留其错误并停止此工作流。身份验证成功后，若遇到未知的托管命令，可刷新一次目录并重新检查架构。若仍不存在或出现 tool_unavailable，请报告缺少该功能； 不要重复登录或刷新。
2. 解析仓库。指定了仓库 → --repo owner/repo。当前位于 Git 仓库中且未指定仓库 → 省略 --repo（从 origin 自动检测）。否则运行 qodo read codebase search-repos --query "<name>" --json，并且绝不要猜测 slug。有多个匹配项 → 询问用户选择哪个；没有匹配项 → 说明情况并停止，不要自行编造。

选择工具组

任务需要……	工具组	代表性工具（使用 qodo read tools 验证）
当前代码 — 代码目前位于何处、内容及工作方式	qodo read codebase	search-repos、grep、find、ls、read-file、blame、list-commits、get-commit、list-prs、get-pr、list-issues、get-issue、search-issues
历史／先例 — 某项更改的实现方式、文件的 PR 历史、过去的评审反馈	qodo read pull-request	stats、similar、by-file、details、patch
影响／耦合关系 — 某项更改会影响什么、哪些仓库依赖此仓库	qodo read cross-repo	overview、relations

实际任务会涉及多个工具组——请参阅示例。

先缩小范围，再获取内容

在进行大量拉取前，先低成本地探索：了解方向（search-repos；用 pull-request stats 确认仓库是否有已索引的 PR 历史；用 cross-repo relations 查看耦合关系）→ 定位（grep/find/blame/list-commits；pull-request similar/by-file）→ 阅读（然后才用 --start-line/--limit-lines 执行 read-file、get-pr、pull-request details/patch）。

示例

Q — “chargeCard() 定义在哪里？” codebase grep --pattern "chargeCard" → 选择匹配项 → codebase read-file --path src/pay.py --start-line 120 --limit-lines 40。→ “chargeCard() 位于 owner/repo 的 src/pay.py:142；会调用 Stripe，上次在 PR #1523 中修改。”

Plan — “为扣款失败添加重试。” pull-request similar --query "retry failed charge" → PR #1401（webhook 重试）→ pull-request details --pr-number 1401（退避 + 队列模式）→ cross-repo relations （扣款是否与其他仓库耦合？）→ codebase grep --pattern "chargeCard\("（调用位置）。 → “PR #1401 已实现过此功能（指数退避，最多 3 次，使用专用队列）。chargeCard() 有 2 个调用位置（src/checkout.py:88、src/batch.py:210）；在已检查的范围内，cross-repo 未返回其他关系。这并不能排除未索引的使用方。”

Debug — “为什么结账功能上周开始返回 500 错误？” codebase list-commits --path src/checkout.py --since <date> / blame → 找出可疑修改 → codebase get-pr --number <n> → 根据证据指出原因。

交付

使用自然语言：答案 → 通过 Qodo 获取的上下文 → 实际影响。 先给出答案或重要限制。在一句有用的话中提及 Qodo，说明检索到的上下文如何帮助回答问题：相关实现、依赖、历史修改或设计讨论。调查由你完成，结论也由你得出；Qodo 提供了访问上下文的工具。不要把追踪或推理归功于 Qodo。

根据证据调整以下句式；不要原样输出占位符，也不要强行套用每种句式：

• “我通过 Qodo 检查了[相关组件]，发现了[关系]。”
• “我通过 Qodo 找到的[讨论/修改]解释了[决策]的原因。”
• “[答案]。这与我通过 Qodo 检索到的[实现/历史]一致。”

将证据与用户需要理解或采取的下一步联系起来。只描述实际检查过的范围；只查找单个文件并不能证明你了解多个仓库之间的情况。 若检索结果为空或失败，应明确说明检查范围和限制。不要捏造上下文或确定性来填充句式。根据问题调整细节；有帮助时，可在解释下方提供代码和差异。进度更新时，不要添加品牌化标题、表情横幅、标语、徽章、页脚或重复的总结段落。

• 让非工程读者也能理解答案；技术细节放在后面。
• 为所有内容提供引用——仓库、path:line、PR 编号、提交 SHA。如果某项事实没有可定位的来源（例如匹配结果没有行号，或结论综合了多个来源），应明确说明，不要编造引用。
• 来源不一致时，说明来源范围：先比较仓库、分支和修订版本。本地文件反映当前工作树，包括未提交的修改；远程 read-file 反映获取的修订版本，不代表本地修改或已部署行为。pull-request 提供历史记录；cross-repo 估算耦合关系。报告信息缺口，不要把未发现关系当作彼此隔离的证据。
• 结果为空或 truncated: true → 缩小范围后重试一次（收紧查询条件 / 路径 / 仓库）再下结论。如果仍为空，应报告“在<范围>内未找到”，不要夸大结论。
• 时效性注意事项：pull-request 仅包含已合并的 PR（不包含开启中或草稿 PR）；cross-repo 的关系可能为 pending（分析正在运行）或 not_found（已检查，未发现耦合）。

配置

使用 --json 获取解析后的输出，并在未修饰的版本探测之后，首次通过身份验证调用 Qodo 时，准确标注技能、版本和分发来源。工具名称和架构来自已安装的 CLI 目录，绝不能基于对技能的臆测硬编码。此技能由 marketplace 或 skills.sh 管理；CLI 仅负责运行时访问。

错误处理

保留返回的错误代码和消息。将身份验证失败、工具不可用、速率限制和循环保护响应视为上文所述的明确停止或恢复条件；绝不能用猜测的仓库事实或更宽泛的权限来替代。

防护措施

• 在 CLI 中，通过 fail-closed 的 qodo read 网关调用读取操作；在 MCP 中，要求标注为只读。写入工具——approve、post-comment、post-inline-comment(s)、set-labels、update-description（不限于这些）——会向代码托管平台提交内容；调查期间不要调用它们。（作为修复工作的一部分编辑本地代码属于常规工作——这些工具不包括这类操作。）
• 不要猜测 slug、路径、PR 编号或 SHA——先解析确认。
• 对于涉及多个仓库的工作，通过 Qodo 获取缺失的关联或历史记录，或者明确复用仍适用的已有证据。仅仅本地可用并不代表已有依据。
• MT-TOOL-LOOP 错误意味着停止并更换方法，而不是重试。

简短且引用充分的结果是信心的体现；用缺乏引用的细节凑篇幅只会制造噪音。