Task Vantage 演示版

Task Vantage 演示是一个参考实现，展示了通过多个接口提供的现代任务管理平台：

🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或保持原样作为表情使用，不直接对应具体文字含义。在这里，我将其意译为“🚀（火箭）”。 REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口） - 使用（某种技术/工具）构建 Hono（霍诺）并通过Auth0 JWT验证进行保障
🤖 表情符号，通常代表机器人或机器人形象，没有直接的中文翻译，但在中文语境中，可以理解为“机器人”或保持原样使用该表情符号。 代理服务 - 带有基于网页的聊天界面的AI代理 LlamaIndex（注：此名称可能为特定技术或项目的专有名词，直接翻译为“拉玛索引”可能并不准确，具体含义需结合上下文或官方解释，此处仅为直译）以及OpenAI
📱 网络应用程序 - 现代网页界面，用于直接进行项目和任务管理

用户访问点：

🖥️ 电脑 Claude Desktop（可译为“Claude桌面版”或保持原样，若“Claude”为特定产品名则不需翻译） → MCP服务器（AI助手集成）
🌐 表示“互联网”或“网络”。 网络浏览器 → 代理服务（AI聊天界面）
🌐（表示互联网或全球连接的符号，无直接对应中文含义，可理解为“网络”或“全球互联”的意象） 网络浏览器 → Web 应用程序（传统的任务管理用户界面）

了解更多见 docs/ABOUT.md 翻译为中文是：“文档/关于（文件）.md” 或者更自然的表达可以是：“文档/关于页面.md”。这里，“docs”通常表示文档目录，“ABOUT.md”是一个Markdown格式的文件，用于描述关于某个项目或主题的信息关于产品愿景和背景。

📚 文档

文件	描述
docs/LOGGING.md（文件名翻译为中文可表述为：文档/日志记录.md）用于调试认证流程的详细日志记录系统
docs/VERCEL.md（文件名，可译为“文档/VERCEL.md”或保持原样，因为文件名通常不翻译）	Vercel 无服务器函数的完整部署指南
docs/ABOUT.md 翻译为中文是：文档/关于文件（或“关于我们”文件）	产品愿景与任务优势概览

🏗️ 项目结构

src/
├── 🚀 api/          # REST API (Hono + Auth0)
├── 🔌 mcp/          # MCP Server (Hono + mcp-handler + CTE)
├── 🤖 agent/        # Agent Service (Hono + LlamaIndex + OpenAI)
├── 📱 webapp/       # Web Application (Hono + Auth0 OAuth2)
└── 🛠️ utils/        # Shared utilities (logging, etc.)

vercel/              # Deployment configurations
├── api/            # API service deployment
├── mcp/            # MCP service deployment
├── agent/          # Agent service deployment
└── webapp/         # Web app deployment

⚡ 快速启动

要求

Node.js 22及以上版本
npm（Node Package Manager，Node包管理器） （或兼容的包管理器）
Auth0 账户 （用于身份验证）
OpenAI API密钥 （针对AI代理功能）

安装

安装依赖项：

   npm install

配置环境：

   cp .env.example .env
   # Edit .env with your Auth0 and OpenAI credentials

启动所有服务：

   npm run dev:all

可用脚本

发展

# Run individual services
npm run dev:api        # Start REST API (port 8787)
npm run dev:mcp        # Start MCP server (port 8080)
npm run dev:agent      # Start Agent service (port 3000)
npm run dev:webapp     # Start Web App (port 3001)

# Development with file watching
npm run dev:agent:watch   # Auto-restart agent on file changes
npm run dev:webapp:watch  # Auto-restart webapp on file changes

# Run all services in parallel
npm run dev:all        # Starts all 4 services + opens browser tabs
npm start              # Alias for dev:all

# Open services in browser
npm run open:agent     # Opens http://localhost:3000
npm run open:webapp    # Opens http://localhost:3001

部署（Vercel）

