企业过滤器配置

• 处理方式：支持通过正则表达式的方式配置过滤器，且支持 3 种模式。

  匹配规则时不处理	匹配到正则后，不做任何处理。
  匹配规则时拦截	匹配到正则后，直接拦截请求，阻断模型请求。
  匹配规则时替换内容	匹配到正则后，按照配置替换内容。

• 消息通知：支持开启消息通知，通过 webhook 的方式，推送到所需要的消息接收平台。

• 执行顺序：按照配置的排序执行。

• 正则数量限制：最多可添加10条。

• 正则表达式标准：正则配置遵循 ECMAScript 标准，支持i（不区分大小写）、g（全局匹配）、s（DOTALL 模式）等常用标志位。

• 正则配置示例：

  规则名称	正则表达式	替换内容	原文	替换后
  身份证号	(?<pre>.*)(\d{15})((\d{2})([0-9Xx]))(?<post>.*)	$<pre>***$<post>	身份证号：330204197709022312。	身份证号：***。
  邮箱	\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*	***	我的邮箱是 lin***@aliyunmail.com	我的邮箱是 ***
  密码	(.*password=)([\w\d]+)(.*)	$1***$3	{password=1213213}	{password=***}

步骤一：脚本开发

目前支持使用 TypeScript 语言进行脚本开发，可以参考样例进行代码开发，操作步骤如下：

1. 下载模板代码库：单击仓库地址：lingma-extension-template，该模板仓库集成了开发脚本所需的脚手架，请仔细阅读README.md文件和代码示例。

2. 实现“前置处理”接口：实现接口RequestPreHandler，API 可参考自定义脚本 API，以下为一个示例片段SensitiveContentFilter.ts的实现。

   /**
    * 敏感内容过滤器，通过该过滤器可以实现对发送给模型的数据进行敏感信息预处理
    */
   export const sensitiveContentFilter: RequestPreHandler = {
     handle: async (request: RawRequest, SDKTool: LingmaSDKTool) => {
       const dataMap = PayloadUtil.getPayloadData(request.payload);
       for (const [key, value] of dataMap.entries()) {
         if (value.includes('password')) {
           return ResultUtil.buildBlockResult('内容包含password');
         }
       }
       // 如果需要针对不同的 action 做差异化处理，则参考如下实现
       switch (request.action) {
         case ActionEnum.COMPLETION:
           // do something
           break;
         case ActionEnum.CODE_PROBLEM_SOLVE:
           // do something
           break;
         default:
           return ResultUtil.buildNoOpsResult();
       }
       return ResultUtil.buildNoOpsResult();
     },
   };

3. 运行调试代码，通过运行main方法来测试脚本是否符合预期，操作步骤如下：

   步骤一

   编辑src/index.ts文件，修改main函数，调整实际需要调试代码，如下示例： async function main() { const value1 = ['password=123', 'abc']; const value2 = 'hello world'; const dataMap = new Map<PayloadDataKeyEnum, PayloadDataValueType>(); dataMap.set(PayloadDataKeyEnum.SELECTED_CODE, value1); dataMap.set(PayloadDataKeyEnum.USER_INPUT, value2); const mockRequest: RawRequest = { action: ActionEnum.CODE_GENERATE_COMMENT, payload: { associatedContexts: [], data: dataMap, }, requestId: '123', }; const response = await sensitiveContentFilter.handle(mockRequest, SDKTool); console.log(response); }

   步骤二

   在 VS Code 中打开想要调试的代码文件并设置断点，然后从调试视图中选择“启动程序”并单击运行按钮即可。

步骤二：编译构建

将运行调试完成的 ts 文件编译为 js 文件，如将SensitiveContentFilter.ts文件编译为SensitiveContentFilter.js文件，编译构建步骤如下：

1. 打开配置文件src/build.js，修改entryPoints和outfile两个配置参数，并在entryPoints参数中指定需要编译构建的 ts 文件路径，在outfile中指定构建后的产物输出路径。

