使用 AI Agent 查询 MatrixOne 文档

MatrixOne 文档查询 Skill 用于让 AI Agent 从终端检索 MatrixOne 官方文档，适合查询 SQL 语法、内置函数、操作符、MySQL 兼容性和 MatrixOne 方言行为。

获取文件

推荐下载完整 ZIP，解压后即可获得保持原始目录结构的全部 skill 文件：

下载 matrixone-docs-main.zip

也可以按需下载单个文件：

文件	用途
SKILL.md	Codex skill 说明文件
README.md	独立使用说明
fetch-index.sh	下载并缓存 LLM 索引文件
search-docs.sh	在缓存索引中搜索关键词
read-doc.sh	根据搜索结果中的 doc_path 读取文档正文

可以直接下载整个目录中的文件并保持以下结构：

matrixone-docs-main/
├── README.md
├── SKILL.md
└── scripts/
    ├── fetch-index.sh
    ├── read-doc.sh
    └── search-docs.sh

如果安装到 Codex 的 skill 目录，可以放在：

$CODEX_HOME/skills/matrixone-docs/

安装后目录结构示例：

$CODEX_HOME/skills/matrixone-docs/SKILL.md
$CODEX_HOME/skills/matrixone-docs/README.md
$CODEX_HOME/skills/matrixone-docs/scripts/fetch-index.sh
$CODEX_HOME/skills/matrixone-docs/scripts/search-docs.sh
$CODEX_HOME/skills/matrixone-docs/scripts/read-doc.sh

使用方式

首次使用某个文档版本时，先下载索引：

export MO_DOCS_VERSION="3.0.13"
bash scripts/fetch-index.sh

搜索 SQL 语法：

bash scripts/search-docs.sh "CREATE TABLE" --kind sql --limit 5

搜索内置函数：

bash scripts/search-docs.sh "DATE_FORMAT" --kind function

搜索操作符：

bash scripts/search-docs.sh "LIKE" --kind operator

读取搜索结果中的文档：

bash scripts/read-doc.sh "MatrixOne/Reference/Functions-and-Operators/Datetime/date-format/"

长文档可以分页读取：

bash scripts/read-doc.sh "MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-table/" --cursor 0 --limit 500

版本配置

版本可以通过三种方式指定：

方式	示例	优先级
环境变量	export MO_DOCS_VERSION="3.0.13"	最高
命令参数	--version 3.0.13	次高
默认值	3.0.13	最低

索引会缓存在：

cache/v{version}/

例如：

cache/v3.0.13/llms-sql.txt
cache/v3.0.13/llms-func.txt
cache/v3.0.13/llms-op.txt

LLM 索引文件

该 skill 使用官网发布的 LLM 友好索引文件：

文件	--kind	内容
llms-sql.txt	sql	SQL 参考文档
llms-func.txt	function	内置函数文档
llms-op.txt	operator	操作符文档

默认搜索全部三类索引：

bash scripts/search-docs.sh "keyword" --kind all

脚本会按固定模式拼出索引 URL：

https://docs.matrixorigin.cn/en/v26.{MO_DOCS_VERSION}/llms-{kind}.txt

例如 MO_DOCS_VERSION=3.0.13 时：

https://docs.matrixorigin.cn/en/v26.3.0.13/llms-sql.txt

当前脚本不支持传入任意 base URL，也不支持 latest 作为版本号。版本需要使用 x.y.z 格式，例如 3.0.13。

给 Agent 的使用示例

当用户询问 MatrixOne SQL 语法时：

用户：MatrixOne 里 CREATE TABLE 支持 CLUSTER BY 吗？
Agent：
1. bash scripts/fetch-index.sh --version 3.0.13
2. bash scripts/search-docs.sh "CLUSTER BY" --kind sql --version 3.0.13
3. 使用 search-docs.sh 返回的 doc_path 调用 read-doc.sh
4. 根据官方文档回答，并说明对应文档路径

当 SQL 执行失败且怀疑是方言问题时：

用户：这个 MySQL SQL 在 MatrixOne 里报错，帮我确认语法。
Agent：
1. 提取报错中的关键字或语法结构
2. 使用 search-docs.sh 搜索 SQL / function / operator
3. 使用 read-doc.sh 读取匹配文档
4. 对比 MatrixOne 支持情况和用户 SQL

原始文件内容

SKILL.md

