engawa-scholar 0.2.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の決定的な処理とテスト、7つの repository-local Skillを含みます。仕様の正本は SPEC.mdです。

できること

• accepted/candidate bibliographyを分離し、未承認文献の引用混入を検出する
• 引用、参照、数式、図表などのTeX anchorを静的検査する
• projectが設定したLaTeX build commandを実行し、最新PDFとlogを保存する
• 日本語TeXと英語TeXをfile単位で安全にミラーする
• working treeの原稿をGit objectとして明示保存し、過去版と最新草稿を往復する
• 文献探索、推敲、ミラー、版操作、TeX環境診断、background build、engawaへのfeedbackを自然言語から扱う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 repositoryでなければmain branchで初期化します。 既存repositoryでは現在のbranch、remote、履歴を変更しません。

インストールせずに使う

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

uvx engawa-scholar --version

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

uv tool install engawa-scholar
engawa --version

論文repositoryへ導入する

新しい論文なら、空のdirectoryでそのまま始められます。

mkdir my-paper
cd my-paper
uvx engawa-scholar init .
git status
uvx engawa-scholar status
uvx engawa-scholar check all

既存repositoryへ導入する場合も、そのrootで同じinit .を実行します。既存ファイルは 上書きしません。manuscript/が既にあれば、そのlayoutと内容をそのまま使います。 存在しない場合だけ、日英それぞれのmain.texと基本sectionを含む雛形を作ります。

.engawa/config.toml           # bibliography、version、build設定
.agents/skills/engawa-*       # Codex向けSkill
.codex/agents/engawa-builder.toml # background build用agent
AGENTS.md                     # engawaの短いrepository指示
Makefile                      # PDF buildとcheckの短い入口
references/library.bib        # 人間が追加・acceptした引用可能文献
references/candidates.bib     # AIが探索した未承認候補
references/reference.md       # 候補の概要と確認範囲
materials/README.md           # 過去原稿、論文PDF、補助資料などの置き場
manuscript/{ja,en}/main.tex   # 最小構成のLaTeX entry point

生成する雛形は次の構成です。

manuscript/
├── figures/                   # 日英で共有する図とそのsource
├── ja/
│   ├── main.tex
│   └── sections/
│       ├── abstract.tex
│       ├── introduction.tex
│       ├── methods.tex
│       ├── results.tex
│       ├── discussion.tex
│       └── conclusion.tex
└── en/
    ├── main.tex
    └── sections/              # jaと同じ6 section

日本語版はjlreq、英語版は標準articleを使う編集開始用の雛形です。投稿先の document classやbuild commandへ適宜置き換えてください。engawaは既存原稿の directory構成を強制しません。既存projectでは、実際のTeXとreference fileが .engawa/config.tomlのversion.includeに含まれるよう調整してください。 materials/は現在の原稿とは別の参考資料用で、engawaのsnapshot対象には既定で 含まれません。必要に応じてprevious-manuscripts/、papers/、notes/などに 分けて使えます。

日常の使い方

原稿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を同梱しません。初期設定はlatexmkを使い、日本語版を LuaLaTeX、英語版をpdfLaTeXでbuildします。投稿先や既存projectに合わせる場合は .engawa/config.tomlのcommandを変更してください。commandはtrusted project codeとして shellを挟まずargvで実行されます。

[build.ja]
main = "main.tex"
cwd = "manuscript/ja"
output_dir = ".engawa/build/ja"
command = ["latexmk", "-lualatex", "-interaction=nonstopmode", "-halt-on-error", "-outdir={output_dir}", "{main}"]
timeout_seconds = 120

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

make pdf
make pdf-ja
make pdf-en
make check

# Makeを使わない場合
uvx engawa-scholar build ja
uvx engawa-scholar build en

引数なしのmakeもmake pdfと同じです。Makefileはengawa CLIのpreflight、build、 postflightをそのまま利用し、PDFを直接別経路で生成しません。通常インストールした CLIを使う場合は、たとえばmake ENGAWA=engawa pdfと上書きできます。

結果は.engawa/build/<target>/へ保存され、履歴は蓄積せず最新結果だけを更新します。 各runはversion authoring setとconfigを固定した一時snapshot上でpreflight、組版、 postflightを行います。開始時と昇格時のsource digestが一致し、今回のPDFも確認できた 場合だけlatest PDFへ反映します。build中に原稿が変わったrunはstaleとなり、以前の PDFを保持します。必要なclass、figure、scriptなどのproject-local build inputは .engawa/config.tomlのversion.includeへ含めてください。output_dirはauthoring set の外でなければなりません。build commandのnetwork、filesystem、subprocessは sandboxされません。

Build中も会話を続ける

Codexへ「PDFをbackgroundでbuildして。待っている間は別の相談を続けたい」と依頼すると、 engawa-build Skillがprojectのengawa-builder agentへbuildを委譲します。メインthreadは 相談やread-only作業を続けられます。builderは成功結果を要約し、修復も依頼されている 場合だけ、明白なTeX構文や既存fileへのpath typoを一回修正して再buildします。

build中は同じTeX、BibTeX、figure、configをメインagentから編集しません。外部変更が あった場合もdigest不一致でPDF昇格を止め、builderは古いsnapshotを元に修復せずメインへ 返します。package導入、引用、科学的内容、曖昧なlabelやfigureは自動判断しません。

TeX環境を用意する

Codexへ「make pdfが動くようにTeX環境を診断して」「TeX Liveを入れたい」と 依頼すると、engawa-setup-tex Skillが既存環境を先に検査します。既に必要なtoolと classがあればインストールは行いません。不足がある場合はOSに合う公式GUIまたは package managerの選択肢と容量・権限・更新方法を示し、明示的な選択と承認を得てから 導入します。診断だけの依頼でsystem packageやPATHを変更することはありません。

engawaへfeedbackを送る

Codexへ「この不具合をengawaへ報告して」「この改善案をissueにしたい」と依頼すると、 feedback-engawa Skillが既存issueとの重複を確認し、再現手順や環境情報を整理します。 原稿本文、未公開結果、credential、local absolute pathなどは含めません。公開されるtitleと bodyを提示し、明示的な確認を得た後にだけNkzono99/engawaへGitHub Issueを作成します。

日英ミラーを設定する

.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を 変更しません。保存前後と復元直前にauthoring set全体のpath、literal bytes、Git modeを 検査し、同時変更があれば原稿を書き換えず停止します。.git、engawaのcache/build、 submoduleはauthoring setへ取り込みません。現在、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です。