Ai Log

ai-log

把「上次记录日志到现在」的工作内容总结后追加写入本地日志文件。

> 命令入口为 scripts/ai_logger.py（薄入口，委托给同目录 scripts/ailog/ 包： > config / session / store / transcript / render / entry / cli 各司其职）。 > 可视化模板 scripts/template.html 是构建产物——源码在 scripts/src/（CSS/JS/HTML 部件）， > 由 scripts/build/build_template.py 拼装；改样式或前端逻辑请改 src/ 后重跑构建脚本，勿手改产物。 > 调用方式不变，仍为 python3 /scripts/ai_logger.py ...。 > 下文用 `` 指代本 skill 所在目录的绝对路径（运行时以实际路径替换）。

保存目录（root）从哪来

脚本不再写死任何路径。保存目录按以下优先级解析：

1. --root ：仅本次生效，不落盘。
2. 配置文件 ~/.config/ai-log/config.json 的 root 字段：永久位置，由 --set-root 写入。
3. 兜底 ~/.cache/ai-log：临时位置，未永久指定时使用。

（~/.config、~/.cache 分别尊重 XDG_CONFIG_HOME / XDG_CACHE_HOME。）

永久位置保存在独立配置文件里，不写进本 SKILL.md，因此 skill 文件保持纯规范、可安全随仓库分发。

标准作业流程（SOP）

第 0 步：检查是否需要询问永久保存位置（仅在未永久指定时触发）

每次记录前先查状态：

python3 /scripts/ai_logger.py --status

输出形如 {"configured": true/false, "source": "...", "root": "...", "config_path": "..."}。

• configured: true → 已永久指定，跳过询问，直接进入第 1 步。
• configured: false → 尚未永久指定。用 AskUserQuestion 询问用户是否要永久指定一个保存位置：
• 用户给出目录 → 本次用 --set-root 一次性「永久指定并立即记录」（见第 2 步）。
• 用户暂不指定 → 本次落到临时兜底目录 ~/.cache/ai-log，不写配置，下次仍会再次询问。

> 询问只在 configured:false 时发生；一旦永久指定，后续不再打扰用户。

第 1 步：思考总结

> 先判断模式：默认是「分段模式」——总结上一次记录到现在这一时间段，产出 1 条日志。 > 若用户输入 /ai-log full、或要求「按主题总结所有对话 / 总结整个会话」，则进入 full 模式（见文末「full 模式」专节），按对话主题划分、一次产出多条日志。full 模式更耗 token，必须先获用户许可再执行。

先拟一个标题，再写正文：

• 标题：一句话概括本条日志做了什么，不超过 25 字，不带 markdown 标记。它会在网页详情面板顶部单独醒目展示。
• 正文：概述上一次记录日志到现在的工作内容。默认控制在 2000 字以内，多写细节（做了什么、关键取舍、结果）。聚焦事实，不堆砌套话。
• 可以使用 markdown、mermaid 与 LaTeX：正文支持丰富 markdown，可以多用小标题、列表、表格、引用、行内代码 来组织内容；涉及流程、架构、因果、时序关系时，可以画 mermaid 图（流程图/时序图等）让结构一目了然；涉及公式、复杂度、数学/统计表达时，可以用 LaTeX（行内 $...$、块级 $$...$$）让记法精确。
• 正文里不要再写大标题（# 一级标题）——标题已单独拎出。需要分段时只用小标题（## / ###）与列表。
• 若本条是跨午夜接续（见下）的新一天首条，正文里可先用一两句简要总结上一日的工作，再写今天的内容。

> 跨午夜接续由脚本自动判定：当天本会话还没有记录、但更早日期里有本会话的尾巴时，脚本会把新日志存到今天，起点继承昨日结束时间、时长按真实跨日计算，并在 data.json 写入 carryover 字段；网页会在该条详情面板与时间线节点上标注「前一部分在上一日」。你无需传任何跨日参数，只需在正文里简述上一日即可。

> 正文 markdown / mermaid / LaTeX（可以使用）：标题 #~######（1~6 级）、有序/无序列表、表格、引用、行内代码、围栏代码块、**加粗**/*斜体*；mermaid 图表——把图写在 `mermaid 围栏里即可，网页渲染为矢量图；LaTeX 公式——行内 $...$、块级 $$...$$，由 KaTeX 渲染。三者的库均随 skill 本地分发、离线可用，缺失时回退 CDN。善用这些让日志结构清晰、信息密度高：流程/架构/因果/时序场景可优先画 mermaid 图，公式/复杂度/数学表达可用 LaTeX。 > 注意：用单引号 heredoc 传参时 $ 不会被 Bash 展开（见第 2 步），故 $...$ 公式原样保留、无需转义。