---
name: matrixone-docs
description: |
  Use when the user asks about MatrixOne SQL syntax, built-in functions, operators,
  MySQL compatibility, or needs to verify MatrixOne dialect-specific behavior.
  Also use when a run_sql tool returns an error that may be dialect-related, when
  the SQL being written is not standard/common MySQL SQL, or when the user mentions
  MO documentation, MO syntax, or MatrixOne docs lookup.

  Trigger phrases: "MatrixOne 文档", "MO 文档", "查 MatrixOne 语法", "search matrixone docs",
  "MatrixOne 函数", "MO SQL 语法", "MatrixOne operator", "MO docs".
---

# MatrixOne Docs Skill

Search and read MatrixOne official SQL documentation from the terminal.

## Quick Start

```bash
# Set version (optional, defaults to 3.0.13)
export MO_DOCS_VERSION="3.0.13"

# Fetch index files (one-time per version)
bash skills/matrixone-docs/scripts/fetch-index.sh

# Search for a keyword
bash skills/matrixone-docs/scripts/search-docs.sh "DATE_FORMAT"

# Search with filters
bash skills/matrixone-docs/scripts/search-docs.sh "JOIN" --kind sql --limit 5

# Read a document by path
bash skills/matrixone-docs/scripts/read-doc.sh "MatrixOne/Reference/Functions-and-Operators/date-and-time-functions/date-format/"

# Read with pagination
bash skills/matrixone-docs/scripts/read-doc.sh "MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-table/" --cursor 0 --limit 500
```

## When to Use

- User asks about MatrixOne SQL syntax or behavior
- User needs to check MySQL compatibility of a specific feature
- User asks about a MatrixOne built-in function or operator
- User encounters a `run_sql` error or SQL execution failure, especially when the error may be dialect-related
- The SQL being written uses syntax, functions, or operators that are not standard MySQL or look MatrixOne-specific

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/fetch-index.sh` | Download and cache index files from docs.matrixorigin.cn |
| `scripts/search-docs.sh` | Search cached index by keyword with optional kind filter |
| `scripts/read-doc.sh` | Fetch and display a documentation page by path |

## Version Configuration

The version can be set via:

1. `MO_DOCS_VERSION` environment variable (highest priority)
2. `--version` flag on each script
3. Default: `3.0.13`

Index files are cached per version under `skills/matrixone-docs/cache/v{version}/`.

## Common Mistakes

- **Searching before fetching**: `search-docs.sh` / `read-doc.sh` require cached indexes. Run `fetch-index.sh` first for each new version.
- **Wrong version format**: version must be `x.y.z` (e.g. `3.0.13`). `3.0` or `latest` will fail.
- **Using full URL instead of doc_path**: `read-doc.sh` expects the path segment only (e.g. `MatrixOne/Reference/.../date-format/`), not the full `https://...` URL.
- **Forgetting `--kind` filter**: searching a common keyword like `SELECT` without `--kind sql` may return functions and operators too. Use `--kind` to narrow results.

## Document Kinds

| Kind | Index File | Description |
|------|-----------|-------------|
| `sql` | llms-sql.txt | SQL reference (DDL, DML, etc.) |
| `function` | llms-func.txt | Built-in functions |
| `operator` | llms-op.txt | Operators |
| `all` | (all three) | Search across all kinds |

fetch-index.sh

#!/usr/bin/env bash
set -euo pipefail

# Resolve skill root regardless of CWD (scripts can be invoked from repo root or elsewhere).
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
CACHE_DIR="$SKILL_DIR/cache"

usage() {
  cat <<'EOF'
Usage: fetch-index.sh [--version <x.y.z>]

Download MatrixOne documentation index files from docs.matrixorigin.cn
and cache them locally under skills/matrixone-docs/cache/v{version}/.

Environment:
  MO_DOCS_VERSION    Doc version (default: 3.0.13), overridden by --version.
EOF
  exit 0
}

VERSION="${MO_DOCS_VERSION:-3.0.13}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --version) VERSION="$2"; shift 2 ;;
    -h|--help) usage ;;
    *) echo "Unknown option: $1"; usage ;;
  esac
done

if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "Error: invalid version '$VERSION' (expected x.y.z)" >&2
  exit 1
fi

BASE_URL="https://docs.matrixorigin.cn/en/v26.${VERSION}"
DEST="$CACHE_DIR/v${VERSION}"
mkdir -p "$DEST"

KINDS=("sql" "func" "op")
NAMES=("SQL Reference" "Functions" "Operators")
FILES=("llms-sql.txt" "llms-func.txt" "llms-op.txt")

