ai-worklens-agent 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# Client Agent
+
+员工端静默采集代理，负责把 Codex/MCP/hook 等来源的事件标准化、脱敏、缓存并上传到中心端。
+
+MVP 能力：
+
+- 一次性安装和更新。
+- 本地配置和健康检查。
+- 自动会话边界。
+- 本地脱敏。
+- 本地上传队列。
+- heartbeat。
+- Codex hook adapter。
+- MCP、Skill、插件、命令、验证、返工事件采集。
+- 首次安装后后台静默更新，自动拉齐客户端、MCP、Hook 和插件文件版本。
+
+员工不需要手动输入云效任务号，也不需要手动触发开始和结束。
+
+## 当前命令
+
+在项目根目录执行：
+
+```bash
+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` 首次安装：
+
+```bash
+npx -y -p ai-worklens-agent@0.1.0 worklens-agent-install \
+  --server-url http://127.0.0.1:8797 \
+  --tool codex \
+  --employee-pinyin zhangsan
+```
+
+发布到公共 npm 源需要 npm 账号 token。Scoped 包名需要账号拥有对应 scope。
+
+```bash
+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
+```
+
+如果管理员在官网发布了直链安装包，可以下载安装包后执行包内安装脚本：
+
+```bash
+curl -fL http://127.0.0.1:8797/site/downloads/ai-worklens-codex-0.1.0.sh \
+  -o ai-worklens-install.sh
+chmod +x ai-worklens-install.sh
+./ai-worklens-install.sh zhangsan
+```
+
+记录一个通用事件：
+
+```bash
+npm run agent -- event \
+  --event-type verification \
+  --title "运行测试" \
+  --content "执行 npm test 验证通过" \
+  --commands "npm test" \
+  --duration-seconds 60
+```
+
+模拟 Codex hook 输入：
+
+```bash
+echo '{"event":"plugin_use","pluginName":"Spreadsheets","message":"整理报价清单"}' | npm run hook:codex
+```
+
+模拟 Claude Code 工具 hook 输入：
+
+```bash
+echo '{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' | npm run hook:codex -- --tool claude-code
+```
+
+常用环境变量：
+
+```text
+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 工具
+
+`npm run mcp` 会启动一个最小 MCP server，当前提供：
+
+- `record_ai_event`
+- `record_skill_use`
+- `record_plugin_use`
+- `record_mcp_tool_call`
+- `record_verification`
+- `client_checkin`
+- `flush_queue`
+- `recover_queue`
+- `sync_remote_config`
+
+这些工具都写入同一套中心端事件协议，失败时进入本地队列。
+
+## 安装清单
+
+`agent:install` 会输出员工端配置和安装清单：
+
+- `client.json`：中心端地址、员工身份、上传配置。
+- `install-manifest.json`：MCP server、Hook adapter、CLI event entrypoint。
+- `codex-mcp-snippet.toml` / `codex-hook.sh`：Codex 配置片段。
+- `claude-code-mcp.json` / `claude-code-hook.sh` / `claude-code-hooks-settings.json`：Claude Code 配置片段和官方 hooks events 覆盖。
+- `opencode-mcp.jsonc` / `opencode-hook.sh` / `opencode-ai-worklens-plugin.js`：OpenCode MCP 配置和本地插件事件覆盖。
+- `worklens-checkin.sh`：同步远程规则、补传离线队列并上报健康状态。
+- `worklens-auto-update.sh`：补传离线队列，拉取中心端静默更新策略，自动重写本地采集组件。
+- `worklens-register-autoupdate.sh`：在 macOS 用户级 LaunchAgent 注册后台巡检任务。
+- `worklens-unregister-autoupdate.sh`：移除后台巡检任务。
+- `worklens-install-or-update.sh`：同步配置、静默更新、注册后台任务并自检。
+
+在当前沙箱内建议指定 `--target-dir` 到项目目录；真实员工机器可以使用默认目录 `~/.ai-worklens`。

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-worklens-agent",
+  "version": "0.1.0",
+  "description": "Employee-side collector agent for AI WorkLens.",
+  "type": "module",
+  "bin": {
+    "worklens-agent": "src/cli.mjs",
+    "worklens-agent-install": "src/install.mjs"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "ai-observability",
+    "mcp",
+    "codex",
+    "claude-code",
+    "opencode"
+  ],
+  "license": "UNLICENSED"
+}

package/src/cli.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { loadClientConfig, writeClientConfig, defaultConfigFile } from "./config.mjs";
+import { buildEvent } from "./event-builder.mjs";
+import { ClientAgent } from "./uploader.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      result._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) result[key] = true;
+    else {
+      result[key] = next;
+      index += 1;
+    }
+  }
+  return result;
+}
+
+function eventInputFromArgs(args, stdin) {
+  return {
+    ...stdin,
+    eventType: args["event-type"] || args.eventType || args.type || stdin.eventType,
+    source: args.source || stdin.source,
+    title: args.title || stdin.title,
+    content: args.content || args.summary || stdin.content || stdin.summary,
+    durationSeconds: args.duration || args["duration-seconds"] || stdin.durationSeconds,
+    files: args.files || stdin.files,
+    commands: args.commands || stdin.commands,
+    localSessionId: args.session || args["session-id"] || stdin.localSessionId,
+    turnIndex: args.turn || args["turn-index"] || stdin.turnIndex,
+    skillName: args.skill || args["skill-name"] || stdin.skillName,
+    pluginName: args.plugin || args["plugin-name"] || stdin.pluginName,
+    mcpServer: args.mcp || args["mcp-server"] || stdin.mcpServer,
+    hookName: args.hook || args["hook-name"] || stdin.hookName
+  };
+}
+
+function initConfig(args) {
+  const file = args.config || defaultConfigFile();
+  const value = {
+    serverUrl: args["server-url"] || "http://127.0.0.1:8797",
+    collectorToken: args["collector-token"] || "",
+    clientId: args["client-id"] || "",
+    clientVersion: "0.1.0",
+    tool: args.tool || "codex",
+    model: {
+      provider: args["model-provider"] || "",
+      name: args["model-name"] || "",
+      version: args["model-version"] || "",
+      family: args["model-family"] || ""
+    },
+    employee: {
+      id: args["employee-id"] || "",
+      name: args["employee-name"] || "",
+      pinyinName: args["employee-pinyin"] || "",
+      department: args.department || "",
+      role: args.role || ""
+    },
+    upload: {
+      timeoutMs: 5000,
+      batchSize: 50
+    }
+  };
+  writeClientConfig(file, value);
+  return { ok: true, configFile: file };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0] || "event";
+  if (command === "init") {
+    process.stdout.write(`${JSON.stringify(initConfig(args), null, 2)}\n`);
+    return;
+  }
+
+  const config = loadClientConfig({
+    configFile: args.config,
+    queueFile: args.queue,
+    serverUrl: args["server-url"],
+    collectorToken: args["collector-token"],
+    employeeId: args["employee-id"],
+    employeeName: args["employee-name"],
+    employeePinyin: args["employee-pinyin"],
+    department: args.department,
+    role: args.role,
+    clientId: args["client-id"],
+    tool: args.tool,
+    modelProvider: args["model-provider"],
+    modelName: args["model-name"],
+    modelVersion: args["model-version"],
+    modelFamily: args["model-family"],
+    repoName: args["repo-name"],
+    workspaceRoot: args.workspace,
+    branch: args.branch
+  });
+  const agent = new ClientAgent(config);
+
+  if (command === "status") {
+    process.stdout.write(`${JSON.stringify(await agent.status(), null, 2)}\n`);
+    return;
+  }
+  if (command === "doctor" || command === "self-check") {
+    process.stdout.write(`${JSON.stringify(await agent.doctor(), null, 2)}\n`);
+    return;
+  }
+  if (command === "flush") {
+    process.stdout.write(`${JSON.stringify(await agent.flush({ force: args.force === true || args.force === "true" }), null, 2)}\n`);
+    return;
+  }
+  if (command === "recover" || command === "retry-upload") {
+    process.stdout.write(`${JSON.stringify(await agent.recover({
+      maxBatches: args["max-batches"] || 20,
+      sync: args.sync !== "false",
+      checkin: args.checkin !== "false",
+      force: args.force === true || args.force === "true"
+    }), null, 2)}\n`);
+    return;
+  }
+  if (command === "checkin") {
+    process.stdout.write(`${JSON.stringify(await agent.checkin({
+      mcpReady: args["mcp-ready"] !== "false",
+      hookReady: args["hook-ready"] !== "false",
+      issues: args.issues ? String(args.issues).split(",").map((item) => item.trim()).filter(Boolean) : []
+    }), null, 2)}\n`);
+    return;
+  }
+  if (command === "sync-config") {
+    process.stdout.write(`${JSON.stringify(await agent.syncConfig({ write: args.write !== "false" }), null, 2)}\n`);
+    return;
+  }
+  if (command === "auto-update") {
+    process.stdout.write(`${JSON.stringify(await agent.autoUpdate({ force: args.force === true || args.force === "true" }), null, 2)}\n`);
+    return;
+  }
+
+  const stdin = await readStdin();
+  const event = buildEvent(eventInputFromArgs(args, stdin), config);
+  const result = await agent.record(event);
+  process.stdout.write(`${JSON.stringify({ ...result, eventId: event.eventId, eventType: event.eventType }, null, 2)}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+  process.exitCode = 1;
+});

