# QianjiangClaw 技能体系与运行时依赖规划

## 1. 目标

这份文档用于定义两层能力：

- 技能体系：用户在界面里看到和选择的能力入口
- 底层依赖体系：小龙虾实际执行任务所需要的运行时、库、工具和外部组件

核心原则：

- 用户应理解“我在使用什么能力”，而不是“我在安装什么库”
- 高频、通用、直接影响首用体验的依赖应随安装包预装
- 低频、体积大、业务定制强的依赖可以按需动态安装
- 技能中心展示的是业务能力；依赖体系由安装包和运行时托管

## 2. 技能体系

### 2.1 内置技能

这些能力应作为默认内置技能出现在产品中，用户无需额外理解底层依赖。

| 技能名称 | 目标能力 | 典型任务 |
|---|---|---|
| 聊天问答 | 通用问答、解释、改写、总结 | 问答、写邮件、改文案、总结会议 |
| 文档处理 | 读取和整理常见文档 | 总结 `txt/md/docx/pdf`、对比文档、抽取重点 |
| 表格处理 | 读取和分析表格数据 | 统计 Excel、筛选 CSV、汇总报表、生成表格结论 |
| 代码与脚本 | 处理工程和脚本任务 | 改代码、跑脚本、生成小工具、分析日志 |
| 文件整理 | 管理本地文件 | 批量重命名、归档、搜索、导出、移动文件 |
| 网页信息处理 | 获取和清洗网页内容 | 抓页面、提取文章、汇总网页信息 |
| 运行诊断 | 排障与运行状态检查 | 导出诊断、查看日志、检查 runtime/Gateway 状态 |

### 2.2 后续扩展技能

这些能力可以作为第二批或按行业定制技能上线。

| 技能名称 | 目标能力 | 说明 |
|---|---|---|
| 数据可视化 | 图表和趋势输出 | 面向表格和统计结果的图表生成 |
| OCR 文档识别 | 扫描件/图片文字提取 | 属于重依赖能力，不建议第一批预装 |
| 浏览器自动化 | 表单填写、网页操作 | 依赖浏览器驱动和更重的自动化能力 |
| 企业系统接入 | 内部业务系统联动 | 取决于客户系统和定制接口 |
| IM/Office 协作 | 企业 IM、邮件、Office 协同 | 强业务定制能力 |

## 3. 运行时依赖体系

### 3.1 建议预装的基础依赖

这些依赖属于高频、稳定、跨场景通用，建议作为 bundled runtime 的标准组成部分。

| 依赖 | 用途 | 是否预装 |
|---|---|---|
| Python | 通用脚本执行基础 | 是 |
| openpyxl | `.xlsx` 读写和基础表格处理 | 是 |
| pandas | 表格统计、清洗、聚合 | 是 |
| requests | HTTP 请求 | 是 |
| beautifulsoup4 | HTML 解析 | 是 |
| lxml | 更稳的 HTML/XML 解析 | 是 |
| pypdf | PDF 文本提取 | 是 |
| python-docx | Word 文档读取 | 是 |
| charset-normalizer | 编码识别和处理 | 是 |
| pyyaml | YAML/配置处理 | 是 |

### 3.2 建议按需动态安装的扩展依赖

这些依赖不适合作为安装包第一批默认预装内容。

| 依赖 | 用途 | 是否默认预装 |
|---|---|---|
| matplotlib | 图表生成 | 否 |
| seaborn | 统计图表美化 | 否 |
| pyxlsb | `.xlsb` 文件解析 | 否 |
| camelot / tabula | PDF 表格抽取 | 否 |
| playwright / selenium | 浏览器自动化 | 否 |
| OCR 相关依赖 | 图片识别、票据识别、扫描件处理 | 否 |
| 数据库驱动 | MySQL/Postgres/SQL Server 等接入 | 否 |
| 企业专有 SDK | 客户内部系统接入 | 否 |

## 4. 技能与依赖映射

| 技能 | 必需依赖 | 建议预装 | 可选扩展 |
|---|---|---|---|
| 聊天问答 | OpenClaw runtime、LLM 配置 | 是 | 无 |
| 文档处理 | Python、pypdf、python-docx、charset-normalizer | 是 | OCR |
| 表格处理 | Python、openpyxl、pandas | 是 | pyxlsb、图表库 |
| 代码与脚本 | Python、本地命令执行能力 | 是 | Node/其他语言工具链 |
| 文件整理 | Python、本地文件工具 | 是 | 无 |
| 网页信息处理 | requests、beautifulsoup4、lxml | 是 | playwright/selenium |
| 运行诊断 | 日志、诊断导出、runtime manager | 是 | 无 |

## 5. 预装与动态安装的判断标准

### 5.1 应预装

满足以下任一条件的依赖应优先预装：

- 高频使用
- 影响首次任务成功率
- 属于核心产品能力
- 体积可接受，版本稳定

当前最明确需要预装的是：

- Python
- openpyxl
- pandas
- requests
- beautifulsoup4
- pypdf
- python-docx
- charset-normalizer
- pyyaml

### 5.2 可动态安装

满足以下特征的依赖更适合按需安装：

- 体积较大
- 低频使用
- 强行业/客户定制
- 平台兼容性复杂

例如：

- 浏览器自动化
- OCR
- 高级图表
- 数据库驱动
- 客户专有工具链

## 6. 当前项目对应的落地建议

### 6.1 第一批必须补齐

为了让“安装包开箱可用”，当前最优先要做到：

1. bundled runtime 预装 Python
2. bundled runtime 预装 `openpyxl`
3. bundled runtime 预装 `pandas`
4. bundled runtime 预装基础文档/网页处理依赖
5. 安装后无需首次任务再 `pip install`

### 6.2 第一批用户可见技能

技能中心第一批建议只放这几项：

- 工作台问答
- 表格处理
- 文档处理
- 文件整理
- 运行诊断

### 6.3 第二批再扩展

当运行时稳定后，再增加：

- 网页自动化
- OCR
- 数据可视化
- 企业系统接入

## 7. 后续实施顺序

### 阶段 1

- 固定第一批内置技能清单
- 固定第一批 bundled runtime 预装依赖清单
- 在安装包构建流程中把这些依赖真正打进去

### 阶段 2

- 技能中心按中文产品页展示这些技能
- 每个技能补充说明、适用场景、输入输出示例

### 阶段 3

- 增加动态依赖安装机制
- 增加依赖安装状态提示和失败恢复
- 区分“预装能力”和“扩展能力”

### 阶段 4

- 对行业型技能做单独打包或远程下发
- 引入更细的权限、积分和套餐控制

## 8. 当前结论

当前小龙虾已经可以通过动态安装依赖完成 Excel 统计任务，说明架构可行。

但正式产品不应长期依赖“首次执行时现场装库”的方式。正确方向应是：

- 技能中心内置“表格处理”等核心技能
- bundled runtime 预装与这些技能对应的高频基础依赖
- 用户只需要选择技能和下任务，不需要理解底层是否安装过 `openpyxl/pandas`
