@axiom-lattice/examples-deep_research 1.0.14 → 1.0.16

package/src/agents/data_agent/skills/data-visualization.ts

@@ -0,0 +1,77 @@
+export const dataVisualization = {
+  name: "data-visualization",
+  description:
+    "为数据分析结果选择合适的图表类型并生成 ECharts 配置。适用于需要将查询结果可视化为柱状图、折线图、饼图、散点图等图表的场景。",
+  prompt: `## 图表类型选择指南
+
+根据数据特征和业务问题选择最合适的图表类型：
+
+- **柱状图** (bar): 比较类别或时间周期
+  - 使用 category xAxis，value yAxis
+  - 多系列用于分组/堆叠柱状图
+  
+- **折线图** (line): 展示时间趋势
+  - 使用 category/time xAxis，value yAxis
+  - 多系列展示多个指标
+  
+- **饼图** (pie): 展示构成/百分比
+  - 无需 xAxis/yAxis
+  - 数据格式: [{value: number, name: string}, ...]
+  - 使用 radius: ["40%", "70%"] 创建环形图
+  
+- **散点图** (scatter): 相关性分析
+  - 使用 value xAxis 和 value yAxis
+  - 数据格式: [[x, y], [x, y], ...]
+  
+- **热力图** (heatmap): 多维数据
+  - 需要 category xAxis 和 yAxis
+  - 数据格式: [[xIndex, yIndex, value], ...]
+
+## ECharts 配置要求
+
+生成完整的 ECharts 配置，必须包含：
+
+\`\`\`json
+{
+  "table": [...],  // 原始数据表格
+  "echarts": {
+    "title": {"text": "清晰的图表标题"},
+    "tooltip": {
+      "trigger": "axis",  // bar/line 用 "axis", pie/scatter 用 "item"
+      "formatter": "..."  // 可选：自定义格式化
+    },
+    "legend": {...},  // 多系列时必需
+    "xAxis": {
+      "type": "category",  // 或 "time", "value"
+      "name": "X轴名称",
+      "data": [...]  // category 类型时必需
+    },
+    "yAxis": {
+      "type": "value",
+      "name": "Y轴名称"
+    },
+    "series": [{
+      "type": "bar|line|pie|scatter|heatmap",
+      "name": "系列名称",
+      "data": [...],
+      "label": {...}  // 可选：显示数值
+    }],
+    "grid": {...}  // 可选：控制边距
+  }
+}
+\`\`\`
+
+## 最佳实践
+
+- 图表标题清晰描述业务问题
+- 轴标签使用业务术语，而非技术字段名
+- 数值格式化：百分比、货币、千分位
+- 时间序列使用 "xAxis.type: 'time'" 并正确格式化日期
+- 多系列时使用 legend 区分
+- 重要数值在图表上直接标注（series.label）
+
+## 输出格式
+
+提供完整的 chart JSON 配置，可直接用于渲染。
+`,
+};

package/src/agents/data_agent/skills/infographic-creator.ts

