Skill: huuuwnnn-droid/pingcode-timelogger (version 1.1.0)

--- name: pingcode-timelogger description: Automate PingCode timesheet filling — create sub-tasks and log work hours. Use when asked to fill PingCode timesheets, log work hours, create work items, or auto-generate timesheets from Git commits. Triggers on "fill PingCode", "log hours", "PingCode timesheet", "fill timesheet", "工时填报", "填工时", "PingCode填报", "根据Git提交填工时". --- # PingCode TimeLogger Automate PingCode timesheet: create sub-tasks under a parent work item, set properties, and log work hours. Supports manual task lists and auto-generation from Git commits. ## Setup Config lives at `~/.openclaw/skills/pingcode-timelogger/config.yaml`. Read it first on every invocation. If config doesn't exist, guide the user through first-time setup: 1. Copy the template from `references/config-template.yaml` in this skill directory 2. User fills in their PingCode URL, cookie, project info, and optionally Git credentials 3. Validate by making a test API call to PingCode ### Config Structure ```yaml pingcode: url: https://company.pingcode.com # PingCode instance URL cookie_file: ./cookies.txt # Path to cookie file (relative to config dir) project_id: "" # Project _id (24-char hex) default_parent_id: "" # Default parent work item _id user_id: "" # Assignee user _id task_type_id: "" # "任务" type _id completed_state_id: "" # "已完成" state _id git: provider: github # github or gitlab url: https://api.github.com # API base URL token_file: ./git-token.txt # Path to token file (relative to config dir) username: "" # Git username repos: [] # Repos to scan, e.g. ["owner/repo1"] defaults: work_category: 研发 # 研发/设计/部署/测试/文档/产品/调研/其他 assignee_name: "" # Display name for confirmation messages ``` ## Authentication Two strategies, with automatic fallback: ### Strategy 1: API Direct (Primary) Read cookie from `cookie_file` in config. Use `credentials: 'include'` or `Cookie` header for all API calls. ### Strategy 2: Browser Automation (Fallback) If API calls fail (401/403), fall back to browser automation: 1. Open PingCode URL in browser 2. Check if user is logged in 3. If not, ask user to log in manually 4. Operate via browser UI Always try API first. Only fall back to browser when API auth fails. ## Core Workflow ### Step 0: User Confirmation (Mandatory) Before creating anything, **always** present the full plan to the user and wait for explicit confirmation: 1. Parse user input (task table or description) 2. Organize into the correct structure (see Task Structure below) 3. Output a clear summary: which story → which tasks → which sub-tasks → hours per item 4. **Wait for user to say OK** before executing 5. During execution, report progress in real-time (don't batch all updates to the end) ### Task Structure Two modes depending on the project: #### Mode A: Flat (e.g., SMA project) Simple parent → child tasks. Each task is a direct sub-item under the parent story/task. #### Mode B: Phased (e.g., RD-IT project) Three-level structure aligned with delivery phases: ``` Story (需求) ├── 前端开发 (task) ← phase node, sub-tasks underneath │ ├── sub-task: feature A │ └── sub-task: feature B ├── 后端开发 (task) ← phase node, sub-tasks underneath │ └── sub-task: API work ├── 自测 (task) ← phase node, usually no children ├── 联调 (task) ← phase node ├── 研发自扫 (task) ← phase node ├── 产品文档 (task) ← phase node ├── PRD文档 (task) ← phase node ├── 测试 (task) ← phase node, may have children (test cases, test report) ├── 上线准备 (task) ← phase node, may have children (manual, release plan) └── 上线文档梳理 (task) ← phase node ``` **Rules for Mode B**: - All phase nodes are **sibling tasks** under the story (not nested) - **Only 前端开发 and 后端开发** have sub-tasks for specific dev work - Other phases (自测, 联调, 文档, etc.) are usually single tasks - 测试 and 上线准备 **may** have sub-tasks if there are multiple deliverables - **Work hours go on the lowest level**: sub-tasks if they exist, otherwise directly on the phase task - Estimated hours (`estimated_workload`) = registered hours (same value) - If a phase task already exists under the story, reuse it; don't create duplicates **Determining the mode**: Check the project identifier prefix (SMA → Mode A, RD-IT → Mode B). If unclear, ask the user. ### Locate Target Parent User provides one of: - **PingCode URL**: Extract work item ID from URL path, e.g. `https://company.pingcode.com/pjm/projects/SMA/work-items/SMA-348` → look up `SMA-348` - **Work item identifier**: e.g. `SMA-348` → `GET /api/agile/work-items/SMA-348` to get `_id` - **Nothing specified**: Use `default_parent_id` from config For **Mode B**, also check existing children of the story: ``` GET {pingcode_url}/api/agile/work-items/{story_id}/children ``` Reuse existing phase tasks (e.g., if "后端开发" already exists, create sub-tasks under it). ### Create Sub-Tasks For each task in the list: ``` POST {pingcode_url}/api/agile/work-item Cookie: <from cookie_file> { "property_values": [ {"key": "title", "value": "<task title>"}, {"key": "type", "value": "<task_type_id from config>"}, {"key": "project_id", "value": "<project_id from config>"}, {"key": "assignee", "value": "<user_id from config>"}, {"key": "parent_id", "value": "<parent _id>"}, {"key": "due", "value": null}, {"key": "phase", "value": null} ] } ``` Note: Endpoint is `/api/agile/work-item` (singular), NOT `/api/agile/work-items`. ### Set Date and Status ``` PUT {pingcode_url}/api/agile/work-items/{_id}/property Cookie: <from cookie_file> # Set start date: {"key": "start", "value": {"date": <unix_timestamp>}} # Set end date: {"key": "due", "value": {"date": <unix_timestamp>}} ``` Batch set status to completed: ``` POST {pingcode_url}/api/agile/work-items/state Cookie: <from cookie_file> { "state_id": "<completed_state_id from config>", "work_item_ids": ["id1", "id2", ...], "bypass": 0 } ``` ### Set Estimated Workload ``` PUT {pingcode_url}/api/agile/work-items/{_id}/property Cookie: <from cookie_file> {"key": "estimated_workload", "value": <hours_as_number>} ``` **⚠️ The value is in HOURS (not seconds). Do NOT multiply by 3600.** Set estimated workload = registered hours (same value) on every task/sub-task that has hours logged. ### Log Work Hours ``` POST {pingcode_url}/api/ladon/workload/register Cookie: <from cookie_file> { "principal_type": "work_item", "principal_id": "<task_id>", "man_hour": <hours>, "remaining_workload": 0, "register_date": <cst_midnight_unix_ts>, "work_category_id": "<category_id>", "work_content": "<task description>", "pilot_id": "<project_id>" } ``` **⚠️ `pilot_id` is required — set it to the project's `_id` (same as `project_id`).** **work_category_id mapping** — read `references/category-ids.md` for the full list. Common: 研发=`5cb7e7fffda1ce4ca0050002`. **register_date**: Must be CST (UTC+8) midnight timestamp. Formula: `new Date('YYYY-MM-DDT00:00:00+08:00').getTime() / 1000` **Distribute hours across weekdays** (Mon–Fri). Never pile all hours on one day. ## Git Commit Auto-Fill When user says "根据Git提交填工时" or similar: 1. Read Git config from `config.yaml` (provider, token, repos) 2. Ask user for: target date range, total work hours for the period 3. Fetch commits via Git API — see `references/git-integration.md` 4. Group commits by day and summarize into task titles 5. Distribute hours proportionally across days based on commit count 6. Confirm task list with user before creating 7. Execute standard workflow (create tasks → set properties → log hours) ## Important Rules - **Always confirm** the full task list with user before creating anything - **Report progress in real-time** — don't wait until the end to send all updates - **API endpoint is singular**: `/api/agile/work-item` for creation - **Never use Bearer token** — PingCode auth requires Cookie - **Status flow**: Only use "已完成", never "关闭". Must go: 打开→进行中→已完成 (two steps) - **Type matters**: Tasks (type=4) can have hours logged directly. User Stories (type=3) cannot — must create task sub-items under them - **estimated_workload unit is HOURS** — do NOT multiply by 3600 - **pilot_id is required** for workload register — use the project_id - **Read-only for production data**: Never delete or modify existing work items without explicit user confirmation ## Error Handling | Error | Action | |-------|--------| | 401/403 on API | Switch to browser fallback | | Cookie expired | Ask user to re-export cookie or log in via browser | | Parent is Epic (type=2) | Cannot create task directly under Epic; find or create a User Story first | | work_category_id missing | Required field since 2026-04; always include it | | pilot_id not found | Add `pilot_id: <project_id>` to workload register request | | estimated_workload too large | Unit is hours, not seconds; do NOT multiply by 3600 | ## First-Time Setup Guide If config file doesn't exist, walk user through setup: 1. Create config directory: `mkdir -p ~/.openclaw/skills/pingcode-timelogger` 2. Copy template: read `references/config-template.yaml` and save to config dir 3. User fills in PingCode URL 4. Guide user to export cookies (browser DevTools → Application → Cookies → copy all for the PingCode domain, or use a cookie export extension) 5. Help user find project_id, task_type_id, state_ids by browsing PingCode API or UI 6. Optionally configure Git integration 7. Test with a dry-run (show what would be created without actually creating)

