docs: 添加智能体交接手册（含服务/凭证/故障排查）

智能体交接手册.md

@@ -0,0 +1,374 @@
+# 栖云数字城堡 · 智能体交接手册
+
+> 本手册专为**新接手智能体**编写，读完本手册应能独立完成日常运维和故障排查。
+> 冯先生（用户）—— 90后四级副职培训班学员，严肃交易者，西安。
+> 最后更新：2026-06-25
+
+---
+
+## 一、核心身份信息
+
+| 信息 | 内容 |
+|:---|:---|
+| 称呼 | 冯先生 |
+| 城市 | 西安 |
+| 教育 | 上海交通大学 MEM（非全日制，在读） |
+| 职业 | 国网陕西电力（工会+安全相关） |
+| 交易风格 | 价格行为学，ETH/USDT 永续，1x 杠杆，中低频，趋势+波段 |
+| 培训 | 90后四级副职培训班（6周分段式，非"浙大培训"） |
+
+### 冯先生的铁律（不可违反）
+
+1. **Token 头号杀手** — 所有下载/安装/批量操作必须重定向 stdout/stderr，禁止进度条、安装日志、大文件输出进入对话
+2. **本地大模型只在 D 盘** — 不碰 C 盘，不移动模型文件
+3. **删除任何文件前必须请示**
+4. **不碰防火墙/安全组**
+
+---
+
+## 二、服务器清单与访问
+
+### 东京服务器（主力）
+
+| 项目 | 值 |
+|:---|:---|
+| 公网 IP | 43.163.225.30 |
+| 内网 IP (Tailscale) | 100.111.102.100 |
+| 用户 | ubuntu |
+| SSH 密钥 | `C:\Users\32779\Desktop\保险箱\ssh_new.pem` |
+| SSH 命令 | `ssh -i "密钥路径" ubuntu@43.163.225.30` |
+| 规格 | 2C/4G |
+| 角色 | Caddy 网关、Gitea、Memos、freqtrade、audiobookshelf、WebDAV、SS 代理 |
+| 主机名 | vm-4-13-ubuntu |
+
+### 北京服务器（知识库+备份）
+
+| 项目 | 值 |
+|:---|:---|
+| 公网 IP | 81.70.93.78 |
+| 内网 IP (Tailscale) | 100.104.225.62 |
+| 用户 | ubuntu |
+| SSH 密钥 | `C:\Users\32779\Desktop\保险箱\BJ.pem` |
+| 规格 | 2C/4G |
+| 角色 | Meilisearch（7700）、QA API（8100）、备份存储 |
+| SSH 到东京密钥 | `~/.ssh/tokyo_key.pem`（放在北京服务器上） |
+
+### 本机（Windows）
+
+| 项目 | 值 |
+|:---|:---|
+| Tailscale IP | 100.99.151.78 |
+| 主机名 | fxy |
+| Python | `C:\Users\32779\.workbuddy\binaries\python\envs\default\Scripts\python.exe` |
+| Git Bash | `/c/Users/32779/.workbuddy/binaries/python/envs/default/Scripts/python.exe` |
+
+---
+
+## 三、Gitea 仓库清单
+
+所有仓库在 **fxy** 用户下，访问：`gitea.xybkwd.top`
+
+**Git Push URL 格式**：
+```
+http://beast:bb731ed7d0d267b98a1c7d082de6c8fc0329ac21@localhost:3000/fxy/<repo名>.git
+```
+*注：`localhost:3000` 指东京服务器内网的 Gitea 端口，本地机不可直连，需通过 SSH 到东京操作。*
+
+### 仓库列表
+
+| 仓库名 | 说明 | 关键词 |
+|:---|:---|:---|
+| `server-ops` | 服务器运维、配置归档、**全景架构手册**、CHANGELOG | **新智能体首先阅读** |
+| `nav-page` | 导航页前端（`nav.xybkwd.top`） | 知识库搜索/问答界面 |
+| `dashboard` | 控制面板（`dashboard.xybkwd.top`） | freqtrade 状态、策略切换 |
+| `qiyun-portal` | 栖云个人门户 |
+| `todo-system` | 待办系统 |
+| `daily-brief` | **新闻管线**（国内/国际/政策/研报/行情） |
+| `inspiration-collector` | 灵感收集器、AI 日报/周报、Memos 同步 |
+| `weread-notes` | 微信读书笔记、阅读日报 |
+| `work-docs` | 冯先生的工作文档归档 |
+| `qa-archive` | 知识库问答记录归档（自动同步） |
+| `freqtrade-strategies` | 交易策略 |
+| `beast-trader-strategies` | Beast Trader 策略 |
+| `boox-notes` | BOOX 阅读笔记 |
+| `ebook-library` | 电子书库 |
+| `obsidian-vault` | Obsidian 笔记库 |
+| `culture-sports` | 文体部 |
+| `qa-archive` | 问答记录归档 |
+
+---
+
+## 四、域名与服务
+
+所有服务统一域名 `*.xybkwd.top`，经 **Caddy**（东京 `/etc/caddy/Caddyfile`）反向代理。
+需要认证的域名由 `auth.xybkwd.top`（端口 9002）统一管理。
+
+### 4.1 核心服务
+
+| 域名 | 服务 | 端口 | 后端 | 需认证 |
+|:---|:---|:---:|:---|:---:|
+| nav.xybkwd.top | 导航页 + 知识库搜索/问答 | 静态 | `nav-page` 前端 | ✅ |
+| auth.xybkwd.top | 统一登录 | 9002 | Tokyo auth_proxy | — |
+| gitea.xybkwd.top | Git 仓库 | 3000 | Docker gitea | ✅ |
+| dashboard.xybkwd.top | 控制面板 | 9000 | `dashboard` 前端 | ✅ |
+| memo.xybkwd.top | 备忘录 | 5230 | Docker memos | — |
+| search.xybkwd.top | 搜索 | →8100 | → Beijing:8100 | ✅ |
+
+### 4.2 内容服务
+
+| 域名 | 服务 | 端口 |
+|:---|:---|:---:|
+| brief.xybkwd.top | 每日简报 | 静态文件 |
+| books.xybkwd.top | 在线阅读（Calibre-Web） | Docker 8083 |
+| podcast.xybkwd.top | 播客（Audiobookshelf） | Docker 13378 |
+| www.xybkwd.top | 主站（Halo） | Docker 8090 |
+
+### 4.3 同步/存储/工具
+
+| 域名 | 服务 | 端口 |
+|:---|:---|:---:|
+| dav.xybkwd.top | WebDAV 日记同步 | Docker 8766 |
+| vault.xybkwd.top | 密码管理（Vaultwarden） | Docker 8088（仅 127.0.0.1） |
+| ss.xybkwd.top | Shadowsocks 代理订阅 | 静态文件 |
+
+### 4.4 本机 Docker 服务（通过 Tailscale 访问）
+
+| 服务 | 端口 | 位置 |
+|:---|:---:|:---|
+| Immich（照片管理） | 2283 | `D:\immich\`，Docker |
+| Ollama 本地模型 | 11434 | 本机服务 |
+
+---
+
+## 五、数据流
+
+### 5.1 知识库备份（东京 → 北京）
+
+```
+东京 /home/ubuntu/ 下的 repos + configs
+  ↓ 每天凌晨 3:00 rsync（由北京 backup_tokyo_to_beijing.sh 触发）
+北京 /home/ubuntu/backups/tokyo/
+  ├── repos/          ← 最新的裸仓库
+  ├── repos_working/  ← 工作副本
+  ├── gitea_data/     ← 7轮滚动备份
+  └── configs/
+```
+
+### 5.2 知识库索引（北京）
+
+```
+北京 /home/ubuntu/backups/tokyo/repos/
+  ├── inspiration-collector/ai-insights/daily/
+  ├── weread-notes/notes/
+  ├── weread-notes/daily/
+  └── work-docs/
+      ↓ 每天凌晨 4:10（indexer.py）
+Meilisearch（北京:7700）
+```
+
+### 5.3 问答归档（北京 → 东京 Gitea）
+
+```
+用户提问 → kb_server.py（北京:8100）
+  ↓ 实时
+.md 文件写入北京 /home/ubuntu/kb/qa-archive/
+  ↓ 每 30 分钟
+Tokyo rsync 拉取 → git commit → git push → Gitea fxy/qa-archive
+```
+
+### 5.4 新闻管线（东京）
+
+| 时间 | 脚本 | 内容 |
+|:---:|:---|:---|
+| 每天 2/8/14/20 点 | `fetch_tencent_news.py` | 腾讯新闻 |
+| 每天 2/8/14/20 点 | `fetch_domestic_politics.py` | 国内时政 |
+| 每天 3/9/15/21 点 | `fetch_news.py` | 国际新闻 |
+| 每天 3/9/15/21 点 | `fetch_policy.py` | 政策 |
+| 每天 3/9/15/21 点 | `fetch_research.py` | 研报 |
+| 每小时 | `fetch_market.py` | 行情 |
+| 3/9/15/21 点+5分 | `cn_merge.py` | 汇总精选 80 条 |
+| 22:40 | `archive_daily_brief.py` | 归档到 Gitea |
+| 23:50 | `fetch_market_daily.py` | 指数/汇率/数字货币 |
+| 22:00 | `run_daily_digest.sh` | 灵感日报 |
+| 22:00 | `run_daily_work_report.sh` | 工作日报 |
+| 周日 8:30 | `run_weekly_reading_report.sh` | 阅读周报 |
+| 周日 9:00 | `run_weekly_work_report.sh` | 工作周报 |
+
+---
+
+## 六、知识库 RAG 问答
+
+### 架构
+
+```
+浏览器 nav.xybkwd.top/search.html
+  ├─ 搜索 → /search-api/* → Caddy（东京）→ Beijing:7700（Meilisearch）
+  └─ 问答 → /api/ask → Caddy（东京）→ Beijing:8100（kb_server.py）
+                                    ├─ Meilisearch 检索（3 搜索词 × 6 篇，去重得 top 12）
+                                    └─ DeepSeek API → 基于资料回答
+```
+
+### 关键参数
+
+| 参数 | 值 |
+|:---|:---|
+| Meilisearch API | `http://localhost:7700`（北京） |
+| 索引名 | `knowledge` |
+| API Key | `m42-s8k-xybkwd-search-2026` |
+| DeepSeek Key | `sk-bbca4a0380d549389f0d27cdea0b5228` |
+| 模型 | `deepseek-v4-flash` |
+| 单次成本 | ≈ ¥0.02 |
+| 服务名 | `kb-qa`（systemd，端口 8100） |
+| 北京安全组 | 需开放 7700、8100 给东京 IP |
+
+**铁律**：AI 仅从 Meilisearch 索引内容回答，不访问互联网。不知道说不知道。
+
+---
+
+## 七、Tailscale VPN
+
+| 节点 | IP | 系统 |
+|:---|:---|:---:|
+| 东京 vm-4-13-ubuntu | 100.111.102.100 | Linux |
+| 北京 vm-0-12-ubuntu | 100.104.225.62 | Linux |
+| 本机 fxy | 100.99.151.78 | Windows（与北京 direct 连接） |
+
+- 版本：1.98.4
+- 用户：fengxy07@
+
+---
+
+## 八、本机本地工具
+
+### Ollama
+
+| 项目 | 值 |
+|:---|:---|
+| API | `http://localhost:11434` |
+| 模型 | `qwen3.5:9b`（6.3GB，IQ4_NL 量化） |
+| 模型路径 | `D:\ollama\model_data\models\` |
+| 调用 | `ollama run qwen3.5:9b` |
+| API 调用 | `curl http://localhost:11434/api/generate -d '{"model":"qwen3.5:9b","prompt":"...","stream":false}'` |
+| 上下文 | 65536 tokens |
+
+**踩坑**：Ollama pull 需清除代理 `HTTP_PROXY=""`；桌面端和 CLI 抢端口 11434；路径用 Windows 反斜杠。
+
+### Word/PDF → Markdown 工具
+
+- `DocFormatter.exe`（桌面，11MB，独立 exe，无需 Python）
+- 功能：doc2md 转换 + Ollama 去水印/规整排版
+- 输出目录可选，保留子目录结构
+
+### A股数据工具
+
+| 数据 | 方法 |
+|:---|:---|
+| K线/财务 | mootdx TCP 7709（首选，不限速） |
+| 龙虎榜/解禁/融资融券/大宗 | `datacenter-web.eastmoney.com`（本机可直连） |
+| 东财其他 | `push2.eastmoney.com` ❌ TLS 失败，走 WebFetch |
+| 实时行情 | `qt.gtimg.cn`（腾讯） |
+
+---
+
+## 九、Docker 服务（东京）
+
+| 容器 | 端口 | 状态 |
+|:---|:---:|:---:|
+| memos | 5230 | 运行 13 天 |
+| halo | 8090 | 运行 13 天 |
+| vaultwarden | 8088（仅本机） | 健康运行 11 天 |
+| calibre-web | 8083 | 运行 10 天 |
+| webdav | 8766 | 运行 8 天 |
+| freqtrade | 8081 | 运行 6 天 |
+| freqtrade-swing | 8082 | 运行 6 天 |
+| audiobookshelf | 13378 | 运行 4 天 |
+
+**重启顺序**：数据依赖的服务（postgres/redis）→ 应用服务。重启请用 `docker restart <容器名>`。
+
+---
+
+## 十、故障排查速查
+
+### 如果用户说"网站打不开"
+1. 查 Caddy：`ssh 东京 && sudo systemctl status caddy`
+2. 查对应 Docker 容器是否运行：`docker ps | grep <服务名>`
+3. 查端口监听：`ss -tlnp | grep <端口>`
+4. 最严重情况：**检查是否有人误开防火墙/安全组**。UFW 绝对禁用。
+
+### 如果用户说"知识库搜不到"
+1. 查北京索引器：`ssh 北京 && ls /home/ubuntu/backups/tokyo/repos/work-docs/`
+2. 手动触发索引：`ssh 北京 && cd /home/ubuntu/kb && python3 indexer.py`
+3. 查 Meilisearch：`curl http://localhost:7700/health`
+
+### 如果用户说"问答不回复"
+1. 查北京 QA 服务：`ssh 北京 && sudo systemctl status kb-qa`
+2. 查日志：`ssh 北京 && sudo journalctl -u kb-qa --no-pager -n 20`
+3. 查 DeepSeek API Key 是否有效
+
+### 如果用户说"问答没归档"
+1. 查北京归档文件：`ssh 北京 && ls /home/ubuntu/kb/qa-archive/2026-06/`
+2. 查东京同步：`ssh 东京 && ls /tmp/qa-archive/2026-06/`
+3. 手动同步：`ssh 东京 && /home/ubuntu/scripts/sync_qa.sh`
+
+### 如果 Ollama 不工作
+1. 查服务：`curl http://localhost:11434/api/tags`
+2. 查模型列表：`ollama list`
+3. 常见原因：桌面版抢占端口 11434，退出桌面版重试
+
+---
+
+## 十一、踩坑汇总（新智能体必读）
+
+| # | 坑 | 症状 | 修复 |
+|:---:|:---|:---|:---|
+| 1 | Caddy `handle_path` | API 代理路径不对 | 用 `@matcher` + `handle @matcher` |
+| 2 | Caddy 规则顺序 | `/api/ask` 被 `/api/*` 拦截 | 精确匹配放前面 |
+| 3 | 服务监听 127.0.0.1 | 跨服务器连不上 | 改 `0.0.0.0` |
+| 4 | `rsync --delete` | 删掉 .git 目录 | 同步到 Git 仓库时去掉 `--delete` |
+| 5 | Ollama pull 被代理阻断 | 下载失败 | `HTTP_PROXY=""` 清除后再 pull |
+| 6 | 模型默认上下文 4096 | 长文本被无声截断 | 设 `OLLAMA_CONTEXT_LENGTH=65536` |
+| 7 | Windows Python 编码 | 中文输出乱码 | 加 `PYTHONIOENCODING=utf-8` |
+| 8 | Git Bash 路径 | Windows 下路径不识别 | 用绝对路径调用 Python |
+| 9 | UFW 防火墙 | 启用后所有服务崩溃 | **绝对不碰防火墙**，通过云控制台安全组管理 |
+| 10 | 助理模式覆盖 | 已有功能被助理模式覆盖 | 涉及 `search.html` 等前端文件时做好备份 |
+
+---
+
+## 十二、关键路径与凭证位置
+
+| 资源 | 位置 |
+|:---|:---|
+| 东京 SSH 密钥 | `C:\Users\32779\Desktop\保险箱\ssh_new.pem` |
+| 北京 SSH 密钥 | `C:\Users\32779\Desktop\保险箱\BJ.pem` |
+| Gitea 访问 | `gitea.xybkwd.top`（需认证） |
+| Gitea API | `http://beast:bb731e...@localhost:3000/api/v1/`（东京内网） |
+| Caddy 配置 | 东京 `/etc/caddy/Caddyfile` |
+| 北京备份脚本 | `backup_tokyo_to_beijing.sh` |
+| 知识库索引器 | 北京 `/home/ubuntu/kb/indexer.py` |
+| QA API 服务 | 北京 `/home/ubuntu/kb/kb_server.py` / systemd `kb-qa` |
+| 新闻管线脚本 | 东京 `/home/ubuntu/scripts/` |
+| cron 任务 | 东京 `crontab -l -u ubuntu` |
+| 北京→东京 SSH 密钥 | 北京 `~/.ssh/tokyo_key.pem` |
+| 全景架构手册 | Gitea `fxy/server-ops/栖云数字城堡_全景架构手册.md` |
+| 工作空间记忆 | 本机 `C:\Users\32779\.workbuddy\MEMORY.md` |
+| 本机项目目录 | `C:\Users\32779\WorkBuddy\2026-06-20-00-28-14\` |
+
+---
+
+## 十三、关于冯先生的重要背景
+
+- 正在参加 **90后四级副职培训班**（不是"浙大培训"），六周分段式：
+  1. 渭南党校
+  2. 延安干部学院
+  3. 清华大学
+  4. 太行春天
+  5. 浙江大学
+  6. 渭南党校（即将）
+- 交易品种：ETH/USDT 永续合约，1x 杠杆
+- 交易平台：freqtrade + Binance
+- 写作中不准笼统称"浙大培训"，要称"90后四级副职培训班"或标注具体地点
+
+---
+
+*本手册由 WorkBuddy 于 2026-06-25 生成，内容基于全景架构手册 + 工作空间记忆 + 服务器实时状态。*
+*建议每次基础设施变更后同步更新。*