@@ -0,0 +1,344 @@
+export const infographicCreator = {
+    name: "infographic-creator",
+    description:
+        "创建信息图表，将数据可视化为易于理解的图表。适用于需要将数据可视化为易于理解的图表的场景。",
+    prompt: `
+  
+  信息图（Infographic）将数据、信息与知识转化为可感知的视觉语言。它结合视觉设计与数据可视化，用直观符号压缩复杂信息，帮助受众快速理解并记住要点。
+
+Infographic = Information Structure + Visual Expression
+
+本任务使用 AntV Infographic 创建可视化信息图。
+
+在开始任务前，需要理解 AntV Infographic 语法规范，包括模板列表、数据结构、主题等。
+
+规范
+AntV Infographic 语法
+AntV Infographic 语法是一种自定义的 DSL，用于描述信息图渲染配置。它使用缩进描述信息，具有较强鲁棒性，便于 AI 流式输出并渲染信息图。主要包含以下信息：
+
+template：用模板表达文字信息结构。
+data：信息图数据，包含 title、desc、数据项等。数据项通常包含 label、desc、icon 等字段。
+theme：主题包含 palette、font 等样式配置。
+例如：
+
+\`\`\`infographic
+infographic list-row-horizontal-icon-arrow
+data
+  title Title
+  desc Description
+  lists
+    - label Label
+      value 12.5
+      desc Explanation
+      icon document text
+theme
+  palette #3b82f6 #8b5cf6 #f97316
+\`\`\`
+语法规范
+第一行必须是 infographic <template-name>，模板从下方列表中选择（见“可用模板”部分）。
+
+使用 data / theme 块，块内用两个空格缩进。
+
+键值对使用「键 空格 值」；数组使用 - 作为条目前缀。
+
+icon 使用图标关键词（如 star fill）。
+
+data 应包含 title/desc + 模板对应的主数据字段（不一定是 items）。
+
+主数据字段选择（只用一个，避免混用）：
+
+list-* → lists
+sequence-* → sequences（可选 order asc|desc）
+compare-* → compares（支持 children 分组对比），可包含多个对比项
+hierarchy-structure → items（每一项对应一个独立层级，每一层级可以包含子项，最多可嵌套 3 层）
+hierarchy-* → 单一 root（树结构，通过 children 嵌套）；
+relation-* → nodes + relations；简单关系图可省略 nodes，在 relations 中用箭头语法
+chart-* → values（数值统计，可选 category）
+不确定时再用 items 兜底
+compare-binary-* / compare-hierarchy-left-right-* 二元模板：必须两个根节点，所有对比项挂在这两个根节点的 children
+
+hierarchy-*：使用单一 root，通过 children 嵌套（不要重复 root）
+
+theme 用于自定义主题（palette、font 等） 例如：暗色主题 + 自定义配色
+
+\`\`\`infographic
+infographic list-row-simple-horizontal-arrow
+theme dark
+  palette
+    - #61DDAA
+    - #F6BD16
+    - #F08BB4
+\`\`\`
+使用 theme.base.text.font-family 指定字体，如手写风格 851tegakizatsu
+
+使用 theme.stylize 选择内置风格并传参 常见风格：
+
+rough：手绘效果
+pattern：图案填充
+linear-gradient / radial-gradient：线性/径向渐变
+例如：手绘风格（rough）
+
+\`\`\`infographic
+infographic list-row-simple-horizontal-arrow
+theme
+  stylize rough
+  base
+    text
+      font-family 851tegakizatsu
+\`\`\`
+输出格式要求：
+必须使用 Markdown 代码块格式输出，语言标识为 infographic。格式如下：
+
+\`\`\`infographic
+infographic <template-name>
+data
+  ...
+theme
+  ...
+\`\`\`
+
+禁止输出纯文本、JSON、HTML、JS 代码或其他格式。只能输出上述格式的 Markdown 代码块。
+
+数据语法示例
+按模板类别的数据语法示例（使用对应字段，避免同时添加 items）：
+
+list-* 模版
+\`\`\`infographic
+infographic list-grid-badge-card
+data
+  title Feature List
+  lists
+    - label Fast
+      icon flash fast
+    - label Secure
+      icon secure shield check
+\`\`\`
+sequence-* 模版
+\`\`\`infographic
+infographic sequence-steps-simple
+data
+  sequences
+    - label Step 1
+    - label Step 2
+    - label Step 3
+  order asc
+\`\`\`
+hierarchy-* 模版
+\`\`\`infographic
+infographic hierarchy-structure
+data
+  root
+    label Company
+    children
+      - label Dept A
+      - label Dept B
+\`\`\`
+compare-* 模版
+\`\`\`infographic
+infographic compare-swot
+data
+  compares
+    - label Strengths
+      children
+        - label Strong brand
+        - label Loyal users
+    - label Weaknesses
+      children
+        - label High cost
+        - label Slow release
+\`\`\`
+四象限图
+
+\`\`\`infographic
+infographic compare-quadrant-quarter-simple-card
+data
+  compares
+    - label High Impact & Low Effort
+    - label High Impact & High Effort
+    - label Low Impact & Low Effort
+    - label Low Impact & High Effort
+\`\`\`
+chart-* 模版
+\`\`\`infographic
+infographic chart-column-simple
+data
+  values
+    - label Visits
+      value 1280
+    - label Conversion
+      value 12.4
+\`\`\`
+relation-* 模版
+边标签写法：A -label-> B 或 A -->|label| B
+
+\`\`\`infographic
+infographic relation-dagre-flow-tb-simple-circle-node
+data
+  nodes
+    - id A
+      label Node A
+    - id B
+      label Node B
+  relations
+    A - approves -> B
+    A -->|blocks| B
+\`\`\`
+兜底 items 示例
+\`\`\`infographic
+infographic list-row-horizontal-icon-arrow
+data
+  items
+    - label Item A
+      desc Description
+      icon sun
+    - label Item B
+      desc Description
+      icon moon
+\`\`\`
+可用模板
+chart-bar-plain-text
+chart-column-simple
+chart-line-plain-text
+chart-pie-compact-card
+chart-pie-donut-pill-badge
+chart-pie-donut-plain-text
+chart-pie-plain-text
+chart-wordcloud
+compare-binary-horizontal-badge-card-arrow
+compare-binary-horizontal-simple-fold
+compare-binary-horizontal-underline-text-vs
+compare-hierarchy-left-right-circle-node-pill-badge
+compare-quadrant-quarter-circular
+compare-quadrant-quarter-simple-card
+compare-swot
+hierarchy-mindmap-branch-gradient-capsule-item
+hierarchy-mindmap-level-gradient-compact-card
+hierarchy-structure
+hierarchy-tree-curved-line-rounded-rect-node
+hierarchy-tree-tech-style-badge-card
+hierarchy-tree-tech-style-capsule-item
+list-column-done-list
+list-column-simple-vertical-arrow
+list-column-vertical-icon-arrow
+list-grid-badge-card
+list-grid-candy-card-lite
+list-grid-ribbon-card
+list-row-horizontal-icon-arrow
+list-sector-plain-text
+list-zigzag-down-compact-card
+list-zigzag-down-simple
+list-zigzag-up-compact-card
+list-zigzag-up-simple
+relation-dagre-flow-tb-animated-badge-card
+relation-dagre-flow-tb-animated-simple-circle-node
+relation-dagre-flow-tb-badge-card
+relation-dagre-flow-tb-simple-circle-node
+sequence-ascending-stairs-3d-underline-text
+sequence-ascending-steps
+sequence-circular-simple
+sequence-color-snake-steps-horizontal-icon-line
+sequence-cylinders-3d-simple
+sequence-filter-mesh-simple
+sequence-funnel-simple
+sequence-horizontal-zigzag-underline-text
+sequence-mountain-underline-text
+sequence-pyramid-simple
+sequence-roadmap-vertical-plain-text
+sequence-roadmap-vertical-simple
+sequence-snake-steps-compact-card
+sequence-snake-steps-simple
+sequence-snake-steps-underline-text
+sequence-stairs-front-compact-card
+sequence-stairs-front-pill-badge
+sequence-timeline-rounded-rect-node
+sequence-timeline-simple
+sequence-zigzag-pucks-3d-simple
+sequence-zigzag-steps-underline-text
+模板选择建议：
+
+严格顺序（流程/步骤/发展趋势）→ sequence-*
+时间线 → sequence-timeline-*
+阶梯图 → sequence-stairs-*
+路线图 → sequence-roadmap-vertical-*
+折线路径 → sequence-zigzag-*
+环形进度 → sequence-circular-simple
+彩色蛇形步骤 → sequence-color-snake-steps-*
+金字塔 → sequence-pyramid-simple
+观点列举 → list-row-* 或 list-column-*
+二元对比（利弊）→ compare-binary-*
+SWOT → compare-swot
+层级结构（树图）→ hierarchy-tree-*
+数据图表 → chart-*
+象限分析 → quadrant-*
+网格列表（要点）→ list-grid-*
+关系展示 → relation-*
+词云 → chart-wordcloud
+思维导图 → hierarchy-mindmap-*
+示例
+绘制互联网技术演进信息图
+
+\`\`\`infographic
+infographic list-row-horizontal-icon-arrow
+data
+  title Internet Technology Evolution
+  desc From Web 1.0 to AI era, key milestones
+  lists
+    - time 1991
+      label Web 1.0
+      desc Tim Berners-Lee published the first website, opening the Internet era
+      icon web
+    - time 2004
+      label Web 2.0
+      desc Social media and user-generated content become mainstream
+      icon account multiple
+    - time 2007
+      label Mobile
+      desc iPhone released, smartphone changes the world
+      icon cellphone
+    - time 2015
+      label Cloud Native
+      desc Containerization and microservices architecture are widely used
+      icon cloud
+    - time 2020
+      label Low Code
+      desc Visual development lowers the technology threshold
+      icon application brackets
+    - time 2023
+      label AI Large Model
+      desc ChatGPT ignites the generative AI revolution
+      icon brain
+\`\`\`
+生成流程
+第一步：理解用户需求
+在创建信息图之前，先理解用户需求与想表达的信息，以便确定模板和数据结构。
+
+若用户提供清晰的内容描述，应将其拆解为清晰、简洁的结构。
+
+否则需要向用户澄清（如：“请提供清晰简洁的内容描述。”、“你希望使用哪个模板？”）
+
+提取关键信息结构（title、desc、items 等）。
+明确所需数据字段（title、desc、items、label、value、icon 等）。
+选择合适模板。
+使用 AntV Infographic 语法描述信息图内容，并以 Markdown 代码块格式输出，语言标识为 infographic。
+
+输出格式示例：
+\`\`\`infographic
+infographic <template-name>
+data
+  title ...
+  desc ...
+  ...
+theme
+  ...
+\`\`\`
+
+关键注意：
+1. 必须尊重用户输入的语言。例如用户输入中文，则语法中的文本也必须是中文。
+2. 必须使用 Markdown 代码块格式，语言标识为 infographic，而不是 HTML、JS 或其他代码格式。
+3. 代码块内只包含 AntV Infographic DSL 语法，不要包含任何解释性文字。
+
+
+
+
+  `,
+};

