csh
c69278283f
Generate TSL API Markdown from YAML or JSON into a configurable project scope.\nAdd file and directory lint modes, tags-aware indexing, and keyword search across tags and descriptions.\nBundle the toolkit through the playbook build and sync workflows.
231 lines
6.2 KiB
Markdown
231 lines
6.2 KiB
Markdown
# 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 可以由维护者在自己的
|
||
版本库中管理
|