ai-worklens-agent

v0.1.13

Published

7 days ago

Employee-side collector agent for AI WorkLens.

0High
0Medium
0Low

s1ow

ai-observability mcp codex claude-code opencode

Client Agent

员工端静默采集代理，负责把 Codex/Hook/可选 MCP 等来源的事件标准化、脱敏、缓存并上传到中心端。

MVP 能力：

一次性安装和更新。
本地配置和健康检查。
自动会话边界。
本地脱敏。
本地上传队列。
heartbeat。
Codex hook adapter。
Hook 识别 Skill、插件、MCP 调用、命令、验证和返工事件。
首次安装后后台静默更新，自动拉齐客户端、MCP、Hook 和插件文件版本。

员工不需要手动输入云效任务号，也不需要手动触发开始和结束。

当前命令

在项目根目录执行：

npm run agent:status
npm run agent:install -- --target-dir ./.worklens-client --server-url http://127.0.0.1:8797 --tool codex
npm run agent:install -- --target-dir ./.worklens-client --server-url http://127.0.0.1:8797 --tool claude-code
npm run agent:install -- --target-dir ./.worklens-client --server-url http://127.0.0.1:8797 --tool opencode
npm run agent:sync -- --config ./.worklens-client/client.json
npm run agent:auto-update -- --config ./.worklens-client/client.json
npm run agent:checkin
npm run agent:flush
npm run agent:recover
npm run mcp

如果管理员已经把员工端发布到 npm 或企业私有 npm 源，可以使用 npx 首次安装：

Windows 命令提示符或 PowerShell 使用一行命令，不要混用 macOS/Linux 的反斜杠换行：

npx -y --loglevel=error --registry https://registry.npmjs.org -p [email protected] worklens-agent-install --server-url http://192.168.1.241:8797 --tool codex --employee-pinyin zhangpeng

macOS / Linux：

NPM_CONFIG_UPDATE_NOTIFIER=false npx -y --loglevel=error -p [email protected] worklens-agent-install \
  --server-url http://192.168.1.241:8797 \
  --tool codex \
  --employee-pinyin zhangsan

默认安装会启用 MCP，便于保留手动记录和健康上报能力。如果后续确认 token 开销需要进一步压缩，可追加 --mcp false 重新安装为 Hook-only 模式。

安装完成后请重新打开一个新的 Codex 会话。第一次触发 Hook 时，如果 Codex 提示信任或允许 Hook，请选择信任/允许；否则 codex-hook.cmd 手动验证可以成功，但真实 Codex 会话不会触发采集。

发布到公共 npm 源需要 npm 账号 token。Scoped 包名需要账号拥有对应 scope。

npm run client:npm:publish -- \
  --package-name @your-org/ai-worklens-agent \
  --version 0.2.0 \
  --tag latest \
  --dry-run

NPM_TOKEN=<npm_token> npm run client:npm:publish -- \
  --package-name @your-org/ai-worklens-agent \
  --version 0.2.0 \
  --tag latest

如果管理员在官网发布了直链安装包，可以下载安装包后执行包内安装脚本：

curl -fL http://192.168.1.241:8797/site/downloads/ai-worklens-codex-0.1.13.sh \
  -o ai-worklens-install.sh
chmod +x ai-worklens-install.sh
./ai-worklens-install.sh zhangsan

记录一个通用事件：

npm run agent -- event \
  --event-type verification \
  --title "运行测试" \
  --content "执行 npm test 验证通过" \
  --commands "npm test" \
  --duration-seconds 60

模拟 Codex hook 输入：

echo '{"event":"plugin_use","pluginName":"Spreadsheets","message":"整理报价清单"}' | npm run hook:codex

Windows 命令提示符验证 Codex hook 是否真实可执行：

echo {"hook_event_name":"UserPromptSubmit","prompt":"worklens windows smoke","session_id":"manual-smoke"} | "%USERPROFILE%\.ai-worklens\codex-hook.cmd"

如果这条命令成功上报，但真实 Codex 会话仍没有数据，优先检查是否已经在 Codex 中信任/允许了 Hook，并确认使用的是安装后新打开的 Codex 会话。

模拟 Claude Code 工具 hook 输入：

