Back to Details

debugging-with-opensrc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging with OpenSrc

借助OpenSrc进行调试

Overview

概述

CRITICAL: Never guess how a library works. Always verify by reading the actual source code.
OpenSrc provides access to the exact version of external libraries installed in this project. Use it BEFORE making assumptions.
重要提示：永远不要猜测库的工作方式。务必通过阅读实际源代码来验证。
OpenSrc可让你访问项目中安装的外部库的精确版本。请在做出假设前使用它。

When to Use This Skill

何时使用此Skill

  • Something doesn't work as expected
  • Documentation is unclear or missing
  • Need to understand library internals
  • Debugging integration issues
  • Before implementing patterns with external libraries
  • When error messages are cryptic
  • 功能不符合预期
  • 文档说明不清晰或缺失
  • 需要理解库的内部实现
  • 调试集成问题
  • 在使用外部库实现特定模式之前
  • 错误信息难以理解时

OpenSrc Commands

OpenSrc命令

bash
undefined
bash
undefined

Sync all repos (run after git clone)

Sync all repos (run after git clone)

bun run opensrc:sync
bun run opensrc:sync

Fetch new package

Fetch new package

bun run opensrc:use <package> # npm package bun run opensrc:use owner/repo # GitHub repo
undefined
bun run opensrc:use <package> # npm package bun run opensrc:use owner/repo # GitHub repo
undefined

Available Repos (opensrc/repos/github.com/)

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

LibraryPathWhat to look for
Effect
Effect-TS/effect/packages/effect/src/
Schema, Effect.gen, Layer, Context
TanStack Router
TanStack/router/packages/react-router/src/
createFileRoute, loader, useParams
TanStack Query
TanStack/query/packages/react-query/src/
useSuspenseQuery, queryOptions
TanStack Form
TanStack/form/packages/react-form/src/
useForm, validation
TanStack Start
TanStack/router/packages/start/src/
SSR, server functions
TRPC
trpc/trpc/packages/server/src/
procedures, middleware, routers
Drizzle ORM
drizzle-team/drizzle-orm/drizzle-orm/src/
pgTable, relations, queries
Better Auth
better-auth/better-auth/packages/better-auth/src/
auth config, plugins, sessions
OpenCode
sst/opencode/packages/opencode/src/
skills, commands, plugins
Pino
pinojs/pino/lib/
logger, transports
Sentry
getsentry/sentry-javascript/packages/
SDK, integrations, tracing
库名称路径重点关注内容
Effect
Effect-TS/effect/packages/effect/src/
Schema, Effect.gen, Layer, Context
TanStack Router
TanStack/router/packages/react-router/src/
createFileRoute, loader, useParams
TanStack Query
TanStack/query/packages/react-query/src/
useSuspenseQuery, queryOptions
TanStack Form
TanStack/form/packages/react-form/src/
useForm, validation
TanStack Start
TanStack/router/packages/start/src/
SSR, server functions
TRPC
trpc/trpc/packages/server/src/
procedures, middleware, routers
Drizzle ORM
drizzle-team/drizzle-orm/drizzle-orm/src/
pgTable, relations, queries
Better Auth
better-auth/better-auth/packages/better-auth/src/
auth config, plugins, sessions
OpenCode
sst/opencode/packages/opencode/src/
skills, commands, plugins
Pino
pinojs/pino/lib/
logger, transports
Sentry
getsentry/sentry-javascript/packages/
SDK, integrations, tracing

Debugging Workflow

调试流程

Step 1: Identify the Problem

步骤1：识别问题

Error: "X is not a function" or "Cannot read property Y"
→ Find where X/Y is defined in source code
Error: "X is not a function" or "Cannot read property Y"
→ 查找X/Y在源代码中的定义位置

Step 2: Locate Relevant Source

步骤2：定位相关源代码

bash
undefined
bash
undefined

Use CK semantic search to find in opensrc

使用CK语义搜索在opensrc中查找

mcp_ck_semantic_search( query="useSuspenseQuery implementation", path="opensrc/repos/github.com/TanStack/" )
mcp_ck_semantic_search( query="useSuspenseQuery implementation", path="opensrc/repos/github.com/TanStack/" )

Or grep for specific function

或使用grep查找特定函数

mcp_grep( pattern="export function useSuspenseQuery", path="opensrc/repos/github.com/TanStack/" )
undefined
mcp_grep( pattern="export function useSuspenseQuery", path="opensrc/repos/github.com/TanStack/" )
undefined

Step 3: Read the Implementation

步骤3：阅读实现代码

bash
undefined
bash
undefined

Read the actual source file

读取实际源文件

mcp_read(filePath="opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts")
undefined
mcp_read(filePath="opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts")
undefined

