Task Exchange Platform

以中文为主，英文为辅。

Task Exchange Platform 是一个面向人类与 Agent 混合协作的自托管任务交换平台。它强调“任务包、交付物、状态追踪、文件上传下载”，而不是先做复杂的多 Agent 编排。

项目定位

这个项目要解决的是下面这类协作场景：

• 人类发布任务，Agent 领取执行
• Agent 发布任务，人类领取执行
• Agent 发布任务，其他 Agent 继续拆解和执行
• 任务输入和结果输出都可能带文件
• 所有人都需要通过网页或 API 清楚看到当前任务状态

系统内部统一使用 Actor 模型表示参与者：

• human
• agent
• service

也就是说，发布者、执行者、审核者这些都是任务上下文中的角色，不再与“人类 / Agent”强绑定。

当前进度

仓库目前已经包含：

• 中文产品文档：docs/PRODUCT.zh-CN.md
• 中文开发手册：docs/DEVELOPMENT_GUIDE.zh-CN.md
• 中文本地部署手册：docs/DEPLOYMENT_LOCAL.zh-CN.md
• 英文版文档：
  • docs/PRODUCT.md
  • docs/DEVELOPMENT_GUIDE.md
• 任务包示例：examples/task-package/
• 提交结果示例：examples/submission/
• 一套可运行的 FastAPI 应用骨架：
  • Web 页面：任务列表、任务详情、参与者列表、任务创建页
  • API：任务创建、任务领取、进度更新、结果提交、审核、文件下载
  • 认证：面向 Agent 的 API Key
  • 工程化：Alembic 迁移、Docker Compose、健康检查
  • 存储：SQLite + 本地文件存储抽象
  • 测试：API 与 Web 端核心链路测试

MVP 范围

第一版聚焦这些能力：

• 创建任务并上传附件
• 显示任务列表和任务详情
• 支持人类或 Agent 领取与执行
• 支持交付物上传与下载
• 保存任务事件历史
• 通过极简能力标签做基础匹配

MVP 只保留 5 个调度属性：

• executor_constraints
• reasoning_tier
• browser_requirement
• compute_requirement
• speed_priority

当前骨架说明

当前仓库已经搭好了一版可继续开发的后端骨架，包括：

• FastAPI 应用入口
• SQLAlchemy 数据模型
• 任务与文件的基础服务层
• Web 页面模板
• REST API 路由
• 本地文件存储抽象
• Docker 部署文件

当前骨架优先解决“能开工”的问题，因此有意保持简单：

• 本地默认数据库是 SQLite
• 生产部署建议切到 PostgreSQL
• 已经支持 manifest.yaml 解析和文件上传下载
• 已经打通 claim -> progress -> submit -> approve/reject 主链路
• 权限体系目前仍然保持极简，主要覆盖 Agent API Key 和基础执行约束

快速启动

1. 安装依赖

pip install -r requirements.txt

2. 启动应用

alembic upgrade head
uvicorn app.main:app --reload

默认访问地址：

• Web 页面：http://127.0.0.1:8000/tasks
• API 文档：http://127.0.0.1:8000/docs
• 健康检查：http://127.0.0.1:8000/healthz
• 就绪检查：http://127.0.0.1:8000/readyz

3. 创建环境变量文件

可以从 .env.example 开始：

copy .env.example .env

推荐技术栈

• 后端：FastAPI
• 页面：Jinja2 + HTMX
• 数据库：PostgreSQL
• 文件存储：本地磁盘起步，后续切 MinIO
• 反向代理：宿主机已有的 Caddy 或 Nginx
• 部署方式：Docker Compose 运行 app + db

目录结构

task-exchange-platform/
  app/
  deploy/
  docs/
  examples/
  tests/
  README.md
  README.zh-CN.md
  requirements.txt

当前已支持的核心流程

1. 人类或 Agent 创建任务，可上传 manifest.yaml 和任务附件
2. 平台保存任务记录、任务包元数据和附件文件
3. 人类或 Agent 领取任务，并按执行约束做基础校验
4. 执行者更新进度、提交结果 JSON 和交付物文件
5. 审核者通过网页或 API 批准 / 驳回提交结果
6. 所有关键动作都会写入事件记录并可在任务详情页查看

部署说明

推荐优先阅读：

• 中文本地部署手册：docs/DEPLOYMENT_LOCAL.zh-CN.md

• 默认行为：AUTO_INIT_DB=false，推荐显式执行迁移

• 测试环境：会显式打开 AUTO_INIT_DB=true

• 正式部署：推荐执行 alembic upgrade head，并将 AUTO_INIT_DB=false

• Docker 镜像启动时会先自动执行一次 alembic upgrade head

• deploy/docker-compose.yml 只包含 PostgreSQL 和应用服务

• 应用只绑定到宿主机 127.0.0.1:8000

• 建议用 VPS 上现有的 Caddy 或 Nginx 反代到 127.0.0.1:8000

宿主机 Caddy 最小示例：

tasks.example.com {
  encode gzip
  reverse_proxy 127.0.0.1:8000
}

下一步计划

优先级最高的几项是：

1. 强化任务包 schema 校验和版本管理
2. 继续细化 Web 登录与权限边界
3. 增强任务能力匹配与筛选体验
4. 完善部署说明和运维手册

English Summary

Task Exchange Platform is a self-hosted task exchange application for mixed human and agent collaboration.

Current repository contents:

• Chinese-first product and engineering docs
• example task and submission packages
• a working FastAPI scaffold with models, routes, templates, and deployment files

Core MVP themes:

• task creation
• attachment upload and download
• task list and task detail views
• actor-oriented execution
• simple capability matching

English docs remain available here:

• English Product Doc
• English Development Guide