名称: coda-packs 描述: 通过REST API v1管理Coda Packs。支持列出、创建、更新和删除私有Packs。需要CODA_API_TOKEN。删除操作需要确认。注意：构建、Gallery提交、分析和协作者管理需要使用Coda的Pack SDK CLI，无法通过REST API实现。

Coda Packs 技能

通过REST API v1管理Coda Packs。创建、列出、更新和删除私有Packs。

⚠️ API 限制

Coda REST API v1的Pack管理功能有限：

功能	REST API	Pack SDK CLI
列出Packs	✅ 可用	✅
创建Pack	✅ 可用	✅
更新Pack	✅ 可用	✅
删除Pack	✅ 可用	✅
构建版本	❌ 不可用	✅ 必需
Gallery提交	❌ 不可用	✅ 必需
分析	❌ 不可用	✅ 必需
协作者	❌ 不可用	✅ 必需

对于构建、Gallery提交和高级功能，请使用：

npx @codahq/packs-sdk register    # 创建账户
npx @codahq/packs-sdk build       # 构建Pack
npx @codahq/packs-sdk release     # 提交到Gallery

使用场景

当用户想要：

列出现有的Coda Packs
创建新的私有Pack外壳
更新Pack元数据（名称、描述）
删除未使用的Packs

不适用场景

请勿用于 文档管理（表格、行、页面）→ 使用 coda 技能
请勿用于 构建Pack版本 → 使用Pack SDK CLI
请勿用于 Gallery提交 → 使用Pack SDK CLI
请勿用于 查看分析 → 使用Pack SDK CLI或Coda网页界面

先决条件

API令牌：设置环境变量 CODA_API_TOKEN
- 获取令牌地址：https://coda.io/account -> API设置
- 必须具有Pack管理权限
Python 3.7+ 并安装 requests 库

快速开始

# 设置
export CODA_API_TOKEN="your_token_here"

# 列出您的Packs
python scripts/coda_packs_cli.py packs list

# 创建新的Pack外壳
python scripts/coda_packs_cli.py packs create \
  --name "我的集成" \
  --description "实现酷炫功能"

# 更新Pack
python scripts/coda_packs_cli.py packs update my-pack-id \
  --description "更新后的描述"

# 删除Pack（需要确认）
python scripts/coda_packs_cli.py packs delete my-pack-id

完整的Pack开发工作流程

由于REST API仅支持基本的Pack管理，以下是完整的工作流程：

步骤1：创建Pack外壳（通过REST API）

python scripts/coda_packs_cli.py packs create \
  --name "Karakeep书签" \
  --description "保存和搜索书签"

步骤2-4：使用Pack SDK CLI（必需）

# 安装Pack SDK
npm install -g @codahq/packs-sdk

# 初始化Pack项目
npx @codahq/packs-sdk init karakeep-pack

# 开发您的Pack（编辑pack.ts）
# 参见：https://coda.io/packs/build/latest/guides/quickstart/

# 构建和上传
npx @codahq/packs-sdk build
npx @codahq/packs-sdk upload

# 提交到Gallery（准备就绪后）
npx @codahq/packs-sdk release

CLI工具使用

Pack管理

# 列出所有Packs
python scripts/coda_packs_cli.py packs list

# 获取Pack详情
python scripts/coda_packs_cli.py packs get 48093
python scripts/coda_packs_cli.py packs get "Karakeep"

# 创建新Pack
python scripts/coda_packs_cli.py packs create \
  --name "我的Pack" \
  --description "描述" \
  --readme "# 我的Pack

详细信息"

# 更新Pack元数据
python scripts/coda_packs_cli.py packs update my-pack-id \
  --name "新名称" \
  --description "新描述"

# 删除Pack（需要确认）
python scripts/coda_packs_cli.py packs delete my-pack-id
# 或跳过确认：--force

Pack ID解析

CLI接受数字Pack ID和Pack名称：

# 这些是等效的：
python scripts/coda_packs_cli.py packs get 48093
python scripts/coda_packs_cli.py packs get "Karakeep"

如果名称不明确，CLI会列出匹配项并退出。

安全护栏

需要确认的操作

操作	风险	确认提示
删除Pack	不可逆	“删除Pack ‘X’？此操作无法撤销。”

无需确认的操作

创建Pack：安全，可逆
列出/获取Packs：只读
更新Pack：可逆

错误处理

常见API错误：

代码	含义	解决方案
`401`	令牌无效	刷新CODA_API_TOKEN
`403`	权限不足	确保令牌具有Pack管理权限
`404`	Pack未找到	检查Pack ID或名称
`429`	速率限制	等待并重试（自动处理）

参考资料

Pack SDK指南：https://coda.io/packs/build/latest/guides/overview/
Pack SDK快速入门：https://coda.io/packs/build/latest/guides/quickstart/
Coda API文档：https://coda.io/developers/apis/v1
Pack SDK NPM：https://www.npmjs.com/package/@codahq/packs-sdk

示例：Karakeep Pack外壳

为测试创建：

名称：Karakeep
ID：48093
描述：Karakeep书签管理器 - 保存URL、搜索并使用标签组织

完整Pack开发的后续步骤：

使用Pack SDK CLI：npx @codahq/packs-sdk init karakeep-pack
实现Karakeep API集成（参见https://docs.karakeep.app/api/）
构建和上传：npx @codahq/packs-sdk build && npx @codahq/packs-sdk upload