# Bootstrap Vercel projects (first time setup)
npm run bootstrap:all     # Link all 4 Vercel projects
npm run bootstrap:api     # Link task-vantage-api project
npm run bootstrap:mcp     # Link task-vantage-mcp project
npm run bootstrap:agent   # Link task-vantage-agent project
npm run bootstrap:webapp  # Link task-vantage-webapp project

# Deploy services
npm run deploy:all        # Deploy all services sequentially
npm run deploy:parallel   # Deploy all services in parallel
npm run deploy:api        # Deploy API service only
npm run deploy:mcp        # Deploy MCP service only
npm run deploy:agent      # Deploy Agent service only
npm run deploy:webapp     # Deploy Web App service only

监测

# View deployment logs
npm run logs:all          # View logs for all services
npm run logs:api          # View API service logs
npm run logs:mcp          # View MCP service logs
npm run logs:agent        # View Agent service logs
npm run logs:webapp       # View Web App service logs

# Open deployed services in browser
npm run open:deployed:all     # Open all service dashboards
npm run open:deployed:api     # Open API service dashboard
npm run open:deployed:mcp     # Open MCP service dashboard
npm run open:deployed:agent   # Open Agent service dashboard
npm run open:deployed:webapp  # Open Web App service dashboard

见 VERCEL.md（文件名，可理解为“关于Vercel的Markdown文件”）请参阅详细的部署说明。

服务URL（本地开发）

服务	URL	用途
🚀 API 根据全局信息，翻译目标语言为中文，且“API”必须翻译为“API”，原文内容为“	http://localhost:8787	REST API endpoints	”，因此译文内容为：	http://localhost:8787	REST API 接口端点
电源插头 MCP	http://localhost:8080/mcp	MCP服务器端点（Claude桌面版）
🤖 代理	http://localhost:3000	AI聊天界面（网页浏览器）
📱 网络应用	http://localhost:3001	任务管理界面（网页浏览器）

关键路线

代理聊天界面http://localhost:3000/chat/app（通过网页浏览器进行的AI聊天）
网络应用仪表盘http://localhost:3001/app（任务管理界面）
API 状态http://localhost:8787/health 翻译为中文是：“本地主机上的8787端口健康检查接口”
MCP Health（可译为“MCP健康”或根据具体语境调整为更贴切的表述，如“MCP医疗健康”等）http://localhost:8080/health 翻译成中文是：“本地主机的8080端口健康检查接口”。不过，通常我们不会直接这样翻译网址，而是根据上下文或具体用途来解释其含义。在这个例子中，“/health”路径通常用于表示一个健康检查端点，用于监控服务是否正常运行。所以，也可以简化为“本地健康检查接口（8080端口）”

🔐 认证流程

Task Vantage 使用 Auth0（注：这是一个专有名词，通常不翻译，直接保留原名，但在此按照要求说明其含义，即“Auth0”是一个用于身份验证和授权的服务平台名称） 针对不同服务的不同流程进行认证：

服务	认证方法	令牌类型
REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口）	JWT验证	持有者（令牌） `access_token`
MCP 服务器自定义令牌交换（CTE）	持有人 → API令牌
代理服务	OAuth2 会话	会话 + 持有者令牌
网络应用	OAuth2 授权码	会话 + 访问令牌

详情请参阅下面的序列图以了解完整的认证流程。

🔧 环境配置

快速设置：

cp .env.example .env
# Edit .env with your credentials

特定服务配置

每个服务都有其自己的配置文档，记录在README文件中：

服务	配置指南
🚀 API服务	src/api/README.md（这个路径通常表示在项目源代码的api目录下的README文件，直接翻译为中文路径形式可保持原样，若需说明其内容或用途，则可译为“src/api/README.md（源代码api目录下的说明文件）”）
🔌（这个符号本身在中文里没有直接对应的翻译，它是一个电源插头或插座的符号，可以理解为“电源插头”或“插座”） MCP服务	src/mcp/README.md 翻译为中文是：src/mcp/README文件（或：说明文件）
🤖 代理服务	src/agent/README.md（翻译为中文可表述为：源代码目录/agent/下的README文件）
📱（一个手机图标） Web应用服务	src/webapp/README.md（文件名保持不变，翻译说明部分）：源代码目录/webapp下的README.md文件

