可导航 CLI 输出系统规格¶
意图¶
CLI 打印的每一次读取都是图中的一个节点。无论读者是从搜索结果、链接还是猜测落到某个位置,都必须看到自己在哪里,以及接下来可以执行的每一个动作,都以可运行的命令呈现:向上到该节点所在的层级,向下到其子节点,横向到其邻居,向外到它命名的节点。没有人需要提前知道路径,也不必阅读长页面来查找一个事实:他们进行搜索,落在能回答的最小子节点上,然后从那里继续移动。
本记录拥有读取提供的移动,以及它们在文本和 JSON 中的呈现方式。spec:AST-046 拥有这些移动首先行走的文档树。
非目标¶
- 每个命令的节点是什么。文档树属于
spec:AST-046;每个采用本记录的命令自行决定其节点。 - 交互式导航。没有提示符、分页器,也不会在运行之间保留状态;每一步移动都是其自身的命令。
- CLI 之外的链接,例如文档站点 URL。
需求¶
- FR1 — 读取标明自身位置。 位于顶层以下的读取 MUST 标明其位置:文档树节点标明其面包屑,区块标明其主题,搜索结果标明其上方的标题路径(
Astryx CLI › API › Functions › search())。 - FR2 — 向上。 除顶层外的每次读取 MUST 提供打开其所在层级的命令:对于区块,是其主题的区块列表;对于节点或主题,是其所在的层级(指南的命名空间,或扁平主题的 Guides 或 Foundations 层级,
spec:AST-046FR12);对于顶层命名空间,是主题列表。 - FR3 — 向下。 有子节点的读取 MUST 列出这些子节点,每个都带有摘要,并给出打开其中某一个的命令:命名空间列出其子节点,主题索引列出其区块,主题列表列出其主题和命名空间。在文本中,具有多个区块的主题一次只读取一个层级:不加选项的读取列出其区块,
--full打印整个文档;密集变体设计为整体阅读,因此--dense打印整个文档。JSON 契约不变:docs(topic)和--json返回整个文档,--index返回其区块。 - FR4 — 横向。 在有序层级中占据位置的读取 MUST 提供打开其前一项和后一项的命令(如果存在):区块在其主题中的邻居,以及文档树节点在其父级槽位中的邻居。
- FR5 — 向外。 命名另一个节点的读取 MUST 给出打开该节点的命令:命令文档打开其 API 函数,函数文档打开其命令,类型化文档打开其列为相关的每个文档。
- FR6 — 搜索落在节点上。 每个搜索结果 MUST 是一个节点,即能回答的最小子节点(
spec:AST-046FR10),并带有读取该节点的命令和打开其上一层的命令。 - FR7 — 移动即命令,JSON 承载它们。 在文本中,每个移动 MUST 是一个完整的命令,以命令名
spec:AST-081FR5 选定的命令名开头。在 JSON 中,读取 MUST 将移动作为数据携带:links,包含up、previous和next(在 FR4 适用时),以及related(在 FR5 适用于类型化文档时),每个都是一条astryx ...命令;搜索结果携带command和parent。除主题列表外,每次读取的linksMUST 出现在每个现有响应中,作为新增字段;已发布的类型 MUST 将每个移动类型化为astryx docs命令。文本视图 MUST 保持为 JSON 的投影。 - FR8 — 错误移动会告知去向。 不存在的路径、主题或区块 MUST 以稳定的错误码失败,并建议读者从最近存在的层级可以到达的节点(
spec:AST-046FR6)。 - FR9 — 移动是推导出来的,不是写死的。 CLI MUST 从文档树和主题的区块推导出 Up、Down 和 Across,从类型化文档自身的字段推导出 Out,这样没有任何文档自行列出移动,并且每个提供者的文档——无论是 Core、CLI 还是集成——都获得相同的移动。从一个文档到另一个文档的链接 MUST 按文档身份命名其目标,绝不按路径或标题。类型化字段(
fn、command、related)中的裸名称命名其所属提供者的文档,因此它是一种文档身份:它在该字段允许的类别中进行解析;如果一个名称匹配多个允许类别的文档,那就是错误,而不是静默选择。在文档文本内部,链接 MUST 写作{@link <target>},并读取为打开其文档的命令;未命名任何文档的链接 MUST 按原样打印。主题的区块 MAY 包含一个reference块,它包含所命名的文档而不是副本:读取 MUST 将其内联为该文档的内容(schema 的内容收窄到其投影命名的字段),然后是一行命名该文档及打开它的命令,这样读取仍然只返回稳定的内容块。该块无法包含的目标、字段或投影 MUST 使创作检查失败。workflow和collection块(GraphContentBlock)属于命名空间文档的blocks,由后续阶段渲染。没有提供者的目标命名的是编写该链接的提供者的文档:在合并了多个提供者区块的主题中,每个区块依据其自身的提供者解析。组件文档的文本字段(description、summary、label,任意深度,包括示例的 label;绝不包含代码或默认值)以及主题的 description 和 summary 也包含链接;组件文档的裸目标命名的是该组件提供者的文档,其中 Core 组件的提供者是 CLI 的文档,后者包含 Core 的指南。搜索结果的 description 也按相同方式读取。CLI MUST 在读取文档时解析每个链接,Doctor MUST 对未解析或有歧义的链接发出警告。链接命名的是文档身份,而不是提供者实例,因此它能跨越版本变化而保持有效。 - FR10 — 阶段 1 覆盖文档和搜索。
astryx docs和astryx searchMUST 满足 FR1–FR9、FR11 和 FR12。文档在代码块或正文中作为示例显示的某个命令不是链接:FR11 保持这一点。其他命令在后续阶段采用本记录,每个作为各自的变更。 - FR11 — 读取所显示的内容不能过期。 移动或交叉链接 MUST 在读取生成时推导,绝不存储在文档中。文档、提示行或仓库的 agent 提示所显示的每个其他
astryx命令 MUST 命名真实的命令,并且只能使用该命令接受的选项;它显示的每条astryx docs命令 MUST 能打开文档;否则测试 MUST 使构建失败。文档故意显示错误的命令(作为错误码示例)MUST 被列为此类命令,并且当某个条目不再显示时,该列表 MUST 失败。 - FR12 — 每个文档都只需一次行走。 提供者发布的每个文档 MUST 可通过读取提供的移动从
astryx docs到达:从主题列表和每个命名空间 Down,然后 Across 和 Out。邻居 MUST 一致:某一项的 Next 打开的读取将该项命名为其 Previous。测试 MUST 从顶部遍历整个图,并在遇到无法到达的文档文件、无法打开的移动或未命名任何文档的链接时失败。
平台支持¶
这些移动操作是普通命令,以 FR5 选择的命令名 spec:AST-081 开头,因此它们可以在 CLI 运行的任何 shell 中运行。JSON 携带它们时不带该名称。
当前状态影响¶
在此记录之前,只有 docs-tree 命名空间和类型化文档提供了向上的路径,且仅限于文本中;章节、主题和主题的索引都是死胡同。
阶段 1 变更:
- 在文本中,单独读取主题时,如果该主题有多个章节,会列出其章节;
--full和--dense会完整打印;docs(topic)和--json仍返回整个文档; docs.node、docs.index、docs.detail和docs.detail.section携带links:每次读取都有up,章节和 docs-tree 节点上还有previous和next;- 章节读取、整个主题的读取以及主题索引都以各自的移动操作结尾;
- 文档搜索命中结果携带
parent及其上方的标题路径; - 文档之间的链接是类型化的(文本中使用
{@link <target>},以及类型化字段),在每次读取时解析,并由 Doctor 检查并发出警告;CLI 自身文档中手写的astryx docs链接会变成类型化链接; - 一项测试证明文档或提示中显示的每个命令都是具有真实选项的真实命令,并且每个 docs 命令都能打开;
- 一项测试从顶部遍历整个图,并到达 CLI 随附的每个文档文件,正如 FR12 所述。
architecture:cli-surface INV27 将此记录落实到代码中。
验证¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 |
|---|---|---|---|
| FR1–FR5, FR7 | docs() 调度器测试、CLI 运行以及图遍历(packages/cli/test/docs-graph.test.mjs) |
顶层命名空间;位于其槽位中部的类型化文档;指南的第一个和最后一个章节;一个扁平主题的整体 | 读取没有向上的路径、移动操作无法运行,或文本移动没有 links |
| FR6 | 搜索测试 | 章节命中;docs-tree 命中;主题命中 | 命中结果没有 parent,或 parent 无法打开上一级 |
| FR8 | spec:AST-046 FR6 测试 |
未知路由、主题和章节 | 没有建议的死胡同 |
| FR9 | 链接测试、doctor docs-tree 检查以及图遍历 | 内联链接、列表和表格中的链接、类型化字段;指向另一个提供者的链接;代码反引号中的链接 | 链接未指向任何文档却仍然通过、链接通过猜测解析,或使用了存储的路由 |
| FR11 | 图遍历的 shown-commands 检查 | 文档正文和代码块中的命令、CLI 提示行以及 agent 提示;故意错误列表 | CLI 没有的命令或选项、无法打开的 docs 命令,或过时的列表条目 |
| FR12 | 图遍历(packages/cli/test/docs-graph.test.mjs) |
每个树节点;CLI 随附的每个文档文件;章节、主题、指南和树节点上的 Next 和 Previous | 某个文档文件无法被遍历到达、移动操作无法打开,或某个 Next 的读取指向另一个 Previous |
决策日志¶
DEC-1 — 移动操作是命令,不是路由¶
参考: spec:AST-047/DEC-1
决策者: josephfarina, 2026-09-28
每个移动操作都是一个完整的 astryx ... 命令,读者可以直接运行。
已否决:裸路由。它们要求读者重新构建命令,并知道章节键应放在哪个参数中。
DEC-2 — 跨命名时使用相邻项,而非整个层级¶
参考: spec:AST-047/DEC-2
决策者: josephfarina, 2026-09-28
FR4 命名前一项和后一项;整个层级只需一次向上移动。
已否决:在每次读取时列出所有同级项,这会使每个叶节点与其父节点一样长。
DEC-3 — 按命令采用,文档和搜索优先¶
参考: spec:AST-047/DEC-3
决策者: josephfarina, 2026-09-28
读者首先会在文档中迷失,而搜索是他们到达的方式。其他命令将采用这些移动操作作为各自的变更。
已否决:为每个命令都做一处变更,这样变更量过大难以审查,并且会一次性决定每个命令的节点。
未决问题¶
- 哪个命令接下来采用此记录,以及它的节点是什么。
- 顶层命名空间是否在彼此之间提供
previous和next。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx