railwise-ai 1.2.32 → 1.2.34

package/agent-pack/assets/tool/github-pr-search.ts

@@ -0,0 +1,57 @@
+/// <reference path="../env.d.ts" />
+import { tool } from "nb-railwise/tool"
+import DESCRIPTION from "./github-pr-search.txt"
+
+async function githubFetch(endpoint: string, options: RequestInit = {}) {
+  const response = await fetch(`https://api.github.com${endpoint}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+      Accept: "application/vnd.github+json",
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  })
+  if (!response.ok) {
+    throw new Error(`GitHub API error: ${response.status} ${response.statusText}`)
+  }
+  return response.json()
+}
+
+interface PR {
+  title: string
+  html_url: string
+}
+
+export default tool({
+  description: DESCRIPTION,
+  args: {
+    query: tool.schema.string().describe("Search query for PR titles and descriptions"),
+    limit: tool.schema.number().describe("Maximum number of results to return").default(10),
+    offset: tool.schema.number().describe("Number of results to skip for pagination").default(0),
+  },
+  async execute(args) {
+    const owner = "anomalyco"
+    const repo = "railwise"
+
+    const page = Math.floor(args.offset / args.limit) + 1
+    const searchQuery = encodeURIComponent(`${args.query} repo:${owner}/${repo} type:pr state:open`)
+    const result = await githubFetch(
+      `/search/issues?q=${searchQuery}&per_page=${args.limit}&page=${page}&sort=updated&order=desc`,
+    )
+
+    if (result.total_count === 0) {
+      return `No PRs found matching "${args.query}"`
+    }
+
+    const prs = result.items as PR[]
+
+    if (prs.length === 0) {
+      return `No other PRs found matching "${args.query}"`
+    }
+
+    const formatted = prs.map((pr) => `${pr.title}\n${pr.html_url}`).join("\n\n")
+
+    return `Found ${result.total_count} PRs (showing ${prs.length}):\n\n${formatted}`
+  },
+})

package/agent-pack/assets/tool/github-pr-search.txt

@@ -0,0 +1,10 @@
+Use this tool to search GitHub pull requests by title and description.
+
+This tool searches PRs in the sst/railwise repository and returns LLM-friendly results including:
+- PR number and title
+- Author
+- State (open/closed/merged)
+- Labels
+- Description snippet
+
+Use the query parameter to search for keywords that might appear in PR titles or descriptions.

package/agent-pack/assets/tool/github-triage.ts

@@ -0,0 +1,113 @@
+/// <reference path="../env.d.ts" />
+import { tool } from "nb-railwise/tool"
+import DESCRIPTION from "./github-triage.txt"
+
+const TEAM = {
+  desktop: ["adamdotdevin", "iamdavidhill", "Brendonovich", "nexxeln"],
+  zen: ["fwang", "MrMushrooooom"],
+  tui: ["thdxr", "kommander", "rekram1-node"],
+  core: ["thdxr", "rekram1-node", "jlongster"],
+  docs: ["R44VC0RP"],
+  windows: ["Hona"],
+} as const
+
+const ASSIGNEES = [...new Set(Object.values(TEAM).flat())]
+
+function pick<T>(items: readonly T[]) {
+  return items[Math.floor(Math.random() * items.length)]!
+}
+
+function getIssueNumber(): number {
+  const issue = parseInt(process.env.ISSUE_NUMBER ?? "", 10)
+  if (!issue) throw new Error("ISSUE_NUMBER env var not set")
+  return issue
+}
+
+async function githubFetch(endpoint: string, options: RequestInit = {}) {
+  const response = await fetch(`https://api.github.com${endpoint}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+      Accept: "application/vnd.github+json",
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  })
+  if (!response.ok) {
+    throw new Error(`GitHub API error: ${response.status} ${response.statusText}`)
+  }
+  return response.json()
+}
+
+export default tool({
+  description: DESCRIPTION,
+  args: {
+    assignee: tool.schema
+      .enum(ASSIGNEES as [string, ...string[]])
+      .describe("The username of the assignee")
+      .default("rekram1-node"),
+    labels: tool.schema
+      .array(tool.schema.enum(["nix", "opentui", "perf", "web", "desktop", "zen", "docs", "windows", "core"]))
+      .describe("The labels(s) to add to the issue")
+      .default([]),
+  },
+  async execute(args) {
+    const issue = getIssueNumber()
+    const owner = "anomalyco"
+    const repo = "railwise"
+
+    const results: string[] = []
+    let labels = [...new Set(args.labels.map((x) => (x === "desktop" ? "web" : x)))]
+    const web = labels.includes("web")
+    const text = `${process.env.ISSUE_TITLE ?? ""}\n${process.env.ISSUE_BODY ?? ""}`.toLowerCase()
+    const zen = /\bzen\b/.test(text) || text.includes("railwise black")
+    const nix = /\bnix(os)?\b/.test(text)
+
+    if (labels.includes("nix") && !nix) {
+      labels = labels.filter((x) => x !== "nix")
+      results.push("Dropped label: nix (issue does not mention nix)")
+    }
+
+    const assignee = nix ? "rekram1-node" : web ? pick(TEAM.desktop) : args.assignee
+
+    if (labels.includes("zen") && !zen) {
+      throw new Error("Only add the zen label when issue title/body contains 'zen'")
+    }
+
+    if (web && !nix && !(TEAM.desktop as readonly string[]).includes(assignee)) {
+      throw new Error("Web issues must be assigned to adamdotdevin, iamdavidhill, Brendonovich, or nexxeln")
+    }
+
+    if ((TEAM.zen as readonly string[]).includes(assignee) && !labels.includes("zen")) {
+      throw new Error("Only zen issues should be assigned to fwang or MrMushrooooom")
+    }
+
+    if (assignee === "Hona" && !labels.includes("windows")) {
+      throw new Error("Only windows issues should be assigned to Hona")
+    }
+
+    if (assignee === "R44VC0RP" && !labels.includes("docs")) {
+      throw new Error("Only docs issues should be assigned to R44VC0RP")
+    }
+
+    if (assignee === "kommander" && !labels.includes("opentui")) {
+      throw new Error("Only opentui issues should be assigned to kommander")
+    }
+
+    await githubFetch(`/repos/${owner}/${repo}/issues/${issue}/assignees`, {
+      method: "POST",
+      body: JSON.stringify({ assignees: [assignee] }),
+    })
+    results.push(`Assigned @${assignee} to issue #${issue}`)
+
+    if (labels.length > 0) {
+      await githubFetch(`/repos/${owner}/${repo}/issues/${issue}/labels`, {
+        method: "POST",
+        body: JSON.stringify({ labels }),
+      })
+      results.push(`Added labels: ${labels.join(", ")}`)
+    }
+
+    return results.join("\n")
+  },
+})

