项目管理系统（业财一体）技能

概述

装了这个技能 = 在飞书 / 钉钉 / 企业微信任意一个平台得到一套完整的"以项目为主线"的经营管理系统：客户与销售跟进、立项审批、WBS 任务与进度、四科目预算、支出申请与付款、合同与开票、回款到账与账户扣减、结项与损益总账。核心规格平台无关（§2–§7），平台落地看适配器（§0 索引 + §11）。全部脚本、配方、模板与演示数据随包附带，已在三平台真实生产环境验证。

0. 你能得到什么

• references/build-guide.md：一键复建 23 张表 + 关联拓扑 + 项目损益公式列 + 5 角色权限矩阵 + 2 仪表盘 11 图 + 贯穿式演示数据
• references/cross-platform-spec.md：跨平台唯一事实源规格（三平台同名/同结构/同关联/同口径/同演示数据/同角色）
• references/pitfalls-3platforms.md：三平台公式与工作流引擎级实测坑位库（含本技能亲手抓出的"文本↔关联键失配致跨表汇总归零"这一致命口径修复法）
• references/workflow-recipes.md：13 条自动化工作流的完整配方要点，含立项→自动建总览、回款/开票→自动回写合同与账户、任务进度→自动改项目状态等
• references/manual-{feishu,dingtalk,wecom}.md：三份小白视角详尽操作手册（各平台一份），可直接作为交付物或转发给团队
• references/demo-data-seeds.md：贯穿"客户→立项→计划→任务→预算→支出→付款→收票→合同→开票→回款→结项"的连贯样例数据源（JSON，逐表字段与值）
• references/fieldmap.txt：23 张表逐字段清单（字段名[类型]，含 link 指向）
• adapters/dingtalk/：钉钉 AI 表格适配器（README + 角色配额归并解法 + 文本 join 键跨表汇总 DSL 模板）——目标平台是钉钉时读这里，跳过 §4 飞书坑位
• adapters/wecom/：企业微信智能表格适配器（README + LOOKUP/FILTER 文本键跨表汇总模板 + 反向列改名坑）——企微无自动化引擎，闭环靠公式 + 定时任务补偿
• assets/：architecture.svg（五域架构图）与 lifecycle-flow.svg（全生命周期流程图）——二进制/图形不随 SkillHub 包分发，以本文 §3 与 mermaid 描述为准

0.5 第 0 步：平台选择弹窗（先于一切操作，强制流程）

当本技能被触发、且用户消息中没有明确指定目标平台时，Agent 必须先调用 AskUserQuestion 工具弹出单选问题「你想在哪个平台搭建项目管理系统？」，提供三个选项及说明：

1. 飞书 · 多维表格 —— 全流程脚本现成（§1–§7 + references/build-guide.md 一键复建），闭环工作流 13 条 API 可全启用；适合已在用飞书的团队
2. 钉钉 · AI 表格 —— 支持 filterUp/lookup + 工作流；但工作流不能写关联字段（汇总必须公式化）、自定义角色约 3 个上限（用 role-update 归并扩展）（走 adapters/dingtalk/）
3. 企业微信 · 智能表格 —— 公式引擎最强（FILTER/LOOKUP 原生跨表求和），但无自动化引擎、无表级角色引擎，闭环靠公式 + 定时任务、权限靠文档分享三档近似（走 adapters/wecom/）

规则：

• 用户已明确平台，或消息中出现平台特征（飞书分享链接、dingtalk.com/alidocs 链接、doc.weixin.qq.com 链接）时跳过弹窗，直接路由
• 做出选择后只执行该平台流程；本文档其他平台的命令、字段格式、ID 一律不得混用（平台差异速查见 §11）
• 连接器检测：搭建前必须先检测目标平台 CLI 可用性（§1.1）。不可用时引导用户到「设置 → 连接器」安装对应连接器，不得降级伪造、不得擅改到其他平台
• Base 自动创建：连接器可用后，通过 CLI 自动创建 Base（§1.2），不需要用户手动新建或提供 Base token
• 用户在已搭建过的系统上做日常操作（查询/审批/改数），同样先按其平台加载对应适配器文档，再执行核心业务规格（§2–§3）

