miseon-stack/project-management-skills/feishu-project-progress-sentinel

Claude Code and agent skill by miseon-stack/project-management-skills

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

项目进度巡检哨兵——定期扫描群聊/云文档/**会议妙记(智能纪要+待办)**等数据源,与线上实施表比对差异,输出分级预警(P0/P1/P2)、给客户的沟通建议与下一步行动,并把已完成事项生成群内话术与存档材料(共识留痕)。触发场景:用户说"巡检一下项目""扫一遍进度""检查项目表和实际的差异""有什么风险和预警""下一步该怎么跟客户说""把刚做的事生成群话术/存档共识""定期帮我看项目""扫一下数据更新/检查变化""卡片推送到 webhook/推给测试群/**改成客户可转发的对外版**",「**做成项目周报(≤500 字)/周报推给我**」,或要求对客户A/客户B/客户C三个项目的进展做差异核对与决策辅助。含十四个可直接跑的脚本(**一键 run_all.sh** / **半自动判读 suggest_verdicts.py** / **本地接口 api_server.py** / 采集 collect.py(群消息+文档+日历+**妙记**)/ 比对 analyze.py / **人工判读 apply_verdicts.py** / 变化对比 snapshot_table.py+diff_findings.py+diff_messages.py / 话术与存档 group_msg.py / 卡片推送 push.py / 人员同步 sync_people.py)、项目×数据源登记册、决策与话术手册、**卡片对外化白名单规范**。默认只读产出:回写线上表与发送卡片消息都需单独授权。

Install

npx vskill@latest install miseon-stack/project-management-skills/feishu-project-progress-sentinel

SKILL.md

The same SKILL.md was published earlier as miseon-stack/project-management-skills/feishu-project-progress-sentinel.

项目进度巡检哨兵

⚠️⚠️ 先决条件:飞书命令必须使用有权限的用户身份

本 skill 的所有 lark-cli 调用必须使用拥有目标群组与多维表格权限的用户身份(--as user)。 默认的应用/机器人身份对实施表会返回 91403 权限错误,且只能看到极少数群组。 巡检脚本里所有 lark-cli 调用必须补 `--as user`。 若你的环境需要多套身份,可在 lark-cli 中配置具名 profile 并显式指定(凭据文件自行保管,勿入库)。 报 91403 或 user 身份 missing → 重跑 lark-cli auth login --as user --no-wait --json --domain all

  • 扫码 + --device-code(详见 feishu-project-table-sync)。

一眼看清「表里写的」和「实际发生的」差多少,并告诉你该做什么、该怎么跟客户说。

铁律

  1. 只读优先。 本 skill 的产出是差异清单 + 预警 + 建议 + 话术草稿。回写线上表走 feishu-project-table-sync,发群消息必须用户确认——本 skill 不自动做这两件事。
  2. 三张实施表全部按「客户可见」处理(客户A / 客户B / 客户C)。对外措辞是硬约束,不是风格偏好。
  3. 不发明事实。 差异必须带证据(群消息原句 / 文档段落 / 记录号)。找不到证据的写「待确认」,不写成结论。
  4. 线上是唯一事实源。 一切以当次实读的线上表为准,不信本地 md 快照。
  5. 跟踪范围 = 客户A、客户B、客户C。 客户D / 其他客户非主责,不主动扫。
  6. ★判「逾期未动」前必须先查本地交付物(2026-09-20 教训)。 「线上日期过了 + 群内没动静」不等于没做 —— 可能是已交付但没写进表。动笔前先翻:各项目 项目资料/(方案 md、客户版文档)、工具/(脚本)、产物/。客户C T06 考勤报表就是这样:线上停在 9/12 逾期 8 天、群内无动作,实际我方方案 + 客户版 + 导入脚本 + 多维表格样板早已交付,只是没回写 → 误判成「没做」。本地无交付物 + 群内无动静才能写「逾期未动」。
  7. ★改「计划开始 / 计划完成」属于改承诺,比改状态更敏感(2026-09-20 立规)。 三张实施表的排期是双方共识:
  • 负责人是我方的条目,可提建议但仍要用户点名才落库;
  • 负责人是客户方的条目(客户B大量任务负责人 = 客户方负责人),一律不擅自改,只列「现值 → 建议值」清单交用户人工处理 / 与客户同步后统一改;
  • 输出重排提案时必须打上归属列(我方 / 客户方),用户才能一眼看出哪些能自己定。

目录结构

scripts/collect.py 采集:群消息 + 云文档(纪要/方案)+ 日历 + **会议妙记** → raw-<项目>-<日期>.json
scripts/analyze.py 比对:线上表 × raw → findings-*.json + 巡检报告-*.md
scripts/apply_verdicts.py ★ 把人工判读合并进 findings 与报告(保住判读,不被下次 analyze 覆盖)
scripts/sync_people.py ★ 从各表「人员」字段自动收拢 open_id↔姓名 → references/people.local.json
scripts/snapshot_table.py ★ 实读三表 → 逐条快照 table-snapshot-<项目>-<日期>.json(次日 diff 的基线)
scripts/diff_findings.py ★ 对比两日 findings:信号增删/级别变动/focus/各清单计数
scripts/diff_messages.py ★ 对比两日 raw:列出新增群消息(原始事实增量)
scripts/group_msg.py 输出:群内话术草稿 + 存档材料(共识留痕)
scripts/push.py 推送:巡检结果 → 飞书消息卡片(webhook / lark-cli 双通道,默认 dry-run)
scripts/run_all.sh ★ 一键:采集→快照→比对→diff→回灌判读→汇总(run-<日期>.json)
scripts/suggest_verdicts.py ★ 半自动判读:翻本地交付物 + 群消息 → 判读候选(人只确认)
scripts/api_server.py ★ 本地 HTTP 接口(127.0.0.1:8787,只读为主 + 异步巡检)
scripts/common.py 公共库(lark-cli 调用、记录解析、日期、人员、@ 渲染用的 id 映射)
references/projects.json 项目 × 数据源登记册(base/table/群 oc/字段名)——**不含凭据,可入库**
references/secrets.local.json 机器人 webhook 等凭据 ——**不入库**(.gitignore 排除),缺失时功能降级
references/people.local.json ★ open_id↔姓名映射(来自实施表人员字段,是姓名不是凭据,可入库)
references/team.json 我方成员名单(用于区分客户方发言)
references/playbook.md ★ 决策建议规则 + 对外话术模板 + 存档共识做法

本 skill 双位置同步(2026-09-17 用户要求):项目级 <工作区>/.workbuddy/skills/feishu-project-progress-sentinel/(随 GitHub 备份) 与用户级 ~/.workbuddy/skills/feishu-project-progress-sentinel/ 各放一份,改完必须互相同步 (rsync -a --delete 项目级/ 用户级/ 即可;secrets.local.json 不要带去用户级也行,凭据以项目级为准)。

产出默认落在 `<工作区>/.workbuddy/巡检/`。


快速开始(最短路径)

bash
# ★ 一键(推荐):采集 → 表快照 → 比对 → 变化 diff → 回灌当天判读 → 汇总
cd "<WORKSPACE>/.workbuddy/skills/feishu-project-progress-sentinel/scripts"
./run_all.sh # 三项目 + 3 天窗口;末尾打印 / 落一份 JSON 汇总
./run_all.sh --project 客户B --days 7 --json
./run_all.sh --skip-collect --no-diff # 已有当天 raw 时只重算,十几秒
# 分步(要单跑某一步时才用)
python3 collect.py --project all --days 3 # 采集(约 1 分钟)
python3 analyze.py --project all # 比对出报告
# 报告:<工作区>/.workbuddy/巡检/巡检报告-<项目>-<日期>.md
# ★ 判读落盘后再合并(见下文「三步」):先写 verdicts-<项目>-<日期>.json
python3 apply_verdicts.py --project 客户A # 人工判读写进 findings + 报告
python3 group_msg.py --project 客户B --items items.json --kind both # 话术 + 存档
python3 push.py --project 客户B # 生成卡片预览(不发送)
python3 push.py --project 客户B --send # 真发到该项目的机器人群

路径不固定时用 cd "$(dirname …)" 或直接写绝对路径;common.py 里 DEFAULT_WORKSPACE=<WORKSPACE>。

已挂自动化:工作日 08:30 自动跑 all + 3 天窗口,只汇报不落手。

一键入口 / 半自动判读 / 接口层(2026-09-21 新增)

人看的操作手册(常用命令、接口 curl 示例、排错表)在 `USAGE.md`;本节只讲设计取舍与坑。

巡检原来要按顺序敲 4–5 条命令、判读全靠人逐条读。现在这三件事都补齐了:

① run_all.sh —— 一条命令跑完
bash
./run_all.sh [--project all|客户B|客户A|客户C] [--days N | --since YYYY-MM-DD]
[--skip-collect] [--no-snapshot] [--no-analyze] [--no-diff] [--json]

步骤与顺序(顺序不能换):collect → snapshot_table → analyze → diff_findings / diff_messages → apply_verdicts(自动回灌当天判读)→ 汇总。

  • 为什么末尾要自动回灌判读:analyze.py 是拿 raw 重建 findings,当天已确认的判读会被冲掉;

run_all.sh 检测到 verdicts-<项目>-<今天>.json 就自动 apply_verdicts 合并。

  • 汇总落 <工作区>/.workbuddy/巡检/run-<日期>.json;带 --json 时把同一份 JSON 打到 stdout(给接口/程序消费)。
  • 逐步日志落 .workbuddy/巡检/.run-<日期>.log;某步失败不中断整轮,退出码 1(全成功 0,参数或环境错 2)。
  • 工作区自动推导(技能装在 <工作区>/.workbuddy/skills/ 下时三层上去就是工作区),也可

SENTINEL_WORKSPACE=... 显式指定;解释器用 SENTINEL_PYTHON=... 覆盖。

  • ⚠️ shell 坑(踩过一次):$VAR) 这种「变量紧跟全角括号」会被 bash 当成变量名的一部分

(报 FAILED\uXXXX: unbound variable)→ 中文文案里引用变量一律写 ${VAR}。

② suggest_verdicts.py —— 判读只做确认,不从零判断
bash
python3 suggest_verdicts.py --project all # 出候选
python3 suggest_verdicts.py --project 客户B --no-hub # 不查数据仓群消息
python3 suggest_verdicts.py --project 客户B --promote # 确认后直接落成正式 verdicts(旧文件自动备份 .bak)

对每条未判读信号自动给出候选判读 + 置信度 + 证据,产出:

  • verdicts-<项目>-<日期>.suggested.json(结构与正式 verdicts 一致,改完去掉 .suggested 即可用)
  • 判读候选-<项目>-<日期>.md(人看的勾选清单,逐条列证据)

它自动做两件原来必须人工做的事:翻本地交付物(项目资料/、工具/、产物/、日报/)与 翻数据仓群消息(hub.db LIKE 检索,默认 14 天窗口)。

判读规则(信号类型 × 归属 → 候选):

信号类型归属候选判读
overdue我方 + 本地有强命中交付物疑似已完成未回写 · 待确认(确认后改状态)
overdue我方 + 本地无命中逾期属实 · 我方条目(本地无交付物)→ 给完成日或顺延
overdue客户方 + 群内有动作逾期属实 · 客户方条目(近期有动作)→ 催办即可
overdue客户方 + 无动作逾期属实 · 客户方条目 → 统一核对
no_progress本地有产出已有产出未回写 → 补一句进展
due_soon / blocked / stale_table——规则型判定,不挂证据(挂上是噪音)

★ 证据分级与假阳性(实测调了 4 轮,别退回旧参数):

  1. 硬排除「自产分析物」 —— 巡检报告-/findings-/verdicts-/判读候选-/全量差异核对/

D类逾期重排提案/会议摘要汇编/周会/提案/评估/复盘/汇总/周报/日报///归档//README.md 等一律不作证据 —— 否则会把我方自己写的巡检报告当成交付物(第一轮就踩到:T08 的证据竟是自己那份「全量差异核对」)。

  1. 路径分级权重:项目资料/、工具/ = 交付物(×1.0);产物/ ×0.7;**会议纪要/、群聊资料/ ×0.4

(只能证明"会上说过",不能证明"做完")**;产物/归档|数据|被@待办 整个目录不扫。

  1. 弱词门槛:标题按 2 字滑窗切词会产生「维表」「阅会」这类跨词假词 → 只看弱词时必须命中 ≥3 个不同词;

命中 strong(≥3 字词块 / ≥4 位英文)按 ×3 加权;文件名含任务编号 +4。

  1. 置信度封顶:若前两条证据全是「会议记录」,置信度最高只能到「中」 —— 只靠会议纪要撑不起

「疑似已完成」。

判读落盘口径不变:候选 → 人确认(改 .suggested.json,或在 判读候选-*.md 上批注后照改) → 正式 verdicts-*.json → apply_verdicts.py(run_all.sh 会自动做最后这步)。

③ api_server.py —— 把巡检暴露成本地接口
bash
SENTINEL_WORKSPACE=<WORKSPACE> python3 api_server.py # 127.0.0.1:8787
python3 api_server.py --port 8899 --token mysecret # POST 需 X-Token 头
方法路径说明
GET/人看的首页:三项目状态分布 + 未判读数 + 报告链接
GET/health健康检查(工作区、项目、最新巡检日期)
GET/summary[?date=]各项目汇总(有 run-<date>.json 直接用,否则现算)
GET/findings?project=客户B[&date=latest]结构化 findings(程序消费用这个)
GET/report?project=客户B[&date=latest]巡检报告 markdown 原文
GET/verdicts?project=客户B当天已确认的判读
POST/inspect {"project":"all","days":3}后台跑 run_all.sh → 立即返回 job_id
GET/jobs、/jobs/<id>任务状态 + 日志尾(采集要 1 分钟以上,必须异步)
POST/verdicts/suggest?project=生成判读候选,返回清单路径
POST/push?project=客户B&tag=internal卡片预览(dry-run)

★ 接口层的红线(不要为了"完整"放开):

  • 只监听 `127.0.0.1`。改 --host 0.0.0.0 会打警告 —— 服务没有额外鉴权加固,只适合本机 / 内网可信环境。
  • `/push` 永远只 dry-run:传 dry_run=0 直接返回 403,真发送必须人工在命令行执行 push.py --send。
  • 接口里没有「写线上表」:那是 feishu-project-table-sync 的职责,且需用户点名授权。
  • /verdicts/suggest 的 promote=true 会覆盖正式 verdicts(自动备份 .bak)—— 只在人已确认候选时用。

能被谁调用:妙搭应用、多维表格 / 仪表盘的外部数据源、你自己的看板、其他 Agent(curl / fetch), 或后续在群内加「@机器人 巡检」的机器人(需要一台常驻进程的机器,配合 --token 收口)。

标准流程

0. 确认范围与窗口
参数默认说明
项目用户指定客户B / 客户A / 客户C / all
窗口今天 −3 天 → 今天上次巡检之后再没跑过就往前放;跨周建议 7 天
表停更阈值3 天超过即 P0
1. 采集
bash
cd "<WORKSPACE>/.workbuddy/skills/feishu-project-progress-sentinel/scripts"
python3 collect.py --project 客户B --since 2026-09-15
python3 collect.py --project all --days 7 --max-docs 10
python3 collect.py --project 客户A --since 2026-09-14 --no-docs # 只要群消息,快
  • 群消息走原生 API(im +chat-messages-list 在本机必然因缺 scope 失败,已在脚本内绕开)。
  • 云文档 = 群消息里出现的 docx/wiki 链接 + 按项目关键词搜到的纪要/方案,各取前 N 篇。
  • 会议妙记 = 独立通道,不能漏(2026-09-18 补):

minutes +search --participant-ids me --start … --end … 按「我参与 + 时间窗」拉妙记, 再用标题匹配 search_keywords 过滤,然后 minutes +detail --summary --todo --keyword 取 AI 摘要与结构化待办(带负责人、带完成态)。

  • ⚠️ 妙记不在云空间:drive +search 搜不到、群消息里也常没人贴链接 —— 只靠前两条通道会整场会议的结论与分派全部丢失(2026-09-18 实测:9/10–9/18 共 14 场会全部漏采)。
  • ⚠️ minutes 子命令会先往 stdout 打 [minutes +detail] querying … 日志行,C.lark() 只认首字符是 { 的输出会直接判失败 → 用 _lark_raw()(找第一个 { 再 parse)。
  • 妙记待办是结构化产出,比从文本里猜准得多,analyze 里已让它整体优先于其他待办候选。
  • --no-minutes 可关掉;会议刚结束时妙记可能还没生成,下一轮巡检才会补上(正常现象,报告里别当成缺口)。
  • 有群读不到(受限群 231203 / 无权限)脚本会打 ⚠️,要在报告里写明数据源缺口,不要假装覆盖完整。
2. 比对 + 预警
bash
python3 analyze.py --project 客户B # 自动找当天 raw
python3 analyze.py --project all --stale-days 3

产出 findings-<项目>-<日期>.json 与 巡检报告-<项目>-<日期>.md。

2.5 看变化(「扫一下数据更新 / 检查变化」标准动作,2026-09-18 起)

用户说「扫一下数据更新」「看看有什么变化」「和昨天比变了什么」时,跑这套日增量对比:

bash
cd scripts
# ① 采集必须与前一份 raw 同窗口 —— 先读前一天 raw 的 window.since
python3 -c "import json;print(json.load(open('<巡检目录>/raw-<项目>-<昨日>.json'))['window'])"
python3 collect.py --project 客户A --since <昨日 raw 的 since> # 逐项目对齐
python3 analyze.py --project all
# ② 逐条快照(建立基线,供明天 diff)
python3 snapshot_table.py 2026-09-18
# ③ 两类 diff
python3 diff_findings.py --old 2026-09-17 --new 2026-09-18
python3 diff_messages.py --old 2026-09-17 --new 2026-09-18
  • `diff_messages` 是「数据更新」的事实来源:diff_findings 只反映信号口径变化,真正的进展(客户定角色、会期敲定、验收口径松动)都在新增消息里。先看 diff_messages,再用 diff_findings 交叉验证。
  • 窗口不一致 = 假消失 ⭐ 最容易踩:昨天用 --days 7、今天用 --days 2,会出现一堆「消失信号」(new_requirement / risk_words / todo_candidates 计数暴跌),其实是消息掉出窗口。每次对比前对齐 since。
  • 父行跳过会造成「预警盲区」:父行(有子记录引用)只进 index、不产信号,所以父行自身逾期会静默不报(客户A T04 实例:计划完成 9/04 逾期 14 天、「进行中」,一旦被挂上子记录就再不预警)。发现"某条信号莫名消失但记录还在"时先查 父记录 字段,是父行就说明被规则跳过 —— 需要时在报告里单独提示,不要当成进度更新。
  • diff_findings 的 ✅ 输出规范:把变化拆成「表内变化(状态/计划日/进展)」「群内事实增量」「信号增删」三段给用户,不要只贴脚本文本。

脚本能自动识别的信号

kind含义级别
stale_table整张表停更 ≥ N 天P0
blocked状态含「阻塞 / 待确认」P0
overdue计划完成已过、状态未完成(≥3 天升 P0)P0/P1
due_soon≤3 天内到期仍未完成P1
completion_candidate群消息出现完成迹象、表内仍非完成态P1
status_delta群消息出现启动/进行/启用/阻塞实况、表内状态不符P0(阻塞)/P1
new_requirement★ 客户方群消息里要新东西、表内无对应任务P1
no_progress最新进展为空(仅「进行中」)P1/P2

状态差异(4/5/6 三类)统称「实况与表内不符」,卡片上单列一段「🔄」并附证据行 —— 只给证据不自动改状态,人工核实后走 verdicts 落盘。

另外产出四张「人工判读」清单:表内可能缺录 / 客户新增需求(new_requirements) / 风险词命中 / 待办候选 / 客户侧最后发言距今。

★ 子项目层级(2026-09-17 客户B起用「父记录」字段):表内行分两种 ——

  • 父行(有子记录引用它)= 子项目汇总行:只进 index(供缺录/新增需求匹配),不产任何逐任务信号(否则"进展空缺/状态差异"全是噪声)。聚合产出 findings.subprojects = [{no,title,status,total,done,doing,blocked,pct,children[]}]。
  • 子行:正常参与全部信号检测。
  • 卡片新增「📦 子项目进度」区块:每个子项目一行 T02 知识库迁移与搭建 3/5 子任务完成 · 进行中 2。
  • ⚠️ 父行的状态是人工维护的汇总口径,不与子任务自动校验;子项目下的风险仍看子行信号。

状态差异的两条精度约束(2026-09-17 实测踩出,改代码别放松):

  1. 只看群消息,不看文档 —— 方案/交接清单里的「待客户确认」会被反复引用,造成文档自证式误报(客户A T57/T67 实例)。
  2. 重合阈值 ≥3 个 2-gram —— 2 个太松,「全员功能使用培训」会命中「云打印功能的客户B使用」这种不相干消息。

new_requirement 同理:只收客户方的群消息(我方自己人讨论不算),带内部商务词(收费/报价/人天/合同/付款/成本/钱/预算/发票/请款)的一律排除。

3. ★ Agent 必须补的三步(脚本给不了)

脚本只做机械比对,以下必须由你(模型)完成,不能省:

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/miseon-stack/project-management-skills/feishu-project-progress-sentinel/badge)](https://verified-skill.com/skills/miseon-stack/project-management-skills/feishu-project-progress-sentinel)

Something wrong with this skill or its page? Tell us.