> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Living Index

> Build and publish a bilingual, agent-native 3D personal homepage with visual content and scene authoring.

# A room that answers back

The Living Index 是一个用 Three.js、React 和 TypeScript 构建的三维个人主页框架。默认房间把 12 个生活维度变成可探索的物件，同时保留完整的语义化内容索引、键盘路径和 WebGL 降级。

The Living Index is a 3D personal-homepage framework built with Three.js, React, and TypeScript. Its default room turns 12 dimensions of a life into explorable objects while preserving a complete semantic index, keyboard paths, and a WebGL fallback.

<CardGroup cols={2}>
  <Card title="Visual authoring" icon="sliders" href="/content/content-studio">
    在 Content Studio 中编辑双语内容、照片、社交链接、卡片、物件位置与 GLB。

    Edit bilingual copy, photos, social links, cards, object placement, and GLBs in Content Studio.
  </Card>

  <Card title="Scene composition" icon="cube" href="/content/scene-layout">
    移动、旋转、停用、重新激活或替换内置物件，并增加装饰或交互资产。

    Move, rotate, disable, reactivate, or replace built-in objects, and add decorative or interactive assets.
  </Card>

  <Card title="Agent-native" icon="robot" href="/development/agent-native">
    使用仓库内开源 skills 让 coding agent 修改内容、场景、原生资产或框架能力。

    Use the repository's open skills to let a coding agent change content, scenes, native assets, or framework capabilities.
  </Card>

  <Card title="GitHub → Cloudflare" icon="cloud" href="/deployment/github-actions">
    本地验证后推送 `main`；GitHub Actions 负责质量检查并部署 Cloudflare Worker。

    Validate locally and push `main`; GitHub Actions runs quality gates and deploys the Cloudflare Worker.
  </Card>
</CardGroup>

## What you can customize / 可自定义内容

* 个人姓名、首屏文案、城市与作者时区 / Name, intro copy, city, and author timezone
* 镜子页个人照片、简介与最多 12 个带平台图标的社交链接 / Mirror portrait, bio, and up to 12 platform-icon social links
* 所有摄影作品、相纸详情与一个拥有专属文字栏的 Spotlight / Every photo, instant-photo details, and one Spotlight with a dedicated editorial column
* 三种内容卡：纯文字、图文和链接按钮 / Three card kinds: text, media, and link buttons
* 内置物件的相对位置、旋转、缩放、启停与可逆 GLB 外观替换 / Relative placement, rotation, scale, enable state, and reversible GLB visual replacement for built-ins
* 自定义装饰或交互 GLB 的绝对 transform 与内容 / Absolute transforms and content for decorative or interactive custom GLBs
* coding agent 直接生成的轻量 Three.js 原生资产 / Lightweight native Three.js assets generated by a coding agent

## First run / 首次运行

```bash theme={null}
git clone https://github.com/ACondaway/HOME-3D.git
cd HOME-3D
npm install
npm run dev
```

打开终端显示的本地 URL，并添加 `?studio=1`。如果 3000 端口已占用，开发服务器可能自动选择 3001 或其他端口。

Open the local URL printed in your terminal and append `?studio=1`. If port 3000 is occupied, the development server may select 3001 or another port.

```text theme={null}
http://localhost:3000/?studio=1
```

<Warning>
  Studio 的浏览器草稿只存在于当前 origin 的 `localStorage`。它不是已发布文件。普通页面不会读取草稿；只有 `?studio=1` 用它恢复未保存编辑。

  The Studio browser draft exists only in the current origin's `localStorage`. It is not a published file. Normal pages ignore it; only `?studio=1` uses it to restore unsaved work.
</Warning>

## Save and publish / 保存与发布

点击 **Save to project** 会同时写入内容文件、生成场景源码，并确认最终 GLB：

**Save to project** writes the content document, regenerates scene source, and confirms final GLBs in one local transaction:

```text theme={null}
public/content/site-content.json
app/generated/scene-config.ts
public/uploads/...
```

验证后精确暂存相关文件并推送：

Validate, stage the exact files, and push:

```bash theme={null}
npm run typecheck
npm run lint
npm test
git diff --check

git add public/content/site-content.json app/generated/scene-config.ts
git add public/uploads/<files-used-by-this-change>
git commit -m "Update portfolio content and scene"
git push
```

<Tip>
  如果只改了文本，没有场景或上传资源变化，只暂存实际变更的文件。先运行 `git status --short`，不要无差别提交缓存或孤儿文件。

  If you changed only text, stage only the files that actually changed. Run `git status --short` first; do not indiscriminately commit caches or orphaned files.
</Tip>

## Continue / 继续阅读

* [Quickstart](/quickstart)
* [Content Studio](/content/content-studio)
* [Scene layout](/content/scene-layout)
* [GLB models](/customization/glb-models)
* [Agent-native development](/development/agent-native)