产品手册

• 1: AISE服务基座
• 1.1: 用户登陆
• 1.2: 用户、部门和角色管理
• 1.3: 统一身份认证
• 1.4: 模型适配器
• 1.4.1: Qwen2.5模型适配
• 1.5: 提示词仓库
• 1.6: 特性开关
• 1.6.1: 知识库对话-特性开关
• 1.6.2: 应用-特性开关
• 1.7: 知识库支撑系统
• 1.7.1: 知识库权限管理
• 1.7.2: 知识库文档对话
• 1.8: 应用市场
• 1.8.1: 插件上传文件名校验
• 1.9: 系统运维
• 1.9.1: Oauth2代理
• 1.9.2: 服务检测
• 1.9.3: 数据库备份
• 1.9.4: 系统激活
• 1.9.5: 系统日志清理机制
• 1.9.6: 域登录
• 2: SmartCode AI编码助手
• 2.1: JetBrains插件
• 2.1.1: 代码补全
• 2.1.2: 代码对话
• 2.2: Visual Studio插件
• 2.2.1: 使用代码助手生成代码
• 2.2.2: 使用代码助手解释代码
• 2.2.3: 使用代码助手注释代码
• 2.2.4: 研发知识问答
• 2.2.5: 常见问题
• 2.2.5.1: 代码助手提示“代码生成暂无结果”
• 2.2.5.2: 使用代码助手时提示“请登录后再使用”
• 2.2.5.3: 代码助手提示“授权已经过期”
• 2.3: 支持使用#变量
• 3: SmartChat 企业级ChatGPT服务
• 3.1: 图表生成
• 3.2: 图片识别
• 4: Code Review Agent 代码评审智能体
• 4.1: 启用和配置
• 4.1.1:
• 4.2: 指令参考
• 4.2.1:
• 4.2.2:
• 4.2.3:
• 4.2.4:
• 4.2.5:
• 4.2.6:
• 5: SmartAnswer 企业知识库

1 - AISE服务基座

1.1 - 用户登陆

用户登陆

支持普通的帐号密码登陆和sso等第三方的登陆。企业管理员使用内置管理帐号 aise-admin登陆。另外aise还内置了一个普通用户：aise-user, 在刚部署完成后可以使用此帐号登陆。

1.2 - 用户、部门和角色管理

1. 创建用户

管理员需要在AISE的管理端创建用户，并分配给用户账号密码。

1. 点击系统管理 ｜ 用户管理 ｜ 新增
2. 输入用户昵称、用户账号、归属部门以及密码。

2. 创建部门

为了进行更好的权限管理以及分组，可以将企业的组织架构映射到AISE的部门中，并可以根据部门配置对应的权限。

1. 点击系统管理 ｜ 部门管理 ｜ 添加部门

2. 输入上级部门，部门名称

3. 用户管理

内置用户和角色管理能力，并支持用户的部门分配和角色分配。

4. 用户组管理

为了进行更好的权限管理以及分组，可以将企业的组织架构映射到AISE的用户组中，并可以根据用户组配置对应的权限。

1. 点击系统管理｜用户组管理｜新增
2. 输入用户组名称、Azure用户组Id（Azure Group ID，选输）及备注
3. 点击系统管理｜用户组管理｜用户组名称
4. 选择用户，点击确认按钮，关联用户成功
5. 用户组访问权限配置
   1. AISE管理｜模型适配器｜修改
   2. 选择访问范围和用户组

用户组除了在AISE系统新增外，用户通过Oatuh2登录时，也会同步用户的组信息到AIS系统中，如果用户已创建过auzre用户组，则直接关联到当前组中。 同步azure用户组必须有Team.ReadBasic.All权限。

1.3 - 统一身份认证

将AISE门户登录页面用作所有AISE应用程序和插件的中央身份验证点，为用户提供熟悉且简化的登录体验，消除了需要为每个单独的应用程序重复输入密码的需求；通过标准化OAuth2集成企业现有身份认证系统。

1.4 - 模型适配器

1. 基本模型能力

当前市场上的各类大模型层出不穷，企业的大模型战略需要适应市场的快速变化，确保引入到企业的模型可以灵活的适配各种场景，并且可以满足企业内部复杂组织架构、权限、安全性、审计等要求。同时，企业还需要根据内部的个性化需求对模型本身进行适配和调整，因此需要平台具备模型训练，微调以及对模型资产进行版本管理和变更管理的能力。

AISE的模型能力层提供以下能力，确保可以为企业的大模型战略提供完整支撑

• 多厂商适配：内置对市场主流大模型厂商的介入支撑，包括：微软Azure OpenAI， DeepSeek深度求索，Llama，HuggineFace，阿里通义大模型，华为和百川智能 。

• SaaS服务和私有部署支持：支持通过SaaS API和私有部署方式介入以上厂商的大模型服务。

• 推理服务通用接口支持：支持通过VLLM，TGI和OpenAI标准接口提供的推理服务 。

• 英伟达Nvidia GPU支持：用户可以选择Nvidia A100，A800，A10，L20以及4090系列GPU作为私有部署的硬件算力。

• 国产华为晟腾系列NPU：用户可以选择晟腾系列NPU作为私有部署硬件算力，包括：晟腾910A/B系列，晟腾310系列；并支持多卡并行推理配置。

• 参数可视化配置：支持对模型常用参数进行可视化配置，用户管理员可以通过模型适配器界面完成模型参数的配置，内置标准化参数支持和个性化参数注入。

• 多实例负载均衡：用户可以为同一个模型实例添加多个子实例，AISE模型适配器自动针对多个子实例提供流量分配，为用户提供模型实例的横向扩展能力。

• 模型路由能力：支持按模型类型、按组织单位、按应用场景进行模型路由分配 。

• 组织架构路由：支持针对不同部门提供不同的模型实例，支持在统一场景下为不同组织单位提供不同的模型路由，比如：同样是代码补全服务，可以为不同开发小组分配不同的代码补全模型。

• 按场景进行模型路由：针对代码补全、代码对话、通用代码任务，如：代码解释、代码纠错，代码评审、单元测试 生成等不同任务提供不同的模型路由。

• 增强型模型密钥验证能力：在使用Azure OpenAI的模型服务时，支持通过Service Principle的方式进行服务端身份验证，并动态获取模型密钥（access token），此密钥在一定时间内自动过期，提供更高的安全性和企业可管理性。

• 支持在固定代码任务中使用FIM模式：FIM（Fill in the Middle）是一种特殊的生成模式，通过对前文和后文的同时推理提供更优化的模型生成控制，一般用户代码生成任务。AISE不仅代码生成任务上提供FIM能力，同时也支持在通用代码任务（代码解释、代码纠错，代码评审、单元测试）上使用FIM能力。

模型支持列表

AISE模型适配器内置对以下厂商和模型提供开箱即用的接入能力。

2. 模型全局配置

模型配置完成后，需要对AISE进行模型全局配置，来配置智能对话中可以使用的模型，代码补全中可以使用的模型，向量化模型等等。

1. 点击系统管理 ｜参数设置 ｜ 找到参数名称为“全局配置-模型” 的参数

2. 修改配置，配置如下：

   详细介绍：

     "chat_model_types":[
         "completion_azure_gpt",
         "completion_azure_gpt35_16k",
         "completion_azure_gpt4",
         "completion_azure_gpt4_32k",
         "completion_azure_gpt4_128k",
         "completion_deepseek_chat"
       ],
     "embedding_model_type":   "embedding_azure_text-embedding-ada-002",
     "code_completion_model_types": [
         "codecompletion_azure_text-davinci-003"
       ],
     "task_configuration":{
         "chat_model":{
             "use_current_chat_model":"false",
             "task_method_chat_model_type":"completion_azure_gpt35_16k"
           },
         "completion_model":{
           "task_method_completion_model_type":"completion_azure_text-davinci-003"
           }
       }
   }
   

   参数说明

   参数	说明
   chat_model_types	代码对话可以使用的模型列表
   embedding_model_type	指定向量化模型
   code_completion_model_types	指定代码补全模型
   task_method_chat_model_type	指定提示词模版为对话类型时使用的模型
   task_method_completion_model_type	指定提示词模版为完成类型时使用的模型