0.7 付费服务调用流程（X402 支付协议）

本技能为付费技能（¥19.90/次），采用微信 Agent Pay 协议（X402 支付流程）。Agent 在提供搭建方案前，必须先完成支付验证。

调用流程：

1. 首次调用：Agent 向服务端发送 POST 请求（不带 X-Out-Trade-No header）
   • 端点：https://lanjingshuzi.cn/skillhub/project-management/api/v1/skill/invoke
   • 请求体：{"query": "<用户需求描述>"}
   • 服务端返回 HTTP 402，响应头包含：
     • WeixinPay-Required: 微信支付二维码 base64 数据
     • X-Out-Trade-No: 订单号
   • Agent 将二维码展示给用户，提示扫码支付
2. 支付确认：用户扫码支付后，Agent 再次发送 POST 请求（带 X-Out-Trade-No header）
   • 端点：同上
   • 请求体：{"query": "<用户需求描述>"}
   • Header：X-Out-Trade-No: <上次返回的订单号>
   • 服务端验证支付状态：
     • 已支付：返回 HTTP 200 + 搭建方案内容
     • 未支付：返回 HTTP 402，提示继续等待支付
3. 履约完成：订单支付后 24 小时内可重复查询，已履约订单直接返回结果。

端点运营方：蓝鲸数字 lanjingshuzi.cn

注意事项：

• 每次搭建方案生成前必须完成支付验证
• 支付二维码有效期 5 分钟，超时需重新下单
• 订单号由服务端生成，Agent 不得自行构造

1. 前置条件与连接器检测

1.1 连接器可用性检测（第 0 步，强制）

在开始搭建前，Agent 必须先检测目标平台的 CLI 是否可用：

• 飞书：执行 lark-cli --version 或任意 lark-cli 命令，确认返回正常
• 钉钉：执行 dws --version 或任意 dws 命令，确认返回正常
• 企业微信：执行 wecom-cli --version 或任意 wecom-cli 命令，确认返回正常

连接器可用时：向用户确认，直接进入 §1.2 自动创建 Base：

✅ 检测到 [飞书/钉钉/企业微信] 连接器已就绪，正在为你自动创建 Base 并搭建项目管理系统，全程无需手动操作，预计 8 分钟完成。

连接器不可用时的处理：如实告知未检测到该平台连接器，然后进入陪伴式引导模式——每次只说一个动作，等用户完成并回复后再给下一步，直到配置成功。

第一步（发送以下消息）：

检测到你的智能体尚未配置 [飞书/钉钉/企业微信] 连接器，我来一步步带你配置，全程约 2 分钟。

第 1 步：请看左侧栏，找到「专家·技能·连接器」这一行（图标是三个小圆圈），点击它。

完成后回复「好了」或「找到了」，我告诉你下一步。

后续步骤（用户每回复一次，发送下一步）：

第 2 步：顶部有三个标签：专家、技能、连接器。点击「连接器」。完成后回复「好了」。

第 3 步：找到「[飞书/钉钉/企业微信]」这个卡片（飞书蓝色纸飞机、钉钉蓝色翅膀、企业微信绿色气泡），点右边的「+」按钮。完成后回复「好了」。

第 4 步：弹出登录窗口，用你的账号登录并授权（扫码或输入密码）。这是最后一步。回复「好了」或「配置完了」。

用户完成全部步骤后：重新执行 CLI 可用性检测，通过后发送：

✅ 连接器配置成功！正在为你自动创建 Base 并搭建项目管理系统，预计 8 分钟完成。

然后进入 §1.2。

用户中途卡住时：如果用户回复「没找到」「看不到」「不会」等，用更具体的描述重新引导（如「左侧栏中间位置，写着'专家·技能·连接器'七个字」）；必要时建议用户截图，据截图判断位置。

1.2 Base 自动创建（无需用户手动操作）