echo '{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' | npm run hook:codex -- --tool claude-code

常用环境变量：

WORKLENS_SERVER_URL=http://127.0.0.1:8797
WORKLENS_EMPLOYEE_ID=E001
WORKLENS_EMPLOYEE_NAME=张三
WORKLENS_DEPARTMENT=产品研发
WORKLENS_ROLE=前端工程师
WORKLENS_CLIENT_ID=zhangsan-mac
WORKLENS_TOOL=codex
WORKLENS_MODEL_PROVIDER=openai
WORKLENS_MODEL_NAME=gpt-5.4
WORKLENS_MODEL_VERSION=5.4
WORKLENS_CONFIG_FILE=/path/to/client.json
WORKLENS_QUEUE_FILE=/path/to/queue.json

Hook 事件映射

| Hook 输入 | 标准事件 | | --- | --- | | user_prompt / prompt / user_message | user_prompt | | assistant_response / assistant_turn | assistant_response | | skill_use | skill_use | | plugin_use | plugin_use | | mcp_tool_call | mcp_tool_call | | UserPromptSubmit / PostToolUse / PreToolUse | user_prompt / tool_call / command | | command 且命令包含 test/lint/build/typecheck | verification | | command 普通命令 | command | | error / failure | error | | rework / retry / fix | rework |

上传失败时事件会留在本地 queue.json，下次 agent:flush、agent:recover、后台巡检或新事件触发时继续发送。

离线缓存和恢复

每条事件先写入本地队列，再按批上传到中心端。
中心端不可用、HTTP 失败、超时或只接收了部分事件时，未确认事件继续保留在 queue.json。
队列会记录失败次数、最近错误和下次重试时间，默认指数退避，避免中心端故障时持续高频请求。
中心端恢复后执行 npm run agent:recover 会同步最新采集规则、按批补传队列并上报健康状态。
需要人工立即补传时可执行 npm run agent:recover -- --force，会忽略 nextAttemptAt 直接重试。
服务端按 eventId 幂等接收，同一事件重传不会重复入库；客户端根据服务端返回的 eventIds 清理已确认事件。

MCP 工具

默认安装会启用 MCP 作为 Hook 之外的健康上报和手动补记入口。npm run mcp 会启动一个轻量 MCP server，当前对模型暴露：

record_ai_event
client_checkin
flush_queue
recover_queue
sync_remote_config

record_ai_event 覆盖 Skill、插件、MCP 调用、模式切换、工具结果、验证和重试等事件维度。旧版细分工具名仍可调用以兼容已安装客户端，但不再出现在 tools/list，减少模型可见 schema 的 token 开销。所有 MCP 事件仍写入同一套中心端事件协议，失败时进入本地队列。

安装清单

agent:install 会输出员工端配置和安装清单：

client.json：中心端地址、员工身份、上传配置。
install-manifest.json：Hook adapter、CLI event entrypoint 和可选 MCP server 信息。
codex-mcp-snippet.toml / codex-hook.sh / codex-hook.cmd：Codex 可选 MCP 片段和默认 Hook 脚本。
claude-code-mcp.json / claude-code-hook.sh / claude-code-hook.cmd / claude-code-hooks-settings.json：Claude Code 可选 MCP 配置片段和官方 hooks events 覆盖。
opencode-mcp.jsonc / opencode-hook.sh / opencode-hook.cmd / opencode-ai-worklens-plugin.js：OpenCode 可选 MCP 配置和本地插件事件覆盖。
worklens-checkin.sh / worklens-checkin.cmd：同步远程规则、补传离线队列并上报健康状态。
worklens-auto-update.sh / worklens-auto-update.cmd：补传离线队列，拉取中心端静默更新策略，自动重写本地采集组件。
worklens-register-autoupdate.sh：在 macOS 用户级 LaunchAgent 注册后台巡检任务。
worklens-unregister-autoupdate.sh：移除后台巡检任务。
worklens-install-or-update.sh：同步配置、静默更新、注册后台任务并自检。

在当前沙箱内建议指定 --target-dir 到项目目录；真实员工机器可以使用默认目录 ~/.ai-worklens。

Published

Vulnerabilities

Links

Maintainers

Keywords