3. 添加模型

将企业内选型的模型通过模型适配器，添加到AISE中，并在具体的AI应用场景中使用这些模型。添加方式如下：

1. 点击AISE管理 ｜ 模型适配器

2. 输入模型标识 ｜ 模型类型 ｜ 模型参数 ｜ 配置项

   参数
   模型类型	下拉列表选择
   模型参数	{“temperature”:“0.7”,“max_tokens”:“800”,“top_p”:“0.95”,“frequency_penalty”:“0”,“presence_penalty”:“0”,“stop”:"",“chunk_size”:""}
   配置项	{“API_KEY”: “”,“ServiceEndPoint”: “”,“ApiVersion”: “2023-03-15-preview”,“deploymentName”: “”}

4. 启用多实例

通过启用多实例的方式来对流量进行不同模型实例的分发，适用于用户量比较大的企业

1. 启用 “是否有实例”
2. 点击添加配置项
3. 输入其他实例配置项信息

5. 模型权限配置

对模型进行访问权限控制，支持公开模型，以及按部门划分模型访问权限。

1.4.1 - Qwen2.5模型适配

特性说明

orch服务增加对Qwen2.5模型的适配，适配后，通过配置，可用Qwen2.5模型进行chat对话，代码补全,提示词。

操作指引

新增模型类型 用途说明

1. completion_qwen_chat

   用途：适用于提供对话能力的模型 适用模型:qwen2.5-14b、qwen2.5-72b-instruct、Qwen2.5_Coder_32B_Instruct

2. codecompletion_qwen_coder

   用途：适用于提供代码补全能力的模型 适用模型:qwen2.5-14b、qwen2.5-72b-instruct、Qwen2.5_Coder_32B_Instruct

3. completion_qwen_completion

   用途：适用于对完成模式提示词进行解释的模型 适用模型:qwen2.5-14b、qwen2.5-72b-instruct、Qwen2.5_Coder_32B_Instruct

配置模型适配器

1. 新增模型适配器时的参数说明：

1.1 模型适配器参数说明

1.2 模型参数说明

1.3 配置项参数说明

2. 新增对话模型。

   需要在模型适配器中增加Qwen2.5_14B_Chat(N卡环境)/Qwen2.5_32B_Chat_TGI（昇腾环境）/Qwen2.5_72B_Chat_Saas（SaaS版）模型，并确保模型类型指定为：completion_qwen_chat

3. 新增代码补全模型。

   需要在模型适配器中增加Qwen2.5_14B_Coder（N卡）/Qwen2.5_32B_Coder_TGI（昇腾）模型，并确保模型类型指定为：codecompletion_qwen_coder

4. 新增提示词推理模型。

   需要在模型适配器中增加Qwen2.5_14B_Completion（N卡）/Qwen2.5_32B_Completion_TGI（昇腾）模型，并确保模型类型指定为：completion_qwen_completion

配置 全局配置-模型

1. 配置全局配置-模型

   点击系统管理/参数设置 菜单，找到全局配置-模型

2. chat对话配置Qwen2.5

   点击修改，在 “chat_model_types”:配置内容增加"completion_qwen_chat" 。此时在对话时的对话模型选择时就可以选择Qwen2.5模型进行对话。

3. 代码补全配置Qwen2.5

   点击修改， “code_completion_model_types”:配置内容修改为"codecompletion_qwen_coder" 。此时使用SmartCode插件进行代码补全时，就会使用Qwen2.5来完成。

4. 提示词配置Qwen2.5

   1. 点击修改， “task_method_completion_model_type”:配置内容修改为"completion_qwen_completion" 。此时使用完成模式的提示词时，就会使用Qwen2.5 模型来完成。
   2. 点击修改， “task_method_completion_model_type”:配置内容修改为"completion_qwen_completion" 。此时使用完成模式的提示词时，就会使用Qwen2.5模型来完成。

1.5 - 提示词仓库

1. 多级提示词库

提示工程是企业构建AI应用的核心实践，提示词是AI驱动下企业的核心资产。

提示词库 提示词工厂

AISE提供了统一的提示词仓库，具备三层提示词结构，包括：

• 系统内置提示词：提供系统内置的高频AI任务相关的提示词版本管理，AISE系统所提供的代码解释，代码评审，注释生成，单元测试生成等内置通用代码任务即通过系统内置提示词提供。系统内置提示词的修改权限不对用户开放，由产品团队根据模型适配和提示工程的迭代随产品版本进行更新。

• 系统基础提示词：系统基础提示词为用户管理员事先配置好并对所有用户开放的提示词，普通用户可以使用此类提示词但是不能对其进行修改。系统基础提示词为企业提供了为用户推送标准化提示词的能力；并且支持按组织单位进行分配。

• 用户提示词：用户可以创建自己的提示词模板，并可以共享给其他用户使用。用户提示词为用户提供了重用提示词的便捷方式，鼓励用户探索AI应用场景并在内部进行共享。

AISE的提示词仓库提供模型适配能力，用户可以针对不同的模型提供不同版本的提示词，系统根据用户调用过程中所使用的模型进行动态匹配，以便确保最佳的提示词生成效果。 AISE所提供的提示词仓库可以通过AISE所提供的标准化接口进行调用，在AISE内置的核心AI应用场景中打通使用，用户可以在SmartCode，SmartChat等不同客户端使用同样的提示词仓库管理体验。 提示词仓库提供内容版本管理，用户对提示词的修改会被记录并允许用户比较和回滚到特定版本。

2. 系统/组织级提示词

管理员可以根据实际的需求创建组织级的的提示词模版，通过创建提示词模版来扩展AI使用场景。

1. 点击AISE管理 ｜ 提示词库 ｜ 新增

2. 输入提示词标识、简称 、全称 、自然语言、关键词类型、系统目录、用户角色、状态、模版内容等信息。

3. 用户提示词

自定义提示词说明

支持通过模型角色提示词对模型行为进行控制，为不同的用户和应用场景设定不同的大模型行为方式。

自定义提示词示例

在提示词工厂定义提示词斜杠指令为：value2field / 在SmartCode插件中通过斜杠指令调用

创建提示词

1. 点击应用 ｜ 提示词工厂

2. 点击我的提示词旁边的“创建”按钮

3. 这里假设我们创建一个YAMLToJSON的提示词

4. 保存后效果如下：

5. 回到客户端，输入“/” 召唤出自定义提示词模版，如下图所示：

6. 提供一个YAML内容，测试：

7. 转换后效果如下：

1.6 - 特性开关

1.6.1 - 知识库对话-特性开关

特性说明

SmartChat知识库对话功能，需要开启特性开关才能对话。

特性指引

SmartChat知识库对话功能特性开关，开启步骤如下：

1. 点击系统管理/参数设置菜单，找到特性开关-chat_library点击修改按钮，弹出参数设置修改窗口，确认特性开关是否开启，若未开启，SmartChat知识库对话功能无法生效。

1.6.2 - 应用-特性开关

特性说明

应用市场管理菜单中的应用和参数设置菜单中的特性开关进行关联，可实现应用的灰度发布。现有应用市场中应用只能设置打开或关闭应用，无法对某个用户或者某个部门单独发布，在应用市场管理菜单中新增和特性开关功能（特性开关在系统管理/参数设置菜单中进行配置）进行关联后，可对指定用户或部门单独发布应用。

操作指引

1. 点击系统管理/参数设置菜单，然后点击新增按钮。
2. 然后弹出新增系统参数对话框,输入相关参数,点击确定按钮，保存特性开关成功。
   1. 对所有用户生效
   2. 对指定用户生效，此时无法再指定部门
   3. 对指定部门生效，此时无法再指定用户
3. 点击AISE管理/应用市场管理菜单，选择要关联特性开关的应用，点击修改按钮，显示修改应用列表对话框
4. 点击特性开关下拉菜单，弹出特性开关选择窗口。
5. 选择已创建的特性开关，点击确定按钮关联成功，再点击确定按钮保存成功。
6. 关联成功后可通过修改特性开关中的相关参数控制应用市场中的应用是否显示。

