研发项目管理

概述

装了这个技能 = 在飞书 / 钉钉 / 企业微信任意一个平台得到一套完整研发项目管理系统：项目→迭代（版本）→需求/缺陷双流水线→研发日报，工时只在日报填一次即自动回填、需求/缺陷状态自动流转、迭代与项目完成率和进度自动逐级聚合、评审出结果与临近到期自动提醒、研发管理驾驶舱实时看板。核心规格平台无关（§2–§7），平台落地看适配器（§0 索引 + §11）。已在三平台真实生产环境逐值验证一致。

0. 你能得到什么

• scripts/BUILD_RD.md：一键复建 6 张表（项目/迭代/需求/缺陷/研发日报-需求/研发日报-缺陷）+ 基础字段 + 6 双向关联 + 30 公式/查找 + 仪表盘 8–11 图表
• 工作流配方库（本文 §5）：评审结果变更通知、临期到期提醒的完整结构要点（飞书/钉钉原生，企微用定时+待办补偿）
• 引擎坑位库（本文 §4）：三平台公式/工作流引擎已验证限制与绕法，价值最高的部分（含钉钉 COUNT 归零、企微计算列不回值需服务端 SQL 校验等）
• assets/：架构图与业务流程图样例（注意：二进制图片被 SkillHub 客户端禁止上传，仅本地安装包包含；SkillHub 包内以本文 mermaid/文字描述为准）
• adapters/dingtalk/：钉钉 AI 表格适配器（README + 评审通知/临期提醒 DSL 模板 + 文本键聚合与 SUM 计数模板）——目标平台是钉钉时读这里
• adapters/wecom/：企业微信智能表格适配器（README + FILTER 文本键聚合模板 + 审批轮询 cron + 企微待办临期提醒模板）——企微无自动化引擎，闭环靠定时任务/待办补偿

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

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

1. 飞书 · 多维表格 —— 全流程脚本现成（§1–§7 + scripts/BUILD_RD.md 一键复建），原生自动化+卡片通知，适合已在用飞书的团队
2. 钉钉 · AI 表格 —— 原生 workflow-dsl 通知，跨表聚合用 lookup；计算列经普通查询不回值、需用服务端 psql 校验（走 adapters/dingtalk/）
3. 企业微信 · 智能表格 —— 公式引擎最强、API 写入最顺；无原生自动化，评审/临期提醒用定时任务+企微待办补偿（走 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 付费服务调用流程（Pay Skill）

本技能为付费技能（19.9 元/次），调用服务端获取定制化研发项目管理搭建方案前需完成微信支付。

透明披露：

• 服务端点：https://lanjingshuzi.cn/skillhub/rd-project-management/api/v1/skill/invoke
• 端点运营主体：蓝鲸数字（lanjingshuzi.cn）
• 数据处理范围：请求体仅包含用户的搭建需求描述（平台类型、项目/迭代规模等），不含用户个人隐私数据
• 付费方式：微信支付（WeChat Pay）
• 在发起支付前，必须向用户明确告知本次调用将产生 ¥19.90 费用，并获得用户确认后才可继续

前置检查：当前智能体是否支持微信 AI 支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（如 mcp__weixinpay__weixinpay_register，工具名带前缀也算；存在任意一个即视为支持）。

只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：向用户透明告知本技能为付费技能（¥19.90/次，微信支付），端点由蓝鲸数字（lanjingshuzi.cn）运营，继续本 Skill 的后续流程。
• 不支持：终止流程且不要发起下单。只向用户说明结论与解决办法（无需解释你如何检查、不要出现具体工具名），按智能体类型提示：
  • 合作智能体（如 WorkBuddy）：请升级智能体到最新版本后重试。
  • 开放智能体（如 OpenClaw / DeepSeek Harness）：请根据 https://skillhub.cn/install/skillhub.md ，安装 @tencent-adm/weixinpay-installer。
  • 无法判断类型：请升级智能体或安装微信支付 AI 支付插件后重试。

工作流程

第一步：请求资源

POST https://lanjingshuzi.cn/skillhub/rd-project-management/api/v1/skill/invoke
Content-Type: application/json

{
  "query": "用户的查询内容（如：帮我搭建一个飞书研发项目管理系统，含需求缺陷双流水线与工时看板）",
  "platform": "feishu | dingtalk | wecom",
  "project_count": 3,
  "need_approval": true,
  "need_dashboard": true
}

第二步：处理 402 响应

服务端返回 HTTP 402，提取以下两个值并必须保存：

• Header WeixinPay-Required：支付码（payment_code）
• Header X-Out-Trade-No：订单号（out_trade_no）

