agent-work-log

一个可移植的、只提醒不直写的 work-log npm 插件，支持 Pi、Claude Code、Codex 和 Grok。

它把同一套判断逻辑分成三层：

• 共享 hook：跟踪用户提示、工具调用和回合结束，只在有实质进展时提醒一次；
• work-log skill：说明什么时候写、如何只查最近 10 条并决定更新或新建；
• Pi adapter：使用 Pi 原生事件，同时给 claude-bridge 子进程设置宿主标记，防止内外两层重复触发。

发布包不内置任何用户的思源数据库 ID 或 token，也不直接写数据库。真正的写入仍由当前模型通过本机 siyuan MCP 完成。hook 的持久化状态只包含布尔值、计数和不可逆事件哈希，不保存原始提示、助手回复、工作目录或会话 ID。

前置条件

• Node.js 20 或更高版本；
• 目标 Agent 已安装并能启动；
• 每个需要落盘的 Agent 都能访问 siyuan MCP gateway；
• 首次启用 Claude Code、Codex 或 Grok 插件 hook 时，人工检查并信任 hook 命令。

安装

发布到 npm 后，在每台机器运行：

npx @yizixu/agent-work-log@latest install

从本地 tarball 安装：

npx .\yizixu-agent-work-log-0.1.1.tgz install

只配置部分 Agent：

npx @yizixu/agent-work-log@latest install --targets pi,claude

只生成共享 marketplace、暂不调用各 Agent 的插件安装命令：

npx @yizixu/agent-work-log@latest install --no-activate

安装器会生成 ~/.agent-work-log/marketplace，其中只有一份插件源码。Claude Code、Codex 和 Grok 从各自的 marketplace manifest 安装它；Pi 的 settings.json 直接指向同一插件目录。

如果检测到旧的 ~/.pi/agent/extensions/work-log/config.json，安装 Pi 适配器时会：

1. 把兼容配置迁移到 ~/.agent-work-log/config.json；
2. 生成不含未知字段或凭据字段的兼容备份 config.json.pre-agent-work-log.bak；
3. 仅把旧扩展的 enabled 改成 false，不删除旧代码。

安装完成后新开 Agent 会话。

状态与配置

agent-work-log status
agent-work-log status --json

全局配置：~/.agent-work-log/config.json。默认值见 config/default.json。

首次安装后必须填写自己的思源事项库和已完成视图 ID；插件没有可回退的内置个人数据库。待办视图可选：

{
  "siyuan": {
    "taskDatabaseId": "<your-task-database-id>",
    "completedViewId": "<your-completed-view-id>",
    "todoViewId": "<your-todo-view-id>"
  }
}

缺少 taskDatabaseId 或 completedViewId 时，hook 会安全跳过提醒和写入。

常用配置：

• enabled：全局启用或关闭；
• minPromptChars / minProgressChars：过滤短聊天；
• requireToolUse：没有工具调用时不提醒；
• skipIfSiyuanWriteThisTurn：本轮已写思源时跳过；
• skipNativeWhenHostedBy：在 Pi 这类上层宿主中关闭内层原生 hook；
• siyuan：事项库、视图、字段和去重窗口配置。

Pi 中还可使用：

/work-log on
/work-log off
/work-log status

防重复机制

• hook 绑定 Agent 生命周期，不绑定模型名称；
• 相同 promptId、toolUseId 和 Stop 事件会幂等处理；
• 一轮最多发送一次 work-log continuation；
• 检测到本轮调用思源写操作后立即跳过提醒；
• Pi 设置 AGENT_WORK_LOG_HOST=pi，因此 pi-claude-bridge 内的 Claude Code hook 会直接放行；
• work-log 数据去重固定只读最近 10 条，避免全库扫描和历史完成日期被改写。

隐私与本地数据

• 配置和状态文件在支持 POSIX 权限的平台上以仅当前用户可读写的模式创建；Windows 使用当前用户 ACL；
• 状态文件不保存原始提示、助手回复、工具参数、工作目录或原始会话 ID；
• 调试日志只记录动作和会话 ID 的哈希；状态默认 7 天后清理；
• 旧配置迁移只接受当前版本支持的字段，token、secret、password 等未知字段不会进入新配置或兼容备份；
• npm run audit:sensitive 会扫描发布源中的常见凭据、私钥、个人路径和硬编码思源 ID。

开发与打包

npm test
npm run check
npm pack

GitHub 自动发布

仓库包含两个 workflow：

• .github/workflows/ci.yml：在 main 和 Pull Request 上使用 Node.js 20、22、24 执行测试、包校验、敏感数据扫描和打包预览；
• .github/workflows/release.yml：推送 v* tag 后校验 tag 与包版本，执行完整检查，通过 npm Trusted Publishing（OIDC）发布，并创建带 .tgz 附件的 GitHub Release。

首次发布需要完成一次引导：

1. 确认 GitHub 仓库是 yizixu/agent-work-log；若实际地址不同，同时修改 package.json 的 repository、homepage 和 bugs。
2. npm 包使用 scoped 名称 @yizixu/agent-work-log。无需在 npm 网站预先新建仓库或包：首次成功执行 npm publish 时会自动创建公开包。先确认当前登录的是拥有 @yizixu scope 的账号，再完成首次发布：

npm login
npm whoami
npm run check
npm publish --access public

3. 在 npm 包设置中添加 Trusted Publisher：选择 GitHub Actions，填写 GitHub owner、仓库名和 workflow 文件名 release.yml，允许 npm publish。不需要在 GitHub 保存长期 NPM_TOKEN。
4. 在干净工作区执行 npm 的版本命令；内置 version lifecycle 会同步 package.json、.codex-plugin/plugin.json 和 .claude-plugin/plugin.json，运行完整检查并创建 tag：

npm version patch
git push origin main --follow-tags

release workflow 使用 GitHub 托管 runner、id-token: write 和 npm 11.5.1 以上版本；Trusted Publishing 会自动生成 npm provenance。建议同时启用 GitHub tag protection，限制谁可以创建发布 tag。