1.7 - 知识库支撑系统

1.7.1 - 知识库权限管理

特性说明

新增知识库管理员角色和知识库用户角色，点击应用/应用市场菜单，拥有知识库管理员角色的用户，可以在知识库助手中新增,修改,查询,删除知识库，而拥有知识库用户角色的用户，只能查询知识库。

操作指引

新增 知识库管理员/知识库用户 角色

1. 使用具有管理员角色的用户登录AISE 管理系统，点击系统管理/用户管理菜单，点击以下新增用户按钮；

   

2. 然后系统会弹出新增用户对话框，找到角色下拉菜单;

   a.角色下拉菜单选择普通用户和知识库管理员，点击确定，新增成功；

   

   b.角色下拉菜单选择普通用户和知识库用户，点击确定，新增成功；

   

   c.知识库管理员或知识库用户角色不能单独使用，该用户必须具有管理员或普通用户角色

角色的权限展示

知识库用户（查询）

1.从应用市场页面找到知识库助手入口，点击“启用”进入知识库页面。
“知识库用户”角色，只能查询知识库列表，没有对知识库的新增，编辑，删除等权限。

2. “知识库用户”角色，有查询知识库详情的权限，但不能编辑和修改。
   1. 普通知识库
   2. workspace知识库

知识库管理员（增删改查）

1. “知识库管理员”角色，有知识库相关的所有权限，如列表查询 知识库创建 知识库删除

   

2. 新增普通知识库或workspace知识库

3. 普通知识库

   1. 知识库详情
   2. 新增普通知识库

4. workspace知识库

   1. workspace知识库详情
   2. workspace知识库新增数据源

1.7.2 - 知识库文档对话

特性说明

知识库助手增加上传文件，训练文件，根据文件进行文档对话功能。知识库对话支持的场景有两种： 场景1: 从AI服务基座应用市场的知识库助手选择一个知识库（有训练完成的文档），点击开始对话进入SmartChat开始对话 场景2: 在SmartChat页面自主选择知识库下拉列表开始对话

操作指引

1. 知识库上传文档，点击“开始对话”对该知识库进行问答

a.点击应用/应用市场菜单，打开知识库助手

b.进入知识库详情页面，点击添加数据源

c.类型选择文档类型,点击上传按钮上传文件

d.文件上传成功后，点击确定按钮会将已成功上传的文件保存到该知识库并在后台进行训练

e.文件保存成功后回到知识库详情页面，查看数据源列表的训练状态，只有训练状态为completed的文档才可以进行对话，点击列表右上角的刷新图标可以刷新训练状态

f.点击知识库的开始对话按钮，跳转到smartChat开始对话

g.跳转到smartChat页面后可以基于该知识库文档进行问答

2. 在SmartChat页面自主选择知识库进行问答

a.用户在SmartChat页面新建会话时可以自主选择相关知识库，下拉选数据默认为空。

b.知识库选择完毕之后，用户可以针对当前选中知识库进行文档对话。

1.8 - 应用市场

为承载企业多样的AI应用并为这些应用提供基础的版本分发、升级和场景化管理，AISE内置了应用市场管理。

应用市场通过为每个AI应用分配唯一的app_key的方式，为AISE的其他服务提供针对不同应用提供个性化场景的能力。

1. 创建应用

说明：组织可以在AISE应用市场维护已经开发好的AISE扩展。包括对版本进行维护。方便用户快速获取相关应用。

1. 点击AISE管理 ｜ 应用市场管理 ｜ 新增
2. 输入应用键、名称、包类型、类型、提供者、标签、选择图标、说明、描述等信息

2. 维护版本

用户可以针对smartcode插件维护版本信息。

1. 点击添加

2. 输入发布日期、版本号、版本描述、发布者等信息

3. 启用强制更新

为了保障用户可以使用最新的代码补全以及代码聊天插件，AISE管理员可以在后台启用强制更新策略，配置如下。

1.8.1 - 插件上传文件名校验

特性说明

aise管理 - 应用市场管理页面，在进行插件安装包上传时，增加文件名校验功能， 规则如下：

• 开头使用英文，可以用 _ 或 - 作为连接符，不能使用空格
• 开头后面紧跟一个主版本号(数字)，必须用 _ 或 - 作为连接符
• 主版本号后有一个小数点,再加上次版本号(数字)
• 紧接着一个点加上构建号(数字)
• 最后文件扩展名为 zip / vsi

操作指引

场景标题

上传文件smartcode_vscode(2),这种带括号的文件会导致报错无法下载

场景说明

日常操作中，同一文件多次下载或者保存后会出现带括号的这种文件名，上传这种文件，会导致插件在应用市场无法下载，报错

操作步骤

1.增加文件名校验后，aise管理 - 应用市场管理页面上传符合格式要求的文件

2.可以成功下载，不会产生报错。

1.9 - 系统运维

1.9.1 - Oauth2代理

操作指引

AISE系统Oauth2代理配置

默认情况下Auzre oauth2代理是关闭状态，如果需要开启按照如下步骤进行操作:

1. 登录部署服务器，切换到安装目录； cd /home/aise/aise-system-core-deploy
2. 修改docker-compose-allinone.yml文件中有关代理的参数
   1. AISE_PROXY_FLAG：默认为false，true为开启Oauth2代理
   2. AISE_PROXY_HOST：IP为代理IP地址
   3. AISE_PROXY_PORT：Port为代理端口
   4. AISE_PROXY_USER_NAME：username为代理用户名，如果不校验可不填
   5. AISE_PROXY_PASSWORD：password为代理用户名，如果不校验可不填
3. 最后重新部署aise-modules-system;

   docker rm -f aise-modules-system
   docker-compose -f docker-compose-allinone.yml up -d aise-modules-system
   

1.9.2 - 服务检测

特性说明

服务检测功能主要检测docker应用的运行状态，如果运行异常需要提示客户具体哪个docker应用异常，除了aise-mysql和aise-redis服务，其他服务都可以灵活配置启用或关闭。

服务检测-页面：通过页面查询服务检测结果，用户可以直观的查询所有服务的运行状态，可以通过详情查询历史异常信息。

服务检测-接口：通过接口查询服务检测结果，第三方通过调用该接口查询服务运行状态。

操作指引

服务检测字典设置

用户可以自由设置哪些服务需要需要检测，aise-mysql和aise-redis为默认服务，不需要另外配置

1. 用户登录AISE管理系统，点击左侧菜单的 系统管理 | 字典管理 ，即可进入如下界面

2. 查找名称为服务检测-URL的字典项，点击字典类型，进入字典数据列表页面

3. 新增检测服务

   1. 点击新增按钮，弹出添加字典键值窗口
   2. 输入必选项信息，字典标签填写服务名称，字典键值填写检测URL，字典排序填写展示顺序，状态默认正常，点击确定按钮，新增成功

4. 修改检测服务

   1. 点击修改按钮，弹出添加字典键值窗口
   2. 修改字典键值、字典排序、状态（状态如果是停用，就不用再检测），点击确定按钮，修改成功

5. 删除检测服务

   1. 选择所要删除字典项，点击删除按钮，确定后删除字典，删除后不会再检测该服务

服务检查查询

1. 用户登录AISE管理系统，点击左侧菜单的 系统监控 | 服务检测 ，即可进入如下界面，默认5分钟检测一次
2. 输入容器名称或选择状态可以查询过滤指定容器
3. 点击服务详情，可查询该服务历史失败信息

服务检测接口调用

服务检测提供单独的接口供第三方调用，检测时间间隔为5分钟

1. 接口地址：https://AISE服务地址/core-api/system/operlog/health_check?refresh=false ，其中AISE服务地址需要根据生产实际情况替换
2. 正常报文信息，status状态为1，代表服务正常

   {"msg":"查询成功","data":[],"status":"1"}
   