Step 4: Understand the Expected Behavior

步骤4：理解预期行为

Look for:
  • Function signatures and return types
  • Default values and optional parameters
  • Error handling and edge cases
  • Internal state management
重点关注：
  • 函数签名与返回类型
  • 默认值与可选参数
  • 错误处理与边缘情况
  • 内部状态管理

Common Debugging Scenarios

常见调试场景

Scenario: TanStack Form Validation Not Working

场景：TanStack Form验证不生效

BAD: Search web for "TanStack Form validation issue"
GOOD:
1. Read opensrc/repos/github.com/TanStack/form/packages/react-form/src/useForm.ts
2. Find validator interface and expected return type
3. Check how Standard Schema integration works
4. Fix based on actual implementation
错误做法：在网上搜索“TanStack Form validation issue”
正确做法：
1. 阅读opensrc/repos/github.com/TanStack/form/packages/react-form/src/useForm.ts
2. 查找验证器接口及预期返回类型
3. 查看标准Schema集成的工作方式
4. 根据实际实现进行修复

Scenario: TRPC Procedure Not Receiving Context

场景：TRPC流程未接收Context

1. Read opensrc/repos/github.com/trpc/trpc/packages/server/src/core/middleware.ts
2. Understand how context flows through middleware chain
3. Check if .use() returns opts.next() correctly
1. 阅读opensrc/repos/github.com/trpc/trpc/packages/server/src/core/middleware.ts
2. 理解Context如何在中间件链中传递
3. 检查.use()是否正确返回opts.next()

Scenario: Effect Layer Not Providing Service

场景：Effect Layer未提供服务

1. Read opensrc/repos/github.com/Effect-TS/effect/packages/effect/src/Layer.ts
2. Understand Layer.effect vs Layer.succeed
3. Check Context.Tag usage patterns
1. 阅读opensrc/repos/github.com/Effect-TS/effect/packages/effect/src/Layer.ts
2. 理解Layer.effect与Layer.succeed的区别
3. 查看Context.Tag的使用模式

Scenario: OpenCode Skill Not Loading

场景：OpenCode Skill未加载

1. Read opensrc/repos/github.com/sst/opencode/packages/opencode/src/
2. Find skill loading logic
3. Check frontmatter parsing and description matching
4. Run `opencode debug skill` to verify
1. 阅读opensrc/repos/github.com/sst/opencode/packages/opencode/src/
2. 查找Skill加载逻辑
3. 检查前置元数据解析及描述匹配情况
4. 运行`opencode debug skill`进行验证

Scenario: Better Auth Session Not Persisting

场景：Better Auth会话未持久化

1. Read opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/
2. Find session handling logic
3. Check cookie configuration and storage
1. 阅读opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/
2. 查找会话处理逻辑
3. 检查Cookie配置与存储设置

Key Principle

核心原则

Source code is the truth.
  • Documentation can be outdated
  • Stack Overflow answers may not apply to your version
  • Blog posts may use different configurations
  • Only the source code shows exactly what happens
源代码才是真相。
  • 文档可能已过时
  • Stack Overflow的答案可能不适用于你的版本
  • 博客文章可能使用不同的配置
  • 只有源代码能准确展示实际运行逻辑

Example: Full Debugging Session

示例：完整调试会话

Problem: useSuspenseQuery returns undefined even though data is in cache

Step 1: Check TanStack Query source
→ Read opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts

Step 2: Find the issue
→ Discover that useSuspenseQuery requires queryOptions() wrapper, not raw object

Step 3: Verify in project
→ Check how other components use it successfully

Step 4: Fix
→ Change from trpc.x.useQuery() to useSuspenseQuery(trpc.x.queryOptions())
问题：useSuspenseQuery在缓存中已有数据的情况下仍返回undefined

步骤1：查看TanStack Query源代码
→ 阅读opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts

步骤2：定位问题
→ 发现useSuspenseQuery需要用queryOptions()包装，而不能直接传入原始对象

步骤3：在项目中验证
→ 查看其他组件如何成功使用该函数

步骤4：修复
→ 从trpc.x.useQuery()改为useSuspenseQuery(trpc.x.queryOptions())

OpenCode Agent Infrastructure

OpenCode Agent基础设施

Testing Skills and CLAUDE.md Changes

测试Skills与CLAUDE.md变更

After modifying skills or CLAUDE.md, test in a NEW session:
bash
undefined
修改Skills或CLAUDE.md后，请在新会话中进行测试：
bash
undefined

Test with specific model (use perl timeout for non-interactive)

使用指定模型测试（使用perl timeout实现非交互式运行）

perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "your test prompt" 2>&1
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "your test prompt" 2>&1

Examples:

示例：

Test database skill autoloading

测试数据库Skill自动加载

perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "potrebujem vytvorit novu tabulku v databaze" 2>&1
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "potrebujem vytvorit novu tabulku v databaze" 2>&1

Test auth skill

测试认证Skill

perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "ako pridam protected procedure pre admin" 2>&1
undefined
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "ako pridam protected procedure pre admin" 2>&1
undefined

OpenCode Debug Commands

OpenCode调试命令

bash
undefined
bash
undefined

List all available skills (verify skill is registered)

列出所有可用Skills（验证Skill是否已注册）

opencode debug skill
opencode debug skill

Check OpenCode version

检查OpenCode版本

opencode --version
opencode --version

Run with different models

使用不同模型运行

opencode run -m anthropic/claude-sonnet-4-5 "message" opencode run -m anthropic/claude-opus-4 "message"
undefined
opencode run -m anthropic/claude-sonnet-4-5 "message" opencode run -m anthropic/claude-opus-4 "message"
undefined

Skill File Structure

Skill文件结构

.opencode/skill/<skill-name>/
├── SKILL.md              # Main skill file with frontmatter
└── references/           # Optional additional docs
    ├── examples.md
    └── patterns.md
.opencode/skill/<skill-name>/
├── SKILL.md              # 包含前置元数据的主Skill文件
└── references/           # 可选的附加文档
    ├── examples.md
    └── patterns.md

SKILL.md Frontmatter Format

SKILL.md前置元数据格式

yaml
---
name: skill-name
description: "ALWAYS LOAD THIS SKILL when: keyword1, keyword2, keyword3. Contains X, Y, Z."
---
yaml
---
name: skill-name
description: "ALWAYS LOAD THIS SKILL when: keyword1, keyword2, keyword3. Contains X, Y, Z."
---

Skill Title

Skill标题

Content...

内容...


**Key insight:** The `description` field determines when the model loads the skill automatically. Use:

- `"ALWAYS LOAD THIS SKILL when: ..."` for critical skills
- `"LOAD THIS SKILL when: ..."` for optional skills
- Include relevant keywords the user might mention

**关键要点：** `description`字段决定模型何时自动加载该Skill。请遵循以下格式：

- 对于关键Skill，使用`"ALWAYS LOAD THIS SKILL when: ..."`
- 对于可选Skill，使用`"LOAD THIS SKILL when: ..."`
- 包含用户可能提及的相关关键词

Testing Skill Autoloading

测试Skill自动加载

  1. Make changes to skill or CLAUDE.md
  2. Run test in NEW session (skills load at session start)
  3. Check JSON output for 
    "tool":"skill"
    call
  4. Verify skill content was used in response
bash
undefined
  1. 修改Skill或CLAUDE.md
  2. 在新会话中运行测试（Skills在会话启动时加载）
  3. 检查JSON输出中的
    "tool":"skill"
    调用
  4. 验证响应中是否使用了Skill内容
bash
undefined

Look for skill loading in output

在输出中查找Skill加载情况

perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "test prompt" 2>&1 | grep -A5 '"tool":"skill"'
undefined
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "test prompt" 2>&1 | grep -A5 '"tool":"skill"'
undefined

OpenCode Source Code Locations

OpenCode源代码位置

For debugging OpenCode itself:
opensrc/repos/github.com/sst/opencode/packages/opencode/src/
├── skill/          # Skill loading and management
├── command/        # Custom commands
├── plugin/         # Plugin system
├── session/        # Session management
└── provider/       # Model providers
若要调试OpenCode本身，请查看：
opensrc/repos/github.com/sst/opencode/packages/opencode/src/
├── skill/          # Skill加载与管理
├── command/        # 自定义命令
├── plugin/         # 插件系统
├── session/        # 会话管理
└── provider/       # 模型提供商

Remember

请牢记

  1. Read source FIRST - before asking, before web searching
  2. Exact version matters - opensrc has YOUR installed version
  3. Follow the code path - trace from entry point to implementation
  4. Check types - TypeScript types often reveal expected usage
  5. Look at tests - library tests show correct usage patterns
  6. Test in NEW session - skills and CLAUDE.md load at session start
  1. 先读源代码 - 在提问、搜索网络之前先阅读源代码
  2. 精确版本很重要 - opensrc中是你项目已安装的版本
  3. 跟踪代码路径 - 从入口点到实现代码逐步跟踪
  4. 检查类型 - TypeScript类型通常会揭示预期用法
  5. 查看测试用例 - 库的测试用例会展示正确的使用模式
  6. 在新会话中测试 - Skills与CLAUDE.md在会话启动时加载