guanwei 1.3.2 → 1.3.5

package/README.md

@@ -15,7 +15,7 @@
   <a href="https://github.com/RubyCcll/guanwei/releases"><img src="https://img.shields.io/github/v/release/RubyCcll/guanwei" alt="Release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9c4a2f" alt="MIT License"></a>
   <a href="https://github.com/RubyCcll/guanwei"><img src="https://img.shields.io/badge/TypeScript-5.8-3178c6" alt="TypeScript"></a>
-  <a href="https://github.com/RubyCcll/guanwei/issues"><img src="https://img.shields.io/badge/tests-181-brightgreen" alt="Tests"></a>
+  <a href="https://github.com/RubyCcll/guanwei/issues"><img src="https://img.shields.io/badge/tests-278-brightgreen" alt="Tests"></a>
 </p>
 
 <p align="center">
@@ -25,6 +25,8 @@
 
 > 占问所得，仅供修身养性、怡情遣兴之用，不构成任何决策依据。
 
+> **定位**：**自托管工具** —— 排盘与 AI 解读都跑在你自己机器上，档案与起占记录只落本地（`~/.guanwei/data`）；项目方不提供托管服务，**不采集任何遥测、不上报使用数据**。
+
 ## ▶️ 立即体验（无需注册 · 无需配置 · 无需 API Key）
 
 <p align="center">
@@ -56,7 +58,7 @@
 - 起占结果由后端计算并**持久化入库**（SQLite），六爻摇卦、塔罗抽牌等交互结果同样后端定稿
 
 ### AI 深度解读
-- **9 术角色化解读**：每术独立 persona（紫微：命盘结构 → 星曜落宫 → 十二宫 → 大限流年 → 人生阶段），技能清单单轮注入（多 Agent 编排规划中，接入后作为 guanwei-pro 模式，见 ROADMAP）
+- **9 术角色化解读**：每术独立 persona（紫微：命盘结构 → 星曜落宫 → 十二宫 → 大限流年 → 人生阶段）；**紫微已支持三步深度编排**（`orchestrate: "ziwei-deep"`：三次独立推理后汇总，guanwei-pro 雏形），其余八术为单轮 persona 注入
 - **双轨 Schema**：命盘类（原始解读/性格/原生家庭/心智模式/人生阶段/事业/爱情/财富/健康）、占问类（现状/趋势/时机）
 - **盘面事实一致性约束**：AI 必须逐字引用排盘数据，不得编造；后端**六亲宫位事实校验 + 矛盾定向修正**（宫位地支/主星/借星/生年四化）
 - **解读稳定性**：Step1 盘面解析缓存复用、低温采样、论断锚定（主观程度词必须有盘面依据）、去重与字数预算
@@ -122,7 +124,28 @@ curl -X POST http://127.0.0.1:3020/v1/chart -H "Content-Type: application/json"
 curl http://127.0.0.1:3020/v1/arts             # 九术能力清单 + 参数 schema
 ```
 
-> 排盘免费（纯计算零 token）；协议风格与未来托管 API 一致（/v1、统一错误码），本地自部署与第三方集成同源。
+> 排盘免费（纯计算零 token）；`/v1` 协议与统一错误码便于本地集成与二次开发。
+>
+> 安全默认：服务只绑 `127.0.0.1` 并内置 per-IP 限流（默认 120 次/分，`GUANWEI_API_RATE_MAX` 可调）、SSE 连接上限与闲置回收。
+> 如需公网/局域网暴露：`GUANWEI_API_HOST=0.0.0.0 npm start`，并请自行加反向代理与更严格的网关限流。
+> Docker 用户可用 `docker compose --profile api up -d` 启动该服务（容器内自动置 `GUANWEI_API_HOST=0.0.0.0`）。
+
+#### 想让它被外部调用（内网/公网试跑）？
+
+默认只绑 `127.0.0.1`，必须显式放开：
+
+```bash
+GUANWEI_API_HOST=0.0.0.0 GUANWEI_API_RATE_MAX=60 npm start    # packages/guanwei-api
+```
+
+- **限流兜底**：per-IP 桶（默认 120/分，可调）、SSE 连接上限与闲置回收、429 带 `Retry-After`
+- **只要计数、不采隐私**：仅本机可读的使用计数（无 IP / 无参数 / 无载荷），`GUANWEI_API_STATS=0` 可完全关闭
+
+```bash
+curl http://127.0.0.1:3020/v1/stats     # {"total":…, "byEndpoint":{"/v1/chart":…}, "byDay":{…}}
+```
+
+- **公网务必**在前置反代加网关鉴权（Nginx basic auth / Authelia / Cloudflare Access 等）与更严格的限流
 
 ## 🚀 快速开始（一行命令）
 
@@ -184,7 +207,7 @@ guanwei start
 
 镜像：`ghcr.io/rubyccll/guanwei-guanwei-web` / `guanwei-guanwei-backend`；端口冲突时 `WEB_PORT=5180 API_PORT=3020 docker compose up -d` 覆盖。也可直接 `docker pull ghcr.io/rubyccll/guanwei-guanwei-web:latest`。
 
-#### 方式六：本地 Node.js（≥ 22.5，需 node:sqlite 内置支持）
+#### 方式六：本地 Node.js（≥ 22.13.0，需 node:sqlite 内置支持）
 
 ```bash
 ./scripts/setup.sh                    # 交互式：选服务商 + 输入 Key
