aitable-workflow-cli 0.1.15 → 0.1.16-beta.1786022310508

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

@@ -1,322 +0,0 @@
----
-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

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

package/templates/support-qa/lib/assemble-cli.ts

@@ -1,30 +0,0 @@
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
-import { assembleProfile } from "./assemble.js";
-
-/**
- * profile 装配 CLI（模板内工具，tsx 运行）
- *
- *   npm run assemble  → 校验 + 写盘（persona.md / owner-map.json / role kb_collections）
- *   npm run check     → 仅严格校验（preflight，不写盘）；有 error 退出码 1
- */
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const CONFIG_DIR = path.resolve(HERE, "..");
-const checkOnly = process.argv.includes("--check");
-
-const { issues, wrote } = assembleProfile(CONFIG_DIR, { dryRun: checkOnly });
-
-for (const i of issues) {
-  console.log(`${i.level === "error" ? "✗" : "⚠"} [${i.level}] ${i.message}`);
-}
-for (const w of wrote) {
-  console.log(`✓ 已更新 ${path.relative(CONFIG_DIR, w)}`);
-}
-
-const errors = issues.filter((i) => i.level === "error").length;
-if (errors > 0) {
-  console.log(`\nprofile ${checkOnly ? "校验" : "装配"}失败：${errors} 个错误（未产出任何文件）`);
-  process.exit(1);
-}
-console.log(`\nprofile ${checkOnly ? "校验通过" : `装配完成（${wrote.length} 个文件更新）`}`);

package/templates/support-qa/lib/assemble.ts

