腾讯智能表格多表构建器
适用场景
- 用户要做一个「智能表格」而不是普通 Excel，且里面需要多张工作表互相引用。
- 需求管理类：需求列表、详细规格、版本规划、操作手册、资源依赖等分表。
- 设计需求管理类：基础信息、目标背景、详细规格、进度排期、资源依赖等分表。
- 目标是把主要内容沉淀在智能表格内部，减少跳转到外部文档。
核心原则
- 一张数据集一行：需求/规格/任务尽量以行为单位管理，便于筛选、分组、看板。
- 关联字段串表：用
reference类型字段把工作表连起来，实现"从需求看规格/版本/依赖"。 - 详细内容写在字段里：页面说明、交互流程、验收标准、操作步骤等放在
text字段中；在智能表格里点击行即可在详情面板查看完整内容，不用跳转外部文档。 - 多视图辅助管理：在核心表上建表格视图、看板视图、按状态/优先级/待验收等视图。
- 示例数据先行：预置少量覆盖全类型的示例行，让用户立刻看懂结构。
标准表结构建议
核心表：需求列表
| 字段 | 类型 | 说明 |
|---|---|---|
| 需求名称 | text（主键） | 简短名称 |
| 需求ID | text | 可用手工编号或 autoNumber |
| 需求描述 | text | 一句话背景/目标 |
| 所属模块 | singleSelect | 用户中心/订单交易/支付清结算/权限管理/... |
| 所属版本 | singleSelect | v1.0 / v1.1 / ... |
| 优先级 | singleSelect | P0 / P1 / P2 / P3 |
| 紧急程度 | singleSelect | 非常紧急 / 紧急 / 一般 / 不急 |
| 当前状态 | singleSelect | 待启动 / 进行中 / 评审中 / 待验收 / 已验收 / 已归档 / 已驳回 |
| 验收标准 | text | 可验收的量化/定性标准 |
| 验收结果 | singleSelect | 待验收 / 通过 / 不通过 / 驳回 |
| 验收意见 | text | 评审意见 |
| 验收时间 | dateTime | 日期 |
| 负责人 / 协作人 | text | |
| 创建日期 / 计划完成 | dateTime | |
| 归档链接 | url | 定稿后归档地址 |
| 标签 | select（多选） | 紧急 / 需评审 / 对外 / 对内 / 待补充 / 已评审 |
| 完成进度 | progress | 0-100 |
关联表（按需选用）
- 详细规格要求：页面/功能名称、关联需求(reference)、页面说明、交互流程、前置/后置条件、异常处理、验收要点、UI稿链接、优先级、状态、计划完成。
- 版本规划：版本号、版本目标、关联需求(reference，多选)、计划上线/实际上线时间、版本状态、负责人、发布说明、风险与依赖。
- 操作手册：手册名称、适用角色、关联需求/功能(reference)、操作步骤、截图说明、注意事项、状态、负责人、文档链接。
- 资源与依赖：资源/依赖项名称、类型、关联需求(reference)、状态、负责人、预计/实际可用时间、阻塞原因/备注。
构建流程
- 新建智能表格：
manage.create_file设file_type为smartsheet。 - 新增工作表：
smartsheet.add_table指定title与index。 - 清理默认占位字段：
- 用smartsheet.list_fields查看默认字段。
- 找到唯一的text字段作为主键，用smartsheet.update_fields改名为合适标题。
- 用smartsheet.delete_fields删除其余占位字段。 - 添加字段：用
smartsheet.add_fields批量添加；单选/多选用property_single_select/property_select；日期用property_date_time；URL 用property_url。 - 关联字段：先建好目标表并拿到目标表
sheet_id与主键field_id，再创建field_type="reference"字段，property_reference中设置sub_id、field_id、is_multiple。 - 写入数据：
- 先写核心表（需求列表），从add_records返回值中解析出record_id。
- 其他表通过reference_value.items填入目标需求record_id。 - 添加视图：在核心表上建
grid和kanban视图。
关键记录值格式
| 字段类型 | 记录值格式 |
|---|---|
| text | {"field":"字段名","text_value":{"items":[{"text":"内容","type":"text"}]}} |
| singleSelect / select | {"field":"字段名","option_value":{"items":[{"text":"选项"}]}} |
| dateTime | {"field":"字段名","string_value":"毫秒级Unix时间戳"} |
| url | {"field":"字段名","url_value":{"items":[{"link":"...","text":"...","type":"url"}]}} |
| progress / number | {"field":"字段名","number_value":50} |
| reference | {"field":"字段名","reference_value":{"items":["record_id_1","record_id_2"]}} |
常用工具归属
- 文件创建 / 工作表管理：
tencent-docsservice（manage.create_file、smartsheet.*）。 - 字段/记录/视图编辑：
tencent-docsservice（smartsheet.add_fields、smartsheet.add_records、smartsheet.add_view）。
付费能力（支付宝 AI 按量付费 / A2M）
本 Skill 的核心产出由远端付费服务提供，脱离后端服务无法独立完成。调用链严格遵循支付宝 A2M 按次计费协议。
付费端点
POST https://skillpay-gateway.app.workbuddy.link/api/skill/tencent-smartsheet-multitable-builder/invoke
免费端点（先看契约再付费）
GET https://skillpay-gateway.app.workbuddy.link/api/skill/tencent-smartsheet-multitable-builder/spec
六步调用链
- 探测（probe） —— 先请求
spec端点，获取入参契约与当前价格。 - 账单下发（402） —— 直接调用
invoke端点时，服务返回 HTTP 402 Payment Required，响应头携带Payment-Needed字段（Base64URL 编码的账单，含out_trade_no、amount、currency=CNY、resource_id、pay_before、seller_signature）。此时不产出任何内容。 - 用户支付 —— 按账单金额完成支付，取得支付凭证。
- 携带凭证重试（Payment-Proof） —— 用同一请求体重放，并在
Payment-Proof请求头携带 Base64URL 编码的支付凭证（含payment_proof与trade_no）。 - 验付（verify） —— 服务端调用支付宝接口
alipay.aipay.agent.payment.verify验签，校验金额、资源、商户一致。 - 履约确认（fulfillment complete / ack） —— 验付通过后服务调用
alipay.aipay.agent.fulfillment.confirm完成履约回执，并在响应中返回交付物与fulfillment_confirmed: true。
费用
- 计费方式：按次调用计费
- 单价：¥0.05 / 次
- 币种：CNY
幂等与安全
- 严禁伪造、复用或改造
Payment-Proof凭证。 - 严禁在未完成付费的情况下，由本地逻辑补齐或模拟付费端点应有的产出。
- 不得改写
Payment-Needed账单中的签名与金额字段。 - 同一凭证重复提交必须返回同一结果，且不重复扣费。
- 验付失败时服务回退为 402，不得降级放行。
资源
scripts/build_smartsheet_v2.py：一个可运行的示例脚本，演示 5 表 + 关联字段 + 示例数据的完整构建过程。可据此改写为项目特定版本。
