Starfish AI Chat 教程

• 进入“设置”并选择“模型配置”，可查看当前用户可访问的模型平台列表（如 DeepSeek、OpenAI 等）。
• 每个模型平台作为一级目录，点击可展开其下的模型列表。

新增：

• 点击“新建设置”，填写以下参数后保存：
  • 设置名称（自定义）：自定义平台名称（如“OpenAI”、“DeepSeek”）。
  • AI Endpoint：模型接口地址。
  • AI Backend URL：部署在本地用于转发 AI 请求的后端地址，默认值为 http://localhost:3789。
  • API Key：访问 AI 接口所需的密钥。
  • 温度：控制生成内容随机性的参数：
    • 温度较低（如 0.1 或 0.2）：生成内容更确定、连贯
    • 温度较高（如 0.8 或 1.0 以上）：内容更具创造性，但连贯性可能较弱
  • 错误重试次数：系统自动重新发起请求的次数上限
  • 配置类型：私有/系统（仅管理员可设）。
  
• 保存后显示当前模型平台下的模型列表。

修改/删除。

进入相应模型平台，可直接修改参数或删除平台。

新增：

在模型列表下点击“新增模型”，填写：

• 模型ID（自定义）：唯一标识符，创建后不可更改（如 gpt-3.5、deepseek-chat）。
• 模型名称（自定义）：显示名称，可修改（如 OpenAI GPT-3.5、DeepSeek 中文对话模型）。

修改/删除：

在模型列表中编辑或删除模型。

设为默认：

可将某模型设为平台默认，新建对话或未指定模型时自动选用。

进入“设置”中的“MCP 管理”，可查看 MCP 服务器管理列表，包括：

• 服务器：展示当前所有的 MCP 服务器。
• 资源：与 MCP 服务器相关的资源信息。
• 工具：所有未禁用 MCP 服务器中的工具列表（含描述和参数配置）。

新增：

点击“添加MCP服务器”，填写以下参数后添加：

• 服务器名称：自定义服务器名称。
• 服务器地址：MCP Server 访问URL（默认http://localhost:8848/，可按实际环境填写）。
• 认证类型：用户名+密码或 Token。
• 传输类型：Agent 与 MCP Server 之间的数据传输方式。支持 HTTP 和 SSE 两种方式。

修改/删除：

可随时修改或删除已创建的 MCP 服务器。

启用/禁用：

切换服务器启用状态，禁用后该服务器下工具不可用。

刷新：

手动刷新服务器和工具列表，获取最新状态。

进入“设置”中的“知识库配置”，展开知识库列表（所有用户公开可见）。

新增：

点击“创建知识库”，输入自定义名称创建新知识库。

配置：

• 点击任意知识库的配置按钮，可进入该知识库的详细配置页面。

每个知识库的配置分为两部分：

• 知识库参数设置
  • DolphinDB 服务器 URL：知识库数据存储服务器地址。
  • 用户名、密码：访问服务器的认证信息。
  • 数据库名、表名：指定知识库数据存储的数据库和表。
  • 向量模型路径：用于指定文档向量化所使用的模型文件路径。
  • 词表路径：用于指定分词或向量化过程中使用的词表文件路径。
  • 检索数量：每次检索返回的结果条数（1-10，默认3条）。
• 知识库表结构要求：为了保证系统正常运行，配置的数据库名和表名对应的 DolphinDB 库表必须严格遵循以下结构设计：

建库建表参考脚本：

db1 = database(, HASH, [STRING, 10])
db2 = database(, VALUE, 2017.08M..2017.09M)
db = database(directory = 'dfs://DocsVecDB2', partitionType = COMPO, partitionScheme = [db1,db2], engine= `PKEY, atomic = `TRANS)
db.createPartitionedTable(table = table(1:0, ["id","updateTime","content","embedding","metadata"],["STRING","TIMESTAMP","BLOB","FLOAT[]","BLOB"]),tableName = 'data',partitionColumns =`id`updateTime,primaryKey = `id`updateTime,indexes = {"embedding": "vectorindex(type=hnsw, dim=1024)"})

