Skip to content

Commit

Permalink
chore: update ai module doc (#149)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ricbet
Ricbet authored Sep 18, 2024
1 parent ce387ad commit ba91138
Show file tree
Hide file tree
Showing 2 changed files with 253 additions and 75 deletions.
160 changes: 126 additions & 34 deletions docs/integrate/module-usage/ai-native-module.en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ Complete example code can be found in ai.back.service.ts.

```typescript
@Injectable()
export class AiBackService extends BaseAIBackService implements IAIBackService {
export class AiBackService implements IAIBackService<ReqeustResponse, ChatReadableStream> {
// Here you can interact with any large model API interface
}
```
Expand Down Expand Up @@ -144,45 +144,15 @@ Other capabilities' Provider API documentation is as follows:
| Method Name | Description | Parameter Type | Return Type |
| ------------------------------ | ------------------------------------------------------------------- | --------------------------------- | ----------- |
| middleware | Provides middleware to extend some AI capabilities | IAIMiddleware | void |
| registerInlineChatFeature | Registers inline chat related features | IInlineChatFeatureRegistry | void |
| registerChatFeature | Registers chat panel related features | IChatFeatureRegistry | void |
| registerChatRender | Registers chat panel related rendering layers, can customize render | IChatRenderRegistry | void |
| registerResolveConflictFeature | Registers intelligent conflict resolution related features | IResolveConflictRegistry | void |
| registerRenameProvider | Registers intelligent renaming related features | IRenameCandidatesProviderRegistry | void |
| registerProblemFixFeature |
Register smart repair related functions | IProblemFixProviderRegistry | void |
| registerIntelligentCompletionFeature | Register for smart code completion related functions | IIntelligentCompletionsRegistry | void |

#### IAIMiddleware

| Method Name | Description | Parameter Type | Return Type |
| --------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| language.provideInlineCompletions | Extends inline completion capabilities | (model: ITextModel, position: Position, token: CancellationToken, next: (reqBean: CompletionRequestBean) => MaybePromise, completionRequestBean: CompletionRequestBean) => MaybePromise | void |

Example:

```typescript
middleware: IAIMiddleware = {
language: {
provideInlineCompletions: async (
model: ITextModel,
position: Position,
token: CancellationToken,
next: (reqBean: CompletionRequestBean) => MaybePromise,
completionRequestBean: CompletionRequestBean
) => {
// Custom logic based on parameter information to alter the code completion results
// For example
return {
sessionId: completionRequestBean.sessionId,
codeModelList: [
{
content: 'Hello OpenSumi!'
}
]
};
}
}
};
```

#### IInlineChatFeatureRegistry

Expand Down Expand Up @@ -381,6 +351,127 @@ registerRenameProvider(registry: IRenameCandidatesProviderRegistry): void {
}
```

#### IProblemFixProviderRegistry

| Method Name | Description | Parameter Type | Return Type |
| --------------------------------- | ---------------------- | ------------------------ | -------- |
| registerHoverFixProvider | Register a provider for problem diagnosis | IHoverFixHandler | void |

Example:

```typescript
registerProblemFixFeature(registry: IProblemFixProviderRegistry): void {
registry.registerHoverFixProvider({
provideFix: async (
editor: ICodeEditor,
context: IProblemFixContext,
token: CancellationToken,
): Promise<ChatResponse | InlineChatController> => {
const { marker, editRange } = context;
const prompt = 'Self-assembled prompts for problem diagnosis';

const controller = new InlineChatController({ enableCodeblockRender: true });
const stream = await this.aiBackService.requestStream(prompt, {}, token);
controller.mountReadable(stream);

return controller;
},
});
}
```

#### IIntelligentCompletionsRegistry

| Method Name | Description | Parameter Type | Return Type |
| --------------------------------- | ---------------------- | ------------------------ | -------- |
| registerIntelligentCompletionProvider | Register a smart completion provider | IIntelligentCompletionProvider | void |

Note: Configuring the `enableMultiLine` field in the returned completion list can enable multi-line completion.

Example:

```typescript
registerIntelligentCompletionFeature(registry: IIntelligentCompletionsRegistry): void {
registry.registerIntelligentCompletionProvider(async (editor, position, bean, token) => {
const model = editor.getModel()!;
const value = model.getValueInRange({
startLineNumber: position.lineNumber,
startColumn: 1,
endLineNumber: position.lineNumber + 3,
endColumn: model?.getLineMaxColumn(position.lineNumber + 3),
});

const cancelController = new AbortController();
const { signal } = cancelController;

token.onCancellationRequested(() => {
cancelController.abort();
});

const getRandomString = (length) => {
const characters = 'opensumi';
let result = '';
for (let i = 0; i < length; i++) {
result += characters.charAt(Math.floor(Math.random() * characters.length));
}
return result;
};

/**
* 随机增删字符
*/
const insertRandomStrings = (originalString) => {
const minChanges = 2;
const maxChanges = 5;
const changesCount = Math.floor(Math.random() * (maxChanges - minChanges + 1)) + minChanges;
let modifiedString = originalString;
for (let i = 0; i < changesCount; i++) {
const randomIndex = Math.floor(Math.random() * originalString.length);
const operation = Math.random() < 0.5 ? 'delete' : 'insert';
if (operation === 'delete') {
modifiedString = modifiedString.slice(0, randomIndex) + modifiedString.slice(randomIndex + 1);
} else {
const randomChar = getRandomString(1);
modifiedString = modifiedString.slice(0, randomIndex) + randomChar + modifiedString.slice(randomIndex);
}
}
return modifiedString;
};

try {
await new Promise((resolve, reject) => {
const timeout = setTimeout(resolve, 1000);

signal.addEventListener('abort', () => {
clearTimeout(timeout);
reject(new DOMException('Aborted', 'AbortError'));
});
});

return {
items: [
{
insertText: insertRandomStrings(value),
range: {
startLineNumber: position.lineNumber,
startColumn: 1,
endLineNumber: position.lineNumber + 3,
endColumn: model?.getLineMaxColumn(position.lineNumber + 3),
},
},
],
// Whether to enable multi-line completion
enableMultiLine: true,
};
} catch (error) {
if (error.name === 'AbortError') {
return { items: [] };
}
throw error;
}
});
}

**Complete example code can be found in [ai-native.contribution.ts](https://github.com/opensumi/core/blob/main/packages/startup/entry/sample-modules/ai-native/ai-native.contribution.ts).**

## Related Configuration
Expand All @@ -406,6 +497,7 @@ The AI Native Config-related configuration parameters can control the on/off sta
| supportsInlineCompletion | boolean | Whether to enable the code intelligent completion feature |
| supportsConflictResolve | boolean | Whether to enable the AI intelligent conflict resolution feature |
| supportsRenameSuggestions | boolean | Whether to enable the AI to provide renaming suggestions feature |
| supportsProblemFix | boolean | Whether to enable AI problem diagnosis capability |
| supportsTerminalDetection | boolean | Whether to enable the AI terminal detection feature |
| supportsTerminalCommandSuggest | boolean | Whether to enable the AI terminal command suggestion feature |

Expand Down
168 changes: 127 additions & 41 deletions docs/integrate/module-usage/ai-native-module.zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,11 @@ const app = new ClientApp(opts);

> 完整示例代码见 [ai.back.service.ts](https://github.com/opensumi/core/blob/main/packages/startup/entry/sample-modules/ai-native/ai.back.service.ts)
**1. 新建一个后端 service 文件，并继承 BaseAIBackService 服务**
**1. 新建一个后端 service 文件**

```typescript
@Injectable()
export class AiBackService extends BaseAIBackService
implements IAIBackService<ReqeustResponse, ChatReadableStream> {
export class AiBackService implements IAIBackService<ReqeustResponse, ChatReadableStream> {
// 在这里可以跟任何的大模型 API 做接口交互

// 例如 request 可以一次性返回大模型的返回结果
Expand Down Expand Up @@ -203,50 +202,14 @@ export class AiNativeContribution implements AINativeCoreContribution {
| 方法名 | 描述 | 参数类型 | 返回类型 |
| ------------------------------ | ------------------------------------------- | --------------------------------- | -------- |
| middleware | 提供中间件来扩展部分 AI 能力 | IAIMiddleware | void |
| registerInlineChatFeature | 注册 inline chat 相关功能 | IInlineChatFeatureRegistry | void |
| registerChatFeature | 注册 chat 面板相关功能 | IChatFeatureRegistry | void |
| registerChatRender | 注册 chat 面板相关渲染层，可以自定义 render | IChatRenderRegistry | void |
| registerResolveConflictFeature | 注册智能解决冲突相关功能 | IResolveConflictRegistry | void |
| registerRenameProvider | 注册智能重命名相关功能 | IRenameCandidatesProviderRegistry | void |
| registerProblemFixFeature | 注册智能修复相关功能 | IProblemFixProviderRegistry | void |
| registerIntelligentCompletionFeature | 注册智能代码补全相关功能 | IIntelligentCompletionsRegistry | void |

#### IAIMiddleware

| 方法名 | 描述 | 参数类型 | 返回类型 |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| language.provideInlineCompletions | 扩展内联补全能力 | (model: ITextModel, position: Position, token: CancellationToken, next: (reqBean: CompletionRequestBean) => MaybePromise<IAICompletionResultModel | null>, completionRequestBean: CompletionRequestBean) => MaybePromise<IAICompletionResultModel | null> | void |

用例：

```typescript
middleware: IAIMiddleware = {
language: {
provideInlineCompletions: async (
model: ITextModel,
position: Position,
token: CancellationToken,
next: (
reqBean: CompletionRequestBean
) => MaybePromise<IAICompletionResultModel>,
completionRequestBean: CompletionRequestBean
) => {
// 在这里可以根据参数信息做一些自定义逻辑，来改变代码补全返回的结果
// 例如
return {
sessionId: completionRequestBean.sessionId,
codeModelList: [
{
content: 'Hello OpenSumi!'
}
]
};

// 当然也可以直接返回原始的代码补全结果（该结果会直接请求 back service 后端服务的 requestCompletion 方法）
return next(completionRequestBean);
}
}
};
```

#### IInlineChatFeatureRegistry

Expand Down Expand Up @@ -457,6 +420,128 @@ registerRenameProvider(registry: IRenameCandidatesProviderRegistry): void {
}
```

#### IProblemFixProviderRegistry

| 方法名 | 描述 | 参数类型 | 返回类型 |
| --------------------------------- | ---------------------- | ------------------------ | -------- |
| registerHoverFixProvider | 注册问题诊断的提供者 | IHoverFixHandler | void |

用例:

```typescript
registerProblemFixFeature(registry: IProblemFixProviderRegistry): void {
registry.registerHoverFixProvider({
provideFix: async (
editor: ICodeEditor,
context: IProblemFixContext,
token: CancellationToken,
): Promise<ChatResponse | InlineChatController> => {
const { marker, editRange } = context;
const prompt = '可自行组装问题诊断的 prompt';

const controller = new InlineChatController({ enableCodeblockRender: true });
const stream = await this.aiBackService.requestStream(prompt, {}, token);
controller.mountReadable(stream);

return controller;
},
});
}
```

#### IIntelligentCompletionsRegistry

| 方法名 | 描述 | 参数类型 | 返回类型 |
| --------------------------------- | ---------------------- | ------------------------ | -------- |
| registerIntelligentCompletionProvider | 注册智能补全的提供者 | IIntelligentCompletionProvider | void |

说明: 在返回的补全列表当中配置 `enableMultiLine` 字段可开启多行补全的能力

用例:

```typescript
registerIntelligentCompletionFeature(registry: IIntelligentCompletionsRegistry): void {
registry.registerIntelligentCompletionProvider(async (editor, position, bean, token) => {
const model = editor.getModel()!;
const value = model.getValueInRange({
startLineNumber: position.lineNumber,
startColumn: 1,
endLineNumber: position.lineNumber + 3,
endColumn: model?.getLineMaxColumn(position.lineNumber + 3),
});

const cancelController = new AbortController();
const { signal } = cancelController;

token.onCancellationRequested(() => {
cancelController.abort();
});

const getRandomString = (length) => {
const characters = 'opensumi';
let result = '';
for (let i = 0; i < length; i++) {
result += characters.charAt(Math.floor(Math.random() * characters.length));
}
return result;
};

/**
* 随机增删字符
*/
const insertRandomStrings = (originalString) => {
const minChanges = 2;
const maxChanges = 5;
const changesCount = Math.floor(Math.random() * (maxChanges - minChanges + 1)) + minChanges;
let modifiedString = originalString;
for (let i = 0; i < changesCount; i++) {
const randomIndex = Math.floor(Math.random() * originalString.length);
const operation = Math.random() < 0.5 ? 'delete' : 'insert';
if (operation === 'delete') {
modifiedString = modifiedString.slice(0, randomIndex) + modifiedString.slice(randomIndex + 1);
} else {
const randomChar = getRandomString(1);
modifiedString = modifiedString.slice(0, randomIndex) + randomChar + modifiedString.slice(randomIndex);
}
}
return modifiedString;
};

try {
await new Promise((resolve, reject) => {
const timeout = setTimeout(resolve, 1000);

signal.addEventListener('abort', () => {
clearTimeout(timeout);
reject(new DOMException('Aborted', 'AbortError'));
});
});

return {
items: [
{
insertText: insertRandomStrings(value),
range: {
startLineNumber: position.lineNumber,
startColumn: 1,
endLineNumber: position.lineNumber + 3,
endColumn: model?.getLineMaxColumn(position.lineNumber + 3),
},
},
],
// 是否启动多行补全
enableMultiLine: true,
};
} catch (error) {
if (error.name === 'AbortError') {
return { items: [] };
}
throw error;
}
});
}
```

**完整示例代码见 [ai-native.contribution.ts](https://github.com/opensumi/core/blob/main/packages/startup/entry/sample-modules/ai-native/ai-native.contribution.ts)**

## 相关配置
Expand All @@ -482,6 +567,7 @@ AI Native Config 相关的配置参数可以控制所有 AI 能力的开关
| supportsInlineCompletion | boolean | 是否开启代码智能补全功能 |
| supportsConflictResolve | boolean | 是否开启 AI 智能解决冲突的功能 |
| supportsRenameSuggestions | boolean | 是否开启 AI 提供重命名建议的功能 |
| supportsProblemFix | boolean | 是否开启 AI 问题诊断能力 |
| supportsTerminalDetection | boolean | 是否开启 AI 终端检测功能 |
| supportsTerminalCommandSuggest | boolean | 是否开启 AI 终端命令建议功能 |

Expand Down

0 comments on commit ba91138

Please sign in to comment.