diff --git a/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md b/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md index 3e851d54..5d2280fc 100644 --- a/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md +++ b/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md @@ -65,6 +65,7 @@ Process: - Treat `docs/next/README.md` as the next-release root README, and `docs/next/website/src/content/docs/` as the full next-release mirror of website docs. - Compare meaningful user-facing changes in the range against next-release docs first. - Flag missing release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes. + - Compare English next-release website docs against `docs/next/website/src/content/docs/ja/` and `docs/next/website/src/content/docs/zh-cn/`. Flag missing localized files, stale localized files, and heading-outline drift where translated docs do not have the same section structure as English. - Compare `docs/next/README.md` against root `README.md`, and compare the staged website-doc mirror against `website/src/content/docs/`. Flag each difference as intended to ship in this release, stale, or needing user decision. - Also audit example config snippets for release readiness. @@ -75,7 +76,7 @@ Process: ```bash just release-docs-check ``` - - This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, and exact 1:1 sync between `docs/next/website/src/content/docs/` and `website/src/content/docs/`. + - This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, exact 1:1 sync between `docs/next/website/src/content/docs/` and `website/src/content/docs/`, and localized heading-outline parity between English, Japanese, and Simplified Chinese docs. - Do not run `just release` unless the working tree is clean and the docs check passes. 9. Apply changes only when asked. diff --git a/docs/next/website/src/content/docs/ja/cli-reference.mdx b/docs/next/website/src/content/docs/ja/cli-reference.mdx index f3a8d015..ea15d44d 100644 --- a/docs/next/website/src/content/docs/ja/cli-reference.mdx +++ b/docs/next/website/src/content/docs/ja/cli-reference.mdx @@ -19,6 +19,7 @@ herdr --no-session # シングルプロセスの逃げ道 herdr --default-config # デフォルト設定を表示 herdr update # 設定済みチャンネルからダウンロードしてインストール herdr update --handoff # 対応する実行中サーバーでライブハンドオフにオプトイン +herdr completion zsh # zsh 補完スクリプトを生成 herdr channel show # stable または preview を表示 herdr channel set preview # プレビュービルドにオプトイン herdr channel set stable # Linux/macOS の直接インストールを安定版に戻す @@ -33,6 +34,48 @@ herdr status server herdr status client ``` +API スキーマコマンド: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +`herdr api schema` は、インストール済みバイナリに同梱されたソケットプロトコルスキーマの短い概要を表示します。完全な JSON Schema ドキュメントが欲しいときは `--json` を使い、ファイルに書き出すには `--output PATH` を使ってください。 + +## シェル補完 + +```bash +herdr completion zsh +herdr completions zsh +herdr completion bash +herdr completion fish +herdr completion powershell +herdr completion elvish +``` + +`completion` はスクリプトを標準出力に表示します。`completions` はエイリアスです。一時的な zsh セッションでは、スクリプトを直接読み込めます: + +```bash +source <(herdr completion zsh) +``` + +永続的な zsh 設定では、生成された `_herdr` 関数を `compinit` が実行される前の `fpath` 上に置いてください: + +```bash +mkdir -p ~/.zfunc +herdr completion zsh > ~/.zfunc/_herdr +``` + +その後、`.zshrc` に次の内容があることを確認してください: + +```zsh +fpath=(~/.zfunc $fpath) +autoload -Uz compinit +compinit +``` + ## サーバー ```bash diff --git a/docs/next/website/src/content/docs/ja/socket-api.mdx b/docs/next/website/src/content/docs/ja/socket-api.mdx index dca7136d..a5ebc5f5 100644 --- a/docs/next/website/src/content/docs/ja/socket-api.mdx +++ b/docs/next/website/src/content/docs/ja/socket-api.mdx @@ -17,6 +17,18 @@ Herdr は、実行中のセッションを調査・制御する必要がある これらの層は同じ制御面を共有します。 +## スキーマ + +インストール済み CLI は、その Herdr バイナリに同梱されたソケットプロトコルスキーマを表示できます: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +通常の `herdr api schema` は短い概要を表示します。`--json` はツール向けの完全な JSON Schema を表示し、`--output PATH` はそのドキュメントをファイルに書き込みます。スキーマには、生のリクエスト、成功レスポンス、エラーレスポンス、発行イベント、購読イベントが含まれます。 + ## 制御できるもの ソケット API では次のことができます: diff --git a/docs/next/website/src/content/docs/ja/windows-beta.mdx b/docs/next/website/src/content/docs/ja/windows-beta.mdx index 9d282a70..f6b45500 100644 --- a/docs/next/website/src/content/docs/ja/windows-beta.mdx +++ b/docs/next/website/src/content/docs/ja/windows-beta.mdx @@ -57,6 +57,23 @@ Windows Terminal は特定のエージェント向けに画像貼り付け経路 Kitty graphics は実験的なままで、まだ Windows でのサポートを謳っていません。Windows Terminal での画像レンダリングを特にテストしているのでない限り、`experimental.kitty_graphics = false` のままにしてください。 +## 既知の注意点 + +### カーソル描画 + +Windows のターミナルは ConPTY 経由で Herdr を実行するため、フルスクリーン再描画中にネイティブの端末カーソルがちらついたり、ジャンプしたり、古い位置を一瞬表示したりすることがあります。Herdr のデフォルト `host_cursor = "auto"` は、Windows では Herdr のカーソルを端末セルの内容として描画し、Linux と macOS ではネイティブの端末カーソルを使い続けます。Windows でのトレードオフは、外側ターミナルのネイティブな点滅、形状、カーソル色の代わりに、Herdr 内で安定した非点滅カーソルを表示することです。 + +Windows で外側ターミナルのカーソルに戻すには、次を設定してください: + +```toml +[ui] +host_cursor = "native" +``` + +### キーボードとマウス + +Windows のターミナルは、修飾キー付きのキーをすべて同じ形で報告するわけではありません。Herdr は Windows Terminal と Windows 上の Alacritty ではマウス報告と `ctrl+j` を保持しますが、`shift+enter` は外側ターミナルが修飾付き Enter として区別して報告する場合にだけ動作します。Windows またはターミナルがそれを通常の Enter として報告する場合、Herdr は通常の Enter を転送します。 + ## コピーと貼り付け Herdr のペインテキストコピーは Windows ベータで動作します。ペイン内でテキストをドラッグ選択すると Herdr 経由でコピーされます。 diff --git a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx index 91a7b205..c32b14bc 100644 --- a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx +++ b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx @@ -19,6 +19,7 @@ herdr --no-session # 单进程逃生舱 herdr --default-config # 打印默认配置 herdr update # 从配置的通道下载并安装 herdr update --handoff # 对受支持的运行中服务器启用实时交接 +herdr completion zsh # 生成 zsh 补全脚本 herdr channel show # 打印 stable 或 preview herdr channel set preview # 启用预览构建 herdr channel set stable # 把 Linux/macOS 直接安装切回稳定版 @@ -33,6 +34,48 @@ herdr status server herdr status client ``` +API schema 命令: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +`herdr api schema` 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 `--json`;要写入文件则使用 `--output PATH`。 + +## Shell 补全 + +```bash +herdr completion zsh +herdr completions zsh +herdr completion bash +herdr completion fish +herdr completion powershell +herdr completion elvish +``` + +`completion` 会把脚本打印到 stdout。`completions` 是别名。临时 zsh 会话可以直接加载脚本: + +```bash +source <(herdr completion zsh) +``` + +持久 zsh 设置中,把生成的 `_herdr` 函数写到 `compinit` 运行前已经在 `fpath` 上的位置: + +```bash +mkdir -p ~/.zfunc +herdr completion zsh > ~/.zfunc/_herdr +``` + +然后确认 `.zshrc` 包含: + +```zsh +fpath=(~/.zfunc $fpath) +autoload -Uz compinit +compinit +``` + ## 服务器 ```bash diff --git a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx index 3a5320b8..7454ecc7 100644 --- a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx +++ b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx @@ -17,6 +17,18 @@ Herdr 为需要检查或控制运行中会话的脚本和智能体提供了一 这些层共享同一套控制面。 +## Schema + +安装的 CLI 可以打印该 Herdr 二进制中包含的 socket 协议 schema: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +普通的 `herdr api schema` 打印简短摘要。`--json` 打印供工具使用的完整 JSON Schema,`--output PATH` 将该文档写入文件。schema 覆盖原始请求、成功响应、错误响应、发出的事件和订阅事件。 + ## 你能控制什么 socket API 可以: diff --git a/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx b/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx index e092451a..971835ca 100644 --- a/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx +++ b/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx @@ -57,6 +57,23 @@ Windows Terminal 可能为特定智能体支持图像粘贴路径,但 Herdr 自 Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专门在 Windows Terminal 中测试图像渲染,否则保持 `experimental.kitty_graphics = false`。 +## 已知注意事项 + +### 光标渲染 + +Windows 终端通过 ConPTY 运行 Herdr,在活跃的全屏重绘期间,原生终端光标可能闪烁、跳动,或短暂显示旧位置。Herdr 默认的 `host_cursor = "auto"` 会在 Windows 上把 Herdr 光标绘制为终端单元格内容,而 Linux 和 macOS 继续使用原生终端光标。Windows 上的取舍是:在 Herdr 内得到稳定的不闪烁光标,但不使用外层终端的原生闪烁、形状和光标颜色。 + +要在 Windows 上改回外层终端光标,请设置: + +```toml +[ui] +host_cursor = "native" +``` + +### 键盘和鼠标 + +Windows 终端并不都以相同形式报告带修饰键的按键。Herdr 在 Windows Terminal 和 Windows 上的 Alacritty 中保留鼠标报告和 `ctrl+j`,但 `shift+enter` 只有在外层终端把它报告为独立的修饰 Enter 键时才有效。如果 Windows 或终端把它报告为普通 Enter,Herdr 会转发普通 Enter。 + ## 复制与粘贴 Herdr 的窗格文本复制在 Windows 测试版上可用。在窗格内拖选文本即可通过 Herdr 复制。 diff --git a/justfile b/justfile index 97c02d0e..d35e3d5d 100644 --- a/justfile +++ b/justfile @@ -3,7 +3,7 @@ # Run tests test: cargo nextest run --locked --status-level fail --final-status-level fail --failure-output final --success-output never - python3 -m unittest scripts.test_agent_detection_manifest_check scripts.test_changelog scripts.test_preview scripts.test_vendor_libghostty_vt scripts.test_vendor_portable_pty + python3 -m unittest scripts.test_agent_detection_manifest_check scripts.test_changelog scripts.test_docs_translation_parity scripts.test_preview scripts.test_vendor_libghostty_vt scripts.test_vendor_portable_pty just integration-assets-test just plugin-marketplace-test @@ -29,7 +29,7 @@ windows-lint: # Check formatting + run unit tests + Windows target lint + maintenance script tests check: ci windows-lint - python3 -m unittest scripts.test_agent_detection_manifest_check scripts.test_changelog scripts.test_preview scripts.test_vendor_libghostty_vt scripts.test_vendor_portable_pty + python3 -m unittest scripts.test_agent_detection_manifest_check scripts.test_changelog scripts.test_docs_translation_parity scripts.test_preview scripts.test_vendor_libghostty_vt scripts.test_vendor_portable_pty @echo "docs reminder: if this changes user-facing behavior, make sure the relevant release docs are updated or called out before release." # Install repo-local git hooks @@ -109,6 +109,7 @@ release-docs-check: exit 1; \ fi; \ done + python3 scripts/docs_translation_parity.py --docs-root website/src/content/docs # Prepare the release commit without tagging or pushing (usage: just release-prepare 0.1.1) release-prepare version: diff --git a/scripts/docs_translation_parity.py b/scripts/docs_translation_parity.py new file mode 100644 index 00000000..6b15441b --- /dev/null +++ b/scripts/docs_translation_parity.py @@ -0,0 +1,145 @@ +from __future__ import annotations + +import argparse +import sys +from pathlib import Path + + +DEFAULT_LOCALES = ("ja", "zh-cn") + + +def heading_outline(path: Path) -> list[int]: + outline: list[int] = [] + in_fence = False + + for line in path.read_text(encoding="utf-8").splitlines(): + stripped = line.lstrip() + if stripped.startswith("```") or stripped.startswith("~~~"): + in_fence = not in_fence + continue + if in_fence or not stripped.startswith("#"): + continue + + level = 0 + for char in stripped: + if char != "#": + break + level += 1 + + if level == 0 or level > 6: + continue + if len(stripped) > level and stripped[level] not in (" ", "\t"): + continue + + outline.append(level) + + return outline + + +def english_docs(docs_root: Path) -> list[Path]: + return sorted( + path + for path in docs_root.glob("*.mdx") + if path.is_file() + ) + + +def locale_docs(docs_root: Path, locale: str) -> list[Path]: + locale_root = docs_root / locale + if not locale_root.exists(): + return [] + return sorted(path for path in locale_root.glob("*.mdx") if path.is_file()) + + +def check_docs_translation_parity(docs_root: Path, locales: tuple[str, ...] = DEFAULT_LOCALES) -> list[str]: + errors: list[str] = [] + english = english_docs(docs_root) + english_names = {path.name for path in english} + + for locale in locales: + translated_names = {path.name for path in locale_docs(docs_root, locale)} + + for missing in sorted(english_names - translated_names): + errors.append(f"{docs_root / locale / missing}: missing translation file") + + for stale in sorted(translated_names - english_names): + errors.append(f"{docs_root / locale / stale}: no matching English doc") + + for source in english: + source_outline = heading_outline(source) + + for locale in locales: + translated = docs_root / locale / source.name + if not translated.exists(): + continue + + translated_outline = heading_outline(translated) + if translated_outline == source_outline: + continue + + errors.append( + format_outline_error(source, translated, source_outline, translated_outline) + ) + + return errors + + +def format_outline_error( + source: Path, + translated: Path, + source_outline: list[int], + translated_outline: list[int], +) -> str: + return ( + f"{translated}: heading outline differs from {source} " + f"(English {format_counts(source_outline)}, translated {format_counts(translated_outline)})" + ) + + +def format_counts(levels: list[int]) -> str: + if not levels: + return "0 headings" + + parts = [] + for level in range(1, 7): + count = levels.count(level) + if count: + parts.append(f"h{level}={count}") + return ", ".join(parts) + + +def parse_args(argv: list[str]) -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Check localized docs have the same heading outline as English docs." + ) + parser.add_argument( + "--docs-root", + default="website/src/content/docs", + type=Path, + help="Docs content root containing English .mdx files and locale subdirectories.", + ) + parser.add_argument( + "--locale", + action="append", + dest="locales", + help="Locale subdirectory to check. Can be passed more than once.", + ) + return parser.parse_args(argv) + + +def main(argv: list[str] | None = None) -> int: + args = parse_args(sys.argv[1:] if argv is None else argv) + locales = tuple(args.locales or DEFAULT_LOCALES) + errors = check_docs_translation_parity(args.docs_root, locales) + + if errors: + print("error: localized docs heading outlines differ from English docs", file=sys.stderr) + for error in errors: + print(f"- {error}", file=sys.stderr) + return 1 + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/test_docs_translation_parity.py b/scripts/test_docs_translation_parity.py new file mode 100644 index 00000000..9a8aa378 --- /dev/null +++ b/scripts/test_docs_translation_parity.py @@ -0,0 +1,78 @@ +from __future__ import annotations + +import tempfile +import unittest +from pathlib import Path + +from scripts.docs_translation_parity import check_docs_translation_parity, heading_outline + + +class DocsTranslationParityTests(unittest.TestCase): + def test_heading_outline_ignores_fenced_code_blocks(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + path = Path(tmp) / "doc.mdx" + path.write_text( + "# Title\n\n```md\n## Not a heading\n```\n\n## Real section\n", + encoding="utf-8", + ) + + self.assertEqual(heading_outline(path), [1, 2]) + + def test_parity_accepts_translated_heading_text_with_same_shape(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "ja").mkdir() + (root / "zh-cn").mkdir() + (root / "guide.mdx").write_text("# Guide\n\n## Install\n\n### Verify\n", encoding="utf-8") + (root / "ja" / "guide.mdx").write_text( + "# ガイド\n\n## インストール\n\n### 確認\n", + encoding="utf-8", + ) + (root / "zh-cn" / "guide.mdx").write_text( + "# 指南\n\n## 安装\n\n### 验证\n", + encoding="utf-8", + ) + + self.assertEqual(check_docs_translation_parity(root), []) + + def test_parity_reports_missing_heading_sections(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "ja").mkdir() + (root / "zh-cn").mkdir() + (root / "cli-reference.mdx").write_text( + "# CLI reference\n\n## Launch\n\n## Shell completions\n", + encoding="utf-8", + ) + (root / "ja" / "cli-reference.mdx").write_text( + "# CLI リファレンス\n\n## 起動\n", + encoding="utf-8", + ) + (root / "zh-cn" / "cli-reference.mdx").write_text( + "# CLI 参考\n\n## 启动\n\n## Shell 补全\n", + encoding="utf-8", + ) + + errors = check_docs_translation_parity(root) + + self.assertEqual(len(errors), 1) + self.assertIn("ja/cli-reference.mdx", errors[0]) + self.assertIn("heading outline differs", errors[0]) + + def test_parity_reports_missing_and_stale_files(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "ja").mkdir() + (root / "zh-cn").mkdir() + (root / "guide.mdx").write_text("# Guide\n", encoding="utf-8") + (root / "ja" / "old.mdx").write_text("# Old\n", encoding="utf-8") + (root / "zh-cn" / "guide.mdx").write_text("# 指南\n", encoding="utf-8") + + errors = check_docs_translation_parity(root) + + self.assertIn(f"{root / 'ja' / 'guide.mdx'}: missing translation file", errors) + self.assertIn(f"{root / 'ja' / 'old.mdx'}: no matching English doc", errors) + + +if __name__ == "__main__": + unittest.main() diff --git a/website/src/content/docs/ja/cli-reference.mdx b/website/src/content/docs/ja/cli-reference.mdx index f3a8d015..ea15d44d 100644 --- a/website/src/content/docs/ja/cli-reference.mdx +++ b/website/src/content/docs/ja/cli-reference.mdx @@ -19,6 +19,7 @@ herdr --no-session # シングルプロセスの逃げ道 herdr --default-config # デフォルト設定を表示 herdr update # 設定済みチャンネルからダウンロードしてインストール herdr update --handoff # 対応する実行中サーバーでライブハンドオフにオプトイン +herdr completion zsh # zsh 補完スクリプトを生成 herdr channel show # stable または preview を表示 herdr channel set preview # プレビュービルドにオプトイン herdr channel set stable # Linux/macOS の直接インストールを安定版に戻す @@ -33,6 +34,48 @@ herdr status server herdr status client ``` +API スキーマコマンド: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +`herdr api schema` は、インストール済みバイナリに同梱されたソケットプロトコルスキーマの短い概要を表示します。完全な JSON Schema ドキュメントが欲しいときは `--json` を使い、ファイルに書き出すには `--output PATH` を使ってください。 + +## シェル補完 + +```bash +herdr completion zsh +herdr completions zsh +herdr completion bash +herdr completion fish +herdr completion powershell +herdr completion elvish +``` + +`completion` はスクリプトを標準出力に表示します。`completions` はエイリアスです。一時的な zsh セッションでは、スクリプトを直接読み込めます: + +```bash +source <(herdr completion zsh) +``` + +永続的な zsh 設定では、生成された `_herdr` 関数を `compinit` が実行される前の `fpath` 上に置いてください: + +```bash +mkdir -p ~/.zfunc +herdr completion zsh > ~/.zfunc/_herdr +``` + +その後、`.zshrc` に次の内容があることを確認してください: + +```zsh +fpath=(~/.zfunc $fpath) +autoload -Uz compinit +compinit +``` + ## サーバー ```bash diff --git a/website/src/content/docs/ja/socket-api.mdx b/website/src/content/docs/ja/socket-api.mdx index dca7136d..a5ebc5f5 100644 --- a/website/src/content/docs/ja/socket-api.mdx +++ b/website/src/content/docs/ja/socket-api.mdx @@ -17,6 +17,18 @@ Herdr は、実行中のセッションを調査・制御する必要がある これらの層は同じ制御面を共有します。 +## スキーマ + +インストール済み CLI は、その Herdr バイナリに同梱されたソケットプロトコルスキーマを表示できます: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +通常の `herdr api schema` は短い概要を表示します。`--json` はツール向けの完全な JSON Schema を表示し、`--output PATH` はそのドキュメントをファイルに書き込みます。スキーマには、生のリクエスト、成功レスポンス、エラーレスポンス、発行イベント、購読イベントが含まれます。 + ## 制御できるもの ソケット API では次のことができます: diff --git a/website/src/content/docs/ja/windows-beta.mdx b/website/src/content/docs/ja/windows-beta.mdx index 9d282a70..f6b45500 100644 --- a/website/src/content/docs/ja/windows-beta.mdx +++ b/website/src/content/docs/ja/windows-beta.mdx @@ -57,6 +57,23 @@ Windows Terminal は特定のエージェント向けに画像貼り付け経路 Kitty graphics は実験的なままで、まだ Windows でのサポートを謳っていません。Windows Terminal での画像レンダリングを特にテストしているのでない限り、`experimental.kitty_graphics = false` のままにしてください。 +## 既知の注意点 + +### カーソル描画 + +Windows のターミナルは ConPTY 経由で Herdr を実行するため、フルスクリーン再描画中にネイティブの端末カーソルがちらついたり、ジャンプしたり、古い位置を一瞬表示したりすることがあります。Herdr のデフォルト `host_cursor = "auto"` は、Windows では Herdr のカーソルを端末セルの内容として描画し、Linux と macOS ではネイティブの端末カーソルを使い続けます。Windows でのトレードオフは、外側ターミナルのネイティブな点滅、形状、カーソル色の代わりに、Herdr 内で安定した非点滅カーソルを表示することです。 + +Windows で外側ターミナルのカーソルに戻すには、次を設定してください: + +```toml +[ui] +host_cursor = "native" +``` + +### キーボードとマウス + +Windows のターミナルは、修飾キー付きのキーをすべて同じ形で報告するわけではありません。Herdr は Windows Terminal と Windows 上の Alacritty ではマウス報告と `ctrl+j` を保持しますが、`shift+enter` は外側ターミナルが修飾付き Enter として区別して報告する場合にだけ動作します。Windows またはターミナルがそれを通常の Enter として報告する場合、Herdr は通常の Enter を転送します。 + ## コピーと貼り付け Herdr のペインテキストコピーは Windows ベータで動作します。ペイン内でテキストをドラッグ選択すると Herdr 経由でコピーされます。 diff --git a/website/src/content/docs/zh-cn/cli-reference.mdx b/website/src/content/docs/zh-cn/cli-reference.mdx index 91a7b205..c32b14bc 100644 --- a/website/src/content/docs/zh-cn/cli-reference.mdx +++ b/website/src/content/docs/zh-cn/cli-reference.mdx @@ -19,6 +19,7 @@ herdr --no-session # 单进程逃生舱 herdr --default-config # 打印默认配置 herdr update # 从配置的通道下载并安装 herdr update --handoff # 对受支持的运行中服务器启用实时交接 +herdr completion zsh # 生成 zsh 补全脚本 herdr channel show # 打印 stable 或 preview herdr channel set preview # 启用预览构建 herdr channel set stable # 把 Linux/macOS 直接安装切回稳定版 @@ -33,6 +34,48 @@ herdr status server herdr status client ``` +API schema 命令: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +`herdr api schema` 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 `--json`;要写入文件则使用 `--output PATH`。 + +## Shell 补全 + +```bash +herdr completion zsh +herdr completions zsh +herdr completion bash +herdr completion fish +herdr completion powershell +herdr completion elvish +``` + +`completion` 会把脚本打印到 stdout。`completions` 是别名。临时 zsh 会话可以直接加载脚本: + +```bash +source <(herdr completion zsh) +``` + +持久 zsh 设置中,把生成的 `_herdr` 函数写到 `compinit` 运行前已经在 `fpath` 上的位置: + +```bash +mkdir -p ~/.zfunc +herdr completion zsh > ~/.zfunc/_herdr +``` + +然后确认 `.zshrc` 包含: + +```zsh +fpath=(~/.zfunc $fpath) +autoload -Uz compinit +compinit +``` + ## 服务器 ```bash diff --git a/website/src/content/docs/zh-cn/socket-api.mdx b/website/src/content/docs/zh-cn/socket-api.mdx index 3a5320b8..7454ecc7 100644 --- a/website/src/content/docs/zh-cn/socket-api.mdx +++ b/website/src/content/docs/zh-cn/socket-api.mdx @@ -17,6 +17,18 @@ Herdr 为需要检查或控制运行中会话的脚本和智能体提供了一 这些层共享同一套控制面。 +## Schema + +安装的 CLI 可以打印该 Herdr 二进制中包含的 socket 协议 schema: + +```bash +herdr api schema +herdr api schema --json +herdr api schema --output herdr-api.schema.json +``` + +普通的 `herdr api schema` 打印简短摘要。`--json` 打印供工具使用的完整 JSON Schema,`--output PATH` 将该文档写入文件。schema 覆盖原始请求、成功响应、错误响应、发出的事件和订阅事件。 + ## 你能控制什么 socket API 可以: diff --git a/website/src/content/docs/zh-cn/windows-beta.mdx b/website/src/content/docs/zh-cn/windows-beta.mdx index e092451a..971835ca 100644 --- a/website/src/content/docs/zh-cn/windows-beta.mdx +++ b/website/src/content/docs/zh-cn/windows-beta.mdx @@ -57,6 +57,23 @@ Windows Terminal 可能为特定智能体支持图像粘贴路径,但 Herdr 自 Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专门在 Windows Terminal 中测试图像渲染,否则保持 `experimental.kitty_graphics = false`。 +## 已知注意事项 + +### 光标渲染 + +Windows 终端通过 ConPTY 运行 Herdr,在活跃的全屏重绘期间,原生终端光标可能闪烁、跳动,或短暂显示旧位置。Herdr 默认的 `host_cursor = "auto"` 会在 Windows 上把 Herdr 光标绘制为终端单元格内容,而 Linux 和 macOS 继续使用原生终端光标。Windows 上的取舍是:在 Herdr 内得到稳定的不闪烁光标,但不使用外层终端的原生闪烁、形状和光标颜色。 + +要在 Windows 上改回外层终端光标,请设置: + +```toml +[ui] +host_cursor = "native" +``` + +### 键盘和鼠标 + +Windows 终端并不都以相同形式报告带修饰键的按键。Herdr 在 Windows Terminal 和 Windows 上的 Alacritty 中保留鼠标报告和 `ctrl+j`,但 `shift+enter` 只有在外层终端把它报告为独立的修饰 Enter 键时才有效。如果 Windows 或终端把它报告为普通 Enter,Herdr 会转发普通 Enter。 + ## 复制与粘贴 Herdr 的窗格文本复制在 Windows 测试版上可用。在窗格内拖选文本即可通过 Herdr 复制。