convert-sc-design-hblab

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

convert-sc-design-hblab

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：确定已安装脚本的路径

SKILL_DIR

is the directory containing this skill — the directory from which this

SKILL.md

was loaded. It contains

scripts/read_sheet.py

. Each agent resolves this from its own skill registry; no hardcoded path is needed.

SKILL_DIR

是包含本技能的目录——即加载本

SKILL.md

文件的目录，其中包含

scripts/read_sheet.py

脚本。每个Agent会从自身的技能注册表中获取该路径，无需硬编码路径。

Step 1.5: Extract the spreadsheet ID

步骤1.5：提取表格ID

If the user gave a URL like:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0

The spreadsheet ID is the segment between

/d/

and the next

1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

bash

undefined

如果用户提供的是如下格式的链接：

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0

表格ID位于

/d/

和下一个

之间的部分：

1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

bash

undefined

Extract from URL (bash)

SPREADSHEET_ID=$(echo "$URL" | sed 's|./d/([^/]).*|\1|')


If the user gave a raw alphanumeric ID with no slashes, use it directly.

SPREADSHEET_ID=$(echo "$URL" | sed 's|./d/([^/]).*|\1|')


如果用户提供的是不含斜杠的纯字母数字ID，可直接使用。

Step 2: Fetch sheet data

步骤2：获取表格数据

bash

python3 "$SKILL_DIR/scripts/read_sheet.py" --spreadsheet-id "$SPREADSHEET_ID" --sheet-name <SHEET_NAME>

If the caller already has a Google Sheets tab id from the URL, they can target it directly:

bash

python3 "$SKILL_DIR/scripts/read_sheet.py" --spreadsheet-id "$SPREADSHEET_ID" --gid <GID>

bash

python3 "$SKILL_DIR/scripts/read_sheet.py" --spreadsheet-id "$SPREADSHEET_ID" --sheet-name <SHEET_NAME>

如果调用者已从链接中获取到Google Sheets的标签ID（gid），可直接指定该ID：

bash

python3 "$SKILL_DIR/scripts/read_sheet.py" --spreadsheet-id "$SPREADSHEET_ID" --gid <GID>

Step 2.5: Discover the sheet name

步骤2.5：确定表格名称

If the user did not specify a sheet name, omit

--sheet-name

— the script reads the first sheet by default. If the user provides both

--sheet-name

and

--gid

--gid

overrides

--sheet-name

To inspect headers and data shape before committing to a format, always run json first:

bash

python3 "$SKILL_DIR/scripts/read_sheet.py" \
  --spreadsheet-id "$SPREADSHEET_ID" \
  --format json

Ask the user whether they want to read additional sheets if the spreadsheet has multiple tabs. Always preserve the full sheet content unless the user explicitly asks for summarization.

如果用户未指定表格名称，可省略

--sheet-name

参数——脚本默认读取第一个表格。如果用户同时提供

--sheet-name

和

--gid

参数，

--gid

参数会覆盖

--sheet-name

的设置。

在确定输出格式前，建议先以json格式运行脚本，查看表头和数据结构：

bash

python3 "$SKILL_DIR/scripts/read_sheet.py" \
  --spreadsheet-id "$SPREADSHEET_ID" \
  --format json

如果表格包含多个标签页，请询问用户是否需要读取其他标签页。除非用户明确要求摘要，否则请保留表格的完整内容。

Step 3: Classify data shape and format accordingly

步骤3：根据数据结构选择对应格式

After inspecting the JSON output, classify the data:

Shape	Signs	Recommended approach
Tabular	Row 0 = headers, rows 1+ = records	`--format table` , add heading + 1-sentence description
Key-value / config	Two columns (key, value)	Don't use a table — render as `## Key` / value prose
Pivot / cross-tab	First col = label, remaining = categories	`--format table` , note pivot structure above table
Free text / notes	Irregular rows, no clear header	`--format text` , render each row as a paragraph or bullet

