aitable-workflow-core 0.1.21 → 0.1.22-beta.1788156544984

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aitable-workflow-core",
-  "version": "0.1.21",
+  "version": "0.1.22-beta.1788156544984",
   "description": "配置驱动的 AI 表格工作流自动化引擎(core):YAML 定义业务流程，AI 逐步执行并回写钉钉 AI 表格；含 CLI 与工作流引擎。",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "dependencies": {
-    "aitable-workflow-base": "0.1.21",
+    "aitable-workflow-base": "0.1.22-beta.1788156544984",
     "@inquirer/prompts": "^8.5.2",
     "cron-parser": "^5.6.2",
     "cross-spawn": "^7.0.6",

package/skills/aitable-workflow/reference/event-sources.md

@@ -6,9 +6,21 @@ YAML 里配置键用 **snake_case**（`base_id`、`watch_mode`、`poll_interval_
 
 **只有用户明确要求外部事件驱动入口（群消息、webhook、对话监听、定时触发、监听表格变更）时才生成 `event_sources`。** 表单提交、手动新建记录这类场景不要生成事件源——tracker 自身轮询即可。
 
-## 四种内置类型
+## 内置类型一览
 
-### 1. `dingtalk_message` — 钉钉群消息（dws 轮询）
+| type | 机制 | 用在哪 |
+| --- | --- | --- |
+| `dingtalk_message` | dws 逐群轮询 | 监听指定群的全部消息，不需要机器人 |
+| `dingtalk_group_message` | 同上（语义化别名） | 新写的 workflow 用这个名字 |
+| `dingtalk_user_message` | dws `list-all` 单次批量拉取 | 群多到逐群轮询扛不住时（200+ 群） |
+| `dingtalk_stream` | WebSocket 推送 | @机器人触发、要支持单聊 |
+| `cron_scheduler` | 定时 | 日报、巡检、定时汇总 |
+| `aitable_record` | AI 表格记录轮询 | 监听表格记录新增/变更 |
+
+三个 `dingtalk_*` 消息类型产出**同构**的 `message_received` 事件 —— 换入站方式只改 `type`，
+下游 handler / workflow 零改动。
+
+### 1. `dingtalk_message` — 钉钉群消息（dws 逐群轮询）
 
 个人身份轮询拉取会话消息，**不需要机器人**。
 
@@ -35,7 +47,24 @@ event_sources:
 5. `conversation_ids` 也可以整值填运行时引用（如 `${globalVar.group_pull_list}`），此时群列表由 config-sync 之类的 workflow 动态发布，见 `runtime-refs.md` 与 `../../aitable-workflow-design/patterns/config-in-aitable.md`。
 6. `conversation_ids` 三档语义：完全缺省 → setup/check 报必填缺失（防「声明轮询源却不监听任何会话」的静默缺口）；显式空数组 `[]` → 「默认停用」的合法状态，仅 suggestion 提示、不阻断；非空数组 / ref 串 → 正常启用。
 
-### 2. `dingtalk_stream` — 钉钉企业内机器人（WebSocket 推送）
+### 2. `dingtalk_group_message` — 语义化别名
+
+与 `dingtalk_message` **完全同一个实现**（同 factory、同必填校验），只是名字更准确。
+新写的 workflow 用这个名字；已有模板里的 `dingtalk_message` 仍然有效，不要为了改名而改。
+
+### 3. `dingtalk_user_message` — 批量拉取（群很多时用）
+
+配置与 `dingtalk_message` 相同（`conversation_ids` 必填，也接受写在 `filters.conversation_ids` 下），
+差别只在拉取机制：它用一次 `dws chat message list-all` 把**所有**会话的消息拉回来，再在本地按
+`conversation_ids` 过滤。
+
+**什么时候必须换成它**：逐群轮询是「一个群一次 dws 子进程调用」，群数上到 200+ 时一轮就要拉起
+200+ 个子进程，一轮跑不完下一轮就到了。换成本类型后一轮只要 1~5 次分页调用。
+
+代价：拉的是当前账号能看到的**全部**会话，所以过滤在本地做，`conversation_ids` 写错不会报错、
+只会静默什么都收不到。群数不多时用 `dingtalk_group_message` 更直白。
+
+### 4. `dingtalk_stream` — 钉钉企业内机器人（WebSocket 推送）
 
 **前提：必须先在钉钉开放平台创建一个企业内机器人**，拿到 `client_id` / `client_secret` 配进来。没有机器人这个类型用不了。
 
@@ -55,7 +84,7 @@ event_sources:
 - 凭据可用直接值或 `*_env` 指向环境变量，**二者满足其一即可**（不是都要填）。
 - 出站 @人 由 `messaging.replyToConversation` 消费本源登记的 `sessionWebhook` 完成——用这个类型时回复能力自动可用。
 
-#### 两种钉钉入站怎么选
+#### 两种机制怎么选（轮询 vs 推送）
 
 | | `dingtalk_message` | `dingtalk_stream` |
 | --- | --- | --- |
@@ -65,9 +94,26 @@ event_sources:
 | 单聊 | **不支持**，只能监听群会话 | **支持**单聊 + 群 |
 | 需要配什么 | `conversation_ids`（要先拿到会话 ID） | 机器人凭据（不必枚举会话） |
 
-选择依据：用户提到「@机器人」「私聊/单聊机器人」「实时响应」→ `dingtalk_stream`；提到「监听某个群的全部消息」「不想建机器人」→ `dingtalk_message`。
+选择依据：用户提到「@机器人」「私聊/单聊机器人」「实时响应」→ `dingtalk_stream`；提到「监听某个群的全部消息」「不想建机器人」→ `dingtalk_message`；群数上到 200+ → `dingtalk_user_message`。
+
+#### 设计期就要定下来的四条通道约束
+
+这四条会改变方案形状，**必须在写 `workflow.yml` 之前问清楚**，事后发现要返工：
+
+1. **`dingtalk_stream` 要企业内机器人，而企业内机器人可能要等管理员审批。** 用户等不了时
+   唯一的替代是「轮询入站 + 自定义机器人出站」，触发方式会从「@ 才答」变成「不 @ 也答」——
+   这是用户感知得到的行为差异，得他同意。开通流程见交付包的 `references/bot-provisioning.md`。
+2. **归属不匹配的外部群加不进企业内机器人**（服务端报 `300001`）。用户要监听的群里有外部群时，
+   设计上就得允许「同一个 workflow 里不同群走不同通道」，别假设全局一种通道。
+3. **`dingtalk_stream` 是独占长连接**：同一份机器人凭据同时只允许一个进程连着。第二个实例会
+   抢走第一个的连接，症状是群消息时有时无。所以不要设计成多实例并行消费同一批群。
+4. **出站能不能 @人 取决于通道**：`session`（stream 登记的 sessionWebhook）与 webhook 能 @人，
+   机器人 API 不能（钉钉限制，只能在正文前置称呼）。需求里有「@提醒某人」时先确认通道能做到。
+
+出站三档（`session` → 机器人 API → webhook）的选路顺序、`skipped` 语义与机器人开通流程，
+见交付包 skill 里的 `references/bot-provisioning.md`（不在本 skill 内）。
 
-### 3. `cron_scheduler` — 定时调度
+### 5. `cron_scheduler` — 定时调度
 
 用于日报、巡检、定时汇总等。`daily_at` / `cron` / `interval_ms` **三者恰选其一**。
 
@@ -82,7 +128,7 @@ event_sources:
       event_type: daily_review # 产出的自定义事件类型
 ```
 
-### 4. `aitable_record` — AI 表格记录轮询
+### 6. `aitable_record` — AI 表格记录轮询
 
 监听 AI 表格记录的新增 / 变更。
 

package/skills/aitable-workflow-design/SKILL.md

@@ -16,8 +16,10 @@ description: 把业务需求变成 aitable-workflow 产物的工作方法。当
 ## 步骤
 
 1. **需求澄清（任何任务的第一步）** → `patterns/clarification-checklist.md`
-   逐项核对「我替用户做的每个决策是否有需求依据」。有缺口就在**同一轮**里发**一张** `<question-form>` 问清，发完停下等答复；格式见 `reference/question-form-protocol.md`。
-   无法提问（非交互执行）时按缺省假设推进，但必须写进产物注释与汇报的「需确认项」。**禁止静默猜测。**
+   逐项核对「我替用户做的每个决策是否有需求依据」。有缺口就在**同一轮**里问清，问完停下等答复；
+   **发问方式取决于通道**，先按 `reference/clarify-channels.md` 判定（内层发一张
+   `<question-form>`，格式见 `reference/question-form-protocol.md`；外层散文式一问一答）。
+   没人可问时按缺省假设推进，但必须写进产物注释与汇报的「需确认项」。**禁止静默猜测。**
 2. **判定项目形态**，选一条主线（两份清单不要混用）：
    - 全新项目（无 workflow.yml）→ `patterns/greenfield-checklist.md`
    - 修改已有项目（已有 workflow.yml / recipes）→ `patterns/brownfield-editing.md`
@@ -33,7 +35,8 @@ description: 把业务需求变成 aitable-workflow 产物的工作方法。当
 | 我要做什么 | 识别信号 | 加载 |
 | --- | --- | --- |
 | 判断需求够不够、该问什么 | **任何任务的第一步** | `patterns/clarification-checklist.md` |
-| 发澄清表单 | 需要向用户提问 | `reference/question-form-protocol.md` |
+| 判定该用哪种方式发问 | 需要向用户提问 | `reference/clarify-channels.md` |
+| 发澄清表单（仅内层通道） | 宿主会解析 `<question-form>` | `reference/question-form-protocol.md` |
 | 全新项目从零生成 | 无 workflow.yml；scene 是全新场景 | `patterns/greenfield-checklist.md` |
 | 改已有项目 | 已有 workflow.yml / recipes / views.yml；「新增一个步骤」「加一个 workflow」 | `patterns/brownfield-editing.md` |
 | 配置存 AI 表格由运营维护 | 「运营自己改」「不重启生效」「配置表」、globalVar 发布订阅 | `patterns/config-in-aitable.md` |

package/skills/aitable-workflow-design/patterns/clarification-checklist.md

@@ -18,43 +18,26 @@
 | **需求过于单薄** | 「监听群消息，是 X 类问题就回复，其他不回」 | 缺的是：哪些群、群列表由谁维护、要不要 @ 才响应、机器人自己的消息是否处理、判断靠关键词还是模型、要不要留痕、判断不了时怎么办 |
 | **有多种合理拆法且选择会改变架构** | 「审核后发送」——审核是人工卡点还是模型判定？ | 直接把两种拆法摆出来让用户选 |
 
-一两句话的需求天然属于第二种：能跑通不等于决策有依据，**这种情况应当提问**，而不是把下面 10 项默默替用户定了。
+一两句话的需求天然属于第二种：能跑通不等于决策有依据，**这种情况应当提问**，而不是把下面 11 项默默替用户定了。
 
 **只有流程清楚了，下面的技术决策点才有意义。** 不要在还不知道业务流程长什么样时就去问 `record_policy`。
 
 ## 怎么问
 
-一轮**只发一张表单**，发完停止输出等答复：
-
-<question-form>
-{
-  "id": "clarify-1",
-  "title": "开始生成前，先确认几点",
-  "questions": [
-    {
-      "id": "trigger",
-      "label": "这个流程怎么被触发？",
-      "type": "radio",
-      "options": [
-        { "label": "群里 @ 机器人（也支持单聊）", "value": "dingtalk_stream" },
-        { "label": "定时", "value": "cron_scheduler" }
-      ],
-      "required": true
-    }
-  ]
-}
-</question-form>
-
-- `type`：`radio` | `checkbox` | `text` | `textarea` | `switch`
-- `radio` / `checkbox` 必须给 `options`（`label` 给人看，`value` 是稳定机器值）
-- 可选：`required`、`defaultValue`（你推断的预填，能减少用户负担就填）、`help`、`placeholder`、`maxSelections`
-- 只在「另一题的答案决定本题是否相关」时用 `showIf: { questionId, hasValue }`
-- **一次问完**，3-6 题；不要挤牙膏式连环追问
-- 问会**改变架构**的决策点，不问用户答不上来的实现细节（别问「用不用 globalVar」，要问「配置想让谁改、怎么改」）
+**发问机制取决于通道，先读 `../reference/clarify-channels.md` 判定**——内层通道发一张
+`<question-form>`，外层通道散文式一问一答。把表单发给不解析它的宿主，用户只会收到一段裸 JSON。
+
+两个通道共同的原则：
+
+- **一轮问完**要问的所有点，不要挤牙膏式连环追问。
+- 问会**改变架构**的决策点，不问用户答不上来的实现细节（别问「用不用 globalVar」，要问「配置想让谁改、怎么改」）。
+- 你推断得出的默认值就直接预填/明说，能减少用户负担。
+- 选项穷不尽的（判断口径、话术、边界条件）就让用户自己说一段话，不要硬凑成选择题。
 
 ## 没人能回答时
 
-非交互执行（`--yes` / 服务端自动流程）拿不到答复。此时按下面每项的「缺省假设」推进，但**必须**：
+内层非交互执行（`--yes` / `--skip-questions` / 服务端自动流程），或外层用户明确说「你自己定」——
+两种情况处理相同：按下面每项的「缺省假设」推进，但**必须**：
 
 - 在产物 YAML / recipe 里以注释写明「假设：…（需确认）」
 - 在最终汇报里单列「需确认项」清单
@@ -72,7 +55,19 @@
 - **缺省假设**：表单提交或手动新建 → **不生成** `event_sources`，靠 tracker 自身轮询。
 - **不澄清的后果**：给表单场景生成了事件源 → 多一套永不触发的死配置；给群消息场景漏了事件源 → 流程根本不会启动。
 
-### 2. AI 表格数据源的筛选条件 ⚠️ 最高优先级
+### 2. 数据放新表还是已有的表
+
+- **这一项由 setup 阶段问用户，设计期不用主动问。** 建资源发生在 setup，问法与两个方向的
+  处理都在交付包 skill 的 `references/base-and-table.md`。
+- **设计期该做的**：`tracker.base_id` 留空、根级 `base_name` 给一个业务化名字
+  （缺省会回落成项目目录名）。留空是正确的默认值，不是待办。
+- **唯一需要设计期介入的情形**：用户在澄清时主动说「就写进我那张已有的表」。
+  这时 `field_definitions` 必须**照那张表现有的列写** —— 凭空发明字段名不会报错，
+  只会往用户的真实业务表里静默加列，而字段建出来之后改名等于数据迁移。
+  此时本项连带绑死第 8 项。
+- ID 一律由用户给，**不要猜** —— 猜出来的 ID 轻则指向不存在的资源，重则指向别人的表。
+
+### 3. AI 表格数据源的筛选条件 ⚠️ 最高优先级
 
 - 只在触发方式含「AI 表格记录新增或变更」时适用。
 - **只处理满足什么条件的记录？**（例：状态 = 待处理；知识沉淀 = 待沉淀）
@@ -81,21 +76,21 @@
 - **不澄清的后果**：**这是已发生过的线上故障。** 无筛选条件时每轮全表分页扫描，几百行时正常，涨到几万行后 dws 查询直接超时，链路静默停摆且无报错。
 - **这一项永远不允许留空**——哪怕是猜的也必须写一个条件并标注假设。
 
-### 3. 业务配置怎么维护
+### 4. 业务配置怎么维护
 
 - 群列表、管理员名单、模块负责人、分类规则这类配置，是**写在配置文件里**（改配置要改文件重启），还是**存 AI 表格由运营自己改、运行时自动同步**？
 - **决定**：后者需要额外生成一个 config-sync workflow + `ctx.setGlobalVar` 发布 + 下游 `${globalVar.*}` live-read（见 `config-in-aitable.md`）。这是一个**独立 workflow**，不是一个 step。
 - **缺省假设**：写在配置文件里（静态）。
 - **不澄清的后果**：选错方向后返工成本极高——从静态改成同步要新增 workflow、改所有消费点的引用、加配置表；反过来也一样。
 
-### 4. 留痕策略
+### 5. 留痕策略
 
 - 是否**每个事件**都要在表里留一行？还是只在需要人工介入 / 有结论时才建记录？
 - **决定**：`record_policy: eager` vs `on_demand` + 透传 step 返回 `tracker: false`（见 `../../aitable-workflow/reference/workflow-yml.md`）。
 - **缺省假设**：`eager`（全部留痕）。
 - **不澄清的后果**：高频事件源（活跃群、频繁变更的表）用 `eager` 会让表在几天内堆到几万行噪音，运营无法使用，且反过来让筛选性能问题雪上加霜。
 
-### 5. Agent 需要哪些资料
+### 6. Agent 需要哪些资料
 
 - 只在存在 `requiresAgent: true` 的步骤时适用。
 - Agent 干活时需要：业务规格文档 / 知识库文章 / 历史处理记录 / 都不需要？
@@ -103,28 +98,28 @@
 - **缺省假设**：产出 `AGENTS.md`（**无论如何都要产**，否则 Agent 没有输出契约），不配知识库和 memory。
 - **不澄清的后果**：没有 `AGENTS.md` 时 Agent 返回格式不稳定，下游解析随机失败；漏配 `kb_collections` 时知识库完全不注入且**不报错**，表现为「Agent 好像不知道这些知识」。
 
-### 6. 人工把关环节
+### 7. 人工把关环节
 
 - 哪些环节需要人工确认后才能继续？
 - **决定**：`step.auto: false` + `needs_human.reason` / `assignee_field`。
 - **缺省假设**：全自动，无人工环节。
 - **不澄清的后果**：该把关的没把关（自动发送了未审核内容），或不该把关的加了人工卡点（流程永远停在待确认）。
 
-### 7. 要记录哪些信息
+### 8. 要记录哪些信息
 
 - 这个流程要记录 / 沉淀哪些关键信息？
 - **决定**：`field_definitions`（见 `../../aitable-workflow/reference/field-types.md`）。
 - **缺省假设**：从 scene 里能识别的名词 + 系统骨架字段。
 - **不澄清的后果**：字段缺失导致 `input_mapping` / `output_mapping` 引用不存在的字段；字段冗余导致表格臃肿。**字段一旦被 setup 建出来，改名等于数据迁移。**
 
-### 8. 异常处理
+### 9. 异常处理
 
 - 出错、超时或卡住时怎么处理？通知谁？
 - **决定**：recipe 的降级分支、`status: "failed"` vs 降级为 `"success"` + 失败标记、SLA 配置、通知目标字段。
 - **缺省假设**：写入失败结果并返回 `status: "success"` 不阻断流程，`ctx.log` 记录原因。
 - **不澄清的后果**：失败即阻断整条流程，一条坏数据卡死所有后续记录。
 
-### 9. 修改范围
+### 10. 修改范围
 
 - 只在 brownfield（已有 workflow.yml）时适用。
 - 本次要改动哪些已有 workflow？是改现有的还是新增一个？
@@ -132,7 +127,7 @@
 - **缺省假设**：只改与需求描述直接相关的那一个 workflow，其余不动。
 - **不澄清的后果**：误改无关 workflow，或该改的没改。
 
-### 10. 其他约束
+### 11. 其他约束
 
 - 还有什么必须遵守的规则或要避免的做法？（SLA、VIP 优先、敏感词过滤、禁止自动发送…）
 - **缺省假设**：无额外约束。

package/skills/aitable-workflow-design/patterns/output-and-report.md

@@ -41,6 +41,6 @@
 
 规则：
 
-- **「需确认项」不能为空**，除非用户逐条回答过澄清表单里的每一项。你替用户做的每个决定都要在这里出现，并写清「改哪个文件的哪个字段」才能推翻它。
+- **「需确认项」不能为空**，除非用户逐条回答过你提出的每一个澄清问题。你替用户做的每个决定都要在这里出现，并写清「改哪个文件的哪个字段」才能推翻它。
 - 「还需你补齐」只列**用户必须自己动手**的（凭据、base_id、表格授权），不要把你能生成的东西推给用户。
 - 假设也要落在产物里：受影响的文件用注释写明「假设：…（需确认）」。**绝不静默猜测。**

package/skills/aitable-workflow-design/reference/clarify-channels.md

@@ -0,0 +1,47 @@
+# 澄清通道：先判定，再发问
+
+「该不该问」见 `../patterns/clarification-checklist.md`；本文件只回答「**这次该用哪种方式问**」。
+
+同一份方法论有两个消费方，发问机制完全不同。**用错通道的后果是用户根本看不到问题**：
+把 `<question-form>` 发给不解析它的宿主，用户只会收到一段裸 JSON。
+
+## 判定：我在哪个通道
+
+| 判据 | 通道 | 怎么问 |
+| --- | --- | --- |
+| 工作目录下有 `.aitable/skills/`，且本轮资料是从那里挂载给你的 | **内层**（`aitable-workflow design` 起的 agent，宿主会解析表单） | `<question-form>`，格式见 `question-form-protocol.md` |
+| 你是宿主里的 coding agent，直接读项目 `node_modules/aitable-workflow-core/skills/` 或交付包里的资料 | **外层**（普通对话，无表单解析器） | 散文式提问，见下 |
+
+拿不准就按**外层**处理：散文式提问在两个通道里都能被人读懂，裸 JSON 只在内层能用。
+
+## 外层：散文式提问的规矩
+
+对齐交付类 skill 的对话风格（同类范例：群答疑助手交付包的 `conversational-setup.md`）。
+
+- **一次只问一件事，问完停下等答复。** 不要一口气抛 6 个问题，用户会只答第一个。
+- **用户听得懂的话，不要念字段名。** 问「这份配置以后想让谁改、怎么改」，
+  不问「要不要 `globalVar`」；问「只处理哪些记录」，不问「`filter` 怎么写」。
+- **问句用粗体原句给出**，例如：「**这个流程是谁来触发的，什么时候开始跑？**」
+  自己不要临场改写成更"专业"的说法。
+- **选项穷不尽就别做成选择题。** 判断口径、话术、边界条件的答案本来就是一段话，
+  硬凑两个选项会让用户只能挑一个都不对的。
+- **答案落到哪里，写成「答案 → 动作」表自己对照，不要读给用户听。**
+- **用户拿不定主意时，直接给默认并说清后果**：「那我先按每条都留痕做，
+  群消息量大的话表会涨得快，之后想改我告诉你改哪里。」
+- **不猜、不编造标识**：Base ID / Table ID / 会话 ID / 群名只能从用户给的链接或字符串里读，
+  猜错会把资源建到错误的地方。
+- **有代价的动作先说清再做**：要用户去申请权限、建号、等审批的，
+  在动手之前一次说完，不要默认用户接受等待。
+
+顺序上先问业务流程（谁发起、经过哪几个环节、什么算做完），流程清楚了再问
+`clarification-checklist.md` 里那 10 个技术决策点中缺的那几项。
+
+## 两个通道都适用：没人能回答时
+
+内层非交互执行（`--yes` / `--skip-questions` / 服务端自动流程）与外层用户明确说
+「你自己定就行」，处理方式相同：按每项的「缺省假设」推进，并且
+
+- 在产物 YAML / recipe 里以注释写明「假设：…（需确认）」；
+- 在最终汇报的「需确认项」里逐条列出（见 `../patterns/output-and-report.md`）。
+
+**绝不静默猜测。** 假设可以有，隐藏假设不行。

package/skills/aitable-workflow-design/reference/question-form-protocol.md

@@ -1,6 +1,11 @@
 # `<question-form>` 发问协议
 
-澄清由你发起，答复经由 CLI（`@inquirer` 表单）或 Web（右栏卡片）回收，因此格式必须严格。**一轮只发一张表单，发完停止输出、等待答复。**
+> **仅内层通道适用。** 本协议依赖宿主解析 `<question-form>` 标签——只有
+> `aitable-workflow design` 起的 agent 满足（答复经 CLI `@inquirer` 表单或 Web 右栏卡片回收）。
+> 普通对话里的宿主不解析它，发出去就是一段裸 JSON，用户看不懂也答不了。
+> **动手前先按 `clarify-channels.md` 判定通道**；外层通道走散文式提问，不要用本协议。
+
+内层通道格式必须严格。**一轮只发一张表单，发完停止输出、等待答复。**
 
 判断「该不该问」见 `../patterns/clarification-checklist.md`；本文件只讲「怎么问」。