📝 docs(tsl): rebuild canonical syntax and routing manual

docs/tsl/modules/pytsl_api.md

@@ -1,5 +1,15 @@
 # 天软 pyTSL 接口使用说明
 
+文档类型：模块摘要
+是否可直接用于生成代码：仅部分
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：项目级部署文档、官方 pyTSL 详细接口文档、[tsl_python_interop.md](tsl_python_interop.md)、[index.md](index.md)
+
+本页用于确认 pyTSL 的接入方向和最小链路，不替代项目级部署文档或完整接口手册。
+
+- 如果登录方式、凭证来源、环境变量、部署入口、连接上下文或返回结构没有确认，不继续生成接入代码，直接回项目级部署文档或官方 pyTSL 详细接口文档。
+
 ## 定位
 
 - 官方 Python SDK，面向取数/执行/批量/异步与数据转换。
@@ -17,6 +27,12 @@
 - `pip install tspytsl`（在线安装）
 - 离线安装与手动部署
 
+## 同步 / 异步怎么选
+
+- 同步：任务短、交互简单、立即取结果时优先用 `pyTSL.Client`。
+- 异步：任务长、需要并发或批量调度时再看 `pyTSL.AsyncClient` 与 `async_util`。
+- 如果只是先打通最小链路，先用同步客户端，不要一开始就上异步。
+
 ## 核心类与模块
 
 - `pyTSL.Client`：同步客户端
@@ -35,8 +51,31 @@
 - `EncodeStream` / `DecodeStream`
 - `DataFrameToTSArray`
 
+## 最小成功路径
+
+1. 先回项目级部署文档确认登录方式、凭证来源、环境变量和部署入口。
+2. 安装 `tspytsl`。
+3. 创建 `pyTSL.Client(...)`。
+4. 调 `login()` 登录。
+5. 用 `query(...)`、`exec(...)` 或 `call(...)` 执行任务。
+6. 从返回结果里读取你真正需要的内容；常见起手是 `result.dataframe()`。
+7. 完成后显式 `logout()`。
+
+## 返回结果与失败处理
+
+- 常见返回会落在 `TSResultValue` 这一层；真正用之前，先确认你要的是表格、标量还是其他结构。
+- 最小起手路径可以先看 `result.dataframe()` 是否符合预期，再扩展到别的读取方式。
+- 登录、查询和退出应当成对出现；不要把长期未退出的连接当默认用法。
+- 如果失败，先检查安装、登录上下文、查询语句和返回结构，再决定是否切到异步客户端。
+- 如果还不能确认登录方式、凭证来源或返回结构，不继续扩展接入代码，先回项目级部署文档和官方接口文档。
+
 ## 示例（Python）
 
+示例里的 `"user"` / `"password"` 只表示调用外形，不代表项目里的真实登录方式或凭证来源。
+
+代码块身份：配置片段 / 概念骨架
+代码块说明：可参考最小链路，不是已验证可执行示例。
+
 ```python
 import pyTSL