mcpField
D
debugging-with-opensrc

debugging-with-opensrc

github.com/blogic-cz开发389 次安装3 天前更新
代码仓库

关于 debugging-with-opensrc

面向开发者的第三方库调试技能，优先读取 OpenSrc 中与已安装依赖对应的源码镜像，并沿调用路径排查，再据此修改和验证应用代码。

主要功能

  1. 01检查已安装依赖的源码
  2. 02追踪从 API 到内部实现的调用
  3. 03核对签名、默认值与错误路径
  4. 04以类型和测试作为证据
  5. 05验证针对性修复

适用场景

  1. 01排查库集成故障
  2. 02解决文档与运行行为不符
  3. 03确认依赖在边缘情形下的表现

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/blogic-cz/blogic-marketplace --skill debugging-with-opensrc

安装后在 Claude Code 中输入/debugging-with-opensrc确认已加载。

附带文件references/opencode-skill-testing.md

详细介绍

使用 OpenSrc 调试

概述

先阅读源代码，再调试外部库的行为。

将 OpenSrc 镜像视为已安装版本的事实来源。

何时使用此技能

  • 调查应用代码依赖第三方库内部实现的集成问题。
  • 解决文档与实际运行行为不一致的问题。
  • 确认已安装依赖中的预期函数签名、默认值、错误路径或边缘情况处理。

OpenSrc 命令

# Sync configured repos when the OpenSrc config exists
test ! -f opensrc/sources.json || \
bun run scripts/opensrc-sync.ts

# Fetch a package or GitHub repo
bunx opensrc --modify false <package-or-owner/repo>

可用仓库（opensrc/repos/github.com/）

库路径查找内容
EffectEffect-TS/effect/packages/effect/src/Schema、Effect.gen、Layer、Context
TanStack RouterTanStack/router/packages/react-router/src/createFileRoute、loader、useParams
TanStack QueryTanStack/query/packages/react-query/src/useSuspenseQuery、queryOptions
TanStack FormTanStack/form/packages/react-form/src/useForm、验证
TanStack StartTanStack/router/packages/start/src/SSR、服务端函数
TRPCtrpc/trpc/packages/server/src/procedures、middleware、routers
Drizzle ORMdrizzle-team/drizzle-orm/drizzle-orm/src/pgTable、relations、queries
Better Authbetter-auth/better-auth/packages/better-auth/src/身份验证配置、插件、会话
OpenCodesst/opencode/packages/opencode/src/技能、命令、插件
Pinopinojs/pino/lib/日志记录器、传输器
Sentrygetsentry/sentry-javascript/packages/SDK、集成、追踪

调试工作流

  1. 用一句话描述失败行为（输入、观察到的输出、预期输出）。
  2. 确定涉及的具体依赖项和软件包区域。
  3. 使用可用的项目搜索工具，在 opensrc/repos/github.com/ 中查找相关源文件。
  4. 在更改应用代码之前，先阅读实现和相关类型。
  5. 从公共 API 到内部辅助函数，追踪调用流程。
  6. 提取具体预期：
    • 函数签名和返回类型
    • 必需的包装器、构建器或选项
    • 默认值和可选参数的行为
    • 错误处理和边缘情况
  7. 根据已验证的行为，在应用代码中应用修复。
  8. 使用有针对性的测试或复现步骤进行验证。

常见调试场景

场景：TanStack Form 验证不起作用
  1. 阅读 opensrc/repos/github.com/TanStack/form/packages/react-form/src/useForm.ts。
  2. 检查验证器接口和预期返回类型。
  3. 确认当前安装版本中 Standard Schema 集成的接入方式。
  4. 根据已验证的行为修复应用代码。
场景：TRPC 过程未收到上下文
  1. 阅读 opensrc/repos/github.com/trpc/trpc/packages/server/src/core/middleware.ts。
  2. 追踪上下文如何通过中间件链传递。
  3. 确认当前版本中的中间件返回值和 opts.next() 行为。
场景：Effect Layer 未提供服务
  1. 阅读 opensrc/repos/github.com/Effect-TS/effect/packages/effect/src/Layer.ts。
  2. 比较 Layer.effect 和 Layer.succeed 的行为。
  3. 根据库中的用法模式，确认 Context.Tag 的用法。
场景：Better Auth 会话未持久化
  1. 阅读 opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/。
  2. 追踪会话处理和持久化流程。
  3. 确认已安装代码中的 Cookie／存储预期。

关键原则

源代码才是事实。

  • 文档可能已经过时
  • Stack Overflow 上的回答可能不适用于你的版本
  • 博客文章可能使用了不同的配置
  • 只有源代码才能准确展示实际发生的情况

示例：完整的调试过程

问题：尽管存在缓存数据，useSuspenseQuery 仍返回 undefined。

  1. 阅读 opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts 及其附近的类型定义。
  2. 确认已安装版本所期望的输入形式。
  3. 在项目代码中确认成功的用法。
  4. 应用符合已验证预期的修复。

注意：某次对特定版本的调查发现，通过 queryOptions() 包装输入可以解决问题。这只是一个示例发现，并非通用规则。

OpenCode 专属内部机制

调试 OpenCode 技能加载或自动加载测试内部机制时，请使用 references/opencode-skill-testing.md。

请记住

  1. 先阅读源代码——先于提问和网络搜索
  2. 精确版本很重要——opensrc 中的是你安装的版本
  3. 沿代码路径追踪——从入口点追踪到实现
  4. 检查类型——TypeScript 类型通常会揭示预期用法
  5. 查看测试——库的测试会展示正确的用法

评论

支持 Markdown