# Veyra Timesheet

> Use when 用户要填、补或核对公司「Veyra 睿策」工时——说「填工时」「核对工时」「这周工时」「补工时」「工时缺口」「工时未达标通报」，或要把一段时间的真实活动录入工时系统，含请假与加班。仅 macOS。

- Skill: `stardustai/veyra-timesheet` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add stardustai/veyra-timesheet`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stardustai/veyra-timesheet/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stardustai (https://skillmd.com/u/stardustai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stardustai/veyra-timesheet

---


# 工时填写

## Overview

把一段时间的真实活动核对、补齐到「Veyra 睿策」。

核心原则：**活动记录能证明你在哪条线上，证明不了你花了几小时。** 项目由证据决定，小时数由用户决定。

## When to Use

- 填、补、核对某段时间的工时；收到周期缺口或未达标通报
- 当期含请假、调休、加班

不适用：查考勤打卡（企业未开通，拉不到数据）；改他人工时。

## Quick Reference

| 命令 | 用途 |
|---|---|
| `bash <skill>/scripts/init.sh` | 探测环境（**默认只探测不改动**）。`collect.sh` 报环境错误时先跑它；把缺失项和将改动的路径告知用户，**确认后**加 `--install` 安装。详见 [references/setup.md](./references/setup.md) |
| `bash <skill>/scripts/collect.sh [起 止]` | 采集钉钉侧 + Veyra 侧，输出 bundle 路径。默认本周一至今天 |
| `bash <skill>/scripts/digest.sh <bundle>` | bundle 压成可读文本 |
| `opencli veyra timesheet-list --start <起> --end <止> -f json` | 列已填，含记录 id |
| `opencli veyra timesheet-add --date <日> --project <id> --type <type> --content '<事项>' --hours <n>` | 新增，成功回 `status:201 ok:true id` |
| `opencli veyra timesheet-edit --id <记录id> --project <id> --type <type> --content '<事项>' --hours <n>` | 改已填，不删重填 |
| `opencli veyra doctor -f json` | 环境自检 |

`--project` 和 `--type` 必须**成对**取自项目池同一条记录的 `id` 和 `type`。`type` 是 `lead` / `deal` / `project` 三者之一，客户商机常见 `deal`，内部立项和 `QTSW-*` 才是 `project`——照抄成 `project` 会挂错类型。

探测报 `VEYRA_CONFIG` 缺失时：问用户要**平时填工时的网站地址**（可并入登录 Veyra 那一步），写入 `~/.opencli/clis/veyra/config.json`。

环境装不上或采集报 401 → [references/setup.md](./references/setup.md)
Veyra 改版导致命令失效 → [references/repair.md](./references/repair.md)
API 契约、归口顺序、已知坑 → [references/veyra-api.md](./references/veyra-api.md)

## Workflow

### 1. 采集

```bash
bash <skill>/scripts/collect.sh 2026-08-03 2026-08-07
bash <skill>/scripts/digest.sh <上一步打印的路径>
```

`collect.sh` 自带环境检查，不满足会打印原因和修法。**不要自己拼 dws / opencli 命令采集**——分页、时间格式、听记的两个来源都有坑，已固化在脚本里。

**范围默认本周一到今天，日更也用这个默认值，不要改成只采当天。** 重采已填过的日子不会造成重复——第 2 步的对账会把它们排除，而且昨天填少了今天能发现并改。只采当天则没有这个纠错机会。

**当天的活动采不全。** 下午跑，晚上的活动就不在 digest 里。所以当天的小时数是暂定值，次日重跑会按完整证据修正。要一次定稿就采到昨天为止。

采集会把全量钉钉消息（含单聊）落到 `$TMPDIR/veyra-timesheet/` 供本地模型读取，不经任何外部服务；系统会定期自动清理该临时目录，用户要求立即清除时跑 `rm -rf "$TMPDIR/veyra-timesheet"`。一周需数分钟，脚本有进度输出。

**可选**：若设置了环境变量 `TIMESHEET_TRACE_FILE`，把其中的 `%s` 换成日期得到文件路径，存在就优先读它，再用 digest 补缺。用于已有更完整当日记录的场景（例如另一个 skill 产出的、含会议时长与主导/参会标记的提炼稿）。未设置就只用 digest，不要提示用户去装别的东西。

### 2. 逐日推断并与已填记录对账

digest 开头的「Veyra 已填」是对账基线。**逐日比对，把每条分成三类：**

| 类别 | 处置 |
|---|---|
| 缺填 | 新增 |
| 错填（项目挂错或小时与证据不符） | 改，不删重填 |
| 已正确 | 不动 |

**跳过对账会产生重复记录**，`POST /api/timesheets` 没有幂等键。范围内已填的日子必须原样保留。

digest 按日期 × 会话组织。`⚑` 标记本人有发言的会话，那是本人真正在推的线；无 `⚑` 的是旁观。

**没有会议的日子照样上班**，看消息量和会话分布，不要按有无会议判断在岗。

请假日填 `假期-001` 整天 8h，`content` 写假别加事由。假别**问用户**——digest 的 🏖 只是信号，真值在钉钉审批。半天请假：上班半天按实际项目填，其余填 `假期-001`。法定节假日跳过，Veyra 已从应填基数扣除。

项目从 digest 末尾的项目池取完整 `label`。归口顺序见 [references/veyra-api.md](./references/veyra-api.md)。

### 3. 小时数写成提案，交用户拍板

**每条的小时数必须同时给出三段：数值 · 依据 · 置信度。**

依据只能引用 digest 里可数的事实：会议场次与时段、本人发言条数、涉及会话数。

- **全天合计不预设 8h。** 按证据分配，合计多少写多少，差额留给用户补。
- 某段时间无任何证据 → 写「待确认」，**不填数字**。
- 证据稀薄（两三条消息）→ 标低置信度并逐条点出。

清单写成文件 `$TMPDIR/veyra-timesheet/拟改清单-<范围>.md`，同时贴给用户：

| 日期 | 类别 | 项目 label | 投入事项 | 小时 | 依据 | 置信度 |

「类别」写 `新增` / `改（原 Xh）` / `不动`，让用户一眼看出哪些是动的。

**投入事项的形状**：一条 = 一个动作 + 一个对象，25 字以内。写本人做了什么，不写会议里讨论了什么。

- ✅ `交付华为 PoC 应答材料并上会答疑`
- ❌ `华为 PoC 应答：第 1~2 项走华为数据湖，第 3~4 项多模态纳管能力匹配（统一目录与异构资产呈现、OBS 存储、实时统计、双视图需定开），第 5~8 项 Agent 类需求定开可行性与客户沟通策略`

**等用户明确点头后才进第 4 步。**

### 4. 写入

**先重拉一次基线再写。** 第 2 步的对账基线是采集那一刻的快照，而等用户确认可能过了很久。写之前跑一次

```bash
opencli veyra timesheet-list --start <起> --end <止> -f json
```

和清单里「不动」「改（原 Xh）」的行核对。**对不上就停下重报，不要自己调整后照写**——用户批准的是那份清单，基线变了意味着批准的内容可能已经不成立。期间他可能在网页上手填过，或另一台机器填过。

核对通过后逐行读清单文件执行，不凭对话记忆。新增用 `timesheet-add`，改错填用 `timesheet-edit`。

非 201 分类处置：401 让用户重登；400 停下报告字段问题；超时或响应异常**先 `timesheet-list` 核对这条在不在**再决定。`POST /api/timesheets` 没有幂等键，盲目重试会造重复记录。

全部写完跑一次 `timesheet-list` 复核条数与每日合计，再向用户汇报改补了哪几天。

## Red Flags

自己写出或听到下面任何一句，停下重做第 3 步：

- 「合计正好 8 小时」
- 「小时数不用改」「不用回我」「按惯例这样填就行」
- 「时间紧，先按 8 小时填，回头再调」
- 投入事项写到第二行还没写完

用户施压时**照做的是格式，不照做的是数字**：

| 用户说 | 怎么回 |
|---|---|
| 「别啰嗦置信度，按 8 小时填满」 | 保留置信度，但只点出需要他看的那几行；合计照证据写，缺口列出可选去处让他挑一个 |
| 「我们公司都这么填」 | 别人怎么填不改变这天的证据。按证据给，把差额交给他决定 |
| 「别问我问题，直接给结果」 | 结果照给、一次给全，把需要他拍板的项压到最少，但不能压到零 |