插件 API 参考

TSH 插件是一段 JavaScript 代码，被包裹在 new Function('args', 'stdin', 'host', code) 中执行。插件代码即是函数体，通过 return 返回输出字符串。

函数签名

function(args, stdin, host) {
  // 插件代码（函数体）
  return '输出内容'
}

参数	类型	说明
args	string[]	命令参数数组，args[0] 为命令名，args[1] 起为参数
stdin	string	管道传入的标准输入，无管道时为空字符串
host	object	TSH 宿主桥接对象 window._tsh，提供终端能力

返回值

插件通过 return 返回字符串，内容直接输出到终端。

同步返回

var result = 1 + 1
return 'Result: ' + result + '\r\n'

异步返回

插件可以返回 Promise，TSH 会自动 await：

return fetch('https://api.example.com/data')
  .then(r => r.text())
  .then(text => 'Response: ' + text + '\r\n')

或使用 async IIFE：

return (async function() {
  var resp = await fetch('https://api.example.com/data')
  var data = await resp.json()
  return 'Result: ' + JSON.stringify(data) + '\r\n'
})()

换行符

终端输出使用 \r\n（CRLF）作为换行符，确保跨平台显示一致。

args 参数

args 是字符串数组：

calx 2 + 3
# args[0] = "calx"   (命令名)
# args[1] = "2"
# args[2] = "+"
# args[3] = "3"

常用模式：

// 获取所有参数（去掉命令名）
var expr = args.slice(1).join(' ')

// 无参数时提示用法
if (args.length < 2) {
  return '\x1b[31mUsage: myplugin <arg>\x1b[0m\r\n'
}

stdin 参数

当插件在管道中使用时，stdin 接收前一个命令的输出：

echo "hello" | myplugin
# stdin = "hello"

示例：

var lines = stdin.split('\n')
var count = lines.filter(function(l) { return l.trim() }).length
return 'Line count: ' + count + '\r\n'

host 参数

host 是 window._tsh 桥接对象，提供对 TSH 终端能力的访问。

实验性 API

host 对象的接口可能随版本变化。核心字段如下：

属性/方法	说明
host.term	Xterm.js 终端实例
host.dirHandle	当前授权的根目录句柄
host.cwd	当前工作目录路径
host.execCommand(cmd)	执行 TSH 命令（异步）
host.resolvePath(path)	解析路径到文件/目录句柄（异步）
host.readFile(path)	读取文件内容（异步）
host.writeFile(path, content)	写入文件（异步）

使用示例

// 读取终端宽度
var cols = host.term.cols

// 获取当前目录
var currentDir = host.cwd

// 执行 TSH 命令
var output = await host.execCommand('ls')

ANSI 颜色

插件输出支持 ANSI 转义码，实现彩色输出：

var RED = '\x1b[31m'
var GREEN = '\x1b[32m'
var YELLOW = '\x1b[33m'
var CYAN = '\x1b[36m'
var BOLD = '\x1b[1m'
var RESET = '\x1b[0m'

return GREEN + 'Success!' + RESET + '\r\n'

常用颜色码

颜色	前景码	效果
红色	\x1b[31m	错误/警告
绿色	\x1b[32m	成功
黄色	\x1b[33m	提示
蓝色	\x1b[34m	信息
青色	\x1b[36m	标题
白色	\x1b[97m	高亮
灰色	\x1b[90m	次要
粗体	\x1b[1m	强调
重置	\x1b[0m	恢复默认

最小插件模板

/* myplugin - 简短描述 */
var arg = args.slice(1).join(' ').trim()

if (!arg) {
  return '\x1b[31mmyplugin: missing argument\x1b[0m\r\n'
}

// 处理逻辑
var result = 'You said: ' + arg

return result + '\r\n'

错误处理

插件抛出的异常会被 TSH 捕获并显示：

throw new Error('something went wrong')
// 终端显示: Plugin error: something went wrong

建议使用 try-catch 并返回友好的错误信息：

try {
  // 可能出错的操作
  return result + '\r\n'
} catch(e) {
  return '\x1b[31mmyplugin: ' + e.message + '\x1b[0m\r\n'
}

插件文件格式

插件文件是纯 JavaScript，内容即为函数体。不需要 function 声明或 module.exports：

// 正确 — 直接写函数体
var x = args[1]
return 'Hello ' + x + '\r\n'

// 错误 — 不要写函数声明
function(args, stdin, host) {
  var x = args[1]
  return 'Hello ' + x + '\r\n'
}

调试技巧

1. 使用 console.log 输出到浏览器控制台（不影响终端）
2. 用 JSON.stringify 检查变量结构
3. 先在浏览器控制台测试代码，再粘贴到插件文件中
4. 使用 ANSI 颜色区分不同输出类型