package/src/agents/data_agent/skills/notebook-report.ts

@@ -0,0 +1,82 @@
+export const notebookReport = {
+  name: "notebook-report",
+  description:
+    "生成笔记本风格的数据分析报告，包含执行摘要、分析步骤（SQL、可视化、洞察）和结论。适用于需要将多步骤分析整合为完整、可复现的分析报告的场景。",
+  prompt: `
+  如何可视化数据，请通过data-visualization技能了解。
+  
+  ## 报告结构
+
+### 报告标题部分
+
+- **标题**：清晰、描述性的分析标题
+- **上下文**：简要介绍分析内容和原因
+- **数据源**：数据库信息和时间周期
+- **执行摘要**：所有关键发现的高级摘要（2-3 段）
+
+### 分析步骤（笔记本单元格）
+
+每个分析步骤是一个完整的单元格，包含：
+
+\`\`\`markdown
+## 步骤 [N]：[步骤标题]
+
+### 问题 / 目标
+[此步骤要回答的业务问题，来自 topic_[sub_topic_name].md]
+
+### SQL 查询
+\`\`\`sql
+[完整 SQL 查询，带注释说明]
+\`\`\`
+
+### 数据可视化
+\`\`\`chart
+{
+  "table": [...],
+  "echarts": {
+    "title": {"text": "[图表标题]"},
+    "tooltip": {...},
+    "legend": {...},
+    "xAxis": {...},
+    "yAxis": {...},
+    "series": [...]
+  }
+}
+\`\`\`
+
+### 关键发现
+[来自 data-analysis-agent 的核心洞察，用业务语言表达]
+
+### 业务解释
+[这些发现对业务的意义和影响]
+
+### 建议
+[基于此分析的具体、可操作建议]
+\`\`\`
+
+### 报告结论
+
+- **所有发现的摘要**：综合所有步骤的洞察
+- **总体建议**：按优先级排序的可操作建议
+- **后续分析**：建议的下一步分析方向（如适用）
+
+## 报告编写原则
+
+- **故事性**：将分析组织成连贯的故事，而非技术报告
+- **业务聚焦**：使用业务术语，避免技术 jargon
+- **数据驱动**：将具体数值自然融入叙述
+- **可操作**：每个发现都应导向可执行的建议
+- **逻辑递进**：步骤之间要有清晰的逻辑连接
+
+## 数据来源
+
+报告应基于：
+- \`/question.md\`：原始业务问题
+- \`/topic_*.md\`：各子主题的分析结果
+- 步骤 3 的综合摘要
+
+## 输出格式
+
+生成完整的 Markdown 格式报告，包含所有分析步骤、图表配置和洞察。
+`,
+};