填写完上述参数后，点击“保存”按钮，系统将保存知识库配置。

• 知识库文档管理：仅在参数设置完整并保存后，才能进行文档管理。
  • 添加文档：上传 PDF（最大10MB），系统自动解析并生成向量。可手动编辑标题和内容。
• 文档列表查看：展示该知识库所有已上传文档，包括名称、上传时间等信息。
• 文档操作：仅支持查看，不能删除或修改文档

删除/刷新：

可删除不再需要的知识库，或手动刷新列表获取最新状态。

• 进入“设置”中的“Agent 配置”，展开智能体列表，展示所有已创建的智能体（系统和私有类型）。
• 内置 Agent 说明：系统默认提供以下三类内置 Agent，用户可直接选择使用：
  • 因子 Agent：专注于 DolphinDB 因子脚本的编写与分步处理，适合量化因子开发与数据分析场景。
  • 策略 Agent：专门用于 DolphinDB 策略脚本和回测框架的编写，支持多种资产和行情类型的策略开发。
  • 分析 Agent：面向数据分析与业务洞察，能够根据表结构和数据，辅助用户进行多维度分析和结果解读。

新增：

点击“添加”按钮，填写以下参数后保存：

• Agent 名称：自定义唯一显示名称。
• Agent 描述（选填）：简要说明职责或场景。
• 配置类型：私有/系统（仅管理员可设）。
• 角色与任务：定义身份定位及主要任务。
• 允许使用的 MCP 配置：选择可调用的 MCP 服务器（多选）。
• 允许使用的知识库：指定可访问的知识库（多选）。
• 工作流程：自定义多步处理流程。
• 发送库表信息（开关）：是否允许发送库表结构信息。
• 启用函数调用（开关）：是否允许调用函数（包括用户自定义函数、内置的 coldefs 和 execute 函数）
  • 用户自定义函数：需先在 DolphinDB 中以 function view 方式注册，并在此处配置为可调用函数。
  • coldefs：返回指定表的列定义（列名与类型），用于校验与映射。
  • execute：执行一段脚本或查询语句，返回运行结果或状态信息。

填写完上述参数后，点击“保存”按钮，系统将保存智能体配置。

若点击“取消”按钮，则退出 Agent 配置，返回对话界面。

编辑/删除：

• 编辑：点击任意智能体进入配置界面修改，保存生效。
• 删除：在列表中点击“删除”按钮，移除不再需要的智能体（操作不可恢复）。

按照第2.1节的流程，完成AI模型平台及模型的配置，确保可用于对话调用。

具体配置流程可参考 MCP 使用指南。

• MCP服务器名称：factorCalculate
• 包含工具：详细定义见文末 “附件:MCP工具详细说明”。
  • 工具1：get_datasource_structure（数据结构查询）
    • 入参：databases（数据库路径列表）、tables（表名列表，需与databases一一对应）
    • 出参：每个表的列定义（列名与类型）、推断时间列、股票代码列、时间范围、样本数据等结构信息
    • 目的：构建因子计算流水线前，批量获取目标库表结构和关键字段，用于字段映射及频率/区间确认。
  • 工具2：sql_with_contextby（SQL计算执行）
    • 入参：dbPath、tableName、startDate、endDate、factorName、factorFormula、securityidName、tradetimeName、outputTableName
    • 出参：执行状态消息（含结果表名等信息），结果写入指定共享表 outputTableName
    • 目的：基于映射字段和因子公式，在指定时间区间批量计算单因子结果，写入共享内存表供后续预览。

• 知识库名称：小型函数及因子文档库
• 内容说明：包含主流金融因子的标准定义、计算公式及研报文档。支持因子公式检索和参数查询。
• 配置参数：已设置 DolphinDB 服务器、数据库、表名、向量模型路径等，确保知识库可被Agent调用。

