Data & penyimpanan

Di mana sesuatu berada, siapa yang dapat membaca apa, dan aturan yang diikuti agen sehingga halaman yang menghadap pelanggan tidak akan secara tidak sengaja melihat data internal.

Tiga tempat di mana sesuatu berada

1. Ruang kerja Anda (~/workspace/)

Sistem file tempat agen berjalan. Draf markdown, aset yang dihasilkan, Skills kustom, pekerjaan, ruang sementara, dan dokumen ini semuanya berada di sini.

• Pemilik: pengguna Linux agent (agen itu sendiri).
• Dapat diakses dari chat. TIDAK dapat diakses dari proses Console atau proses situs publik.
• Dua jalur konvensional:
• ~/workspace/uploads/: file yang Anda tempelkan ke chat akan berada di sini.
• ~/workspace/downloads/: file yang didaftarkan agen untuk diunduh melalui UI workspace. Disajikan oleh nginx di URL yang terjaga.

2. PostgreSQL (tiga database)

State persisten untuk apa pun yang terstruktur. Jangan pernah SQLite, jangan pernah JSON-on-disk untuk state aplikasi.

What goes where:

• console_db: state khusus internal. Daftar pelanggan, tahap deal, tabel penilaian internal, log audit. Situs publik tidak dapat mengaksesnya; REVOKE diterapkan pada lapisan peran database, bukan hanya konvensi.
• site_db: konten yang dirender oleh situs publik. Laporan yang telah dihitung sebelumnya, halaman dokumentasi, apa pun yang seharusnya murah untuk dibaca saat rendering halaman. Console menulis di sini, situs membaca.
• console_site_db: saluran lintas permukaan yang eksplisit. Console menulis antrian moderasi; situs merender entri yang disetujui; situs menulis kembali sinyal interaksi; Console membacanya.

3. Memori dan progres

Dua file khusus di ruang kerja Anda:

• ~/workspace/.memory.md: read at the start of every chat. Use "remember this: X" to append.
• ~/workspace/progress.md: change log. The agent appends after meaningful changes; you can read it to reconstruct what happened.

Ini adalah markdown dengan sengaja: Anda dapat melakukan grep pada mereka, membuat versinya, mengeditnya secara manual, dan melakukan grep lagi.

Mengapa tiga database alih-alih satu

Dua alasan.

1. Pemisahan permukaan. Pengunjung situs publik secara teoritis dapat menemukan cara untuk melakukan kueri peran database yang digunakan situs untuk autentikasi. Jika peran tersebut hanya memiliki akses ke site_db, radius ledakan dari kebocoran apa pun terbatas pada data yang sudah Anda putuskan untuk dipublikasikan.
2. Kejelasan maksud. Ketika agen menulis aplikasi Console, ia tahu untuk menggunakan console_db. Ketika menulis halaman situs, site_db. Ketika membangun alur kerja lintas permukaan, console_site_db. Tidak ada pertanyaan yang tidak disengaja seperti "apakah tabel ini harus dipublikasikan?"

Agen tidak mencoba membengkokkan aturan ini. Jika Anda meminta "expose this Console page publicly," agen akan memberi tahu Anda bahwa ia perlu memindahkan data melalui console_site_db dan membangun kembali jalur baca di situs, daripada mengakses console_db dari situs.

Bekerja dengan database

Polanya, setiap kali:

• Sesi SQLAlchemy diimpor dari src/db.py (modul bersama per-aplikasi).
• Model Pydantic menjaga setiap input dan setiap batas API.
• psycopg2 mentah hanya ketika SQLAlchemy berlebihan (pencarian read-only yang dijaga token, skrip sederhana).

Anda akan melihat pernyataan CREATE TABLE IF NOT EXISTS di bagian atas aplikasi baru. Agen memperlakukan skema sebagai kode: setiap aplikasi mendeklarasikan tabelnya sendiri. Tidak ada sistem migrasi platform; kolom baru ditambahkan dengan ALTER TABLE dan agen mencatat perubahannya.

Bagaimana dengan ClickHouse

ClickHouse tersedia secara lokal untuk beban kerja analitik di mana PostgreSQL akan lambat: rollup time-series pada jutaan baris, agregasi kolumnar, dan sejenisnya. Agen membaca skill ClickHouse sebelum menggunakannya, memilihnya dengan sengaja, dan memberi tahu Anda alasannya. Default tetap PostgreSQL.

Di mana hal-hal TIDAK berada

• Tidak ada penyimpanan objek yang dikelola platform. Jika Anda ingin menyimpan PDF 50 MB atau video, simpan sebagai file di ~/workspace/downloads/ (dibatasi oleh nginx) atau sebagai kolom BYTEA di Postgres (baik untuk artefak kecil).
• Tidak ada variabel lingkungan untuk rahasia. Kredensial disimpan di penyimpanan rahasia yang diketik, terbatas pada permukaan dan konektor. Agen tidak pernah menyalinnya ke dalam file atau kolom database.
• Tidak ada halaman "pengaturan platform" selain yang ditampilkan UI ruang kerja. Jadwal, mode, persetujuan semuanya adalah tombol eksplisit.

Siklus hidup data

• File yang Anda buat akan tetap ada hingga Anda menghapusnya. Agen tidak membersihkan ruang kerja Anda secara otomatis.
• Baris database akan tetap ada hingga Anda (atau pekerjaan pembersihan eksplisit) menghapusnya. Agen menulis pekerjaan pembersihan saat Anda meminta: "hapus baris vsg_runs yang lebih lama dari 90 hari setiap hari Minggu."
• File memori dan progres bertambah seiring waktu. Agen terkadang menyarankan pemangkasan ketika memori menjadi berisik.
• Log audit konektor disimpan oleh platform; Anda dapat menelusurinya tetapi tidak dapat menghapusnya.

Di balik layar. Setiap peran Postgres melakukan autentikasi melalui autentikasi peer Unix-socket (pengguna OS cocok dengan nama peran). Tidak ada kata sandi yang bisa bocor, tidak ada string koneksi yang salah dikonfigurasi. Grant dan REVOKE bersifat eksplisit dan terlihat. Database system_db ada untuk keperluan internal platform (api-proxy, layanan konektor, bridge); tidak ada permukaan yang pernah terhubung ke database tersebut.