engawa-scholar 0.1.0

Human-led scholarly writing, with AI at the margins

engawa

Human-led scholarly writing, with AI at the margins.

engawaは、人間がLaTeX原稿を主導して書き、CodexなどのAIに文献探索、 推敲、日英ミラー、組版、版の退避と復元を任せるためのrepository-localな CLIとSkillです。日常的に見るものは原稿のTeXとAIとの会話だけに絞り、 Gitとengawaのsnapshotを安全網として使います。

現在は初期usable versionです。CLIの決定的な処理とテスト、4つの repository-local Skillを含みます。仕様の正本は SPEC.mdです。

できること

• accepted/candidate bibliographyを分離し、未承認文献の引用混入を検出する
• 引用、参照、数式、図表などのTeX anchorを静的検査する
• projectが設定したLaTeX build commandを実行し、最新PDFとlogを保存する
• 日本語TeXと英語TeXをfile単位で安全にミラーする
• working treeの原稿をGit objectとして明示保存し、過去版と最新草稿を往復する
• 文献探索、推敲、ミラー、版操作を自然言語から扱うSkillを導入する

engawa自身はLLM APIを呼びません。文章生成と検索は、原稿repositoryで起動した CodexなどがSkillに従って行い、CLIは検査、状態管理、build、snapshotを担当します。

必要なもの

• uv
• Git
• Codexなどrepository-local Skillを利用できるAI（AIなしでもCLIは使用可能）
• buildする場合だけ、projectで使用するTeX distributionとbuild tool

engawa initはgit initを実行しません。導入先は既存のGit repositoryである 必要があります。

インストールせずに使う

PyPI上のdistribution名はengawa-scholarです。uvxが隔離環境を自動作成して cacheするため、engawa自体の事前installや仮想環境の管理は不要です。

uvx engawa-scholar --version

通常のpackageとしてinstallする場合も、短いengawa commandを利用できます。

uv tool install engawa-scholar
engawa --version

論文repositoryへ導入する

導入先のrootで実行します。

cd path/to/paper
git status
uvx engawa-scholar init .
uvx engawa-scholar status
uvx engawa-scholar check all

既存ファイルは上書きしません。初期化により、足りないものだけが追加されます。

.engawa/config.toml           # bibliography、version、build設定
.agents/skills/engawa-*       # Codex向けSkill
AGENTS.md                     # engawaの短いrepository指示
references/library.bib        # 人間が追加・acceptした引用可能文献
references/candidates.bib     # AIが探索した未承認候補
references/reference.md       # 候補の概要と確認範囲

