创建第一个任务
如何写清楚任务、选择执行方式，并让 Agent 更稳定地交付结果。
Poco 的任务不是普通聊天。一次任务会进入会话，系统会为它创建运行记录、装配能力、准备工作区，再交给 Poco Agent 执行。你写得越清楚，Poco Agent 越容易少走弯路，最终产物也越稳定。
第一次使用时，不要急着把所有能力都打开。先把任务目标、范围和验收写清楚，再按需要选择仓库、附件、浏览器和计划模式。
选择任务入口
| 入口 | 推荐使用方式 |
|---|---|
| 首页新建任务 | 快速发起一次普通任务 |
| Agent 工作台 | 使用团队预设的指令、能力和提问示例 |
| 新任务 | 临时选择 MCP、Skills、插件、浏览器等能力 |
| 定时任务 | 让同类任务按周期自动运行 |
如果你不确定从哪里开始，优先使用首页或左侧导航里的新任务入口。
写清楚任务
一个稳定的任务通常包含四件事：
- 目标：你希望 Agent 最终完成什么。
- 背景：相关仓库、文件、业务规则或输入材料。
- 约束：不要做什么、必须遵守什么格式。
- 验收：怎样判断结果可用。
不要只写“帮我优化一下”。Poco Agent 会自主规划和调用工具，如果目标太宽，执行路径会变得不可控。
代码分析示例：
请检查 backend 中会话创建接口的实现，找出可能导致重复创建会话的问题。
要求：
1. 只分析代码，不修改文件。
2. 输出问题位置、触发条件和修复建议。
3. 如果证据不足，请明确说明还需要补充什么日志或测试。文档产出示例：
请基于当前仓库的部署配置，生成一份面向运维同学的上线检查清单。
范围：
- 只覆盖 Backend、Executor Manager、Executor、Frontend、对象存储和数据库。
- 不写代码实现细节。
输出要求：
1. 使用 Markdown。
2. 每个检查项包含“检查内容、检查方法、失败处理建议”。
3. 最后补一节“上线前 10 分钟快速确认”。选择执行方式
| 执行方式 | 适合场景 | 注意点 |
|---|---|---|
| 直接执行 | 目标明确、风险较低 | Agent 会直接开始操作 |
| 计划模式 | 代码修改、发布、跨模块任务 | 先审批计划，再允许执行 |
| 指定时间执行 | 希望稍后运行 | 需要确认时间和时区 |
| 夜间执行 | 长任务、低优先级任务 | 适合不急的批处理 |
涉及生产配置、数据库、权限、删除数据、批量修改、发布流程等高风险任务时，建议使用计划模式。计划模式下，Poco Agent 会先给出执行计划，你批准后才进入实际执行阶段。
计划审批时重点看四点：
- 是否覆盖你的真实目标。
- 是否会修改不该修改的范围。
- 是否说明了验证方式。
- 是否有明显过度设计或无关动作。
使用附件和仓库
可以上传 PDF、Markdown、图片、日志、需求文档等。长文本直接粘贴时，系统也会整理成文件，方便 Poco Agent 阅读。
附件会作为本次运行输入放入工作区的 inputs/ 目录。它适合提供材料，不适合当作需要修改的正式产物。如果你希望 Poco Agent 基于附件生成新文件，请明确说“读取附件后，在工作区生成新的 Markdown/HTML/表格”。
如果任务依赖代码仓库，建议写清楚：
仓库：poco-ai-agent
范围：frontend/features/webhooks 和 backend/app/services/webhook_service.py
目标：确认 WebHook 失败重试逻辑是否和文档一致。仓库任务建议先做连通性检查，避免 Agent 启动后才发现无权限。
浏览器能力
开启浏览器后，Poco Agent 可以访问网页、查看页面效果或做自动化操作。它适合：
- 检查前端页面渲染。
- 登录后台系统读取页面信息。
- 预览 HTML 产物。
- 做网页表单或流程验证。
纯文本分析、代码阅读、文档写作一般不需要开启浏览器。
如果任务需要登录态，建议先在远程浏览器中完成登录，再发起任务。登录态复用依赖系统同步，刚登录完立即运行时，如果页面状态没有同步完成，可能需要稍等或重新触发任务。
常用任务模板
代码审查：
请审查最近一次提交，重点关注运行时错误、边界条件和缺失测试。
按严重程度排序输出问题，并给出文件位置。文档生成：
请根据当前仓库的部署配置，生成一份面向运维同学的上线检查清单。
要求简洁、可执行，包含环境变量、数据库、对象存储和回滚检查。问题定位：
用户反馈定时任务偶发不执行。请从 executor_manager 和 backend 的调度链路入手排查。
先列出可能原因，再说明需要查看哪些日志或数据表。能力沉淀：
帮我梳理下上述的所有流程和关键动作，做成一套标准的Skills，每个月当我需要整理当月发票时自动触发。定时任务：
请每天 09:00 生成昨天失败任务巡检报告。
要求：
1. 按失败原因分类。
2. 标出需要人工处理的会话。
3. 生成 report.html，方便发布中心自动发布。
4. 失败时通知我，成功时不通知。使用技巧
- 一次任务只交付一个主要目标，不要把“修 Bug、写文档、重构架构、上线部署”混在一起。
- 输出格式提前说明，例如“Markdown”“表格”“HTML 页面”“PR 描述”。
- 只想分析时，明确写“不要修改文件”。
- 需要产物时，明确写“请生成文件”，并说明文件名或入口文件。
- 任务中途方向小幅变化，继续追问即可；目标彻底改变时，新建会话更干净。
- 不确定方案时用计划模式，让 Poco Agent 先把路径讲清楚。