extract-from-md v6 仕様書 / エージェント指示 / マニュアル
extract-from-md v6
0. v5 → v6 変更点
| 項目 | v5 | v6 |
|---|---|---|
| Markdown 解析 | 手書き正規表現 + フェンス走査 | unified + remark-parse による MDAST 解析 |
| コードブロック検出 | FENCE_OPEN_RE で1行ずつ走査 | unist-util-visit で AST の type:'code' ノードを走査 |
| 境界ケース | 4連バッククォート、リスト内インデント、コード内 ``` などで誤動作の可能性 | CommonMark 準拠で全ケースを正確に処理 |
| フェンス情報の解釈 | parseFenceInfo() が info 文字列を自前でトークン化 | node.lang + node.meta を MDAST から受け取り parseFenceInfoFromMDAST() で解釈 |
| 依存関係 | Node.js stdlib のみ | unified, remark-parse, unist-util-visit を追加 |
| Node.js | 14+ | 16+ (ESM only) |
0.1 なぜ AST ベースにしたか
v5 までの手書き正規表現パーサは、以下の境界ケースで誤動作するリスクがあった:
- 4連バッククォート:
````jsで開いたブロックを```で閉じてしまう - リスト内インデント: リスト項目内のコードブロックが正しく認識されない
- **コード内の
文字列**: コードブロックの本文中に ``“ が含まれる場合、フェンスの終端と誤認 - 未終端フェンス: メッセージが途中で切れた場合の挙動が不安定
- チルダフェンス:
~~~と```の混在
remark-parse は CommonMark 準拠のステートマシン で解析するため、これらのケースを全て正しく処理する。
0.2 MDAST の code ノード構造
remark-parse が生成する code ノードは以下の構造を持つ:
{ "type": "code", "lang": "js", "meta": "title=\"js/a.js\"", "value": "const a = 1;\n", "position": { "start": { "line": 5, "column": 1, "offset": 42 }, "end": { "line": 7, "column": 4, "offset": 68 } }}lang: info string の最初の単語(js)meta: 残りの部分(title="js/a.js"/[js/a.js]/js/a.jsなど)value: コード本文position: 行・列の位置情報
parseFenceInfoFromMDAST() が lang + meta からパスを抽出する。
Part 1. 仕様書
1.1 依存関係
npm install unified remark-parse unist-util-visit| パッケージ | バージョン | 用途 |
|---|---|---|
unified | 11.x | 処理パイプライン |
remark-parse | 11.x | Markdown → MDAST |
unist-util-visit | 5.x | AST 走査 |
ESM only。Node.js 16+ が必要。
1.2 パス解決の 5 ソース(変更なし)
| # | ソース | 例 | 既定 |
|---|---|---|---|
| 1 | marker | // === @file: js/x.js === | ✅ |
| 2 | fence | ```js title="js/x.js" / ```js [js/x.js] | ✅ |
| 3 | heading | 直前見出し ## `js/x.js` | opt-in |
| 4 | paragraph | 直前段落 | opt-in |
| 5 | bare | // js/x.js | --mode all のみ |
1.3 マーカー文法(変更なし)
v5 と同じ。=== は推奨だが必須ではない。@file: path / @file path / @file:path / @ 省略 / 各言語のコメント記法を全て受理。
1.4 --out 既定値(変更なし)
| 入力種別 | 既定 --out |
|---|---|
| ディレクトリ | <input>/out |
| ファイル | <parent>/<basename(拡張子抜き)>/out |
1.5 その他(v5 から継承)
- モード:
strict-marker(既定) /marker/heading/all - lang↔拡張子ハード検査(heading/paragraph/bare のみ)
- 継続結合:
parts(既定) /auto/same-target/off - 競合: 後勝ち +
_superseded/退避 - 会計: 全ブロック disposition 分類、合計不一致 exit 3
- exit: 0 成功 / 1 CLI エラー / 2 未抽出あり / 3 会計バグ
1.6 v5 との互換性
CLI オプションは完全互換。v5 と同じコマンドがそのまま動作する。
唯一の違いは 未終端フェンスの扱い:
- v5: 未終端フェンスもブロックとして抽出(
unclosed: trueフラグ付き) - v6:
remark-parseは閉じたコードブロックのみcodeノードとして返す。未終端フェンスは MDAST のcodeノードにならない ため、v5 のようなunclosedフラグ付きブロックは生成されない。
注意: 未終端フェンスの内容を救出したい場合は、v5 の
--no-unclosedフラグに相当する機能が v6 では動作しない。代わりに、LLM プロンプトで「必ずフェンスを閉じる」ことを強制する運用を推奨。
Part 2. エージェント指示(LLM プロンプト)
## 出力フォーマット(厳守)
1 ファイル = 1 見出し + 1 コードブロック。説明文はコードブロックの外。
### 形式
## `relative/path/to/file.ext`
```<lang> // === @file: relative/path/to/file.ext === <ファイルの完全な内容> ```
### ルール
1. 見出しは H2 (`##`)。パスはバッククォートで囲む。2. フェンスは三連バッククォート。言語タグ必須。3. コード本体の 1 行目に @file マーカー。推奨形式は `===` 装飾付き: JS/TS : // === @file: js/00-main.js === CSS : /* === @file: styles/00-base.css === */ HTML/XML : <!-- === @file: index.html === --> Python/Sh : # === @file: setup.py === SQL : -- === @file: db/schema.sql === 装飾なし (`// @file: js/00-main.js`) や空白区切り (`// @file js/00-main.js`) も受理されるが、`===` 装飾付きを推奨(HTML bundle 規約と一致)。 1 行目厳守。先頭に空行を入れない。BOM を付けない。4. パスは相対のみ。`./` 不要、`..` 禁止、絶対パス禁止。5. 1 ファイルは 1 コードブロック。省略記号 (`...`) 禁止。6. 途中で切れる場合、必ず `// @part: n/m` を 2 行目に。最終パートに `// @end`。7. 末尾に「確認コマンド」「実行方法」等を書く場合、必ず ```bash 等の 非ファイル言語タグを付ける。8. コードブロック内に説明・diff・チェックリストを書かない。
### 自己検証
生成後、以下が exit 0 になること: node scripts/extract-from-md.mjs <output.md> --dry --verbose (--out 未指定なら <output>/out/ に書かれる)--emit-prompt で取得可能。
Part 3. マニュアル
3.1 インストール(v6 新規)
# 依存関係のインストールnpm install unified remark-parse unist-util-visitpackage.json がない場合は npm init -y で作成してからインストール。
3.2 基本コマンド(v5 と同じ)
# ディレクトリ入力 → messages/out/ に出力node scripts/extract-from-md.mjs messages/
# ファイル入力 → prompts/foo/out/ に出力node scripts/extract-from-md.mjs prompts/foo.md
# 明示的に out を指定node scripts/extract-from-md.mjs messages/ --out ./out
# 事前確認node scripts/extract-from-md.mjs messages/ --dry --verbose
# 上書きnode scripts/extract-from-md.mjs messages/ --force
# LLM 用プロンプト取得node scripts/extract-from-md.mjs --emit-prompt
# モード一覧node scripts/extract-from-md.mjs --list-modes3.3 v6 で改善された境界ケース
以下のケースで v5 よりも正確に動作する:
4連バッククォート:
````js// === @file: js/a.js ===const s = "```";v5: 内部の `` ``` `` をフェンス終端と誤認する可能性v6: `remark-parse` が正しく処理
**リスト内コードブロック**:```markdown- 項目1 ```js // === @file: js/b.js === const b = 2; ``````v5: インデントの dedent が不正確な場合ありv6: CommonMark 準拠で正確に処理
**チルダフェンス**:```markdown~~~python# === @file: setup.py ===print("hi")~~~```v5: 処理可能だったが、チルダとバッククォートの混在で問題が起きる可能性v6: 全ケースを正確に処理
### 3.4 トラブルシューティング(v6 追加分)
#### `Cannot find module 'unified'`
依存関係がインストールされていない。`npm install unified remark-parse unist-util-visit` を実行。
#### `ERR_REQUIRE_ESM`
Node.js 14 以下を使用している。Node.js 16+ にアップグレードするか、`package.json` に `"type": "module"` を追加。
#### 未終端フェンスの内容が抽出されない
v6 では `remark-parse` の仕様上、閉じられていないフェンスは `code` ノードにならない。これは **意図した動作**。未終端フェンスの内容を救出したい場合は、v5 を使用するか、LLM プロンプトでフェンスを必ず閉じることを強制する。
---
## Part 4. HTML bundle 連携(変更なし)
```bashnode scripts/extract-from-md.mjs llm-output.md \ --out public/tools/snake \ --mode strict-marker \ --marker-line 1 \ --join parts \ --force \ --manifest ./public/tools/snake/_report/manifest.json
node scripts/html-build/audit-imports.mjs --project snakenode scripts/html-build/verify.mjs --project snake```
---
## 付録. v5 → v6 移行ガイド
| 手順 | コマンド ||---|---|| 1. 依存関係のインストール | `npm install unified remark-parse unist-util-visit` || 2. スクリプトの置き換え | v6 を `scripts/extract-from-md.mjs` に配置 || 3. 動作確認 | `node scripts/extract-from-md.mjs messages/ --dry --verbose` || 4. 既存の運用を確認 | CLI オプションは互換。未終端フェンスのみ挙動が異なる |
**CLI オプションは互換**のため、既存のバッチスクリプトや CI 設定の変更は不要。