✨ feat(tsl-codegen): add decoupled documentation toolkit

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.
2026-07-20 09:08:38 +08:00
parent 1d5304e7b6
commit c69278283f
18 changed files with 13955 additions and 12821 deletions
@@ -0,0 +1,230 @@
+# 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 可以由维护者在自己的
+版本库中管理