连接器可用后，Agent 通过 CLI 自动创建 Base，不需要用户手动新建或提供 Base token：

• 飞书：lark-cli base +base-create --name 项目管理系统业财一体 --format json，从 data.base.base_token 取
• 钉钉：dws aitable +create --name 项目管理系统业财一体 --format json，取 base id
• 企业微信：wecom-cli smartsheet doc create --json '{"title":"项目管理系统业财一体"}'，取 docid

创建成功后告知用户 Base 已就绪，直接进入搭建流程（见 references/build-guide.md）。

2. 三步快速开始

1. 按 §1.1 检测连接器 → 按 §1.2 自动创建 Base（用户零手动操作）
2. 按 references/build-guide.md 逐步执行 —— 23 表建表 + 关联拓扑 + 项目损益公式列 + 贯穿式演示数据（每表 ≥1 条）
3. 按 §5 配方创建并启用 13 条工作流（飞书 API 可全启用；钉钉/企微见 §11 差异）；§3 权限矩阵建 5 角色（或钉钉 3 归并、企微 3 档近似）；§4 仪表盘建 2 张共 11 图
4. 三平台真实案例与操作手册见 references/manual-*.md

3. 架构与核心逻辑

3.1 五域 23 表（见 assets/architecture.svg）

中枢 = 项目总览：客户、合同、预算、任务、支出申请、付款单、收票登记、过程资料都回链到项目，形成"项目 360 视图"。

3.2 资金闭环（见 assets/lifecycle-flow.svg）

• 收入线：合同应收 → 开票申请 → 回款到账 → 计入资金账户 → 自动回写合同开票/回款状态 + 项目累计回款
• 支出线：预算 → 支出申请（两级审批 + 预算预警）→ 付款单 → 扣减资金账户 → 收票登记 → 项目累计支出
• 两条线汇总到项目总览：应收余额 = 项目总金额 − 累计回款；毛利 = 累计回款 − 累计支出；回款率 = 累计回款 / 项目总金额；预算执行率 = 累计支出 / 项目预算

3.3 审批状态机

草稿 → 待审批 → 已审批（触发下游工作流）/ 已驳回（可改后重提）。审批入口 = 单据表内"审批按钮 + 审批结果 select + 审批意见/时间/审批人"四件套；关键单据（立项/预算/支出/合同/开票/回款/结项）都有。

3.4 项目级损益公式列（本技能修复的致命口径 + 新增）

⚠️ 关键工程决策：飞书原模板里 项目总览.历史支出金额 是 lookup，其 where 条件写成 [付款单.关联项目] = [本行.项目编号]——link 字段和 text 字段跨表匹配永远不相等（link 归一化到对端主键字符串，项目编号是文本），所以跨表汇总恒为 0。本技能改用文本键镜像 + FILTER-SUM：

1. 在子表（付款单/项目预算）加公式字段 父项目编号 = [关联项目].[项目编号]（一级 link→text 二级链在飞书可用），把父表键拉平成文本
2. 在项目总览加公式列 项目累计支出(元) = [付款单].FILTER(CurrentValue.[父项目编号]=[项目编号] && CurrentValue.[是否已付款]).[付款金额（元）].SUM()
3. 同理得 项目预算总额(元)；派生 应收余额 = [项目总金额/元] - [历史回款金额]、项目毛利/元 = [历史回款金额] - [项目累计支出(元)]、回款率(%) = [历史回款金额]/[项目总金额]*100、预算执行率(%) = [项目累计支出]/[项目预算总额]*100、可结项判断 = IF(AND([项目进度]>=1,[回款率(%)]>=99.5),"可结项","未达标")

三平台同一坑：钉钉 filterUp operator 仅 equal/contain 且需文本键；企微 link 点号钻取一律 null，改用裸 [link]（=对端主键文本）或 LOOKUP。三平台都必须按此文本键口径实现，否则项目 360 数字全为 0。

3.5 权限矩阵（5 角色，同构）

