yeuimu
d3790ab856
Rename the skill directory and update all references (SKILL.md frontmatter name, AGENTS.md, design doc, install.sh). Git tracks this as a rename so history is preserved.
196 lines
11 KiB
Markdown
196 lines
11 KiB
Markdown
# 设计：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> 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/`）
|
||
|
||
### 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**。
|
||
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 的命令兼容（独立命令树）。
|