2. 在代码库根目录下执行命令node build.js，执行成功后对应的 js 文件将输出到outfile指定的产物输出路径。

步骤三：本地测试

在脚本上传企业配置后台之前，可在本地完成调试，以确保脚本能够与通义灵码的 IDE 插件集成，并对补全或问答场景的行为进行正确的安全过滤处理。具体调试步骤如下：

1. 将构建好的 js 文件拷贝到通义灵码本地存储路径的/extension/local/script/目录下。

2. 修改config.json文件：该文件所在目录为通义灵码本地存储路径的/extension/local/，打开config.json文件，并找到contentHandlerScripts，在对应的内容里增加该脚本的配置信息，如果没有contentHandlerScripts，可以新增一个数组类型的配置，参考示例如下：

   {
     "contentHandlerScripts": [
       {
         "identifier": "SensitiveContentFilter", 
         "name": "敏感内容过滤",
         "version": "1.0.0",
         "scriptPath": "~/.lingma/extension/local/script/SensitiveContentFilter.js",
         "state": "enabled",
         "bizType": "completion"
       }
     ]
   }

   配置参数说明：

   参数	说明
   identifier	脚本 ID，需确保唯一性。
   name	脚本名称。
   version	脚本的版本号，如果修改了脚本内容，需要升级版本号，否则脚本无法生效。
   scriptPath	脚本存放的路径，请注意： 脚本一定要存放在本地存储路径的/extension/local/script/目录下。 脚本的 js 文件名称（如：SensitiveContentFilter.js）一定要与identifier的值保持一致。
   state	脚本状态，enabled表示启用、disabled表示禁用。
   bizType	脚本应用的业务场景，completion表示行间代码生成补全、chat表示智能问答。

步骤四：脚本上传

经过本地调试并通过验证后，可进行脚本上传，操作步骤如下：

1. 前往通义灵码控制台-策略管理，选择需要开通安全过滤器的场景。

2. 选择过滤器选项为：自定义脚本。

3. 将构建后的 js文件上传。

4. 上传后单击保存配置，约5分钟内会下发到插件端生效。

自定义脚本 API

目前自定义脚本支持三种处理方式，如下：

• 阻断处理：即阻断后续流程，一旦阻断，则不会请求大模型进行推理，中断本次请求。

• 过滤处理：对发送处理的数据进行了修改（如：混淆、删除、替换等），然后继续后续流程。

• 无处理：对发送的数据没有做任何处理，原样返回，然后继续后续流程。

/**
 * 灵码编程助手前置处理接口
 */
export interface RequestPreHandler {
  // 处理请求
  handle: (request: RawRequest, SDKTool: LingmaSDKTool) => Promise<HandlerResponse>;
}

/**
 * 请求对象定义，请求包括触发的行为和待发送给 LLM 的原始数据
 */
export interface RawRequest {
  // 当前请求唯一标识，可用于追踪请求执行
  action: ActionEnum;
  // 触发请求的行为枚举
  payload: ContentPayload;
  // 封装原始数据内容的payload
  requestId: string;
}

// ContentPayload.data 中 value 类型
export type PayloadDataValueType = string | number | string[];
/**
 * 封装发送给 LLM 的原始数据内容
 */
export class ContentPayload {
  // 待处理的数据集合，对应的 key 参考 ContextValueKeyEnum 定义
  data: Map<PayloadDataKeyEnum, PayloadDataValueType>;
  // 与处理关联的上下文
  associatedContexts: ContextItem[];

  constructor() {
    this.data = new Map<PayloadDataKeyEnum, PayloadDataValueType>();
    this.associatedContexts = [];
  }
}

/**
 * ContentPayload.data 中 key 枚举
 */
