zn-ai/docs/ClawX-Chat-Skill-Runtime-Migration-Checklist.md

zn-ai 对齐 ClawX 的聊天 Skill 运行时迁移清单

1. 目标

让 zn-ai 的聊天运行时具备与 ClawX 同方向的能力：

• 用户在聊天中提到某个已启用的 skill 时，模型能把它当成可规划、可调用、可回传结果的运行时能力，而不是只把它当成设置页里的开关。
• 用户上传文件、引用网页、请求执行动作时，运行时能根据当前已启用 skills 自动规划合适的 skill/tool 链路。
• 聊天链路能产生真实的 thinking / tool_use / tool_result / final answer。
• 用户能在 UI 中看到执行过程、失败原因和最终结果。

首个样板场景仍然是：

• 用户发送：使用 minimax-xlsx 这个 skill，帮我分析下
• 如果会话里已有 .xlsx/.csv/.tsv 附件，运行时能识别并把文件交给表格类 skill

但这份文档的目标已经调整为：

• 架构上按“所有已启用 skills 都能接入聊天运行时”来设计
• xlsx/minimax-xlsx 只是第一条落地样板，不再作为唯一目标

2. 范围定义

2.1 最终目标范围

最终目标不是只支持 minimax-xlsx，而是支持：

• 所有已启用 skills 在聊天时可见
• 所有已启用 skills 可被模型规划
• 所有已启用 skills 可被运行时调用
• 所有已启用 skills 的结果可回传给模型并写入会话历史
• 所有已启用 skills 的执行结果可被 renderer 展示

2.2 首批交付范围

首批交付不要求把每一个 skill 都逐个深度适配，但要求：

• 运行时架构必须按“全量 skills 通用接入”设计
• 第一批用 xlsx/minimax-xlsx 完成端到端验收
• 第二批逐步覆盖其他 skill 类型，而不是继续新增特判分支

2.3 明确不再采用的方向

不采用下面这种方案：

• 只为 minimax-xlsx 单独写一条聊天特判链路
• 只为少数 skill 手工写 prompt 注入和执行代码
• 让不同 skill 分别走不同的 ad-hoc 执行协议

3. 全量 skills 通用接入边界与阶段化策略

这一节单独回答一个关键问题：

• 这次迁移是不是要把“所有 skills 都接进聊天运行时”考虑进去？

答案是：

• 要考虑进去
• 但不是要求第一批把每一个 skill 都做成同等质量的深度适配
• 而是要求从第一天起，架构必须按“全量 skills 可接入”来设计

3.1 通用接入边界

本次迁移的“全量 skills 通用接入”边界如下：

• 所有已启用 skills 都必须能进入聊天运行时的 capability 列表
• 所有已启用 skills 都必须能被 planner 看见并参与候选规划
• 所有已启用 skills 都必须能映射到统一 executor 协议
• 所有 skills 的执行结果都必须能落入统一的 tool_result 结构
• 所有 skills 的执行过程都必须能被 transcript 和 renderer 消费

本次迁移不承诺的边界如下：

• 不承诺首批就为每一个 skill 做专门的高质量 UI 定制
• 不承诺首批就为每一个 skill 做类型专属优化
• 不承诺首批就覆盖所有外部依赖复杂、权限要求高的 skills

换句话说：

• 首批必须做到“都能接”
• 但不要求首批“都接得一样深、一样好看、一样聪明”

3.2 SKILL.md -> runtime capability 通用抽取规则

这是第一项必须补进文档的内容。

目标：

• 不能把 SKILL.md 原文直接塞给模型
• 需要抽成稳定、短小、可规划的 runtime capability

通用抽取规则建议如下：

1. 基础身份字段

   • skillKey
   • displayName
   • description

2. 能力字段

   • inputKinds
   • outputKinds
   • triggerHints
   • supportedFileTypes

3. 约束字段

   • requiresFiles
   • requiresEnv
   • requiresRuntime
   • riskLevel

4. 执行字段

   • defaultEntrypoint
   • callPattern
   • resultShape

抽取优先级建议：

1. 先读显式元数据
2. 再读 SKILL.md 的标题、description、usage、limitations
3. 最后使用默认推断规则兜底

兜底策略：

• 如果 skill 没有足够结构化信息，也必须能生成最小 capability
• 不能因为 metadata 不完整就把 skill 排除出聊天运行时

3.3 Skill 分类分层策略

这是第二项必须补进文档的内容。

目标：

• 不同 skill 的输入输出模式不同
• 不能要求所有 skill 共用完全相同的 planner 提示和 executor 适配方式

首版推荐分层如下：

1. 文档/文件类

   • 例：xlsx、minimax-xlsx、pdf、docx
   • 典型输入：文件、路径、sheet、段落、页码
   • 典型输出：结构化数据、文件、摘要

2. 浏览器/网页类

   • 例：browser automation、web browse
   • 典型输入：URL、页面元素、交互动作
   • 典型输出：页面快照、DOM 结果、提取数据

3. 搜索/检索类

   • 例：web search、knowledge search
   • 典型输入：query、filters、time range
   • 典型输出：候选结果、摘要、来源

4. 命令/脚本类

   • 例：shell、uv、脚本执行型 skill
   • 典型输入：命令参数、工作目录、文件引用
   • 典型输出：stdout、stderr、产物文件、退出状态

5. 外部 API / 服务类

   • 例：需要第三方 API key 的 skill
   • 典型输入：结构化参数、凭据引用、速率限制
   • 典型输出：API 响应、结构化记录、失败状态

分层原则：

• planner 先按 skill type 缩小候选范围
• executor 再按该 type 的 adapter 执行
• UI 先展示通用结果，再逐步补 skill type 专属展示

3.4 Skill 前置检查策略

这是第三项必须补进文档的内容。

目标：

• 不是 skill 已启用就一定可执行
• 聊天运行时必须在规划前或执行前做前置检查

每个 skill 的前置检查至少包括：

