@axiom-lattice/examples-deep_research 1.0.14 → 1.0.17

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/skills/test/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: test
+description: test1112222434441111
+metadata:
+  a: a
+  b: b
+  category: TTTT
+---
+testsetetetete

package/src/agents/index.ts

@@ -1,3 +1,4 @@
 //import "./todo";
 import "./research";
 import "./data_agent";
+import "./inventory_doctor";

package/src/agents/inventory_doctor/index.ts

@@ -0,0 +1,53 @@
+import {
+  registerAgentLattices,
+  AgentType,
+  AgentConfig,
+} from "@axiom-lattice/core";
+import z from "zod";
+import "./tools";
+
+const inventoryDoctorPrompt = `You are the Inventory Doctor Agent handling WMS pick-shortage incidents.
+
+## Mission
+- Scenario: System shows stock=5 for SKU A, picker finds 0 at location.
+- Follow Think-Act-Observe loops to diagnose and either auto-fix or dispatch physical verification.
+
+
+## Workflow
+1) Trigger: on Pick Shortage, freeze concurrent changes for the SKU/location.
+2) Data Retrieval & Triage:
+   - Check in-flight tasks (putaway/move/wave) for middle states or delays.
+   - Pull last 24h location logs; highlight unconfirmed moves or cancellations.
+   - Form hypotheses: data delay, stuck middleware, physical misplacement.
+3) Reasoning & Execution:
+   - Branch A Auto-fix: if middle-state, call retry_sync then notify picker to retry.
+   - Branch B Physical verify: push a cycle-count task to nearby operator; include candidate locations (B/C) for misplaced stock.
+   - Record every action in the report body for auditability.
+4) Reporting: return a concise Markdown case report with diagnosis, actions taken, residual risk, and training/monitoring suggestions.
+
+## Output format
+Use Markdown sections: 诊断概览 / 关键发现 / 处置动作 / 后续建议. Keep facts first, then recommendations.`;
+
+const inventoryDoctorAgent: AgentConfig = {
+  key: "inventory_doctor_agent",
+  name: "Inventory Doctor Agent",
+  description:
+    "Diagnoses pick-shortage inventory anomalies in WMS, auto-fixes data middle states, or dispatches cycle counts for physical verification, and returns an audit-friendly report.",
+  type: AgentType.DEEP_AGENT,
+  prompt: inventoryDoctorPrompt,
+  tools: [
+    "get_wms_movement_tasks",
+    "get_location_logs",
+    "retry_sync",
+    "dispatch_cycle_count",
+    "notify_picker",
+    "write_case_report",
+  ],
+  schema: z.object({
+    skuId: z.string().optional(),
+    locationId: z.string().optional(),
+    incidentId: z.string().optional(),
+  }),
+};
+
+registerAgentLattices([inventoryDoctorAgent]);

package/src/agents/inventory_doctor/tools.ts