export enum PayloadDataKeyEnum {
  // 用户圈选的代码片段
  SELECTED_CODE ='lingma:code',
  // 用户输入的文本
  USER_INPUT = 'lingma:text',
  // 报错信息
  ERROR_MESSAGES = 'lingma:error_messages',
  // 终端打印的日志信息
  TERMINAL_CONTENT = 'lingma:terminal_content',
  // 代码补全时，当前光标所在行的前文代码片段
  PREFIX_CODE = 'lingma:code_prefix',
  // 代码补全时，当前光标所在行的后文代码片段
  SUFFIX_CODE = 'lingma:code_suffix',
  // 相似代码片段
  SIMILAR_CODE = 'lingma:similar_code',
}

/**
 * 触发请求的行为枚举
 */
export enum ActionEnum {
    // 单元测试
    GENERATE_TESTCASE           = 'GENERATE_TESTCASE',
    // 生成注释
    CODE_GENERATE_COMMENT       = 'CODE_GENERATE_COMMENT',
    // 代码解释
    EXPLAIN_CODE                = 'EXPLAIN_CODE',
    // 代码优化
    OPTIMIZE_CODE               = 'OPTIMIZE_CODE',
    // 自由问答（即在问答输入框中直接输入文本的行为）
    FREE_INPUT                  = 'FREE_INPUT',
    // 代码问题快捷修复
    CODE_PROBLEM_SOLVE          = 'CODE_PROBLEM_SOLVE',
    // shell命令生成
    TERMINAL_COMMAND_GENERATION = 'TERMINAL_COMMAND_GENERATION',
    // 终端报错修复
    TERMINAL_EXPLAIN_FIX        = 'TERMINAL_EXPLAIN_FIX',
    // 代码补全
    COMPLETION                  = 'COMPLETION',
}

/**
 * 预处理结果
 */
export class HandlerResponse {
  // 处理策略，通过该策略可以控制后续的处理逻辑
  handlePolicy: HandlePolicy;
  // 原因描述
  reason?: string;
  // 当handlePolicy=FILTER时，需要设置该属性，其值为经过过滤后的数据（必须与ContentRequest.payload的内容保持一致）
  payload?: ContentPayload;
  constructor() {
    // 默认值
    // eslint-disable-next-line @typescript-eslint/no-use-before-define
    this.handlePolicy = HandlePolicy.NO_OPS;
    this.reason = '';
    this.payload = new ContentPayload();
  }
}

/**
 * 处理策略枚举
 */
export enum HandlePolicy {
  // 阻断策略，直接阻断请求
  BLOCK = 'BLOCK',
  // 过滤策略，拦截请求并对payload内容进行修改
  FILTER = 'FILTER',
  // 忽略策略，不处理请求
  NO_OPS = 'NO_OPS',
}

• 处理方式：支持通过正则表达式的方式配置过滤器，仅支持一种模式，如下：

  匹配规则时不处理

  匹配到正则后，不做任何处理。

• 消息通知：支持开启消息通知，通过 webhook 的方式，推送到所需要的消息接收平台。

• 执行顺序：按照配置的排序执行。

• 正则数量限制：最多可添加10条。

• 正则表达式标准：正则配置遵循 ECMAScript 标准，支持i（不区分大小写）、g（全局匹配）、s（DOTALL 模式）等常用标志位。

• 正则配置示例：

  规则名称	正则表达式	原文
  身份证号	(?<pre>.*)(\d{15})((\d{2})([0-9Xx]))(?<post>.*)	身份证号：330204197709022312。
  邮箱	\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*	我的邮箱是 lin***@aliyunmail.com
  密码	(.*password=)([\w\d]+)(.*)	{password=1213213}

步骤一：脚本开发

目前支持使用 TypeScript 语言进行脚本开发，可以参考样例进行代码开发，操作步骤如下：

1. 下载模板代码库：单击仓库地址：lingma-extension-template，该模板仓库集成了开发脚本所需的脚手架，请仔细阅读README.md文件和代码示例。

