操作留痕查询

> **本地运行，零网络、免 API Key、数据不出电脑。**
> 四项诚实承诺：① 算不出就说算不出，绝不编造数字；② 高危动作强制人工确认；③ 幂等断点，绝不重复副作用；④ 全程留痕可审计。

# 操作留痕查询

三十多个财税技能包，每个跑完都会往 `_out/` 写一行 `fin-log.jsonl`。
日志躺在各自的输出目录里，**想问「上个月到底跑了什么、哪次报了算不出」就得挨个目录翻**。

本包只做一件事：把某个目录下所有 `fin-log.jsonl` 递归收上来，按时间 / 技能 / 级别 / 关键词过滤，
出一张明细表 + 一张异常表（坏行 + 缺字段 + 被过滤统计）+ 一张校验表（计数全景）。

三条底线：

- **坏行不崩**：JSONL 里塞进半行乱码，只跳过那一行并登记「文件 + 行号 + 原文」，其余照常出表；
- **不合并原文**：本包只读，不把别人的日志内容搬进自己的 `fin-log.jsonl`，只记自己这次查询；
- **不猜级别来源**：日志自带 `level` 就用自带的；没有则按口径推导，并在「级别来源」列明写「推导」二字。

## 输入

| 用途 | 参数 |
|---|---|
| 要扫描的目录 | 位置参数 `dir`，递归找 `fin-log.jsonl`；**默认当前目录 `.`** |
| 起始时间 | `--since YYYY-MM-DD 或完整 ISO` |
| 结束时间 | `--until YYYY-MM-DD 或完整 ISO` |
| 技能过滤 | `--skill <slug>` **可重复**，按 slug 精确前缀匹配 |
| 级别过滤 | `--level <级别>` **可重复**，如 高 / 中 / 低 / INFO |
| 关键词 | `--keyword <子串>`，任意字段子串，大小写不敏感 |
| 打印条数 | `--limit N`，默认 20，只影响终端打印 |
| 输出目录 | `--out-dir`，默认 `_out` |
| 操作人 | `--operator`，写进本包日志 |
| 写盘 | `--execute`，不加只打印 |

日志文件的名字固定为 `fin-log.jsonl`（常量在 `fin_contract.LOG_NAME`），本包不认别的名字。

## 输出

| 文件 | 内容 |
|---|---|
| `at_留痕明细_主表.csv` | 文件 / 行号 / 时间 / slug / 级别 / 级别来源 / 事件 / 关键字段 |
| `at_留痕明细_异常表.csv` | 坏行 + 缺 ts / 缺 skill 的日志行 + 各过滤条件的被过滤条数（带风险等级） |
| `at_留痕明细_校验表.csv` | 扫描目录数 / 日志文件数 / 总行数 / 坏行数 / 缺字段行数 / 命中行数 / 各 skill 命中数 / 各级别命中数 / 时间范围 / 级别与时间口径 |
| `fin-log.jsonl` | 本包自己的一条查询记录（追加） |

主表按时间升序排列。

## 用法

```bash
PY="<python 3.8+ 路径>"   # 纯标准库

# 1) 先看有哪些：扫描当前目录（含子目录）的所有 fin-log.jsonl
"$PY" <skill目录>/scripts/trail_view.py _out

# 2) 按条件查（可重复 --skill / --level，写盘加 --execute）
"$PY" <skill目录>/scripts/trail_view.py _out \
      --since 2026-09-01 --until 2026-09-30 --skill loan-schedule --operator 张会计 --execute

# 只看高风险的算不出记录
"$PY" <skill目录>/scripts/trail_view.py _out --level 高 --execute
```

**默认不写盘**——不加 `--execute` 只打印预览，确认后再落盘。

## 真实输出（实测粘贴）

一次带时间窗口 + 技能过滤的查询：

