engawa-scholar 0.3.0

Japanese-first scholarly writing with real-time AI assistance

engawa

Human-led, Japanese-first scholarly writing with real-time AI assistance.

engawaは、日本語で考え、書く著者にCodexなどのAIが対話を通じてリアルタイムに伴走し、 英語の投稿準備稿まで育てるためのrepository-localな執筆フレームワークです。著者の指示に 基づく文章の追加、ラフな文章の整理、原稿の検査、日本語から英語へのミラー、英語稿の ニュアンス調整、組版、版の退避と復元を、一つの執筆過程として支えます。

engawa自身は交換可能なIMRaDベースの初期骨格を含みますが、それを必須の論文構成法として 規定しません。文章作法、文献検索手法、分野別・投稿先別の規範などの具体的な方法論は、 利用者が選択する外部Skillやpluginに委ねます。 engawaはそれらと組み合わせられる安全な執筆workflowを提供し、研究上の主張、解釈、 最終文言の決定は人間に残します。日常的に見るものは原稿のTeXとAIとの会話だけに絞り、 Gitとengawaのsnapshotを安全網として使います。

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

できること

• 著者の指示に沿った文章追加、ラフな文章の整理、review、編集後の検査を対話的に支える
• accepted/candidate bibliographyを分離し、未承認文献の引用混入を検出する
• 引用、参照、数式、図表などのTeX anchorを静的検査する
• projectが設定したLaTeX build commandを実行し、最新PDFとlogを保存する
• 日本語TeXを英語TeXへfile単位で安全にミラーし、英語側のニュアンス調整を支える
• working treeの原稿をGit objectとして明示保存し、過去版と最新草稿を往復する
• 執筆、日英ミラー、build、版操作を自然言語から扱う4つの標準Skillを導入する

engawa自身はLLM APIを呼びません。文章の生成・整理・翻訳・調整は、原稿repositoryで 起動したCodexなどがSkillに従って行い、CLIは検査、状態管理、build、snapshotを 担当します。文献探索などの専門workflowが必要な場合は、外部Skillやpluginを組み合わせます。

必要なもの

• 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 .を実行します。既存の原稿、設定、 一般のrepository指示は上書きせず、AGENTS.md内のengawa管理blockだけを現在の標準指示へ 更新します。manuscript/が既にあれば、そのlayoutと内容をそのまま使います。存在しない 場合だけ、日英それぞれのmain.texとIMRaDベースのsection雛形を作ります。

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

以前のengawaが導入した検索、文章方法論、TeX環境構築、feedback用Skillや、利用者が追加した 同名Skillは自動削除しません。再度init .を実行すると新しい標準Skillと管理blockを導入し、 外部化されたSkill directoryが残っていればその存在を報告します。必要な専門Skillはそのまま 利用できますが、存在する限りAIから選択可能なので、継続利用しないものは内容を確認してから 利用者が削除してください。変更されていない旧版の標準Skill templateは現行版へ更新し、 利用者による変更を検出した場合は上書きせず停止します。

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

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 file

日本語版はjlreq、英語版は標準articleを使います。IMRaD（Introduction、Methods、 Results、Discussion）にAbstractとConclusionを加えた、すぐ書き始めるための標準骨格です。 これは必須の論文構成法ではなく、sectionの改名、並べ替え、分割、統合、削除は自由です。 AIや選択した外部Skillに構成変更を任せる場合も、著者が明示的に指示します。投稿先に合わせ、 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を起動し、通常の言葉で依頼します。

methodsのこの位置に、装置をこの構成にした理由を一段落追加して
このメモをresultsの文章に整えて。情報が不足していたら補わずに教えて
この段落を、主張の範囲と不確実性を変えずに読みやすくして
このsectionをreviewして、引用・参照と説明不足の箇所を確認して
日本語版のintroductionの変更を英語版へ反映して
英語版のこの表現が日本語より強くなっていないか確認して整えて
いまの原稿を「before-analysis」として保存して
前の版を試したい。あとで最新へ戻れるようにして