飞书可 5 角色完整配置；钉钉自定义角色约 3 上限（走 role-update PATCH 归并，见 adapters/dingtalk/）；企微无表级角色引擎（只能以文档分享三档近似）。

4. 引擎坑位库（改动前必读，全部实战验证）

飞书公式引擎

1. link 字段名 == 表名 → [X].[Y] 被解析为整表列。修复：改 link 名（加"关联/项目"前后缀）。
2. FILTER 内 CurrentValue.[link].[field] 二级链不支持（静默 [无效引用]）；三级链一律不支持。跨表取父单字段用两段二级链辅助字段（§3.4）。
3. 比较两侧表示必须一致：link 引用被归一化为对端主键字符串 vs 名称文本永不匹配 → 汇总口径统一按文本键（§3.4）。
4. 直接二级链 [link].[字段] 可用（如 [关联项目].[项目编号]）。
5. button 字段实测可 API 建，与文档说法相反。

飞书工作流引擎

1. 「当前时间」写法 {"value_type":"date","value":"now"}；client_token 每次必须唯一。
2. SetRecordTrigger 对公式字段加 operator/value 过滤运行时永不触发；watch 字段不带条件 + IfElseBranch 用 link 钻取父表真实 select 判定。
3. FindRecordAction filter 对公式字段 text 有时被拒 → 改对真实 datetime 用 date 算子。
4. LarkMessageAction receiver 至少含一个有效 item；btn_list setRecord 改 checkbox 用 value_type: boolean。
5. 无 +workflow-delete，只能 disable；无执行历史 API，验证跑过 = 检索送达 IM 卡片。
6. 引用路径 $.stepX.xxx 必须写 field ID（fldXXX），否则 "does not exist in path tree"。

飞书 CLI 与仪表盘

1. 中文 JSON 一律 Write 到 CLI 解析目录后 --json @./f.json；--jq 经 .cmd wrapper 从 Git Bash 失效（引号被字面传入）→ 直连 core exe + grep/awk 解析；.cmd 会吞括号（base-copy --name "...(含括号)..." --without-content 会报"此时不应有"）→ 名称去括号或直连 exe。
2. dashboard-block-create data-config：statistics 用 count_all:true 或 series:[{field_name,rollup:SUM}] 二选一；column/pie group_by 最多 2；text 组件的 content 含中文换行 n 在 shell 层易失败；跨表汇总口径见 §3.4。

钉钉 AI 表格（详见 adapters/dingtalk/）

1. 关联字段写入值必须是 {"linkedRecordIds":["recId"]}（裸数组 / {id} / {recordId} 均 InvalidArgument）。
2. 工作流 CreateRecord/UpdateRecord 写不进 bidirectionalLink（静默丢弃仍报 success） → 状态回写/跨表汇总不能靠工作流写关联；用"子表 lookup 带父键文本 + 父表 filterUp/公式"三段式；新流程默认 STOP 需 enable。
3. filterUp 的 operator 仅 equal/contain 且需文本键；API 批量写/导入行的 filterUp 不重算，需 field update 原样重存 config 触发整列重建（先明细列后汇总列）。
4. 公式 config={"formula":"[精确字段名]"} 只同表、字段类型不可变；lookup/filterUp 无匹配返回 null 非 0，减法要 IF(x,x,0) 兜底。
5. 每 Base 自定义角色约 3 上限，第 4 个 role-create 稳定 HTTP 500；解法：role-update（PATCH –sub-roles）扩展/改名归并，不受配额；authLevel 枚举 manage/edit-own/edit-custom-field/edit-field-range/read/none，无"编辑全部"档 → 全员共编只能 manage。
6. leaf 命令带 + 前缀（+table-list / +field-list / +record-batch-create），裸命令名会 unknown；+table-list 返回 .data.tables[] 含 tableId/tableName/views[]。
7. DWS 必须纯 dws 单条/多行执行，不能混 echo/&&/管道/$( )/重定向。

企业微信 智能表格（详见 adapters/wecom/）

