csh
e1f7ce052c
Bundle the TSL API index and markdown references under the skill, route TSL docs to use it, and update the codegen index generator to maintain the bundled data.
72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
---
|
|
name: tsl-api-reference
|
|
description: "Use when writing or reviewing TSL code and you need authoritative TSL API facts: builtin functions, dotnet functions, module APIs, exact signatures, parameters, return values, examples, or Chinese keyword discovery when the function name is unknown."
|
|
---
|
|
|
|
# TSL API Reference
|
|
|
|
## Overview
|
|
|
|
Use the bundled API index and markdown references in this skill instead of
|
|
guessing from similar languages. The API index is `data/function_index.tsv`
|
|
with `name / scope / module / signature / page / anchor / summary`; the full
|
|
entries live under `references/codegen/`.
|
|
|
|
This skill is for API facts only. For TSL syntax, variables, control flow,
|
|
object model, and runtime language rules, use the TSL syntax documentation or a
|
|
future `tsl-syntax-reference` skill.
|
|
|
|
## Procedure
|
|
|
|
Use this skill's bundled lookup script. In the commands below,
|
|
`<this-skill-dir>` means the directory containing this `SKILL.md`; replace it
|
|
with the actual skill directory before running.
|
|
|
|
The script resolves bundled `data/` and `references/` relative to its own file.
|
|
|
|
1. If the function name is known, run exact lookup:
|
|
|
|
```bash
|
|
python <this-skill-dir>/scripts/lookup.py --name argmax
|
|
```
|
|
|
|
Use the returned entry body for the exact signature, parameters, return
|
|
value, examples, and source location.
|
|
|
|
2. If only the intended behavior is known, run keyword discovery:
|
|
|
|
```bash
|
|
python <this-skill-dir>/scripts/lookup.py --kw 数组 排序
|
|
```
|
|
|
|
Terms are matched with AND semantics over `name`, `signature`, `module`, and
|
|
`summary`. Pick a candidate, then run `--name` for the complete entry.
|
|
|
|
3. Use `--limit N` when keyword discovery returns too many rows.
|
|
|
|
4. Use `--tsv /abs/path/function_index.tsv` only when testing or overriding the
|
|
bundled index. The normal installed skill is self-contained and does not
|
|
require the full playbook repository.
|
|
|
|
## Output Contract
|
|
|
|
- Exact mode prints each matching markdown entry body plus its
|
|
`scope/module · page#anchor` source marker.
|
|
- Keyword mode prints `# N matches`, then
|
|
`name / signature / page#anchor / summary` rows.
|
|
|
|
## Failure Handling
|
|
|
|
- If exact lookup has no match, retry with Chinese keywords.
|
|
- If keyword lookup is too broad, add more terms or lower/raise `--limit`.
|
|
- If bundled data is missing, reinstall the skill or pass `--tsv` for debugging.
|
|
- If summaries or index.md counts look stale in an installed skill, reinstall
|
|
it. An installed skill is a read-only snapshot: it ships only `lookup.py`, not
|
|
the index generator, so it cannot and need not rebuild anything locally.
|
|
- Rebuilding the index is a playbook-repository maintenance step, not a skill
|
|
operation. Only when developing inside the playbook repo, after editing API
|
|
markdown, rebuild the tsv and every `index.md` by running (from the repo root)
|
|
`python scripts/tsl_codegen_function_index.py`. The leaf pages are the source
|
|
of truth; the tsv and all index pages are derived. Use `--check` to verify
|
|
they are in sync without writing (exits non-zero when stale).
|