自动同步: 2026-03-14 02:10

2026-03-14 02:10:08 +08:00
parent 8da5f11591
commit 3b83bbb929
52 changed files with 4378 additions and 1930 deletions
@@ -0,0 +1,428 @@
+# 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` 添加状态管理命令。
@@ -0,0 +1,142 @@
+# KB-Workflow 稳定性重构 - 实施计划
+
+**目标：** 重构 kb-workflow 技能体系，确保工作流稳定可靠执行
+**方案：** 全面重构（文档 + 代码 + 状态管理）
+**预计总时间：** 120 分钟
+
+---
+
+## Checkpoint 1: 主 SKILL.md 重构 (P1)
+
+**预计时间：** 30 分钟
+
+- [ ] Task 1.1: 编写状态机定义表格
+  - **Action:** 定义 9 个状态及前置/后置条件
+  - **Verify:** 表格完整，覆盖所有流程分支
+
+- [ ] Task 1.2: 重写步骤模板
+  - **Action:** 使用统一模板重写 8 个步骤
+  - **Verify:** 每个步骤包含前置条件、执行命令、成功标准、失败处理
+
+- [ ] Task 1.3: 添加端到端成功示例
+  - **Action:** 编写 B站视频完整处理流程示例
+  - **Verify:** 示例包含每个步骤的输入输出
+
+- [ ] Task 1.4: 添加常见错误处理示例
+  - **Action:** 编写 403 下载失败、无字幕、AI 调用失败等场景
+  - **Verify:** 覆盖 SkillBug.md 中记录的问题
+
+- [ ] Task 1.5: 整理环境变量清单
+  - **Action:** 汇总所有必需/可选环境变量到一处
+  - **Verify:** 清晰标注哪些必需、哪些可选
+
+---
+
+## Checkpoint 2: 子技能 SKILL.md 统一 (P2)
+
+**预计时间：** 40 分钟
+
+- [ ] Task 2.1: kb-link-parser SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.2: kb-bilibili-metadata SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.3: kb-bilibili-content SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.4: kb-zhihu-metadata SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.5: kb-zhihu-content SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.6: kb-whisper SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.7: kb-ocr-processor SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.8: kb-deep-analyzer SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+- [ ] Task 2.9: kb-funasr SKILL.md
+  - **Action:** 添加输出格式 Schema + 成功/错误示例
+  - **Verify:** 子代理能理解输出要求
+
+---
+
+## Checkpoint 3: 状态管理代码 (P3)
+
+**预计时间：** 30 分钟
+
+- [ ] Task 3.1: 设计 state.json 结构
+  - **Action:** 定义完整的状态文件 Schema
+  - **Verify:** 结构能表示所有必要信息
+
+- [ ] Task 3.2: 实现 --init-state 命令
+  - **Action:** 编写创建初始状态的代码
+  - **Verify:** 能正确生成 state.json
+
+- [ ] Task 3.3: 实现 --get-state 命令
+  - **Action:** 编写查询状态的代码
+  - **Verify:** 能正确返回当前状态
+
+- [ ] Task 3.4: 实现 --advance-step 命令
+  - **Action:** 编写推进步骤的代码
+  - **Verify:** 能正确更新状态
+
+- [ ] Task 3.5: 实现 --record-error 命令
+  - **Action:** 编写记录错误的代码
+  - **Verify:** 能正确记录错误信息
+
+- [ ] Task 3.6: 实现 --resume 命令
+  - **Action:** 编写获取恢复指令的代码
+  - **Verify:** 能返回下一步应该执行的命令
+
+- [ ] Task 3.7: 更新 SKILL.md
+  - **Action:** 添加状态命令用法说明
+  - **Verify:** 主代理能理解如何使用状态管理
+
+---
+
+## Checkpoint 4: kb_utils.py 验证模块 (P4)
+
+**预计时间：** 20 分钟
+
+- [ ] Task 4.1: 定义 OUTPUT_SCHEMAS
+  - **Action:** 为每个步骤定义输出 Schema
+  - **Verify:** Schema 覆盖所有必要字段
+
+- [ ] Task 4.2: 实现 validate_output 函数
+  - **Action:** 编写验证逻辑
+  - **Verify:** 能正确检测格式错误
+
+- [ ] Task 4.3: 实现 format_success 函数
+  - **Action:** 编写成功输出格式化
+  - **Verify:** 输出格式统一
+
+- [ ] Task 4.4: 实现 format_error 函数
+  - **Action:** 编写错误输出格式化
+  - **Verify:** 输出格式统一
+
+- [ ] Task 4.5: 更新子技能代码
+  - **Action:** 修改各子技能 .py 文件导入使用
+  - **Verify:** 所有子技能输出格式统一
+
+---
+
+## 验证标准
+
+- [ ] 所有 Checkpoint 完成
+- [ ] 用一个真实 B站链接测试完整流程
+- [ ] 测试断点续传功能
+- [ ] 用户确认满意