Repository navigation
feat(LLMsDocsCli): resolve API docs from package skills #1325
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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) | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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, Handle skills-directory enumeration errors per package so one failure does not discard packages already resolved or prevent resolving others. Prompt for AI agentsIn `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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 Continue scanning when the current copy yields no usable docs, and break only after usable docs are found. Prompt for AI agentsIn `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.There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Package index links point nowhere When a caller runs Preserve a usable relative document path for each local entry, or emit links that point to the actual package documentation files. Prompt for AI agentsIn `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. |
||
| } | ||
| } | ||
|
|
||
| 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` 指向自建/本地源。 |
There was a problem hiding this comment.
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,
GetAsyncselects the first matching extension entry in assets order, andSearchAsynccollapses entries that share a generatedDocumentPath. 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