开发指南
开发指南
Poco 开发规范、验证命令和代码边界。
本页用于帮助开发者快速找到系统链路、代码边界和验证入口。改代码前先确认你改的是哪一段链路：任务创建、运行调度、能力装配、Poco Agent 执行、回调落库、产物交付，还是外部集成。
先建立链路视角
Poco 的核心链路如下：
- Frontend 提交任务、附件、仓库、浏览器和能力选择。
- Backend 创建 Session、User Message 和 Run，并保存配置快照。
- Executor Manager 领取 Run，解析环境变量、MCP、Skills、插件、Subagents、Slash Commands 和附件。
- Executor Manager 准备工作区和容器，把任务交给 Poco Agent 运行时。
- Poco Agent 执行工具、更新 Todo、请求用户确认、写入工作区文件。
- 高频流事件由 Executor 带连续序号直达 Backend，Backend 先推送给前端，再后台批量持久化。
- 普通状态和终态仍由 Executor Manager 转发；实时直达持续失败时，也通过 Manager 批量降级。
- 前端按序号展示实时内容，缺口从历史事件补齐，终态再用服务端消息历史校准。
- 终态后异步导出工作区，触发 WebHook、通知、产物推荐、发布中心等下游动作。
改动时不要只看单个接口。比如“任务完成后没有文件”可能涉及 Poco Agent 是否写入文件、工作区忽略规则、导出状态、文件清单 API 和前端产物面板。
前端开发
前端使用 Next.js 16、React 19、TypeScript、Tailwind CSS v4 和 shadcn/ui。
cd frontend
source ~/.nvm/nvm.sh && nvm use 22
pnpm lint开发页面时需要遵守：
- 用户可见文本使用 i18n。
- 优先复用 shadcn/ui 和项目共享组件。
- 开发业务与办公两套布局前，先阅读业务与办公场景 UI 架构。
- 办公首页的 Mock 边界和后续接口契约记录在办公场景接口待办。
- 新增主题、开发页面或调整配色前，先阅读主题系统与前端配色开发手册；视觉排查与回归验收参考主题视觉验收与踩坑手册。
- 剪贴板复制统一使用共享 copy 工具或组件。
- 不为验证主动运行
pnpm build，除非明确要求。
常见入口：
| 场景 | 重点文件 |
|---|---|
| 首页创建任务 | frontend/features/home/components/home-page-client.tsx、task-composer.tsx |
| 执行页状态 | frontend/features/chat/hooks/use-execution-session.ts |
| 会话消息和人工确认 | frontend/features/chat/components/execution/chat-panel/* |
| 文件产物面板 | frontend/features/chat/components/execution/file-panel/* |
| 定时任务 | frontend/features/scheduled-tasks/* |
| 能力管理 | frontend/features/mcp、skills、plugins、subagents |
| WebHook | frontend/features/webhooks/* |
Python 开发
Python 服务使用 Python 3.12+、FastAPI、SQLAlchemy 和 uv。
Ruff 从仓库根目录运行：
uv run ruff check <path>
uv run ruff format --check <path>Backend 分层边界
Repositories
- 只做数据库操作。
- 不写业务逻辑。
- 返回 SQLAlchemy 模型实例。
Services
- 编排业务逻辑。
- 管理事务。
- 返回 SQLAlchemy 模型或明确的 Pydantic schema。
- 不返回
dict[str, Any]。
API
- 负责依赖注入。
- 负责响应转换。
- 不直接把 ORM 模型传给
Response.success(...)。
关键链路源码
| 链路 | 主要文件 | 读代码重点 |
|---|---|---|
| 任务入队 | backend/app/services/task_service.py | Session/Run 创建、配置快照、输入文件、Agent 绑定 |
| Run 队列 | backend/app/services/run_service.py、backend/app/repositories/run_repository.py | claim、lease、单会话活跃运行限制、失败恢复 |
| Manager 拉取 | executor_manager/app/services/run_pull_service.py | 准备阶段、能力暂存、容器选择、dispatch |
| 能力解析 | executor_manager/app/services/config_resolver.py、*_stager.py | 环境变量替换、MCP/Skill/Plugin/Subagent/Slash 落地 |
| Poco Agent 执行 | executor/app/core/engine.py、executor/app/api/v1/task.py | 工作区、计划模式、用户问答、内置工具、停止机制 |
| 执行 Hook | executor/app/hooks/* | 回调、Todo、工作区 diff、记忆、浏览器状态、快照 |
| Executor 实时出口 | executor/app/core/stream_callback.py、executor/app/hooks/callback.py | stream_seq、journal、批量发送、持久化确认、Manager 降级 |
| 回调落库 | backend/app/services/callback/orchestrator.py | Session/Run 状态、消息、用量、事件、终态副作用 |
| Backend 实时入口 | backend/app/services/stream_ingress_service.py | 连续序号校验、实时广播、批量持久化、终态 flush |
| 实时事件 | backend/app/services/stream_event_service.py | SSE、顺序缓冲、缺口恢复、溢出与回放 |
| 前端消息顺序 | frontend/features/chat/utils/stream-sequence-buffer.ts、use-chat-messages.ts | hydration、连续消费、缺口补拉、终态历史校准 |
| 定时任务 | backend/app/services/scheduled_task_service.py | Cron、多步骤、复用会话、通知、运行入队 |
| 工作区导出 | executor_manager/app/services/workspace_export_service.py | 导出清单、归档、忽略规则 |
| 发布中心 | backend/app/services/publish_center_service.py | 入口文件选择、自动发布、版本记录 |
| WebHook | backend/app/services/webhooks/service.py | 事件过滤、payload、签名、派发 |
配置快照原则
任务创建时，Backend 会把本次任务相关配置固化为快照。这样可以解释一次运行当时用了哪些能力、浏览器设置、记忆开关和输入文件。
开发时注意：
- 会话级配置不应保存本次运行独有的附件输入。
- Run 级配置可以包含本次运行的
input_files。 - Agent 绑定会话不应随意接收运行时覆盖配置。
- 敏感 MCP 配置、Skill 文件内容和大体积暂存内容不要直接写入持久化快照。
- 新增环境变量时，同步更新配置文档和示例文件。
终态不是一个动作
一次运行结束后，系统通常会分两段处理：
- 立即终态：标记 completed/failed，写入消息、用量、Run 状态，推送实时事件。
- 导出补齐：导出工作区文件清单和压缩包，再触发工作区导出 WebHook、自动发布、产物推荐等动作。
因此不要把“会话 completed”当成“所有文件和下游动作都 ready”。涉及文件、发布和分享时，要检查 workspace_export_status。
日志规范
使用 logger.*(..., extra={...}) 时不要使用 message、name、levelname 等 LogRecord 保留字段。
文档开发
前端静态文档位于 frontend/content/docs，通过 /docs 路由访问。
新增文档页面时：
- 在对应分组目录下新增
.mdx文件。 - 在该目录的
meta.json中配置标题和顺序。 - 运行
pnpm lint验证。