@celljs/ta-extensions 0.0.0-stage → 4.6.1
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/README.md +19 -2
- package/host/index.mjs +271 -0
- package/package.json +44 -4
- package/skills/ta-package/SKILL.md +90 -0
- package/web/index.js +941 -0
- package/web-src/actions.ts +184 -0
- package/web-src/archive.spec.ts +101 -0
- package/web-src/archive.ts +229 -0
- package/web-src/extensions-util.spec.ts +38 -0
- package/web-src/extensions-util.ts +40 -0
- package/web-src/host.spec.ts +72 -0
- package/web-src/host.ts +101 -0
- package/web-src/i18n.ts +157 -0
- package/web-src/import-dialog.tsx +89 -0
- package/web-src/index.tsx +46 -0
- package/web-src/page.tsx +246 -0
- package/web-src/pictures.tsx +87 -0
- package/web-src/react.ts +11 -0
- package/web-src/style.ts +90 -0
package/README.md
CHANGED
|
@@ -1,3 +1,20 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Cell - Ta Extensions
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Ta 自带的 pi 包(默认开启,可在 设置 → 扩展 关闭):告诉用户可以用自然语言做扩展,并负责扩展的分享。不改 Ta 的核心,由三部分组成:
|
|
4
|
+
|
|
5
|
+
- **技能**(`pi.skills`,`skills/ta-package`):Ta 按用户的描述做、改 pi 包(pi 扩展、Web 扩展、技能、提示模板),以及按用户的话导出、导入扩展。终端里的 Ta 也有;关掉这个包,技能也随之去掉。
|
|
6
|
+
- **Web 扩展**(`pi.web`,`web-src/index.tsx` → `web/index.js`):导航栏里的"扩展"页。
|
|
7
|
+
- 顶部一句话说明回答结束就生效;输入框下是四种扩展(卡片、页面、命令、技能)的示意图(`web-src/pictures.tsx`,只用页面的 CSS 变量,跟随主题),点一个就做它的示例。发出后开一个新对话(`openSession` + `switchSession`)把"做一个扩展:……"发给 Ta。
|
|
8
|
+
- "我的扩展":`extensions/` 目录里的包(Ta 做的、从文件导入的),显示名称、版本、内容标签和说明,右侧是开关(`setPackageEnabled`,停用的变淡);悬停出现修改(问一句想怎么改,再开新对话交给 Ta)、导出、移除。
|
|
9
|
+
- "安装的扩展":`packages` 设置里的包(npm、Git),同样有开关,可复制来源、移除。
|
|
10
|
+
- 导入:按钮、页面右上角菜单或把文件拖到页面上;弹窗里选 `.tgz` 文件,或填 `npm:…` / Git 地址安装(`installPackage`,即 `ta install`)。导入、安装、移除后调用 `reloadExtensions`,当前对话和页面马上用上。
|
|
11
|
+
- "分享给别人":导出 → 发送 .tgz 文件 → 对方导入 三步图示,下面一行说明也支持 npm、Git 来源或直接对 Ta 说。
|
|
12
|
+
- **服务端**(`pi.host`,`web-src/host.ts` → `host/index.mjs`):页面经 `callHost`(`TaPackageServer.callPackageHost`)调用。
|
|
13
|
+
- `exportPackage(id)`:把包目录打成一个 `.tgz`(gzip 的 tar,顶层是包目录,去掉 `node_modules`、`.git` 和链接),用 base64 交给页面下载。和 `tar -czf <名字>.tgz <名字>` 的格式相同,没有 Ta 也能用 `tar` 解开。
|
|
14
|
+
- `importPackage(data, overwrite?)`:检查文件(只有一个顶层目录、里面有 `package.json`、路径不出目录、不超过 5000 个文件和 20 MB;跳过链接和 macOS tar 附带的 `._*`),放进 agent 目录的 `extensions/<包名去掉 scope>`,pi 无需设置就会加载。同名目录已存在时返回 `exists`,页面问过用户再带 `overwrite` 重来;先写到隐藏的临时目录再换上,会话不会加载到一半的文件。`npm pack` 打出的包(顶层是 `package/`)也能导入。
|
|
15
|
+
|
|
16
|
+
## 限制
|
|
17
|
+
|
|
18
|
+
- 导出、导入文件需要 ta serve(页面和服务端都在 ta serve 里);单独运行 `ta` 时,按技能里的说明让 Ta 用 `tar` 和 `ta install` 完成。
|
|
19
|
+
- 从文件导入的扩展只放进用户的 `extensions/`;要给一个项目用,把目录放进项目的 `.ta/extensions/` 并提交。
|
|
20
|
+
- 扩展会在本机运行代码:导入别人给的扩展前,页面提示只导入信任的来源,技能也要求 Ta 先读一遍再说明它做什么。
|
package/host/index.mjs
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
// web-src/host.ts
|
|
2
|
+
import { randomBytes } from "node:crypto";
|
|
3
|
+
import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { basename, dirname, join as join2 } from "node:path";
|
|
5
|
+
|
|
6
|
+
// web-src/archive.ts
|
|
7
|
+
import { lstatSync, readdirSync, readFileSync } from "node:fs";
|
|
8
|
+
import { join } from "node:path";
|
|
9
|
+
import { gunzipSync, gzipSync } from "node:zlib";
|
|
10
|
+
var BLOCK = 512;
|
|
11
|
+
var LEFT_OUT = new Set(["node_modules", ".git", ".DS_Store"]);
|
|
12
|
+
var ExtensionArchive;
|
|
13
|
+
((ExtensionArchive) => {
|
|
14
|
+
ExtensionArchive.MAX_BYTES = 20 * 1024 * 1024;
|
|
15
|
+
ExtensionArchive.MAX_FILES = 5000;
|
|
16
|
+
function collect(root) {
|
|
17
|
+
const files = [];
|
|
18
|
+
let bytes = 0;
|
|
19
|
+
const walk = (directory, prefix) => {
|
|
20
|
+
for (const name of readdirSync(directory).sort()) {
|
|
21
|
+
if (LEFT_OUT.has(name)) {
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
const file = join(directory, name);
|
|
25
|
+
const stat = lstatSync(file);
|
|
26
|
+
const path = prefix ? `${prefix}/${name}` : name;
|
|
27
|
+
if (stat.isDirectory()) {
|
|
28
|
+
walk(file, path);
|
|
29
|
+
} else if (stat.isFile()) {
|
|
30
|
+
bytes += stat.size;
|
|
31
|
+
if (files.length >= ExtensionArchive.MAX_FILES || bytes > ExtensionArchive.MAX_BYTES) {
|
|
32
|
+
throw new Error(`The package in ${root} is larger than ${ExtensionArchive.MAX_FILES} files or ${ExtensionArchive.MAX_BYTES / 1024 / 1024} MB.`);
|
|
33
|
+
}
|
|
34
|
+
files.push({ path, data: readFileSync(file), executable: (stat.mode & 73) !== 0 });
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
};
|
|
38
|
+
walk(root, "");
|
|
39
|
+
return files;
|
|
40
|
+
}
|
|
41
|
+
ExtensionArchive.collect = collect;
|
|
42
|
+
function pack(top, files, mtime = Date.now()) {
|
|
43
|
+
const blocks = [header(`${top}/`, 0, 493, "5", mtime)];
|
|
44
|
+
const directories = new Set;
|
|
45
|
+
for (const file of files) {
|
|
46
|
+
const parts = file.path.split("/");
|
|
47
|
+
for (let i = 1;i < parts.length; i++) {
|
|
48
|
+
const directory = parts.slice(0, i).join("/");
|
|
49
|
+
if (!directories.has(directory)) {
|
|
50
|
+
directories.add(directory);
|
|
51
|
+
blocks.push(header(`${top}/${directory}/`, 0, 493, "5", mtime));
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
blocks.push(header(`${top}/${file.path}`, file.data.length, file.executable ? 493 : 420, "0", mtime));
|
|
55
|
+
blocks.push(file.data, new Uint8Array(padding(file.data.length)));
|
|
56
|
+
}
|
|
57
|
+
blocks.push(new Uint8Array(BLOCK * 2));
|
|
58
|
+
return gzipSync(Buffer.concat(blocks));
|
|
59
|
+
}
|
|
60
|
+
ExtensionArchive.pack = pack;
|
|
61
|
+
function unpack(archive) {
|
|
62
|
+
let tar;
|
|
63
|
+
try {
|
|
64
|
+
tar = gunzipSync(archive, { maxOutputLength: ExtensionArchive.MAX_BYTES + ExtensionArchive.MAX_FILES * BLOCK * 2 });
|
|
65
|
+
} catch {
|
|
66
|
+
throw new Error("The file is not a .tgz of a package, or is larger than the limit.");
|
|
67
|
+
}
|
|
68
|
+
const files = [];
|
|
69
|
+
let top;
|
|
70
|
+
let longPath;
|
|
71
|
+
let bytes = 0;
|
|
72
|
+
for (let offset = 0;offset + BLOCK <= tar.length; ) {
|
|
73
|
+
const block = tar.subarray(offset, offset + BLOCK);
|
|
74
|
+
if (block.every((byte) => byte === 0)) {
|
|
75
|
+
break;
|
|
76
|
+
}
|
|
77
|
+
if (!checksumOk(block)) {
|
|
78
|
+
throw new Error("The file is not a .tgz of a package: a header of it is broken.");
|
|
79
|
+
}
|
|
80
|
+
const size = octal(block.subarray(124, 136));
|
|
81
|
+
const type = String.fromCharCode(block[156] || 48);
|
|
82
|
+
const body = tar.subarray(offset + BLOCK, offset + BLOCK + size);
|
|
83
|
+
offset += BLOCK + size + padding(size);
|
|
84
|
+
if (type === "x") {
|
|
85
|
+
longPath = paxPath(body) ?? longPath;
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
88
|
+
if (type === "L") {
|
|
89
|
+
longPath = text(body);
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
const name = longPath ?? joinName(text(block.subarray(345, 500)), text(block.subarray(0, 100)));
|
|
93
|
+
longPath = undefined;
|
|
94
|
+
if (type !== "0" && type !== "7" && type !== "5") {
|
|
95
|
+
continue;
|
|
96
|
+
}
|
|
97
|
+
const parts = safeParts(name);
|
|
98
|
+
if (parts.some((part) => part.startsWith("._") || part === "__MACOSX")) {
|
|
99
|
+
continue;
|
|
100
|
+
}
|
|
101
|
+
if (top === undefined) {
|
|
102
|
+
top = parts[0];
|
|
103
|
+
} else if (parts[0] !== top) {
|
|
104
|
+
throw new Error(`The file holds more than one directory: ${top} and ${parts[0]}.`);
|
|
105
|
+
}
|
|
106
|
+
if (type === "5" || parts.length === 1) {
|
|
107
|
+
continue;
|
|
108
|
+
}
|
|
109
|
+
bytes += size;
|
|
110
|
+
if (files.length >= ExtensionArchive.MAX_FILES || bytes > ExtensionArchive.MAX_BYTES) {
|
|
111
|
+
throw new Error(`The package is larger than ${ExtensionArchive.MAX_FILES} files or ${ExtensionArchive.MAX_BYTES / 1024 / 1024} MB.`);
|
|
112
|
+
}
|
|
113
|
+
files.push({ path: parts.slice(1).join("/"), data: new Uint8Array(body), executable: (octal(block.subarray(100, 108)) & 73) !== 0 });
|
|
114
|
+
}
|
|
115
|
+
if (top === undefined || !files.some((file) => file.path === "package.json")) {
|
|
116
|
+
throw new Error("The file is not a package: it has no package.json in its directory.");
|
|
117
|
+
}
|
|
118
|
+
return { top, files };
|
|
119
|
+
}
|
|
120
|
+
ExtensionArchive.unpack = unpack;
|
|
121
|
+
function header(path, size, mode, type, mtime) {
|
|
122
|
+
const block = Buffer.alloc(BLOCK);
|
|
123
|
+
const [prefix, name] = split(path);
|
|
124
|
+
block.write(name, 0, 100, "utf8");
|
|
125
|
+
field(block, 100, 8, mode);
|
|
126
|
+
field(block, 108, 8, 0);
|
|
127
|
+
field(block, 116, 8, 0);
|
|
128
|
+
field(block, 124, 12, size);
|
|
129
|
+
field(block, 136, 12, Math.floor(mtime / 1000));
|
|
130
|
+
block.write(type, 156, 1, "latin1");
|
|
131
|
+
block.write("ustar\x0000", 257, 8, "latin1");
|
|
132
|
+
block.write(prefix, 345, 155, "utf8");
|
|
133
|
+
block.fill(32, 148, 156);
|
|
134
|
+
const sum = block.reduce((total, byte) => total + byte, 0);
|
|
135
|
+
block.write(`${sum.toString(8).padStart(6, "0")}\x00 `, 148, 8, "latin1");
|
|
136
|
+
return block;
|
|
137
|
+
}
|
|
138
|
+
function split(path) {
|
|
139
|
+
if (Buffer.byteLength(path) <= 100) {
|
|
140
|
+
return ["", path];
|
|
141
|
+
}
|
|
142
|
+
for (let at = path.indexOf("/");at > 0; at = path.indexOf("/", at + 1)) {
|
|
143
|
+
const prefix = path.slice(0, at);
|
|
144
|
+
const name = path.slice(at + 1);
|
|
145
|
+
if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) {
|
|
146
|
+
return [prefix, name];
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
throw new Error(`The path ${path} is too long for the archive.`);
|
|
150
|
+
}
|
|
151
|
+
function field(block, offset, length, value) {
|
|
152
|
+
block.write(`${value.toString(8).padStart(length - 1, "0")}\x00`, offset, length, "latin1");
|
|
153
|
+
}
|
|
154
|
+
function octal(bytes) {
|
|
155
|
+
const value = Number.parseInt(text(bytes).trim() || "0", 8);
|
|
156
|
+
return Number.isFinite(value) ? value : 0;
|
|
157
|
+
}
|
|
158
|
+
function text(bytes) {
|
|
159
|
+
const end = bytes.indexOf(0);
|
|
160
|
+
return Buffer.from(end < 0 ? bytes : bytes.subarray(0, end)).toString("utf8");
|
|
161
|
+
}
|
|
162
|
+
function checksumOk(block) {
|
|
163
|
+
let sum = 0;
|
|
164
|
+
for (let i = 0;i < BLOCK; i++) {
|
|
165
|
+
sum += i >= 148 && i < 156 ? 32 : block[i];
|
|
166
|
+
}
|
|
167
|
+
return sum === octal(block.subarray(148, 156));
|
|
168
|
+
}
|
|
169
|
+
function joinName(prefix, name) {
|
|
170
|
+
return prefix ? `${prefix}/${name}` : name;
|
|
171
|
+
}
|
|
172
|
+
function paxPath(body) {
|
|
173
|
+
for (const record of Buffer.from(body).toString("utf8").split(`
|
|
174
|
+
`)) {
|
|
175
|
+
const match = /^\d+ path=(.*)$/.exec(record);
|
|
176
|
+
if (match) {
|
|
177
|
+
return match[1];
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
return;
|
|
181
|
+
}
|
|
182
|
+
function safeParts(path) {
|
|
183
|
+
if (path.startsWith("/") || path.includes("\\") || path.includes("\x00") || /^[a-zA-Z]:/.test(path)) {
|
|
184
|
+
throw new Error(`The file has a path out of its directory: ${path}`);
|
|
185
|
+
}
|
|
186
|
+
const parts = path.split("/").filter((part) => part !== "" && part !== ".");
|
|
187
|
+
if (parts.length === 0 || parts.some((part) => part === "..")) {
|
|
188
|
+
throw new Error(`The file has a path out of its directory: ${path}`);
|
|
189
|
+
}
|
|
190
|
+
return parts;
|
|
191
|
+
}
|
|
192
|
+
function padding(size) {
|
|
193
|
+
return (BLOCK - size % BLOCK) % BLOCK;
|
|
194
|
+
}
|
|
195
|
+
})(ExtensionArchive ||= {});
|
|
196
|
+
|
|
197
|
+
// web-src/host.ts
|
|
198
|
+
var PackageFiles;
|
|
199
|
+
((PackageFiles) => {
|
|
200
|
+
function directoryName(name) {
|
|
201
|
+
const plain = name.slice(name.lastIndexOf("/") + 1).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "");
|
|
202
|
+
return plain || "extension";
|
|
203
|
+
}
|
|
204
|
+
PackageFiles.directoryName = directoryName;
|
|
205
|
+
})(PackageFiles ||= {});
|
|
206
|
+
|
|
207
|
+
class ExtensionsService {
|
|
208
|
+
host;
|
|
209
|
+
constructor(host) {
|
|
210
|
+
this.host = host;
|
|
211
|
+
}
|
|
212
|
+
dispose() {}
|
|
213
|
+
async exportPackage(id, cwd) {
|
|
214
|
+
const pkg = (await this.host.listPackages(cwd)).find((candidate) => candidate.id === id);
|
|
215
|
+
if (!pkg) {
|
|
216
|
+
throw new Error(`No package has the id ${id}; it may have moved or gone.`);
|
|
217
|
+
}
|
|
218
|
+
if (pkg.origin === "builtin") {
|
|
219
|
+
throw new Error(`${pkg.name} comes with Ta: everyone has it already.`);
|
|
220
|
+
}
|
|
221
|
+
const top = basename(pkg.root);
|
|
222
|
+
const archive = ExtensionArchive.pack(top, ExtensionArchive.collect(pkg.root));
|
|
223
|
+
return { fileName: `${top}${pkg.version ? `-${pkg.version}` : ""}.tgz`, data: Buffer.from(archive).toString("base64") };
|
|
224
|
+
}
|
|
225
|
+
async importPackage(data, overwrite = false) {
|
|
226
|
+
if (typeof data !== "string" || data === "") {
|
|
227
|
+
throw new Error("Pass the bytes of the file in base64.");
|
|
228
|
+
}
|
|
229
|
+
const { top, files } = ExtensionArchive.unpack(Buffer.from(data, "base64"));
|
|
230
|
+
const name = this.nameOf(files) ?? top;
|
|
231
|
+
const directory = PackageFiles.directoryName(name);
|
|
232
|
+
const extensions = join2(this.host.agentDir, "extensions");
|
|
233
|
+
const target = join2(extensions, directory);
|
|
234
|
+
if (existsSync(target) && !overwrite) {
|
|
235
|
+
return { status: "exists", name, directory };
|
|
236
|
+
}
|
|
237
|
+
const staging = join2(extensions, `.${directory}.${randomBytes(4).toString("hex")}`);
|
|
238
|
+
try {
|
|
239
|
+
for (const file of files) {
|
|
240
|
+
const path = join2(staging, ...file.path.split("/"));
|
|
241
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
242
|
+
writeFileSync(path, file.data);
|
|
243
|
+
if (file.executable) {
|
|
244
|
+
chmodSync(path, 493);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
rmSync(target, { recursive: true, force: true });
|
|
248
|
+
renameSync(staging, target);
|
|
249
|
+
} finally {
|
|
250
|
+
rmSync(staging, { recursive: true, force: true });
|
|
251
|
+
}
|
|
252
|
+
return { status: "imported", name, directory };
|
|
253
|
+
}
|
|
254
|
+
nameOf(files) {
|
|
255
|
+
const manifest = files.find((file) => file.path === "package.json");
|
|
256
|
+
try {
|
|
257
|
+
const name = JSON.parse(Buffer.from(manifest?.data ?? []).toString("utf8"))?.name;
|
|
258
|
+
return typeof name === "string" && name.trim() ? name.trim() : undefined;
|
|
259
|
+
} catch {
|
|
260
|
+
return;
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
function activate(host) {
|
|
265
|
+
return new ExtensionsService(host);
|
|
266
|
+
}
|
|
267
|
+
export {
|
|
268
|
+
activate as default,
|
|
269
|
+
PackageFiles,
|
|
270
|
+
ExtensionsService
|
|
271
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/ta-extensions",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "4.6.1",
|
|
4
|
+
"description": "A pi package for Ta: the page of extensions, where the user makes one by saying what it should do, and hands extensions on or takes them in as one file",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"pi-package"
|
|
7
|
+
],
|
|
8
|
+
"homepage": "https://github.com/cellbang/cell",
|
|
9
|
+
"bugs": {
|
|
10
|
+
"url": "https://github.com/cellbang/cell/issues"
|
|
11
|
+
},
|
|
12
|
+
"repository": {
|
|
13
|
+
"type": "git",
|
|
14
|
+
"url": "https://github.com/cellbang/cell.git"
|
|
15
|
+
},
|
|
16
|
+
"license": "MIT",
|
|
17
|
+
"files": [
|
|
18
|
+
"web",
|
|
19
|
+
"host",
|
|
20
|
+
"skills",
|
|
21
|
+
"web-src"
|
|
22
|
+
],
|
|
23
|
+
"scripts": {
|
|
24
|
+
"build": "tsc -b && bun build web-src/index.tsx --format esm --target browser --outfile web/index.js && bun build web-src/host.ts --format esm --target node --outfile host/index.mjs",
|
|
25
|
+
"clean": "rm -rf lib web host *.tsbuildinfo",
|
|
26
|
+
"test": "bun test ./lib",
|
|
27
|
+
"watch": "tsc -b -w --preserveWatchOutput"
|
|
28
|
+
},
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@celljs/ta-protocol": "4.6.1",
|
|
31
|
+
"@celljs/ta-web": "4.6.1",
|
|
32
|
+
"@types/react": "^19.3.0"
|
|
33
|
+
},
|
|
34
|
+
"publishConfig": {
|
|
35
|
+
"access": "public"
|
|
36
|
+
},
|
|
37
|
+
"pi": {
|
|
38
|
+
"web": [
|
|
39
|
+
"./web/index.js"
|
|
40
|
+
],
|
|
41
|
+
"host": "./host/index.mjs",
|
|
42
|
+
"skills": [
|
|
43
|
+
"./skills"
|
|
44
|
+
]
|
|
45
|
+
}
|
|
46
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ta-package
|
|
3
|
+
description: Creates, changes, exports or imports a package of Ta, a pi package whose extension adds commands and tools to Ta and whose web extension adds pages, widgets and message views to Ta's web page. Use it whenever the user wants Ta or its web page to do or show something new, or wants to hand an extension on or take one in.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Packages of Ta
|
|
7
|
+
|
|
8
|
+
Ta is pi; what Ta can do grows with pi packages. A package can hold a pi extension (commands and tools, in the terminal and on the web page), a web extension (what the web page shows), skills and prompt templates. Build the smallest package that does what the user asked.
|
|
9
|
+
|
|
10
|
+
## Where
|
|
11
|
+
|
|
12
|
+
Put a new package in `~/.ta/agent/extensions/<name>/`, a lowercase name with dashes. pi loads the packages there by itself; there is nothing to install. Use `.ta/extensions/<name>/` of the project only when the user wants it for this project alone. To change a package, change its files in place. To remove one, delete its directory, after asking.
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
<name>/
|
|
16
|
+
package.json {"name": "<name>", "version": "0.1.0", "type": "module", "pi": {"extensions": ["./index.ts"], "web": ["./web.js"]}}
|
|
17
|
+
index.ts the pi extension, if the package needs commands, tools or events of the agent
|
|
18
|
+
web.js the web extension, if the package shows something on the web page
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
List in `pi` only the parts that exist. The pi extension is an ordinary pi extension: read pi's extension documentation (its path is in your instructions) before writing one.
|
|
22
|
+
|
|
23
|
+
## The web extension
|
|
24
|
+
|
|
25
|
+
One ES module with no imports, which exports a function. The web page calls it with `pi` and calls the function it returns, if any, when it unloads the extension. Write plain JavaScript without JSX: `const h = pi.React.createElement`.
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
export default function (pi) {
|
|
29
|
+
const h = pi.React.createElement;
|
|
30
|
+
function Clock() {
|
|
31
|
+
const [now, setNow] = pi.React.useState(() => new Date());
|
|
32
|
+
pi.React.useEffect(() => {
|
|
33
|
+
const timer = setInterval(() => setNow(new Date()), 1000);
|
|
34
|
+
return () => clearInterval(timer);
|
|
35
|
+
}, []);
|
|
36
|
+
return h('div', { style: { fontSize: 32, fontVariantNumeric: 'tabular-nums' } }, now.toLocaleTimeString());
|
|
37
|
+
}
|
|
38
|
+
pi.ui.setWidget('clock', Clock, { title: 'Clock', placement: 'panel' });
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`pi` has:
|
|
43
|
+
|
|
44
|
+
- `React`: the React of the page. Use it for components and hooks; never bring another.
|
|
45
|
+
- `ui.setWidget(key, Component, options?)`: a widget. `options.placement` is `'aboveEditor'` (default) or `'belowEditor'`, around the message box as in pi, or `'panel'`, a card in the cards tab of the workbench on the right (it opens when the first card comes): the place for what stays in view, like a timer or a list; `options.title` titles a card. `setWidget(key, undefined)` removes it.
|
|
46
|
+
- `registerView(name, { title, render, icon?, location?, order?, head?, pages?, menu? })`: a view of its own; `render` is a component, `icon` a component that draws an icon of `size` pixels in `currentColor` (take one of `ui.icons`). `location: 'page'` (default) fills the main area, with an icon in the navigation on the left; `'sidebar'` is a tab at the top of the sidebar, beside the one of the chats (its icon is the tab), and fills the sidebar when picked; `'panel'` is a tool of the workbench beside the conversation, as the explorer or the terminal of an IDE: the workbench's `+` and its empty state list it, and it opens as one of its tabs. A `sidebar` or `panel` view gets a title and scrolling: render only the content. `order` sorts the views, smaller first (default 100). `head` is a component for the top bar in place of the title: for a `sidebar` view, the rest of the row right of the tabs (a search, a button to add), or the middle of a page's bar beside the menu and the workbench button. `pages`, on a `sidebar` view, lists the pages it leads to (ids `<package name>/<view name>`; `assistant/assistant` is the double): the navigation leaves them out. `menu`, on a page, returns its actions as sections of `{ key, label, icon?, disabled?, danger?, run }`; it is called each time the menu opens, and the sidebar view that lists the page draws it as a … on hover.
|
|
47
|
+
- `registerMessageRenderer(customType, Component)`: shows the messages the pi extension sends with `pi.sendMessage({ customType, content, display: true, details })`; the component gets `{ message }`, `message.details` holds the data.
|
|
48
|
+
- `registerTool({ name, description, parameters, execute(toolCallId, params) })`: a tool the model can call in the conversations the page opens, which runs in the browser; `parameters` is a JSON schema of an object; `execute` returns the text the model reads, or throws.
|
|
49
|
+
- `registerOpener(link => boolean)`: opens what links of replies point to: `{ type: 'file', cwd, path, selection? }` (`selection` is `{ startLine, startColumn?, endLine?, endColumn? }`, from 1), `{ type: 'directory', cwd, path }` or `{ type: 'url', url }`; return `true` when it opened it, else the next opener is asked. @celljs/ta-workspace opens files, directories and pages already; register one only for links the package shows its own way.
|
|
50
|
+
- `on(type, handler)`: events of the conversation shown, as pi sends them (`agent_start`, `agent_end`, `message_end`, `tool_execution_end`, ...).
|
|
51
|
+
- `sendUserMessage(text)`: sends a message to the conversation shown as if the user typed it; `'/name args'` runs a command of a pi extension.
|
|
52
|
+
- `switchSession(sessionId)`: shows another open session of ta serve (an id of `server.listSessions()`) as the conversation; on a phone the drawer closes.
|
|
53
|
+
- `reloadExtensions()`: after the extension installed, imported, turned on or off (`packages.setPackageEnabled(id, enabled)`) or removed a package itself (`packages.installPackage`, `packages.removePackage`), loads the web extensions and the pi extensions of the conversation again, as the end of a reply does. `packages.listPackages()` lists every package Ta loads, with what each holds.
|
|
54
|
+
- `ui.notify(message, type?)`: a short notice; `type` is `'info'`, `'warning'` or `'error'`. `ui.confirm(title, message?, { confirmLabel?, danger? })` asks before going ahead and resolves with the answer; `danger` for what cannot be undone.
|
|
55
|
+
- `ui.input(title, placeholder?, { value? })` and `ui.editor(title, prefill?)`: ask for one line or several, as pi's; they resolve with the text, or `undefined` when the user cancelled.
|
|
56
|
+
- `ui.openEditor({ id, title, render, icon?, onClose? }, { preview?, preserveFocus? })`: a tab beside the conversation, for a file, a diff, a page or anything to read at length; opening an id that is open shows it again. With `preview` (a single click), the next preview takes its place until it is kept (`ui.pinEditor(id)`, or a double click on it). `ui.setEditorDirty(id, dirty)` marks it changed and not saved: the user is asked before it closes. `ui.closeEditor(id)` closes it; `onClose` runs when the user does. `ui.useActiveEditor()`: a React hook, the id of the tab shown.
|
|
57
|
+
- `ui.CodeEditor` (`{ path, value, readOnly?, line?, column?, endColumn?, selection?, onChange?, onSave? }`; `selection`, `{ startLine, startColumn?, endLine?, endColumn? }`, selects those lines and shows them in the middle) and `ui.DiffEditor` (`{ path, original, modified, inline?, readOnly?, onChange?, onSave?, onDiff? }`): Monaco, bundled with the page, for the text of a file and the change between two texts.
|
|
58
|
+
- `ui.useCwd()`: a React hook, the directory of the conversation shown. `ui.useSessionId()`: the session of the conversation shown.
|
|
59
|
+
- `ui.showView(id)`: shows a view of any extension by its id, a page in the main area or a workbench tool as its tab; `''` shows the conversation again. `ui.useView(id)`: a React hook, `{ title, location, shown, menu? }` while that view is loaded, else `undefined`.
|
|
60
|
+
- `ui.Composer`: the message box of every conversation, `{ placeholder?, onSend(text), mentions?, mentionLabel?, actions? }`: `mentions` (`{ name, detail? }[]`) is what `@` lists; `actions` are sections of its + menu, entries `{ key, label, icon?, detail?, insert? | run() }` (`insert` puts text at the caret). Use it for any conversation an extension shows, rather than a box of its own. `ui.Markdown` (`{ text }`) renders messages as the conversations do. `ui.Dialog` (`{ title, onClose, children }`) is a dialog over the whole page, as Ta's own: use it to make or change things rather than a form in a sidebar.
|
|
61
|
+
- `ui.Avatar`: Ta's avatar, the Cell logo, as a component `{ size?, mood?, mark? }`; `mark`, one or two characters, tells agents apart. Use it wherever Ta speaks, and draw Ta no other way.
|
|
62
|
+
- `ui.icons`: the lucide icons of the page by name (`Plus`, `Hash`, `Search`, `Files`, ...): a web extension cannot import them. Check for one before using it: the list only grows.
|
|
63
|
+
- `storage.get(key)` and `storage.set(key, value)`: small JSON values kept on the server for the package, so they stay across browsers and devices; setting `null` removes a key. A package keeps at most 4 MB there. `storage.onChange(keys => ...)` hears keys changed by other pages or the server. `storage.directory(cwd)` has the same methods for values of one directory (use `ui.useCwd()`), such as the folders open in a tree: keep there what belongs to a directory, and in `storage` what belongs to the user.
|
|
64
|
+
- `ui.theme` (`'light'` or `'dark'`) and `ui.language` (`'zh-CN'` or `'en-US'`): write the words of the extension in the language of the page.
|
|
65
|
+
- The services of ta serve, for what the rest cannot do, all on its one connection: `server` (sessions: the commands of pi's RPC mode, `listSessions`, `openSession`, `prompt`, ...), `workspace` (files and programs of a directory: `listDirectory`, `readFile`, `writeFile`, `fileUrl`, `findFiles`, `runCommand`), `terminals` (`openTerminal`, `writeTerminal`, ...; output by `onTerminalData`) and `packages` (`listPackages`, `installPackage`, `removePackage`).
|
|
66
|
+
|
|
67
|
+
Look like the page: inherit its font, and use its colors through CSS variables, which follow the light and dark theme: `var(--ta-text)`, `var(--ta-secondary)`, `var(--ta-muted)`, `var(--ta-card)`, `var(--ta-raised)`, `var(--ta-border)`, `var(--ta-accent)`, `var(--ta-red)`. Radius 8px for controls. Keep data the extension must remember with `pi.storage`; `localStorage` only for what belongs to one browser, under keys that start with the package name.
|
|
68
|
+
|
|
69
|
+
The two halves talk through the conversation: the web extension sends `/command args` with `sendUserMessage`; the pi extension answers with `pi.sendMessage` and a `customType` the web extension renders.
|
|
70
|
+
|
|
71
|
+
## Packages that come with Ta
|
|
72
|
+
|
|
73
|
+
Ta comes with some packages of its own, which are on until the user turns them off in Settings → Extensions: `@celljs/ta-workspace` (the explorer, search, source control, terminals and browser beside the conversation), `@celljs/ta-channels` (agents and channels) and `@celljs/ta-extensions` (this skill, and the Extensions page in the navigation, which lists the user's packages to change, export or remove and imports others). Do not copy or change them; build a new package for something new. The web page calls packages "extensions": use that word with the user.
|
|
74
|
+
|
|
75
|
+
Under `ta serve`, with `@celljs/ta-channels` on, you have tools to build a team for what the user wants: `create_agent` (a name and a role: another Ta with its own session), `create_channel` (agents, the lead first), `add_to_channel` (agents that exist, after the members; the lead stays), `post_to_channel` (a message; the agents it names with @ answer, or the lead, and they may hand on a few times) and `list_channels`. The agents run in ta serve, so they go on when the page closes. When the user asks for a team, for roles working together or for a review by several hands, create the agents and the channel and post the goal; do not write a package for it. In `ta` without `serve` the tools say they need `ta serve`: tell the user so.
|
|
76
|
+
|
|
77
|
+
## Hand on and take in
|
|
78
|
+
|
|
79
|
+
A package travels as one `.tgz` file: a gzipped tar of its directory, the directory at its top. The Extensions page exports and imports such files; do the same when the user asks in words.
|
|
80
|
+
|
|
81
|
+
- Export: `tar -czf <dest>/<name>.tgz --exclude node_modules --exclude .git -C ~/.ta/agent/extensions <name>` (or `-C .ta/extensions` for one of the project). Put it where the user said, else in the current directory, and give its path. Others can also install a package published to npm or held in a Git repository: `npm:<name>`, `git:<repository>` or its URL.
|
|
82
|
+
- Import a file: `tar -tzf <file>` first: one directory at the top, a `package.json` in it, no path with `..` or starting with `/`. Then `tar -xzf <file> -C ~/.ta/agent/extensions`; a file of `npm pack` has `package/` at the top: extract it to a directory named after its package instead (`mkdir ~/.ta/agent/extensions/<name> && tar -xzf <file> --strip-components 1 -C ~/.ta/agent/extensions/<name>`). Ask before replacing a directory there.
|
|
83
|
+
- Import by a source: `ta install <source>` (add `-l` for the project alone). When `ta` is not on the PATH, tell the user to paste the source into Import on the Extensions page.
|
|
84
|
+
- A package runs code on the user's machine: before importing one that the user did not write, read its `package.json` and extension files, and say in one sentence what it does.
|
|
85
|
+
|
|
86
|
+
## Check before you answer
|
|
87
|
+
|
|
88
|
+
1. `node --check web.js` and, for the pi extension, read it once more against pi's documentation.
|
|
89
|
+
2. When your reply on the web page ends, the page loads new and changed web extensions and their tools, and reloads the pi extensions of its conversation. Otherwise the page loads them when it is shown again, and `/reload` reloads pi extensions in the terminal. Do not ask the user to restart anything.
|
|
90
|
+
3. Tell the user in one or two sentences what the package does and where it shows. No file listings unless asked.
|