PavedPath Code
PavedPath Code（代码版）帮助代理避免为软件工程问题重新发明解决方案。它搜索 GitHub 和开源证据以寻找经过验证的实现路径，然后通过最小、可验证的更改将最强的模式适配到本地代码库。
将 GitHub 作为主要证据来源，而不是链接转储。目标是定义本地代码问题，找到已在公共仓库、议题、拉取请求、讨论、示例、发布说明和源代码中走过的路径，评估证据的强度，然后将最强模式转化为一个小的本地修复、实现路径或验证计划。
这是专注于代码领域的 PavedPath 版本。不要将其扩展为未来的通用 PavedPath 版本。它适用于软件工程工作：错误、运行时错误、构建/测试/部署失败、依赖问题、框架或 API 使用、集成障碍、实现模式、工程工具选择和开源解决方案适配。
使用时机
- 运行时、构建、测试、部署、包、SDK、API、依赖、框架或集成错误。
- 功能实现因不明确的边缘情况、缺失的使用模式、版本行为或不确定的 API 契约而受阻。
- 本地问题与维护者或其他开源用户在议题、PR、示例、代码、发布说明或讨论中可能已解决的问题相似。
- 用户询问 GitHub 或开源项目是否已经解决了某个具体的工程问题。
- 成熟的实现示例或可复用的项目会减少针对特定能力的不确定性。
- 答案应比较合适的 GitHub 仓库并解释如何本地适配一个经过验证的路径。
不要将 PavedPath Code 用于复制编辑、代码库已明确答案的纯本地重构、非代码的生活决策、自媒体工作流、学习方法、消费者购买决策，或明确禁止网络/GitHub 研究的请求。除非用户明确指定并授权，否则不要检查私有仓库。
默认工作流程
- 首先描述本地代码问题。 捕获目标、症状、错误签名、复现路径、版本、运行时、依赖/框架名称、最近更改、约束和已尝试的修复。如果缺少可发现的事实，在询问之前先检查本地文件/日志。
- 选择证据模式。 对于错误/回归，首先搜索议题、PR、发布和代码。对于能力或工具需求，首先搜索候选仓库。对于功能实现，使用仓库候选和议题/PR/代码证据两者。
- 评估子代理的用处。 在进行大量 GitHub 研究之前，决定条件性子代理工作是否能提高广度、证据质量或审查覆盖范围。如果不使用子代理，在报告搜索路径时简要说明原因。
- 创建定向搜索。 优先使用精确的错误文本、包/API 名称、版本号、框架 + 症状、文件名、配置键、堆栈跟踪片段、失败的命令名称或能力 + 框架/运行时/API 名称。
- 在相关时找到合适的 GitHub 项目。 优先选择匹配度高、Star 数高、活跃、非归档且具有清晰许可证和真实示例的仓库。当高 Star 数集过于宽泛或错过确切问题时，降低 Star 数的阈值。
- 搜索开源证据表面。 在相关的开源仓库中使用议题、PR、讨论、代码、示例、发布说明和官方项目文档。当项目本身可能解决问题时，仓库搜索是必需的。
- 首先按问题匹配度排序，Star 数作为成熟度信号。 高 Star 数仓库是检查的有力候选，但维护者确认的议题、已合并的 PR、已发布的修复、官方示例和精确匹配的代码胜过流行的相邻项目。当排序很重要时，使用 research-rubric.md。
- 深度阅读最强的项目和证据。 使用 extraction-playbook.md 提取项目基础信息、可复用表面、根因或实现模式、版本约束、风险、适配边界和验证步骤。
- 以最小适配转化到本地工作。 保留经过验证的工作流、API、配置结构或架构。仅适应用户本地接口、配置、数据/认证模型、部署目标或语言/运行时所需的部分。
- 在声称成功前进行验证。 使用适用于本地问题的测试、构建、复现命令、真实请求、日志、浏览器检查或手动检查。
- 如果证据薄弱，明确指出。 不要将薄弱的匹配强行转化为自信的建议。当开源证据不足时，将建议标记为基于首原则或仅限本地。
子代理/并行研究指导
子代理是有条件的研究辅助手段，而不是默认要求。控制器仍然负责问题框架、范围控制、证据排序、本地适配和最终验证。
当至少满足以下一种情况时使用子代理：
- 问题涉及 2 个或更多独立的生态系统、框架、语言、工具、部署面或 GitHub 社区。
- 仓库发现需要在多个查询系列中覆盖广泛的候选。
- 议题、PR、讨论、代码、发布和示例证据可以按项目、版本或搜索表面清晰地分割。
- 最终推荐受益于独立的证据审查、风险审查或候选拒绝审查。
当满足以下任何一种情况时，不要使用子代理：
- 任务是一个狭窄的错误，只有一个明显的包、仓库、API 或维护者表面。
- 在外部研究可安全进行之前，必须先了解本地仓库上下文、日志、配置或复现细节。
- GitHub 速率限制、授权边界、私有仓库、秘密、生产数据或敏感日志会使委托有风险。
- 子代理主要会重复相同的搜索或编辑相同的本地文件。
当使用子代理时，控制器必须：
- 定义每个子代理的查询系列、仓库范围、证据表面、约束、允许的写入范围和预期输出。
- 要求直接链接、验证后的元数据、问题匹配理由、风险说明和明确的拒绝原因。
- 除非单独的实现阶段有狭窄的允许写入范围，否则保持子代理为只读。
- 在排序前合并并去重结果；不要将同一议题、PR、代码路径或仓库的重复报告视为独立证据。
- 在最终确定之前，使用
gh、源码读取、测试、日志、真实请求或官方文档直接验证最强的声明。
优先使用 GitHub CLI
将 GitHub CLI (gh) 作为默认的搜索和检查表面。优先使用 gh search repos、gh search issues、gh search prs、gh search code、gh repo view、gh issue view、gh pr view 和 gh api，而不是浏览器抓取或自定义脚本。不要为这个技能添加或依赖捆绑的搜索脚本。
使用以下简短命令模板作为起点，然后根据本地问题调整查询、仓库、字段和限制：
github search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
github search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
github search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
github search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
github repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
github api -X GET search/repositories -f q='<query> archived:false' -f sort=stars -f order=desc
仅在命令因 403、429、私有仓库授权错误或明确的 gh 未认证消息而失败时运行 gh auth status。如果 GitHub 返回 403/429，在重试、减少广度或切换端点之前，检查发出的速率限制或授权上下文。不要在提示、文件、日志或内存中粘贴或持久化令牌、cookie、私有仓库内容或凭据。
搜索策略
- 从狭窄的查询开始：确切的错误字符串、异常类、CLI 输出、包 + 方法名、配置键或堆栈跟踪片段。
- 添加约束：包/框架版本、语言、平台、部署目标、打包器、数据库、认证提供者或运行时。
- 按此顺序搜索相关表面：议题/PR/讨论、已合并的修复、发布说明/变更日志、示例/模板、源代码，然后才是仓库级别的候选。
- 对于没有错误的实现障碍，搜索所需能力加上框架/运行时/API 名称。
- 对于诸如趋势、热门列表、主题搜索或参与度指标等公共平台数据需求，不要从可视化浏览器抓取开始。首先寻找可复用的公共端点、开源爬虫、归档数据集和 API 字段证据；然后用一个最小的真实请求验证所选源，并明确将匿名热门列表数据与已登录的搜索/主题数据区分开。
- 对于可复用项目发现，按 Star 数排序搜索仓库，然后仅深度阅读与本地问题匹配的候选。记录 Star 数、forks、语言、许可证、活动状态和基本内容。
- 降级过时、版本不匹配、已归档、未解决、推测性或仅基于用户猜测的匹配。
- 仅将 Star 数/forks 用作支持的成熟度上下文和相似匹配仓库之间的决胜因素。它们不能覆盖问题匹配度、维护者确认的证据、已合并的 PR、发布说明、官方示例或可复现的代码。
- 对于安全、认证、支付、基础设施或生产操作，当事实可能发生变化时，将开源发现与当前的官方文档或仓库进行交叉检查。
证据标准
对于每个重要的证据项，确定：
- 精确匹配：相同的错误、行为、API、版本、环境或工作流；
- 证据强度：维护者确认、已合并的 PR、已发布的修复、可复现的代码示例、测试夹具或重复的独立报告；
- 适用性：本地需要满足哪些条件才能使解决方案适用；
- 实现价值：值得适配的补丁、配置、API 使用、依赖版本、工作流、测试或操作模式；
- 当仓库是候选时，项目基本信息：名称、URL、Star 数、forks、语言、许可证、活动状态、基本内容、匹配理由和适配成本；
- 风险：过时版本、未解决的问题、不安全的变通方案、许可证问题、安全/隐私影响、部署不匹配或过于宽泛的更改。
输出合同
当 PavedPath Code 对答案产生实质性影响时，包括：
- 本地问题概况：目标、症状/错误、版本/环境和本地约束；
- 搜索路径：使用的查询或发现方法、搜索的 GitHub/开源表面，以及是否使用或跳过了子代理；
- 子代理轨迹（当使用子代理时）：每个子代理的范围、证据表面、关键发现、被拒绝的候选、去重结果，以及控制器直接验证了哪些声明；
- 项目候选（当 GitHub 项目本身相关时）：仓库链接、Star 数、forks、语言、许可证、活动状态、基本内容、匹配理由以及如何在本地使用；
- 关键证据：指向议题、PR、代码、示例、发布或仓库的链接，附带匹配理由；
- 推荐的解决方案：直接复用什么、本地适配什么、避免复制什么以及为什么它合适；
- 被拒绝或有风险的选项：为什么它们不适用或需要谨慎；
- 验证标准：确认修复所需的测试、构建、复现命令、真实请求或手动检查；
- 置信度标签（当证据薄弱或未找到强大的开源解决方案时）。
当仓库级别的解决方案相关时，包含一个紧凑的项目表格。对于纯议题/PR/代码修复，表格是可选的，但如果影响信任或适用性，则包含仓库上下文。
不要仅用链接、Star 数或流行度排名来回答。不要在没有链接证据的情况下写“常见的 GitHub 模式”。不要让外部示例覆盖本地约束。
对于网站、SaaS、落地页、主题或前端模板候选研究，为每个严肃候选同时包含仓库 URL 和实时预览/演示 URL。如果没有可用的或已验证的预览，明确说明并降级该候选。
迁移说明
github-solution-research 已重命名为 PavedPath Code。以前的行为保持不变；这是针对代码领域 PavedPath 版本的命名和定位更新。新安装应使用 pavedpath-code 技能名称和目标代理运行时的活动技能/指令目录。
安全边界
- 优先于复制代码，阅读模式并复用现有的公共接口。如果必须复用代码，检查许可证并保持归属/义务风险可见。
- 避免对现有开源解决方案进行大规模重写。保持其经过验证的流程完整，仅进行用户问题所需的本地适配。
- 避免从仓库、README、议题、PR 或文档中大量逐字摘录。
- 不要在输出、日志、技能或内存中保存 GitHub 令牌、cookies、私有仓库内容或凭据。
- 不要将令牌、cookies、私有仓库内容、敏感日志、秘密、生产数据或凭据传递给子代理。
- 如果网络访问不可用，声明无法进行开源研究，并将建议标记为仅限本地。