Document and harden project handoff

2026-07-12 14:54:03 +08:00
parent ab758e774e
commit 8e4ff3779b
17 changed files with 1030 additions and 32 deletions
@@ -4,6 +4,13 @@

 ## Run

+```bash
+web/manage.sh start
+web/manage.sh status
+```
+
+前台调试仍可直接运行：
+
 ```bash
 python3 web/app.py --host 100.114.68.27 --port 18080
 ```
@@ -30,17 +37,40 @@ https://lab.k1412.top/

 ## AI Policy

- 默认摘要模型：`ChatGPT-5.6:fast`
- 默认翻译模型：`ChatGPT-5.6:light`
- 深度分析模型：`ChatGPT-5.6:large`，只在前端手动选择时使用
- Atlas 解释：`ChatGPT-5.6:fast`
- 主题导读、阅读路径、主题比较：`ChatGPT-5.6:large`，只在前端手动确认后调用
- Search Agent 查询理解：`ChatGPT-5.6:light`
- Search Agent 结果简报、搜索追问、论文对话：`ChatGPT-5.6:fast`
+- 默认摘要模型：`ChatGPT-5.6:Terra`
+- 默认翻译模型：`ChatGPT-5.6:Luna`
+- 深度分析模型：`ChatGPT-5.6:Sol`，只在前端手动选择时使用
+- Atlas 解释：`ChatGPT-5.6:Terra`
+- 主题导读、阅读路径、主题比较：`ChatGPT-5.6:Sol`，只在前端手动确认后调用
+- Search Agent 查询理解：`ChatGPT-5.6:Luna`
+- Search Agent 结果简报、搜索追问、论文对话：`ChatGPT-5.6:Terra`
 - Ollama 请求单并发执行，并缓存结果到 `web/cache/ai/`
 - 应用侧不下发 `num_ctx` / `keep_alive`，上下文长度和模型常驻由 Ollama 服务端统一控制
 - arXiv 摘要缓存到 `web/cache/arxiv/`

+模型 tier 可以覆盖：
+
+```bash
+OLLAMA_MODEL_LIGHT=ChatGPT-5.6:Luna \
+OLLAMA_MODEL_FAST=ChatGPT-5.6:Terra \
+OLLAMA_MODEL_LARGE=ChatGPT-5.6:Sol \
+web/manage.sh restart
+```
+
+`/api/health` 会返回可用模型、默认模型和缺失的默认标签。维护时先看健康接口，不要假设旧 alias 仍存在。
+
+## Service Management
+
+```bash
+web/manage.sh start
+web/manage.sh stop
+web/manage.sh restart
+web/manage.sh status
+web/manage.sh logs
+```
+
+`manage.sh` 会把仓库中的 `agent-knowledge-atlas.service` 链接到用户级 systemd，并把可覆盖环境写入忽略提交的 `web/cache/service.env`。日志使用 systemd journal。它不替代 TLS、反向代理或鉴权。
+
 ## Knowledge Design

 先由后端从本地语料轻量计算：
@@ -62,3 +92,7 @@ https://lab.k1412.top/
 - 搜索意图理解、关键词扩展、结果简报
 - 基于搜索结果继续追问
 - 基于单篇论文继续对话式研读
+
+## Product Boundary
+
+当前 Atlas 是资料探索原型，不是已经验证的学习产品。用户对“只浏览论文、图谱和 AI 摘要”的实用性评价很低，因为它没有保存个人理解、主张、反证、应用和复习状态。后续产品方向见 `docs/08-next-work.md`，不要把下一阶段继续收敛为图谱视觉优化。