@opentiny/next-sdk 0.2.6 → 0.2.8

package/page-tools/effects.ts

@@ -0,0 +1,343 @@
+/**
+ * page-tools/effects - 页面工具调用提示效果模块（框架无关）
+ *
+ * 作用：
+ * - 在调用通过 withPageTools 注册的页面工具时，显示页面级的调用状态提示
+ * - 以左下角小 tip 形式展示“当前正在调用的工具”文案，尽量不打扰用户操作
+ * - 纯 DOM + CSS 实现，不依赖 Vue/React 等框架
+ */
+
+export type ToolInvokeEffectConfig = {
+  /**
+   * 自定义提示文案，默认使用“工具标题 || 工具名称”
+   * 例如："正在为你整理订单数据"
+   */
+  label?: string
+}
+
+type RuntimeEffectConfig = {
+  label: string
+}
+
+let overlayElement: HTMLDivElement | null = null
+let labelElement: HTMLDivElement | null = null
+let styleElement: HTMLStyleElement | null = null
+let activeCount = 0
+
+const BODY_GLOW_CLASS = 'next-sdk-tool-body-glow'
+
+function ensureDomReady() {
+  return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+function ensureStyleElement() {
+  if (!ensureDomReady()) return
+  if (styleElement) return
+
+  const style = document.createElement('style')
+  style.textContent = `
+  .${BODY_GLOW_CLASS} {
+    position: relative;
+  }
+
+  .next-sdk-tool-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 999999;
+    pointer-events: none;
+    display: flex;
+    align-items: flex-end;
+    justify-content: flex-start;
+    padding: 0 0 18px 18px;
+    background: transparent;
+    animation: next-sdk-overlay-fade-in 260ms ease-out;
+  }
+
+  .next-sdk-tool-overlay--exit {
+    animation: next-sdk-overlay-fade-out 220ms ease-in forwards;
+  }
+
+  .next-sdk-tool-overlay__glow-ring {
+    display: none;
+  }
+
+  .next-sdk-tool-overlay__panel {
+    position: relative;
+    min-width: min(320px, 78vw);
+    max-width: min(420px, 82vw);
+    padding: 10px 14px;
+    border-radius: 999px;
+    background:
+      linear-gradient(135deg, rgba(15, 23, 42, 0.9), rgba(17, 24, 39, 0.9)),
+      radial-gradient(circle at top left, rgba(96, 165, 250, 0.25), transparent 55%),
+      radial-gradient(circle at bottom right, rgba(45, 212, 191, 0.22), transparent 60%);
+    box-shadow:
+      0 12px 28px rgba(15, 23, 42, 0.78),
+      0 0 0 1px rgba(148, 163, 184, 0.26);
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    pointer-events: none;
+    transform-origin: center;
+    animation: next-sdk-panel-pop-in 260ms cubic-bezier(0.18, 0.89, 0.32, 1.28);
+    color: #e5e7eb;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+  }
+
+  .next-sdk-tool-overlay__indicator {
+    width: 26px;
+    height: 26px;
+    border-radius: 999px;
+    background: radial-gradient(circle at 30% 10%, #f9fafb, #93c5fd);
+    box-shadow:
+      0 0 0 1px rgba(191, 219, 254, 0.6),
+      0 8px 18px rgba(37, 99, 235, 0.8),
+      0 0 28px rgba(56, 189, 248, 0.9);
+    position: relative;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+  }
+
+  .next-sdk-tool-overlay__indicator-orbit {
+    position: absolute;
+    inset: 2px;
+    border-radius: inherit;
+    border: 1px solid rgba(248, 250, 252, 0.6);
+    box-sizing: border-box;
+    opacity: 0.9;
+  }
+
+  .next-sdk-tool-overlay__indicator-orbit::before {
+    content: '';
+    position: absolute;
+    width: 6px;
+    height: 6px;
+    border-radius: 999px;
+    background: #f9fafb;
+    box-shadow:
+      0 0 12px rgba(248, 250, 252, 0.9),
+      0 0 24px rgba(250, 249, 246, 0.9);
+    top: 0;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    transform-origin: 50% 18px;
+    animation: next-sdk-indicator-orbit 1.4s linear infinite;
+  }
+
+  .next-sdk-tool-overlay__indicator-core {
+    width: 14px;
+    height: 14px;
+    border-radius: inherit;
+    background: radial-gradient(circle at 30% 20%, #f9fafb, #bfdbfe);
+    box-shadow:
+      0 0 12px rgba(248, 250, 252, 0.9),
+      0 0 32px rgba(191, 219, 254, 0.8);
+    opacity: 0.96;
+  }
+
+  .next-sdk-tool-overlay__content {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+
+  .next-sdk-tool-overlay__title {
+    font-size: 11px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: rgba(156, 163, 175, 0.96);
+    display: flex;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .next-sdk-tool-overlay__title-dot {
+    width: 6px;
+    height: 6px;
+    border-radius: 999px;
+    background: #22c55e;
+    box-shadow:
+      0 0 8px rgba(34, 197, 94, 0.9),
+      0 0 14px rgba(22, 163, 74, 0.9);
+  }
+
+  .next-sdk-tool-overlay__label {
+    font-size: 12px;
+    font-weight: 500;
+    color: #e5e7eb;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    overflow: hidden;
+  }
+
+  @keyframes next-sdk-overlay-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+
+  @keyframes next-sdk-overlay-fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+
+  @keyframes next-sdk-indicator-orbit {
+    from {
+      transform: translate(-50%, -50%) rotate(0deg) translateY(0);
+    }
+    to {
+      transform: translate(-50%, -50%) rotate(360deg) translateY(0);
+    }
+  }
+
+  @keyframes next-sdk-panel-pop-in {
+    0% {
+      opacity: 0;
+      transform: scale(0.92) translateY(10px);
+    }
+    100% {
+      opacity: 1;
+      transform: scale(1) translateY(0);
+    }
+  }
+  `
+
+  document.head.appendChild(style)
+  styleElement = style
+}
+
+function ensureOverlayElement() {
+  if (!ensureDomReady()) return
+  if (overlayElement) return
+
+  ensureStyleElement()
+
+  const overlay = document.createElement('div')
+  overlay.className = 'next-sdk-tool-overlay'
+
+  const glowRing = document.createElement('div')
+  glowRing.className = 'next-sdk-tool-overlay__glow-ring'
+
+  const panel = document.createElement('div')
+  panel.className = 'next-sdk-tool-overlay__panel'
+
+  const indicator = document.createElement('div')
+  indicator.className = 'next-sdk-tool-overlay__indicator'
+
+  const indicatorOrbit = document.createElement('div')
+  indicatorOrbit.className = 'next-sdk-tool-overlay__indicator-orbit'
+
+  const indicatorCore = document.createElement('div')
+  indicatorCore.className = 'next-sdk-tool-overlay__indicator-core'
+
+  const content = document.createElement('div')
+  content.className = 'next-sdk-tool-overlay__content'
+
+  const titleRow = document.createElement('div')
+  titleRow.className = 'next-sdk-tool-overlay__title'
+  titleRow.textContent = 'AI 正在调用页面工具'
+
+  const titleDot = document.createElement('span')
+  titleDot.className = 'next-sdk-tool-overlay__title-dot'
+
+  const label = document.createElement('div')
+  label.className = 'next-sdk-tool-overlay__label'
+
+  titleRow.prepend(titleDot)
+  content.appendChild(titleRow)
+  content.appendChild(label)
+
+  indicator.appendChild(indicatorOrbit)
+  indicator.appendChild(indicatorCore)
+  panel.appendChild(indicator)
+  panel.appendChild(content)
+  overlay.appendChild(glowRing)
+  overlay.appendChild(panel)
+
+  document.body.appendChild(overlay)
+
+  overlayElement = overlay
+  labelElement = label
+}
+
+function updateOverlay(config: RuntimeEffectConfig) {
+  if (!ensureDomReady()) return
+  ensureOverlayElement()
+  if (!overlayElement || !labelElement) return
+  overlayElement.classList.remove('next-sdk-tool-overlay--exit')
+  labelElement.textContent = config.label
+}
+
+function removeOverlayWithAnimation() {
+  if (!overlayElement) return
+  overlayElement.classList.add('next-sdk-tool-overlay--exit')
+  const localOverlay = overlayElement
+  let handled = false
+  let timerId: ReturnType<typeof setTimeout> | undefined
+  const handle = () => {
+    if (handled) return
+    handled = true
+    if (timerId !== undefined) {
+      clearTimeout(timerId)
+      timerId = undefined
+    }
+    if (localOverlay.parentNode) {
+      localOverlay.parentNode.removeChild(localOverlay)
+    }
+    if (overlayElement === localOverlay) {
+      overlayElement = null
+      labelElement = null
+    }
+    localOverlay.removeEventListener('animationend', handle)
+  }
+  localOverlay.addEventListener('animationend', handle)
+  // 兜底：若 animationend 未触发（如 prefers-reduced-motion 或样式被覆盖），确保清理
+  timerId = setTimeout(handle, 500)
+}
+
+/**
+ * 在页面上显示工具调用提示效果。
+ * - 若当前已有其他工具在执行，仅更新文案，不重复创建 DOM
+ * - 会增加 activeCount 计数，需配对调用 hideToolInvokeEffect
+ */
+export function showToolInvokeEffect(config: RuntimeEffectConfig) {
+  if (!ensureDomReady()) return
+  activeCount += 1
+  updateOverlay(config)
+}
+
+/**
+ * 隐藏工具调用提示效果。
+ * - 使用引用计数：只有当所有调用结束后才真正移除 Overlay
+ */
+export function hideToolInvokeEffect() {
+  if (!ensureDomReady() || activeCount <= 0) return
+  activeCount -= 1
+  if (activeCount === 0) {
+    removeOverlayWithAnimation()
+  }
+}
+
+/**
+ * 将 RouteConfig 中的 invokeEffect 配置编译成运行时效果配置。
+ * - boolean / undefined：关闭或开启默认文案
+ * - 对象：允许自定义 label
+ */
+export function resolveRuntimeEffectConfig(
+  toolName: string,
+  toolTitle: string | undefined,
+  value: boolean | ToolInvokeEffectConfig | undefined
+): RuntimeEffectConfig | undefined {
+  if (!value) return undefined
+  const baseLabel = toolTitle || toolName
+  if (typeof value === 'boolean') {
+    return value ? { label: baseLabel } : undefined
+  }
+  return {
+    label: value.label || baseLabel
+  }
+}
+

package/remoter/createRemoter.ts

@@ -39,8 +39,8 @@ export interface FloatingBlockOptions {
 
   /** 遥控端页面地址，默认为： https://ai.opentiny.design/next-remoter */
   qrCodeUrl?: string
-  /** 被遥控页面的 sessionId, 必填 */
-  sessionId: string
+  /** 被遥控页面的 sessionId；无 sessionId 时仅显示「打开对话框」菜单，不显示二维码、识别码、遥控器链接 */
+  sessionId?: string
   /** 菜单项配置 */
   menuItems?: MenuItemConfig[]
   /** 遥控端页面地址，默认为： https://chat.opentiny.design */
@@ -52,11 +52,13 @@ export interface FloatingBlockOptions {
 // 动作类型
 export type ActionType = 'qr-code' | 'ai-chat' | 'remote-control' | 'remote-url'
 
+/** 有 sessionId 时的完整菜单；无 sessionId 时仅返回 ai-chat（不依赖会话的菜单项） */
 const getDefaultMenuItems = (options: FloatingBlockOptions): MenuItemConfig[] => {
-  return [
+  const hasSession = !!options.sessionId
+  const baseItems: MenuItemConfig[] = [
     {
       action: 'qr-code',
-      show: true,
+      show: hasSession,
       text: '扫码登录',
       desc: '使用手机遥控页面',
       icon: qrCode
@@ -70,7 +72,7 @@ const getDefaultMenuItems = (options: FloatingBlockOptions): MenuItemConfig[] =>
     },
     {
       action: 'remote-url',
-      show: true,
+      show: hasSession,
       text: `遥控器链接`,
       desc: `${options.remoteUrl}`,
       active: true,
@@ -80,14 +82,15 @@ const getDefaultMenuItems = (options: FloatingBlockOptions): MenuItemConfig[] =>
     },
     {
       action: 'remote-control',
-      show: true,
+      show: hasSession,
       text: `识别码`,
-      desc: `${options.sessionId.slice(-6)}`,
+      desc: hasSession ? `${options.sessionId!.slice(-6)}` : '',
       know: true,
       showCopyIcon: true,
       icon: scan
     }
   ]
+  return baseItems
 }
 
 class FloatingBlock {
@@ -105,10 +108,6 @@ class FloatingBlock {
   }
 
   constructor(options: FloatingBlockOptions) {
-    if (!options.sessionId) {
-      throw new Error('sessionId is required')
-    }
-
     this.options = {
       ...options,
       qrCodeUrl: options.qrCodeUrl || DEFAULT_QR_CODE_URL,
@@ -146,11 +145,16 @@ class FloatingBlock {
   }
 
   /**
-   * 合并菜单项配置
-   * @param userMenuItems 用户自定义菜单项配置
-   * @returns 合并后的菜单项配置
+   * 合并菜单项配置。
+   * - 有 sessionId：使用默认菜单 + 用户配置（可定制每一项的 show/text/icon 等）
+   * - 无 sessionId：不渲染任何下拉菜单，仅保留点击浮标打开对话框的能力
    */
   private mergeMenuItems(userMenuItems?: MenuItemConfig[]): MenuItemConfig[] {
+    // 无 sessionId：完全关闭下拉菜单（包括 ai-chat 项），只保留点击浮标触发 onShowAIChat
+    if (!this.options.sessionId) {
+      return []
+    }
+
     if (!userMenuItems) {
       return getDefaultMenuItems(this.options)
     }
@@ -161,7 +165,6 @@ class FloatingBlock {
         return {
           ...defaultItem,
           ...userItem,
-          // 确保show属性存在，默认为true
           show: userItem.show !== undefined ? userItem.show : defaultItem.show
         }
       }
@@ -354,10 +357,12 @@ class FloatingBlock {
   }
 
   private copyRemoteControl(): void {
+    if (!this.options.sessionId) return
     this.copyToClipboard(this.options.sessionId.slice(-6))
   }
 
   private copyRemoteURL(): void {
+    if (!this.options.sessionId) return
     this.copyToClipboard(this.options.remoteUrl + this.sessionPrefix + this.options.sessionId)
   }
 
@@ -417,8 +422,9 @@ class FloatingBlock {
     }, 1500)
   }
 
-  // 创建二维码弹窗
+  // 创建二维码弹窗（无 sessionId 时不展示）
   private async showQRCode(): Promise<void> {
+    if (!this.options.sessionId) return
     const qrCode = new QrCode((this.options.qrCodeUrl || '') + this.sessionPrefix + this.options.sessionId, {})
     const base64 = await qrCode.toDataURL()
     const modal = this.createModal(
@@ -906,6 +912,21 @@ class FloatingBlock {
       this.dropdownMenu.parentNode.removeChild(this.dropdownMenu)
     }
   }
+
+  // 隐藏组件
+  public hide(): void {
+    if (this.floatingBlock) {
+      this.floatingBlock.style.display = 'none'
+    }
+    this.closeDropdown()
+  }
+
+  // 显示组件
+  public show(): void {
+    if (this.floatingBlock) {
+      this.floatingBlock.style.display = 'flex'
+    }
+  }
 }
 
 // 导出组件

package/skills/index.ts

@@ -42,21 +42,42 @@ export function parseSkillFrontMatter(content: string): { name: string; descript
   return name && description ? { name, description } : null
 }
 
+/**
+ * 将 Vite import.meta.glob 得到的多种 key 格式统一为「相对 skills 根目录」的路径（如 ./calculator/SKILL.md），
+ * 以便 getSkillMdContent / getMainSkillPathByName 等能正确按 path 查找。
+ * 兼容任意引入位置：./skills/xxx、../skills/xxx、src/skills/xxx 等，取最后一个 skills/ 后的部分并加上 ./
+ */
+function normalizeSkillModuleKeys(modules: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, content] of Object.entries(modules)) {
+    const normalizedKey = key.replace(/\\/g, '/')
+    const skillsIndex = normalizedKey.lastIndexOf('skills/')
+    const relativePath = skillsIndex >= 0 ? normalizedKey.slice(skillsIndex + 7) : normalizedKey
+    const standardPath = relativePath.startsWith('./') ? relativePath : `./${relativePath}`
+    result[standardPath] = content
+  }
+  return result
+}
+
 /**
  * 获取所有「主 SKILL.md」的路径（一级子目录下的 SKILL.md）
+ * - 对传入的 modules 先做 normalize，兼容任意 import.meta.glob 写法
  */
 export function getMainSkillPaths(modules: Record<string, string>): string[] {
-  return Object.keys(modules).filter((path) => MAIN_SKILL_PATH_REG.test(path))
+  const normalized = normalizeSkillModuleKeys(modules)
+  return Object.keys(normalized).filter((path) => MAIN_SKILL_PATH_REG.test(path))
 }
 
 /**
  * 获取所有技能的概况列表（name、description、path），用于 systemPrompt 或列表展示
+ * - 内部统一对 modules 做 normalize，避免调用方关心路径细节
  */
 export function getSkillOverviews(modules: Record<string, string>): SkillMeta[] {
-  const mainPaths = getMainSkillPaths(modules)
+  const normalized = normalizeSkillModuleKeys(modules)
+  const mainPaths = Object.keys(normalized).filter((path) => MAIN_SKILL_PATH_REG.test(path))
   const list: SkillMeta[] = []
   for (const path of mainPaths) {
-    const content = modules[path]
+    const content = normalized[path]
     if (!content) continue
     const parsed = parseSkillFrontMatter(content)
     if (!parsed) continue
@@ -81,23 +102,57 @@ export function formatSkillsForSystemPrompt(skills: SkillMeta[]): string {
 
 /**
  * 获取所有已加载的技能文件路径（含主 SKILL.md 与 reference 下的 .md/.json/.xml 等）
+ * - 对 modules 做 normalize 后再返回 key 列表
  */
 export function getSkillMdPaths(modules: Record<string, string>): string[] {
-  return Object.keys(modules)
+  const normalized = normalizeSkillModuleKeys(modules)
+  return Object.keys(normalized)
 }
 
 /**
  * 根据相对路径获取某个技能文档的原始内容（支持 .md、.json、.xml 等文本格式）
+ * - 自动对 modules 做 normalize，再按 path 查找
  */
 export function getSkillMdContent(modules: Record<string, string>, path: string): string | undefined {
-  return modules[path]
+  const normalized = normalizeSkillModuleKeys(modules)
+
+  // 1. 尝试原有的严格匹配
+  const exactMatch = normalized[path]
+  if (exactMatch) return exactMatch
+
+  // 2. 降级匹配：如果严格匹配完整路径未找到
+  // 则尝试寻找后缀能够匹配上的真实文件路径。
+  // 去除开头的 '.' 或 './' 以精确匹配结尾部分的路径。
+  const suffix = path.replace(/^\.?\//, '/')
+  const matchingKey = Object.keys(normalized).find((key) => key.endsWith(suffix))
+  return matchingKey ? normalized[matchingKey] : undefined
 }
 
 /**
- * 根据技能 name 查找其主 SKILL.md 的路径（name 与目录名一致）
+ * 根据技能 name 查找其主 SKILL.md 的路径
+ * 支持匹配目录名（如 ecommerce）或 SKILL.md 内 frontmatter 定义的 name
+ * - 依赖 getMainSkillPaths，内部已做 normalize
  */
 export function getMainSkillPathByName(modules: Record<string, string>, name: string): string | undefined {
-  return getMainSkillPaths(modules).find((p) => p.startsWith(`./${name}/SKILL.md`))
+  const normalizedModules = normalizeSkillModuleKeys(modules)
+  const paths = getMainSkillPaths(normalizedModules)
+
+  // 1. 先尝试按目录名精确匹配 (兼容老逻辑)
+  const dirMatch = paths.find((p) => p.startsWith(`./${name}/SKILL.md`))
+  if (dirMatch) return dirMatch
+
+  // 2. 如果按目录名找不到，则解析内容按 frontmatter 的 name 匹配
+  for (const p of paths) {
+    const content = normalizedModules[p]
+    if (content) {
+      const parsed = parseSkillFrontMatter(content)
+      if (parsed && parsed.name === name) {
+        return p
+      }
+    }
+  }
+
+  return undefined
 }
 
 // ============ 内置工具：供 remoter 注入，替代业界 skill 中「读取文档」的操作 ============
@@ -106,32 +161,104 @@ export function getMainSkillPathByName(modules: Record<string, string>, name: st
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type SkillToolsSet = Record<string, any>
 
+// 提升为模块级常量：避免 tool() 推断 PARAMETERS 泛型时递归展开 Zod 链导致"类型实例化过深"
+const SKILL_INPUT_SCHEMA = z.object({
+  skillName: z
+    .string()
+    .optional()
+    .describe(
+      '进入某个技能的主入口名称。优先匹配技能的目录名（如 ecommerce），或者技能的中文名称（如"客户价保单创建及审核"）。'
+    ),
+  path: z
+    .string()
+    .optional()
+    .describe('你想查阅的文档的路径。如 ./calculator/SKILL.md 或从其他文档里看到的相对路径 ./reference/inventory.md。'),
+  currentPath: z
+    .string()
+    .optional()
+    .describe(
+      '你当前正在阅读的文档路径（如果有）。比如你刚刚读取了 ./ecommerce/SKILL.md，请把这个路径原样传回来，这样系统才能根据你的相对路径准确找到下一份文件。'
+    )
+})
+
 /**
  * 根据 skillMdModules 创建供 AI 调用的工具集
  * - get_skill_content: 按技能名或路径获取完整文档内容，便于大模型自动识别并加载技能
  * remoter 可将返回的 tools 合并进 extraTools 注入 agent
  */
 export function createSkillTools(modules: Record<string, string>): SkillToolsSet {
+  const normalizedModules = normalizeSkillModuleKeys(modules)
+
+  // @ts-ignore ai package 的 tool() 函数类型推断存在"类型实例化过深"的已知限制，无法正确推断包含复杂 Zod 链的 schema
   const getSkillContent = tool({
     description:
-      '根据技能名称或文档路径获取该技能的完整文档内容。传入 skillName（如 calculator）或 path（如 ./calculator/SKILL.md）。支持 .md、.json、.xml 等各类文本格式文件。',
-    inputSchema: z.object({
-      skillName: z.string().optional().describe('技能名称，与目录名一致，如 calculator'),
-      path: z.string().optional().describe('文档相对路径，如 ./calculator/SKILL.md 或 ./product-guide/reference/xxx.json')
-    }),
-    execute: (args: { skillName?: string; path?: string }) => {
-      const { skillName, path: pathArg } = args
+      '根据技能名称或文档路径获取该技能的完整文档内容。如果你想根据相对路径查阅文件，请务必同时提供你当前所在的文件路径 currentPath。',
+    inputSchema: SKILL_INPUT_SCHEMA,
+    execute: (args: { skillName?: string; path?: string; currentPath?: string }): Record<string, unknown> => {
+      const { skillName, path: pathArg, currentPath: currentPathArg } = args
       let content: string | undefined
+      let resolvedPath = ''
+
       if (pathArg) {
-        content = getSkillMdContent(modules, pathArg)
+        // 使用明确提供的当前阅读上下文作为基准路径（默认在根目录）
+        let basePathContext = '.'
+        if (currentPathArg) {
+          // 提取出当前文档所在的目录
+          // 比如 ./ecommerce/SKILL.md -> ./ecommerce
+          const lastSlashIndex = currentPathArg.lastIndexOf('/')
+          if (lastSlashIndex >= 0) {
+            basePathContext = currentPathArg.slice(0, lastSlashIndex)
+          }
+        }
+
+        // 尝试 1：按照大模型当前提供的上下文进行标准相对路径解析
+        const dummyBase = `http://localhost/${basePathContext}/`
+        const url = new URL(pathArg, dummyBase)
+        resolvedPath = '.' + url.pathname
+        content = getSkillMdContent(normalizedModules, resolvedPath)
+
+        // 尝试 2：如果大模型忘了传正确的 currentPath，或者是强行传错，做个智能根目录回退
+        if (content === undefined && (pathArg.startsWith('./') || pathArg.startsWith('../')) && currentPathArg) {
+          const baseParts = currentPathArg.split('/')
+          if (baseParts.length >= 2) {
+            const skillRoot = baseParts[1]
+            const fallbackDummyBase = `http://localhost/${skillRoot}/`
+            const fallbackUrl = new URL(pathArg, fallbackDummyBase)
+            const fallbackPath = '.' + fallbackUrl.pathname
+            content = getSkillMdContent(normalizedModules, fallbackPath)
+            if (content) {
+              resolvedPath = fallbackPath
+            }
+          }
+        }
+
+        // 尝试 3：后缀自动降级匹配修正
+        if (content && !normalizedModules[resolvedPath]) {
+          const suffix = resolvedPath.replace(/^\.?\//, '/')
+          const matchingKey = Object.keys(normalizedModules).find((key) => key.endsWith(suffix))
+          if (matchingKey) {
+            resolvedPath = matchingKey
+          }
+        }
       } else if (skillName) {
-        const mainPath = getMainSkillPathByName(modules, skillName)
-        content = mainPath ? getSkillMdContent(modules, mainPath) : undefined
+        const mainPath = getMainSkillPathByName(normalizedModules, skillName)
+        if (mainPath) {
+          resolvedPath = mainPath
+          content = getSkillMdContent(normalizedModules, mainPath)
+        }
       }
+
       if (content === undefined) {
-        return { error: '未找到对应技能文档', skillName: skillName ?? pathArg }
+        return {
+          error: '未找到对应技能文档',
+          skillName,
+          path: pathArg,
+          providedCurrentPath: currentPathArg,
+          attemptedPath: resolvedPath
+        }
       }
-      return { content, path: pathArg ?? getMainSkillPathByName(modules, skillName!) }
+
+      return { content, path: resolvedPath }
     }
   })