重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
debugging-with-opensrc by blogic-cz/blogic-marketplace
npx skills add https://github.com/blogic-cz/blogic-marketplace --skill debugging-with-opensrc关键:切勿猜测库的工作原理。务必通过阅读实际源代码来验证。
OpenSrc 提供了对本项目中安装的外部库确切版本的访问权限。在做出假设之前,请先使用它。
# 同步所有仓库(在 git clone 后运行)
bun run opensrc:sync
# 获取新包
bun run opensrc:use <package> # npm 包
bun run opensrc:use owner/repo # GitHub 仓库
| 库 | 路径 | 需要关注的内容 |
|---|---|---|
| Effect | Effect-TS/effect/packages/effect/src/ | Schema, Effect.gen, Layer, Context |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
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 |
Error: "X is not a function" or "Cannot read property Y"
→ 在源代码中找到 X/Y 的定义位置
# 使用 CK 语义搜索在 opensrc 中查找
mcp_ck_semantic_search(
query="useSuspenseQuery implementation",
path="opensrc/repos/github.com/TanStack/"
)
# 或者使用 grep 查找特定函数
mcp_grep(
pattern="export function useSuspenseQuery",
path="opensrc/repos/github.com/TanStack/"
)
# 阅读实际的源文件
mcp_read(filePath="opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts")
查找:
错误做法:在网上搜索 "TanStack Form validation issue"
正确做法:
1. 阅读 opensrc/repos/github.com/TanStack/form/packages/react-form/src/useForm.ts
2. 查找验证器接口和预期的返回类型
3. 检查 Standard Schema 集成的工作原理
4. 根据实际实现进行修复
1. 阅读 opensrc/repos/github.com/trpc/trpc/packages/server/src/core/middleware.ts
2. 理解上下文如何流经中间件链
3. 检查 .use() 是否正确返回 opts.next()
1. 阅读 opensrc/repos/github.com/Effect-TS/effect/packages/effect/src/Layer.ts
2. 理解 Layer.effect 与 Layer.succeed 的区别
3. 检查 Context.Tag 的使用模式
1. 阅读 opensrc/repos/github.com/sst/opencode/packages/opencode/src/
2. 查找技能加载逻辑
3. 检查 frontmatter 解析和描述匹配
4. 运行 `opencode debug skill` 进行验证
1. 阅读 opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/
2. 查找会话处理逻辑
3. 检查 cookie 配置和存储
源代码是唯一的真理。
问题: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())
修改技能或 CLAUDE.md 后,在新的会话中进行测试:
# 使用特定模型进行测试(对于非交互式操作使用 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 "potrebujem vytvorit novu tabulku v databaze" 2>&1
# 测试身份验证技能
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "ako pridam protected procedure pre admin" 2>&1
# 列出所有可用技能(验证技能是否已注册)
opencode debug skill
# 检查 OpenCode 版本
opencode --version
# 使用不同模型运行
opencode run -m anthropic/claude-sonnet-4-5 "message"
opencode run -m anthropic/claude-opus-4 "message"
.opencode/skill/<skill-name>/
├── SKILL.md # 主技能文件,包含 frontmatter
└── references/ # 可选的附加文档
├── examples.md
└── patterns.md
---
name: skill-name
description: "ALWAYS LOAD THIS SKILL when: keyword1, keyword2, keyword3. Contains X, Y, Z."
---
# 技能标题
## 内容...
关键见解: description 字段决定了模型何时自动加载该技能。使用:
"ALWAYS LOAD THIS SKILL when: ..." 用于关键技能"LOAD THIS SKILL when: ..." 用于可选技能"tool":"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"'
用于调试 OpenCode 本身:
opensrc/repos/github.com/sst/opencode/packages/opencode/src/
├── skill/ # 技能加载和管理
├── command/ # 自定义命令
├── plugin/ # 插件系统
├── session/ # 会话管理
└── provider/ # 模型提供商
每周安装次数
33
仓库
GitHub 星标
3
首次出现
10 天前
安全审计
安装于
opencode33
claude-code30
codex23
github-copilot22
kimi-cli22
gemini-cli22
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.
# Sync all repos (run after git clone)
bun run opensrc:sync
# Fetch new package
bun run opensrc:use <package> # npm package
bun run opensrc:use owner/repo # GitHub repo
| Library | Path | What 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 |
Error: "X is not a function" or "Cannot read property Y"
→ Find where X/Y is defined in source code
# Use CK semantic search to find in opensrc
mcp_ck_semantic_search(
query="useSuspenseQuery implementation",
path="opensrc/repos/github.com/TanStack/"
)
# Or grep for specific function
mcp_grep(
pattern="export function useSuspenseQuery",
path="opensrc/repos/github.com/TanStack/"
)
# Read the actual source file
mcp_read(filePath="opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts")
Look for:
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
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. 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. 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. Read opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/
2. Find session handling logic
3. Check cookie configuration and storage
Source code is the truth.
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())
After modifying skills or CLAUDE.md, test in a NEW session:
# Test with specific model (use perl timeout for non-interactive)
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
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
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "ako pridam protected procedure pre admin" 2>&1
# List all available skills (verify skill is registered)
opencode debug skill
# Check 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"
.opencode/skill/<skill-name>/
├── SKILL.md # Main skill file with frontmatter
└── references/ # Optional additional docs
├── examples.md
└── patterns.md
---
name: skill-name
description: "ALWAYS LOAD THIS SKILL when: keyword1, keyword2, keyword3. Contains X, Y, Z."
---
# Skill Title
## 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"tool":"skill" call# Look for skill loading in output
perl -e 'alarm 120; exec @ARGV' opencode run -m anthropic/claude-sonnet-4-5 --format json "test prompt" 2>&1 | grep -A5 '"tool":"skill"'
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
Weekly Installs
33
Repository
GitHub Stars
3
First Seen
10 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode33
claude-code30
codex23
github-copilot22
kimi-cli22
gemini-cli22
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
127,000 周安装
Spring Boot Kotlin项目创建指南:使用GitHub Copilot快速搭建全栈应用
7,900 周安装
ASP.NET .NET Framework容器化指南:Windows Docker容器部署完整教程
7,900 周安装
CentOS Linux 问题诊断专家 | RHEL兼容命令与最佳实践解决方案
7,900 周安装
Azure资源健康诊断与修复指南 - 利用日志遥测分析问题
7,900 周安装
Azure成本优化工作流:自动分析IaC与资源,生成成本节约建议与GitHub Issue
7,900 周安装
GitHub Copilot上下文助手 - 智能分析代码依赖,精准定位所需文件
8,000 周安装