FAILED=0
for i in "${!KINDS[@]}"; do
  KIND="${KINDS[$i]}"
  NAME="${NAMES[$i]}"
  FILE="${FILES[$i]}"
  URL="${BASE_URL}/llms-${KIND}.txt"
  DEST_FILE="$DEST/$FILE"

  echo "Fetching $NAME index ($KIND) from $URL ..."
  if curl -fsSL --connect-timeout 10 --max-time 30 -o "$DEST_FILE" "$URL"; then
    LINES=$(wc -l < "$DEST_FILE" | tr -d ' ')
    echo "  OK: $LINES lines -> $DEST_FILE"
  else
    echo "  FAILED: could not fetch $URL" >&2
    FAILED=1
  fi
done

if [[ $FAILED -eq 1 ]]; then
  echo ""
  echo "Some indexes failed to download. Check your network or the version." >&2
  echo "URL pattern: $BASE_URL/llms-{kind}.txt" >&2
  exit 1
fi

echo ""
echo "Done. Indexes cached at $DEST/"
echo "Run: bash skills/matrixone-docs/scripts/search-docs.sh <keyword>"

search-docs.sh

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
CACHE_DIR="$SKILL_DIR/cache"

usage() {
  cat <<'EOF'
Usage: search-docs.sh <query> [--kind all|sql|function|operator] [--limit <n>] [--version <x.y.z>]

Search cached MatrixOne documentation indexes. Requires fetch-index.sh to have
been run first for the requested version.

Environment:
  MO_DOCS_VERSION    Doc version (default: 3.0.13), overridden by --version.
EOF
  exit 0
}

QUERY=""
KIND="all"
LIMIT=8
VERSION="${MO_DOCS_VERSION:-3.0.13}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --kind)   KIND="$2"; shift 2 ;;
    --limit)  LIMIT="$2"; shift 2 ;;
    --version) VERSION="$2"; shift 2 ;;
    -h|--help) usage ;;
    *) QUERY="$1"; shift ;;
  esac
done

if [[ -z "$QUERY" ]]; then
  echo "Error: query is required" >&2
  usage
fi

if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "Error: invalid version '$VERSION'" >&2
  exit 1
fi

case "$KIND" in
  all|sql|function|operator) ;;
  *) echo "Error: kind must be one of all, sql, function, operator" >&2; exit 1 ;;
esac

INDEX_DIR="$CACHE_DIR/v${VERSION}"
KIND_MAP='sql:llms-sql.txt function:llms-func.txt operator:llms-op.txt'

FILES_TO_SEARCH=()
if [[ "$KIND" == "all" ]]; then
  FILES_TO_SEARCH=("$INDEX_DIR/llms-sql.txt" "$INDEX_DIR/llms-func.txt" "$INDEX_DIR/llms-op.txt")
else
  KIND_KEY="$KIND"
  case "$KIND" in
    sql)      FILENAME="llms-sql.txt" ;;
    function) FILENAME="llms-func.txt" ;;
    operator) FILENAME="llms-op.txt" ;;
  esac
  FILES_TO_SEARCH=("$INDEX_DIR/$FILENAME")
fi

for f in "${FILES_TO_SEARCH[@]}"; do
  if [[ ! -f "$f" ]]; then
    echo "Error: index file not found: $f" >&2
    echo "Run: bash skills/matrixone-docs/scripts/fetch-index.sh --version $VERSION" >&2
    exit 1
  fi
done

# Parse index lines format:
# - [Title](URL) [compatibility]: optional summary
# Match against lowercase query in title, summary, compatibility.
QUERY_LC=$(echo "$QUERY" | tr '[:upper:]' '[:lower:]')
COUNT=0

search_file() {
  local file="$1"
  local tag="$2"
  while IFS= read -r line; do
    [[ $COUNT -ge $LIMIT ]] && return
    # Only process lines starting with "- [title](url) [compat]"
    [[ "$line" == "- ["* ]] || continue

    # Extract title: everything between "- [" and "]("
    local title
    title=$(echo "$line" | sed -n 's/^- \[\(.*\)\](\(.*\)) \[\(.*\)\].*$/\1/p')
    [[ -n "$title" ]] || continue

    # Extract url: between "](" and ")"
    local url
    url=$(echo "$line" | sed -n 's/^- \[.*\](\(.*\)) \[.*\].*$/\1/p')
    [[ -n "$url" ]] || continue

    # Extract compatibility: between "] [" and "]"
    local compat
    compat=$(echo "$line" | sed -n 's/^- \[.*\](.*) \[\(.*\)\].*$/\1/p')

    # Extract optional summary: after the compat bracket
    local summary
    summary=$(echo "$line" | sed -n 's/^- \[.*\](.*) \[.*\]: \(.*\)$/\1/p')

    local haystack
    haystack=$(echo "$title $compat $summary" | tr '[:upper:]' '[:lower:]')
    if [[ "$haystack" != *"$QUERY_LC"* ]]; then
      continue
    fi

    # Extract doc_path from URL: strip https://docs.matrixorigin.cn/en/v26.x.y.z/
    local prefix="https://docs.matrixorigin.cn/en/v26.${VERSION}/"
    local doc_path="${url#$prefix}"

    echo "---"
    echo "title:       $title"
    echo "kind:        $tag"
    echo "compatibility: $compat"
    [[ -n "$summary" ]] && echo "summary:     $summary"
    echo "url:         $url"
    echo "doc_path:    $doc_path"
    COUNT=$((COUNT + 1))
  done < "$file"
}

