REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

Expression 內建函數

Asgard Expression 系統提供 8 個專用的內建函數，讓您在動態內容中處理對話歷史、資料轉換和編碼需求。

內建函數清單

對話歷史函數

history

取得指定索引區間的歷史對話紀錄清單

語法：
```
history(start, end)
```
參數：
- start (number)：起始位置（0 開始，支援負數倒數）
- end (number)：結束位置（包含該位置，支援負數倒數）
回傳：
- string：對話紀錄清單，格式為純文字，每行代表一筆對話
範例：
```
// 回傳索引 0, 1, 2 的三筆對話
history(0, 2)
 
// 回傳倒數第 3 筆至最後一筆對話
history(-3, -1)
 
// 回傳所有對話
history(0, -1)
```
回傳格式：
```
bot: Hi, how can I help you?
user: Hello, I need assistance with my order.
bot: Okay, please provide your order number.
```
historySize

取得目前頻道的歷史對話紀錄數量

語法：
```
historySize()
```
回傳：
- number：對話記錄數量
範例：
```
// 回傳數字，例如：5
historySize()
```
資料處理函數

urlEncode

將字串進行 URL 編碼

語法：
```
urlEncode(val)
```
參數：
- val (string)：要編碼的字串
回傳：
- string：URL 編碼後的結果
範例：
```
// "hello%20world"
urlEncode('hello world')
 
// "%E6%90%9C%E5%B0%8B%E9%97%9C%E9%8D%B5%E5%AD%97"
urlEncode('搜尋關鍵字')
 
// 將前一則訊息進行 URL 編碼
urlEncode(prevMessage)
```
vecToStr

將向量陣列轉換為字串格式

語法：
```
vecToStr(vector, prefix, suffix, delimiter)
```
參數：
- vector (array<number>)：向量陣列
- prefix (string)：開頭字符
- suffix (string)：結尾字符
- delimiter (string)：分隔符
回傳：
- string：轉換後的字串
範例：
```
// "{1,2,3}"
vecToStr([1, 2, 3], '{', '}', ',')
 
// "[0.1|0.5|0.8]"
vecToStr([0.1, 0.5, 0.8], '[', ']', '|')
```
xpathExtract

利用 XPath 在 XML 文件中進行查找

語法：
```
xpathExtract(xml, path)
```
參數：
- xml (string)：XML 文件內容
- path (string)：XPath 查詢語法
回傳：
- string：所有符合元素的 Inner Text，以換行符號分隔
範例：
```
const xml = '<root><item>1</item><item>2</item></root>'
// "1\n2"
xpathExtract(xml, '/root/item')
 
// 查詢所有結果標題
xpathExtract(responseXml, '//result/title')
```
日期時間函數

isoNow

回傳特定時區當前日期時間的 RFC3339 格式字串

語法：
```
isoNow(timezone)
```
參數：
- timezone (string)：IANA 時區名稱
回傳：
- string：RFC3339 格式的當前日期時間
範例：
```
// "2025-05-27T01:08:44+08:00"
isoNow('Asia/Taipei')
 
// "2025-05-26T17:08:44Z"
isoNow('UTC')
 
// "2025-05-26T13:08:44-04:00"
isoNow('America/New_York')
```
isoToday

回傳特定時區當前日期的 RFC3339 格式字串

語法：
```
isoToday(timezone)
```
參數：
- timezone (string)：IANA 時區名稱
回傳：
- string：RFC3339 格式的當前日期
範例：
```
// "2025-05-27"
isoToday('Asia/Taipei')
 
// "2025-05-26"
isoToday('UTC')
 
// "2025-05-26"
isoToday('America/New_York')
```

進階應用範例

對話分析與摘要

// 分析對話趨勢
(() => {
  const totalMessages = historySize();
  if (totalMessages === 0) return '無對話記錄';
 
  // 取得最近對話進行分析
  const recentCount = Math.min(10, totalMessages);
  const recentHistory = history(-recentCount, -1);
 
  const lines = recentHistory.split('\n');
  const userMessages = lines.filter(line => line.startsWith('user:')).length;
  const botMessages = lines.filter(line => line.startsWith('bot:')).length;
 
  return `分析最近 ${recentCount} 則對話：使用者 ${userMessages} 則，機器人 ${botMessages} 則`;
})()

