Repository Index

A complete map of the Familiars repository. Directory structure, key-file jump table, database migration list, Bridge route catalog, and environment variable reference. Sources: actual repository structure + CLAUDE.md + ARCHITECTURE.md.

---

1 · Project Positioning

Familiars is a Windows-first multi-agent AI desktop application:

• Frontend: Electron + Vue 3 (electron/)
• Backend: Single-process FastAPI bridge, default 127.0.0.1:18711 (src/bridge/)
• Local small models: QLoRA rewriter / decider / memorizer writer
• Tool system: 15 default tool instances + approval gate + sensitive information detection
• Memory: Dialogue tree + scope×category 25-cell long-term memory
• Digital human: GPT-SoVITS + multi-backend rendering
• Social listeners: WeChat / QQ / Feishu
• Broker ecosystem: Installable app packages + marketplace

---

2 · Top-Level Directory Structure

familiars/
├── src/                       # Backend Python source
├── electron/                  # Electron frontend
│   ├── electron/              # Main process (main.js, python.js)
│   └── renderer/              # Vue 3 renderer process
├── workspace/                 # Runtime data (database, secrets, agent profiles)
├── test/                      # pytest tests
├── models/                    # Local model weights (not in git)
├── deploy/relay/              # Standalone relay deployment (Docker + Caddy)
├── docs/                      # Documentation source files
├── website/                   # Documentation site (VitePress)
├── scripts/                   # Helper scripts
├── external/                  # External tools (gitleaks, etc.)
├── agent_recipes/             # Recipe definitions
├── runs/                      # Training run artifacts
├── training/                  # Training scripts
├── pipeline/                  # Training pipeline
├── dataset/                   # Datasets
├── frames/                    # Digital human frame artifacts
├── assets/                    # Static assets
├── deliverables/              # Deliverables
├── packages/                  # Packaging artifacts
├── .claude/                   # Claude Code config (hooks, settings)
├── CLAUDE.md                  # Team standards & Claude Code instructions
├── ARCHITECTURE.md            # Architecture documentation
├── OPERATION.md               # User operation manual
├── SECURITY.md                # Security notes (user-level)
├── REPOSITORY.md              # Repository index (agent knowledge-base version)
├── CLI.md                     # CLI reference
├── BROKER_DEVELOPMENT.md      # Broker development guide
├── main.py                    # Bridge CLI entry point
├── requirements.txt           # Python dependencies
└── .env                       # Environment variables (not in git)

---

3 · src/ Subdirectory Structure

