ai-log

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

当会话 ID、模型、transcript、用量或设备名的探测结果异常时，读取 references/platform-runtime.md；正常记录无需加载该文件。

命令入口为 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 <SKILL_DIR>/scripts/ai_logger.py ...。 下文用 <SKILL_DIR> 指代本 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 <SKILL_DIR>/scripts/ai_logger.py --status

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

• configured: true → 已永久指定，跳过询问，直接进入第 1 步。
• configured: false → 尚未永久指定。使用当前平台可用的用户询问机制询问是否要永久指定一个保存位置：
  • 用户给出目录 → 本次用 --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（可以使用）：标题 #######（16 级）、有序/无序列表、表格、引用、行内代码、围栏代码块、**加粗**/*斜体*；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 <<'EOF'
## 小标题
- 列表项
正文 **加粗** 与 `行内代码`
EOF
)
# 已永久指定 / 沿用现有配置或临时兜底：
python3 <SKILL_DIR>/scripts/ai_logger.py --title "本条日志标题（≤25字）" --summary "$SUMMARY"

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

⚠️ 传参规范（关键）：<<'EOF' 的单引号禁用了所有 Bash 展开，换行原样保留、$ ` ! 等特殊字符不被解释。

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

会话代号无需自己生成。脚本按以下顺序确定原始会话 ID：--session-id → AILOG_SESSION_ID → Codex 的 CODEX_THREAD_ID / Claude Code 的 CLAUDE_CODE_SESSION_ID。随后用 SHA1 确定性派生「emoji + 动物名 + 后缀」（如 🦊 Fox-3f2a），保证同一会话恒定、不同会话几乎不重复。若平台未暴露 ID，则使用固定的 Anon-0000，此时应建议调用者显式传入 --session-id，不能生成随机 ID 冒充稳定会话。时间戳由脚本计算：本次开始时间 = 本会话上一条的结束时间（无则等于结束时间），结束时间 = 当前时间。

平台、模型与 token / 轮数自动记录：平台解析顺序为 --platform → AILOG_PLATFORM → 平台会话变量 → generic。模型解析顺序为 --model → AILOG_MODEL → Claude Code 的 ANTHROPIC_MODEL / Codex 当前 rollout 最新 turn_context.model → 空值。transcript 可用 --transcript 或 AILOG_TRANSCRIPT 显式指定；否则 Claude Code 在 ${CLAUDE_CONFIG_DIR:-~/.claude}/projects 查找，Codex 在 ${CODEX_HOME:-~/.codex}/sessions 查找。脚本统计本会话上一条日志之后的分段用量；内部格式变化或文件不可读时省略 usage，绝不估算或伪造。

第 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.example.com），无需精确到具体 GET/POST 方法——脚本自动拼 /api/ingest/entries。

配置流程

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

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

触发方式

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

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

上报行为

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

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

设备标识（device）

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

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

首次在线提交前必须确认设备名（强制）：设备名是供人识别和筛选的标签，不是硬件唯一标识。解析顺序为 AILOG_DEVICE → config.json.device → 短主机名建议值。当用户首次要 --report 且环境变量和配置中都没有设备名时，必须使用当前平台可用的用户询问机制确认；可以展示短主机名作为建议，但不能未经确认直接持久化或上报。随后用 --set-device <名称> 写入配置：

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

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

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

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

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

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

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

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

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

数据来源：

• 读 transcript（更全、更耗 token）：读取当前平台定位到的会话 JSONL，能覆盖已被上下文压缩、滚出窗口的早期对话；代价是要读完整 transcript，token 消耗最大。读取前先通过 --status 的 runtime.transcript 确认路径；不可用时回退当前上下文并明确说明。
• 凭当前上下文（更省）：仅凭当前对话上下文记忆划分；省 token，但被压缩/超窗的早期对话可能遗漏。

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

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

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

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

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

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

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

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

第 3 步：确认输出

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

自定义会话名称（别名）

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

• 网页右键胶囊：在鼠标位置动画弹出菜单（含「重命名」），输入名称 → 写浏览器 localStorage，即时生效、跨所有日期（file:// 下各 index.html 同源共享 localStorage）。换浏览器 / 清缓存会丢失。

• 脚本固化（永久保存）：写入 <root>/aliases.json 并同步刷新 <root>/aliases.js，换设备 / 清缓存仍在：

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

零重渲染：数据走外部 JS 资产而非内联——每天页面引用同目录 ./data.js、所有页面共享引用根部 ../aliases.js。file:// 下浏览器允许 <script src> 加载本地 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：

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

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

产物（按天目录 <root>/{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 以 <script src> 加载。
• index.html：纯静态模板，运行时读取 ./data.js 与 ../aliases.js 渲染，双击离线打开。明亮多彩流动背景 + 浅色磨砂玻璃前景：
  • 吸顶头部：标题 + 会话图例胶囊；左键切换该会话显隐、右键在鼠标位置弹出菜单自定义名称（有别名时显示「自定义名(自动代号)」，括号内为半透明小字）。
  • 左侧泳道（独立滚动）：每会话一列、每条日志一行，节点 = emoji + 当天序号，同列竖线连接同一会话；不同会话区间可重叠。跨午夜接续的节点左上角带 🌙 角标。
  • 右侧详情：点击节点后纵向堆叠多个磨砂玻璃框；首框顶部单独展示该条标题（右上角有编辑/删除按钮），其下为会话头与跨日标注（若有）；其余框为日志内容(支持 markdown、mermaid 图与 $LaTeX$ 公式) / 时间 / 本段消耗(token/轮数) / Git 分支 / 模型 / 项目目录，单次只展示一条；节点与详情间有低透明度静态虚线连接。
  • 页脚磨砂玻璃，标注当天时间跨度与总时长。

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

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