响应体示例：

{
  "code": "PAYMENT_REQUIRED",
  "message": "需要支付后才能获取研发项目管理系统定制化搭建方案",
  "WeixinPay": {
    "WeixinPay-Required": "xY9zAbc123def456",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  },
  "out_trade_no": "WX402_20260921120000abcdef123456",
  "amount": "19.90",
  "currency": "CNY"
}

第三步：发起支付（必须获得用户确认）

在调用支付前，必须向用户明确展示以下信息并获得确认：

• 本次使用将产生 ¥19.90 费用
• 支付通过微信支付完成
• 服务端点由蓝鲸数字（lanjingshuzi.cn）运营

用户确认后方可将 WeixinPay-Required 的值作为 paymentCode，调用 weixinpay_pay 工具向用户发起微信支付授权。等待用户完成支付。

第四步：支付成功后获取资源（️ 必须执行）

POST https://lanjingshuzi.cn/skillhub/rd-project-management/api/v1/skill/invoke
Content-Type: application/json
X-Out-Trade-No: WX402_20260921120000abcdef123456

{
  "query": "与第一步完全相同的请求体",
  "platform": "feishu",
  "project_count": 3,
  "need_approval": true,
  "need_dashboard": true
}

⚠️ 第四步是最容易被 Agent 遗漏的一步：不携带 X-Out-Trade-No Header 重试，就永远拿不到付费内容。body 保持与第一次请求一致，仅通过 Header 传递订单号。

成功响应（HTTP 200）：

{
  "code": "SUCCESS",
  "message": "研发项目管理系统定制化搭建方案",
  "out_trade_no": "WX402_xxx",
  "transaction_id": "4200001234202306300000000001",
  "content": "# 研发项目管理系统定制化搭建方案nn..."
}

content 字段即为完整的定制化搭建方案（Markdown 格式），包含表结构设计、公式配置、工作流自动化、平台适配要点、搭建步骤和验证清单。

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

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

在获取到付费方案后、开始搭建前，Agent 必须先检测目标平台的 CLI 是否可用：

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

连接器可用时：

向用户发送确认消息，然后直接进入 §1.2 自动创建 Base：

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

连接器不可用时的处理：

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

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

检测到你的 WorkBuddy 尚未配置 [飞书/钉钉/企业微信] 连接器，我来一步步带你配置，你只需要跟着点就行，全程约 2 分钟。

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

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

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

第 2 步：现在顶部有三个标签：专家、技能、连接器。点击「连接器」这个标签。

完成后回复「好了」。

第 3 步：现在看到连接器列表了吗？找到「[飞书/钉钉/企业微信]」这个卡片（飞书是蓝色纸飞机图标，钉钉是蓝色翅膀图标，企业微信是绿色气泡图标），点击卡片右边的「+」按钮。

完成后回复「好了」。

第 4 步：现在会弹出 [飞书/钉钉/企业微信] 的登录窗口，请用你的账号登录并授权（扫码或输入密码）。这是最后一步，授权完成后就配置好了。

登录授权完成后回复「好了」或「配置完了」。

用户完成全部步骤后：

重新执行 CLI 可用性检测，通过后发送：

✅ 连接器配置成功！正在为你自动创建 Base 并搭建研发项目管理系统，全程无需其他手动操作，预计 5 分钟完成。

然后进入 §1.2 自动创建 Base 流程。

用户中途卡住时：

如果用户回复「没找到」「看不到」「不会」等，不要跳过，用更具体的描述重新引导：

• 「专家·技能·连接器」→「左侧栏中间位置，写着'专家·技能·连接器'七个字，图标是三个小圆圈」
• 「连接器标签」→「顶部三个按钮，最右边那个写着'连接器'」
• 必要时建议用户截图发过来，根据截图判断位置

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

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

• 飞书：lark-cli base +base-create --name 研发项目管理系统，从输出中提取 Base token
• 钉钉：dws aitable +base-bootstrap --name 研发项目管理系统 --tables '[...]' --yes，从输出中提取 baseId
• 企业微信：wecom-cli smartsheet create --json '{"name":"研发项目管理系统",...}'，从输出中提取 docid

创建成功后告知用户 Base 已就绪，直接进入搭建流程。

2. 三步快速开始

1. 按 §1.1 检测连接器 → 按 §1.2 自动创建 Base（用户零手动操作）
2. 按 scripts/BUILD_RD.md 手册逐步执行：建 6 表（普通字段）→ 加 6 双向关联 → 加 30 公式/查找 → 录演示数据 → 建看板视图/甘特/表单 + 仪表盘
3. 按 §5 创建并启用自动化（飞书/钉钉：评审通知 + 临期提醒；企微：定时任务 + 待办提醒）
4. 维护主数据：项目 → 迭代 → 需求/缺陷； thereafter 日常录入见 §6

