wuyang
132 lines
4.9 KiB
Markdown
132 lines
4.9 KiB
Markdown
# AI Continuation Guide
|
|
|
|
This file is the entrypoint for any AI or engineer continuing the repository.
|
|
|
|
## Start Here
|
|
|
|
Run these commands before changing anything:
|
|
|
|
```bash
|
|
git status --short --branch
|
|
git log -5 --oneline --decorate
|
|
python3 tools/check_project.py
|
|
sed -n '1,260p' docs/06-project-status.md
|
|
sed -n '1,260p' docs/07-exploration-history.md
|
|
sed -n '1,260p' docs/08-next-work.md
|
|
```
|
|
|
|
The active branch and remote are normally:
|
|
|
|
```text
|
|
branch: main
|
|
remote: https://git.k1412.top/wuyang/agent.git
|
|
```
|
|
|
|
Do not assume the public web service is running just because the repository is healthy. Check it separately:
|
|
|
|
```bash
|
|
web/manage.sh status
|
|
curl -fsS https://lab.k1412.top/api/health | jq
|
|
```
|
|
|
|
## Actual Goal
|
|
|
|
This is not merely a paper browser. The user wants a scaffold that turns a large raw corpus into personal, reusable cognition:
|
|
|
|
1. remember important knowledge;
|
|
2. compress it into a coherent system;
|
|
3. use that system to explain causes, compare approaches, answer new questions, and propose designs.
|
|
|
|
The current Atlas is a corpus exploration prototype, not a validated solution to this goal. The user rated its practical learning value at effectively zero because browsing left no durable learning state. Do not spend the next iteration polishing the graph without addressing this gap.
|
|
|
|
## Truth Hierarchy
|
|
|
|
Treat repository artifacts according to their evidence level:
|
|
|
|
1. `research/*/findings.md` and `evidence-ledger.md`: current evidence-backed conclusions.
|
|
2. `experiments/*`: method, failures, and validation boundaries.
|
|
3. `docs/`: stable system-level knowledge, but verify dates and sources before extending it.
|
|
4. `papers/items/*.md` with `status: skimmed`: partially reviewed.
|
|
5. `papers/items/*.md` with `status: queued`: collection records only, not understood papers.
|
|
6. Auto tags and model screening outputs: high-recall triage, never final truth.
|
|
|
|
The old `learning/agent-memory/` module is retained as a failed experiment. It is not the current synthesis.
|
|
The Agent evaluation design under `research/evaluation/` is an implementation contract, not a completed
|
|
benchmark. Its task contracts explicitly mark which runners do not exist yet.
|
|
`evaluation-site/` is a presentation layer for that contract. It must not introduce stronger claims than
|
|
the research artifact or display simulation values as real benchmark results.
|
|
|
|
## Repository Contracts
|
|
|
|
- Keep jobs, papers, and industry practice as separate first-class streams.
|
|
- Use metadata and indexes for cross-cutting organization; do not make deep directories the primary UX.
|
|
- Preserve original sources and raw traces. A summary must not overwrite evidence.
|
|
- Distinguish collection, screening, full-text evidence, synthesis, and user learning state.
|
|
- Run `python3 tools/collection/build_index.py` after changing item frontmatter.
|
|
- Run `python3 tools/check_project.py` and `git diff --check` before committing.
|
|
- Use `python3`, not `python`, in this environment.
|
|
- Keep generated cache and PID/log files under `web/cache/`; they are intentionally ignored.
|
|
- Never commit credentials. Git authentication is configured outside the repository.
|
|
|
|
## Ollama Contract
|
|
|
|
Default endpoint:
|
|
|
|
```text
|
|
http://192.168.1.10:11434
|
|
```
|
|
|
|
Current model tiers are configurable with:
|
|
|
|
```text
|
|
OLLAMA_MODEL_LIGHT=ChatGPT-5.6:Luna
|
|
OLLAMA_MODEL_FAST=ChatGPT-5.6:Terra
|
|
OLLAMA_MODEL_LARGE=ChatGPT-5.6:Sol
|
|
```
|
|
|
|
The application serializes Ollama calls because all models share one V100 32G GPU. Application requests must not send `num_ctx` or `keep_alive`; the Ollama server owns context size and residency. Expensive `Sol` actions should remain explicit, not automatic.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Rebuild the main index
|
|
python3 tools/collection/build_index.py
|
|
|
|
# Validate repository integrity
|
|
python3 tools/check_project.py
|
|
|
|
# Start or inspect the web service
|
|
web/manage.sh start
|
|
web/manage.sh status
|
|
web/manage.sh logs
|
|
|
|
# Research pipeline help
|
|
python3 tools/research/search_arxiv_memory.py --help
|
|
python3 tools/research/screen_memory_corpus.py --help
|
|
python3 tools/research/build_memory_landscape.py --help
|
|
|
|
# Collection fallback when the arXiv export API is unavailable
|
|
python3 tools/collection/collect_arxiv.py --backend search-html --help
|
|
|
|
# Aggregate Agent evaluation result JSONL
|
|
python3 tools/evaluation/score_agent_runs.py --help
|
|
|
|
# Preview the static Agent evaluation report
|
|
python3 -m http.server 4173 --directory evaluation-site
|
|
```
|
|
|
|
Read the scripts before rerunning network or model-heavy research jobs. The committed research data is the reproducible snapshot; a refresh changes the time boundary and may be expensive.
|
|
|
|
## Before Handoff
|
|
|
|
After meaningful work, update all affected layers:
|
|
|
|
- artifact or code;
|
|
- generated index/data if applicable;
|
|
- experiment record for the method and result;
|
|
- `docs/06-project-status.md` for current facts;
|
|
- `docs/07-exploration-history.md` for a new major decision or failed route;
|
|
- `docs/08-next-work.md` for changed priorities.
|
|
|
|
Commit with a narrow message and push `main` unless the user requests another branch.
|