@@ -0,0 +1,244 @@
+/**
+ * Inventory Doctor Agent Tools
+ * 
+ * Tools for diagnosing and fixing WMS pick-shortage incidents
+ */
+
+import z from "zod";
+import { registerToolLattice } from "@axiom-lattice/core";
+
+/**
+ * Get WMS movement tasks for a SKU and location
+ * Returns pending tasks that might affect inventory visibility
+ */
+registerToolLattice(
+  "get_wms_movement_tasks",
+  {
+    name: "get_wms_movement_tasks",
+    description:
+      "Retrieve in-flight movement tasks (putaway/move/wave) for a specific SKU and location. Use this to check for tasks in middle states that might cause inventory discrepancies.",
+    needUserApprove: false,
+    schema: z.object({
+      skuId: z.string().describe("SKU identifier"),
+      locationId: z.string().describe("Location identifier"),
+    }),
+  },
+  async (input: { skuId: string; locationId: string }) => {
+    // Mock data with random values
+    const taskTypes = ["putaway", "move", "wave", "replenishment"];
+    const statuses = ["in_progress", "pending", "queued", "processing"];
+    const hasPendingTasks = Math.random() > 0.3; // 70% chance of having pending tasks
+    const taskCount = hasPendingTasks ? Math.floor(Math.random() * 3) + 1 : 0;
+
+    const tasks = Array.from({ length: taskCount }, (_, i) => ({
+      id: `move-${Math.floor(Math.random() * 9000) + 1000}`,
+      type: taskTypes[Math.floor(Math.random() * taskTypes.length)],
+      status: statuses[Math.floor(Math.random() * statuses.length)],
+      etaMin: Math.floor(Math.random() * 60) + 5, // 5-65 minutes
+    }));
+
+    return {
+      pending: hasPendingTasks,
+      tasks,
+    };
+  }
+);
+
+/**
+ * Get location activity logs
+ * Returns recent activity logs for a location to identify unconfirmed moves or cancellations
+ */
+registerToolLattice(
+  "get_location_logs",
+  {
+    name: "get_location_logs",
+    description:
+      "Retrieve activity logs for a location within a specified lookback period. Use this to identify unconfirmed moves, cancellations, or other activities that might explain inventory discrepancies.",
+    needUserApprove: false,
+    schema: z.object({
+      locationId: z.string().describe("Location identifier"),
+      lookbackHours: z.number().describe("Number of hours to look back"),
+    }),
+  },
+  async (input: { locationId: string; lookbackHours: number }) => {
+    // Mock data with random values
+    const actions = ["move", "putaway", "pick", "adjustment", "cycle_count"];
+    const statuses = [
+      "pending_confirm",
+      "completed",
+      "cancelled",
+      "in_progress",
+      "failed",
+    ];
+    const operators = [
+      "op_x",
+      "op_y",
+      "op_z",
+      "worker_01",
+      "worker_05",
+      "worker_12",
+    ];
+    const locations = ["A-01", "A-02", "B-01", "B-02", "C-03", "D-05"];
+
+    const logCount = Math.floor(Math.random() * 5) + 1; // 1-5 logs
+    const now = new Date();
+    const logs = Array.from({ length: logCount }, (_, i) => {
+      const hoursAgo = Math.floor(Math.random() * input.lookbackHours);
+      const timestamp = new Date(now.getTime() - hoursAgo * 60 * 60 * 1000);
+      const fromLoc = locations[Math.floor(Math.random() * locations.length)];
+      const toLoc = locations[Math.floor(Math.random() * locations.length)];
+
+      return {
+        ts: timestamp.toISOString(),
+        action: actions[Math.floor(Math.random() * actions.length)],
+        from: fromLoc,
+        to: toLoc !== fromLoc ? toLoc : locations[Math.floor(Math.random() * locations.length)],
+        status: statuses[Math.floor(Math.random() * statuses.length)],
+        operator: operators[Math.floor(Math.random() * operators.length)],
+      };
+    });
+
+    // Sort by timestamp descending
+    logs.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
+
+    return logs;
+  }
+);
+
+/**
+ * Retry synchronization for a stuck task
+ * Attempts to refresh the status of a task that might be in a middle state
+ */
+registerToolLattice(
+  "retry_sync",
+  {
+    name: "retry_sync",
+    description:
+      "Retry synchronization for a task that appears to be stuck in a middle state. This will attempt to refresh the task status and resolve data delays.",
+    needUserApprove: false,
+    schema: z.object({
+      taskId: z.string().describe("Task identifier to retry"),
+    }),
+  },
+  async (input: { taskId: string }) => {
+    // Mock data with random outcomes
+    const fixed = Math.random() > 0.2; // 80% success rate
+    const messages = [
+      "status refreshed to completed",
+      "task synchronized successfully",
+      "sync completed, inventory updated",
+      "task status updated to completed",
+      "synchronization failed, task still in progress",
+      "unable to sync, task may require manual intervention",
+    ];
+
+    return {
+      fixed,
+      message: fixed
+        ? messages[Math.floor(Math.random() * 4)]
+        : messages[Math.floor(Math.random() * 2) + 4],
+    };
+  }
+);
+
+/**
+ * Dispatch a cycle count task for physical verification
+ * Creates a cycle count task and assigns it to an operator
+ */
+registerToolLattice(
+  "dispatch_cycle_count",
+  {
+    name: "dispatch_cycle_count",
+    description:
+      "Dispatch a cycle count task to physically verify inventory at specified locations. Use this when physical verification is needed to resolve inventory discrepancies.",
+    needUserApprove: false,
+    schema: z.object({
+      skuId: z.string().describe("SKU identifier to verify"),
+      locations: z.array(z.string()).describe("List of location identifiers to check"),
+      priority: z.string().describe("Priority level (e.g., 'high', 'medium', 'low')"),
+    }),
+  },
+  async (input: {
+    skuId: string;
+    locations: string[];
+    priority: string;
+  }) => {
+    // Mock data with random values
+    const workers = [
+      "worker_01",
+      "worker_05",
+      "worker_07",
+      "worker_12",
+      "worker_15",
+      "worker_20",
+    ];
+    const taskId = `cc-${Math.floor(Math.random() * 9000) + 1000}`;
+    const assignee = workers[Math.floor(Math.random() * workers.length)];
+    const etaMinutes = Math.floor(Math.random() * 30) + 5; // 5-35 minutes
+    const eta = `${etaMinutes}m`;
+
+    return {
+      taskId,
+      assignee,
+      eta,
+    };
+  }
+);
+
+/**
+ * Notify picker about inventory status
+ * Sends a notification to the picker about the current status
+ */
+registerToolLattice(
+  "notify_picker",
+  {
+    name: "notify_picker",
+    description:
+      "Send a notification message to the picker about inventory status, retry instructions, or other relevant information.",
+    needUserApprove: false,
+    schema: z.object({
+      message: z.string().describe("Message to send to the picker"),
+    }),
+  },
+  async (input: { message: string }) => {
+    // Mock data with random delivery status
+    const delivered = Math.random() > 0.1; // 90% success rate
+
+    return {
+      delivered,
+    };
+  }
+);
+
+/**
+ * Write case report to file system
+ * Saves the diagnostic case report as a markdown file
+ */
+registerToolLattice(
+  "write_case_report",
+  {
+    name: "write_case_report",
+    description:
+      "Save the diagnostic case report as a markdown file. Use this to record the diagnosis, actions taken, and recommendations for audit purposes.",
+    needUserApprove: false,
+    schema: z.object({
+      markdown: z.string().describe("Markdown content of the case report"),
+    }),
+  },
+  async (input: { markdown: string }) => {
+    // Mock data with random path and timestamp
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5);
+    const reportId = Math.floor(Math.random() * 10000);
+    const paths = [
+      `/reports/inventory-case-latest.md`,
+      `/reports/inventory-case-${reportId}.md`,
+      `/reports/case-${timestamp}.md`,
+      `/reports/inventory-diagnosis-${reportId}.md`,
+    ];
+
+    return {
+      saved: true,
+      path: paths[Math.floor(Math.random() * paths.length)],
+    };
+  }
+);

