feat: add inkreach CLI + inkreach-teable-ops skill
A self-built CLI and companion agent skill for operating a deployed
inkreach-teable instance — configuring tables, fields, records, views, and
the project's OWN automation engine.
Why not the official 'teable' CLI:
inkreach-teable's automation is self-built with a different contract:
- conditions (not filter), fieldIds (not watchFieldIds)
- recordCondition (not recordMatchesConditions)
- webhook route /api/webhook/{baseId}/{wfId} (not the /base//workflow/ form)
- scheduledTime backend honors only timing.type + timing.interval
The official CLI targets the upstream contract and 404s/misconfigures here.
Table/field/record/view APIs ARE upstream-compatible, but automation is not.
inkreach CLI (packages/inkreach-cli/):
- Node.js + commander, zero extra runtime deps
- Uses node:http (NOT fetch — Node 24 fetch drops Authorization header)
- Commands: auth (login/status/token), base/table/field/record/view,
workflow (list/get/create/update/delete/activate/deactivate/test),
trigger set (8 types, builds correct config keys), action add/update/delete
(6 types), secret, runs (list/get/rerun), fire (button-click/webhook), sql
- --json mode for agent parsing; GET->modify->PUT whole-graph for node edits
- Verified end-to-end: create workflow -> set webhook trigger -> add script
action -> activate -> fire webhook -> runs list (succeeded)
inkreach-teable-ops skill (.agents/skills/inkreach-teable-ops/):
- SKILL.md entry: module map, routing rules, 11 key constraints (the real
contract keys), execution rules, error recovery
- guides/: cli-reference, automation-guide, tables-fields, instance-access,
development (build/restart, known gotchas)
- api-reference/: trigger-types (8 triggers, exact config), action-types
(6 actions, sandbox globals), field-types (21 types incl. Button)
- metadata.json + install.sh
This commit is contained in:
yeuimu
@@ -0,0 +1,195 @@
|
||||
# 设计：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 的命令兼容（独立命令树）。
|
||||
Reference in New Issue
Block a user