1. 依赖检查

   • 本地二进制是否存在
   • Python/Node/uv 运行时是否可用
   • 所需脚本是否存在

2. 环境变量检查

   • 必需 env 是否已配置
   • API key 是否存在
   • 敏感变量是否允许在当前运行环境使用

3. 权限检查

   • 是否需要文件访问
   • 是否需要网络访问
   • 是否需要 shell/命令执行权限
   • 是否需要浏览器自动化权限

4. 输入检查

   • 文件是否存在
   • 文件类型是否受支持
   • 参数是否齐全

前置检查的输出必须标准化为：

• ready
• blocked_missing_dependency
• blocked_missing_env
• blocked_missing_permission
• blocked_invalid_input

这一步的意义是：

• 避免模型盲目调用 skill
• 避免把“权限没给”误判成“skill 不会用”
• 避免用户只看到一句模糊失败文案

3.5 通用 tool_result 标准化与 UI 渲染协议

这是第四项必须补进文档的内容。

目标：

• 所有 skill 返回结果必须进入统一 tool_result
• renderer 先消费统一协议，再渐进增强不同 skill 类型的展示

建议统一结果结构：

• ok
• summary
• structuredData
• artifacts
• logs
• error
• retryable
• skillType
• renderHints

其中：

• structuredData 用于模型继续推理
• artifacts 用于文件、图片、表格结果回传
• logs 用于调试和错误诊断
• renderHints 用于 UI 做轻量差异化展示

UI 渲染协议建议分两层：

1. 通用层

   • 所有 skills 都显示状态、摘要、错误、耗时、输入概览

2. 类型增强层

   • 文档类显示文件、sheet、提取结果摘要
   • 搜索类显示来源列表和摘要
   • 浏览器类显示页面结果与操作轨迹
   • 命令类显示输出日志与产物

原则：

• 没有类型增强时，通用层也必须完整可用
• UI 不得依赖某个单 skill 的私有字段才能渲染

3.6 阶段化策略

“全量 skills 通用接入”建议按 4 个阶段推进：

Phase A：通用协议冻结

目标：

• 冻结 capability schema
• 冻结 skill type taxonomy
• 冻结 preflight check 输出
• 冻结 tool_result 标准结构

产出：

• skill registry 契约
• planner 输入输出契约
• renderer 消费契约

Phase B：样板链路落地

目标：

• 用 xlsx/minimax-xlsx 跑通文件类样板
• 验证“启用 -> 可见 -> 可规划 -> 可执行 -> 可回传 -> 可展示”

要求：

• 代码实现必须走通用协议
• 不允许新增只服务于 minimax-xlsx 的永久特判

Phase C：扩展到多 skill 类型

目标：

• 选至少 1 个搜索类 skill
• 选至少 1 个浏览器或命令类 skill
• 验证通用架构不是只对文件类有效

要求：

• 不改聊天主链路，只增加 registry/parser/adapter 配置

Phase D：规模化接入与收敛

目标：

• 把更多已启用 skills 纳入 capability 列表
• 补前置检查、错误模型、UI 增强
• 补自动化回归

验收口径：

• 新增 skill 时，原则上不需要再改 chat.send 主编排
• 如果新增 skill 还需要改主编排，说明架构仍未真正通用

4. 当前主结论

当前 zn-ai 的主阻塞不是 minimax-xlsx 没启用，而是：

• 聊天运行时没有把已启用 skills 注入成可用能力
• 聊天主链路仍是“文本 provider 直连”，不是通用 tool/skill runtime
• 附件虽然能进入聊天，但没有稳定进入“技能可消费输入链路”
• renderer 能显示少量工具状态，但没有完整执行闭环
• 现有设计更接近“个别功能特判”，还不是“所有 skills 通用接入聊天运行时”

5. 验收标准

迁移完成后，至少要通过这 6 个场景：

1. 已启用 minimax-xlsx，用户发送 使用 minimax-xlsx 这个 skill，帮我分析下，模型不会只返回空泛文本，而会进入 skill/tool 执行链路。
2. 用户上传 .xlsx/.csv/.tsv 后发送同一句话，运行时能把附件作为分析输入，而不是只把文件路径当普通文本。
3. 用户启用任意其他文档类或搜索类 skill 后，聊天运行时能把该 skill 暴露为能力，而不是只在 Skills 页显示“已启用”。
4. 聊天中能看到工具执行状态、结果摘要、失败信息；失败时能明确是“文件缺失 / skill 不可见 / provider 不支持 / runtime 执行失败 / skill 依赖未满足”。
5. 多轮对话里，tool 结果能回灌到后续推理，不会出现“执行过了但模型下一轮不知道结果”。
6. 新增一个符合规范的 skill 时，不需要再给聊天链路补新的特判代码，只需通过注册/抽取机制接入。

6. 通用接入原则

这一节是本次调整的核心。

5.1 所有 skills 都必须经过同一条能力链路

统一链路：

1. Skill 发现
2. Skill 元数据抽取
3. Runtime capability 注入
4. Planner 选择 skill/tool
5. Executor 调用 skill/tool
6. Tool result 标准化
7. Transcript 写回
8. Renderer 展示

任何 skill 都不应该绕过这条链路单独接入聊天。

5.2 xlsx/minimax-xlsx 只是样板，不是特例

首批先用它验收，是因为它最能暴露当前缺口：

• 附件输入
• 文件访问
• tool loop
• 结果回灌
• UI 展示

但一旦链路建好，其他 skills 也必须复用同一套机制。

5.3 先做“通用协议”，再做“具体 skill 适配”

顺序必须是：

1. 先冻结通用 skill capability schema
2. 先冻结通用 planner/executor/tool_result 协议
3. 再做 xlsx/minimax-xlsx 样板接入
4. 再扩展到更多 skills

不能反过来先做某一个 skill 的特例实现，再倒推通用架构。

7. 通用能力模型

6.1 Skill capability schema

每个已启用 skill 在聊天运行时至少要暴露这些字段：

