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

agents/thinker/workspace/memory/plans/kb-workflow-refactor.md

@@ -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站链接测试完整流程
+- [ ] 测试断点续传功能
+- [ ] 用户确认满意