aitable-workflow-core 0.1.23 → 0.1.24

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

@@ -9,7 +9,7 @@
 ## 1. 探测项目形态（不问用户，自己看）
 
 - 有 `profile/profile.yml` 吗？→ 有则**增量修改**它；**没有也默认走 `profile_v2`**，即新建一份收敛的 `profile/profile.yml`——这是新建项目的默认配置模式
-- 需要拆多个 workflow 吗？判据是**触发节律差异**，见 `../../aitable-workflow/reference/multi-workflow.md`
+- 需要拆多个 workflow 吗？判据是**触发节律差异**，见 `../../aitable-workflow/references/multi-workflow.md`
 - 需求里有没有引擎侧做不到、必须交给 DWS 自动化的部分（跨表落正式表、回消息带「点回那一行」的链接、公式计算）？
   有则**先**读 `recipe-vs-automation.md` 定分工再往下走 —— 它决定要建哪些表、哪些字段，定晚了字段要返工
 
@@ -22,8 +22,8 @@
 - 状态字段的 `options` 与 `tracker.states` 完全一致
 - 系统骨架字段（`标题`/`状态`/`当前步骤`/`处理人`/`事件日志`）**不要声明**
 - 字段声明写在每个 `workflow.yml` 的 `tracker.field_definitions` 里，**不是根级**（根级已废弃）
-- 同一段 `tracker` 里 `states` 与 `fields` 一起给齐，缺一个整段 tracker 会被静默忽略 → `../../aitable-workflow/reference/multi-workflow.md`
-- 详见 `../../aitable-workflow/reference/workflow-yml.md`
+- 同一段 `tracker` 里 `states` 与 `fields` 一起给齐，缺一个整段 tracker 会被静默忽略 → `../../aitable-workflow/references/multi-workflow.md`
+- 详见 `../../aitable-workflow/references/workflow-yml.md`
 
 ## 3. 设计单一决策字段
 
@@ -38,18 +38,18 @@
 ## 4. 规划 steps 与输出列
 
 - 每个 step 一件事，`id` 用 `[a-z0-9_]`
-- **输出列必须与展示列分开**：跨进程恢复时 StepEngine 会回退到「`output_mapping` 目标字段非空」启发式，被人工编辑的列绝不能做输出目标（见 `../../aitable-workflow/reference/workflow-yml.md` 的重入守卫章节）
+- **输出列必须与展示列分开**：跨进程恢复时 StepEngine 会回退到「`output_mapping` 目标字段非空」启发式，被人工编辑的列绝不能做输出目标（见 `../../aitable-workflow/references/workflow-yml.md` 的重入守卫章节）
 - 人工把关的 step 设 `auto: false` + `needs_human.reason`
-- 每个 step 都要决定：**这一步真的需要 LLM 吗？** 能穷举成映射表的就写确定性逻辑（见 `../../aitable-workflow/reference/recipe-contract.md` 的执行策略）
+- 每个 step 都要决定：**这一步真的需要 LLM 吗？** 能穷举成映射表的就写确定性逻辑（见 `../../aitable-workflow/references/recipe-contract.md` 的执行策略）
 - `edges` 闭链 `__start__` → … → `__end__`
 
 ## 5. 事件源与筛选条件
 
 - 只有确实是事件驱动（群消息 / @机器人 / 定时 / 表格变更）才生成 `event_sources`
 - 表单提交、手动新建 → **不生成**，tracker 自身轮询即可
-- **`aitable_record` 必须带 `filter`** —— 见 `../../aitable-workflow/reference/event-sources.md` 的「筛选条件」节，这是硬要求
+- **`aitable_record` 必须带 `filter`** —— 见 `../../aitable-workflow/references/event-sources.md` 的「筛选条件」节，这是硬要求
 - 按澄清结果配 `record_policy`（`eager` / `on_demand`）
-- 详见 `../../aitable-workflow/reference/event-sources.md`
+- 详见 `../../aitable-workflow/references/event-sources.md`
 
 ## 6. 写 recipes
 
@@ -57,7 +57,7 @@
 - recipe 里需要调用 dws 时，只能用 `DwsClient.runJson([...])`；不要写裸 `dws`、`child_process` 或 `toolkit.shell.runJson("dws", ...)`
 - `record_policy: on_demand` 时，所有可能不产生结论的分支返回 `tracker: false`
 - 需要 LLM 结构化输出的，加契约 + 修复 + 重试（`json-contract-and-repair.md`）