原稿のdirectory構成は強制しません。既定ではmanuscript/**をversion対象にするため、 例えば次のように置けます。

manuscript/
├── ja/
│   ├── main.tex
│   └── sections/
└── en/
    ├── main.tex
    └── sections/

既存projectでは、実際のTeXとreference fileが .engawa/config.tomlのversion.includeに含まれるよう調整してください。

日常の使い方

原稿repositoryのrootでCodexを起動し、通常の言葉で依頼します。

この段落を、主張と不確実性を変えずに読みやすくして
この主張を支持する最近の文献を探して。まだ引用には入れないで
候補のsmith2025をacceptして、この文末に引用を追加して
日本語版のintroductionの変更を英語版へ反映して
いまの原稿を「before-analysis」として保存して
前の版を試したい。あとで最新へ戻れるようにして

AIは対象TeXを直接編集します。通常の編集前にsnapshotを自動作成せず、保存を依頼した 場合だけversion saveを使います。変更後は関連するengawa checkを実行し、変更箇所と 未解決事項を短く報告します。

実行モデル

engawaは、依頼を満たす最小十分なworkflowで著者が認識できる進捗を早く返すことを 目標にします。一つのcontext ownerが読解から編集、検査までを一貫して扱い、通常編集は 一回の編集と一回の成功した関連検査で完了します。CLIは文章生成やLLM orchestrationを 行わないため、coordination overheadを追加しません。

全体reviewでは、依頼されたcoverageを満たすために読む範囲と検査を広げ、必要な時間を 使います。日本語可読性ガイドは、明示的な読みやすさ改善または段落以上の改稿でだけ context ownerが参照します。

日本語の読みやすさ

engawa-polishには、段落の役割、論証のつながり、指示対象、認知負荷、冗長な LLM調の表現を点検する軽量ガイドを同梱しています。これは技術書向けの文章規範を 論文用に翻案した観点であり、固定文体ではありません。著者の文体、投稿先の 規定、科学的な正確さを優先し、敬体化、一文一行、劇的な語りなどを強制しません。

文献の扱い

引用可能な正本はreferences/library.bibです。AIが見つけた文献は、実在性とmetadataを 確認した後でも、まずreferences/candidates.bibとreferences/reference.mdへ入ります。 人間が文献を指定またはacceptするまでTeXへ引用しません。

uvx engawa-scholar check all

この検査はcandidate-only citation、未登録またはcandidate bibliographyのbuild登録、 重複key・DOI・arXiv ID、未定義のcitation/referenceなどを検出します。

Buildを設定する

engawaはTeX distributionを同梱しません。.engawa/config.tomlへproject固有のcommandを argvとして設定します。commandはtrusted project codeとしてshellを挟まず実行されます。

[build.ja]
main = "main.tex"
cwd = "manuscript/ja"
output_dir = ".engawa/build/ja"
command = ["latexmk", "-pdf", "-outdir={output_dir}", "{main}"]
timeout_seconds = 120

[build.en]
main = "main.tex"
cwd = "manuscript/en"
output_dir = ".engawa/build/en"
command = ["latexmk", "-pdf", "-outdir={output_dir}", "{main}"]
timeout_seconds = 120

uvx engawa-scholar build ja
uvx engawa-scholar build en

結果は.engawa/build/<target>/へ保存され、履歴は蓄積せず最新結果だけを更新します。 build commandのnetwork、filesystem、subprocessはsandboxされません。

日英ミラーを設定する

.engawa/mirror.tomlにfile pairを登録します。

schema_version = 1

[[pair]]
id = "introduction"
source = "manuscript/ja/sections/introduction.tex"
target = "manuscript/en/sections/introduction.tex"

uvx engawa-scholar mirror status introduction

通常はCodexへ「introductionを英語版へ反映して」と依頼してください。Skillは mirror beginで同時変更を監視し、英語TeXを直接編集した後、anchorとhashを検査して mirror finalizeします。英語側にも独自変更がある場合は黙って上書きしません。

既に意味が対応しているpairを初めて登録した場合だけ、人間の確認後にbaselineを採用します。

uvx engawa-scholar mirror adopt introduction

原稿の版を保存する

uvx engawa-scholar version save first-draft
uvx engawa-scholar version list
uvx engawa-scholar version diff first-draft
uvx engawa-scholar version switch first-draft
uvx engawa-scholar version latest

switchは切替直前の草稿を自動保存します。過去版を編集中にlatestを実行すると、その編集も 保存してから最初の最新草稿へ戻ります。特定のTeX fileだけを再利用することもできます。

uvx engawa-scholar version take first-draft --file manuscript/ja/sections/method.tex

snapshotはlocal Git objectとnamespaced tagだけで構成され、通常のindex、HEAD、branchを 変更しません。現在、snapshotのpush / fetchとblock単位のtakeは未実装です。

CLI概要

uvx engawa-scholar init [path]
uvx engawa-scholar status
uvx engawa-scholar check [ja|en|all]
uvx engawa-scholar build [ja|en|all]
uvx engawa-scholar mirror status|begin|finalize|abort|adopt ...
uvx engawa-scholar version save|list|show|diff|switch|latest|take|adopt|recover ...

診断commandは--jsonに対応します。exit codeは成功が0、検査・build・競合などの 作業上の失敗が1、設定不備または利用不能機能が2、復旧が必要な中断状態が3です。

設計上の境界

• research question、story、claim、結果解釈、結論は人間が決める
• TeXへ会話ログ、approval台帳、engawa固有markerを増やさない
• AIは明示依頼なしにcommit、push、投稿、メール、submissionを行わない
• acceptedになった文献も、個々のclaimを支持するかは別途確認する
• build成功は最終PDFの視覚確認や論文完成を意味しない

詳細な安全保証、snapshot format、check項目は SPEC.mdを参照してください。

開発

git clone https://github.com/Nkzono99/engawa.git
cd engawa
uv sync --extra dev
uv run python -m compileall -q src
uv run pytest
uv build --no-sources

テストは一時Git repositoryだけを使用し、networkへ接続しません。

ライセンス

MIT Licenseです。