# d6e 設計思想

English version: [design-philosophy.md](./design-philosophy.md)

このドキュメントは d6e の設計原則を説明します。対象読者は「システムのどこまでを
d6e に依存させ、どこからは依存させないか」を判断する開発者・アーキテクトです。
ここに書かれている内容はすべて実装済みの事実であり、将来の構想ではありません。

## d6e とは何か

d6e はセルフホスト可能な AI ワークプラットフォームです。**インスタンス**を
自社環境（オンプレミスまたはプライベートクラウド）にデプロイし、その中で
**ワークスペース**をホストします。ワークスペースには、AI エージェントが実務を
こなすために必要なものが束ねられています。

- PostgreSQL ベースのワークスペースデータベース
- ファイルストレージ（アップロード、生成レポート、Google Drive 同期）
- STF（State Transition Function — ビジネスロジック）
- ワークフローとスケジュール
- SaaS 認証情報（freee、Money Forward、Google Workspace、Salesforce、
  Notion、Box、GitHub、Chatwork、Zendesk など）
- 上記すべてを AI エージェントが操作するチャットコンソール

中央アカウントサイト（https://www.d6e.ai）が扱うのはアカウント・ログイン・
OAuth クライアント登録のみです。データはあなたのインスタンスの中にあります。

## 背景: なぜ疎結合であるべきか

ファットなフレームワークは、最初は速く、後で高くつきます。機能がフレームワーク
と密結合していると、フレームワークの差し替えはその上に築いたすべてに対する
破壊的変更になります。フレームワークが技術負債に変わるのはこの構造のためです。

AI 支援開発はこのトレードオフを変えました。速く作るためにファットなフレーム
ワークに頼る必要はもうなく、疎結合なプラットフォームと標準的な部品の組み合わせ
でも十分に速く、しかも選択肢を残せます。d6e は既存システムと疎結合であり続ける
ように設計されています。あなたの業務をホストするものであって、あなたのシステム
を飲み込むものではありません。

以下の原則は、この意図を具体化したものです。

## 原則 1: データと AI は自社環境に

インスタンス（API、データベース、ファイルストレージ、エージェント実行環境）は
あなたが管理するインフラ上で動きます。ワークスペースのデータが d6e 運営側の
サーバーに送られることはありません。中央サイトはワークスペースの中身に一切
触れず、認証の仲介だけを行います。

## 原則 2: すべてが公開 API

API の面はただ一つです。d6e コンソール（組み込みの Web UI)は、API キーで
呼び出せるものと同じ公開 REST API（`/api/v1/*`）のクライアントとして動いて
います。インスタンスの MCP サーバーは、組み込みチャットエージェントが使う
ものと同じツール群 — SQL、ファイル、Drive、SaaS 呼び出し、STF 実行、
ワークフロー管理をカバーする約 90 個の `d6e_*` ツール — を公開しています。

実務上の帰結:

- コンソールでできることは、スクリプト・バックエンド・カスタムフロントエンド
  からもすべてできます。
- 手元の AI コーディングエージェント（Codex CLI、Claude Code、Cursor など）を
  インスタンスの MCP サーバーに接続すれば、ホストされたエージェントと
  ツール単位で同等の環境で、実ワークスペースに対して開発できます。専用 SDK の
  学習は不要です。
- カスタムフロントエンドは普通の Web アプリです。標準的な OAuth2
  （認可コードフロー）でユーザーを認証し、インスタンスの API を呼び出します。
  d6e の「中に」作るものではありません。

## 原則 3: 資産は可搬に、結合は疎に

d6e の上で作るものは、d6e の外でも生き残る形式に意図的に揃えてあります。

| 資産 | 形式 | 可搬性 |
|---|---|---|
| JS STF | 素の JavaScript（`$input` を読み、JSON 化可能な値を `return`） | 純粋関数。d6e SDK も import も不要 |
| Docker STF | 任意のコンテナイメージ（stdin に JSON、stdout に `{"output": ...}`、エラーは stderr） | Docker が動く場所ならどこでも動く。d6e 非依存 |
| Effect | 宣言的な HTTP 呼び出し（URL、メソッド、ヘッダー/ボディ/クエリのマッピング） | 任意の HTTP クライアントで数分で書き直せる |
| プロンプト | Markdown | コピー&ペーストで移動可能 |
| ワークスペース DB | 素の PostgreSQL（`user_data` スキーマ） | 標準 SQL。標準ツールでダンプ・リストア可能 |
| ファイル | パス付きの通常ファイル | いつでもダウンロード・同期で持ち出せる |
| カスタムフロントエンド | 自分で所有・デプロイする独立 Web アプリ | 最初から d6e の外にある |
| Plugin | `template.yaml` + 上記ファイル一式（素の git リポジトリ） | 上記すべての人間可読な宣言 |