3. 异常报文信息，status状态为0，代表服务异常，data数组显示所有检测异常的服务

   {
   "msg": "查询成功",
   "data": [{
   "containerName": "aise-chatui",
   "title": "aise-chatui服务未启动成功",
   "errorMsg": "",
   "recordTime": "2024-11-26 14:39:28"
   }],
   "status": "0"
   }
   

1.9.3 - 数据库备份

特性说明

数据库备份支持全量和增量备份

全量备份：每天凌晨3点备份一次，默认最多保留7天

增量备份：暂不支持

操作指引

全量备份参数修改

1. 点击系统监控/定时任务菜单，选择任务数据库备份-全量，点击修改按钮，弹出定时任务修改窗口

2. 调用方法参数 MysqlBackupTask.work（“full”,“7”,“AISE服务地址”,“13306”,"./mysql-backup"）

   1. full: 全量标志，默认值
   2. 7：备份保留天数,默认保留7天以内的备份数据,可按需修改
   3. AISE服务地址：mysql数据库域名地址，可以是IP地址,需要根据生产实际情况修改 若为多机部署,建议使用IP指向mysql数据库部署服务器IP
   4. 13306：mysql数据库端口(默认为13306) 若部署时有指定过其他端口,则此处需要修改为您指定的端口
   5. ./mysql-backup：数据库备份存储目录,默认为.表示当前目录(当前目录为部署目录的1.mysql/backup文件夹下) 可以更改为其他目录(路径可使用相对或绝对路径)

3. cron执行参数：每天凌晨3点执行备份

4. 备份文件默认地址：/home/aise/aise-system-core-deploy/1.mysql/backup，可通过修改任务详情页面中调整调用方法参数

1.9.4 - 系统激活

操作指引

AISE系统激活指南

首次部署时，系统带有默认激活码。如激活码过期或者临时修改，则按照如下步骤进行操作:

1. 从软件开发商或销售人员获取新的激活码；
2. 登录部署服务器，切换到安装目录；

   cd /home/aise/aise-system-core-deploy
   

3. 修改docker-compose-allinone.yml文件中AISE_ACTIVATION_CODE激活码参数
4. 最后重新部署aise-gateway;

   docker rm -f aise-gateway
   docker-compose -f docker-compose-allinone.yml up -d aise-gateway
   

1.9.5 - 系统日志清理机制

特性说明

AISE 后台管理系统，之前是日志默认保留60天，超过60天的日志会被删除，现修改成默认保留7天，且在docker-compose-allinone.yml中的服务aise-manager、aise-auth、aise-modules-system、aise-modules-job、aise-modules-file、aise-gateway新增环境变量AISE_LOG_MAX_HISTORY，部署时可以通过修改环境变量修改日期默认保留天数。

操作指引

单应用日志保留天数修改：

1. 部署全部应用时，可以修改multihost.env文件中AISE_LOG_MAX_HISTORY参数，然后执行start.sh脚本

2. 部署单个应用，修改docker-compose-allinone.yml文件中所属应用参数，例如：${AISE_LOG_MAX_HISTORY:-10}

3. 执行以下命令：

   cd /home/aise/aise-system-core-deploy
   docker-compose -f docker-compose-allinone.yml stop aise-manager
   docker-compose -f docker-compose-allinone.yml rm -f aise-manager
   docker-compose -f docker-compose-allinone.yml up -d aise-manager
   

4. 示例说明：默认保留7天，如果当天是11月27日，会删除11月20日之前的日志

1.9.6 - 域登录

操作指引

AISE系统域登录配置

默认情况下AISE系统域登录配置为关闭状态，如果需要开启按照如下步骤进行操作:

1. 登录AISE系统，点击左侧导航栏“系统管理”->“域登录”->“域配置”菜单，如下图所示:
2. 默认关闭状态，点击“启用”按钮，如下图所示:
3. 各个参数的详细说明如下:
   1. 域服务器地址:AD服务器地址，默认格式为: ldap://example.com:389,example.com为域服务器名称或IP地址，389为端口
   2. 账号:管理员账号，使用DN格式：CN=admin,CN=Users,DC=example,DC=com
   3. 密码:管理员密码
   4. 域名称:域名称，格式为example.com,确保该域名可以正常访问域服务器
   5. 基础DN：域服务器的根目录，格式为：DC=example,DC=com
   6. 跟随引用：默认值
   7. AISE账号：选中后，已登录验证过的域账号将不能使用普通登录窗口登录，必须使用域账号登录窗口登录
   8. 默认部门：域账号登录成功后，默认选择的部门
   9. 默认角色：域账号登录成功后，默认选择的角色
4. 点击“保存”按钮，配置成功
5. 只有启用时登录页面才会显示域账号登录窗口，如下图所示：
6. 已登录过域账号可以在“系统管理”->“域登录”->“用户管理”菜单中查看域账号信息，如下图所示:

注意事项:
1、如果已在AISE系统创建过用户，且用户名称和域账号名称相同，则使用域账号登录时，不会重新创建和修改用户信息，只是绑定该账号为域账号

2 - SmartCode AI编码助手

2.1 - JetBrains插件

2.1.1 - 代码补全

单行补全

单行补全模式 可用于属性生成、参数补全、变量赋值 等场景。

多行补全

在实际开发场景中，特别是在写一个新的方法/函数时，每个开发人员的诉求往往是不同的。

• 某些场景下开发人员希望给一个方法名字，或者一个简单的注释补全工具就可以给我们自动生成整个方法的业务逻辑。
• 某些场景下我们希望给一个方法名字，然后补全工具在方法里能够逐行的给予补全，这样开发人员可以进行快速的修正，然后补全插件根据修正后的内容，继续给予补全建议。那么这种场景下就需要具备单行/多行补全的切换能力。 通过单行/多行补全开发人员可以根据自己的场景快速的切换补全模式。实现高效开发。

点击右下角的 补全模式

点击后，S（Single Line）会切换为M（MultiLine），如下图所示：

按tab键接受代码，继续回车，如下图所示：

方法级代码补全

• 输入注释

手工触发

插件默认是自动触发补全，有时候开发人员在进行代码编写时，不管是开发人员在打字时、空格时、回车时默认都会触发代码自动补全。这样很大程度上会干扰开发人员的正常开发，所以很多开发人员希望关闭自动补全，而是通过手工快捷键触发的方式来进行补全，这样开发人员可以真正做到随叫随到的补全效果。

设置手工触发补全

• 点击修改设置，如下图所示：

• 自动补全 ｜ 改为 “关闭”：

• 设置代码补全触发快捷键：Keymap | Trigger inline Completion

• 点击 Add keyboard Shortcut

• 设置完成后，我们测试是否可以收工触发代码补全。回到PhotoController.java文件，并输入注释以及部分代码。点击回车，并按你设置的代码补全触发快捷键【Control+Comand+T】，查看代码补全效果。

2.1.2 - 代码对话

按 Tab 或单击“接受”以应用代码建议。

SmartCode支持3种代码片段选择方式，如 代码解释 中所示，分为以下入口：

1. 右键快捷菜单
2. CodeLens
3. #selection 变量

代码解释

代码解释能力允许开发人员选择代码片段，通过大模型对代码进行自然语言解释。 下图：使用右键快捷菜单调用 代码解释 特性

下图：使用codelens（方法体悬浮菜单）方式调用 代码解释 特性

下图：使用 #selection 变量自定义 代码解释 提示词

代码评审

使用右键快捷菜单调用 代码评审 特性

生成测试

根据用户选择代码自动生成单元测试用例，并提供较为丰富的测试覆盖能力。

生成注释

为方法体提供顶部注释生成能力

代码检查

允许用户提供自定义代码检查规则，通过快捷方式触发。

多轮对话

支持用户与AI进行连续、多轮的技术对话交流，对话时保持上下文连贯性。 下图展示了多轮对话能力，用户在完成前一轮对话后，可以通过文字语意，比如：这段/以上/前面的，这样的说法提示SmartCode关注前文内容，保持对话的连贯性。

2.2 - Visual Studio插件

应用场景

代码智能推荐与补全