package/agent-pack/assets/tool/github-triage.txt

@@ -0,0 +1,6 @@
+Use this tool to assign and/or label a GitHub issue.
+
+Choose labels and assignee using the current triage policy and ownership rules.
+Pick the most fitting labels for the issue and assign one owner.
+
+If unsure, choose the team/section with the most overlap with the issue and assign a member from that team at random.

package/agent-pack/assets/tool/inclinometer.ts

@@ -0,0 +1,248 @@
+/// <reference path="../env.d.ts" />
+import { tool } from "nb-railwise/tool"
+
+// ============================================================
+// Deep horizontal displacement (inclinometer) tools
+// 基坑深层水平位移（测斜仪）监测数据处理与分析
+// ============================================================
+
+// ============================================================
+// Tool: Inclinometer profile calculation
+// ============================================================
+
+export const inclinometer_profile = tool({
+  description:
+    "测斜仪深层水平位移剖面计算。根据各深度处的测斜仪读数（A+/A-/B+/B-），计算各深度处的累计水平位移，生成位移-深度剖面。基坑监测中深层水平位移分析的核心工具。data_analyst 处理测斜数据时必须调用此工具。",
+  args: {
+    pointId: tool.schema.string().describe("测斜孔编号，如 CX-01"),
+    gaugeLength: tool.schema.number().positive().default(0.5).describe("测斜仪导轮间距(m)，常见为0.5m或1.0m"),
+    direction: tool.schema
+      .enum(["A", "B", "AB"])
+      .default("A")
+      .describe("计算方向：A=垂直基坑方向, B=平行基坑方向, AB=双向"),
+    baseDepth: tool.schema.number().positive().describe("管底深度(m)，即假定不动点深度"),
+    initialReadings: tool.schema
+      .array(
+        tool.schema.object({
+          depth: tool.schema.number().describe("测量深度(m)，从管口往下"),
+          aPlus: tool.schema.number().describe("A+方向读数"),
+          aMinus: tool.schema.number().describe("A-方向读数"),
+          bPlus: tool.schema.number().optional().describe("B+方向读数"),
+          bMinus: tool.schema.number().optional().describe("B-方向读数"),
+        }),
+      )
+      .min(2)
+      .describe("初始（基准）读数，从浅到深排列"),
+    currentReadings: tool.schema
+      .array(
+        tool.schema.object({
+          depth: tool.schema.number().describe("测量深度(m)"),
+          aPlus: tool.schema.number().describe("A+方向读数"),
+          aMinus: tool.schema.number().describe("A-方向读数"),
+          bPlus: tool.schema.number().optional().describe("B+方向读数"),
+          bMinus: tool.schema.number().optional().describe("B-方向读数"),
+        }),
+      )
+      .min(2)
+      .describe("本期读数，深度序列与初始读数一致"),
+    alertThreshold: tool.schema.number().positive().optional().describe("水平位移报警值(mm)"),
+  },
+  async execute(args) {
+    const K = 2 * 25000 // 灵敏度系数，标准测斜仪 2×25000
+    const L = args.gaugeLength
+
+    // Build depth-indexed maps
+    const initMap = new Map(args.initialReadings.map((r) => [r.depth, r]))
+    const currMap = new Map(args.currentReadings.map((r) => [r.depth, r]))
+
+    // Get sorted depths (deep to shallow for bottom-up accumulation)
+    const depths = [...new Set([...initMap.keys(), ...currMap.keys()])].sort((a, b) => b - a)
+
+    // Calculate incremental displacement at each depth
+    const increments: Array<{
+      depth: number
+      deltaA: number
+      deltaB: number | null
+    }> = []
+
+    for (const d of depths) {
+      const init = initMap.get(d)
+      const curr = currMap.get(d)
+      if (!init || !curr) continue
+
+      // A direction: combined reading = (A+ - A-) to eliminate zero offset
+      const initCombA = init.aPlus - init.aMinus
+      const currCombA = curr.aPlus - curr.aMinus
+      const deltaA = ((currCombA - initCombA) / K) * L * 1000 // mm
+
+      let deltaB: number | null = null
+      if (
+        init.bPlus !== undefined &&
+        init.bMinus !== undefined &&
+        curr.bPlus !== undefined &&
+        curr.bMinus !== undefined
+      ) {
+        const initCombB = init.bPlus - init.bMinus
+        const currCombB = curr.bPlus - curr.bMinus
+        deltaB = ((currCombB - initCombB) / K) * L * 1000 // mm
+      }
+
+      increments.push({ depth: d, deltaA, deltaB })
+    }
+
+    // Bottom-up accumulation (from base depth upward)
+    // The deepest point (base) is assumed to have zero displacement
+    let cumA = 0
+    let cumB = 0
+    const profile: Array<{
+      depth: number
+      incremental_a_mm: number
+      incremental_b_mm: number | null
+      cumulative_a_mm: number
+      cumulative_b_mm: number | null
+      resultant_mm: number | null
+      status: string
+    }> = []
+
+    for (const inc of increments) {
+      cumA += inc.deltaA
+      if (inc.deltaB !== null) cumB += inc.deltaB
+
+      const resultant = inc.deltaB !== null ? Math.sqrt(cumA * cumA + cumB * cumB) : null
+
+      let status = "🟢 正常"
+      if (args.alertThreshold) {
+        const checkVal = resultant ?? Math.abs(cumA)
+        const ratio = checkVal / args.alertThreshold
+        if (ratio >= 1.0) status = "🔴 超限"
+        else if (ratio >= 0.85) status = "🟠 接近阈值"
+        else if (ratio >= 0.7) status = "🟡 关注"
+      }
+
+      profile.push({
+        depth: inc.depth,
+        incremental_a_mm: Number(inc.deltaA.toFixed(3)),
+        incremental_b_mm: inc.deltaB !== null ? Number(inc.deltaB.toFixed(3)) : null,
+        cumulative_a_mm: Number(cumA.toFixed(3)),
+        cumulative_b_mm: inc.deltaB !== null ? Number(cumB.toFixed(3)) : null,
+        resultant_mm: resultant !== null ? Number(resultant.toFixed(3)) : null,
+        status,
+      })
+    }
+
+    // Reverse so output is shallow-to-deep (top to bottom)
+    profile.reverse()
+
+    // Find max displacement
+    const maxPoint = profile.reduce(
+      (max, p) => {
+        const val = p.resultant_mm ?? Math.abs(p.cumulative_a_mm)
+        return val > max.value ? { depth: p.depth, value: val } : max
+      },
+      { depth: 0, value: 0 },
+    )
+
+    return JSON.stringify({
+      point_id: args.pointId,
+      direction: args.direction,
+      gauge_length_m: L,
+      base_depth_m: args.baseDepth,
+      measurement_count: profile.length,
+      max_displacement: {
+        depth_m: maxPoint.depth,
+        value_mm: Number(maxPoint.value.toFixed(3)),
+      },
+      profile,
+      alert_threshold_mm: args.alertThreshold ?? null,
+      message: `✅ ${args.pointId} 测斜分析完成：${profile.length}个测点，最大位移 ${maxPoint.value.toFixed(3)}mm（深度 ${maxPoint.depth}m）${args.alertThreshold ? `，控制值 ${args.alertThreshold}mm` : ""}`,
+    })
+  },
+})
+
+// ============================================================
+// Tool: Inclinometer multi-period trend analysis
+// ============================================================
+
+export const inclinometer_trend = tool({
+  description:
+    "测斜仪多期数据趋势分析。输入同一测斜孔多期的最大水平位移值，分析位移发展趋势、速率变化，预测未来位移。用于基坑监测周报中的深层位移趋势判断。",
+  args: {
+    pointId: tool.schema.string().describe("测斜孔编号"),
+    maxDepth: tool.schema.number().positive().describe("最大位移所在深度(m)"),
+    records: tool.schema
+      .array(
+        tool.schema.object({
+          date: tool.schema.string().describe("观测日期 YYYY-MM-DD"),
+          maxDisplacement: tool.schema.number().describe("该期最大累计水平位移(mm)"),
+        }),
+      )
+      .min(3)
+      .describe("多期最大位移数据，按时间排序"),
+    alertThreshold: tool.schema.number().positive().optional().describe("报警值(mm)"),
+    predictionDays: tool.schema.number().int().positive().default(7).describe("预测天数"),
+  },
+  async execute(args) {
+    const n = args.records.length
+    const t0 = new Date(args.records[0]!.date).getTime()
+    const days = args.records.map((r) => (new Date(r.date).getTime() - t0) / 86400000)
+    const vals = args.records.map((r) => r.maxDisplacement)
+
+    // Period rates
+    const rates: Array<{ period: string; rate: number; increment: number }> = []
+    for (let i = 1; i < n; i++) {
+      const dt = days[i]! - days[i - 1]!
+      const dv = vals[i]! - vals[i - 1]!
+      rates.push({
+        period: `${args.records[i - 1]!.date} → ${args.records[i]!.date}`,
+        rate: dt > 0 ? Number((dv / dt).toFixed(4)) : 0,
+        increment: Number(dv.toFixed(3)),
+      })
+    }
+
+    // Linear regression
+    const meanX = days.reduce((s, v) => s + v, 0) / n
+    const meanY = vals.reduce((s, v) => s + v, 0) / n
+    const ssxy = days.reduce((s, x, i) => s + (x - meanX) * (vals[i]! - meanY), 0)
+    const ssxx = days.reduce((s, x) => s + (x - meanX) * (x - meanX), 0)
+    const b = ssxx > 0 ? ssxy / ssxx : 0
+    const a = meanY - b * meanX
+
+    const lastDay = days[n - 1]!
+    const predictions = Array.from({ length: args.predictionDays }, (_, i) => {
+      const d = lastDay + i + 1
+      return {
+        date: new Date(t0 + d * 86400000).toISOString().slice(0, 10),
+        predicted_mm: Number((a + b * d).toFixed(3)),
+      }
+    })
+
+    // Stability
+    const last3 = rates.slice(-3).map((r) => Math.abs(r.rate))
+    const avgLast3 = last3.length > 0 ? last3.reduce((s, v) => s + v, 0) / last3.length : 0
+    const avgRate = Math.abs(b)
+
+    let stability: string
+    if (avgLast3 < 0.01) stability = "✅ 已收敛"
+    else if (avgLast3 < 0.05) stability = "🟢 趋于收敛"
+    else if (avgLast3 > avgRate * 1.5) stability = "🔴 加速发展，需加密监测"
+    else stability = "🟡 等速发展，继续监测"
+
+    let daysToAlert: number | string = "不会到达"
+    if (args.alertThreshold && b > 0) {
+      const d = (args.alertThreshold - a) / b - lastDay
+      if (d > 0) daysToAlert = Number(d.toFixed(1))
+    }
+
+    return JSON.stringify({
+      point_id: args.pointId,
+      max_depth_m: args.maxDepth,
+      latest_mm: vals[n - 1],
+      trend_rate_mm_per_day: Number(b.toFixed(4)),
+      stability,
+      rates,
+      predictions,
+      days_to_alert: daysToAlert,
+      message: `✅ ${args.pointId} 深层位移趋势：最新 ${vals[n - 1]}mm，速率 ${b.toFixed(4)}mm/d，${stability}`,
+    })
+  },
+})