@@ -225,10 +248,26 @@ guanwei stop                 # 停止（docker 模式）
 
 ### 测试
 ```bash
-npm test                 # 181 项测试（核心引擎/渲染/交互/存储/流程/提示词）
+npm test                 # 278 项测试（含九术引擎对权威库的交叉验证）
 cd server && npx tsx scripts/divineStoreSmoke.ts   # SQLite 存储冒烟
 ```
 
+## 🔬 与权威实现的交叉验证
+
+排盘结果不靠自述——九术引擎的关键算法都与**外部权威实现**逐项对拍，且全部可在本仓复跑（`npx vitest run`；未装 `pyswisseph` 时星历两组自动跳过）：
+
+| 验证面 | 权威源 | 案例规模 | 断言 |
+|---|---|---|---|
+| 星盘行星 / 上升 / 中天 | **Swiss Ephemeris**（瑞士星历） | 8 时空 × 7 古典行星 | 黄经 ≤0.05°、上升/中天 ≤0.1° |
+| 节气时刻（定年月柱、奇门定局、六壬月将的共同地基） | Swiss Ephemeris 太阳视黄经过宫（二分求根） | 3 年 × 24 节气 | 与历表差 ≤90 秒 |
+| 八字四柱 / 胎元 / 命宫 / 身宫 / 大运 | **lunar-typescript** `EightChar`（sect2） | 10 案例（含立春分钟级边界、晚子时） | 全字段一致，大运序列对齐 |
+| 紫微宫位 / 十四主星 / 辅星 / 亮度 | **iztro** 2.6.0 | 24 案例 × 14 星（含闰月分界、晚子时、正月初一） | 零差异 |
+| 奇门阴阳遁 / 局数 / 五层盘（地盘天盘八门九星八神） | **qimen-dunjia** 3.1.0（拆补法） | 19 案例 × 逐宫 | 全对齐（含夜子时） |
+| 六壬月将（中气定将） | Swiss Ephemeris 太阳视黄经 30° 分段 | 12 中气 × 前后 6 小时 + 全年 24 时刻 | 与过宫时刻一致 |
+| 六爻纳甲 / 世位 / 六神 | 京房八宫递变 + 上下经卦纳甲**独立推导** | 64 卦 + 200 次摇卦 | 全对齐 |
+
+> 交叉验证抓到过的真实缺陷（均已修复并有回归）：六爻「宫纳甲」误用致 56/64 卦装卦错、奇门夜子时日柱少进一日、节气时刻在 1986–1991 夏令时窗口系统性偏 1 小时、六十四卦「地水师/水地比」上下卦写反、紫微亮度表整体失真。
+
 ## 📁 目录结构
 
 ```
@@ -236,24 +275,41 @@ cd server && npx tsx scripts/divineStoreSmoke.ts   # SQLite 存储冒烟
 ├── server/
 │   ├── src/
 │   │   ├── routes/      # divine（排盘）/ ai（解读）/ users / hour（时辰反推）
-│   │   └── services/    # promptBuilder / llmProvider / divineStore / hourInference / relativesCheck / sixRelatives
-│   ├── data/            # SQLite 与用户数据（gitignore）
+│   │   └── services/    # db（统一 SQLite）/ usersStore / divineStore / promptBuilder / llmProvider / dataDir / auth
 │   └── .env.example
 ├── shared/core/         # 前后端共用引擎（排盘算法/数据，单一副本）
-├── scripts/             # setup.sh（一键配置）/ guanwei（CLI）/ release.sh（发版）/ setup.bat（Windows）
+├── packages/guanwei-api/# 开放 API（REST /v1 + MCP）
+├── scripts/             # setup.sh / guanwei（CLI）/ release.sh / preflight-release.sh / check-*.mjs
 ├── deploy/              # nginx 配置（Docker 部署）
 ├── .devcontainer/       # GitHub Codespaces 模板
 ├── Dockerfile.web / Dockerfile.server / docker-compose.yml
-├── docs/                # 开源素材（banner/截图/GIF/示例报告）
+├── docs/assets/         # 对外素材（banner/截图/GIF/示例报告）
+├── internal/            # 内部文档（规划/监控/SOP/草稿）——**仅本地，git 忽略，永不公开**
 └── tests/               # 测试（含回归集）
 ```
 