• 高效编写新代码：在编写代码时，代码助手能够基于对代码上下文的理解，实时推荐相关的代码片段、函数、变量名等。例如，当用户在编写一个循环结构时，它会推荐常用的循环语法和相关函数，帮助用户快速完成代码的编写，提高编码速度和准确性。
• 减少重复劳动：对于一些常用的代码模式，如条件判断、异常处理等，代码助手可以自动补全代码，避免重复编写相同的代码，节省时间和精力。
• 多行代码推荐：除了单行代码补全，代码助手还支持多行代码推荐。例如，在编写一个复杂的算法或函数时，它可以根据用户的意图和上下文，推荐完整的代码块，帮助用户快速构建代码逻辑。

代码快速熟悉与理解

• 功能与逻辑快速理解：当接手新的项目或研究开源代码时，代码助手可以从功能、目的、使用场景和主要逻辑多个维度帮助用户快速理解代码、复杂数据结构与算法分析。例如，在阅读一个复杂的系统代码时，代码助手可以详细解释其功能和实现逻辑。
• 解读非标准化代码和注释：有时候，用户可能会遇到一些非标准化的代码或没有详细注释的代码。代码助手可以解读这些代码，提供通俗易懂的注释和说明，帮助用户理解代码的意图和功能。例如，在一些历史遗留代码中，可能存在一些晦涩难懂的代码，代码助手会解释这些代码的功能、目的、使用场景和主要逻辑。

代码调试与优化

• 快速定位代码错误：在代码运行报错时，代码助手通过分析堆栈信息和代码逻辑，能够快速定位代码中的错误和异常。例如，当运行代码报错时，在报错处单击代码助手图标，它会根据堆栈信息自动识别出可能导致问题的代码行或模块，并提供相关的上下文信息和建议，帮助用户快速找到错误根源，节省调试时间。
• 性能优化建议：代码助手能够分析代码的性能瓶颈，提供优化建议。例如，当用户检查代码时，它会识别出可能导致性能问题的代码片段，如低效的循环、不必要的计算等，并建议用户使用更高效的算法或数据结构来优化代码，提高程序的运行速度和响应能力。
• 代码可读性与可维护性优化：代码助手可以帮助用户提高代码的可读性和可维护性。例如，它会根据代码的结构和逻辑，建议用户对代码进行优化，如简化复杂的逻辑、提取重复的代码片段、增强注释和文档的清晰度等，使代码更加简洁、易读和易维护，降低后续代码修改和扩展的难度。

单元测试用例生成

• 功能验证测试用例生成：在编写新功能或修改现有功能时，代码助手可以基于代码实现自动为功能模块创建单元测试用例。例如，当用户编写一个处理用户登录的函数时，它会生成涵盖正常登录、无效用户名、错误密码等各种情况的测试用例，确保函数行为的正确性。
• 边界条件测试用例生成：代码助手能够识别代码中的边界条件，比如数组为空、字符串为空或达到最大长度等情况，并自动生成相应的测试用例。这些测试用例有助于检测代码在极端情况下的健壮性，提前发现潜在的边界问题。
• 异常处理测试用例生成：在开发过程中，异常处理是容易被忽略但又非常关键的环节。代码助手会根据代码逻辑，自动为可能引发异常的代码路径生成测试用例，如模拟网络错误、数据库连接失败等场景，确保代码能够正确捕获和处理异常。
• 高质量测试用例生成：代码助手能够分析代码逻辑和业务需求，生成既覆盖正常情况又兼顾异常场景的高质量测试用例。例如，对于一个电商网站的购物车功能，它会生成测试用例来验证添加商品、更新商品数量、删除商品等操作在不同条件下的正确性，以及应对库存不足、价格变更等异常情况的能力。

功能特性

• 支持多种编程语言，并能根据开发者键入的函数签名和注释自动生成函数体。
• 支持根据行级注释或代码上下文信息自动生成与描述场景匹配的代码。
• 可根据开发者当前光标位置的前后语句片段进行代码填空和补全。
• 支持跨文件生成与任务相关的代码。
• 支持从功能、目的和实现逻辑三个维度对代码进行解释说明。
• 可根据用户需求内容生成行级、函数级注释信息，能够帮助开发人员高效补充代码注释。
• 可根据输入的代码和错误信息，得到错误原因并给出修复方案。
• 支持生成高覆盖率的单元测试代码，包括单个方法和类级别的单元测试框架代码。
• 可根据提问来检索研发相关知识，提供答案。
• 支持对代码进行函数级检查功能，可及时、主动发现编码缺陷，提升代码质量和安全性。
• 支持代码翻译，可以指出不同语言关键元素差异，帮助开发者适应新环境

2.2.1 - 使用代码助手生成代码

使用快捷键通过上下文生成代码

1、打开一个c#文件，将编辑光标移动至需要生成代码位置，按下快捷键“Alt+C”。

2、代码助手将根据上下文生成代码，按下Tab键可接受代码助手生成代码内容。

通过问答生成代码

1、在研发对话窗口输入框中输入生成代码需求，如：“C#冒泡排序”，单击研发对话窗口输入框右下角按钮发送。

2、代码助手将在研发对话窗口中生成Java冒泡排序代码。

3、单击输入框右上角可以将对话内容归档并新建会话，单击研发对话窗口右上角可以查看历史提问。

4、对代码助手生成的代码块，可以进行如下操作：

• 单击复制代码。
• 单击在当前光标位置插入代码。
• 单击将代码另存为文件。

5、对代码助手回答的内容，可以进行如下操作：

• 单击可以针对提问重新生成结果。
• 单击可以复制回答内容。
• 单击对回答满意。
• 单击对回答不满意。

2.2.2 - 使用代码助手解释代码

通过问答功能解释代码

1、选中示例代码中“true”方法代码，单击右键，选择菜单“CodeArts 盘古助手：Add to Chat”或使用快捷键Ctrl+Shift+X将代码添加至研发对话窗口。

2、在研发对话窗口输入框中输入“/”，在弹出菜单中选择“/explain”，或单击研发对话窗口中“Code Explain”，单击发送。

3、代码助手将对代码进行解释，通过文字描述帮助开发人员理解代码。针对本次选中的代码，代码助手给的解释是：这段代码的主要功能是对一个整型数组进行排序。它使用了冒泡排序算法，这是一种简单但效率较低的排序算法。

2.2.3 - 使用代码助手注释代码

注释代码

1、选中示例代码，单击右键，选择菜单“CodeArts 盘古助手：Add to Chat”或使用快捷键Ctrl+Shift+X将代码添加至研发对话窗口。

2、在研发对话窗口输入框中输入“/”，在弹出菜单中选择“/comment”或单击研发对话窗口中“Code Comment”，单击发送。

3、代码助手将对代码进行注释，通过文字描述帮助开发人员理解代码。

2.2.4 - 研发知识问答

研发知识问答

1、在研发对话窗口中输入研发相关问题“生成一段读取文本内容代码”。

2、代码助手将使用Python或其他语言生成一段读取文本内容的代码。

2.2.5 - 常见问题

2.2.5.1 - 代码助手提示“代码生成暂无结果”

问题现象

使用代码助手生成代码时，研发对话窗口或IDE右下角提示“代码生成暂无结果”。

可能原因

代码助手对当前代码上下文生成代码暂无结果。

解决办法

重新触发代码生成或切换至代码中其他位置触发代码生成。

2.2.5.2 - 使用代码助手时提示“请登录后再使用”

问题现象

使用代码助手功能时，研发对话窗口或IDE弹出提示“请登录后再使用”。

可能原因

• 未使用账号登录。
• 原有登录状态已过期。

解决办法

使用研发对话窗口登录账号，或通过系统菜单“扩展”中的“登录”子菜单进行登录账号。

2.2.5.3 - 代码助手提示“授权已经过期”

问题现象

• 使用代码助手功能时，研发对话窗口上方提示“您的试用已经过期，请联系客户成功处理。”。
• 使用代码助手功能时，研发对话窗口上方提示“您的试用有效期已不足x天，请联系客户成功处理。”。

可能原因