package/agent-pack/assets/tool/monitoring_csv.ts

@@ -0,0 +1,120 @@
+/// <reference path="../env.d.ts" />
+import { tool } from "nb-railwise/tool"
+import path from "path"
+
+export default tool({
+  description:
+    "处理自动化监测仪器（静力水准、全站仪机器人、测斜仪）的海量CSV/TXT数据文件。输入文件路径，返回清洗后的核心数据指标（本期变化量、累计变化量、速率、超限测点列表）。data_analyst 必须调用此工具，绝不直接读取原始文件。",
+  args: {
+    filePath: tool.schema.string().describe("用户上传的 CSV、TXT 或 Excel 文件的绝对路径"),
+    sensorType: tool.schema
+      .enum(["settlement", "inclinometer", "strain_gauge", "convergence", "gnss"])
+      .describe(
+        "传感器类型：settlement=沉降/静力水准, inclinometer=测斜仪, strain_gauge=应变计, convergence=收敛计, gnss=GNSS",
+      ),
+    alertThreshold: tool.schema
+      .number()
+      .positive()
+      .optional()
+      .describe("报警控制值（mm），用于自动标记超限测点，不传则不做超限判断"),
+    periodDays: tool.schema.int().positive().default(7).describe("统计周期天数，默认7天（本期=最近N天）"),
+  },
+  async execute(args) {
+    const file = Bun.file(args.filePath)
+    const exists = await file.exists()
+
+    if (!exists) return JSON.stringify({ error: `文件不存在：${args.filePath}，请检查路径是否正确。` })
+
+    const ext = path.extname(args.filePath).toLowerCase()
+    if (![".csv", ".txt", ".dat"].includes(ext))
+      return JSON.stringify({
+        error: `暂不支持 ${ext} 格式，请转换为 CSV/TXT/DAT 文件后重试。`,
+      })
+
+    const raw = await file.text()
+    const lines = raw
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0 && !l.startsWith("#"))
+
+    if (lines.length < 2) return JSON.stringify({ error: "文件内容为空或仅有标题行，无有效数据。" })
+
+    const header = lines[0]!.split(/[,\t;]/)
+    const rows = lines.slice(1).map((l) => l.split(/[,\t;]/))
+
+    const timeIdx = header.findIndex((h) => /time|date|时间|日期/i.test(h))
+    const idIdx = header.findIndex((h) => /id|point|测点|编号/i.test(h))
+    const valIdx = header.findIndex((h) => /value|val|读数|高差|沉降|位移|应变/i.test(h))
+
+    if (valIdx === -1)
+      return JSON.stringify({
+        error: `无法识别数值列，请确认 CSV 列头包含 value/val/读数/沉降/位移 等关键字。识别到的列：${header.join(", ")}`,
+      })
+
+    const pointGroups: Record<string, number[]> = {}
+    for (const row of rows) {
+      const id = idIdx >= 0 ? (row[idIdx] ?? "unknown") : `P${rows.indexOf(row)}`
+      const raw = parseFloat(row[valIdx] ?? "")
+      if (isNaN(raw)) continue
+      if (!pointGroups[id]) pointGroups[id] = []
+      pointGroups[id]!.push(raw)
+    }
+
+    const totalPoints = Object.keys(pointGroups).length
+    if (totalPoints === 0) return JSON.stringify({ error: "未能从文件中解析到有效的数值数据，请检查文件格式。" })
+
+    const cutoff = args.periodDays
+    const results = Object.entries(pointGroups).map(([id, vals]) => {
+      const mean = vals.reduce((a, b) => a + b, 0) / vals.length
+      const deviations = vals.map((v) => Math.abs(v - mean))
+      const mad = deviations.reduce((a, b) => a + b, 0) / deviations.length
+      const threshold3sigma = 3 * (mad * 1.4826)
+      const cleaned = vals.filter((v) => Math.abs(v - mean) <= threshold3sigma)
+
+      const baseline = cleaned[0] ?? 0
+      const current = cleaned[cleaned.length - 1] ?? 0
+      const cumulative = current - baseline
+
+      const recent = cleaned.slice(-cutoff)
+      const periodChange = recent.length >= 2 ? recent[recent.length - 1]! - recent[0]! : 0
+      const rate = recent.length >= 2 ? periodChange / cutoff : 0
+
+      const removedCount = vals.length - cleaned.length
+
+      const exceeded = args.alertThreshold ? Math.abs(cumulative) >= args.alertThreshold : false
+      const ratioPct = args.alertThreshold
+        ? Number(((Math.abs(cumulative) / args.alertThreshold) * 100).toFixed(1))
+        : null
+
+      return {
+        point_id: id,
+        total_readings: vals.length,
+        removed_outliers: removedCount,
+        cumulative_mm: Number(cumulative.toFixed(3)),
+        period_change_mm: Number(periodChange.toFixed(3)),
+        rate_mm_per_day: Number(rate.toFixed(4)),
+        exceeded_threshold: exceeded,
+        ratio_pct: ratioPct,
+      }
+    })
+
+    const exceeded = results.filter((r) => r.exceeded_threshold)
+    const maxCumulative = results.reduce((a, b) => (Math.abs(a.cumulative_mm) > Math.abs(b.cumulative_mm) ? a : b))
+
+    return JSON.stringify({
+      file: path.basename(args.filePath),
+      sensor_type: args.sensorType,
+      total_points: totalPoints,
+      period_days: args.periodDays,
+      alert_threshold_mm: args.alertThreshold ?? null,
+      exceeded_count: exceeded.length,
+      max_cumulative_point: maxCumulative.point_id,
+      max_cumulative_mm: maxCumulative.cumulative_mm,
+      exceeded_points: exceeded.map((r) => r.point_id),
+      summary: results,
+      data_quality_note: results.some((r) => r.removed_outliers > 0)
+        ? `共剔除 ${results.reduce((s, r) => s + r.removed_outliers, 0)} 个异常跳变点（采用 MAD 3σ 方法）`
+        : "原始数据质量良好，无异常值剔除",
+    })
+  },
+})

