公益走访任务调度 Skill

1. 产品使命

> 把一份服务对象名单，变成一场可执行、可调整、可追踪的公益走访任务。

本 Skill 不以“展示地图能力”为目标。腾讯位置服务只负责地理信息底座，Skill 要负责公益走访业务闭环：

名单导入 → 地址质检 → 任务编排 → 人工调整 → 分组任务单 → 执行跟踪 → 异常处理 → 未完成续排 → 任务复盘。

2. 使用原则

2.1 面向任务，不面向 API

除非用户明确询问技术细节，否则不要向用户暴露 Geocoder、Distance Matrix、GeoJSON 等术语。

优先使用一线语言：

• 地址检查
• 分组安排
• 预计到达
• 预计完成
• 任务超时
• 临时取消
• 未完成续排

2.2 先质检，再规划

任何地址未经过质检，不得直接进入正式走访方案。

地址状态：

• confirmed：可自动参与任务编排
• review：可解析但存在歧义，默认不参与自动路线
• failed：无法可靠定位

2.3 人工决定高于算法

工作人员明确指定、锁定、排除或调整后的结果，不得被下一次自动优化覆盖。

2.4 尽量局部重排

当用户说“王老师请假”“A013 今天不在家”“第二组不要动”时，不要整场推倒重来。优先保留：

• 已完成对象
• 锁定组
• 锁定对象
• 未受影响组
• 已确认人工顺序

只重新计算受影响部分。

2.5 不因为优化路线而破坏专业规则

最短路不是最高优先级。约束优先级：

1. 安全与隐私规则
2. 强业务约束
3. 高优先级 / 必访对象
4. 时间窗和人员可用性
5. 工作量平衡
6. 道路时间与距离

3. 典型触发场景

• “这是明天要走访的 40 户，我们有 8 个人，帮我排一下。”
• “两人一组，每户 30 分钟，中午 12 点结束。”
• “第二组别动，王老师临时请假了。”
• “A023 今天家里没人，把后面重新排一下。”
• “今天还有哪些没完成？”
• “把没完成的安排到周六。”
• “看看这些服务对象主要分布在哪几个片区。”

不用于普通旅游路线、餐饮、打车等非公益服务场景。

4. 首次使用：腾讯位置服务 API Key

任何真实地理服务调用前先执行：

python scripts/visit_dispatch.py config status

未配置时，引导用户在本地终端执行：

python scripts/visit_dispatch.py config set
python scripts/visit_dispatch.py config verify

规则：

• 不要求用户把完整 API Key 发到聊天正文；
• Key 使用隐藏输入；
• Key 保存在用户配置目录，不进入 Skill 包；
• 日志和输出只显示掩码；
• 验证 Key 时使用行政区接口，不发送服务对象地址；
• 服务对象姓名、电话、证件、健康及家庭信息不得发送给地图服务。

详见 references/privacy.md 与 references/tencent-location-api.md。

5. 标准任务流程

阶段 A：创建任务

优先识别：

• 任务名称 / 日期
• 服务对象名单
• 工作人员名单
• 出发点
• 开始 / 结束时间
• 每户预计服务时长
• 交通方式
• 每组人数或组数
• 必须满足的特殊规则

轻微缺失时可用合理默认值继续，但必须写入 assumptions，不得把默认值伪装成用户要求。

阶段 B：地址质检

检查：

• 无法定位
• 地址过短或口语化
• 行政区疑似错误
• 重复地址
• 明显离群位置

只有 confirmed 默认参与正式规划。

阶段 C：智能编排

至少考虑：

• 真实道路距离 / 时间
• 工作人员数量与分组
• 工作人员可用时间
• 是否可驾驶 / 有车
• 工作人员角色
• 每人最大任务量
• 服务对象优先级
• 必访对象
• 可访问时间窗
• 单户服务时长
• 最少同行人数
• 指定角色
• 锁定组

阶段 D：人工调整

支持把用户自然语言要求转成任务约束：

• 锁定某对象到某组
• 锁定某组不参与重算
• 某工作人员不可用
• 某对象暂停 / 改期
• 某对象必须优先

阶段 E：下发任务

正式方案除负责人总览外，应生成每组独立任务单。一线人员默认只需要看到：

• 本组人员
• 本组服务对象编号
• 地址
• 顺序
• 预计到达 / 离开时间
• 路程时间
• 必要业务备注

不要默认把全体服务对象名单复制给每一组。

5.1 结果交付与文件生成

完成规划或复盘后，Skill 不应只给聊天文字。应根据用户目的生成可直接使用的文件成品。

格式选择规则

• 用户说“发给同事执行、排班、任务表、分组表、现场填写” → 优先 Excel (.xlsx)。
• 用户说“正式方案、项目材料、汇报、存档、打印” → 优先 Word (.docx)。
• 用户说“浏览器查看、分享链接、现场大屏、查看分组和路线概览” → 优先 HTML (.html)。
• 用户明确指定格式 → 严格按指定格式生成。
• 用户要求“都要/完整交付包” → 同时生成 Excel + Word + HTML。
• 用户没有指定，但任务明显用于实际执行 → 默认生成 Excel；如同时需要负责人快速查看，可附加 HTML。

