@spaceflow/review 0.80.0 → 0.81.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.80.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.79.0...@spaceflow/review@0.80.0) (2026-04-08)
+
+### 新特性
+
+* **review:** 在 review.md 中补充 `-f` 模式忽略 `includes` 过滤的说明,新增测试用例验证直接文件模式下的过滤行为 ([9c15284](https://github.com/Lydanne/spaceflow/commit/9c1528486f93b89442ba6eea4d1cb4503be5f6c7))
+
+### 其他修改
+
+* **review-summary:** released version 0.48.0 [no ci] ([71629d2](https://github.com/Lydanne/spaceflow/commit/71629d27024b4c27c5bbe8564a2b87d45548882d))
+
 ## [0.79.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.78.0...@spaceflow/review@0.79.0) (2026-04-08)
 
 ### 新特性

package/dist/index.js

@@ -1,8 +1,8 @@
 import { LlmJsonPut, REVIEW_STATE, addLocaleResources, calculateNewLineNumber, createStreamLoggerState, defineExtension, logStreamEvent, normalizeVerbose, parallel, parseChangedLinesFromPatch, parseDiffText, parseHunksFromPatch, parseRepoUrl, parseVerbose, shouldLog, t, z } from "@spaceflow/core";
-import { access, mkdir, readFile, readdir, writeFile } from "fs/promises";
+import { access, mkdir, readFile, readdir, unlink, writeFile } from "fs/promises";
 import { basename, dirname, extname, isAbsolute, join, normalize, relative } from "path";
 import { homedir } from "os";
-import { execSync, spawn } from "child_process";
+import { execFileSync, execSync, spawn } from "child_process";
 import micromatch_0 from "micromatch";
 import { existsSync } from "fs";
 var __webpack_modules__ = ({});
@@ -332,12 +332,19 @@ const CODE_BLOCK_TYPES = [
 
 
 
-/** 远程规则缓存 TTL（毫秒），默认 5 分钟 */ const REMOTE_SPEC_CACHE_TTL = 5 * 60 * 1000;
 class ReviewSpecService {
     gitProvider;
     constructor(gitProvider){
         this.gitProvider = gitProvider;
     }
+    normalizeServerUrl(url) {
+        return url.trim().replace(/\/+$/, "");
+    }
+    logVerbose(verbose, level, message) {
+        if (shouldLog(verbose, level)) {
+            console.log(message);
+        }
+    }
     /**
    * 检查规则 ID 是否匹配（精确匹配或前缀匹配）
    * 例如: "JsTs.FileName" 匹配 "JsTs.FileName" 和 "JsTs.FileName.UpperCamel"
@@ -414,54 +421,219 @@ class ReviewSpecService {
         }
         return specs;
     }
-    async resolveSpecSources(sources) {
+    async resolveSpecSources(sources, verbose) {
         const dirs = [];
         for (const source of sources){
-            // 优先尝试解析为远程仓库 URL（浏览器复制的链接）
+            this.logVerbose(verbose, 3, `   🔎 规则来源: ${source}`);
             const repoRef = parseRepoUrl(source);
+            if (repoRef) {
+                this.logVerbose(verbose, 3, `      解析远程仓库: ${repoRef.serverUrl}/${repoRef.owner}/${repoRef.repo} path=${repoRef.path || "(root)"} ref=${repoRef.ref || "(default)"}`);
+            } else {
+                this.logVerbose(verbose, 3, `      非仓库 URL，按本地目录处理`);
+            }
             if (repoRef && this.gitProvider) {
-                const dir = await this.fetchRemoteSpecs(repoRef);
+                this.logVerbose(verbose, 3, `      尝试方式 #1: Git Provider API`);
+                const dir = await this.fetchRemoteSpecs(repoRef, verbose);
                 if (dir) {
                     dirs.push(dir);
+                    this.logVerbose(verbose, 2, `      ✅ 采用方式: Git Provider API -> ${dir}`);
                     continue;
                 }
+                this.logVerbose(verbose, 3, `      ❌ Git Provider API 未获取到规则，继续尝试`);
+            }
+            if (repoRef) {
+                this.logVerbose(verbose, 3, `      尝试方式 #2: tea api`);
+                const teaDir = await this.fetchRemoteSpecsViaTea(repoRef, verbose);
+                if (teaDir) {
+                    dirs.push(teaDir);
+                    this.logVerbose(verbose, 2, `      ✅ 采用方式: tea api -> ${teaDir}`);
+                    continue;
+                }
+                this.logVerbose(verbose, 3, `      ❌ tea api 未获取到规则，继续尝试`);
+            }
+            // API 拉取失败或未配置 provider 时，回退到 git clone（使用仓库根 URL，而非目录 URL）
+            if (repoRef) {
+                this.logVerbose(verbose, 3, `      尝试方式 #3: git clone 回退`);
+                const fallbackCloneUrl = this.buildRepoCloneUrl(repoRef);
+                this.logVerbose(verbose, 3, `         clone URL: ${fallbackCloneUrl}`);
+                const fallbackDir = await this.cloneSpecRepo(fallbackCloneUrl, repoRef.path, verbose);
+                if (fallbackDir) {
+                    dirs.push(fallbackDir);
+                    this.logVerbose(verbose, 2, `      ✅ 采用方式: git clone 回退 -> ${fallbackDir}`);
+                    continue;
+                }
+                this.logVerbose(verbose, 3, `      ❌ git clone 回退失败`);
             }
             if (this.isRepoUrl(source)) {
-                const dir = await this.cloneSpecRepo(source);
+                this.logVerbose(verbose, 3, `      尝试方式 #4: 直接 clone 来源 URL`);
+                const dir = await this.cloneSpecRepo(source, undefined, verbose);
                 if (dir) {
                     dirs.push(dir);
+                    this.logVerbose(verbose, 2, `      ✅ 采用方式: 直接 clone 来源 URL -> ${dir}`);
+                } else {
+                    this.logVerbose(verbose, 3, `      ❌ 直接 clone 来源 URL 失败`);
                 }
             } else {
                 // 检查是否是 deps 目录，如果是则扫描子目录的 references
                 const resolvedDirs = await this.resolveDepsDir(source);
                 dirs.push(...resolvedDirs);
+                this.logVerbose(verbose, 3, `      deps 目录解析结果: ${resolvedDirs.length > 0 ? resolvedDirs.join(", ") : "(空)"}`);
             }
         }
         return dirs;
     }
-    /**
-   * 通过 Git API 从远程仓库拉取规则文件
-   * 缓存到 ~/.spaceflow/review-spec-cache/ 目录，带 TTL
-   */ async fetchRemoteSpecs(ref) {
-        const cacheKey = `${ref.owner}__${ref.repo}${ref.path ? `__${ref.path.replace(/\//g, "_")}` : ""}${ref.ref ? `@${ref.ref}` : ""}`;
-        const cacheDir = join(homedir(), ".spaceflow", "review-spec-cache", cacheKey);
-        // 检查缓存是否有效（非 CI 环境下使用 TTL）
-        const isCI = !!process.env.CI;
-        if (!isCI) {
-            try {
-                const timestampFile = join(cacheDir, ".timestamp");
-                const timestamp = await readFile(timestampFile, "utf-8");
-                const age = Date.now() - Number(timestamp);
-                if (age < REMOTE_SPEC_CACHE_TTL) {
-                    const entries = await readdir(cacheDir);
-                    if (entries.some((f)=>f.endsWith(".md"))) {
-                        return cacheDir;
-                    }
+    buildRemoteSpecDir(ref) {
+        const dirKey = `${ref.owner}__${ref.repo}${ref.path ? `__${ref.path.replace(/\//g, "_")}` : ""}${ref.ref ? `@${ref.ref}` : ""}`;
+        return join(homedir(), ".spaceflow", "review-spec", dirKey);
+    }
+    async getLocalSpecsDir(dir) {
+        try {
+            const entries = await readdir(dir);
+            if (!entries.some((f)=>f.endsWith(".md"))) {
+                return null;
+            }
+            return dir;
+        } catch  {
+            return null;
+        }
+    }
+    async prepareRemoteSpecDirForWrite(dir) {
+        await mkdir(dir, {
+            recursive: true
+        });
+        try {
+            const entries = await readdir(dir);
+            for (const name of entries){
+                if (name.endsWith(".md") || name === ".timestamp") {
+                    await unlink(join(dir, name));
                 }
-            } catch  {
-            // 缓存不存在或无效，继续拉取
             }
+        } catch  {
+        // 忽略目录清理失败，后续写入时再处理
+        }
+    }
+    isTeaInstalled() {
+        try {
+            execSync("command -v tea", {
+                stdio: "pipe"
+            });
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    getTeaLoginForServer(serverUrl) {
+        try {
+            const output = execFileSync("tea", [
+                "login",
+                "list",
+                "-o",
+                "json"
+            ], {
+                encoding: "utf-8",
+                stdio: "pipe"
+            });
+            const normalizedServerUrl = this.normalizeServerUrl(serverUrl);
+            const logins = JSON.parse(output);
+            const matched = logins.find((login)=>login.url && this.normalizeServerUrl(login.url) === normalizedServerUrl);
+            return matched?.name ?? null;
+        } catch  {
+            return null;
+        }
+    }
+    runTeaApi(endpoint, loginName) {
+        const args = [
+            "api",
+            "-l",
+            loginName,
+            endpoint
+        ];
+        return execFileSync("tea", args, {
+            encoding: "utf-8",
+            stdio: "pipe"
+        });
+    }
+    encodePathSegments(path) {
+        if (!path) return "";
+        return path.split("/").filter(Boolean).map((segment)=>encodeURIComponent(segment)).join("/");
+    }
+    buildTeaContentsEndpoint(ref) {
+        const owner = encodeURIComponent(ref.owner);
+        const repo = encodeURIComponent(ref.repo);
+        const encodedPath = this.encodePathSegments(ref.path || "");
+        const pathPart = encodedPath ? `/${encodedPath}` : "";
+        const query = ref.ref ? `?ref=${encodeURIComponent(ref.ref)}` : "";
+        return `/repos/${owner}/${repo}/contents${pathPart}${query}`;
+    }
+    buildTeaRawFileEndpoint(ref, filePath) {
+        const owner = encodeURIComponent(ref.owner);
+        const repo = encodeURIComponent(ref.repo);
+        const encodedFilePath = this.encodePathSegments(filePath);
+        const query = ref.ref ? `?ref=${encodeURIComponent(ref.ref)}` : "";
+        return `/repos/${owner}/${repo}/raw/${encodedFilePath}${query}`;
+    }
+    /**
+   * 使用 tea api 拉取远程规则
+   * 前置条件：本地安装 tea 且已登录目标服务器
+   */ async fetchRemoteSpecsViaTea(ref, verbose) {
+        if (!this.isTeaInstalled()) {
+            this.logVerbose(verbose, 3, `         tea 不可用（未安装）`);
+            return null;
+        }
+        const loginName = this.getTeaLoginForServer(ref.serverUrl);
+        if (!loginName) {
+            this.logVerbose(verbose, 3, `         tea 未登录目标服务器: ${this.normalizeServerUrl(ref.serverUrl)}`);
+            return null;
+        }
+        this.logVerbose(verbose, 3, `         tea 登录名: ${loginName}`);
+        const specDir = this.buildRemoteSpecDir(ref);
+        this.logVerbose(verbose, 3, `         本地规则目录: ${specDir}`);
+        try {
+            console.log(`   📡 使用 tea 拉取规则: ${ref.owner}/${ref.repo}${ref.path ? `/${ref.path}` : ""}${ref.ref ? `@${ref.ref}` : ""}`);
+            const contentsEndpoint = this.buildTeaContentsEndpoint(ref);
+            this.logVerbose(verbose, 3, `         tea api endpoint(contents): ${contentsEndpoint}`);
+            const contentsRaw = this.runTeaApi(contentsEndpoint, loginName);
+            const contents = JSON.parse(contentsRaw);
+            const mdFiles = contents.filter((f)=>f.type === "file" && !!f.name && f.name.endsWith(".md") && !!f.path);
+            if (mdFiles.length === 0) {
+                console.warn("   ⚠️ tea 远程目录中未找到 .md 规则文件");
+                return null;
+            }
+            const fetchedFiles = [];
+            for (const file of mdFiles){
+                const fileEndpoint = this.buildTeaRawFileEndpoint(ref, file.path);
+                this.logVerbose(verbose, 3, `         tea api endpoint(raw): ${fileEndpoint}`);
+                const fileContent = this.runTeaApi(fileEndpoint, loginName);
+                fetchedFiles.push({
+                    name: file.name,
+                    content: fileContent
+                });
+            }
+            await this.prepareRemoteSpecDirForWrite(specDir);
+            for (const file of fetchedFiles){
+                await writeFile(join(specDir, file.name), file.content, "utf-8");
+            }
+            console.log(`   ✅ 已通过 tea 拉取 ${mdFiles.length} 个规则文件到本地目录`);
+            return specDir;
+        } catch (error) {
+            console.warn(`   ⚠️ tea 拉取规则失败:`, error instanceof Error ? error.message : error);
+            const localDir = await this.getLocalSpecsDir(specDir);
+            if (localDir) {
+                const mdCount = await this.getSpecFileCount(localDir);
+                this.logVerbose(verbose, 3, `         本地目录命中: ${localDir} (.md=${mdCount})`);
+                console.log(`   📦 使用本地已存在规则目录`);
+                return localDir;
+            }
+            this.logVerbose(verbose, 3, `         本地目录未命中: ${specDir}`);
+            return null;
         }
+    }
+    /**
+   * 通过 Git API 从远程仓库拉取规则文件
+   * 保存到 ~/.spaceflow/review-spec/ 目录
+   */ async fetchRemoteSpecs(ref, verbose) {
+        const specDir = this.buildRemoteSpecDir(ref);
+        this.logVerbose(verbose, 3, `         本地规则目录: ${specDir}`);
         try {
             console.log(`   📡 从远程仓库拉取规则: ${ref.owner}/${ref.repo}${ref.path ? `/${ref.path}` : ""}${ref.ref ? `@${ref.ref}` : ""}`);
             const contents = await this.gitProvider.listRepositoryContents(ref.owner, ref.repo, ref.path || undefined, ref.ref);
@@ -470,32 +642,41 @@ class ReviewSpecService {
                 console.warn(`   ⚠️ 远程目录中未找到 .md 规则文件`);
                 return null;
             }
-            await mkdir(cacheDir, {
-                recursive: true
-            });
+            const fetchedFiles = [];
             for (const file of mdFiles){
                 const content = await this.gitProvider.getFileContent(ref.owner, ref.repo, file.path, ref.ref);
-                await writeFile(join(cacheDir, file.name), content, "utf-8");
+                fetchedFiles.push({
+                    name: file.name,
+                    content
+                });
             }
-            // 写入时间戳
-            await writeFile(join(cacheDir, ".timestamp"), String(Date.now()), "utf-8");
-            console.log(`   ✅ 已拉取 ${mdFiles.length} 个规则文件到缓存`);
-            return cacheDir;
+            await this.prepareRemoteSpecDirForWrite(specDir);
+            for (const file of fetchedFiles){
+                await writeFile(join(specDir, file.name), file.content, "utf-8");
+            }
+            console.log(`   ✅ 已拉取 ${mdFiles.length} 个规则文件到本地目录`);
+            return specDir;
         } catch (error) {
             console.warn(`   ⚠️ 远程规则拉取失败:`, error instanceof Error ? error.message : error);
-            // 尝试使用过期缓存
-            try {
-                const entries = await readdir(cacheDir);
-                if (entries.some((f)=>f.endsWith(".md"))) {
-                    console.log(`   📦 使用过期缓存`);
-                    return cacheDir;
-                }
-            } catch  {
-            // 无缓存可用
-            }
+            const localDir = await this.getLocalSpecsDir(specDir);
+            if (localDir) {
+                const mdCount = await this.getSpecFileCount(localDir);
+                this.logVerbose(verbose, 3, `         本地目录命中: ${localDir} (.md=${mdCount})`);
+                console.log(`   📦 使用本地已存在规则目录`);
+                return localDir;
+            }
+            this.logVerbose(verbose, 3, `         本地目录未命中: ${specDir}`);
             return null;
         }
     }
+    async getSpecFileCount(dir) {
+        try {
+            const entries = await readdir(dir);
+            return entries.filter((f)=>f.endsWith(".md")).length;
+        } catch  {
+            return 0;
+        }
+    }
     /**
    * 解析 deps 目录，扫描子目录中的 references 文件夹
    * 如果目录本身包含 .md 文件则直接返回，否则扫描子目录
@@ -541,16 +722,35 @@ class ReviewSpecService {
     isRepoUrl(source) {
         return source.startsWith("http://") || source.startsWith("https://") || source.startsWith("git@") || source.includes("://");
     }
-    async cloneSpecRepo(repoUrl) {
+    buildRepoCloneUrl(ref) {
+        return `${ref.serverUrl}/${ref.owner}/${ref.repo}.git`;
+    }
+    async resolveClonedSpecDir(cacheDir, subPath) {
+        const normalizedSubPath = subPath?.trim().replace(/^\/+|\/+$/g, "");
+        if (!normalizedSubPath) {
+            return cacheDir;
+        }
+        const targetDir = join(cacheDir, normalizedSubPath);
+        try {
+            await access(targetDir);
+            return targetDir;
+        } catch  {
+            console.warn(`   警告: 克隆仓库中未找到子目录 ${normalizedSubPath}，改为使用仓库根目录`);
+            return cacheDir;
+        }
+    }
+    async cloneSpecRepo(repoUrl, subPath, verbose) {
         const repoName = this.extractRepoName(repoUrl);
         if (!repoName) {
             console.warn(`警告: 无法解析仓库名称: ${repoUrl}`);
             return null;
         }
         const cacheDir = join(homedir(), ".spaceflow", "review-spec", repoName);
+        this.logVerbose(verbose, 3, `         clone 目标目录: ${cacheDir}`);
         try {
             await access(cacheDir);
             // console.log(`   使用缓存的规则仓库: ${cacheDir}`);
+            this.logVerbose(verbose, 3, `         发现已存在仓库目录，尝试 git pull`);
             try {
                 execSync("git pull --ff-only", {
                     cwd: cacheDir,
@@ -560,10 +760,11 @@ class ReviewSpecService {
             } catch  {
                 console.warn(`   警告: 无法更新规则仓库，使用现有版本`);
             }
-            return cacheDir;
+            return this.resolveClonedSpecDir(cacheDir, subPath);
         } catch  {
             // console.log(`   克隆规则仓库: ${repoUrl}`);
             try {
+                this.logVerbose(verbose, 3, `         本地仓库目录不存在，执行 git clone`);
                 await mkdir(join(homedir(), ".spaceflow", "review-spec"), {
                     recursive: true
                 });
@@ -571,7 +772,7 @@ class ReviewSpecService {
                     stdio: "pipe"
                 });
                 // console.log(`   克隆完成: ${cacheDir}`);
-                return cacheDir;
+                return this.resolveClonedSpecDir(cacheDir, subPath);
             } catch (error) {
                 console.warn(`警告: 无法克隆仓库 ${repoUrl}:`, error);
                 return null;
@@ -579,6 +780,10 @@ class ReviewSpecService {
         }
     }
     extractRepoName(repoUrl) {
+        const parsedRef = parseRepoUrl(repoUrl);
+        if (parsedRef) {
+            return `${parsedRef.owner}__${parsedRef.repo}`;
+        }
         let path = repoUrl;
         path = path.replace(/\.git$/, "");
         path = path.replace(/^git@[^:]+:/, "");
@@ -3177,7 +3382,7 @@ class ReviewContextBuilder {
     }
     async getContextFromEnv(options) {
         const reviewConf = this.config.getPluginConfig("review");
-        if (shouldLog(options.verbose, 2)) {
+        if (shouldLog(options.verbose, 3)) {
             console.log(`[getContextFromEnv] reviewConf: ${JSON.stringify(reviewConf)}`);
         }
         const ciConf = this.config.get("ci");
@@ -3536,7 +3741,7 @@ class ReviewIssueFilter {
         if (shouldLog(verbose, 1)) {
             console.log(`📂 解析规则来源: ${specSources.length} 个`);
         }
-        const specDirs = await this.reviewSpecService.resolveSpecSources(specSources);
+        const specDirs = await this.reviewSpecService.resolveSpecSources(specSources, verbose);
         if (shouldLog(verbose, 2)) {
             console.log(`   解析到 ${specDirs.length} 个规则目录`, specDirs);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceflow/review",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "Spaceflow 代码审查插件，使用 LLM 对 PR 代码进行自动审查",
   "license": "MIT",
   "author": "Lydanne",
@@ -25,7 +25,7 @@
     "@vitest/coverage-v8": "^4.0.18",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.0.18",
-    "@spaceflow/cli": "0.40.0"
+    "@spaceflow/cli": "0.41.0"
   },
   "peerDependencies": {
     "@spaceflow/core": "0.30.0"

package/src/review-context.ts

@@ -65,7 +65,7 @@ export class ReviewContextBuilder {
 
   async getContextFromEnv(options: ReviewOptions): Promise<ReviewContext> {
     const reviewConf = this.config.getPluginConfig<ReviewConfig>("review");
-    if (shouldLog(options.verbose, 2)) {
+    if (shouldLog(options.verbose, 3)) {
       console.log(`[getContextFromEnv] reviewConf: ${JSON.stringify(reviewConf)}`);
     }
     const ciConf = this.config.get<CiConfig>("ci");
@@ -268,7 +268,9 @@ export class ReviewContextBuilder {
    */
   private normalizeSingleFilePath(file: string, cwd: string): string {
     const normalizedInput = normalize(file);
-    const relativePath = isAbsolute(normalizedInput) ? relative(cwd, normalizedInput) : normalizedInput;
+    const relativePath = isAbsolute(normalizedInput)
+      ? relative(cwd, normalizedInput)
+      : normalizedInput;
     return relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
   }
 

package/src/review-issue-filter.ts

@@ -39,7 +39,7 @@ export class ReviewIssueFilter {
     if (shouldLog(verbose, 1)) {
       console.log(`📂 解析规则来源: ${specSources.length} 个`);
     }
-    const specDirs = await this.reviewSpecService.resolveSpecSources(specSources);
+    const specDirs = await this.reviewSpecService.resolveSpecSources(specSources, verbose);
     if (shouldLog(verbose, 2)) {
       console.log(`   解析到 ${specDirs.length} 个规则目录`, specDirs);
     }

package/src/review-spec/review-spec.service.spec.ts

@@ -976,6 +976,13 @@ const MAX_COUNT = 100;
       expect(result).toBe("org__repo");
     });
 
+    it("should extract from directory URL", () => {
+      const result = (service as any).extractRepoName(
+        "https://git.bjxgj.com/xgj/review-spec/src/branch/main/references",
+      );
+      expect(result).toBe("xgj__review-spec");
+    });
+
     it("should handle single part path", () => {
       const result = (service as any).extractRepoName("repo");
       expect(result).toBe("repo");
@@ -1274,10 +1281,74 @@ const MAX_COUNT = 100;
       ]);
       expect(result.length).toBeGreaterThanOrEqual(0);
     });
+
+    it("should fallback to clone repo root URL when API fetch fails for directory URL", async () => {
+      gitProvider.listRepositoryContents.mockRejectedValue(new Error("401 unauthorized"));
+      (access as Mock)
+        .mockRejectedValueOnce(new Error("not found"))
+        .mockResolvedValueOnce(undefined);
+      (mkdir as Mock).mockResolvedValue(undefined);
+      (child_process.execSync as Mock).mockReturnValue("");
+      (child_process.execFileSync as Mock).mockImplementation(() => {
+        throw new Error("tea unavailable");
+      });
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const result = await service.resolveSpecSources([
+        "https://git.bjxgj.com/xgj/review-spec/src/branch/main/references",
+      ]);
+
+      expect(result.some((dir) => dir.includes("xgj__review-spec/references"))).toBe(true);
+      const cloneCall = (child_process.execSync as Mock).mock.calls.find((call) =>
+        String(call[0]).includes('git clone --depth 1 "https://git.bjxgj.com/xgj/review-spec.git"'),
+      );
+      expect(cloneCall).toBeTruthy();
+      consoleSpy.mockRestore();
+    });
+
+    it("should resolve remote specs via tea when provider API fails", async () => {
+      gitProvider.listRepositoryContents.mockRejectedValue(new Error("401 unauthorized"));
+      (child_process.execSync as Mock).mockReturnValue(""); // command -v tea
+      (child_process.execFileSync as Mock)
+        .mockReturnValueOnce(
+          JSON.stringify([
+            {
+              name: "git.bjxgj.com",
+              url: "https://git.bjxgj.com",
+            },
+          ]),
+        ) // tea login list -o json
+        .mockReturnValueOnce(
+          JSON.stringify([
+            {
+              type: "file",
+              name: "js.base.md",
+              path: "references/js.base.md",
+            },
+          ]),
+        ) // tea api contents
+        .mockReturnValueOnce("# Test `[JsTs.Base]`"); // tea api raw file
+      (readdir as Mock).mockResolvedValue([]);
+      (mkdir as Mock).mockResolvedValue(undefined);
+      (writeFile as Mock).mockResolvedValue(undefined);
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const result = await service.resolveSpecSources([
+        "https://git.bjxgj.com/xgj/review-spec/src/branch/main/references",
+      ]);
+
+      expect(result.some((dir) => dir.includes("review-spec"))).toBe(true);
+      expect(child_process.execFileSync).toHaveBeenCalledWith(
+        "tea",
+        ["api", "-l", "git.bjxgj.com", "/repos/xgj/review-spec/contents/references?ref=main"],
+        expect.objectContaining({ encoding: "utf-8", stdio: "pipe" }),
+      );
+      consoleSpy.mockRestore();
+    });
   });
 
   describe("fetchRemoteSpecs", () => {
-    it("should fetch and cache remote specs", async () => {
+    it("should fetch and persist remote specs into review-spec dir", async () => {
       gitProvider.listRepositoryContents.mockResolvedValue([
         { type: "file", name: "rule.md", path: "rule.md" },
       ]);
@@ -1301,7 +1372,7 @@ const MAX_COUNT = 100;
       consoleSpy.mockRestore();
     });
 
-    it("should handle API failure and use expired cache", async () => {
+    it("should handle API failure and use local specs directory", async () => {
       gitProvider.listRepositoryContents.mockRejectedValue(new Error("API error"));
       (readdir as Mock).mockResolvedValue(["cached.md"]);
       const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
@@ -1313,7 +1384,7 @@ const MAX_COUNT = 100;
       logSpy.mockRestore();
     });
 
-    it("should handle API failure without cache", async () => {
+    it("should handle API failure without local specs directory", async () => {
       gitProvider.listRepositoryContents.mockRejectedValue(new Error("API error"));
       (readdir as Mock).mockRejectedValue(new Error("no cache"));
       const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
@@ -1325,15 +1396,12 @@ const MAX_COUNT = 100;
       logSpy.mockRestore();
     });
 
-    it("should use valid cache in non-CI environment", async () => {
-      const originalCI = process.env.CI;
-      delete process.env.CI;
-      (readFile as Mock).mockResolvedValue(String(Date.now()));
+    it("should use local specs directory as fallback", async () => {
+      gitProvider.listRepositoryContents.mockRejectedValue(new Error("API error"));
       (readdir as Mock).mockResolvedValue(["cached.md"]);
       const ref = { owner: "org", repo: "repo" };
       const result = await (service as any).fetchRemoteSpecs(ref);
       expect(result).toBeTruthy();
-      process.env.CI = originalCI;
     });
   });
 
@@ -1416,6 +1484,19 @@ const MAX_COUNT = 100;
       expect(result).toBeTruthy();
     });
 
+    it("should return sub directory when subPath is provided", async () => {
+      (access as Mock)
+        .mockRejectedValueOnce(new Error("not found"))
+        .mockResolvedValueOnce(undefined);
+      (mkdir as Mock).mockResolvedValue(undefined);
+      (child_process.execSync as Mock).mockReturnValue("");
+      const result = await (service as any).cloneSpecRepo(
+        "https://github.com/org/repo.git",
+        "references",
+      );
+      expect(result).toContain("org__repo/references");
+    });
+
     it("should handle clone failure", async () => {
       (access as Mock).mockRejectedValue(new Error("not found"));
       (mkdir as Mock).mockResolvedValue(undefined);

package/src/review-spec/review-spec.service.ts

@@ -7,19 +7,26 @@ import {
   type RemoteRepoRef,
   type RepositoryContent,
 } from "@spaceflow/core";
-import { readdir, readFile, mkdir, access, writeFile } from "fs/promises";
+import { readdir, readFile, mkdir, access, writeFile, unlink } from "fs/promises";
 import { join, basename, extname } from "path";
 import { homedir } from "os";
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import micromatch from "micromatch";
 import { ReviewSpec, ReviewRule, RuleExample, Severity } from "./types";
 import { extractGlobsFromIncludes } from "../review-includes-filter";
 
-/** 远程规则缓存 TTL（毫秒），默认 5 分钟 */
-const REMOTE_SPEC_CACHE_TTL = 5 * 60 * 1000;
-
 export class ReviewSpecService {
   constructor(protected readonly gitProvider?: GitProviderService) {}
+
+  protected normalizeServerUrl(url: string): string {
+    return url.trim().replace(/\/+$/, "");
+  }
+
+  protected logVerbose(verbose: VerboseLevel | undefined, level: number, message: string): void {
+    if (shouldLog(verbose, level as VerboseLevel)) {
+      console.log(message);
+    }
+  }
   /**
    * 检查规则 ID 是否匹配（精确匹配或前缀匹配）
    * 例如: "JsTs.FileName" 匹配 "JsTs.FileName" 和 "JsTs.FileName.UpperCamel"
@@ -114,58 +121,249 @@ export class ReviewSpecService {
     return specs;
   }
 
-  async resolveSpecSources(sources: string[]): Promise<string[]> {
+  async resolveSpecSources(sources: string[], verbose?: VerboseLevel): Promise<string[]> {
     const dirs: string[] = [];
 
     for (const source of sources) {
-      // 优先尝试解析为远程仓库 URL（浏览器复制的链接）
+      this.logVerbose(verbose, 3, `   🔎 规则来源: ${source}`);
       const repoRef = parseRepoUrl(source);
+      if (repoRef) {
+        this.logVerbose(
+          verbose,
+          3,
+          `      解析远程仓库: ${repoRef.serverUrl}/${repoRef.owner}/${repoRef.repo} path=${repoRef.path || "(root)"} ref=${repoRef.ref || "(default)"}`,
+        );
+      } else {
+        this.logVerbose(verbose, 3, `      非仓库 URL，按本地目录处理`);
+      }
       if (repoRef && this.gitProvider) {
-        const dir = await this.fetchRemoteSpecs(repoRef);
+        this.logVerbose(verbose, 3, `      尝试方式 #1: Git Provider API`);
+        const dir = await this.fetchRemoteSpecs(repoRef, verbose);
         if (dir) {
           dirs.push(dir);
+          this.logVerbose(verbose, 2, `      ✅ 采用方式: Git Provider API -> ${dir}`);
+          continue;
+        }
+        this.logVerbose(verbose, 3, `      ❌ Git Provider API 未获取到规则，继续尝试`);
+      }
+      if (repoRef) {
+        this.logVerbose(verbose, 3, `      尝试方式 #2: tea api`);
+        const teaDir = await this.fetchRemoteSpecsViaTea(repoRef, verbose);
+        if (teaDir) {
+          dirs.push(teaDir);
+          this.logVerbose(verbose, 2, `      ✅ 采用方式: tea api -> ${teaDir}`);
+          continue;
+        }
+        this.logVerbose(verbose, 3, `      ❌ tea api 未获取到规则，继续尝试`);
+      }
+      // API 拉取失败或未配置 provider 时，回退到 git clone（使用仓库根 URL，而非目录 URL）
+      if (repoRef) {
+        this.logVerbose(verbose, 3, `      尝试方式 #3: git clone 回退`);
+        const fallbackCloneUrl = this.buildRepoCloneUrl(repoRef);
+        this.logVerbose(verbose, 3, `         clone URL: ${fallbackCloneUrl}`);
+        const fallbackDir = await this.cloneSpecRepo(fallbackCloneUrl, repoRef.path, verbose);
+        if (fallbackDir) {
+          dirs.push(fallbackDir);
+          this.logVerbose(verbose, 2, `      ✅ 采用方式: git clone 回退 -> ${fallbackDir}`);
           continue;
         }
+        this.logVerbose(verbose, 3, `      ❌ git clone 回退失败`);
       }
       if (this.isRepoUrl(source)) {
-        const dir = await this.cloneSpecRepo(source);
+        this.logVerbose(verbose, 3, `      尝试方式 #4: 直接 clone 来源 URL`);
+        const dir = await this.cloneSpecRepo(source, undefined, verbose);
         if (dir) {
           dirs.push(dir);
+          this.logVerbose(verbose, 2, `      ✅ 采用方式: 直接 clone 来源 URL -> ${dir}`);
+        } else {
+          this.logVerbose(verbose, 3, `      ❌ 直接 clone 来源 URL 失败`);
         }
       } else {
         // 检查是否是 deps 目录，如果是则扫描子目录的 references
         const resolvedDirs = await this.resolveDepsDir(source);
         dirs.push(...resolvedDirs);
+        this.logVerbose(
+          verbose,
+          3,
+          `      deps 目录解析结果: ${resolvedDirs.length > 0 ? resolvedDirs.join(", ") : "(空)"}`,
+        );
       }
     }
 
     return dirs;
   }
 
+  protected buildRemoteSpecDir(ref: RemoteRepoRef): string {
+    const dirKey = `${ref.owner}__${ref.repo}${ref.path ? `__${ref.path.replace(/\//g, "_")}` : ""}${ref.ref ? `@${ref.ref}` : ""}`;
+    return join(homedir(), ".spaceflow", "review-spec", dirKey);
+  }
+
+  protected async getLocalSpecsDir(dir: string): Promise<string | null> {
+    try {
+      const entries = await readdir(dir);
+      if (!entries.some((f) => f.endsWith(".md"))) {
+        return null;
+      }
+      return dir;
+    } catch {
+      return null;
+    }
+  }
+
+  protected async prepareRemoteSpecDirForWrite(dir: string): Promise<void> {
+    await mkdir(dir, { recursive: true });
+    try {
+      const entries = await readdir(dir);
+      for (const name of entries) {
+        if (name.endsWith(".md") || name === ".timestamp") {
+          await unlink(join(dir, name));
+        }
+      }
+    } catch {
+      // 忽略目录清理失败，后续写入时再处理
+    }
+  }
+
+  protected isTeaInstalled(): boolean {
+    try {
+      execSync("command -v tea", { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  protected getTeaLoginForServer(serverUrl: string): string | null {
+    try {
+      const output = execFileSync("tea", ["login", "list", "-o", "json"], {
+        encoding: "utf-8",
+        stdio: "pipe",
+      });
+      const normalizedServerUrl = this.normalizeServerUrl(serverUrl);
+      const logins = JSON.parse(output) as Array<{ name?: string; url?: string }>;
+      const matched = logins.find(
+        (login) => login.url && this.normalizeServerUrl(login.url) === normalizedServerUrl,
+      );
+      return matched?.name ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  protected runTeaApi(endpoint: string, loginName: string): string {
+    const args = ["api", "-l", loginName, endpoint];
+    return execFileSync("tea", args, {
+      encoding: "utf-8",
+      stdio: "pipe",
+    });
+  }
+
+  protected encodePathSegments(path: string): string {
+    if (!path) return "";
+    return path
+      .split("/")
+      .filter(Boolean)
+      .map((segment) => encodeURIComponent(segment))
+      .join("/");
+  }
+
+  protected buildTeaContentsEndpoint(ref: RemoteRepoRef): string {
+    const owner = encodeURIComponent(ref.owner);
+    const repo = encodeURIComponent(ref.repo);
+    const encodedPath = this.encodePathSegments(ref.path || "");
+    const pathPart = encodedPath ? `/${encodedPath}` : "";
+    const query = ref.ref ? `?ref=${encodeURIComponent(ref.ref)}` : "";
+    return `/repos/${owner}/${repo}/contents${pathPart}${query}`;
+  }
+
+  protected buildTeaRawFileEndpoint(ref: RemoteRepoRef, filePath: string): string {
+    const owner = encodeURIComponent(ref.owner);
+    const repo = encodeURIComponent(ref.repo);
+    const encodedFilePath = this.encodePathSegments(filePath);
+    const query = ref.ref ? `?ref=${encodeURIComponent(ref.ref)}` : "";
+    return `/repos/${owner}/${repo}/raw/${encodedFilePath}${query}`;
+  }
+
   /**
-   * 通过 Git API 从远程仓库拉取规则文件
-   * 缓存到 ~/.spaceflow/review-spec-cache/ 目录，带 TTL
+   * 使用 tea api 拉取远程规则
+   * 前置条件：本地安装 tea 且已登录目标服务器
    */
-  protected async fetchRemoteSpecs(ref: RemoteRepoRef): Promise<string | null> {
-    const cacheKey = `${ref.owner}__${ref.repo}${ref.path ? `__${ref.path.replace(/\//g, "_")}` : ""}${ref.ref ? `@${ref.ref}` : ""}`;
-    const cacheDir = join(homedir(), ".spaceflow", "review-spec-cache", cacheKey);
-    // 检查缓存是否有效（非 CI 环境下使用 TTL）
-    const isCI = !!process.env.CI;
-    if (!isCI) {
-      try {
-        const timestampFile = join(cacheDir, ".timestamp");
-        const timestamp = await readFile(timestampFile, "utf-8");
-        const age = Date.now() - Number(timestamp);
-        if (age < REMOTE_SPEC_CACHE_TTL) {
-          const entries = await readdir(cacheDir);
-          if (entries.some((f) => f.endsWith(".md"))) {
-            return cacheDir;
-          }
-        }
-      } catch {
-        // 缓存不存在或无效，继续拉取
+  protected async fetchRemoteSpecsViaTea(
+    ref: RemoteRepoRef,
+    verbose?: VerboseLevel,
+  ): Promise<string | null> {
+    if (!this.isTeaInstalled()) {
+      this.logVerbose(verbose, 3, `         tea 不可用（未安装）`);
+      return null;
+    }
+    const loginName = this.getTeaLoginForServer(ref.serverUrl);
+    if (!loginName) {
+      this.logVerbose(
+        verbose,
+        3,
+        `         tea 未登录目标服务器: ${this.normalizeServerUrl(ref.serverUrl)}`,
+      );
+      return null;
+    }
+    this.logVerbose(verbose, 3, `         tea 登录名: ${loginName}`);
+    const specDir = this.buildRemoteSpecDir(ref);
+    this.logVerbose(verbose, 3, `         本地规则目录: ${specDir}`);
+    try {
+      console.log(
+        `   📡 使用 tea 拉取规则: ${ref.owner}/${ref.repo}${ref.path ? `/${ref.path}` : ""}${ref.ref ? `@${ref.ref}` : ""}`,
+      );
+      const contentsEndpoint = this.buildTeaContentsEndpoint(ref);
+      this.logVerbose(verbose, 3, `         tea api endpoint(contents): ${contentsEndpoint}`);
+      const contentsRaw = this.runTeaApi(contentsEndpoint, loginName);
+      const contents = JSON.parse(contentsRaw) as Array<{
+        type?: string;
+        name?: string;
+        path?: string;
+      }>;
+      const mdFiles = contents.filter(
+        (f) => f.type === "file" && !!f.name && f.name.endsWith(".md") && !!f.path,
+      );
+      if (mdFiles.length === 0) {
+        console.warn("   ⚠️ tea 远程目录中未找到 .md 规则文件");
+        return null;
+      }
+      const fetchedFiles: Array<{ name: string; content: string }> = [];
+      for (const file of mdFiles) {
+        const fileEndpoint = this.buildTeaRawFileEndpoint(ref, file.path!);
+        this.logVerbose(verbose, 3, `         tea api endpoint(raw): ${fileEndpoint}`);
+        const fileContent = this.runTeaApi(fileEndpoint, loginName);
+        fetchedFiles.push({ name: file.name!, content: fileContent });
+      }
+      await this.prepareRemoteSpecDirForWrite(specDir);
+      for (const file of fetchedFiles) {
+        await writeFile(join(specDir, file.name), file.content, "utf-8");
       }
+      console.log(`   ✅ 已通过 tea 拉取 ${mdFiles.length} 个规则文件到本地目录`);
+      return specDir;
+    } catch (error) {
+      console.warn(`   ⚠️ tea 拉取规则失败:`, error instanceof Error ? error.message : error);
+      const localDir = await this.getLocalSpecsDir(specDir);
+      if (localDir) {
+        const mdCount = await this.getSpecFileCount(localDir);
+        this.logVerbose(verbose, 3, `         本地目录命中: ${localDir} (.md=${mdCount})`);
+        console.log(`   📦 使用本地已存在规则目录`);
+        return localDir;
+      }
+      this.logVerbose(verbose, 3, `         本地目录未命中: ${specDir}`);
+      return null;
     }
+  }
+
+  /**
+   * 通过 Git API 从远程仓库拉取规则文件
+   * 保存到 ~/.spaceflow/review-spec/ 目录
+   */
+  protected async fetchRemoteSpecs(
+    ref: RemoteRepoRef,
+    verbose?: VerboseLevel,
+  ): Promise<string | null> {
+    const specDir = this.buildRemoteSpecDir(ref);
+    this.logVerbose(verbose, 3, `         本地规则目录: ${specDir}`);
     try {
       console.log(
         `   📡 从远程仓库拉取规则: ${ref.owner}/${ref.repo}${ref.path ? `/${ref.path}` : ""}${ref.ref ? `@${ref.ref}` : ""}`,
@@ -183,7 +381,7 @@ export class ReviewSpecService {
         console.warn(`   ⚠️ 远程目录中未找到 .md 规则文件`);
         return null;
       }
-      await mkdir(cacheDir, { recursive: true });
+      const fetchedFiles: Array<{ name: string; content: string }> = [];
       for (const file of mdFiles) {
         const content = await this.gitProvider!.getFileContent(
           ref.owner,
@@ -191,28 +389,37 @@ export class ReviewSpecService {
           file.path,
           ref.ref,
         );
-        await writeFile(join(cacheDir, file.name), content, "utf-8");
+        fetchedFiles.push({ name: file.name, content });
       }
-      // 写入时间戳
-      await writeFile(join(cacheDir, ".timestamp"), String(Date.now()), "utf-8");
-      console.log(`   ✅ 已拉取 ${mdFiles.length} 个规则文件到缓存`);
-      return cacheDir;
+      await this.prepareRemoteSpecDirForWrite(specDir);
+      for (const file of fetchedFiles) {
+        await writeFile(join(specDir, file.name), file.content, "utf-8");
+      }
+      console.log(`   ✅ 已拉取 ${mdFiles.length} 个规则文件到本地目录`);
+      return specDir;
     } catch (error) {
       console.warn(`   ⚠️ 远程规则拉取失败:`, error instanceof Error ? error.message : error);
-      // 尝试使用过期缓存
-      try {
-        const entries = await readdir(cacheDir);
-        if (entries.some((f) => f.endsWith(".md"))) {
-          console.log(`   📦 使用过期缓存`);
-          return cacheDir;
-        }
-      } catch {
-        // 无缓存可用
+      const localDir = await this.getLocalSpecsDir(specDir);
+      if (localDir) {
+        const mdCount = await this.getSpecFileCount(localDir);
+        this.logVerbose(verbose, 3, `         本地目录命中: ${localDir} (.md=${mdCount})`);
+        console.log(`   📦 使用本地已存在规则目录`);
+        return localDir;
       }
+      this.logVerbose(verbose, 3, `         本地目录未命中: ${specDir}`);
       return null;
     }
   }
 
+  protected async getSpecFileCount(dir: string): Promise<number> {
+    try {
+      const entries = await readdir(dir);
+      return entries.filter((f) => f.endsWith(".md")).length;
+    } catch {
+      return 0;
+    }
+  }
+
   /**
    * 解析 deps 目录，扫描子目录中的 references 文件夹
    * 如果目录本身包含 .md 文件则直接返回，否则扫描子目录
@@ -268,7 +475,32 @@ export class ReviewSpecService {
     );
   }
 
-  protected async cloneSpecRepo(repoUrl: string): Promise<string | null> {
+  protected buildRepoCloneUrl(ref: RemoteRepoRef): string {
+    return `${ref.serverUrl}/${ref.owner}/${ref.repo}.git`;
+  }
+
+  protected async resolveClonedSpecDir(cacheDir: string, subPath?: string): Promise<string> {
+    const normalizedSubPath = subPath?.trim().replace(/^\/+|\/+$/g, "");
+    if (!normalizedSubPath) {
+      return cacheDir;
+    }
+    const targetDir = join(cacheDir, normalizedSubPath);
+    try {
+      await access(targetDir);
+      return targetDir;
+    } catch {
+      console.warn(
+        `   警告: 克隆仓库中未找到子目录 ${normalizedSubPath}，改为使用仓库根目录`,
+      );
+      return cacheDir;
+    }
+  }
+
+  protected async cloneSpecRepo(
+    repoUrl: string,
+    subPath?: string,
+    verbose?: VerboseLevel,
+  ): Promise<string | null> {
     const repoName = this.extractRepoName(repoUrl);
     if (!repoName) {
       console.warn(`警告: 无法解析仓库名称: ${repoUrl}`);
@@ -276,24 +508,27 @@ export class ReviewSpecService {
     }
 
     const cacheDir = join(homedir(), ".spaceflow", "review-spec", repoName);
+    this.logVerbose(verbose, 3, `         clone 目标目录: ${cacheDir}`);
 
     try {
       await access(cacheDir);
       // console.log(`   使用缓存的规则仓库: ${cacheDir}`);
+      this.logVerbose(verbose, 3, `         发现已存在仓库目录，尝试 git pull`);
       try {
         execSync("git pull --ff-only", { cwd: cacheDir, stdio: "pipe" });
         // console.log(`   已更新规则仓库`);
       } catch {
         console.warn(`   警告: 无法更新规则仓库，使用现有版本`);
       }
-      return cacheDir;
+      return this.resolveClonedSpecDir(cacheDir, subPath);
     } catch {
       // console.log(`   克隆规则仓库: ${repoUrl}`);
       try {
+        this.logVerbose(verbose, 3, `         本地仓库目录不存在，执行 git clone`);
         await mkdir(join(homedir(), ".spaceflow", "review-spec"), { recursive: true });
         execSync(`git clone --depth 1 "${repoUrl}" "${cacheDir}"`, { stdio: "pipe" });
         // console.log(`   克隆完成: ${cacheDir}`);
-        return cacheDir;
+        return this.resolveClonedSpecDir(cacheDir, subPath);
       } catch (error) {
         console.warn(`警告: 无法克隆仓库 ${repoUrl}:`, error);
         return null;
@@ -302,6 +537,11 @@ export class ReviewSpecService {
   }
 
   protected extractRepoName(repoUrl: string): string | null {
+    const parsedRef = parseRepoUrl(repoUrl);
+    if (parsedRef) {
+      return `${parsedRef.owner}__${parsedRef.repo}`;
+    }
+
     let path = repoUrl;
     path = path.replace(/\.git$/, "");
     path = path.replace(/^git@[^:]+:/, "");