• skillKey
• displayName
• description
• inputKinds
• outputKinds
• triggerHints
• requiresFiles
• supportedFileTypes
• requiresEnv
• requiresRuntime
• riskLevel

说明：

• 这里不是把整个 SKILL.md 原样塞给模型
• 而是把它抽成稳定的、可规划的最小能力描述

6.2 Tool execution schema

所有 skills 在执行层至少统一到这些结构：

• toolName
• toolCallId
• input
• status
• result
• error
• artifacts
• summary

6.3 Tool result schema

所有 skill/tool 返回结果都要能映射成统一结构：

• ok
• summary
• structuredData
• files
• logs
• error
• retryable

6.4 Transcript schema

所有 skills 的执行都要进入统一会话记录：

• thinking
• tool_use
• tool_result
• assistant final

6.5 Skills 通用接入数据流图

下面这张文字版流程图，定义的是 registry -> planner -> executor -> tool_result -> transcript -> renderer 的标准主链路：

[已启用 skills / 内建 tools / SKILL.md metadata / adapter manifest]
                            |
                            v
                    [Registry]
  产出统一 capability list / tool registry entries / preflight metadata
                            |
                            v
[用户消息 / 附件 / 会话历史 / runtime context / capability list]
                            |
                            v
                    [Planner]
  选择 skill/tool，产出 thinking + tool_use plan
  如果当前无需调用 tool，则直接走 assistant final
                            |
                            v
                    [Executor]
  执行 preflight check
  把附件、参数、上下文转成 adapter 可消费输入
  调用具体 skill/tool adapter，拿到 raw result / artifacts / logs / error
                            |
                            v
                  [tool_result Normalize]
  统一映射成 ok / summary / structuredData / files / logs / error / retryable / renderHints
                            |
              +-------------+-------------+
              |                           |
              v                           v
        [Transcript]                [模型续推]
  写回 thinking / tool_use /     把 tool_result 回灌给模型，
  tool_result / assistant final   决定继续下一次 tool_use 或输出 final
              |
              v
         [Renderer]
  渲染执行状态、结果卡片、错误原因、产物入口、最终回答

实现约束：

• registry 只负责暴露能力，不负责替模型做最终决策
• planner 只负责选什么能力、传什么输入，不直接承担具体执行
• executor 只负责执行与标准化，不负责私自改写会话历史
• tool_result 必须同时服务两条链路：一条给模型续推，一条给 transcript / renderer 展示
• transcript 是多轮续接的唯一可信记录，不能只在 UI 本地保留工具结果
• renderer 优先消费统一协议，再按 skill type 做渐进增强

落地时最容易漏掉的环节：

• 只做了 registry -> planner -> executor，但没有把 tool_result 回灌模型
• 只做了 tool_result -> renderer，但没有把 tool_use / tool_result 写回 transcript
• 只让 minimax-xlsx 走这条链路，其他 enabled skills 仍然走特判分支
• 让 provider 直接内嵌 planner / executor 逻辑，导致通用 runtime 无法复用

6.6 Skills 通用接入代码文件映射图

下面这张图把上一节的数据流，直接映射到当前 zn-ai 里已经存在或建议新增的关键文件：

[Registry capability 装配入口]
  runtime-context.ts
  说明：当前这里是 runtime capability 注入边界；
       后续可把真正的 registry 生成下沉到 skill-capability-registry.ts，
       但对 chat.send 的上游入口仍然是这里。
                |
                v
[聊天主编排入口]
  handlers/chat.ts
  说明：接收用户消息、附件、会话历史，串联 planner / executor / transcript
                |
      +---------+---------+
      |                   |
      v                   v
[规划层]              [执行层]
  skill-planner.ts      tool-runtime.ts
  说明：                 说明：
  - 消费 message         - 执行 preflight check
    / attachments        - 调用 skill/tool adapter
    / history            - 生成标准化 tool_result
    / runtime context    - 产出 tool status / artifacts / logs
  - 产出 thinking
    / tool_use plan
    / no-tool decision
      |                   |
      +---------+---------+
                |
                v
[共享协议层]
  chat-model.ts
  说明：定义 thinking / tool_use / tool_result / assistant final
       的 transcript schema 与共享消息结构
                |
                v
[渲染层]
  ChatMessageList.tsx
  说明：消费 transcript、toolStatuses、attachments、tool_result，
       渲染执行状态、结果摘要、错误信息和最终回答

按职责拆到文件后的推荐边界如下：

• runtime-context.ts

  • 负责把当前 enabled skills、内建 tools、session 信息装配成模型可见的 runtime context
  • 不负责直接决定“这次该调用哪个 skill”
  • 不负责写死某个 skill 的执行分支

• handlers/chat.ts

  • 负责主编排，是 chat.send 的唯一入口
  • 负责把用户消息、附件、历史、runtime context 串起来
  • 负责调用 skill-planner.ts 和 tool-runtime.ts
  • 负责把 thinking / tool_use / tool_result / final 写回 transcript
  • 不负责继续堆 if user says x then call y 的特判

• skill-planner.ts

  • 负责根据 capability list、附件类型、用户意图、历史上下文决定是否调用 skill/tool
  • 输出统一的 planner decision，而不是直接在这里执行 tool
  • 如果模型无需调 tool，也要能明确返回 assistant-final-only 这类决策

• tool-runtime.ts

  • 负责 preflight check、adapter dispatch、错误归一化、tool_result 标准化
  • 负责把 raw result 转成 transcript 和 renderer 都能消费的结构
  • 不负责挑选哪个 tool；那是 planner 的职责

• chat-model.ts

  • 负责冻结共享协议，避免 gateway 和 renderer 各自维护一套 message shape
  • 这里必须成为 thinking / tool_use / tool_result / tool status / attachments 的统一来源
  • 如果协议扩展，不应该只改 UI 或只改 gateway 单边

