Stp

路径变量说明（本文档通用）：

• <STP_ROOT> = ~/.openclaw/workspace/skills/stp
• <STP_SCRIPTS> = <STP_ROOT>/scripts
• <STP_TASK_LIST> = ~/.openclaw/workspace/task-list
• <STP_TASKS> = ~/.openclaw/workspace/tasks

STP（Structured Task Planning）结构化任务规划与分步执行

功能概述

1. 任务解析：从 Markdown 任务文档加载步骤
2. 确认流程：生成计划书后必须用户确认才能执行（所有模式）
3. 目录管理：自动创建任务专属目录（格式：task-{ID}）
4. 文档生成：生成标准化步骤文档和执行日志
5. 状态跟踪：支持步骤状态标记（待执行/成功/失败）
6. 智能执行：每个步骤作为子任务执行，附带成功判断标准
7. 快速失败：步骤失败立即终止，不尝试替代方案
8. 完整日志：所有 exec 命令和 AI 执行过程完整记录

两种使用模式

模式 A：文件模式（用户提供 Markdown 文档）

用户提供已写好的任务文档路径：

# 完整参数
python3 <STP_SCRIPTS>/execute_task.py --file /path/to/task.md

# 简写参数
python3 <STP_SCRIPTS>/execute_task.py -f /path/to/task.md

流程：

1. 读取 Markdown 任务文档
2. 解析任务名称和执行步骤
3. 生成计划书并展示
4. 等待用户确认 ← 必须确认才能继续
5. 用户确认后创建任务目录并执行

模式 B：自然语言模式（AI 自动生成计划）

用户用自然语言描述任务，AI 自动生成计划书：

# 完整参数
python3 <STP_SCRIPTS>/execute_task.py --nlp "我想查一下腾讯、贵州茅台、Meta 的股票价格"

# 简写参数
python3 <STP_SCRIPTS>/execute_task.py -n "帮我安装 CosyVoice"

流程：

1. 接收自然语言任务描述
2. AI 分析意图并生成 Markdown 计划书
3. 保存计划书到 <STP_TASK_LIST>/<filename>.md
4. 生成计划书并展示
5. 等待用户确认 ← 必须确认才能继续
6. 用户确认后开始执行

两种模式的核心区别

重要提示：

• 两种模式都必须经过用户确认才能执行
• 参数不区分大小写，但建议统一使用小写
• 混用参数时，--file 优先于 --nlp

模式 B：自然语言任务规划流程（Agent 专用）

当用户输入自然语言描述时，主 Agent 需要：

第一步：任务分析与计划生成

1. 理解用户意图：分析自然语言，明确任务目标
2. 拆解执行步骤：将任务分解为可执行的具体步骤
3. 生成计划书：按标准格式生成 Markdown 任务文档
4. 保存到 task-list：~/.openclaw/workspace/task-list/<filename>.md

第二步：展示并确认

📋 任务计划书已生成

任务名称：xxx
文件位置：~/.openclaw/workspace/task-list/xxx.md
步骤数：5

核心执行步骤：
- [ ] 步骤 1：xxx
- [ ] 步骤 2：xxx
...

确认执行：
  输入 "ok" 或 "确认" → 开始执行
  输入 "取消" → 放弃此任务
  输入修改意见 → 我会调整计划后重新展示

第三步：执行或取消

• 确认后：保存任务文档，调用 STP 脚本开始执行
• 取消：不执行，记录日志
• 修改：更新计划书后重新展示

计划书标准格式

# 任务名称

## 任务描述
用户原始需求的简要描述

## 技术方案
- 使用的工具/库/API
- 关键技术约束

## 核心执行步骤
- [ ] 步骤 1：具体描述（含成功标准）
- [ ] 步骤 2：具体描述（含成功标准）
- [ ] 步骤 3：具体描述（含成功标准）

## 预期产出
- 输出文件/结果说明

示例计划书

# 三支股票收盘价查询

## 任务描述
查询腾讯控股、贵州茅台、Meta 三支股票的最新收盘价

## 技术方案
- 使用 AkShare 库查询股票数据
- 支持 A股(沪深)、港股、美股三个市场

## 核心执行步骤
- [ ] 步骤 1：编写基于 AkShare 的股票查询脚本，保存至 `temp/scripts/stock_query.py`
- [ ] 步骤 2：查询贵州茅台（600519.SH）收盘价
- [ ] 步骤 3：查询腾讯控股（00700.HK）收盘价
- [ ] 步骤 4：查询 Meta（META.O）收盘价

## 预期产出
- 三支股票的收盘价信息（股票名称、代码、日期、价格、市场）

模式 A：文件模式使用方式

步骤1：准备 Markdown 任务文档

# 任务名称

## 核心执行步骤
- [ ] 步骤 1：具体描述
- [ ] 步骤 2：具体描述
- [ ] 步骤 3：具体描述

步骤2：运行并确认

python3 <STP_SCRIPTS>/execute_task.py --file /path/to/task.md

输出示例：

========================================
📋 任务计划书已生成
========================================

