TAPD工时自动填写系统 V3.0

概述

本 skill 提供完整的 TAPD 工时自动填写网页解决方案，包含：

• tapd-timesheet-v3.html：表单式交互界面，分步骤引导填写（V3.0 字节跳动后台风格）
• tapd_proxy.py：本地代理服务，解决浏览器跨域问题，转发请求到 TAPD API

适用场景：每周五填写工时、批量补填多日工时、多任务工时分配、每日工时自定义。

何时使用此 Skill

触发词：

• "填写TAPD工时" / "工时填报"
• "timesheet" / "自动化填写工时"
• "批量提交工时" / "TAPD工时系统"
• "启动工时系统" / "打开工时页面"

快速开始（他人导入后使用步骤）

第1步：启动代理服务

cd ~/.workbuddy/skills/tapd-timesheet/scripts/
python3 tapd_proxy.py

成功提示：✅ TAPD 代理服务已启动: http://127.0.0.1:8899

> 每次使用工时系统前，都需要先启动代理服务（或者设置开机自启）。

第2步：打开网页界面

用浏览器打开：

file:///Users/zh/.workbuddy/skills/tapd-timesheet/assets/tapd-timesheet-v3.html

或者启动一个本地HTTP服务：

cd ~/.workbuddy/skills/tapd-timesheet/assets/
python3 -m http.server 8080
# 然后访问 http://localhost:8080/tapd-timesheet-v3.html

网页使用流程（V3.0 表单式界面）

步骤1：填写身份信息

• 输入工时人员姓名（格式：中文名+数字，如"邵文彬74"）
• 输入TAPD个人访问令牌
• 获取方式：TAPD → 左下角头像 → 个人设置 → 个人访问令牌 → 生成新令牌
• 可选择"保存Token到本地"，下次自动填充
• ✅ 右上角头像随时修改：点击右上角用户头像，可随时修改姓名和 Token（防止最后提交时 Token 失效）

步骤2：选择工时周期

• 快捷选择：本周 / 上周 / 自定义日期范围
• 每日工时设置：默认 8 小时，可自定义（1-24 小时）
• 系统自动排除周末和法定节假日，只计算工作日
• 加班日期多选：自动列出所选日期范围内的所有非工作日，用复选框多选

步骤3：添加工作任务

• 点击"添加工作任务"
• 填写：任务ID（19位完整ID）、工作内容描述、精力分配（%）
• 系统自动从任务ID第3~10位截取项目ID
• 可添加多个任务，按精力百分比自动分配每日工时
• 智能工时分配：
• 按精力百分比分配工时
• 单条工时不超过每日工时上限
• 自动补足每日工时（兜底逻辑）
• 如果累加超过每日上限，则从当日最大工时的任务里扣减

步骤4：确认并提交

• 预览所有工时记录（按日期/任务ID排序）
• 可编辑工作内容描述
• 点击"确认提交"，系统逐条提交（间隔1秒）
• 实时显示每条记录的提交状态（提交中/已完成/失败）
• ✅ 提交后一键撤回：支持撤回已提交的工时

步骤5：查看结果

• 全部提交完成后，自动调用TAPD查询接口
• 以表格形式展示已成功创建的工时记录
• 失败记录单独列出，可重试

核心功能特性（V3.0）

1. 多步骤表单交互

• 步骤1：填写姓名 + TAPD Token，验证有效性
• 步骤2：设置工时周期（开始/结束日期）、每日工时、加班日期
• 步骤3：添加任务，设置精力百分比、工作内容
• 步骤4：确认并提交工时到 TAPD

2. 智能工时分配

• 按精力百分比自动分配工时
• 支持每日工时自定义（默认 8 小时）
• 单条工时上限为每日工时
• 自动补足每日工时（兜底逻辑）
• 超出每日工时则从最大工时任务扣减
• 支持加班日期（非工作日）填报

3. Token 管理

• 支持 Token 保存到本地（localStorage）
• 右上角头像随时修改 Token（防止提交时失效）
• Token 有效性验证
• 修改后立即更新 AppState

4. 其他功能

• 支持撤回已提交的工时
• 节假日数据动态获取（2026 年及之后）
• 响应式设计，参考字节跳动后台 UI 风格
• 支持表单式交互（非聊天式）

核心技术说明

TAPD API 认证方式