• 您的使用许可已到期。
• 您的使用许可只剩x天有效期。

解决办法

通过华为云商店重新购买插件使用许可，或联系华为云商店客服处理。

2.3 - 支持使用#变量

通过使用 对话变量 开发者可以实现一些之前不容易实现的提示词，比如：开发者可以通过以下提示词引用某个文件内容，并要求AI将所引用的代码作为参考进行生成，示例如下：

• 请根据这个文件中的内容 #file:BankTransactionController.java 生成API文档，并使用标准的markdown格式输出。
• 请参考 #file:Dockerfile 编写一个 docker-compose.yaml 并将对外端口设置为8090，并将日志映射到本地路径中
• 请对 #selection 进行分析，重点关注其中可能存在的代码安全问题，并提供解决方案和示例代码 用户也可以组合以上变量，构建出更加复杂的提示词，比如：
• 请参考 #file:api_reference.yaml，修正以下代码中的接口调用逻辑 #selection
• 请参考 #editor:model.py77-89，生成10个单元测试，尽量覆盖各种场景

各类变量的具体调用方式

1. 打开SmartCode，在对话输入框点击“#”或者输入“#”，调起#变量

   

2. #selection变量用于在提示词中引入当前活动编辑器中被选中的代码内容

   • 选择#selection变量，选择代码，回车，对已选代码进行回复

     

   • 选择#selection变量，未选择代码，回车会提示：没有选择代码

     

3. 使用#editor变量，用于在当前编辑中选择不同的代码库，系统会提示选择类、方法等不同的代码块

   • 选择#editor变量，弹窗显示提取出的代码块

     

   • 选择#selection变量，未选择代码，回车会提示：没有选择代码

4. 使用#file变量可以引入当前项目中的任意文件，包括已经开启和未开启的。

   

3 - SmartChat 企业级ChatGPT服务

3.1 - 图表生成

使用场景

场景1 - 使用Mermaid生成思维导图

1. SmartChat Web端，对话使用Mermaid生成思维导图，可以使用以下提示词内容

使用mermaid生成一个说明devops知识体系的思维导图，请确保输出的mermaid markdown符合格式规范。

2. 点击“预览”，查看Mermaid生成的思维导图

3. Mermaid生成的思维导图点击“放大”，放大的图片可以进行放大、缩小、翻转

4. Mermaid生成的思维导图进行“下载”

场景2 - 使用Mermaid生成一个序列图

1. SmartChat Web端，对话使用Mermaid生成序列图，可以使用以下提示词

使用Mermaid生成一个序列图来说明银行中的存款流程，其中有4个角色： 客户 柜员员工 分行经理 银行系统

2. 点击“预览”，查看Mermaid生成的序列图

场景3 - 使用mermaid生成可视化ER图

1. SmartChat Web端，对话使用Mermaid生成可视化ER图，可以使用以下提示词

分析以下sql语句的内容，使用mermaid可视化ER图展示其中所涉及的表和他们之间的关联；直接生成ER图，不要其他文字解释
    
SELECT employee_id, department_name, l.city, e.department_id, l.location_id 
FROM employees e, departments d, locations l 
WHERE e.department_id = d.department_id 
AND d.location_id = l.location_id ;

2. 点击“预览”，查看Mermaid生成的可视化ER图

场景4 - 使用Mermaid Markdown格式对代码直接输出

1. 代码直接使用Mermaid Markdown格式输出，可是使用以下提示词

直接输出以下内容，使用mermaid markdown格式

    gitGraph
        commit id: "1"
        commit id: "2"
        branch nice_feature
        checkout nice_feature
        commit id: "3"
        checkout main
        commit id: "4"
        checkout nice_feature
        branch very_nice_feature
        checkout very_nice_feature
        commit id: "5"
        checkout main
        commit id: "6"
        checkout nice_feature
        commit id: "7"
        checkout main
        merge nice_feature id: "customID" tag: "customTag" type: REVERSE
        checkout very_nice_feature
        commit id: "8"
        checkout main
        commit id: "9"

2. 点击“预览”，查看Mermaid生成的git图

场景5 - explain_chat 提示词

explain_chat 是本次版本更新中新提供的提示词，可以针对某段代码生成对应的流程图和时序图，帮助开发人员可视化的理解代码结构。

1. 在SmartChat Web中输入 /explain_chat 即可调出词提示词的输入界面，在其中输入 代码语言 类型和代码内容

2. 点击 Submit 后即可以完成对应的流程图和时序图的生成，对于以下示例代码所生成的图如下 示例代码：

    public boolean insert(String word) {
        TrieNode current = root;
        for (char c : word.toCharArray()) {
            if (!current.hasChild(c)) {
                current.children.put(c, new TrieNode(c));
            }
            current = current.children.get(c);
        }
        if (current.isEndOfWord) {
            return false;
        }
        current.isEndOfWord = true;
        return true;
    }

流程图

时序图

3.2 - 图片识别

激活图片识别能力

图片识别能力的激活需要在管理后台完成2项配置，分别是：开启特性开关和配置GPT-4o模型。

1.首先，管理人员需要确保在 参数设置 中开启使用人 chat-data-v2 和 chat_image 两个特性的权限；这2个特性开关可以完全开启或者为指定人员或者部门开启（部门和人员只能二选一）。

2.需要在模型适配器中增加GPT-4o模型，并确保模型类型指定为：completion_azure_gpt4_vision。

3.最后，确保在 参数设置中的 aise.model.config.default 配置中包含 “image_model_type”: “completion_azure_gpt4_vision” 配置内容

使用场景

1.在web页面中，用户可点击输入框右下角的图标，在弹出的页面中选择图片进行上传。

2.选择图片后，可在输入框中对图片进行描述、提问等。

3.发送图片和问题，模型将对图片进行识别并回答问题。

4 - Code Review Agent 代码评审智能体

4.1 - 启用和配置

服务端配置

要使用 Code Review Agent，管理员首先需要在服务端添加可用的大模型API访问地址，并配置模型访问参数。当前支持的模型包括

• GPT系列模型：支持 gpt-3.5-turbo-16k、gpt-4、gpt-4o，并支持使用 OpenAI 或者 Azure OpenAI 服务。
• DeepSeek系列模型：支持 deepseek api服务、 deepseek v2 16b，并支持使用自建的模型API服务，包括使用Nvidia GPU或者华为晟腾910B等硬件平台。

有关模型部署和推理服务的更多信息，请联系部署实施人员。

配置大模型

默认模型为 gpt-3.5-turbo-16k，常用的模型还包括：gpt-4o 和 deepseek/deepseek-chat ,如果需要使用其他模型，请联系部署实施人员来修改。

# pr_agent\settings\configuration.toml 
[config]
model="gpt-3.5-turbo-16k"
model_turbo="gpt-3.5-turbo-16k"
fallback_models=["gpt-3.5-turbo-16k"]

配置模型访问参数

以下是 在 .secrets.toml 中 Azure OpenAI 的配置示例：

[openai]
key = "<OpenAI API key>"
api_type = "azure" 
api_version = '2023-03-15-preview'  
api_base = "<endpoint url>"  
deployment_id = "<your deployment_id>"  

以下是 在 .secrets.toml 中 deepseek 的配置示例：

[openai]
key = "<model key>" 
api_base = "<model api endpoint>" 

DevOps 平台支持

Code Review Agent 代码评审智能体 支持多种 DevOps 平台，包括 Azure DevOps、GitLab 等。当前我们已经提供对 Azure DevOps 平台的的支持，对于GitLab 平台的支持正在适配中，末未正式支持后我们会补充这部分的文档。

Azure DevOps 配置

目前 Code Review Agent 代码评审智能体 已支持 Azure DevOps Servies和Azure DevOps Server的集成。 在使用前需要先配置好webhook, 目前使用到了两个webhook,一个是创建PR事件和提交PR Comment事件。

另外还需配置启用的 Azure DevOps 机构。

获取访问token

需要配置用于Code Review Agent 调用 Azure DevOps API 的 访问 token（pat）。