package/agent-pack/assets/tool/os_contract_query.ts

@@ -0,0 +1,63 @@
+/// <reference path="../env.d.ts" />
+import { tool } from "nb-railwise/tool"
+import { callOsApi, first, list, num, prettyJson, type Obj } from "../lib/os_api"
+
+function compactContract(item: Obj) {
+  const attachments = list(item.attachments)
+  return {
+    id: first(item, ["id"]),
+    contractNo: first(item, ["contractNo", "code"]),
+    projectName: first(item, ["projectName", "name"]),
+    category: first(item, ["category", "contractCategory"]),
+    type: first(item, ["type", "projectType"]),
+    status: first(item, ["status"]),
+    partyA: first(item, ["partyA"]),
+    partyB: first(item, ["partyB"]),
+    amount: num(item.amount ?? item.amountYuan),
+    paidAmount: num(item.paidAmount),
+    unpaidAmount: num(item.unpaidAmount),
+    manager: first(item, ["manager"]),
+    collectionOwner: first(item, ["collectionOwner"]),
+    signDate: first(item, ["signDate"]),
+    startDate: first(item, ["startDate"]),
+    endDate: first(item, ["endDate"]),
+    attachmentCount: attachments.length,
+    attachments: attachments.slice(0, 5).map((attachment) => ({
+      id: first(attachment, ["id", "fileId", "token"]),
+      name: first(attachment, ["name", "fileName", "title"]),
+      url: first(attachment, ["url", "downloadUrl"]),
+    })),
+  }
+}
+
+export default tool({
+  description: "Query OS finance contracts, including party B, amount, collection status and attachment summaries.",
+  args: {
+    keyword: tool.schema.string().optional().describe("Keyword for contract number, project name, party A/B or manager."),
+    year: tool.schema.string().optional().describe("Contract year filter."),
+    manager: tool.schema.string().optional().describe("Manager filter."),
+    contractCategory: tool.schema.string().optional().describe("Contract category filter."),
+    status: tool.schema.string().optional().describe("Status filter."),
+    pendingOnly: tool.schema.boolean().optional().describe("Return pending contracts only."),
+    limit: tool.schema.number().int().min(1).max(100).optional().describe("Maximum result count."),
+  },
+  async execute(args) {
+    const data = await callOsApi("/finance/contracts", {
+      query: {
+        keyword: args.keyword,
+        year: args.year,
+        manager: args.manager,
+        contractCategory: args.contractCategory,
+        status: args.status,
+        pendingOnly: args.pendingOnly,
+        size: args.limit || 20,
+      },
+    })
+    const root = data && typeof data === "object" && !Array.isArray(data) ? data as Obj : null
+    const items = root ? list(root.items) : list(data)
+    return prettyJson({
+      total: root?.total ?? items.length,
+      items: items.map(compactContract),
+    })
+  },
+})