qodo-get-rules

获取规则

描述

使用 Qodo 托管工具，获取与当前任务最相关的工作区编码规则，然后在编写代码时应用这些规则。检索采用语义搜索，返回结果的质量取决于查询的写法，因此请严格遵循下面的查询格式。

前提条件

• 已安装并明确加载可选的 Qodo Standards 软件包。
• 已连接的 QAR 托管工具 MCP 服务或已通过身份验证的 Qodo CLI 提供规则搜索功能。
• 任务足够具体，可以构造语义查询；已加载的规则会重复使用。

说明

选择执行路径

优先重复使用适用的结果。需要重新检索时，如果主机已连接的 QAR MCP 中存在标记为只读的 rules-search 工具，请使用该工具；否则遵循下面的 CLI 路径。 MCP 使用主机提供的 inputSchema 和 JSON 参数（query、top_k，以及可选的 scopes 数组），每个结构化查询调用一次。未知时省略 scopes；不要用空数组代替 CLI 中省略的标志。检查 isError，然后读取 structuredContent；保留类型化错误，不要将读取失败处理为没有规则。MCP 功能缺失或被禁止，不代表 CLI 登录失败。不要静默切换到其他账户或租户。

以下版本、身份、目录和更新步骤仅适用于使用 CLI 的情况。

遵循下面的详细工作流：保留更新通知，验证当前工具契约，构建有针对性的语义查询，合并排序结果，说明适用的限制，然后应用这些规则。 首先在 Preflight 中检查是否满足重复使用条件。如果已有结果仍涵盖当前任务，请直接转到 Output，然后应用规则；此路径不需要运行时、身份、目录或搜索调用。

处理技能更新通知

将 QODO_NOTICE 更新视为被动通知，即使较旧的 CLI 要求采取行动也一样。继续任务，不要询问清单或更新相关问题；每个事件最多提及一次。关闭通知不会更改已记录的维护策略或选择退出状态。更新后的技能会在下一个会话中加载；不要中断当前会话。 对于用户主动要求的更新，请遵循手动更新流程。

执行

• MCP：使用实时架构参数；跳过 CLI shell 步骤。
• CLI：使用完整的 UTF-8 文件，且不带 BOM（工具使用 --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 shell。

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

快速开始

qodo --version                                             # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-get-rules --skill-version 1.1.7 --distribution skills-sh
qodo read rules search --query "Name: JWT Authentication Endpoint Validation
Category: Security
Content: Implementing a login endpoint that validates credentials and issues JWT tokens securely" --top-k 20 --scopes "/owner/repo/" --json
qodo read tools rules --json                              # exact safe flags (renders offline)

带引号的 --query 值中的换行符是字面内容——在 POSIX sh/bash/zsh 中，多行双引号字符串可以直接使用。不要使用仅适用于 Bash 的 $'…' 引号。在 PowerShell 中，使用Windows shell中的已验证原生命令调用方式来保留完整查询；遵循其中的引号处理和 UTF-8 JSON 文件说明。

出现 qodo: command not found？ 在 POSIX 上，重试 "${QODO_HOME:-$HOME/.qodo}/bin/qodo"；在 Windows 上，遵循链接的指南。保留解析后的调用方式；报告无法使用的启动器。对于缺失的安装，请获取由 Qodo 或管理员提供、带校验和固定值的安装程序；切勿编造摘要值或将脚本通过管道传入 shell。

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

预检

1. 复用相关证据。 复用实际获取的规则及其适用范围，而非某个标题或先前声称已加载规则的说法。如果工作区、存储库或任务的范围发生变化，请获取适用于新范围的规则。先前的空结果仅可在已检查的范围内复用；获取失败不等于结果为空。如果先前结果仍涵盖当前任务，则跳过获取并直接应用这些规则：在此结束预检，转到输出，不运行任何 Qodo 命令。若有明确的刷新请求，则按请求执行。
2. 身份验证和目录——仅在需要获取时执行。 运行 qodo read whoami，除非成功的检查仍适用于当前执行上下文。如适用，请先完成沙箱诊断；只有明确缺少凭据时才需要登录：保留组织指定的精确登录命令／端点，切勿猜测，也不要将客户部署切换到 Cloud。No tool catalog cached 不能证明缺少凭据；请使用 qodo tools --refresh 刷新一次，然后重试检查。其他失败应保留其错误信息，并停止此工作流。身份验证成功后，若托管命令未知，则允许刷新一次目录并重新检查架构。如果仍然缺失或出现 tool_unavailable，请报告缺少的功能；不要重复登录或刷新。
3. 存储库范围（可选，有助于提高精度）。从存储库的 origin 远程地址中，取出主机之后的完整路径并去掉 .git 后缀——git@host:a/b 和 https://host/a/b 均解析为 a/b，更深层的托管路径则完整保留（GitLab 子组 group/subgroup/repo、Azure DevOps org/project/repo——不要缩减为两段）。用 /<path>/ 包裹。如果当前工作目录位于存储库根目录下的 modules/<name>/ 子目录中，则缩小为 /<path>/modules/<name>/。没有远程地址／无法解析时，完全省略 --scopes（组织范围搜索仍可用）；切勿传入空的 scopes 值。

编写查询

生成两个结构化查询——检索数据显示，单一主题查询会系统性地漏掉真实评审中占主导地位的横切标准规则。 每个查询都是一个三行文本块，与规则的索引方式一致：