d6e 自身が提供するのは**糊**です: 認証、ワークスペースのメンバーシップ、
認証情報の保管、ポリシー適用、監査ログ、スケジューリング、オーケストレー
ション。仮に別のプラットフォームへ移行するとしたら書き直すのはこの糊であって、
ロジック・データ・プロンプトはそのまま持ち出せます。移行コストが糊の範囲に
収まるのは設計上の意図です。

## 原則 4: 段階的に採用できる

d6e はビッグバン導入を要求しません。典型的な経路は次の通りです。

1. **コンソールのみ** — インスタンスをデプロイし、データを入れ、チームが
   チャットで AI エージェントと働き始める。
2. **指示を固める** — 繰り返す手順は、その場のチャットからプロンプトファイル
   へ、`files:` 参照へ、再現性が重要なところは STF・ワークフローへと段階的に
   固めていく。
3. **Plugin としてパッケージ化** — `template.yaml` にプロンプト・ファイル・
   STF・Effect・ワークフローを束ね、他のワークスペース（他社）がワンクリック
   で同じ能力を導入できるようにする。
4. **カスタムフロントエンド** — 専用 UI に値する業務には、公開 API に対して
   普通の Web アプリを作る。ワークスペースは引き続き記録のシステムであり、
   フロントエンドはあなたのものです。

どのステップも任意です。どこで止めても、動くシステムが手元に残ります。

## 原則 5: ガバナンスは境界で

すべての利用者が同じ API を通るため、統制は一箇所で効きます。

- **テーブルポリシー（デフォルト拒否）** — ワークスペースのテーブルへの
  アクセスは、許可ポリシーに一致しない限り拒否されます。拒否ポリシーが先に
  評価されます。これはコンソール・エージェント・MCP クライアント・API キー
  呼び出しのすべてに等しく適用されます。
- **監査ログ** — ワークスペースの操作は記録され、後から確認できます。
- **使用状況分析** — トークン消費はモデル別・ユーザー別・リクエスト種別に
  追跡され、コストは驚きになる前に可視化されます。
- **認証情報の暗号化保管** — SaaS 認証情報と STF シークレットはサーバー側で
  暗号化して保管されます。STF シークレットは API 経由では書き込み専用
  （管理者のみ）で、コンテナ実行時に注入されます。エージェントや Plugin 作者は
  値ではなく名前（`__SECRET_REF_ONLY__`）で参照します。

## 依存の境界線

何をどちらに置くかの短い経験則です。

**d6e に置くもの: AI が操作する状態と、AI が使う認証情報。**

- エージェントが読み書きするワークスペーステーブル
- エージェントが生成・消費するファイル
- エージェントが代理操作する SaaS 接続
- そのデータのそばで再現性を持って動くべき STF・ワークフロー

**d6e の外に残すもの: すでに所有しているものすべて。**

- フロントエンド（フレームワーク・ホスティングは自由）
- バックエンド — API ルート、ワーカー、サーバー。d6e はサーバーサイド
  ロジックの移設を要求しません。有用なところでは自分のバックエンドから
  d6e の API を呼び、そうでないところでは自分のサービスを直接呼べば
  よいだけです。
- 外部データベース・既存の記録システム。ワークスペースの SQL 面
  （`d6e_sql`）は意図的にインスタンス自身の `user_data` スキーマに限定
  されており、d6e が知らないうちに本番データベースのクライアントになる
  ことはありません。エージェントが外部システムに触れる必要があるときは、
  明示的に行います: Docker STF（コンテナはネットワークアクセス付きで実行
  され、認証情報は STF シークレットから注入）または Effect です。境界を
  接続するのであって、データベースを移設するのではありません。

## 関連リソース

- フロントエンドとインスタンスの関係:
  https://github.com/d6e-ai/d6e-custom-frontend-skills/blob/main/docs/frontend-and-instance.ja.md
- ローカル AI エージェント開発ガイド:
  https://github.com/d6e-ai/d6e-plugin-skills/blob/main/docs/local-ai-development.ja.md
- Plugin 開発（template.yaml 仕様、スキル）:
  https://github.com/d6e-ai/d6e-plugin-skills
- Docker STF 開発:
  https://github.com/d6e-ai/d6e-docker-stf-skills
- カスタムフロントエンド開発:
  https://github.com/d6e-ai/d6e-custom-frontend-skills

---

最終更新: 2026-07