```
方案：扫描 _out/at_logs | 日志文件 4 个 | 总行数 10 | 坏行 2 | 命中 3
过滤条件：since=2026-09-01 until=2026-09-30 skill=loan level=- keyword=-

--- 命中明细（3 条）---
  2026-09-20T09:00:00 | loan-schedule          | 低   (推导) | 计划提交复核 | 2026-09/loan-schedule/fin-log.jsonl:3
  2026-09-26T15:20:10 | loan-schedule          | 中   (推导) | 技能 loan-schedule 运行：输入 贷款明细.xlsx，读入 3 行，主表 0 行，异常 1  | 2026-09/loan-schedule/fin-log.jsonl:2
  2026-09-27T08:05:53 | loan-schedule          | 低   (推导) | 技能 loan-schedule 运行：输入 贷款明细.xlsx，读入 4 行，主表 77 行，异常 0 | 2026-09/loan-schedule/fin-log.jsonl:1

--- 坏行 / 缺字段 / 被过滤（6 条）---
  [高] 2026-08/invoice-book/fin-log.jsonl：缺可读的 ts 时间字段，无法参与时间过滤
  [低] 2026-09/accounting-archive/fin-log.jsonl：skill 不匹配（要 loan）：被过滤掉 2 条
  [低] 2026-08/invoice-book/fin-log.jsonl：时间早于 --since 2026-09-01：被过滤掉 1 条
  [低] 2026-09/broken/fin-log.jsonl：skill 不匹配（要 loan）：被过滤掉 1 条
  [高] 2026-09/broken/fin-log.jsonl：不是合法 JSON：Expecting ',' delimiter: line 1 column 12 (char 11)｜原文 {
  [高] 2026-09/broken/fin-log.jsonl：JSON 顶层不是对象（是 list），无法解析字段
--- 校验表 ---
  日志文件数 | 4
  总行数 | 10
  坏行数 | 2
  缺 ts 行数 | 1
  命中行数 | 3
  被过滤行数 | 4
  各 skill 命中数 | loan-schedule=3
  各级别命中数 | 中=1；低=2
  时间范围 | 2026-09-20T09:00:00 ~ 2026-09-27T08:05:53
```

日志自带级别字段时，主表会显示「高(字段)」而不是「高(推导)」：

```
  2026-09-27T10:30:00 | accounting-archive     | 高   (字段) | 发现重号凭证 | 2026-09/accounting-archive/fin-log.jsonl:2
```

## 拒绝权（什么情况下算不出）

| 情况 | 处理 |
|---|---|
| 目录不存在 / 不是目录 | **直接拒绝**：「不是目录或找不到」 |
| 目录里一个 `fin-log.jsonl` 都搜不到 | **直接拒绝**：「先跑一次别的技能包生成日志」 |
| 日志全是坏行，一条可读记录都没有 | **直接拒绝**：列出坏行后 refuse，不给出「0 条命中」的假成功 |
| 可读记录被过滤条件全部排除，命中 0 条 | **直接拒绝**：「N 条可读记录被过滤条件全部排除」，提示放宽条件 |
| 某行缺可读的 `ts` | 进异常表（高），不参与时间过滤 |
| 某行缺 `skill` | 进异常表（高），不进主表 |
| 某行不是合法 JSON / 顶层不是对象 | 进异常表（高），记文件 + 行号 + 原文前 80 字 |

坏行**不会让脚本崩溃**，也不会被静默吞掉——只是那一条不进主表。

## 关键设计（容易踩的坑）

1. **只读，不合并**：本包不会把别人的日志内容写进自己的 `fin-log.jsonl`，
   那里只留一条「我来查过，条件是这些」的记录。原日志一个字节都不改。
2. **级别口径必须说清**：现行 55 个技能包写的日志里**没有** `level` 字段
   （`write_log` 只记 ts/skill/version + 业务字段）。本包的级别是：
   ① 能读到 `level` / `级别` / `severity` 就用它（标「字段」）；
   ② 读不到就按内容推导——出现「算不出 / refuse / 拒绝执行」→ 高；异常行数 > 0 → 中；其余 → 低（标「推导」）。
   **推导值不是日志里的事实**，用它下结论前请回看原始那一行。
