研报分析助手

研报分析功能模块为 Starfish AI 专有功能，仅在 Starfish AI 授权生效后可用。

研报分析功能通过“创建任务—任务列表跟踪”的方式使用。

用户可在研报分析模块中创建任务，对行业研报进行处理，并从中提取或补充因子。

创建完成后，任务将显示在任务列表中。用户可在任务列表中查看任务执行状态、创建人、创建时间等。系统支持通过可视化方式展示任务结果，辅助用户分析因子合理性。对于执行失败的任务，可在任务列表中查看失败信息，必要时暂停任务并调整相关代码后重新执行，以提高因子生成效率。

使用前准备

在使用研报分析和因子衍生功能之前，需要配置 AI 模型和 AI 权限管理。本节重点介绍如何进行 AI 模型配置，关于 AI 权限管理的说明参见系统管理 → AI 权限配置页面。

管理员还需提前配置并保存任务所需的数据源映射。配置入口为系统管理 → AI 权限管理 → 数据源映射；具体步骤参见“系统管理”的数据源映射。

研报分析与衍生因子功能在执行过程中所使用的 AI 模型，默认为当前用户在 AI 助手中配置的默认模型。

创建研报分析任务时支持选择 AI 模型。在使用研报分析或衍生因子功能之前，请先完成以下准备工作：

进入 AI 助手页面，点击设置 → 模型配置
确认当前账号下已配置可用的 AI 模型
将期望使用的模型设置为默认模型

若未提前设置默认模型，研报分析与衍生因子任务可能会使用非预期的模型执行，或因缺少默认模型配置而无法正常运行。

建议在首次使用相关功能前，务必完成默认模型的确认与设置。

创建任务

点击研报分析助手的下拉列表的“创建任务”，进入研报分析任务创建页面。用户可在该页面完成研报上传、因子解析、数据源配置及任务参数设置等操作。

在研报分析创建任务页面的右下角展示了当前登录用户的 AI 权限使用情况及上限。

研报上传

在创建任务页面中，用户需首先上传研报文件。

支持上传 PDF 格式研报文件
支持自定义研报任务名称
上传完成后，系统会在研报预览区域自动解析并展示 PDF 中的文字内容

用户可根据实际研究需求，对解析出的文本内容进行以下操作：

对文本进行增删或修改
编辑当前任务的任务名称，以便在任务列表中进行区分和管理

因子解析

点击 “因子解析” 按钮后，研报分析助手将基于研报内容自动解析潜在因子。

因子列表如上图所示，若自动解析得到的因子完整且符合研究需求，可直接使用；若存在遗漏或不符合研究目标的情况，可点击右上角的“添加因子”补充因子。

输入因子名称与对应的因子描述，即可补充因子。

在补充因子时，需要输入因子名称及对应的因子描述。通过自动解析与手动补充相结合的方式，可确保因子定义更加准确和完整。

数据源与字段配置

创建任务前，确认所需数据已经配置为可用的数据源映射。研报 Agent 在配置的映射范围内解析因子的数据需求。

完成研报因子解析后，若因子列表中至少包含一个因子，页面会显示“更多配置”区域。

在创建任务 → 更多配置 → 数据设置中，选择因子评价数据的获取方式。

不勾选“人工覆盖评价数据”：默认使用研报助手针对因子分析得到的评价数据源。
勾选“人工覆盖评价数据”：选择已保存的因子评价数据源映射，检查并按需调整评价价格列。评价数据应与因子的资产、频率及时间范围匹配。

启用知识库（RAG）增强分析能力（可选）

可选择知识库，引入 RAG（检索增强生成）机制，以提升因子生成和代码修复效果。选择知识库后，系统将在任务执行过程中自动应用以下增强策略：

因子解释增强

在生成因子解释后，系统将因子解释文本作为输入，在知识库中检索相似的因子实现说明。检索结果将作为上下文，参与首次代码生成的提示词构造。

代码错误修复增强

当代码生成过程中出现错误时，系统将使用错误信息在知识库中进行检索，获取可能的解决方案，作为上下文传入下一轮代码生成提示词。

因子结果入库（可选）

本节入库对象为因子计算结果数据。若需将生成的代码保存为私有因子，请在任务详情中使用“存入草稿”和“保存到因子库”；两项功能分别配置和操作。

用户可选择是否将运行成功的因子结果写入数据库。若启用结果入库，需指定目标数据库表，并确保表结构满足以下字段要求：


字段名	字段类型
securityId	SYMBOL / STRING
tradeTime	TIMESTAMP
factorName	STRING
value	DOUBLE
updateTime	TIMESTAMP
username	SYMBOL / STRING

以下展示了使用复合分区建表的示例。同时按两个维度进行数据分区：时间维度（按研报任务成功时间的月份）和业务维度（按因子名称）。

