docs/05-dev-guidelines.md

Objectverse Diary — 开发规范

代码规范

Python

• 使用 type hints
• 保持函数简短
• 避免隐藏的网络调用
• 不硬编码 secrets
• 使用 Pydantic 验证模型 JSON 输出
• Prompts 放在 src/prompts/，不要内联到 UI 代码中
• UI 文案放在 src/ui/copy.py

Gradio

• 使用 gr.Blocks，不使用 gr.Interface 做主应用
• 所有主要组件必须有 elem_id 或 elem_classes
• 自定义 CSS 放在 src/ui/styles.css
• 英文文案优先，中文辅助在后
• 应用需在 1366px 桌面和移动端宽度下可用

Model

• 总模型参数量必须有文档记录
• 不调用商业 API
• 文本生成支持本地 llama.cpp 路径
• VLM 降级方案必须有文档
• 输出必须是结构化 JSON，渲染前验证

Data

• 不包含个人敏感数据
• Sample traces 必须匿名化
• 公开数据集使用合成或已授权的示例
• 原始图片与公开 trace 数据分离

---

Git 规范

分支策略

main:    stable submission branch
dev:     active development branch
feat/*:  feature branches
fix/*:   bug fixes
docs/*:  documentation

Commit 格式

feat: add object persona generator
fix: repair malformed diary JSON
docs: add field notes draft
style: improve off-brand gradio theme
chore: update model config

---

AGENTS.md 模板

直接放到项目根目录 AGENTS.md

# AGENTS.md

## Project

Objectverse Diary is a Build Small Hackathon project.
It is an English-first, Chinese-second Gradio application where users upload
everyday object photos and small AI models generate secret object personas,
diary entries, conversations, and shareable cards.

## Primary Goals

1. Compete in the "An Adventure in Thousand Token Wood" track.
2. Keep total model parameters <= 32B.
3. Use Gradio for all UI and interaction.
4. Host the final app as a Hugging Face Space.
5. Avoid commercial cloud AI APIs.
6. Maximize hackathon badges.
7. Use English as the main UI language and Chinese as secondary helper text.

## Non-Negotiable Rules

- Do not use OpenAI, Anthropic, Gemini, Cohere, or other commercial model APIs.
- Do not leak private credit codes, tokens, emails, or credentials.
- Do not hardcode secrets.
- Do not remove Gradio.
- Do not make the UI Chinese-first.
- Do not exceed the 32B total model parameter limit.
- Do not add large features that risk missing the submission deadline.
- Do not store unconsented personal user data.

## Tech Stack

- Python
- Gradio Blocks
- Hugging Face Spaces
- llama.cpp / llama-cpp-python for text generation
- MiniCPM-V or fallback lightweight VLM for object understanding
- LoRA / PEFT for fine-tuning
- Markdown documentation

## UI Requirements

The interface must be English-first and Chinese-second.
Visual style: strange object archive, not default Gradio demo.
Recommended UI mood: mysterious archive, typewriter diary, warm dark paper,
amber highlight, museum label, strange but polished.

## Architecture

1. Image upload → 2. Object understanding → 3. Persona generation →
4. Secret diary generation → 5. Object chat → 6. Share card rendering →
7. Trace export

## Coding Guidelines

- Use type hints
- Prefer small, composable functions
- Prompts under src/prompts
- UI copy under src/ui/copy.py
- CSS under src/ui/styles.css
- Runtime code under src/models
- Trace code under src/traces
- Use Pydantic schemas for model outputs
- Add clear fallback behavior when model output is invalid

## Testing Requirements

- App runs locally
- App runs on HF Space
- At least 6 sample objects work
- Share card renders correctly
- Trace export works
- No secret keys committed
- README links valid
- Demo video flow reproducible

---

Codex Skills 模板

以下 Skills 文件放在 .codex/skills/ 对应目录下。

.codex/project.md

项目上下文文件，包含 hackathon 信息、核心创意、硬性约束和开发优先级。

.codex/skills/gradio-ui/SKILL.md

Gradio Off-Brand UI 规范：布局结构（Hero → Object Intake → Object File → Secret Diary → Chat → Share Card → Trace）、视觉方向（dark paper / amber / typewriter / museum）。

.codex/skills/model-runtime/SKILL.md

模型运行时规范：Vision Runner、Text Runner、Schema 三层架构，以及降级策略（VLM 失败 → 手动描述、文本模型失败 → 模板降级、JSON 异常 → 修复重试）。

.codex/skills/dataset-trace/SKILL.md

数据集与 Trace 规范：训练数据格式、trace 格式、隐私规则、验收标准（≥100 训练样本、≥6 公开 traces）。

.codex/skills/hf-space/SKILL.md

HF Space 部署规范：必要文件、README YAML header、部署检查清单。

.codex/skills/submission/SKILL.md

提交规范：8 项交付物、Demo 视频结构、社交文案模板、最终检查清单。