アプリを作る
マニフェストを書く
定義をマニフェスト（YAML）で書くときの共通の形、定義の種類、ファイルの置き方、検証、CEL の式を説明します。
このページでは、Hane の定義をマニフェストとして書く方法を説明します。マニフェストは Git に置く YAML で、hanectl で apply すると draft になり、ReleaseBundle を有効にしたときに効きます。定義そのものの考え方は 定義とリリース にあります。
すべてのマニフェストは、apiVersion・kind・metadata・spec の 4 つを持ちます。
apiVersion: data/v1alpha1 # 書式のバージョン（<群>/v1alpha1）kind: Rule # 定義の種類metadata: name: lease-end-date # 英小文字・数字・ハイフン。63 文字まで annotations: description: 開始日と契約月数から満了日を計算するspec: target: LeaseContract field: end_date inputs: [start_date, term_months] expr: addDays(addMonths(record.start_date, record.term_months), -1)statusと定義のバージョンはファイルに書きません。Hane が apply のたびに付けます。specは種類ごとに JSON Schema で決まっていて、知らないキーは受け付けません。- 1 つのファイルに
---で区切って複数のマニフェストを書けます。
| apiVersion | kind | 中身 |
|---|---|---|
data/v1alpha1 |
Schema・Ontology・Rule・Calculation・Migration・Axiom・Aspect |
型と項目、関係、計算の規則と計算の定義、項目の名前や型の変更、業務の知識と観点 |
workflows/v1alpha1 |
Workflow・Schedule |
案件の進め方と、毎日の発火 |
approvals/v1alpha1 |
AssignmentRule・DeciderPolicy |
Task の割り当てと、外への操作を誰が決めるか |
agents/v1alpha1 |
Agent・EvalSuite・TriageRule |
Agent、評価、洗い出しの規則 |
documents/v1alpha1 |
DocumentType・ExtractionSchema・DocumentSource |
書類の種類、抽出の定義、外部の保管場所 |
communication/v1alpha1 |
SenderIdentity・ContactPolicy・ContactRetention・CallBriefTemplate |
送信の名義、連絡の規則、連絡先の保持、確認事項のひな形 |
integrations/v1alpha1 |
Connection |
外部のシステムとの接続 |
gateway/v1alpha1 |
Route・PublishedApi・ToolExposure・Consumer |
顧客の API への経路と、Agent のツールにする設定 |
browser/v1alpha1 |
BrowserFlow |
ポータルを操作する手順 |
platform/v1alpha1 |
Budget・RoleBinding・GitSource |
予算、ロールの割り当て、Git からの同期 |
release/v1alpha1 |
EnvironmentBinding・SourcePolicy |
環境ごとに違う名前、出どころの決まり |
factory/v1alpha1 |
Application |
Hane が配信するアプリ |
すぐ効く設定
Section titled “すぐ効く設定”次の種類は ReleaseBundle に束ねず、環境ごとに apply した時点で効く設定です。Consumer・ContactRetention・DocumentSource・EnvironmentBinding・GitSource・RoleBinding・SenderIdentity・SourcePolicy。それ以外は draft になり、ReleaseBundle を有効にするまで効きません。hanectl は apply の後に、どちらだったかを表示します。
ファイルの置き方
Section titled “ファイルの置き方”種類ごとにディレクトリを分け、bundle.yaml に ReleaseBundle に束ねる範囲を書きます。Bundle は hanectl だけが読むファイルで、Hane には送りません。
ディレクトリdefinitions/
- bundle.yaml
ディレクトリschemas/
- vehicle.yaml
- lease-contract.yaml
ディレクトリrules/
- …
ディレクトリworkflows/
- …
ディレクトリschedules/
- …
ディレクトリpolicies/
- …
ディレクトリagents/
- …
ディレクトリsenders/ 束ねない設定。bundle.yaml の resources に入れない
- …
apiVersion: release/v1alpha1kind: Bundlemetadata: name: vehicle-leasespec: resources: - schemas/ - rules/ - workflows/ - schedules/ - policies/ - agents/新しい種類のディレクトリを足したら、resources にも足します。足し忘れると、apply はできても ReleaseBundle に入らず、有効になりません。
| いつ | どこで | 確かめること |
|---|---|---|
hanectl validate -f <dir> |
手元 | 形（JSON Schema）、定義の間の参照、CEL の式。秘密値の名前や言葉の衝突は警告で出す |
hanectl diff -f <dir> |
Hane | apply で何が変わるか。AI に任せる範囲を広げる変更などに印を付ける |
hanectl apply -f <dir> |
Hane | 同じ検査をサーバーでも行い、通ったら draft にする |
| ReleaseBundle の有効化 | Hane | 環境ごとの名前（EnvironmentBinding）が解けるか、stage と prod では評価（EvalSuite）が通っているか |
手元の検証は Hane と同じ検査の部品を使うので、CI で hanectl validate を流すと、apply の前に誤りに気づけます。
CEL の式
Section titled “CEL の式”条件や計算の式は CEL で書きます。式は 1,000 文字までで、今の時刻・乱数・外部の読み書きは使えません。同じ入力からはいつも同じ値になります。
| 書く場所 | 使える変数 |
|---|---|
Rule の expr |
record（入力の項目だけ） |
Schedule の forEach.where |
record・states・event（event.date は発火した日） |
Workflow の式（題名・分岐・期限など） |
subject・states・case・steps・input |
GET /v1/data/records の where |
record・states |
暦の日付は YYYY-MM-DD の文字列で持ち、次の関数で計算します。
| 関数 | 中身 |
|---|---|
addDays(date, n)・addMonths(date, n) |
日数・月数を足した日付 |
daysBetween(a, b) |
2 つの日付の間の日数 |
isDate(v) |
日付の文字列か |
zonedDate(time, zone) |
記録した時刻を、タイムゾーンの暦の日付にする |
minOf(a, b) |
小さいほう |
moneyText(m) |
金額を通貨の桁数で文にする |
# 申入れの期限が 90 日以内の有効な契約に、毎朝案件を作るapiVersion: workflows/v1alpha1kind: Schedulemetadata: name: daily-expiry-scanspec: every: day at: "07:00" timezone: Asia/Tokyo forEach: type: LeaseContract where: record.status == "active" && record.notice_due != null && daysBetween(event.date, record.notice_due) <= 90 workflow: lease-expirystates は項目ごとの値の状態（confirmed・estimated・pending_inquiry・unknown）です。確定でない値で先へ進めないようにするには、states.end_date != "confirmed" のように分岐します。