qi-coding-agent 0.1.0__py3-none-any.whl

qi_agent/system_prompt.py

@@ -0,0 +1,278 @@
+"""system prompt 构建(对齐 pi 的 `dist/core/system-prompt.js`)。
+
+pi 的默认 prompt 是**代码内字符串 + 运行时拼接**;qi v1 曾把基座写成包数据
+`src/qi_agent/SYSTEM.md`(静态 Markdown,无占位符)。本模块改为对齐 pi:
+
+1. **默认基座在代码里**(`DEFAULT_*` 三段静态文案 + 按实际工具集生成的
+   「可用工具」「指南」两块动态文案);
+2. `SYSTEM.md`(项目 > 用户)一旦存在就**整体替换**默认基座 —— pi 的
+   customPrompt 语义,不是只换某一层;
+3. 无论走哪条分支,后面统一追加:**项目上下文**(AGENTS.md 等)→ **技能清单**(XML)
+   → **当前工作目录**。
+
+P-E4c 起 core **不再追加角色层与数据源** —— 两者都是“角色”的概念,归 qi-agents
+(E1.1/E15):角色说明由它通过 `before_agent_start` 拼进来(那个钩子的返回值是链式的),
+数据源实例住在角色目录里。默认基座的身份描述也因此不再宣称“多 agent”。
+
+副作用(与 pi 一致,已写进 docs/configuration.md):自定义 SYSTEM.md 会丢掉
+默认基座里的「可用工具 / 指南」两块 —— 那两块只随默认基座出现。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Sequence
+
+if TYPE_CHECKING:                                  # 只为类型标注,避免运行期耦合
+    from .extensions import Tool
+    from .models import Skill
+
+# ── 默认基座:静态文案 ───────────────────────────────────────
+
+DEFAULT_IDENTITY = (
+    "你是运行在 qi 框架中的 AI 助手。qi 是一个编码 agent 框架:默认单 agent 干活;"
+    "装了 qi-agents 扩展后可以按某个角色运行,也能把任务委派给别的角色。"
+)
+
+DEFAULT_ENVIRONMENT = """环境:
+- 你有一个**会话工作目录**(见文末),所有文件工具的相对路径都基于它;只在该目录内读写。
+- **需要事实时才用工具**:涉及本仓库/文件/命令的问题,用工具确认而不是凭记忆猜。
+  寒暄、闲聊、概念性问答不需要动工具 —— 不要为了“显得在干活”而调工具。
+- 需求不明确时用 `clarify` 提问;不要猜一个需求就动手。"""
+
+DEFAULT_METHOD = """做法:
+1. **先看再做**:改文件前先读;改代码前先定位调用点与影响面。
+2. **小步验证**:改动后尽量用工具(读回、跑测试)确认结果,再报告结论。
+3. **不编造**:工具没返回的信息就说没有;不确定就说不确定。失败与报错如实说,并给出下一步建议。
+4. **务实**:能一步到位的不要拆成五步;不要为了完整而完整。"""
+
+
+def build_guidelines(tool_names: Sequence[str], tools: Sequence[Tool] = ()) -> list[str]:
+    """按**实际可用工具**生成指南(pi 的条件化 guidelines)。
+
+    pi 只在「有 bash/powershell 但没有 grep/find/ls」时提示用 shell 做文件操作,
+    并按两者是否同时存在分三种措辞。qi 的默认工具集自带 ls/find/grep,所以这条通常
+    不出现,但收窄到 `["read","bash","edit","write"]` 时就会出现 —— 与 pi 同形。
+
+    `tools` 非空时额外追加**工具自带的指南**(pi 的 `promptGuidelines`):它们随工具
+    启用而出现,所以写工具的人不必把“用这个工具而不是那个”塞进 description。
+    自带指南**必须点名工具**(平铺追加时“这个”指谁看不出来)。
+    """
+    has = set(tool_names)
+    out: list[str] = []
+
+    def add(text: str) -> None:
+        if text not in out:
+            out.append(text)
+
+    if ({"bash", "powershell"} & has) and not ({"grep", "find", "ls"} & has):
+        if "bash" in has and "powershell" in has:
+            add("用 bash 或 PowerShell 做文件操作:列目录、搜索、找文件")
+        elif "powershell" in has:
+            add("用 PowerShell 做文件操作:列目录、搜索、找文件")
+        else:
+            add("用 bash 做文件操作:列目录、搜索、找文件")
+    for tool in tools:
+        for line in tool.prompt_guidelines:
+            add(line)
+    add("结论先行,简明扼要")
+    add("涉及文件时把路径写清楚")
+    add("使用与用户一致的语言(默认中文)")
+    return out
+
+
+def docs_navigation() -> list[tuple[str, list[tuple[str, str]]]]:
+    """读 `docs/docs.json` 的 `navigation`:`[(分组标题, [(手册标题, 路径)])]`。
+
+    读不到(打包漏了 `docs.json`、开发树里没有 docs/、文件坏了)→ 空列表。
+    调用方据此**整块不注入**,不报错也不注入半个块。
+    """
+    from .paths import DOCS_DIR_NAME, DOCS_INDEX_FILE_NAME, docs_dir   # 延迟导入,避免环
+
+    root = docs_dir()
+    if root is None:
+        return []
+    try:
+        data = json.loads((root / DOCS_INDEX_FILE_NAME).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+    out: list[tuple[str, list[tuple[str, str]]]] = []
+
+    def collect(items: object) -> list[tuple[str, str]]:
+        """把（可能嵌套的）分组的条目展平成一串 (标题, 路径)。
+
+        `docs.json` 的分组照 pi 的写法可以有子分组("指南 → 运行 qi / 定制 qi / 构建于 qi"),
+        而提示词里只需要一份平铺的“标题: 文件”清单 —— 递归取到底即可。
+        """
+        flat: list[tuple[str, str]] = []
+        for item in items if isinstance(items, list) else []:
+            if not isinstance(item, dict):
+                continue
+            path = str(item.get("path") or "")
+            if path:
+                flat.append((str(item.get("title") or ""), path))
+            else:
+                flat.extend(collect(item.get("items")))
+        return flat
+
+    for group in data.get("navigation") or []:
+        if not isinstance(group, dict):
+            continue
+        items = [(title, name) for title, name in collect(group.get("items")) if title and name]
+        if items:
+            out.append((str(group.get("title") or DOCS_DIR_NAME), items))
+    return out
+
+
+def render_docs_index(tool_names: Sequence[str]) -> str:
+    """把手册索引渲染成提示词里的一节(pi 的 `Additional docs:` 的 qi 版)。
+
+    两个与 pi 的差别:
+      - pi 把主题→文件写**死在源码里**;qi 从 `docs.json` 的 `navigation` 生成 ——
+        手册增删时不会漂。
+      - 与 `render_skills` 同规矩:没有能读文件的工具(`read` / `bash`)就**整块不注入**
+        (给了路径也读不到)。
+
+    路径给**绝对**的(`docs_dir()` 在 wheel 里与源码树里不一样,不能写死 `docs/`),
+    正文不塞进上下文 —— 模型自己用 read 打开。
+    """
+    if not ({"read", "bash"} & set(tool_names)):
+        return ""
+    from .paths import docs_dir
+
+    root = docs_dir()
+    navigation = docs_navigation()
+    if root is None or not navigation:
+        return ""
+    lines = ["文档(qi 自带的手册;要查用法、或要改 qi 自身,先读对应文件,不要凭记忆猜):",
+             f"- 根目录: {root}"]
+    for title, items in navigation:
+        listed = "、".join(f"{name}" for _name_title, name in items)
+        lines.append(f"- {title}: {listed}")
+    lines.append("读的时候把根目录与文件名拼成绝对路径;文件之间互相引用时按相对链接跟着走。")
+    return "\n".join(lines)
+
+
+def default_base_prompt(tools: Sequence[Tool] = ()) -> str:
+    """默认基座(身份 + 可用工具 + 指南 + 环境 + 做法)。
+
+    只在没有自定义 `SYSTEM.md` 时使用;`tools` 为**本回合解析后**的工具集
+    (`ToolCatalog.resolve` 的结果),清单即模型可调用的全集 —— 所以这里不写
+    pi 那句“你可能还有别的工具”:qi 不会给出清单外的工具。
+    """
+    listed = "\n".join(f"- {t.name}: {t.prompt_line}" for t in tools) or "(无)"
+    guidelines = "\n".join(f"- {g}" for g in build_guidelines([t.name for t in tools], tools))
+    parts = [
+        DEFAULT_IDENTITY,
+        f"可用工具:\n{listed}",
+        f"指南:\n{guidelines}",
+        DEFAULT_ENVIRONMENT,
+        DEFAULT_METHOD,
+    ]
+    # 手册索引只随**默认基座**出现(自定义 `SYSTEM.md` 是“整体替换”,作者自己决定要不要提)
+    if (index := render_docs_index([t.name for t in tools])):
+        parts.append(index)
+    return "\n\n".join(parts)
+
+
+# ── 技能清单(pi 的 <available_skills> 形态,渐进披露)──────────
+
+_SKILL_READ_TOOLS = ("read", "bash")   # 能读 SKILL.md 全文的工具,优先 read
+
+
+def _xml(value: object) -> str:
+    return (str(value).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+            .replace('"', "&quot;").replace("'", "&apos;"))
+
+
+def render_skills(skills: Sequence[Skill], tool_names: Sequence[str]) -> str:
+    """技能清单:只给名字/描述/路径,正文用时再读(渐进披露)。
+
+    与 pi 一致:没有能读文件的工具(`read` / `bash`)就**整块不注入** —— 注入了也读不到,
+    只会诱导模型调用不存在的工具。
+    """
+    if not skills:
+        return ""
+    reader = next((t for t in _SKILL_READ_TOOLS if t in set(tool_names)), None)
+    if reader is None:
+        return ""
+    how = "用 read 读取它的 SKILL.md 全文" if reader == "read" else "用 bash 读取它的 SKILL.md 全文"
+    lines = [
+        f"以下技能为特定任务提供专门的执行说明;任务与其描述匹配时,{how}执行。",
+        "技能文件里出现相对路径时,以 SKILL.md 所在目录(技能目录)为基准解析,"
+        "并在工具命令里使用绝对路径。",
+        "",
+        "<available_skills>",
+    ]
+    for s in skills:
+        lines += [
+            "  <skill>",
+            f"    <name>{_xml(s.name)}</name>",
+            f"    <description>{_xml(s.description)}</description>",
+            f"    <location>{_xml(s.path)}</location>",
+            "  </skill>",
+        ]
+    lines.append("</available_skills>")
+    return "\n".join(lines)
+
+
+# ── 项目上下文(pi 的 <project_context>)──────────────────────
+
+def render_project_context(files: Sequence[tuple[Path, str]]) -> str:
+    """把 AGENTS.md 等**内容**渲染成 `<project_context>`(路径放在属性上)。"""
+    if not files:
+        return ""
+    lines = ["<project_context>", "", "项目专属说明与约定:", ""]
+    for path, content in files:
+        lines.append(f'<project_instructions path="{path}">\n{content.strip()}\n'
+                     "</project_instructions>")
+        lines.append("")
+    lines.append("</project_context>")
+    return "\n".join(lines)
+
+
+# ── 组装 ────────────────────────────────────────────────────
+
+def build_system_prompt(base_prompt: str | None = None, *,
+                        cwd: Path | None = None,
+                        tools: Sequence[Tool] = (),
+                        context_files: Sequence[tuple[Path, str]] | None = None,
+                        skills: Sequence[Skill] = (),
+                        append: str | None = None) -> str:
+    """拼出 core 的 system prompt:**基座 → 项目上下文 → 技能 → 工作目录**。
+
+    参数:
+      - `base_prompt`:自定义基座(`SYSTEM.md` 正文)。空/None → 默认基座;
+        非空 → **整体替换**默认基座(pi 的 customPrompt 语义)。
+      - `tools`:本回合实际可用的工具集,决定「可用工具 / 指南 / 技能能否被读取」。
+      - `cwd`:会话工作目录,写进 prompt 末尾;`context_files=None` 时也用它去找
+        `AGENTS.md`(`context_files=[]` 表示显式不注入)。
+      - `skills`:**顶层**技能(六层来源,见 loader)。
+
+    **没有“角色层”与“数据源”** —— 两者都是 agent 的概念,归 qi-agents(E1.1/E15):
+    角色说明由它通过 `before_agent_start` 拼进来(那个钩子的返回值是链式的),数据源
+    实例也在 agent 目录里。core 只负责“基座 + 项目上下文 + 技能 + cwd”。
+    """
+    tool_names = [t.name for t in tools]
+    base = (base_prompt or "").strip() or default_base_prompt(tools)
+    parts: list[str] = [base]
+
+    if context_files is None:
+        from .loader import load_project_context   # 延迟导入:避免 loader ↔ 本模块静态环
+
+        context_files = load_project_context(cwd)
+    ctx = render_project_context(context_files)
+    if ctx:
+        parts.append(ctx)
+
+    rendered_skills = render_skills(skills, tool_names)
+    if rendered_skills:
+        parts.append(rendered_skills)
+
+    parts.append(f"当前工作目录: {Path(cwd) if cwd else Path.cwd()}")
+    # `--append-system-prompt`:用户显式追加的一段,**放最后**(与 pi 同义:追加到
+    # system prompt 末尾,而不是插进某个中间层)。空/空白不占位。
+    if append and append.strip():
+        parts.append(append.strip())
+    return "\n\n".join(p for p in parts if p and p.strip())

qi_agent/theme.py

@@ -0,0 +1,389 @@
+"""pi 主题移植(TUI 视觉基线)。
+
+`themes/dark.json` / `themes/light.json` 逐字取自 pi
+(`@earendil-works/pi-coding-agent` 的 `dist/modes/interactive/theme/`),
+键名与语义保持一致 —— 这样 qi 的配色和 pi 是同一份数据,日后可直接 diff 上游。
+
+对外只暴露三件事:
+  - `load_palette(name)`:读调色板(vars → colors 解析)
+  - `resolve_theme(setting)`:settings/env 决定 dark|light,`auto` 时探测终端背景
+  - 若干格式化纯函数(footer 用),与 pi `footer.js` 的行为一致
+"""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+import json
+import os
+import re
+import select
+import sys
+import termios
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+THEMES_DIR = Path(__file__).resolve().parent / "themes"
+
+THEME_CHOICES = ("dark", "light")
+"""内置主题名(与 pi 的两个 JSON 一一对应)。"""
+
+AUTO_THEME = "auto"
+"""跟随终端背景(对齐 pi 的默认行为)。"""
+
+
+class ThemeError(Exception):
+    """主题名未知 / 调色板损坏。"""
+
+
+@dataclass(frozen=True)
+class Palette:
+    """一份 pi 调色板(semantic key → #rrggbb)。
+
+    `terminal_bg` 是探测到的终端背景色:Textual 的 inline 区域必须有不透明底色,
+    把它设成终端背景色才能在视觉上“不填色”(pi 本身不画底色)。
+    """
+
+    name: str
+    colors: dict[str, str]
+    page_bg: str = "#18181e"
+    terminal_bg: str | None = None
+
+    @property
+    def is_dark(self) -> bool:
+        return self.name != "light"
+
+    def hex(self, key: str) -> str:
+        """取语义色;未知名直接报错(拼错颜色名时不要静默变白)。"""
+        try:
+            return self.colors[key]
+        except KeyError as exc:  # pragma: no cover - 只在配置/代码写错时触发
+            raise ThemeError(f"未知主题色: {key}") from exc
+
+    def fg(self, key: str, text: str) -> str:
+        """Rich markup 前景色片段(hex 直写,无需注册)。"""
+        return f"[{self.hex(key)}]{text}[/]"
+
+    def bg_markup(self, key: str, text: str) -> str:
+        return f"[on {self.hex(key)}]{text}[/]"
+
+    def style(self, key: str, *, bold: bool = False, italic: bool = False,
+              dim: bool = False, bg: bool = False) -> str:
+        """Rich style 字符串:`#rrggbb`(+on #rrggbb),可选 bold/italic/dim。"""
+        color = f"on {self.hex(key)}" if bg else self.hex(key)
+        parts = [color]
+        if bold:
+            parts.append("bold")
+        if italic:
+            parts.append("italic")
+        if dim:
+            parts.append("dim")
+        return " ".join(parts)
+
+
+def load_palette(name: str) -> Palette:
+    """读内置调色板;`colors` 里的 var 名按 pi 规则解析成 hex。"""
+    if name not in THEME_CHOICES:
+        raise ThemeError(f"未知主题 {name!r};内置:{', '.join(THEME_CHOICES)}")
+    path = THEMES_DIR / f"{name}.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:  # pragma: no cover
+        raise ThemeError(f"主题文件不可用: {path}") from exc
+    variables: dict[str, str] = data.get("vars") or {}
+    raw: dict[str, str] = data.get("colors") or {}
+    # 统一小写:pi 的 JSON 里大小写混用(#2D2838 / #343541)。归一后才可预期 ——
+    # 注意 Textual 的 `Color.hex` 会**原样保留**传入字符串的大小写,所以别指望它帮你归一。
+    colors = {
+        key: (value if value.startswith("#") else variables.get(value, value)).lower()
+        for key, value in raw.items()
+    }
+    page_bg = ((data.get("export") or {}).get("pageBg") or "#18181e").lower()
+    return Palette(name=name, colors=colors, page_bg=page_bg)
+
+
+# ── 终端背景探测(OSC 11)────────────────────────────────
+
+
+def _luminance(r: int, g: int, b: int) -> float:
+    return (0.299 * r + 0.587 * g + 0.114 * b) / 255
+
+
+def parse_background_color(reply: str) -> str | None:
+    """从 OSC 11 回复里取出背景色 `#rrggbb`(支持 8/16 位分量与 #RRGGBB)。"""
+    match = re.search(r"rgb:([0-9a-fA-F]+)/([0-9a-fA-F]+)/([0-9a-fA-F]+)", reply)
+    if match:
+        channels = []
+        for part in match.groups():
+            value = int(part, 16)
+            channels.append(value >> 8 if len(part) >= 3 else value)
+        return "#{:02x}{:02x}{:02x}".format(*[min(255, c) for c in channels])
+    match = re.search(r"#([0-9a-fA-F]{6})", reply)
+    if match:
+        return "#" + match.group(1).lower()
+    return None
+
+
+def parse_osc11(reply: str) -> str | None:
+    """把终端的 OSC 11 回复解析成 dark|light(解析不出返回 None)。"""
+    color = parse_background_color(reply)
+    if color is None:
+        return None
+    rgb = tuple(int(color[i:i + 2], 16) for i in (1, 3, 5))
+    return "light" if _luminance(*rgb) > 0.5 else "dark"
+
+
+def _query_osc11(timeout: float) -> str | None:
+    """向终端发 OSC 11 查询并读回复(必须在 Textual 接管 stdin 之前调用)。"""
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        return None
+    fd = sys.stdin.fileno()
+    try:
+        saved = termios.tcgetattr(fd)
+    except (termios.error, ValueError, OSError):
+        return None
+    raw = copy.deepcopy(saved)
+    raw[3] &= ~(termios.ICANON | termios.ECHO)
+    raw[6][termios.VMIN] = 0
+    raw[6][termios.VTIME] = 0
+    try:
+        termios.tcsetattr(fd, termios.TCSANOW, raw)
+        os.write(sys.stdout.fileno(), b"\x1b]11;?\x07")
+        sys.stdout.flush()
+        deadline = time.monotonic() + timeout
+        buf = ""
+        while time.monotonic() < deadline:
+            ready, _, _ = select.select([fd], [], [], max(0.0, deadline - time.monotonic()))
+            if not ready:
+                break
+            chunk = os.read(fd, 64)
+            if not chunk:
+                break
+            buf += chunk.decode("utf-8", "replace")
+            if "\x07" in buf or "\x1b\\" in buf:
+                break
+        return buf or None
+    except OSError:
+        return None
+    finally:
+        termios.tcsetattr(fd, termios.TCSANOW, saved)
+
+
+def detect_terminal_background(timeout: float = 0.15) -> str | None:
+    """终端背景色 `#rrggbb`;不支持 OSC 11 / 超时返回 None。"""
+    reply = _query_osc11(timeout)
+    return parse_background_color(reply) if reply else None
+
+
+def detect_terminal_theme(timeout: float = 0.15) -> str | None:
+    """终端背景明暗(dark|light);探测失败返回 None。"""
+    bg = detect_terminal_background(timeout)
+    if bg is None:
+        return None
+    rgb = tuple(int(bg[i:i + 2], 16) for i in (1, 3, 5))
+    return "light" if _luminance(*rgb) > 0.5 else "dark"
+
+
+def theme_from_env() -> str | None:
+    """`QI_THEME` 显式覆盖(取值 dark|light|auto)。"""
+    value = (os.environ.get("QI_THEME") or "").strip().lower()
+    return value or None
+
+
+def resolve_theme(setting: str | None = None, *, probe: bool = True) -> Palette:
+    """决定用哪份调色板。
+
+    优先级:`QI_THEME` > `settings.theme` > 探测终端背景 > dark。
+    `auto`(或未设)走探测;探测不出来对齐 pi 落 dark。探测到的背景色
+    一并带在 `Palette.terminal_bg` 上(Textual inline 区域用色)。
+    """
+    choice = (theme_from_env() or setting or AUTO_THEME).strip().lower()
+    background = detect_terminal_background() if probe else None
+    detected = parse_osc11(background or "")
+    if choice in THEME_CHOICES:
+        palette = load_palette(choice)
+    elif choice in (AUTO_THEME, "", "default", "none"):
+        palette = load_palette(detected or "dark")
+    else:
+        # 未知名字:不静默,交给调用方决定怎么提示;这里退回 dark 更稳妥
+        palette = load_palette("dark")
+    return dataclasses.replace(palette, terminal_bg=background)
+
+
+# ── footer 格式化(逐条对齐 pi footer.js)──────────────
+
+
+def format_tokens(count: int) -> str:
+    """紧凑 token 数:`1234` → `1.2k`(与 pi `formatTokens` 一致)。"""
+    if count < 1000:
+        return str(count)
+    if count < 10_000:
+        return f"{count / 1000:.1f}k"
+    if count < 1_000_000:
+        return f"{round(count / 1000)}k"
+    if count < 10_000_000:
+        return f"{count / 1_000_000:.1f}M"
+    return f"{round(count / 1_000_000)}M"
+
+
+def shorten_home(path: str, home: str | None = None) -> str:
+    """把家目录缩成 `~`(pi `formatCwdForFooter` 的最小版本)。"""
+    home = home if home is not None else str(Path.home())
+    if home and (path == home or path.startswith(home + os.sep)):
+        return "~" + path[len(home):]
+    return path
+
+
+def format_cwd_line(cwd: str, *, home: str | None = None, branch: str | None = None,
+                    session_name: str | None = None) -> str:
+    """footer 第一行:`~/repo (main) • 会话名`。"""
+    text = shorten_home(cwd, home)
+    if branch:
+        text = f"{text} ({branch})"
+    if session_name:
+        text = f"{text} • {session_name}"
+    return text
+
+
+# ── Rich 渲染桥接(markdown / 代码高亮)──────────────
+
+
+def rich_theme(palette: Palette):
+    """Rich 的主题名 → pi 语义色。
+
+    Rich 的 markdown 渲染走 `console.get_style("markdown.h1")` 这类名字,
+    所以把这套名字映射到 pi 的 md* 键,词法高亮之外的 markdown 视觉才一致。
+    """
+    from rich.style import Style
+    from rich.theme import Theme as RichTheme
+
+    c = palette.colors
+    heading = Style(color=c["mdHeading"], bold=True)
+    return RichTheme(
+        {
+            "markdown.h1": heading,
+            "markdown.h2": heading,
+            "markdown.h3": heading,
+            "markdown.h4": heading,
+            "markdown.h5": heading,
+            "markdown.h6": heading,
+            "markdown.paragraph": Style(color=c["text"]),
+            "markdown.item": Style(color=c["text"]),
+            "markdown.item.bullet": Style(color=c["mdListBullet"]),
+            "markdown.item.number": Style(color=c["mdListBullet"]),
+            "markdown.hr": Style(color=c["mdHr"]),
+            "markdown.link": Style(color=c["mdLink"]),
+            "markdown.link_url": Style(color=c["mdLinkUrl"]),
+            "markdown.block_quote": Style(color=c["mdQuote"]),
+            "markdown.code": Style(color=c["mdCode"]),
+            "markdown.code_block": Style(color=c["mdCodeBlock"]),
+            "markdown.kbd": Style(bold=True),
+        },
+        inherit=True,
+    )
+
+
+def syntax_theme(palette: Palette):
+    """pi `syntax*` 键 → pygments token 的 Rich 代码高亮主题。
+
+    pi 用 highlight.js,qi 用 pygments;这里按**语义**对齐(注释/关键字/函数/
+    字符串/数字/类型/运算符…),颜色取同一份调色板,所以两种实现看起来是一套。
+    背景保持终端默认(pi 的代码块没有底色)。
+    """
+    from pygments.style import Style as PygStyle
+    from pygments.token import (
+        Comment,
+        Generic,
+        Keyword,
+        Name,
+        Number,
+        Operator,
+        Punctuation,
+        String,
+        Text as PygText,
+        Token,
+    )
+    from rich.syntax import PygmentsSyntaxTheme
+
+    c = palette.colors
+
+    class QiPygmentsStyle(PygStyle):
+        # None = 不画底色(pi 的代码块没有背景,只有 mdCodeBlock 前景色)。
+        # pygments 上游把它注解成 str,这里用 Any 声明才能写 None。
+        background_color: Any = None
+        styles = {
+            Token: c["text"],
+            PygText: c["text"],
+            Comment: c["syntaxComment"],
+            Keyword: c["syntaxKeyword"],
+            Name: c["text"],
+            Name.Function: c["syntaxFunction"],
+            Name.Builtin: c["syntaxType"],
+            Name.Class: c["syntaxType"],
+            Name.Variable: c["syntaxVariable"],
+            Name.Attribute: c["syntaxVariable"],
+            String: c["syntaxString"],
+            Number: c["syntaxNumber"],
+            Operator: c["syntaxOperator"],
+            Punctuation: c["syntaxPunctuation"],
+            Generic.Deleted: c["toolDiffRemoved"],
+            Generic.Inserted: c["toolDiffAdded"],
+        }
+
+    return PygmentsSyntaxTheme(QiPygmentsStyle)
+
+
+def textual_theme(palette: Palette):
+    """pi 调色板 → Textual 主题。
+
+    background 取探测到的终端背景色:Textual inline 区域总会有一个不透明底色,
+    只有与终端一致才看不出“被填色”。另外把 markdown 的 md* 色挂成 CSS 变量,
+    供 App.CSS 里覆盖 MarkdownFence / MarkdownH1 等组件默认样式。
+    """
+    from textual.theme import Theme as TuiTheme
+
+    c = palette.colors
+    return TuiTheme(
+        name=f"qi-{palette.name}",
+        dark=palette.is_dark,
+        primary=c["accent"],
+        secondary=c["border"],
+        accent=c["borderAccent"],
+        foreground=c["text"],
+        background=palette.terminal_bg or palette.page_bg,
+        success=c["success"],
+        warning=c["warning"],
+        error=c["error"],
+        surface=c["userMessageBg"],
+        panel=c["toolPendingBg"],
+        variables={
+            "md-code": c["mdCode"],
+            "md-code-block": c["mdCodeBlock"],
+            "md-code-block-border": c["mdCodeBlockBorder"],
+            "md-quote": c["mdQuote"],
+            "md-hr": c["mdHr"],
+            "md-list-bullet": c["mdListBullet"],
+            "md-link": c["mdLink"],
+            "md-link-url": c["mdLinkUrl"],
+            "md-heading": c["mdHeading"],
+        },
+    )
+
+
+def git_branch(cwd: str | os.PathLike[str]) -> str | None:
+    """当前 git 分支;非仓库/无 git 时 None(不打印错误)。"""
+    import subprocess
+
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=str(cwd), capture_output=True, text=True, timeout=1.0,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0:
+        return None
+    branch = out.stdout.strip()
+    return branch if branch and branch != "HEAD" else None