pavedpath-code

PavedPath Code

PavedPath Code（代码版）可帮助 Agent 避免在软件工程问题上重复造轮子。它会搜索 GitHub 和开源项目中的证据，寻找经过验证的实现路径，然后以最少且可验证的改动，将最可靠的模式适配到本地代码库。

将 GitHub 作为主要证据来源，而不是堆砌链接。目标是明确本地代码问题，在公开代码库、问题、拉取请求、讨论、示例、发行说明和源代码中寻找已有的解决路径，评估证据的可靠程度，然后将最可靠的模式转化为小规模的本地修复、实现路径或验证计划。

这是 PavedPath 的代码专项版本。请勿将其扩展为未来的通用版 PavedPath。它面向软件工程工作：错误、运行时错误、构建／测试／部署失败、依赖问题、框架或 API 的使用、集成障碍、实现模式、工程工具选择，以及开源解决方案的适配。

适用场景

• 运行时、构建、测试、部署、软件包、SDK、API、依赖、框架或集成错误。
• 某项功能的实现因边界情况不明确、缺少使用模式、版本行为不明或 API 契约不确定而受阻。
• 本地问题与维护者或其他开源用户可能已在问题、PR、示例、代码、发行说明或讨论中解决的问题相似。
• 用户询问 GitHub 或开源项目是否已解决某个具体的工程问题。
• 成熟的实现示例或可复用项目能够减少某项特定功能的不确定性。
• 答案应比较合适的 GitHub 代码库，并说明如何在本地适配一条经过验证的路径。

不要将 PavedPath Code 用于文案编辑、代码库本身已有明确答案的纯本地重构、非代码类生活决策、自媒体工作流、学习方法、消费购物决策，或明确禁止开展网络／GitHub 调研的请求。除非用户明确限定并授权访问，否则不要检查私有代码库。

默认工作流

1. 先明确本地代码问题。 记录目标、症状、错误特征、复现路径、版本、运行时、依赖项／框架名称、近期更改、约束条件和已尝试的修复方法。如果缺少可查明的信息，先检查本地文件／日志，再进行询问。
2. 选择证据模式。 对于错误／回归问题，先搜索 issues、PR、版本发布记录和代码。对于能力或工具需求，先搜索候选仓库。对于功能实现，同时使用候选仓库和 issue／PR／代码证据。
3. 评估子 Agent 是否有用。 在开展大量 GitHub 研究前，判断有条件地使用子 Agent 是否能扩大覆盖范围、提高证据质量或改善审查覆盖率。如果不使用子 Agent，报告搜索路径时简要说明原因。
4. 制定有针对性的搜索。 优先搜索精确错误文本、包／API 名称、版本号、框架 + 症状、文件名、配置键、堆栈跟踪片段、失败的命令名称，或能力 + 框架／运行时／API 名称。
5. 在相关时查找合适的 GitHub 项目。 优先选择契合度高、Star 数多、活跃、未归档、许可证明确且包含真实示例的仓库。如果 Star 数多的候选范围太广，或找不到与问题完全匹配的项目，则降低 Star 数门槛。
6. 搜索开源证据来源。 在相关开源仓库中查找 issues、PR、讨论、代码、示例、版本发布说明和官方项目文档。如果某个项目本身可能解决问题，就必须搜索仓库。
7. 先按问题契合度排序，再将 Star 数作为成熟度信号。 Star 数多的仓库是值得检查的有力候选，但维护者确认的 issue、已合并的 PR、已发布的修复、官方示例和完全匹配的代码，比相邻领域的热门项目更有参考价值。需要排序时，使用 research-rubric.md。
8. 深入阅读最有力的项目和证据。 使用 extraction-playbook.md，提取项目基础信息、可复用部分、根本原因或实现模式、版本限制、风险、适配边界和验证步骤。
9. 以最少改动转化为本地工作。 在适用时保留经验证的工作流、API、配置结构或架构。仅针对用户本地的接口、配置、数据／身份验证模型、部署目标或语言／运行时所必需的部分进行调整。
10. 在宣称成功前进行验证。 根据本地问题，使用测试、构建、复现命令、实际请求、日志、浏览器检查或手动检查进行验证。
11. 证据薄弱时如实说明。 不要把薄弱的匹配说成有把握的建议。如果开源证据不足，应注明该建议基于第一性原理或仅适用于本地。

子 Agent / 并行调研指南

子 Agent 是有条件使用的调研辅助工具，并非默认要求。控制者仍需负责界定问题、控制范围、评估证据优先级、结合本地情况调整，并进行最终核验。

符合以下任一条件时，使用子 Agent：

• 问题涉及 2 个或更多彼此独立的生态、框架、语言、工具、部署场景或 GitHub 社区。
• 仓库发现需要覆盖多个查询类别中的大量候选项。
• 可以按项目、版本或搜索范围，清晰拆分 Issue、PR、讨论、代码、发布和示例证据。
• 最终建议经独立证据审查、风险审查或候选项排除审查后会更有依据。

符合以下任一条件时，不要使用子 Agent：

• 任务是一个范围狭窄的错误，且有一个明显相关的软件包、仓库、API 或维护者渠道。
• 必须先了解本地仓库上下文、日志、配置或复现细节，才能安全地界定外部调研范围。
• GitHub 速率限制、授权边界、私有仓库、机密、生产数据或敏感日志会使委派存在风险。
• 子 Agent 大多会重复相同的搜索，或编辑相同的本地文件。

使用子 Agent 时，控制者必须：

• 明确每个子 Agent 的查询类别、仓库范围、证据渠道、约束、允许的写入范围和预期输出。
• 要求提供直接链接、经核实的元数据、问题匹配依据、风险说明和明确的排除理由。
• 除非另有一个允许写入范围明确且狭窄的实施阶段，否则子 Agent 只能读取，不得写入。
• 合并并去重结果后再排序；同一问题、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，再考虑抓取网页或编写自定义脚本。不要为此技能添加或依赖捆绑的搜索脚本。

以下简短命令模板可作为起点，然后根据本地问题调整查询、仓库、字段和数量限制：

gh search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh 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 数、Fork 数、语言、许可证、活跃度和基本内容。
• 降低过时、版本不匹配、已归档、尚未解决、纯属推测或仅基于用户猜测的匹配项的优先级。
• 仅将 Star 数／Fork 数作为成熟度的辅助参考，并在匹配度相近的仓库之间用作决胜因素。它们不能凌驾于问题匹配度、维护者确认的证据、已合并的 PR、发行说明、官方示例或可复现代码之上。
• 对于安全、身份验证、支付、基础设施或生产运维问题，如果相关事实可能已发生变化，应将开源资料与当前官方文档或仓库交叉核对。

证据标准

对于每项重要证据，请明确指出：

• 精确匹配：错误、行为、API、版本、环境或工作流是否相同；
• 证据强度：维护者确认、已合并的 PR、已发布的修复、可复现的代码示例、测试夹具或多次独立报告；
• 适用性：本地必须满足哪些条件，解决方案才适用；
• 实现价值：值得借鉴的补丁、配置、API 用法、依赖版本、工作流、测试或运维模式；
• 项目基本信息（如果候选项是某个仓库）：名称、URL、Star 数、Fork 数、语言、许可证、活跃度、基本内容、匹配理由和改造成本；
• 风险：版本过旧、问题尚未解决、不安全的变通方案、许可证问题、安全／隐私影响、部署不匹配或改动范围过大。

输出约定

当 PavedPath Code 对答案产生实质影响时，请包含：

• 本地问题概况：目标、症状／错误、版本／环境，以及本地限制；
• 搜索路径：使用的查询或发现方法、搜索过的 GitHub／开源渠道，以及是否使用或跳过了子 Agent；
• 子 Agent 追踪记录（使用子 Agent 时）：每个子 Agent 的范围、证据渠道、主要发现、排除的候选项、去重结果，以及主控直接核实的声明；
• 项目候选项（GitHub 项目本身相关时）：仓库链接、Stars、fork 数、语言、许可证、活跃度、基本内容、匹配理由，以及如何在本地使用；
• 关键证据：相关问题、PR、代码、示例、发布版本或仓库的链接，以及匹配理由；
• 推荐方案：哪些内容可直接复用、哪些内容需在本地调整、哪些内容应避免照搬，以及它为何适用；
• 排除或有风险的选项：说明为何不适用或需要谨慎；
• 验证标准：确认修复所需的测试、构建、复现命令、真实请求或手动检查；
• 证据较弱或未找到有力的开源方案时，标注置信度。

如果相关的是仓库级解决方案，请附上一张简洁的项目表。对于纯粹的问题／PR／代码修复，表格可选；但如果仓库背景会影响可信度或适用性，请包含相关信息。

不要只给出链接、Stars 数或热度排名。不要在没有附上证据链接的情况下写“GitHub 上的常见模式”。不要让外部示例凌驾于本地限制之上。

对于网站、SaaS、落地页、主题或前端模板候选项研究，每个严肃候选项都必须同时提供仓库 URL 和在线预览／演示 URL。如果没有可用或已验证的预览，请明确说明，并降低该候选项的评价。

迁移说明

github-solution-research 已更名为 PavedPath Code。此前的行为保持不变；此更新仅针对 PavedPath 的代码专用版本进行命名和定位调整。新安装应使用 pavedpath-code 技能名称，以及目标 Agent 运行时当前使用的技能／指令目录。

安全边界

• 优先阅读已有模式并复用现有公共接口，而不是复制代码。若必须复用代码，请检查许可证，并明确标示署名／义务方面的风险。
• 避免大幅改写现有开源解决方案。保留其经验证的流程，只针对用户的问题做必要的本地调整。
• 避免大段照搬仓库、README、问题、PR 或文档中的内容。
• 不要在输出、日志、技能或记忆中保存 GitHub 令牌、Cookie、私有仓库内容或凭证。
• 不要向子 Agent 传递令牌、Cookie、私有仓库内容、敏感日志、密钥、生产数据或凭证。
• 如果无法访问网络，请说明无法进行开源研究，并将建议标记为仅适用于本地。