429 lines
11 KiB
Markdown
429 lines
11 KiB
Markdown
# Session: 2026-03-13 04:57:53 UTC
|
|
|
|
- **Session Key**: agent:thinker:main
|
|
- **Session ID**: 39b5e8d4-de3d-4939-bf48-624b99412423
|
|
- **Source**: feishu
|
|
|
|
## Conversation Summary
|
|
|
|
assistant: 好的，我已经收集了所有关键决策。现在让我呈现最终设计方案。
|
|
|
|
---
|
|
|
|
## 📐 设计方案总结
|
|
|
|
### 设计概览
|
|
|
|
**目标：** 重构 kb-workflow 技能体系，确保工作流稳定可靠执行
|
|
|
|
**方案要点：**
|
|
- 全面重构（文档 + 代码 + 状态管理）
|
|
- 文件级状态 + Python 脚本管理
|
|
- 共享验证模块 kb_utils.py
|
|
- 混合示例组织（内嵌核心 + 补充目录）
|
|
- 四阶段迭代实现
|
|
|
|
---
|
|
|
|
### 第一部分：状态管理机制
|
|
|
|
```
|
|
~/work/knowledge-base/
|
|
├── pending/
|
|
│ └── {platform}_{id}.state.json # 新增：工作流状态文件
|
|
```
|
|
|
|
**state.json 结构：**
|
|
```json
|
|
{
|
|
"url": "https://bilibili.com/video/BVxxx",
|
|
"platform": "bilibili",
|
|
"content_id": "BVxxx",
|
|
"content_type": "video",
|
|
"current_step": "metadata",
|
|
"completed_steps": ["env_check", "link_parse"],
|
|
"step_results": {
|
|
"link_parse": {"output_file": "pending/bilibili_BVxxx.link.json"},
|
|
"metadata": {"output_file": "metadata/bilibili_BVxxx.meta.json"}
|
|
},
|
|
"errors": [],
|
|
"created_at": "2026-03-13T12:00:00+08:00",
|
|
"updated_at": "2026-03-13T12:05:00+08:00"
|
|
}
|
|
```
|
|
|
|
**kb_workflow.py 新增命令：**
|
|
```bash
|
|
python3 kb_workflow.py --init-state "[URL]" # 创建初始状态
|
|
python3 kb_workflow.py --get-state "[URL]" # 查询当前状态
|
|
python3 kb_workflow.py --advance-step "[URL]" "metadata" # 推进到下一步
|
|
python3 kb_workflow.py --record-error "[URL]" "错误信息" # 记录错误
|
|
python3 kb_workflow.py --resume "[URL]" # 获取恢复指令
|
|
```
|
|
|
|
---
|
|
|
|
**这部分设计看起来合理吗？**
|
|
user: Conversation info (untrusted metadata):
|
|
```json
|
|
{
|
|
"message_id": "om_x100b540d5e21d530b4b235d9a470ccf",
|
|
"sender_id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"sender": "张青",
|
|
"timestamp": "Fri 2026-03-13 12:22 GMT+8"
|
|
}
|
|
```
|
|
|
|
Sender (untrusted metadata):
|
|
```json
|
|
{
|
|
"label": "张青 (ou_a0f6627b64d2dc8b0236671603d1e47b)",
|
|
"id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"name": "张青"
|
|
}
|
|
```
|
|
|
|
[message_id: om_x100b540d5e21d530b4b235d9a470ccf]
|
|
张青: 可以
|
|
assistant: ### 第二部分：kb_utils.py 验证模块
|
|
|
|
**功能：**
|
|
- 定义统一的 JSON Schema
|
|
- 验证子技能输出
|
|
- 提供格式化工具
|
|
|
|
**模块结构：**
|
|
```python
|
|
# ~/.openclaw/skills/kb-workflow/kb_utils.py
|
|
|
|
# 1. 输出格式 Schema
|
|
OUTPUT_SCHEMAS = {
|
|
"link_parse": {
|
|
"required": ["success", "platform", "content_type", "content_id"],
|
|
"success_field": "success",
|
|
},
|
|
"metadata": {
|
|
"required": ["success", "platform", "content_id", "title"],
|
|
"success_field": "success",
|
|
},
|
|
"content": {
|
|
"required": ["success", "type", "filepath"],
|
|
"success_field": "success",
|
|
},
|
|
"whisper": {
|
|
"required": ["success", "output_files"],
|
|
"success_field": "success",
|
|
},
|
|
"deep_analyze": {
|
|
"required": ["success", "output_file"],
|
|
"success_field": "success",
|
|
},
|
|
}
|
|
|
|
# 2. 验证函数
|
|
def validate_output(step_name: str, output: dict) -> tuple[bool, str]:
|
|
"""验证输出格式，返回 (是否有效, 错误信息)"""
|
|
|
|
# 3. 格式化函数
|
|
def format_success(step: str, data: dict) -> dict:
|
|
"""生成统一格式的成功输出"""
|
|
|
|
def format_error(step: str, error: str) -> dict:
|
|
"""生成统一格式的错误输出"""
|
|
```
|
|
|
|
**子技能集成方式：**
|
|
```python
|
|
# 在各子技能 .py 文件中
|
|
from kb_utils import validate_output, format_success, format_error
|
|
|
|
# 执行完成后
|
|
result = {...}
|
|
is_valid, error_msg = validate_output("metadata", result)
|
|
if not is_valid:
|
|
print(json.dumps(format_error("metadata", error_msg)))
|
|
else:
|
|
print(json.dumps(format_success("metadata", result)))
|
|
```
|
|
|
|
---
|
|
|
|
**这部分设计可以吗？**
|
|
user: Conversation info (untrusted metadata):
|
|
```json
|
|
{
|
|
"message_id": "om_x100b540d6efb8ca8b35b71db8c7e917",
|
|
"sender_id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"sender": "张青",
|
|
"timestamp": "Fri 2026-03-13 12:26 GMT+8"
|
|
}
|
|
```
|
|
|
|
Sender (untrusted metadata):
|
|
```json
|
|
{
|
|
"label": "张青 (ou_a0f6627b64d2dc8b0236671603d1e47b)",
|
|
"id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"name": "张青"
|
|
}
|
|
```
|
|
|
|
[message_id: om_x100b540d6efb8ca8b35b71db8c7e917]
|
|
张青: 可以
|
|
assistant: ### 第三部分：主 SKILL.md 重构
|
|
|
|
**核心改进：**
|
|
|
|
1. **状态机模型** - 明确定义每个状态的前置/后置条件
|
|
2. **决策树可视化** - 用流程图展示分支逻辑
|
|
3. **步骤模板** - 统一每个步骤的描述格式
|
|
|
|
**新 SKILL.md 结构：**
|
|
```markdown
|
|
# KB Workflow
|
|
|
|
## 状态机定义
|
|
|
|
| 状态 | 前置条件 | 执行动作 | 成功后进入 | 失败处理 |
|
|
|------|---------|---------|-----------|---------|
|
|
| init | 用户触发 | 创建 state.json | link_parse | 报错退出 |
|
|
| link_parse | state.json 存在 | 解析链接 | metadata | 记录错误，重试 |
|
|
| metadata | platform 已知 | 提取元数据 | content | 记录错误，重试 |
|
|
| content | 元数据已存在 | 下载内容 | whisper/analyze | 根据错误类型处理 |
|
|
| whisper | 无官方字幕 | 语音识别 | analyze | 尝试 OCR 降级 |
|
|
| analyze | 有文本内容 | AI 深度分析 | archive | **流程失败** |
|
|
| archive | 分析报告存在 | 归档+Git | done | 记录错误，手动处理 |
|
|
| done | - | 汇报完成 | - | - |
|
|
|
|
## 步骤模板（每个步骤包含）
|
|
|
|
### 步骤 N: [名称]
|
|
|
|
**前置条件：**
|
|
- 条件1
|
|
- 条件2
|
|
|
|
**执行命令：**
|
|
```bash
|
|
具体命令
|
|
```
|
|
|
|
**成功标准：**
|
|
- 输出文件存在
|
|
- JSON 格式正确
|
|
- 包含必要字段 X, Y, Z
|
|
|
|
**失败处理：**
|
|
- 错误类型A → 动作A
|
|
- 错误类型B → 动作B
|
|
|
|
**输出示例：**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"必填字段": "..."
|
|
}
|
|
```
|
|
|
|
**错误示例：**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "具体错误信息"
|
|
}
|
|
```
|
|
```
|
|
|
|
---
|
|
|
|
**这个重构方向可以吗？**
|
|
user: Conversation info (untrusted metadata):
|
|
```json
|
|
{
|
|
"message_id": "om_x100b540d64b9a0a8b34ee257f229495",
|
|
"sender_id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"sender": "张青",
|
|
"timestamp": "Fri 2026-03-13 12:29 GMT+8"
|
|
}
|
|
```
|
|
|
|
Sender (untrusted metadata):
|
|
```json
|
|
{
|
|
"label": "张青 (ou_a0f6627b64d2dc8b0236671603d1e47b)",
|
|
"id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"name": "张青"
|
|
}
|
|
```
|
|
|
|
[message_id: om_x100b540d64b9a0a8b34ee257f229495]
|
|
张青: 可以
|
|
assistant: ### 第四部分：实现计划
|
|
|
|
**四阶段迭代：**
|
|
|
|
| 阶段 | 内容 | 预计时间 | 可独立使用 |
|
|
|------|------|---------|-----------|
|
|
| **P1** | 主 SKILL.md 重构 | 30分钟 | ✅ 立即生效 |
|
|
| **P2** | 子技能 SKILL.md 统一 | 40分钟 | ✅ 配合 P1 |
|
|
| **P3** | 状态管理代码 | 30分钟 | ✅ 断点续传 |
|
|
| **P4** | kb_utils.py 验证模块 | 20分钟 | ✅ 格式验证 |
|
|
|
|
**详细任务清单：**
|
|
|
|
**P1: 主 SKILL.md 重构**
|
|
- [ ] 编写状态机定义表格
|
|
- [ ] 重写 8 个步骤（使用统一模板）
|
|
- [ ] 添加端到端成功示例
|
|
- [ ] 添加常见错误处理示例
|
|
- [ ] 整理环境变量清单
|
|
|
|
**P2: 子技能 SKILL.md 统一**
|
|
- [ ] kb-link-parser: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-bilibili-metadata: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-bilibili-content: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-zhihu-metadata: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-zhihu-content: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-whisper: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-ocr-processor: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-deep-analyzer: 添加输出格式 + 成功/错误示例
|
|
- [ ] kb-funasr: 添加输出格式 + 成功/错误示例
|
|
|
|
**P3: 状态管理代码**
|
|
- [ ] 设计 state.json 结构
|
|
- [ ] 实现 --init-state 命令
|
|
- [ ] 实现 --get-state 命令
|
|
- [ ] 实现 --advance-step 命令
|
|
- [ ] 实现 --record-error 命令
|
|
- [ ] 实现 --resume 命令
|
|
- [ ] 更新 SKILL.md 说明状态命令用法
|
|
|
|
**P4: kb_utils.py 验证模块**
|
|
- [ ] 定义 OUTPUT_SCHEMAS
|
|
- [ ] 实现 validate_output 函数
|
|
- [ ] 实现 format_success 函数
|
|
- [ ] 实现 format_error 函数
|
|
- [ ] 更新各子技能 .py 文件导入使用
|
|
|
|
---
|
|
|
|
**设计完成！是否进入 write-plan 阶段，生成详细的实施计划？**
|
|
user: Conversation info (untrusted metadata):
|
|
```json
|
|
{
|
|
"message_id": "om_x100b540d633e84b0b2b051a702c5c2b",
|
|
"sender_id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"sender": "张青",
|
|
"timestamp": "Fri 2026-03-13 12:30 GMT+8"
|
|
}
|
|
```
|
|
|
|
Sender (untrusted metadata):
|
|
```json
|
|
{
|
|
"label": "张青 (ou_a0f6627b64d2dc8b0236671603d1e47b)",
|
|
"id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"name": "张青"
|
|
}
|
|
```
|
|
|
|
[message_id: om_x100b540d633e84b0b2b051a702c5c2b]
|
|
张青: 实施
|
|
assistant: 好的，进入 **write-plan + 执行** 阶段。
|
|
|
|
我先创建计划文件，然后开始执行 P1。
|
|
assistant: 计划已保存。开始执行 **P1: 主 SKILL.md 重构**。
|
|
assistant: **P1 完成！** 主 SKILL.md 已重构，包含：
|
|
- 状态机定义表格
|
|
- 6 个步骤的详细模板（前置条件/执行命令/成功标准/失败处理/示例）
|
|
- 端到端示例
|
|
- 常见错误处理
|
|
|
|
现在开始 **P2: 子技能 SKILL.md 统一**
|
|
user: Conversation info (untrusted metadata):
|
|
```json
|
|
{
|
|
"message_id": "om_x100b540d34d174a0b3c9f1ee9a1f815",
|
|
"sender_id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"sender": "张青",
|
|
"timestamp": "Fri 2026-03-13 12:50 GMT+8"
|
|
}
|
|
```
|
|
|
|
Sender (untrusted metadata):
|
|
```json
|
|
{
|
|
"label": "张青 (ou_a0f6627b64d2dc8b0236671603d1e47b)",
|
|
"id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"name": "张青"
|
|
}
|
|
```
|
|
|
|
[message_id: om_x100b540d34d174a0b3c9f1ee9a1f815]
|
|
张青: 进度如何了
|
|
assistant: 当前进度汇报：
|
|
|
|
| 阶段 | 状态 | 完成度 |
|
|
|------|------|--------|
|
|
| **P1: 主 SKILL.md** | ✅ 完成 | 100% |
|
|
| **P2: 子技能 SKILL.md** | 🔄 进行中 | 5/9 |
|
|
| **P3: 状态管理代码** | ⏳ 待开始 | 0% |
|
|
| **P4: kb_utils.py** | ⏳ 待开始 | 0% |
|
|
|
|
**P2 已完成：**
|
|
- ✅ kb-link-parser
|
|
- ✅ kb-bilibili-metadata
|
|
- ✅ kb-bilibili-content
|
|
- ✅ kb-zhihu-metadata
|
|
- ✅ kb-zhihu-content
|
|
|
|
**P2 剩余：**
|
|
- ⏳ kb-whisper
|
|
- ⏳ kb-ocr-processor
|
|
- ⏳ kb-deep-analyzer
|
|
- ⏳ kb-funasr
|
|
|
|
继续完成 P2...
|
|
user: Conversation info (untrusted metadata):
|
|
```json
|
|
{
|
|
"message_id": "om_x100b540dc61d00b0b3718efd72b20c5",
|
|
"sender_id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"sender": "张青",
|
|
"timestamp": "Fri 2026-03-13 12:54 GMT+8"
|
|
}
|
|
```
|
|
|
|
Sender (untrusted metadata):
|
|
```json
|
|
{
|
|
"label": "张青 (ou_a0f6627b64d2dc8b0236671603d1e47b)",
|
|
"id": "ou_a0f6627b64d2dc8b0236671603d1e47b",
|
|
"name": "张青"
|
|
}
|
|
```
|
|
|
|
[message_id: om_x100b540dc61d00b0b3718efd72b20c5]
|
|
张青: 进度如何了
|
|
assistant: 当前进度汇报：
|
|
|
|
| 阶段 | 状态 | 完成度 |
|
|
|------|------|--------|
|
|
| **P1: 主 SKILL.md** | ✅ 完成 | 100% |
|
|
| **P2: 子技能 SKILL.md** | ✅ 完成 | 9/9 |
|
|
| **P3: 状态管理代码** | 🔄 开始 | 0% |
|
|
| **P4: kb_utils.py** | ⏳ 待开始 | 0% |
|
|
|
|
**P2 已全部完成：**
|
|
- ✅ kb-link-parser
|
|
- ✅ kb-bilibili-metadata
|
|
- ✅ kb-bilibili-content
|
|
- ✅ kb-zhihu-metadata
|
|
- ✅ kb-zhihu-content
|
|
- ✅ kb-whisper
|
|
- ✅ kb-ocr-processor
|
|
- ✅ kb-deep-analyzer
|
|
- ✅ kb-funasr
|
|
|
|
现在开始 **P3: 状态管理代码**，需要修改 `kb_workflow.py` 添加状态管理命令。
|