package/src/agents/data_agent/skills/sql-query.ts

@@ -0,0 +1,58 @@
+export const sqlQuery = {
+  name: "sql-query",
+  description:
+    "生成和执行 SQL 查询以检索业务数据。适用于需要从数据库获取数据、探索表结构、验证查询正确性的场景。委托给 sql-builder-agent 执行。",
+  prompt: `## 委托给 sql-builder-agent
+
+所有 SQL 相关操作都委托给 sql-builder-agent 子代理执行。
+
+## 数据库模式探索
+
+**请求模式信息**：
+- "请列出数据库中所有可用的表"
+- "请显示表 [X] 的模式，包括列、数据类型和关系"
+
+**检查现有文档**：
+- 先读取 \`/db_schema.md\`（如存在）
+- 仅在需要时请求新的模式探索
+
+## 查询生成与执行
+
+**提供清晰的业务需求**：
+1. **业务问题**：明确要回答的问题
+2. **指标**：需要计算的业务指标（收入、订单数、转化率等）
+3. **维度**：分组维度（地区、渠道、产品类别等）
+4. **筛选条件**：时间范围、状态、类别等
+5. **比较需求**：同比、环比、目标对比等
+
+**请求格式示例**：
+"我需要按地区比较 2024 年第三季度与 2023 年第三季度的收入。请生成并执行 SQL 查询。"
+
+"请查询过去 6 个月每个月的订单量和平均订单金额，按渠道分组。"
+
+## 接收与验证结果
+
+sql-builder-agent 会返回：
+- **SQL 查询**：格式清晰的完整查询
+- **查询结果**：返回的数据
+- **模式信息**：使用的表结构信息
+
+**验证要点**：
+- 查询是否正确回答了业务问题
+- 数据质量（NULL 值、异常值）
+- 结果完整性（行数、时间范围）
+- 列名是否业务友好
+
+## 错误处理
+
+如遇到查询错误：
+- 分析错误信息
+- 检查表名、列名是否正确
+- 验证 JOIN 条件和数据类型
+- 请求 sql-builder-agent 修正并重新执行
+
+## 文档化
+
+将使用的 SQL 查询和结果保存到分析文档中，便于后续参考和复现。
+`,
+};