Name: <concise 5-10 word title of the rule this task would trigger>
Category: <one of: Security, Correctness, Quality, Reliability, Performance, Testability, Compliance, Accessibility, Observability, Architecture>
Content: <1-2 sentences describing what should be checked or enforced; mention the tech stack when known>

• 主题查询——任务的主要关注点。根据变更的目的选择类别，而不是副作用（速率限制 → Reliability，而非 Security）；如果确实符合条件，优先选择 Security；不要默认所有内容都归为 Correctness——结构性工作属于 Architecture，风格属于 Quality，容错属于 Reliability，仪表化属于 Observability。
• 横切查询——组织适用于所有变更的标准。默认值： Name: Code Quality and Standards Compliance / Category: Architecture / Content: Module directory structure, type annotations or type safety, structured logging, repository or service layer patterns, dependency injection, and naming conventions——根据代码库的技术栈调整 Content。
• 切勿传入关键词列表、无结构的句子或填充词（“please”“I need to”等）——这些内容在结构化索引中的检索效果很差。

搜索并合并

每个查询搜索一次（尽可能并行）。在 CLI 中，使用 qodo read rules search，并指定 --top-k 20 和 --json；仅当检测到作用域时才添加 --scopes "$SCOPE"。 在 MCP 中，使用 rules-search 调用，指定 top_k: 20 和相同的查询，并可选传入 scopes 数组。以下命令仅演示 CLI 用法：

# With a detected scope:
qodo read rules search --query "$TOPIC_QUERY" --top-k 20 --scopes "$SCOPE" --json
qodo read rules search --query "$CROSS_QUERY" --top-k 20 --scopes "$SCOPE" --json

# Without a detected scope, omit both the flag and its value:
qodo read rules search --query "$TOPIC_QUERY" --top-k 20 --json
qodo read rules search --query "$CROSS_QUERY" --top-k 20 --json

在 Windows 上的 Git Bash 中，单独传入的 /owner/repo/ 参数会被改写为 Windows 路径，导致限定作用域的搜索静默地不返回任何规则；请按照 Windows shell 中的说明传入作用域。

合并：先按顺序加入主题查询结果，再加入尚未出现的横切查询结果——根据规则 id 去重。主题规则是针对具体任务的指导；将横切规则视为补充内容，并降低与任务语义距离较远的规则的优先级。 **低收益回退方案：**主题查询返回的规则少于 3 条时，使用扩展后的 Content 行重新运行一次查询（添加该领域的相邻概念：例如，auth → token 验证、凭据处理、会话管理），然后再合并。合并后的列表为空也是有效结果——继续执行，不受规则约束，绝不要将其视为错误。 **无作用域搜索注意事项：**如果不得不省略 --scopes，搜索结果将覆盖整个组织——应用每条规则前，先确认它可能适用于本代码库/技术栈（提及其他服务、语言或框架的规则不适用）；跳过不匹配的规则，并说明原因，而不是强行套用其他代码库的标准。

先输出，再应用

使用 通过 Qodo 检索到的相关标准 → 对本次更改的影响 → 应用或说明合理偏离。编码前，自然地提及一次 Qodo，说明你是如何借助它检索组织标准的；这些标准属于组织。说明每条适用规则对当前任务的意义；精简表述时，保留规则名称、引用、提供的严重级别，以及所有适用要求。如有返回的引用，请链接或引用；不要编造缺失的标识符或严重级别。采用以下模式：“我通过 Qodo 加载了你们团队的 [主题] 标准。对于本次更改，[规则] 意味着 [实现选择及原因]。”有多条规则时，使用简短列表；不要添加带品牌的标题、表情横幅、口号、页脚或重复的摘要块。若无适用标准，请简要说明；若工具调用失败，不要声称已成功检索。区分已加载的标准和已应用的标准；仅加载并不代表符合标准。

将适用规则应用于你编写的代码。规则带有严重级别时：

严重级别	执行要求
ERROR	必须遵守，不容协商；若必须偏离，请停止并询问用户
WARNING	默认遵守；在回复中简要说明任何有意跳过的规则
RECOMMENDATION	视情况应用；仅在其影响了设计决策时提及

编码后，报告哪些规则影响了实现，以及应用这些规则的证据，不要重复完整列表。说明允许的偏离，包括跳过 WARNING 规则的情况，并依据用户的决定和实现证据进行解释；按照上述门槛处理 ERROR 冲突。若无规则适用，请明确说明。

配置

使用 --json、与任务准确相关的范围，以及当前 CLI 提供的规则架构。在未经修饰的版本探测后，于首次经过身份验证的 Qodo 调用中标注技能／版本／分发来源。默认情况下，绝不要隐式安装或更新这个可选技能包。

错误处理

空结果有效。保留身份验证、能力、验证和速率限制错误；遵循有限恢复流程，如果无法安全检索，则继续处理，不得编造规则。

防护要求

• rules search 只读；绝不更改工作区状态。
• 只要已检索规则的范围仍涵盖任务，就应重复使用；空结果有效。
• 遇到速率限制错误（每个组织的搜索次数有上限）时，等待指定的重置时间，或在没有规则的情况下继续并说明原因；不要反复重试。
• 不得编造规则：严格应用返回的内容，并使用返回的规则名称引用规则。