---
name: swing-ccms-report-work
description: 使用 swing-cli report-work 进行 CCMS 自动报工。当用户要求报工、填报工时、报一下昨天/今天/某天的工时、查询或申报工时记录、生成报工提案、提交或删除工时记录时使用。
---

# CCMS 自动报工

通过 `swing-cli report-work` 生成报工提案、逐块写入 CCMS 并管理记录。命令参数以当前安装版本的 `--help` 输出为准，不要凭记忆拼接参数。

## 基本原则

- 使用 `swing-cli`，不要在未征得 Operator 同意时改用会联网下载包的 `npx`。
- 默认按 JSON 处理输出。判断成功与否时读取顶层 `success` 字段，不要只看进程退出码。
- 不读取本地 Token 文件，不输出 Token、密码、Cookie 或 Authorization header。
- 不猜测 server、项目 ID、模块 ID 或其他标识符。先查询，存在歧义时询问 Operator。
- 只执行 Operator 请求所需的最小命令。

## 命令面

- `report-work source`：Evidence Scope 授权管理（`add`/`list`/`remove`/`discover`）
- `report-work mapping`：Target Mapping 管理（`list`/`add`/`suggest`/`accept`/`remove`）
- `report-work context`：为指定日期生成最小化 Proposal Context
- `report-work proposal`：提案管理（`import`/`preview`/`discard`）
- `report-work apply` / `resume`：按已确认指纹逐块写入 / 续传
- `report-work list`：查看某日报工记录与 Managed 状态
- `report-work receipt list`：查看 Apply Receipts
- `report-work delete`：删除 CLI 创建且仍为 STAY 的 Managed 记录

## 自动报工流程

当 Operator 要求生成报工提案时：

1. 运行 `report-work source list`，确认 Evidence Scope 只包含已授权根目录；为空时先 `source discover` 展示候选并征得授权。
2. 运行 `report-work context --date <YYYY-MM-DD>`（日期按 Operator 所述或昨天，Asia/Shanghai）。请假、调休或半天必须使用 `--off-day` 或 `--blocks` 显式覆盖，绝不根据活动量推断出勤。
3. 只使用 Proposal Context 中的 Evidence Digests、实时授权目标和 Target Mappings。不得读取上下文未包含的原始 diff、完整会话、隐藏推理或工具输出。

### 证据分析与提案生成

- 按 `evidence[].projectHint` 和 `source` 聚类证据，识别当天 2 到 4 个主要工作主题；每块对应一个主题，同一主题最多拆两块且明细必须可区分。证据量大时优先分析 `projectHint` 与相关仓库的子集，不逐条阅读全部证据。
- Work Block 时段由 CCMS 定义（`FIRST`→`FORTH` 顺序覆盖工作日），无需查证时段切分。
- 生成 `schemaVersion: 1` 提案 JSON：每个 Expected Work Block 恰好一项；证据不足时用 `state: unresolved`，不得用历史目标或当天主目标补齐。
- 已解决项必须包含项目、完整 Module Path、叶子模块名、Approval Target，以及 1 到 4 条独立 Work Detail List。不发送 `taskId`；明细中不写 Agent 名称、commit hash、会话引用或本地路径。
- **Work Detail List 简洁规则**：每条只写结果不写过程，动宾短句、不超过 20 字。例如「完成生产执行报表只读复核」而非「对 41 个表单标识逐项分类并交叉核对 37 个 UUID 分布」。证据细节放进 `evidenceRefs` 引用，不要抄进 remark。
- 多个项目可出现在同一提案（不同块归属不同项目），每块携带自己的 `approvalUserId`。

### 确认与写入

1. 导入提案并运行 `report-work proposal preview <id>`，把完整预览和 Proposal Fingerprint 展示给 Operator。
2. 只有 Operator 明确确认该指纹后，才可运行 `report-work apply <id> --fingerprint <fingerprint>`。`apply` 一个命令逐块写入，每块 payload 携带各自的 `approvalUserId`，无需按项目分开执行；某块失败时报告已成功块和失败块，再次确认恢复意图后才运行 `resume`。
3. 写入后运行 `report-work list --date <date>` 与 `report-work receipt list --date <date>` 核对 live 状态与回执。
4. 删除只允许使用 `list` 返回且 `managed: true` 的记录；必须展示 snapshot 并再次获得确认。

Target Mapping 的人工纠正不会自动学习。使用 `mapping suggest` 生成建议后，必须再次确认才能运行 `mapping accept --confirm`。

## Sensitive Operation

以下操作前必须获得 Operator 对该条具体命令的明确确认：

- `report-work apply`、`report-work resume`：必须确认当前 preview 输出的 Proposal Fingerprint
- `report-work delete`：必须确认当前 `list` 输出的记录 snapshot
- `report-work mapping accept`、`report-work mapping remove`
- `report-work proposal discard`

确认只对展示的 server、日期、对象和参数有效。任何参数变化都必须重新确认。

## 失败与重试

- 查询命令遇到临时网络错误时最多重试一次。
- 写命令超时或网络错误后，不要立即重试，先用查询命令检查目标状态；确认未生效后才能重新执行，重新执行前再次确认。
- 实际业务命令返回 `AUTH_ERROR`、HTTP 401 或 HTTP 403 时停止，请 Operator 在 Agent 会话之外的终端重新登录；不要索要账号密码，不要代执行 `auth login`。

## 向 Operator 报告

报告应包含目标环境、执行的命令、每块写入结果、receipt 状态与写后核对结果；不粘贴含敏感字段的原始响应。