Develop The Living Index with Coding Agents

Use the repository’s open skills to customize content, compose scenes, generate native Three.js assets, and extend the framework without losing accessibility or deployment guarantees.

The Living Index 是一个 agent-native 代码框架：仓库不仅提供可视化 Content Studio，也提供面向 coding agent 的开放技能、事实源映射、测试契约和交付规则。

The Living Index is an agent-native framework. Alongside the visual Content Studio, the repository includes open coding-agent skills, source-of-truth maps, executable contracts, and release rules.

Start with AGENTS.md

仓库根目录的 AGENTS.md 会根据任务把 agent 路由到最小的相关 skill：

The root AGENTS.md routes an agent to the smallest relevant skill:

Skill	适用任务 / Use it for
$living-index-content	个人资料、镜子页照片与社交链接、摄影与 Spotlight、内容卡片 / Profile, mirror portrait and social links, photography, Spotlight, and content cards
$living-index-scene	作者时区光照、物件移动、GLB、停用/替换、装饰与交互行为 / Author-timezone lighting, placement, GLBs, disable/replace, decorative and interactive behavior
$living-index-native-assets	直接用 Three.js 生成简单家具、灯具、标牌和装饰 / Generate simple furniture, lamps, signs, and props directly with Three.js
$living-index-developer	新字段、模块、交互、路由、跨层能力和发布级改动 / New fields, modules, interactions, routes, cross-layer capabilities, and release-ready changes

这些 skill 位于 skills/，随 MIT 许可一起开源，可以阅读、复制和改进。

These skills live in skills/ and are open source under the repository’s MIT license. You can inspect, copy, and improve them.

Choose Studio, GLB, native code, or framework work

• 使用 Content Studio 完成日常文案、图片、社交链接、卡片、已有物件位置和 GLB 配置。 / Use Content Studio for routine copy, images, social links, cards, existing placement, and GLB configuration.
• 使用 GLB 表达复杂拓扑、UV 纹理或来自 Blender 的资产。 / Use GLB for complex topology, UV textures, or Blender-authored assets.
• 使用原生 Three.js 表达简单、轻量且应立即加载的场景物件。 / Use native Three.js for simple, lightweight objects that should load immediately.
• 只有新能力跨越 schema、editor、runtime、semantic index、routes 和 tests 时，才进入框架开发。 / Enter framework development when a capability spans schema, editor, runtime, semantic index, routes, and tests.

Prompt with product intent / 用产品意图描述任务

告诉 agent 物件的用途，而不只是文件操作：

Describe the product intent, not only the file operation:

Use $living-index-scene to add this GLB as a decorative object.
Place it beside the camera, keep it out of the semantic index, and verify
that Save to project generates the published scene source.

Use $living-index-content to add a bilingual photography series.
Keep every photo visible, make one Spotlight, and add accessible alt text.

Use $living-index-native-assets to generate a small ceramic floor lamp.
It should react to day/night lighting and must not open a content page.

Cross-layer invariants / 跨层约束

任何 agent 改动都应保留：

Every agent change should preserve:

• 中英文内容的有意对齐。 / Intentional Chinese and English parity.
• 空间交互对应的语义索引与键盘路径。 / A semantic index and keyboard path for every spatial interaction.
• reduced motion、WebGL failure 和 noscript 降级。 / Reduced-motion, WebGL-failure, and noscript fallbacks.
• loopback-only 的保存与上传接口。 / Loopback-only save and upload endpoints.
• JSON、生成场景源码和最终上传资源的一致提交。 / One consistent change set for JSON, generated scene source, and final uploads.
• 第三方资产在 ASSET_CREDITS.md 中的来源与许可记录。 / Third-party provenance and licence records in ASSET_CREDITS.md.

Source-of-truth map / 事实源

关注点 / Concern	Source
内容 schema、限制与 merge	app/content-config.ts
中英文默认章节	app/portfolio-data.ts, app/portfolio-data-en.ts
发布内容	public/content/site-content.json
发布场景快照	app/generated/scene-config.ts
编辑器	app/ContentStudio.tsx, app/SceneStudio.tsx
Three.js 运行时	app/RoomExperience.tsx
光照与摆放事务	app/solar-lighting.ts, app/scene-placement.ts
本地保存、上传与 GLB 校验	build/content-studio-vite-plugin.ts
可执行契约	tests/

不要手工修改 app/generated/scene-config.ts。请在本地 ?studio=1 中编辑并点击 Save to project，让 JSON、场景源码和 GLB 生命周期保持同步。

Do not hand-edit app/generated/scene-config.ts. Edit through local ?studio=1 and use Save to project so JSON, generated scene source, and the GLB lifecycle stay synchronized.

Validate and publish / 验证与发布

npm run typecheck
npm run lint
npm test
git diff --check

然后只暂存本次变更涉及的具体路径，提交并推送。main 分支上的 GitHub Actions 负责质量检查和 Cloudflare Worker 部署；普通开发流程不要绕过 CI 直接部署。

Then stage only the exact paths changed, commit, and push. GitHub Actions on main owns validation and Cloudflare Worker deployment. Do not bypass CI with a direct deployment in the normal workflow.