@celljs/ta-extensions 4.8.0 → 4.9.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.en.md +4 -1
- package/README.md +4 -1
- package/host/index.mjs +64 -61
- package/package.json +14 -4
- package/skills/ta-package/SKILL.md +12 -8
- package/web/index.js +488 -120
- package/web-src/actions.ts +0 -204
- package/web-src/archive.spec.ts +0 -101
- package/web-src/archive.ts +0 -229
- package/web-src/context.ts +0 -24
- package/web-src/extensions-util.spec.ts +0 -38
- package/web-src/extensions-util.ts +0 -40
- package/web-src/host.spec.ts +0 -72
- package/web-src/host.ts +0 -115
- package/web-src/i18n.ts +0 -240
- package/web-src/import-dialog.tsx +0 -89
- package/web-src/index.tsx +0 -50
- package/web-src/market-detail.tsx +0 -138
- package/web-src/market-parts.tsx +0 -94
- package/web-src/market-store.ts +0 -116
- package/web-src/market-style.ts +0 -94
- package/web-src/market-util.spec.ts +0 -79
- package/web-src/market-util.ts +0 -239
- package/web-src/market-view.tsx +0 -245
- package/web-src/market.spec.ts +0 -154
- package/web-src/market.ts +0 -232
- package/web-src/page.tsx +0 -278
- package/web-src/pictures.tsx +0 -87
- package/web-src/react.ts +0 -11
- package/web-src/signal.ts +0 -34
- package/web-src/style.ts +0 -92
package/README.en.md
CHANGED
|
@@ -9,6 +9,9 @@ A built-in pi package for Ta (enabled by default, can be disabled in Settings
|
|
|
9
9
|
- "Installed Extensions": packages from the `packages` setting (npm or Git), with toggles. You can copy the source or remove them.
|
|
10
10
|
- Import: use the button, the page's top-right menu, or drag files to the page. In the dialog, select a `.tgz` file or enter an `npm:…` / Git address to install (`installPackage`, equivalent to `ta install`). After import, install, or remove, call `reloadExtensions` so the current session and page get the updates immediately.
|
|
11
11
|
- "Share with Others": export → send .tgz file → they import. A three-step diagram shows this flow, with a note explaining that npm, Git sources, or telling Ta directly also work.
|
|
12
|
+
- Each row and the page of a package of the marketplace have Share: the share dialog of Ta (a QR code, a link).
|
|
13
|
+
- The search of Quick open gets three sections from here (`search.ts`, `registerSearch`): Installed and Come with Ta, filtered in memory, and Marketplace, npm searched through the host a page at a time, with Install on those not installed.
|
|
14
|
+
- Extensions opened without installing are not listed under "Mine": Quick open installs or deletes them ([@celljs/ta-launcher](../ta-launcher/README.en.md)). The page of a package of the marketplace with a web extension has Open besides Install: its pages run at once as a temporary extension (`pi.openTemporary`), found in Quick open afterwards.
|
|
12
15
|
- "Marketplace" (`market-view.tsx`, `market-detail.tsx`): npm packages with the `pi-package` keyword—the ones listed in pi's official package directory.
|
|
13
16
|
- Search box (searches 300 ms after input stops) and a few popular topics. Without keywords, lists by npm's combined ranking (download volume dominates); scrolling to the bottom auto-loads the next page.
|
|
14
17
|
- Each card shows an avatar from the first letter of the name (same name, same color), name (scope faded), author, monthly downloads, description, category tags, and publish date, with an "Install" button on the right: one-click install as user-level `npm:<name>` (`installPackage`, unpinned version, updatable with `ta update`). A loading spinner appears during install; "Installed" shows when done; built-in extensions show "Built-in". Installation continues if you leave the page.
|
|
@@ -24,4 +27,4 @@ A built-in pi package for Ta (enabled by default, can be disabled in Settings
|
|
|
24
27
|
- Extensions imported from files are placed only in the user's `extensions/`. To use one in a project, place the directory in the project's `.ta/extensions/` and commit it.
|
|
25
28
|
- Extensions run code on this machine. Before importing extensions from others, the page warns to only import from trusted sources, and the skill asks Ta to review it first and explain what it does. Marketplace installs are one-click (no approval prompts, following pi's practice); you can view the intro and source code at the bottom of the list or in the detail page.
|
|
26
29
|
- The marketplace only recognizes the official npm registry (search, manifests, and download counts at registry.npmjs.org). READMEs depend on jsDelivr or GitHub. If either is unreachable, the page shows why and offers "Retry"; this doesn't affect already-installed extensions. Installation still uses pi's npm, respecting your npm config.
|
|
27
|
-
- Most npm data is in English; Chinese searches won't find everything. Topic buttons use English keywords.
|
|
30
|
+
- Most npm data is in English; Chinese searches won't find everything. Topic buttons use English keywords.
|
package/README.md
CHANGED
|
@@ -12,7 +12,10 @@ Ta 自带的 pi 包(默认开启,可在 设置 → 扩展 关闭):告诉
|
|
|
12
12
|
- "市场"(`market-view.tsx`、`market-detail.tsx`):npm 上带 `pi-package` 关键词的包,也就是 pi 官网包目录收录的那些。
|
|
13
13
|
- 搜索框(输入停 300 ms 后搜索)和几个常用话题;没有关键词时按 npm 的综合排序(下载量占大头)列出,滚动到底自动加载下一页。
|
|
14
14
|
- 每张卡片是名字首字母头像(同名同色)、名称(scope 变淡)、作者、月下载量、说明、类别标签和发布时间,右侧一个"安装"按钮:一键安装为用户级的 `npm:<名字>`(`installPackage`,不锁版本,`ta update` 能更新),安装中转圈,装好后显示"已安装",随 Ta 提供的显示"内置"。安装在离开页面后继续。
|
|
15
|
-
- 点卡片进入详情页(`Esc` 或"返回"回到列表,滚动位置不变):头像、名称、说明、作者/版本/下载量/许可证/时间、安装或移除、npm/源代码/主页链接,`pi.video` / `pi.image` 预览,以及 README
|
|
15
|
+
- 点卡片进入详情页(`Esc` 或"返回"回到列表,滚动位置不变):头像、名称、说明、作者/版本/下载量/许可证/时间、安装或移除、npm/源代码/主页链接,`pi.video` / `pi.image` 预览,以及 README。带 Web 扩展的包还有"打开":不安装,作为临时扩展直接运行它的页面(`pi.openTemporary`,见 [@celljs/ta-launcher](../ta-launcher/README.md)),之后在"快捷打开"里找到它。
|
|
16
|
+
- 免安装打开的临时扩展不列在"我的"里,由"快捷打开"安装或删除。
|
|
17
|
+
- 每一行和市场详情页都有"分享":打开 Ta 的分享弹窗(二维码、链接)。
|
|
18
|
+
- 快捷打开的搜索里加了"已安装""内置""市场"三个分区(`search.ts`,`registerSearch`):前两个在内存里过滤,市场经服务端搜 npm、分页,未安装的有"安装"按钮。
|
|
16
19
|
- **服务端**(`pi.host`,`web-src/host.ts` → `host/index.mjs`):页面经 `callHost`(`TaPackageServer.callPackageHost`)调用。
|
|
17
20
|
- `exportPackage(id)`:把包目录打成一个 `.tgz`(gzip 的 tar,顶层是包目录,去掉 `node_modules`、`.git` 和链接),用 base64 交给页面下载。和 `tar -czf <名字>.tgz <名字>` 的格式相同,没有 Ta 也能用 `tar` 解开。
|
|
18
21
|
- `searchMarket(query, from?)`、`marketPackage(name)`(`market.ts`):在服务端查 npm,因为包也装在服务端;结果缓存 5 分钟,同一请求合并。搜索走 `/-/v1/search?text=<词> keywords:pi-package`;npm 对有关键词的搜索仍会把所有 `pi-package` 排在后面,所以只保留名称、说明或关键词里含有每个词的包,出现第一个不相关的就结束分页。详情不取 npm 的整份包文档(发版频繁的包有几十 MB),只取 `/<名字>/latest` 清单、上月下载量,README 先从 jsDelivr 取发布的那一版,没有再取 GitHub 仓库的;README 里的 HTML 图片、链接、标题转成 Markdown(Ta 的 Markdown 不渲染 HTML),去掉徽章,相对链接指向 GitHub 仓库。
|
package/host/index.mjs
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
// web-src/host.ts
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import { basename, dirname, join as join2 } from "node:path";
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { basename as basename2, join as join2 } from "node:path";
|
|
5
4
|
|
|
6
|
-
//
|
|
7
|
-
import {
|
|
8
|
-
import {
|
|
5
|
+
// ../ta-harness/esm/node/package-archive.js
|
|
6
|
+
import { randomBytes } from "node:crypto";
|
|
7
|
+
import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
8
|
+
import { basename, dirname, join } from "node:path";
|
|
9
9
|
import { gunzipSync, gzipSync } from "node:zlib";
|
|
10
10
|
var BLOCK = 512;
|
|
11
11
|
var LEFT_OUT = new Set(["node_modules", ".git", ".DS_Store"]);
|
|
12
|
-
var
|
|
13
|
-
((
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
var PackageArchive;
|
|
13
|
+
(function(PackageArchive2) {
|
|
14
|
+
PackageArchive2.MAX_BYTES = 20 * 1024 * 1024;
|
|
15
|
+
PackageArchive2.MAX_FILES = 5000;
|
|
16
16
|
function collect(root) {
|
|
17
17
|
const files = [];
|
|
18
18
|
let bytes = 0;
|
|
@@ -28,8 +28,8 @@ var ExtensionArchive;
|
|
|
28
28
|
walk(file, path);
|
|
29
29
|
} else if (stat.isFile()) {
|
|
30
30
|
bytes += stat.size;
|
|
31
|
-
if (files.length >=
|
|
32
|
-
throw new Error(`The package in ${root} is larger than ${
|
|
31
|
+
if (files.length >= PackageArchive2.MAX_FILES || bytes > PackageArchive2.MAX_BYTES) {
|
|
32
|
+
throw new Error(`The package in ${root} is larger than ${PackageArchive2.MAX_FILES} files or ${PackageArchive2.MAX_BYTES / 1024 / 1024} MB.`);
|
|
33
33
|
}
|
|
34
34
|
files.push({ path, data: readFileSync(file), executable: (stat.mode & 73) !== 0 });
|
|
35
35
|
}
|
|
@@ -38,7 +38,42 @@ var ExtensionArchive;
|
|
|
38
38
|
walk(root, "");
|
|
39
39
|
return files;
|
|
40
40
|
}
|
|
41
|
-
|
|
41
|
+
PackageArchive2.collect = collect;
|
|
42
|
+
function extract(files, target) {
|
|
43
|
+
const staging = join(dirname(target), `.${basename(target)}.${randomBytes(4).toString("hex")}`);
|
|
44
|
+
try {
|
|
45
|
+
for (const file of files) {
|
|
46
|
+
const path = join(staging, ...file.path.split("/"));
|
|
47
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
48
|
+
writeFileSync(path, file.data);
|
|
49
|
+
if (file.executable) {
|
|
50
|
+
chmodSync(path, 493);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
rmSync(target, { recursive: true, force: true });
|
|
54
|
+
renameSync(staging, target);
|
|
55
|
+
} finally {
|
|
56
|
+
rmSync(staging, { recursive: true, force: true });
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
PackageArchive2.extract = extract;
|
|
60
|
+
function nameOf(files) {
|
|
61
|
+
var _a;
|
|
62
|
+
var _b;
|
|
63
|
+
const manifest = files.find((file) => file.path === "package.json");
|
|
64
|
+
try {
|
|
65
|
+
const name = (_a = JSON.parse(Buffer.from((_b = manifest === null || manifest === undefined ? undefined : manifest.data) !== null && _b !== undefined ? _b : []).toString("utf8"))) === null || _a === undefined ? undefined : _a.name;
|
|
66
|
+
return typeof name === "string" && name.trim() ? name.trim() : undefined;
|
|
67
|
+
} catch (_c) {
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
PackageArchive2.nameOf = nameOf;
|
|
72
|
+
function directoryName(name) {
|
|
73
|
+
const plain = name.slice(name.lastIndexOf("/") + 1).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "");
|
|
74
|
+
return plain || "extension";
|
|
75
|
+
}
|
|
76
|
+
PackageArchive2.directoryName = directoryName;
|
|
42
77
|
function pack(top, files, mtime = Date.now()) {
|
|
43
78
|
const blocks = [header(`${top}/`, 0, 493, "5", mtime)];
|
|
44
79
|
const directories = new Set;
|
|
@@ -57,12 +92,13 @@ var ExtensionArchive;
|
|
|
57
92
|
blocks.push(new Uint8Array(BLOCK * 2));
|
|
58
93
|
return gzipSync(Buffer.concat(blocks));
|
|
59
94
|
}
|
|
60
|
-
|
|
95
|
+
PackageArchive2.pack = pack;
|
|
61
96
|
function unpack(archive) {
|
|
97
|
+
var _a;
|
|
62
98
|
let tar;
|
|
63
99
|
try {
|
|
64
|
-
tar = gunzipSync(archive, { maxOutputLength:
|
|
65
|
-
} catch {
|
|
100
|
+
tar = gunzipSync(archive, { maxOutputLength: PackageArchive2.MAX_BYTES + PackageArchive2.MAX_FILES * BLOCK * 2 });
|
|
101
|
+
} catch (_b) {
|
|
66
102
|
throw new Error("The file is not a .tgz of a package, or is larger than the limit.");
|
|
67
103
|
}
|
|
68
104
|
const files = [];
|
|
@@ -82,14 +118,14 @@ var ExtensionArchive;
|
|
|
82
118
|
const body = tar.subarray(offset + BLOCK, offset + BLOCK + size);
|
|
83
119
|
offset += BLOCK + size + padding(size);
|
|
84
120
|
if (type === "x") {
|
|
85
|
-
longPath = paxPath(body)
|
|
121
|
+
longPath = (_a = paxPath(body)) !== null && _a !== undefined ? _a : longPath;
|
|
86
122
|
continue;
|
|
87
123
|
}
|
|
88
124
|
if (type === "L") {
|
|
89
125
|
longPath = text(body);
|
|
90
126
|
continue;
|
|
91
127
|
}
|
|
92
|
-
const name = longPath
|
|
128
|
+
const name = longPath !== null && longPath !== undefined ? longPath : joinName(text(block.subarray(345, 500)), text(block.subarray(0, 100)));
|
|
93
129
|
longPath = undefined;
|
|
94
130
|
if (type !== "0" && type !== "7" && type !== "5") {
|
|
95
131
|
continue;
|
|
@@ -107,8 +143,8 @@ var ExtensionArchive;
|
|
|
107
143
|
continue;
|
|
108
144
|
}
|
|
109
145
|
bytes += size;
|
|
110
|
-
if (files.length >=
|
|
111
|
-
throw new Error(`The package is larger than ${
|
|
146
|
+
if (files.length >= PackageArchive2.MAX_FILES || bytes > PackageArchive2.MAX_BYTES) {
|
|
147
|
+
throw new Error(`The package is larger than ${PackageArchive2.MAX_FILES} files or ${PackageArchive2.MAX_BYTES / 1024 / 1024} MB.`);
|
|
112
148
|
}
|
|
113
149
|
files.push({ path: parts.slice(1).join("/"), data: new Uint8Array(body), executable: (octal(block.subarray(100, 108)) & 73) !== 0 });
|
|
114
150
|
}
|
|
@@ -117,7 +153,7 @@ var ExtensionArchive;
|
|
|
117
153
|
}
|
|
118
154
|
return { top, files };
|
|
119
155
|
}
|
|
120
|
-
|
|
156
|
+
PackageArchive2.unpack = unpack;
|
|
121
157
|
function header(path, size, mode, type, mtime) {
|
|
122
158
|
const block = Buffer.alloc(BLOCK);
|
|
123
159
|
const [prefix, name] = split(path);
|
|
@@ -192,7 +228,7 @@ var ExtensionArchive;
|
|
|
192
228
|
function padding(size) {
|
|
193
229
|
return (BLOCK - size % BLOCK) % BLOCK;
|
|
194
230
|
}
|
|
195
|
-
})(
|
|
231
|
+
})(PackageArchive || (PackageArchive = {}));
|
|
196
232
|
|
|
197
233
|
// web-src/market-util.ts
|
|
198
234
|
var KIND_WORDS = {
|
|
@@ -517,15 +553,6 @@ class NpmMarket {
|
|
|
517
553
|
}
|
|
518
554
|
|
|
519
555
|
// web-src/host.ts
|
|
520
|
-
var PackageFiles;
|
|
521
|
-
((PackageFiles) => {
|
|
522
|
-
function directoryName(name) {
|
|
523
|
-
const plain = name.slice(name.lastIndexOf("/") + 1).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "");
|
|
524
|
-
return plain || "extension";
|
|
525
|
-
}
|
|
526
|
-
PackageFiles.directoryName = directoryName;
|
|
527
|
-
})(PackageFiles ||= {});
|
|
528
|
-
|
|
529
556
|
class ExtensionsService {
|
|
530
557
|
host;
|
|
531
558
|
market;
|
|
@@ -548,54 +575,30 @@ class ExtensionsService {
|
|
|
548
575
|
if (pkg.origin === "builtin") {
|
|
549
576
|
throw new Error(`${pkg.name} comes with Ta: everyone has it already.`);
|
|
550
577
|
}
|
|
551
|
-
const top =
|
|
552
|
-
const archive =
|
|
578
|
+
const top = basename2(pkg.root);
|
|
579
|
+
const archive = PackageArchive.pack(top, PackageArchive.collect(pkg.root));
|
|
553
580
|
return { fileName: `${top}${pkg.version ? `-${pkg.version}` : ""}.tgz`, data: Buffer.from(archive).toString("base64") };
|
|
554
581
|
}
|
|
555
582
|
async importPackage(data, overwrite = false) {
|
|
556
583
|
if (typeof data !== "string" || data === "") {
|
|
557
584
|
throw new Error("Pass the bytes of the file in base64.");
|
|
558
585
|
}
|
|
559
|
-
const { top, files } =
|
|
560
|
-
const name =
|
|
561
|
-
const directory =
|
|
586
|
+
const { top, files } = PackageArchive.unpack(Buffer.from(data, "base64"));
|
|
587
|
+
const name = PackageArchive.nameOf(files) ?? top;
|
|
588
|
+
const directory = PackageArchive.directoryName(name);
|
|
562
589
|
const extensions = join2(this.host.agentDir, "extensions");
|
|
563
590
|
const target = join2(extensions, directory);
|
|
564
591
|
if (existsSync(target) && !overwrite) {
|
|
565
592
|
return { status: "exists", name, directory };
|
|
566
593
|
}
|
|
567
|
-
|
|
568
|
-
try {
|
|
569
|
-
for (const file of files) {
|
|
570
|
-
const path = join2(staging, ...file.path.split("/"));
|
|
571
|
-
mkdirSync(dirname(path), { recursive: true });
|
|
572
|
-
writeFileSync(path, file.data);
|
|
573
|
-
if (file.executable) {
|
|
574
|
-
chmodSync(path, 493);
|
|
575
|
-
}
|
|
576
|
-
}
|
|
577
|
-
rmSync(target, { recursive: true, force: true });
|
|
578
|
-
renameSync(staging, target);
|
|
579
|
-
} finally {
|
|
580
|
-
rmSync(staging, { recursive: true, force: true });
|
|
581
|
-
}
|
|
594
|
+
PackageArchive.extract(files, target);
|
|
582
595
|
return { status: "imported", name, directory };
|
|
583
596
|
}
|
|
584
|
-
nameOf(files) {
|
|
585
|
-
const manifest = files.find((file) => file.path === "package.json");
|
|
586
|
-
try {
|
|
587
|
-
const name = JSON.parse(Buffer.from(manifest?.data ?? []).toString("utf8"))?.name;
|
|
588
|
-
return typeof name === "string" && name.trim() ? name.trim() : undefined;
|
|
589
|
-
} catch {
|
|
590
|
-
return;
|
|
591
|
-
}
|
|
592
|
-
}
|
|
593
597
|
}
|
|
594
598
|
function activate(host) {
|
|
595
599
|
return new ExtensionsService(host);
|
|
596
600
|
}
|
|
597
601
|
export {
|
|
598
602
|
activate as default,
|
|
599
|
-
PackageFiles,
|
|
600
603
|
ExtensionsService
|
|
601
604
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/ta-extensions",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.9.1",
|
|
4
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
5
|
"keywords": [
|
|
6
6
|
"pi-package"
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"web",
|
|
19
19
|
"host",
|
|
20
20
|
"skills",
|
|
21
|
-
"
|
|
21
|
+
"!**/*.map"
|
|
22
22
|
],
|
|
23
23
|
"scripts": {
|
|
24
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",
|
|
@@ -27,14 +27,24 @@
|
|
|
27
27
|
"watch": "tsc -b -w --preserveWatchOutput"
|
|
28
28
|
},
|
|
29
29
|
"devDependencies": {
|
|
30
|
-
"@celljs/ta-
|
|
31
|
-
"@celljs/ta-
|
|
30
|
+
"@celljs/ta-harness": "4.9.1",
|
|
31
|
+
"@celljs/ta-protocol": "4.9.1",
|
|
32
|
+
"@celljs/ta-web": "4.9.1",
|
|
32
33
|
"@types/react": "^19.3.0"
|
|
33
34
|
},
|
|
34
35
|
"publishConfig": {
|
|
35
36
|
"access": "public"
|
|
36
37
|
},
|
|
37
38
|
"pi": {
|
|
39
|
+
"title": {
|
|
40
|
+
"en": "Extensions page",
|
|
41
|
+
"zh-CN": "扩展页"
|
|
42
|
+
},
|
|
43
|
+
"summary": {
|
|
44
|
+
"en": "The Extensions page: ask Ta for a new extension in a sentence, import or export one, or install one from the market.",
|
|
45
|
+
"zh-CN": "导航栏里的\"扩展\"页:用一句话让 Ta 做扩展,导入、导出,或从市场安装。"
|
|
46
|
+
},
|
|
47
|
+
"icon": "Puzzle",
|
|
38
48
|
"web": [
|
|
39
49
|
"./web/index.js"
|
|
40
50
|
],
|
|
@@ -11,6 +11,8 @@ Ta is pi; what Ta can do grows with pi packages. A package can hold a pi extensi
|
|
|
11
11
|
|
|
12
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
13
|
|
|
14
|
+
A small tool for now, which the user wants to use for a while rather than keep (a converter, a calculator, a board for one task), and which is only a page, goes in `~/.ta/agent/temporary/<name>/` instead: a temporary extension, as a mini program. It holds only a web extension (no pi extension, skills or prompts: those of a temporary package do not load) with one `page` view; it starts when the user opens it and is cleared after a while unused. Tell the user it is in Quick open (pulled down over the first tab of a phone, the grid at the bottom of the navigation elsewhere), where holding it keeps it in Mine or installs it. When in doubt, or when the user says to keep it, use `extensions/`.
|
|
15
|
+
|
|
14
16
|
```
|
|
15
17
|
<name>/
|
|
16
18
|
package.json {"name": "<name>", "version": "0.1.0", "type": "module", "pi": {"extensions": ["./index.ts"], "web": ["./web.js"]}}
|
|
@@ -18,7 +20,7 @@ Put a new package in `~/.ta/agent/extensions/<name>/`, a lowercase name with das
|
|
|
18
20
|
web.js the web extension, if the package shows something on the web page
|
|
19
21
|
```
|
|
20
22
|
|
|
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.
|
|
23
|
+
List in `pi` only the parts that exist. A web extension with only pages, used now and then, can start when one of them opens rather than with the page: `"webActivation": "open"` in `pi` (temporary ones always do); it is then in Quick open, not in the navigation, and what else it registers is there only while it runs. Also give `pi` what the user reads in the lists of extensions, in the user's language and English: `"title": {"en": "Timer", "zh-CN": "计时器"}`, `"summary"` (one sentence: what it does and where it shows), and `"icon"`, the name of one of `pi.ui.icons`. The pi extension is an ordinary pi extension: read pi's extension documentation (its path is in your instructions) before writing one.
|
|
22
24
|
|
|
23
25
|
## The web extension
|
|
24
26
|
|
|
@@ -43,13 +45,14 @@ export default function (pi) {
|
|
|
43
45
|
|
|
44
46
|
- `React`: the React of the page. Use it for components and hooks; never bring another.
|
|
45
47
|
- `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
|
|
48
|
+
- `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 list of the sidebar: its icon is at the top of the navigation, above the one of the chats (a tab at the bottom of a phone, before the chats), and it 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. `'board'` is a card of the board, which a phone brings out with a swipe to the left over its first tab (a button of the navigation elsewhere), for what is good to see at a glance (what runs, what is next): the user takes cards off, puts them back and orders them; render a few lines, no title. `'launcher'` is a section of Quick open, under Recent and Mine. 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 row at the top of the sidebar (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
49
|
- `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
50
|
- `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
51
|
- `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.
|
|
52
|
+
- `registerComposerAddon({ actions?(conversation), above?, subscribe?(listener) })`: adds to the message box of every conversation (the double's, an agent's, any other): `actions` gives a section of entries of its + menu (`{ key, label, icon?, detail?, run() }`, or `items` for a list shown in its place, entries with `checked` and `group`); `above` is a component drawn above the box with `{ conversation }`; `subscribe` tells the boxes to read `actions` again. `conversation` is `{ sessionId, sessionFile?, cwd?, kind: 'double' | 'chat', group?, title? }`.
|
|
50
53
|
- `on(type, handler)`: events of the conversation shown, as pi sends them (`agent_start`, `agent_end`, `message_end`, `tool_execution_end`, ...).
|
|
51
54
|
- `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.
|
|
55
|
+
- `switchSession(sessionId, opening?)`: shows another open session of ta serve (an id of `server.listSessions()`) as the conversation; on a phone the drawer closes. Pass a promise of the id for a session still opening (`{ title, cwd }` in `opening` says what it is): it is in front at once, showing that it opens, so a click never waits on the server.
|
|
53
56
|
- `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
57
|
- `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
58
|
- `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.
|
|
@@ -58,20 +61,21 @@ export default function (pi) {
|
|
|
58
61
|
- `ui.createTerminal({ cols?, rows?, cwd? })`: a terminal as VS Code's (xterm.js on WebGL, in the page's theme), loaded the first time one is made; URLs and paths of files in it (`src/a.ts:10:5`) open with Cmd or Ctrl + click, paths from `cwd` or the directory the shell reports (OSC 7): `write(data)` the program's output, `onData(listener)` what the user types, `onResize(listener)` its new size in characters, `attach(element)` shows it in an element with a size and `position: relative` (returns the function that takes it out; it keeps its screen meanwhile), `focus()`, `dispose()`. `pi.terminals` runs a shell of the server behind it.
|
|
59
62
|
- `ui.useCwd()`: a React hook, the directory of the conversation shown. `ui.useSessionId()`: the session of the conversation shown.
|
|
60
63
|
- `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`.
|
|
61
|
-
- `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.
|
|
64
|
+
- `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.Empty` (`{ title, hint?, compact?, tone?, picture?, children? }`) is what an empty list or view shows, as Ta's own lists: a short title without a full stop, at most one quieter hint, centered in its parent (a column of flex); `compact` in a menu, picker or dialog; `picture` above it where seeing what will be there helps (a first page, a list the user fills). Use it rather than text of your own. `ui.Picture` (`{ width?, height?, frame?, className?, children }`, 160 by 96 in a rounded frame unless told) is a small picture as Ta's own: draw a few `rect`, `circle`, `path` and `text` in it with the classes `ta-pic-pane` (a surface), `ta-pic-line` (a bar of text), `ta-pic-box` (an outline), `ta-pic-accent` (what it is about), `ta-pic-mark` (green), `ta-pic-soft` (half of it), `ta-pic-dot`, `ta-pic-bad` (red), `ta-pic-path` (a dashed way), `ta-pic-stroke` (a green line), `ta-pic-tick` (a line on green) and `ta-pic-text` (code), never colors of your own, so it follows the theme. `ui.PictureCards` (`{ cards, columns?, compactColumns? }`, cards `{ key, picture, label, hint?, title?, disabled?, onPick() }`) is a row of them to pick from, as the suggestions of an empty conversation. `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.
|
|
65
|
+
- `ui.usePages()`: a React hook, every page there is (`{ id, extension, title, icon?, state, onOpen, place, usedAt?, source?, temporary? }`), what Quick open lists; `ui.stopExtension(name)` stops one that started on open, `ui.forgetPage(id)` takes one out of Recent. `openTemporary(source, 'link')` opens a package of npm or Git without installing it and shows its first page: ask the user first. `ui.useContextMenu()`: a React hook, `[menu, open]`: render `menu`, and call `open(event, sections)` from `onContextMenu` (a long press on a touch screen is one), sections of `{ key, label, icon?, disabled?, danger?, run }`. `ui.shareExtension({ title, source?, packageId? })` opens Ta's dialog that shares an extension (a link and its QR code), `ui.openShared(text)` opens such a link after asking, and `registerSearch({ key, title, order?, remote?, search(query, offset), subscribe? })` adds a section to the search of Quick open (entries `{ key, title, detail?, icon?, tint?, action?, open(), menu? }`). `ui.QrCode` (`{ text }`) draws a QR code; `ui.scanCode?.(instructions)`, only in the Ta app, scans one with the camera.
|
|
62
66
|
- `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.
|
|
63
67
|
- `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.
|
|
64
68
|
- `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.
|
|
65
69
|
- `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.
|
|
66
|
-
- 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`).
|
|
70
|
+
- 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`, and for temporary packages `openTemporaryPackage`, `updateTemporaryPackage`, `installTemporaryPackage`).
|
|
67
71
|
|
|
68
|
-
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.
|
|
72
|
+
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. Write a font size in px as `calc(13px * var(--ta-font-scale))` (a line height in px too), so that it follows the font size of the settings; the messages of a conversation and its field carry the class `ta-conversation`, which adds the font size of conversations. 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.
|
|
69
73
|
|
|
70
74
|
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.
|
|
71
75
|
|
|
72
76
|
## Packages that come with Ta
|
|
73
77
|
|
|
74
|
-
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), `@celljs/ta-computer-use` (desktop apps through Cua Driver), `@celljs/ta-changes` (the files each reply changed, their diffs, and undo), `@celljs/ta-cron` (prompts that run on a schedule, with the Scheduled page, `/loop`, `/remind`, `/schedule` and the tool `schedule_task`), `@celljs/ta-agents` (other coding agents such as CodeBuddy Code, Claude Code and Codex as models) 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.
|
|
78
|
+
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), `@celljs/ta-computer-use` (desktop apps through Cua Driver), `@celljs/ta-changes` (the files each reply changed, their diffs, and undo), `@celljs/ta-cron` (prompts that run on a schedule, with the Scheduled page, `/loop`, `/remind`, `/schedule` and the tool `schedule_task`), `@celljs/ta-bots` (bots of WeChat and WeCom connected to the double, an agent or a conversation, with the tool `bot_send_file`), `@celljs/ta-agents` (other coding agents such as CodeBuddy Code, Claude Code and Codex as models), `@celljs/ta-launcher` (Quick open: Recent and Mine, and links of extensions opened without installing) 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.
|
|
75
79
|
|
|
76
80
|
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.
|
|
77
81
|
|
|
@@ -88,4 +92,4 @@ A package travels as one `.tgz` file: a gzipped tar of its directory, the direct
|
|
|
88
92
|
|
|
89
93
|
1. `node --check web.js` and, for the pi extension, read it once more against pi's documentation.
|
|
90
94
|
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.
|
|
91
|
-
3. Tell the user in one or two sentences what the package does and where it shows. No file listings unless asked.
|
|
95
|
+
3. Tell the user in one or two sentences what the package does and where it shows. No file listings unless asked.
|