path: README.md
content: # 🕐 PingCode TimeLogger

> OpenClaw Skill：自动化 PingCode 工时填报，支持手动任务清单和 Git 提交自动生成。

## ✨ 功能

- **创建子任务**：在指定父工作项下批量创建子任务
- **自动登记工时**：设置日期、状态、工时，自动分配到工作日
- **Git 提交转工时**：读取 GitHub / GitLab 提交记录，自动生成任务并填报
- **双通道认证**：API 直连优先，浏览器自动化兜底
- **通用脱敏**：所有敏感信息从配置文件读取，skill 本身不含任何硬编码

## 📦 安装

### 方式一：ClawHub（推荐）

```bash
clawhub install pingcode-timelogger
```

### 方式二：手动

将 `SKILL.md` 和 `references/` 目录放入你的 OpenClaw workspace 的 `skills/pingcode-timelogger/` 下。

## ⚙️ 配置

### 1. 创建配置目录

```bash
mkdir -p ~/.openclaw/skills/pingcode-timelogger
```

### 2. 复制配置模板

将 `references/config-template.yaml` 复制到配置目录：

```bash
cp <skill-dir>/references/config-template.yaml ~/.openclaw/skills/pingcode-timelogger/config.yaml
```

### 3. 填写配置

编辑 `~/.openclaw/skills/pingcode-timelogger/config.yaml`：