src/
├── api/                       # FastAPI endpoints (legacy, partially superseded by bridge/routes)
├── base/                      # Infrastructure
│   ├── auth/                  # Device authentication (device.py, manager.py, models.py)
│   ├── config.py              # pydantic-settings config aggregate
│   ├── crypto.py              # HKDF + Fernet encryption
│   ├── bridge_token.py        # Bridge token generation/validation
│   ├── gpu_tier.py            # GPU tier classification
│   ├── vram_gate.py           # VRAM admission gate
│   ├── load_policy.py         # Model loading policy
│   ├── model_choices.py       # Model selection UI logic
│   ├── model_load_lock.py     # Model loading lock
│   ├── paths_align.py         # Path drift auto-alignment
│   ├── signals.py             # Signal mechanism
│   ├── quick_inputs.py        # Quick inputs
│   ├── runtime_mode.py        # intense_mode / recipe_task_mode context
│   ├── agent_settings.py      # Agent config loading
│   ├── user_profile.py        # User profile
│   ├── filelock.py            # File lock
│   └── subprocess_utils.py    # Subprocess utilities (no_window_kwargs)
├── bridge/                    # FastAPI bridge
│   ├── app.py                 # Application entry + startup side-effects
│   ├── run.py                 # hypercorn/uvicorn launcher
│   ├── deps.py                # DI container
│   ├── certs.py               # Self-signed certificate generation
│   ├── safe_files.py          # Safe file operations
│   └── routes/                # Route files (see §7)
├── broker/                    # Broker exchange layer
│   ├── hub.py                 # Identity + transport + match engine + rate limiter
│   └── workshop/              # Installable app packages (rooms + threads + reputation + triggers)
├── decider/                   # Proactive decision module
├── digital_human/             # Digital human rendering
│   ├── backends/              # Rendering backends (anime_dynamic, anime_morph, anime_pretrained)
│   ├── library.py             # Digital human asset library
│   └── utils/                 # Utilities (timing, text_norm)
├── flow/                      # Flow execution engine
│   ├── engine.py              # FlowEngine (owner-thread + per-role worker-thread)
│   ├── resume.py              # Rehydrate from DB (pinned template + mutation replay)
│   └── _builtin/              # Built-in flow templates (hello_world, etc.)
├── gift/                      # Gift system
│   ├── runner.py, planner.py, budget.py, shopper.py
│   ├── filter.py, calendar.py, video.py
├── models/                    # Core model layer
│   ├── assistant.py           # Assistant + AssistantManager
│   ├── conversation.py        # ConversationSession + DialogueManager + Dialogue
│   ├── transferer.py          # Cross-agent / cross-client / cross-model dispatch
│   ├── memorizer/             # Memory writer / reader / consolidator
│   ├── trainer/               # Training helpers
│   ├── router/                # Model routing
│   ├── clients/               # Tool clients (base, browser, multimodal, input, doc, daily, system, mini_model)
│   ├── log_pass.py            # Log processing pipeline
│   ├── RAG/                   # RAG components
│   │   ├── framework_docs.py  # Manager document index
│   │   ├── bridge_api_surface.py  # Bridge API catalog
│   │   ├── bridge_api_reflected.py # FastAPI reflection audit
│   │   └── chunk_store.py     # Chunk storage
├── observability/             # Observability
│   ├── audit.py               # Audit log
│   ├── agent_log.py           # Agent log
│   ├── logging.py             # Structured logging
│   └── status.py              # Status monitoring
├── pipeline/                  # Training / inference pipeline
│   ├── gpu_priority.py, soft_schema.py, multimodal_session.py
├── recipes/                   # Recipe system
│   ├── sandbox/               # Sandbox execution
│   ├── runtime.py             # Recipe runtime override
│   └── source_reader.py       # Source code reader
├── services/                  # Service layer
│   └── external_agents/       # External agent registration
├── skills/                    # Skill system
├── storage/                   # Storage layer
│   ├── db.py                  # SQLite WAL connection + migration runner
│   ├── files.py               # File storage
│   ├── locks.py               # Storage locks
│   ├── repos/                 # Data repositories (assistant_repo, skill_repo, todo_repo, ...)
│   └── migrations/            # Database migrations (v1–v50)
├── tools/                     # Tool system
│   ├── tool_dispatcher.py     # Tool name → callable table, instance registration
│   ├── security.py            # Risk levels + approval gate
│   ├── sensitive_detector.py  # Three-layer sensitive information detection
│   ├── turn_secrets.py        # Per-turn ciphertext replacement
│   └── ...                    # Other tool helpers
├── trainer/                   # Training context
└── utils/                     # Tool implementations
    ├── base_tools.py          # Core tools (read/write/exec/find/grep/download/compress/process/network)
    ├── browser_tools.py       # Chrome CDP automation
    ├── multimodal_tools.py    # VisionProcessor + operate()
    ├── memory_tools.py        # Node, DialogTree, Memorizer
    ├── memory_store.py        # Memory storage
    ├── daily_tools.py         # Daily tools
    ├── doc_tools.py           # Document tools
    ├── user_tools.py          # User tools
    ├── user_secret_tools.py   # User secret tools
    ├── phone_tools.py         # Phone tools
    ├── search_tools.py        # Search tools
    ├── search_sources_forger.py # Search source constructor
    ├── system_tools.py        # System tools
    ├── broker_tools.py        # Broker tools
    ├── registry_tools.py      # Registry tools
    ├── skill_watcher_tools.py # Skill watcher
    ├── framework_tools.py     # Framework docs + log tools (manager-only)
    ├── context_helpers.py     # ContextVar propagation helpers
    ├── json_parse.py          # Fault-tolerant JSON parsing
    ├── _explore_filter.py     # Exploration filter
    ├── autorun.py             # Auto-start on boot (Windows/macOS/Linux)
    ├── reminder_dispatch.py   # Reminder dispatch
    ├── video_adapters.py      # Video adapters
    ├── tool_source.py         # Tool source
    ├── monitor/               # Activity monitors
    └── daily_monitor/         # Daily monitors

