# Ai Log

> 记录 AI 工作日志。当用户发送「记录日志」「记一下日志」「log 一下」等指令时使用，自动为本次工作拟一个标题（≤25字）并总结上一次记录至今的内容（正文默认 2000 字内，可以用 markdown、mermaid 图与 LaTeX 公式），写入按天目录 {保存目录}/{YYYY-MM-DD}/ 下的 data.json 与可视化 index.html。自动统计本段 token 与对话轮数；跨午夜接续会自动存入新一天并标注；网页可右键胶囊给会话自定义名称（跨所有日期生效），也可在详情面板/节点右键菜单编辑、删除、预览日志条目。另有 full 模式（`/ai-log full` 或「按主题/按每轮总结所有对话」）：回看整段对话、按用户所选颗粒度（主题或轮次）划分，一次产出多条日志（节点带 🚀 角标），更耗 token，须先获用户许可并选颗粒度与数据来源。支持在线提交（`/ai-log…

- **Type:** Skill
- **Install:** `agentstack add skill-icloudsheep-claude-skills-ai-log`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [icloudsheep](https://agentstack.voostack.com/s/icloudsheep)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [icloudsheep](https://github.com/icloudsheep)
- **Source:** https://github.com/icloudsheep/claude-skills/tree/main/skills/ai-log

## Install

```sh
agentstack add skill-icloudsheep-claude-skills-ai-log
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 步：检查是否需要询问永久保存位置（仅在未永久指定时触发）

每次记录前先查状态：

```bash
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` 较短可直接用引号传：

```bash
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`。

### 配置流程

```bash
# 永久指定提交地址（写入 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`：

```bash
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 ` 写入配置：

```bash
# 首次确认设备名（写入 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` 标记（使时间线节点显示 🚀 角标），脚本会让每条的开始时间自动接续上一条的结束时间，从而把整段会话**串行切成多个主题块**：

```bash
# 主题 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](https://github.com/icloudsheep)
- **Source:** [icloudsheep/claude-skills](https://github.com/icloudsheep/claude-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-icloudsheep-claude-skills-ai-log
- Seller: https://agentstack.voostack.com/s/icloudsheep
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.