• Bearer Token，不是 Basic Auth
• 代理服务在请求头中自动添加：Authorization: Bearer
• Token 获取：TAPD → 左下角头像 → 个人设置 → 个人访问令牌

工时提交必填字段

代理服务（tapd_proxy.py）

• 监听端口：8899
• 转发路径：/proxy/timesheets.json → https://api.tapd.cn/timesheets.json
• 支持 GET（查询）和 POST（提交）
• 自动处理 UTF-8 编码（修复中文乱码）
• 端口复用：allow_reuse_address = True（避免"Address already in use"）
• 新增接口：/holiday/{year} 动态获取节假日数据（timor.tech API）

查询已创建工时

提交完成后自动调用：

GET http://127.0.0.1:8899/proxy/timesheets.json?workspace_id=XXX&owner=XXX&spentdate=XXX&tapd_token=XXX

文件说明

tapd-timesheet/
├── SKILL.md                    # 本文档
├── assets/
│   └── tapd-timesheet-v3.html # 网页主界面（表单式交互，V3.0）
└── scripts/
    ├── tapd_proxy.py           # 本地代理服务（必启动）
    ├── holidays.json            # 2024-2026 节假日数据（备用）
    └── WORKFLOW.md             # CLI 工作流文档（备用）

安装依赖

前端

无需安装依赖，直接打开 HTML 文件即可。

后端（代理服务）

• Python 3.x
• 无需额外安装包（使用标准库）

常见问题

Q：代理服务启动失败，提示"Address already in use"？

A：代理脚本已设置 allow_reuse_address = True，一般可自动恢复。如果仍报错，先杀掉旧进程：

lsof -i :8899 | grep LISTEN | awk '{print $2}' | xargs kill -9

Q：提交一直返回401/422？

A：Token 已失效，需要重新生成。获取方式：TAPD → 左下角头像 → 个人设置 → 个人访问令牌。

• ✅ 可通过右上角头像随时修改 Token，无需重新开始。

Q：如何设置开机自启代理服务？

A：在 ~/.zshrc 或 ~/.bashrc 中添加：

nohup python3 ~/.workbuddy/skills/tapd-timesheet/scripts/tapd_proxy.py > /tmp/tapd_proxy.log 2>&1 &

Q：其他人导入这个 skill 后，文件路径在哪里？

A：导入后所有文件在 ~/.workbuddy/skills/tapd-timesheet/ 目录下。

Q：如何修改每日工时？

A：在步骤2中，有"每日工时"输入框，默认 8 小时，可修改为 1-24 之间的任意值（支持 0.5 步进）。

Q：提交后如何撤回？

A：提交完成后，在结果页面有"撤回"按钮，点击可撤回已提交的工时记录。

更新记录

V3.0 (2026-05-20)

• ✅ 新增：每日工时自定义设置（步骤2可修改，默认 8 小时）
• ✅ 新增：右上角头像随时修改 Token（防止提交时失效）
• ✅ 新增：单条工时上限校验（不超过每日工时）
• ✅ 新增：超出每日工时则从最大工时任务扣减（智能兜底）
• ✅ 优化：UI 参考字节跳动后台风格调整（主色 #1664FF、4px 圆角、轻阴影）
• ✅ 优化：加班日期多选功能（自动列出非工作日，复选框选择）
• ✅ 修复：2026 年节假日数据错误（4月7日错误排除）
• ✅ 修复：JS 语法错误（[...] 括号缺失）
• ✅ 修复：模态框显示控制（classList.add('show') 匹配 CSS）

V2.0 (2026-05-19)

• ✅ 新增：加班日期多选功能
• ✅ 新增：提交后一键撤回功能
• ✅ 新增：工时计算兜底逻辑（确保每日 8 小时）
• ✅ 优化：UI 交互优化

V1.0 (2026-05-13)

• ✅ 初始版本（聊天式交互界面）

安全说明

• ✅ 代码中没有硬编码 Token，Token 通过参数动态传递
• ✅ Token 保存在浏览器 localStorage，不会泄露到外部
• ✅ 代理服务仅监听 127.0.0.1（本地回环），不对外网开放
• ⚠️ 请勿将 Token 提交到公开仓库
• ⚠️ 建议不要将 Token 分享给他人

许可证

MIT License（自由使用和修改）

作者

WorkBuddy AI Agent（自动生成并维护）

反馈与改进

如有问题或改进建议，请在 WorkBuddy Skill 市场留言或在 GitHub 提交 Issue。