-- 详见 `../../aitable-workflow/reference/recipe-contract.md`
+- 详见 `../../aitable-workflow/references/recipe-contract.md`
 
 ## 7. 角色与 workspace
 
@@ -66,14 +66,14 @@
 - 角色写进 profile 的 `roles:` 段（persona 用 `{ file: prompts/<id>.md }`，相对 `profile/` 目录；或内联字符串）
 - **无论如何都要产出 `workspaces/<role.id>/AGENTS.md`**，里面必须有明确的输出契约
 - 需要知识库时配 `knowledge_scope.kb_collections` 并产出 `wiki/<name>/_index.md` 骨架
-- 详见 `../../aitable-workflow/reference/profile-and-roles.md` 与 `../../aitable-workflow/reference/workspace-context.md`
+- 详见 `../../aitable-workflow/references/profile-and-roles.md` 与 `../../aitable-workflow/references/workspace-context.md`
 
 ## 9. 环境变量声明
 
 - 每个 `${env.X}` 都在 `.env.example` 里留一条，`KEY=` 上方写注释描述
 - 可选凭据用 `${env.X?}`
 - **不要生成 `.env`**，不要在 `.env.example` 写真实凭据
-- 详见 `../../aitable-workflow/reference/runtime-refs.md`
+- 详见 `../../aitable-workflow/references/runtime-refs.md`
 
 
 ## 11. 交叉核对

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

@@ -13,7 +13,7 @@
 | `workspaces/<role-id>/AGENTS.md` | 每个角色 | 业务规格 + **输出契约**；复杂上下文放这里而不是塞进 prompt |
 | `.env.example` | 需要外部凭据时 | 只声明变量名与用途，**绝不**生成 `.env` |
 
-细节契约见 `../../aitable-workflow/SKILL.md` 的路由表；不可违反项见 `../../aitable-workflow/reference/invariants.md`。
+细节契约见 `../../aitable-workflow/SKILL.md` 的路由表；不可违反项见 `../../aitable-workflow/references/invariants.md`。
 
 ## 汇报三段
 
@@ -40,5 +40,5 @@
 规则：
 
 - **「需确认项」不能为空**，除非用户逐条回答过你提出的每一个澄清问题。你替用户做的每个决定都要在这里出现，并写清「改哪个文件的哪个字段」才能推翻它。
-- 「还需你补齐」只列**用户必须自己动手**的（凭据、base_id、表格授权），不要把你能生成的东西推给用户。**绝不要往 `config.yml` 写根级 `tracker`** → 规则见 `../../aitable-workflow/reference/multi-workflow.md`。
+- 「还需你补齐」只列**用户必须自己动手**的（凭据、base_id、表格授权），不要把你能生成的东西推给用户。**绝不要往 `config.yml` 写根级 `tracker`** → 规则见 `../../aitable-workflow/references/multi-workflow.md`。
 - 假设也要落在产物里：受影响的文件用注释写明「假设：…（需确认）」。**绝不静默猜测。**

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

