street-12345-reply · 12345 工单答复 Skill

把「逐条查政策 + 凑四要素 + 反复改语气」的人工流程压缩为「AI 出四要素初稿 + 人审事实与口径」的协作流程。政策条款 chunk 级回溯，红 / 橙 / 黄三色敏感工单隔离，红色工单不生成完整答复，所有产出由人工定稿、不直连 12345 平台。

不可突破的红线

1. 政策条款 chunk 级回溯： 每个政策断言必须溯源到具体 chunk（文件号 + 条款号 + 生效日期）。AI 不自行概括、不编造不存在的条款、不引用已废止政策。
2. 红色工单不生成完整四要素： 涉法涉诉 / 紧急安全类红色工单仅生成诉求回应框架 + 政策参考，办理情况和后续承诺由法务/相关业务部门人工填写（零容忍安全边界）。
3. 历史相似案例要点化： 检索到的相似办结工单只显示要点摘要，不返回全文，避免错误传染（C-02 防御）。
4. 入库前数据脱敏： 姓名 / 手机 / 身份证 / 座机 / 银行卡 / 邮箱通过正则脱敏；办结 24 个月归档、36 个月销毁。
5. 所有产出由人工定稿： 答复初稿仅作"待审核"提交至 12345 平台；不直连 12345 平台、不自动提交、不替代人工把控口径。

一、核心能力速查

二、标准工作流程

前置步骤：脱敏 / 时限 / 长文本检查（最先做）

• 脱敏入库： 入库前对 appeal_text / complainant_info / contact 做正则脱敏（覆盖 6 类字段），姓名按 N+1 字符保留。
• 时限计算： received_at + deadline_days 计算剩余工作日，扣除法定节假日（HOLIDAY_DATES 注入，默认无；2026 年度节假日已硬编码）。
• 长文本策略：
• 2000–5000 字：自动分段摘要输入模型，提示「已超过 2000 字，启用分段摘要策略」。
• \>5000 字：截断到 5000 字，提示「请人工精简诉求核心段落」。
• 重复投诉检查： mark_repeat_appeal() 比对历史办结库，命中则标黄。

步骤一：工单读取与解析（F1）

• 单条录入（粘贴 + ticket_no + complainant + received_at + deadline_days + handling_state）。
• Excel 批量导入（列名自动识别 + 映射方案版本化，下次同模板自动记忆）。
• 提取诉求主题 / 关键词 / 涉及地点 / 涉及主体。
• 状态机流转：草稿 → 待分类。

步骤二：智能分类与分拨（F2）

• 内置 ≥20 一级 / ≥80 二级分类（业务方 v0.1 清单待双签）。
• 三层匹配：精确别名 / 模糊匹配 / LLM 兜底（v1 用关键词评分 + 同义词扩展）。
• Top3 推荐 + 置信度：

• 状态机流转：待分类 → 分类已确认。

步骤三：政策与案例检索（F3）

• 政策检索： BM25（关键词匹配）+ Embedding（条款向量）混合检索，召回 10 条候选，重排取 Top5。
• 条款粒度： chunk_id = {file_no}_{clause_no}_{version}，含文件号 + 条款号 + 发布机构 + 生效日期 + 原文 ≥12 字。
• 层级优先： L1（国家法律）> L2（行政法规）> L3（地方性法规）> L4（地方政府规章）> L5（规范性文件）> L6（内部文件）。
• 同层冲突规则： 距离本街道办近优先 → 时效新近优先 → 历史使用频率优先。
• 相似案例： 诉求摘要 + 分类指纹匹配，仅检索办结 12 个月内答复，要点化展示不返回全文。
• 状态机流转：分类已确认 → 政策检索中 → 初稿生成中。

步骤四：敏感工单标记（F5）

• 关键词词典匹配（红 / 橙 / 黄三色）。
• 强信号词任一命中即标对应颜色；弱信号词组合命中按配置升级。
• 临近超时：剩余工作日 ≤1 标黄；重复投诉：同诉求人 ≥1 次历史标黄。
• 红色工单 = 零容忍边界：仅生成诉求回应 + 政策参考，办理情况与后续承诺由人工填写。