• ChatMessageList.tsx

  • 负责把通用 transcript 协议渲染出来
  • 先支持通用 tool_result 卡片，再渐进增强不同 skill type 的专属展示
  • 不应该依赖某个 skill 的私有字段才能完成基础渲染

这张映射图对应的实施顺序建议是：

1. 先冻结 chat-model.ts 的共享 schema
2. 再补 skill-planner.ts 和 tool-runtime.ts
3. 然后让 handlers/chat.ts 接管主编排
4. 再把 runtime-context.ts 从“固定两三个 tool 描述”升级成“全量 enabled skills capability 注入”
5. 最后让 ChatMessageList.tsx 完整消费新的 transcript / tool_result 协议

如果后面要继续往下拆实现任务，这 6 个文件基本就能直接映射成 6 条主工作流，不容易再把 registry、planner、executor、renderer 的职责混到一起。

8. 优先级清单

状态回填基线（2026-04-24）：

• 已完成：当前阶段目标已经落地，后续只做增强，不再影响本阶段是否达标
• 部分完成：主链路已接入或已有样板，但仍有明显缺口，暂不能视为该项收口
• 未开始：还停留在文档/设计层，或尚未形成有效实现

P0 阻塞项

这些必须先补，不补就很难达到目标效果。

P0-1 建立“全量 enabled skills -> runtime capabilities”注入机制

状态：部分完成

现状：

• 已有 capability registry 和 runtime context 注入链路，首批样板能把已启用 skill 暴露给聊天运行时
• 但“依赖/环境不满足”的统一降级提示还没有完全收口，新增 skill 也还没有做到真正零补丁接入

目标：

• 聊天发送前，运行时拿到当前所有已启用 skills 的能力描述
• 不是只暴露 browser.open_url、skills.install
• 首批先验证 xlsx/minimax-xlsx，但实现必须支持所有 skills

当前涉及文件：

• zn-ai/electron/gateway/runtime-context.ts
• zn-ai/electron/gateway/handlers/chat.ts
• zn-ai/electron/gateway/handlers/skills.ts

清单：

• 在聊天发送前读取当前 enabled skills
• 为 enabled skills 生成通用 runtime capability 描述
• 首批先支持 xlsx/minimax-xlsx 样板注入
• 确保后续 skill 接入不需要再改聊天主链路
• 明确“已启用但依赖/环境不满足”时的降级提示

P0-2 建立通用 skill metadata 抽取机制

状态：已完成

现状：

• capability schema、默认抽取规则、SKILL.md 降级抽取和 registry 入口都已落地
• 更细的 skill type 扩展仍会继续增强，但不影响这一阶段的 metadata 抽取主目标

目标：

• 从 skill 配置和 SKILL.md 提取统一 capability schema
• 为所有 skills 提供同一套抽取入口

当前涉及文件：

• zn-ai/electron/gateway/handlers/skills.ts
• 新增建议文件：zn-ai/electron/gateway/skill-capability-registry.ts
• 新增建议文件：zn-ai/electron/gateway/skill-capability-parser.ts

清单：

• 定义 capability schema
• 定义默认抽取规则
• 为缺少结构化元数据的 skill 提供降级抽取策略
• 支持后续按 skill 类型扩展抽取器

P0-3 从“文本 provider”升级到“可执行 tool 的聊天运行时”

状态：部分完成

现状：

• tool-capable provider/runtime 契约和 planner-first 执行链路已接入，tool_result 也能回灌后续回答
• 但 provider 原生 tool loop 还没有完整打通，tools/toolChoice 仍未成为统一主路径

目标：

• 聊天主链路不能只调用 provider.chat(messages, model)
• 必须支持模型发起工具调用，运行时执行后再把结果回给模型

当前涉及文件：

• zn-ai/electron/providers/BaseProvider.ts
• zn-ai/electron/providers/OpenAIProvider.ts
• zn-ai/electron/gateway/handlers/chat.ts

清单：

• 设计统一 tool-capable provider/runtime 接口
• 支持模型输出 tool_use 或等价调用结构
• 运行时执行 skill/tool 后生成 tool_result
• 把 tool_result 回灌给模型，继续完成最终回答
• 保留现有文本流式输出作为降级路径

P0-4 建立通用 planner / registry，而不是继续堆特判

状态：部分完成

现状：

• tool registry、planner、tool runtime 已建立统一入口，skills.install、浏览器、xlsx/minimax-xlsx 已纳入同一条链路
• 但新增 skill 仍需要补 adapter，尚未做到“任意已启用 skill 都能直接执行”

目标：

• skill 调用不能再靠“遇到某句提示词就手工分支”
• 所有 skills 和内建 tools 都通过统一 registry 暴露给 planner

当前涉及文件：

• zn-ai/electron/gateway/handlers/chat.ts
• 新增建议文件：zn-ai/electron/gateway/tool-runtime.ts
• 新增建议文件：zn-ai/electron/gateway/tool-registry.ts
• 新增建议文件：zn-ai/electron/gateway/skill-planner.ts

清单：

• 抽象通用 tool registry
• skill/tool 共用一套注册与调度模型
• 把 skills.install、浏览器、xlsx/minimax-xlsx 纳入统一 planner
• 后续 skill 不再新增聊天特判

P0-5 把附件真正接入“通用 skill 输入链路”

状态：部分完成

现状：

• 文件类样板已能把附件作为结构化输入交给表格分析链路，.xls 也已补上本地 fallback
• 但附件输入 schema 还没有沉淀成所有文件类 skill 共用的公共层

目标：

• 对 .xlsx/.csv/.tsv，不能只把 [media attached: ...] 拼到文本里
• 附件要变成 planner/executor 可消费的标准输入
• 设计要对所有“需要文件输入”的 skills 通用

当前涉及文件：

• zn-ai/src/stores/chat.ts
• zn-ai/electron/api/routes/files.ts
• zn-ai/electron/gateway/handlers/chat.ts

清单：

