34 lines
2.0 KiB
Markdown
34 lines
2.0 KiB
Markdown
# AGENTS.md — project law for dsh (DeepSeek Harness)
|
|
|
|
## What this is
|
|
A **story layer** that sits next to a stock FreshRSS reader (Docker) and turns its
|
|
syndicated feed items into ranked, deduplicated, optionally-LLM-summarized
|
|
"stories". FreshRSS + RSSHub run in Docker. Everything in this repo is the thin
|
|
Python layer on the host that does fetch → cluster → rank → optional LLM.
|
|
|
|
## Hard rules (violating these fails the task)
|
|
1. **Keep the test suite green.** `pytest` in `prototype/` must pass before and
|
|
after every change. The core accept is "two reworded copies → one cluster".
|
|
2. **Do NOT rebuild FreshRSS.** It is a stock container. No fork, no replacement,
|
|
no patches to it.
|
|
3. **Do NOT add Kafka** (or any broker). Async workers + SQLite/JSON is the ceiling.
|
|
4. **Do NOT add a frontend framework.** `prototype/out/index.html` is a generated,
|
|
self-contained static page. No React/Vue/Next/HTMX build tooling.
|
|
5. **Cap the LLM.** Only the top-k ranked stories (default 10, flag `--topk`) get
|
|
summarized; input is headline + first ~300 chars. Never the long tail.
|
|
6. **Story summaries point at the HOST Hermes/llama.cpp, never at DeepSeek.**
|
|
`LLM_BASE_URL` defaults to `http://127.0.0.1:8080/v1`, model `hermes`.
|
|
Coding work may use DeepSeek; news summaries must not — unless the operator
|
|
explicitly overrides `LLM_BASE_URL`.
|
|
7. **Do not change ports.** FreshRSS = 8280, RSSHub = 1200, Hermes = 8080,
|
|
`--serve` = 8765. 8280 exists so FreshRSS does not steal llama.cpp's 8080.
|
|
|
|
## Feature backlog (already spec'd — just implement)
|
|
- [ ] `cluster.py --serve :8765` — serve `prototype/out/` on port 8765.
|
|
- [ ] LLM top-k cap — enforce `--topk` everywhere (done in current code; keep it).
|
|
- [ ] Snapshot mode — `--snapshot JSON` ingests a FreshRSS export with no Docker.
|
|
|
|
## Interfaces
|
|
- `python cluster.py [--opml feeds.opml | --snapshot x.json] [--llm] [--topk N] [--serve :8765]`
|
|
- Env (only for `--llm`): `LLM_BASE_URL`, `LLM_MODEL`.
|
|
- Output: `prototype/out/index.html` + `prototype/out/stories.json`. |