1. 关联(two_way)写入值 [{"record_id":"X"}]；单选 [{"id","text"}] 需先取 option id；多选/百分比按百分数填（13 = 13% 存 0.13，公式里 (1+[税率]) 取到 0.13）。
2. link/two_way 点号钻取 [关联字段].[目标列] 一律返回 null（与飞书不同）→ 跨表取值改用裸 [关联字段]（=对端记录主键文本）或 LOOKUP(值, 目标表.主键列, 目标列, 0)。
3. lookup 字段类型不能引用公式列（报 640027）；跨表汇总改公式：表.FILTER(AND(CurrentValue.[文本列]=[本行公式文本列],...)).[度量].SUM()（企微 FILTER 可对公式列求和，比钉钉强）。
4. FILTER/IF 里 autonumber 与 text 类型不匹配 → 结果 null：给主单加"单号 = 公式镜像（=[编号 autonumber] 转文本）"，汇总按 text=text 匹配。
5. two_way 反向列默认名"关联"，需 fields update 改名；fields update 无 --yes。
6. 读记录用 wecom-cli smartsheet records query --json '{"docid":..,"sql":["SELECT * FROM 表名"]}'，表/列名裸中文不加引号（加引号 parse failed），返回 values[].columns/rows。
7. 企微无自动化引擎、无按钮字段、无表级角色引擎 → 审批闭环靠公式 + 定时任务，权限靠文档分享三档近似。

通用打包与上传

1. SkillHub zip 三条铁律：① 条目路径必须正斜杠（.NET 逐条目 Replace('','/') 重写）；② 拒无扩展名文件（许可证放 frontmatter license）；③ 客户端跳二进制（png/jpg 等，示意图改用文字/mermaid 描述或走 instructions 托管）。实测可过：.md .json .jsonl。

5. 自动化配方库（13 条，详见 references/workflow-recipes.md）

飞书可全部 API 启用；钉钉可建但不能靠工作流写关联字段（→ 状态回写用文本键公式实现，工作流只做通知）；企微无工作流引擎（→ 全部改公式，通知走定时轮询）。

6. 日常操作 Playbook（按角色，摘要）

• 销售：客户信息 → 联系人 / 发起跟进 → 成交后建项目立项 → 部门上级审批 → 总经理审理 → 审批通过自动建总览
• 项目经理：项目计划（套模板）→ 拆任务（WBS/负责人/预计起止）→ 更新任务进度自动改状态 → 过程资料归档
• 花钱线：项目支出申请（项目负责人 → 上级领导审批；预算预警列自动标红）→ 付款单登记（勾"是否已付款"→ 自动扣资金账户 + 项目累计支出↑）→ 收票登记
• 收钱线：项目合同 → 开票申请（审批 → 勾"已开票" → 自动回写合同开票状态）→ 回款单（勾"回款是否到账" → 自动回写合同回款 + 账户余额 + 累计回款）
• 结项：项目结项申请 → 审批人先看总览"可结项判断"列（须进度=100% 且回款率≥99.5%）→ 通过后自动改项目状态为已结项
• 公司非项目：非项目报销申请 → 财务审批 → 公司运营支出登记（勾"是否已付款"→ 扣账户 → 自动回写报销单支付状态）

排障第一问：项目总览某财务列数字不对？ → 看是否按 §3.4 文本键口径实现；账户余额没变？ → 看"是否已付款/回款是否到账"是否勾上（触发工作流）。

7. 验证清单（改公式/工作流后）

1. +field-list 读回表达式无 [无效引用]
2. 项目累计支出/预算总额 对 P1/P2/P3 三行值不同，且 SUM = 明细全表合计（防 §3.4 文本键失配）
3. 可结项判断 在进度未 100% 时正确显示"未达标"
4. 13 条工作流 +workflow-list status 全部 enabled（飞书）；钉钉/企微对应能力受限处按 §11 已替代实现
5. 2 仪表盘共 11 图能出数（有演示数据后）
6. 权限矩阵：用非管理员账号验证敏感表（资金账户/公司运营支出/非项目报销）对非相关角色不可见

8. 安全与隐私

