quarto-dsh

Quarto 編集・レンダリング強化ハーネス。 Quarto の正確な知識（quarto-pe）とエージェント基盤（deepseek-harness）を融合。

Quarto 編集・レンダリングを「正確に・自動で」

quarto-dsh は Quarto の実在キーだけを検証 し、記法を検査し、レンダリングを自動化するための CLI / Web UI / LSP ツールです。

ネットに転がる誤った設定に惑わされず、公式仕様に基づく正確な設定だけを手元で確認できます。

始める → GitHub

なぜ quarto-dsh か

Quarto は高機能な一方、_quarto.yml のキーは project / format / website / book / execute などに散在し、Web 上の情報には実在しない記法や誤ったコマンドが混ざっています。

quarto-dsh は quarto-pe（Quarto の正確な設定・記法知識）と deepseek-harness（プラグイン型エージェント基盤）の技術エッセンスを融合し、正確さと自動化を両立させました。

DeepSeek Harness について

DeepSeek Harness (DSH) は、DeepSeek AI が提供するオープンソース（MIT）のプラグインベース・エージェントフレームワークです。エージェント基盤（harness）として、「モデルと行動の間をつなぐ層」 を担い、コードの調査・編集・コマンド実行・タスク遂行を自動化します。

Important現状: Developer Preview

DSH は 開発者プレビュー 段階にあり、急速に開発が進んでいます。互換性を破壊する変更が含まれることに注意してください。dsh コマンドは npx @deepseek-ai/dsh で起動できます。

中核思想: Everything is a Plugin

DSH の根底にあるのは 「すべての機能がプラグイン」 という設計思想です。

  • すべての機能が plugin として実装されており、Cordis というメタフレームワークのランタイム上で動作します（Cordis の設計は A Programming Paradigm for Spatiotemporal Composability で説明されています）。
  • モデル呼び出し・ツール連携・ファイル操作・シェル実行など、機能の追加・差し替えはプラグインの追加・変更で行えます。本体を書き換える必要はありません。

モジュール構成

packages/ 配下に core, api, llm, shell, web など 13 種類のモジュールがあります。各モジュールが役割を分担します。

モジュール 主な役割
core エージェントの核となる実行ループ・状態管理
api 外部 API との連携・プロバイダー抽象化
llm モデル呼び出し・ストリーミング・ツール呼び出し（tool calls）
shell コマンド実行（サンドボックス化）
web Web UI（既定で http://127.0.0.1:3080）
他 セッション管理・計画・ツール連携など計 13 種

主な特徴

  • 任意の LLM・プロバイダーと組み合わせられる — DeepSeek だけでなく、OpenAI、Anthropic、Azure など 30 以上のプロバイダーに対応し、役割ごとに異なるモデルを割り当てられます。
  • プラグインエコシステム — dsh-vision、dsh-pdf、dsh-weather など、ツールや UI 拡張のプラグインが多数用意されており、plugin-registry で簡単に追加・管理できます。自作プラグインは dsh-plugin トピックで公開・発見できます。
  • 安全な実行環境 — コマンド実行はサンドボックス化され、プランモードではファイル変更を行わず、承認が必要な操作は UI が確認ダイアログを出します。
  • 永続的セッションと履歴 — 各タスクは append-only ledger に記録され、fleet resume で途中から再開可能です。セッションをフォークして並行に試行することもできます。

使用方法（概要）

  1. Web UI 起動 — npx @deepseek-ai/dsh web（またはソースから pnpm dsh web）で起動し、http://127.0.0.1:3080 にアクセス。
  2. モデル設定 — Settings → Models で DeepSeek などの API キーを入力（サーバー再起動は不要）。
  3. ワークスペース選択 — プロジェクトディレクトリを選んでファイル操作対象を決定。
  4. タスク実行 — チャットウィンドウに「リポジトリを要約して主要パッケージを列挙してください」のように指示すると、エージェントがコードを読み、必要に応じてコマンドを走らせて結果を返します。

開発・拡張

  • 新しいプラグインは packages/ に ESM 形式で追加し、ctx.effect() / ctx.on() で登録。Cordis のサービス・イベント機構にフックします。
  • vendor/ ディレクトリに外部依存（Cordis など）のソースコードがピン留めされ、vendor/README.md の手順で更新できます。
  • 開発は docs/development.md と docs/architecture.md から始められます。

DeepSeek Harness は、「好きなモデルで好きな作業を自動化」 できるオープンソースのエージェント基盤として、CLI、Web UI、VS Code など多様なクライアントから利用可能です。フィードバックは GitHub Discussions で受け付けています。

