aitable-workflow-core 0.1.23 → 0.1.24

package/skills/aitable-workflow/{reference → references}/runtime-refs.md

@@ -18,24 +18,6 @@ recipe:
     api_key: "${env.IDEALAB_API_KEY}"
 ```
 
-### 可选引用 `${env.NAME?}`
-
-带 `?` 后缀表示可选：
-
-- 整值引用 → 解析为 `undefined`，该字段视为**未设置**
-- 嵌入引用（`"prefix-${env.X?}"`）→ 解析为空字符串
-
-用于「两条凭据路径任选其一」的场景：
-
-```yaml
-toolkit_config:
-  messaging:
-    webhook: "${env.DINGTALK_WEBHOOK?}"    # 二者
-    robots: "${env.DINGTALK_ROBOTS?}"      # satisfy 其一即可
-```
-
-`validate` 对可选引用只给 suggestion，不报 error。
-
 ### JSON 自动解析
 
 环境变量值以 `{` 或 `[` 开头时会被 **`JSON.parse`**（解析失败直接抛错）。这是 JSON map 型凭据的实现方式：
@@ -69,18 +51,6 @@ DINGTALK_WEBHOOK=
 
 **绝不**把真实凭据写进 `.env.example`，也绝不生成 `.env`（那是用户自己填的）。
 
-### 事件源 config 里的整值引用会被保护
-
-`event_sources[].config` 中**整值**的运行时引用在配置加载插值时会被**遮蔽保留**，不会被提前求值——这样它们能保持 live-read 语义交给 `ConfigCenter`。但**嵌入式**引用（`"prefix-${env.X}"`）仍会被立即插值。
-
-所以事件源里要 live-read 就写整值形式：
-
-```yaml
-config:
-  conversation_ids: "${globalVar.group_pull_list}"   # ✓ 整值，保持 live-read
-  # conversation_ids: "list-${globalVar.x}"          # ✗ 嵌入式，会被提前求值
-```
-
 ## `${config.a.b}` — 项目配置
 
 调用时 live-read，dot-path 访问 `aitable-workflow.config.yml` 的内容。配置热更新后下次调用即生效。
@@ -116,13 +86,13 @@ const admins = ctx.getGlobalVar<string[]>("admins") ?? [];
 ### 配置里消费
 
 ```yaml
-event_sources:
-  - name: "群消息监听"
-    type: dingtalk_message
-    config:
-      conversation_ids: "${globalVar.group_pull_list}"
-    handler_config:
-      admins: "${globalVar.admins}"
+workflows:
+  <workflowId>:
+    event_sources:
+      群消息监听:
+        conversation_ids: "${globalVar.group_pull_list}"
+        handler_config:
+          admins: "${globalVar.admins}"
 ```
 
 事件源支持 `subscribe`，发布方写入时会触发消费方 reconcile，不必自己轮询。
@@ -139,11 +109,10 @@ event_sources:
 步骤配置里的 ref 必须自己解：直接把 `config.x` 当值用会拿到字面串。因为 step/handler 的 config schema
 普遍宽松，这类错误**不报错只静默降级**（名单恒为空、开关恒为假），比抛错难排得多。
 
-完整的「配置存 AI 表格 + 自动同步」落地模式见 `../../aitable-workflow-design/patterns/config-in-aitable.md`。
 
 ## 选择指南
 
-- 值是**凭据或部署差异** → `${env.X}`（加上 `?` 如果可选）
+- 值是**凭据或部署差异** → `${env.X}`
 - 值**已经在 config 里**，只是想复用 → `${config.a.b}`
 - 值由**另一个 workflow 在运行期决定** → `${globalVar.x}`
 - 值是**另一个 workflow 的静态声明**（tracker 表、事件源配置） → `{ ref: "workflow:..." }`，见 `multi-workflow.md`
@@ -154,4 +123,3 @@ event_sources:
 - [ ] 可选凭据用了 `${env.X?}`
 - [ ] 没有生成 `.env`，没有在 `.env.example` 写真实凭据
 - [ ] `globalVar` 的消费方能容忍值不存在（重启后为空）
-- [ ] 事件源里需要 live-read 的引用是整值形式，不是嵌入式

package/skills/aitable-workflow/{reference → references}/workflow-yml.md

@@ -2,6 +2,8 @@
 
 `workflow.yml` 是工作流的声明式定义。运行时由 `parseWorkflowTemplate` 解析，结构错误会 fail-fast。
 
+profile_v2 项目中，运行配置以 `profile/profile.yml` 为唯一事实源；`workflow.yml` 只放结构、tracker、字段、步骤编排与事件源身份
+
 ## 顶层结构
 
 ```yaml
@@ -18,7 +20,6 @@ tracker:                 # 必填，结构见下方
 steps: [...]             # 必填
 edges: [...]             # 必填
 event_sources: [...]     # 仅事件驱动场景，详见 event-sources.md
-toolkit_config: {...}    # 可选，本 workflow 级别的 toolkit 配置
 notification: {...}      # 可选
 ```
 
@@ -55,13 +56,15 @@ tracker:
 ### field_definitions 规则
 
 1. **所有业务字段都必须在 `field_definitions` 中显式声明**（包括 `text` 类型），写在 `tracker` 内（根级已废弃）。
-2. 含「日期」「时间」关键词的字段用 `date`。有限可选项用 `singleSelect` / `multipleSelect`。
-3. 表示成员/负责人且需要发 IM 时，声明为 `user` 人员字段。
-4. 状态字段的 `options` 必须与 `tracker.states` 的值**完全一致**。
-5. `creator` / `lastModifier` / `createdTime` / `lastModifiedTime` 是**系统只读字段**，不写入、不出现在 FormDesigner `visible_fields`。
-6. 系统骨架字段（`标题`/`状态`/`当前步骤`/`处理人`/`事件日志`）**无需声明**，setup 自动创建。
-7. 业务标题字段尽量复用主键语义，不要生成无业务含义的重复标题。
-8. `formula` / `lookup` 不在 `field_definitions` 能力范围内（只透传 `formatter` / `description`）。
+2. 完整合法类型见 [`field-types.md`](./field-types.md)；常见选择：
+   - 含「日期」「时间」关键词的字段用 `date`。
+   - 有限可选项用 `singleSelect` / `multipleSelect`。
+   - 表示成员/负责人且需要发 IM 时，声明为 `user` 人员字段。
+3. 状态字段的 `options` 必须与 `tracker.states` 的值**完全一致**。
+4. `creator` / `lastModifier` / `createdTime` / `lastModifiedTime` 是**系统只读字段**，不写入、不出现在 FormDesigner `visible_fields`。
+5. 系统骨架字段（`标题`/`状态`/`当前步骤`/`处理人`/`事件日志`）**无需声明**，setup 自动创建。
+6. 业务标题字段尽量复用主键语义，不要生成无业务含义的重复标题。
+7. `formula` / `lookup` 不在 `field_definitions` 能力范围内（只透传 `formatter` / `description`）。
 
 ### 单一决策字段模式
 
@@ -88,7 +91,6 @@ steps:
     output_mapping:           # key=recipe 返回 output 的键，value=写回的 AI 表格字段名
       category: "问题类型"
       priority: "紧急程度"
-    config: {}                # 可选，该 step 的 recipe 配置（详见 config-surface.md）
     engine: claude            # 可选，覆盖该 step 的 agent 引擎
 ```
 
@@ -228,7 +230,7 @@ tracker:
 - `type` 只能是 `Grid`、`FormDesigner`、`Kanban`、`Calendar`、`Gallery` 或 `Gantt`。
 - `Grid` 用 `field_order` 控制列及顺序；其他视图用 `visible_fields` 控制展示字段及顺序。
 - `Kanban` / `Gallery` 的 `group_by`、`Calendar` / `Gantt` 的 `date_field` 必须引用已有字段。
-- `filter` 只对 `Grid` 下发；数组条件之间为 AND。每项必须含 `field`，并在 `equals`（单值）或 `any_of`（非空多值）二选一；字段与选项值必须真实存在。
+- `filter` 只对 `Grid` 下发；数组条件之间为 AND。每项必须含 `field`，并在 `equals`（单个字符串）或 `any_of`（非空字符串数组）二选一；字段与选项值必须真实存在。多值筛选写 `any_of: ["待处理", "处理中"]`。
 - `for_each_step: needs_human | all` 只在确实需要按步骤展开视图时使用。
 - 用户明确需要填表入口时，追加 `input_form`（`FormDesigner`）；其 `visible_fields` 放用户输入字段和必要状态字段，不放「当前步骤」「事件日志」及 `creator`、`lastModifier`、`createdTime`、`lastModifiedTime` 等系统只读字段。
 - `field_order` / `visible_fields` / `group_by` / `date_field` / `filter[].field` 不得凭空创建字段。视图需要新列时，先在该 workflow 的 `tracker.field_definitions` 中声明。

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

@@ -8,7 +8,7 @@ description: 把业务需求变成 aitable-workflow 产物的工作方法。当
 本包回答「**怎么把需求变成产物**」。框架的字段名、语法与契约一律去 `../aitable-workflow/SKILL.md` 路由，**不要在本包里找契约，也不要凭记忆写**。
 
 <IMPORTANT>
-先路由，再动手。命中后**完整读取**目标文件，不要扫标题。
+先路由，再动手。
 
 不要预读全部文件；按下面的步骤，每步只读命中的 1-2 个。
 </IMPORTANT>
@@ -22,10 +22,12 @@ description: 把业务需求变成 aitable-workflow 产物的工作方法。当
 2. **判定项目形态**，选一条主线（两份清单不要混用）：
    - 全新项目（无 workflow.yml）→ `patterns/greenfield-checklist.md`
    - 修改已有项目（已有 workflow.yml / recipes）→ `patterns/brownfield-editing.md`
-3. **写代码前**读框架契约：从 `../aitable-workflow/SKILL.md` 的路由表按你实际要产出的部分加载 reference 文件；不可违反项见 `../aitable-workflow/reference/invariants.md`。
+3. **写代码前**读框架契约：从 `../aitable-workflow/SKILL.md` 的路由表按你实际要产出的部分加载 references 文件；不可违反项见 `../aitable-workflow/references/invariants.md`。
 4. **命中架构决策**时读对应模式：
    - 需要跨表落库、回消息带「点回那一行」的链接、或公式计算 → `patterns/recipe-vs-automation.md`（先定引擎/自动化分工，再写任何一侧）
    - 配置要让运营在 AI 表格里自助维护 → `patterns/config-in-aitable.md`（这是一个**独立 workflow**，不是一个 step）
+   - recipe 要读取用户已有 AI 表格、FAQ 表或外部业务参考表 → `patterns/external-aitable-read.md`
+   - 涉及钉钉企业内机器人、群机器人、Stream 监听或消息回复通道 → `patterns/dingtalk-bot-patterns.md`
    - 需要 LLM 输出可被稳定解析 → `patterns/json-contract-and-repair.md`
 5. **收尾** → `patterns/output-and-report.md`：核对产物清单，按三段格式汇报（已生成 / 需确认项 / 还需你补齐）。
 6. 回到 `patterns/clarification-checklist.md` 自查一遍。
@@ -39,9 +41,9 @@ description: 把业务需求变成 aitable-workflow 产物的工作方法。当
 | 改已有项目 | 已有 workflow.yml / recipes；「新增一个步骤」「加一个 workflow」 | `patterns/brownfield-editing.md` |
 | 定引擎与自动化的分工 | 跨表落库、消息要带「点回那一行」的链接、公式计算、`automations/*.json` | `patterns/recipe-vs-automation.md` |
 | 配置存 AI 表格由运营维护 | 「运营自己改」「不重启生效」「配置表」、globalVar 发布订阅 | `patterns/config-in-aitable.md` |
+| 读取外部 AI 表格 | FAQ 表、用户已有表、业务参考表、跨 Base 表、整表读取 | `patterns/external-aitable-read.md` |
+| 设计钉钉机器人通道 | 企业内机器人、自定义机器人、Stream、@机器人、群消息回复、`robot_creds` | `patterns/dingtalk-bot-patterns.md` |
 | 让 LLM 输出可被解析 | JSON 契约、解析失败、重试、降级 | `patterns/json-contract-and-repair.md` |
 | 收尾与汇报 | 文件写完了 | `patterns/output-and-report.md` |
 | 查框架语法与契约 | workflow.yml / recipe / 事件源 / 字段 / profile 的准确写法 | `../aitable-workflow/SKILL.md`（那里再路由） |
-| 查 toolkit 方法与配置 | ctx.toolkit.<name>.<method> | `../aitable-workflow/reference/generated/toolkits.md` |
-
-
+| 查 toolkit 方法与配置 | ctx.toolkit.<name>.<method> | `../aitable-workflow/references/generated/toolkits.md` |

package/skills/aitable-workflow-design/patterns/brownfield-editing.md

@@ -68,7 +68,7 @@ step id 是 StepEngine 的状态锚点，也是 profile 的锚点。重命名会
 
 - 新配置写进 `profile/profile.yml` 的 `workflows.<id>.{toolkit_config,steps,event_sources}`；角色写进 profile 的 `roles:` 段
 - 不要绕过 profile 直接改 `workflow.yml` 的配置（会被 profile 覆盖，改了没效果）
-详见 `../../aitable-workflow/reference/profile-and-roles.md`。
+详见 `../../aitable-workflow/references/profile-and-roles.md`。
 
 ## 常见改动的正确做法
 
@@ -91,7 +91,7 @@ step id 是 StepEngine 的状态锚点，也是 profile 的锚点。重命名会
 
 ### 给已有事件源加筛选条件
 
-如果发现现有 `aitable_record` 事件源没有 `filter`，**这是应该主动修的性能隐患**（见 `../../aitable-workflow/reference/event-sources.md`）。加 `filter` 时确认字段名与该 workflow 的 `field_definitions` 一致。
+如果发现现有 `aitable_record` 事件源没有 `filter`，**这是应该主动修的性能隐患**（见 `../../aitable-workflow/references/event-sources.md`）。加 `filter` 时确认字段名与该 workflow 的 `field_definitions` 一致。
 
 ### 改字段类型或名称
 

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

@@ -17,15 +17,13 @@
 | **需求过于笼统** | 「做个客服机器人」「帮我自动化一下招聘」 | 业务流程本身：谁发起、经过哪几个环节、每个环节谁做什么、什么算做完。**先把流程问出来**，再问下面的技术决策点 |
 | **需求过于单薄** | 「监听群消息，是 X 类问题就回复，其他不回」 | 缺的是：哪些群、群列表由谁维护、要不要 @ 才响应、机器人自己的消息是否处理、判断靠关键词还是模型、要不要留痕、判断不了时怎么办 |
 | **有多种合理拆法且选择会改变架构** | 「审核后发送」——审核是人工卡点还是模型判定？ | 直接把两种拆法摆出来让用户选 |
+| **涉及用户真实资源但没给定位信息** | 「我们已经有张表，要自动处理」「就在现有群里答」 | 先问用户给 Base/Table 链接或 ID、群链接/群名/openConversationId，或确认由哪张表/哪个群维护；不要默认去 AI 表格或钉钉会话列表里替用户找 |
 
 一两句话的需求天然属于第二种：能跑通不等于决策有依据，**这种情况应当提问**，而不是把下面 11 项默默替用户定了。
 
-**只有流程清楚了，下面的技术决策点才有意义。** 不要在还不知道业务流程长什么样时就去问 `record_policy`。
 
 ## 选择要问的问题
 
-本文件只定义**该问什么**。问题如何展示与收集答案由当前入口注入的协议决定；
-本文件不规定具体传递方式。
 
 选择问题时遵循：
 
@@ -35,15 +33,6 @@
 - 选项穷不尽的（判断口径、话术、边界条件）应允许用户自由描述，不要硬凑成封闭选项。
 - 具体每轮问几项、用什么字段格式、何时停下，严格遵循当前入口提供的发问协议。
 
-## 没人能回答时
-
-非交互执行（`--yes` / `--skip-questions` / 服务端自动流程），或用户明确说「你自己定」时，
-按下面每项的「缺省假设」推进，但**必须**：
-
-- 在产物 YAML / recipe 里以注释写明「假设：…（需确认）」
-- 在最终汇报里单列「需确认项」清单
-
-**绝不静默猜测。** 假设可以有，隐藏假设不行。
 
 ## 值得问的决策点
 
@@ -52,36 +41,40 @@
 ### 1. 触发方式
 
 - 这个流程被什么触发？群消息 / 群内@机器人（支持单聊）/ 定时 / AI 表格记录新增或变更 / 表单提交 / 手动新建？
-- **决定**：是否生成 `event_sources`，以及用哪种 `type`（见 `../../aitable-workflow/reference/event-sources.md`）。
+- **决定**：是否生成 `event_sources`，以及用哪种 `type`（见 `../../aitable-workflow/references/event-sources.md`）。
 - **缺省假设**：表单提交或手动新建 → **不生成** `event_sources`，靠 tracker 自身轮询。
 - **不澄清的后果**：给表单场景生成了事件源 → 多一套永不触发的死配置；给群消息场景漏了事件源 → 流程根本不会启动。
 
 触发或通知涉及钉钉机器人时，还要在写 `workflow.yml` 前确认：
 
+先读 `patterns/dingtalk-bot-patterns.md`，按那里的通道模型落配置。
 - 企业里是否已有可复用的机器人？有则复用，不默认新建。
 - 需要新建且要求「@机器人响应」时，用户是否接受公开发布及可能的管理员审批等待？
   不接受时改用群消息轮询 / 自定义机器人，并明确「无法判断是否被 @」等行为差异。
 - 是否包含不归属当前企业的外部群？有则不能假设所有群共用一种通道。
-
-这些答案会改变 `event_sources`、凭据配置和群路由结构，不能留到 setup 时才决定，也不能静默假设用户接受审批等待。
+- 要监听或加机器人的目标群是哪几个？**群属于用户的真实业务资源，先问用户提供群链接、群名或
+  openConversationId，或者确认群列表由 AI 表格配置表维护。不要默认枚举当前账号可见会话并自行匹配。**
+- 使用 Stream 机器人时，默认在有效 @ 消息进入处理后贴处理中的表情反馈；用户明确不要时再移除。
 
 ### 2. 数据放新表还是已有的表
 
-- **这一项由 setup 阶段问用户，设计期不用主动问。** 建资源发生在 setup，问法与两个方向的
-  处理都在交付包 skill 的 `references/base-and-table.md`。
-- **设计期该做的**：`tracker.base_id` 留空、根级 `base_name` 给一个业务化名字
-  （缺省会回落成项目目录名）。留空是正确的默认值，不是待办。
-- **唯一需要设计期介入的情形**：用户在澄清时主动说「就写进我那张已有的表」。
-  这时 `field_definitions` 必须**照那张表现有的列写** —— 凭空发明字段名不会报错，
-  只会往用户的真实业务表里静默加列，而字段建出来之后改名等于数据迁移。
-  此时本项连带绑死第 8 项。
-- ID 一律由用户给，**不要猜** —— 猜出来的 ID 轻则指向不存在的资源，重则指向别人的表。
+- 用户是否已经表达了「我们有现成的 AI 表格 / 就写进那张表 / 从现有表触发」？
+- **决定**：第二步产物是否只声明新表骨架，还是必须按已有 Base/Table 的字段现实来设计。
+- **默认路径**：用户没有提到已有资源时，`tracker.base_id` 留空、根级 `base_name` 给一个业务化名字
+  （缺省会回落成项目目录名）。留空是正确的默认值，不是待办；setup 会再问用户新建还是复用。
+- **用户提到已有表时必须设计期澄清**：先问用户提供 Base/Table 链接或 ID，并确认是「在已有 Base
+  里新建一张流程表」还是「直接写进某张已有 Table」。不要默认去 AI 表格列表里替用户找。
+- 用户明确要写进某张已有 Table 时，`field_definitions` 必须**照那张表现有的列写** —— 凭空发明字段名不会报错，
+  只会往用户的真实业务表里静默加列，而字段建出来之后改名等于数据迁移。此时本项连带绑死第 8 项。
+- ID 一律由用户给，**不要猜、不要默认搜索** —— 猜出来的 ID 轻则指向不存在的资源，重则指向别人的表。
+  只有用户明确说「你帮我找一下」时，才允许用当前账号可见列表辅助定位；找到后也必须把名称/链接/ID
+  回给用户确认，再写入配置。
 
 ### 3. AI 表格数据源的筛选条件 ⚠️ 最高优先级
 
 - 只在触发方式含「AI 表格记录新增或变更」时适用。
 - **只处理满足什么条件的记录？**（例：状态 = 待处理；知识沉淀 = 待沉淀）
-- **决定**：`aitable_record` 的 `filter` / `filters`（见 `../../aitable-workflow/reference/event-sources.md`）。
+- **决定**：`aitable_record` 的 `filter` / `filters`（见 `../../aitable-workflow/references/event-sources.md`）。
 - **缺省假设**：用状态字段 = `tracker.states.initial`。
 - **不澄清的后果**：**这是已发生过的线上故障。** 无筛选条件时每轮全表分页扫描，几百行时正常，涨到几万行后 dws 查询直接超时，链路静默停摆且无报错。
 - **这一项永远不允许留空**——哪怕是猜的也必须写一个条件并标注假设。
@@ -96,7 +89,7 @@
 ### 5. 留痕策略
 
 - 是否**每个事件**都要在表里留一行？还是只在需要人工介入 / 有结论时才建记录？
-- **决定**：`record_policy: eager` vs `on_demand` + 透传 step 返回 `tracker: false`（见 `../../aitable-workflow/reference/workflow-yml.md`）。
+- **决定**：`record_policy: eager` vs `on_demand` + 透传 step 返回 `tracker: false`（见 `../../aitable-workflow/references/workflow-yml.md`）。
 - **缺省假设**：`eager`（全部留痕）。
 - **不澄清的后果**：高频事件源（活跃群、频繁变更的表）用 `eager` 会让表在几天内堆到几万行噪音，运营无法使用，且反过来让筛选性能问题雪上加霜。
 
@@ -104,7 +97,7 @@
 
 - 只在存在 `requiresAgent: true` 的步骤时适用。
 - Agent 干活时需要：业务规格文档 / 知识库文章 / 历史处理记录 / 都不需要？
-- **决定**：`workspaces/<role.id>/AGENTS.md`、角色的 `knowledge_scope.kb_collections` + `wiki/` 骨架、memory toolkit（见 `../../aitable-workflow/reference/workspace-context.md`）。
+- **决定**：`workspaces/<role.id>/AGENTS.md`、角色的 `knowledge_scope.kb_collections` + `wiki/` 骨架、memory toolkit（见 `../../aitable-workflow/references/workspace-context.md`）。
 - **缺省假设**：产出 `AGENTS.md`（**无论如何都要产**，否则 Agent 没有输出契约），不配知识库和 memory。
 - **不澄清的后果**：没有 `AGENTS.md` 时 Agent 返回格式不稳定，下游解析随机失败；漏配 `kb_collections` 时知识库完全不注入且**不报错**，表现为「Agent 好像不知道这些知识」。
 
@@ -118,7 +111,7 @@
 ### 8. 要记录哪些信息
 
 - 这个流程要记录 / 沉淀哪些关键信息？
-- **决定**：`field_definitions`（见 `../../aitable-workflow/reference/workflow-yml.md`）。
+- **决定**：`field_definitions`（见 `../../aitable-workflow/references/workflow-yml.md`）。
 - **缺省假设**：从 scene 里能识别的名词 + 系统骨架字段。
 - **不澄清的后果**：字段缺失导致 `input_mapping` / `output_mapping` 引用不存在的字段；字段冗余导致表格臃肿。**字段一旦被 setup 建出来，改名等于数据迁移。**
 

package/skills/aitable-workflow-design/patterns/config-in-aitable.md

@@ -12,7 +12,7 @@
 | 排查难度 | 低（配置就在代码里） | 中（要看表里的值 + globalVar 当前状态） |
 | 适合 | 配置基本不变、只有开发会改 | 名单/规则/开关这类运营高频调整的配置 |
 
-**默认选静态。** 只有用户明确表达「运营要自己改」「不想每次都找开发」时才上同步方案。
+**默认选静态。**。
 
 ## 架构
 
@@ -32,7 +32,7 @@ globalVar（进程内 KV 总线）
 
 **tracker 和「配置表」是两个不同的概念，不要混用。** tracker 是 config-sync workflow 自己的**留痕表**——每行是一次同步执行的结果记录（同步了多少条、有没有报错），随这个 workflow 的状态机流转；配置表是运营维护的数据源表，本质是外部数据，跟状态机无关，两者不是同一张表。
 
-配置表的读取**不走** `ctx.toolkit.table.queryRows()`（那个 API 只能批量读「当前 workflow 自己的 tracker」，见 `../../aitable-workflow/reference/generated/core-api.md` 的 `TableToolkit`）。config-sync 通常读取任意一张（或多张）配置表，走 **dws CLI**（`aitable-workflow-core` 导出的 `DwsClient`）整表查询，与该表是不是某个 workflow 的 tracker 无关：
+配置表的读取**不走** `ctx.toolkit.table.queryRows()`（那个 API 只能批量读「当前 workflow 自己的 tracker」，见 `../../aitable-workflow/references/generated/core-api.md` 的 `TableToolkit`）。config-sync 通常读取任意一张（或多张）配置表，走 **dws CLI**（`aitable-workflow-core` 导出的 `DwsClient`）整表查询，与该表是不是某个 workflow 的 tracker 无关：
 
 ```typescript
 import { DwsClient } from "aitable-workflow-core";
@@ -62,7 +62,7 @@ meta:
 tracker:
   base_id: "bXXXXXXXX"   # 留痕表：记录每轮同步执行的结果，不是配置表本身
   table_id: ""
-  states:                # 必填（active ≥2 且显式 review），见 ../../aitable-workflow/reference/multi-workflow.md
+  states:                # 必填（active ≥2 且显式 review），见 ../../aitable-workflow/references/multi-workflow.md
     initial: "待处理"
     active: [ "处理中", "审核中" ]
     review: "审核中"
@@ -162,7 +162,7 @@ export default recipe;
 
 ## 4. 消费方
 
-在业务 workflow 的配置里用**整值** `${globalVar.*}` 引用（整值形式才保持 live-read，见 `../../aitable-workflow/reference/runtime-refs.md`）：
+在业务 workflow 的配置里用**整值** `${globalVar.*}` 引用：
 
 ```yaml
 # workflows/<consumer>/workflow.yml
@@ -225,7 +225,6 @@ config:
 - [ ] config-sync 的 `record_policy: on_demand` + recipe 返回 `tracker: false`（同步本身不需要留痕）
 - [ ] config-sync 的 `tracker` 是同步执行的留痕表，**不是**配置表本身
 - [ ] 配置表读取走 dws CLI（`DwsClient`），不是 `ctx.toolkit.table.queryRows()`
-- [ ] 消费方用的是**整值** `${globalVar.x}`，不是嵌入式
 - [ ] 消费方能容忍 globalVar 为空（重启后的窗口期）
 - [ ] 读到空配置有防抖（连续 N 轮才清空）
 - [ ] globalVar 的 key 全局唯一且有语义

package/skills/aitable-workflow-design/patterns/dingtalk-bot-patterns.md

@@ -0,0 +1,129 @@
+# 钉钉机器人设计模式
+
+本文件只讲设计期决策与产物落法；创建机器人、发布版本、加群、审批等操作步骤归 setup 阶段的 `aitable-workflow-setup/references/bot-provisioning.md`。
+
+## 先判定通道
+
+1. 用户希望「@ 机器人后才答」或需要单聊提问：优先用企业内机器人 Stream。
+2. 用户希望监听群里所有消息，或企业内机器人审批来不及：用 `dingtalk_group_message` / `dingtalk_user_message` 轮询入站。
+3. 群很多时优先 `dingtalk_user_message`；群少且需要简单明确时可用 `dingtalk_group_message`。
+4. 自定义群机器人 Webhook 只适合作出站降级，不作为入站监听来源。
+
+## 设计期必须问清
+
+- 是否已经有可复用的企业内机器人；没有时是否接受管理员审批与发布等待。
+- 要监听几个机器人；每个机器人服务哪些群或单聊入口。
+- 是否必须 @ 提问者；`sessionWebhook` 能 @，robot API 主动推送不能真 @，只能正文前置称呼。
+- 是否存在外部群或跨组织群；群归属会影响企业内机器人是否能被加入和触发。
+- 是否允许用户在 AI 表格里自助维护机器人名单和凭据；允许时用独立 config-sync workflow 发布配置。
+
+## 推荐配置
+
+动态多机器人只使用一个字段：`robot_creds`。它不是名单，而是凭据映射；配置多少个 credRef，就监听多少个机器人。
+
+```yaml
+toolkit_config:
+  messaging:
+    robot_creds: "${globalVar.robot_creds}"
+
+event_sources:
+  企业机器人监听:
+    type: dingtalk_stream
+    robot_creds: "${globalVar.robot_creds}"
+    conversation_types: ["group"]
+```
+
+`robot_creds` 的值形如：
+
+```json
+{
+  "support-bot": {
+    "client_id": "dingxxxx",
+    "client_secret": "******"
+  }
+}
+```
+
+`support-bot` 是 credRef。Stream 入站事件会携带实际接收消息的 credRef；回复时同一个 credRef 会用于选择正确机器人身份，避免多机器人串号。
+
+## 配置来源选择
+
+- 单一机器人、凭据不需要运营改：可用 `.env`，例如 `robot_creds: "${env.DINGTALK_ROBOTS}"`。
+- 多机器人、运营要自己加减：用 AI 表格配置表 + config-sync，把启用的机器人凭据发布成 `globalVar.robot_creds`。
+- 首轮 config-sync 前 `globalVar.robot_creds` 为空是正常状态；产物注释里要说明这会导致 Stream 暂不建连或机器人身份出站暂不可用。
+
+## Recipe 发消息
+
+业务 recipe 优先只用：
+
+```ts
+ctx.toolkit.messaging.replyToConversation(conversationId, content, options)
+```
+
+不要在业务 recipe 里直接拼 webhook、直接读取 appKey/appSecret，或手写钉钉发送逻辑。需要卡片时用 `replyToConversationWithButtons` 或已存在的 messaging 方法。
+
+## conversationId / senderId 怎么传到 replyToConversation
+
+`replyToConversation(conversationId, answer, options)` 的两个定位参数**不从 handler 直接透传**，而是走 tracker 表字段 + `input_mapping`：
+
+1. **Handler** 把 `conversationId` / `senderStaffId` / `senderName` 写进 tracker 表字段（`output_mapping` 写到 `create_record` 的 `fields` 里）。
+2. **`workflow.yml`** 在 `tracker.field_definitions` 声明这些字段，并在下游回复 step 的 `input_mapping` 里把它们映射成 recipe 入参名（如 `conversationId` / `senderId` / `senderName`）。
+3. **回复 step** 从 `ctx.input.conversationId` 读，传给 `replyToConversation`；`mentionSender` 用 `ctx.input.senderId` 或 `false`。
+
+```yaml
+# workflow.yml
+tracker:
+  field_definitions:
+    - name: 群ID
+    - name: 提问人ID
+    - name: 提问人
+
+steps:
+  - id: reply
+    recipe: reply-to-group
+    input_mapping:
+      conversationId: "群ID"
+      senderId:       "提问人ID"
+      senderName:     "提问人"
+```
+
+```typescript
+// 回复 step
+const conversationId = String(ctx.input.conversationId ?? "");
+const senderId       = String(ctx.input.senderId ?? "");
+const res = await ctx.toolkit.messaging.replyToConversation(conversationId, answer, {
+  mentionSender: senderId || false,
+});
+```
+
+handler 写、下游读，**不要**试图绕开 tracker 表把 ID 放在内存里传 —— WorkItem 是跨进程的瞬态载体，只有 tracker 表字段稳。
+
+## Typing 表情反馈（"正在输入…"）
+
+Stream 机器人默认加处理中的表情反馈：handler 收到有效 @ 消息并决定进入处理流程时，调用 `toolkit.messaging.beginDingTalkProcessingFeedback(ctx)` 给原消息加一个随机表情反馈。用户明确不要即时反馈时才去掉。
+
+参数需要 `openMsgId` / `conversationId` / `robotCode` / `credRef` 四项，按 `type: "dingtalk_stream_message"` 组成一个 EventContext 形状的对象（这些字段来自 `event.payload`，如 `payload.dingtalk.openMsgId`）：
+
+```typescript
+import { resolveDingTalkStreamMessageEventContext } from "aitable-workflow-core";
+
+const dingtalk = (event.payload.dingtalk ?? {}) as Record<string, unknown>;
+const streamCtx = resolveDingTalkStreamMessageEventContext({
+  type: "dingtalk_stream_message",
+  openMsgId: String(dingtalk.openMsgId ?? ""),
+  conversationId,
+  robotCode: String(dingtalk.robotCode ?? ""),
+  credRef: String(dingtalk.credRef ?? ""),
+});
+if (streamCtx) {
+  ctx.toolkit.messaging?.beginDingTalkProcessingFeedback?.(streamCtx);
+}
+```
+
+只在 stream 通道有意义；轮询入站（`dingtalk_group_message` / `dingtalk_user_message`）和 webhook 通道不调。空消息、机器人自身消息、被规则过滤的消息不要贴反馈。
+
+## 避免重复文档
+
+- 本文件讲「怎么设计」。
+- `aitable-workflow/references/event-sources.md` 讲事件源字段与框架能力。
+- `aitable-workflow-setup/references/bot-provisioning.md` 讲建号、发布、加群、审批。

package/skills/aitable-workflow-design/patterns/external-aitable-read.md

@@ -0,0 +1,132 @@
+# 读取外部 AI 表格最佳实践
+
+当 recipe 需要读取用户已有表、FAQ 表、配置表或业务参考表时，用这个模式。它适用于“表不是当前 workflow tracker，但运行时要拿它的数据做判断”的场景。
+
+## 什么时候用
+
+- FAQ 自动答疑：读取已有 FAQ 表，按问题/相似问/答案做匹配。
+- 业务参考表：读取产品、客户、负责人、规则等静态或半静态数据。
+- 配置表同步：读取运营维护的配置表，再发布到 `globalVar`。
+
+如果只读当前 workflow tracker 表，用 `ctx.toolkit.table.queryRows()`。如果按 recordId 读取指定表的一行，用 `ctx.toolkit.table.readRecordIn()`。如果要分页拉取指定外部表的多行，走 `DwsClient`。
+
+## 配置声明
+
+外部表引用用 `tableRefConfigSchema`，不要手写 `{ baseId, tableId }`。
+
+```typescript
+import { tableRefConfigSchema } from "aitable-workflow-core";
+import { z } from "zod";
+
+config: z.object({
+  faq_table: tableRefConfigSchema({
+    label: "FAQ 表",
+    description: "用户已有的 FAQ 数据表",
+    ownership: "external",
+    access: "read",
+  }).optional(),
+})
+```
+
+运行期必须检查未配置态，给出可读错误或降级结果。
+
+```typescript
+const table = ctx.config.faq_table as { baseId?: string; tableId?: string } | undefined;
+if (!table?.baseId || !table.tableId) {
+  return {
+    status: "success",
+    output: { action: "manual", reply: "FAQ 表还未配置，稍等人工客服来处理" },
+    logs: ["FAQ 表未配置，已降级转人工"],
+  };
+}
+```
+
+## 标准读取流程
+
+1. 用 `DwsClient` 跑 `aitable field get`，建立字段名到字段 ID 的映射。
+2. 用 `aitable record query --all` 拉记录。
+3. 从 `record.cells` 取值；cells 通常按字段 ID 键控，不要假设字段名直接可用。
+4. 把单元格值归一成业务对象，再交给匹配或生成逻辑。
+
+```typescript
+import { DwsClient, dwsPayload, findArrayPayload } from "aitable-workflow-core";
+
+const dws = new DwsClient({ bin: "dws", timeoutMs: 30_000 });
+
+async function readExternalRows(target: { baseId: string; tableId: string }): Promise<Record<string, unknown>[]> {
+  const fieldsRaw = await dws.runJson([
+    "aitable", "field", "get",
+    "--base-id", target.baseId,
+    "--table-id", target.tableId,
+  ]);
+
+  const fieldNameById = new Map<string, string>();
+  for (const field of findArrayPayload(fieldsRaw)) {
+    const item = dwsPayload(field);
+    if (!item || typeof item !== "object") continue;
+    const record = item as Record<string, unknown>;
+    const id = typeof record.fieldId === "string" ? record.fieldId : "";
+    const name = typeof record.fieldName === "string" ? record.fieldName : "";
+    if (id && name) fieldNameById.set(id, name);
+  }
+
+  const recordsRaw = await dws.runJson([
+    "aitable", "record", "query",
+    "--base-id", target.baseId,
+    "--table-id", target.tableId,
+    "--all",
+  ]);
+
+  return findArrayPayload(recordsRaw).map((row) => {
+    const item = dwsPayload(row);
+    const cells = item && typeof item === "object"
+      ? ((item as Record<string, unknown>).cells ?? (item as Record<string, unknown>).fields ?? {})
+      : {};
+    if (!cells || typeof cells !== "object") return {};
+    return Object.fromEntries(
+      Object.entries(cells as Record<string, unknown>).map(([fieldId, value]) => [
+        fieldNameById.get(fieldId) ?? fieldId,
+        normalizeCellValue(value),
+      ]),
+    );
+  });
+}
+```
+
+## 单元格归一
+
+真实表里常见 cellValue 不止字符串。recipe 里先归一，再写业务判断。
+
+```typescript
+function normalizeCellValue(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalizeCellValue).filter(Boolean).join(" ");
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    if (typeof record.markdown === "string") return record.markdown;
+    if (typeof record.text === "string") return record.text;
+    if (Array.isArray(record.text)) return record.text.map(normalizeCellValue).filter(Boolean).join(" ");
+    if (typeof record.value === "string") return record.value;
+  }
+  return "";
+}
+```
+
+## FAQ 表建议
+
+- 先探测字段清单，再把实际采用的字段名写进 recipe config 或代码常量。
+- FAQ 行数不大时可以全表读取后本地匹配；数据持续增长时，应改成离线索引或配置同步 workflow，不要每条消息都全量拉表。
+- 答案里含图片或附件时，保留 markdown/richText 内容；回复通道不支持的富内容要降级为文本说明。
+
+## 自查
+
+- [ ] 表引用用 `tableRefConfigSchema({ access: "read" })`。
+- [ ] 未配置 `baseId/tableId` 时有降级，不抛给用户看不懂的异常。
+- [ ] 先 `field get` 建字段映射，再读 `record.cells`。
+- [ ] 解析函数覆盖 string、数组、richText/markdown、空值。
+- [ ] 大表读取有缓存、同步表或索引方案，不在高频消息里无界全表扫描。