• Agent 名称：因子计算
• Agent 描述：根据用户输入的因子名称和时间信息，自动检索知识库公式，匹配数据表字段，调用 MCP 工具完成因子计算，并展示前5行结果。
• 角色与任务：

  ## 角色描述 (Role Profile)
  你是一个专注于金融因子计算的 DolphinDB 智能专家。你的职责是将自然语言需求转化为精确的计算流水线。
  你具备自主探查数据的能力，能够从平台可用的数据源中找到最匹配的库表，并基于真实的物理字段完成计算。
  
  **你的唯一目标**：完成因子计算并直接在窗口展示前5行结果，供用户预览。
  **你的核心原则**：只做决策与调用，不写复杂脚本，不直接查询数据。
  
  ## 绝对限制
  违反以下任何限制将导致任务失败，必须严格遵守：
  ### 执行与调用限制
  - 严格流程顺序：你必须且只能按以下顺序执行：
      - 分析需求 -> 从输入中选定表 -> 调用工具 get_datasource_structure 获取物理列名，防止字段幻觉。
      - 映射字段 -> 调用工具 sql_with_contextby：用于在数据库内存中执行计算。
      - 使用Function call： export_table_to_window：生成一行代码直接调用数据库内的全局函数视图，展示结果。
  - 禁止操作：
      - 严禁直接猜测数据库列名。必须等待 get_datasource_structure 返回物理列名后方可写公式。
      - 严禁使用 MCP 工具机制去调用 export_table_to_window（即不要发送 JSON Tool Call）。
      - 禁止为 export_table_to_window 编写 def ... 函数定义体（它已存在于数据库中）。
      - 严禁在最后一步输出 Markdown 代码块（如 dolphindb...）或 XML 标签。
      - 禁止调用 execute、testsql 或任何通用查询工具。
  - 必须执行的操作：
      - 最后一步必须发起 export_table_to_window 的 Function Call。
      - 关键: 调用 export_table_to_window 时，必须使用位置参数（Positional Argument），不要使用关键字参数（如 tableName=...）。
  
  ### 数据完整性限制
  - 基于上下文：因子公式必须来自知识库，数据表必须来自平台提供的库表信息。严禁凭空捏造表名或字段名。
  - 公式准确性：factorFormula 参数中的变量名必须严格等于数据库表中的物理列名（区分大小写）。
      - 错误示例：数据库列名为 close_price，公式写成 mavg(close, 20) -> 失败。
      - 正确示例：数据库列名为 close_price，公式写成 mavg(close_price, 20) -> 成功。
  - 参数填充：所有字段必须存在。无法确定的字段使用空字符串 ""，不可使用 null。
  
  ## 输入上下文说明 (Context Awareness)
  平台将在对话中提供以下三类信息，你必须基于这些信息进行推理：
  
  - 用户需求：包含因子名称（如 "MA", "RSI"）和时间范围（startDate, endDate）。
  - 知识库 (Knowledge Base)：包含因子标准名称、计算公式、参数语法（Syntax）和所需变量（如 close, volume）。
  - 库表信息：包含 type、path 和 comments（字段说明）。

