API 参考

DataHand 提供 Python API、命令行与 Web 三种使用方式。本文档以 Python API 为主。

DataHandAgent

核心入口类。

初始化

from datahand import DataHandAgent

agent = DataHandAgent(
    model="deepseek-chat",    # 模型名
    local=False,              # True=本地模型，False=云端
    api_key="sk-xxx",         # 云端模型需要
    ollama_host="http://localhost:11434",  # 本地模型地址
    verbose=False,            # 是否打印详细日志
)

对话

方法	说明
`agent.chat(message, use_llm=None)`	自然语言交互，返回 `Response`；`use_llm=False` 强制走规则引擎
`agent.llm_available`	模型是否可用（属性）
`agent.reset()`	重置会话（保留脚本与技能）

数据加载

方法	说明
`load_file(path, auto_header=True)`	加载单个文件（自动检测表头行）
`load_files([path, ...])`	加载多个文件
`load_excel_sheets(path)`	加载一个 Excel 的所有工作表
`load_files_deep([path, ...])`	深度加载：自动识别每个文件的所有 Sheet
`list_tables()`	列出所有已加载的表（含行列数与当前标记）
`use_table(name)`	切换当前表
`remove_table(name)`	移除表

# 深度加载：多文件 × 多 Sheet 全识别
tables = agent.load_files_deep(["a.xlsx", "b.xlsx"])
for t in tables:
    print(t["name"], t["rows"], t["columns"])

# 切换当前表
agent.use_table("a::Sheet2")

多表对比与跨表处理

# 对比多个表
cmp = agent.compare_tables(["表A", "表B"])     # 返回 DataFrame
diff = agent.table_columns_diff(["表A", "表B"])  # 字段交集/差集

# 跨表合并
agent.merge_tables("表A,表B", how="auto")     # 智能识别关联键
agent.merge_tables("表A,表B", how="concat")   # 纵向拼接
agent.merge_tables("表A,表B", how="left", key="客户ID")  # 左连接

分析与洞察

智能数据洞察

# 完整洞察（dict）
insight = agent.auto_insights()
print(insight["overview"])       # 数据概览
print(insight["metrics"])        # 关键指标
print(insight["correlations"])   # 强相关字段
print(insight["trend"])          # 时间趋势
print(insight["suggestions"])    # 行动建议

# 文本格式报告
print(agent.insights_text())

数据质量

# 审计 + 记录历史
score = agent.audit_quality(record_history=True)
print(score["score"], score["grade"], score["summary"])

# 颜色标注 Excel
agent.auditor.annotate_excel("标注.xlsx")

# 问题明细
issues = agent.auditor.find_issues()

# 历史分析
agent.quality_history_summary()      # 摘要
agent.quality_history_by_category()  # 按类别
agent.quality_history_by_month()     # 按月
agent.quality_history_by_year()      # 按年
agent.generate_quality_report("历史报告.xlsx")

算法增强

# 机器学习异常检测
agent.algo_tools.detect_outliers_ml(method="IForest", contamination=0.05)

# 数据集对比报告（HTML 可视化）
agent.algo_tools.compare_datasets_report("表A", "表B")

# 清洗增强
agent.algo_tools.clean_column_names()
agent.algo_tools.remove_constant_columns()

报告导出

# 按需生成（默认仅 excel）
result = agent.export_report_suite(
    title="销售分析报告",
    formats=["excel", "ppt", "word"],   # 可选：excel / ppt / word
    open_result=True,                    # 生成后自动打开
)
print(result["files"])

# HTML 数据看板
agent.export_dashboard(title="数据驾驶舱", theme="dark", open_result=True)

# 保存处理结果（自动归档到知识库）
agent.chat("保存到 output/结果.xlsx")

版本管理

查看版本、管理快照与回滚。

方法 / 属性	说明
`agent.version.current_version`	当前版本号（如 "1.0.0"）
`agent.version.history()`	版本历史列表
`agent.version.bump(level, note)`	升版本（level: major/minor/patch）
`agent.create_snapshot(name, note="")`	创建数据快照
`agent.list_snapshots()`	列出所有快照
`agent.rollback(snapshot_id)`	回滚到指定快照
`agent.version_info()`	版本信息汇总（dict）

# 查看版本
print(agent.version.current_version)   # "1.0.0"
for v in agent.version.history():
    print(v["version"], v["time"], v["note"])

# 处理前创建快照
agent.create_snapshot("清洗前", note="保留原始数据")

# 执行操作
agent.chat("清洗数据")

# 不满意 → 回滚
snaps = agent.list_snapshots()
agent.rollback(snaps[0]["id"])
print("已回滚，当前形状:", agent.ctx.df.shape)

# 升版本（发版时）
agent.version.bump("minor", note="新增智能洞察")

自动快照：执行清洗、合并等破坏性操作前会自动创建快照。快照保存在 ~/.datahand/versions/snapshots/，默认保留最近 20 个。

数据知识库

方法	说明
`knowledge_base_files(source, limit, order)`	列出文件（source: upload/output；order: desc/asc）
`knowledge_base_stats()`	统计（文件数、总大小）
`knowledge_base_search(keyword)`	关键词搜索
`knowledge_base_deduplicate()`	内容去重，返回删除数

记忆与技能

# 3 层记忆
agent.habit_summary()        # L2 工作习惯画像
agent.recent_operations(20)  # 最近操作
agent.list_skills()          # L3 已沉淀技能
agent.delete_skill(name)     # 删除技能

# 脚本管理
agent.save_script("名称", code, "描述")
agent.run_script("名称", "新数据.xlsx")   # 离线复用，零 Token
agent.list_scripts()

角色管理

agent.list_roles()                                   # 列出角色
agent.save_role("风控分析师", "金融", "风控", "关注风险指标")  # 创建
agent.delete_role("风控分析师")                        # 删除

命令行

# 交互模式
python -m datahand.cli

# 加载文件并执行一条指令
python -m datahand.cli -f 销售数据.xlsx -q "按 部门 统计 销售额"

# 指定本地模型
python -m datahand.cli -f data.xlsx --local -m qwen2.5:7b

# 禁用模型，仅用规则引擎
python -m datahand.cli -f data.xlsx --no-llm

# 查看版本
python -m datahand --version

交互模式命令

命令	说明
`/load <路径>`	加载文件
`/files`	列出已加载的表
`/columns`	显示字段
`/info`	数据概况
`/preview [n]`	预览前 n 行
`/use <表名>`	切换当前表
`/snapshot <名称>`	创建快照
`/rollback <id>`	回滚到快照
`/scripts` / `/run <名>`	脚本列表 / 运行脚本
`/reset` / `/help` / `/quit`	重置 / 帮助 / 退出

数据结构

# 上下文（所有工具共享）
agent.ctx.df           # 当前 DataFrame
agent.ctx.dataframes   # {表名: DataFrame} 所有已加载的表
agent.ctx.current_file # 当前表名
agent.ctx.charts       # 生成的图表路径

# 响应对象
resp = agent.chat("按部门统计销售额")
print(resp.content)    # 文本结果
print(resp.data)       # 处理后的 DataFrame
resp.save("结果.xlsx") # 保存
resp.charts            # 本次生成的图表