db1 =database(, partitionType = VALUE, partitionScheme =[2025.01M]);
db2 =database(, partitionType = VALUE, partitionScheme =["factor1"]);
database(directory = 'dfs://factorFromReports', partitionType = COMPO, partitionScheme = [db1,db2], engine= `OLAP)

createPartitionedTable(dbHandle = database('dfs://factorFromReports'),table = table(1:0, ["securityId","tradeTime","factorName","value","updateTime","username"],["SYMBOL","TIMESTAMP","STRING","DOUBLE","TIMESTAMP","STRING"]),tableName = 'result',partitionColumns =["updateTime","factorName"])

这种分区方式适用于按任务执行时间检查结果或按因子名称进行因子级别管理的场景。

若业务场景更偏向于按行情时间或按任务创建人查询数据，可根据实际需求选择其他分区方案。

启用衍生因子（可选）

对于当前创建的研报因子任务，用户可选择是否启用衍生因子功能。

启用后，当研报因子任务成功完成时，系统将自动触发衍生因子任务的创建。用户可根据自身的 AI 权限配置，设置衍生因子的生成轮数。

每一轮衍生因子均基于上一轮生成结果进行推导，从而逐步生成新的因子。

参考衍生因子章节了解更多信息。

任务列表

在任务列表中，用户可查看研报分析任务及其对应因子任务的运行状态。

任务状态用于反映当前因子任务所处的执行阶段。无论任务处于何种状态，用户均可点击因子名称进入任务详情页面，查看以下信息：

从研报中解析得到的因子解释
因子公式
自动生成的运行代码
代码生成与迭代过程记录

Agent 工作区

在因子任务详情中展开“Agent 工作区”，查看以下内容：


页签	用途
工作区状态	查看任务状态、最近错误、检查结果和重试次数。
因子定义	查看因子定义和计算要求，核对研报公式及含义。
数据参数	查看语义字段与真实字段的映射，以及多数据源关联关系。
因子代码	查看当前有效代码。
代码历史	查看代码版本变化。
Agent 上下文	查看任务过程消息及相关工具、Skill 调用。

图中的重试次数仅为该任务的运行记录。

工作区集中保存因子定义、数据参数、代码和流程状态。任务恢复时可据此识别已生成的有效产物；排查问题时，应结合最近错误和检查结果定位需要修正的阶段。

结果检查与问题定位

因子代码执行成功后，Result Checker 对工作区中的因子定义、数据映射、数据关系、数据准备和代码实现进行只读静态验收，检查它们是否一致地描述和实现了同一个因子。

检查覆盖完整性、一致性、可行性、数据合理性、计算正确性、规范性及可解释性。只有通过执行检查和静态验收，因子生成结果才能通过该质量检查环节；后续因子评价仍需单独完成。

检查不通过时，系统提供需要回退修正的最早阶段。字段缺失或映射不正确时，应先检查数据配置；公式或窗口设置不一致时，应检查因子定义及实现。

系统通过重试上限、AI 异常上限和重复工具调用限制控制无效循环。达到限制后，应根据工作区反馈处理问题；不应仅重复重启或只修改最后一次代码。

静态验收通过表示通过平台检查，不保证完全复现研报结论，也不保证因子具有预测能力。用户仍需核对经济含义、数据口径和评价结果。

因子任务状态

每一个因子任务在执行过程中可能处于以下状态。不同状态下，系统支持的操作有所不同。

运行中：因子任务正在运行中。支持查看因子公式、因子解释、因子代码运行记录等详情。
中断：因子任务被用户手动暂停。支持查看因子公式、因子解释、因子代码运行记录等详情，也支持编辑当前代码并重新启动任务。
失败：因子任务在生成阶段失败，通常为 AI 请求失败。可能原因包括达到最大重试次数限制等。支持查看已成功生成的部分记录。
生成评价中：系统已完成因子生成，正在进入因子评价阶段。支持查看因子假设、因子公式、因子解释、因子代码的运行记录、最终结论等任务详情。
因子函数生成失败：在因子评价任务中发现因子函数未能成功运行。支持查看因子假设、因子公式、因子解释、因子代码的运行记录、最终结论等任务详情。可以重启因子任务（状态将变更为“运行中”）；也支持修改最后一次生成的代码并重新启动任务。
评价任务失败：因子评价阶段运行失败。通常发生在执行 alphalens 评价过程中，常见原因包括：因子值为空、因子表字段不符合要求、评价数据源与因子表时间不匹配、因子分组失败等。支持查看因子假设、因子公式、因子解释、因子代码的运行记录、最终结论等任务详情。支持修改最后一次生成的代码并重新启动任务。
成功：因子生成结果已通过执行检查和 Result Checker 静态验收，且因子评价已完成。支持查看因子假设、因子公式、因子解释、因子代码的运行记录、因子评价结果、创建衍生因子等。

任务结果

当因子任务全部执行完成后，任务列表中的状态栏将展示最终执行结果。

成功：表示因子生成结果已通过执行检查和 Result Checker 静态验收，且因子评价已完成。系统将返回最终可用的因子代码，并给出评价结论，同时以可视化方式展示因子评价结果。
评价任务失败 / 因子函数生成失败：造成失败的原因通常有以下几点：
- 数据源缺失
- 因子定义不清晰
- 字段配置不匹配
用户可进入任务详情页面，点击查看错误信息，获取具体报错内容并进行针对性调整。

代码调整

在因子任务运行过程中，如用户在任务详情页面中发现自动生成的代码仍存在优化空间，可进行人工干预，具体操作包括：

手动暂停当前因子任务
对自动生成的代码进行修改
提交修改并重新启动任务

该机制为研究人员提供了灵活的调整能力。在实际应用中，当研究人员基于专业经验判断生成的代码需要优化时，可及时进行干预，从而提升因子评价结果的可靠性和研报分析的整体质量。

保存因子代码草稿

在任务详情中，点击代码运行历史右侧的“存入草稿”，或点击页面右下角的草稿入口。
首次使用时，在“关联因子库草稿”弹窗中填写因子名称，并按需填写注释、属性和标签，点击“创建”。
在研报代码草稿中检查、编辑或粘贴因子代码，再点击“保存到因子库”。
看到保存成功提示后，进入因子与评价 → 我的因子，查看并继续管理、测试和使用对应私有因子。