• 为文件类 skill 建立统一附件输入 schema
• 首批先验证表格类输入
• tool/skill 执行时能拿到稳定文件路径或句柄信息
• 附件缺失、路径失效时返回结构化错误

P0-6 把 tool 结果写回会话历史

状态：部分完成

现状：

• tool_use / tool_result 已写回 transcript，并能参与后续轮次的推理
• 但大结果摘要、上下文膨胀控制和进一步的历史裁剪策略还没有完全收口

目标：

• 执行过的 skill 结果必须成为会话上下文的一部分
• 下一轮问“继续分析第 2 个 sheet”时，模型能接上

当前涉及文件：

• zn-ai/electron/gateway/handlers/chat.ts
• zn-ai/src/stores/chat.ts
• zn-ai/runtime-shared/shared/chat-model.ts

清单：

• 在 transcript/session history 中保留 tool_use / tool_result
• 重新定义发送下一轮时的 history flatten 规则
• 避免把关键 tool 结果过滤掉
• 对大结果做摘要，避免上下文膨胀

P1 重要项

这些不一定是第一批 blocker，但会直接影响可用性和稳定性。

P1-1 建立“聊天 runtime 与 Skills 页”的同步机制

状态：部分完成

现状：

• skills.update/install 后已能广播 runtime refresh，Skills 页也已经接到这类变化
• 但聊天 runtime/store 侧还没有完整消费这些变更，热更新边界仍不够清晰

当前涉及文件：

• zn-ai/electron/gateway/handlers/skills.ts
• zn-ai/electron/gateway/types.ts
• zn-ai/src/lib/skills-api.ts

清单：

• skills.update 后广播 runtime refresh
• 聊天 runtime 监听 skills 变化并刷新能力缓存
• 明确“需要重启 gateway”与“可热更新”的边界

P1-2 补齐聊天 UI 的执行可视化

状态：部分完成

现状：

• 通用 tool-only 消息和结果卡片已经具备，browser.open_url、skills.install 有专项展示
• 但表格分析专项卡片、失败重试和查看详情入口还没有补齐

当前涉及文件：

• zn-ai/src/stores/chat.ts
• zn-ai/src/components/chat/ChatMessageList.tsx
• zn-ai/src/pages/Home/index.tsx

清单：

• 区分普通 assistant 文本和 tool-only 消息
• 增加通用 tool 结果展示结构
• 首批先做好表格分析类结果卡片
• 为失败结果增加重试或查看详情入口

P1-3 对齐 ClawX 的 workspace/context 注入机制

状态：未开始

现状：

• 目前仍以现有 runtime context 注入为主
• workspace/context 资源目录、统一说明文件和启动期上下文装配还没有正式开工

当前参考文件：

• ClawX/electron/utils/openclaw-workspace.ts
• ClawX/resources/context/AGENTS.clawx.md
• ClawX/resources/context/TOOLS.clawx.md

清单：

• 为 zn-ai 增加运行时 context 资源目录
• 定义 skill/tool 使用约束说明
• 让 agent/workspace 在 gateway 启动后获得一致上下文

P1-4 明确 provider 能力矩阵

状态：未开始

现状：

• provider 契约已经开始具备 tool-capable 方向的定义
• 但支持矩阵、白名单和成体系的降级策略还没有形成可执行结果

清单：

• 列出支持 tool loop 的 provider/model 白名单
• 不支持时给出明确降级策略
• 区分“模型不支持”与“skill 执行失败”

P2 增强项

这些会提高稳定性、可维护性和长期对齐度。

P2-1 Skill 类型分层

状态：部分完成

现状：

• capability parser 已有轻量分类能力
• 但 taxonomy 冻结、分类专属 adapter 和跨类型接入标准还没有全部完成

目标：

• 不是所有 skill 都有相同输入输出模式
• 需要按类型建立统一接入层

推荐分类：

• 文档/文件类
• 浏览器/网页类
• 搜索/检索类
• 命令/脚本类
• 外部 API 类

清单：

• 定义 skill type taxonomy
• 为每类定义默认 input/output adapter
• 首批至少覆盖文档类与浏览器类

P2-2 回归测试与 smoke

状态：部分完成

现状：

• 已有 runtime context、planner、shortcut、chat-tooling 等聚焦单测
• 但非 xlsx skill 回归、tool_use -> tool_result -> final 集成测试，以及开发态/打包态 smoke 还未补齐

清单：

• 单测：已启用 skill 会出现在 runtime context
• 单测：上传 .xlsx 后进入表格分析链路
• 单测：新增一个非 xlsx skill 也能进入通用 registry
• 集成测试：tool_use -> tool_result -> final
• smoke：开发态和打包态都验证一次

P2-3 错误模型和日志分层

状态：部分完成

现状：

• shared schema 已具备基础的 tool error/result 结构
• 但授权、provider、tool、skill、附件的统一错误模型和 UI 提示映射仍未收口

清单：

• 区分授权错误、provider 错误、tool 错误、skill 错误、附件错误
• transcript 中保留最小必要诊断字段
• UI 侧映射成用户能理解的提示

9. 推荐推进顺序

当前进度判断：

• 第一阶段：已基本完成
• 第二阶段：部分完成
• 第三阶段：未完成

第一阶段

• P0-1 全量 enabled skills 注入 runtime
• P0-2 通用 skill metadata 抽取
• P0-3 tool-capable 聊天运行时
• P0-4 通用 planner / registry
• P0-5 附件进入通用 skill 输入链路

完成标志：

• 架构上已经不再依赖单个 skill 特判
• xlsx/minimax-xlsx 成为第一条跑通的样板链路

第二阶段

• P0-6 tool 结果回灌历史
• P1-1 runtime 与 Skills 页同步
• P1-2 聊天 UI 执行可视化

完成标志：

• 用户能稳定看到执行过程，且多轮能接续

第三阶段

• P1-3 workspace/context 对齐
• P1-4 provider 能力矩阵
• P2 全部增强项

完成标志：

• 新增 skill 时，聊天运行时不再需要新增 ad-hoc 接入代码

