文档:整理项目规则与当前开发说明

This commit is contained in:
2026-11-12 22:00:52 +08:00
parent bc19475b29
commit 48ae58e577
5 changed files with 102 additions and 6 deletions
+13 -4
View File
@@ -9,6 +9,13 @@
- 公网入口:[https://quality.lyunlab.me](https://quality.lyunlab.me)。服务器提供前端静态页面和 HTTPS;API 经 SSH 加密回连到本机后端。
- MySQL、模型凭据、业务来源文件和运行数据保存在本机,不包含在本仓库中。本机需保持开机联网且项目服务运行,其他电脑才能使用完整功能。
## 开发入口
- [项目规则](AGENTS.md):本项目的业务约束、代码入口和验证选择,配合全局使用习惯执行。
- [当前进度](docs/当前进度.md):最近核实的代码、验证、部署状态及待办;跨会话继续时先核对实际状态。
- [智能分析接入](docs/DeepSeekHarness正式接入.md):当前 DSH、模型原文、报告、图表与平台边界。
- `开发交付说明.md` 及带日期的实施、验收文档保留为历史证据;其中早期数据范围、运行方式和功能状态不能直接视作当前状态。本地交付说明及被 Git 排除的验收资料不随源码同步。
## 本机运行
Linux 容器部署、自动重启、空间回收、备份保留及容量告警见 [Docker 部署说明](deploy/docker/README.md)。这些配置随源码进入 Gitea;构建镜像使用手动入口,不要求配置 Gitea 自动构建。Mac 测试服务的开机启动与守护见 [本机服务说明](deploy/macos/README.md)。
@@ -19,7 +26,9 @@ Linux 容器部署、自动重启、空间回收、备份保留及容量告警
pnpm --dir web install --frozen-lockfile
python3 scripts/project.py build
随后运行:
上述安装、构建及下列启动命令用于独立开发环境。当前共享测试服务已由守护程序运行;日常检查使用 `python3 deploy/macos/service.py status`。维护共享服务前先阅读本机服务说明,不在端口已被占用时重复启动,旧停止命令也不能替代守护管理。
独立开发环境随后运行:
python3 scripts/project.py start
@@ -35,11 +44,11 @@ Linux 容器部署、自动重启、空间回收、备份保留及容量告警
在系统设置中配置本机模型。设置保存在私有的 `.runtime/nao-model-config.json`;旧版根目录 `apikey.txt` 只作为未配置时的兼容入口,严禁提交任一凭据文件。
AI 助理使用固定的 Python 3.11.15、nao-core 0.3.26 和带哈希的 `requirements-nao.lock`。首次运行依赖安装命令会一并安装 AI 环境;已有环境只检查,不覆盖正在运行的会话。可单独运行 `python3 scripts/setup_nao_runtime.py --check` 检查版本、导入和原生服务器。检查不会调用模型。明确不使用 AI 时,可使用 `setup_runtime.py --without-ai`;需要 AI 时再运行 `setup_nao_runtime.py`。
项目保留固定的 Python 3.11.15 和旧 nao 依赖安装入口;`requirements-nao.lock` 中的 nao-core 0.3.26 属于兼容源码环境,不代表当前正式分析引擎。总安装器仍会准备这些依赖及 DSH;`--without-ai` 仅准备 Java/数据库环境,`--without-dsh` 不是可用的正式智能分析部署方式。已有环境不得为更新说明而覆盖或中断运行中的会话。
质量智能分析现统一使用 DeepSeek Harness(DSH),正式入口为 `scripts/quality_analysis_runtime.py`。API 配置只管理模型、端点和思考选项,分析引擎固定为 DSH。运行时保留模型原始回答;正常问题直接对话,仅在明确要求时生成报告。会话按页加载并通过同一事件流更新,图表支持 Top100;图表转换和加载失败时静默省略,后台保留诊断。
质量智能分析固定使用 DeepSeek Harness(DSH)。API 配置管理模型、端点和思考设置,不提供 NAO/DSH 切换。Java 管理身份、授权、正式指标及历史,DSH 执行工具循环;模型正文原样保存,普通问题直接回答,只有明确要求时生成报告。图表失败时静默省略,后台保留诊断。
DSH CLI 固定为 `0.2.2-rc.1`,依赖与官方 Python SDK 校验记录在 `runtime/dsh/`。可运行 `python3 scripts/setup_dsh_runtime.py --node /path/to/node24` 安装项目内运行环境,`--check` 检查真实启动且不调用模型。`scripts/build_dsh_application.py` 构建独立的 DSH 应用目录。当前系统隔离与正式服务已在 macOS 验证;Linux/Windows 等效隔离未完成验收时明确拒绝启动。接入方式和边界见 [正式接入说明](docs/DeepSeekHarness正式接入.md)。
DSH CLI 固定为 `0.2.2-rc.1`,依赖与官方 Python SDK 校验记录在 `runtime/dsh/`,要求 Node 24.9+。可运行 `python3 scripts/setup_dsh_runtime.py --node /path/to/node24` 安装项目内运行环境,`--check` 检查真实启动且不调用模型。`scripts/build_dsh_application.py` 构建独立应用,正式运行包使用其中的 `scripts/quality_analysis_runtime.py`;根目录同名源码仍有双引擎兼容逻辑,不能据此推断线上支持切换。当前系统隔离与正式服务在 macOS 验证;Linux/Windows 等效隔离未验收时明确拒绝 DSH 启动。详见[正式接入说明](docs/DeepSeekHarness正式接入.md)。
## 旧版本时间迁移