@liuhange/dsh-gov-data-inspector 3.1.2 → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuhange789
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -36,3 +36,80 @@ apply(ctx); // 注册工具: inspect_gov_data
 ## License
 
 MIT
+## 无凭据降级模式
+
+当官方数据源（国家/省级）凭据未配置或不可达时，插件自动进入**降级模式**而非中止运行。
+
+### 降级触发条件
+
+- 国家和省级数据源均未配置 API Key / Endpoint
+- 国家和省级数据源均不可达（网络超时、HTTP 错误等）
+
+### 降级表现
+
+| 检测模式 | 完整模式表现 | 降级模式表现 |
+|---------|------------|------------|
+| classification | 正常分类 | **正常分类**（不依赖知识库） |
+| guide | 语义检测基于官方知识库 | 语义检测降级为本地规则检测 |
+| full | 全量检测 | 分类正常 + 语义/逻辑降级 |
+
+### 降级标记
+
+降级模式下，巡检报告包含以下额外字段：
+
+```json
+{
+  "degradedMode": true,
+  "degradedReason": "官方数据源全部不可用，已降级为本地规则检测模式"
+}
+```
+
+### 端点协议宽松化
+
+数据源端点支持以下三种协议：
+- `https://` — HTTPS 远程端点
+- `http://` — HTTP 远程端点（不再强制 HTTPS）
+- 本地文件路径 — 直接读取本地 JSON 文件
+
+## 异常输入处理
+
+插件对以下异常输入场景提供明确的友好错误提示，不会崩溃或产生未捕获异常：
+
+| 异常场景 | 错误码 | 错误提示 |
+|---------|--------|---------|
+| 格式错误的 JSON | `GOV_DATA_INPUT_INVALID` | JSON 格式错误，请检查文件内容 |
+| 空数据（空文件/空数组） | `GOV_DATA_INPUT_INVALID` | 无数据，请确认输入文件内容 |
+| 超长数据（超 100 万字段） | `GOV_DATA_SCALE_EXCEEDED` | 数据量超出处理上限 |
+| 无效 URL / 不可达路径 | `GOV_DATA_URL_UNREACHABLE` | 数据源不可达，请检查路径或 URL |
+| 非 UTF-8 编码文件 | `GOV_DATA_ENCODING_ERROR` | 文件编码非 UTF-8 |
+| 部分字段缺失 | 正常处理 | 报告中列出缺失字段清单 |
+
+### itemTypeOverride 参数
+
+当自动匹配无法识别事项类型时，用户可通过 `itemTypeOverride` 参数手动指定：
+
+```javascript
+execute({
+  dataSource: './data.json',
+  inspectionMode: 'guide',
+  itemTypeOverride: '现场勘查类'
+})
+```
+
+### 未匹配事项类型警告
+
+当事项无法匹配到任何检测规则时，报告中会包含 `UNMATCHED_ITEM_TYPE` 警告：
+
+```json
+{
+  "warnings": [
+    {
+      "type": "UNMATCHED_ITEM_TYPE",
+      "guideId": "建设工程规划核实",
+      "message": "该事项未匹配到检测规则，语义检测被跳过"
+    }
+  ]
+}
+```
+
+匹配逻辑支持四通道：手动指定 → 名称关键词 → 编码前缀 → 流程字段关键词。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Cordis Framework Patch Declaration for @liuhange/dsh-gov-data-inspector
+# This file declares the plugin's runtime patch for the Cordis framework.
+# Used by DSH plugin manager to apply framework-level patches during installation.
+plugin: @liuhange/dsh-gov-data-inspector
+version: 3.1.2
+patch:
+  - target: tools
+    action: register
+    description: Register plugin tools into Cordis runtime

package/lib/__tests__/exceptionInput.test.js

