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