# 本地数据与研究任务

[English](https://github.com/hongchanho93/tradeflow-lite/blob/main/docs/en/data-and-tasks.md) · [首页](https://github.com/hongchanho93/tradeflow-lite/blob/main/README.zh-CN.md) · [示例](https://github.com/hongchanho93/tradeflow-lite/blob/main/docs/zh-CN/examples.md)

## 选择自己的数据

打开 **AI → 设置 → 我的数据 → 添加我的数据**，在系统窗口中选择最小相关目录。聊天里的路径不能产生目录授权。不要选择源码仓库、整个用户目录或包含无关凭证的文件夹。

`.tfc` 连接器把所选目录中的文件转换为应用的品种/历史数据合同。通过数据卡片**更多 → 导入接入文件**检查候选文件，小样本验证通过后安装；也可以选择**让 AI 接入**，按钮只准备消息，是否发送由你决定。

文件留在原处，连接器只读访问。停用会停止相关工作并撤下动态查询工具；删除只移除登记和连接器，不删除原始文件。目录移动或被替换后，需要重新明确选择，不会悄悄信任旧路径下的新目录。

## CSV、SQLite 与 Parquet

CSV 通过受控字节/文本接口读取。随仓库的例子使用 `time,open,high,low,close,volume`、Unix 秒、日线不复权，以及 `SH_600000.csv` 这类文件名。这些只是示例假设，不要求你的数据遵循相同名称或格式。连接器应适配实际列名、时间和价量单位，不能编造缺失价格或将未知成交量补零。

SQLite 使用原生只读接口，要求稳定的**非 WAL 快照**；带活动 WAL 的在线数据库不是受支持的一致输入，应通过数据库自身的流程准备正确快照。Parquet 支持原生结构检查及已支持的扁平、非重复列投影读取。实际类型和编码先用样本验证，不代表普遍支持嵌套/重复结构。精确整数、时间单位与有损转换必须明确处理。

Arrow IPC、任意解压、远程服务凭证管理和通用数据库导入器尚未实现。支持 CSV、SQLite、Parquet 不代表也支持上述功能。编写连接器前，先用 `tf_data_guide` 读取运行中的接口，再用 `tf_data_sample` 检查对应格式的样本。

验证只检查语法/声明与少量目录、历史样本，不认证整份数据质量。错误提供 `stage`、`errorCode`，可定位时包含 `path/reason/expected` 及清洗后的 `failureDetail`。`listSymbols` 必须遵守 `query.limit`。明确不支持的历史格式可以准确返回 `{unsupported:'lowercase_reason_code'}`，正式报告为 `data_history_unsupported`，不伪装成空历史；代码崩溃或坏输出仍然验证失败。

## 告诉 AI 要计算什么

在 AI 对话中说明数据源、品种范围、周期、复权、数据窗口、计算方法和输出。已有 `.tft` 时，把完整文本提供给助手；不要假定业务 MCP 可以直接读取应用仓库里的文件。可参考[随仓库的示例](https://github.com/hongchanho93/tradeflow-lite/blob/main/examples/user-research/README.zh-CN.md)。

助手先读 `tf_task_guide`，生成完整 `.tft`，调用 `tf_task_validate` 后，通过 `tf_task_start` 小范围试跑。验证本身不执行计算。使用 `tf_task_wait` 本地等待，避免反复通过模型高频轮询；成功后核对 `tf_task_status`、`tf_task_page`，再扩大范围或保存定义。

一个任务使用一个明确数据源，按品种处理实际返回的窗口。品种范围可来自目录、自选、明确列表或上次结果的候选列表。用户连接器可作为 Task 输入，但不会自动成为内置行情 Provider，也不会替换前台图表。打开对应内置源的图表，可能看到不同数据。

Task ID、表格列 ID 等必须遵守指南中的小写标识规则，例如 `last_close`，不要写 `lastClose`。按 `path/reason/expected` 修正错误，不要改动无关字段。

## 正确理解结果

结果可以是表格、品种列表、序列或报告。核对已处理、跳过、失败、短窗口数量，以及时间、覆盖与收盘状态。执行完成不证明数据最新、完整历史、覆盖全市场，更不证明策略可以真实成交。

CSV 参考连接器按最早到最新分页，首窗口可能是最早的数据，不是最近 N 根。当前任务不会自动读完每个品种全部历史分页。完整历史回测必须另行核对输入范围与成交假设。

`tf_task_page` 中，Table/SymbolList/Series 的 `pageUnit='rows'`，Report 的 `pageUnit='characters'`。始终检查 `complete`、`nextOffset`；五个报告字符不是五行。解析 `rowsJson` 后保留表格结构，部分分页不能被描述成完整查询结果。

## 保存、复用与停止

可以让 AI 把结果保存到桌面、文档或下载目录。表格通常用 CSV，报告通常用 Markdown，也支持 TXT、JSON。`tf_result_save_file` 可以直接导出完整任务结果，不必将每行先传给模型。它只创建新文件，重名会生成新名称，不覆盖原始文件；成功回执后才能说已保存。

“保存为工具”保存的是已经验证并成功运行的 `.tft` 定义，不是结果数据。工具进入内置 AI 和 MCP 共用的目录。重启只恢复定义，不自动执行；复用、修改、删除时以任务库提供的当前名称和版本为准。

结果只存在应用内存，并归属具体会话。重启或释放会话可能移除结果，需要永久保留时必须导出；保存定义不等于永久结果数据库。AI 读取的结果分页可能发送给所选服务，因此本地计算不等于外部模型绝对看不到数据。

手动切图不会取消独立任务。可以让 AI 停止，但取消可能需要等待原生读取真正退出。停用、替换或删除连接器会取消旧连接上的工作。取消不能收回已发送给模型的数据，也不能撤销已经保存的文件。

这是用户自有研究运行时，不是官方选股器、全历史成交模拟器或交易账户。无限历史流、实时任务订阅和永久结果库尚未内置。资源预算用于保证响应，不是付费等级，也不能证明策略有效。