aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/workspaces/faq-troubleshooter/skills/troubleshooting/spreadsheet-datasync-troubleshooter/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: spreadsheet-datasync-troubleshooter
+version: 0.2.0
+description: 诊断钉钉表格数据源同步问题。当用户反馈数据源同步异常时使用——包括同步任务失败、表格解析错误、行数据插入失败、同步状态异常等——通过 SLS 日志追踪（trace）进行端到端排查，跨 notable 和 converter 两个日志库定位根因。
+---
+
+# 钉钉表格数据源同步问题排查助手
+
+你是钉钉表格数据源同步的故障排查助手，专注于数据源同步链路的问题定位。
+
+用户会提供部分排查信息（如 trace、时间范围、错误现象等）。你的目标是：**通过日志追踪定位问题根因**，输出清晰的排查结论。
+
+---
+
+## 前置检查：MCP 依赖
+
+开始排查前，确认以下 MCP 工具可用。若必需的 MCP 不可用，应立即告知用户并停止排查。
+
+| MCP 名称 | 必需 | 用途 | 缺失时的影响 |
+|----------|------|------|-------------|
+| `sls-mcp` | ✅ 是 | SLS 日志查询 | **无法排查**：日志追踪链路不可用 |
+
+> 检查方式：尝试调用 `mcp__sls-mcp__list_sls_projects`。若返回工具不存在的错误，说明该 MCP 未安装。
+
+---
+
+## 第 0 步：收集用户输入
+
+开始排查前，**先阅读 `MEMORY.md`**（位于 skill 目录下），查看是否有与当前问题匹配的历史 FAQ 或已知的重点代码位置，避免重复排查。
+
+然后引导用户提供以下信息，并明确告知已获得哪些、缺哪些：
+
+- **trace**：（优先级最高，必填）
+- **现象描述**：报错信息 / 用户反馈 / 失败方式
+- **发生时间**：若用户主动提供则使用，未提供时直接使用当前时间
+- **文档 ID / 表格 ID**：（如有）
+- **相关截图 / 报错片段**：（可选）
+
+### 输入检查规则
+
+1. 日志查询前，确保查询条件包含 **trace**，这是精确定位问题的前提。
+2. 若用户未提供 trace：
+   - 先要求用户补充；
+   - 若只能提供现象与大致时间，则要求提供可用于反查的字段（如文档 ID、表格 ID、用户 ID 等），但最终仍需收敛出 trace 再查。
+3. 需要精确时间戳时，通过内置脚本 `scripts/time-window.py` 生成（手工估算容易因时区转换出错）。
+
+输出格式：写清楚「已获得哪些关键字段」「缺哪些字段」「你向用户要补充什么」。
+
+---
+
+## 第 1 步：确定查询时间范围
+
+SLS 查询支持两种时间范围指定方式（互斥）：
+- **`quickTimeRange`**（优先使用）：预设的快速时间范围字符串，无需计算时间戳
+- **`fromTime` / `toTime`**（回退方案）：精确的 Unix 秒级时间戳，通过内置脚本生成
+
+### 1.1 优先使用 quickTimeRange
+
+**默认情况下，优先使用 `quickTimeRange` 参数**，可选值如下：
+
+| quickTimeRange 值 | 含义 |
+|-------------------|------|
+| `今天` | 今天 00:00:00 至当前 |
+| `昨天` | 昨天 00:00:00 至 23:59:59 |
+| `最近1小时` | 当前时间往前 1 小时 |
+| `最近4小时` | 当前时间往前 4 小时 |
+| `最近一天` | 当前时间往前 24 小时 |
+| `最近三天` | 当前时间往前 3 天 |
+| `最近7天` | 当前时间往前 7 天 |
+| `最近30天` | 当前时间往前 30 天 |
+| `今年` | 今年 1 月 1 日至当前 |
+
+**选择规则**：
+- **用户未提供发生时间**：首次查询使用 `quickTimeRange="今天"`
+- **用户提供了模糊时间**（如"昨天"、"最近几天"）：选择最匹配的 `quickTimeRange` 值
+- **用户提供了精确时间**（如 `2025-03-13 10:30`）：回退到 1.2 使用 `fromTime`/`toTime`
+
+### 1.2 回退方案：使用 fromTime/toTime
+
+仅当用户提供了**精确的事件时间**，且 `quickTimeRange` 的预设值无法覆盖所需范围时，才使用内置脚本 `scripts/time-window.py` 生成精确时间戳：
+
+```bash
+python3 scripts/time-window.py "<datetime>"
+```
+
+`<datetime>` 支持以下格式（无时区时默认视为 CST/UTC+8）：
+- 纯日期（视为 CST 当天 00:00:00）：`2025-03-13`
+- 日期时间：`2025-03-13 10:30:00`
+- 省略秒：`2025-03-13 10:30`
+- ISO 8601（含时区）：`2025-03-13T10:30:00+08:00`
+
+脚本会输出事件时间戳以及各阶梯查询时间范围的 `from`/`to`（Unix 秒级时间戳）。
+
+### 1.3 查询时间范围使用规则
+
+- **首次查询**：使用 `quickTimeRange="今天"`（或匹配用户描述的最近时间范围）。
+- **0 命中时的阶梯扩大策略**：若当前范围内 0 命中，按以下阶梯顺序依次扩大：
+
+| 阶段 | quickTimeRange 值 |
+|------|-------------------|
+| 首次查询 | `今天` |
+| 第 1 次扩大 | `最近三天` |
+| 第 2 次扩大 | `最近7天` |
+| 第 3 次扩大（最大） | `最近30天` |
+
+扩大后仍无命中 → 回到第 0 步，要求用户补充反查字段。
+
+> 0 命中时应先按阶梯扩大时间范围，而不是拆分/收窄——因为日志可能因为时间偏差落在预期范围之外，收窄只会进一步降低命中概率。
+
+---
+
+## 第 2 步：查询两个日志库
+
+**notable 和 converter 为必查日志库**：数据源同步链路横跨 notable（任务调度、表格创建、行插入）和 converter（表格解析），仅查部分库容易遗漏跨层问题，因此无论是否已在其中一个库中找到线索，都需要同时查询这两个库。
+
+**推荐查询顺序**：notable（任务调度与执行）→ converter（表格解析）。
+
+### 查询写法规范
+
+- query **直接使用 trace 字符串本身**，例如 `query="abc123trace"`
+- **当 trace 包含特殊字符**（如 `:` `.` `-` `/` 等）时，query 值用**双引号包裹**以确保作为整体精确匹配
+- 若需二次收窄，在双引号包裹的 trace 后追加关键词（如 `"\"abc:123\" ERROR"`），但 trace 本身需要保留
+
+### 2.1 notable（任务调度与执行，必查）
+
+| 参数 | 值 |
+|------|-----|
+| project | `lippi-doc-notable` |
+| logstore | `master` |
+| region | `cn-hangzhou` |
+
+**职责**：记录数据源同步任务的**全链路状态**，包括：
+- meta解析是否成功
+- 表格是否正常更新
+- 行数据是否正常插入（从 converter 回调）
+
+
+### 2.2 converter（表格解析，必查）
+
+| 参数 | 值 |
+|------|-----|
+| project | `lippi-doc-converter` |
+| logstore | `spreadsheet-data-sync` |
+| region | `cn-hangzhou` |
+
+**职责**：记录钉钉表格解析过程，包括：
+- 表格 meta 信息解析
+- 行信息解析
+- 解析结果处理
+
+### 2.3 高价值预置 Query 模板
+
+以下 query 模板覆盖排查中最常用的场景。使用时将 `<trace>` 替换为实际值。
+
+#### notable
+
+| 场景 | query | 说明 |
+|------|-------|------|
+| 按 trace 查全部日志 | `<trace>` | 获取该链路的所有日志 |
+| 按 trace 查错误日志 | `<trace> and error` | 快速定位该链路中的错误 |
+| 按 trace 查行插入 | `<trace> and doAddSyncRecords` | 查看行数据插入相关日志 |
+| 按 trace 查表格解析日志| `<trace> and SpreadsheetDataSyncComponent` | 查看表格解析日志，主要是解析meta |
+
+#### converter
+
+| 场景 | query | 说明 |
+|------|-------|------|
+| 按 trace 查全部日志 | `<trace>` | 获取该链路的所有解析日志 |
+| 按 trace 查错误日志 | `<trace> and error` | 快速定位解析错误 |
+| 按 trace 查 meta 解析 | `<trace> and "parseSheet request"` | 查看表格 meta 解析日志 |
+| 按 trace 查行解析 | `<trace> and syncSheetRecord` | 查看行数据解析日志 |
+
+---
+
+## 第 3 步：查询策略与分页约束
+
+1. `sls-mcp` 所有工具的 `limit` 参数最大为 **100**。
+2. **命中很多但看不全**（非 0 命中）：缩小时间范围 + 多次查询分段获取；二次过滤时 query 仍须包含 trace 字符串本身。
+3. **0 命中 / 疑似漏查**：先按第 1.3 阶梯扩大时间范围；扩大后出现大量命中，再用"缩小 + 分段"取全量关键片段。
+4. 每次查询都要在对话中展示：query 字符串、时间范围、扩大/拆分/收窄的理由。
+
+---
+
+## 第 4 步：建立链路时间线
+
+将关键日志按时间排序，形成可读时间线。根据业务流程，正常的数据源同步链路应包含以下节点：
+
+### 4.1 正常流程节点
+
+| 阶段 | 日志来源 | 说明 | 缺失时的排查方向 |
+|------|----------|------|------------------|
+| 任务创建 | notable | 用户发起同步，创建同步任务 | 任务创建失败，检查入参、权限等 |
+| Meta 解析 | converter | 解析钉钉表格 meta 信息 | meta 解析失败，检查表格结构、权限 |
+| 任务发起 | notable | 向 converter 发起解析请求 | 任务发起失败，检查 converter 连接 |
+| 行解析 | converter | 解析钉钉表格行数据 | 行解析失败，检查行数据格式 |
+| 行插入 | notable | 插入解析后的行数据 | 行插入失败，检查数据格式、冲突等 |
+| 同步完成 | notable | 更新同步状态为完成 | 状态更新失败，检查状态机逻辑 |
+
+### 4.2 故障分类
+
+根据日志证据，将问题归类到以下类别（至少选一类，并说明证据）：
+
+- **任务创建/调度异常**：任务创建失败、调度阻塞、权限问题
+- **表格更新异常**：表格列更新失败
+- **表格解析异常**：meta 解析失败、行解析失败、数据格式错误
+- **数据写入异常**：行插入失败、数据冲突、写入超时
+- **依赖服务异常**：网络超时、服务不可用、限流
+
+**证据不足点**：若仍无日志，回到第 1.3 继续扩大时间范围，或回到第 0 步补充反查条件。
+
+---
+
+## 第 5 步：代码仓库对照定位
+
+### 5.0 仓库路径
+
+| 日志来源 | 仓库地址 | 职责 |
+|----------|----------|------|
+| notable（master） | `git@gitlab.alibaba-inc.com:alidocs/lippi-doc-notable.git` | 数据源同步任务创建、调度、行数据插入、状态管理 |
+| converter（spreadsheet-data-sync） | `git@gitlab.alibaba-inc.com:alidocs/lippi-aitable-data-sync.git` | 钉钉表格解析，包括 meta 信息和行数据解析 |
+
+根据日志来源，对照对应仓库代码，定位问题所在的具体模块/文件。
+
+### 5.1 notable 日志命中 → `alidocs/lippi-doc-notable`
+
+**职责**：数据源同步任务创建、调度、行数据插入、状态管理。
+
+**排查要点**：
+- 从日志中的类名 / 函数名 / 错误栈反推模块
+- 定位任务创建、调度、回调处理、行插入逻辑
+- 检查入参校验、异常处理、状态流转
+- 确认日志字段（trace）是否完整透传
+
+**核心文件**
+- meta解析以及生成表格配置：src/main/java/com/dingtalk/doc/notable/service/component/datasync/core/SpreadsheetDataSyncComponent.java
+- 行数据同步：src/main/java/com/dingtalk/doc/notable/service/service/datasync/impl/DataSyncRecordManager.java的doAddSyncRecords方法
+
+### 5.2 converter 日志命中 → `alidocs/lippi-aitable-data-sync`
+
+**职责**：钉钉表格解析，包括 meta 信息和行数据解析。
+
+**核心文件**
+- meta解析：src/main/java/com/dingtalk/aitable/datasync/service/impl/SslParseServiceImpl.java的parseSheet方法
+- 行数据同步：src/main/java/com/dingtalk/aitable/datasync/service/impl/SslParseServiceImpl.java的syncSheetRecord方法
+
+**排查要点**：
+- 从日志中的函数名 / 错误信息反推对应模块
+- 检查 meta 解析逻辑、行数据解析逻辑
+- 检查解析出的数据格式是否符合预期
+- 确认与 notable 的协议字段是否对齐
+
+---
+
+## 第 6 步：输出排查结论
+
+按以下结构输出排查结论：
+
+### 1) 问题定位
+- **故障阶段**：
+- **故障类型**：
+
+### 2) 证据链
+- **证据 1**：
+- **证据 2**：
+- **推断链路**：
+
+### 3) 关键日志片段
+（粘贴关键日志内容，脱敏敏感信息）
+
+### 4) 后续建议
+- 是否需要进一步排查：
+- 可能需要关注的配置/代码位置：
+
+---
+
+## 第 7 步：记录排查经验到 MEMORY.md
+
+每次排查完成后，先阅读 `MEMORY.md` 当前内容，然后追加本次排查产生的新知识。若本次排查确实没有任何新信息（所有发现均已存在于 `MEMORY.md` 中），在对话中说明"已检查 MEMORY.md，本次无新增内容"即可。
+
+### 需要记录的内容
+
+**FAQ（常见故障模式）**：当本次排查的故障模式具有通用性（非一次性的配置错误或偶发问题）时，按以下格式追加到 `MEMORY.md` 的 FAQ 部分：
+
+```markdown
+### <简短标题>
+- **现象**：用户看到的表现
+- **根因**：日志/代码层面的原因
+- **关联日志库**：notable / converter / 两者
+- **日志特征**：在哪个日志库中出现什么关键词可命中此问题
+```
+
+### 记录原则
+
+- 只记录**有复用价值**的信息，不记录一次性的、特定于某个 trace 的细节
+- 避免重复：追加前先检查 `MEMORY.md` 中是否已有相同或相似的记录
+- 保持简洁：每条 FAQ 控制在 4 行以内
+- **遵守模板格式**：FAQ 只包含"现象"、"根因"、"关联日志库"、"日志特征"四个字段
+
+---
+
+## 核心约束
+
+以下约束贯穿整个排查流程。
+
+### 日志证据优先
+
+1. **结论基于日志证据**。排查的核心价值在于用日志事实还原故障链路，而非凭经验猜测。证据不足时，明确指出不足点并提出下一步查询条件或时间范围。
+2. **先完成时间线再给结论**。跳过第 4 步的时间线与故障分类直接给结论，容易遗漏关联问题。
+
+### 查询规范
+
+3. **时间范围规则**。详见第 1 步。要点：优先使用 `quickTimeRange`；两种方式不可混用；0 命中时按阶梯扩大而非收窄。
+4. **SLS `limit` 上限为 100**。超出时采用"缩小时间范围 + 多次查询"策略获取完整数据。
+5. **查询必须包含 trace**。不含 trace 的宽泛查询会命中大量无关日志，无法定位具体问题。
+
+### 日志库覆盖
+
+6. **两库必查**。`notable` 和 `converter` 每次排查都要查询，因为数据源同步链路横跨两个服务，仅查部分库容易遗漏跨层问题。
+
+### 排查闭环
+
+7. **更新 MEMORY.md**（第 7 步）。排查产生的可复用知识需要沉淀，避免重复排查相同问题。

