miseon-stack/project-management-skills/feishu-project-table-sync
Claude Code and agent skill by miseon-stack/project-management-skills
- community
Checking that the SKILL.md file is still in the repository.
把项目最新进度写进飞书「项目表」(多维表格),并回读校验。触发场景:用户说"更新项目表/项目进度写进多维表格/保持项目表最新/回写云端计划表/同步进度到飞书/以线上为准/漏掉的补一下",或要求把某个项目的进展记录到对应 Base。核心流程:定位 base/table → 读当前值 → 查字段 → dry-run → 批量更新 → 统一回读验收。全程走 lark-cli,不开浏览器预览、不在本地做完整镜像。含多个已验证的坑:--json @ 与 --output 只接受当前目录内的相对路径、只读字段(Formula/Lookup/自动编号)、select 写入不存在的选项会自动新建选项、异步生效不可逐项写完即读、table-list 的 ID 键名是 id、状态是 select 数组、错误码含义。
Install
npx vskill@latest install miseon-stack/project-management-skills/feishu-project-table-syncSKILL.md
The same SKILL.md was published earlier as miseon-stack/project-management-skills/feishu-project-table-sync.
飞书项目表进度同步
⚠️⚠️ 先决条件:必须使用有权限的用户身份(--as user)
默认的应用 / 机器人身份读不到目标 Base。 访问客户 Base 时,若应用未被授权、也未被加入文档协作者, 会一律返回 91403 you don't have permission。
所有命令都要带上 `--as user`:
- 需要多套身份时,可在 lark-cli 中配置具名 profile(凭据文件自行保管,含 secret,勿入库)。
- 该身份需具备 user 权限(设备码登录,授权所需业务域),才能读取目标实施表与群组。
- 若某次报
91403或 user 身份missing→ 重跑:
``bash lark-cli auth login --as user --no-wait --json --domain all # 把 verification_url 转二维码给用户扫(lark-cli auth qrcode <url> -o ./qr.png), # 同一轮不要阻塞轮询;用户确认后再: lark-cli auth login --as user --device-code <code> ``
- 下文所有示例为简洁省略了身份参数,实际执行必须补上。
铁律
- 线上是唯一事实源,本地极简。(用户 2026-09-14 明确:「以后全部以线上文档为准,漏掉的就补,然后有更新就更新到飞书多维表格上,本地不用搞这么多」)
- 要进度先读线上,不要相信本地 md 的旧快照;本地与线上冲突时以线上为准。
- 发现线上缺字段/缺记录/缺进展 → 直接补到线上,不要先写本地等确认。
- 不产出 HTML 报告、不做完整 md 镜像。本地只留导航(
00_工作总索引.md)、各项目README.md(要点 + 线上链接)、以及无法上云的原始材料。
- 全程走 `lark-cli`。 不要用 present_files 打开飞书链接、不要开浏览器预览。
- 写前必读当前值,写后必验收。 保留旧值便于说明"从什么改到什么"。
- 分级授权:
最新进展(纯文本)可直接写;状态变更要有可溯源证据;对外承诺、排期变更、金额、客户可见口径需先跟用户确认。 - 优先 `--as user`(官方约定:操作 Base 优先用户身份)。
⚠️ 工作目录约定(最容易踩的坑)
`--json @<file>` 和 `--output <file>` 都只接受「当前目录内的相对路径」,绝对路径会被直接拒绝:
--json @/tmp/x.json→ ❌--file must be a relative path within the current directory--output /tmp/x.ndjson→ ❌unsafe output path--json @./x.json→ ✅--output ./x.ndjson→ ✅
--json 也不支持 stdin(`-`),会被当成字面 JSON 解析报错。
→ 正确姿势:先 `cd` 到一个 scratch 目录,再用相对路径。
这样也天然避免了记录文件散落到项目根目录。
导出记录的三个硬约束(实测)
- `--output` 目标文件已存在会报 `output file already exists` → 加
--overwrite。(重跑同一路径时最容易撞到。) - `--jq` 与 `--format ndjson` 不兼容,报
--jq does not support ndjson→ 先导出,再用 Python 读文件;manifest 摘要也用 Python 解析 stdout。 - 表里有 `button` / `not_support` 等字段时,整表 ndjson 导出会失败:
field "xxx" has unsupported field type "button"→ 必须用--field-id逐个投影出需要的字段,不能整表导。 - 字段名可能带 emoji、空格、全角括号(如
🚥 质检结果、F 码、✍️ 任务负责人(原培训人))。shell 里容易转义出错 → 用 Pythonsubprocess传参数列表最稳,且必须逐字照抄+field-list返回的name。
🔎 盘点「某客户全部相关对象」
收到「检查 XX 相关全部的」这类要求时,不要只查自己知道的那张表——同一客户往往散落多个 Base、多条业务线。
- 返回
candidates列表,逐个+table-list看有哪些表、多少条。 +table-list的返回键是 `tables`(不是items/data.items),每项含id/name/records_count/rev。- 拿到表清单后,先判断每条线分别属于谁:客户交付主表、客户方自维护表、通用迁移/推广线、内部培训线……不同 owner、不同业务线的表不要混着改。
- 无关的表要明确排除并说明理由(例如按客户名筛选后 0 条命中)。
- 交叉核对的顺序:交付主表 → 阶段表 → 客户方明细表 → 群聊原始消息 → 其它旁路表。群聊消息常能挖出表格里没有的事故与决策。
项目表登记册(2026-09-15 实查)
每个客户项目都有一张线上「项目实施表」(命名不统一:客户A叫「项目推进计划表」、客户B叫「飞书实施项目表」、客户C叫「项目上线计划表」)。标准结构 = 上线计划总表(主表)+ 项目阶段 + 项目上线进度监控仪表盘。
交付主表(我方维护)
| 项目 | Base token | 子表 | table_id | 记录数 | |
|---|---|---|---|---|---|
| 客户A | <TOKEN> | 上线计划总表(主表) | <TABLE_ID> | 31 | |
| 客户A | 同上 | 项目阶段 | <TABLE_ID> | 6 | |
| 客户A | 同上 | 项目组成员 | <TABLE_ID> | 6 | |
| 客户A | 同上 | 仪表盘 / 工作流 | <DASHBOARD_ID> / <WORKFLOW_ID> | — | |
| 客户B AI 客服 | <TOKEN> | 上线计划总表(主表) | <TABLE_ID> | 42 | |
| 客户B | 同上 | 项目阶段 | <TABLE_ID> | 5 | |
| 客户B | 同上 | 仪表盘 | <DASHBOARD_ID> | — | |
| 客户C | <TOKEN> | 上线计划总表(主表) | <TABLE_ID> | 13 | |
| 客户C | 同上 | 项目阶段 | <TABLE_ID> | 4 | |
| 客户C | 同上 | 仪表盘 | <DASHBOARD_ID> | — |
客户D / 其他客户 未发现实施表,且非本人主责(2026-09-15 用户明确),只登记不跟踪 —— 客户D只有排班数据与日报 Base;其他客户只有《🍺其他客户AI效率先锋活动案例收集表》<TOKEN>。不要主动为这两个项目扫缺口、写进展或建表;仅当用户明确要求时才处理。需要时先 +title-resolve 复查,不要凭印象断言。
本人主责项目(跟踪范围)= 客户A、客户B、客户C。
客户C的其它线上材料(均≠实施表):
- ERP 业务看板
<TOKEN>→ 订单数据<TABLE_ID>/ 字段说明<TABLE_ID>(2026-09-15:1597 / 13 条)+ 3 个仪表盘。 - 订单演示 Base
<TOKEN>→ 演示数据 100 条 / 字段说明 13 条。 - 启动前置调研副本
<TOKEN>→ 收集表 5 条(客户方同事维护,只读作证据)。 - AI 手写单据识别
<TOKEN>→ 测试 5 条,正式订单/识别测试均 0 条;属于原型验证,不要误判为已交付。
客户C实施表旧疑似副本 <TOKEN> 已于 2026-09-15 回读确认为已删除(API 返回 note has been deleted);当前唯一有效实施表为 <TOKEN>。
只读旁路表(他人维护,只读作证据,不要改)
| 归属 | Base token | 表 | table_id | 记录数 | 说明 | |
|---|---|---|---|---|---|---|
| 客户B·客户方 | <TOKEN> | 飞书AI智能体功能点明细表 | <TABLE_ID> | 35 | 客户方负责人维护,细颗粒功能进度 | |
| 客户B·CSM同事 | <TOKEN> | 问题收集 | <TABLE_ID> | 70 | 通用迁移问题(是否解决/分类/严重程度) | |
| 客户B·CSM同事 | <TOKEN> | 数据表(8.4 上线计划) | <TABLE_ID> | 38 | 8 月通用飞书上线推广线 | |
| 客户B·CSM同事 | <TOKEN> | 数据表 | <TABLE_ID> | 2 | 仅文档索引 | |
| 内部(无关) | <TOKEN> | 豆包进飞书培训任务 | <TABLE_ID> | 5735 | bytedance 域;按客户名筛「客户B」得 0 条,与客户B交付无关 |
(已更正 2026-09-15) 旧记录曾写「客户C没有项目进度表」——错误。客户C实施表为《【客户C】项目上线计划表》<TOKEN>(13 + 4 条),当时只查了 ERP 订单看板那个 Base 就下了结论。教训:盘点某客户资产时必须用 `+title-resolve` 全量解析,不能只查自己已知的那张表。
记录数会变(任务会新增、删除,展示名称也可修改)。每次先 +record-list 实读,别信上表;稳定映射用 record_id,不因出现新编号就断言旧任务被重编号。
标准流程
0. 定位 Base
优先用 CLI 解析,不要靠 grep 本地文档:
再列子表 —— ID 的键名是 `id`,不是 `table_id`:
1. 读当前值(保留旧值)
--field-id做投影,只取需要的字段(可重复传)。- `--format ndjson` 不打印记录:记录写入
--output文件,stdout 只返回 manifest(record_file/records_count/has_more)。 - ndjson 记录是「扁平结构」,字段直接在行对象上,不在
fields里:{"record_id":"rec...","状态":["进行中"],"最新进展":"..."}。别照+record-get的嵌套结构解析。 has_more=true说明被截断(默认上限 2000 行),需用--filter-json下推谓词收窄。
用 python 解析落盘文件:
缩小范围:文本关键词 → +record-search;结构化条件 → +record-list --filter-json:
⚠️ 自动编号字段不能 `intersects`,必须 `==`;OR 组合也只能写成多个 == 子条件。
2. 查字段类型与选项(写前必做)
只读字段绝不可写:formula / lookup / auto_number / 附件 / 系统字段。误传会在返回里出现 ignored_fields / READONLY。
已知只读字段:
- 客户A「项目阶段」:
进度(%)(formula)、工期(天)(formula)、显示名称(formula)。只能写状态(未开始/进行中/完成)、计划开始、计划结束、文本字段。 - 客户B「项目阶段」:
进度(%)(formula)、工期(天)、显示名称。状态选项同为未开始/进行中/完成。 - 客户B「上线计划总表」:
任务编号(auto_number)、最后更新时间(updated_at)。状态选项未开始/进行中/已完成/阻塞/待确认。 - 客户B「功能点明细表」:
功能点状态选项待开始/进行中/已完成/已阻塞/已卡死/pass/转让飞书/转后期待定。
三张实施表常用字段 ID(2026-09-20 实读,三表同名同 ID,可直接用):
| 字段 | field_id | 说明 | |
|---|---|---|---|
| 状态 | <FIELD_ID> | select,单选也写数组 ["进行中"] | |
| 最新进展 | <FIELD_ID> | text | |
| 计划开始 / 计划完成 | <FIELD_ID> / <FIELD_ID> | datetime | |
| 优先级 | <FIELD_ID> | select | |
| 交付物/产出(客户A)· 交付(客户C)· 附件(客户B) | <FIELD_ID> | text | |
| 主字段 | 客户A <FIELD_ID>=任务编号(auto_number) · 客户B <FIELD_ID>=任务标题 · 客户C <FIELD_ID>=任务名称 | 客户C另有 auto_number「编号」<FIELD_ID> |
→ 写 `--json` 时 key 一律用 field_id,不要用显示名(客户B「负责人 (人员 )」显示名含空格,按名取值恒 None)。
已核实的阶段 `进度(%)` 算法:= 关联上线计划总表 中 状态="已完成" 的记录数 ÷ 关联记录总数(0~1 小数)。以当次字段 expression 为准;NDJSON 中 formula 结果为字符串,数值比较前显式转换。 完成率与状态不一致只触发核查,不自动改成完成。 先核对关联任务是否齐全、阶段目标及验收是否闭环;100%可能只反映部分关联任务,0%也可能因未关联记录。客户功能点表的 完成进度 是手填 number,不是同一公式。不得将手填100%、单功能初测、阶段任务完成率或整体项目验收混为一谈。
「进度恒为 0%」的正确修法 = 补关联,不是改公式(2026-09-17 客户B实践):进度(%) 公式首项就是 IF(COUNTA(关联上线计划总表)=0, 0, …) —— 关联为空的记录永远算 0,与真实完成度无关。客户B P1 子阶段「完成相关知识库的导入、创建及调用P1」<RECORD_ID> 就是空关联恒 0;补上对应任务(T70/T86/T87/T88)后自动计算即恢复。 → 补关联用 +record-batch-update 写 link 字段:{"关联上线计划总表":[{"id":"rec_xxx"},{"id":"rec_yyy"}]}(数组即该字段全量值,是覆盖语义,先读回现值再追加)。 → 补完要跟用户讲清:如果关联任务本身都没标「已完成」,补完仍会显示 0% —— 低值来自任务状态,不是公式 bug。绝不要为了「好看」改公式或硬标完成(阶段进度同时被仪表盘引用)。
2.5 批量新增记录(+record-batch-create)
- ★ `+record-batch-create` 是 `write` 级(不是 high-risk-write),不接受 `--yes` —— 加了会报
unknown flag "--yes"。只有+record-delete/+field-update这类 high-risk-write 才要--yes。 - CellValue 口径(2026-09-23 实测通过):
text→ 字符串;select→["未开始"];datetime→"2026-09-24 00:00";user→[{"id":"ou_xxx"}](多人就多元素);link→[{"id":"rec_xxx"}]。 - key 优先用 field_id(字段名可能带空格/全角括号,见 §1 第 4 条);不要写 auto_number / formula / lookup / 附件字段,
任务编号由系统自动分配。 - 返回
data.record_id_list与提交顺序一一对应,拿它做后续校验即可,不必立刻全表回读。 - ⚠️ 若 target 记录里某人 open_id 解析不到(跨租户无通讯录权限属正常),该字段留空不报错,但要在备注里标注「负责人待补充」。
- 实例(2026-09-23):客户A上线计划总表批量新增「AI 销售经营助手」12 条 → 自动编号 T78–T89,全表 31 → 43 条。
3. 组装并写入
- 单批最多 200 条(超限报
1254104,拆批)。 - ⚠️ 一个 batch 只能装同一张表的记录(2026-09-17 实测):把「项目阶段」表的记录混进主表的 batch 里,该条会单独返回
record_not_found,其余记录照常写入成功 —— 不会整体报错,极易漏察。跨表写入必须按 table-id 分开提交,并逐表回读。 - 同一 Table 连续批量写入串行执行;
1254291= 并发写冲突,短暂等待后重试当前批次。 1254045= 字段不存在(重新+field-list取真实字段名或 field_id);1254015= CellValue 类型不匹配。- 中文/换行放 JSON 文件里,别用 shell 拼字符串。
- ⚠️ 写 select 字段时,若值不在选项列表里,Lark 会「静默新建该选项」而不是报错。 实例:把
@本人@FDE同事(人名)误写进「优先级」select,结果字段选项里真的多出一个叫@本人@FDE同事的优先级。→ 写 select 前必须核对+field-list的options,写错了要同时改记录值 + 清理字段选项。
清理被污染的 select 选项(+field-update)
⚠️ `+field-update` 是 PUT 全量语义:必须提交该字段的完整定义(含全部要保留的选项),漏掉的选项会被删掉。 ⚠️ 不接受 `property` 包装:写成 {"field_name":...,"type":"select","property":{"options":[...]}} 会报 800010701 Unrecognized key(s) in object: 'property'。正确写法是 options / multiple 直接放顶层:
⚠️ --dry-run 不做 schema 校验,会照样打印带 property 的 body 然后正式执行才报错 —— 所以 dry-run 通过 ≠ 结构正确。 ⚠️ 改字段前先确认没有记录还在用那个待删选项(全表读回来筛一遍),否则那些记录的值会被清空。 ⚠️ 改完必须回读:+field-list 看选项列表 + +record-list 统计各选项记录数,确认没丢数据。
3.5 删除记录(空壳/误建)
- 属 high-risk-write,必须
--yes;先跟用户确认再删(删了不能从 CLI 恢复)。 - ⚠️
任务编号是auto_number,删除后该编号不会被回收复用 —— 会出现编号断号(如删掉 T98 后从 T99 直接接 T100)。这是正常的,不要以为是丢数据。 - 删完回读全表确认条数 -1、目标 record_id 消失。
4. 验收
⚠️ Table 更新多为异步生效:接口成功返回后立即读可能看不到最新值。 → 以写入成功响应作为操作结果;需要确认最终状态时,先完成本轮全部变更,再统一读取验收,不要逐项写完立刻读回。
验收用 +record-get 精确读目标记录(比全表 +record-list 省):
⚠️ `+record-get --format json` 的 `data.data` 是「无表头行数组」(data.data[0] 是一行值的 list,不是 dict),按 rec['fields']['字段名'] 解析会报 'list' object has no attribute 'get'。行内值的顺序与 --field-id 传入顺序一致,但更稳的做法是直接用 `--format ndjson` 回读(字段名扁平在行对象上),或用 --field-id 投影后按索引取值。
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-table-sync/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-table-sync)