3. 架构与核心逻辑

三层 + 双流水线：项目基础信息 →(1:N)→ 迭代基础信息 →(1:N)→ 需求处理流程 / 缺陷处理流程；每条工单挂多条研发日报（登记工时）。见 assets/architecture.jpg。

工时回填闭环：已登记工时 = SUM(研发日报.本次工时 按 工单匹配)；剩余工时 = MAX(0, 预估 − 已登记)；工时进度 = 已登记 ÷ 预估。人只在日报填一次工时，工单上的数字全自动。

状态机（只读、自动）：需求 待评审→(评估结果=通过)进行中→(工时满 或 勾选完成)已完成；驳回→已驳回。缺陷对应 待评审→进行中→已解决/暂不处理。

逐级聚合：迭代 = 该迭代内需求/缺陷的 总数/完成数/完成率、计划/投入总工时、迭代进度；项目 = 跨其全部迭代的同名聚合 + 迭代总数 + 项目进度。

看板与提醒：需求/缺陷看板（按评估结果分组）+ 甘特（按计划起止）+ 手机录入表单；评审出结果、临近到期自动给处理人发通知/待办。

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

公式引擎

1. link 字段名 == 表名 → [X].[Y] 被解析为整表列。修复=改 link 名（如 需求处理流程→所属需求）。
2. FILTER 内 CurrentValue.[link].[field] 二级链不支持（静默变 [无效引用]）；三级链也不支持。跨表用两段二级链辅助字段或双向 link 直接 SUM([link].[度量])。
3. 比较两侧表示必须一致：link 渲染为主键文本 vs 名称文本永不匹配；autonumber ≠ text。→ 用工单编号镜像为 text，跨表按 text=text 匹配。
4. 直接二级链 [link].[字段] 可用；SUM([link字段].[工时]) 即主单/父级汇总正确写法。
5. 看板/图表 group/dimension 不支持公式字段 → 看板按「评估结果」select 分组；条件计数不要用 FILTER(cur.[checkbox]=TRUE())（布尔比较不稳），改按状态文本或 SUM 一个 0/1「完成标记」列。

平台引擎（三平台实测差异）

1. 飞书：公式跨表用 FILTER 一步到位；工作流 LarkMessageAction receiver 可用 {"value_type":"ref","value":"$.trigger_1.<处理人fld>"} 动态发给记录处理人；ChangeRecordTrigger 必须带 condition_list（≥1 组）。
2. 钉钉：跨表聚合用 lookup(associateField=反向link, valuesField=子表列, SUM/COUNT)；COUNT 聚合器对文本列返回 0 → 总数类用子表常量「计数」列 + SUM，且常量公式必须写 IF(TRUE,1,1)（纯 1 对既有行不物化）；计算列经普通 record query 不回值 → 用 dws aitable psql 服务端校验；API 批量写入行的 filterUp/lookup 不自动重算 → field update 原样重存 config 唤醒。
3. 企微：link 点号钻取返回 null → 用裸[关联]或 LOOKUP()/FILTER 文本键；同名列跨表聚合被拒 → 表.FILTER(CV.[键]=[本行列]).度量.SUM()；records query 是 SQL 接口（--sql）；无自动化，提醒用 cron/待办补偿；fields add 偶发静默丢失，逐建后 fields list 读回。

工作流/CLI

1. SetRecordTrigger/ChangeRecordTrigger 对公式字段加值过滤运行时不触发 → watch 不带值 + branch 内用 link 钻取真实 select。
2. workflow create 需唯一 client_token；新建默认 disabled 必须 enable；平台无 delete，只能 disable。
3. 消息/卡片按钮自包含：setRecord 改触发记录、openLink 跳转可插值 recordId；Action 节点不设 children。
4. 中文 JSON 一律写到 CLI 解析目录再 --json @file（企微 @file 只认安装工作目录）；table/field/record list 串行；批量列式 {fields,rows}，link 单元格按平台格式。

5. 工作流配方库

5.1 评审结果变更通知处理人（需求 / 缺陷各一条）

触发：需求/缺陷「评估结果」变为非空 → 发消息给该记录「处理人」。

• 飞书：ChangeRecordTrigger(sheet 需求处理流程, condition_list 评估结果 isNotEmpty) → LarkMessageAction(receiver=[ref $.trigger_1.处理人fld], content 含 ref 需求标题+评估结果)。
• 钉钉：workflow-dsl WhenRecordUpdated(sheet, updatedFields=[评估结果]) → SendMessage(to.users=[ref $.start.处理人fld]) → enable。
• 企微：无引擎 → 定时查询「评估结果刚变更」或建待办补偿（见 adapters/wecom）。

