@jieapi/plugin-sdk 0.0.0-stage → 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AiCode contributors
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.
@@ -0,0 +1,18 @@
1
+ export type JsonValue = string | number | boolean | null | JsonValue[] | {
2
+ [key: string]: JsonValue;
3
+ };
4
+ export type PluginArgs = Record<string, unknown>;
5
+ export type HostParams = Record<string, unknown>;
6
+ export type PluginHandler = (args: PluginArgs) => unknown | Promise<unknown>;
7
+ export interface PluginDefinition {
8
+ /** 键与插件清单中的 handler 字段一致;返回 undefined 时宿主收到 null。 */
9
+ handlers: Record<string, PluginHandler>;
10
+ }
11
+ /** 调用宿主能力,对应文档中的 host.* 方法。 */
12
+ export declare function hostCall<T = unknown>(method: string, params?: HostParams): Promise<T>;
13
+ /** 向同插件已打开的页面推送事件。 */
14
+ export declare function emit(name: string, payload?: JsonValue): void;
15
+ /** 写入 stderr,宿主会转入应用日志。 */
16
+ export declare function log(message: string): void;
17
+ /** 注册 handlers 并开始读取宿主的 NDJSON 请求;每个进程只能调用一次。 */
18
+ export declare function definePlugin(definition: PluginDefinition): void;
package/dist/index.js ADDED
@@ -0,0 +1,103 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.hostCall = hostCall;
4
+ exports.emit = emit;
5
+ exports.log = log;
6
+ exports.definePlugin = definePlugin;
7
+ const readline_1 = require("readline");
8
+ const SUPPORTED_METHODS = new Set(['tool.invoke', 'hook.invoke', 'ui.invoke']);
9
+ const pending = new Map();
10
+ let hostSeq = 0;
11
+ let started = false;
12
+ function send(message) {
13
+ process.stdout.write(JSON.stringify(message) + '\n');
14
+ }
15
+ function errorMessage(error) {
16
+ return String((error === null || error === void 0 ? void 0 : error.message) || error);
17
+ }
18
+ function errorCode(error) {
19
+ const code = error === null || error === void 0 ? void 0 : error.code;
20
+ return typeof code === 'string' && code ? code : 'PLUGIN_ERROR';
21
+ }
22
+ /** 调用宿主能力,对应文档中的 host.* 方法。 */
23
+ function hostCall(method, params) {
24
+ const id = 'host-' + ++hostSeq;
25
+ return new Promise((resolve, reject) => {
26
+ pending.set(id, {
27
+ resolve: (value) => resolve(value),
28
+ reject
29
+ });
30
+ send({ jsonrpc: '2.0', id, method, params: params !== null && params !== void 0 ? params : {} });
31
+ });
32
+ }
33
+ /** 向同插件已打开的页面推送事件。 */
34
+ function emit(name, payload = null) {
35
+ send({ jsonrpc: '2.0', method: 'plugin.event', params: { name, payload } });
36
+ }
37
+ /** 写入 stderr,宿主会转入应用日志。 */
38
+ function log(message) {
39
+ process.stderr.write('[plugin] ' + message + '\n');
40
+ }
41
+ function handleRequest(id, method, params, handlers) {
42
+ if (!SUPPORTED_METHODS.has(method)) {
43
+ send({ jsonrpc: '2.0', id, error: { code: 'METHOD_UNKNOWN', message: method } });
44
+ return;
45
+ }
46
+ const name = typeof params.handler === 'string' ? params.handler : '';
47
+ const handler = handlers[name];
48
+ if (typeof handler !== 'function') {
49
+ send({ jsonrpc: '2.0', id, error: { code: 'HANDLER_NOT_FOUND', message: name } });
50
+ return;
51
+ }
52
+ Promise.resolve()
53
+ .then(() => { var _a; return handler((_a = params.args) !== null && _a !== void 0 ? _a : {}); })
54
+ .then((result) => send({ jsonrpc: '2.0', id, result: result === undefined ? null : result }))
55
+ .catch((error) => send({
56
+ jsonrpc: '2.0',
57
+ id,
58
+ error: { code: errorCode(error), message: errorMessage(error) }
59
+ }));
60
+ }
61
+ function handleResponse(message) {
62
+ const id = String(message.id);
63
+ const waiter = pending.get(id);
64
+ if (!waiter)
65
+ return;
66
+ pending.delete(id);
67
+ if (message.error) {
68
+ const error = new Error(message.error.message || 'host error');
69
+ error.code = message.error.code || 'HOST_ERROR';
70
+ waiter.reject(error);
71
+ }
72
+ else {
73
+ waiter.resolve(message.result === undefined ? null : message.result);
74
+ }
75
+ }
76
+ /** 注册 handlers 并开始读取宿主的 NDJSON 请求;每个进程只能调用一次。 */
77
+ function definePlugin(definition) {
78
+ if (started)
79
+ throw new Error('definePlugin 只能调用一次');
80
+ started = true;
81
+ const handlers = definition.handlers;
82
+ (0, readline_1.createInterface)({ input: process.stdin }).on('line', (line) => {
83
+ var _a;
84
+ if (!line.trim())
85
+ return;
86
+ let message;
87
+ try {
88
+ message = JSON.parse(line);
89
+ }
90
+ catch {
91
+ return;
92
+ }
93
+ if (message.method && message.id !== undefined) {
94
+ handleRequest(message.id, message.method, (_a = message.params) !== null && _a !== void 0 ? _a : {}, handlers);
95
+ }
96
+ else if (message.method) {
97
+ return;
98
+ }
99
+ else if (message.id !== undefined) {
100
+ handleResponse(message);
101
+ }
102
+ });
103
+ }
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "@jieapi/plugin-sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "TypeScript SDK for building AiCode plugins",
5
+ "license": "MIT",
6
+ "type": "commonjs",
7
+ "main": "dist/index.js",
8
+ "types": "dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "require": "./dist/index.js",
13
+ "default": "./dist/index.js"
14
+ },
15
+ "./page": {
16
+ "types": "./types/aicode.d.ts"
17
+ },
18
+ "./page/vue": {
19
+ "types": "./types/aicode-vue.d.ts"
20
+ }
21
+ },
22
+ "files": [
23
+ "dist",
24
+ "types",
25
+ "LICENSE"
26
+ ],
27
+ "engines": {
28
+ "node": ">=12"
29
+ },
30
+ "keywords": [
31
+ "aicode",
32
+ "plugin",
33
+ "sdk"
34
+ ],
35
+ "repository": {
36
+ "type": "git",
37
+ "url": "git+https://github.com/jieapi/AiCode.git",
38
+ "directory": "plugins/sdk"
39
+ },
40
+ "homepage": "https://github.com/jieapi/AiCode/tree/main/plugins/sdk",
41
+ "bugs": {
42
+ "url": "https://github.com/jieapi/AiCode/issues"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public"
46
+ },
47
+ "scripts": {
48
+ "build": "tsc -p tsconfig.json",
49
+ "prepublishOnly": "npm run build"
50
+ }
51
+ }
@@ -0,0 +1,188 @@
1
+ /**
2
+ * AiCode 插件页面组件库(`/__aicode/aicode-ui-vue.js`)的模板类型声明。
3
+ *
4
+ * 组件库在运行时挂到全局 `window.AicodeUI`,页面通过 `app.use(AicodeUI)` 注册。
5
+ * 本文件由 `@jieapi/plugin-sdk/page/vue` 导出,把同名组件并入 Vue 的 `GlobalComponents`,
6
+ * 让 Volar / vue-tsc 在模板里补全 `<AicodeButton>`、`<aicode-button>` 等标签与它们的 props。
7
+ *
8
+ * 需要项目安装 `vue`(仅用于类型,构建时仍使用 `/__aicode/vue.global.prod.js`)。
9
+ */
10
+
11
+ import type {
12
+ ComponentOptionsMixin,
13
+ ComputedOptions,
14
+ DefineComponent,
15
+ EmitsOptions,
16
+ MethodOptions,
17
+ } from 'vue';
18
+
19
+ type AicodeOption = { label: string; value: string };
20
+
21
+ type AicodeComponent<Props, Emits extends EmitsOptions> = DefineComponent<
22
+ Props,
23
+ {},
24
+ {},
25
+ ComputedOptions,
26
+ MethodOptions,
27
+ ComponentOptionsMixin,
28
+ ComponentOptionsMixin,
29
+ Emits
30
+ >;
31
+
32
+ interface AicodeBadgeProps {
33
+ text?: string;
34
+ kind?: string;
35
+ }
36
+
37
+ interface AicodeGroupProps {
38
+ title?: string;
39
+ collapsible?: boolean;
40
+ /** 支持 `v-model:expanded`。 */
41
+ expanded?: boolean;
42
+ }
43
+
44
+ interface AicodeRowProps {
45
+ title?: string;
46
+ subtitle?: string;
47
+ badge?: string;
48
+ badgeKind?: string;
49
+ /** `AicodeUI.icons` 中的图标名。 */
50
+ icon?: string;
51
+ chevron?: boolean;
52
+ selectable?: boolean;
53
+ selected?: boolean;
54
+ }
55
+
56
+ interface AicodeFieldProps {
57
+ label?: string;
58
+ }
59
+
60
+ interface AicodeSegmentedProps {
61
+ modelValue?: string;
62
+ options?: AicodeOption[];
63
+ disabled?: boolean;
64
+ }
65
+
66
+ interface AicodeButtonProps {
67
+ /** 同 `aicode-button-{variant}` 的样式变体。 */
68
+ variant?: string;
69
+ compact?: boolean;
70
+ disabled?: boolean;
71
+ }
72
+
73
+ interface AicodeEmptyProps {
74
+ text?: string;
75
+ }
76
+
77
+ interface AicodeMarkdownProps {
78
+ text?: string;
79
+ }
80
+
81
+ interface AicodeIconButtonProps {
82
+ /** 无障碍标签,同时用于 title。 */
83
+ label?: string;
84
+ }
85
+
86
+ interface AicodeSwipeRowProps {
87
+ disabled?: boolean;
88
+ actionText?: string;
89
+ }
90
+
91
+ interface AicodeSwitchProps {
92
+ modelValue?: boolean;
93
+ disabled?: boolean;
94
+ }
95
+
96
+ interface AicodeInputProps {
97
+ modelValue?: string;
98
+ placeholder?: string;
99
+ disabled?: boolean;
100
+ type?: string;
101
+ }
102
+
103
+ interface AicodeTextareaProps {
104
+ modelValue?: string;
105
+ placeholder?: string;
106
+ disabled?: boolean;
107
+ }
108
+
109
+ interface AicodeSelectProps {
110
+ modelValue?: string;
111
+ options?: AicodeOption[];
112
+ disabled?: boolean;
113
+ }
114
+
115
+ interface AicodeDividerProps {
116
+ flat?: boolean;
117
+ }
118
+
119
+ interface AicodeInfoRowProps {
120
+ label?: string;
121
+ value?: string;
122
+ }
123
+
124
+ interface AicodeBottomSheetProps {
125
+ modelValue?: boolean;
126
+ title?: string;
127
+ }
128
+
129
+ interface AicodeDialogProps {
130
+ modelValue?: boolean;
131
+ title?: string;
132
+ message?: string;
133
+ confirmText?: string;
134
+ cancelText?: string;
135
+ confirmDisabled?: boolean;
136
+ }
137
+
138
+ declare module 'vue' {
139
+ export interface GlobalComponents {
140
+ AicodeBadge: DefineComponent<AicodeBadgeProps>;
141
+ AicodeCard: DefineComponent;
142
+ AicodeGroup: AicodeComponent<AicodeGroupProps, {
143
+ 'update:expanded': (expanded: boolean) => void;
144
+ }>;
145
+ AicodeRow: AicodeComponent<AicodeRowProps, {
146
+ click: (event: MouseEvent) => void;
147
+ }>;
148
+ AicodeField: DefineComponent<AicodeFieldProps>;
149
+ AicodeSegmented: AicodeComponent<AicodeSegmentedProps, {
150
+ 'update:modelValue': (value: string) => void;
151
+ }>;
152
+ AicodeButton: AicodeComponent<AicodeButtonProps, {
153
+ click: (event: MouseEvent) => void;
154
+ }>;
155
+ AicodeEmpty: DefineComponent<AicodeEmptyProps>;
156
+ AicodeMarkdown: DefineComponent<AicodeMarkdownProps>;
157
+ AicodeIconButton: AicodeComponent<AicodeIconButtonProps, {
158
+ click: (event: MouseEvent) => void;
159
+ }>;
160
+ AicodeSwipeRow: AicodeComponent<AicodeSwipeRowProps, {
161
+ delete: () => void;
162
+ }>;
163
+ AicodeSwitch: AicodeComponent<AicodeSwitchProps, {
164
+ 'update:modelValue': (value: boolean) => void;
165
+ }>;
166
+ AicodeInput: AicodeComponent<AicodeInputProps, {
167
+ 'update:modelValue': (value: string) => void;
168
+ }>;
169
+ AicodeTextarea: AicodeComponent<AicodeTextareaProps, {
170
+ 'update:modelValue': (value: string) => void;
171
+ }>;
172
+ AicodeSelect: AicodeComponent<AicodeSelectProps, {
173
+ 'update:modelValue': (value: string) => void;
174
+ }>;
175
+ AicodeDivider: DefineComponent<AicodeDividerProps>;
176
+ AicodeInfoRow: DefineComponent<AicodeInfoRowProps>;
177
+ AicodeBottomSheet: AicodeComponent<AicodeBottomSheetProps, {
178
+ 'update:modelValue': (value: boolean) => void;
179
+ }>;
180
+ AicodeDialog: AicodeComponent<AicodeDialogProps, {
181
+ 'update:modelValue': (value: boolean) => void;
182
+ confirm: () => void;
183
+ cancel: () => void;
184
+ }>;
185
+ }
186
+ }
187
+
188
+ export {};
@@ -0,0 +1,998 @@
1
+ /**
2
+ * AiCode 插件页面宿主桥类型声明。
3
+ *
4
+ * 与宿主资源 `/__aicode/aicode.js` 对应:页面加载该脚本后,`window.aicode` 即为本文件描述的
5
+ * 桥对象。本文件只含类型,没有运行时代码;通过 `@jieapi/plugin-sdk/page` 引入后生效。
6
+ *
7
+ * 宿主请求返回 Promise;失败时 reject 一个带 `code` 与 `message` 的 Error,见
8
+ * {@link AicodeError}。文档:/advanced/plugin/ui-pages
9
+ */
10
+
11
+ // ---------------------------------------------------------------------------
12
+ // 基础类型
13
+ // ---------------------------------------------------------------------------
14
+
15
+ export type JsonPrimitive = string | number | boolean | null;
16
+
17
+ /** 可 JSON 序列化的值,对应宿主与插件进程之间的数据。 */
18
+ export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
19
+
20
+ export type JsonObject = { [key: string]: JsonValue };
21
+
22
+ /** 宿主失败时 reject 的错误;`code` 为稳定错误码,例如 `FILE_EXISTS`、`STALE_CONTEXT`。 */
23
+ export interface AicodeError extends Error {
24
+ code: AicodeErrorCode | (string & {});
25
+ }
26
+
27
+ export type AicodeErrorCode =
28
+ // 通用
29
+ | 'PLUGIN_INACTIVE'
30
+ | 'PARAM_INVALID'
31
+ | 'PARAM_MISSING'
32
+ | 'METHOD_UNKNOWN'
33
+ | 'TOO_LARGE'
34
+ | 'INTERNAL'
35
+ | 'PAGE_CLOSED'
36
+ | 'SERVICE_UNAVAILABLE'
37
+ | 'RUNTIME_UNAVAILABLE'
38
+ // 文件
39
+ | 'PATH_INVALID'
40
+ | 'PATH_DENIED'
41
+ | 'FILE_EXISTS'
42
+ | 'STALE_CONTEXT'
43
+ | 'IO_ERROR'
44
+ | 'STORAGE_FAILED'
45
+ | 'TOO_MANY_WATCHES'
46
+ | 'WATCH_FAILED'
47
+ // 会话
48
+ | 'WORKSPACE_UNAVAILABLE'
49
+ | 'SESSION_NOT_FOUND'
50
+ | 'SESSION_FORBIDDEN'
51
+ | 'CHAT_UI_UNAVAILABLE'
52
+ | 'CHAT_BUSY'
53
+ | 'MODE_UNSUPPORTED'
54
+ | 'APPROVAL_NOT_FOUND'
55
+ | 'NOT_REMEMBERABLE'
56
+ // 模型
57
+ | 'MODEL_ACCESS_NOT_DECLARED'
58
+ | 'MODEL_NOT_AVAILABLE'
59
+ | 'MODEL_UNSUPPORTED'
60
+ | 'MODEL_ERROR'
61
+ | 'PROVIDER_NOT_FOUND'
62
+ | 'PROVIDER_DISABLED'
63
+ | 'PROVIDER_NO_KEY'
64
+ | 'HANDLE_NOT_FOUND'
65
+ | 'HANDLE_LIMIT'
66
+ | 'MODEL_LIMIT'
67
+ | 'SELF_PROVIDER_FORBIDDEN'
68
+ | 'STREAM_NOT_FOUND'
69
+ | 'STREAM_LIMIT'
70
+ | 'STREAM_BUFFER_OVERFLOW'
71
+ | 'CURSOR_INVALID'
72
+ | 'REQUEST_TOO_LARGE'
73
+ | 'CONTEXT_TOO_LARGE'
74
+ | 'PARAM_UNSUPPORTED'
75
+ | 'IMAGE_TOO_LARGE'
76
+ | 'IMAGE_TYPE_UNSUPPORTED'
77
+ | 'ALL_KEYS_FAILED'
78
+ // 工具
79
+ | 'TOOL_NOT_ALLOWED'
80
+ | 'TOOL_NOT_FOUND'
81
+ | 'TOOL_ERROR'
82
+ | 'TOOL_TIMEOUT'
83
+ | 'TOOL_APPROVAL_TIMEOUT'
84
+ | 'TOOL_USER_REJECTED'
85
+ | 'TOOL_DENIED'
86
+ // 网络与系统
87
+ | 'HTTP_FAILED'
88
+ | 'NO_ACTIVITY'
89
+ | 'APP_INFO_UNAVAILABLE'
90
+ // 浮层
91
+ | 'OVERLAY_NOT_DECLARED'
92
+ | 'OVERLAY_NOT_AUTHORIZED'
93
+ | 'OVERLAY_SYSTEM_PERMISSION_MISSING'
94
+ | 'OVERLAY_NOT_FOUND'
95
+ | 'OVERLAY_DENIED'
96
+ | 'OVERLAY_LIMIT'
97
+ | 'OVERLAY_SERVICE_FAILED'
98
+ | 'SURFACE_NOT_FOUND';
99
+
100
+ /** 页面主题,跟随 App 的明暗设置。 */
101
+ export type AicodeTheme = 'light' | 'dark' | (string & {});
102
+
103
+ /** 浮层的可见性策略。 */
104
+ export type OverlayVisibilityPolicy = 'always' | 'foreground' | 'background';
105
+
106
+ /** 工具审批选择。 */
107
+ export type ApprovalChoice = 'once' | 'always' | 'reject';
108
+
109
+ /** 计划审批选择。 */
110
+ export type PlanApprovalChoice = 'approve' | 'refine';
111
+
112
+ /** 新建会话可用的模式;`auto` 只能由使用者手动选择。 */
113
+ export type ChatMode = 'build' | 'plan';
114
+
115
+ /** 终端标签状态。 */
116
+ export type TerminalState = 'running' | 'finished' | 'cancelled';
117
+
118
+ /** 宿主工具执行结果状态。 */
119
+ export type ToolResultStatus = 'success' | 'error' | 'partial';
120
+
121
+ export interface AicodePageContext {
122
+ /** 当前页面所属插件 ID。 */
123
+ pluginId: string;
124
+ /** 页面实例 ID;同一入口多次打开时不同。 */
125
+ pageId: string;
126
+ /** 页面入口的槽位,配置页为 `config`。 */
127
+ slot?: string;
128
+ /** 从聊天页打开的会话 ID。 */
129
+ sessionId?: string;
130
+ /** 从编辑器或文件树打开时的文件路径。 */
131
+ path?: string;
132
+ isDirectory?: boolean;
133
+ /** 编辑器选区文本。 */
134
+ selection?: string;
135
+ /** 选区语言标识,如 `kotlin`、`typescript`。 */
136
+ language?: string;
137
+ lineStart?: number;
138
+ lineEnd?: number;
139
+ /** 插件版本号。 */
140
+ version: string;
141
+ /** 当前系统语言,如 `zh-CN`。 */
142
+ languageTag: string;
143
+ theme: AicodeTheme;
144
+ workspaceName: string;
145
+ /** 工作区标识;工作区切换后旧页面调用文件方法会得到 `STALE_CONTEXT`。 */
146
+ contextKey: string;
147
+ /** 页面当前是否可见。 */
148
+ visible: boolean;
149
+ /** 当前执行环境的 home 目录。 */
150
+ home: string;
151
+ /** 当前工作区根目录。 */
152
+ workspace: string;
153
+ /** 插件私有数据目录的真实路径,对应虚拟根 `data://`。 */
154
+ dataDir: string;
155
+ }
156
+
157
+ export interface AicodeOverlayContext {
158
+ pluginId: string;
159
+ overlayId: string;
160
+ pageId: string;
161
+ version: string;
162
+ density: number;
163
+ }
164
+
165
+ export type AicodeContext = AicodePageContext | AicodeOverlayContext;
166
+
167
+ /**
168
+ * 已知事件的 payload 形状。`events.on` 的回调拿到的是通用 `AicodeEvent`;
169
+ * 可按事件名取这里的类型断言 payload,或在调用 `on` 时显式指定泛型参数。
170
+ */
171
+ export interface AicodeEventPayloads {
172
+ 'fs.changed': FsChangeEvent;
173
+ 'ui.lifecycle': { visible: boolean; reason: string; contextKey: string };
174
+ 'chat.run.started': { sessionId: string; startedAt: number };
175
+ 'chat.run.finished': { sessionId: string; status: string; error?: string; finishedAt: number };
176
+ }
177
+
178
+ /** 页面收到的宿主或插件事件。 */
179
+ export interface AicodeEvent<T = JsonValue> {
180
+ name: string;
181
+ payload: T;
182
+ }
183
+
184
+ // ---------------------------------------------------------------------------
185
+ // 文件
186
+ // ---------------------------------------------------------------------------
187
+
188
+ /** 文件方法共用的选项。 */
189
+ export interface FsOptions {
190
+ /**
191
+ * 调用方持有的 `context().contextKey`。工作区已经切换时请求返回 `STALE_CONTEXT`,
192
+ * 用于拦截仍在排队的旧项目操作。
193
+ */
194
+ contextKey?: string;
195
+ }
196
+
197
+ export interface FsWatchOptions extends FsOptions {
198
+ /** 递归监听子目录,默认 false。 */
199
+ recursive?: boolean;
200
+ }
201
+
202
+ export interface FsReadResult {
203
+ content: string;
204
+ size: number;
205
+ }
206
+
207
+ export interface FsBinaryResult {
208
+ base64: string;
209
+ size: number;
210
+ }
211
+
212
+ export interface FsEntry {
213
+ name: string;
214
+ isDir: boolean;
215
+ size: number;
216
+ }
217
+
218
+ export interface FsListResult {
219
+ entries: FsEntry[];
220
+ }
221
+
222
+ export interface FsStatResult {
223
+ exists: boolean;
224
+ isDir: boolean;
225
+ size: number;
226
+ }
227
+
228
+ export interface FsChange {
229
+ path: string;
230
+ kind: 'created' | 'modified' | 'deleted';
231
+ }
232
+
233
+ export type FsChangeEvent = {
234
+ subscriptionId: string;
235
+ path: string;
236
+ } & (
237
+ | {
238
+ contextKey: string;
239
+ changes: FsChange[];
240
+ truncated: boolean;
241
+ error?: never;
242
+ }
243
+ | {
244
+ error: { code: string; message: string };
245
+ contextKey?: never;
246
+ changes?: never;
247
+ truncated?: never;
248
+ }
249
+ );
250
+
251
+ // ---------------------------------------------------------------------------
252
+ // 命令与终端
253
+ // ---------------------------------------------------------------------------
254
+
255
+ export interface BashResult {
256
+ output: string;
257
+ /** 命令无法启动时为 null。 */
258
+ exitCode: number | null;
259
+ truncated: boolean;
260
+ }
261
+
262
+ export interface TerminalRunResult {
263
+ tabId: string;
264
+ state: TerminalState;
265
+ }
266
+
267
+ export interface TerminalPollResult {
268
+ output: string;
269
+ /** 下次轮询应传入的偏移。 */
270
+ offset: number;
271
+ state: TerminalState;
272
+ exitCode?: number;
273
+ /** 超出宿主保留的最近 128 KiB 时为 true。 */
274
+ truncated: boolean;
275
+ }
276
+
277
+ export interface TerminalTab {
278
+ tabId: string;
279
+ title: string;
280
+ command: string;
281
+ state: TerminalState;
282
+ }
283
+
284
+ // ---------------------------------------------------------------------------
285
+ // 会话与消息
286
+ // ---------------------------------------------------------------------------
287
+
288
+ export interface ChatSession {
289
+ id: string;
290
+ title: string;
291
+ createdAt: number;
292
+ updatedAt: number;
293
+ mode: ChatMode | (string & {});
294
+ isPinned: boolean;
295
+ parentId?: string;
296
+ subagentType?: string;
297
+ providerId?: string;
298
+ model?: string;
299
+ goal?: string;
300
+ goalStatus?: string;
301
+ reasoningEffort: string;
302
+ totalInputTokens: number;
303
+ totalOutputTokens: number;
304
+ lastInputTokens: number;
305
+ }
306
+
307
+ export interface ChatToolCall {
308
+ id: string;
309
+ name: string;
310
+ /** 参数超过 4000 字符时转为截断字符串并带 `argumentsTruncated`。 */
311
+ arguments: JsonObject | string;
312
+ argumentsTruncated?: boolean;
313
+ }
314
+
315
+ export interface ChatAttachment {
316
+ fileName: string;
317
+ containerPath: string;
318
+ mimeType: string;
319
+ sizeBytes: number;
320
+ isImage: boolean;
321
+ }
322
+
323
+ export interface ChatMessage {
324
+ id: string;
325
+ role: 'user' | 'assistant' | 'tool' | (string & {});
326
+ content: string;
327
+ timestamp: number;
328
+ toolName?: string;
329
+ isError: boolean;
330
+ isCompacted: boolean;
331
+ isContextSummary: boolean;
332
+ isCompactionMarker: boolean;
333
+ inputTokens: number;
334
+ outputTokens: number;
335
+ cachedInputTokens: number;
336
+ /** 思考文本,最多 8000 字符。 */
337
+ reasoning?: string;
338
+ reasoningTruncated?: boolean;
339
+ /** 最多 50 条。 */
340
+ toolCalls?: ChatToolCall[];
341
+ /** 最多 20 条。 */
342
+ attachments?: ChatAttachment[];
343
+ }
344
+
345
+ export interface ChatRun {
346
+ running: boolean;
347
+ /** `running` / `success` / `error` / `cancelled` / `idle` 等。 */
348
+ status: string;
349
+ error?: string;
350
+ startedAt?: number;
351
+ finishedAt?: number;
352
+ }
353
+
354
+ export interface ChatSessionListResult {
355
+ sessions: ChatSession[];
356
+ }
357
+
358
+ export interface ChatSessionResult {
359
+ session: ChatSession;
360
+ }
361
+
362
+ export interface ChatMessageListResult {
363
+ sessionId: string;
364
+ messages: ChatMessage[];
365
+ hasMore: boolean;
366
+ }
367
+
368
+ export interface ChatRunStateResult {
369
+ sessionId: string;
370
+ run: ChatRun;
371
+ }
372
+
373
+ export interface ChatWaitForRunResult {
374
+ timedOut: boolean;
375
+ run: ChatRun;
376
+ }
377
+
378
+ /** 待确认的工具调用。 */
379
+ export interface ToolApprovalRequest {
380
+ id: string;
381
+ toolName: string;
382
+ title: string;
383
+ summary: string;
384
+ details: string;
385
+ argsPreview: string;
386
+ sessionId: string;
387
+ /** 非空时才能提交 `always`。 */
388
+ rememberablePatterns: string[];
389
+ rememberDisabledReason?: string;
390
+ }
391
+
392
+ export interface UserQuestionOption {
393
+ label: string;
394
+ description: string;
395
+ }
396
+
397
+ export interface UserQuestionItem {
398
+ question: string;
399
+ header: string;
400
+ multiSelect: boolean;
401
+ options: UserQuestionOption[];
402
+ }
403
+
404
+ export interface PendingUserQuestion {
405
+ id: string;
406
+ sessionId: string;
407
+ questions: UserQuestionItem[];
408
+ }
409
+
410
+ export interface PlanApprovalRequest {
411
+ id: string;
412
+ sessionId?: string;
413
+ reason: string;
414
+ }
415
+
416
+ export interface ChatApprovalsResult {
417
+ sessionId: string;
418
+ /** 没有待处理项时为 null。 */
419
+ tool: ToolApprovalRequest | null;
420
+ question: PendingUserQuestion | null;
421
+ plan: PlanApprovalRequest | null;
422
+ }
423
+
424
+ /** `chat.resolveQuestion` 的答案项。 */
425
+ export interface UserQuestionAnswer {
426
+ question: string;
427
+ selected: string[];
428
+ customText?: string;
429
+ }
430
+
431
+ // ---------------------------------------------------------------------------
432
+ // 模型句柄
433
+ // ---------------------------------------------------------------------------
434
+
435
+ /** 插件自己声明的提供商当前配置的模型列表。 */
436
+ export interface ProviderModelsResult {
437
+ providerId: string;
438
+ /** 本次操作的模型;仅 addModel / deleteModel 返回。 */
439
+ model?: string;
440
+ models: string[];
441
+ selectedModel: string;
442
+ }
443
+
444
+ export interface ModelProviderInfo {
445
+ id: string;
446
+ name: string;
447
+ type: string;
448
+ enabled: boolean;
449
+ hasKey: boolean;
450
+ isPlugin: boolean;
451
+ isDefault: boolean;
452
+ defaultModel: string;
453
+ selectedModel: string;
454
+ modelCount: number;
455
+ }
456
+
457
+ export interface ModelInfo {
458
+ id: string;
459
+ displayName: string;
460
+ contextTokens: number;
461
+ inputTokens: number | null;
462
+ outputTokens: number | null;
463
+ supportsTools: boolean;
464
+ supportsVision: boolean;
465
+ supportsReasoning: boolean;
466
+ supportsCustomTemperature: boolean;
467
+ supportsImageOutput: boolean;
468
+ modelType: string;
469
+ reasoningLevels?: string[];
470
+ reasoningDefaultLevel?: string;
471
+ inputCostUsdPerM?: number;
472
+ outputCostUsdPerM?: number;
473
+ cacheReadCostUsdPerM?: number;
474
+ cacheWriteCostUsdPerM?: number;
475
+ source: string;
476
+ }
477
+
478
+ export interface ModelHandle {
479
+ id: string;
480
+ providerId: string;
481
+ model: string;
482
+ name?: string;
483
+ params: {
484
+ reasoningEffort?: string;
485
+ maxOutputTokens?: number;
486
+ temperature?: number;
487
+ };
488
+ createdAt: number;
489
+ }
490
+
491
+ export interface ModelProviderState {
492
+ signature?: string;
493
+ thinkingBlocksJson?: string;
494
+ }
495
+
496
+ export interface ModelToolCall {
497
+ id: string;
498
+ name: string;
499
+ /** 单条超过 64 KiB 时转为截断字符串并带 `argumentsTruncated`。 */
500
+ arguments: JsonObject | string;
501
+ argumentsTruncated?: boolean;
502
+ }
503
+
504
+ export interface ModelImage {
505
+ mimeType: string;
506
+ /** 输出图片为 base64;输入图片也可用 `path` 指定文件。 */
507
+ base64?: string;
508
+ path?: string;
509
+ }
510
+
511
+ export interface ModelMessage {
512
+ role: 'user' | 'assistant' | 'tool';
513
+ content: string;
514
+ /** `user` 可带图片。 */
515
+ images?: ModelImage[];
516
+ /** `assistant` 上一轮的工具调用。 */
517
+ toolCalls?: ModelToolCall[];
518
+ reasoning?: string;
519
+ providerState?: ModelProviderState;
520
+ /** `tool` 消息必填,需匹配前面 assistant 的某个 `toolCalls[].id`。 */
521
+ toolCallId?: string;
522
+ /** `tool` 消息必填。 */
523
+ name?: string;
524
+ }
525
+
526
+ export interface ModelToolDefinition {
527
+ /** `app` 引用宿主内置 / MCP 工具,`custom` 由插件自己执行。 */
528
+ type: 'app' | 'custom';
529
+ name: string;
530
+ description?: string;
531
+ inputSchema?: JsonObject;
532
+ }
533
+
534
+ export interface ModelParams {
535
+ reasoningEffort?: string;
536
+ maxOutputTokens?: number;
537
+ temperature?: number;
538
+ }
539
+
540
+ export interface ModelCreateOptions {
541
+ providerId: string;
542
+ model: string;
543
+ name?: string;
544
+ systemPrompt?: string;
545
+ params?: ModelParams;
546
+ }
547
+
548
+ export interface ModelStartOptions {
549
+ handleId: string;
550
+ messages: ModelMessage[];
551
+ tools?: ModelToolDefinition[];
552
+ systemPrompt?: string;
553
+ params?: ModelParams;
554
+ }
555
+
556
+ export interface ModelReadOptions {
557
+ streamId: string;
558
+ /** 上次读取返回的 cursor;首次省略或传 0。 */
559
+ cursor?: number;
560
+ maxEvents?: number;
561
+ /** 没有新事件时的最长等待,默认 15000。 */
562
+ waitMs?: number;
563
+ }
564
+
565
+ export type ModelStreamEvent =
566
+ | { type: 'text'; text: string }
567
+ | { type: 'reasoning'; text: string }
568
+ | { type: 'toolCall'; name: string }
569
+ | {
570
+ type: 'retry';
571
+ attempt: number;
572
+ maxRetries: number;
573
+ error: { code: string; statusCode?: number };
574
+ }
575
+ | { type: 'keySwitch'; index: number; total: number };
576
+
577
+ export interface ModelFinal {
578
+ content: string;
579
+ contentTruncated?: boolean;
580
+ reasoning?: string;
581
+ reasoningTruncated?: boolean;
582
+ /** 最多 32 条。 */
583
+ toolCalls?: ModelToolCall[];
584
+ toolCallsTruncated?: boolean;
585
+ providerState?: ModelProviderState;
586
+ images?: ModelImage[];
587
+ imageCount?: number;
588
+ imagesTruncated?: boolean;
589
+ stopReason?: string;
590
+ stopDetail?: string;
591
+ usage: {
592
+ input: number;
593
+ output: number;
594
+ cachedInput: number;
595
+ cacheCreation: number;
596
+ };
597
+ durationMs: number;
598
+ }
599
+
600
+ export interface ModelReadResult {
601
+ streamId: string;
602
+ events: ModelStreamEvent[];
603
+ cursor: number;
604
+ done: boolean;
605
+ status?: 'success' | 'error' | 'cancelled';
606
+ final?: ModelFinal;
607
+ error?: { code: string; message: string; partialContent?: string };
608
+ }
609
+
610
+ // ---------------------------------------------------------------------------
611
+ // 工具、MCP 与网络
612
+ // ---------------------------------------------------------------------------
613
+
614
+ export interface HostToolInfo {
615
+ name: string;
616
+ description: string;
617
+ /** `builtin` / `mcp` 等。 */
618
+ type: string;
619
+ permissionPolicy: string;
620
+ capabilities: string[];
621
+ /** 仅 `includeSchema` 为 true 时出现。 */
622
+ inputSchema?: JsonObject;
623
+ }
624
+
625
+ export interface ToolsListResult {
626
+ tools: HostToolInfo[];
627
+ }
628
+
629
+ export interface ToolExecuteResult {
630
+ status: ToolResultStatus;
631
+ data?: JsonValue;
632
+ message?: string;
633
+ code?: string;
634
+ images?: ModelImage[];
635
+ imagesTruncated?: boolean;
636
+ dataTruncated?: boolean;
637
+ }
638
+
639
+ export interface ToolExecuteOptions {
640
+ sessionId?: string;
641
+ context?: { path?: string; selection?: string; language?: string };
642
+ /** 默认 120000,范围 1000–600000。 */
643
+ timeoutMs?: number;
644
+ }
645
+
646
+ export interface ToolsPendingResult {
647
+ /** 没有待审批请求时为 null。 */
648
+ approval: ToolApprovalRequest | null;
649
+ }
650
+
651
+ export interface McpStatusResult {
652
+ servers: Array<{ name: string; state: string; toolCount: number; error: string | null }>;
653
+ }
654
+
655
+ export interface HttpRequestOptions {
656
+ url: string;
657
+ method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | (string & {});
658
+ headers?: Record<string, string>;
659
+ body?: string;
660
+ /** 单位秒,默认 60。 */
661
+ timeout?: number;
662
+ }
663
+
664
+ export interface HttpResponse {
665
+ status: number;
666
+ headers: Record<string, string>;
667
+ /** 响应体,上限 1 MiB。 */
668
+ body: string;
669
+ }
670
+
671
+ // ---------------------------------------------------------------------------
672
+ // 系统
673
+ // ---------------------------------------------------------------------------
674
+
675
+ export interface AppInfo {
676
+ packageName: string;
677
+ versionName: string;
678
+ versionCode: number;
679
+ sdkInt: number;
680
+ languageTag: string;
681
+ isForeground: boolean;
682
+ }
683
+
684
+ export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
685
+
686
+ export interface OverlayInfo {
687
+ overlayId: string;
688
+ pluginId: string;
689
+ width: number;
690
+ height: number;
691
+ /** 创建结果的位置,单位为屏幕像素。 */
692
+ x: number;
693
+ y: number;
694
+ draggable: boolean;
695
+ snap: string;
696
+ visibilityPolicy: OverlayVisibilityPolicy;
697
+ }
698
+
699
+ export interface OverlaySelfInfo extends OverlayInfo {
700
+ /** 当前显示位置,单位为 dp。 */
701
+ x: number;
702
+ y: number;
703
+ density: number;
704
+ foreground: boolean;
705
+ }
706
+
707
+ export interface OverlayRect {
708
+ left: number;
709
+ top: number;
710
+ width: number;
711
+ height: number;
712
+ topRadius?: number;
713
+ bottomRadius?: number;
714
+ coversBottom?: boolean;
715
+ }
716
+
717
+ export interface OverlayCreateOptions {
718
+ /** 清单 `contributes.overlay.surfaces[].id`;省略时取第一个。 */
719
+ surface?: string;
720
+ width?: number;
721
+ height?: number;
722
+ visibilityPolicy?: OverlayVisibilityPolicy;
723
+ x?: number;
724
+ y?: number;
725
+ }
726
+
727
+ export interface OverlayMessage {
728
+ type: string;
729
+ [key: string]: JsonValue;
730
+ }
731
+
732
+ /** 宿主注入的页面桥;页面脚本加载 `/__aicode/aicode.js` 后可用。 */
733
+ export interface AicodeBridge {
734
+ /** 读取当前页面上下文;未使用的字段不出现。 */
735
+ context(): Promise<AicodeContext>;
736
+
737
+ /** 轻量 Toast 提示。 */
738
+ toast(message: string): Promise<{ ok: boolean }>;
739
+
740
+ /** 在对话中显示可关闭提示条;按钮点击回调同插件进程的 handler。 */
741
+ tip(options: { title?: string; text: string; action?: { label: string; handler: string } }): Promise<{
742
+ ok: boolean;
743
+ }>;
744
+
745
+ app: {
746
+ /** App 是否有 Activity 处于 STARTED。 */
747
+ isForeground(): Promise<boolean>;
748
+ info(): Promise<AppInfo>;
749
+ };
750
+
751
+ ui: {
752
+ /** 关闭插件页并回到打开前的位置。 */
753
+ close(): Promise<{ ok: boolean }>;
754
+ /** 用系统浏览器打开 http/https 链接。 */
755
+ openUrl(url: string): Promise<{ ok: boolean }>;
756
+ /** 打开或关闭页面内全屏弹层,并上报挖孔矩形。 */
757
+ setOverlay(visible: boolean, rect?: OverlayRect): Promise<{ ok: boolean }>;
758
+ /**
759
+ * 接管页面内返回;handler 同步返回 true 表示已处理。
760
+ * 解析为注销函数。
761
+ */
762
+ onBack(handler: () => boolean): Promise<() => void>;
763
+ };
764
+
765
+ /** 订阅宿主与插件进程事件,返回取消订阅函数。 */
766
+ events: {
767
+ on<T = JsonValue>(handler: (event: AicodeEvent<T>) => void): () => void;
768
+ };
769
+
770
+ /** 宿主托管的系统浮层。 */
771
+ overlay: {
772
+ create(options?: OverlayCreateOptions): Promise<OverlayInfo>;
773
+ update(
774
+ overlayId: string,
775
+ options: {
776
+ dx?: number;
777
+ dy?: number;
778
+ width?: number;
779
+ height?: number;
780
+ visible?: boolean;
781
+ visibilityPolicy?: OverlayVisibilityPolicy;
782
+ }
783
+ ): Promise<{ ok: boolean }>;
784
+ close(overlayId: string): Promise<{ ok: boolean }>;
785
+ /** 浮层页面关闭自身。 */
786
+ close(): Promise<null>;
787
+ self(): Promise<OverlaySelfInfo>;
788
+ /** 浮层页面上报拖拽区域,单位为 CSS 像素。 */
789
+ setDragRegion(rect: { left: number; top: number; width: number; height: number }): Promise<void>;
790
+ moveBy(dx: number, dy: number): Promise<void>;
791
+ resize(
792
+ width: number,
793
+ height: number,
794
+ options?: { animate?: boolean; x?: number; y?: number }
795
+ ): Promise<{ width: number; height: number }>;
796
+ setVisibilityPolicy(policy: OverlayVisibilityPolicy): Promise<void>;
797
+ /** 接收宿主消息:state / click / dragStart / dragEnd / longPress / snap。 */
798
+ onMessage(handler: (message: OverlayMessage) => void): () => void;
799
+ /** 把交互或状态回传给插件进程;需要插件实现 overlay.message handler。 */
800
+ postMessage(payload?: JsonValue): Promise<void>;
801
+ };
802
+
803
+ /** 调用同一插件常驻进程的 handler;不支持跨插件调用。 */
804
+ invoke<T = unknown>(handler: string, args?: Record<string, unknown>): Promise<T>;
805
+
806
+ /** 在当前工作区执行一次性命令;`timeout` 单位秒,默认 30、上限 300。 */
807
+ bash(command: string, options?: { timeout?: number }): Promise<BashResult>;
808
+
809
+ /** 通过 Shizuku 在 Android 系统执行命令;需插件声明范围且使用者已单独授权。 */
810
+ shizuku: {
811
+ exec(command: string, options?: { timeout?: number }): Promise<BashResult>;
812
+ };
813
+
814
+ terminal: {
815
+ run(command: string, options?: { title?: string }): Promise<TerminalRunResult>;
816
+ poll(tabId: string, offset: number): Promise<TerminalPollResult>;
817
+ stop(tabId: string): Promise<{ ok: boolean }>;
818
+ close(tabId: string): Promise<{ ok: boolean }>;
819
+ /** `appendNewline` 默认 true。 */
820
+ write(tabId: string, text: string, options?: { appendNewline?: boolean }): Promise<{ ok: boolean }>;
821
+ list(): Promise<TerminalTab[]>;
822
+ };
823
+
824
+ chat: {
825
+ listSessions(options?: { includeSubagents?: boolean; limit?: number }): Promise<ChatSessionListResult>;
826
+ createSession(options?: { title?: string; mode?: ChatMode }): Promise<ChatSessionResult>;
827
+ listMessages(
828
+ sessionId: string,
829
+ options?: { limit?: number; before?: number; after?: number }
830
+ ): Promise<ChatMessageListResult>;
831
+ /** 只表示请求已入队;需要聊天页存活。 */
832
+ sendMessage(sessionId: string, text: string): Promise<{ sessionId: string; accepted: boolean }>;
833
+ setDraft(
834
+ text: string,
835
+ options?: { sessionId?: string; append?: boolean }
836
+ ): Promise<{ sessionId?: string; accepted: boolean }>;
837
+ stop(sessionId: string): Promise<{ sessionId: string; accepted: boolean }>;
838
+ openSession(sessionId: string): Promise<{ sessionId: string; accepted: boolean }>;
839
+ getSession(sessionId: string): Promise<ChatSessionResult>;
840
+ renameSession(sessionId: string, title: string): Promise<{ ok: boolean }>;
841
+ pinSession(sessionId: string, pinned: boolean): Promise<{ ok: boolean }>;
842
+ /** 提交删除请求;accepted 表示已入队。 */
843
+ deleteSession(sessionId: string): Promise<{ sessionId: string; accepted: boolean }>;
844
+ getRunState(sessionId: string): Promise<ChatRunStateResult>;
845
+ waitForRun(sessionId: string, options?: { timeoutMs?: number }): Promise<ChatWaitForRunResult>;
846
+ listApprovals(sessionId: string): Promise<ChatApprovalsResult>;
847
+ /** `always` 仅在 `rememberablePatterns` 非空时可用。 */
848
+ resolveToolApproval(
849
+ sessionId: string,
850
+ requestId: string,
851
+ choice: ApprovalChoice
852
+ ): Promise<{ ok: boolean }>;
853
+ resolveQuestion(
854
+ sessionId: string,
855
+ requestId: string,
856
+ answers: UserQuestionAnswer[]
857
+ ): Promise<{ ok: boolean }>;
858
+ resolvePlanApproval(
859
+ sessionId: string,
860
+ requestId: string,
861
+ choice: PlanApprovalChoice
862
+ ): Promise<{ ok: boolean }>;
863
+ };
864
+
865
+ /**
866
+ * 维护本插件在 `contributes.providers` 中声明的提供商。
867
+ * 只能访问本插件声明的条目;其它插件或用户自建的提供商一律按不存在处理。
868
+ */
869
+ providers: {
870
+ /** 读取当前配置的模型列表;不访问上游服务。 */
871
+ listModels(providerId: string): Promise<ProviderModelsResult>;
872
+ /** 追加模型;重复添加视为成功,尚无选中模型时自动选中该模型。 */
873
+ addModel(
874
+ providerId: string,
875
+ model: string,
876
+ options?: { contextTokens?: number }
877
+ ): Promise<ProviderModelsResult>;
878
+ /** 删除模型;不存在视为成功,删除的是选中模型时回退到剩余模型。 */
879
+ deleteModel(providerId: string, model: string): Promise<ProviderModelsResult & {
880
+ removed: boolean;
881
+ }>;
882
+ /** 修改模型上下文窗口,用于自动识别不到的模型。 */
883
+ setModelContext(
884
+ providerId: string,
885
+ model: string,
886
+ contextTokens: number
887
+ ): Promise<{ providerId: string; model: string; contextTokens: number }>;
888
+ /** 设置插件提供商的 API Key;空串清除,旧值不会返回。 */
889
+ setApiKey(providerId: string, apiKey: string): Promise<{
890
+ providerId: string;
891
+ hasKey: boolean;
892
+ }>;
893
+ };
894
+
895
+ /** 模型句柄;需要清单声明 `contributes.modelAccess`。 */
896
+ model: {
897
+ listProviders(): Promise<{ providers: ModelProviderInfo[] }>;
898
+ listModels(providerId: string | { providerId: string }): Promise<{
899
+ providerId: string;
900
+ models: ModelInfo[];
901
+ }>;
902
+ create(options: ModelCreateOptions): Promise<{ handle: ModelHandle }>;
903
+ close(handleId: string | { handleId: string }): Promise<{ ok: boolean }>;
904
+ start(options: ModelStartOptions): Promise<{ streamId: string }>;
905
+ read(options: ModelReadOptions): Promise<ModelReadResult>;
906
+ cancel(streamId: string | { streamId: string }): Promise<{ ok: boolean }>;
907
+ /** `start` + `read` 循环,逐条回调事件并返回最终 read 结果。 */
908
+ stream(
909
+ options: Omit<ModelStartOptions, 'waitMs'> & { waitMs?: number },
910
+ onEvent: (event: ModelStreamEvent) => void
911
+ ): Promise<ModelReadResult>;
912
+ };
913
+
914
+ fs: {
915
+ read(path: string, options?: FsOptions): Promise<FsReadResult>;
916
+ write(path: string, content: string, options?: FsOptions): Promise<void>;
917
+ list(path: string, options?: FsOptions): Promise<FsListResult>;
918
+ delete(path: string, options?: FsOptions): Promise<void>;
919
+ stat(path: string, options?: FsOptions): Promise<FsStatResult>;
920
+ mkdir(path: string, options?: FsOptions): Promise<void>;
921
+ /** 目标已存在时返回 `FILE_EXISTS`。 */
922
+ rename(from: string, to: string, options?: FsOptions): Promise<void>;
923
+ copy(from: string, to: string, options?: FsOptions & { overwrite?: boolean }): Promise<void>;
924
+ append(path: string, content: string, options?: FsOptions): Promise<void>;
925
+ readBinary(path: string, options?: FsOptions): Promise<FsBinaryResult>;
926
+ writeBinary(path: string, base64: string, options?: FsOptions): Promise<void>;
927
+ /** 订阅文件来源变化;解析为取消订阅函数。 */
928
+ watch(
929
+ path: string,
930
+ options: FsWatchOptions,
931
+ handler: (event: FsChangeEvent) => void
932
+ ): Promise<() => Promise<void>>;
933
+ watch(path: string, handler: (event: FsChangeEvent) => void): Promise<() => Promise<void>>;
934
+ };
935
+
936
+ clipboard: {
937
+ read(): Promise<{ text: string }>;
938
+ write(text: string): Promise<{ ok: boolean }>;
939
+ };
940
+
941
+ share: {
942
+ text(text: string, options?: { title?: string }): Promise<{ ok: boolean }>;
943
+ };
944
+
945
+ /** 插件私有加密键值存储;值上限 64 KiB。 */
946
+ secrets: {
947
+ get(key: string): Promise<{ value: string }>;
948
+ set(key: string, value: string): Promise<{ ok: boolean }>;
949
+ delete(key: string): Promise<{ ok: boolean }>;
950
+ list(): Promise<{ keys: string[] }>;
951
+ };
952
+
953
+ /** 宿主工具目录与执行;只允许内置 / MCP 工具。 */
954
+ tools: {
955
+ list(options?: { includeSchema?: boolean }): Promise<ToolsListResult>;
956
+ execute(
957
+ name: string,
958
+ args: Record<string, unknown>,
959
+ options?: ToolExecuteOptions
960
+ ): Promise<ToolExecuteResult>;
961
+ pending(sessionId?: string): Promise<ToolsPendingResult>;
962
+ resolve(requestId: string, choice: ApprovalChoice): Promise<{ ok: boolean }>;
963
+ };
964
+
965
+ mcp: {
966
+ status(): Promise<McpStatusResult>;
967
+ };
968
+
969
+ /** 宿主代理 HTTP 请求;不跟随重定向、不注入宿主凭据。 */
970
+ http: {
971
+ request(options: HttpRequestOptions): Promise<HttpResponse>;
972
+ };
973
+
974
+ log: {
975
+ write(level: LogLevel, message: string, options?: { tag?: string }): Promise<{ ok: boolean }>;
976
+ };
977
+
978
+ /** 设置 CSS 变量并派发 `aicode:theme` 事件。 */
979
+ applyTheme(variables: Record<string, string | number>): void;
980
+ }
981
+
982
+ /** 宿主注入的组件库全局对象(`/__aicode/aicode-ui-vue.js`)。 */
983
+ export interface AicodeUI {
984
+ install(app: unknown): void;
985
+ renderMarkdown(text: string): string;
986
+ icons: Record<string, string>;
987
+ components: Record<string, unknown>;
988
+ }
989
+
990
+ declare global {
991
+ const aicode: AicodeBridge;
992
+ const AicodeUI: AicodeUI;
993
+
994
+ interface Window {
995
+ aicode: AicodeBridge;
996
+ AicodeUI?: AicodeUI;
997
+ }
998
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.