@vibe-forge/core 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-forge/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "imports": {
     "#~/*.js": {
       "__vibe-forge__": {

package/src/adapter/index.ts

@@ -3,4 +3,4 @@ import type { Adapter } from './type'
 export * from './loader'
 export * from './type'
 
-export const defineAdapter = (adapter: Adapter) => adapter
+export const defineAdapter = <T extends Adapter>(adapter: T): Adapter => adapter

package/src/adapter/loader.ts

@@ -1,9 +1,11 @@
 import type { Adapter } from './type'
 
+const resolveAdapterPackageName = (type: string) => (
+  type.startsWith('@') ? type : `@vibe-forge/adapter-${type}`
+)
+
 export const loadAdapter = async (type: string) =>
   (
     // eslint-disable-next-line ts/no-require-imports
-    require(
-      type.startsWith('@') ? type : `@vibe-forge/adapter-${type}`
-    )
+    require(resolveAdapterPackageName(type))
   ).default as Adapter

package/src/adapter/type.ts

@@ -20,6 +20,7 @@ export type SessionInfo =
 export interface SessionInitInfo {
   uuid: string
   model: string
+  adapter?: string
   version: string
   tools: string[]
   slashCommands: string[]
@@ -86,10 +87,6 @@ export interface AdapterQueryOptions {
   onEvent: (event: AdapterOutputEvent) => void
 }
 
-export interface AdapterInitOptions {
-  force?: boolean
-}
-
 export interface AdapterSession {
   kill: () => void
   emit: (event: AdapterEvent) => void
@@ -98,8 +95,7 @@ export interface AdapterSession {
 
 export interface Adapter {
   init?: (
-    ctx: AdapterCtx,
-    options: AdapterInitOptions
+    ctx: AdapterCtx
   ) => Promise<void>
   query: (
     ctx: AdapterCtx,

package/src/channel.ts

@@ -40,6 +40,13 @@ export const channelBaseSchema = z.object({
   systemPrompt: z
     .string().optional()
     .describe('在此频道启动会话时注入的系统提示词'),
+  // 指令
+  commandPrefix: z
+    .string().optional()
+    .describe('频道指令前缀，默认 /'),
+  language: z
+    .enum(['zh', 'en']).optional()
+    .describe('频道提示语言，默认 zh'),
   // 访问权限控制
   access: channelAccessSchema
     .optional()
@@ -54,8 +61,24 @@ export type ChannelConfig = {
   [K in ChannelType]: ChannelConfigByType<K>
 }[ChannelType]
 
+export interface ChannelSendResult {
+  messageId?: string
+}
+
+export interface ChannelFollowUp {
+  content: string
+  i18nContents?: Array<{
+    content: string
+    language: string
+  }>
+}
+
 export interface ChannelConnection<TMessage> {
-  sendMessage: (message: TMessage) => Promise<void>
+  sendMessage: (message: TMessage) => Promise<ChannelSendResult | undefined>
+  pushFollowUps?: (input: {
+    messageId: string
+    followUps: readonly ChannelFollowUp[]
+  }) => Promise<void>
   startReceiving?: (options: {
     handlers: ChannelEventHandlers
   }) => Promise<void>

package/src/controllers/task/prepare.ts

@@ -6,6 +6,8 @@ import { getCache, setCache } from '@vibe-forge/core/utils/cache'
 import { createLogger } from '@vibe-forge/core/utils/create-logger'
 import { uuid } from '@vibe-forge/core/utils/uuid'
 
+import { resolveServerLogLevel } from '#~/env.js'
+
 import type { RunTaskOptions } from './type'
 
 export const prepare = async (
@@ -36,7 +38,13 @@ export const prepare = async (
     // 移除 NODE_OPTIONS 环境变量，防止干扰子进程的运行环境
     NODE_OPTIONS: undefined
   }
-  const logger = createLogger(cwd, ctxId, sessionId, env?.LOG_PREFIX ?? '')
+  const logger = createLogger(
+    cwd,
+    ctxId,
+    sessionId,
+    env?.LOG_PREFIX ?? '',
+    resolveServerLogLevel(env)
+  )
 
   const jsonVariables: Record<string, string | null | undefined> = {
     ...env,

package/src/controllers/task/run.ts

@@ -1,8 +1,8 @@
 import type { AdapterCtx, AdapterOutputEvent, AdapterQueryOptions } from '#~/adapter/index.js'
 import { loadAdapter } from '#~/adapter/index.js'
 import type { ModelServiceConfig } from '#~/config.js'
+import { callHook } from '#~/hooks/call.js'
 import type { TaskDetail } from '#~/types.js'
-import { callHook } from '#~/utils/api.js'
 
 import { prepare } from './prepare'
 import type { RunTaskOptions } from './type'
@@ -129,6 +129,17 @@ export const run = async (
 
   const originalOnEvent = adapterOptions.onEvent
   const wrappedOnEvent = (event: AdapterOutputEvent) => {
+    if (event.type === 'init') {
+      originalOnEvent({
+        ...event,
+        data: {
+          ...event.data,
+          adapter: adapterType
+        }
+      })
+      return
+    }
+
     if (event.type === 'exit') {
       const { data } = event
 
@@ -151,6 +162,8 @@ export const run = async (
   }
 
   const adapter = await loadAdapter(adapterType)
+  await adapter.init?.(ctx)
+
   const resolvedModel = resolveQueryModel({
     config,
     userConfig,

package/src/env.ts

@@ -1,18 +1,45 @@
 import { env as processEnv } from 'node:process'
 
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
 export interface ServerEnv {
   __VF_PROJECT_AI_SERVER_HOST__: string
   __VF_PROJECT_AI_SERVER_PORT__: number
   __VF_PROJECT_AI_SERVER_WS_PATH__: string
   __VF_PROJECT_AI_SERVER_DATA_DIR__: string
   __VF_PROJECT_AI_SERVER_LOG_DIR__: string
-  __VF_PROJECT_AI_SERVER_LOG_LEVEL__: 'debug' | 'info' | 'warn' | 'error'
+  __VF_PROJECT_AI_SERVER_LOG_LEVEL__: LogLevel
+  __VF_PROJECT_AI_SERVER_DEBUG__: boolean
   __VF_PROJECT_AI_SERVER_ALLOW_CORS__: boolean
   __VF_PROJECT_AI_CLIENT_MODE__?: 'dev' | 'static'
   __VF_PROJECT_AI_CLIENT_BASE__?: string
   __VF_PROJECT_AI_CLIENT_DIST_PATH__?: string
 }
 
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'] as const satisfies readonly LogLevel[]
+
+export function normalizeLogLevel(value: unknown): LogLevel | undefined {
+  if (typeof value !== 'string') return undefined
+  const normalized = value.trim().toLowerCase()
+  return LOG_LEVELS.includes(normalized as LogLevel)
+    ? normalized as LogLevel
+    : undefined
+}
+
+export function resolveServerLogLevel(
+  env: {
+    __VF_PROJECT_AI_SERVER_LOG_LEVEL__?: unknown
+    __VF_PROJECT_AI_SERVER_DEBUG__?: unknown
+  },
+  fallback: LogLevel = 'info'
+): LogLevel {
+  if (env.__VF_PROJECT_AI_SERVER_DEBUG__ === true || env.__VF_PROJECT_AI_SERVER_DEBUG__ === 'true') {
+    return 'debug'
+  }
+
+  return normalizeLogLevel(env.__VF_PROJECT_AI_SERVER_LOG_LEVEL__) ?? fallback
+}
+
 export function loadEnv(): ServerEnv {
   const {
     __VF_PROJECT_AI_SERVER_HOST__ = 'localhost',
@@ -21,6 +48,7 @@ export function loadEnv(): ServerEnv {
     __VF_PROJECT_AI_SERVER_DATA_DIR__ = '.data',
     __VF_PROJECT_AI_SERVER_LOG_DIR__ = '.logs',
     __VF_PROJECT_AI_SERVER_LOG_LEVEL__ = 'info',
+    __VF_PROJECT_AI_SERVER_DEBUG__,
     __VF_PROJECT_AI_SERVER_ALLOW_CORS__,
     __VF_PROJECT_AI_CLIENT_MODE__ = 'static',
     __VF_PROJECT_AI_CLIENT_BASE__,
@@ -32,8 +60,8 @@ export function loadEnv(): ServerEnv {
     __VF_PROJECT_AI_SERVER_WS_PATH__,
     __VF_PROJECT_AI_SERVER_DATA_DIR__,
     __VF_PROJECT_AI_SERVER_LOG_DIR__,
-    __VF_PROJECT_AI_SERVER_LOG_LEVEL__:
-      __VF_PROJECT_AI_SERVER_LOG_LEVEL__ as ServerEnv['__VF_PROJECT_AI_SERVER_LOG_LEVEL__'],
+    __VF_PROJECT_AI_SERVER_LOG_LEVEL__: normalizeLogLevel(__VF_PROJECT_AI_SERVER_LOG_LEVEL__) ?? 'info',
+    __VF_PROJECT_AI_SERVER_DEBUG__: __VF_PROJECT_AI_SERVER_DEBUG__ === 'true',
     __VF_PROJECT_AI_SERVER_ALLOW_CORS__: __VF_PROJECT_AI_SERVER_ALLOW_CORS__ != null
       ? __VF_PROJECT_AI_SERVER_ALLOW_CORS__ === 'true'
       : true,

package/src/hooks/call.ts

@@ -0,0 +1,74 @@
+import { Buffer } from 'node:buffer'
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import process from 'node:process'
+
+import type { HookInputs, HookOutputs } from './type'
+
+export type HookEventName = keyof HookInputs
+
+type HookInputPayload<K extends HookEventName> = Omit<HookInputs[K], 'hookEventName'>
+
+const pickHookEnv = (env: Record<string, unknown>): Record<string, string> => {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === 'string') {
+      result[key] = value
+    }
+  }
+  return result
+}
+
+const resolveHookCliJs = () => {
+  try {
+    const pkgJsonPath = require.resolve('@vibe-forge/cli/package.json')
+    return path.resolve(path.dirname(pkgJsonPath), 'call-hook.js')
+  } catch (error) {
+    throw new Error('Failed to resolve @vibe-forge/cli hook entry', { cause: error })
+  }
+}
+
+export const callHook = async <K extends HookEventName>(
+  hookEventName: K,
+  input: HookInputPayload<K>,
+  env: Record<string, unknown> = process.env
+): Promise<HookOutputs[K]> => {
+  const childEnv = pickHookEnv(env)
+  const child = spawn(process.execPath, [resolveHookCliJs()], {
+    cwd: typeof input.cwd === 'string' ? input.cwd : process.cwd(),
+    env: childEnv,
+    stdio: ['pipe', 'pipe', 'pipe']
+  })
+
+  const stdoutChunks: Buffer[] = []
+  const stderrChunks: Buffer[] = []
+
+  child.stdout.on('data', chunk => stdoutChunks.push(chunk))
+  child.stderr.on('data', chunk => stderrChunks.push(chunk))
+
+  const exitCode = await new Promise<number>((resolve, reject) => {
+    child.once('error', reject)
+    child.once('close', code => resolve(code ?? 0))
+    child.stdin.end(JSON.stringify({
+      ...input,
+      hookEventName
+    }))
+  })
+
+  const stdout = Buffer.concat(stdoutChunks).toString('utf-8').trim()
+  const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim()
+
+  if (exitCode !== 0) {
+    throw new Error(`Failed to call hook: process exited with code ${exitCode}${stderr ? ` - ${stderr}` : ''}`)
+  }
+
+  if (stdout === '') {
+    return { continue: true } as HookOutputs[K]
+  }
+
+  try {
+    return JSON.parse(stdout) as HookOutputs[K]
+  } catch (error) {
+    throw new Error(`Failed to parse hook output: ${stdout}${stderr ? `\nstderr: ${stderr}` : ''}`, { cause: error })
+  }
+}

package/src/hooks/index.ts

@@ -33,5 +33,7 @@ export type PluginConfig =
   | Record<string, Record<string, unknown>>
   | Partial<PluginMap>
 
+export * from './call'
 export * from './loader'
+export * from './runtime'
 export * from './type'

package/src/hooks/runtime.ts

@@ -0,0 +1,139 @@
+import { Buffer } from 'node:buffer'
+import process from 'node:process'
+
+import { loadConfig, resetConfigCache } from '#~/config/load.js'
+import { resolveServerLogLevel } from '#~/env.js'
+import { createLogger } from '#~/utils/create-logger.js'
+import { transformCamelKey } from '#~/utils/string-transform.js'
+
+import type { HookInput, HookInputs, HookOutputCore, HookOutputs } from './type'
+import type { HookContext, Plugin } from './index'
+import { resolvePlugins } from './loader'
+
+export const callPluginHook = async <K extends keyof HookInputs>(
+  eventName: K,
+  context: HookContext,
+  input: HookInputs[K],
+  plugins: Partial<Plugin>[] = []
+): Promise<HookOutputs[K]> => {
+  const { logger } = context
+  const filteredPlugins = plugins.filter(
+    (
+      item
+    ): item is
+      & {
+        name?: string
+      }
+      & {
+        [P in K]: NonNullable<Plugin[P]>
+      } => !!item && !!item[eventName]
+  )
+
+  let index = 0
+
+  const next = async (): Promise<HookOutputs[K]> => {
+    if (index >= filteredPlugins.length) {
+      return { continue: true }
+    }
+
+    const currentPlugin = filteredPlugins[index]
+    const { name = '<anonymous>', [eventName]: hook } = currentPlugin
+    index++
+
+    const withNameLogger = {
+      ...logger,
+      info: logger.info.bind(logger, `[plugin.${name}]`),
+      warn: logger.warn.bind(logger, `[plugin.${name}]`),
+      debug: logger.debug.bind(logger, `[plugin.${name}]`),
+      error: logger.error.bind(logger, `[plugin.${name}]`)
+    }
+
+    try {
+      return await hook(
+        {
+          ...context,
+          logger: withNameLogger
+        },
+        input,
+        next
+      )
+    } catch (error) {
+      if (error instanceof Error && !error.name.includes('[plugin.')) {
+        error.name = `${error.name}[plugin.${name}]`
+      }
+      throw error
+    }
+  }
+
+  return next()
+}
+
+export const executeHookInput = async (
+  input: HookInput,
+  env: Record<string, string | null | undefined> = process.env
+) => {
+  const workspaceFolder = env.__VF_PROJECT_WORKSPACE_FOLDER__ ?? input.cwd ?? process.env.HOME ?? '/'
+  const ctxId = env.__VF_PROJECT_AI_CTX_ID__ ?? input.sessionId ?? 'default'
+  const logPrefix = env.__VF_PROJECT_AI_LOG_PREFIX__ ?? ''
+  const loggerBase = createLogger(
+    workspaceFolder,
+    ctxId,
+    input.sessionId,
+    logPrefix,
+    resolveServerLogLevel(env)
+  )
+
+  const logger: typeof loggerBase = {
+    ...loggerBase,
+    info: (...args) => loggerBase.info(`[${input.hookEventName}]`, ...args),
+    warn: (...args) => loggerBase.warn(`[${input.hookEventName}]`, ...args),
+    debug: (...args) => loggerBase.debug(`[${input.hookEventName}]`, ...args),
+    error: (...args) => loggerBase.error(`[${input.hookEventName}]`, ...args)
+  }
+
+  resetConfigCache()
+  const jsonVariables = {
+    ...env,
+    WORKSPACE_FOLDER: workspaceFolder,
+    __VF_PROJECT_WORKSPACE_FOLDER__: workspaceFolder
+  }
+  const [config, userConfig] = await loadConfig({ jsonVariables })
+  const plugins = [
+    ...await resolvePlugins(config?.plugins ?? []),
+    ...await resolvePlugins(userConfig?.plugins ?? [])
+  ]
+
+  return callPluginHook(
+    input.hookEventName,
+    { logger },
+    input as HookInputs[typeof input.hookEventName],
+    plugins
+  )
+}
+
+export const readHookInput = async () => {
+  const stdoutBuffer = await new Promise<Buffer>((resolve) => {
+    const chunks: Buffer[] = []
+    process.stdin.on('data', chunk => chunks.push(chunk))
+    process.stdin.once('end', () => resolve(Buffer.concat(chunks)))
+  })
+
+  return transformCamelKey<HookInput>(
+    JSON.parse(stdoutBuffer.toString() || '{}')
+  )
+}
+
+export const runHookCli = async () => {
+  try {
+    const input = await readHookInput()
+    const result = await executeHookInput(input)
+    console.log(JSON.stringify(result))
+  } catch (error) {
+    console.log(
+      JSON.stringify({
+        continue: false,
+        stopReason: `run hook error: ${String(error)}`
+      } satisfies HookOutputCore)
+    )
+  }
+}

package/src/types.ts

@@ -9,6 +9,8 @@ export interface Project {
 
 export type SessionStatus = 'running' | 'completed' | 'failed' | 'terminated' | 'waiting_input'
 
+export type SessionPermissionMode = 'default' | 'acceptEdits' | 'plan' | 'dontAsk' | 'bypassPermissions'
+
 export interface Session {
   id: string
   parentSessionId?: string
@@ -21,6 +23,9 @@ export interface Session {
   isArchived?: boolean
   tags?: string[]
   status?: SessionStatus
+  model?: string
+  adapter?: string
+  permissionMode?: SessionPermissionMode
 }
 
 export type ChatMessageContent =

package/src/utils/cache.ts

@@ -46,6 +46,13 @@ export const getCache = async <K extends keyof Cache>(
   key: K
 ): Promise<Cache[K] | undefined> => {
   const cachePath = getCachePath(cwd, taskId, sessionId, key)
-  await fs.access(cachePath)
+  try {
+    await fs.access(cachePath)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined
+    }
+    throw error
+  }
   return JSON.parse(await fs.readFile(cachePath, 'utf-8'))
 }

package/src/utils/create-logger.ts

@@ -1,6 +1,8 @@
 import { createWriteStream, existsSync, mkdirSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 
+import type { LogLevel } from '#~/env.js'
+
 export interface Logger {
   stream: NodeJS.WritableStream
   info: (...args: unknown[]) => void
@@ -9,19 +11,29 @@ export interface Logger {
   error: (...args: unknown[]) => void
 }
 
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+}
+
 export const createLogger = (
   cwd: string,
   taskId: string,
   sessionId: string,
-  logPrefix = ''
+  logPrefix = '',
+  level: LogLevel = 'info'
 ) => {
-  const date = new Date()
-  // 以 年-月-日-小时 作为一级目录名
-  const dateDir = `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}-${date.getHours()}`
+  const normalizedSessionId = sessionId ?? 'default'
+  const taskDir = resolve(
+    cwd,
+    `.ai${logPrefix}/logs/${taskId}`
+  )
 
   const loggerFilePath = resolve(
-    cwd,
-    `.ai${logPrefix}/logs/${taskId}/${dateDir}/${sessionId ?? 'default'}.log.md`
+    taskDir,
+    `${normalizedSessionId}.log.md`
   )
   // 默认日志文件不存在时，创建一个默认的日志文件
   if (!existsSync(loggerFilePath)) {
@@ -30,7 +42,10 @@ export const createLogger = (
   const loggerStream = createWriteStream(loggerFilePath, {
     flags: 'a'
   })
-  const createLog = (tag: string) => (...args: unknown[]) => {
+  const createLog = (tag: string, currentLevel: LogLevel) => (...args: unknown[]) => {
+    if (LOG_LEVEL_PRIORITY[currentLevel] < LOG_LEVEL_PRIORITY[level]) {
+      return
+    }
     const msg = args
       .map((arg) => {
         if (typeof arg === 'string') {
@@ -66,9 +81,9 @@ export const createLogger = (
   }
   return {
     stream: loggerStream,
-    info: createLog('I'),
-    warn: createLog('W'),
-    debug: createLog('D'),
-    error: createLog('E')
+    info: createLog('I', 'info'),
+    warn: createLog('W', 'warn'),
+    debug: createLog('D', 'debug'),
+    error: createLog('E', 'error')
   }
 }

package/src/utils/definition-loader.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { basename, dirname, join, relative, resolve } from 'node:path'
+import { basename, dirname, relative, resolve } from 'node:path'
 import process from 'node:process'
 
 import { glob } from 'fast-glob'
@@ -79,6 +79,50 @@ export const loadLocalDocuments = async <Attrs extends object>(
   return Promise.all(promises)
 }
 
+const normalizePath = (path: string) => path.split('\\').join('/')
+
+const stripExtension = (fileName: string) => fileName.replace(/\.[^/.]+$/, '')
+
+const getFirstNonEmptyLine = (text: string) =>
+  text
+    .split('\n')
+    .map(line => line.trim())
+    .find(Boolean)
+
+const toPromptPath = (cwd: string, path: string) => {
+  const relPath = normalizePath(relative(cwd, path))
+  return relPath.startsWith('..') ? normalizePath(path) : relPath
+}
+
+const resolveDocumentName = (
+  path: string,
+  explicitName?: string,
+  indexFileNames: string[] = []
+) => {
+  const trimmedName = explicitName?.trim()
+  if (trimmedName) return trimmedName
+
+  const fileName = basename(path).toLowerCase()
+  if (indexFileNames.includes(fileName)) {
+    return basename(dirname(path))
+  }
+
+  return stripExtension(basename(path))
+}
+
+const resolveDocumentDescription = (
+  body: string,
+  explicitDescription?: string,
+  fallbackName?: string
+) => {
+  const trimmedDescription = explicitDescription?.trim()
+  return trimmedDescription || getFirstNonEmptyLine(body) || fallbackName || ''
+}
+
+const resolveSpecIdentifier = (path: string, explicitName?: string) => {
+  return resolveDocumentName(path, explicitName, ['index.md'])
+}
+
 export class DefinitionLoader {
   private readonly cwd: string
 
@@ -113,13 +157,12 @@ export class DefinitionLoader {
     const rulesPrompt = rules
       .map((rule) => {
         const { path, body, attributes } = rule
-        const name = attributes.name ?? basename(path)
-        const desc = attributes.description ?? name
-        return (
-          `  - ${name}：${desc}\n` +
-          `${attributes.always ? body : ''}\n` +
-          '--------------------\n'
-        )
+        const name = resolveDocumentName(path, attributes.name)
+        const desc = resolveDocumentDescription(body, attributes.description, name)
+        const content = attributes.always && body.trim()
+          ? `<rule-content>\n${body.trim()}\n</rule-content>\n`
+          : ''
+        return `  - ${name}：${desc}\n${content}--------------------\n`
       })
       .filter(Boolean)
       .join('\n')
@@ -150,9 +193,7 @@ export class DefinitionLoader {
     // Filter by directory name (skill name)
     if (skills) {
       paths = paths.filter(path => {
-        const parts = path.split('/')
-        // .../skills/{name}/SKILL.md
-        return skills.includes(parts[parts.length - 2])
+        return skills.includes(basename(dirname(path)))
       })
     }
 
@@ -164,13 +205,17 @@ export class DefinitionLoader {
   generateSkillsPrompt(skills: Definition<Skill>[]): string {
     return skills
       .map((skill) => {
-        const { path, body } = skill
+        const { path, body, attributes } = skill
+        const name = resolveDocumentName(path, attributes.name, ['skill.md'])
+        const desc = resolveDocumentDescription(body, attributes.description, name)
         return (
           '技能相关信息如下，通过阅读以下内容了解技能的详细信息：\n' +
-          `- 技能文件资源路径：${dirname(path)}\n` +
+          `- 技能名称：${name}\n` +
+          `- 技能介绍：${desc}\n` +
+          `- 技能文件资源路径：${toPromptPath(this.cwd, dirname(path))}\n` +
           '- 资源内容：\n' +
           '<skill-content>\n' +
-          `${body}\n` +
+          `${body.trim()}\n` +
           '</skill-content>\n' +
           '资源内容中的文件路径相对「技能文件资源路径」路径，通过读取相关工具按照实际需要进行阅读。\n'
         )
@@ -185,7 +230,11 @@ export class DefinitionLoader {
         skills
           .filter(({ attributes: { always } }) => always !== false)
           .map(
-            ({ attributes: { name, description } }) => `  - ${name}：${description}\n`
+            ({ path, body, attributes }) => {
+              const name = resolveDocumentName(path, attributes.name, ['skill.md'])
+              const desc = resolveDocumentDescription(body, attributes.description, name)
+              return `  - ${name}：${desc}\n`
+            }
           )
           .join('')
       }\n` +
@@ -197,7 +246,8 @@ export class DefinitionLoader {
     const patterns = [
       `.ai/specs/${name}.md`,
       `.ai/specs/${name}/index.md`,
-      `.ai/plugins/*/specs/${name}.md`
+      `.ai/plugins/*/specs/${name}.md`,
+      `.ai/plugins/*/specs/${name}/index.md`
     ]
     const paths = await this.scan(patterns)
     if (paths.length === 0) return undefined
@@ -221,34 +271,23 @@ export class DefinitionLoader {
   generateSpecRoutePrompt(specsDocuments: Definition<Spec>[]): string {
     const specsRouteStr = specsDocuments
       .filter(({ attributes }) => attributes.always !== false)
-      .map(({ path, attributes }) => {
-        const name = attributes.name ?? basename(dirname(path))
-        const desc = attributes.description ?? name
+      .map(({ path, body, attributes }) => {
+        const name = resolveDocumentName(path, attributes.name, ['index.md'])
+        const desc = resolveDocumentDescription(body, attributes.description, name)
+        const identifier = resolveSpecIdentifier(path, attributes.name)
         const params = attributes.params ?? []
-        // Calculate relative path for display/ID
-        // User code used relative('.ai/specs', path), but here path is absolute.
-        // We can try to make it relative to cwd/.ai/specs if possible, or just relative to cwd.
-        // The user code seems to assume specs are in .ai/specs.
-        // Let's use relative(join(this.cwd, '.ai/specs'), path) if it's in there, otherwise...
-        // Actually, just providing a relative path from project root is probably fine or the name.
-        // User code: relative('.ai/specs', path)
-
-        let relPath = relative(join(this.cwd, '.ai/specs'), path)
-        if (relPath.startsWith('..')) {
-          // Maybe in a plugin?
-          relPath = relative(this.cwd, path)
-        }
+        const paramsPrompt = params.length > 0
+          ? params
+            .map(({ name, description }) => `    - ${name}：${description ?? '无'}\n`)
+            .join('')
+          : '    - 无\n'
 
         return (
           `- 流程名称：${name}\n` +
           `  - 介绍：${desc}\n` +
-          `  - 标识：${relPath}\n` +
+          `  - 标识：${identifier}\n` +
           '  - 参数：\n' +
-          `${
-            params
-              .map(({ name, description }) => `    - ${name}：${description}\n`)
-              .join('')
-          }\n`
+          `${paramsPrompt}`
         )
       })
       .join('\n')
@@ -285,7 +324,9 @@ export class DefinitionLoader {
 
     // 2. Fallback to Markdown file
     const patterns = [
+      `.ai/entities/${name}.md`,
       `.ai/entities/${name}/README.md`,
+      `.ai/plugins/*/entities/${name}.md`,
       `.ai/plugins/*/entities/${name}/README.md`
     ]
     const paths = await this.scan(patterns)
@@ -327,7 +368,9 @@ export class DefinitionLoader {
     // List both .md and index.json entities
     const mdPatterns = [
       '.ai/entities/*.md',
-      '.ai/plugins/*/entities/*.md'
+      '.ai/entities/*/README.md',
+      '.ai/plugins/*/entities/*.md',
+      '.ai/plugins/*/entities/*/README.md'
     ]
     const jsonPatterns = [
       '.ai/entities/*/index.json',
@@ -350,7 +393,12 @@ export class DefinitionLoader {
       '项目存在如下实体：\n' +
       `${
         entities
-          .map(({ attributes: { name, prompt: _p }, body }) => `  - ${name}：${body}\n`)
+          .filter(({ attributes }) => attributes.always !== false)
+          .map(({ path, attributes, body }) => {
+            const name = resolveDocumentName(path, attributes.name, ['readme.md', 'index.json'])
+            const desc = resolveDocumentDescription(body, attributes.description, name)
+            return `  - ${name}：${desc}\n`
+          })
           .join('')
       }\n` +
       '解决用户问题时，需根据用户需求可以通过 run-tasks 工具指定为实体后，自行调度多个不同类型的实体来完成工作。\n' +

package/src/utils/api.ts

@@ -1,32 +0,0 @@
-import process from 'node:process'
-
-import type { HookInputs, HookOutputs } from '#~/hooks/type.js'
-
-export type HookEventName = keyof HookInputs
-
-type HookInputPayload<K extends HookEventName> = Omit<HookInputs[K], 'hookEventName'>
-
-const host = process.env.__VF_PROJECT_AI_SERVER_HOST__ ?? 'localhost'
-const port = process.env.__VF_PROJECT_AI_SERVER_PORT__ ?? '8787'
-const baseUrl = `http://${host}:${port}`
-
-export const callHook = async <K extends HookEventName>(
-  hookEventName: K,
-  input: HookInputPayload<K>,
-  env: Record<string, unknown> = process.env
-): Promise<HookOutputs[K]> => {
-  const response = await fetch(`${baseUrl}/api/hooks/call`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      hookEventName,
-      input,
-      env
-    })
-  })
-  if (!response.ok) {
-    const errorText = await response.text()
-    throw new Error(`Failed to call hook: ${response.statusText} - ${errorText}`)
-  }
-  return response.json()
-}