@@ -0,0 +1,180 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+const tmpDir = resolve(tmpdir(), 'gov-data-inspector-test');
+const badJsonPath = resolve(tmpDir, 'bad.json');
+const emptyPath = resolve(tmpDir, 'empty.json');
+const emptyArrayPath = resolve(tmpDir, 'empty-array.json');
+const nonUtf8Path = resolve(tmpDir, 'non-utf8.json');
+const partialDataPath = resolve(tmpDir, 'partial.json');
+const validDataPath = resolve(tmpDir, 'valid.json');
+beforeAll(() => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(badJsonPath, '{ "事项名称": "测试", invalid json }', 'utf-8');
+    writeFileSync(emptyPath, '', 'utf-8');
+    writeFileSync(emptyArrayPath, '[]', 'utf-8');
+    const gbkBuffer = Buffer.from([0xB2, 0xE2, 0xCA, 0xD4]);
+    writeFileSync(nonUtf8Path, gbkBuffer);
+    writeFileSync(partialDataPath, JSON.stringify([{ 事项名称: '测试事项' }]), 'utf-8');
+    writeFileSync(validDataPath, JSON.stringify([{ 事项名称: '食品经营许可', 办理时限: '20个工作日' }]), 'utf-8');
+});
+afterAll(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+async function getExecute() {
+    const mod = await import('../index.js');
+    const tools = [];
+    mod.apply({ tools: { register: (t) => tools.push(t) } });
+    const tool = tools[0];
+    return tool.execute;
+}
+describe('异常输入处理', () => {
+    it('格式错误的JSON → 返回GOV_DATA_INPUT_INVALID', async () => {
+        const execute = await getExecute();
+        const result = JSON.parse(await execute({ dataSource: badJsonPath }));
+        expect(result.error).toBe('GOV_DATA_INPUT_INVALID');
+        expect(result.message).toContain('JSON 格式错误');
+    });
+    it('空数据(空文件) → 返回无数据提示', async () => {
+        const execute = await getExecute();
+        const result = JSON.parse(await execute({ dataSource: emptyPath }));
+        expect(result.error).toBe('GOV_DATA_INPUT_INVALID');
+        expect(result.message).toContain('无数据');
+    });
+    it('空数据(空数组) → 返回无数据提示', async () => {
+        const execute = await getExecute();
+        const result = JSON.parse(await execute({ dataSource: emptyArrayPath }));
+        expect(result.error).toBe('GOV_DATA_INPUT_INVALID');
+        expect(result.message).toContain('无数据');
+    });
+    it('无效URL → 返回不可达提示而非崩溃', async () => {
+        const execute = await getExecute();
+        const result = JSON.parse(await execute({ dataSource: 'http://invalid.localhost.nonexistent:99999/data.json' }));
+        expect(result.error).toBeDefined();
+        expect(result.message).toBeDefined();
+    });
+    it('部分字段缺失的数据 → 正常处理并报告缺失字段', async () => {
+        const execute = await getExecute();
+        const result = JSON.parse(await execute({ dataSource: partialDataPath, inspectionMode: 'guide' }));
+        expect(result.error).toBeUndefined();
+        expect(result.guideInspection).toBeDefined();
+        expect(result.guideInspection.missingFields).toBeGreaterThan(0);
+    });
+    it('非UTF-8编码文件 → 返回编码错误提示', async () => {
+        const execute = await getExecute();
+        const result = JSON.parse(await execute({ dataSource: nonUtf8Path }));
+        expect(result.error).toBe('GOV_DATA_ENCODING_ERROR');
+        expect(result.message).toContain('UTF-8');
+    });
+});
+describe('EncodingDetector', () => {
+    it('UTF-8文件正常读取', async () => {
+        const { EncodingDetector } = await import('../encodingDetector.js');
+        const result = EncodingDetector.detect(validDataPath);
+        expect(result.content).not.toBeNull();
+        expect(result.encodingError).toBeUndefined();
+    });
+    it('非UTF-8文件返回编码错误', async () => {
+        const { EncodingDetector } = await import('../encodingDetector.js');
+        const result = EncodingDetector.detect(nonUtf8Path);
+        expect(result.content).toBeNull();
+        expect(result.encodingError).toContain('UTF-8');
+    });
+    it('不存在的文件返回读取错误', async () => {
+        const { EncodingDetector } = await import('../encodingDetector.js');
+        const result = EncodingDetector.detect(resolve(tmpDir, 'nonexistent.json'));
+        expect(result.content).toBeNull();
+        expect(result.encodingError).toContain('无法读取');
+    });
+});
+describe('DataScaleGuard', () => {
+    it('正常规模数据通过', async () => {
+        const { DataScaleGuard } = await import('../dataScaleGuard.js');
+        const data = [{ a: 1, b: 2 }, { c: 3 }];
+        const result = DataScaleGuard.check(data);
+        expect(result.exceeded).toBe(false);
+        expect(result.fieldCount).toBe(3);
+    });
+    it('超100万字段数据返回exceeded=true', async () => {
+        const { DataScaleGuard } = await import('../dataScaleGuard.js');
+        const data = [];
+        for (let i = 0; i < 100001; i++)
+            data.push({ f: i });
+        const result = DataScaleGuard.check(data, 100000);
+        expect(result.exceeded).toBe(true);
+        expect(result.fieldCount).toBeGreaterThan(100000);
+    });
+    it('自定义上限', async () => {
+        const { DataScaleGuard } = await import('../dataScaleGuard.js');
+        const result = DataScaleGuard.check([{ a: 1, b: 2, c: 3 }], 2);
+        expect(result.exceeded).toBe(true);
+    });
+});
+describe('UrlReachabilityChecker', () => {
+    it('本地文件存在 → reachable=true', async () => {
+        const { UrlReachabilityChecker } = await import('../urlReachabilityChecker.js');
+        const result = await UrlReachabilityChecker.check(validDataPath);
+        expect(result.reachable).toBe(true);
+    });
+    it('不存在的文件 → reachable=false', async () => {
+        const { UrlReachabilityChecker } = await import('../urlReachabilityChecker.js');
+        const result = await UrlReachabilityChecker.check(resolve(tmpDir, 'nonexistent.json'));
+        expect(result.reachable).toBe(false);
+        expect(result.error).toBeDefined();
+    });
+    it('空路径 → reachable=false', async () => {
+        const { UrlReachabilityChecker } = await import('../urlReachabilityChecker.js');
+        const result = await UrlReachabilityChecker.check('');
+        expect(result.reachable).toBe(false);
+    });
+});
+describe('EndpointResolver', () => {
+    it('HTTPS URL → kind=https', async () => {
+        const { EndpointResolver } = await import('../endpointResolver.js');
+        const result = EndpointResolver.resolve('https://api.example.com/data');
+        expect(result?.kind).toBe('https');
+    });
+    it('HTTP URL → kind=http', async () => {
+        const { EndpointResolver } = await import('../endpointResolver.js');
+        const result = EndpointResolver.resolve('http://api.example.com/data');
+        expect(result?.kind).toBe('http');
+    });
+    it('本地文件路径 → kind=file', async () => {
+        const { EndpointResolver } = await import('../endpointResolver.js');
+        const result = EndpointResolver.resolve(validDataPath);
+        expect(result?.kind).toBe('file');
+    });
+    it('相对路径 → kind=file', async () => {
+        const { EndpointResolver } = await import('../endpointResolver.js');
+        const result = EndpointResolver.resolve('./data.json');
+        expect(result?.kind).toBe('file');
+    });
+    it('非法字符串 → null', async () => {
+        const { EndpointResolver } = await import('../endpointResolver.js');
+        const result = EndpointResolver.resolve('not-a-valid-endpoint');
+        expect(result).toBeNull();
+    });
+});
+describe('DegradedModeController', () => {
+    it('activate返回degradedMode=true', async () => {
+        const { DegradedModeController } = await import('../degradedModeController.js');
+        const result = DegradedModeController.activate('测试降级原因');
+        expect(result.degradedMode).toBe(true);
+        expect(result.degradedReason).toBe('测试降级原因');
+        expect(result.localKb).toBeDefined();
+        expect(result.localKb.timeLimits).toEqual([]);
+        expect(result.localKb.materials).toEqual([]);
+        expect(result.localKb.conditions).toEqual([]);
+    });
+});
+describe('UnmatchedWarningBuilder', () => {
+    it('build返回正确警告结构', async () => {
+        const { UnmatchedWarningBuilder } = await import('../unmatchedWarningBuilder.js');
+        const warning = UnmatchedWarningBuilder.build('guide-001');
+        expect(warning.type).toBe('UNMATCHED_ITEM_TYPE');
+        expect(warning.guideId).toBe('guide-001');
+        expect(warning.message).toContain('未匹配到检测规则');
+    });
+});
+//# sourceMappingURL=exceptionInput.test.js.map

package/lib/__tests__/semanticRuleEngine.test.js

@@ -25,27 +25,62 @@ const itemTypeMatching = {
 describe('SemanticRuleEngine', () => {
     it('时限为"90个工作日"且法定上限为20 → 输出semantic错误', () => {
         const guide = { 事项名称: '食品经营许可', 办理时限: '90个工作日' };
-        const details = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching);
-        const timeError = details.find((d) => d.field === '办理时限');
+        const result = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching);
+        const timeError = result.details.find((d) => d.field === '办理时限');
         expect(timeError).toBeDefined();
         expect(timeError.errorType).toBe('semantic');
         expect(timeError.suggestion).toContain('20');
     });
     it('材料含"营业执照复映件"且标准为"营业执照复印件" → 输出semantic错误', () => {
         const guide = { 事项名称: '食品经营许可', 申请材料: '营业执照复映件、行政许可申请表' };
-        const details = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching);
-        const matError = details.find((d) => d.field === '申请材料');
+        const result = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching);
+        const matError = result.details.find((d) => d.field === '申请材料');
         expect(matError).toBeDefined();
         expect(matError.errorType).toBe('semantic');
         expect(matError.suggestion).toContain('营业执照复印件');
     });