2. 实现“后置处理”接口：实现接口RequestPostHandler，API 可参考自定义脚本 API，以下为一个示例片段LLMChatAuditHandler.ts的实现，实现的功能为对通义灵码的AIChat操作进行审计，将审计内容上报至阿里云SLS。

   import {ResultUtil} from '../common/HandlerRespUtil';
   import { JsonUtil } from '../common/JsonUtil';
   import {PayloadUtil} from '../common/PayloadUtil';
   import {Config} from '../sdk/ConfigManager';
   import {LingmaSDKTool} from '../sdk/LingmaSDKTool';
   import axios from "axios";
   import moment from "moment";
   import os from "os";
   import {
     ActionEnum, AIResponse,
     HandlePolicy,
     RawRequest,
     RequestPostHandler,
     RequestPreHandler
   } from '../sdk/RequestHandleSDK';
   
   /**
    * 自定义脚本后置过滤器,通过该脚本可以完成将请求内容发送到远程服务器进行处理（如代码扫描、内容审计等）
    */
   export const llmResultAuditHandler: RequestPostHandler = {
     handle: async (request: RawRequest, response: AIResponse,SDKTool: LingmaSDKTool) => {
        // 操作人名称
        let userName = SDKTool.user.name;
        // 操作人id
        let userId = SDKTool.user.uid;
        // ide
        let ide = SDKTool.idePlatform;
        // ide
        let ideVersion = SDKTool.ideVersion;     
        // 操作时间
        let operationTime = moment().format("YYYY-MM-DD HH:mm:ss");
        // 操作ip
        let opeartionIp = getIpAddress();
        // 操作业务场景(补全 or 问答场景)
        let bizType = "chat";
        // 操作的请求id
        let requestId = request.requestId;
        // 操作action
        let action = request.action;
        // 操作内容(此处建议参考自身审计需求选取合适字段，避免上报内容过大(超过16k)导致上报失败)
        let inferredResult = response.inferredResult.text;
       
        // 上报sls
        // sls的Project名称
        let slsProject = "xxx";
        // sls的LogStore名称
        let slsLogStore = "xxx";
        // sls实例所在地域的endPoint
        let endPoint = "cn-hangzhou.log.aliyuncs.com";
        let slsWebTrackingUrl = `http://${slsProject}.${endPoint}/logstores/${slsLogStore}/track?APIVersion=0.6.0&request_id=${requestId}&action=${action}&biz_type=${bizType}&user_name=${userName}&user_id=${userId}&ide=${ide}&ide_version=${ideVersion}&operation_time=${operationTime}&opeartion_ip=${opeartionIp}&inferredResult=${inferredResult}`;
        axios.get(slsWebTrackingUrl).catch((error) => {
          console.error(error);
        });
   
        // 返回过滤结果
       return ResultUtil.buildPostHandlerResponse(HandlePolicy.NO_OPS, response.inferredResult,'无需处理');
     },
   };
   
   /**
    * 将自定义脚本过滤器添加到配置中
    * @param config LingmaExtensionSDK提供的统一管理配置的对象
    */
   export function modifyConfig(config: Config) {
     config.postContentHandlers.push(llmResultAuditHandler);
     return config;
   }
   
   function getIpAddress() {
     const interfaces = os.networkInterfaces();
     for (let devName in interfaces) {
       let iface = interfaces[devName];
   
       for (let i = 0; i < iface.length; i++) {
         let alias = iface[i];
         if (
           alias.family === "IPv4" &&
           alias.address !== "127.0.0.1" &&
           !alias.internal
         )
           return alias.address;
       }
     }
   
     return "No IP address found";
   }

3. 运行调试代码，通过运行main方法来测试脚本是否符合预期，操作步骤如下：

   步骤一

   编辑src/index.ts文件，修改main函数，调整实际需要被调试的代码，如下示例： async function main() { const value2 = 'hello world'; const dataMap = new Map<PayloadDataKeyEnum, PayloadDataValueType>(); dataMap.set(PayloadDataKeyEnum.USER_INPUT, value2); const request: RawRequest = { action: ActionEnum.CODE_GENERATE_COMMENT, payload: { associatedContexts: [], data: dataMap, }, requestId: 'test-request-id', }; const aiResponse: AIResponse = { inferredResult: { text: 'reply hello world', }, }; const response = await llmResultAuditHandler.handle(request, aiResponse, SDKTool); console.log(response); }

   步骤二

   在 VS Code 中打开想要调试的代码文件并设置断点，然后从调试视图中选择“启动程序”并单击运行按钮即可。

