@shibayama/pdgkit 0.1.0

package/docs/ai-authoring-guide.md

@@ -0,0 +1,507 @@
+# PatentDSL（.pdg）記述ガイド — AI 用
+
+このガイドは、特許図面を PatentDSL（`.pdg`）で記述する AI のための指示書です。ホスト（明細書作成ツールなど）のシステムプロンプトにそのまま注入して使います。読んだ AI が、説明から正しい `.pdg` を一度で再現できることを目的に書かれています。正典は [spec.md](spec.md) です。
+
+---
+
+## 0. 出力契約（最初に守ること）
+
+- 出力は `.pdg` のコードブロックを 1 つだけにする。前後に説明文を付けない（明示的に求められた場合を除く）。
+- コードブロックの 1 行目は必ず図種アサーション `#! kind: <block|flow|state|seq>` にする。
+- 与えられた情報だけで判断し、足りない部分は最も妥当な構造で補って、完成した `.pdg` を出す。質問で止まらない。
+- 検証エラー（diagnostics）を渡されたら、その指摘だけを直して `.pdg` 全体を再出力する。
+
+出力の形:
+
+````
+```pdg
+#! kind: block
+10 = ...
+...
+```
+````
+
+---
+
+## 1. 言語の全体像
+
+- 1 行 = 1 文。改行が文の終わり。文は 3 種類だけ（定義・包含・接続）。`#` から行末はコメント。
+- 符号（ID）は `[A-Za-z0-9_*]+`。装置の構成要素には数値（`10`, `11`, `100`）、方法のステップには `S100`, `S110` のように `S` + 10 刻みを使うのが慣例。
+- ラベルは「日本語 / english」の形。区切りは前後に空白のある ` / ` のみ。`A/D` や `I/O` のような語中の `/` はそのまま書ける。片方だけでもよい。
+
+---
+
+## 2. 3 つの文（正確な書式）
+
+### 定義 — 符号にラベルを付ける
+
+```pdg
+10 = 制御装置 / control device
+11 = CPU
+13 = "I/O インターフェース" / "I/O interface"
+```
+
+### 包含 — 親が子を内包する（スペース区切り）
+
+```pdg
+10 : 11 12 13
+```
+
+### 接続 — 線・矢印を引く（演算子の前後に半角スペース必須）
+
+```pdg
+11 -> 12 : 制御信号 / control signal
+```
+
+演算子:
+
+| 演算子 | 線種 | 用途 |
+|---|---|---|
+| `-` | 単線 | 方向のない接続 |
+| `->` | 矢印 | 方向のある接続（基本） |
+| `<-` | 逆矢印 | `A <- B` は `B -> A` と同じ |
+| `<->` | 双方向 | 相互通信 |
+| `..` | 破線 | 論理的・補助・電源など |
+| `.>` | 破線矢印 | 無線通信などの方向あり破線 |
+| `=>` | 太矢印 | 主信号の強調 |
+
+---
+
+## 3. 絶対規則（破るとエラーになる）
+
+1. 接続演算子の前後には半角スペースを必ず置く。`11 - 12` は正、`11-12` は誤り。
+2. 接続は 1 行に 1 本だけ。連鎖記法 `A -> B -> C` は使えない。`A -> B` と `B -> C` の 2 行に分ける。
+3. 1 ファイルに 1 つの図だけを書く。複数の図は別々に出力する。
+4. 符号（ID）に使えるのは `A-Za-z0-9_*` だけ。`=` `:` `-` `>` `<` `.` `/` `#` `"` `(` `)`・空白は使えない。
+5. ラベルに ` / `（区切り扱いの空白付きスラッシュ）、`:`、`=`、`#`、`"` を含めたいときは、その語を `"..."` で囲む。
+6. 色・線の太さ・座標・フォントは指定できない（特許図面は黒線・無装飾）。
+
+---
+
+## 4. 図種の決め方（手順）
+
+図種は宣言ではなく、書いた構造から自動的に決まります。次の手順で「狙った図種」を確実に作ります。
+
+### 手順 1: 入力から図種を選ぶ
+
+- 装置・システムの構成（何が何を含み、何と何がつながるか） → ブロック図 `block`
+- 処理・方法の流れ、条件分岐 → フローチャート `flow`
+- 状態とその間の遷移 → 状態遷移図 `state`
+- 複数の主体（クライアントとサーバなど）間のやりとり → シーケンス図 `seq`
+
+### 手順 2: 「目印」で図種を成立させる
+
+図種は次の優先順位で推論されます（上にあるものが優先。最初に該当したもので確定）。
+
+1. 包含文 `:` が 1 つでもある → ブロック図
+2. ラベル末尾が `?` の符号がある → フローチャート
+3. 符号 `*` が登場する → 状態遷移図
+4. `<->`、または往復ペア（`A -> B` と `B -> A` の両方）がある → シーケンス図
+5. 上記以外（片方向の接続のみ） → フローチャート
+
+選んだ図種に応じて、必要な目印を入れ、他の図種の目印を混ぜないようにします。
+
+| 狙う図種 | 入れる目印 | 入れてはいけないもの |
+|---|---|---|
+| block | 包含 `親 : 子...` | （`:` があれば最優先で block になるので他は気にしなくてよい） |
+| flow | 片方向 `->` でつなぐ。条件分岐は末尾 `?` | 包含 `:`（あると block になる） |
+| state | `*` と状態をつなぐ | 包含 `:`、末尾 `?` |
+| seq | 主体間で往復させる、または `<->` | 包含 `:`、末尾 `?`、符号 `*` |
+
+### 手順 3: 1 行目で宣言する
+
+`#! kind: block` のように、選んだ図種を 1 行目に必ず書く。これは検証で構造と照合され、食い違えばエラーになる。宣言と実際の構造を一致させること。
+
+---
+
+## 5. 形状の自動決定
+
+書く必要はなく、図種と構造から自動で決まります。狙って形を出すために知っておくこと。
+
+- フローチャートで条件分岐の菱形を出すには、ラベル末尾を `?` にし、その符号を接続に登場させる。
+- フローチャートで入次数 0 のノードは開始（角丸）、出次数 0 のノードは終了（角丸）になる。
+- 状態遷移図で `*` は初期・終端の黒丸になる。
+
+---
+
+## 6. 符号の付け方
+
+- 装置クレーム: 上位構成に大きい番号（`100` = システム）、その下の部に十の位（`10`, `20`）、さらに下の部品に一の位を加える（`11`, `12`）と階層が読みやすい。
+- 方法クレーム: `S100`, `S110`, `S120` のように `S` + 10 刻み。後から間に挿入しやすい。
+- 図に登場する符号はすべて定義する。定義せず接続だけに書いた符号は「暗黙ノード」になり、意図しない空ノードが現れる。
+- 複数の図で同じ部品を指すときは、図をまたいで同じ符号・同じ名称を使う（この一貫性は書き手が管理する）。
+
+---
+
+## 7. 自然言語から組み立てる手順と例
+
+以降の `.pdg` はすべて検証済み（`validate` が通り、宣言どおりの図種になる）。発明の説明を図にする際の手本として使う。
+
+### 7.1 組み立ての手順
+
+1. 構成要素を洗い出す。文中の名詞（部・装置・ステップ・主体）を列挙する。
+2. 符号を割り当てる。装置は数値（上位ほど大きく、下位部品ほど小さく）、方法ステップは `S100`, `S110`。
+3. 包含関係を書く（ブロック図のとき）。「A は B と C を含む／備える／有する」→ `A : B C`。
+4. 接続を書く。「A が B へ〜を送る／出力する」→ `A -> B : ラベル`。1 行 1 本。
+5. ラベルを付ける。可能なら「日本語 / english」。
+6. 図種を宣言する。1 行目に `#! kind: ...`。
+7. 自己点検する（セクション 8）。
+
+### 7.2 詳しい組み立て（思考過程の例）
+
+指示: 「センサ端末は、温度センサと加速度センサを有する検出部と、取得部および判定部を有する処理部と、通信部とを備える。検出部のセンサ値は処理部へ送られ、処理部の送信データは通信部を介してゲートウェイへ無線送信される。」
+
+- (1) 構成要素: センサ端末 / 検出部 / 温度センサ / 加速度センサ / 処理部 / 取得部 / 判定部 / 通信部 / ゲートウェイ（外部）。
+- (2) 符号: 100=センサ端末、10=検出部、11=温度センサ、12=加速度センサ、20=処理部、21=取得部、22=判定部、30=通信部、200=ゲートウェイ。
+- (3) 包含: 端末は検出部・処理部・通信部を備える（`100 : 10 20 30`）。検出部は 2 センサを有する（`10 : 11 12`）。処理部は取得部・判定部を有する（`20 : 21 22`）。
+- (4) 接続: 検出部→処理部（センサ値）、処理部→通信部（送信データ）、通信部→ゲートウェイ（無線なので破線矢印 `.>`）。
+- (5)(6) ラベルを付け、包含があるので `#! kind: block`。
+
+```pdg
+#! kind: block
+100 = センサ端末 / sensor terminal
+10 = 検出部 / detector
+11 = 温度センサ / temperature sensor
+12 = 加速度センサ / acceleration sensor
+20 = 処理部 / processor
+21 = 取得部 / acquisition unit
+22 = 判定部 / determination unit
+30 = 通信部 / communication unit
+200 = ゲートウェイ / gateway
+100 : 10 20 30
+10 : 11 12
+20 : 21 22
+10 -> 20 : センサ値 / sensor value
+20 -> 30 : 送信データ / tx data
+30 .> 200 : 無線 / wireless
+```
+
+### 7.3 図種別の例
+
+#### ブロック図（基本）
+
+指示: 「制御装置が CPU、メモリ、I/O インターフェースを内蔵し、I/O インターフェースが外部機器へ信号を出力する。」
+
+```pdg
+#! kind: block
+10 = 制御装置 / control device
+11 = CPU
+12 = メモリ / memory
+13 = "I/O インターフェース" / "I/O interface"
+20 = 外部機器 / external device
+10 : 11 12 13
+13 -> 20 : 信号 / signal
+```
+
+#### ブロック図（階層 + 外部機器、有線・無線）
+
+指示: 「システム本体は制御部（CPU・メモリ）と通信部（無線部・有線部）を備える。無線部は外部端末と無線で、有線部は外部サーバと有線でつながり、外部サーバと外部端末は相互通信する。」
+
+考え方: 多段の包含。`<->` を含むが、包含 `:` があるため必ずブロック図になる（`:` が最優先）。
+
+```pdg
+#! kind: block
+100 = システム本体 / Main system
+10 = 制御部 / Control
+20 = 通信部 / Comm
+11 = CPU
+12 = メモリ / memory
+21 = 無線部 / wireless
+22 = 有線部 / wired
+30 = 外部サーバ / external server
+40 = 外部端末 / external terminal
+100 : 10 20
+10 : 11 12
+20 : 21 22
+21 .> 40 : 無線 / wireless
+22 -> 30 : 有線 / wired
+30 <-> 40 : 通信 / comm
+```
+
+#### ブロック図（制御ループ / フィードバック）
+
+指示: 「制御システムは制御部・駆動部・センサ部・対象装置を備える。制御部が駆動部へ指令を出し、駆動部が対象装置を駆動し、センサ部が対象装置の状態を検出して制御部へ測定値を戻す。」
+
+考え方: フィードバックの戻り線は破線矢印 `.>` にすると読みやすい。
+
+```pdg
+#! kind: block
+100 = 制御システム / control system
+10 = 制御部 / controller
+20 = 駆動部 / driver
+30 = センサ部 / sensor unit
+40 = 対象装置 / controlled object
+100 : 10 20 30 40
+10 -> 20 : 指令 / command
+20 -> 40 : 駆動 / drive
+40 .> 30 : 状態 / state
+30 -> 10 : 測定値 / measured value
+```
+
+#### フローチャート（条件分岐）
+
+指示: 「開始後に条件 A を判定し、真なら処理 X、偽なら処理 Y を行い、いずれも終了へ進む。」
+
+考え方: 包含を使わず片方向でつなぐ。条件は末尾 `?` で菱形。分岐に Yes / No ラベル。
+
+```pdg
+#! kind: flow
+S100 = 開始 / Start
+S110 = 条件A? / "Condition A?"
+S120 = 処理X / Process X
+S130 = 処理Y / Process Y
+S140 = 終了 / End
+S100 -> S110
+S110 -> S120 : Yes
+S110 -> S130 : No
+S120 -> S140
+S130 -> S140
+```
+
+#### フローチャート（並列 / フォーク・ジョイン）
+
+指示: 「開始後に分岐し、経路 A と経路 B を並行して行い、合流してから終了する。」
+
+```pdg
+#! kind: flow
+S100 = 開始 / Start
+S110 = 分岐 / Branch
+S120 = 経路A / Path A
+S130 = 経路B / Path B
+S140 = 合流 / Join
+S150 = 終了 / End
+S100 -> S110
+S110 -> S120
+S110 -> S130
+S120 -> S140
+S130 -> S140
+S140 -> S150
+```
+
+#### フローチャート（リトライのループ）
+
+指示: 「試行して成功かを判定する。成功なら完了。失敗なら待機してから再試行する。」
+
+考え方: ループがあるが、末尾 `?` があるためフローチャートになる（`?` は往復判定より優先）。
+
+```pdg
+#! kind: flow
+S100 = 開始 / Start
+S110 = 試行 / Attempt
+S120 = 成功? / "Success?"
+S130 = 完了 / Done
+S140 = 待機 / Wait
+S100 -> S110
+S110 -> S120
+S120 -> S130 : Yes
+S120 -> S140 : No
+S140 -> S110
+```
+
+#### 状態遷移図（基本）
+
+指示: 「待機から起動で動作中になり、停止で待機へ戻る。動作中に異常が起きるとエラーになり、リセットで待機へ戻る。」
+
+考え方: 初期は `*`。各遷移にきっかけをラベルで。
+
+```pdg
+#! kind: state
+S1 = 待機 / Idle
+S2 = 動作中 / Running
+S3 = エラー / Error
+* -> S1
+S1 -> S2 : 起動 / start
+S2 -> S1 : 停止 / stop
+S2 -> S3 : 異常 / fault
+S3 -> S1 : リセット / reset
+```
+
+#### 状態遷移図（初期と終端）
+
+指示: 「待機で受信すると処理中になり、完了で待機へ戻る。処理中に異常終了すると終了状態になる。」
+
+考え方: 初期も終端も `*` で表す（`* -> S1` が初期、`S2 -> *` が終端）。
+
+```pdg
+#! kind: state
+S1 = 待機 / Idle
+S2 = 処理中 / Processing
+* -> S1
+S1 -> S2 : 受信 / receive
+S2 -> S1 : 完了 / done
+S2 -> * : 異常終了 / abort
+```
+
+#### シーケンス図（基本）
+
+指示: 「クライアントがサーバへ認証要求を送り、サーバがトークンを返す。続いてリソース要求と応答を行う。」
+
+考え方: 主体間のやりとり。往復するので seq になる。行の順序がそのまま時系列。
+
+```pdg
+#! kind: seq
+100 = クライアント / client
+200 = サーバ / server
+100 -> 200 : 認証要求 / auth request
+200 -> 100 : トークン / token
+100 -> 200 : リソース要求 / resource request
+200 -> 100 : リソース応答 / resource response
+```
+
+#### シーケンス図（双方向通信）
+
+指示: 「端末がサーバへ接続要求し、サーバが応答する。確立後にデータを双方向でやりとりし、最後に端末が切断する。」
+
+考え方: 双方向のやりとりは `<->`。`<->` があれば seq になる。
+
+```pdg
+#! kind: seq
+100 = 端末 / terminal
+200 = サーバ / server
+100 -> 200 : 接続要求 / connect
+200 -> 100 : 応答 / response
+100 <-> 200 : データ通信 / data exchange
+100 -> 200 : 切断 / disconnect
+```
+
+### 7.4 クレーム文からの変換
+
+#### 装置クレーム → ブロック図
+
+「〜と、〜と、〜と、を備える（有する／含む）装置」という文は、装置を親、各構成要素を子とするブロック図になる。
+
+指示: 「撮像部と、前記撮像部が取得した画像を処理する画像処理部と、処理結果を表示する表示部と、を備える撮像装置。」
+
+考え方: 撮像装置=10 が撮像部=11・画像処理部=12・表示部=13 を備える。「前記撮像部が取得した画像を処理する」→ 11 から 12 へ画像。「処理結果を表示する」→ 12 から 13 へ処理結果。
+
+```pdg
+#! kind: block
+10 = 撮像装置 / imaging device
+11 = 撮像部 / imaging unit
+12 = 画像処理部 / image processor
+13 = 表示部 / display unit
+10 : 11 12 13
+11 -> 12 : 画像 / image
+12 -> 13 : 処理結果 / result
+```
+
+#### 方法クレーム → フローチャート
+
+「〜するステップと、〜するステップと、…を含む方法」という文は、各ステップを順につないだフローチャートになる。判定のステップは末尾 `?` で菱形にする。
+
+指示: 「画像を取得するステップと、前記画像から特徴量を抽出するステップと、欠陥の有無を判定するステップと、欠陥が有る場合に警告を出力するステップと、を含む検査方法。」
+
+考え方: 取得=S100、抽出=S110、欠陥あり?=S120（判定→菱形）、警告=S130、終了=S140。判定で Yes/No に分岐。
+
+```pdg
+#! kind: flow
+S100 = 画像を取得 / Acquire image
+S110 = 特徴量を抽出 / Extract features
+S120 = 欠陥あり? / "Defect?"
+S130 = 警告を出力 / Output alert
+S140 = 終了 / End
+S100 -> S110
+S110 -> S120
+S120 -> S130 : Yes
+S120 -> S140 : No
+S130 -> S140
+```
+
+---
+
+## 8. 出力前の自己点検
+
+出力する前に、次をすべて確認する。
+
+- 1 行目が `#! kind: ...` で、宣言した図種が実際の構造と一致している。
+- 接続演算子の前後に半角スペースがある。連鎖記法（1 行に複数の接続）を使っていない。
+- 図に登場する符号をすべて定義した（暗黙ノードが意図的でない）。
+- 狙った図種以外の目印（`:` `?` `*` `<->`）を誤って入れていない。
+- ラベルの予約記号は必要に応じて `"..."` で囲んだ。
+- 1 ファイルに 1 つの図だけを書いている。
+
+---
+
+## 9. よくある誤りと修正
+
+| 誤り | 直し方 |
+|---|---|
+| `A -> B -> C` と 1 行に複数接続 | `A -> B` と `B -> C` に分ける |
+| `11-12`（スペースなし） | `11 - 12` にする |
+| フローチャートにしたいのに `:` を書いた | 包含 `:` を消す（`:` があると必ずブロック図になる） |
+| 菱形にしたいのに長方形になる | ラベル末尾を `?` にし、そのノードを接続に登場させる。図がブロック図になっていないか確認 |
+| 同じ符号を 2 回定義（警告） | 重複定義を 1 つにまとめる |
+| 宣言した図種と推論が不一致 | 目印（`:` / 末尾 `?` / `*` / 往復・`<->`）を見直すか、宣言を修正 |
+
+---
+
+## 10. 図種別テンプレート
+
+必要に応じてコピーして書き換える。
+
+ブロック図:
+
+```pdg
+#! kind: block
+100 = システム / System
+10 = サブシステムA / Subsystem A
+20 = サブシステムB / Subsystem B
+100 : 10 20
+10 -> 20 : データ / data
+```
+
+フローチャート:
+
+```pdg
+#! kind: flow
+S100 = 開始 / Start
+S110 = 処理 / Process
+S120 = 終了 / End
+S100 -> S110
+S110 -> S120
+```
+
+状態遷移図:
+
+```pdg
+#! kind: state
+S1 = 状態1 / State 1
+S2 = 状態2 / State 2
+* -> S1
+S1 -> S2 : 遷移 / transition
+S2 -> S1 : 復帰 / return
+```
+
+シーケンス図:
+
+```pdg
+#! kind: seq
+100 = 主体A / Actor A
+200 = 主体B / Actor B
+100 -> 200 : 要求 / request
+200 -> 100 : 応答 / response
+```
+
+---
+
+## 11. 出力フォーマットの指定(レンダリングも行う場合)
+
+`.pdg` を書くだけでなく、あなた自身が pdgkit で描画まで行う環境(コードを実行できるチャットやエージェント)では、利用者の自然文の指定を次のコマンド/オプションに対応させる。指定が無ければ SVG を既定とする。描画の前に必ず検証(`pdgkit validate` / `validate()`)を通す。
+
+| 利用者の言い方(例) | CLI | ライブラリ |
+|---|---|---|
+| SVG で / ベクタで | `pdgkit render fig.pdg -o fig.svg` | `renderToSvg(src)` |
+| PNG で / 画像で | `pdgkit render fig.pdg --to png -o fig.png` | `renderToPng(src)` |
+| JPEG で | `pdgkit render fig.pdg --to jpeg -o fig.jpg` | `renderToJpeg(src)` |
+| PDF で / 出願用に | `pdgkit render fig.pdg --to pdf -o fig.pdf` | `renderToPdf(src)` |
+| PowerPoint で / PPTX で / スライドに | `pdgkit render fig.pdg --to pptx -o fig.pptx` | `renderToPptx(src)` |
+| 編集できる PPTX で / 図形として編集できるように | `pdgkit render fig.pdg --to pptx --editable -o fig.pptx` | `renderToPptx(src, { editable: true })` |
+| 符号表(符号の説明)も | `pdgkit refs fig.pdg --format md`(または `csv`) | `refsToMarkdown(parse(src))` |
+
+言語の指定は上記に足す: 日英併記なら `--lang both`(`{ lang: 'both' }`)、英語なら `--lang en`(`{ lang: 'en' }`)。既定は日本語。
+
+例: 「この図を編集できる PPTX にして」→ `.pdg` を書いて `pdgkit validate` を通したうえで、`pdgkit render fig.pdg --to pptx --editable -o fig.pptx` を実行する。
+
+---
+
+PatentDSL / pdgkit — Copyright (c) 2026 しばやま, MIT License.