---

4 · Key File Jump Table

4.1 Startup Chain

File	Responsibility
src/bridge/app.py	FastAPI mounting, CUDA pin, JIT model load, autorun, monitor rehydrate
src/bridge/run.py	hypercorn/uvicorn launcher
src/bridge/deps.py	DI container (AssistantManager, DialogueManager, CommHub, UsageTracker)
src/bridge/certs.py	Self-signed certificate generation
electron/electron/main.js	Electron main process; spawns Python bridge
electron/electron/python.js	Bridge lifecycle (BRIDGE_PORT=18711, health probe, fallback port)

4.2 Core Models

File	Responsibility
src/models/assistant.py	Assistant + AssistantManager: agent lifecycle, reports, persona evolution
src/models/conversation.py	ConversationSession + DialogueManager + Dialogue + RAG composition
src/models/transferer.py	Cross-agent / cross-client / cross-model dispatch (6-priority resolver)
src/models/clients/base_client.py	ToolClient base — tool loop, history pruning, schema normalization
src/models/memorizer/writer.py	MemoryWriter: memory writes + SECRET.json management
src/models/memorizer/reader.py	MemoryReader: memory reads + secrets recall
src/models/RAG/framework_docs.py	Manager document index (render_framework_index)
src/models/RAG/bridge_api_surface.py	Bridge API catalog injection

4.3 Tool System

File	Responsibility
src/tools/tool_dispatcher.py	Tool name → callable table, 15 default instance registrations
src/tools/security.py	Risk levels (TOOL_RISK) + approval gate (@requires_approval) + skill-scope authorization
src/tools/sensitive_detector.py	Three-layer sensitive information detection (gitleaks + presidio + mini-LLM [disabled]) + commit pipeline
src/tools/turn_secrets.py	Per-turn ciphertext→plaintext replacement (ENC:: prefix)
src/utils/base_tools.py	Core tool implementations (read/write/exec/find/grep/download/compress/process/network)
src/utils/browser_tools.py	Chrome CDP automation, shared-profile, browser_open exploration cards
src/utils/multimodal_tools.py	VisionProcessor (OCR, screenshot grid, keyframes), operate() loop
src/utils/memory_tools.py	Node, DialogTree, Memorizer
src/utils/framework_tools.py	FrameworkDocsTools + LogTools (manager-only)

4.4 Security & Encryption

File	Responsibility
src/base/crypto.py	HKDF-SHA256 + Fernet encryption (encrypt_value / decrypt_value)
src/base/bridge_token.py	Bridge token generation (256-bit) + constant-time validation
src/base/auth/device.py	Device fingerprint generation (macOS/Windows/Linux)
src/base/auth/manager.py	AuthManager singleton (workspace/auth.json)
src/base/auth/models.py	UserIdentity + AuthState data classes

4.5 Storage

File	Responsibility
src/storage/db.py	SQLite WAL connection + migration runner; FAMILIARS_DB_PATH
src/storage/files.py	File storage
src/storage/repos/	Data repositories (assistant, skill, todo, rag_feedback, watch, cron, ...)

4.6 Broker

File	Responsibility
src/broker/hub.py	Broker layer root: identity + transport + match engine + rate limiter + per-broker store/ledger
src/broker/workshop/__init__.py	Installable broker apps: rooms + threads + reputation + triggers

4.7 Flow