• 配置类型：系统
• 允许使用的MCP配置：factorCalculate
• 允许使用的知识库：小型函数及因子文档库
• 工作流程：

  # 工作流程（必须严格遵守工作流程和输出格式，不得输出其他内容）
  你必须严格按照以下**三个阶段**进行交互，**不要一次性输出所有内容**。
  
  ## 阶段一：需求分析与数据锁定
  直接输出 Markdown 文本，完成后停止生成，等待系统调用工具。
  ### 1. 需求分析与数据锁定
  - 阅读输入：分析用户输入的因子名称、时间范围，以及知识库提供的计算公式（Formula）。
  - 分析内容：
      - 因子名称：明确当前计算的因子。
      - 计算公式：提取知识库中的抽象公式（如 (High - Low) / Close）。
      - 关键变量：列出公式所需的逻辑变量（如：最高价、最低价、收盘价）。
      - 时间/标的：确认计算的时间范围和标的类型。
  - 输出示例：
  <MARKDOWN>
  ### 1. 需求分析完成
  - **因子**: MA (移动平均)
  - **公式**: `mavg(close, 20)`
  - **核心变量**: 收盘价 (Price), 窗口期 (20)
  - **时间范围**: 2024.01.01 - 2024.06.01</MARKDOWN>
  
  **(在此处停止文本生成，并立即调用工具 get_datasource_structure 以获取物理列名)**
  
  ## 阶段二：字段映射与计算执行
  当 get_datasource_structure 返回表结构后，执行此阶段。
  ### 2. 匹配平台库表与公式转译
  - 关键动作：基于工具返回的 columns 列表，将逻辑变量（如 High）精确映射为物理列名（如 high_price）。如果字段不存在，需报错。
  - 公式转译 (Translation)：
      - 这是一个关键步骤。你必须将知识库中的“抽象公式”翻译成“可执行公式”。
      - 将公式中的逻辑变量替换为数据库表中实际的物理列名。
  - 输出示例：
  <MARKDOWN>
  ### 2. 数据匹配与公式转译
  - **数据源**: dfs://stock / daily_kline
  - **变量映射**:
      - 逻辑变量 High -> 物理列名 high_price
      - 逻辑变量 Low -> 物理列名 low_price
      - 逻辑变量 PreClose -> 物理列名 pre_close
  - **生成可执行公式**: (high_price - low_price) / pre_close</MARKDOWN>
  
  **(在此处停止文本生成，并根据 Step 2 的结果发起 sql_with_contextby 工具调用)**
  ## 阶段三：结果确认与展示
  当 sql_with_contextby 工具成功返回后（通常返回状态或临时表名），一次性输出 Step 3 和 Step 4。
  ### 3. 执行计算
  - 简要确认计算已完成，并复述生成的临时表名（outputTableName）。
  - 输出示例： 
  <MARKDOWN>
  ### 3. 计算任务已执行
  - 状态：计算完成，结果已写入内存表 res_ma_2024。 
  - 操作: 正在调用数据库视图展示前 5 行数据... </MARKDOWN>
  
  ### 4. 结果预览 
  - 执行逻辑：
      - 此处不需要输出任何 Markdown 文本或代码块。
      - 直接发起 Function Call：export_table_to_window。
      - 参数格式 (CRITICAL)：
          - 不要使用参数名（如 tableName="..."）。
          - 直接传入表名字符串作为第一个参数。
          - 目标是生成 args=["您的表名"] 的列表结构，而不是 kwargs={"tableName": "..."}。
  
  **(在此处停止文本生成，并立即发起 export_table_to_window 的 Function Call，仅传入表名字符串)**

• 发送库表信息：已开启
• 函数调用：已开启
  • 函数名称：export_table_to_window

    # 该函数需在 DolphinDB 平台以 function view 方式注册。
    def export_table_to_window(tableName){
        try{
            // 检查表是否存在
            if(objs(true).name.find(tableName) < 0){
                return "错误：内存中未找到表 [" + tableName + "]，请检查上一步计算是否成功。"
            }
            // 获取表对象
            t = objByName(tableName)
            // 查询前5行
            res = select top 5 * from t
            return res
        }catch(ex){
            return "查询结果时出错：" + ex
        }
    }
    addFunctionView(export_table_to_window)

  • 参数：

    {
        "type": "object",
        "properties": {
            "tableName": {
                "type": "string",
                "description": "DolphinDB 内存中已存在的共享表名称（即上一步 sql_with_contextby 计算输出的 outputTableName）。"
            }
        },
        "required": [
            "tableName"
        ]
    }

  • 示例：

    // 示例：预览因子计算结果的前5行
    export_table_to_window(
        "factor_result_temp"
    )