street-grid-weekly · 网格巡查周报

把"零散记录手工汇总成周报"压缩为"AI 归集分类闭环 + 人审事实与口径"：原始巡查记录自动归一、事件自动识别与分类、隐患 5 态闭环跟踪（NEW/IN_PROGRESS/CLOSED/OVERDUE/PENDING）、多级汇总自动去重、周报双版本输出（完整版+精华版）。所有事实溯源到原始记录，所有处置状态由用户确认，AI 不做推断。

不可突破的红线

1. AI 不推断处置结果。 原始记录中未明确写明"已处理/已整改/已解决"的事件，强制标记为「状态待确认」，由网格员人工确认后写入周报。严禁将「已上报」「已联系」「已协调」等同于「已解决」。（详见 references/ai_no_inference_guardrails.md 4 层强制约束）
2. 周报正文强制脱敏。 正文不出现居民完整姓名、联系电话、详细门牌（保留至楼栋单元）；完整明细仅在本地 Excel 台账保留，不上报上级周报；任何含姓名/电话/身份证的输出必须经过 validators.desensitize_resident 脱敏。
3. 超期未闭环隐患自动标红置顶。 处置中事件持续天数超过配置阈值（默认 7 天，可由街道网格管理中心调整）自动转「超期」状态，周报未闭环事项章节置顶标红，禁止被新事件淹没。
4. 历史事项匹配必须用户确认。 本周记录与历史台账匹配（地点+类型+描述相似度 ≥0.85）时，仅作为建议，必须用户确认才能关联；用户拒绝则作为本周新发现事项独立记录，避免不同事件被错误关联。
5. 三层级权限隔离。 网格员仅看本人记录与本人周报；社区可查看本社区各网格；街道可查看全街道。生成上级周报时自动按层级过滤，超出权限范围的数据不进入汇总。
6. 所有数字可溯源到原始记录。 周报中每个统计数字、户数、天数必须能指回某条原始记录；状态描述仅使用记录中实际出现的关键词，不补全不推理。
7. 不进入涉密内容。 输入材料如含"秘密/机密/绝密/工作秘密"标识或个人信息批量导出，拒绝处理、不摘录、不写入产出、不进入草稿持久化，提示用户线下办理。

一、核心能力速查

二、标准工作流程

前置：可行性检查（必须先做）

• 输入材料不能含密级标识（"秘密/机密/绝密/工作秘密"等），如有则拒绝处理（见红线 7）。
• 单次输入记录条数 ≤500 条（超量建议分批）；总字数 ≤50 万字。
• 选「周报生成」却无任何巡查记录 → 提示用户"本周无巡查记录，无法生成周报"，不生成空泛内容。
• 选「多级汇总」但下级周报文件不存在或格式不识别 → 报错并要求先单网格跑通。

步骤一：记录归集（F1）

支持 5 种输入方式，按用户实际习惯组合：

1. 文字粘贴：用户从微信/笔记本复制多段记录，按双换行（\n\n）分隔，每段生成一条 RawRecord；时间地点关键词自动提取。
2. 语音转写：上传语音文件（≤10 分钟/条），调用 ASR 服务转写；转写置信度低时标「转写待确认」逐句人工复核。
3. Excel/CSV 导入：列名自动识别（日期/地点/内容），必填列缺失报错并给示例模板。
4. 逐条录入：简易表单手动录入，适用于巡查现场立即记一笔。
5. 照片 OCR：上传巡查照片（如楼道杂物照片），OCR 提取文字+ AI 识别场景。

自动后处理：每条记录生成 UUID；时间/地点关键词自动提取；重复检测（相似度 ≥0.85 标"疑似重复"待用户确认）。

步骤二：事件识别与分类（F2）

• 对每条 RawRecord 跑 3 阶段识别：关键词匹配（0.4 权重）→ 语义向量（0.4 权重）→ LLM 兜底（0.2 权重）→ 综合置信度。
• 单条记录允许关联 1-2 个分类（主+次），冲突时按 B 安全 > D 矛盾 > C 卫生 > E 设施 > A 走访 > F 宣传 > G 其他 的优先级选主分类。
• 置信度分层：
• 绿色（≥0.9）：自动接受
• 黄色（0.7-0.9）：建议人工确认
• 红色（<0.7）：强制人工确认才能进入周报