```yaml
pingcode:
  url: https://your-company.pingcode.com   # 你的 PingCode 地址
  cookie_file: ./cookies.txt                # Cookie 文件路径
  project_id: "xxxxxxxxxxxxxxxxxxxxxxxx"    # 项目 ID（24位hex）
  default_parent_id: ""                     # 默认父工作项 ID（可选）
  user_id: "xxxxxxxxxxxxxxxxxxxxxxxx"       # 你的用户 ID
  task_type_id: ""                          # "任务"类型 ID
  completed_state_id: ""                    # "已完成"状态 ID
  open_state_id: ""                         # "打开"状态 ID
```

### 4. 导出 PingCode Cookie

1. 用浏览器登录你的 PingCode
2. 打开开发者工具（F12）→ Application → Cookies
3. 复制 PingCode 域名下的所有 Cookie
4. 保存到 `~/.openclaw/skills/pingcode-timelogger/cookies.txt`

> 💡 也可以让 OpenClaw 通过浏览器自动操作（兜底方案），此时不需要 Cookie 文件，但需要你在浏览器中已登录 PingCode。

### 5. 查找 ID（如果不知道的话）

在 PingCode 中打开开发者工具的 Network 面板，操作时观察 API 请求：

| 需要的 ID | 怎么找 |
|-----------|--------|
| `project_id` | 打开项目，看 URL 或 API 请求中的 project 参数 |
| `user_id` | 查看个人信息相关的 API 返回 |
| `task_type_id` | 创建一个任务，看请求中的 type 字段 |
| `completed_state_id` | 修改任务状态为"已完成"，看请求中的 state_id |

