Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/

2026-08-07 22:31:32 +08:00

17 KiB

Raw Blame History

PRD - 敏感词检测 v1.2（AI 辅助运营）

需求编号: REQ-通用-004 版本: v1.2（基于 v1.1 升级）状态: 草案 v1.0（待评审）作者: 宋献日期: 2026-07-28 前置版本: PRD-REQ-通用-004-敏感词检测-v1.0（v0.7.1 上线），v1.1（DB化+后台 UI+审计日志，2026-07-28 上线） 关联文档:

前置 PRD：01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md

前置技术方案：02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md

关联战略：01-产品文档/00-产品规划/IT服务台AI化战略路线图-v1.0.md

1. 需求描述

1.1 背景（v1.1 回顾）

v1.1（2026-07-28 上线）实现了：

词库入库（sensitive_words / privacy_patterns）
后台管理 UI（4 Tabs）
命中审计日志
灰度开关

但 v1.1 仍然依赖人肉运营：

新敏感词需运营逐条人工发现并加入
词库命中规则写死 4 条 + 运营手动扩展
绕过场景（如"自己不会百度嘛"加语气词）无法识别
词库命中率/误判率无人系统分析

1.2 v1.2 升级动机

业务压力：组织正经历 AI 技术冲击，没有时间从"人肉维护"过渡到"AI 维护"，敏感词检测 v1.2 必须直接进入 AI 辅助运营阶段。

1.3 v1.2 目标

目标	描述
G1 自动化运营	词库发现 / 分类 / 调整由 AI 完成，人工仅最终审核
G2 绕过场景覆盖	引入 AI 语义级检测，替代 wordfilter 主路径
G3 反馈闭环	误判自动反馈 → AI 学习 → 自动加白名单
G4 数据驱动	命中率/误判率/绕过模式可量化分析

1.4 范围

范围项	v1.2 状态	说明
AI 敏感词发现引擎	✅ P0 必做	Dify 工作流：历史 messages + 工单 → LLM 提取
AI 审核工作台	✅ P0 必做	运营一键 approve / reject
AI 误判反馈闭环	✅ P0 必做	坐席 WARN 后"非命中"反馈 → AI 学习 → 白名单建议
AI 语义级检测	✅ P0 主路径	替代 wordfilter（用户决策 2026-07-28 确认）
AI 自动构造测试用例	🟡 P1	对抗样本自动生成
AI 智能日报	🟡 P1	每日违规模式自动分析
AI 自动审批（无人审核）	❌ P2 不做	与 2026-07-08 决策冲突，保留人工最终审核
AI 自动变更 severity	❌ P2 不做	需配套审计，待评审

1.5 Non-goals

不做	原因
完全无人化（AI 全自动）	决策保留：所有 AI 推荐需人工最终确认
多语言支持	业务尚未确认
跨租户词库隔离	当前单租户架构，无 SaaS 化需求
组织级 AI 化变革	独立任务（见 AI 化路线图），v1.2 仅做工具自身 AI 化

2. 用户故事

2.1 运营人员

优先级	用户故事
P0	作为运营，我希望看到 AI 自动推荐的新词候选，一键加入词库
P0	作为运营，我希望 AI 自动判定分类（profanity/privacy）和 severity，无需我手动选
P0	作为运营，我希望 AI 自动分析"非命中"反馈，给出白名单建议
P1	作为运营，我希望看到每日违规分析报告（高频词/高频坐席）
P1	作为运营，我希望 AI 自动生成对抗样本测试，验证词库覆盖率

2.2 坐席

优先级	用户故事
P0	作为坐席，我希望 AI 能识别"自己不会百度嘛"等绕过的语气（不被精确匹配绕过）
P0	作为坐席，我希望误报时一键标记"非命中"，系统记住我的反馈
P0	作为坐席，我希望继续保留最终发送权（不被 AI 强制阻断）

2.3 管理员