package/src/agents/data_agent/tools/load_skills.ts

@@ -0,0 +1,88 @@
+/**
+ * Load Skills Tools
+ * Tools for loading skill metadata and content
+ */
+
+import z from "zod";
+import { registerToolLattice } from "@axiom-lattice/core";
+import * as analystSkill from "../skills/analyst";
+import * as dataVisualizationSkill from "../skills/data-visualization";
+import * as sqlQuerySkill from "../skills/sql-query";
+import * as analysisMethodologySkill from "../skills/analysis-methodology";
+import * as notebookReportSkill from "../skills/notebook-report";
+import * as infographicCreatorSkill from "../skills/infographic-creator";
+
+// Type definition for skill structure
+interface Skill {
+  name: string;
+  description: string;
+  prompt: string;
+}
+
+// Registry of all available skills
+const skillsRegistry: Record<string, Skill> = {
+  analyst: analystSkill.analyst,
+  "data-visualization": dataVisualizationSkill.dataVisualization,
+  "sql-query": sqlQuerySkill.sqlQuery,
+  "analysis-methodology": analysisMethodologySkill.analysisMethodology,
+  "notebook-report": notebookReportSkill.notebookReport,
+  "infographic-creator": infographicCreatorSkill.infographicCreator,
+};
+
+/**
+ * Load all skills and return their metadata (name and description, without prompt)
+ */
+registerToolLattice(
+  "load_skills",
+  {
+    name: "load_skills",
+    description:
+      "Load all available skills and return their metadata (name and description). This tool returns skill information without the prompt content. Use this to discover what skills are available.",
+    needUserApprove: false,
+    schema: z.object({}),
+  },
+  async (_input: Record<string, never>, _config: any) => {
+    try {
+      const skillsMeta = Object.values(skillsRegistry).map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+      }));
+
+      return JSON.stringify(skillsMeta, null, 2);
+    } catch (error) {
+      return `Error loading skills: ${error instanceof Error ? error.message : String(error)
+        }`;
+    }
+  }
+);
+
+/**
+ * Load a specific skill's content and return its prompt
+ */
+registerToolLattice(
+  "load_skill_content",
+  {
+    name: "load_skill_content",
+    description:
+      "Load a specific skill's content by name and return its prompt. Use this tool to get the full prompt content for a skill that you want to use.",
+    needUserApprove: false,
+    schema: z.object({
+      skill_name: z.string().describe("The name of the skill to load"),
+    }),
+  },
+  async (input: { skill_name: string }, _config: any) => {
+    try {
+      const skill = skillsRegistry[input.skill_name];
+
+      if (!skill) {
+        const availableSkills = Object.keys(skillsRegistry).join(", ");
+        return `Skill "${input.skill_name}" not found. Available skills: ${availableSkills}`;
+      }
+
+      return skill.prompt;
+    } catch (error) {
+      return `Error loading skill content: ${error instanceof Error ? error.message : String(error)
+        }`;
+    }
+  }
+);

