127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# 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:`.
|