# TSL Codegen Toolkit

本工具把 YAML/JSON 录入文件转换为 TSL API skill 使用的 Markdown 函数文档，
并根据 Markdown 重建 `function_index.tsv`

## 目录结构

```text
tools/tsl-codegen/
  ├─ README.md                         使用说明
  ├─ STANDARD.md                       函数文档与录入格式标准
  ├─ examples/
  │   ├─ example.yaml                  YAML 录入例子
  │   └─ example.json                  JSON 录入例子
  ├─ scripts/
  │   ├─ generate.py                    YAML/JSON → Markdown
  │   ├─ lint.py                        Markdown 格式校验
  │   └─ build_index.py                 重建 function_index.tsv
  └─ tests/                             工具测试
```

## 使用顺序

### 1. 进入仓库根目录

先切换到包含 `tools/` 和 `skills/` 的仓库根目录。后续命令都从该目录运行：

```bash
cd /path/to/playbook
```

JSON 使用 Python 标准库，不需要额外安装解析包。YAML 需要安装 `pyyaml`：

```bash
python -m pip install pyyaml
```

### 2. 阅读标准

先阅读 [`STANDARD.md`](STANDARD.md)。其中定义：

- Markdown 函数条目的固定结构
- YAML/JSON 录入字段
- 参数表、返回类型和示例代码规则

录入文件和生成的 Markdown 都必须符合该标准

### 3. 准备自己的 YAML 或 JSON

从以下例子选择一种格式：

- [`examples/example.yaml`](examples/example.yaml)
- [`examples/example.json`](examples/example.json)

例子中的函数是格式示例，不是真实 TSL API。复制例子到自己的工作目录，再修改
`module`、`path` 和 `functions`。例如：

```text
tmp/my-functions.yaml
tmp/my-functions.json
```

一个录入文件对应一个 Markdown 叶子页。录入文件不放入 skill；是否长期保留由
维护者自行决定

### 4. 选择 Skill 中的目标位置

TSL API skill 的相关目录如下：

```text
skills/tsl-api-reference/
  ├─ SKILL.md
  ├─ data/
  │   └─ function_index.tsv
  ├─ references/
  │   └─ codegen/
  │       ├─ builtin/                    playbook 维护
  │       ├─ dotnet/                     playbook 维护
  │       └─ project/                    用户项目文档的默认 scope
  │           └─ <module-dir>/<page>.md
  └─ scripts/
      └─ lookup.py
```

Markdown 目标路径固定为：

```text
skills/tsl-api-reference/references/codegen/<scope>/<module-dir>/<page>.md
```

- `<scope>`：用户文档默认使用 `project`，也可以自定义单级目录名。`builtin` 和
  `dotnet` 由 playbook 项目维护，不应用于存放用户自己的函数文档
- `<module-dir>`：功能分类目录，例如 `base`、`runtime`、`document`
- `<page>.md`：同类函数的叶子文档，例如 `array.md`、`string.md`

录入文件的 `module` 是 Markdown 一级标题，不是目录名。例如：

```text
module: 我的项目 / 数组
path: base/array
目标文件: project/base/array.md
```

查找项目中的现有页面：

```bash
rg --files skills/tsl-api-reference/references/codegen/project
```

生成后可以直接打开目标 Markdown 手动阅读。例如：

```text
skills/tsl-api-reference/references/codegen/project/base/array.md
```

### 5. 生成 Markdown

#### 新建叶子页

目标文件不存在时，可以直接生成到 skill。例如：

```bash
python tools/tsl-codegen/scripts/generate.py tmp/my-functions.yaml
```

JSON 使用相同命令：

```bash
python tools/tsl-codegen/scripts/generate.py tmp/my-functions.json
```

生成器读取录入文件中的 `path`，默认写入
`skills/tsl-api-reference/references/codegen/project/<path>.md`。不指定
`--scope` 时，scope 就是 `project`

需要使用自定义 scope 时，通过 `--scope` 指定单级目录名：

```bash
python tools/tsl-codegen/scripts/generate.py tmp/my-functions.json --scope my-project
```

#### 修改现有叶子页

生成器会整体覆盖 `path` 对应的页面。只有录入文件包含该页面的全部函数时才运行
生成器。只修改现有页面中的少量函数时，应按照 `STANDARD.md` 直接编辑 Markdown

### 6. 手动检查并校验 Markdown

以下命令以新建页面
`skills/tsl-api-reference/references/codegen/project/base/my_functions.md` 为例

先打开文件，检查页面标题、函数签名、参数、返回类型和示例

#### 6.1 格式化表格（可选）

此步骤不是必需的，仅用于对齐 Markdown 表格列宽。使用前需要安装 Node.js，并在
仓库根目录安装 `prettier`：

```bash
npm install --save-dev prettier
```

然后格式化目标文件：

```bash
npx prettier --write skills/tsl-api-reference/references/codegen/project/base/my_functions.md
```

#### 6.2 校验

校验目标文件：

```bash
python tools/tsl-codegen/scripts/lint.py --file skills/tsl-api-reference/references/codegen/project/base/my_functions.md
```

校验整个项目目录：

```bash
python tools/tsl-codegen/scripts/lint.py --dir skills/tsl-api-reference/references/codegen/project
```

使用 `--strict` 时，警告也会导致校验失败

校验器将以下问题视为错误：

- 缺少描述
- 缺少返回类型
- 有参数但没有参数表
- 无参数但存在参数表
- 参数表不是固定三列

以下问题默认作为警告：

- 可选参数说明未以 `可选。` 开头
- tags 行为空

### 7. 更新并验证函数索引

Markdown 确认无误后，重建 TSV：

索引会分别保存函数的 tags 和描述。关键词检索会同时匹配函数名、签名、模块、
tags 和描述

```bash
python tools/tsl-codegen/scripts/build_index.py --skill-dir skills/tsl-api-reference
```

检查 TSV 是否与 Markdown 一致：

```bash
python tools/tsl-codegen/scripts/build_index.py --skill-dir skills/tsl-api-reference --check
```

默认从 `<skill-dir>/references/codegen` 读取 Markdown，并写入
`<skill-dir>/data/function_index.tsv`

最后使用函数名验证 skill 可以检索到新条目。把 `myFunction` 替换为真实函数名：

```bash
python skills/tsl-api-reference/scripts/lookup.py --name myFunction
```

最终提交：

- 新增或修改的 Markdown 叶子页
- `skills/tsl-api-reference/data/function_index.tsv`

TSL API skill 只需要 Markdown 和 TSV。录入用的 YAML/JSON 可以由维护者在自己的
版本库中管理