139 lines
3.6 KiB
Markdown
139 lines
3.6 KiB
Markdown
|
# Copilot SDK 自动任务脚本使用说明
|
|||
|
|
|
|||
|
|
本目录提供了一个通用任务执行脚本，以及两个示例任务脚本：
|
|||
|
|
- `auto_programming_task.py`（通用）
|
|||
|
|
- `run_mindmap_action_to_tool.sh`（示例：mind map action → tool）
|
|||
|
|
- `run_infographic_action_to_tool.sh`（示例：infographic action → tool）
|
|||
|
|
|
|||
|
|
## 1. 先决条件
|
|||
|
|
|
|||
|
|
- 在仓库根目录执行（非常重要）
|
|||
|
|
- Python 3 可用
|
|||
|
|
- 当前环境中可正常使用 Copilot SDK / CLI
|
|||
|
|
|
|||
|
|
建议先验证：
|
|||
|
|
|
|||
|
|
python3 plugins/debug/copilot-sdk/auto_programming_task.py --help | head -40
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 核心行为（当前默认）
|
|||
|
|
|
|||
|
|
`auto_programming_task.py` 默认是 **两阶段自动执行**：
|
|||
|
|
|
|||
|
|
1) 先规划（Planning）：AI 根据你的需求自动补全上下文、扩展为可执行计划。
|
|||
|
|
2) 再执行（Execution）：AI 按计划直接改代码并给出结果。
|
|||
|
|
|
|||
|
|
如果你要关闭“先规划”，可使用 `--no-plan-first`。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 可复制命令（通用）
|
|||
|
|
|
|||
|
|
### 3.1 最常用：直接写任务文本
|
|||
|
|
|
|||
|
|
python3 plugins/debug/copilot-sdk/auto_programming_task.py \
|
|||
|
|
--task "把 plugins/actions/xxx/xxx.py 转成 plugins/tools/xxx-tool/ 下的单文件 Tool 插件。保留 i18n 和语言回退逻辑。不要升级 SDK 版本。" \
|
|||
|
|
--cwd "$PWD" \
|
|||
|
|
--model "gpt-5.3-codex" \
|
|||
|
|
--reasoning-effort "xhigh" \
|
|||
|
|
--timeout 3600 \
|
|||
|
|
--stream \
|
|||
|
|
--trace-events \
|
|||
|
|
--heartbeat-seconds 8
|
|||
|
|
|
|||
|
|
### 3.2 使用任务文件（长任务推荐）
|
|||
|
|
|
|||
|
|
先写任务文件（例如 task.txt），再执行：
|
|||
|
|
|
|||
|
|
python3 plugins/debug/copilot-sdk/auto_programming_task.py \
|
|||
|
|
--task-file "./task.txt" \
|
|||
|
|
--cwd "$PWD" \
|
|||
|
|
--model "gpt-5.3-codex" \
|
|||
|
|
--reasoning-effort "xhigh" \
|
|||
|
|
--timeout 3600 \
|
|||
|
|
--stream \
|
|||
|
|
--trace-events \
|
|||
|
|
--heartbeat-seconds 8
|
|||
|
|
|
|||
|
|
### 3.3 关闭规划阶段（仅直接执行）
|
|||
|
|
|
|||
|
|
python3 plugins/debug/copilot-sdk/auto_programming_task.py \
|
|||
|
|
--task "你的任务" \
|
|||
|
|
--cwd "$PWD" \
|
|||
|
|
--model "gpt-5-mini" \
|
|||
|
|
--reasoning-effort "medium" \
|
|||
|
|
--timeout 1800 \
|
|||
|
|
--no-plan-first
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 可复制命令（示例脚本）
|
|||
|
|
|
|||
|
|
### 4.1 Mind Map 示例任务
|
|||
|
|
|
|||
|
|
./plugins/debug/copilot-sdk/run_mindmap_action_to_tool.sh
|
|||
|
|
|
|||
|
|
### 4.2 Infographic 示例任务
|
|||
|
|
|
|||
|
|
./plugins/debug/copilot-sdk/run_infographic_action_to_tool.sh
|
|||
|
|
|
|||
|
|
说明：这两个脚本是“固定任务模板”，适合当前仓库；复制到其他仓库时通常需要改任务内容。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 结果如何判定“完成”
|
|||
|
|
|
|||
|
|
建议同时满足以下条件：
|
|||
|
|
|
|||
|
|
1) 进程退出码为 0
|
|||
|
|
2) 输出中出现阶段结束信息（含最终摘要）
|
|||
|
|
3) 看到 `session.idle`（若是 `session.error` 则未完成）
|
|||
|
|
4) `git diff --name-only` 显示改动范围符合你的约束
|
|||
|
|
|
|||
|
|
可复制检查命令：
|
|||
|
|
|
|||
|
|
echo $?
|
|||
|
|
git diff --name-only
|
|||
|
|
git status --short
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 参数速查
|
|||
|
|
|
|||
|
|
- `--task`：直接传任务文本
|
|||
|
|
- `--task-file`：从文件读取任务文本（与 `--task` 二选一）
|
|||
|
|
- `--cwd`：工作区目录（建议用 `$PWD`）
|
|||
|
|
- `--model`：模型（例如 `gpt-5.3-codex`、`gpt-5-mini`）
|
|||
|
|
- `--reasoning-effort`：`low|medium|high|xhigh`
|
|||
|
|
- `--timeout`：超时秒数
|
|||
|
|
- `--stream`：实时输出增量内容
|
|||
|
|
- `--trace-events`：输出事件流，便于排错
|
|||
|
|
- `--heartbeat-seconds`：心跳输出间隔
|
|||
|
|
- `--no-plan-first`：关闭默认“先规划后执行”
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 常见问题
|
|||
|
|
|
|||
|
|
### Q1：为什么提示找不到脚本？
|
|||
|
|
你大概率不在仓库根目录。先执行：
|
|||
|
|
|
|||
|
|
pwd
|
|||
|
|
|
|||
|
|
确认后再运行命令。
|
|||
|
|
|
|||
|
|
### Q2：执行很久没有输出？
|
|||
|
|
加上 `--trace-events --stream`，并适当增大 `--timeout`。
|
|||
|
|
|
|||
|
|
### Q3：改动超出预期范围？
|
|||
|
|
把范围约束明确写进任务文本，例如：
|
|||
|
|
|
|||
|
|
“不要修改其他文件代码，可以读取整个项目作为代码库。”
|
|||
|
|
|
|||
|
|
并在完成后用：
|
|||
|
|
|
|||
|
|
git diff --name-only
|
|||
|
|
|
|||
|
|
进行核对。
|