Azure DevOps 支持2种第三方服务认证方式，分别为：PAT 令牌 或 DefaultAzureCredential 认证（仅适用于Azure DevOps 在线服务）。

• PAT 创建速度更快，并有内置的到期日期，，PAT需要附属于某个真实用户，需要用户对PAT的过期时间进行小心的维护，否则额很容易出现因为PAT过期而影响使用的情况。
• 使用 DefaultAzureCredential，可以使用托管身份或服务主体，安全性更好，并且会为代理创建单独的 ADO 用户身份（通过 AAD）；但创建过程复杂，而且仅适用于 Azure DevOps 在线服务）。

如果选择了 PAT，您可以在 .secrets.toml 中分配该值。如果选择了 DefaultAzureCredential，您可以直接分配 AZURE_CLIENT_SECRET 等额外的环境变量。

以下是 .secrets.toml 的配置示例：

[azure_devops]
# For Azure devops personal access token
org = "<azure devops org or collection>" 
pat = "<pat>" 

设置服务访问用户和密码

要在 Azure DevOps 中通过 Service Hook 调用 Code Review Agent，首先我们需要配置或者获取 .secrets.toml 中的访问用户名和密码。

以下是 .secrets.toml 文件中的配置示例，您剋打开这个我文件，修复并记录其中的 webhook_username 和 webhook_password，在后续的配置中需要用到。

## in # pr_agent/settings/.secrets.toml 中
[azure_devops_server]
webhook_username = "<basic auth user>" #default value is aisedevpr
webhook_password = "<basic auth password>" #default password is <TO BE Fill>

确保 webhook 端点仅通过 HTTPS 访问，以降低使用基本身份验证时凭据被拦截的风险。

Code Review Agent提供和api支持基本认证和匿名访问（不需要认证）两种模式，前者适用于外网环境，后者适用于内网环境。如果想采用匿名方式（无认证），只里面要把

在 .secrets.toml中，对整个节点注释(或者删除)即可.

# [azure_devops_server]
# webhook_username = "<basic auth user>" 
# webhook_password = "<basic auth password>" 

另外azure devops 的webhook配置那里帐号和密码留空即可，修改完后需要重启 Code Review Agent 服务才能生效。

配置Service Hook

使用Code Review Agent之前需要在Azure DevOps对应的团队项目(Team Project)中配置对应的Web Hook，所需要配置的Web Hook主要有两个。

• Pull Request created: 当PR创建的时候自动触发
• Pull request commented on：当PR上被用户添加了新的评论的时候触发

Web Hooks 配置界面如图：

Web Hook 的具体配置参数如下

• URL：需要只想当前的 /workspace-api/pragent/
• 认证方式中的用户名和密码可以在我们提供的物料中获取

完成以上配置后，Code Review Agent 就可以正常工作了。

4.1.1 -

Local configuration file

By uploading a local .pr_agent.toml file to the root of the repo’s main branch, you can edit and customize any configuration parameter. Note that you need to upload .pr_agent.toml prior to creating a PR, in order for the configuration to take effect.

For example, if you set in .pr_agent.toml:

[pr_reviewer]
extra_instructions="""\
- instruction a
- instruction b
...
"""

Then you can give a list of extra instructions to the review tool.

Extra instructions

All Code Review Agent tools have a parameter called extra_instructions, that enables to add free-text extra instructions. Example usage:

/update_changelog --pr_update_changelog.extra_instructions="Make sure to update also the version ..."

Working with large PRs

TODO

Changing a model

TODO

Patch Extra Lines

By default, around any change in your PR, git patch provides three lines of context above and below the change.

@@ -12,5 +12,5 @@ def func1():
 code line that already existed in the file...
 code line that already existed in the file...
 code line that already existed in the file....
-code line that was removed in the PR
+new code line added in the PR
 code line that already existed in the file...
 code line that already existed in the file...
 code line that already existed in the file...

For the review, describe, ask and add_docs tools, if the token budget allows, Code Review Agent tries to increase the number of lines of context, via the parameter:

[config]
patch_extra_lines=3

Increasing this number provides more context to the model, but will also increase the token budget. Code Review Agent automatically sets this number to 0, using the original git patch.

Editing the prompts

The prompts for the various Code Review Agent tools are defined in the pr_agent/settings folder. In practice, the prompts are loaded and stored as a standard setting object. Hence, editing them is similar to editing any other configuration value - just place the relevant key in .pr_agent.tomlfile, and override the default value.

For example, if you want to edit the prompts of the describe tool, you can add the following to your .pr_agent.toml file:

[pr_description_prompt]
system="""
...
"""
user="""
...
"""

Note that the new prompt will need to generate an output compatible with the relevant post-process function.

4.2 - 指令参考

指令参考

当前 Code Review Agent 所支持的指令内容如下，我们持续改进现有指令的生成效果并根据需要持续添加新的指令内容：

• /summary: 生成PR描述，创建PR时会自动生成，也可以手工执行。
• /review：触发代码审查并提供反馈。
• /ask [问题]：提出具体问题并获取回答。
• /update_changelog：自动生成并更新变更日志。
• /generate_labels：自动生成标签，并添加到当前PR中

4.2.1 -

Overview

The summary(same with describe) tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels.

The tool can be triggered automatically every time a new PR be created, or it can be invoked manually by commenting on any PR:

/describe

Example usage

Manual triggering

Invoke the tool manually by commenting /describe on any PR:

{width=512}

After ~30 seconds, the tool will generate a description for the PR:

{width=512}

If you want to edit configurations, add the relevant ones to the command:

/describe --pr_description.some_config1=... --pr_description.some_config2=...

Automatic triggering

To run the describe automatically when a PR is opened, define in a configuration file:

[azure_devops_server]
pr_commands = [
    "/describe",
    #"/review --pr_reviewer.num_code_suggestions=0",
    #"/update_changelog"
    #"/improve", #dont add this ,mabey has loop exec bug
]


[gitlab]
url = "https://gitlab.com" # URL to the gitlab service
pr_commands = [
    "/describe --pr_description.final_update_message=false",
    "/review --pr_reviewer.num_code_suggestions=0",
    "/improve",
]
handle_push_trigger = false
push_commands = [
    "/describe",
    "/review --pr_reviewer.num_code_suggestions=0",
]

[pr_description]
publish_labels = ...
...

• The pr_commands lists commands that will be executed automatically when a PR is opened.
• The [pr_description] section contains the configurations for the describe tool you want to edit (if any).

Configuration options

!!! example “Possible configurations”

Markers template

To enable markers, set pr_description.use_description_markers=true. Markers enable to easily integrate user’s content and auto-generated content, with a template-like mechanism.

For example, if the PR original description was:

User content...

## PR Type:
pr_agent:type

## PR Description:
pr_agent:summary

## PR Walkthrough:
pr_agent:walkthrough

The marker pr_agent:type will be replaced with the PR type, pr_agent:summary will be replaced with the PR summary, and pr_agent:walkthrough will be replaced with the PR walkthrough.

{width=512}

→

{width=512}

Configuration params:

• use_description_markers: if set to true, the tool will use markers template. It replaces every marker of the form pr_agent:marker_name with the relevant content. Default is false.
• include_generated_by_header: if set to true, the tool will add a dedicated header: ‘Generated by Code Review Agent at …’ to any automatic content. Default is true.

Usage Tips

!!! tip “Automation” - When you first install , the default mode for the describe tool is: pr_commands = ["/describe", ...] meaning the describe tool will run automatically when any PR be created, with the default configurations.

• Markers are an alternative way to control the generated description, to give maximal control to the user. If you set:

pr_commands = ["/describe --pr_description.use_description_markers=true", ...]

the tool will replace every marker of the form pr_agent:marker_name in the PR description with the relevant content, where marker_name is one of the following: * type: the PR type. * summary: the PR summary. * walkthrough: the PR walkthrough.

• Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all.

4.2.2 -

Overview

The review tool scans the PR code changes, and automatically generates a PR review. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR:

/review

Example usage

Manual triggering

Invoke the tool manually by commenting /review on any PR:

{width=512}