+### 公开区 / 内部区约定（重要）
+
+| 区域 | 位置 | 是否公开 |
+|---|---|---|
+| 源码与测试 | `src/` `server/src/` `shared/` `packages/` `tests/` `scripts/` | 公开（git + npm 包） |
+| 对外素材 | `docs/assets/` | 公开（仅 GitHub 展示，不进 npm 包） |
+| 内部文档 | `internal/` | **仅本地**（git 全目录忽略；请勿把内部内容放进公开区） |
+| 运行时数据 | `~/.guanwei/data`（`GUANWEI_DATA_DIR` 可覆盖） | **永不公开**（物理隔离于项目树之外） |
+
+发布前自检：`./scripts/preflight-release.sh` —— 依次校验仓库边界、npm 包内容（文件名 + 内容级扫描）、类型、全量测试、版本一致性；CI 与 release 流水线同样内置边界与包内容守卫。
+
 ## 🔐 安全说明
-- 所有密钥仅存于本地 `server/.env`（已 gitignore），仓库只提供 `.env.example` 模板；Docker 镜像构建已排除 `.env`（.dockerignore）
-- 密码哈希使用 **scrypt（带随机盐）**，登录时兼容升级存量旧哈希
+- **鉴权**：已内置 token 鉴权（`X-Guanwei-Token`，30 天滚动过期）+ scrypt（随机盐）密码哈希；档案/记录/详情接口均校验归属，归属不符统一 404（不泄露资源存在性）
+- **默认最小暴露**：后端默认只绑 `127.0.0.1`（容器/局域网用 `HOST=0.0.0.0` 显式放开）；开放 API 默认只绑本机并内置 per-IP 限流；CORS 默认仅本机来源
+- **限流**：`/api/ai` 30/分、起占 60/分、登录/注册 10/分、其余计算端点 120/分（`GUANWEI_RATE_*` 可调）；反代下通过 `trust proxy` 取真实客户端 IP
+- **密钥**：仅存于本地 `server/.env`（已 gitignore），仓库只提供 `.env.example` 模板；Docker 构建排除 `.env`；发布流水线有内容级扫描（密钥形态命中即拒绝发布）
+- **数据隔离**：运行时数据（用户档案 + 占卜记录）默认在 `~/.guanwei/data`，位于项目树之外——npm/Docker 构建上下文物理上取不到；`scripts/check-boundary.mjs` 与 `scripts/check-package.mjs` 在 CI/发布前双重把关
+- **统一存储**：账号、占卜记录、AI 失败留档同处一个 SQLite 库（`guanwei.db`，WAL + `BEGIN IMMEDIATE` 事务），并发注册/建档不会互相覆盖；1.3.4 及更早版本遗留的 JSON 用户库（`db.json`）在首次启动时一次性导入（原文件保留可回滚）
+- **隐私**：出生信息与人生经历会发送给所配置的 LLM 服务商用于生成解读；如需完全离线，请仅使用本地排盘能力（不调用 `/api/ai/*`）
 - AI 报告质量门槛：结构评分不达标不入库，自动留档供改进提示词
 - 测试数据全部虚构/匿名化，不含真实用户隐私；真实案例仅存本地（git 忽略）
-- ⚠️ **部署边界（务必知晓）**：本项目定位为「本地/内网自部署」工具，**未内置登录鉴权体系**——用户身份仅靠传入的 username 区分，知道用户名即可读取该用户档案（`GET /:username/profile` 无口令校验）。**请勿直接暴露到公网**；如需公网访问，必须在前面架设反向代理 + 网关鉴权（如 Nginx basic auth / Authelia / Cloudflare Access 等），或在应用层另行加固。
+- ⚠️ **部署边界**：默认配置面向「本地/内网自部署」。若需公网访问，请在前置反向代理上加网关鉴权（Nginx basic auth / Authelia / Cloudflare Access 等），并显式设置 `GUANWEI_ALLOWED_ORIGINS` 与更严格限流。
 
 ## 📄 示例输出