3. **`--skill` 是前缀匹配**：`--skill loan` 命中 `loan-schedule`，想精确就写全 slug。
4. **时间只认「YYYY-MM-DD 开头」**：`2026-09-27T08:05:53`、`2026-09-27` 都行；
   其他写法读不出就进异常表，绝不当成「无时间」蒙混过关，也绝不按 0 补。
5. **`--keyword` 搜的是整行**：把所有字段拼起来做子串匹配，
   命中哪一条要靠主表的「文件:行号」回原文件对。
6. **扫描目录别圈自己**：默认扫描 `.` 且输出在 `_out/`，
   如果 `fin-log.jsonl` 就在 `_out/` 下，下一次扫描会把自己这次的查询记录也算进去——
   要看历史就换个出参目录或指定更小的扫描范围。
7. **本包不管日志的真实性**：本地日志可以被人为编辑，本包只负责解析与呈现，
   不做防篡改校验（防篡改请用 `book-backup-verify` 对账套做 sha256 基线）。

## 人工复核（必读）

- 主表「级别」列里标「推导」的行，级别是本包按内容推断的，不是日志里写死的
- 「缺 ts / 缺 skill 的行」往往意味着日志被截断或被手工改过，值得回查源文件
- 被过滤掉的行并没有消失，异常表里都有条数，别只看主表就下「这段时间没跑过」的结论
- 关键词命中不代表业务上相关，关键词匹配的是任意字段的子串
- 日志时间取决于机器时钟，跨时区或改过系统时间的机器，时间范围会失真

## 相邻路线转交

| 用户要做的事 | 转交给 |
|---|---|
| 账套备份与可恢复性验证（sha256 基线） | `book-backup-verify` |
| 凭证附件归档与存证 | `accounting-archive` |
| 凭证号重号 / 分录校验 | `accounting-entry-check` |
| 发票重复报销核对 | `invoice-duplicate-check` |
| 异常行本身的业务核查 | `fin-anomaly-scan` |
| 归档目录里按月导出报表 | `report-batch-export` |

## 可直接复制的说法

```text
把我这个目录下所有技能包的运行日志（fin-log.jsonl）收上来查一下。
按时间、技能、级别、关键词过滤，坏行跳过但要告诉我哪一行坏了。
级别优先看日志里自带的 level 字段；没有的话你推导，但要在表里标明是推导的。
缺时间或缺技能字段的行单独列出来，别混进明细里。
查不到任何日志就说查不到，不要给一个"命中 0 条"糊弄我。
先给我看预览，确认了再加 --execute。
```

## 做完怎么算完成

- [ ] 主表行数 = 各 skill 命中数之和，与终端打印一致
- [ ] 坏行已逐条回原文件查看，不是「没找到」而是「看懂了」
- [ ] 标「推导」的级别已抽查若干条，确认推导口径符合业务判断
- [ ] 被过滤条数之和 + 命中数 + 缺字段数 = 总行数 - 坏行数
- [ ] 时间范围与预期一致（跨年 / 跨月的时间窗口已试过）
- [ ] 原日志未被改动，输出只落在 `--out-dir`
- [ ] 命中结果已回查过原始日志行，没有「看起来合理但其实是解析错位」的记录

---

本 Skill 采用 BUSL-1.1 许可（源码可见，可自由使用）。

版权所有 © 2026 律令科技（深圳）有限公司（@lexord-technology）。
本技能由律令科技（深圳）有限公司开发，**财友云（caiyouyun.cn）**发布与展示。

允许个人及企业内部免费使用、复制、修改，包括内部生产环境。
未经书面许可，不得将本 Skill 或其修改版作为商业服务对外销售、转售或提供托管服务。
各版本发布之日起 4 年后自动转为 Apache License 2.0。详见随包 `LICENSE.md`。