diff --git a/tools/BootstrapBlazor.LLMsDocs.Cli/BootstrapBlazor.LLMsDocs.Cli.csproj b/tools/BootstrapBlazor.LLMsDocs.Cli/BootstrapBlazor.LLMsDocs.Cli.csproj index 4d758163..6a0ecd43 100644 --- a/tools/BootstrapBlazor.LLMsDocs.Cli/BootstrapBlazor.LLMsDocs.Cli.csproj +++ b/tools/BootstrapBlazor.LLMsDocs.Cli/BootstrapBlazor.LLMsDocs.Cli.csproj @@ -1,7 +1,7 @@ - 11.0.1 + 11.0.2 Exe false diff --git a/tools/BootstrapBlazor.LLMsDocs.Cli/README.md b/tools/BootstrapBlazor.LLMsDocs.Cli/README.md index d9f6e29b..278df9ad 100644 --- a/tools/BootstrapBlazor.LLMsDocs.Cli/README.md +++ b/tools/BootstrapBlazor.LLMsDocs.Cli/README.md @@ -50,6 +50,7 @@ dotnet tool uninstall -g BootstrapBlazor.LLMsDocs.Cli ```bash bb-llms search table # 按关键词搜索组件,定位准确名称 bb-llms get Table # 拉取 Table 组件的完整 API 文档(核心命令) +bb-llms get Markdown # 从项目还原的 BootstrapBlazor.Markdown 包读取文档 bb-llms get SelectCity # 拉取 Region 扩展包中 SelectCity 的 API 文档 bb-llms list # 列出全部组件 bb-llms index # 打印文档索引 @@ -105,7 +106,9 @@ bb-llms get IRecognizerProvider # 共享服务接口,按包列出 Azure/B **文档源解析优先级**:`--base-url` > 环境变量 `BB_LLMS_BASE_URL` > 当前项目还原的包内文档 > 官网。 显式指定源时不进行项目发现,沿用该源原有行为。自动模式查找当前目录或父目录中的项目;若没有,再查找当前目录下的项目。项目或还原目标不唯一时必须分别用 `--project` 或 `--framework` 指定,不能任意选择版本;带运行时标识的目标使用完整名称,如 `net8.0/win-x64`。项目尚未还原时回退官网;当前只读取项目目录下 `obj/project.assets.json`。 -包内核心文档支持 `skills/bb-api` 和旧版 `skills/bootstrapblazor`;扩展包读取 `docs/llms`。自动模式下的官网缓存与显式源缓存隔离。 +包内文档按项目实际还原的包版本读取:扫描每个 `BootstrapBlazor` / `BootstrapBlazor.*` 包的 `skills/*/SKILL.md`,从对应的 `references/llms.txt` 建立组件与文档的映射,支持一个包提供多个 skill。`Table` 从 `BootstrapBlazor` 包读取,`Markdown` 从 `BootstrapBlazor.Markdown` 包读取;组件所属包以索引为准,不根据组件名猜测。 + +核心包的 `skills/bb-api` 和旧版 `skills/bootstrapblazor` 均兼容;扩展包没有可用的 skill 文档索引时,回退旧版 `docs/llms`。同一个包的多个 skill 收录同名类型时,按 skill 目录名的顺序优先读取第一项,列表不重复展示。不扫描项目未引用的包或全局缓存中的其他版本;对应包未还原或未携带所需文档时,仍按上述规则回退官网。自动模式下的官网缓存与显式源缓存隔离。 ```bash # 用环境变量指向自建/镜像源 diff --git a/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs b/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs index bf74d04b..1414ea0d 100644 --- a/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs +++ b/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs @@ -99,7 +99,7 @@ private async Task> MergeAsync(List local, Canc { var entries = local.Select(e => e.Entry).ToList(); var names = entries.Select(e => e.Name).ToHashSet(StringComparer.OrdinalIgnoreCase); - Console.Error.WriteLine($"Source: project packages ({string.Join(", ", packages.Select(p => $"{p.Package} {p.Version}"))})."); + Console.Error.WriteLine($"Source: project packages ({string.Join(", ", packages.Select(p => $"{p.Package} {p.Version}").Distinct(StringComparer.OrdinalIgnoreCase))})."); try { using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct); @@ -129,11 +129,13 @@ private async Task> MergeAsync(List local, Canc private List ReadLocalEntries() { var entries = new List(); + var names = new HashSet(StringComparer.OrdinalIgnoreCase); foreach (var package in packages) { try { - entries.AddRange(ReadPackageEntries(package)); + entries.AddRange(ReadPackageEntries(package) + .Where(entry => names.Add($"{package.Package}/{entry.Entry.Name}"))); } catch (Exception ex) when (ex is IOException or UnauthorizedAccessException) { diff --git a/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs b/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs index 7d25f728..1cddb688 100644 --- a/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs +++ b/tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs @@ -99,15 +99,22 @@ private static IReadOnlyList ReadPackages(string assetsPath, string { continue; } - var candidates = core - ? new[] { Path.Combine(packageRoot, "skills", "bb-api", "references"), Path.Combine(packageRoot, "skills", "bootstrapblazor", "references") } - : [Path.Combine(packageRoot, "docs", "llms")]; - var docs = candidates.FirstOrDefault(p => File.Exists(Path.Combine(p, "llms.txt")) - && (!core || File.Exists(Path.Combine(Path.GetDirectoryName(p)!, "SKILL.md")))); - if (docs is not null) + var skillsRoot = Path.Combine(packageRoot, "skills"); + var docs = Directory.Exists(skillsRoot) + ? Directory.GetDirectories(skillsRoot).Order(StringComparer.Ordinal) + .Where(p => File.Exists(Path.Combine(p, "SKILL.md")) + && File.Exists(Path.Combine(p, "references", "llms.txt"))) + .Select(p => Path.Combine(p, "references")).ToArray() + : []; + if (docs.Length == 0 && !core) { - packages.Add(new PackageDocs(name, item.Name[(separator + 1)..], docs, !core)); + var legacyDocs = Path.Combine(packageRoot, "docs", "llms"); + if (File.Exists(Path.Combine(legacyDocs, "llms.txt"))) + { + docs = [legacyDocs]; + } } + packages.AddRange(docs.Select(directory => new PackageDocs(name, item.Name[(separator + 1)..], directory, !core))); break; } } diff --git a/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/SKILL.md b/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/SKILL.md index fa7e6494..cf27a8ca 100644 --- a/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/SKILL.md +++ b/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/SKILL.md @@ -1,30 +1,38 @@ --- name: bootstrapblazor -description: 涉及 BootstrapBlazor(简称 BB / bb,如“BB 组件”“bb 的 Table”“用 bb 写表格”)的组件参数、事件回调、公开方法、用法时使用,通过 bb-llms CLI 获取官方组件 API 文档,避免臆造参数。 +description: 涉及 BootstrapBlazor(简称 BB / bb,如“BB 组件”“bb 的 Table”“用 bb 写表格”)及其扩展组件的参数、事件回调、公开方法、用法时使用,通过 bb-llms CLI 按当前项目包版本查询 API,避免臆造参数或假设组件所属包。 --- # BootstrapBlazor 组件文档查询 -当任务涉及 BootstrapBlazor(简称 **BB** / **bb**,下同)组件(编写或修改 .razor、配置组件参数、调用组件方法等)时,优先用 `bb-llms` 获取**权威**组件 API。 +当任务涉及 BootstrapBlazor(简称 **BB** / **bb**,下同)及其扩展组件(编写或修改 `.razor`、配置组件参数、调用组件方法等)时,优先用 `bb-llms` 获取 API 文档,不要凭记忆臆造参数。 > 用户说“BB 组件”“bb 的 Table”“用 bb 写个表格”等时,BB / bb 均指 BootstrapBlazor,按本流程查询。 -## 用法 +## 查询流程 -1. 不确定组件名时先搜索: +在当前项目目录运行命令,使 CLI 能按项目实际还原的 NuGet 包及其版本查询包内文档。包内文档由各包提供的 skill 及其 `references/llms.txt` 索引组成;组件可能来自核心包、任一扩展包,或作为服务记录在索引中。**不要仅凭组件名推断所属包**,由索引解析归属。 + +1. 已知准确名称时直接获取文档;CLI 会按索引解析文档来源,不要求组件来自 `BootstrapBlazor` 核心包: + ```bash + bb-llms get # 例:bb-llms get Table + ``` +2. 不确定准确名称或需要确认是否有对应文档时,先搜索。搜索结果合并当前项目包与官网索引: ```bash bb-llms search <关键词> ``` -2. 获取某组件的参数 / 事件 / 方法文档: +3. 获取搜索结果中的准确名称对应的参数 / 事件 / 方法文档: ```bash - bb-llms get # 例:bb-llms get Table + bb-llms get <搜索结果中的名称> ``` -3. 浏览全部组件: +4. 浏览索引中的条目: ```bash bb-llms list ``` -输出为 Markdown(参数表、事件回调、公开方法、GitHub 源码链接)。文档源默认 https://www.blazor.zone/llms ,自动本地缓存;可用环境变量 `BB_LLMS_BASE_URL` 或 `--base-url` 指向自建/本地源。 +`get` 优先读取当前项目已还原包内、与引用版本对应的文档;本地没有该文档时回退官网。`search`、`list` 合并项目包与官网索引,因此组件不在当前项目的包里时也可能找到官网文档。若有多个项目或还原目标,使用 `--project` / `--framework` 指定;项目尚未还原时,CLI 可能只能回退官网,版本可能与项目引用不同。找不到名称时先用 `search` 定位,不要仅据此判断组件不存在。 + +输出为 Markdown(参数表、事件回调、公开方法、GitHub 源码链接)。官网源默认 `https://www.blazor.zone/llms`,按需联网并本地缓存;可用环境变量 `BB_LLMS_BASE_URL` 或 `--base-url` 指向自建/本地源。 ## 前置条件 diff --git a/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/instructions.md b/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/instructions.md index 1dfd14dd..43290e57 100644 --- a/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/instructions.md +++ b/tools/BootstrapBlazor.LLMsDocs.Cli/Templates/instructions.md @@ -1,9 +1,9 @@ ## BootstrapBlazor 组件文档 -需要 BootstrapBlazor(简称 BB / bb)组件的参数 / 事件 / 公开方法时,使用 `bb-llms` CLI 获取官方文档,不要凭记忆臆造 API: +需要 BootstrapBlazor(简称 BB / bb)及其扩展组件的参数 / 事件 / 公开方法时,在当前项目目录使用 `bb-llms` CLI 查询文档,不要凭记忆臆造 API。CLI 优先按当前项目实际还原的 NuGet 包及其版本读取包内 skill 文档;组件所属包由索引解析,不要仅凭组件名假设它来自核心包: -- 查找组件名:`bb-llms search <关键词>` -- 获取组件文档:`bb-llms get `(例:`bb-llms get Table`) -- 列出全部组件:`bb-llms list` +- 已知准确名称时获取文档:`bb-llms get `(例:`bb-llms get Table`) +- 不确定准确名称时先搜索:`bb-llms search <关键词>`,再用搜索结果中的准确名称执行 `get` +- 浏览索引条目:`bb-llms list` -文档源默认 https://www.blazor.zone/llms ,按需联网拉取并本地缓存;可用环境变量 `BB_LLMS_BASE_URL` 或 `--base-url` 指向自建/本地源。 +`get` 本地缺少文档时回退官网;`search` / `list` 合并项目包和官网索引。项目或还原目标不唯一时使用 `--project` / `--framework` 指定。官网源默认 https://www.blazor.zone/llms,按需联网拉取并本地缓存;可用环境变量 `BB_LLMS_BASE_URL` 或 `--base-url` 指向自建/本地源。