if [[ "$KIND" == "all" ]]; then
  search_file "${FILES_TO_SEARCH[0]}" "sql"
  search_file "${FILES_TO_SEARCH[1]}" "function"
  search_file "${FILES_TO_SEARCH[2]}" "operator"
else
  search_file "${FILES_TO_SEARCH[0]}" "$KIND"
fi

if [[ $COUNT -eq 0 ]]; then
  echo "No results found for '$QUERY' (kind=$KIND, version=$VERSION)" >&2
  exit 1
fi

read-doc.sh

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
CACHE_DIR="$SKILL_DIR/cache"

usage() {
  cat <<'EOF'
Usage: read-doc.sh <doc_path> [--cursor <n>] [--limit <n>] [--version <x.y.z>]

Read a MatrixOne documentation page by its doc_path. The doc_path is obtained
from search-docs.sh output.

Environment:
  MO_DOCS_VERSION    Doc version (default: 3.0.13), overridden by --version.
EOF
  exit 0
}

DOC_PATH=""
CURSOR=0
LIMIT=8000
VERSION="${MO_DOCS_VERSION:-3.0.13}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --cursor)  CURSOR="$2"; shift 2 ;;
    --limit)   LIMIT="$2"; shift 2 ;;
    --version) VERSION="$2"; shift 2 ;;
    -h|--help) usage ;;
    *) DOC_PATH="$1"; shift ;;
  esac
done

if [[ -z "$DOC_PATH" ]]; then
  echo "Error: doc_path is required" >&2
  usage
fi

if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "Error: invalid version '$VERSION'" >&2
  exit 1
fi

if [[ "$CURSOR" -lt 0 ]]; then
  echo "Error: cursor must be >= 0" >&2
  exit 1
fi

if [[ "$LIMIT" -lt 1 || "$LIMIT" -gt 20000 ]]; then
  echo "Error: limit must be between 1 and 20000" >&2
  exit 1
fi

# Build URL. doc_path may or may not have a trailing slash; strip it for the .md append.
DOC_PATH_CLEAN="${DOC_PATH%/}"
URL="https://docs.matrixorigin.cn/en/v26.${VERSION}/${DOC_PATH_CLEAN}.md"

TMPFILE=$(mktemp /tmp/mo-docs-read.XXXXXX)
trap 'rm -f "$TMPFILE"' EXIT

echo "Fetching $URL ..." >&2
if ! curl -fsSL --connect-timeout 10 --max-time 30 -o "$TMPFILE" "$URL"; then
  echo "Error: failed to fetch $URL" >&2
  exit 1
fi

TOTAL_CHARS=$(wc -m < "$TMPFILE" | tr -d ' ')

if [[ "$CURSOR" -ge "$TOTAL_CHARS" ]]; then
  echo "Error: cursor $CURSOR exceeds total chars $TOTAL_CHARS" >&2
  exit 1
fi

# Extract the requested window.
END=$((CURSOR + LIMIT))
if [[ "$END" -gt "$TOTAL_CHARS" ]]; then
  END="$TOTAL_CHARS"
fi

CONTENT=$(tail -c +$((CURSOR + 1)) "$TMPFILE" | head -c $((END - CURSOR)))
RETURNED=${#CONTENT}

NEXT_CURSOR=0
if [[ "$END" -lt "$TOTAL_CHARS" ]]; then
  NEXT_CURSOR="$END"
fi

echo "doc_path:       $DOC_PATH"
echo "source_url:     $URL"
echo "total_chars:    $TOTAL_CHARS"
echo "cursor:         $CURSOR"
echo "returned_chars: $RETURNED"
echo "next_cursor:    $NEXT_CURSOR"
echo "---"
echo "$CONTENT"