.qmd（Quarto Markdown）ファイルは DeepSeek Harness のテキスト処理エンジンと相性が良いです。

プレーンテキストとして直接扱える

  • DeepSeek Harness では「ファイル操作」プラグインが標準で提供されており、任意のテキストファイルを 読み込み・書き換え・保存 できます。
  • .qmd はプレーンテキストなので、プラグインにパスを渡すだけで内容を取得し、内容の要約や構造解析、コードブロック抽出などのタスクを実行できます。
  • YAML front-matter もただのテキストなので、タイトル・著者・メタデータの一括整形も容易です。

コードブロックと実行結果の統合

  • Quarto のコードチャンク（{r}、{python} など）はプレーンテキストとして認識されるため、LLM にコード実行指示を出す際にそのまま送信でき、実行結果を再び .qmd に埋め込むフローがシームレスです。
  • 解析・集計の結果をチャンクの実行結果欄に書き戻す、というリポーティングの自動化ができます。

CI/CD パイプラインでの自動化

  • Harness の CLI から dsh run <task> を呼び出すだけで、.qmd を対象に自動要約・目次生成・画像キャプション付与といったバッチ処理が可能です。
  • これにより、Quarto プロジェクトのビルド前に AI がコンテンツを最適化できます（例: プッシュ時に quarto render と合わせて実行）。

拡張プラグインの作成

  • 必要なら 独自プラグイン（例: dsh-quarto）を作り、Quarto のメタデータ（YAML front-matter）を解析して、ドキュメント構造をモデルに渡すことも容易です。
  • プラグインは packages/ に追加し、ctx.effect() でフックすれば即座に利用できます。
  • 自作プラグインは dsh-plugin トピックを付けて公開すると見つけてもらいやすくなります。

quarto-dsh との関係

quarto-dsh は DSH のモノレポそのものは採用せず、プラグインアーキテクチャの思想のみを実物の Cordis（@cordisjs/core）で再現しています。エージェントループ・セッションログ・能力シーム（llm / shell / tools）という DSH の中核アイデアを、Quarto 専用に特化した形で実装したのが quarto-dsh です。

結論: .qmd は単なるテキストファイルであるため、DeepSeek Harness のファイル操作やコード実行プラグインと自然に連携でき、Quarto ドキュメントの自動処理・最適化に有効です。

機能

VALIDATE ### ✅ lint

_quarto.yml と front matter を実在キーで検証。project.type: blog のような実在しない値も即座に指摘します。

quarto-dsh lint

INSPECT ### 🔍 scan

callout 型・チャンクオプション・相互参照・Div の開閉を .qmd ごとに検査します。

quarto-dsh scan index.qmd

AUTOMATE ### 🚀 render

quarto render / preview をエージェントや CI から実行。テンプレートからプロジェクト生成、GitHub Pages デプロイ設定の生成もできます。

quarto-dsh render
quarto-dsh project website-blog my-blog
quarto-dsh ci

機能一覧

機能 内容
quarto-dsh lint _quarto.yml / front matter を実在キーで検証
quarto-dsh scan callout・チャンク・相互参照・Div の検査
quarto-dsh render quarto render / preview 実行
quarto-dsh project テンプレートからプロジェクト生成
quarto-dsh ci GitHub Pages 自動デプロイ設定を生成
quarto-dsh chat LLM エージェントで編集・検証を遂行
quarto-dsh web ブラウザで lint / scan / render / chat
quarto-dsh-lsp エディタの補完・診断

CLI Web UI LSP DeepSeek Agent

読み進める

STEP 1 ### インストール セットアップと動作確認。

STEP 2 ### lint / scan 設定を検証し、記法を検査。

STEP 3 ### render / project レンダリングを自動化し、プロジェクトを生成。

STEP 4 ### CI デプロイ GitHub Pages で公開。

クイックスタート

Tip必要なもの
  • Quarto >= 1.3（brew install quarto）
  • Node.js >= 20
  • LLM エージェントを使う場合のみ DEEPSEEK_API_KEY
git clone https://github.com/watanabe3tipapa/quarto-dsh.git
cd quarto-dsh
pnpm install
pnpm build

quarto-dsh lint          # 設定の検証（実在キーかどうか）
quarto-dsh scan index.qmd
quarto-dsh render        # レンダリング
Note正確さへのこだわり

project.type は実在値のみ（default / website / book / manuscript）。旧 quarto-pe にあった誤記（article / blog / presentation）や実在しないコマンド（quarto check project / quarto config など）は収録していません。