10. 推荐 sub-agent 编制

9.1 推荐数量

• 推荐：7 个 sub-agent
• 最小可行：5 个 sub-agent
• 稳妥完整：8 个 sub-agent

解释：

• 因为这次目标已经从“单个 skill 样板”升级为“全量 skills 通用接入架构”
• 需要单独有人负责 skill metadata/registry，不适合继续塞进原有分工里

默认建议采用：

• 7 个 worker sub-agent + 1 个主协调 agent

说明：

• 主协调 agent 不计入上面的 sub-agent 数量
• 主协调 agent 负责冻结接口、安排波次、收敛冲突、做最终集成

9.2 7 个 sub-agent 分工

SA-1 Skill Capability Registry

职责：

• 把所有 enabled skills 注入聊天 runtime context
• 定义通用 capability schema
• 负责 skill metadata 抽取与 registry

主要文件归属：

• zn-ai/electron/gateway/runtime-context.ts
• zn-ai/electron/gateway/handlers/skills.ts
• zn-ai/electron/gateway/types.ts
• 新增 zn-ai/electron/gateway/skill-capability-registry.ts
• 新增 zn-ai/electron/gateway/skill-capability-parser.ts

验收：

• 任何已启用 skill 都能进入 runtime capability 列表

SA-2 Provider 与 Tool Runtime

职责：

• 把文本 provider 升级为可执行 tool 的聊天运行时
• 定义 tool call / tool result / resume 推理接口

主要文件归属：

• zn-ai/electron/providers/BaseProvider.ts
• zn-ai/electron/providers/OpenAIProvider.ts
• 新增 zn-ai/electron/gateway/tool-runtime.ts

验收：

• 模型能发起真实 tool 调用，不再只有文本流

SA-3 Planner / Tool Registry

职责：

• 设计通用 planner
• 统一 skill/tool 注册与调度
• 去掉继续堆特判的趋势

主要文件归属：

• 新增 zn-ai/electron/gateway/tool-registry.ts
• 新增 zn-ai/electron/gateway/skill-planner.ts
• 必要时补 zn-ai/electron/gateway/types.ts

验收：

• skills.install、浏览器、xlsx/minimax-xlsx 都通过统一 registry 接入

SA-4 Chat Orchestration / Transcript

职责：

• 负责 chat.send 主编排
• 把 tool_use / tool_result / final 写回会话历史
• 处理 history flatten 和多轮续接

主要文件归属：

• zn-ai/electron/gateway/handlers/chat.ts
• zn-ai/electron/gateway/session-store.ts
• zn-ai/runtime-shared/shared/chat-model.ts

验收：

• 多轮对话能接上前一轮 tool 结果

SA-5 Attachment / File Skill Input

职责：

• 把 .xlsx/.csv/.tsv 等文件变成通用 skill 输入
• 先打通文件类 skill 输入适配层

主要文件归属：

• zn-ai/src/stores/chat.ts
• zn-ai/electron/api/routes/files.ts

验收：

• 文件类 skill 拿到稳定输入，不再只依赖文本路径猜测

SA-6 Renderer Tool UI

职责：

• 聊天 UI 展示 tool 卡片、状态、结果摘要、失败详情
• 对齐 pendingFinal、tool-only 消息和分析过程可视化

主要文件归属：

• zn-ai/src/components/chat/ChatMessageList.tsx
• zn-ai/src/pages/Home/index.tsx
• 新增聊天执行可视化组件时归此 agent

验收：

• 用户能在聊天页看清楚“何时开始分析、分析了什么、结果是什么”

SA-7 Testing / Smoke / Rollout

职责：

• 为前 6 个 agent 的改动补回归测试
• 增加最小集成测试和开发态 smoke
• 记录“新增 skill 是否零特判接入”的验收结果

主要文件归属：

• zn-ai/tests/chat-runtime-context.test.ts
• zn-ai/tests/gateway-rpc-dispatch.test.ts
• 新增与 skill registry、planner、tool_result 相关测试
• 需要时补充 docs/ 中的验收记录

验收：

• 至少有 1 条覆盖“已启用 skill + planner + tool_result + final”的集成链路
• 至少有 1 条覆盖“新增非 xlsx skill 无需新增聊天特判”的回归验证

9.3 6 个核心文件实施任务拆解表

这张表只聚焦最容易互相卡住的 6 个核心文件。

• 辅助文件仍然跟随主责 sub-agent 所在分支推进
• 任何辅助文件的改动，都不应绕开对应核心文件的 owner
• chat-model.ts 虽然归 SA-4 主责，但必须以“共享契约先冻结”方式提前进入 Wave 1

核心文件	主要实施任务	主责 sub-agent	主要协作方	前置冻结 / 依赖	推荐合并顺序
zn-ai/runtime-shared/shared/chat-model.ts	冻结 thinking / tool_use / tool_result / assistant final / tool status / attachments 的共享 schema，统一 gateway、store、UI 的消息结构	SA-4	SA-1 SA-2 SA-6	先评审 schema，再允许其他链路接入；这是后续 handlers/chat.ts 和 ChatMessageList.tsx 的共同前置	0
zn-ai/electron/gateway/runtime-context.ts	把当前 enabled skills、内建 tools、session 信息装配成 runtime capability 注入入口；从“固定工具说明”升级成“全量能力注入”	SA-1	SA-3 SA-4	依赖 capability schema 冻结；与 skill-capability-registry.ts、skill-capability-parser.ts 一起推进	1
zn-ai/electron/gateway/tool-runtime.ts	定义 preflight check、adapter dispatch、raw result -> tool_result 标准化、resume 推理接口	SA-2	SA-3 SA-4	依赖 chat-model.ts 的 tool_result 结构；需要先冻结 provider / runtime contract	2
zn-ai/electron/gateway/skill-planner.ts	根据 capability list、附件、历史、用户意图产出统一 planner decision，去掉继续堆特判的趋势	SA-3	SA-1 SA-2 SA-4	依赖 runtime capability shape 与 tool runtime contract；与 tool-registry.ts 同分支推进	3
zn-ai/electron/gateway/handlers/chat.ts	接管 chat.send 主编排，串联 runtime context、planner、executor、transcript 写回与多轮续接	SA-4	SA-2 SA-3 SA-5	必须等 runtime-context.ts、tool-runtime.ts、skill-planner.ts 的契约稳定后再合并；其他 agent 不直接改这个文件	4
zn-ai/src/components/chat/ChatMessageList.tsx	消费统一 transcript / tool_result / toolStatuses，渲染 tool 卡片、错误、摘要、最终回答	SA-6	SA-4 SA-7	必须等 chat-model.ts 与 handlers/chat.ts 稳定后接入；优先做通用渲染，再做类型增强	5