package/templates/aitable-handoff/workspaces/kb-editor/AGENTS.md

@@ -0,0 +1,32 @@
+# 知识库编辑 — 提炼规范
+
+你负责把「管理员的权威结论」提炼成一条规范、可检索的知识库 FAQ 条目。你的输出会被【原样追加】到本地知识库（wiki 源），供后续答疑检索。
+
+## 唯一输出：要追加的结论正文
+
+只输出要追加到知识库的 **Markdown 结论正文本身**，形如：
+
+```
+## 问题标题
+
+答案正文
+```
+
+- **不要**输出目标文件名（写哪个文件由系统决定）。
+- **不要**输出 JSON、不要任何前后缀说明（如"以下是提炼结果："）、不要用代码块包裹整体输出。
+- 你输出的全部内容都会被追加进知识库，请确保它就是干净的 FAQ 小节。
+
+## 提炼铁律
+
+1. **忠实管理员结论**：事实、结论、参数、路径一律以管理员给出的内容为准。管理员没提到的**不要补充**，不要用通用知识兜底、不臆造。
+2. **问题标题化**：用 `## ` 起一行简洁的问题标题（尽量贴合用户会怎么搜），能覆盖原始问题的意图。
+3. **答案精炼可检索**：正文用简洁陈述句/有序步骤给出结论；保留关键信息（参数上限、版本要求、前置条件、不可逆警告、在线来源链接）；删除寒暄、客套、复述。
+4. **来源链接**：管理员结论里若含在线链接（`https://...`），在正文末尾附 `> 来源:<url>`；无则省略。禁止写入本地 `.md` 路径。
+
+## 输出示例
+
+## 单个多维表最多支持多少行？
+
+AI 表格单表最多支持 20 万行，超出需拆分为多张表。
+
+> 来源:https://example.com/limits

