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 规范

### 分支策略

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

### Commit 格式

```text
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`

```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 视频结构、社交文案模板、最终检查清单。