miseon-stack/project-management-skills/feishu-project-progress-sentinel
Claude Code and agent skill by miseon-stack/project-management-skills
- community
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-sentinelSKILL.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)。
一眼看清「表里写的」和「实际发生的」差多少,并告诉你该做什么、该怎么跟客户说。
铁律
- 只读优先。 本 skill 的产出是差异清单 + 预警 + 建议 + 话术草稿。回写线上表走
feishu-project-table-sync,发群消息必须用户确认——本 skill 不自动做这两件事。 - 三张实施表全部按「客户可见」处理(客户A / 客户B / 客户C)。对外措辞是硬约束,不是风格偏好。
- 不发明事实。 差异必须带证据(群消息原句 / 文档段落 / 记录号)。找不到证据的写「待确认」,不写成结论。
- 线上是唯一事实源。 一切以当次实读的线上表为准,不信本地 md 快照。
- 跟踪范围 = 客户A、客户B、客户C。 客户D / 其他客户非主责,不主动扫。
- ★判「逾期未动」前必须先查本地交付物(2026-09-20 教训)。 「线上日期过了 + 群内没动静」不等于没做 —— 可能是已交付但没写进表。动笔前先翻:各项目
项目资料/(方案 md、客户版文档)、工具/(脚本)、产物/。客户C T06 考勤报表就是这样:线上停在 9/12 逾期 8 天、群内无动作,实际我方方案 + 客户版 + 导入脚本 + 多维表格样板早已交付,只是没回写 → 误判成「没做」。本地无交付物 + 群内无动静才能写「逾期未动」。 - ★改「计划开始 / 计划完成」属于改承诺,比改状态更敏感(2026-09-20 立规)。 三张实施表的排期是双方共识:
- 负责人是我方的条目,可提建议但仍要用户点名才落库;
- 负责人是客户方的条目(客户B大量任务负责人 = 客户方负责人),一律不擅自改,只列「现值 → 建议值」清单交用户人工处理 / 与客户同步后统一改;
- 输出重排提案时必须打上归属列(我方 / 客户方),用户才能一眼看出哪些能自己定。
目录结构
本 skill 双位置同步(2026-09-17 用户要求):项目级 <工作区>/.workbuddy/skills/feishu-project-progress-sentinel/(随 GitHub 备份) 与用户级 ~/.workbuddy/skills/feishu-project-progress-sentinel/ 各放一份,改完必须互相同步 (rsync -a --delete 项目级/ 用户级/ 即可;secrets.local.json 不要带去用户级也行,凭据以项目级为准)。
产出默认落在 `<工作区>/.workbuddy/巡检/`。
快速开始(最短路径)
路径不固定时用 cd "$(dirname …)" 或直接写绝对路径;common.py 里 DEFAULT_WORKSPACE=<WORKSPACE>。
已挂自动化:工作日 08:30 自动跑 all + 3 天窗口,只汇报不落手。
一键入口 / 半自动判读 / 接口层(2026-09-21 新增)
人看的操作手册(常用命令、接口 curl 示例、排错表)在 `USAGE.md`;本节只讲设计取舍与坑。
巡检原来要按顺序敲 4–5 条命令、判读全靠人逐条读。现在这三件事都补齐了:
① run_all.sh —— 一条命令跑完
步骤与顺序(顺序不能换):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 —— 判读只做确认,不从零判断
对每条未判读信号自动给出候选判读 + 置信度 + 证据,产出:
verdicts-<项目>-<日期>.suggested.json(结构与正式 verdicts 一致,改完去掉.suggested即可用)判读候选-<项目>-<日期>.md(人看的勾选清单,逐条列证据)
它自动做两件原来必须人工做的事:翻本地交付物(项目资料/、工具/、产物/、日报/)与 翻数据仓群消息(hub.db LIKE 检索,默认 14 天窗口)。
判读规则(信号类型 × 归属 → 候选):
| 信号类型 | 归属 | 候选判读 | |
|---|---|---|---|
overdue | 我方 + 本地有强命中交付物 | 疑似已完成未回写 · 待确认(确认后改状态) | |
overdue | 我方 + 本地无命中 | 逾期属实 · 我方条目(本地无交付物)→ 给完成日或顺延 | |
overdue | 客户方 + 群内有动作 | 逾期属实 · 客户方条目(近期有动作)→ 催办即可 | |
overdue | 客户方 + 无动作 | 逾期属实 · 客户方条目 → 统一核对 | |
no_progress | 本地有产出 | 已有产出未回写 → 补一句进展 | |
due_soon / blocked / stale_table | —— | 规则型判定,不挂证据(挂上是噪音) |
★ 证据分级与假阳性(实测调了 4 轮,别退回旧参数):
- 硬排除「自产分析物」 ——
巡检报告-/findings-/verdicts-/判读候选-/全量差异核对/
D类逾期重排提案/会议摘要汇编/周会/提案/评估/复盘/汇总/周报/日报///归档//README.md 等一律不作证据 —— 否则会把我方自己写的巡检报告当成交付物(第一轮就踩到:T08 的证据竟是自己那份「全量差异核对」)。
- 路径分级权重:
项目资料/、工具/= 交付物(×1.0);产物/×0.7;**会议纪要/、群聊资料/×0.4
(只能证明"会上说过",不能证明"做完")**;产物/归档|数据|被@待办 整个目录不扫。
- 弱词门槛:标题按 2 字滑窗切词会产生「维表」「阅会」这类跨词假词 → 只看弱词时必须命中 ≥3 个不同词;
命中 strong(≥3 字词块 / ≥4 位英文)按 ×3 加权;文件名含任务编号 +4。
- 置信度封顶:若前两条证据全是「会议记录」,置信度最高只能到「中」 —— 只靠会议纪要撑不起
「疑似已完成」。
判读落盘口径不变:候选 → 人确认(改 .suggested.json,或在 判读候选-*.md 上批注后照改) → 正式 verdicts-*.json → apply_verdicts.py(run_all.sh 会自动做最后这步)。
③ api_server.py —— 把巡检暴露成本地接口
| 方法 | 路径 | 说明 | |
|---|---|---|---|
| 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. 采集
- 群消息走原生 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. 比对 + 预警
产出 findings-<项目>-<日期>.json 与 巡检报告-<项目>-<日期>.md。
2.5 看变化(「扫一下数据更新 / 检查变化」标准动作,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 实测踩出,改代码别放松):
- 只看群消息,不看文档 —— 方案/交接清单里的「待客户确认」会被反复引用,造成文档自证式误报(客户A T57/T67 实例)。
- 重合阈值 ≥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
- SKILL.md in the repositoryCheckingskills/feishu-project-progress-sentinel/SKILL.md
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
[](https://verified-skill.com/skills/miseon-stack/project-management-skills/feishu-project-progress-sentinel)