优先级	用户故事
P1	作为管理员，我希望所有 AI 推荐/审核记录可追溯
P1	作为管理员，我希望 AI 引擎可灰度启用（如先 1 个部门试运行）
P2	作为管理员，我希望 AI 引擎可关闭，回到 v1.1 模式

3. 功能需求

3.1 AI 敏感词发现引擎（P0）

字段	规格
输入数据	1) 历史 messages（最近 30 天） 2) 工单投诉内容 3) 审计日志（被 WARN 的文本） 4) 运营白名单（已知非敏感词）
AI 处理	Dify 工作流： ① 数据采样（按时间+部门） ② LLM 推理（提取风险词 + 判定分类 + 判定 severity） ③ 去重（与现有词库 diff） ④ 输出"待审核"队列
触发时机	每日凌晨 03:00 自动跑（cron）运营可手动触发（按钮）
输出	`ai_pending_words` 表（待审核队列）
数据量	30 天 messages 约 1 万条，LLM 处理 ≈ 30 秒

3.2 AI 审核工作台（P0）

字段	规格
位置	`/sensitive-words` 管理后台 → 新增 Tab"AI 推荐"
展示	待审核词列表：word / category / severity / AI 置信度 / 来源 / 推荐时间
操作	1) approve → 写入 `sensitive_words` 表 2) reject → 标记"已拒绝"，不再推荐 3) 编辑 → 修改 word/category/severity 后 approve
批量	支持批量 approve（多选）
审计	所有操作写 `ai_word_review_logs` 表

3.3 AI 误判反馈闭环（P0）

字段	规格
坐席侧	WARN 提示条增加"非命中"按钮
后端	接收反馈 → 写入 `false_positive_feedback` 表（text / agent_id / timestamp）
AI 处理	每日分析"非命中"反馈： ① 提取频繁被标记的词/短语 ② LLM 判定"确为误报" → 自动加白名单 ③ LLM 判定"需复审" → 入 AI 审核队列
白名单存储	新增 `whitelist` 表（phrase / category / source / created_at）
检测逻辑	审核时：先查白名单 → 命中则直接 PASS

3.4 AI 语义级检测（P0 主路径）

字段	规格
替代目标	替代 wordfilter 作为主检测引擎
实现方式	Dify LLM 调用（GPT-4o-mini 或国产模型）
输入	坐席消息文本
输出	`{action, category, matched_concepts, confidence, suggestion}`
响应时间	< 2s（P95）
成本	¥0.001 / 次（GPT-4o-mini）按日均 1 千条消息 ≈ ¥1/天
降级策略	Dify 不可用时 → 降级为 wordfilter（v1.1 引擎）降级日志：ERROR + 计数
决策动作	仍维持 WARN（2026-07-08 决策保留）
旁路	wordfilter 仍作为快速预筛（命中则直接 WARN，不调 AI）未命中 → 调 AI 语义

3.5 AI 自动构造测试用例（P1）

字段	规格
触发	CI 流水线 / 运营手动
生成	LLM 自动生成 100 条对抗样本（语气词 / 同义词 / 拼音化）
跑测	自动跑 pytest 报告
输出	覆盖率报告：词库覆盖 / AI 语义覆盖 / 遗漏点

3.6 AI 智能日报（P1）

字段	规格
触发	每日 08:00 自动生成
内容	1) 命中总数（按 action / category 分布） 2) 高频违规坐席（Top 10） 3) 高频违规部门（按部门聚合） 4) 命中时段分布（小时级热力图） 5) AI 语义命中 vs wordfilter 命中（覆盖率对比） 6) 误报率（"非命中"反馈占比）
推送	管理员企微消息卡片
存储	`daily_reports` 表（30 天滚动）

4. 数据需求

4.1 新增表

`ai_pending_words`（AI 推荐词队列）

