Project Structure and Sources of Truth

Understand where The Living Index stores default content, Studio overrides, generated scene source, uploads, runtime code, skills, tests, and deployment configuration.

The Living Index 将模板默认值、个人覆盖、发布场景源码和二进制资源分开保存。理解这些层级可以避免“本地预览正确，但提交或生产不一致”。

The Living Index separates template defaults, personal overrides, generated scene source, and binary resources. Understanding these layers prevents local previews from diverging from committed or production behavior.

Repository map / 仓库结构

.
├── app/
│   ├── page.tsx
│   ├── layout.tsx
│   ├── RoomExperience.tsx
│   ├── ContentStudio.tsx
│   ├── SceneStudio.tsx
│   ├── ContentCardEditor.tsx
│   ├── AboutProfileModule.tsx
│   ├── PhotographyGallery.tsx
│   ├── ModelUploadField.tsx
│   ├── ImageUploadField.tsx
│   ├── content-config.ts
│   ├── content-draft.ts
│   ├── model-loading.ts
│   ├── scene-placement.ts
│   ├── solar-lighting.ts
│   ├── portfolio-data.ts
│   ├── portfolio-data-en.ts
│   └── generated/
│       └── scene-config.ts
├── build/
│   └── content-studio-vite-plugin.ts
├── public/
│   ├── content/
│   │   └── site-content.json
│   └── uploads/
│       ├── profile/
│       ├── photography/
│       ├── cards/
│       └── models/
├── .content-studio-cache/
│   └── models/
├── skills/
│   ├── living-index-content/
│   ├── living-index-scene/
│   ├── living-index-native-assets/
│   └── living-index-developer/
├── tests/
├── worker/
│   └── index.ts
├── .github/workflows/deploy.yml
├── AGENTS.md
├── ASSET_CREDITS.md
├── package.json
├── vite.config.ts
└── wrangler.jsonc

Source-of-truth table / 事实源

Concern	Source of truth
Schema, limits, normalization	app/content-config.ts
Default Chinese content	app/portfolio-data.ts
Default English content	app/portfolio-data-en.ts
Personal content and scene authoring document	public/content/site-content.json
Published scene snapshot	app/generated/scene-config.ts
Content and scene UI	app/ContentStudio.tsx, app/SceneStudio.tsx
Three.js runtime and semantic index	app/RoomExperience.tsx
Author-timezone lighting	app/solar-lighting.ts
Drag-placement transaction	app/scene-placement.ts
Local save/upload/GLB validation	build/content-studio-vite-plugin.ts
Agent workflows	AGENTS.md, skills/
Executable contracts	tests/
Release pipeline	.github/workflows/deploy.yml

How content loads / 内容加载顺序

The default TypeScript data provides a complete starting point. JSON overrides only the fields you author. For production scene state, the runtime overlays PUBLISHED_SCENE_CONFIG from the generated module.

默认 TypeScript 数据提供完整起点，JSON 只覆盖你编辑的字段。生产场景会使用生成模块中的 PUBLISHED_SCENE_CONFIG。

Only ?studio=1 may then overlay living-index.content-draft.v1 for unsaved authoring. Normal routes ignore the browser draft.

只有 ?studio=1 会再覆盖未保存的 living-index.content-draft.v1。普通路由忽略浏览器草稿。

Save outputs / 保存产物

Save to project treats these as one change:

1. normalized public/content/site-content.json;
2. deterministically generated app/generated/scene-config.ts;
3. final referenced GLBs promoted to public/uploads/models;
4. reference-aware removal of superseded published GLBs;
5. cleanup of remaining staged GLBs.

Do not hand-edit the generated scene file. If you manually replace only the JSON, scene changes are not a complete release and the consistency test should fail.

不要手工修改生成场景文件。只手工替换 JSON 不是完整的场景发布，一致性测试应阻止它。

Upload directories / 上传目录

Directory	Ownership
public/uploads/profile	Profile images written immediately
public/uploads/photography	Photography images written immediately
public/uploads/cards	Content-card images written immediately
.content-studio-cache/models	Uncommitted local GLB previews
public/uploads/models	GLBs confirmed by Save to project
public/models	Optional manually coded assets; not the Studio-managed path

Image unlinking does not remove the stored image. GLB cleanup is reference-aware and automatic at the Studio save boundary.

解除图片引用不会删除图片文件；GLB 则在 Studio 保存边界执行精确引用清理。

Runtime modules / 运行时模块

• RoomExperience.tsx creates one renderer, room geometry, asset runtimes, hitboxes, markers, routes, and the semantic index.
• model-loading.ts retains a prepared upload buffer so the first preview can avoid an immediate second request.
• scene-placement.ts keeps plane, height, and heading previews separate from confirmed config.
• solar-lighting.ts resolves IANA/fixed-offset time and calculates the stylized light state.
• AboutProfileModule.tsx renders portrait, bio, and social buttons.
• PhotographyGallery.tsx renders every photo, the Spotlight editorial block, and instant-photo dialog.

Agent-native extension / Agent 原生扩展

Read root AGENTS.md before code changes. It routes work to the repository skills for content, scene composition, native Three.js assets, or cross-layer framework changes.

代码改动前先阅读根目录 AGENTS.md。它会根据内容、场景、原生 Three.js 资产或跨层框架任务选择对应 skill。

See Agent-native development.