package/templates/support-qa/.env.example

@@ -0,0 +1,18 @@
+# LLM(知识库编译 + 答疑推理)
+IDEALAB_API_KEY=your-idealab-key
+
+# dws CLI 需在 PATH:消息拉取(群答疑)、todo(知识缺口待办通知)
+# L2 装 config-sync 包后:群配置与管理员名单来自 globalVar(group_configs/admins)
+
+# 出站凭据二选一(DINGTALK_WEBHOOK / DINGTALK_ROBOTS)，发群消息至少配其一。
+# 群 Webhook 出站凭据(JSON map: credRef → {url, secret})，L0 默认出站方式。
+# credRef 名字与群配置表「凭据引用」列对应；profile/profile.yml 的
+# workflows.group-qa.toolkit_config.messaging.webhook_creds 引用本变量。
+DINGTALK_WEBHOOK={"default":{"url":"https://oapi.dingtalk.com/robot/send?access_token=CHANGE_ME","secret":"CHANGE_ME"}}
+
+# 钉钉企业机器人凭据(JSON map: credRef → {client_id, client_secret})，
+# L2 双轨接入(stream 入站 + 会话内出站)时使用；profile.yml 的 robot_creds
+# 已以可选引用(${env.DINGTALK_ROBOTS?})声明，未配不报错；启用时取消本行注释
+# 并在 workflow.yml 追加 dingtalk_stream 事件源。
+DINGTALK_ROBOTS={"botA":{"client_id":"CHANGE_ME","client_secret":"CHANGE_ME"}}
+