> 💡 首次使用时，直接告诉 OpenClaw "帮我配置 PingCode TimeLogger"，它会引导你一步步完成。

### 6. 配置 Git 集成（可选）

如果你想从 Git 提交记录自动生成工时：

```yaml
git:
  provider: github          # github 或 gitlab
  url: https://api.github.com
  token_file: ./git-token.txt
  username: your-username
  repos: ["owner/repo1", "owner/repo2"]
```

创建 token 文件：
```bash
echo "your-github-token" > ~/.openclaw/skills/pingcode-timelogger/git-token.txt
```

## 🚀 使用

### 手动填报

直接告诉 OpenClaw：

```
帮我在 SMA-348 下填这周的工时：
- 周一：修复用户认证超时问题 3h
- 周二：数据同步接口开发 4h
- 周三：代码审查 + 部署 2h
```

或者给一个 PingCode 链接：

```
帮我在这里填工时：https://your-company.pingcode.com/pjm/projects/SMA/work-items/SMA-348
任务清单如下：...
```

### Git 提交自动填报

```
根据今天的 Git 提交帮我填 PingCode，今天工作了 8 小时
```

OpenClaw 会：
1. 读取你配置的 Git 仓库的提交记录
2. 按日期分组，自动生成任务标题
3. 按提交数量比例分配工时
4. 确认后自动创建子任务并登记工时

## 📁 文件结构

```
pingcode-timelogger/
├── SKILL.md                          # Agent 指令文件
└── references/
    ├── config-template.yaml          # 配置模板
    ├── category-ids.md               # 工作类别 ID 映射
    └── git-integration.md            # Git 集成说明
```

## ⚠️ 注意事项

- PingCode 认证使用 Cookie，不支持 Bearer Token
- 工时会自动分配到工作日（周一~周五），不会堆在一天
- 首次使用会有引导流程，帮你找到各种 ID
- **不会自动删除或修改已有工作项**，除非你明确要求

## 📄 License

MIT


path: references/category-ids.md
content: # PingCode Work Category IDs

Standard work category IDs used in PingCode workload registration.

These IDs may vary between PingCode instances. The values below are defaults; if they don't work, discover them via the PingCode UI:
1. Open any work item → Log Hours → click the "工作类别" dropdown
2. Use browser DevTools (Network tab) to capture the actual IDs

## Default Category Mapping

| Category | Chinese | ID |
|----------|---------|-----|
| Design | 设计 | `5cb7e7fffda1ce4ca0050001` |
| Development | 研发 | `5cb7e7fffda1ce4ca0050002` |
| Deployment | 部署 | `5cb7e7fffda1ce4ca0050003` |
| Testing | 测试 | `5cb7e7fffda1ce4ca0050004` |
| Documentation | 文档 | `5cb7e7fffda1ce4ca0050005` |
| Product | 产品 | `5cb7e7fffda1ce4ca0050006` |
| Research | 调研 | `5cb7e7fffda1ce4ca0050007` |
| Other | 其他 | `5cb7e7fffda1ce4ca0050008` |

## Auto-Discovery

If the default IDs don't work, the skill should discover them by:
1. Opening a work item's time logging UI in the browser
2. Inspecting the dropdown options
3. Saving discovered IDs back to the user's config


path: references/config-template.yaml
content: # PingCode TimeLogger Configuration
# Copy this file to: ~/.openclaw/skills/pingcode-timelogger/config.yaml

