chore: prepare yanting monorepo handoff
This commit is contained in:
@@ -0,0 +1,126 @@
|
||||
# AGENTS.md - Yanting Engineering Repo
|
||||
|
||||
> Public agent instructions for this repository. This file is safe to commit.
|
||||
> Local agents may read ignored `AGENTS.local.md`, but the repository must not depend on it.
|
||||
> Last updated: 2026-06-03.
|
||||
|
||||
## Project
|
||||
|
||||
This repository contains the Phase 1 implementation and engineering handoff for `研听 / report-notebooklm`.
|
||||
|
||||
`研听` is a Chinese research-report interpretation app. It turns global institutional research reports into structured Chinese reading and listening experiences. The product is an interpretation and annotation service, not investment advice.
|
||||
|
||||
Technical identifiers:
|
||||
|
||||
- Code/API/internal name: `report-notebooklm`
|
||||
- Short prefix: `rnb`
|
||||
- API prefix: `/api/report-notebooklm/v1`
|
||||
- Database schema name: `report_notebooklm`
|
||||
- User-facing display name: `研听`
|
||||
|
||||
Do not use the user-facing display name in code identifiers, database schema names, Redis keys, object-storage paths, or package names.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
This is intended to be a single Gitea repository.
|
||||
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `README.md` | Human-facing repository entry point. |
|
||||
| `docs/` | Repo-level public handoff, decisions, and development history. |
|
||||
| `report-notebooklm-api/` | FastAPI backend, database models, migrations, seed importer, API docs. |
|
||||
| `report-notebooklm-app/` | Flutter app, Android/web scaffolds, App docs. |
|
||||
| `docs.jimme.local/` | Ignored local-only notes, not required by the team. |
|
||||
| `AGENTS.local.md` | Ignored local agent overlay. |
|
||||
|
||||
## Public vs Local Documentation
|
||||
|
||||
Public, committed documentation must be portable:
|
||||
|
||||
- Use repository-relative paths.
|
||||
- Use environment variables and placeholders for credentials.
|
||||
- Describe product decisions in team-readable language.
|
||||
- Distinguish implemented behavior from planned/spec behavior.
|
||||
|
||||
Do not commit local-only material:
|
||||
|
||||
- Local absolute paths.
|
||||
- Personal machine setup.
|
||||
- private agent workflow.
|
||||
- raw session logs.
|
||||
- local screenshots, APKs, caches, virtualenvs, build outputs.
|
||||
- credentials or local service passwords.
|
||||
|
||||
Use `docs.jimme.local/` for ignored local notes and raw process references. Durable team-facing conclusions should be distilled into public `docs/`.
|
||||
|
||||
## Product and Compliance Constraints
|
||||
|
||||
- Public responses expose only reviewed display artifacts, not raw NotebookLM artifacts.
|
||||
- Public responses expose `cache_version`; `display_version` and module `version` are internal.
|
||||
- Do not expose raw artifact payloads, local file paths, NotebookLM notebook/source/conversation IDs, account identifiers, or private object-storage paths.
|
||||
- Phase 1 has no report-interpretation download feature.
|
||||
- Phase 1 does not include comments, UGC, paid unlocks, membership, task walls, points, trading signals, or investment recommendations.
|
||||
- NotebookLM-native/source-driven artifacts are the content source. Do not use local LLM rewriting to invent publishable report content.
|
||||
- Gray broker sources and generated media require compliance/operations review before public release.
|
||||
|
||||
## Backend
|
||||
|
||||
Read first:
|
||||
|
||||
- `report-notebooklm-api/README.md`
|
||||
- `report-notebooklm-api/docs/HANDOFF.md`
|
||||
- `report-notebooklm-api/docs/API_AND_DATA.md`
|
||||
- `report-notebooklm-api/docs/CONTENT_PIPELINE.md`
|
||||
- `report-notebooklm-api/docs/RUNBOOK.md`
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
cd report-notebooklm-api
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e ".[dev]"
|
||||
alembic upgrade head
|
||||
python scripts/import_seed_content.py
|
||||
pytest -q
|
||||
uvicorn app.main:app --reload --host <bind-host> --port <port>
|
||||
```
|
||||
|
||||
The backend requires `.env` settings for real MySQL/Redis environments. Use `.env.example` as the template. Do not commit `.env`.
|
||||
|
||||
## App
|
||||
|
||||
Read first:
|
||||
|
||||
- `report-notebooklm-app/README.md`
|
||||
- `report-notebooklm-app/docs/HANDOFF.md`
|
||||
- `report-notebooklm-app/docs/API_CONTRACT_NOTES.md`
|
||||
- `report-notebooklm-app/docs/APP_RUNBOOK.md`
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
cd report-notebooklm-app
|
||||
flutter analyze
|
||||
flutter test
|
||||
flutter build web --dart-define=RNB_API_BASE=<api-base-url>
|
||||
flutter build apk --debug --dart-define=RNB_API_BASE=<emulator-api-base-url>
|
||||
```
|
||||
|
||||
The App intentionally has no built-in live API default. Always pass `RNB_API_BASE`.
|
||||
|
||||
## Decision Records
|
||||
|
||||
Long-lived decisions belong in `docs/DECISIONS.md`.
|
||||
|
||||
Development timeline and major implementation changes belong in `docs/DEVELOPMENT_HISTORY.md`.
|
||||
|
||||
Raw session logs, temporary planning transcripts, or local-only evidence pointers belong in ignored `docs.jimme.local/`.
|
||||
|
||||
## Git Rules
|
||||
|
||||
- Target remote: `https://gitea.neuronlabs.art/third-party-project/yanting.git`.
|
||||
- Commit one monorepo, not nested repositories.
|
||||
- Before the final monorepo push, remove or archive nested `.git/` directories under subprojects so source files are committed as normal directories.
|
||||
- Keep `.env`, build artifacts, caches, APKs, local status files, and local agent overlays ignored.
|
||||
- Use English commit messages with prefixes such as `feat:`, `fix:`, `docs:`, and `chore:`.
|
||||
Reference in New Issue
Block a user