package/src/index.ts

@@ -6,13 +6,23 @@ import {
   registerCheckpointSaver,
   registerModelLattice,
   registerScheduleLattice,
+  FileSystemSkillStore,
+  registerStoreLattice,
+
+  storeLatticeManager,
+  skillLatticeManager,
 } from "@axiom-lattice/core";
 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 fs = require("fs");
 const PACKAGE_VERSION = require("../package.json").version;
 const BUILD_TIME = new Date().toISOString();
 const IS_DEV = process.env.NODE_ENV !== "production";
@@ -101,6 +111,81 @@ registerModelLattice(
 );
 LatticeGateway.registerLatticeRoutes(LatticeGateway.app);
 
+// Configure Skill Store with FileSystem storage
+// Point to the skills directory in data_agent
+// Always use source directory (src/) since .md files are not copied to dist/ during build
+// Try multiple path resolution strategies to work in both dev and production
+const possiblePaths = [
+  // Production: from dist/ go up to src/
+  path.resolve(__dirname, "../src/agents/data_agent/skills"),
+  // Development: relative to __dirname (src/)
+  path.resolve(__dirname, "./agents/data_agent/skills"),
+  // Fallback: from project root
+  path.resolve(process.cwd(), "examples/deep_research/src/agents/data_agent/skills"),
+];
+
+// Check which path exists, default to first path
+let skillsRootDir: string = possiblePaths[0];
+for (const possiblePath of possiblePaths) {
+  if (fs.existsSync(possiblePath)) {
+    skillsRootDir = possiblePath;
+    break;
+  }
+}
+
+if (!fs.existsSync(skillsRootDir)) {
+  console.warn(
+    `Warning: Skills directory not found at any of the expected paths. Using: ${skillsRootDir}`
+  );
+}
+
+console.log(`Skill store root directory: ${skillsRootDir}`);
+
+const skillStore = new FileSystemSkillStore({
+  rootDir: skillsRootDir,
+});
+
+// Remove the default skill store and register our custom one
+// This ensures tools like load_skills and load_skill_content can access our skills
+storeLatticeManager.removeLattice("default", "skill");
+registerStoreLattice("default", "skill", skillStore);
+
+// Configure SkillLatticeManager to use the store
+skillLatticeManager.configureStore("default");
+
+// Test loading skills on startup to verify configuration
+(async () => {
+  try {
+    const skills = await skillStore.getAllSkills();
+    console.log(`Loaded ${skills.length} skills from file system:`);
+    if (skills.length === 0) {
+      console.warn(
+        `Warning: No skills found. Please check if the directory exists: ${skillsRootDir}`
+      );
+    } else {
+      skills.forEach((skill) => {
+        console.log(`  - ${skill.name}: ${skill.description.substring(0, 50)}...`);
+      });
+    }
+  } catch (error) {
+    console.error("Failed to load skills on startup:", error);
+    if (error instanceof Error) {
+      console.error("Error details:", error.message);
+      console.error("Stack:", error.stack);
+    }
+  }
+})();
+
+// // Load skills from the file system asynchronously
+// (async () => {
+//   try {
+//     await loadSkillsFromStore();
+//     console.log("Skills loaded successfully from file system");
+//   } catch (error) {
+//     console.error("Failed to load skills:", error);
+//   }
+// })();
+
 // // 注册 Schedule Lattice（使用 PostgreSQL 持久化）
 // registerScheduleLattice("default", {
 //   name: "Default Scheduler",
@@ -129,7 +214,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,
 });