SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场soia-pkm-log-agent-sessions

soia-pkm-log-agent-sessions

办公与效率

查看项目

更新于 10-16 08:51

技能介绍

用途

soia-pkm-log-agent-sessions 是 soia-open-pkm-vault-skills 提供的一个技能，职责非常单一：在本地 AI 工具（Claude Code、Codex 等）的会话结束时，为知识库（vault）记录一次最小化的改动快照。它不保存完整 prompt、对话或推理内容，也不判断内容应归档到哪里。

主要能力

  • 为 Claude Code 的 SessionEnd 或 Codex 的 notify 生成轻量日志。
  • 使用 git 状态、tracked diff 和 untracked 内容哈希去重；连续编辑同一文件仍会产生新快照。
  • 保留客户已有的 Codex notify 命令，并提供 dry-run、安装检查和卸载步骤。
  • 报告旧日志数量与体量；默认不自动删除或轮转。
  • 默认日志只写时间、agent、变更数量、按顶层分区统计和验证结果；不写 diff、正文、prompt、事件 JSON 或环境变量。
  • 默认不列单个文件路径，只有明确选择 --include-paths 才写入 git status 路径。

使用方式

客户需要提供 vault 路径、AI 名称和期望日志目录。Agent 先展示将修改的用户配置片段，只有客户明确同意后才合并写入。建议首次先手动 dry-run，再触发一次真实小改动进行验证。

手动验证命令：

python3 scripts/session_log.py --vault <vault-path> --agent Codex --dry-run
python3 scripts/session_log.py --vault <vault-path> --agent Codex

默认日志目录：30_日志与思考/20_Agent工作日志/10_自动快照/<年>/<agent>/。可用 --log-dir 或 SOIA_SESSION_LOG_DIR 覆盖；路径必须在 vault 内。agent 仅允许安全 slug。--vault 必须是 Git worktree 根；嵌在更大仓库中的子目录会拒绝运行，避免记录 vault 外改动。

配置硬约束（完整规则见 references/session-log-setup.md）：

  • 修改 .claude/settings.json 或 Codex config.toml 前必须得到客户明确同意。
  • 先备份原配置，结构化合并；已有 hook/notify 不覆盖。
  • 路径使用安装后真实脚本绝对路径。
  • 触发两次验收：第一次应写快照；无实质变化的第二次应为 deduplicated。
  • 再编辑同一 tracked 文件，必须产生新快照，证明去重包含内容而不只是文件名。

安装

依赖 Python 3 和 Git，shell wrapper 需要 POSIX bash。

推荐安装整个插件：

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia

只安装这一个技能：

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-log-agent-sessions -y

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到，需要单独安装，见 docs/install/workbuddy.md。

私有配置路径：~/.config/soia-skills/soia-pkm-log-agent-sessions/config.yml；也可用环境变量 SOIA_PKM_AGENT_SESSION_CONFIG_FILE=<custom-config-path> 指定。

去重状态存放于 $XDG_STATE_HOME/soia-pkm-log-agent-sessions/（无则 ~/.local/state/...），不写 .git，兼容 git worktree。

适用场景

需要为本地 AI 编码会话留下可追溯、但又不泄露敏感内容的最小改动记录时使用。例如记录 Codex 对 vault 的改动、配置 SessionEnd 日志、接入 AI 会话日志等。

限制与边界

  • 不做工作台/Inbox 分流（转 soia-pkm-manage-vault-lifecycle）。
  • 不做 vault 健康检查或知识检索。
  • 不执行 add/commit/push，不读取 git 对象正文到日志。
  • 不自动删除旧日志；需要清理时先输出按月份的数量/体量预览，再让客户单独确认。
  • 配置缺失、vault 非 git 仓库、路径越界或 agent 非安全 slug 时明确失败；hook 调用可选择吞掉失败以免阻断主工具，但安装验收不能忽略失败。

验收要点

  • 日志 frontmatter 使用 tags: [Agent日志, 自动快照]。
  • 状态不在 .git，worktree fixture 可运行。
  • 连续编辑同一路径的内容能产生不同 digest；无变化会去重。
  • 日志无完整 prompt/diff/正文/事件 JSON/秘密值。
  • 配置卸载后原有 hook/notify 仍完整。

回执包含配置是否变更、快照是否写入/去重跳过、日志相对目录、变更数量、状态目录类别、验证和卸载方法。