全局配置

所有服务均使用这些共享的 Auth0 设置：

AUTH0_DOMAIN - 您的 Auth0 域名（例如，your-domain.auth0.com）
LOG_VERBOSE - 启用详细日志记录以进行调试（默认：true）

注\REDIS_URL\ 由 Vercel 自动为部署的服务提供。如果仅在本地使用 Redis，则仅需在本地进行配置。

🏛️ 系统架构

高层概览

该图展示了所有Task Vantage服务如何协同工作：

flowchart TB
%% User interactions
    User(["End User"])
    Claude(["Claude Desktop
with MCP"])
    Browser(["Web Browser"])

%% Services (can run locally or on Vercel)
    subgraph Services["Task Vantage Services"]
        direction TB

        WebApp["📱 Task Vantage Web
(Hono + Auth0 + Session)"]:::webapp
        Agent["🤖 Task Vantage Agent
(LlamaIndex + OpenAI)"]:::agent
        MCP["🔌 Task Vantage MCP
(Hono + mcp-handler + CTE)"]:::mcp
        API["🚀 Task Vantage API
(Hono + JWT validation)"]:::api

        Store["💾 In-memory Store
(Projects, Tasks, Tags, Comments)"]:::store
    end

%% External services
    subgraph External["External Services"]
        Auth0["🔐 Auth0
(Identity Provider)"]:::auth
        OpenAI["🧠 OpenAI
(LLM Provider)"]:::openai
    end

%% User flows
    User -.-> Browser
    User -.-> Claude
    Browser --> WebApp
    Browser --> Agent
    Claude --> MCP

%% Service interactions
    WebApp --> API
    Agent --> MCP
    MCP --> API
    API --> Store
    Agent --> OpenAI

%% Authentication flows
    WebApp --> Auth0
    Agent --> Auth0
    MCP --> Auth0
    API --> Auth0

%% styles
    classDef webapp fill:#FFF2E6,stroke:#FF8C00,color:#8B4513,stroke-width:2px
    classDef agent fill:#EAF2F8,stroke:#5DADE2,color:#1B4F72,stroke-width:2px
    classDef mcp fill:#F5EEF8,stroke:#BB8FCE,color:#4A235A,stroke-width:2px
    classDef api fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:2px
    classDef store fill:#D5F5E3,stroke:#27AE60,color:#145A32,stroke-width:2px
    classDef auth fill:#FADBD8,stroke:#E74C3C,color:#641E16,stroke-width:2px
    classDef openai fill:#E8F5E8,stroke:#28A745,color:#155724,stroke-width:2px

统一的Hono架构

主要优势：

✨（闪闪发光的星星符号，常用于表达兴奋、喜悦或特别的时刻） 一致的框架所有服务均使用 Hono（日语中的“羽衣”或“羽毛衣”，也可指代神话中的神鸟或仙境）为了最大限度地提高代码重用性和可维护性
🚀 这个符号本身在中文里没有直接的翻译，它通常被用作表示火箭、快速前进或加速的象征。在没有具体上下文的情况下，可以简单地将其描述为“火箭”或“快速前进”的符号。例如：“🚀 我们即将踏上这段激动人心的旅程！”可以翻译为：“🚀 我们即将踏上这段激动人心的旅程！”（这里直接保留了符号，因为其含义在中文中已有对应的表达）。 Vercel 优化版原生支持无服务器函数，无需任何配置
🔄 翻译成中文是：🔄（这个符号本身没有直接的中文翻译，但可以理解为表示“循环”、“重复”或“刷新”的意思，具体根据上下文而定。） DRY 部署（或“干式部署”，但“DRY”在此上下文中更可能指一种开发或部署原则，即“Don't Repeat Yourself”，即“不要重复自己”，因此“DRY 部署”可理解为遵循“DRY”原则进行的部署）本地开发环境与生产环境采用相同的代码库结构
🔐 统一的认证模式所有服务中一致集成Auth0

此图展示了每项服务中使用的具体框架和技术：

flowchart TB
    subgraph "🏗️ Technology Stack"
        direction TB

        subgraph WebApp ["📱 Task Vantage Web"]
            WA1["Hono Framework"]
            WA2["@auth0/auth0-hono"]
            WA3["OAuth2 Authorization Code"]
        end

        subgraph Agent ["🤖 Task Vantage Agent"]
            AG1["Hono Framework"]
            AG2["@auth0/auth0-hono"]
            AG3["LlamaIndex + @llamaindex/openai"]
            AG4["Session Management"]
        end

        subgraph MCP ["🔌 Task Vantage MCP"]
            MC1["Hono Framework"]
            MC2["mcp-handler"]
            MC3["@auth0/auth0-api-js"]
            MC4["Custom Token Exchange"]
        end

        subgraph API ["🚀 Task Vantage API"]
            AP1["Hono Framework"]
            AP2["@auth0/auth0-api-js"]
            AP3["JWT Validation"]
            AP4["In-memory Store"]
        end

        subgraph External ["🌐 External Services"]
            EX1["Auth0 Identity Provider"]
            EX2["OpenAI LLM API"]
        end
    end

    %% Framework relationships
    WebApp --> API
    Agent --> MCP
    MCP --> API

    %% Auth flows
    WebApp --> External
    Agent --> External
    MCP --> External
    API --> External

    %% Agent AI integration
    Agent --> EX2

    %% Styling
    classDef webapp fill:#FFF2E6,stroke:#FF8C00,color:#8B4513,stroke-width:2px
    classDef agent fill:#EAF2F8,stroke:#5DADE2,color:#1B4F72,stroke-width:2px
    classDef mcp fill:#F5EEF8,stroke:#BB8FCE,color:#4A235A,stroke-width:2px
    classDef api fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:2px
    classDef external fill:#FADBD8,stroke:#E74C3C,color:#641E16,stroke-width:2px

    class WebApp,WA1,WA2,WA3 webapp
    class Agent,AG1,AG2,AG3,AG4 agent
    class MCP,MC1,MC2,MC3,MC4 mcp
    class API,AP1,AP2,AP3,AP4 api
    class External,EX1,EX2 external

🔄 请求流程

此序列展示了Claude Desktop如何通过MCP创建任务：

%%{init: { "sequence": { "mirrorActors": false }}}%%
sequenceDiagram
    actor User as End User
    participant Claude as Claude Desktop
    participant MCP as Task Vantage MCP
(Hono + mcp-handler + CTE)
    participant Auth0 as Auth0
(Identity Provider)
    participant API as Task Vantage API
(Hono)
    participant Store as In-memory Store

    Note over User,Store: MCP Tool Invocation Flow

    User ->> Claude: "Create a new project called 'Demo'"
    Claude ->> MCP: create_project({name: "Demo"})

    Note over MCP,Auth0: Custom Token Exchange (CTE)
    MCP ->> Auth0: Exchange MCP token for API token
    Auth0 -->> MCP: API access token

    Note over MCP,API: Authenticated API Call
    MCP ->> API: POST /projects with Bearer token
    API ->> Auth0: Validate JWT token
    Auth0 -->> API: Token claims (sub, scope, etc.)

    API ->> Store: Create project in memory
    Store -->> API: Project created
    API -->> MCP: {"id": "proj_123", "name": "Demo"}
    MCP -->> Claude: Tool result: Project created
    Claude -->> User: "I've created the 'Demo' project for you."

    Note over User,Store: Alternative Flows

    rect rgb(255, 248, 220)
        Note over User,WebApp: Web App Flow
        User ->> WebApp: Login & create project
        WebApp ->> Auth0: OAuth2 Authorization Code flow
        Auth0 -->> WebApp: Access token
        WebApp ->> API: Create project with token
    end

    rect rgb(240, 248, 255)
        Note over User,Agent: Agent Chat Flow
        User ->> Agent: Chat with AI agent
        Agent ->> Auth0: Session authentication
        Agent ->> MCP: Call MCP tools
        MCP ->> API: Forward to API
    end

Auth0 Task Vantage

快速接入

详细介绍