From 48ae58e5771ce3e4897878fe800513dc78d986f2 Mon Sep 17 00:00:00 2001 From: lyun Date: Thu, 12 Nov 2026 22:00:52 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E6=95=B4=E7=90=86?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E8=A7=84=E5=88=99=E4=B8=8E=E5=BD=93=E5=89=8D?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 31 ++++++++++++++++++++ README.md | 17 ++++++++--- docs/AI智能分析要求与排查修复基准.md | 12 ++++++-- docs/DeepSeekHarness正式接入.md | 4 +++ docs/当前进度.md | 44 ++++++++++++++++++++++++++++ 5 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/当前进度.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5a3f677 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# 质量数据分析平台项目规则 + +沿用全局沟通与执行习惯;本文件只补充项目约束和入口。 + +## 项目约束 + +- 正式指标由后端指标服务和当前有效规则计算。月、季、年先汇总分量再计算,不平均月率;缺失阶段、零分母、去本部报废等语义以正式服务为准,不在页面、导出或 AI 中另造算法。 +- 当前智能分析固定使用 DSH,保留模型原始正文;普通提问直接回答,报告仅在明确要求时生成。图表失败静默省略并保留后台诊断。遗留 `nao_*.py` 与根目录兼容入口不表示可以恢复双引擎或增加模型审阅。 +- 权限、数据范围及来源绑定由服务端执行;查询、缓存、图表、报告和下载均保留当前授权检查,历史快照不能绕过实时权限。 +- 测试使用隔离数据库与合成数据,复用 `OwnedTestDatabase` 或 `scripts/managed_test_resources.py` 登记和清理自有资源。私有原表回归另选入口,不把业务主库当测试库。 +- `.runtime/`、`runtimedata/`、`output/` 含私有数据、验收产物及可能正在使用的运行包,不按目录名称判断可删除。密钥、登录资料、业务原件和备份不得进入 Git 或普通交接记录。 +- 主工作目录可能在旧分支上积累已由其他工作目录交付的改动。继续开发前核对分支、最新主线及本次差异;不将全部未提交内容一并提交,不切换或重置当前目录来“清理”。 + +## 按需阅读与代码入口 + +| 任务 | 入口 | +| --- | --- | +| 接续当前工作 | `docs/当前进度.md`;先核实记录与实际状态 | +| 启动、构建和验证 | `README.md`;共享服务维护另读 `deploy/macos/README.md` | +| 查询、指标和导出 | `web/src/QueryPage.tsx`、`web/src/metricWorkbook.ts`;后端 `metrics/`、`analytics/`,均位于 `backend/src/main/java/cn/yunsheng/quality/` | +| 智能分析 | `docs/DeepSeekHarness正式接入.md`;前端 `web/src/agent/`、后端 `analysis/`、`scripts/build_dsh_application.py` 及 `runtime/dsh/application/` | +| 数据接入和规则 | 后端 `source/`、`ingestion/`、`workflow/`、`masterdata/`、`dictionary/`;本地授权资产存在时,原表核对另读 `verification/rules.md`,其中样本范围属于历史基线,该文件不随源码同步 | +| 界面与交互 | `DESIGN.md` 及现有组件、主题;无需为纯业务改动读取全部设计说明 | +| 备份、回收和迁移 | `deploy/macos/README.md`、`deploy/docker/README.md`;版本变化触发的维护保护须经兼容性核实后再解除 | + +## 验证入口 + +- 前端按影响选择 `node --test web/verification/<相关测试>.test.mjs`;查询导出对应 `metric_workbook.test.mjs`。必要时再执行 `pnpm --dir web build`。 +- 完整本机构建入口为 `python3 scripts/project.py build`,运行后端非私有原表测试并构建前端;原表全量回归显式加 `--private-acceptance`,资产缺失不能当作通过。 +- Python 用项目对应环境按需运行 `PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=scripts python3 -m unittest discover -s verification -p '<相关测试文件>'`;DSH 环境检查入口为 `python3 scripts/setup_dsh_runtime.py --check`,不调用模型。 +- 不因文档变更触发构建、服务重启、模型请求、数据库迁移或维护清理。开发测试通过、仓库同步和线上生效分别记录。 diff --git a/README.md b/README.md index 943eab6..1d28d8f 100644 --- a/README.md +++ b/README.md @@ -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)。 ## 旧版本时间迁移 diff --git a/docs/AI智能分析要求与排查修复基准.md b/docs/AI智能分析要求与排查修复基准.md index 1c59550..b2bfc7d 100644 --- a/docs/AI智能分析要求与排查修复基准.md +++ b/docs/AI智能分析要求与排查修复基准.md @@ -1,8 +1,16 @@ # AI 智能分析当前要求与排查修复基准 -适用项目:质量数据分析平台。更新日期:2026-11-02。 +适用项目:质量数据分析平台。基础要求日期:2026-11-02;运行与展示边界补充:2026-11-12。 -本文只列当前有效要求与对应验收标准,供智能分析排查、修复和交付时使用。 +本文保留基础业务口径及排查要求。当前实现与验收范围另见 [DSH 接入说明](DeepSeekHarness正式接入.md);下文涉及早期执行、模型审阅和图表完成条件的描述,按本节更新理解。 + +## 当前运行与展示边界 + +- 正式智能分析固定使用 DSH,API 配置不提供双引擎切换;旧引擎与旧实施方案只作历史参考。 +- 保存和展示模型原始正文,不追加模型审阅、格式修复或固定模板改写;服务端的权限、范围、参数与正式口径检查继续保留。 +- 普通提问直接回答,只有明确要求时生成报告,追问保留已确认的输出目标。 +- 图表是可选呈现。生成或加载失败时静默省略并保留后台诊断,不因缺图将已有正常回答标成失败,不展示异常图框或重试入口。 +- 当前进度与已验证范围见 [当前进度](当前进度.md)。历史验收通过不表示所有未来问题或所有平台均已通过。 ## 1. 全链路要求 diff --git a/docs/DeepSeekHarness正式接入.md b/docs/DeepSeekHarness正式接入.md index a427d35..26187cd 100644 --- a/docs/DeepSeekHarness正式接入.md +++ b/docs/DeepSeekHarness正式接入.md @@ -2,10 +2,14 @@ 更新日期:2026年11月12日。 +本文件按当前 Java 引擎约束、独立应用构建入口及最新交付说明整理;项目现状和待办见 [当前进度](当前进度.md)。11月10日的双引擎切换、额外模型审阅和早期报告缺项属于历史阶段,不能作为当前运行说明。 + ## 当前入口 质量智能分析固定使用 DSH。Java 提供身份、授权、正式指标、会话、工具与已保存结果;Python 编排当前模型和工具;DSH 执行思考与工具循环。正式入口是 `scripts/quality_analysis_runtime.py`,独立应用通过 `scripts/build_dsh_application.py` 构建。运行时应用不包含 nao 服务、客户端或执行器。保留的 `nao_*.py` 源文件是打包前的共享业务算子,构建时转换为中性模块名。 +根目录 `scripts/quality_analysis_runtime.py` 仍保留早期双引擎兼容逻辑;当前 Java 正式分析入口固定 DSH,构建后的独立应用使用自己的运行入口。排查线上行为时先核对守护登记的实际运行包,不把根目录兼容源码当作当前部署。 + 前端智能分析入口为 `web/src/agent/AgentWorkspace.tsx`。仅保留对话界面,工具调用在对话内展开;会话先加载最近一页,再按需读取历史,通过会话事件流更新。删除会话只操作当前账号拥有的记录。 ## 模型回答与报告 diff --git a/docs/当前进度.md b/docs/当前进度.md new file mode 100644 index 0000000..7fc5ae7 --- /dev/null +++ b/docs/当前进度.md @@ -0,0 +1,44 @@ +# 当前进度 + +核实日期:2026年11月12日(上海时区)。这是可更新的接续记录,不替代实际代码与运行状态。 + +## 当前任务 + +目标:修正主目录过时说明,补充轻量项目规则与统一进度入口,并按后续授权同步当前文档到 Gitea。 + +验收条件:README 与当前 DSH 实现一致;项目规则简短、入口有效;旧验收明确属于历史记录;仅同步本次当前文档,不改业务代码、数据库或服务配置,不部署。 + +已完成:补充根目录 `AGENTS.md`,更新 README、DSH 接入说明和旧文档的适用范围;本文件作为后续接续入口。已核对9个新增本地文档链接、关键代码入口和改动范围,Git 差异空白检查通过;仅6份 Markdown 变化,原交付说明正文及业务源码保留。本次文档整理未运行构建或业务测试。 + +## 已核实的项目状态 + +| 项目 | 本轮事实及证据 | +| --- | --- | +| 主工作目录 | 仓库根目录,分支 `codex/analysis-tool-lifecycle-fixes-20261103`,HEAD `52d92c9`。开始整理前显示 379 项修改/删除/未跟踪条目,不等于 379 项未交付功能。 | +| 整理前仓库主线 | 文档整理前远端 `main` 为 `bc19475b29fa7331fe729c27af54036cb124db72`,对应交付目录为 `output/gitea-dsh-20261112/worktree/`。本次文档同步在此基础上单独提交;同步后的具体提交以 Git 历史为准。主工作目录的分支与业务改动不变。 | +| 与主线的差异 | 整理前按主线已跟踪文件逐一比较,主目录无缺失,8 个文件不同,其中两个仅多空行。其余涉及文档、设计、Docker 打包清单和 Excel 导出实现/测试;本轮文档改动另计。 | +| 线上前端 | 公开 `release.json` 返回 `2026.11.12.40`,引擎 DSH 且锁定;保留旧提交 `3962521` 及补丁标记,版本与完整源码尚未一一对齐。 | +| 当前后端 | 本机服务守护、MySQL 和后端就绪;本地健康检查为 UP。守护使用已登记的不可变 JAR,DSH 使用独立应用。运行包与根目录源码不应直接视为相同版本。 | +| 当前页面 | 既有线上标签页正常显示总体查询与月度数据。本轮未重新执行全业务验收。 | +| Excel 导出 | 今日格式调整有部署与页面验收记录,源码相对最新主线仍有差异。此前同日现状检查实际重跑 `node --test web/verification/metric_workbook.test.mjs`,23 项通过;不是全量测试,本次文档整理未重复运行。 | +| 自动维护 | 备份和旧数据回收因当前 JAR 与已登记兼容版本不一致而延期。维护状态提示需复核,不能直接解除保护。 | +| 现存备份 | 最近记录为11月10日晚,清单状态 `ISOLATED_RESTORE_VERIFIED`;目录存在、清单指针摘要匹配。本轮未重做恢复,清单中的应用启动验证为 false。 | +| 容量监控 | 本轮采样:MySQL 约10.79 GiB,交付/构建产物约33.62 GiB,可用空间约534 GiB;提示一个超过24小时的测试资源。仅作时点记录,不据此删除。 | + +运行配置、模型凭据、会话标识、真实业务行和备份内容不复制到本记录。 + +## 已约定的执行边界 + +- 文档整理后,用户另行授权同步到 Gitea。本次仅提交 `AGENTS.md`、`README.md`、`docs/当前进度.md`、`docs/DeepSeekHarness正式接入.md` 和 `docs/AI智能分析要求与排查修复基准.md`;不发布、不改变现有业务行为。 +- 仓库为公开仓库,按原有 Git 排除规则将 `开发交付说明.md` 及本地验收资料留在本机。本次同步不解除排除规则,不上传业务原件、备份或账户资料。 +- 智能分析固定 DSH、模型正文原样保留、报告按明确要求生成、图表故障静默;具体代码与边界见 [DSH 接入说明](DeepSeekHarness正式接入.md)。 +- 历史源码、交付记录和原表基线继续保留;旧数据覆盖范围和早期方案不能当成当前验收。 + +## 待处理与下一步 + +1. 运维:检查当前运行包及数据库结构与维护逻辑的兼容性,再决定恢复自动备份和回收;需要新的恢复验证,不能只更新兼容标记。 +2. 版本:核对线上产物、最新主线和主目录剩余差异,特别是今日 Excel 导出改动;分别记录应同步与应保留的内容,不直接整体提交。 +3. 平台:Linux Docker 构建、启动、DSH 等效隔离及恢复仍待目标机验收;Windows 更新/恢复也不能由本轮检查替代。 +4. 容量:核实构建产物及超期测试资源的用途、所有者和活动状态后,再提出清理范围。 + +下次继续:先看根目录 `AGENTS.md`,核对本记录、实际分支/未提交内容及服务状态,然后只推进当次明确的任务。状态变化时更新本文件,不新建重复的当前进度文档。