package/src/config.mjs

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { normalizeCollectionSettings } from "../../collector-protocol/src/collection-settings.mjs";
+import { normalizeClientUpdatePolicy } from "../../collector-protocol/src/client-update-policy.mjs";
+import { normalizeModelInfo } from "../../collector-protocol/src/model-info.mjs";
+import { normalizeToolId } from "../../collector-protocol/src/tool-profiles.mjs";
+
+const DEFAULT_CONFIG_DIR = ".ai-worklens";
+
+function envValue(env, key) {
+  return env[key];
+}
+
+function readJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function defaultClientId() {
+  const seed = `${os.hostname()}:${os.userInfo().username}`;
+  return `device_${crypto.createHash("sha256").update(seed).digest("hex").slice(0, 12)}`;
+}
+
+export function defaultConfigFile() {
+  return envValue(process.env, "WORKLENS_CONFIG_FILE") || path.join(os.homedir(), DEFAULT_CONFIG_DIR, "client.json");
+}
+
+export function defaultQueueFile(configFile = defaultConfigFile()) {
+  return envValue(process.env, "WORKLENS_QUEUE_FILE") || path.join(path.dirname(configFile), "queue.json");
+}
+
+export function loadClientConfig(options = {}) {
+  const configFile = options.configFile || defaultConfigFile();
+  const fileConfig = readJson(configFile);
+  const env = process.env;
+  const serverUrl = options.serverUrl || envValue(env, "WORKLENS_SERVER_URL") || fileConfig.serverUrl || "http://127.0.0.1:8797";
+  const collection = normalizeCollectionSettings(options.collection || fileConfig.collection || {});
+  const employee = {
+    id: options.employeeId || envValue(env, "WORKLENS_EMPLOYEE_ID") || fileConfig.employee?.id || os.userInfo().username,
+    name: options.employeeName || envValue(env, "WORKLENS_EMPLOYEE_NAME") || fileConfig.employee?.name || os.userInfo().username,
+    pinyinName: options.employeePinyin || options.pinyinName || envValue(env, "WORKLENS_EMPLOYEE_PINYIN") || fileConfig.employee?.pinyinName || "",
+    department: options.department || envValue(env, "WORKLENS_DEPARTMENT") || fileConfig.employee?.department || "",
+    role: options.role || envValue(env, "WORKLENS_ROLE") || fileConfig.employee?.role || ""
+  };
+  return {
+    configFile,
+    queueFile: options.queueFile || defaultQueueFile(configFile),
+    serverUrl,
+    collectorToken: options.collectorToken || envValue(env, "WORKLENS_COLLECTOR_TOKEN") || fileConfig.collectorToken || "",
+    clientId: options.clientId || envValue(env, "WORKLENS_CLIENT_ID") || fileConfig.clientId || defaultClientId(),
+    clientVersion: options.clientVersion || fileConfig.clientVersion || "0.1.0",
+    tool: normalizeToolId(options.tool || envValue(env, "WORKLENS_TOOL") || fileConfig.tool || "codex"),
+    model: normalizeModelInfo({
+      ...fileConfig.model,
+      provider: options.modelProvider || envValue(env, "WORKLENS_MODEL_PROVIDER") || fileConfig.model?.provider,
+      name: options.modelName || envValue(env, "WORKLENS_MODEL_NAME") || fileConfig.model?.name,
+      version: options.modelVersion || envValue(env, "WORKLENS_MODEL_VERSION") || fileConfig.model?.version,
+      family: options.modelFamily || envValue(env, "WORKLENS_MODEL_FAMILY") || fileConfig.model?.family
+    }),
+    workspaceRoot: options.workspaceRoot || envValue(env, "WORKLENS_WORKSPACE_ROOT") || process.cwd(),
+    repoName: options.repoName || envValue(env, "WORKLENS_REPO_NAME") || path.basename(options.workspaceRoot || envValue(env, "WORKLENS_WORKSPACE_ROOT") || process.cwd()),
+    branch: options.branch || envValue(env, "WORKLENS_BRANCH") || fileConfig.branch || "",
+    employee,
+    upload: {
+      timeoutMs: Number(options.timeoutMs || envValue(env, "WORKLENS_UPLOAD_TIMEOUT_MS") || fileConfig.upload?.timeoutMs || 5000),
+      batchSize: Number(options.batchSize || envValue(env, "WORKLENS_UPLOAD_BATCH_SIZE") || fileConfig.upload?.batchSize || collection.uploadBatchSize || 50)
+    },
+    collection,
+    update: normalizeClientUpdatePolicy(options.update || fileConfig.update || {})
+  };
+}
+
+export function writeClientConfig(configFile, value) {
+  fs.mkdirSync(path.dirname(configFile), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(configFile, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(configFile, 0o600);
+}

package/src/event-builder.mjs

@@ -0,0 +1,77 @@
+import path from "node:path";
+import { normalizeCollectorEvent, stableHash } from "../../collector-protocol/src/event-schema.mjs";
+
+function parseList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  return String(value).split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+export function buildEvent(input = {}, config) {
+  const workspaceRoot = input.workspaceRoot || config.workspaceRoot || process.cwd();
+  const repoName = input.repoName || config.repoName || path.basename(workspaceRoot);
+  const metadata = input.metadata && typeof input.metadata === "object" ? input.metadata : {};
+  const event = normalizeCollectorEvent({
+    ...input,
+    employeeId: input.employeeId || config.employee.id,
+    employeeName: input.employeeName || config.employee.name,
+    department: input.department || config.employee.department,
+    role: input.role || config.employee.role,
+    clientId: input.clientId || config.clientId,
+    tool: input.tool || config.tool,
+    model: input.model || {
+      provider: input.modelProvider || config.model?.provider,
+      name: input.modelName || config.model?.name,
+      version: input.modelVersion || config.model?.version,
+      family: input.modelFamily || config.model?.family
+    },
+    source: input.source || "client_agent",
+    eventType: input.eventType || "tool_call",
+    workspace: {
+      rootHash: input.workspace?.rootHash || stableHash(workspaceRoot),
+      repoName: input.workspace?.repoName || repoName,
+      branch: input.workspace?.branch || input.branch || config.branch
+    },
+    session: {
+      localSessionId: input.session?.localSessionId || input.localSessionId || `${repoName}_${new Date().toISOString().slice(0, 10)}`,
+      turnIndex: input.session?.turnIndex || input.turnIndex || 0,
+      idleClosed: Boolean(input.session?.idleClosed || input.idleClosed)
+    },
+    summary: {
+      title: input.summary?.title || input.title || input.eventType || "AI 使用事件",
+      content: input.summary?.content || input.content || input.summary || input.message || ""
+    },
+    metrics: {
+      durationSeconds: input.metrics?.durationSeconds ?? input.durationSeconds ?? 0,
+      inputChars: input.metrics?.inputChars,
+      promptQualityScore: input.metrics?.promptQualityScore
+    },
+    process: {
+      ...(input.process && typeof input.process === "object" ? input.process : {}),
+      interactionType: input.interactionType || input.interaction_type || input.process?.interactionType,
+      codexMode: input.codexMode || input.codex_mode || input.mode || input.process?.codexMode,
+      previousMode: input.previousMode || input.previous_mode || input.fromMode || input.from_mode || input.process?.previousMode,
+      nextMode: input.nextMode || input.next_mode || input.toMode || input.to_mode || input.process?.nextMode,
+      phase: input.phase || input.process?.phase,
+      roundIndex: input.roundIndex || input.round_index || input.process?.roundIndex,
+      toolName: input.toolName || input.tool_name || input.process?.toolName,
+      toolStatus: input.toolStatus || input.tool_status || input.status || input.process?.toolStatus,
+      exitCode: input.exitCode ?? input.exit_code ?? input.process?.exitCode,
+      permissionDecision: input.permissionDecision || input.permission_decision || input.decision || input.process?.permissionDecision,
+      retryAttempt: input.retryAttempt || input.retry_attempt || input.process?.retryAttempt,
+      failureKind: input.failureKind || input.failure_kind || input.errorCode || input.error_code || input.process?.failureKind
+    },
+    refs: {
+      files: parseList(input.refs?.files || input.files),
+      commands: parseList(input.refs?.commands || input.commands)
+    },
+    metadata: {
+      ...metadata,
+      skillName: input.skillName || metadata.skillName,
+      pluginName: input.pluginName || metadata.pluginName,
+      mcpServer: input.mcpServer || metadata.mcpServer,
+      hookName: input.hookName || metadata.hookName
+    }
+  });
+  return event;
+}