-    it('事项名称在知识库无对应条目 → 返回空数组不计入错误', () => {
+    it('事项名称在知识库无对应条目 → 返回unmatched警告', () => {
         const guide = { 事项名称: '未知事项类型', 办理时限: '90个工作日' };
-        const details = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching);
-        expect(details.length).toBe(0);
+        const result = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching);
+        expect(result.details.length).toBe(0);
+        expect(result.unmatched).toBe(true);
+        expect(result.warning).toBeDefined();
+        expect(result.warning.type).toBe('UNMATCHED_ITEM_TYPE');
     });
-    it('标准知识库不可用 → 抛出GOV_DATA_KB_MISSING', () => {
-        expect(() => SemanticRuleEngine.detect({}, 'g1', {}, itemTypeMatching)).toThrow();
+    it('标准知识库不可用且非降级 → 抛出GOV_DATA_KB_MISSING', () => {
+        expect(() => SemanticRuleEngine.detect({ 事项名称: '食品经营许可' }, 'g1', {}, itemTypeMatching)).toThrow();
+    });
+    it('标准知识库不可用且降级模式 → 返回空details不抛错', () => {
+        const result = SemanticRuleEngine.detect({ 事项名称: '食品经营许可' }, 'g1', {}, itemTypeMatching, undefined, { degradedMode: true });
+        expect(result.details).toEqual([]);
+    });
+    it('流程字段含关键词可匹配事项类型', () => {
+        const guide = { 事项名称: '建设工程规划核实', 办理流程: '受理→现场勘查→核实→出证', 办理时限: '90个工作日' };
+        const itemTypeMatchingWithFlow = {
+            现场勘查类: { keywords: ['现场勘查', '实地核查'], codePrefix: 'XC' },
+        };
+        const result = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatchingWithFlow);
+        expect(result.unmatched).toBeUndefined();
+    });
+    it('itemTypeOverride手动指定事项类型', () => {
+        const guide = { 事项名称: '建设工程规划核实', 办理时限: '90个工作日' };
+        const result = SemanticRuleEngine.detect(guide, 'g1', kb, itemTypeMatching, undefined, { itemTypeOverride: '行政许可' });
+        expect(result.unmatched).toBeUndefined();
+        const timeError = result.details.find((d) => d.field === '办理时限');
+        expect(timeError).toBeDefined();
+    });
+    it('matchItemType返回matchSource', () => {
+        const nameMatch = SemanticRuleEngine.matchItemType({ 事项名称: '食品经营许可' }, itemTypeMatching);
+        expect(nameMatch.matchSource).toBe('name');
+        const codeMatch = SemanticRuleEngine.matchItemType({ 事项编码: 'XK001' }, itemTypeMatching);
+        expect(codeMatch.matchSource).toBe('code');
+        const flowMatch = SemanticRuleEngine.matchItemType({ 事项名称: '测试', 办理流程: '现场勘查' }, { 现场勘查类: { keywords: ['现场勘查'], codePrefix: 'XC' } });
+        expect(flowMatch.matchSource).toBe('flow');
+        const manualMatch = SemanticRuleEngine.matchItemType({ 事项名称: '测试' }, itemTypeMatching, { itemTypeOverride: '行政许可' });
+        expect(manualMatch.matchSource).toBe('manual');
+        const noMatch = SemanticRuleEngine.matchItemType({ 事项名称: '测试' }, itemTypeMatching);
+        expect(noMatch.matchSource).toBeNull();
+        expect(noMatch.itemType).toBeNull();
     });
     it('时限数值提取', () => {
         expect(SemanticRuleEngine.extractTimeLimitDays('20个工作日')).toBe(20);

package/lib/dataScaleGuard.js

@@ -0,0 +1,19 @@
+export const DataScaleGuard = {
+    check(data, maxFieldCount) {
+        const limit = maxFieldCount ?? 1000000;
+        let fieldCount = 0;
+        for (const row of data) {
+            if (typeof row === 'object' && row !== null) {
+                fieldCount += Object.keys(row).length;
+            }
+            else {
+                fieldCount++;
+            }
+            if (fieldCount > limit) {
+                return { exceeded: true, fieldCount };
+            }
+        }
+        return { exceeded: false, fieldCount };
+    },
+};
+//# sourceMappingURL=dataScaleGuard.js.map

package/lib/degradedModeController.js

@@ -0,0 +1,21 @@
+const DEGRADED_STATUS = { status: 'degraded', fetchedAt: '', recordCount: 0 };
+const EMPTY_KB = {
+    timeLimits: [],
+    materials: [],
+    conditions: [],
+    dataSourceStatus: {
+        national: DEGRADED_STATUS,
+        provincial: DEGRADED_STATUS,
+        standard: DEGRADED_STATUS,
+    },
+};
+export const DegradedModeController = {
+    activate(reason) {
+        return {
+            degradedMode: true,
+            degradedReason: reason,
+            localKb: { ...EMPTY_KB, dataSourceStatus: { ...EMPTY_KB.dataSourceStatus } },
+        };
+    },
+};
+//# sourceMappingURL=degradedModeController.js.map

package/lib/encodingDetector.js

@@ -0,0 +1,31 @@
+export const EncodingDetector = {
+    detect(filePath) {
+        const { readFileSync } = require('node:fs');
+        let buffer;
+        try {
+            buffer = readFileSync(filePath);
+        }
+        catch {
+            return { content: null, encodingError: `无法读取文件: ${filePath}` };
+        }
+        if (buffer.length === 0) {
+            return { content: '', encodingError: '文件为空' };
+        }
+        const isUtf8 = this.isValidUtf8(buffer);
+        if (!isUtf8) {
+            return { content: null, encodingError: '文件编码非 UTF-8，请将文件转换为 UTF-8 编码后重试' };
+        }
+        return { content: buffer.toString('utf-8') };
+    },
+    isValidUtf8(buffer) {
+        try {
+            const str = buffer.toString('utf-8');
+            const reencoded = Buffer.from(str, 'utf-8');
+            return reencoded.equals(buffer);
+        }
+        catch {
+            return false;
+        }
+    },
+};
+//# sourceMappingURL=encodingDetector.js.map

package/lib/endpointResolver.js

@@ -0,0 +1,21 @@
+export const EndpointResolver = {
+    resolve(endpoint) {
+        if (!endpoint || typeof endpoint !== 'string')
+            return null;
+        if (endpoint.startsWith('https://')) {
+            return { kind: 'https', target: endpoint };
+        }
+        if (endpoint.startsWith('http://')) {
+            return { kind: 'http', target: endpoint };
+        }
+        const { existsSync } = require('node:fs');
+        if (existsSync(endpoint)) {
+            return { kind: 'file', target: endpoint };
+        }
+        if (endpoint.startsWith('./') || endpoint.startsWith('../') || endpoint.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(endpoint)) {
+            return { kind: 'file', target: endpoint };
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=endpointResolver.js.map

package/lib/index.js

@@ -5,6 +5,9 @@ import { resolvePolicyBasis } from './policyBasis.js';
 import { KnowledgeBaseLoader } from './knowledgeBaseLoader.js';
 import { InspectionOrchestrator } from './inspectionOrchestrator.js';
 import { StandardRuleSource } from './standardRuleSource.js';
+import { EncodingDetector } from './encodingDetector.js';
+import { DataScaleGuard } from './dataScaleGuard.js';
+import { UrlReachabilityChecker } from './urlReachabilityChecker.js';
 export function apply(ctx) {
     ctx.tools.register({
         name: 'inspect_gov_data',
@@ -14,6 +17,7 @@ export function apply(ctx) {
             properties: {
                 dataSource: { type: 'string', description: '政务数据文件路径' },
                 inspectionMode: { type: 'string', enum: ['guide', 'classification', 'full'] },
+                itemTypeOverride: { type: 'string', description: '手动指定事项类型，覆盖自动匹配结果' },
             },
             required: ['dataSource'],
         },
@@ -29,11 +33,82 @@ export function apply(ctx) {
                 catch {
                     return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: '无法加载business-rules.json' });
                 }
-                const govConfig = rulesConfig.govDataInspection;
-                if (!govConfig) {
+                const govConfigRaw = rulesConfig.govDataInspection;
+                if (!govConfigRaw || typeof govConfigRaw !== 'object') {
                     return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: 'govDataInspection配置段缺失' });
                 }
-                const credentials = govConfig.dataSourceCredentials;
+                const govConfig = govConfigRaw;
+                const requiredFields = {
+                    guideRequiredElements: 'string[]',
+                    logicErrorRules: 'array',
+                    formatRules: 'array',
+                    severityMapping: 'object',
+                    scoreWeights: 'object',
+                    convenienceWeights: 'object',
+                    gbt47949Mapping: 'object',
+                    itemTypeMatching: 'object',
+                    materialConciseThreshold: 'number',
+                    missingFieldStandardClause: 'string',
+                    dataSourcePriority: 'array',
+                    dataSourceCredentials: 'object',
+                };
+                for (const [field, expectedType] of Object.entries(requiredFields)) {
+                    const val = govConfig[field];
+                    if (val === undefined || val === null) {
+                        return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: `govDataInspection.${field}配置缺失` });
+                    }
+                    if (expectedType === 'array' && !Array.isArray(val)) {
+                        return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: `govDataInspection.${field}应为数组` });
+                    }
+                    if (expectedType === 'object' && (typeof val !== 'object' || Array.isArray(val))) {
+                        return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: `govDataInspection.${field}应为对象` });
+                    }
+                    if (expectedType === 'string' && typeof val !== 'string') {
+                        return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: `govDataInspection.${field}应为字符串` });
+                    }
+                    if (expectedType === 'number' && typeof val !== 'number') {
+                        return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: `govDataInspection.${field}应为数字` });
+                    }
+                    if (expectedType === 'string[]' && (!Array.isArray(val) || val.some((v) => typeof v !== 'string'))) {
+                        return JSON.stringify({ error: 'GOV_DATA_RULES_MISSING', message: `govDataInspection.${field}应为字符串数组` });
+                    }
+                }
+                const govConfigTyped = govConfig;
+                const encodingResult = EncodingDetector.detect(args.dataSource);
+                if (encodingResult.content === null) {
+                    if (encodingResult.encodingError === '文件为空') {
+                        return JSON.stringify({ error: 'GOV_DATA_INPUT_INVALID', message: '无数据，请确认输入文件内容' });
+                    }
+                    if (encodingResult.encodingError?.includes('无法读取文件')) {
+                        const reachability = await UrlReachabilityChecker.check(args.dataSource);
+                        if (!reachability.reachable) {
+                            return JSON.stringify({ error: 'GOV_DATA_URL_UNREACHABLE', message: reachability.error ?? '数据源不可达，请检查路径或 URL' });
+                        }
+                    }
+                    return JSON.stringify({ error: 'GOV_DATA_ENCODING_ERROR', message: encodingResult.encodingError ?? '文件编码错误' });
+                }
+                let data;
+                try {
+                    const raw = encodingResult.content;
+                    if (raw.trim() === '') {
+                        return JSON.stringify({ error: 'GOV_DATA_INPUT_INVALID', message: '无数据，请确认输入文件内容' });
+                    }
+                    data = JSON.parse(raw);
+                    if (!Array.isArray(data))
+                        data = [data];
+                }
+                catch (e) {
+                    return JSON.stringify({ error: 'GOV_DATA_INPUT_INVALID', message: `JSON 格式错误，请检查文件内容: ${e.message}` });
+                }
+                if (data.length === 0) {
+                    return JSON.stringify({ error: 'GOV_DATA_INPUT_INVALID', message: '无数据，请确认输入文件内容' });
+                }
+                const maxFieldCount = rulesConfig.govDataInspection?.maxFieldCount;
+                const scaleResult = DataScaleGuard.check(data, maxFieldCount);
+                if (scaleResult.exceeded) {
+                    return JSON.stringify({ error: 'GOV_DATA_SCALE_EXCEEDED', message: `数据量超出处理上限（字段数${scaleResult.fieldCount}），请分批处理或增加maxFieldCount配置` });
+                }
+                const credentials = govConfigTyped.dataSourceCredentials;
                 const credConfig = {
                     national: {
                         apiKey: process.env[credentials.national.apiKey],
@@ -44,13 +119,10 @@ export function apply(ctx) {
                         endpoint: process.env[credentials.provincial.endpoint],
                     },
                 };
-                let kb;
-                try {
-                    kb = await KnowledgeBaseLoader.load(credConfig, govConfig.dataSourcePriority);
-                }
-                catch {
-                    return JSON.stringify({ error: 'GOV_DATA_KB_MISSING', message: '官方数据源全部不可用，语义错误检测已中止' });
-                }
+                const kbLoadResult = await KnowledgeBaseLoader.load(credConfig, govConfigTyped.dataSourcePriority);
+                const kb = kbLoadResult.kb;
+                const degradedMode = kbLoadResult.degraded;
+                const degradedReason = kbLoadResult.degradedReason;
                 const dataSourceStatus = KnowledgeBaseLoader.getDataSourceStatus();
                 let standardRules;
                 const stdRuleResult = await StandardRuleSource.fetch({
@@ -62,10 +134,13 @@ export function apply(ctx) {
                     dataSourceStatus.standard = stdRuleResult.status;
                 }
                 else {
-                    standardRules = govConfig.logicErrorRules;
+                    standardRules = govConfigTyped.logicErrorRules;
                 }
                 if (!standardRules || standardRules.length === 0) {
-                    return JSON.stringify({ error: 'GOV_DATA_LOGIC_RULES_MISSING', message: '标准规则集缺失，逻辑错误检测已中止' });
+                    if (!degradedMode) {
+                        return JSON.stringify({ error: 'GOV_DATA_LOGIC_RULES_MISSING', message: '标准规则集缺失，逻辑错误检测已中止' });
+                    }
+                    standardRules = [];
                 }
                 let policyBasis;
                 try {
@@ -77,18 +152,8 @@ export function apply(ctx) {
                 catch {
                     return JSON.stringify({ error: 'GOV_DATA_POLICY_MISSING', message: '政策依据配置加载失败' });
                 }
-                let data;
-                try {
-                    const { readFileSync } = await import('node:fs');
-                    const raw = readFileSync(args.dataSource, 'utf-8');
-                    data = JSON.parse(raw);
-                    if (!Array.isArray(data))
-                        data = [data];
-                }
-                catch {
-                    return JSON.stringify({ error: 'GOV_DATA_INPUT_INVALID', message: `无法加载数据: ${args.dataSource}` });
-                }
                 const mode = args.inspectionMode ?? 'full';
+                const itemTypeOverride = args.itemTypeOverride;
                 const result = {
                     dataSource: args.dataSource,
                     inspectionMode: mode,
@@ -96,11 +161,19 @@ export function apply(ctx) {
                     policyBasis,
                     dataSourceStatus,
                 };
+                if (degradedMode) {
+                    result.degradedMode = true;
+                    result.degradedReason = degradedReason;
+                }
                 if (mode === 'guide' || mode === 'full') {
-                    result.guideInspection = InspectionOrchestrator.orchestrate(data, govConfig, kb, standardRules);
+                    const orchestrateResult = InspectionOrchestrator.orchestrate(data, govConfigTyped, kb, standardRules, { degradedMode, itemTypeOverride });
+                    result.guideInspection = orchestrateResult;
+                    if (orchestrateResult.warnings && orchestrateResult.warnings.length > 0) {
+                        result.warnings = orchestrateResult.warnings;
+                    }
                 }
                 if (mode === 'classification' || mode === 'full') {
-                    result.classification = classifyGovData(data, govConfig.gbt47949Mapping);
+                    result.classification = classifyGovData(data, govConfigTyped.gbt47949Mapping);
                 }
                 return JSON.stringify(result, null, 2);
             }

package/lib/inspectionOrchestrator.js

@@ -5,9 +5,10 @@ import { FormatValidator } from './formatValidator.js';
 import { QualityMetricsCalculator } from './qualityMetricsCalculator.js';
 import { ErrorDetailBuilder } from './errorDetailBuilder.js';
 export const InspectionOrchestrator = {
-    orchestrate(data, config, kb, standardRules) {
+    orchestrate(data, config, kb, standardRules, options) {
         const allErrorDetails = [];
         const allFormatIssues = [];
+        const allWarnings = [];
         let completeCount = 0;
         let serviceConvenience = 0;
         for (let i = 0; i < data.length; i++) {
@@ -21,8 +22,11 @@ export const InspectionOrchestrator = {
             const isComplete = missingDetails.length === 0;
             if (isComplete)
                 completeCount++;
-            const semanticDetails = SemanticRuleEngine.detect(guide, guideId, kb, config.itemTypeMatching, config.severityMapping);
-            allErrorDetails.push(...semanticDetails);
+            const semanticResult = SemanticRuleEngine.detect(guide, guideId, kb, config.itemTypeMatching, config.severityMapping, { degradedMode: options?.degradedMode, itemTypeOverride: options?.itemTypeOverride });
+            allErrorDetails.push(...semanticResult.details);
+            if (semanticResult.warning) {
+                allWarnings.push(semanticResult.warning);
+            }
             const logicalDetails = LogicRuleEngine.detect(guide, guideId, standardRules, config.severityMapping);
             allErrorDetails.push(...logicalDetails);
             const formatIssues = FormatValidator.validate(guide, guideId, config.formatRules);
@@ -64,6 +68,7 @@ export const InspectionOrchestrator = {
             serviceConvenience: Math.round(serviceConvenience * 100) / 100,
             totalGuidesChecked: data.length,
             detectionRates,
+            warnings: allWarnings,
         };
     },
 };

package/lib/knowledgeBaseLoader.js

@@ -71,15 +71,20 @@ export const KnowledgeBaseLoader = {
             standard: FAILED_STATUS,
         };
         const allFailed = nationalResult.status.status === 'failed' && provincialResult.status.status === 'failed';
-        if (allFailed) {
-            throw new Error('GOV_DATA_KB_MISSING: 官方数据源全部不可用，语义错误检测已中止');
-        }
-        return {
+        const kb = {
             timeLimits: cachedTimeLimits,
             materials: cachedMaterials,
             conditions: cachedConditions,
             dataSourceStatus: cachedDataSourceStatus,
         };
+        if (allFailed) {
+            return {
+                kb,
+                degraded: true,
+                degradedReason: '官方数据源全部不可用，已降级为本地规则检测模式',
+            };
+        }
+        return { kb, degraded: false };
     },
     getTimeLimits() {
         if (!cachedTimeLimits)

package/lib/nationalDataSource.js

@@ -1,7 +1,26 @@
+import { EndpointResolver } from './endpointResolver.js';
 const FAILED_RESULT = {
     data: [],
     status: { status: 'failed', fetchedAt: '', recordCount: 0 },
 };
+function parseOfficialData(raw, source) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => item && typeof item === 'object')
+        .map((item) => ({
+        dataSource: source,
+        itemType: String(item.itemType ?? ''),
+        legalUpperLimit: item.legalUpperLimit,
+        legalLowerLimit: item.legalLowerLimit,
+        standardName: item.standardName,
+        isRequired: item.isRequired,
+        elementName: item.elementName,
+        standardValue: item.standardValue,
+        standardClause: String(item.standardClause ?? ''),
+    }))
+        .filter((d) => d.itemType && d.standardClause);
+}
 export const NationalDataSource = {
     async fetch(credentials) {
         const apiKey = credentials?.apiKey ?? process.env.NATIONAL_API_KEY;
@@ -9,12 +28,23 @@ export const NationalDataSource = {
         if (!apiKey || !endpoint) {
             return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
         }
-        if (!endpoint.startsWith('https://')) {
+        const resolved = EndpointResolver.resolve(endpoint);
+        if (!resolved) {
             return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
         }
         try {
-            const url = new URL(endpoint);
-            url.searchParams.set('apiKey', apiKey);
+            if (resolved.kind === 'file') {
+                const { readFileSync } = require('node:fs');
+                const raw = JSON.parse(readFileSync(resolved.target, 'utf-8'));
+                const data = parseOfficialData(raw, 'national');
+                return {
+                    data,
+                    status: { status: 'success', fetchedAt: new Date().toISOString(), recordCount: data.length },
+                };
+            }
+            const url = new URL(resolved.target);
+            if (apiKey)
+                url.searchParams.set('apiKey', apiKey);
             const response = await fetch(url.toString(), {
                 method: 'GET',
                 headers: { 'Accept': 'application/json' },
@@ -23,22 +53,7 @@ export const NationalDataSource = {
             if (!response.ok)
                 return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
             const raw = await response.json();
-            if (!Array.isArray(raw))
-                return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
-            const data = raw
-                .filter((item) => item && typeof item === 'object')
-                .map((item) => ({
-                dataSource: 'national',
-                itemType: String(item.itemType ?? ''),
-                legalUpperLimit: item.legalUpperLimit,
-                legalLowerLimit: item.legalLowerLimit,
-                standardName: item.standardName,
-                isRequired: item.isRequired,
-                elementName: item.elementName,
-                standardValue: item.standardValue,
-                standardClause: String(item.standardClause ?? ''),
-            }))
-                .filter((d) => d.itemType && d.standardClause);
+            const data = parseOfficialData(raw, 'national');
             return {
                 data,
                 status: { status: 'success', fetchedAt: new Date().toISOString(), recordCount: data.length },

package/lib/provincialDataSource.js

@@ -1,7 +1,26 @@
+import { EndpointResolver } from './endpointResolver.js';
 const FAILED_RESULT = {
     data: [],
     status: { status: 'failed', fetchedAt: '', recordCount: 0 },
 };
+function parseOfficialData(raw, source) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => item && typeof item === 'object')
+        .map((item) => ({
+        dataSource: source,
+        itemType: String(item.itemType ?? ''),
+        legalUpperLimit: item.legalUpperLimit,
+        legalLowerLimit: item.legalLowerLimit,
+        standardName: item.standardName,
+        isRequired: item.isRequired,
+        elementName: item.elementName,
+        standardValue: item.standardValue,
+        standardClause: String(item.standardClause ?? ''),
+    }))
+        .filter((d) => d.itemType && d.standardClause);
+}
 export const ProvincialDataSource = {
     async fetch(credentials) {
         const apiKey = credentials?.apiKey ?? process.env.PROVINCIAL_API_KEY;
@@ -9,12 +28,23 @@ export const ProvincialDataSource = {
         if (!apiKey || !endpoint) {
             return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
         }
-        if (!endpoint.startsWith('https://')) {
+        const resolved = EndpointResolver.resolve(endpoint);
+        if (!resolved) {
             return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
         }
         try {
-            const url = new URL(endpoint);
-            url.searchParams.set('apiKey', apiKey);
+            if (resolved.kind === 'file') {
+                const { readFileSync } = require('node:fs');
+                const raw = JSON.parse(readFileSync(resolved.target, 'utf-8'));
+                const data = parseOfficialData(raw, 'provincial');
+                return {
+                    data,
+                    status: { status: 'success', fetchedAt: new Date().toISOString(), recordCount: data.length },
+                };
+            }
+            const url = new URL(resolved.target);
+            if (apiKey)
+                url.searchParams.set('apiKey', apiKey);
             const response = await fetch(url.toString(), {
                 method: 'GET',
                 headers: { 'Accept': 'application/json' },
@@ -23,22 +53,7 @@ export const ProvincialDataSource = {
             if (!response.ok)
                 return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
             const raw = await response.json();
-            if (!Array.isArray(raw))
-                return { ...FAILED_RESULT, status: { ...FAILED_RESULT.status } };
-            const data = raw
-                .filter((item) => item && typeof item === 'object')
-                .map((item) => ({
-                dataSource: 'provincial',
-                itemType: String(item.itemType ?? ''),
-                legalUpperLimit: item.legalUpperLimit,
-                legalLowerLimit: item.legalLowerLimit,
-                standardName: item.standardName,
-                isRequired: item.isRequired,
-                elementName: item.elementName,
-                standardValue: item.standardValue,
-                standardClause: String(item.standardClause ?? ''),
-            }))
-                .filter((d) => d.itemType && d.standardClause);
+            const data = parseOfficialData(raw, 'provincial');
             return {
                 data,
                 status: { status: 'success', fetchedAt: new Date().toISOString(), recordCount: data.length },

package/lib/semanticRuleEngine.js

@@ -1,16 +1,35 @@
 import { ErrorDetailBuilder } from './errorDetailBuilder.js';
-function matchItemType(guide, itemTypeMatching) {
+import { UnmatchedWarningBuilder } from './unmatchedWarningBuilder.js';
+const FLOW_FIELD_KEYS = ['办理流程', '工作流程', '流程描述', '业务流程', '办理环节'];
+function matchItemType(guide, itemTypeMatching, options) {
+    if (options?.itemTypeOverride) {
+        return { itemType: options.itemTypeOverride, matchSource: 'manual' };
+    }
     if (!itemTypeMatching)
-        return null;
+        return { itemType: null, matchSource: null };
     const itemName = String(guide['事项名称'] ?? '');
     const itemCode = String(guide['事项编码'] ?? '');
     for (const [itemType, rule] of Object.entries(itemTypeMatching)) {
-        if (rule.keywords.some((kw) => itemName.includes(kw)))
-            return itemType;
-        if (itemCode && itemCode.startsWith(rule.codePrefix))
-            return itemType;
+        if (rule.keywords.some((kw) => itemName.includes(kw))) {
+            return { itemType, matchSource: 'name' };
+        }
+    }
+    for (const [itemType, rule] of Object.entries(itemTypeMatching)) {
+        if (itemCode && itemCode.startsWith(rule.codePrefix)) {
+            return { itemType, matchSource: 'code' };
+        }
+    }
+    for (const flowKey of FLOW_FIELD_KEYS) {
+        const flowText = String(guide[flowKey] ?? '');
+        if (!flowText)
+            continue;
+        for (const [itemType, rule] of Object.entries(itemTypeMatching)) {
+            if (rule.keywords.some((kw) => flowText.includes(kw))) {
+                return { itemType, matchSource: 'flow' };
+            }
+        }
     }
-    return null;
+    return { itemType: null, matchSource: null };
 }
 function extractTimeLimitDays(timeLimit) {
     const str = String(timeLimit ?? '');
@@ -141,18 +160,28 @@ function detectConditions(guide, guideId, itemType, kb, severityMapping) {
     return details;
 }
 export const SemanticRuleEngine = {
-    detect(guide, guideId, kb, itemTypeMatching, severityMapping) {
+    detect(guide, guideId, kb, itemTypeMatching, severityMapping, options) {
+        const matchResult = matchItemType(guide, itemTypeMatching, options);
+        const itemType = matchResult.itemType;
+        if (!itemType) {
+            const warning = UnmatchedWarningBuilder.build(guideId);
+            return { details: [], unmatched: true, warning };
+        }
         if (!kb || !kb.timeLimits || !kb.materials || !kb.conditions) {
+            if (options?.degradedMode) {
+                return { details: [] };
+            }
             throw new Error('GOV_DATA_KB_MISSING: 标准知识库不可用，语义错误检测已中止');
         }
-        const itemType = matchItemType(guide, itemTypeMatching);
-        if (!itemType)
-            return [];
+        const hasKbData = kb.timeLimits.length > 0 || kb.materials.length > 0 || kb.conditions.length > 0;
+        if (!hasKbData && options?.degradedMode) {
+            return { details: [] };
+        }
         const details = [];
         details.push(...detectTimeLimit(guide, guideId, itemType, kb, severityMapping));
         details.push(...detectMaterials(guide, guideId, itemType, kb, severityMapping));
         details.push(...detectConditions(guide, guideId, itemType, kb, severityMapping));
-        return details;
+        return { details };
     },
     matchItemType,
     extractTimeLimitDays,

package/lib/unmatchedWarningBuilder.js

@@ -0,0 +1,10 @@
+export const UnmatchedWarningBuilder = {
+    build(guideId) {
+        return {
+            type: 'UNMATCHED_ITEM_TYPE',
+            guideId,
+            message: '该事项未匹配到检测规则，语义检测被跳过',
+        };
+    },
+};
+//# sourceMappingURL=unmatchedWarningBuilder.js.map

package/lib/urlReachabilityChecker.js

@@ -0,0 +1,28 @@
+export const UrlReachabilityChecker = {
+    async check(dataSource) {
+        if (!dataSource || typeof dataSource !== 'string') {
+            return { reachable: false, error: '数据源路径为空' };
+        }
+        if (dataSource.startsWith('http://') || dataSource.startsWith('https://')) {
+            try {
+                const response = await fetch(dataSource, {
+                    method: 'HEAD',
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (response.ok) {
+                    return { reachable: true };
+                }
+                return { reachable: false, error: `数据源不可达，HTTP状态码: ${response.status}` };
+            }
+            catch (e) {
+                return { reachable: false, error: `数据源不可达: ${e.message}` };
+            }
+        }
+        const { existsSync } = require('node:fs');
+        if (existsSync(dataSource)) {
+            return { reachable: true };
+        }
+        return { reachable: false, error: '数据源不可达，请检查路径或 URL' };
+    },
+};
+//# sourceMappingURL=urlReachabilityChecker.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liuhange/dsh-gov-data-inspector",
   "description": "Government data inspection plugin: service guide quality check and public data asset classification",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "publishConfig": {
     "access": "public"
   },
@@ -23,14 +23,10 @@
   },
   "files": [
     "lib/**/*.js",
-    "lib/types/**/*.d.ts"
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml"
   ],
   "license": "MIT",
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsc"
-  },
   "dependencies": {
     "@liuhange/dsh-data-asset-shared": "^3.1.0"
   },
@@ -40,7 +36,7 @@
   },
   "dsh": {
     "bundle": {
-      "patch": true
+      "patch": "./cordis.patch.yml"
     }
   },
   "keywords": [
@@ -56,7 +52,22 @@
     "gbt-47949",
     "政务数据",
     "公共数据",
-    "办事指南"
+    "办事指南",
+    "dsh",
+    "typescript",
+    "nodejs",
+    "automation",
+    "audit",
+    "compliance",
+    "data-governance",
+    "data-quality",
+    "plugin",
+    "open-source"
   ],
-  "homepage": "https://github.com/liuhange789/data-asset-inspector#readme"
-}
+  "homepage": "https://github.com/liuhange789/data-asset-inspector#readme",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc"
+  }
+}