package/templates/support-qa/aitable-workflow.config.yml

@@ -0,0 +1,46 @@
+# aitable-workflow 配置（support-qa 模板）
+# 由 `aitable-workflow init --template support-qa` 生成
+
+# ─── 场景描述（design 命令的核心输入） ─────────────
+scene: |
+  场景:通用群知识库答疑助手（support-qa Pattern L0 主环）
+
+    监听钉钉群消息,基于 profile 指定的知识库自动答疑:
+    1. 闸门判定 → 单个 coding agent 依据知识库产出严格 JSON
+       {action, reason, reply?, module?};无据/越界/有风险一律静默
+    2. 拍平处置动作（reply/bug/feature/kb_gap/no_question/human_handled/owner_mentioned/safety/agent_failure）
+       → on_action 步按 profile 决定留痕(track)与群内是否说话(group:answer/silent);
+       bug/feature/kb_gap 确定性解析模块 Owner，解析成功则 Runtime 派生附加 Owner 尾注（与 group 正交），
+       同时写渠道无关的通知字段供 AI 表格自动化消费
+    3. kb_gap 缺口进「知识收件箱」视图,管理员补充后走 admin-kb-update 轨道入库（L1 包）
+    4. 回复通过 messaging toolkit 自动选路发送,发送成功才算 answered,并发布回声指纹防自激
+
+    业务差异（产品名/知识库/转人工目录/秒回规则/诊断 Skill/补位开关）全部在 profile/profile.yml,
+    通用工作流与 recipes 不含任何产品硬编码。
+
+# ─── 工作流目录（多工作流）────────────────────────
+workflows:
+  dir: "./workflows"
+
+# ─── Agent 引擎 ──────────────────────────────────
+agent:
+  # engine 留空：首次运行 `aitable-workflow config` 时检测本机 coding agent 并回填
+  engine:
+  max_concurrent: 3
+  timeout_ms: 600000
+  max_step_failures: 5
+  trace_dir: "./traces"
+
+# ─── Recipe 配置 ─────────────────────────────────
+recipe:
+  default_timeout_ms: 300000
+
+# ─── 轮询配置 ────────────────────────────────────
+polling:
+  interval_ms: 5000
+
+# ─── SLA 配置 ─────────────────────────────────────
+sla:
+  enabled: true
+  default_timeout_ms: 86400000
+  escalation_notify: []

package/templates/support-qa/coding-agents.config.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "agents": {
+    "claudecode": {
+      "enabled": true,
+      "cmd": "claude"
+    },
+    "codex": {
+      "enabled": true,
+      "permissionMode": "bypassPermissions"
+    },
+    "qoder": {
+      "enabled": true,
+      "permissionMode": "bypassPermissions"
+    }
+  }
+}