inkreach-teable-cli/docs/cli-skill-design.md

设计：inkreach-cli + inkreach-teable-ops skill

日期：2026-08-07 分支：develop 关联调研：自动化 API 契约调研报告（本会话产出）

1. 背景与动机

inkreach-teable（本项目）自研了一套自动化（workflow）引擎，与官方 teable 的自动化完全不兼容：

维度	官方 teable	本项目（inkreach）
过滤条件键名	filter	conditions
监听字段键名	watchFieldIds	fieldIds
recordCondition category	recordMatchesConditions	recordCondition
Webhook 路由	/api/webhook/base/{baseId}/workflow/{wfId}	/api/webhook/{baseId}/{wfId}
scheduledTime	完整 timing	后端只读 timing.type+interval，其余忽略
节点 config 结构	自有契约	本项目自研

官方 teable CLI（v0.6.22）按官方契约调用，无法操作本项目自动化（已实测：列自动化时 404/契约不匹配）。表格/字段/记录/视图的 REST API 则与官方完全兼容。

结论：必须自研一个 inkreach CLI 包装本项目真实契约，并配套一个 skill 教 Agent 如何使用。

2. 目标

1. inkreach CLI（packages/inkreach-cli/）：Node.js 命令行工具，封装本项目全部 REST API，重点是自研自动化契约。
2. inkreach-teable-ops skill（.agents/skills/inkreach-teable-ops/）：教 Agent 何时用哪个 CLI 命令、配置表格与自动化的正确姿势、本项目的部署/开发约定。
3. 端到端验证：在本地实例真实跑通"建表 → 建自动化 → 配 buttonClick 触发器 → 激活 → 查执行历史"全链路。

3. CLI 设计（packages/inkreach-cli/）

3.1 技术选型

• 运行时：Node.js（无额外运行时依赖，项目已是 Node 栈）。
• 框架：commander（成熟、零学习成本、官方 teable CLI 也用 commander）。
• HTTP：node:https/node:http（不用 fetch——Node v24 全局 fetch 会吞 Authorization 头，这是本会话已确认的坑）。封装一个 request()。
• 配置存储：~/.inkreach/config.json（endpoint + token），支持环境变量覆盖 INKREACH_ENDPOINT / INKREACH_TOKEN。
• 输出：默认人类可读（表格/着色），--json 输出原始 JSON 供 Agent 解析。
• 零运行时依赖优先（commander 是唯一依赖），便于 node bin.js 直接跑、便于打包。

3.2 命令树

inkreach [全局选项] <命令>

全局选项:
  --endpoint <url>      覆盖配置的 endpoint（默认 http://localhost:3000）
  --token <token>       覆盖配置的 PAT
  --base-id <id>        默认 base（多数命令可省略）
  --json                输出原始 JSON（供 Agent 解析）
  --debug               打印请求/响应到 stderr

认证:
  auth login            交互式配置 endpoint + 创建/输入 PAT
  auth status           验证 token 有效性（GET /api/user/me）
  auth token create     创建 PAT（POST /api/access-token，返回完整 token 仅一次）
  auth token list       列出 PAT
  auth token delete <id>

表格/字段/记录/视图（兼容官方端点）:
  base list / get
  table list / get / create / update / delete
  field list / get / create / update / delete
  record get / create / update / delete
  view list / get / create / update / delete

自动化（自研契约，核心）:
  workflow list                          列出 base 下所有自动化
  workflow get <id>                      详情（含 nodes + edges）
  workflow create --name <n>             创建（自动带 recordCreated 触发器）
  workflow update <id> [--name] [--desc] 改名/描述
  workflow delete <id>                   软删除
  workflow activate <id>                 激活（建快照 + 注册触发器）
  workflow deactivate <id>               停用
  workflow test <id>                     测试运行（mock 输入跑 action）
  workflow node set <id>                 整体替换 nodes+edges（PUT /node）

  触发器配置（便捷封装，生成正确的 config JSON）:
  trigger set <wfId> --type <T> [选项]   设置触发器类型与配置
    --type: recordCreated|recordUpdated|recordCondition|recordCreatedOrUpdated|
            formSubmitted|scheduledTime|buttonClick|webhook
    --table-id, --field-ids, --form-id, --conditions <json>,
    --schedule <json>, --batch <json>

  Action 配置:
  action add <wfId> --type <T> [选项]    添加 action 节点
    --type: script|sendEmail|httpRequest|createRecord|updateRecord|getRecords
    各类型选项见 api-reference

  action update <wfId> <nodeId> [选项]
  action delete <wfId> <nodeId>

  Secrets:
  secret list <wfId>
  secret set <wfId> --name <n> --value <v>
  secret update <wfId> <id> [--name] [--value]
  secret delete <wfId> <id>

  执行历史:
  runs list <wfId> [--status failed|succeeded|running]
  runs get <wfId> <executionId>
  runs rerun <wfId> <executionId>

触发（手动激发，用于测试）:
  fire button-click <tableId> <recordId> <fieldId>   模拟按钮点击
  fire webhook <baseId> <workflowId> [--body <json>]  模拟 webhook

SQL（只读）:
  sql <sql>                            POST /api/base/{baseId}/sql

3.3 关键设计决策