步骤五：答复初稿生成（F4）

• 四要素：诉求回应 / 政策依据 / 办理情况 / 后续承诺。
• 缺失字段强制标【待补充：…】禁止编造。
• 时间承诺参考表：

• 状态机流转：初稿生成中 → 待补充 / 审核中 / 已定稿 / 已退回（取决于颜色与校验结果）。

步骤六：答复质量校验（F6）

五项校验：

强制阻断： 政策引用不通过、红色绕过生成完整四要素（red_bypass）→ 阻断提交。

步骤七：审核工作流（F8）

• 强制审核触发： 红色（涉法涉诉 / 紧急安全）→ 法务审核；橙色（集体投诉 / 媒体关注）→ 业务办主任审核；用户主动勾选"提交前复核"。
• 三态动作： pass（通过）/ reject（退回修改，强制填原因）/ transfer（转派）。
• 并发安全： 乐观锁版本号；编辑同一工单冲突时，后修改者收到"该工单已被修改，请刷新"提示。
• 状态机流转：审核中 → 已定稿 / 已退回。

步骤八：批量处理（F7）

• 性能档：

• 串行队列，单 AI BOX 禁止并发抢占。
• 红色工单不批量生成，需逐条人工处理。
• 导出 Excel（含工单编号 / 分类 / 标记 / 答复 / 状态）。

三、任务状态机（F9）

10 态机，状态流转图见 references/state-machine.md（或在 scripts/task_state_machine.py 中查看）。

状态定义与允许操作

合法流转

草稿 → 待分类
待分类 → 分类已确认 / 已退回
分类已确认 → 政策检索中 / 已退回
政策检索中 → 初稿生成中 / 已退回
初稿生成中 → 待补充 / 已定稿 / 审核中 / 已退回
待补充 → 初稿生成中
审核中 → 已退回 / 已定稿
已退回 → 草稿 / 待分类 / 分类已确认 / 政策检索中 / 初稿生成中
已定稿 → 已提交 / 审核中 / 已退回
已提交 → （终态）

非法流转抛 IllegalTransition（见 references/error-codes.md）。

版本快照策略

• 自动快照点： 解析完成 / 分类确认 / 政策检索完成 / 初稿生成完成 / 审核通过。
• 触发条件： 任一关键节点流转成功后，自动写入 audit_log 与 state_transitions 表。
• 回退机制： 通过 task_state_machine.history(ticket_no) 可查询完整轨迹，办理人可基于快照回退到指定状态（v1.1 计划：回退接口 rollback_to_snapshot(ticket_no, snapshot_id)）。
• 保留期： 办结后随工单一同归档 24 个月，过期随工单销毁。

错误恢复机制

• 心跳写入： audit_log 表每步操作实时落盘（v1.1 计划：30 秒一次心跳）。
• 进程崩溃恢复： 启动时扫描 tickets.current_state，识别 政策检索中 / 初稿生成中 等中间态时，提示用户重试或转人工。
• 超时降级： 单条生成 90 秒未完成，自动降级到"占位符 + 仅检索"模式；批量超时按已成功部分保留进度。
• 回滚操作： 见 policy_version_manager.rollback(file_no, actor, reason)，双签直接下线。

四、数据合规与安全（F11）

字段级脱敏清单（入库前正则）

数据生命周期

涉密识别

• 关键词清单： references/secret-keywords.md（v1.1 待补，含「秘密 / 机密 / 绝密 / 工作秘密」等）。
• 触发条件： 文件名或内容含密级标注 → 立即拒绝处理、不摘录、不写入任何产出。
• 当前 v1 实现： v1 不强制接入涉密扫描；v1.1 加 scripts/check_secret_keywords.py 类似 S2 实现。

操作日志覆盖范围