reviewだけを依頼した場合、AIは原稿を変更しません。文章の追加や整理を依頼した場合は、 著者が示した意図と範囲で対象TeXを直接編集します。不足する結果、数値、mechanism、引用を 推測で補わず、判断が必要な点は著者へ戻します。通常の編集前にsnapshotを自動作成せず、 保存を依頼した場合だけversion saveを使います。変更後は関連するengawa checkを実行し、 変更箇所と未解決事項を短く報告します。

実行モデル

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

全体reviewでは、依頼されたcoverageを満たすために読む範囲と検査を広げ、必要な時間を 使います。

執筆支援と方法論の分離

engawaが導入する標準Skillの役割は、執筆方法を教えることではなく、著者とAIの作業を 安全かつ継続的に進めることです。

• engawa-writing: reviewと編集を区別し、著者の指示に沿った追加・整理・検査を行う
• engawa-mirror: 日本語稿から英語稿への反映と、日英の変更・競合状態を管理する
• engawa-build: 設定済みの組版と結果確認を行い、必要ならbackground buildを扱う
• engawa-version: 明示された時点の保存、比較、切替、復元を扱う

標準Skillは、未提示の研究内容を発明せず、claimの範囲や不確実性を無断で変えず、 編集後に関連する検査を行うという運用上の契約を提供します。良い論文の構成方法、 段落や論証の改善手法、日本語・英語の文章規範、分野やjournal固有の慣行、文献の 検索・選定方法などは規定しません。必要に応じて、それらに特化した外部Skillやpluginを 利用者が選び、engawaの原稿・検査・mirror・version workflowと組み合わせます。

文献の扱い

引用可能な正本はreferences/library.bibです。著者が文献を一意に指定して直接追加する 場合はacceptedとして扱えます。一方、外部の文献探索Skillが未知の文献を見つけた場合は、 実在性とmetadataを確認した後でも、まずreferences/candidates.bibと references/reference.mdへ入れます。人間が候補をacceptするまでTeXへ引用しません。 engawaはこの安全境界を管理しますが、検索先、検索式、ranking、採否の学術的判断方法は 規定しません。

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は自動判断しません。

日英ミラーを設定する

.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で同時変更のpreimageを記録し、日本語の意味、主張の範囲、不確実性、TeX anchorを保った英語の完成postimageをignored cacheへ作ります。mirror finalize --from-file はlock内でtarget preimageを再確認し、独立変更がなければpostimageを原子的に反映してから anchorとbaselineを確定します。 英語稿のニュアンスや表現の調整も著者が直接依頼できます。同期済みのpairでは調整前に mirror beginを行い、調整後に同じ検査を通してmirror finalize --from-fileするため、英語編集も baselineへ安全に反映できます。transaction外の英語側に独自変更がある状態で次のミラーを 行う場合は、黙って上書きせず競合として扱います。著者が日英を明示的にreconcileして 意味対応を確認した場合だけ、例外的な新baselineとしてmirror adoptできます。

target反映後のledger I/O失敗などでexit 3になった場合は、stageとoperationを保持します。 CLIが報告したhashとtargetが一致し、source/ledgerのpreconditionも有効な場合だけ、報告された --expect-targetでledger更新を再開します。一致しない場合は自動採用せず著者へ戻します。

既に意味が対応している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/introduction.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 --from-file|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、結果解釈、結論は人間が決める
• AIは著者が提示していない結果、数値、mechanism、citationを発明しない
• TeXへ会話ログ、approval台帳、engawa固有markerを増やさない
• AIは明示依頼なしにcommit、push、投稿、メール、submissionを行わない
• acceptedになった文献も、個々のclaimを支持するかは別途確認する
• build成功や機械検査の通過は、最終PDFの視覚確認、論文完成、投稿可能性を意味しない
• 投稿稿の最終文言と実際にsubmitするかどうかは人間が判断する

詳細な安全保証、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です。