@tansr/sdk 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +84 -0
- package/dist/index.d.ts +16465 -0
- package/dist/index.js +32527 -0
- package/package.json +44 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tansr (tansr.com)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# @tansr/sdk
|
|
2
|
+
|
|
3
|
+
Tansr 对外 TypeScript SDK:在自己的程序里以 **headless** 方式驱动 Tansr 智能体——
|
|
4
|
+
prompt 进、事件流出,零 UI 依赖。查询环、工具调度、权限引擎、上下文压缩与模型接入
|
|
5
|
+
全部来自 tansr 内核(已编译内联进发布产物),你拿到的是与 tansr CLI 同一套 harness,
|
|
6
|
+
以库的形态嵌进你的应用。
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npm install @tansr/sdk
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
**运行时要求**:Node ≥ 22.19(Electron ≥ 39,SDK 跑主进程);ESM only;TypeScript
|
|
13
|
+
target ≥ ES2022。发布产物 = 单文件 ESM bundle + 单文件 d.ts(未压缩可读);第三方
|
|
14
|
+
运行时依赖仅 `undici` / `zod` / `zod-to-json-schema`(+可选 `@vscode/ripgrep` 检索
|
|
15
|
+
加速,装不上自动降级)。
|
|
16
|
+
|
|
17
|
+
## 一分钟上手(平台令牌档,终端分发形态)
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { createSession } from '@tansr/sdk';
|
|
21
|
+
|
|
22
|
+
// 令牌从你的服务端换发(appkey 恒在服务端;终端只持短期令牌)
|
|
23
|
+
const session = await createSession({ token, baseUrl: 'https://api.example.com' });
|
|
24
|
+
session.send('帮我总结这份合同');
|
|
25
|
+
for await (const event of session.events) {
|
|
26
|
+
if (event.type === 'msg.text.delta') process.stdout.write(event.text);
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
模型目录与能力位由平台 App 配置(控制台治理)自动下发,本地零配置。
|
|
31
|
+
|
|
32
|
+
## 三档 API × 三档模型来源
|
|
33
|
+
|
|
34
|
+
| API | 形态 | 适用 |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| `query(options)` | `AsyncGenerator<KernelEvent, QueryResult>` | 单轮一问一答,`return` 值携终值(finalText/usage/历史) |
|
|
37
|
+
| `createSession(options)` | `Promise<AgentSession>` | 多轮会话:`send` / `events` / `interrupt` / `messages` / `setModel` / `close` |
|
|
38
|
+
| `runAgent(options)` | `QueryHandle` | 低阶直通:自带 client/executor/tools,零装配 |
|
|
39
|
+
|
|
40
|
+
| 模型来源 | 传什么 | 适用 |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| **令牌档** | `{ token, baseUrl }` | 终端分发(Electron/桌面);能力位由平台治理 |
|
|
43
|
+
| **托管档(BYOK)** | `model: '别名'` + 本地 `.tansr/settings.json` | 自己的服务器/脚本,自带模型 key |
|
|
44
|
+
| **注入档** | `{ client, model }` 对象成对 | 测试(scripted client)/自定义接入 |
|
|
45
|
+
|
|
46
|
+
## 能力面一览
|
|
47
|
+
|
|
48
|
+
- **三环工具一个入口**:`tools: { builtin: [...], platform: [...], custom: [...] }`
|
|
49
|
+
——环2 内置本地工具(read/glob/grep/shell/…)、环3 平台托管能力(imageGen 图像
|
|
50
|
+
生成,平台代调按张计费)、环1 `defineTool` 业务函数(注册即说明书,JSON 参数表/
|
|
51
|
+
zod 双档);
|
|
52
|
+
- **skills**:`defineSkill` 内联 + `dirs` 目录装载(`<name>/SKILL.md`),按需装载零
|
|
53
|
+
发现(恒不扫用户目录);
|
|
54
|
+
- **MCP 外接**:`createMcpHost({ servers })` 应用级共享 / `mcp: { servers }` 会话级,
|
|
55
|
+
配置与业界 `mcpServers` 同形;
|
|
56
|
+
- **渲染管道**:`createSessionView`(事件流 → 不可变视图快照,structuredClone-safe,
|
|
57
|
+
Electron IPC 直传)+ `createNarrator`(人类可读日志行);恒不用手拼事件;
|
|
58
|
+
- **权限**:`permission: { mode?, rules?, askUser? }`——ask 裁决桥到你的 UI,缺席
|
|
59
|
+
fail-closed 降级 deny;
|
|
60
|
+
- **计量**:`cost.usage.updated` 逐请求;终端自查 `/v1/my-usage` 恒无金额字段,
|
|
61
|
+
开发者对账 `/v1/app-usage/by-end-user` 含金额(恒不代理给终端)。
|
|
62
|
+
|
|
63
|
+
能力位(17 工具位 + 3 平台位)在平台控制台按 App 配置;位关而显式选择恒得到装配期
|
|
64
|
+
可读错(`capability_disabled`,含修复指引),恒不静默缺工具。
|
|
65
|
+
|
|
66
|
+
## 文档与示例
|
|
67
|
+
|
|
68
|
+
- **技术手册(完整)**:仓内 `doc/90-SDK技术手册.md`——安装、三方闭环令牌接入、三档
|
|
69
|
+
API、能力位、defineTool/skills/MCP、渲染管道、权限、计量、imageGen、错误码排障、
|
|
70
|
+
安全须知;
|
|
71
|
+
- **官方示例**:`examples/token-server`(开发者服务端令牌换发样板)、
|
|
72
|
+
`examples/electron-chat`(Electron 全形态样板:权限弹框桥 + SessionView 投影 +
|
|
73
|
+
imageGen 产图渲染);
|
|
74
|
+
- **平台契约**:仓内 `doc/89-SDK平台契约v1.md`(wire 形态事实源)。
|
|
75
|
+
|
|
76
|
+
## 安全一句话
|
|
77
|
+
|
|
78
|
+
appkey 恒不出你的服务端;终端只持短期令牌(TTL + 平台定向吊销 = 止损面);Electron
|
|
79
|
+
里 SDK 与令牌恒在主进程,renderer 只见投影状态。完整安全须知见手册第十四章。
|
|
80
|
+
|
|
81
|
+
## License
|
|
82
|
+
|
|
83
|
+
MIT(发布产物内联了 tansr 内部 workspace 包的编译产物,同以 MIT 随包分发;见
|
|
84
|
+
dist 文件头 NOTICE)。
|