1. 键名严格用代码真实值：conditions（非 filter）、fieldIds（非 watchFieldIds）、recordCondition（非 recordMatchesConditions）。CLI 内部硬编码正确键名，Agent 无需记忆。
2. trigger set / action add 是"智能封装"：Agent 传简单参数，CLI 生成正确的节点 JSON，调 PUT /node 整体替换。避免 Agent 手搓节点 JSON 出错。
3. PUT /node 是整体替换：CLI 的 action add/update/delete 内部都先 GET 完整图、修改、再 PUT 全图，保证不丢节点。
4. scheduledTime 如实反映后端行为：skill 文档明确标注"后端只认 timing.type+interval"，CLI 的 --schedule 参数只接受这两个字段，多余的会在文档里说明无效。
5. webhook 路由用真实的：fire webhook 打 /api/webhook/{baseId}/{wfId}（非前端展示的 /base//workflow/ 路径）。
6. 认证：PAT 格式 teable_{id}_{加密sign}：CLI 不自行加密，通过 auth token create（调 POST /api/access-token）拿到完整 token 字符串，存入配置。
7. --json 模式：所有命令支持，输出原始 JSON，Agent 可解析。默认是人类可读表格。
8. 错误处理：非 2xx 响应解析 {error:{code,message}}，人类模式打印友好错误，--json 模式打印原始错误体。

4. Skill 设计（.agents/skills/inkreach-teable-ops/）

4.1 SKILL.md（入口）

YAML frontmatter（name + 极详细的 description 触发条件）+ 以下章节：

1. 先决条件与约束：CLI 安装、endpoint/token、--base-id 默认值、--json 模式
2. 模块地图表：用户意图 → 模块 → 入口命令 → 该读哪篇 guide
3. 路由规则表：正确做法 vs 错误做法（带原因）
4. 快速语法：最常用命令的示例
5. 关键约束：键名差异、scheduledTime 简化、webhook 路由、PUT 整体替换、快照语义
6. 执行规则：标准顺序（确认上下文 → 读后写 → 执行 → 验证）+ 关键规则（带原因）
7. 常见错误与恢复
8. API 参考索引

4.2 目录结构

.agents/skills/inkreach-teable-ops/
├── SKILL.md                      入口
├── metadata.json                 版本元数据
├── scripts/
│   └── install.sh                安装/升级 inkreach CLI（pnpm build + link）
└── guides/ 与 api-reference/     按需加载
    ├── guides/
    │   ├── instance-access.md    本实例访问信息（endpoint、服务状态、凭据获取）
    │   ├── cli-reference.md      CLI 全命令参考（含 --json 用法）
    │   ├── tables-fields.md      建表/字段类型/记录/视图
    │   ├── automation-guide.md   自动化配置全流程（核心）
    │   └── development.md        本项目开发（构建/重启/systemd/已知坑）
    └── api-reference/
        ├── trigger-types.md      8 触发器配置细节（真实键名）
        ├── action-types.md       6 执行器配置细节
        └── field-types.md        字段类型别名与选项

4.3 与官方 agent-skills 的差异

• 键名：全部用本项目真实键名（conditions/fieldIds/recordCondition），不沿用官方的 filter/watchFieldIds。
• scheduledTime：如实标注后端简化实现，不教 Agent 配后端不认的字段。
• webhook：用真实路由，明确说明 authorization 后端不校验。
• 新增 buttonClick 完整链路：按钮字段创建 → buttonClick 触发器 → 激活 → fire button-click 测试。
• development.md：官方无此内容，本项目独有（systemd 双进程、构建重启、沙箱无 process 等坑）。

5. 实施顺序（TDD/SDD）

1. CLI 骨架：packages/inkreach-cli/ 初始化（package.json、bin、commander 框架、request() 封装、config 存储、auth login/status）。
2. 基础资源命令：base/table/field/record/view（官方兼容端点，最简单）。
3. workflow 命令：list/get/create/update/delete/activate/deactivate/test。
4. 触发器/Action 便捷封装：trigger set / action add/update/delete（内部 GET-modify-PUT 全图）。
5. secrets / runs / fire / sql。
6. skill 文档：SKILL.md + guides + api-reference + metadata + install.sh。
7. 端到端验证：真实实例跑通全链路。
8. 注册：在 AGENTS.md 添加 skill 说明。

6. 验证标准

• inkreach auth status 返回当前用户。
• inkreach workflow list --base-id bseeZR7yiDNeMPCa4CN 列出自动化。
• inkreach workflow create --name "CLI测试" --base-id bseeZR7yiDNeMPCa4CN 创建成功。
• inkreach trigger set <wfId> --type buttonClick --table-id tblXXX --field-ids '["fldXXX"]' 正确配置。
• inkreach action add <wfId> --type script --code '...' 正确添加节点。
• inkreach workflow activate <wfId> 激活成功（返回 snapshotId）。
• inkreach fire button-click ... 触发执行。
• inkreach runs list <wfId> 能看到刚才的执行。
• skill 被 Agent 正确加载（出现在 available_skills）。

7. 非目标

• 不做 App 构建/网页抓取（本项目无此功能）。
• 不修复 scheduledTime 后端缺陷（如实记录，CLI 只暴露有效字段）。
• 不发布到 npm（本地 pnpm link 即可）。
• 不保持与官方 teable CLI 的命令兼容（独立命令树）。