第 1.5 步：复用本仓库其他 skill 的产物（效率最大化）

写正文不必从零编造。本段工作中若用到了同仓库的 code-review / git-commit / code-comment，它们已经沉淀了现成、准确的素材，优先复用而非重新归纳：

• git-commit 的产物：本段的 commit message（git log 范围内的标题 + 正文）本就是「为什么改」的高质量摘要，可直接提炼进日志，避免与提交记录两处口径不一致。
• code-review 的产物：本段做过的审查发现（拦下的 log 滥用 / 注释腐化 / 边界问题、最终修订与取舍）是日志的天然内容，结构化记录即可。
• code-comment 的判定：涉及注释改动时，沿用 code-review/code-comment 已给出的结论，不重复推敲。

> 跨 skill 调用需先征得用户同意：复用产物若只是「读取本会话已有的结论 / 已存在的 commit message」，属轻量引用，可直接用。但若需要主动触发另一个 skill 去现做（例如为了写日志而去跑一遍 code-review、或调 git-commit 补一次提交），必须先向用户说明要调用哪个 skill、做什么，获得明确许可后再执行；未获许可则仅凭现有信息总结。

第 2 步：调用脚本

为避免 Bash 篡改内容，summary 一律用「单引号 heredoc」传参，禁止用双引号直接拼接；--title 较短可直接用引号传：