步骤三：隐患闭环跟踪（F4）⭐ 核心

• 对每条事件用 validators.detect_status 检测状态，仅基于原文关键词：
• CLOSED 关键词：已处理/已整改/已解决/已修复/已完成/已消除/已清理
• IN_PROGRESS 关键词：正在/协调中/跟进中/处理中/沟通中/对接中/已联系
• 禁词（不视为 CLOSED）：已上报/已反映/已告知/已通知/已登记
• 与历史台账匹配（地点精确 + 类型相同 + 描述相似度 ≥0.85）→ 必须用户确认才能关联。
• 处置中事件持续天数 > 阈值（默认 7 天）自动转「超期」。
• 计算闭环率 = 已闭环 /（期初遗留 + 本周新发现）×100%。

步骤四：周报生成（F3）

• 完整版（8 章节）：
  1. 本周巡查概况（巡查次数/走访户数/覆盖楼栋）
  2. 事件分类统计（含环比表）
  3. 重点事件与隐患（STAR 模板：情境-任务-行动-结果）
  4. 本周问题与支持需求（影响+措施+支持三要素）
  5. 未闭环事项跟踪（超期置顶标红）
  6. 民情收集摘要
  7. 沉淀与优化（流程改进/典型案例/制度漏洞）
  8. 下周工作计划（事项+负责人+时限+风险）
• 精华版（3 模块）：本周三件大事 + 三个核心数据 + 三项需支持事项，30 秒速览命中关键信息。
• 脱敏强制应用：所有章节中姓名/电话/门牌统一脱敏为「X 栋 X 户居民」「已脱敏」。

步骤五：导出与自检

• 输出 4 类文件：完整版 Word、精华版 Word、Excel 台账、JSON 中间产物、Markdown 自检报告。
• 自检报告覆盖 4 维度：STAR 完整度、数据可溯源率、问题影响度、领导可读性。
• 历史周报自动入库（保存到 history/ 目录），供 F8 后续查询。

三、任务状态机（事件闭环核心）

                ┌─────────────────┐
                │  本周新发现     │  NEW
                │  (默认状态)     │
                └────────┬────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
   ┌──────────┐   ┌──────────┐   ┌──────────┐
   │ 处置中   │   │ 状态待   │   │  直接    │
   │IN_PROG.  │   │  确认    │   │  闭环    │
   │          │   │ PENDING  │   │ CLOSED   │
   └────┬─────┘   └────┬─────┘   └──────────┘
        │              │           (出现闭环关键词)
        │              │ 用户补充
        │              │ 关键词
        │              ▼
        │       ┌──────────┐
        │       │ 处置中/  │
        │       │  已闭环  │
        │       └──────────┘
        │
        │ 持续天数 > 阈值
        │ (默认 7 天)
        ▼
   ┌──────────┐
   │  超期    │  OVERDUE
   │(标红置顶)│
   └────┬─────┘
        │ 出现闭环关键词
        ▼
   ┌──────────┐
   │  已闭环  │  CLOSED
   │ (计入    │
   │  闭环率) │
   └──────────┘

状态转换规则：

严禁的状态转换：
- ❌ PENDING → CLOSED（仅 AI 自动推理）— 必须用户确认
- ❌ IN_PROGRESS → CLOSED 仅基于"已上报"关键词

四、数据合规与安全

4.1 数据本地化

• 所有处理在 AI BOX 本地完成；不联网（除非用户主动启用云端 LLM/ASR/OCR）。
• 历史周报、本周台账、JSON 中间产物保存到本地 history/ 与 output/ 目录。

4.2 脱敏规则（强制）

脱敏实现：scripts/validators.py 中 desensitize_resident()，所有章节渲染前必须调用。

4.3 涉密材料（红线 7）

• 检测关键词：秘密/机密/绝密/工作秘密/机密★/绝密★ 等。
• 命中即拒绝处理，不摘录、不写入产出、不进入草稿状态持久化。
• 提示用户"请走机要室线下办理，本 Skill 无法处理"。

4.4 权限隔离

