playbook/tools/tsl-codegen/README.md

TSL Codegen Toolkit

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

目录结构

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/ 的仓库根目录。后续命令都从该目录运行：

cd /path/to/playbook

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

python -m pip install pyyaml

2. 阅读标准

先阅读 STANDARD.md。其中定义：

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

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

3. 准备自己的 YAML 或 JSON

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

• examples/example.yaml
• examples/example.json

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

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

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

4. 选择 Skill 中的目标位置

TSL API skill 的相关目录如下：

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 目标路径固定为：

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 一级标题，不是目录名。例如：

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

查找项目中的现有页面：

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

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

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

5. 生成 Markdown

新建叶子页

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

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

JSON 使用相同命令：

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 指定单级目录名：

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：

npm install --save-dev prettier

然后格式化目标文件：

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

6.2 校验

校验目标文件：

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

校验整个项目目录：

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

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

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

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

以下问题默认作为警告：

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

7. 更新并验证函数索引

Markdown 确认无误后，重建 TSV：

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

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

检查 TSV 是否与 Markdown 一致：

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 替换为真实函数名：

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 可以由维护者在自己的 版本库中管理