WorkTrace

WorkTrace 是面向团队的工作日志系统。成员可以在网页中填写结构化日报，也可以通过个人 API Key 让 AI Agent 以 REST API 或 MCP（Model Context Protocol）方式提交、查询和维护日志。

界面提供中文与 English 双语切换；日报按 Asia/Shanghai（上海时区）的日期归档。

核心能力

• 企业 Google Workspace 登录：当前仅允许 @feedmob.com 域名账号登录。

• 结构化日报：记录标题、完成事项、进行中、阻塞 / 风险和明日计划，并支持图片附件。

• 团队协作：浏览、搜索和筛选团队工作日志；作者可维护自己的日志。

• 管理员控制台：成员角色、访问域名、全局日志和安全审计管理。

• 个人 API Key：在控制台创建、回显、启用、禁用或撤销用于自动化访问的密钥。

• AI Agent 集成：通过 REST API、MCP 服务和 WorkTrace Skill 接入 Agent；创建日志前可先生成草稿并由用户确认。

• 安全与可靠性：API Key 密文存储、敏感操作审计、幂等写入和受限请求解析。

Related MCP server: Logtime Summarizer

技术栈

• Next.js 15（App Router）、React 19、TypeScript

• Auth.js（Google OAuth）

• SQLite（better-sqlite3）与 Zod

• MCP TypeScript SDK

• Vitest

开始使用

前置条件

• Node.js 22（项目 Docker 镜像同样基于 Node.js 22）

• 已在 Google Cloud Console 创建 OAuth 2.0「Web 应用」客户端

1. 安装依赖

npm ci

2. 配置环境变量

复制示例文件：

cp .env.example .env

至少配置以下项目：

在 Google OAuth 客户端中添加本地回调地址：

http://localhost:3000/api/auth/callback/google

当前登录域名固定为 feedmob.com，如需更换，请同步修改 src/auth.ts、src/lib/request-user.ts 与 src/lib/development-user.ts 中的域名校验。

3. 启动开发服务

npm run dev

打开 http://localhost:3000，使用允许域名内的 Google 账号登录。SQLite 数据库会在首次运行时自动创建。

常用命令

npm test       # 运行测试
npm run build  # 生成生产构建
npm start      # 启动生产服务

Agent 与 API 接入

先在「控制台 → API 密钥」创建个人 API Key。REST API 的请求头格式为：

Authorization: Bearer wtk_你的密钥

MCP 配置示例

MCP 服务位于 /mcp，与 REST API 使用同一个个人 API Key：

{
  "mcpServers": {
    "worktrace": {
      "type": "http",
      "url": "https://你的域名/mcp",
      "headers": {
        "Authorization": "Bearer wtk_你的密钥"
      }
    }
  }
}

可用工具包括：prepare_work_log、create_work_log、update_work_log、list_work_logs、get_work_log 和 get_daily_submission_status。

Agent Skill 可从以下地址读取：

https://你的域名/skill/worktrace

不要在聊天内容、工作日志或代码中保存明文 API Key；请将其存入 Agent 的安全环境变量（例如 WORKTRACE_API_KEY）。

部署

项目包含 Dockerfile、compose.yaml 和 Caddy 反向代理示例。

1. 将 deploy/worktrace.env.example 复制为部署目录中的 .env，填写全部密钥与域名。

2. 在 compose.yaml 所在目录运行：

   docker compose up -d --build

3. 容器监听 127.0.0.1:16063，使用 deploy/Caddyfile.worktrace 配置域名反向代理。

生产环境应设置 AUTH_URL、AUTH_TRUST_HOST、NEXT_PUBLIC_APP_URL、KEY_ENCRYPTION_SECRET 和持久化的 LOCAL_DATABASE_PATH。默认 Compose 配置会将数据卷挂载到 /var/lib/worktrace。

项目结构

src/
  app/          页面、API 路由与 MCP 端点
  components/   可复用的 React 组件
  lib/          认证、数据库、API Key、日志和 MCP 领域逻辑
deploy/         Caddy 配置与生产环境变量示例
docs/           产品、前端与后端需求文档
prisma/         参考 Prisma 模型
stitch-worktrace/  视觉稿与页面素材

安全提示

• .env、数据库和上传文件均不应提交到 Git 仓库。

• 生产环境请使用随机生成的强密钥，并定期轮换 API Key。

• 管理员接口仅限 ADMIN 角色访问；敏感操作会记录审计事件。