CREATE TABLE ai_pending_words (
    id              SERIAL PRIMARY KEY,
    word            VARCHAR(100) NOT NULL,
    category        VARCHAR(50) NOT NULL,
    severity        SMALLINT NOT NULL,
    confidence      DECIMAL(3,2) NOT NULL,    -- 0.00~1.00
    source          VARCHAR(50) NOT NULL,      -- message_sample / complaint / audit_log
    sample_text     TEXT,                      -- 原始样本（前 200 字）
    status          VARCHAR(20) DEFAULT 'pending', -- pending / approved / rejected
    reviewed_by     INTEGER REFERENCES users(id),
    reviewed_at     TIMESTAMP,
    created_at      TIMESTAMP DEFAULT NOW(),
    UNIQUE(word, status)
);
CREATE INDEX idx_pending_status ON ai_pending_words(status, created_at);

`false_positive_feedback`（误判反馈）

CREATE TABLE false_positive_feedback (
    id              BIGSERIAL PRIMARY KEY,
    agent_id        INTEGER NOT NULL REFERENCES agents(id),
    original_text   TEXT NOT NULL,
    matched_word    VARCHAR(100),
    category        VARCHAR(50),
    created_at      TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_fp_agent ON false_positive_feedback(agent_id, created_at);

`whitelist`（白名单）

CREATE TABLE whitelist (
    id              SERIAL PRIMARY KEY,
    phrase          VARCHAR(200) NOT NULL UNIQUE,
    category        VARCHAR(50),
    source          VARCHAR(50),                -- ai_auto / manual / fp_feedback
    created_at      TIMESTAMP DEFAULT NOW(),
    expires_at      TIMESTAMP                   -- 可选：临时白名单
);

`ai_word_review_logs`（AI 推荐审核记录）

CREATE TABLE ai_word_review_logs (
    id              BIGSERIAL PRIMARY KEY,
    pending_id      INTEGER REFERENCES ai_pending_words(id),
    reviewer_id     INTEGER REFERENCES users(id),
    action          VARCHAR(20) NOT NULL,       -- approve / reject / edit
    original_word   VARCHAR(100),
    final_word      VARCHAR(100),
    notes           TEXT,
    created_at      TIMESTAMP DEFAULT NOW()
);

`daily_reports`（每日报告）

CREATE TABLE daily_reports (
    id              SERIAL PRIMARY KEY,
    report_date     DATE UNIQUE NOT NULL,
    payload         JSONB NOT NULL,
    created_at      TIMESTAMP DEFAULT NOW()
);

4.2 `sensitive_words` 表扩展

-- 新增字段
ALTER TABLE sensitive_words ADD COLUMN source VARCHAR(50) DEFAULT 'manual';
-- source 取值: manual / ai_recommend / imported / migrated_from_v07

ALTER TABLE sensitive_words ADD COLUMN confidence DECIMAL(3,2);
-- 仅 ai_recommend 来源的词有置信度

4.3 Alembic 迁移

新建：alembic/versions/057_add_ai_moderation_tables.py

5. 接口需求

5.1 新增后端 API（11 端点）

接口	方法	说明	权限
`/api/admin/ai-pending-words`	GET	列表查询	admin
`/api/admin/ai-pending-words/{id}/approve`	POST	审核通过	admin
`/api/admin/ai-pending-words/{id}/reject`	POST	审核拒绝	admin
`/api/admin/ai-pending-words/batch-approve`	POST	批量通过	admin
`/api/admin/ai-pending-words/trigger`	POST	手动触发 AI 发现	admin
`/api/admin/false-positive-feedback`	POST	坐席提交反馈	agent
`/api/admin/false-positive-feedback`	GET	查询反馈	admin
`/api/admin/whitelist`	GET/POST/PUT/DELETE	白名单 CRUD	admin
`/api/admin/whitelist/auto-suggest`	POST	AI 基于反馈生成建议	admin
`/api/admin/daily-reports/latest`	GET	最新日报	admin
`/api/admin/daily-reports/{date}`	GET	指定日期日报	admin

5.2 改造现有 API

接口	变更
`POST /admin/sensitive-words/test`	增加 AI 语义模式（`mode=ai`）
`GET /admin/moderation-config`	增加 `ai_engine_enabled` 字段
`PUT /admin/moderation-config`	增加 AI 引擎开关

5.3 Dify 工作流（3 个）

工作流	用途
`sensitive_word_discovery`	输入 messages → 输出风险词列表
`false_positive_analyzer`	输入 fp_feedback → 输出白名单建议
`daily_report_generator`	输入审计日志 + 命中数据 → 输出日报

5.4 配置项（v1.2 新增）

# config.py
AI_MODERATION_ENABLED = False  # 总开关
AI_DISCOVERY_CRON_HOUR = 3     # 每日 AI 发现执行时间
AI_DAILY_REPORT_HOUR = 8       # 日报推送时间
DIFY_DISCOVERY_APP_ID = "..."  # 复用现有 Dify app
DIFY_API_KEY = "..."           # 从 .env 读
WHITELIST_ENABLED = True        # 白名单开关

配置同步铁律：新增 6 个配置项时需同步：

config.py 字段
docker-compose.yml 的 backend.environment
.env.example 模板

6. 数据隐私合规（重要）

6.1 LLM 输入数据合规

数据类型	合规要求
历史 messages	喂 LLM 前脱敏：移除手机号/身份证/邮箱/姓名
工单投诉内容	同样脱敏
审计日志	已脱敏（v1.1 仅存 text_excerpt 100 字）

6.2 脱敏规则

# content_moderation_service.py 新增 _sanitize_for_ai()
def _sanitize_for_ai(text: str) -> str:
    """喂 AI 前脱敏"""
    text = re.sub(r'(?<!\d)1[3-9]\d{9}(?!\d)', '[PHONE]', text)
    text = re.sub(r'(?<!\d)\d{17}[\dXx](?!\d)', '[ID_CARD]', text)
    text = re.sub(r'(?<!\d)\d{16,19}(?!\d)', '[BANK]', text)
    text = re.sub(r'[\w.-]+@[\w.-]+\.[\w]+', '[EMAIL]', text)
    text = re.sub(r'[\u4e00-\u9fa5]{2,4}(?=先生|女士|老师|经理|总)', '[NAME]', text)
    return text

6.3 合规审计

审计项	实施
LLM 调用日志	`ai_llm_calls` 表：app_id / 输入 hash / 输出 / 延迟 / 成本
数据脱敏校验	单元测试：确保喂 LLM 前已脱敏
运营 review 记录	所有 AI 推荐审核写入 `ai_word_review_logs`
错误监控	Sentry / 日志告警：Dify API 失败率 > 5%

7. 风险与降级

风险	等级	降级措施
Dify API 不可用	🟡 中	自动降级为 wordfilter（v1.1 引擎）
AI 推荐质量低	🟡 中	置信度 < 0.7 不入"待审核"队列
脱敏不彻底泄露隐私	🟠 高	脱敏失败时不调 LLM，直接降级 wordfilter
AI 误判高（绕过场景也误报）	🟡 中	人工 review 必须；自动阈值兜底
审计日志爆炸	🟢 低	7 天前的旧 fp_feedback 自动清理
AI 引擎与决策冲突	🟡 中	保留人工最终审核（决策保留 2026-07-08）

8. 验收标准

8.1 必达项（v1.2 P0）

AI 发现引擎每天 03:00 自动跑，生成 ≥ 1 个推荐词（基于历史数据）
AI 审核工作台：运营可一键 approve / reject / 批量 approve
AI 误判反馈闭环：坐席"非命中"按钮 → 24h 内 AI 自动分析
AI 语义级检测作为主路径：Dify 不可用时降级 wordfilter
AI 语义覆盖"自己不会百度嘛"等语气绕过场景
数据脱敏：喂 LLM 前已移除 PII
所有 AI 推荐均经人工最终确认
命中动作仍为 WARN（决策保留）
白名单生效：白名单词命中 WARN 时直接 PASS
灰度开关：AI_MODERATION_ENABLED=false 时回到 v1.1 行为

8.2 非必达（v1.2 P1 / P2）

AI 自动构造测试用例（P1）
AI 智能日报推送（P1）
AI 自动审批（不做）
AI 自动变更 severity（不做）

9. 实施路线

阶段	内容	工作量
D1	Dify 工作流（3 个）开发 + 测试	2 天
D2	后端：5 新表 + 11 API + 现有 API 扩展	2 天
D3	前端：AI 审核工作台 + 误报反馈按钮 + 白名单 UI	2 天
D4	AI 语义级检测集成 + 降级逻辑	1 天
D5	数据脱敏 + 合规审计	0.5 天
D6	部署 + 灰度发布（先 1 个坐席试运行 24h）	1 天
总计		8.5 天

10. 关联文档

文档	位置	关联点
前置 PRD v1.0	`01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md`	基础功能
前置技术方案 v1.0	`02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md`	实现参考
前置测试用例	`03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md`	测试基线
关联战略	`01-产品文档/00-产品规划/IT服务台AI化战略路线图-v1.0.md`	v1.2 是战略落地的第一个抓手
Dify 应用清单	`02-技术文档/实现配置/dify_dsl/`	新增 3 工作流
看板验真测试报告	`03-测试文档/04-版本测试报告/看板验真-测试报告-20260707.md`	历史基线

11. 变更日志

版本	日期	变更	变更人
v1.0	2026-07-28	首次整理：v0.7.1 上线内容回溯为正式 PRD	宋献
v1.1	2026-07-28	DB化 + 后台 UI + 审计日志 + 灰度开关	宋献
v1.2 草案 v1.0	2026-07-28	AI 辅助运营：AI 语义级检测纳入 P0 替代 wordfilter	宋献

关键决策记录：

2026-07-08：命中动作固定 WARN（v1.0 决策）

2026-07-28：v1.1 上线（DB化）

2026-07-28：v1.2 启动，AI 语义级检测作为主路径，AI 辅助运营为定位

17 KiB Raw Blame History Unescape Escape

PRD - 敏感词检测 v1.2（AI 辅助运营）

1. 需求描述

1.1 背景（v1.1 回顾）

1.2 v1.2 升级动机

1.3 v1.2 目标

1.4 范围

1.5 Non-goals

2. 用户故事

2.1 运营人员

2.2 坐席

2.3 管理员

3. 功能需求

3.1 AI 敏感词发现引擎（P0）

3.2 AI 审核工作台（P0）

3.3 AI 误判反馈闭环（P0）

3.4 AI 语义级检测（P0 主路径）

3.5 AI 自动构造测试用例（P1）

3.6 AI 智能日报（P1）

4. 数据需求

4.1 新增表

ai_pending_words（AI 推荐词队列）

false_positive_feedback（误判反馈）

whitelist（白名单）

ai_word_review_logs（AI 推荐审核记录）

daily_reports（每日报告）

4.2 sensitive_words 表扩展

4.3 Alembic 迁移

5. 接口需求

5.1 新增后端 API（11 端点）

5.2 改造现有 API

5.3 Dify 工作流（3 个）

5.4 配置项（v1.2 新增）

6. 数据隐私合规（重要）

6.1 LLM 输入数据合规

6.2 脱敏规则

6.3 合规审计

7. 风险与降级

8. 验收标准

8.1 必达项（v1.2 P0）

8.2 非必达（v1.2 P1 / P2）

9. 实施路线

10. 关联文档

11. 变更日志

17 KiB

Raw Blame History

`ai_pending_words`（AI 推荐词队列）

`false_positive_feedback`（误判反馈）

`whitelist`（白名单）

`ai_word_review_logs`（AI 推荐审核记录）

`daily_reports`（每日报告）

4.2 `sensitive_words` 表扩展