• 全部动作：parse / classify / policy_retrieve / mark / generate / validate / state_transition / policy_upload / policy_signoff / policy_gray / policy_blacklist / review_pass / review_reject / review_transfer / export。
• 日志字段：操作人、时间、动作、对象（工单号 / 政策 ID）、详细参数、关联版本号。
• 保留期：与工单生命周期一致（办结 24 月归档 / 36 月销毁）。
• 查询接口：audit_logger.query(ticket_no, action, limit)。

导出二次确认

• data_masking.export_check(text) 扫描导出内容是否还有未脱敏字段。
• 导出前必须通过检查；含 手机号 / 身份证号 / 银行卡 / 邮箱 等任一字段 → 阻止导出并提示。

五、性能与容量

数据量分级

单条性能目标

验收基线条件

• AI BOX 标准版：CPU ≥16 核 / 内存 ≥64 GB / 磁盘 ≥2 TB SSD / Python 3.10+。
• 单 box 串行队列，禁止并发抢占。
• 单任务并发：≤10 人同时使用。
• 政策库种子 ≥15 部 / ≥30 条款（v1.0）。
• 含范围/逻辑/格式三类校验（默认全开）。

六、交付形态

输出格式

• 单条答复：JSON（含 appeal_response / policy_basis / policy_basis_chunks / handling / followup / full_text / pending / disclaimer_hits / state）。
• 批量导出：xlsx，列：ticket_no / appeal_summary / color / classification / full_text / version / state。
• 状态查询：JSON，含 current_state / history / mark / classification。
• 审计查询：JSON，list[audit_log]。

命名模板

• 默认：{工单号}_回复_draft_{YYYYMMDD}.xlsx。
• 批量：批量_{N条}_{YYYYMMDD}.xlsx。
• 已定稿改名：_final 后缀替换 _draft。
• 不覆盖原文件：每次生成新文件，保留历史。

待审核标注

• 工单 state 字段流转至 审核中 后，所有导出内容自动加「【待审核】」前缀。
• 数据库 replies.state 字段值同步。
• 拒绝在红色工单导出未补全内容。

政策库导出

• 政策表导出格式：xlsx，列：file_no / file_name / clause_no / clause_text / publisher / effective_date / layer / status / version。
• 仅 status='active' 政策可被引用；graying 仅供查阅。

七、交付前自检（逐条过）

7.1 数据完整性

• [ ] 诉求内容已脱敏入库，6 类敏感字段无原文
• [ ] 政策引用全部能溯源到 chunk（file_no + clause_no + version 三者全匹配）
• [ ] 红色工单不出现完整办理情况 / 后续承诺
• [ ] 缺失字段全部标【待补充：…】，无编造

7.2 答复质量

• [ ] 四要素全部有实质内容
• [ ] 字数在 200–500 字参考区间（<100 或 >800 需有提示）
• [ ] 语气未触发禁用词词典
• [ ] 时间承诺在参考表区间（≤10 工作日）

7.3 审核流程

• [ ] 红色工单流转至「审核中」+ 法务审核
• [ ] 橙色工单流转至「审核中」+ 业务办主任审核
• [ ] 退回必填原因（强校验）
• [ ] 转派必须指定目标
• [ ] 乐观锁版本号校验通过

7.4 审计与合规

• [ ] audit_log 记录完整（解析 / 分类 / 检索 / 标记 / 生成 / 校验 / 状态流转 / 审核 / 导出）
• [ ] 政策上传双签
• [ ] 政策作废经过灰名单 30 天
• [ ] 导出前 export_check 通过
• [ ] 销毁调度登记入 archive_pool.destroy_after

八、何时不用本 Skill（边界说明）

九、常见问题 FAQ

Q1：政策库里没有我需要的法规怎么办？
A：业务方用 policy-upload 子命令上传新政策（draft 状态），待业务办主任双签生效；或临时走人工起草模式，待政策库扩展。

Q2：红色工单已标红，AI 怎么还生成了完整四要素？
A：这是 v1 的强制阻断场景——red_bypass 异常会被 F6 校验捕获并阻断提交。出现则代表代码 bug，立即提交工单回退。

Q3：批量处理中途某条工单抛错怎么办？
A：process_batch 会捕获异常并记录到结果列表的 errors 字段，继续处理其他工单；用户可从导出 Excel 中看到错误详情。