本期实现：权限校验由调用方负责（如政务平台会话传入 role 字段），Skill 接受 grid_code 与 parent_code 参数做硬过滤。

4.5 操作日志

所有生成、修改、汇总操作记录到 audit_log（含操作人、时间、目标、变更前后），用于审计追溯。

五、性能与容量

5.1 响应时间基线

5.2 容量上限

5.3 资源占用

• 内存峰值：单网格 200 条 ≤500 MB
• 磁盘：每份周报含附件 ≤5 MB
• CPU：单核即可，纯规则模式无 LLM 推理

5.4 降级策略

六、交付形态

6.1 输出文件

6.2 多级汇总输出

6.3 排版规范

• 完整版：3-5 页，含 8 章节，标题黑体，正文宋体 1.5 倍行距。
• 精华版：1 页，3 模块大字呈现。
• 状态着色：超期项红色加粗、处置中项黄色、待确认项灰色斜体、已闭环项绿色。
• 脱敏：周报正文不出现完整姓名/电话/详细门牌；台账保留完整信息但不外发。

6.4 命名标识

• 完整版顶部水印：AI 辅助初稿，待人工审核定稿
• 自检报告顶部水印：待审核：所有事实需复核，闭环率与超期项需人工确认

七、交付前自检（逐条过，全部满足再交付）

7.1 事实与溯源

• [ ] 每个统计数字、户数、影响范围都能指回某条原始记录
• [ ] 没有原始记录中不存在的事实性陈述
• [ ] 数据矛盾未被擅自取舍（出现矛盾应标【待核】）
• [ ] 政治表述均为材料原文（无自撰概括）

7.2 AI 不推断与闭环

• [ ] 所有 PENDING 状态事件已用「待确认」明确提示
• [ ] 无「已上报」被误标为 CLOSED
• [ ] 超期事件标红置顶
• [ ] 闭环率计算正确（已闭环 /（期初遗留 + 本周新发现））
• [ ] 历史事项匹配全部经用户确认

7.3 脱敏

• [ ] 周报正文无完整姓名（王大爷/王小明/张三等）
• [ ] 周报正文无完整电话（11 位手机号）
• [ ] 周报正文无详细门牌（502/302 等房间号）
• [ ] 身份证号、银行卡号、邮箱已脱敏
• [ ] 完整信息仅在 Excel 台账保留

7.4 模板与格式

• [ ] 完整版 8 章节齐备，精华版 3 模块齐备
• [ ] 状态着色：红/黄/绿/灰 正确应用
• [ ] STAR 模板：情境-任务-行动-结果 4 段齐备
• [ ] 重点事件 STAR 完整度 ≥60 分

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

九、常见问题 FAQ

Q1：用户上传了一份空的 Excel，怎么办？
A：提示"未检测到有效巡查记录，请确认文件格式或补充内容"，不生成空周报。

Q2：用户的巡查记录全是"已上报物业"，没有处置结果，怎么办？
A：严禁推断为"已闭环"。所有"已上报"事件标记为「处置中」并在周报中提示网格员补充闭环结果；状态待确认事件置顶提示。

Q3：本周有 30 条记录，分类后只有 5 类，剩 2 条无法归类，怎么办？
A：归入 G 其他类，标记 G1 子类，提示用户"以下事项无法自动归类：XXX，请人工补充分类或描述"。

Q4：用户既需要完整版又需要精华版，5 分钟能跑完吗？
A：30 条记录单网格 30 秒内完成；200 条记录 90 秒内完成；超时提示用户等待或减少数据。

Q5：用户上传了手写扫描件怎么办？
A：提示先 OCR（如扫描全能王），OCR 后再上传；本 Skill 不内置 OCR。

Q6：闭环率很低（<50%），怎么办？
A：在周报"本周问题与支持需求"章节自动生成提示："本周闭环率 X%，建议街道协调资源支持以下未闭环事项：…"，让领导看到治理压力。

Q7：多个网格员上报了同一事件，怎么处理？
A：F5 多级汇总自动去重，合并为一条事件，标注来源网格；台账保留原始记录。

Q8：用户问"下周该做什么"，能给建议吗？
A：基于本周未闭环事项 + 重点工作生成"建议计划"，明确标注"建议"由用户修改；不替用户做决策。