任务名称：安装 Conda 环境
文件：/Users/scotthuang/task.md
步骤数：4

核心执行步骤：
  - [ ] 步骤 1：下载 Miniforge3
  - [ ] 步骤 2：运行安装脚本
  - [ ] 步骤 3：验证 conda 安装
  - [ ] 步骤 4：创建 cosyvoice 环境

========================================
确认执行：
  输入 "ok" 或 "确认" → 开始执行
  输入 "取消" → 放弃此任务
  输入修改意见 → 我会调整后重新展示
========================================

步骤3：用户确认后自动执行

• ✅ 确认 → 创建任务目录，开始执行
• ❌ 取消 → 终止，不创建任务
• 📝 修改 → 更新文档后重新展示

Agent 执行规范（重要！）

执行每个步骤时，必须记录关键命令和输出：

方法：步骤完成后补记执行日志

1. 执行步骤时：正常用 exec tool 执行命令
2. 步骤完成后：把关键命令和输出写入临时文件，然后用 --exec-file 记录

# 1. 先把执行记录写入临时文件
cat > /tmp/step_exec.log << 'EOF'
[命令1] python3 -c "import akshare; print(akshare.__version__)"
[输出1] AkShare version: 1.18.22
[退出码] 0

[命令2] python3 stock_query.py 600519.SH
[输出2] 贵州茅台 收盘价: 1515.01
[退出码] 0
EOF

# 2. 记录步骤状态时附带执行日志
python3 execute_task.py --log task-8 1 success "脚本执行成功" --exec-file /tmp/step_exec.log

执行日志格式建议

[命令] <执行的完整命令>
[输出] <命令输出（可截断关键部分）>
[退出码] <0=成功, 非0=失败>

任务目录结构

~/.openclaw/workspace/tasks/
└── task-XXX/
    ├── task_steps.md      # 步骤文档（含状态标记和成功标准）
    ├── task_execution.log # 完整执行日志（含所有exec命令）
    ├── result.txt         # 结果汇总
    └── temp/
        ├── scripts/
        └── downloads/

task-list 目录

~/.openclaw/workspace/task-list/
├── stock-query-20260208.md    # 自然语言模式生成的计划书
├── highway-query-20260208.md   # ...
└── ...

状态标记

执行规则（重要！）

1. 原方案优先原则

必须严格按照任务文档中定义的方案执行，禁止擅自更改实现方式。

示例：

❌ 错误做法：原方案要求用 AkShare，实际改用新浪 API
✅ 正确做法：严格使用 AkShare，遇到问题按失败处理

2. 快速失败策略

原则：一步到位，不做替代方案尝试

• 子任务返回「失败」状态 → 立即终止整个任务链
• 不自动重试、不尝试其他实现方式
• 记录失败原因到日志

3. 失败处理

• 方案执行失败 → 立即终止，不尝试替代方案
• 明确记录失败原因（违反方案/技术限制/接口问题）
• 任务结果标记为 FAILED

资源

scripts/

• execute_task.py - 主脚本
  • --file <path> / -f <path>：文件模式
  • --nlp <text> / -n <text>：自然语言模式
  • --subtask <task_id> <step_num>：生成子任务 prompt
  • --log <task_id> <step> <status> [消息]：记录步骤状态
  • --exec <task_id> "<命令>" <exit_code> [输出]：记录 exec
  • --exec-file <path>：从文件读取执行日志（与 --log 配合）
  • 自动记录 exec 命令到日志
  • 自动创建 .task_counter 自增ID

task-list/

• 存放自然语言模式生成的任务计划书
• 路径：<STP_TASK_LIST>
• 文件命名格式：<简短描述>-<YYYYMMDD>.md

使用示例

示例 1：文件模式（推荐用于复杂任务）

# 准备任务文件
cat > ~/task-docs/cosyvoice-install.md << 'EOF'
# Mac M系列芯片安装CosyVoice

## 技术方案
- 使用 Conda 管理环境
- CPU 模式运行（PyTorch）

## 核心执行步骤
- [ ] 步骤 1：下载 Miniforge3 安装脚本
- [ ] 步骤 2：运行安装脚本
- [ ] 步骤 3：验证 conda 安装
- [ ] 步骤 4：创建 cosyvoice 环境
EOF

# 执行（会先展示计划书并等待确认）
python3 <STP_SCRIPTS>/execute_task.py -f ~/task-docs/cosyvoice-install.md

示例 2：自然语言模式（推荐用于临时任务）

# 直接描述需求
python3 <STP_SCRIPTS>/execute_task.py -n "帮我安装 CosyVoice"

示例 3：Agent 集成（主 Agent 调用）

# 用户输入自然语言
user_input = "帮我查一下腾讯和茅台的股票价格"

# Agent 调用自然语言模式
import subprocess
result = subprocess.run([
    'python3', '<STP_SCRIPTS>/execute_task.py', 
    '--nlp', user_input
], capture_output=True, text=True)

# 检查输出，如果是确认状态...
# 读取生成的计划书文件
# 展示给用户确认

注意：stp 是 structured-task-planning 的缩写。