5.2 临期/到期提醒（需求 / 缺陷各一条）

• 飞书/钉钉：ReminderTrigger/WhenRecordTimesUp(计划结束日期 前 1 天 09:00) → 发消息给处理人。
• 企微：对「评估通过、未完成」的工单按 计划结束日期 建企微待办（deadline + remind_at_deadline=true），到点提醒；每周跑一次同步。

6. 日常操作 Playbook（摘要）

• 立项：建项目（项目编号）→ 建迭代（迭代编号，选所属项目）
• 提需求/缺陷：新建工单选好所属迭代/项目（企微/钉钉另填文本键），或手机表单录入。状态自动=待评审
• 评审：选评审人、定「评估结果」（通过/驳回）+ 意见；通过后填预估工时、计划起止、处理人 → 触发评审通知
• 填日报：每天在「研发日报-需求/缺陷」新建，选关联工单（+ 工单号文本键）填「本次工时」→ 回工单看已登记/进度/状态自动变化；做完勾选完成
• 看数据：顶部「研发管理驾驶舱」；盯单迭代用看板/甘特视图
• 排障第一问：状态/进度没变？→ 评估结果是否填、日报本次工时是否填

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

1. 表达式读回无 [无效引用]（钉钉用 psql、企微用 records query 交叉验证计算列实际值）
2. 需求「已登记工时」= 其下各日报本次工时之和（示例 XQ-0001：8+8=16 → 进度100% → 已完成）
3. 迭代/项目 需求总数/完成数/完成率/计划·投入工时/进度 与手算一致（示例：某迭代 需求3完成1、缺陷2解决1、计划52投入32、进度40%；项目 迭代2、需求4完成1 25%、进度33.3%）
4. 看板/甘特/表单可用；评审与临期通知/待办实际送达处理人

8. 安全与隐私

包内不含任何密钥、token、租户私有 ID；所有操作以使用者自身飞书/钉钉/企业微信身份授权执行；脚本仅做最小必要读写。实例化后的 Base 权限由使用者自行管理。

9. 更新

见 CHANGELOG.md；语义化版本，minor=新增能力，patch=修坑。

10. SkillHub 上架与打包踩坑记录（2026-09-17 实测）

10.1 zip 打包三条铁律

1. 条目路径必须正斜杠。Windows PowerShell Compress-Archive / .NET CreateFromDirectory 写反斜杠条目，SkillHub 客户端判「文件路径不安全」跳过嵌套条目。
2. tar 的 zip 不能用：JSZip 报 Can't find end of central directory。
3. 正确做法：先 Compress-Archive 生成 JSZip 兼容包，再用 .NET 逐条目复制并把 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，不带 LICENSE 裸文件。
• 客户端跳过二进制文件（jpg/png，提示「禁止上传二进制文件」）→ 示意图用 mermaid/文字写在 SKILL.md 内。
• 实测可过：.md .json .jsonl .sh。本包仅含 SKILL.md + CHANGELOG.md 两个根文件（已过审样例即如此）。

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

• Chrome 后台标签不弹文件框：先激活标签页再点「选择 zip」。
• 千问办公顶部黑条遮挡：scrollIntoView({block:'center'}) 后再点。
• 文件树删除按钮与图标按钮相似，限定作用域勿全局点。

10.4 React 受控表单与报错捕获

• 设值用 HTMLInputElement.prototype 的 value setter + dispatch input。
• 提交失败 toast 无细节：monkey-patch window.fetch 记录响应 body。

10.5 提交与审核

• POST https://api.skillhub.cn/api/v1/orgs/{orgId}/skills 返回 201 即提交成功，进入安全扫描+内容审核，通过后自动上架。
• 被拒时 reviewRejectReason 给原因；升级=bump 版本 + 变更说明 + 重传；审核中勿重复提交同版本号。
• Pay Skill 的官方正路：pay-skill-converter 转既有技能 → lanjingshuzi.cn 网关发布 → /package 导出官方壳（转换器 POSIX-only 需 WSL + Token）。

11. 多平台适配器路由（三平台均生产实测、逐值一致）

同一份核心规格（§2 表结构、§4 公式模式、§5 工作流配方）在三个平台的落地差异速查：

选平台建议：要开箱自动化选钉钉或飞书；要公式最省心、纯 API 写入选企微（注意配 cron/待办）。每平台适配器的坑位清单与模板见对应 README。