package/src/index.ts

@@ -10,7 +10,11 @@ import {
 import "./agents";
 
 import path from "path";
-import { ScheduleType } from "@axiom-lattice/protocols";
+import {
+  LoggerConfig,
+  LoggerType,
+  ScheduleType,
+} from "@axiom-lattice/protocols";
 import { PostgreSQLScheduleStorage } from "@axiom-lattice/pg-stores";
 // 在文件开头添加
 const PACKAGE_VERSION = require("../package.json").version;
@@ -129,7 +133,23 @@ LatticeGateway.registerLatticeRoutes(LatticeGateway.app);
 const port = parsePort();
 console.log(`Starting server on port ${port}`);
 
+// Default logger configuration
+const DEFAULT_LOGGER_CONFIG: LoggerConfig = {
+  name: "default",
+  description: "Default logger for lattice-gateway service",
+  type: LoggerType.PINO,
+  serviceName: "lattice/deep_research",
+  loggerName: "lattice/deep_research",
+  // file: {
+  //   file: "./logs/lattice" + "/deep_research",
+  //   frequency: "daily",
+  //   mkdir: true,
+  //   maxFiles: 30,
+  // },
+};
+
 LatticeGateway.startAsHttpEndpoint({
   port,
   queueServiceConfig: { type: "memory", defaultStartPollingQueue: true },
+  loggerConfig: DEFAULT_LOGGER_CONFIG,
 });