After ~30 seconds, the tool will generate a review for the PR:

{width=512}

If you want to edit configurations, add the relevant ones to the command:

/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...

Automatic triggering

To run the review automatically when a PR is opened, define in a configuration file:

[github_app]
pr_commands = [
    "/review",
    ...
]

[pr_reviewer]
num_code_suggestions = ...
...

• The pr_commands lists commands that will be executed automatically when a PR is opened.
• The [pr_reviewer] section contains the configurations for the review tool you want to edit (if any).

Incremental Mode

Incremental review only considers changes since the last Code Review Agent review. This can be useful when working on the PR in an iterative manner, and you want to focus on the changes since the last review instead of reviewing the entire PR again. For invoking the incremental mode, the following command can be used:

/review -i

Note that the incremental mode is only available for GitHub.

{width=512}

PR Reflection

By invoking:

/reflect_and_review

The tool will first ask the author questions about the PR, and will guide the review based on their answers.

Configuration options

!!! example “General options”

!!! example “Enable\disable specific sub-sections”

!!! example “SOC2 ticket compliance 💎”

This sub-tool checks if the PR description properly contains a ticket to a project management system (e.g., Jira, Asana, Trello, etc.), as required by SOC2 compliance. If not, it will add a label to the PR: “Missing SOC2 ticket”.

!!! example “Adding PR labels”

You can enable\disable the review tool to add specific labels to the PR:

!!! example “Auto-approval”

If enabled, the review tool can approve a PR when a specific comment, /review auto_approve, is invoked.

Usage Tips

!!! tip “General guidelines”

The `review` tool provides a collection of possible feedbacks about a PR.
It is recommended to review the [Configuration options](#configuration-options) section, and choose the relevant options for your use case.

Some of the features that are disabled by default are quite useful, and should be considered for enabling. For example: 
`require_score_review`, `require_soc2_ticket`, and more.

On the other hand, if you find one of the enabled features to be irrelevant for your use case, disable it. No default configuration can fit all use cases.

!!! tip “Automation” When you first install Code Review Agent app, the default mode for the review tool is: pr_commands = ["/review --pr_reviewer.num_code_suggestions=0", ...] Meaning the review tool will run automatically on every PR, without providing code suggestions. Edit this field to enable/disable the tool, or to change the used configurations.

!!! tip “Code suggestions”

If you set `num_code_suggestions`>0 , the `review` tool will also provide code suggestions.

Notice If you are interested **only** in the code suggestions, it is recommended to use the [`improve`](./improve.md) feature instead, since it is a dedicated only to code suggestions, and usually gives better results.
Use the `review` tool if you want to get more comprehensive feedback, which includes code suggestions as well.

!!! tip “Possible labels from the review tool”

The `review` tool can auto-generate two specific types of labels for a PR:

- a `possible security issue` label that detects if a possible [security issue](settings/pr_reviewer_prompts.toml#L136) exists in the PR code (`enable_review_labels_security` flag)
- a `Review effort [1-5]: x` label, where x is the estimated effort to review the PR (`enable_review_labels_effort` flag)

Both modes are useful, and we recommended to enable them.

!!! tip “Extra instructions”

Extra instructions are important.
The `review` tool can be configured with extra instructions, which can be used to guide the model to a feedback tailored to the needs of your project.

Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize.

Examples for extra instructions:
```
[pr_reviewer]
extra_instructions="""\
In the code feedback section, emphasize the following:
- Does the code logic cover relevant edge cases?
- Is the code logic clear and easy to understand?
- Is the code logic efficient?
...
"""
```
Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

!!! tip “Auto-approval”

Code Review Agent can approve a PR when a specific comment is invoked.

To ensure safety, the auto-approval feature is disabled by default. To enable auto-approval, you need to actively set in a pre-defined configuration file the following:
```
[pr_reviewer]
enable_auto_approval = true
```
(this specific flag cannot be set with a command line argument, only in the configuration file, committed to the repository)


After enabling, by commenting on a PR:
```
/review auto_approve
```
Code Review Agent will automatically approve the PR, and add a comment with the approval.


You can also enable auto-approval only if the PR meets certain requirements, such as that the `estimated_review_effort` label is equal or below a certain threshold, by adjusting the flag:
```
[pr_reviewer]
maximal_review_effort = 5
```

4.2.3 -

Overview

The ask tool answers questions about the PR, based on the PR code changes. Make sure to be specific and clear in your questions. It can be invoked manually by commenting on any PR:

/ask "..."

Example usage

{width=512}

{width=512}

Note that the tool does not have “memory” of previous questions, and answers each question independently.

4.2.4 -

Overview

The update_changelog tool automatically updates the CHANGELOG.md file with the PR changes. It can be invoked manually by commenting on any PR:

/update_changelog

Example usage

{width=768}

{width=768}

Configuration options

Under the section pr_update_changelog, the configuration file contains options to customize the ‘update changelog’ tool:

• push_changelog_changes: whether to push the changes to CHANGELOG.md, or just print them. Default is false (print only).
• extra_instructions: Optional extra instructions to the tool. For example: “focus on the changes in the file X. Ignore change in …

4.2.5 -

Overview

The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or it can be invoked manually by commenting on any PR:

/improve

Example usage

Manual triggering

Invoke the tool manually by commenting /improve on any PR. The code suggestions by default are presented as a single comment:

![code suggestions as comment]code_suggestions_as_comment.png){width=512}

To edit configurations related to the improve tool, use the following template:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

For example, you can choose to present the suggestions as commitable code comments, by running the following command:

/improve --pr_code_suggestions.commitable_code_suggestions=true

{width=512}

Note that a single comment has a significantly smaller PR footprint. We recommend this mode for most cases. Also note that collapsible are not supported in Bitbucket. Hence, the suggestions are presented there as code comments.

Automatic triggering

To run the improve automatically when a PR is opened, define in a configuration file:

[github_app]
pr_commands = [
    "/improve",
    ...
]

[pr_code_suggestions]
num_code_suggestions_per_chunk = ...
...

• The pr_commands lists commands that will be executed automatically when a PR is opened.
• The [pr_code_suggestions] section contains the configurations for the improve tool you want to edit (if any)

Extended mode

An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR by setting:

[pr_code_suggestions]
auto_extended_mode=true

(This mode is true by default).

Note that the extended mode divides the PR code changes into chunks, up to the token limits, where each chunk is handled separately (might use multiple calls to GPT-4 for large PRs). Hence, the total number of suggestions is proportional to the number of chunks, i.e., the size of the PR.

Configuration options

!!! example “General options”

!!! example “params for ’extended’ mode”

Usage Tips

!!! tip “Extra instructions”

Extra instructions are very important for the `imrpove` tool, since they enable you to guide the model to suggestions that are more relevant to the specific needs of the project.

Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on.

Examples for extra instructions:
```
[pr_code_suggestions] # /improve #
extra_instructions="""\
Emphasize the following aspects:
- Does the code logic cover relevant edge cases?
- Is the code logic clear and easy to understand?
- Is the code logic efficient?
...
"""
```
Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

!!! tip “Review vs. Improve tools comparison”

- The [review](./review.md) tool includes a section called 'Possible issues', that also provide feedback on the PR Code.
In this section, the model is instructed to focus **only** on [major bugs and issues](settings/pr_reviewer_prompts.toml#L71).
- The `improve` tool, on the other hand, has a broader mandate, and in addition to bugs and issues, it can also give suggestions for improving code quality and making the code more efficient, readable, and maintainable (see [here](pr_code_suggestions_prompts.toml#L34)).
- Hence, if you are interested only in feedback about clear bugs, the `review` tool might suffice. If you want a more detailed feedback, including broader suggestions for improving the PR code, also enable the `improve` tool to run on each PR.

4.2.6 -

Overview

The help tool provides a list of all the available tools and their descriptions. For Code Review Agent Pro users, it also enables to trigger each tool by checking the relevant box.

It can be invoked manually by commenting on any PR:

/help

Example usage

An example result:

{width=750}

→

{width=750}

5 - SmartAnswer 企业知识库