Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<Version>11.0.1</Version>
<Version>11.0.2</Version>
<OutputType>Exe</OutputType>
<SatelliteResourceLanguages>false</SatelliteResourceLanguages>
</PropertyGroup>
Expand Down
5 changes: 4 additions & 1 deletion tools/BootstrapBlazor.LLMsDocs.Cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 # 打印文档索引
Expand Down Expand Up @@ -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
# 用环境变量指向自建/镜像源
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ private async Task<List<ComponentEntry>> MergeAsync(List<LocalEntry> 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);
Expand Down Expand Up @@ -129,11 +129,13 @@ private async Task<List<ComponentEntry>> MergeAsync(List<LocalEntry> local, Canc
private List<LocalEntry> ReadLocalEntries()
{
var entries = new List<LocalEntry>();
var names = new HashSet<string>(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}")));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Package documentation is indistinguishable

When two or more restored packages index an entry with the same name, GetAsync selects the first matching extension entry in assets order, and SearchAsync collapses entries that share a generated DocumentPath. Callers cannot identify or select the other package’s documentation and may receive the wrong package’s API docs.

Preserve package identity in lookups and generated document paths so callers can distinguish and select entries from different packages.

Also at tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:104, tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:118.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs` at line 138:

**Package documentation is indistinguishable**

When two or more restored packages index an entry with the same name, `GetAsync` selects the first matching extension entry in assets order, and `SearchAsync` collapses entries that share a generated `DocumentPath`. Callers cannot identify or select the other package’s documentation and may receive the wrong package’s API docs.

Preserve package identity in lookups and generated document paths so callers can distinguish and select entries from different packages.

Also at `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:104`, `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:118`.

}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Expand Down
21 changes: 14 additions & 7 deletions tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs
Original file line number Diff line number Diff line change
Expand Up @@ -99,15 +99,22 @@ private static IReadOnlyList<PackageDocs> 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)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · One package’s docs hide all local docs

When enumerating a package’s skills directory fails, including after another package has already been resolved, Directory.GetDirectories throws, and Resolve catches the exception around the entire ReadPackages call and returns an empty package list. Lookups then use online docs instead of local docs.

Handle skills-directory enumeration errors per package so one failure does not discard packages already resolved or prevent resolving others.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at line 104:

**One package’s docs hide all local docs**

When enumerating a package’s skills directory fails, including after another package has already been resolved, `Directory.GetDirectories` throws, and `Resolve` catches the exception around the entire `ReadPackages` call and returns an empty package list. Lookups then use online docs instead of local docs.

Handle skills-directory enumeration errors per package so one failure does not discard packages already resolved or prevent resolving others.

.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;
Comment on lines +109 to 118

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Later package docs are skipped

When the same package path exists in multiple package folders and the first copy has no usable docs, the unconditional break stops the package-folder scan before later copies are checked, so local lookup falls back online instead of using the later copy’s docs.

Continue scanning when the current copy yields no usable docs, and break only after usable docs are found.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at lines 109-118:

**Later package docs are skipped**

When the same package path exists in multiple package folders and the first copy has no usable docs, the unconditional `break` stops the package-folder scan before later copies are checked, so local lookup falls back online instead of using the later copy’s docs.

Continue scanning when the current copy yields no usable docs, and break only after usable docs are found.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Package index links point nowhere

When a caller runs bb-llms index with a project package that supplies skill-based docs and follows one of its links, IndexAsync emits each local entry’s DocumentPath, but ReadPackageEntries sets that path to components/<name>.txt or extensions/<name>.txt rather than the skill document’s path under references. Following links in the printed index therefore fails for entries newly discovered from package skills.

Preserve a usable relative document path for each local entry, or emit links that point to the actual package documentation files.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at line 118:

**Package index links point nowhere**

When a caller runs `bb-llms index` with a project package that supplies skill-based docs and follows one of its links, `IndexAsync` emits each local entry’s `DocumentPath`, but `ReadPackageEntries` sets that path to `components/<name>.txt` or `extensions/<name>.txt` rather than the skill document’s path under `references`. Following links in the printed index therefore fails for entries newly discovered from package skills.

Preserve a usable relative document path for each local entry, or emit links that point to the actual package documentation files.

}
}
Expand Down
24 changes: 16 additions & 8 deletions tools/BootstrapBlazor.LLMsDocs.Cli/Templates/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 <ComponentName> # 例:bb-llms get Table
```
2. 不确定准确名称或需要确认是否有对应文档时,先搜索。搜索结果合并当前项目包与官网索引:
```bash
bb-llms search <关键词>
```
2. 获取某组件的参数 / 事件 / 方法文档:
3. 获取搜索结果中的准确名称对应的参数 / 事件 / 方法文档:
```bash
bb-llms get <ComponentName> # 例: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` 指向自建/本地源。

## 前置条件

Expand Down
10 changes: 5 additions & 5 deletions tools/BootstrapBlazor.LLMsDocs.Cli/Templates/instructions.md
Original file line number Diff line number Diff line change
@@ -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 <ComponentName>`(例:`bb-llms get Table`)
- 列出全部组件:`bb-llms list`
- 已知准确名称时获取文档:`bb-llms get <ComponentName>`(例:`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` 指向自建/本地源。
Loading