File	Responsibility
src/flow/engine.py	FlowEngine: owner-thread + per-role worker-thread concurrent execution
src/flow/resume.py	Rehydrate from DB: pinned template + mutation replay + hash verification

4.8 Frontend

File	Responsibility
electron/renderer/src/components/Desktop.vue	Desktop shell (default manager landing)
electron/renderer/src/components/ChatBubble.vue	Chat bubble rendering
electron/electron/main.js	Electron main process
electron/electron/python.js	Bridge lifecycle

---

5 · workspace/ Runtime Data Layout

workspace/
├── familiars.db              # SQLite database (WAL mode)
├── SECRET.json               # Encrypted sensitive information keystore
├── .salt                     # Fernet encryption seed (32 random bytes)
├── .bridge_token             # Bridge API token (256-bit)
├── .bridge.crt / .bridge.key # Self-signed certificate + private key
├── .bridge.port              # Current bridge port (fallback record)
├── .bridge.pid               # Current bridge PID
├── .bridges.json             # Cross-process bridge registry
├── .paths_aliases.json       # Path drift alignment records
├── .inbox.jsonl              # Notification egress persistence log
├── auth.json                 # Wallet + device fingerprint (plaintext)
├── global_settings.json      # Global preferences
├── USER.md                   # User personal profile
├── IDENTITY.md               # Global identity description
├── AGENTS.md                 # Project-level agent rules
├── audit.log                 # Tool call / approval / usage audit
├── .bridge.log               # Bridge process log
├── reports/                  # Report templates
├── agents/                   # Agent profiles
│   └── agent_<id>/
│       ├── IDENTITY.md, USER.md, AGENTS.md, config.json
│       ├── dialogue_<n>/     # Dialogue history (with embeddings)
│       ├── logs/*.jsonl      # Daily event streams
│       ├── memory/           # scope×category memory
│       ├── reports/          # Daily/weekly/monthly/annual reports
│       └── skill_runs/       # Skill execution traces
├── skills/                   # Custom skills
│   └── <skill_id>/SKILL.md
├── manager/
│   ├── brokers/              # Installed brokers
│   ├── flows/                # Committed flow templates
│   ├── pipelines/            # Multi-agent pipelines
│   └── skill_workshop_runs/  # Skill workshop traces
├── _playwright/              # Chrome automation profile (with cookies)
├── monitor_debug/            # Monitor debug screenshots
├── operate/                  # operate() OmniParser output
├── _cache/rag/               # RAG embedding index
└── agent_recipes/            # Recipe external KB

---

6 · Database Migration List

SQLite migrations are in src/storage/migrations/, supporting both .sql and .py formats. The migration runner is in src/storage/db.py.

Version	Filename	Content
v1	v1__init.sql	Initial tables
v2	v2__cron_jobs.sql	Cron jobs
v3	v3__rag_feedback.sql	RAG feedback
v4	v4__memory_category.sql	Memory categories
v5	v5__schedules.sql	Schedules
v6	v6__todos.sql	Todos
v7	v7__cron_runs.sql	Cron run records
v8	v8__schedules_status.sql	Schedule status
v9	v9__reminders.sql	Reminders
v10	v10__proactive_feedback.sql	Proactive feedback
v11	v11__node_origin.sql	Node origin
v12	v12__watch_jobs.sql	Watch jobs
v13	v13__recurrence.sql	Recurrence
v14	v14__watch_jobs_metadata.sql	Watch job metadata
v15	v15__agent_turn_counter.sql	Agent turn counter
v16	v16__schedule_dedup_and_unique.py	Python migration: Schedule dedup + unique constraints
v17	v17__cron_last_fired_and_feedback.sql	Cron last-fired + feedback
v18	v18__broker.sql	Broker layer core tables
v19	v19__broker_workshop.sql	Broker workshop tables
v20	v20__guild.sql + v20__broker_local_package_dir.py	Guild + broker local package directory
v21	v21__broker_identity_assets.sql + v21__guild_task_type.py	Broker identity assets + guild task types
v22	v22__broker_messages.sql	Broker messages
v23	v23__broker_member_caps.sql	Broker member capabilities
v24	v24__broker_approvals.sql	Broker approvals
v25	v25__flow_core.py	Python migration: Flow core tables
v26	v26__flow_trace_index.sql	Flow trace index
v27	v27__guild_medal_images.sql	Guild medal images
v28	v28__broker_author_crl.sql	Broker author CRL
v29	v29__broker_trusted_authors.sql	Broker trusted authors
v30	v30__broker_room_federation.sql	Broker room federation
v31	v31__broker_thread_federation.sql	Broker thread federation
v32	v32__broker_message_federation.sql	Broker message federation
v33	v33__guild_task_federation.sql	Guild task federation
v34	v34__guild_medal_federation.sql	Guild medal federation
v35	v35__guild_ledger_federation.sql	Guild ledger federation
v36	v36__broker_user_consents.sql	Broker user consents
v37	v37__guild_scope_approvals.sql	Guild scope approvals
v38	v38__guild_task_lifecycle.sql	Guild task lifecycle
v39	v39__guild_merge_requests.sql	Guild merge requests
v40	v40__task_edit_history.sql	Task edit history
v41	v41__guild_modification_requests.sql + v41__message_reactions.py	Guild modification requests + message reactions
v42	v42__guild_experience_reports.sql + v42__guild_modification_votes.sql	Guild experience reports + modification votes
v43	v43__guild_task_recall_votes.sql	Guild task recall votes
v44	v44__guild_scope_members.sql	Guild scope members
v45	v45__task_message_channels.sql	Task message channels
v46	v46__guild_task_tags.sql	Guild task tags

---

7 · Bridge Route Catalog

All route files are in src/bridge/routes/, mounted by src/bridge/app.py at import time. There are currently 63 route files:

Route File	Main Endpoints
chat.py	/api/chat/stream (SSE conversation)
agents.py	/api/agents (agent CRUD + list)
tree.py	Dialogue tree operations
settings.py	Global settings
schedule.py	Schedule management
todo.py	Todo management
cron.py	Cron jobs
reminders.py	Reminders
monitor.py	Activity monitors
skills.py	Skill management
skill_forge.py	Skill forge
skill_proposals.py	Skill proposals
skill_workshop.py	Skill workshop runs
tool_skills.py	Tool skills
tools_catalog.py	Tools catalog
tools_source.py	Tool source
digital_human.py	Digital human
asr.py	ASR speech recognition
phone_call.py	Phone calls
auth.py	Authentication
user.py	User
user_profile.py	User profile
usage.py	Usage
feedback.py	Feedback
status.py	Status
dev.py	Developer tools
draft.py	Drafts
quick_inputs.py	Quick inputs
quick_ask.py	Quick ask
reports.py	Reports
gift.py	Gifts
cg.py	CG
agent_workshop.py	Agent workshop
agent_recipes.py	Agent recipes
agent_assets.py	Agent assets
agent_activity.py	Agent activity
broker.py	Broker core
broker_workshop.py	Broker workshop
broker_app.py	Broker app
broker_assets.py	Broker assets
broker_dev.py	Broker dev
marketplace_artifacts.py	Marketplace artifacts
flow_templates.py	Flow template CRUD + custom field renderers
flows.py	Flow instance lifecycle (list/get/trace/cancel)
flow_dev.py	Flow dev
recipe_dev.py	Recipe dev
feishu.py	Feishu integration
background.py	Background tasks
desktop_notify.py	Desktop notifications
broadcast.py	Broadcast
memory_status.py	Memory status
memory.py	Memory operations
onboarding.py	Onboarding wizard
vram.py	VRAM management
learn.py	Learning
responses.py	Responses
setup.py	Setup wizard
demo.py	Public demo sandbox
guild.py	Guild (Ventaris)
xun_da.py	XunDa (wayfinding)
_relay_dev_common.py	Relay dev shared utilities

---

8 · Environment Variable Reference

8.1 Required (.env)

Variable	Description	Default
BASE_URL	OpenAI-compatible API base URL	(required)
API_KEY	LLM provider API key	(required)
DEFAULT_MODEL	Default chat model name	(required)
MANAGER_MODEL	Model for manager executive summaries	gpt-4o

8.2 Models & Embeddings

Variable	Description	Default
MINI_MODEL	Lightweight local model name	Qwen2.5-1.5B
FAST_MODEL	Low-latency cloud model (draft/classify). Empty = fall back to DEFAULT_MODEL	""
EMBEDDING_MODEL	Embedding model	BAAI/bge-m3
RERANKER_MODEL	Reranker model	BAAI/bge-reranker-v2-m3
MEMORIZE_MODEL	Memory writer model. Unset = DEFAULT_MODEL	""
CONSOLIDATE_MODEL	Memory consolidator model. Unset = MANAGER_MODEL	""
MEMORY_TEACHER_BASE_URL	Memory teacher model URL	""
MEMORY_TEACHER_KEY	Memory teacher API key	""
DATAGEN_BASE_URL	Data generation model URL	""
DATAGEN_API_KEY	Data generation API key	""

8.3 Infrastructure Tuning

Variable	Description	Default
TIMEOUT	HTTP timeout (seconds)	300
MAX_TURNS	Maximum tool-loop turns	50
DIALOGUE_EXPIRE_TIME	Dialogue expiry time (seconds)	3600
SLIDE_WINDOW_SIZE	Dialogue history sliding window	5
TOP_K	RAG retrieval top-K	5
WORKSPACE_ROUTE	Workspace root directory	cwd
PORT	Bridge listen port	18711

8.4 RAG Tuning

Variable	Description	Default
RAG_DENSE_TOPK	Dense recall candidate count	20
RAG_CHUNK_SIZE	Target chunk size (characters)	800
RAG_RERANK_MIN_SCORE	Rerank minimum score (0 = keep all)	0.0
RAG_REFINER_MAX_RETRIES	Refiner JSON parse retries	3
RAG_FILE_WEIGHT	File-level rerank weight α	0.4
RAG_CHUNK_WEIGHT	Chunk-level rerank weight β	0.6
RAG_RRF_K	Reciprocal rank fusion constant	60
RAG_FEEDBACK_WEIGHT	Historical success rate weight	0.0
RAG_ANN_MIN_N	Minimum candidates to build HNSW ANN index	64
RAG_MULTIQUERY_N	Multi-query variant count	1

8.5 Circuit Breaker / Concurrency

Variable	Description	Default
CB_FAILURE_THRESHOLD	Circuit breaker open threshold	5
CB_RECOVERY_SECONDS	Circuit breaker recovery time (seconds)	30.0
LLM_MAX_RETRIES	Maximum retry count	3
LLM_RETRY_BASE_DELAY	Initial backoff delay (seconds)	1.0
LLM_RETRY_MAX_DELAY	Maximum backoff delay (seconds)	30.0
LLM_MAX_CONCURRENT_PER_URL	Max concurrent LLM calls per URL	8
LLM_MIN_CONCURRENT_PER_URL	Min concurrent per URL	1
LLM_QUEUE_WAIT_S	Maximum queue wait seconds	120
LLM_AIMD_GROW_AFTER	AIMD growth interval (consecutive successes)	20
LLM_AIMD_SHRINK_FACTOR	AIMD shrink factor	0.5
LLM_GATE_DISABLED	Disable concurrency gate	false
RESPONSES_API_ENABLED	Force Responses API on/off	"" (auto)

8.6 Security & Approval

Variable	Description	Default
FAMILIARS_APPROVAL_DISABLED	Globally disable approval gate	""
FAMILIARS_DB_PATH	SQLite database path	workspace/familiars.db
FAMILIARS_HTTP_INSECURE	Fall back to plain HTTP + uvicorn	""
FAMILIARS_DIAG_ACTOR_DRIFT	Approval misroute stack traces	1
FAMILIARS_TIER4_MAX_MB	GPU Tier4 max MB	Platform-dependent
FAMILIARS_FRAMEWORK_DOCS_TOPK	Framework docs retrieval top-K	Platform-dependent

8.7 Feature Toggles

Variable	Description	Default
MEMORY_WRITER_DISABLED	Disable memory writing	""
WECHAT_TRIGGER_ENABLED	Enable WeChat listener	0
QQ_TRIGGER_ENABLED	Enable QQ listener	0
SCAN_PRESIDIO_DISABLED	Disable Presidio scanning	""
DAILY_MONITOR_DISABLED	Disable daily monitor module	false
GITLEAKS_BIN	gitleaks binary path	""

8.8 Broker / Federation

Variable	Description	Default
FAMILIARS_BROKER_ADVERTISE_URL	This broker's public/LAN base URL	""
FAMILIARS_BROKER_BIND	Bridge HTTP bind address	"" (127.0.0.1)
FAMILIARS_BROKER_DIRECT_TIMEOUT	Direct peer federation timeout (seconds)	10.0

8.9 Daily Monitoring

Variable	Description	Default
DAILY_MONITOR_MAX_TASKS	Max concurrent daily monitors per agent	8
DAILY_MONITOR_EMBEDDING_THRESHOLD	Embedding similarity threshold	0.54
DAILY_MONITOR_KEYWORD_ENABLED	Enable keyword fast-path	true
DAILY_MONITOR_MINI_CONFIRM_ENABLED	Enable mini-model confirmation	true
DAILY_MONITOR_CLIENT_TIMEOUT	Client dispatch timeout (seconds)	60.0

8.10 Updates

Variable	Description	Default
UPDATE_URL	OTA update feed base URL	""
UPDATE_CHECK_INTERVAL_HOURS	Auto-update check interval (hours)	24

---

9 · User Settings (DialogConfig / AssistantConfig)

Field	Type	Default	Description
security_level	str	"medium"	Approval threshold: low/medium/high
intense_mode	bool	true	Auto mode (skip approvals until success)
turbo_mode	bool	false	Skip approvals but keep plan verification
need_figure	bool	true	Need digital human image
need_audio	bool	true	Need voice
need_video	bool	true	Need video call
need_report	bool	true	Need reports
need_initiative	bool	true	Proactive conversation
verify_plan	bool	false	Verify plan before execution
skill_auto_apply	bool	false	Auto-apply skill proposals
color	str	"blue"	Theme color

---

10 · Key Runtime Flows

1. Conversation: renderer → /api/chat/stream (SSE) → ConversationSession tool loop (≤MAX_TURNS) → model → tools → memory → reply
2. Memory: DialogueManager builds RAG history each turn (α·cos + e^{−β·Δt} + γ·tree_distance); persona/identity writes to USER.md/IDENTITY.md
3. Proactive decision: Decider small model decides "should I proactively do something"
4. Broker: Transaction chain + installable apps (manifest+UI+plugins); marketplace runs through deploy/relay
5. Flow: FlowEngine owner-thread + per-role worker-thread concurrent execution; resume.py rehydrates from DB
6. Recipe: compile → dry-run → execute (in sandbox) → verify → register

---

11 · Inclusion & Omission Policy

• The repository treats documentation (ARCHITECTURE/OPERATION/SECURITY/REPOSITORY/CLAUDE/CLI/BROKER_DEVELOPMENT.md) as the manager's built-in knowledge base (indexed by framework_docs.py:render_framework_index + read via framework_tools.py)
• Training artifacts / large model weights are not included in git (models/, training/, dataset/ are gitignored)
• Scratch agent directories (demon, angel, etc.) go under runs/; workspace/agents/ is scanned by the bridge at startup

---

This file is based on the actual repository structure and CLAUDE.md / ARCHITECTURE.md / SECURITY.md. For detailed architecture, see ARCHITECTURE.md.