推荐按下面的节奏合并：

1. 先合并 chat-model.ts 的 schema 冻结 PR。
2. 再并行推进 runtime-context.ts、tool-runtime.ts、skill-planner.ts，但以契约评审通过为合并门槛。
3. 然后由 SA-4 合并 handlers/chat.ts，把前三者正式编排进主链路。
4. 最后由 SA-6 合并 ChatMessageList.tsx，避免 UI 反向驱动协议。

这 6 个文件对应的辅助文件跟随关系建议如下：

• runtime-context.ts 对应辅助文件：skill-capability-registry.ts、skill-capability-parser.ts、必要时 handlers/skills.ts
• tool-runtime.ts 对应辅助文件：BaseProvider.ts、OpenAIProvider.ts
• skill-planner.ts 对应辅助文件：tool-registry.ts、必要时 gateway/types.ts
• handlers/chat.ts 对应辅助文件：session-store.ts、必要时 src/stores/chat.ts
• ChatMessageList.tsx 对应辅助文件：src/pages/Home/index.tsx、新增 tool result 展示组件

如果要把冲突降到最低，可以把这张表当成 branch / PR 边界：

• SA-1 不直接改 handlers/chat.ts，而是通过 capability schema 和 registry 模块接入
• SA-2 不在 provider 内重做 planner，而是只冻结 runtime contract
• SA-3 不直接改 UI，只输出 planner decision 与 registry 结构
• SA-4 只在前三项契约稳定后改 handlers/chat.ts
• SA-6 只消费共享协议，不反向决定 gateway 数据结构

11. 波次安排

Wave 1

当前状态：已完成

现状：

• 核心契约、registry、planner 和 tool runtime 已经冻结并落地

• 第一条样板链路已经跑通，不再停留在纯设计阶段

• SA-1 Skill Capability Registry

• SA-2 Provider 与 Tool Runtime

• SA-3 Planner / Tool Registry

目标：

• 先冻结最核心接口：skill capability schema、tool runtime contract、planner contract

Wave 2

当前状态：部分完成

现状：

• transcript 回写和样板附件链路已经进入主聊天编排

• 但 runtime 与 Skills 页的同步，以及表格专项 UI 可视化还没有全部完成

• SA-5 Attachment / File Skill Input

• SA-4 Chat Orchestration / Transcript

目标：

• 在已冻结契约上，把样板链路接入主聊天编排

Wave 3

当前状态：部分完成

现状：

• 通用 tool UI 和一部分回归验证已经启动

• 但 provider 能力矩阵、完整 smoke 和 rollout 收口还没有完成

• SA-6 Renderer Tool UI

• SA-7 Testing / Smoke / Rollout

目标：

• 把用户体验和回归验证补齐

12. 协作约束

为避免冲突，建议遵守这 5 条：

1. 每个 sub-agent 只改自己负责的文件，不跨写别人的主文件。
2. zn-ai/electron/gateway/handlers/chat.ts 只归 SA-4，其他人不要直接改。
3. zn-ai/src/stores/chat.ts 只归 SA-5，UI agent 不要同时改这个文件。
4. zn-ai/electron/gateway/types.ts 由 SA-1 牵头冻结，其他 agent 只在评审后接入。
5. 主协调 agent 统一做接口冻结、合并、回归验证，不让多个 agent 反复改同一入口。

13. 功能交叉与冲突清单

这一节把真正会互相卡住的交叉点单独列出来。

12.1 冲突 A：chat.send 是所有能力的汇合点

交叉功能：

• skill 可见性
• planner 结果接入
• tool runtime 执行
• 附件输入
• transcript 写回
• final answer 回传

核心文件：

• zn-ai/electron/gateway/handlers/chat.ts

处理规则：

• 只允许 SA-4 直接修改
• SA-1、SA-2、SA-3、SA-5 通过契约和辅助模块接入

12.2 冲突 B：src/stores/chat.ts 同时承担“附件状态”和“聊天执行状态”

交叉功能：

• 附件 staging
• tool 状态消费
• pendingFinal 状态
• UI 展示状态

核心文件：

• zn-ai/src/stores/chat.ts

处理规则：

• SA-5 主责 store shape
• SA-6 尽量通过 selector 和 helper 消费，不重写 store 结构

12.3 冲突 C：事件协议同时影响 runtime、store、UI

交叉功能：

• tool:status
• chat:final
• 未来的 tool_use / tool_result / thinking
• runtime refresh

核心文件：

• zn-ai/electron/gateway/types.ts
• zn-ai/runtime-shared/shared/chat-model.ts

处理规则：

• 先冻结 gateway event contract
• 再冻结 transcript/chat-model contract
• UI 最后接入，不反向驱动协议改名

12.4 冲突 D：provider 能力和 planner/runtime 边界容易混淆

交叉功能：

• provider 是否支持 tool loop
• runtime 如何继续二次调用模型
• planner 与 executor 谁负责决策

核心文件：

• zn-ai/electron/providers/BaseProvider.ts
• zn-ai/electron/providers/OpenAIProvider.ts
• zn-ai/electron/gateway/tool-runtime.ts
• zn-ai/electron/gateway/skill-planner.ts

