search-skill-database

用途

该技能用于查询 Notion 中的 Beam Nexus Skills 数据库，帮助用户浏览公司技能库、按条件筛选并发现队友创建的技能。它返回技能元数据，可用于展示或后续导入。

主要能力

查询全部技能或按条件筛选
支持的筛选维度：团队（General、Solutions、Engineering、Sales）、集成（如 Beam AI、Linear）、技能名称（部分匹配、不区分大小写）、创建者（用户 ID）
支持排序（按创建时间或名称）和结果数量限制
输出格式：人类可读文本或 JSON（用于程序化处理）
自动处理分页，并遵循 Notion 每秒 3 次请求的速率限制

使用方式

步骤 1：验证配置

始终先运行配置检查：

python ../../notion-master/scripts/check_notion_config.py

若配置缺失，可运行安装向导：

python ../../notion-master/scripts/setup_notion.py

或参考 ../../notion-master/references/setup-guide.md。

配置正确时预期输出：

✅ ALL CHECKS PASSED
You're ready to use Notion skills

步骤 2：查询数据库

使用 query_db.py 脚本并传入筛选参数：

基本查询（全部技能）：

python ../../notion-master/scripts/query_db.py

按团队筛选：

python ../../notion-master/scripts/query_db.py --team General
python ../../notion-master/scripts/query_db.py --team Solutions

按集成筛选：

python ../../notion-master/scripts/query_db.py --integration "Beam AI"
python ../../notion-master/scripts/query_db.py --integration "Linear"

按名称搜索：

python ../../notion-master/scripts/query_db.py --name notion
python ../../notion-master/scripts/query_db.py --name agent

组合筛选：

python ../../notion-master/scripts/query_db.py --team Solutions --integration "Beam AI"

排序与限制：

python ../../notion-master/scripts/query_db.py --sort name --limit 10

步骤 3：展示结果

脚本自动以可读格式展示结果，例如：

[RESULTS] Found 5 skills

1. beam-list-agents
   Team: Solutions
   Description: List all agents in Beam AI workspace...
   Integrations: Beam AI
   Created: 2025-12-01
   URL: https://notion.so/...

2. query-notion-db
   Team: General
   Description: Query Notion databases with filters...
   Integrations: Notion
   Created: 2025-11-15
   URL: https://notion.so/...

JSON 输出（用于程序化使用）：

python ../../notion-master/scripts/query_db.py --json

返回包含完整元数据的技能对象 JSON 数组。

步骤 4：用户选择（可选）

展示结果后，可询问用户要导入哪个技能：

Which skill would you like to import? (1-5, or 'none')

若用户选择某个技能：

从结果中获取页面 ID
触发 import-skill-to-nexus 技能并传入页面 ID

可用筛选参数

筛选	标志	示例	说明
团队	`--team`	`--team General`	General、Solutions、Engineering、Sales
集成	`--integration`	`--integration "Beam AI"`	技能集成的工具
名称	`--name`	`--name notion`	技能名称部分匹配
创建者	`--owner`	`--owner user-id`	按创建者（用户 ID）筛选
排序	`--sort`	`--sort name`	created（默认）或 name
限制	`--limit`	`--limit 10`	返回的最大结果数

错误处理

常见错误及解决方案：

错误	原因	解决方案
401 Unauthorized	API 密钥无效	检查 `.env` 中的 `NOTION_API_KEY`
404 Not Found	数据库 ID 不正确	验证 `.env` 中的 `NOTION_SKILLS_DB_ID`
No results found	筛选条件过于严格	尝试更宽泛的筛选
Network timeout	连接问题	检查网络，重试

详细故障排除请参考 ../../notion-master/references/error-handling.md。

与其他技能的集成

典型工作流：

query-notion-db（查找技能）
import-skill-to-nexus（下载所选技能）

示例：

用户: "Find Beam AI skills in Notion"

AI: [运行 query_db.py --integration "Beam AI"]
    [显示 3 条结果]

    Which would you like to import?

用户: "Number 2"

AI: [触发 import-skill-to-nexus 并传入页面 ID]
    [下载并安装技能]

高级用法

自定义数据库查询：若脚本筛选无法满足需求，可直接使用 Notion API，参考 ../../notion-master/references/api-reference.md
数据库模式参考：../../notion-master/references/database-schema.md

注意事项

分页：脚本自动处理分页（获取全部结果）
速率限制：Notion 允许每秒 3 次请求（脚本已处理）
数据库 ID：默认为 Beam Nexus Skills（2bc2cadf-bbbc-80be-af8a-d45dfc8dfa2e）
团队筛选：精确匹配团队名称（区分大小写）
名称筛选：部分匹配，不区分大小写
版本：2.0
创建：2025-11-04
更新：2025-12-10
状态：Production Ready

适用场景

发现队友创建的技能
查找特定集成（如 Beam AI、Linear 等）的技能
在创建新技能前检查是否已存在
按团队（General、Solutions、Engineering、Sales）浏览技能

限制

依赖 Notion API 和正确的配置（API 密钥、数据库 ID）
团队筛选区分大小写
时间估算：1-2 分钟