Q9：周报生成失败，怎么办？
A：返回错误码 + 错误位置 + 修复建议；已生成的章节保留可单独保存；不删除用户的输入数据。

Q10：用户对历史周报有疑问（如"上周 5 楼那个事件后来怎么处理的？"），能查吗？
A：F8 历史周报查询支持按网格/时间/类型/状态筛选，可定位到具体历史事件；显示其当前状态（已闭环/处置中/超期等）。

十、参数定义

配置覆盖：业务方可修改 config/closed_loop_rules.json 中的 overdue_threshold_days 等参数。

十一、依赖与运行

11.1 Python 版本与依赖

• Python ≥ 3.11
• 必装：python-docx>=1.1.0、openpyxl>=3.1.0、pydantic>=2.5.0、rapidfuzz>=3.6.0
• 可选：ASR（Whisper）、OCR（PaddleOCR）、LLM 语义分类

11.2 部署模式

11.3 命令行

# 生成单网格员周报
python scripts/skill_main.py generate \
    --grid G001 --grid-name "网格1" \
    --period 2026-09-07_2026-09-13 \
    --records examples/sample_records.json \
    --output ./output

# 多级汇总（社区级）
python scripts/skill_main.py aggregate \
    --level community --parent C001 \
    --child-reports ./child_reports.json \
    --period 2026-09-07_2026-09-13

# 民情日记结构化
python scripts/skill_main.py diary \
    --input examples/sample_diary.txt \
    --output ./output/diary_entries.json

# 历史周报查询
python scripts/skill_main.py query \
    --grid G001 --start 2026-08-01 --end 2026-09-13 \
    --status OVERDUE

11.4 Python API

from scripts.skill_main import StreetGridWeekly

skill = StreetGridWeekly(grid_code="G001", grid_name="网格1")
result = skill.run_full_pipeline(
    records_input="examples/sample_records.json",
    period_start="2026-09-07",
    period_end="2026-09-13",
    output_dir="./output",
)

11.5 单元测试

cd street-grid-weekly
python -m unittest tests.test_validators \
                  tests.test_classify \
                  tests.test_closed_loop \
                  tests.test_diary \
                  tests.test_ingest \
                  tests.test_generate_weekly \
                  tests.test_aggregate

74 个测试用例，覆盖全部 8 大功能 + 红线规则。

十二、与 PRD 对应

十三、参考文件（按需读取，不要一次性全读）

• references/event_taxonomy.md — 7 大类分类详细说明、关键词体系、边界场景——做 F2 分类、看分类疑问时读
• references/closed_loop_rules.md — 5 态生命周期、相似度算法、闭环率公式——做 F4 闭环、查规则细节时读
• references/star_template_guide.md — STAR 模板使用指南、自检评分、改写示例——做 F3 周报、看 STAR 不规范时读
• references/weekly_template.md — 双版本模板、章节结构、脱敏规范、文件命名——做 F3 周报、查模板疑问时读
• references/ai_no_inference_guardrails.md — AI 不推断原则 4 层强制约束、违规熔断机制——遇到 AI 推断问题、查看红线细则时读
• references/data_schema.md — 原始记录/事件/闭环/周报的数据 schema——开发、字段疑问时读
• config/event_taxonomy.json — 分类体系原始数据（程序读）
• config/status_taxonomy.json — 状态分类原始数据（程序读）
• config/closed_loop_rules.json — 闭环规则原始数据（程序读）
• config/star_templates.json — STAR 模板原始数据（程序读）
• config/weekly_template.json — 周报模板原始数据（程序读）
• config/shawn.json — 作者元数据（SkillHub 读）
• examples/sample_records.json — 10 条样例巡查记录
• examples/sample_diary.txt — 5 段样例民情日记
• examples/sample_weekly_output.md — 样例周报输出
• examples/run_end_to_end.py — 端到端运行脚本
• tests/ — 74 个单元测试用例，覆盖全部功能 + 红线规则
• assets/workflow.mermaid — 处理流程图（黄色节点=人工审核，红色节点=超期）
• README.md — 开发者向文档（架构、数据流、二次开发指南）