summary-user-said

Summary User Said

Read-only scan of the selected local session JSONL, outputting a traceable summary of user statements and an original text table. The script handles the data source, schema, time window, deduplication, evidence, and persistence; the Agent writes the summary only based on the messages.jsonl filtered by the script.

Input → DAG → Artifacts

validate_request(CLI)
  ├────→ --cursor ──┐
  ├────→ --claude ──┤
  ├────→ --codex ───┼→ discover_sources → collect_messages
  └────→ --dir ─────┘                         │
                                              ├→ 有消息 → agent_summary(TO_AGENT)
                                              │              ↓
                                              └→ 无消息 → agent_summary(skip)
                                                             ↓
                                              validate_summary → export_report
                                                                      ├→ 当前路径/<base>.md
                                                                      └→ 当前路径/<base>.messages.md

Privacy and reading boundaries: This skill does not connect to the network, upload, or modify source JSONL, code, or Git status. It does not redact; the filtered original text is passed to the Agent and written into local artifacts; it should only be run in trusted directories.user is only the role declared by the source record and does not prove the true speaker's identity.

Usage

SKILL_ROOT="<此 skill 的绝对路径>"

# 默认：Cursor + 前一个完整自然周
python3 "$SKILL_ROOT/scripts/run.py"

# 单个或组合内置源
python3 "$SKILL_ROOT/scripts/run.py" --cursor --day 3
python3 "$SKILL_ROOT/scripts/run.py" --claude --week 2
python3 "$SKILL_ROOT/scripts/run.py" --cursor --claude --codex --day 7

# 指定目录：自动识别 Cursor、Claude、Codex 的已知 JSONL schema
python3 "$SKILL_ROOT/scripts/run.py" --dir /path/to/history --week 1

When there are matching messages, the first run will agent_summary pause and return exit 2:

# 1. 读取 envelope.data.brief_path 和 messages_path
# 2. 只读取 messages_path，按 brief 写 agent_summary_path
# 3. 用 envelope.data.resume_command 续跑并生成双产物
python3 "$SKILL_ROOT/scripts/run.py" --resume <job_dir>

When there are no matching messages, it does not pause and directly generates dual artifacts stating "no matching user statements".

Parameters

Parameter	Description
`--cursor`	Read `~/.cursor/projects/*/.jsonl`; can be combined with `--claude`、`--codex` combination
`--claude`	Read `~/.claude/projects/*/.jsonl`
`--codex`	Read `~/.codex/sessions/*/.jsonl`
`--dir <DIR>`	Custom history root directory; mutually exclusive with the three built-in sources
`--day <N>`	The previous N full natural days; N must be a positive integer and is mutually exclusive with `--week` mutually exclusive
`--week <N>`	The previous N complete ISO natural weeks; default `1`
`--resume <JOB_DIR>`	Resume waiting for the Agent's job; must be exclusive
`--schema`	Output the JSON contract; must be exclusive

When no data source is selected, default --cursor. Duplicate data sources, duplicate --dir, invalid ranges, or artifact conflicts will fail before scanning, without creating a job, reading history, or overwriting files.

Data sources and reading boundaries

Source	Authorized root directory	Only accepted user records
Cursor	`~/.cursor/projects/`	Top-level `role: user`, and `message.content[].type=text`
Claude Code	`~/.claude/projects/`	Top-level `type: user`, and `message.role: user`
Codex	`~/.codex/sessions/`	`event_msg/user_message`; for old sessions without the former, only then read `response_item/message/role=user`
`--dir`	User-specified directory	Line by line, only the above schema is recognized

The script parses the authorized root directory, discovers only regular .jsonl files within it, and rejects symbolic links; discovery statistics are written to the job artifact and first-run envelope. Unknown schemas and assistant/system/developer/tool content will not enter messages.jsonl。

Additional filtering out:

Cursor fixed closing prompts and duplicate messages within the same session
Claude cross-session forwarding, context continuation summaries, and request interruption events
Codex-concatenated QQ replies, artifact/environment/gateway/todo/browser rules, team delegation,.codex-team and <soul> role settings
Messages outside the window, with empty text, with unlocatable time, or with duplicate evidence

Time priority: Cursor in-text <timestamp>, Claude/Codex structured ISO time, source JSONL mtime fallback. Each message is determined independently and does not inherit the time of other records in the same file.

Output and lifecycle

stdout outputs only one line of JSON envelope {ok, data, error, meta}; esflow events and Agent guidance written to stderr
First run with messages:data.status=to_agent, and provides brief_path, the only messages_path、agent_summary_path that the Agent is allowed to read, and the continuation command
completed:data.status=end, including formal artifact paths, filtering statistics, and invariant checks
job saves process artifact; formal artifacts written directly tothe current directory when executing the command：

<source-set>-<day|week>-<start-date>_to_<end-date>.md
<source-set>-<day|week>-<start-date>_to_<end-date>.messages.md

.md: scope, filtering statistics, cycle overview, key points, decisions and to-dos, per-cycle summaries, recurring topics
.messages.md: in ascending time order, the | 时间 | 内容 | original text table
custom directory's source-set is a short path hash and does not expose the custom absolute path
the two formal artifacts are 0600 exclusively created; if either target already exists, the entire run is rejected and never overwritten

each summary entry must reference at least one source-id:line. Cycle entries may only reference messages from the same cycle; key decisions/to-dos may only be pending、blocked or confirmed; nonexistent, duplicate, or cross-cycle evidence will cause the continuation run to fail.

nodes (5)

id	depth	Responsibilities
`discover_sources`	0	Parse the authorization root directory, discover only regular JSONL within the root directory, and record a discovery audit
`collect_messages`	1	Extract user text according to the known schema, window it, deduplicate it, and write `messages.jsonl`
`agent_summary`	2	TO_AGENT when there are messages; brief limits the Agent to read-only `messages.jsonl`
`validate_summary`	3	Validate message counts, cycle attribution, summary structure, and evidence
`export_report`	4	Exclusively write the summary and original text dual artifacts

Exit codes

0: dual artifacts completed
1: runtime error
2: waiting for the Agent to write summary.json
3: parameter, path, artifact conflict, or business validation failure

Dependencies

pip install esflow

Python requires version 3.10 or higher. Before release, you can run:

python3 test/test_summary_user_said.py -v
python3 -m compileall -q skills/summary-user-said/scripts