包内不含任何密钥、token、租户私有 ID；所有操作以使用者自身平台身份授权执行；脚本仅做最小必要读写。实例化后的 Base 权限由使用者自行管理。付费服务端仅接收搭建需求描述（平台类型/项目规模等），不含用户隐私数据；付费前 Agent 必须显式向用户披露费用、支付方式与运营主体，获得确认后方可发起扣款。

9. 更新

见 CHANGELOG.md；语义化版本，major=能力重构，minor=新增平台/自动化/角色，patch=修坑与文案。

10. SkillHub 上架与打包踩坑记录

10.1 zip 打包三条铁律

1. 条目路径必须正斜杠。PowerShell Compress-Archive 与 .NET ZipFile::CreateFromDirectory 在 Windows 上都写反斜杠条目 → SkillHub 客户端把嵌套条目判为"文件路径不安全"并跳过。
2. tar 的 zip 不能用：tar -a -c -f x.zip 产物 JSZip 报 Can't find end of central directory。
3. 正确做法：Compress-Archive 生成基础包，再用 .NET 逐条目复制到新 zip 并把 FullName.Replace('','/') 作为条目名：

Compress-Archive -Path <skilldir>* -DestinationPath tmp.zip -Force
$za=[IO.Compression.ZipFile]::OpenRead("tmp.zip"); $zo=[IO.Compression.ZipFile]::Open("out.zip",'Create')
foreach($e in $za.Entries){ $ne=$zo.CreateEntry($e.FullName.Replace('','/')); $s=$e.Open(); $d=$ne.Open(); $s.CopyTo($d); $d.Dispose(); $s.Dispose() }
$zo.Dispose(); $za.Dispose()

10.2 文件类型白名单

• 服务器 400 拒无扩展名文件（file type not allowed: LICENSE）→ 许可证放 frontmatter license。
• 客户端跳二进制文件（jpg/png 等，"禁止上传二进制文件"）→ 示意图走文字/mermaid 或 instructions 托管。
• 实测可过：.md .json .jsonl。

10.3 浏览器自动化上传坑（人工上传可忽略）

• Chrome 后台标签不弹文件选择框：先 OS 激活标签页再点选择。
• 千问办公顶部黑条遮挡：目标元素 scrollIntoView({block:'center'}) 再点。
• 文件树删除按钮与图标选项按钮外观相似，务必限定作用域，避免误删已选文件。

10.4 React 受控表单与报错捕获

• 输入框设值走原生 setter + dispatchEvent(new Event('input',{bubbles:true}))；直接赋 .value 不生效。
• 提交失败 toast 无细节时 monkey-patch window.fetch 记录响应 body 才能看到真实错误（如文件类型拒绝）。

10.5 提交与审核

• 接口 POST https://api.skillhub.cn/api/v1/orgs/{orgId}/skills，返回 201 即提交成功，reviewStatus/contentAuditStatus/securityScanStatus=pending 表示进入安全扫描+内容审核；通过后自动上架。
• 审核进度在「我的 Skills」查看；被拒时 reviewRejectReason 给原因。
• 升级：bump 版本号 + 变更说明 + 重传 zip 提交新版本；旧版本保留可回退。审核中的版本不要重复提交同版本号。
• "可疑"标记多为行为启发式（计费字样、外部域名、定时任务字样最嫌）→ 35 文件逐一体检若均安全，去可执行化（.sh → BUILD_*.md 手册）重打包常可过；透明披露付费性质与端点运营方是过审关键。

11. 多平台适配器路由（三平台真实生产实测）

同一份核心规格（§2 表结构、§3 资金闭环与损益公式、§4 引擎坑位、§5 工作流配方）在三个平台的落地差异速查：

选平台建议：要完整闭环 + 自动化 + 角色隔离选飞书；已有钉钉生态、能接受角色归并选钉钉（adapters/dingtalk/）；要公式最省心、纯 API 写入最顺、能自建定时补偿选企微（adapters/wecom/）。每平台适配器的坑位清单与模板见对应 README。