@vibe-forge/core 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-forge/core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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

@@ -87,10 +87,6 @@ export interface AdapterQueryOptions {
   onEvent: (event: AdapterOutputEvent) => void
 }
 
-export interface AdapterInitOptions {
-  force?: boolean
-}
-
 export interface AdapterSession {
   kill: () => void
   emit: (event: AdapterEvent) => void
@@ -99,8 +95,7 @@ export interface AdapterSession {
 
 export interface Adapter {
   init?: (
-    ctx: AdapterCtx,
-    options: AdapterInitOptions
+    ctx: AdapterCtx
   ) => Promise<void>
   query: (
     ctx: AdapterCtx,

package/src/config/types.ts

@@ -178,6 +178,12 @@ export interface Config {
      * 自定义对话风格。通过指定提示词约束对话风格。
      */
     customInstructions?: string
+    /**
+     * 是否注入 Vibe Forge 自动生成的默认系统提示词
+     * （例如 rules / skills / entities / specs 生成的提示词）。
+     * 默认为 true。
+     */
+    injectDefaultSystemPrompt?: boolean
   }
   /**
    * 插件配置

package/src/controllers/task/generate-adapter-query-options.ts

@@ -1,24 +1,122 @@
 import process from 'node:process'
+import { basename, dirname } from 'node:path'
 
 import type { AdapterQueryOptions } from '#~/adapter/type.js'
 import { DefinitionLoader } from '#~/utils/definition-loader.js'
-import type { Definition, Filter, Skill } from '#~/utils/definition-loader.js'
+import type { Definition, Entity, Filter, Skill, Spec } from '#~/utils/definition-loader.js'
+
+const filterSkills = (
+  skills: Definition<Skill>[],
+  selection?: AdapterQueryOptions['skills']
+) => {
+  if (selection == null) return skills
+
+  const include = selection.include != null && selection.include.length > 0
+    ? new Set(selection.include)
+    : undefined
+  const exclude = new Set(selection.exclude ?? [])
+
+  return skills.filter((skill) => {
+    const name = basename(dirname(skill.path))
+    return (include == null || include.has(name)) && !exclude.has(name)
+  })
+}
+
+const dedupeSkills = (skills: Definition<Skill>[]) => {
+  const seen = new Set<string>()
+  return skills.filter((skill) => {
+    if (seen.has(skill.path)) return false
+    seen.add(skill.path)
+    return true
+  })
+}
+
+type SkillSelectionInput =
+  | AdapterQueryOptions['skills']
+  | Entity['skills']
+  | Spec['skills']
+
+const toNormalizedSkillSelection = (
+  selection?: SkillSelectionInput
+): AdapterQueryOptions['skills'] | undefined => {
+  if (selection == null) return undefined
+
+  if (Array.isArray(selection)) {
+    return selection.length > 0
+      ? {
+          include: selection
+        }
+      : undefined
+  }
+
+  if ('type' in selection && Array.isArray(selection.list)) {
+    const list = selection.list.filter((item): item is string => typeof item === 'string')
+    return selection.type === 'include'
+      ? {
+          include: list
+        }
+      : {
+          exclude: list
+        }
+  }
+
+  return selection
+}
+
+const mergeSkillSelections = (
+  ...selections: Array<SkillSelectionInput | undefined>
+): AdapterQueryOptions['skills'] | undefined => {
+  let include: Set<string> | undefined
+  const exclude = new Set<string>()
+
+  for (const selection of selections) {
+    const normalized = toNormalizedSkillSelection(selection)
+    if (normalized == null) continue
+
+    if (normalized.include != null && normalized.include.length > 0) {
+      const current = new Set(normalized.include)
+      include = include == null
+        ? current
+        : new Set([...include].filter(item => current.has(item)))
+    }
+
+    for (const item of normalized.exclude ?? []) {
+      exclude.add(item)
+    }
+  }
+
+  if (include == null && exclude.size === 0) return undefined
+
+  return {
+    include: include == null ? undefined : [...include],
+    exclude: exclude.size === 0 ? undefined : [...exclude]
+  }
+}
+
+const getIncludedSkillNames = (selection?: SkillSelectionInput): string[] => {
+  const normalized = toNormalizedSkillSelection(selection)
+  return normalized?.include ?? []
+}
 
 export async function generateAdapterQueryOptions(
   type: 'spec' | 'entity' | undefined,
   name?: string,
-  cwd: string = process.cwd()
+  cwd: string = process.cwd(),
+  input?: {
+    skills?: AdapterQueryOptions['skills']
+  }
 ) {
   const loader = new DefinitionLoader(cwd)
   const options: Partial<AdapterQueryOptions> = {}
   const systemPromptParts: string[] = []
+  let effectiveSkillSelection = toNormalizedSkillSelection(input?.skills)
 
   // 1. 获取数据
   // 1.1 获取默认数据
   const entities = type !== 'entity'
     ? await loader.loadDefaultEntities()
     : []
-  const skills = await loader.loadDefaultSkills()
+  const defaultSkills = await loader.loadDefaultSkills()
   const rules = await loader.loadDefaultRules()
   const specs = await loader.loadDefaultSpecs()
 
@@ -42,7 +140,9 @@ export async function generateAdapterQueryOptions(
       // always load spec or entity tagged rules
       rules.push(
         ...(
-          await loader.loadRules(attributes.rules)
+          await loader.loadRules(attributes.rules, {
+            baseDir: dirname(data.path)
+          })
         ).map((rule) => ({
           ...rule,
           attributes: {
@@ -56,18 +156,40 @@ export async function generateAdapterQueryOptions(
     if (
       attributes.skills
     ) {
-      targetSkills.push(...await loader.loadSkills(attributes.skills))
+      effectiveSkillSelection = mergeSkillSelections(
+        input?.skills,
+        attributes.skills
+      )
+      targetSkills.push(
+        ...filterSkills(
+          await loader.loadSkills(getIncludedSkillNames(attributes.skills)),
+          effectiveSkillSelection
+        )
+      )
     }
 
     targetBody = body
     targetToolsFilter = attributes.tools
     targetMcpServersFilter = attributes.mcpServers
   }
+  const skills = filterSkills(defaultSkills, effectiveSkillSelection)
+  let selectedSkillsPrompt: Definition<Skill>[] = []
+  if (input?.skills?.include != null && input.skills.include.length > 0) {
+    selectedSkillsPrompt = dedupeSkills(
+      filterSkills(
+        await loader.loadSkills(input.skills.include),
+        effectiveSkillSelection
+      )
+    )
+  }
 
   // 2. 基于数据生成上下文
   // 2.1 加载关联上下文
   systemPromptParts.push(loader.generateRulesPrompt(rules))
-  systemPromptParts.push(loader.generateSkillsPrompt(targetSkills))
+  systemPromptParts.push(loader.generateSkillsPrompt(dedupeSkills(targetSkills)))
+  systemPromptParts.push(loader.generateSkillsPrompt(
+    selectedSkillsPrompt.filter(skill => !targetSkills.some(target => target.path === skill.path))
+  ))
   // 2.2 加载上下文路由
   systemPromptParts.push(loader.generateEntitiesRoutePrompt(entities))
   systemPromptParts.push(loader.generateSkillsRoutePrompt(skills))

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'
@@ -162,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/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

@@ -36,6 +36,25 @@ export interface Spec {
   tools?: Filter
 }
 
+export interface LocalRuleReference {
+  type?: 'local'
+  path: string
+  desc?: string
+}
+
+export interface RemoteRuleReference {
+  type: 'remote'
+  tags?: string[]
+  desc?: string
+}
+
+export type RuleReference = string | LocalRuleReference | RemoteRuleReference
+
+export interface SkillSelection {
+  type: 'include' | 'exclude'
+  list: string[]
+}
+
 export interface Entity {
   name?: string
   always?: boolean
@@ -43,8 +62,8 @@ export interface Entity {
   tags?: string[]
   prompt?: string
   promptPath?: string
-  rules?: string[]
-  skills?: string[]
+  rules?: RuleReference[]
+  skills?: string[] | SkillSelection
   mcpServers?: Filter
   tools?: Filter
 }
@@ -123,6 +142,66 @@ const resolveSpecIdentifier = (path: string, explicitName?: string) => {
   return resolveDocumentName(path, explicitName, ['index.md'])
 }
 
+const toNonEmptyStringArray = (values: unknown): string[] => {
+  if (!Array.isArray(values)) return []
+  return values
+    .filter((value): value is string => typeof value === 'string')
+    .map(value => value.trim())
+    .filter(Boolean)
+}
+
+const isLocalRuleReference = (value: RuleReference): value is LocalRuleReference => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    typeof value.path === 'string' &&
+    (value.type == null || value.type === 'local')
+  )
+}
+
+const isRemoteRuleReference = (value: RuleReference): value is RemoteRuleReference => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    value.type === 'remote'
+  )
+}
+
+const resolveRulePattern = (pattern: string, baseDir: string) => {
+  const trimmed = pattern.trim()
+  if (!trimmed) return undefined
+  if (trimmed.startsWith('./') || trimmed.startsWith('../')) {
+    return normalizePath(resolve(baseDir, trimmed))
+  }
+  return trimmed
+}
+
+const createRemoteRuleDefinition = (
+  rule: RemoteRuleReference,
+  index: number
+): Definition<Rule> => {
+  const tags = toNonEmptyStringArray(rule.tags)
+  const desc = rule.desc?.trim() || (
+    tags.length > 0
+      ? `远程知识库标签：${tags.join(', ')}`
+      : '远程知识库规则引用'
+  )
+  const bodyParts = [
+    desc,
+    tags.length > 0 ? `知识库标签：${tags.join(', ')}` : undefined,
+    '该规则来自远程知识库引用，不对应本地文件。'
+  ].filter((value): value is string => Boolean(value))
+
+  return {
+    path: `remote-rule-${index + 1}.md`,
+    body: bodyParts.join('\n'),
+    attributes: {
+      name: tags.length > 0 ? `remote:${tags.join(',')}` : `remote-rule-${index + 1}`,
+      description: desc
+    }
+  }
+}
+
 export class DefinitionLoader {
   private readonly cwd: string
 
@@ -142,10 +221,53 @@ export class DefinitionLoader {
     })
   }
 
-  async loadRules(rules: string[]) {
-    return loadLocalDocuments<Rule>(
-      await this.scan(rules)
-    )
+  async loadRules(
+    rules: RuleReference[],
+    options?: {
+      baseDir?: string
+    }
+  ) {
+    const baseDir = options?.baseDir ?? this.cwd
+    const definitions: Definition<Rule>[] = []
+
+    for (const [index, rule] of rules.entries()) {
+      if (typeof rule === 'string') {
+        const pattern = resolveRulePattern(rule, baseDir)
+        if (!pattern) continue
+        definitions.push(
+          ...await loadLocalDocuments<Rule>(
+            await this.scan([pattern])
+          )
+        )
+        continue
+      }
+
+      if (isRemoteRuleReference(rule)) {
+        definitions.push(createRemoteRuleDefinition(rule, index))
+        continue
+      }
+
+      if (!isLocalRuleReference(rule)) continue
+
+      const pattern = resolveRulePattern(rule.path, baseDir)
+      if (!pattern) continue
+
+      const docs = await loadLocalDocuments<Rule>(
+        await this.scan([pattern])
+      )
+
+      definitions.push(
+        ...docs.map((doc) => ({
+          ...doc,
+          attributes: {
+            ...doc.attributes,
+            description: rule.desc?.trim() || doc.attributes.description
+          }
+        }))
+      )
+    }
+
+    return definitions
   }
   async loadDefaultRules(): Promise<Definition<Rule>[]> {
     return this.loadRules([

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()
-}