pingcode:
  # Your PingCode instance URL (required)
  url: https://your-company.pingcode.com

  # Path to cookie file, relative to this config directory (required)
  # Export from browser: DevTools → Application → Cookies → copy as text
  cookie_file: ./cookies.txt

  # Project ID — 24-character hex string (required)
  # Find it: open your project in PingCode, check browser DevTools network requests
  project_id: ""

  # Default parent work item ID to create sub-tasks under (optional)
  # If not set, user must specify a parent each time
  default_parent_id: ""

  # Your user ID in PingCode — 24-character hex string (required)
  # Find it: DevTools → network → look for your user ID in API responses
  user_id: ""

  # Work item type IDs (required)
  # These are usually consistent within a PingCode instance
  task_type_id: ""           # "任务" (Task) type ID
  completed_state_id: ""     # "已完成" (Completed) state ID
  open_state_id: ""          # "打开" (Open) state ID

# Git integration (optional — needed for auto-fill from commits)
git:
  # Provider: github or gitlab
  provider: github

  # API base URL
  # GitHub: https://api.github.com
  # GitLab: https://your-gitlab.com
  url: https://api.github.com

  # Path to token file, relative to this config directory
  # Create the file with just the token string inside
  token_file: ./git-token.txt

  # Your Git username (for filtering commits)
  username: ""

  # Repositories to scan for commits
  # Format: ["owner/repo1", "owner/repo2"]
  repos: []

# Default values for time logging
defaults:
  # Work category: 研发/设计/部署/测试/文档/产品/调研/其他
  work_category: 研发

  # Your display name (used in confirmation messages)
  assignee_name: ""


path: references/git-integration.md
content: # Git Integration for PingCode TimeLogger

## Supported Providers

### GitHub

**Fetch commits for a date range:**
```
GET https://api.github.com/repos/{owner}/{repo}/commits?author={username}&since={ISO8601}&until={ISO8601}
Authorization: Bearer <token>
```

Response: Array of commit objects. Key fields:
- `commit.message` — commit message (use first line as task title)
- `commit.author.date` — commit timestamp (for day grouping)
- `sha` — commit hash (for dedup)

**Pagination**: Follow `Link` header for next page. Default 30 per page, max 100 with `?per_page=100`.

### GitLab

**Fetch commits for a date range:**
```
GET {gitlab_url}/api/v4/projects/{project_id}/repository/commits?author={username}&since={ISO8601}&until={ISO8601}
PRIVATE-[REDACTED_SECRET]
```

For project ID, use URL-encoded path: `GET /api/v4/projects/{url_encoded_path}/repository/commits`

Response: Array of commit objects. Key fields:
- `title` — commit message first line
- `committed_date` — timestamp
- `id` — commit hash

**Pagination**: Use `page` and `per_page` query params.

## Commit-to-Task Conversion

### Grouping Strategy
1. Fetch all commits in the date range across configured repos
2. Group by date (using commit timestamp, converted to CST)
3. Within each day, merge related commits:
   - Same prefix (e.g., `fix:`, `feat:`, `chore:`) → group together
   - Same ticket reference (e.g., `#123`, `JIRA-456`) → group together
4. Generate task title from grouped commits:
   - Single commit: Use first line of commit message
   - Multiple related: Summarize (e.g., "Bug fixes: auth timeout, null check, retry logic")

### Hour Distribution
- User provides total hours for the period
- Distribute proportionally by commit count per day
- Minimum 0.5h per day that has commits
- Round to nearest 0.5h
- Adjust last day to make total exact

### Example

User: "根据本周Git提交填8小时工时"

Commits found:
- Monday: 5 commits (auth module fixes)
- Tuesday: 3 commits (API endpoints)
- Wednesday: 0 commits
- Thursday: 2 commits (deploy config)
- Friday: 0 commits

Distribution (total 8h, 10 commits):
- Monday: 5/10 × 8 = 4.0h → "Auth模块问题修复"
- Tuesday: 3/10 × 8 = 2.5h → "API接口开发"
- Thursday: 2/10 × 8 = 1.5h → "部署配置调整"
- Total: 8.0h ✓


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)