API 整合與資料處理

// 建構複雜 API 查詢
(() => {
  const keyword = prevMessage || '';
  const encodedQuery = urlEncode(keyword);
  const timestamp = isoNow('UTC');
 
  // 建構查詢參數
  const params = [`q=${encodedQuery}`, `timestamp=${timestamp}`, `channel=${customChannelId || 'default'}`].join('&');
 
  return `https://api.example.com/search?${params}`;
})()

XML 資料解析

// 處理複雜 XML 回應
(() => {
  if (!xmlResponse) return '無 XML 資料';
 
  try {
    const titles = xpathExtract(xmlResponse, '//result/title');
    const prices = xpathExtract(xmlResponse, '//result/price');
 
    if (!titles) return '無搜尋結果';
 
    const titleList = titles.split('\n');
    const priceList = prices ? prices.split('\n') : [];
 
    let result = '搜尋結果：\n';
    titleList.forEach((title, index) => {
      const price = priceList[index] || '價格未知';
      result += `${index + 1}. ${title} - ${price}\n`;
    });
 
    return result;
  } catch (e) {
    return 'XML 解析錯誤';
  }
})()

向量資料處理

// 向量相似度比較
(() => {
  const userVector = [0.1, 0.5, 0.8, 0.2];
  const systemVector = [0.2, 0.4, 0.7, 0.3];
 
  // 格式化為不同格式供不同系統使用
  const formats = {
    json: vecToStr(userVector, '[', ']', ','),
    csv: vecToStr(userVector, '', '', ','),
    sql: vecToStr(userVector, '(', ')', ','),
  };
 
  return `向量格式化結果：
JSON: ${formats.json}
CSV: ${formats.csv}
SQL: ${formats.sql}`;
})()

時間序列處理

// 建立帶時間戳的日誌
(() => {
  const timezone = 'Asia/Taipei';
  const now = isoNow(timezone);
  const today = isoToday(timezone);
 
  const messageCount = historySize();
  const hasError = prevError ? true : false;
 
  const logEntry = {
    date: today,
    timestamp: now,
    messages: messageCount,
    hasError: hasError,
    channel: customChannelId || 'unknown',
  };
 
  return `[${now}] 日誌：頻道 ${logEntry.channel}，${logEntry.messages} 則訊息${hasError ? '，有錯誤' : ''}`;
})()

效能最佳化

函數調用快取

// ✅ 快取常用值，避免重複調用
(() => {
  const messageCount = historySize(); // 只調用一次
  const timezone = 'Asia/Taipei';
  const currentTime = isoNow(timezone); // 只調用一次
 
  if (messageCount === 0) {
    return `[${currentTime}] 新對話開始`;
  }
 
  const recentHistory = messageCount > 5 ? history(-5, -1) : history(0, -1);
 
  return `[${currentTime}] 對話記錄：${messageCount} 則\n${recentHistory}`;
})()

條件式執行

// ✅ 避免不必要的函數調用
(() => {
  // 先檢查基本條件
  if (!prevMessage) return '無訊息需要處理';
 
  // 只在需要時才調用編碼函數
  const needsEncoding = /[^\w\s]/.test(prevMessage);
  const processedMessage = needsEncoding ? urlEncode(prevMessage) : prevMessage;
 
  return `處理結果：${processedMessage}`;
})()

這些內建函數提供強大的資料處理能力，讓您能在 Expression 中輕鬆處理複雜的對話邏輯和資料轉換需求。

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們

內建函數清單​

對話歷史函數​

history​

historySize​

資料處理函數​

urlEncode​

vecToStr​

xpathExtract​

日期時間函數​

isoNow​

isoToday​

進階應用範例​

對話分析與摘要​

API 整合與資料處理​

XML 資料解析​

向量資料處理​

時間序列處理​

效能最佳化​

函數調用快取​

條件式執行​

準備好開始了嗎？

內建函數清單

對話歷史函數

history

historySize

資料處理函數

urlEncode

vecToStr

xpathExtract

日期時間函數

isoNow

isoToday

進階應用範例

對話分析與摘要

API 整合與資料處理

XML 資料解析

向量資料處理

時間序列處理

效能最佳化

函數調用快取

條件式執行