@@ -1,279 +0,0 @@
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { SUPPORT_ACTIONS, KB_STATUS, KB_STATUS_VALUES } from "./contract.js";
-import { loadFastpathRules } from "./fastpath.js";
-import { isTroubleshootEnabled, loadClassifiers } from "./troubleshoot.js";
-
-/**
- * 最小 profile 装配器（场景层，零 core 依赖）
- *
- * profile v2 重构后职责收敛：
- *   1. roles.support.persona → 读取并写入 workspaces/support/persona.md
- *      （AGENTS.md 基座第一段声明"人设以本目录 persona.md 为准"）；
- *   2. preflight：group-qa 处置动作/知识沉淀 options 与 lib/contract.ts 常量强校验，
- *      admin-kb-update 事件过滤校验，on_action policies 键/值闭集校验（action ⊆
- *      SUPPORT_ACTIONS，group ∈ answer|silent，Owner 尾注由轴2派生不在此配），
- *      L3 fastpath/troubleshoot 预检。
- *
- * 已删除的职责：
- *   - escalation → owner-map/contacts.json 编译与校验：模块→Owner 映射已迁入 AI 表格
- *     「功能模块人员配置表」，由 config-sync 拉取并发布 ${globalVar.module_owners}，
- *     同时物化 workspaces/support/owner-map.json 供 answer Agent 的 module 闭集提示；
- *   - role.yml kb_collections 同步（roles 已内联进 profile.yml）；
- *   - admin-kb-update source-range 回写（由 ${roles.*} 内部引用 + 注入取代）。
- *
- * 两阶段执行：
- *   阶段一 全量校验 + 生成写盘计划（任一 error → 不写任何文件，杜绝半成品）；
- *   阶段二 按计划一次性写盘（内容不变不写，幂等）。
- */
-
-export type AssembleIssue = { level: "error" | "warn"; message: string };
-export type AssembleResult = { issues: AssembleIssue[]; wrote: string[] };
-
-const WORKSPACE_DIR = path.join("workspaces", "support");
-const GENERATED_HEADER = "<!-- 由 lib/assemble.ts 依据 profile/profile.yml 生成，勿手改；改 profile 后重跑 npm run assemble -->";
-
-type WritePlanEntry = { file: string; content: string };
-
-function readRawProfile(configDir: string, issues: AssembleIssue[]): Record<string, unknown> | null {
-  const file = path.resolve(configDir, "profile", "profile.yml");
-  if (!existsSync(file)) {
-    issues.push({ level: "error", message: `profile/profile.yml 不存在: ${file}` });
-    return null;
-  }
-  try {
-    const raw = (parseYaml(readFileSync(file, "utf8")) ?? {}) as Record<string, unknown>;
-    if (raw.schema_version !== 2) {
-      issues.push({ level: "error", message: `profile.yml schema_version 必须为 2（当前: ${raw.schema_version ?? "缺失"}）。请按迁移指引升级。` });
-      return null;
-    }
-    return raw;
-  } catch (err) {
-    issues.push({ level: "error", message: `profile/profile.yml 解析失败: ${err instanceof Error ? err.message : String(err)}` });
-    return null;
-  }
-}
-
-/** 相对 profile 目录解析引用文件；不存在则记 error 并返回 null */
-function resolveRef(configDir: string, rel: string, label: string, issues: AssembleIssue[]): string | null {
-  const abs = path.resolve(configDir, "profile", rel);
-  if (!existsSync(abs)) {
-    issues.push({ level: "error", message: `${label} 引用的文件不存在: profile/${rel}` });
-    return null;
-  }
-  return abs;
-}
-
-/** collections 校验：trim、去空、必须是不含 .. 的相对路径、目录须存在 */
-function validateCollections(configDir: string, raw: unknown, issues: AssembleIssue[]): string[] {
-  const list = Array.isArray(raw)
-    ? raw.map((c) =>
-        typeof c === "string" ? c.trim()
-        : c && typeof c === "object" && "collection" in c ? String((c as { collection: string }).collection).trim()
-        : String(c ?? "").trim())
-    : [];
-  if (list.length === 0 || list.some((c) => !c)) {
-    issues.push({ level: "error", message: "roles.support.knowledge_scope.kb_collections 缺失、为空或含空字符串（必填）" });
-  }
-  const collections = list.filter(Boolean);
-  for (const c of collections) {
-    if (path.isAbsolute(c) || c.split(/[\\/]/).includes("..")) {
-      issues.push({ level: "error", message: `kb_collections 必须是实例内的相对路径（不含 ..）: ${c}` });
-      continue;
-    }
-    if (!existsSync(path.resolve(configDir, c))) {
-      issues.push({ level: "error", message: `kb_collections 目录不存在: ${c}` });
-    }
-  }
-  return collections;
-}
-
-/** 集合严格相等比较 */
-function diffSets(actual: string[], expected: readonly string[]): { missing: string[]; extra: string[] } {
-  const a = new Set(actual);
-  const e = new Set(expected);
-  return { missing: expected.filter((v) => !a.has(v)), extra: actual.filter((v) => !e.has(v)) };
-}
-
-function getIn(obj: unknown, ...keys: string[]): unknown {
-  let current = obj;
-  for (const key of keys) {
-    if (!current || typeof current !== "object") return undefined;
-    current = (current as Record<string, unknown>)[key];
-  }
-  return current;
-}
-
-export function assembleProfile(configDir: string, opts: { dryRun?: boolean } = {}): AssembleResult {
-  const issues: AssembleIssue[] = [];
-  const plan: WritePlanEntry[] = [];
-  const wrote: string[] = [];
-
-  // ─── 阶段一：全量校验 + 生成写盘计划 ───
-  const raw = readRawProfile(configDir, issues);
-  if (!raw) return { issues, wrote };
-
-  const roles = (raw.roles ?? {}) as Record<string, Record<string, unknown>>;
-  const workflows = (raw.workflows ?? {}) as Record<string, Record<string, unknown>>;
-  const supportRole = roles.support;
-  const groupQaWf = workflows["group-qa"];
-
-  // basic validation
-  const roleName = typeof supportRole?.name === "string" ? supportRole.name.trim() : "";
-  if (!roleName) issues.push({ level: "error", message: "roles.support.name 缺失（必填）" });
-  const kbScope = supportRole?.knowledge_scope as Record<string, unknown> | undefined;
-  validateCollections(configDir, kbScope?.kb_collections, issues);
-
-  // 1) persona.md — 读 roles.support.persona（file 引用或内联字符串）
-  const personaField = supportRole?.persona;
-  let personaText = "";
-  if (typeof personaField === "string") {
-    personaText = `${GENERATED_HEADER}\n\n${personaField.trim()}`;
-  } else if (personaField && typeof personaField === "object" && "file" in personaField) {
-    const fileRel = String((personaField as { file: string }).file ?? "").trim();
-    if (!fileRel) {
-      issues.push({ level: "error", message: "roles.support.persona.file 为空" });
-    } else {
-      const abs = resolveRef(configDir, fileRel, "roles.support.persona.file", issues);
-      if (abs) {
-        const content = readFileSync(abs, "utf8").trim();
-        if (!content) {
-          issues.push({ level: "error", message: `roles.support.persona.file 文件内容为空: profile/${fileRel}` });
-        }
-        personaText = `${GENERATED_HEADER}\n\n${content}`;
-      }
-    }
-  } else if (supportRole) {
-    issues.push({ level: "error", message: "roles.support.persona 缺失（必填）" });
-  }
-  if (personaText) {
-    if (/忽略(上述|以上|通用)|必须回复所有|无据也(可以|要)回答|不用静默/.test(personaText)) {
-      issues.push({ level: "error", message: "persona 内容疑似放开通用闸门（只准收紧，不准放开），请修改后重试" });
-    }
-    plan.push({ file: path.resolve(configDir, WORKSPACE_DIR, "persona.md"), content: personaText });
-  }
-
-  // 2) escalation 已迁移：模块→Owner 映射改由 config-sync 从「功能模块人员配置表」拉取，
-  // 装配期不再编译/校验 owner-map×contacts（模块合法性由运行期快照判定）。
-
-  // 2b) on_action policies 闭集校验（读 workflows.group-qa.steps.on_action.policies）：
-  // 键必须 ⊆ SUPPORT_ACTIONS；group 只允许 answer / silent——group 只表达「群里说不说话」（轴1），
-  // Owner 指引由 Runtime 按「action 需要找人 + Owner 可解析」派生（轴2），不存在「通知 Owner」档位。
-  const onActionStep = getIn(groupQaWf, "steps", "on_action") as Record<string, unknown> | undefined;
-  const policiesRaw = onActionStep?.policies;
-  if (policiesRaw && typeof policiesRaw === "object") {
-    const configuredActions = Object.keys(policiesRaw);
-    const { extra } = diffSets(configuredActions, SUPPORT_ACTIONS);
-    if (extra.length > 0) {
-      issues.push({ level: "error", message: `on_action.policies 含未知 action [${extra.join(",")}]，合法值: [${SUPPORT_ACTIONS.join(",")}]` });
-    }
-    for (const [actionName, cfg] of Object.entries(policiesRaw as Record<string, { group?: unknown }>)) {
-      const group = cfg && typeof cfg === "object" ? cfg.group : undefined;
-      if (group === undefined) continue;
-      if (group !== "answer" && group !== "silent") {
-        issues.push({ level: "error", message: `on_action.policies.${actionName}.group 只能是 answer / silent（Owner 尾注不在 group 里配，由 Runtime 按 action 与 Owner 解析结果派生），实际: ${JSON.stringify(group)}` });
-      }
-    }
-  }
-  // 旧 on_silence 步配置仍存在 → 提醒迁移（拍平 action 后该步已改名 on_action）
-  if (getIn(groupQaWf, "steps", "on_silence")) {
-    issues.push({ level: "warn", message: "workflows.group-qa.steps.on_silence 已废弃（拍平 action 后步为 on_action）：请迁移为 steps.on_action.policies（track/group）" });
-  }
-
-  // 3) group-qa preflight：处置动作/知识沉淀 options 与 contract 常量强校验
-  const groupQaFile = path.resolve(configDir, "workflows", "group-qa", "workflow.yml");
-  if (existsSync(groupQaFile)) {
-    try {
-      const wf = (parseYaml(readFileSync(groupQaFile, "utf8")) ?? {}) as Record<string, any>;
-      const defs = Array.isArray(wf?.tracker?.field_definitions) ? wf.tracker.field_definitions : [];
-      for (const [fieldName, expected] of [
-        ["处置动作", SUPPORT_ACTIONS],
-        ["知识沉淀", KB_STATUS_VALUES],
-      ] as const) {
-        const matched = defs.filter((d: any) => d?.name === fieldName);
-        if (matched.length !== 1) {
-          issues.push({ level: "error", message: `group-qa field_definitions 中「${fieldName}」字段必须恰好 1 个，实际 ${matched.length} 个` });
-          continue;
-        }
-        const options = Array.isArray(matched[0]?.options) ? matched[0].options.map((o: any) => String(o)) : [];
-        const { missing, extra } = diffSets(options, expected);
-        if (missing.length > 0 || extra.length > 0) {
-          issues.push({ level: "error", message: `group-qa「${fieldName}」options 与 lib/contract.ts 不一致：缺[${missing.join(",")}] 多[${extra.join(",")}]` });
-        }
-      }
-    } catch (err) {
-      issues.push({ level: "error", message: `workflows/group-qa/workflow.yml 解析失败: ${err instanceof Error ? err.message : String(err)}` });
-    }
-  }
-
-  // 4) admin-kb-update filter preflight（从 profile v2 读取）
-  const adminKbWf = workflows["admin-kb-update"];
-  if (adminKbWf) {
-    const esConfig = getIn(adminKbWf, "event_sources", "管理员更新监听") as Record<string, unknown> | undefined;
-    const filterEquals = typeof esConfig?.filter === "object" && esConfig.filter
-      ? String((esConfig.filter as Record<string, unknown>).equals ?? "")
-      : "";
-    if (filterEquals && filterEquals !== KB_STATUS.READY_TO_PERSIST) {
-      issues.push({ level: "error", message: `admin-kb-update 事件过滤 filter.equals="${filterEquals}" 必须为 "${KB_STATUS.READY_TO_PERSIST}"（否则知识更新轨道不拉单）` });
-    }
-  }
-
-  // 6) L3 fastpath 规则预检（warn：运行期缺失即优雅关闭，不阻断 L0 主环）
-  const fastpathStep = getIn(groupQaWf, "steps", "fastpath") as Record<string, unknown> | undefined;
-  const fastpathRel = typeof fastpathStep?.rules === "string" ? fastpathStep.rules.trim() : "";
-  if (fastpathRel) {
-    const { issues: fpIssues } = loadFastpathRules(configDir, fastpathRel);
-    for (const msg of fpIssues) issues.push({ level: "warn", message: `fastpath: ${msg}` });
-  }
-
-  // 7) L3 troubleshoot 预检（warn：整档可选且运行期缺失即优雅关闭）
-  const troubleshootStep = getIn(groupQaWf, "steps", "troubleshoot") as Record<string, unknown> | undefined;
-  const skillsDirRel = typeof troubleshootStep?.skills_dir === "string" ? troubleshootStep.skills_dir.trim() : "";
-  if (skillsDirRel && !isTroubleshootEnabled(configDir, skillsDirRel)) {
-    issues.push({ level: "warn", message: `troubleshoot: skills_dir 目录不存在，整档将关闭: ${skillsDirRel}` });
-  }
-  const classifiersRel = typeof troubleshootStep?.classifiers === "string" ? troubleshootStep.classifiers.trim() : "";
-  if (classifiersRel) {
-    const { issues: tsIssues } = loadClassifiers(configDir, classifiersRel);
-    for (const msg of tsIssues) issues.push({ level: "warn", message: `troubleshoot: ${msg}` });
-    // classifier.module 合法性不再在装配期交叉校验：模块闭集来自功能模块人员配置表
-    // （config-sync 运行期快照），拼写不匹配时运行期降级并记 owner_resolution_failed。
-  }
-
-  // ─── 阶段二：全过才写盘；任一 error 或 dryRun → 零写盘 ───
-  const hasError = issues.some((i) => i.level === "error");
-  if (opts.dryRun || hasError) return { issues, wrote };
-
-  for (const entry of plan) {
-    try {
-      const prev = existsSync(entry.file) ? readFileSync(entry.file, "utf8") : null;
-      if (prev === entry.content) continue;
-      mkdirSync(path.dirname(entry.file), { recursive: true });
-      writeFileSync(entry.file, entry.content, "utf8");
-      wrote.push(entry.file);
-    } catch (err) {
-      issues.push({ level: "error", message: `写盘失败 ${path.relative(configDir, entry.file)}: ${err instanceof Error ? err.message : String(err)}` });
-    }
-  }
-
-  return { issues, wrote };
-}
-
-// ─── 运行时兜底：进程内每 configDir 只装配一次，结果缓存供调用方决策 ───
-const assembledResults = new Map<string, AssembleResult>();
-
-export function ensureAssembled(configDir: string, log: (msg: string) => void): AssembleResult {
-  const cached = assembledResults.get(configDir);
-  if (cached) return cached;
-  let result: AssembleResult;
-  try {
-    result = assembleProfile(configDir);
-  } catch (err) {
-    result = { issues: [{ level: "error", message: `装配异常: ${err instanceof Error ? err.message : String(err)}` }], wrote: [] };
-  }
-  assembledResults.set(configDir, result);
-  for (const i of result.issues) log(`[profile-assemble][${i.level}] ${i.message}`);
-  if (result.wrote.length > 0) log(`[profile-assemble] 已更新: ${result.wrote.map((w) => path.relative(configDir, w)).join(", ")}`);
-  return result;
-}