iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/zh-Hans/start/getting-started.md

@@ -0,0 +1,170 @@
+# 开始使用 iCode
+
+本教程介绍如何安装 iCode、配置模型，并在项目中使用智能体完成一次开发任务。
+
+## 1. 安装 iCode
+
+使用 [uv](https://docs.astral.sh/uv/getting-started/installation/) 安装 iCode。如果系统中没有 Python 3.14，uv 会自动下载：
+
+```shell
+uv tool install iCode-TUI
+```
+
+以后升级请运行 `uv tool upgrade iCode-TUI`，卸载请运行 `uv tool uninstall iCode-TUI`。
+
+Windows（x64）和 Linux（x86-64 或 ARM64，glibc 2.27 或更高版本）无需其他准备。Apple 芯片的 Mac 需要先运行 `xcode-select --install` 安装 Xcode 命令行工具，uv 安装时要用它编译一个依赖。
+
+如果以前用过 iCode 离线安装包，请先删除它。删除它解压到的文件夹：macOS 上是 `~/Library/Application Support/pyapp/chrys`；Linux 上是 `~/.local/share/pyapp/chrys`，设置了 `XDG_DATA_HOME` 时是 `$XDG_DATA_HOME/pyapp/chrys`；Windows 上是 `%LOCALAPPDATA%\pyapp\data\chrys`。然后在 macOS 或 Linux 上删除 `~/.local/bin/chrys`，在 Windows 上删除 `%LOCALAPPDATA%\chrys\bin` 文件夹。
+
+如果 uv 提示 `icode` 已存在，说明已经有同名命令：可能是之前用离线安装包安装的 iCode，也可能是其他同名程序。确认是 iCode 后，运行 `uv tool install --force iCode-TUI` 覆盖它。
+
+### 离线安装包
+
+Intel 芯片的 Mac、Arm 版 Windows、较旧的 Linux 或无法联网的设备，请改用 [iCode Releases](https://github.com/openJiuwen-ai/iCode/releases) 上的预构建离线安装包。安装包已包含 Python 和全部依赖，无需另行安装 Python。
+
+以下命令中的 `<version>` 和 `<architecture>` 是占位符，请替换为下载文件名中的实际值。
+
+#### macOS
+
+根据处理器选择 `icode-macos-aarch64-v<version>-offline.tar.gz`（Apple 芯片）或 `icode-macos-x86_64-v<version>-offline.tar.gz`（Intel），然后在下载目录运行：
+
+```bash
+tar xzf icode-macos-<architecture>-v<version>-offline.tar.gz
+chmod +x ./icode
+./icode install
+```
+
+#### Linux
+
+根据处理器选择 `icode-linux-x86_64-v<version>-offline.tar.gz` 或 `icode-linux-aarch64-v<version>-offline.tar.gz`，然后在下载目录运行：
+
+```bash
+tar xzf icode-linux-<architecture>-v<version>-offline.tar.gz
+chmod +x ./icode
+./icode install
+```
+
+Linux x86-64 安装包要求 glibc 2.17 或更高版本，ARM64 安装包要求 glibc 2.18 或更高版本。Alpine Linux 等只提供 musl 的发行版不在预构建包的支持范围内。
+
+#### Windows
+
+下载 `icode-windows-x86_64-v<version>-offline.zip`（Arm 版 Windows 请下载 `icode-windows-aarch64-v<version>-offline.zip`）并解压，在 PowerShell 中进入解压目录，然后运行：
+
+```powershell
+.\icode.exe install
+```
+
+安装器会尝试将 iCode 加入当前用户的 `PATH`。安装完成后，请打开一个新终端。
+
+### 验证安装
+
+```shell
+icode --version
+```
+
+命令应输出 iCode 的版本号。如果用 uv 安装后终端找不到 `icode`，请运行 `uv tool update-shell`，然后打开新终端。
+
+使用离线安装包时，在 macOS 或 Linux 上，如果系统找不到 `icode`，请按安装器的提示将 `~/.local/bin` 加入 `PATH`；如果安装器提示 `~/.local/bin/icode` 已存在，该命令会启动其他程序，请改用 `chrys` 命令。在 Windows 上请打开新的终端；如果安装器提示更新用户 PATH 失败，请手动将 `%LOCALAPPDATA%\chrys\bin` 加入用户 `PATH`。
+
+## 2. 在项目中启动 iCode
+
+建议在使用 Git 管理或能够安全恢复的项目中开始本教程。在让智能体修改文件前，请先保存尚未写入磁盘的内容，并使用 Git commit 记录已有变更，以便区分智能体所做的修改，并在需要时恢复到修改前的状态。
+
+在终端中进入要处理的项目目录并启动 iCode：
+
+```shell
+cd <project-directory>
+icode
+```
+
+将 `<project-directory>` 替换为项目目录的实际路径。启动后如需切换目录，请参阅[工作目录](../guides/daily-use/workspaces.md)。
+
+## 3. 配置模型
+
+1. 按 **F4** 或点击屏幕底部的 `f4 模型`，打开“模型配置”窗口。
+2. 点击“新建”。
+3. 填写自定义的配置名称，例如 `我的模型`。
+4. 在模型选项区域，选择模型提供商和 API 样式。仅 OpenAI 和 DeepSeek（OpenAI）提供 API 样式选项。配置前，请根据模型服务商的文档确认其支持的 API，并按文档建议选择 `Chat Completions` 或 `Responses`。如果服务商仅支持其中一种 API，请选择对应的 API 样式；如果两种 API 均支持，则根据服务商的建议或实际使用需求选择。
+5. 填写模型 ID，并根据模型服务的要求填写服务地址和 API 密钥。这些字段名称以所选提供商开头，例如“OpenAI 模型”。
+6. 根据模型提供商的说明，填写最大上下文窗口和最大输出词元数。
+7. 保存配置并关闭配置窗口。若此前没有可用的模型配置，该配置将自动成为当前使用的模型配置。
+
+> **提示**
+>
+> 直接填写的 API 密钥会随模型配置文件保存在本机。若不希望将密钥写入配置文件，请[通过环境变量提供 API 密钥](../guides/configuration/models.md#通过环境变量提供-api-密钥)。
+
+### 验证模型连接
+
+在输入栏中提交：
+
+```text
+你好
+```
+
+iCode 应正常返回问候回复。若模型服务返回错误，请重新检查模型 ID、服务地址、API 密钥等模型配置。
+
+## 4. 使用智能体
+
+### 选择智能体
+
+iCode 默认提供两个主智能体：Q&A Agent（问答智能体）和 Code Agent（代码智能体）。两者都可以阅读项目、分析代码和讨论方案，但定位和可用工具不同：Q&A Agent 主要提供只读能力，适合了解项目、解释代码和分析问题；Code Agent 则可以修改文件、运行命令，适合编写、审查、重构、调试和验证代码。
+
+当前没有正在运行的智能体任务时，可以切换智能体。在输入栏中输入 `#`，输入栏上方会显示智能体列表，可以通过鼠标点击，或使用上下方向键并按回车进行选择。也可以点击输入栏上方状态栏中的智能体名称，在智能体选择窗口中进行切换。
+
+### 使用 Q&A Agent
+
+Q&A Agent 适合在**不修改项目的情况下**了解项目、分析代码、追踪实现和讨论方案。它会基于项目内容给出回答，并尽量提供可追溯的依据。
+
+切换到 **Q&A Agent** 后，在输入栏中输入 `/new` 并回车，开始新会话。
+
+以下示例假设当前项目是一个待办事项应用，仅用于展示使用方式。实际使用时，请根据实际项目调整问题和任务。
+
+```text
+请分析任务列表的实现，并为增加“清除已完成任务”功能提出方案。说明需要修改哪些文件以及实现步骤。
+```
+
+Q&A Agent 可能会搜索文件、读取文件内容或运行只读命令。工具调用会以卡片形式显示，完成分析后会给出实现方案。
+
+### 使用 Code Agent
+
+Code Agent 适用于需要**修改文件、运行命令和验证结果**的任务。它会先阅读相关代码，再按任务要求实现、调试或重构代码。
+
+Q&A Agent 给出实现方案后，可以在同一会话中切换到 **Code Agent**。切换智能体不会清除当前会话的上下文，Code Agent 可以基于已有方案继续完成开发任务：
+
+```text
+请根据刚才讨论的方案实现“清除已完成任务”功能。修改代码并运行必要的测试。
+```
+
+如果出现审批对话框，请检查即将执行的工具调用，尤其是命令内容、目标文件和影响范围，确认符合预期后再批准。有关不同审批模式的行为，请参阅[配置审批模式](../guides/configuration/approval.md)。
+
+任务完成后，检查智能体的最终回复，并通过 `/diff` 浏览当前会话记录的文件修改。随后使用 Git 等版本控制工具检查工作目录的完整变更，并确认功能正确、必要的测试已经通过且不包含无关改动。确认无误后，可以提交这些变更。
+
+### 阅读和复制回复
+
+所有智能体的回复都支持 Markdown、数学公式和 Mermaid 图表。你自己发送的消息中的公式不作数学渲染。
+
+列表和引用可以包含标题、表格、代码和公式。
+
+回复中，`$...$` 或 `\(...\)` 包围的公式以单行显示；`math` 代码块、`$$...$$` 或 `\[...\]` 中的块公式可显示分式、矩阵和对齐公式。普通文字、价格和 shell 变量保留原有 Markdown 格式。不支持或过宽的公式会完整显示为可换行的源码。
+
+例如，`$x^{n+1}$` 显示为 xⁿ⁺¹，`$90^\circ$` 显示为 90°。
+
+Mermaid 代码块会显示为图表，点击**打开完整图表**可查看、滚动完整内容。部分图表会简化显示并提示，不支持的图表保留源码。
+
+鼠标选择复制显示结果，不会因屏幕折行额外插入换行。消息标题旁的**复制**保留原始 Markdown 和 LaTeX。重新打开旧会话时，也会使用当前的渲染效果。
+
+## 5. 结束本次使用
+
+若要结束本次使用，输入 `/exit` 或按 `Ctrl+Q` 退出 iCode。
+
+## 下一步
+
+至此，已经完成 iCode 的安装和模型配置，并了解了 Q&A Agent 和 Code Agent 的基本使用方式，以及如何在同一会话中配合完成开发任务。
+
+接下来，可以继续探索：
+
+- [配置智能体](../guides/configuration/agents.md)，创建或修改智能体，并设置其指令、模型、工具和子智能体
+- [配置模型](../guides/configuration/models.md)，连接并切换不同的模型服务
+- [工作目录](../guides/daily-use/workspaces.md)
+- [配置审批模式](../guides/configuration/approval.md)
+- 通过 [Skills](../guides/extensions/skills.md) 和 [MCP](../guides/extensions/mcp.md) 扩展 iCode

chrys/app/tui/screens/guides/_docs/zh-Hans/start/what-is-icode.md

@@ -0,0 +1,34 @@
+# 什么是 iCode
+
+**iCode 是一个用于运行和构建智能体（Agent）的平台。**
+
+iCode 支持通过自然语言与智能体交互，完成文件阅读与修改、Shell 命令执行、代码库搜索等任务，也可以将复杂任务委派给子智能体。
+
+iCode 的主要交互方式是终端用户界面（Terminal User Interface，TUI），用于集中呈现对话、任务执行和工具调用过程。工具调用会以卡片形式展示，便于了解智能体正在执行的操作。除 TUI 外，iCode 还支持在脚本中以无界面模式运行，通过智能体客户端协议（Agent Client Protocol，ACP）接入编辑器，或在浏览器中运行 TUI。
+
+## 核心特点
+
+* **灵活组合智能体和模型。** iCode 可通过界面点击或快捷命令快速切换智能体和模型，并在同一个会话中根据任务选择不同的组合。
+
+* **智能体可按需配置。** 可以通过 TUI 配置智能体的指令、模型、工具、Skills、MCP 服务器和子智能体，也可以直接编辑 YAML 配置文件，无需修改 iCode 源代码。
+
+## 模型支持
+
+智能体决定“如何工作”，模型则提供推理和生成能力。
+
+在 iCode 中，智能体与模型彼此独立，可以根据不同任务灵活组合。iCode 提供内置智能体，但不提供模型配置或 API 凭据。首次使用前，需要创建模型配置并连接相应的模型服务。
+
+iCode 目前支持 Anthropic、OpenAI、DeepSeek 和 GLM 等模型提供商，也可以通过 OpenAI API 兼容端点连接其他模型服务，包括本地部署的模型。
+
+## 使用 iCode
+
+iCode 提供多种使用入口，可以根据不同的工作场景选择合适的方式：
+
+- **TUI**：iCode 的主要交互界面，适合交互式任务。支持在会话中查看工具调用、处理审批请求，以及切换智能体和模型配置。
+- **无界面命令行（Command-Line Interface，CLI）**：通过 `icode run` 执行非交互式任务，适合一次性任务、脚本和自动化流程。
+- **浏览器界面**：[在浏览器中运行 TUI](../guides/running/icode-serve.md)，适合需要在终端之外使用交互界面的场景。
+- **ACP 服务**：将 iCode 作为智能体后端，[接入支持 ACP 的编辑器或其他开发工具](../guides/running/icode-acp.md)。
+
+首次使用建议从 TUI 开始。通过交互式会话，可以快速熟悉智能体、模型和工具的协作方式。
+
+如果准备开始使用 iCode，请阅读 [开始使用 iCode](getting-started.md)，完成安装、模型配置和首次运行。

chrys/app/tui/screens/guides/index.py

@@ -0,0 +1,215 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""User-guide docs index — YAML topic parsing and docs-root resolution.
+
+Pure logic with no Textual dependency: models the ``docs/index.yaml`` topic
+tree and locale ordering, and locates the docs root at runtime. The dialog
+content is read from the files referenced here; nothing is hardcoded in code.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+INDEX_FILENAME = "index.yaml"
+BUNDLED_DOCS_DIRNAME = "_docs"
+"""Where built wheels carry ``docs/``, next to this module (``pyproject.toml`` force-include)."""
+_CHECKOUT_DEPTH = 6
+"""``<checkout>/src/chrys/app/tui/screens/guides/index.py`` sits this many directories below the checkout."""
+
+
+class GuideIndexError(Exception):
+    """Raised when the guide index mapping table is missing or malformed."""
+
+
+@dataclass(frozen=True, slots=True)
+class GuideTopic:
+    """One node of the guide topic tree (branch or leaf)."""
+
+    id: str | None
+    """Stable identifier, referenced by the ``default`` field."""
+    path: str | None
+    """Leaf-only: markdown path relative to the locale docs subdirectory."""
+    labels: Mapping[str, str] | None
+    """Per-locale display-name overrides, keyed by entries in ``locales``."""
+    children: tuple[GuideTopic, ...]
+    """Branch-only: nested topics."""
+
+    @property
+    def is_leaf(self) -> bool:
+        return self.path is not None
+
+    @property
+    def is_branch(self) -> bool:
+        return bool(self.children)
+
+
+@dataclass(frozen=True, slots=True)
+class GuideIndex:
+    """Parsed ``docs/index.yaml`` topic index."""
+
+    locales: tuple[str, ...]
+    """Ordered locales, also used as docs subdirectory names."""
+    default_topic_id: str | None
+    topics: tuple[GuideTopic, ...]
+
+
+def resolve_docs_root() -> Path | None:
+    """Locate the docs root, or ``None`` when unavailable.
+
+    Resolution order:
+    1. ``CHRYS_DOCS_ROOT``, for previewing edited docs.  A value without an
+       ``index.yaml`` reports the docs as missing instead of quietly showing
+       another copy;
+    2. the copy bundled into built wheels next to this module;
+    3. the source checkout's ``docs/`` (an editable install runs from ``src/``).
+    """
+    override = os.environ.get("CHRYS_DOCS_ROOT")
+    if override:
+        candidate = Path(override).expanduser()
+        return candidate if (candidate / INDEX_FILENAME).is_file() else None
+    here = Path(__file__).resolve()
+    bundled = here.parent / BUNDLED_DOCS_DIRNAME
+    if (bundled / INDEX_FILENAME).is_file():
+        return bundled
+    checkout = here.parents[_CHECKOUT_DEPTH]
+    if (checkout / "pyproject.toml").is_file() and (checkout / "docs" / INDEX_FILENAME).is_file():
+        return checkout / "docs"
+    return None
+
+
+def load_guide_index(docs_root: Path) -> GuideIndex:
+    """Parse and validate ``docs_root/index.yaml`` into a :class:`GuideIndex`.
+
+    Raises :class:`GuideIndexError` with a stable English diagnostic for
+    missing files or schema violations; the caller renders a localized error
+    state instead of crashing the dialog.
+    """
+    index_path = Path(docs_root) / INDEX_FILENAME
+    if not index_path.is_file():
+        raise GuideIndexError(f"Guide index missing: {index_path}")
+    try:
+        raw = yaml.safe_load(index_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, yaml.YAMLError) as error:
+        raise GuideIndexError(f"Guide index unreadable: {index_path}") from error
+    if not isinstance(raw, dict):
+        raise GuideIndexError(f"Guide index must be a mapping: {index_path}")
+
+    locales = _parse_locales(raw.get("locales"), index_path)
+    default_topic_id = _parse_default(raw.get("default"), index_path)
+    topics = _parse_topics(raw.get("topics"), index_path)
+    return GuideIndex(locales=locales, default_topic_id=default_topic_id, topics=topics)
+
+
+def language_cycle(index: GuideIndex) -> tuple[str, ...]:
+    """Return the ordered locales the space key cycles through."""
+    return index.locales
+
+
+def default_topic_id(index: GuideIndex) -> str | None:
+    """Resolve the default leaf: the ``default`` field, else the first leaf."""
+    if index.default_topic_id is not None and _find_leaf(index.topics, index.default_topic_id) is not None:
+        return index.default_topic_id
+    first = next(iter_leaf_topics(index.topics), None)
+    return first[0] if first is not None else None
+
+
+def iter_leaf_topics(topics: tuple[GuideTopic, ...]) -> Iterator[tuple[str | None, GuideTopic]]:
+    """Yield ``(id, topic)`` for every leaf in document order.
+
+    Leaves without an ``id`` yield ``(None, topic)``; callers that only need
+    the topic object may ignore the first element.
+    """
+    for topic in topics:
+        if topic.is_leaf:
+            yield topic.id, topic
+        else:
+            yield from iter_leaf_topics(topic.children)
+
+
+def _find_leaf(topics: tuple[GuideTopic, ...], topic_id: str) -> GuideTopic | None:
+    for leaf_id, topic in iter_leaf_topics(topics):
+        if leaf_id == topic_id:
+            return topic
+    return None
+
+
+def _parse_locales(raw: object, index_path: Path) -> tuple[str, ...]:
+    if raw is None:
+        raise GuideIndexError(f"Guide index missing 'locales': {index_path}")
+    if not isinstance(raw, list):
+        raise GuideIndexError(f"Guide index 'locales' must be a list: {index_path}")
+    locales: list[str] = []
+    for locale in raw:
+        if not isinstance(locale, str) or not locale.strip():
+            raise GuideIndexError(f"Guide index 'locales' has an invalid locale: {index_path}")
+        normalized = locale.strip()
+        if normalized in locales:
+            raise GuideIndexError(f"Guide index 'locales' has duplicate locale {normalized!r}: {index_path}")
+        locales.append(normalized)
+    if not locales:
+        raise GuideIndexError(f"Guide index 'locales' must list at least one locale: {index_path}")
+    return tuple(locales)
+
+
+def _parse_default(raw: object, index_path: Path) -> str | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, str) or not raw.strip():
+        raise GuideIndexError(f"Guide index 'default' must be a non-empty string: {index_path}")
+    return raw.strip()
+
+
+def _parse_topics(raw: object, index_path: Path) -> tuple[GuideTopic, ...]:
+    if raw is None:
+        raise GuideIndexError(f"Guide index missing 'topics': {index_path}")
+    if not isinstance(raw, list):
+        raise GuideIndexError(f"Guide index 'topics' must be a list: {index_path}")
+    return tuple(_parse_topic(item, index_path, depth=0) for item in raw)
+
+
+def _parse_topic(raw: object, index_path: Path, *, depth: int) -> GuideTopic:
+    if depth > 8:
+        raise GuideIndexError(f"Guide index topic nesting too deep: {index_path}")
+    if not isinstance(raw, dict):
+        raise GuideIndexError(f"Guide index topic must be a mapping: {index_path}")
+    topic_id = raw.get("id")
+    if topic_id is not None and (not isinstance(topic_id, str) or not topic_id.strip()):
+        raise GuideIndexError(f"Guide index topic 'id' must be a non-empty string: {index_path}")
+    path = raw.get("path")
+    if path is not None and (not isinstance(path, str) or not path.strip()):
+        raise GuideIndexError(f"Guide index topic 'path' must be a non-empty string: {index_path}")
+    labels_raw = raw.get("labels")
+    if labels_raw is not None and not isinstance(labels_raw, dict):
+        raise GuideIndexError(f"Guide index topic 'labels' must be a mapping: {index_path}")
+    labels: Mapping[str, str] | None = None
+    if labels_raw:
+        for locale, label in labels_raw.items():
+            if not isinstance(locale, str) or not locale.strip():
+                raise GuideIndexError(f"Guide index topic 'labels' has an invalid locale key: {index_path}")
+            if not isinstance(label, str) or not label.strip():
+                raise GuideIndexError(f"Guide index topic 'labels' has an empty label for {locale!r}: {index_path}")
+        labels = {locale.strip(): label.strip() for locale, label in labels_raw.items()}
+    children_raw = raw.get("children")
+    if children_raw is not None and not isinstance(children_raw, list):
+        raise GuideIndexError(f"Guide index topic 'children' must be a list: {index_path}")
+    has_path = path is not None
+    # 'children' declared (even as an empty list) alongside 'path' is a
+    # contradiction — refuse presence of both keys, not just non-empty lists.
+    if has_path and children_raw is not None:
+        raise GuideIndexError(f"Guide index topic has both 'path' and 'children': {index_path}")
+    has_children = children_raw is not None and len(children_raw) > 0
+    if not has_path and not has_children:
+        raise GuideIndexError(f"Guide index topic needs 'path' (leaf) or 'children' (branch): {index_path}")
+    children = tuple(_parse_topic(child, index_path, depth=depth + 1) for child in children_raw) if has_children else ()
+    return GuideTopic(
+        id=topic_id.strip() if isinstance(topic_id, str) else None,
+        path=path.strip() if isinstance(path, str) else None,
+        labels=labels,
+        children=children,
+    )

chrys/app/tui/screens/guides/reader.py

@@ -0,0 +1,173 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""User-guide markdown reading — H1 extraction, file loading, display names.
+
+Pure logic with no Textual dependency.  Document content is always read from
+the filesystem at the moment it is needed; a missing file yields ``None`` so
+the dialog can show its localized "no content" state.
+"""
+
+from __future__ import annotations
+
+import posixpath
+from pathlib import Path, PurePosixPath
+
+from chrys.app.tui.screens.guides.index import GuideIndex, GuideTopic, iter_leaf_topics
+
+
+def extract_h1(markdown: str | None) -> str | None:
+    """Return the first top-level ATX heading (``# ...``) text, if any.
+
+    ``None`` input (a missing file) yields ``None`` — the caller falls back
+    through its display-name chain instead of crashing.
+    """
+    if markdown is None:
+        return None
+    for line in markdown.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("# "):
+            return stripped[2:].strip()
+    return None
+
+
+def read_topic_markdown(docs_root: Path, index: GuideIndex, topic: GuideTopic, locale: str) -> str | None:
+    """Read the markdown for *topic* in *locale*, or ``None`` when unavailable.
+
+    Paths are resolved against the locale subdirectory and confined to it:
+    a ``path`` escaping the docs root (e.g. ``../``) is refused.  A file that
+    cannot be read or is not UTF-8 counts as unavailable too.
+    """
+    if topic.path is None:
+        return None
+    if locale not in index.locales:
+        return None
+    try:
+        docs_root = Path(docs_root).resolve()
+        locale_root = (docs_root / locale).resolve()
+        candidate = (locale_root / topic.path).resolve()
+        if (
+            not locale_root.is_relative_to(docs_root)
+            or not candidate.is_relative_to(locale_root)
+            or not candidate.is_file()
+        ):
+            return None
+        return candidate.read_text(encoding="utf-8")
+    except OSError, UnicodeDecodeError:
+        return None
+
+
+def resolve_guide_link(
+    index: GuideIndex,
+    source_topic: GuideTopic,
+    href: str,
+) -> tuple[GuideTopic | None, str]:
+    """Resolve a markdown relative link from *source_topic* to a guide leaf.
+
+    Returns ``(topic, anchor)`` where *topic* is the leaf whose ``path`` the
+    link resolves to — or ``None`` for page-internal ``#anchor`` links,
+    external URLs, and paths outside the topic tree — and *anchor* is the
+    ``#fragment`` suffix (or ``""``).
+
+    Resolution is purely lexical over ``PurePosixPath`` (never
+    ``Path.resolve()``, which would resolve against the process cwd) and
+    relative to the source topic's directory.  Topic paths are
+    language-independent, so the link resolves identically in every document
+    language; the caller loads the target with the current language.
+    """
+    if not href or source_topic.path is None:
+        return None, ""
+    stripped = href.strip()
+    if stripped.startswith("#") or "://" in stripped:
+        return None, ""
+    path_part, _separator, fragment = stripped.partition("#")
+    if not path_part:
+        return None, ""
+    source_dir = PurePosixPath(source_topic.path).parent
+    # normpath folds "." / ".." lexically; an escaped prefix (e.g. ``../x``
+    # from the docs root) or an absolute href can never equal a topic path.
+    normalized = posixpath.normpath(str(source_dir / PurePosixPath(path_part)))
+    for _leaf_id, topic in iter_leaf_topics(index.topics):
+        if topic.path == normalized:
+            return topic, fragment
+    return None, ""
+
+
+def _labels_label(topic: GuideTopic, *, locale: str, default_locale: str) -> str | None:
+    """Return the per-locale display-name override, or ``None``.
+
+    Resolution: exact *locale* first, then the *default_locale* (the docs
+    root's primary language).  Unknown locales are skipped, so pre-declaring
+    a label for a future language never breaks existing ones.
+    """
+    if not topic.labels:
+        return None
+    if locale in topic.labels:
+        return topic.labels[locale]
+    if default_locale in topic.labels:
+        return topic.labels[default_locale]
+    return None
+
+
+def topic_display_name(topic: GuideTopic, *, locale: str, default_locale: str, current_h1: str | None) -> str:
+    """Resolve a leaf topic's display name via the documented fallback chain.
+
+    Order: per-locale ``labels`` → current-language H1 → filename stem →
+    topic id.  The current-language H1 is the only H1 consulted: a topic
+    without content in the active language degrades to its file name rather
+    than borrowing another language's title.
+    """
+    labeled = _labels_label(topic, locale=locale, default_locale=default_locale)
+    if labeled:
+        return labeled
+    if current_h1:
+        return current_h1
+    if topic.path:
+        return Path(topic.path).stem
+    if topic.id:
+        return topic.id
+    return ""
+
+
+def branch_display_name(topic: GuideTopic, *, locale: str, default_locale: str) -> str:
+    """Resolve a branch node's display name.
+
+    Branches have no per-language file, so there is no H1 fallback.  Order:
+    per-locale ``labels`` → the common directory segment shared by the
+    branch's descendant files (e.g. ``daily-use``) → topic id.
+    """
+    labeled = _labels_label(topic, locale=locale, default_locale=default_locale)
+    if labeled:
+        return labeled
+    directory = _branch_directory_name(topic)
+    if directory:
+        return directory
+    if topic.id:
+        return topic.id
+    return ""
+
+
+def _branch_directory_name(topic: GuideTopic) -> str | None:
+    """Return the last shared directory segment of the branch's leaf files.
+
+    For leaves under ``guides/configuration/*`` this is ``configuration``;
+    for ``guides/daily-use/*`` it is ``daily-use``.  ``None`` when the
+    branch has no leaf files or the files share no directory.
+    """
+    paths = [Path(leaf.path) for _leaf_id, leaf in iter_leaf_topics((topic,)) if leaf.path]
+    if not paths:
+        return None
+    common = list(paths[0].parts[:-1])
+    for path in paths[1:]:
+        common = _common_prefix(common, list(path.parts[:-1]))
+        if not common:
+            return None
+    return common[-1] if common else None
+
+
+def _common_prefix(a: list[str], b: list[str]) -> list[str]:
+    prefix: list[str] = []
+    for left, right in zip(a, b, strict=False):
+        if left != right:
+            break
+        prefix.append(left)
+    return prefix