# 设计：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. 目标

1. **`inkreach-teable` CLI**（`packages/inkreach-cli/`）：Node.js 命令行工具，封装本项目全部 REST API，重点是自研自动化契约。
2. **`inkreach-teable` skill**（`.agents/skills/inkreach-teable/`）：教 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-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 关键设计决策

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/`）

### 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/
├── 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）

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 已在 0.1.5 移除：后端无 SQL 查询 API）。
6. **skill 文档**：SKILL.md + guides + api-reference + metadata + install.sh。
7. **端到端验证**：真实实例跑通全链路。
8. **注册**：在 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 的命令兼容（独立命令树）。