步骤二：编译构建

将运行调试完成的 ts 文件编译为 js 文件，如将LLMChatAuditHandler.ts文件编译为LLMChatAuditHandler.js文件，编译构建步骤如下：

1. 打开配置文件src/build.js，修改entryPoints和outfile两个配置参数，并在entryPoints参数中指定需要编译构建的 ts 文件路径，在outfile中指定构建后的产物输出路径。

2. 在代码库根目录下执行命令node build.js，执行成功后对应的 js 文件将输出到outfile指定的产物输出路径。

步骤三：本地测试

在脚本上传企业配置后台之前，可在本地完成调试，以确保脚本能够与通义灵码的 IDE 插件集成，并对补全或问答场景的行为进行正确的安全过滤处理。具体调试步骤如下：

1. 将构建好的 js 文件拷贝到通义灵码本地存储路径的/extension/local/script/目录下。

2. 修改config.json文件：该文件所在目录为通义灵码本地存储路径的/extension/local/，打开config.json文件，并找到contentHandlerScripts，在对应的内容里增加该脚本的配置信息，如果没有contentHandlerScripts，可以新增一个数组类型的配置，参考示例如下：

   {
     "contentHandlerScripts": [
       {
         "identifier": "LLMChatAuditHandler", 
         "name": "AIChat审计",
         "version": "1.0.0",
         "scriptPath": "~/.lingma/extension/local/script/LLMChatAuditHandler.js",
         "state": "enabled",
         "stage":"post",
         "bizType": "completion"
       }
     ]
   }

   配置参数说明：

   参数	说明
   identifier	脚本 ID，需确保唯一性。
   name	脚本名称。
   version	脚本的版本号，如果修改了脚本内容，需要升级版本号，否则脚本无法生效。
   scriptPath	脚本存放的路径，请注意： 脚本一定要存放在本地存储路径的/extension/local/script/目录下。 脚本的 js 文件名称（如：LLMChatAuditHandler.js）一定要与identifier的值保持一致。
   state	脚本状态，enabled表示启用、disabled表示禁用。
   stage	脚本作用阶段，post表示后置过滤、pre表示前置过滤，默认值为pre前置过滤。
   bizType	脚本应用的业务场景，completion表示行间代码生成补全、chat表示智能问答。

步骤四：脚本上传

经过本地调试并通过验证后，可进行脚本上传，操作步骤如下：

1. 前往通义灵码控制台-策略管理，选择需要开通安全过滤器的场景。

2. 选择过滤器选项为：自定义脚本。

3. 将构建后的 js文件上传。

4. 上传后单击保存配置，约5分钟内会下发到插件端生效。

自定义脚本 API

目前自定义脚本仅支持一种处理方式，如下：

• 无处理：对发送的数据没有做任何处理，原样返回，然后继续后续流程。

/**
 * 灵码编程助手后置处理接口
 * @param request 用户发送的请求
 * @param response LLM返回的推理内容
 * @param SDKTool SDK工具类，通过该工具类可以获取与IDE、Plugin相关的信息
 * @returns 经过后置处理器处理后的返回结果
 */
export interface RequestPostHandler {
  // 后置处理方法
  handle: (request: RawRequest, response: AIResponse, SDKTool: LingmaSDKTool) => Promise<PostHandlerResponse>;
}

/**
 * 请求对象定义，请求包括触发的行为和待发送给 LLM 的原始数据
 */
export interface RawRequest {
  // 当前请求唯一标识，可用于追踪请求执行
  action: ActionEnum;
  // 触发请求的行为枚举
  payload: ContentPayload;
  // 封装原始数据内容的payload
  requestId: string;
}