查看JSON输出后，对数据进行分类：

数据结构	特征	推荐处理方式
表格型	第0行=表头，第1行及以后=记录	使用 `--format table` 参数，添加标题和1句话描述
键值对/配置型	仅包含两列（键、值）	不使用表格——以 `## 键` / 值的散文形式呈现
透视表/交叉表	第一列=标签，其余列=分类	使用 `--format table` 参数，在表格上方标注透视表结构说明
自由文本/笔记型	行结构不规则，无明确表头	使用 `--format text` 参数，将每一行作为段落或项目符号呈现

Step 4: Write the markdown document

步骤4：编写markdown文档

Structure:

undefined

文档结构：

undefined

<Spreadsheet Title or User-Provided Name>

<表格标题或用户指定名称>

Source: Google Sheet — <Sheet Name> (ID: <SPREADSHEET_ID>)

来源：Google Sheet — <表格名称>（ID：<SPREADSHEET_ID>）

<Section heading derived from content>

<根据内容生成的章节标题>

<Formatted content> ```

Derive the title from context or ask the user.
Always include the source line.

Save to

./docs/<sheet-name-kebab-case>.md

. Create

./docs

first:

mkdir -p ./docs

<格式化后的内容>


- 从上下文提取标题，或询问用户。
- 必须包含来源说明行。
- 保存到`./docs/<sheet-name-kebab-case>.md`路径。请先创建`./docs`目录：`mkdir -p ./docs`

Parameters

参数说明

Parameter	Required	Description
`--spreadsheet-id`	Yes	The Google Spreadsheet ID
`--sheet-name`	No	Sheet name to read. Defaults to the first sheet.
`--gid`	No	Google Sheets tab id / `sheetId` . Overrides `--sheet-name` when both are set.
`--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`	否	要读取的表格名称。默认读取第一个表格。
`--gid`	否	Google Sheets标签页ID / `sheetId` 。当同时设置 `--sheet-name` 时，该参数会覆盖前者。
`--credentials`	否	OAuth凭证路径。默认路径为 `~/.config/google-sheets/oauth-token.json` 。
`--output`	否	输出文件路径。默认输出到标准输出。
`--format`	否	输出格式： `json` （默认）、 `table` 或 `text` 。
`--raw`	否	保留空列，不进行清理。

Example

示例

bash

undefined

bash

undefined

Fetch as JSON

以JSON格式获取数据

python3 "$SKILL_DIR/scripts/read_sheet.py"
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--gid "0"

Fetch as markdown table

以markdown表格格式获取数据

python3 "$SKILL_DIR/scripts/read_sheet.py"
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--sheet-name "Sheet1"
--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"
--gid "0"
--format table
--output ./docs/sheet1.md

undefined

mkdir -p ./docs python3 "$SKILL_DIR/scripts/read_sheet.py"
--spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
--gid "0"
--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"
}

First-Run Setup

首次运行设置

If credentials don't exist at

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

Create a Google Cloud project, enable the Google Sheets API
Create an OAuth 2.0 Desktop app credential → download JSON
Get a refresh token via https://developers.google.com/oauthplayground/
- Use scope:
```
https://www.googleapis.com/auth/spreadsheets.readonly
```

Create the credentials file:

bash

mkdir -p ~/.config/google-sheets
# Write the JSON with client_id, client_secret, refresh_token

For detailed steps, see

docs/troubleshooting.md

in the source repo.

如果

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

路径下不存在凭证：

创建Google Cloud项目，启用Google Sheets API
创建OAuth 2.0桌面应用凭证 → 下载JSON文件
通过https://developers.google.com/oauthplayground/获取刷新令牌
- 使用权限范围：
```
https://www.googleapis.com/auth/spreadsheets.readonly
```

创建凭证文件：

bash

mkdir -p ~/.config/google-sheets
# 写入包含client_id、client_secret、refresh_token的JSON内容

如需详细步骤，请查看源码仓库中的

docs/troubleshooting.md

文件。