Q4：政策作废后，引用了此条款的旧工单怎么办？
A：自动扫描 replies.policy_basis LIKE '%<file_no>%'，把受影响答复标"原引条款已失效，请复核"；办结工单历史保留但提示复核。

Q5：节假日配置需不需要每年更新？
A：是。sensitive_marker.HOLIDAY_DATES 目前硬编码 2026 年度，2027 年起需在每年 W1 周由技术维护更新。

Q6：分类准确率低怎么办？
A：先看 SEED_KEYWORDS 是否覆盖本街道办高频诉求；如仍不足，进入 v1.1 切换 LLM 兜底（接口已留）。

Q7：审核驳回必须填原因吗？
A：是。reject_review(comment="") 会抛 ValueError("退回必须填写原因")。这是 PRD §5.8 强校验。

Q8：政策库的种子是否够用？
A：v1.0 内置 15 部核心法规（覆盖大气 / 噪声 / 物业 / 民法典 / 劳动 / 市容 / 食安 / 消防 / 城规 / 应急 / 民政 / 信访 / 维修资金 / 传销 / 价格），30+ 关键条款；建议业务方在 W2 末扩展至 ≥50 部。

Q9：办结 24 个月归档后还能查吗？
A：归档后仍可检索（数据库内），只是物理上从在线存储迁移到归档存储；36 个月销毁后从归档存储删除。

Q10：单 AI BOX 上限是多少？
A：CPU ≥16 核 / 内存 ≥64 GB / 磁盘 ≥2 TB。串行队列；超过 10 人同时使用应升级到多 AI BOX（v2 计划）。

十、参数定义

10.1 工单输入字段（单条 / 批量均适用）

10.2 答复输出字段（process_one 返回）

10.3 状态字段（state）

10.4 错误码（详见 references/error-codes.md）

S3 已定义 8 类异常 + 30+ 错误码，按模块分类（数据源 / 解析 / 分类 / 检索 / 标记 / 生成 / 校验 / 审核 / 状态机 / 政策 / 监控）。

十一、依赖与运行

• Python ≥ 3.10。
• openpyxl>=3.1（批量 Excel 导入 / 导出）。
• 所有计算在 AI BOX 本地完成，不出本机；无外部网络依赖。
• 单 box 串行队列。

# 安装依赖
pip install -r requirements.txt

# 运行测试（77 项全过）
PYTHONPATH=. python3 -m unittest discover -v tests

# 端到端处理一条诉求
python3 -m scripts.skill_cli --db data/work.sqlite run \
    --ticket-no 001 --text "楼下餐馆油烟扰民"

# 批量导入
python3 -m scripts.skill_cli --db data/work.sqlite batch \
    --excel data/sample/批量工单.xlsx --save-mapping data/mapping.json

# 导出
python3 -m scripts.skill_cli --db data/work.sqlite export \
    --input data/ticket_nos.json --output data/回复.xlsx

十二、与 PRD 对应

完整映射见各模块 docstring；以下为功能模块与 PRD 章节对应关系：

十三、参考文件（按需读取）

• README.md：开发者向实现说明与模块清单。
• _skillhub_meta.json：SkillHub 上架元数据。
• config/shawn.json：作者元数据。
• config/categories.json：分类清单 + 部门职责表 + 阈值。
• config/policies_seed.json：内置政策库（15 部 / 30+ 条款）。
• config/sensitive_keywords.json：红/橙/黄关键词词典。
• config/disclaimer_words.json：禁用与推荐词库。
• config/mask_patterns.json：脱敏正则与生命周期。
• config/reply_templates.json：时间承诺参考表。
• references/four-elements.md：四要素规范。
• references/policy-layers.md：政策层级优先级。
• references/classification-guide.md：分类体系说明。
• references/error-codes.md：错误码表（按模块）。
• data/sample/：3 份示例工单。
• tests/：77 个测试全过。
• scripts/：14 个业务模块 + 1 编排 + 1 CLI。