@@ -1,217 +0,0 @@
-# 事件源（event_sources）
-
-事件源在 `workflow.yml` 的 `event_sources` 段声明，每条内联 `handler`（handler recipe 名）。配置键用 **snake_case**。
-
-**只有用户明确要求外部事件驱动入口时才生成 `event_sources`。** 表单提交、手动新建记录 → tracker 自身轮询即可。
-
-## 内置类型一览
-
-| type | 机制 | 用在哪 |
-| --- | --- | --- |
-| `dingtalk_group_message` | dws 逐群轮询 | 监听指定群的全部消息，不需要机器人 |
-| `dingtalk_user_message` | dws `list-all` 单次批量拉取 | 群多到逐群轮询扛不住时（200+ 群） |
-| `dingtalk_stream` | WebSocket 推送 | @机器人触发、要支持单聊 |
-| `dingtalk_event` | dws event 长连接推送 | 实时监听指定群全部消息（个人身份，无轮询延迟） |
-| `cron_scheduler` | 定时 | 日报、巡检、定时汇总 |
-| `aitable_record` | AI 表格记录轮询 | 监听表格记录新增/变更 |
-
-> `dingtalk_message` 是 `dingtalk_group_message` 的旧名，同一实现，已有模板里仍有效。
-
-四个消息类事件源产出**同构**的 `message_received` 事件——换入站方式只改 `type`，下游零改动。
-
-### 1. `dingtalk_group_message` — 钉钉群消息（dws 逐群轮询）
-
-不需要机器人。
-
-```yaml
-event_sources:
-  - name: "群消息监听"
-    type: dingtalk_group_message
-    handler: message_triage_handler
-    config:
-      conversation_ids:
-        - "cidXXXXXXXXXXXX=="
-        - "cidYYYYYYYYYYYY=="
-      aggregate_by_sender: true     # 默认 true
-      watch_senders: []             # 空=所有人
-      fetch_limit: 50
-```
-
-- **`conversation_ids`** 是字符串数组，多个会话**并发**拉取。
-- `aggregate_by_sender`（默认 true）：按发送者分组，每个发送者产出一个独立事件。
-- 事件源只产出原始 `message_received`，**不做「新对话 vs 追问」判断**——由 EventHandler 决策。
-- `conversation_ids` 可整值填运行时引用（如 `${globalVar.group_pull_list}`），见 `runtime-refs.md`。
-- 三档语义：缺省 → setup 报必填缺失；`[]` → 默认停用；非空 → 正常启用。
-
-#### 如何获取群 openConversationId
-
-用 dws 列出当前账号能看到的会话，按群标题过滤取 `openConversationId`：
-
-```bash
-dws chat list-all-conversations --format json | jq '.[] | select(.title == "目标群名") | .openConversationId'
-```
-
-- 标题必须完全匹配；不确定时先用 `dws chat list-all-conversations --format json` 看原始列表。
-- 取到的是 `cidXXXXXXXXXXXX==` 格式，整条填进 `conversation_ids`。
-
-### 2. `dingtalk_user_message` — 批量拉取（群很多时用）
-
-配置与 `dingtalk_group_message` 相同，差别在拉取机制：一次 `dws chat message list-all` 拉全部会话再本地过滤。群数 200+ 时用此类型（1~5 次分页 vs 200+ 次子进程调用）。
-
-代价：`conversation_ids` 写错不会报错，静默什么都收不到。
-
-### 3. `dingtalk_stream` — 企业内机器人（WebSocket 推送）
-
-**前提：必须先在钉钉开放平台创建企业内机器人**，拿到 `client_id` / `client_secret`。
-
-触发方式是**@机器人**（不 @ 不触发），同时**支持单聊**。
-
-```yaml
-  - name: "机器人监听"
-    type: dingtalk_stream
-    handler: message_triage_handler
-    config:
-      robot_creds: "${env.DINGTALK_ROBOTS?}"
-      robot_refs: "${globalVar.stream_robot_refs}"
-```
-
-#### 轮询 vs 推送怎么选
-
-| | `dingtalk_group_message` | `dingtalk_stream` | `dingtalk_event` |
-| --- | --- | --- | --- |
-| 是否需要机器人 | 不需要 | 需要 | 不需要（个人身份） |
-| 触发条件 | 会话内所有消息 | 必须 @机器人 | 会话内所有消息 |
-| 单聊 | 不支持 | 支持 | 不支持（kind 仅 group / all-group）|
-| 实时性 | 轮询间隔（秒级） | 实时 | 实时 |
-
-#### 设计期必须确认的通道约束
-
-1. **企业内机器人可能要等管理员审批。** 用户等不了时唯一替代是「轮询入站 + 自定义机器人出站」，触发方式从「@ 才答」变成「不 @ 也答」。开通流程见交付包 `references/bot-provisioning.md`。
-2. **外部群加不进企业内机器人**（报 `300001`），需允许不同群走不同通道。
-3. **独占长连接**：同一份凭据同时只允许一个进程连着，不要多实例并行。
-4. **出站 @人 取决于通道**：`session` 与 webhook 能 @人，机器人 API 不能。
-
-### 4. `dingtalk_event` — 个人身份事件长连接（dws event）
-
-以当前 dws 登录用户身份建立事件长连接，实时接收目标群的全部消息，无轮询延迟；部署机上需已登录 dws（`dws auth login`）。
-
-```yaml
-  - name: "群消息监听"
-    type: dingtalk_event
-    handler: message_triage_handler
-    config:
-      kind: all-group                                   # 缺省 group
-      conversation_ids: "${globalVar.group_pull_list}"   # 也可内联 ["cidXXX=="]
-```
-
-- **`conversation_ids`** 语义与其他消息源一致（内联数组 / 运行时引用 / 三档语义）。
-- 长连接无轮询：**不配 `poll_interval_ms`**。
-- 媒体图片与轮询源同构处理（`image_mode`，缺省 download）。
-
-**`kind` 选形态**（缺省 `group`；at-me / sender / all-direct 预留扩展）：
-
-| | `group` | `all-group` |
-| --- | --- | --- |
-| 进程模型 | 每群一个监听子进程 | 单进程监听账号全部群 |
-| `conversation_ids` | 订阅目标 | 客户端白名单（空名单 = 丢弃全部，**不是**放行全部）|
-| 30 群内存（实测）| 约 1.2 GB，O(N) | 约 71 MB，O(1) |
-| 群名单热更 | spawn/kill 子进程 | 只改内存名单 |
-| 故障域 | 单群隔离 | 全局（靠指数退避重启兜）|
-| 数据边界 | 仅目标群 | 该账号**全部群**消息流经本进程后被丢弃 |
-
-多群（≥ 5）优先 `all-group`，并建议用专用服务账号登录 dws（而非真人账号）；
-少群且需故障域隔离时用 `group`。实测数据与权衡见
-`docs/plans/2026-09-03-dingtalk-event-all-group.md`。
-
-### 5. `cron_scheduler` — 定时调度
-
-`daily_at` / `cron` / `interval_ms` **三者恰选其一**。
-
-```yaml
-  - name: "每日复盘"
-    type: cron_scheduler
-    handler: daily_review_handler
-    config:
-      daily_at: "09:00"
-      event_type: daily_review
-```
-
-### 6. `aitable_record` — AI 表格记录轮询
-
-```yaml
-  - name: "待沉淀记录监听"
-    type: aitable_record
-    handler: kb_persist_handler
-    config:
-      base_id: "bXXXXXXXX"
-      table_id: "tblXXXXXXXX"
-      watch_mode: both              # created（默认）| updated | both
-      filter:                       # ⚠️ 必填
-        field: "知识沉淀"
-        equals: "待沉淀"
-      poll_interval_ms: 300000
-```
-
-**⚠️ 必须带 `filter` 或 `filters`。** 无 filter 时每轮全表扫描，数据量涨到几万行后 dws 超时，链路**静默停摆且不报错**。完整规则见下方「筛选条件」节。
-
-- 监听**当前 workflow 的 tracker 表** → 不要生成 event_source，tracker 自身轮询即可。
-- 监听**另一个 workflow 的 tracker 表** → 用引用：`source_table: { mode: reference, ref: "workflow:<id>.tracker" }`。
-- `watch_mode`：`created` 只监听新增，`updated` 只监听变更，`both` 两者都。
-- `emit_existing` 默认 `false`：首轮静默建基线，要处理存量才设 `true`。
-
-## 筛选条件（`aitable_record` 必读）
-
-### 简写 DSL `filter`（首选）
-
-```yaml
-# 单条件
-filter:
-  field: "知识沉淀"
-  equals: "待沉淀"
-
-# equals 为数组 → 命中任一（OR）
-filter:
-  field: "状态"
-  equals: ["待处理", "处理中"]
-
-# 数组 → 多条件 AND
-filter:
-  - field: "状态"
-    equals: "待处理"
-  - field: "优先级"
-    equals: ["P0-紧急", "P1-高"]
-```
-
-### 原始 `filters`（仅简写表达不了时用）
-
-```yaml
-filters:
-  operator: and
-  operands:
-    - operator: any_of
-      operands: ["状态", ["待处理", "处理中"]]
-    - operator: neq
-      operands: ["负责人", ""]
-```
-
-两者同时存在时**以 `filters` 为准**。
-
-### 性能铁律
-
-框架自动把 `filter.field` 字段名翻译成 fieldId 走快路径。因此 `filter.field` **必须与 `field_definitions` 里声明的 `name` 完全一致**（含中文、空格、大小写），拼错不会报错，只会退回慢路径然后超时。
-
-### 自查
-
-产出 `aitable_record` 前确认：写了 filter、字段名真实存在、`watch_mode` 匹配业务时机、`emit_existing` 与存量处理结论一致。
-
-## Config Surface
-
-`config` 放驱动层配置（监听哪个群/表、触发时机），`handler_config` 放 handler 业务配置（昵称、复盘表引用）。详见 `config-surface.md`。
-
-## record_policy
-
-`eager`（默认）每事件建行，`on_demand` 配合 recipe 返回 `tracker: false` 实现透传。详见 `workflow-yml.md §record_policy`。
-
-## 跨 workflow 引用
-
-详见 `multi-workflow.md §跨-workflow-引用`。