处理规则：

• SA-2 先冻结 provider/runtime 边界
• SA-3 再实现 planner，不在 provider 内重复做编排

12.5 冲突 E：skill metadata 抽取与 renderer 展示不要耦合

交叉功能：

• SKILL.md 抽取
• capability schema
• UI 上如何显示 skill 名称、说明、输入输出

处理规则：

• SA-1 负责 runtime capability schema
• SA-6 只能消费 schema，不反过来决定抽取字段

14. 最小落地建议

如果本轮只做最小可行闭环，优先只做这 6 件事：

1. 聊天发送前读取 enabled skills，并把它们注入 runtime context。
2. 建立通用 skill capability registry，而不是只处理 minimax-xlsx。
3. 为聊天 runtime 增加最小 tool loop，不再只走纯文本 provider。
4. 让文件类附件进入统一 skill 输入链路。
5. 把 tool_result 写回 session history，保证多轮可续接。
6. 在聊天 UI 里把执行过程展示成 tool 卡片，而不是只显示最终一句话。

15. 非目标

这一版清单默认不把下面内容作为首批阻塞项：

• skill 市场页样式优化
• 为每一个 skill 都单独做精细化 UI 定制
• 完整复刻 ClawX 的所有 execution graph 细节
• 与 skill 运行时无关的 channel/plugin 改造

注意：

• “所有 skills 一次性通用化接入聊天运行时”不再是非目标
• 但“所有 skills 一次性都达到同等体验质量”仍然不是首批目标

16. 建议先开工的代码入口

• zn-ai/electron/gateway/handlers/chat.ts
• zn-ai/electron/gateway/runtime-context.ts
• zn-ai/electron/gateway/handlers/skills.ts
• zn-ai/electron/providers/BaseProvider.ts
• zn-ai/electron/providers/OpenAIProvider.ts
• zn-ai/src/stores/chat.ts
• zn-ai/src/components/chat/ChatMessageList.tsx
• zn-ai/electron/api/routes/files.ts
• 新增 zn-ai/electron/gateway/skill-capability-registry.ts
• 新增 zn-ai/electron/gateway/skill-capability-parser.ts
• 新增 zn-ai/electron/gateway/tool-registry.ts
• 新增 zn-ai/electron/gateway/skill-planner.ts

17. Progress Update (2026-04-24)

This checkpoint extends the "first batch of real generic skill execution adapters" beyond xlsx/minimax-xlsx and lands the first reusable document-family, search-family, browser-family, and command-family runtimes.

Completed in this round:

• zn-ai/electron/gateway/chat-tooling.ts
  • Added a real document adapter for enabled docx, pptx, and pdf skills.
  • Added Node-side analyzers for .docx, .pptx, and .pdf.
  • Added real search adapters for brave-web-search and tavily-search.
  • Added a browser-category adapter so browser-capable skills can reuse the managed browser.open_url runtime.
  • Added a command-category adapter that keeps find-skills on the safe ClawHub path and also executes generic command-style skills from safe manifest command templates or a single local scripts/ entrypoint.
  • Reads skill credentials from saved skill config (apiKey / env) instead of relying only on process env.
  • Normalizes Brave and Tavily responses into shared search-results payloads and URL artifacts.
  • Reused the same tool_runtime -> tool_result -> transcript path as spreadsheet analysis.
  • Kept unsupported generic skills on capability-aware blocked results instead of silently falling through.
• zn-ai/src/components/chat/ChatMessageList.tsx
  • Added a dedicated search-result card for query, provider, answer, ranked results, and install commands.
  • Reused the same card for command-style discovery results such as find-skills.
• zn-ai/electron/gateway/skill-capability-parser.ts
  • Tightened file-extension inference so URL-like fragments such as .search or .results no longer become fake input extensions.
  • Tightened auth detection to prefer explicit auth/env signals and avoid substring false positives.
  • Promoted office-style document skills into the shared document-analysis render shape.
• zn-ai/tests/chat-tooling.test.ts
  • Added execution regressions for .docx, .pptx, and .pdf.
  • Added execution regressions for brave-web-search and tavily-search.
  • Added execution regressions for browser-capable skills, find-skills, and generic command-style skills that run from manifest command templates or local script entrypoints.
  • Kept .xls fallback coverage and generic blocked-state coverage.
• zn-ai/tests/chat-message-list.test.tsx
  • Added UI regressions for dedicated search cards and command-style install-command rendering.
• zn-ai/tests/skill-capability-parser.test.ts
  • Added parser regressions for document capability classification, URL-like extension filtering, and auth detection.

Current first-batch runtime coverage:

• Spreadsheet execution: .xls, .xlsx, .xlsm, .csv, .tsv
• Document execution: .docx, .pptx, .pdf
• Search execution: brave-web-search, tavily-search
• Browser execution: browser-capable skills that map to explicit URL open flows
• Command execution: find-skills through ClawHub search, plus generic command-style skills that expose a safe single-command template or one local scripts/ entrypoint
• Generic non-document skills without a real adapter: still blocked with explicit reasons such as missing_required_env, user_authorization_required, or skill_runtime_not_implemented

What is still not done:

• Browser/search/command category executors now exist, but multi-step shell flows, install/login/setup commands, and other unsafe command patterns are still intentionally blocked. Generic command execution is limited to safe single-command templates and local script entrypoints.
• Cross-type adapter manifesting and large-scale skill onboarding are still follow-up work after this checkpoint.

Verification for this checkpoint:

• pnpm typecheck
• pnpm exec vitest run tests/skill-capability-parser.test.ts tests/chat-tooling.test.ts
• pnpm exec vitest run tests/chat-provider-tool-loop.test.ts tests/chat-store-runtime-refresh.test.ts tests/chat-runtime-context.test.ts tests/runtime-context-capabilities.test.ts tests/skill-planner.test.ts tests/chat-tooling.test.ts tests/skill-capability-parser.test.ts tests/chat-message-list.test.tsx