Excel 应包含

至少包含：

1. 任务总览：任务状态、户数、分组数、异常地址、预计工时等；
2. 走访任务：全量内部任务表；
3. G1/G2/...：每组独立任务表；
4. 状态字段应便于现场回填。

Word 应包含

至少包含：

• 任务基本信息；
• 执行摘要；
• 分组安排；
• 每组走访顺序；
• 异常与风险提醒；
• 未完成/后续安排。

HTML 应包含

至少包含：

• 响应式负责人看板；
• 核心任务指标；
• 每组任务卡片；
• 路线顺序与状态；
• 异常提醒。

HTML 默认不得把腾讯位置服务 API Key 写入前端源码。

文件生成命令

python scripts/render_outputs.py output/task-001/task.json \
  --formats xlsx,docx,html \
  --out-dir output/task-001/deliverables

Skill 应在生成后把文件路径/附件直接交付给用户，而不是只告诉用户“可以导出”。

阶段 F：执行跟踪

对象状态：

• pending 待走访
• completed 已完成
• not_home 未见面
• cancelled 临时取消
• address_issue 地址异常
• reschedule 需改期
• follow_up 需二次跟进

任务状态：

• planned
• in_progress
• partially_completed
• completed
• closed

阶段 G：异常与续排

任务变化时：

1. 保留已完成对象；
2. 保留锁定组；
3. 排除不可用工作人员；
4. 只收集需要继续处理的对象；
5. 用新的剩余时间窗口重新编排；
6. 输出新版本任务，并保留来源任务 ID；
7. 不覆盖原始任务历史。

阶段 H：复盘

至少输出：

• 原计划户数
• 已完成户数
• 未见面
• 临时取消
• 地址异常
• 需改期
• 需二次跟进
• 未完成清单
• 下一步建议

6. 标准命令

配置

python scripts/visit_dispatch.py config status
python scripts/visit_dispatch.py config set
python scripts/visit_dispatch.py config verify

地址质检

python scripts/visit_dispatch.py audit examples/sample_visits.csv \
  --region "安丘市" --out output/audit

创建任务

python scripts/visit_dispatch.py plan examples/sample_visits.csv \
  --staff examples/sample_staff.csv \
  --groups 2 \
  --start-address "山东省潍坊市安丘市人民政府" \
  --start-time "08:30" \
  --end-time "12:00" \
  --default-service-minutes 30 \
  --region "安丘市" \
  --out output/task-001

更新执行状态

python scripts/visit_dispatch.py update-status output/task-001/task.json \
  --object-id ET003 --status completed --note "已完成走访"

临时调整：工作人员不可用

python scripts/visit_dispatch.py replan output/task-001/task.json \
  --staff-unavailable ST02 \
  --start-time 10:30 \
  --end-time 12:00 \
  --out output/task-001-v2

生成任务复盘

python scripts/visit_dispatch.py summary output/task-001/task.json

7. 标准输出与交付

一次 plan 必须生成：

output/task-001/
├── task.json                  # 完整任务状态
├── manager-summary.md         # 负责人总览
├── routes.csv                 # 全局路线表（内部使用）
├── review.csv                 # 待确认地址
├── failed.csv                 # 无法解析地址
├── geocoded.csv               # 地址解析结果
├── group-tasks/
│   ├── G1.md                  # 第一组独立任务单
│   ├── G2.md
│   └── ...
└── deliverables/              # 按用户需求生成
    ├── 公益走访任务.xlsx
    ├── 公益走访任务.docx
    └── 公益走访任务.html

负责人总览应优先回答：

> 这次有多少户？分几组？预计能否按时完成？哪些地址有问题？哪一组负担过重？哪些对象没有排进去？

8. 不得做的事情

• 不为模糊地址编造精确位置；
• 不把姓名、手机号、身份证、健康信息等发送给地图 API；
• 不因路线更短而违反双人走访、专业角色、时间窗等强约束；
• 不在重排时删除已完成记录；
• 不把“计划完成”写成“实际完成”；
• 不默认向普通成员展示全量服务对象位置；
• 不把 API 失败静默伪装为成功。

9. Skill 成功标准

本 Skill 的成功不以“路线算出来了”为准，而以用户是否获得以下结果为准：

> 一份能发给同事执行、现场发生变化还能改、结束后还能知道谁没完成的走访任务。

10. 交付判断示例

用户：“给我一个可以发给四个组长的任务表。”
→ 生成 Excel，并优先按组拆分工作表。

用户：“把这次走访形成正式方案给资助方。”
→ 生成 Word，弱化精确个人位置，突出安排逻辑和风险说明。

用户：“我想在电脑上打开看看整体安排。”
→ 生成 HTML 看板。

用户：“Excel、Word、网页都给我。”
→ 一次生成三种格式。