Files

T

yeuimu 8dacbf7f2d fix(cli): 轨迹分析驱动的 8 处命令修复 + 技能文档同步 (0.1.5)

- table get/update: 改用真实路由 /api/base/:baseId/table/:tableId(/name)
- view get/update/delete: table 域路由;view update 实现文档承诺的
  --filter/--sort/--group/--column-meta(sort 自动包装 sortObjs)
- record create --fields 自动包装 {records:[{fields}]}
- record delete 单条走单删端点(修复单值 query 解析成 string 的 400),
  支持位置参数;record list 加为 record get 别名
- record get-one / record get --record-id 走 table 域路由
- 移除 sql 命令:后端无 SQL 查询 API(404),技能文档 5 处同步改写
- plugin 技能 dev-workflow 内联 known-good webpack.config
  (禁止 output.library.type=iife,评估轨迹中 with_skill 组也反复踩坑)

2026-09-29 06:45:37 +00:00

11 KiB

Raw Blame History

设计：inkreach-cli + inkreach-teable skill

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

1. 背景与动机

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

维度	官方 teable	本项目（inkreach-teable）
过滤条件键名	`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-teable CLI 包装本项目真实契约，并配套一个 skill 教 Agent 如何使用。

2. 目标

inkreach-teable CLI（packages/inkreach-cli/）：Node.js 命令行工具，封装本项目全部 REST API，重点是自研自动化契约。
inkreach-teable skill（.agents/skills/inkreach-teable/）：教 Agent 何时用哪个 CLI 命令、配置表格与自动化的正确姿势、本项目的部署/开发约定。
端到端验证：在本地实例真实跑通"建表 → 建自动化 → 配 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-teable/config.json（endpoint + token），支持环境变量覆盖 INKREACH_TEABLE_ENDPOINT / INKREACH_TEABLE_TOKEN。
输出：默认人类可读（表格/着色），--json 输出原始 JSON 供 Agent 解析。
零运行时依赖优先（commander 是唯一依赖），便于 node bin.js 直接跑、便于打包。

3.2 命令树

inkreach-teable [全局选项] <命令>

全局选项:
  --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>~~                        (removed in 0.1.5 — backend has no SQL query API)

3.3 关键设计决策

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

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

4.1 SKILL.md（入口）

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

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

4.2 目录结构

.agents/skills/inkreach-teable/
├── SKILL.md                      入口
├── metadata.json                 版本元数据
├── scripts/
│   └── install.sh                安装/升级 inkreach-teable 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）

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

6. 验证标准

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

7. 非目标

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

11 KiB Raw Blame History Unescape Escape