Skip to content

DEVELOPING.md

Latest commit

 

History

History
58 lines (46 loc) · 3.27 KB

DEVELOPING.md

File metadata and controls

58 lines (46 loc) · 3.27 KB
Raw

Developing — house rules

Notes to future‑me (and anyone building on this): how this repo stays publishable without leaking anything, and how to add to it safely.

One repo, kept safe by .gitignore

This is a single working copy (~/Projects/StackChan-LocalAI) that you develop in and push to GitHub. There is no separate "public" clone — the .gitignore alone keeps secrets out of git, so every commit is publish‑safe by construction.

The real data/.config.yaml, the ASR model, and the flash/NVS backups live in this folder but are git‑ignored — they exist on disk, never in a commit, and therefore in no branch. .gitignore is the authoritative list of what stays private.

The one rule that keeps it safe

Real values live ONLY in git‑ignored files. Every tracked file uses placeholders.

So anything committed is publish‑safe by construction — no per‑commit scrubbing needed. Placeholders in use: LOCAL_AI_IP, DEVICE_IP, DEVICE_MAC, YOUR_VLLM_API_KEY, <your-wifi>, ~ / $HOME. (local-ai / LOCAL_AI_IP are stand-ins for the machine that runs the server — replace them with your own host name and LAN IP.)

Private (git‑ignored) vs its public skeleton

A skeleton is a committed (public) file that carries placeholders instead of real values — you copy it and fill it in locally. The real, filled‑in file is git‑ignored.

Private — local only, real values Public skeleton — committed, placeholders
xiaozhi-server/data/.config.yaml (real LOCAL_AI_IP / API key) data/.config.yaml.example (LOCAL_AI_IP, YOUR_VLLM_API_KEY) → cp it and fill in
xiaozhi-server/models/SenseVoiceSmall/* (ASR model binary) models/SenseVoiceSmall/README.md (can't placeholder a binary → download instructions)
backup/*.bin, device-nvs/*.bin (embed Wi‑Fi creds) the dir README.md + scripts (generate your own)

New secrets → keep the real value in a git‑ignored file and commit a placeholder skeleton next to it.

Adding something new (checklist)

  1. Does the new file contain a real IP / key / MAC / SSID / password, or a large binary?
    • Yes → git‑ignore it and commit a sanitized *.example (or a download‑README) skeleton instead.
    • No → commit normally.
  2. Never hard‑code a real value into a tracked doc/config/script — it would ship to GitHub on push.
  3. Before committing, run ./check.sh (emotion↔firmware contract, CJK strip, config sanity, backup + patch fidelity).

Publish workflow

cd ~/Projects/StackChan-LocalAI
git add -A && git commit -m "…"
git push origin master

Set origin to your GitHub URL once: git remote add origin git@github.com:<you>/StackChan-LocalAI.git.

Firmware

The firmware source lives outside the repo at ~/stackchan-fw/StackChan (ESP‑IDF 5.5.4); this repo carries only firmware-mod/*.patch. After editing the source: regenerate the patch, then run firmware-mod/verify-patches.sh (it reverse‑applies each patch to catch drift). Build/flash with firmware-mod/build-and-flash.sh [--flash].

Reversibility

The device is fully restorable — full 16 MB flash backup + original NVS (both local‑only). Restore commands are in backup/README.md and device-nvs/README.md. Always keep those local .bins.