/**
 * 模型推理生成的结果数据
 */
export class InferredResult {
  //LLM生成的文本内容
  text: string;
  constructor() {
    this.text = '';
  }
}

// ContentPayload.data 中 value 类型
export type PayloadDataValueType = string | number | string[];
/**
 * 封装发送给 LLM 的原始数据内容
 */
export class ContentPayload {
  // 待处理的数据集合，对应的 key 参考 ContextValueKeyEnum 定义
  data: Map<PayloadDataKeyEnum, PayloadDataValueType>;
  // 与处理关联的上下文
  associatedContexts: ContextItem[];

  constructor() {
    this.data = new Map<PayloadDataKeyEnum, PayloadDataValueType>();
    this.associatedContexts = [];
  }
}

/**
 * ContentPayload.data 中 key 枚举
 */
export enum PayloadDataKeyEnum {
  // 用户圈选的代码片段
  SELECTED_CODE ='lingma:code',
  // 用户输入的文本
  USER_INPUT = 'lingma:text',
  // 报错信息
  ERROR_MESSAGES = 'lingma:error_messages',
  // 终端打印的日志信息
  TERMINAL_CONTENT = 'lingma:terminal_content',
  // 代码补全时，当前光标所在行的前文代码片段
  PREFIX_CODE = 'lingma:code_prefix',
  // 代码补全时，当前光标所在行的后文代码片段
  SUFFIX_CODE = 'lingma:code_suffix',
  // 相似代码片段
  SIMILAR_CODE = 'lingma:similar_code',
  // 补全场景执行补全的文件路径
  FILE_PATH = 'lingma:file_path',
}

/**
 * 触发请求的行为枚举
 */
export enum ActionEnum {
    // 单元测试
    GENERATE_TESTCASE           = 'GENERATE_TESTCASE',
    // 生成注释
    CODE_GENERATE_COMMENT       = 'CODE_GENERATE_COMMENT',
    // 代码解释
    EXPLAIN_CODE                = 'EXPLAIN_CODE',
    // 代码优化
    OPTIMIZE_CODE               = 'OPTIMIZE_CODE',
    // 自由问答（即在问答输入框中直接输入文本的行为）
    FREE_INPUT                  = 'FREE_INPUT',
    // 代码问题快捷修复
    CODE_PROBLEM_SOLVE          = 'CODE_PROBLEM_SOLVE',
    // shell命令生成
    TERMINAL_COMMAND_GENERATION = 'TERMINAL_COMMAND_GENERATION',
    // 终端报错修复
    TERMINAL_EXPLAIN_FIX        = 'TERMINAL_EXPLAIN_FIX',
    // 代码补全
    COMPLETION                  = 'COMPLETION',
}

/**
 * 后置处理结果
 */
export class PostHandlerResponse {
  // 处理策略，通过该策略可以控制后续的处理逻辑
  handlePolicy: HandlePolicy;
  // 原因描述
  reason?: string;
  // 经过后置处理器处理过的模型返回结果
  processedResult: InferredResult;
  constructor() {
    // 默认值
    this.handlePolicy = HandlePolicy.NO_OPS;
    this.reason = '';
    this.processedResult = new InferredResult();
  }
}

/**
 * 封装大模型返回结果
 */
export class AIResponse {
  // 模型推理结果
  inferredResult: InferredResult;
  constructor() {
    this.inferredResult = new InferredResult();
  }
}

/**
 * 模型推理生成的结果数据
 */
export class InferredResult {
  //LLM生成的文本内容
  text: string;
  constructor() {
    this.text = '';
  }
}

/**
 * 处理策略枚举(后置过滤器当前只支持NO_OPS)
 */
export enum HandlePolicy {
  // 阻断策略，直接阻断请求
  BLOCK = 'BLOCK',
  // 过滤策略，拦截请求并对payload内容进行修改
  FILTER = 'FILTER',
  // 忽略策略，不处理请求
  NO_OPS = 'NO_OPS',
}