gsheet2md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gsheet2md

Read a Google Sheet by

SPREADSHEET_ID

and turn the result into usable markdown.

通过

SPREADSHEET_ID

读取Google Sheet，并将结果转换为可用的Markdown格式。

Requirements

要求

OAuth credentials at

~/.config/google-sheets/oauth-token.json

with:

```
client_id
```
```
client_secret
```
```
refresh_token
```

Google Sheets API enabled for that OAuth app

需在

~/.config/google-sheets/oauth-token.json

路径下存放OAuth凭证，包含：

```
client_id
```
```
client_secret
```
```
refresh_token
```

该OAuth应用需启用Google Sheets API

Output Policy

输出规则

Use the installed script from the skill directory, but write any authored markdown into
```
./docs
```
of the current workspace.
If
```
./docs
```
does not exist, create it before writing files.
Do not save generated documents into the installed skill directory.

使用技能目录中已安装的脚本，但需将生成的Markdown文件写入当前工作区的
```
./docs
```
目录。
若
```
./docs
```
目录不存在，需先创建再写入文件。
请勿将生成的文档保存到已安装的技能目录中。

Usage

使用方法

Step 1: Resolve the installed script path

步骤1：确定已安装脚本的路径

Find the directory that contains this

SKILL.md

. The Python script lives at:

bash

<skill-dir>/scripts/read_sheet.py

找到包含此

SKILL.md

的目录。Python脚本位于：

bash

<skill-dir>/scripts/read_sheet.py

Step 2: Fetch sheet data

步骤2：获取表格数据

bash

python3 <skill-dir>/scripts/read_sheet.py --spreadsheet-id <SPREADSHEET_ID> --sheet-name <SHEET_NAME>

bash

python3 <skill-dir>/scripts/read_sheet.py --spreadsheet-id <SPREADSHEET_ID> --sheet-name <SHEET_NAME>

Step 3: Convert to readable markdown

步骤3：转换为易读的Markdown格式

After fetching the sheet data, the agent should turn it into a well-structured markdown document.

The agent is responsible for:

Understanding the data structure
Formatting sections with clear headings, tables, and lists
Writing short descriptions where needed
Organizing the content for human readers
Saving the final markdown file under
```
./docs/<derived-sheet-name>.md
```
in the current workspace

获取表格数据后，Agent需要将其转换为结构清晰的Markdown文档。

Agent需负责：

理解数据结构
使用清晰的标题、表格和列表格式化内容
必要时添加简短说明
整理内容以方便人类阅读
将最终的Markdown文件保存到当前工作区的
```
./docs/<derived-sheet-name>.md
```
路径下

Parameters

参数

Parameter	Required	Description
`--spreadsheet-id`	Yes	The Google Spreadsheet ID
`--sheet-name`	No	Sheet name to read. Defaults to the first sheet.
`--credentials`	No	OAuth credentials path. Defaults to `~/.config/google-sheets/oauth-token.json` .
`--output`	No	Output file path. Defaults to stdout.
`--format`	No	Output format: `json` (default), `table` , or `text` .
`--raw`	No	Keep empty columns instead of cleaning them.

参数	是否必填	描述
`--spreadsheet-id`	是	Google电子表格ID
`--sheet-name`	否	要读取的表格名称，默认读取第一个表格
`--credentials`	否	OAuth凭证路径，默认路径为 `~/.config/google-sheets/oauth-token.json`
`--output`	否	输出文件路径，默认输出到标准输出(stdout)
`--format`	否	输出格式： `json` （默认）、 `table` 或 `text`
`--raw`	否	保留空列，不进行清理

Example

示例

bash

undefined

bash

undefined

Fetch as JSON

以JSON格式获取数据

python3 <skill-dir>/scripts/read_sheet.py
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--sheet-name "Sheet1"

Fetch as markdown table

以Markdown表格格式获取数据

python3 <skill-dir>/scripts/read_sheet.py
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--format table

Save raw output directly into the current workspace docs folder

将原始输出直接保存到当前工作区的docs文件夹

mkdir -p ./docs python3 <skill-dir>/scripts/read_sheet.py
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--format table
--output ./docs/sheet1.md

undefined

mkdir -p ./docs python3 <skill-dir>/scripts/read_sheet.py
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--format table
--output ./docs/sheet1.md

undefined

OAuth Credentials Format

OAuth凭证格式

json

{
  "type": "oauth",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "refresh_token": "your-refresh-token"
}

json

{
  "type": "oauth",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "refresh_token": "your-refresh-token"
}

Workflow For Markdown Output

Markdown输出工作流程

Run the script to fetch the sheet data.
Inspect the returned structure before formatting it.
Ensure
```
./docs
```
exists in the current workspace. If
```
./docs
```
does not exist, create it.
Write a markdown document that matches the content shape instead of forcing a fixed template.
Save the markdown document under
```
./docs/
```
using a filename derived from the sheet name.

运行脚本获取表格数据。
在格式化前检查返回的数据结构。
确保当前工作区中存在
```
./docs
```
目录，若不存在则创建。
根据内容结构编写Markdown文档，而非强制使用固定模板。
使用从表格名称衍生的文件名，将Markdown文档保存到
```
./docs/
```
目录下。