@teammy/cli 0.0.10 → 0.1.0

package/README.md

@@ -2,10 +2,12 @@
 
 成员设备上的命令行客户端，需要 Node.js 22.13+，推荐 Node.js 24。
 
-0.0.10 与服务端保持版本一致，支持多项目后台同步、根 README / `_template/` 公共资料分发，以及 `workspaces/.teammy-local.json` 中的 `files.ignore` 忽略规则。规则相对本人目录，下一轮检查生效，不删除已共享历史。公共资料由项目设置指定的一位成员维护。自动任务整理在服务端运行。
+0.1.0 提供完整目录发布、后台升级修复、Hook 清理与新增 Agent 采集支持，需与配套服务端一起升级。
+
+客户端与服务端保持配套版本，支持多项目后台同步、根 README / `_template/` 公共资料分发，以及 `workspaces/.teammy-local.json` 中的 `files.ignore` 忽略规则。规则相对本人目录，下一轮检查生效，不删除已共享历史。公共资料由项目设置指定的一位成员维护。自动任务整理在服务端运行。
 
 ```sh
-npm install -g @teammy/cli@0.0.10
+npm install -g @teammy/cli@0.1.0
 ```
 
 ```sh
@@ -22,7 +24,7 @@ teammy logs
 
 本人本地文件是发布来源，服务器旧正文不会下载到本人目录。首次本地缺失的历史文件保留在服务器，不推断为删除；确认曾在本地存在的文件，之后删除并完成稳定等待才传播。其他成员目录只接收，不反向发布，本地误改会保留并报告。
 
-默认约一分钟检查一次，每个文件连续一分钟没有变化后发布；首次下载立即开始，大批量接收自动续批。周期由全站网页设置热更新。项目会话通过 hook 及后台补扫自动登记、提取并上传；只采集属于当前项目目录的会话，不自动扩展到 monorepo 上层其他会话。已有接入可通过 `sync on` 安装本项目 hook。
+默认约一分钟检查一次，文件变化连续一分钟稳定后准备完整目录版本；内容可分批传输，完整版本发布后才对外可见并触发任务整理。首次下载立即开始，大批量接收自动续批。周期由全站网页设置热更新。项目会话通过 hook 及后台补扫自动登记、提取并上传；只采集属于当前项目目录的会话，不自动扩展到 monorepo 上层其他会话。已有接入可通过 `sync on` 安装本项目 hook。
 
 macOS 使用用户 LaunchAgent，Linux 使用 systemd 用户服务；不安装系统级服务、不启用 lingering。登录会话没有可用服务管理器的环境可用 `connect --no-start` 后运行 `sync --foreground`，此方式需保持终端运行。Windows 暂不支持自动后台服务。
 
@@ -32,8 +34,32 @@ macOS 使用用户 LaunchAgent，Linux 使用 systemd 用户服务；不安装
 
 `sync --once` 执行一轮并可复用后台进程；不保证文件已稳定或所有批次完成。需要手动覆盖时，先 off，再使用 `sync --once --settle-ms 0`、`--restore-missing`、`--retry` 等参数。`--restore-missing` 只恢复缺失的同事副本，不覆盖现有修改。`--adopt-baseline` 保留为显式核对本人本地文件与历史一致性的工具，正常接入不需要。管理员重置设备后，先 off，再用原 connect 命令加 `--reconnect`，保留同步基线。
 
-已接入目录不能静默改绑；切换项目需指定另一个项目根。若修改 Node.js 或 CLI 安装位置，重新运行 sync on 可更新该用户服务的启动路径。服务依赖安装路径持续存在，不能把临时安装目录当作长期运行环境。
+已接入目录不能静默改绑；切换项目需指定另一个项目根。若修改 Node.js 或 CLI 安装位置，运行 `teammy repair` 更新所有绑定项目的 Hook 和后台入口。服务依赖安装路径持续存在，不能把临时安装目录当作长期运行环境。
+
+对话库汇集成员与 Agent 的工作对话，支持 Claude Code / tclaude、Codex / tcodex、Cursor CLI SQLite / 远程 transcript JSONL、Pi v3（用户级被动采集扩展）、DSH v0。连接或开启同步时合并项目 hook，保留已有用户配置；hook 只登记本地线索，不等待网络，后台统一上传用户与 assistant 正文。`session list`、`session search --query TEXT`、`session read --owner MEMBER --key KEY` 用于查询对话库；`session sources` 查看本机来源；详见 `teammy session --help`。产品名称更新不改变 `session` 子命令。
+
+## 更新与卸载
+
+本次文件发布协议依赖服务端 `atomic-file-publications` 能力，两端需配套更新。以下维护命令从 0.1.0 提供，先安装新版，再执行修复：
+
+```sh
+npm install -g @teammy/cli@0.1.0
+teammy repair
+```
+
+`repair` 替换后台并校准全部绑定项目的 Hook，保留身份、队列和各项目 on/off 状态；同版本重装也可执行。不要求旧服务先成功停止，不依赖服务器在线。仅安装 npm 包不会替换已经运行的进程，因此请执行第二条命令。
+
+`teammy repair --stop` 持久暂停整个本机后台；显式 `repair` 或 `sync on` 恢复。`status` 和 `logs --all` 在业务库异常时仍提供可用诊断。不要通过清空状态目录处理普通升级问题。
+
+```sh
+teammy session teardown --all  # 仅移除 Hook，目录发现继续工作
+teammy session setup           # 显式恢复当前项目 Hook
+teammy uninstall               # 移除后台服务和所有已登记 Hook，保留用户数据
+npm uninstall -g @teammy/cli
+```
+
+上述命令支持 `--state-dir`；多个独立状态目录需分别清理。卸载 Hook 后，普通 repair/sync on 不会重新注入；显式 session setup 或重新接入才会启用。已启动的 Agent 可能缓存旧命令，需要新开会话加载配置。新版 Hook 即使遇到入口缺失、未绑定或解析失败，也静默成功，不向 prompt/system prompt 插入文本、Skill、工具或 MCP 配置。
 
-会话支持 Claude Code、Codex、Cursor CLI SQLite / 远程 transcript JSONL、Pi v3、DSH v0。连接或开启同步时合并项目 hook，保留已有用户配置；hook 只登记本地线索，不等待网络，后台统一上传用户与 assistant 正文。`session list`、`session search --query TEXT`、`session read --owner MEMBER --key KEY` 用于查看团队会话；`session sources` 查看本机来源；详见 `teammy session --help`。
+Pi 扩展随连接和修复自动维护，支持自定义 profile 与会话路径；仅采集已绑定项目，不增加模型工具或上下文。`--no-session` 不采集正文。多个项目共享扩展，卸载最后一个绑定的 Hook 后移除扩展文件。最新版使用最近落盘分支，已上传的旧版本保留搜索。
 
 服务器单独安装 `@teammy/server`。`server-info --url URL` 只查询能力与版本，以 JSON 返回，不创建绑定。许可证附于 `dist/LICENSE`。

package/bin/session-hook.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// This entry does not load the CLI or SQLite. The registered shell command also
+// protects missing Node/package files before JavaScript can run.
+const deadline = setTimeout(() => process.exit(0), 1500);
+try {
+  const { runHook } = await import('../dist/hook.js');
+  await runHook(process.argv.slice(process.argv[2] === 'session' ? 4 : 2));
+} catch {
+  // Hook diagnostics must never become host-visible stdout, stderr or exit codes.
+} finally {
+  clearTimeout(deadline);
+  process.exit(0);
+}

package/bin/teammy.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+if (process.argv[2] === 'session' && process.argv[3] === 'hook') {
+  await import('./session-hook.js').catch(() => process.exit(0));
+}
+// npm's public executable is a symlink. Persist the package entry, so service
+// definitions and the sibling Hook entry remain valid when launched via PATH.
+process.argv[1] = realpathSync(fileURLToPath(import.meta.url));
 // SQLite's known experimental notice is not an actionable CLI diagnostic.
 const warningHandlers = process.listeners('warning');
 process.removeAllListeners('warning');

package/dist/hook.js

@@ -0,0 +1,340 @@
+// apps/client/sessions/hook-entry.ts
+import { parseArgs } from "node:util";
+import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute as isAbsolute2, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { join as join3 } from "node:path";
+
+// apps/client/sessions/registration.ts
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// apps/client/runtime/log.ts
+import { createHash } from "node:crypto";
+function rootKey(root) {
+  return createHash("sha256").update(root).digest("hex").slice(0, 16);
+}
+
+// apps/client/sessions/registration.ts
+var registrationPath = (directory, root) => join(directory, "hook-registrations", rootKey(root) + ".json");
+function readRegistration(directory, root) {
+  const path = registrationPath(directory, root);
+  if (!existsSync(path)) return null;
+  const value = JSON.parse(readFileSync(path, "utf8"));
+  if (value.format !== 1 || value.root !== root || !Array.isArray(value.configs))
+    throw new Error("Invalid Hook registration.");
+  return value;
+}
+function registrations(directory, onError) {
+  const path = join(directory, "hook-registrations");
+  if (!existsSync(path)) return [];
+  return readdirSync(path).filter((name) => /^[a-f0-9]{16}\.json$/.test(name)).flatMap((name) => {
+    try {
+      const value = JSON.parse(readFileSync(join(path, name), "utf8"));
+      const registration = readRegistration(directory, value.root);
+      if (!registration) throw new Error("Missing Hook registration.");
+      return [registration];
+    } catch (error) {
+      onError(join(path, name), error);
+      return [];
+    }
+  });
+}
+
+// apps/client/sessions/hooks.ts
+import { createHash as createHash2, randomUUID } from "node:crypto";
+import { mkdir, open, opendir, rename, unlink } from "node:fs/promises";
+import { isAbsolute, join as join2 } from "node:path";
+import { z as z5 } from "zod";
+
+// packages/protocol/sessions.ts
+import { z as z4 } from "zod";
+
+// packages/protocol/files.ts
+import { z } from "zod";
+var MAX_BLOB_BYTES = 128 * 1024 * 1024;
+var MAX_FILE_BYTES = 10 * 1024 * 1024;
+var MAX_BATCH_FILES = 200;
+var HashSchema = z.string().regex(/^[a-f0-9]{64}$/);
+var RevisionSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var FilePathSchema = z.string().min(1).max(1024).refine((path) => {
+  if (path !== path.normalize("NFC") || /[\\\x00-\x1f\x7f:<>"|?*]/.test(path)) return false;
+  return path.split("/").every(
+    (part) => part.length > 0 && part.length <= 255 && part !== "." && part !== ".." && !/[. ]$/.test(part) && !/^\.teammy(?:-|$)/i.test(part) && !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)
+  );
+}, "Path must be a portable, normalized relative file path.");
+var BlobRefSchema = z.object({
+  sha256: HashSchema,
+  size: z.number().int().min(0).max(MAX_BLOB_BYTES)
+});
+var FileBlobRefSchema = BlobRefSchema.extend({
+  size: z.number().int().min(0).max(MAX_FILE_BYTES)
+});
+var FileChangeSchema = z.discriminatedUnion("kind", [
+  FileBlobRefSchema.extend({ kind: z.literal("upsert"), path: FilePathSchema }).strict(),
+  z.object({ kind: z.literal("delete"), path: FilePathSchema }).strict()
+]);
+var FileCommitSchema = z.object({
+  operationId: z.uuid(),
+  parentRevision: RevisionSchema,
+  changes: z.array(FileChangeSchema)
+}).strict().refine(
+  (batch) => new Set(batch.changes.map((change) => change.path)).size === batch.changes.length,
+  "Duplicate paths in a publication."
+);
+var CommitResultSchema = z.object({ operationId: z.uuid(), revision: RevisionSchema });
+var FileEntrySchema = FileBlobRefSchema.extend({
+  path: FilePathSchema,
+  revision: RevisionSchema
+});
+var ManifestSchema = z.object({
+  revision: RevisionSchema,
+  complete: z.boolean().default(false),
+  files: z.array(FileEntrySchema),
+  nextCursor: z.string().nullable()
+});
+var FileRevisionSchema = z.object({
+  revision: RevisionSchema,
+  operationId: z.uuid(),
+  createdAt: z.string(),
+  changes: z.array(FileChangeSchema)
+});
+var ChangesSchema = z.object({
+  headRevision: RevisionSchema,
+  revisions: z.array(FileRevisionSchema)
+});
+var BlobCheckSchema = z.object({ hashes: z.array(HashSchema).max(MAX_BATCH_FILES) }).strict();
+var MissingBlobsSchema = z.object({ missing: z.array(HashSchema) });
+var FileTreeEntrySchema = z.discriminatedUnion("kind", [
+  FileEntrySchema.extend({ kind: z.literal("file") }),
+  z.object({
+    kind: z.literal("directory"),
+    path: FilePathSchema,
+    fileCount: z.number().int().positive()
+  })
+]);
+var FileTreeSchema = z.object({
+  revision: RevisionSchema,
+  path: z.union([z.literal(""), FilePathSchema]),
+  entries: z.array(FileTreeEntrySchema),
+  nextCursor: z.string().nullable()
+});
+var FileSelectionSchema = z.object({ revision: RevisionSchema, file: FileEntrySchema });
+
+// packages/protocol/identity.ts
+import { z as z2 } from "zod";
+var NameSchema = z2.string().regex(/^[a-z][a-z0-9_-]{0,63}$/);
+var DeviceIdSchema = z2.uuid();
+var BindRequestSchema = z2.object({ deviceId: DeviceIdSchema, projectId: NameSchema.optional() }).strict();
+var BindingSchema = z2.object({
+  workspaceId: NameSchema,
+  memberId: NameSchema,
+  deviceId: DeviceIdSchema
+});
+var MembersSchema = z2.object({ members: z2.array(NameSchema) });
+
+// packages/protocol/session-analysis.ts
+import { z as z3 } from "zod";
+var SessionAnalysisKindSchema = z3.enum(["overview", "handoff"]);
+var SessionOverviewOutputSchema = z3.object({ title: z3.string().trim().min(1), summary: z3.string().trim().min(1) }).strict();
+var SessionHandoffOutputSchema = z3.object({ markdown: z3.string().trim().min(1) }).strict();
+var SessionOverviewSchema = SessionOverviewOutputSchema.extend({
+  sourceRevision: RevisionSchema,
+  sourceHash: HashSchema,
+  generatedAt: z3.string(),
+  stale: z3.boolean()
+});
+var SessionAnalysisStateSchema = z3.object({
+  kind: SessionAnalysisKindSchema,
+  status: z3.enum(["absent", "queued", "running", "succeeded", "failed"]),
+  available: z3.boolean(),
+  currentRevision: RevisionSchema,
+  sourceRevision: RevisionSchema.nullable(),
+  stale: z3.boolean(),
+  result: z3.union([SessionOverviewOutputSchema, SessionHandoffOutputSchema]).nullable(),
+  generatedAt: z3.string().nullable(),
+  error: z3.string().nullable()
+});
+
+// packages/protocol/sessions.ts
+var AgentSchema = z4.enum(["claude-code", "codex", "cursor", "pi", "dsh"]);
+var SessionSnapshotSchema = z4.object({
+  formatVersion: z4.literal(1),
+  adapterVersion: z4.literal(1),
+  agent: AgentSchema,
+  nativeId: z4.string().min(1).max(512),
+  cwd: z4.string().min(1).max(4096),
+  messages: z4.array(
+    z4.object({
+      id: z4.string().min(1).max(1024),
+      role: z4.enum(["user", "assistant"]),
+      text: z4.string().min(1),
+      source: z4.string().min(1).max(1024)
+    }).strict()
+  )
+}).strict().refine(
+  (s) => new Set(s.messages.map((m) => m.id)).size === s.messages.length,
+  "Duplicate message IDs."
+);
+var SessionCommitSchema = z4.object({
+  operationId: z4.uuid(),
+  sessionKey: HashSchema,
+  parentRevision: RevisionSchema,
+  blob: BlobRefSchema
+}).strict();
+var SessionInfoSchema = z4.object({
+  owner: NameSchema,
+  sessionKey: HashSchema,
+  agent: AgentSchema,
+  nativeId: z4.string(),
+  cwd: z4.string(),
+  title: z4.string(),
+  revision: RevisionSchema,
+  updatedAt: z4.string(),
+  messageCount: z4.number().int().nonnegative(),
+  blob: BlobRefSchema,
+  overview: SessionOverviewSchema.optional()
+});
+var SessionListSchema = z4.object({
+  sessions: z4.array(SessionInfoSchema),
+  nextCursor: RevisionSchema.nullable()
+});
+var SessionStatsSchema = z4.object({
+  totalSessions: z4.number().int().nonnegative(),
+  totalMessages: z4.number().int().nonnegative(),
+  memberCount: z4.number().int().nonnegative(),
+  updatedAt: z4.string().nullable()
+});
+var SessionScopeSchema = z4.object({
+  owner: NameSchema.optional(),
+  sessionKey: HashSchema.optional()
+}).strict().refine((v) => !v.sessionKey || !!v.owner, "A session scope requires an owner.");
+var SessionSearchSchema = z4.object({
+  matches: z4.array(
+    z4.object({
+      owner: NameSchema,
+      sessionKey: HashSchema,
+      revision: RevisionSchema,
+      messageId: z4.string(),
+      role: z4.enum(["user", "assistant"]),
+      snippet: z4.string(),
+      title: z4.string()
+    })
+  ),
+  nextCursor: RevisionSchema.nullable()
+});
+
+// apps/client/sessions/normalize.ts
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+// apps/client/sessions/hooks.ts
+var HintSchema = z5.object({
+  agent: AgentSchema,
+  path: z5.string().min(1).max(4096).refine(isAbsolute).optional(),
+  nativeId: z5.string().min(1).max(512).optional(),
+  projectDir: z5.string().min(1).max(4096).refine(isAbsolute)
+});
+function inbox(directory, root) {
+  return join2(directory, "session-hints", createHash2("sha256").update(root).digest("hex"));
+}
+async function recordHint(directory, root, input) {
+  const hint = HintSchema.parse(input);
+  const targetDir = inbox(directory, root);
+  await mkdir(targetDir, { recursive: true, mode: 448 });
+  const target = join2(
+    targetDir,
+    `${createHash2("sha256").update(JSON.stringify(hint)).digest("hex")}.json`
+  );
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, "wx", 384);
+  try {
+    await handle.writeFile(JSON.stringify(hint));
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, target);
+}
+async function hookPayload() {
+  let size = 0;
+  const parts = [];
+  const timeout = setTimeout(() => process.stdin.destroy(new Error("Hook input timeout.")), 500);
+  try {
+    for await (const part of process.stdin) {
+      const bytes = Buffer.from(part);
+      size += bytes.length;
+      if (size > 4 * 1024 * 1024) throw new Error("Hook payload too large.");
+      parts.push(bytes);
+    }
+    return object(JSON.parse(Buffer.concat(parts).toString("utf8")));
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// apps/client/sessions/hook-entry.ts
+async function runHook(args) {
+  try {
+    const { values } = parseArgs({
+      args,
+      options: {
+        agent: { type: "string" },
+        root: { type: "string" },
+        "state-dir": { type: "string" },
+        "project-dir": { type: "string" },
+        file: { type: "string" },
+        "integration-file": { type: "string" }
+      }
+    });
+    const directory = await realpath(
+      resolve(values["state-dir"] ?? join3(homedir(), ".teammy", "client"))
+    );
+    const payload = values.file ? {} : await hookPayload();
+    let selectedRoot = values.root;
+    if (values["integration-file"]) {
+      if (values.agent !== "pi" || typeof payload.cwd !== "string") return;
+      const cwd = await realpath(payload.cwd);
+      const candidates = registrations(directory, () => {
+      }).filter(
+        (item) => item.enabled && item.configs.some(
+          (config) => config.kind === "pi-extension" && config.path === values["integration-file"]
+        )
+      );
+      const matches = [];
+      for (const item of candidates) {
+        try {
+          const project = await realpath(item.projectDir);
+          const rel = relative(project, cwd);
+          if (!isAbsolute2(rel) && rel !== ".." && !rel.startsWith(".." + sep)) matches.push(item);
+        } catch {
+        }
+      }
+      matches.sort((a, b) => b.projectDir.length - a.projectDir.length);
+      selectedRoot = matches[0]?.root;
+      if (!selectedRoot) return;
+    }
+    const root = await realpath(resolve(selectedRoot ?? "workspaces"));
+    const registration = readRegistration(directory, root);
+    if (!registration?.enabled) return;
+    const projectDir = await realpath(registration.projectDir);
+    if (projectDir !== await realpath(values["project-dir"] ?? dirname(root))) return;
+    if (typeof payload.cwd === "string") {
+      const rel = relative(projectDir, await realpath(payload.cwd));
+      if (isAbsolute2(rel) || rel === ".." || rel.startsWith(".." + sep)) return;
+    }
+    const file = values.file ?? payload.transcript_path ?? payload.session_file ?? payload.sessionFile;
+    const nativeId = payload.session_id ?? payload.conversation_id;
+    if (typeof file === "string" && file || typeof nativeId === "string")
+      await recordHint(directory, root, {
+        agent: values.agent,
+        ...typeof file === "string" && file ? { path: resolve(projectDir, file) } : {},
+        ...typeof nativeId === "string" ? { nativeId } : {},
+        projectDir
+      });
+  } catch {
+  }
+}
+export {
+  runHook
+};