SUMMARY=$(cat /scripts/ai_logger.py --title "本条日志标题（≤25字）" --summary "$SUMMARY"

# 用户本次选择永久指定目录：永久落盘 + 立即记一条
python3 /scripts/ai_logger.py --set-root "/your/chosen/dir" --title "标题" --summary "$SUMMARY"

> ⚠️ 传参规范（关键）： - 这是 markdown 块级语法（# 标题 / - 列表 / | 表格）能正确渲染的前提——renderMd 按真实换行逐行扫描。 > - **切勿**写成 --summary "第一行\n- 列表项"：双引号里的 \n 是字面反斜杠+n 而非换行，整段会被压成一个 ，块级 markdown 全部失效；内容中的 $VAR、 cmd 还会被 Bash 展开/执行，导致内容被篡改甚至命令报错、日志写不进去。 > - 内容长度不受限（脚本对 --summary` 无字数上限），写多行富文本时务必用上面的 heredoc 方式。

会话代号无需自己生成：脚本读环境变量 CLAUDE_CODE_SESSION_ID 哈希派生「emoji + 动物名 + 后缀」（如 🦊 Fox-3f2a），同一会话恒定、不同会话独立。时间戳也由脚本算：本次开始时间 = 本会话上一条的结束时间（无则等于结束时间，因此不同会话区间可重叠），结束时间 = 当前时间。

token / 轮数自动记录：脚本据 CLAUDE_CODE_SESSION_ID 定位会话 transcript（~/.claude/projects/*/.jsonl），统计「本会话上一条记录之后到现在」这一分段的 input/output/cache tokens、对话轮数与 API 调用次数，写入条目的 usage 字段。无需传参；transcript 不可用时该字段缺失、UI 自动省略。

第 3 步：确认输出

执行完成后仅输出一句简短确认（如「✅ 日志已保存」，可附 index.html 路径），禁止输出多余解释。若本次落在临时兜底目录，可顺带提醒一句「本次为临时位置，可随时永久指定」。

在线提交（双模式）

用户明确说「双提交」「在线提交」「同步到线上」、或输入 /ai-log online 时，在写完本地 data.json 之后 额外 POST 到 Ailogy 后端。

提交目标（report_url）从哪来

与保存目录管理机制一致，按以下优先级解析：

1. 环境变量 AILOG_REPORT_URL（优先级最高）
2. 配置文件 ~/.config/ai-log/config.json 的 report_url 字段（永久，由 --set-report-url 写入）
3. 兜底空字符串（不上报）

只需填根地址（如 https://ailogy.icloudsheep.top），无需精确到具体 GET/POST 方法——脚本自动拼 /api/ingest/entries。

配置流程

# 永久指定提交地址（写入 config.json，之后每次 --report 自动用）
python3 /scripts/ai_logger.py --set-report-url https://ailogy.icloudsheep.top

# 查看当前配置（--status 输出含 report_url 字段）
python3 /scripts/ai_logger.py --status
# → {"configured": true, "root": "...", "report_url": "https://ailogy.icloudsheep.top", ...}

触发方式

用户在对话中说「双提交」「在线提交」、或用 /ai-log online 时，在记录日志的命令中追加 --report：

python3 /scripts/ai_logger.py --report --title "标题" --summary "$SUMMARY"

上报行为

• 上报是尽力而为：成功打印 📤 已在线提交至 ，失败打印 ⚠️ 在线提交失败（本地已保存）：，不阻断本地写入。
• 未配置 report_url 时带 --report 会提示 ⚠️ 已要求在线提交但未配置提交地址，建议用户先 --set-report-url。
• 无 --report 时不触发上报（默认行为不变）。

> ⚠️ 仅当用户明确要求时才加 --report。普通「记录日志」不加此参数——不自动上报。

设备标识（device）

每条上报会带上设备名，后端据此提供「按设备筛选」。设备名解析优先级：

1. 环境变量 AILOG_DEVICE
2. 配置文件 ~/.config/ai-log/config.json 的 device 字段
3. 兜底主机名（socket.gethostname() 的首段）

首次在线提交前必须确认设备名（强制）：当用户首次要 --report、且 config.json 中尚无 device 字段时，先用 AskUserQuestion 询问用户本机的设备名（给出主机名作为默认建议），然后用 --set-device 写入配置：

# 首次确认设备名（写入 config.json）
python3 /scripts/ai_logger.py --set-device "我的 MacBook"

• 若用户接受默认主机名，仍写入配置以固定（避免主机名变动导致设备漂移）。
• 主机名可能在多机间重复：若用户有多台同名机器，提醒其各自指定不同设备名（如加后缀），避免数据混在一起。
• 一旦 device 已配置，后续 --report 不再询问。

full 模式（整段对话回溯总结）

触发：用户输入 /ai-log full，或要求「按主题总结所有对话 / 按每轮总结 / 总结整个会话 / 分别记日志」。

与默认「分段模式」的区别：不按时间点总结当前一段，而是回看整段对话、按所选颗粒度（主题 / 轮次）切分，一次产出多条日志。

第 0 步：先获用户许可 + 选颗粒度与数据来源（强制）

full 模式要遍历大量对话内容，比普通记录显著更耗 token。执行前必须用 AskUserQuestion 向用户说明并征得同意，且让用户选择颗粒度与数据来源两项：

颗粒度（按什么划分一条日志）：

• 按对话主题（粗，推荐）：把若干连贯的任务/问题归为一个主题，一条日志。通常 2~8 条，信息密度高、token 适中。
• 按每轮对话（细）：用户每一轮提问（及其后的助手处理）各记一条。条数 = 真实提问轮数，可能很多条，token 消耗随轮数线性上升——轮数多时务必提醒用户。

数据来源：

• 读 transcript（更全、更耗 token）：读取本会话 ~/.claude/projects/*/.jsonl 的用户/助手消息，能覆盖已被上下文压缩、滚出窗口的早期对话；代价是要读完整 transcript，token 消耗最大。
• 凭当前上下文（更省）：仅凭当前对话上下文记忆划分；省 token，但被压缩/超窗的早期对话可能遗漏。

用户未明确同意前，不得开跑。

第 1 步：按所选颗粒度划分并各自总结

• 按主题：通读对话，按主题（一个连贯的任务/问题/专题）切分，主题数量由内容自然决定（通常 2~8 个，别硬凑）。
• 按轮次：以用户每一轮真实提问为界切分（排除纯工具结果回灌），每轮一条；轮的标题概括该轮诉求，正文记该轮的处理与结果。

每条都产出一条日志，各自遵循默认模式的标题（≤25 字）+ 正文（≤2000 字、多用 markdown/mermaid）规范。排序：按在对话中出现的先后顺序排列。

第 2 步：按主题顺序串行写入

逐条调用脚本（同一会话内多次调用），带 --mode full 标记（使时间线节点显示 🚀 角标），脚本会让每条的开始时间自动接续上一条的结束时间，从而把整段会话串行切成多个主题块：

# 主题 1
python3 /scripts/ai_logger.py --mode full --title "主题一标题" --summary "$SUMMARY_1"
# 主题 2（start 自动接主题 1 的 end）
python3 /scripts/ai_logger.py --mode full --title "主题二标题" --summary "$SUMMARY_2"
# …按出现顺序继续

每条 summary 仍用单引号 heredoc 传参（见第 2 步传参规范）。多条日志会追加到当天，与普通日志同列、同会话代号，在时间线上按主题依次排开。

第 3 步：确认输出

全部写完后仅输出一句简短确认，并附主题条数（如「✅ 已按主题记录 5 条日志」）。

自定义会话名称（别名）

每个会话的自动代号（如 Fox-3f2a）可重命名为易读名称，跨所有日期对同一会话生效。所有展示会话名处变为「自定义名 (自动代号)」。两层持久化：

• 网页右键胶囊：在鼠标位置动画弹出菜单（含「重命名」），输入名称 → 写浏览器 localStorage，即时生效、跨所有日期（file:// 下各 index.html 同源共享 localStorage）。换浏览器 / 清缓存会丢失。
• 脚本固化（永久保存）：写入 /aliases.json 并同步刷新 /aliases.js，换设备 / 清缓存仍在：

``bash python3 /scripts/ai_logger.py --rename "Fox-3f2a" "重构专项" # 设别名 python3 /scripts/ai_logger.py --rename "Fox-3f2a" "" # 清别名 ``

> 零重渲染：数据走外部 JS 资产而非内联——每天页面引用同目录 ./data.js、所有页面共享引用根部 ../aliases.js。file:// 下浏览器允许 ` 加载本地 js（不受 fetch 的 CORS 限制），故改别名只重写 aliases.js 一个文件，所有日期页面刷新即生效，**无需重渲染任何 HTML**。 > 网页渲染时 **localStorage 软别名优先于 aliases.js 硬别名**。右键改名后控制台会打印对应的 --rename 命令，便于一键永久固化。 > 注意：index.html / data.js / 根部 aliases.js` 三者需保持目录结构在一起（单独拷走某个 html 会丢数据）——这是离线零重渲染的合理取舍。

编辑 / 删除日志条目

每条日志详情面板右上角有 ✏️ 编辑 与 🗑️ 删除 按钮，两层持久化（与别名同理）：

• 网页操作（即时、本地）：
• 编辑：弹出源码编辑框，标题为单行文本、正文为 Markdown 源码多行框（⌘/Ctrl+Enter 保存），支持 mermaid 代码块与 $LaTeX$ 公式。
• 删除：二次确认后即时隐藏该条。
• 改动写入浏览器 localStorage（键 ai-log:edits，按 日期#seq 定位），跨同源所有日期、刷新即生效；换浏览器 / 清缓存会丢失（删除可借此恢复）。
• 脚本固化（永久写回 data.json）：网页操作后控制台会打印对应命令，运行即把改动落盘并重渲染该日 HTML：

``bash # 编辑某条（按 日期 + seq 定位；--title / --summary 至少给一个） python3 /scripts/ai_logger.py --edit "2026-06-24" 3 --title "新标题" --summary "$SUMMARY" # 删除某条（其余条目 seq 保持不变，避免打乱定位） python3 /scripts/ai_logger.py --delete "2026-06-24" 3 ``

> 网页渲染时 localStorage 覆盖层优先于 data.json：未落盘的本地改动始终生效；一旦运行落盘命令、data.json 已是最新，覆盖层与之一致即无差异。

产物（按天目录 /{YYYY-MM-DD}/）

• data.json：结构化数据真源，脚本读写。每条记录含 seq(当天序号)、title(标题)、会话代号(id/emoji/name)、start/end/duration、datetime、project(工作目录名)、branch(git 分支)、model、cwd、summary 等字段；跨午夜接续的条目还含 carryover(prev_date/prev_end)；含 transcript 数据时还含 usage(input/output/cache_read/cache_write/turns/api_calls)。
• data.js：当天数据的 JS 资产（window.AILOG_DATA = {...}），由 data.json 生成，供 index.html 以 `` 加载。
• index.html：纯静态模板，运行时读取 ./data.js 与 ../aliases.js 渲染，双击离线打开。明亮多彩流动背景 + 浅色磨砂玻璃前景：
• 吸顶头部：标题 + 会话图例胶囊；左键切换该会话显隐、右键在鼠标位置弹出菜单自定义名称（有别名时显示「自定义名(自动代号)」，括号内为半透明小字）。
• 左侧泳道（独立滚动）：每会话一列、每条日志一行，节点 = emoji + 当天序号，同列竖线连接同一会话；不同会话区间可重叠。跨午夜接续的节点左上角带 🌙 角标。
• 右侧详情：点击节点后纵向堆叠多个磨砂玻璃框；首框顶部单独展示该条标题（右上角有编辑/删除按钮），其下为会话头与跨日标注（若有）；其余框为日志内容(支持 markdown、mermaid 图与 $LaTeX$ 公式) / 时间 / 本段消耗(token/轮数) / Git 分支 / 模型 / 项目目录，单次只展示一条；节点与详情间有低透明度静态虚线连接。
• 页脚磨砂玻璃，标注当天时间跨度与总时长。

另有 /aliases.js（root 根目录，所有日期共享）：window.AILOG_ALIASES = {...} 会话别名资产，由 --rename / 右键固化维护；其人读真源为同目录 aliases.json。

` 根还有三处指向 skill 内 git 受控资产的软链，git pull 更新 skill 后页面刷新即读到新内容、无需重渲染：version.js（版本号）、mermaid.min.js（mermaid 库）、katex/（KaTeX 公式库目录，含 katex.min.js / katex.min.css / fonts/*.woff2`，离线可用，加载失败回退 CDN）。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: icloudsheep
• Source: icloudsheep/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.