@geoly-ai/social-hub-cli 0.0.12 → 0.0.14

package/dist/index.js

@@ -4,6 +4,8 @@ import { getSocialHubHealth } from "@geoly-ai/social-hub-sdk";
 import { getBaseUrl, requireClient } from "./client.js";
 import { registerAccountsExtensions, registerAuthAndConfig, registerPermissionsExplain, registerRedditExtensions, } from "./register-extensions.js";
 import { registerAdminCommands } from "./register-admin.js";
+import { assertApplyOrDryRun } from "./dry-run.js";
+import { withPermissionGate } from "./permission-runner.js";
 import { registerBatchAndExport } from "./register-batch.js";
 import { registerAgentContext, registerOpsRuntime, } from "./register-ops.js";
 import { registerDoctorAndVersion } from "./register-shared.js";
@@ -44,6 +46,12 @@ events
     .command("append")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("--type <type>", "事件类型，如 comment")
+    .option("--external-ref <ref>", "幂等键（也可放在 payload.externalRef / event_id）")
+    .option("--account <uuid>", "socialAccountId")
+    .option("--subreddit <name>", "subreddit")
+    .option("--result <result>", "succeeded | failed | skipped")
+    .option("--target-url <url>", "目标 URL / permalink")
+    .option("--actor <actor>", "user | agent | cron")
     .option("--payload <json>", "JSON 对象", "{}")
     .action(async (opts) => {
     let payload = {};
@@ -56,6 +64,30 @@ events
     }
     const res = await requireClient().appendEvent(opts.team, {
         type: opts.type,
+        externalRef: opts.externalRef ??
+            (typeof payload.externalRef === "string" ? payload.externalRef : undefined) ??
+            (typeof payload.event_id === "string" ? payload.event_id : undefined),
+        socialAccountId: opts.account ??
+            (typeof payload.socialAccountId === "string"
+                ? payload.socialAccountId
+                : undefined),
+        subreddit: opts.subreddit ??
+            (typeof payload.subreddit === "string" ? payload.subreddit : undefined),
+        result: opts.result ??
+            (payload.result === "succeeded" ||
+                payload.result === "failed" ||
+                payload.result === "skipped"
+                ? payload.result
+                : undefined),
+        targetUrl: opts.targetUrl ??
+            (typeof payload.targetUrl === "string" ? payload.targetUrl : undefined) ??
+            (typeof payload.permalink === "string" ? payload.permalink : undefined),
+        actor: opts.actor ??
+            (payload.actor === "user" ||
+                payload.actor === "agent" ||
+                payload.actor === "cron"
+                ? payload.actor
+                : undefined),
         payload,
     });
     console.log(JSON.stringify(res, null, 2));
@@ -85,6 +117,102 @@ events
     const res = await requireClient().appendEventsBatch(opts.team, body);
     console.log(JSON.stringify(res, null, 2));
 });
+events
+    .command("import-openclaw-history")
+    .description("POST /interaction-history/import — OpenClaw v1 JSON 幂等入库")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-f, --file <path>", "interaction-history.json 路径")
+    .option("--dry-run", "只校验 schema/slot/幂等，不写库")
+    .option("--no-auto-mark", "关闭 auto_metrics 阈值补 mark")
+    .action(async (opts) => {
+    const fs = await import("node:fs/promises");
+    const raw = await fs.readFile(opts.file, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        console.error("Invalid JSON file");
+        process.exit(1);
+    }
+    const res = await requireClient().importInteractionHistory(opts.team, {
+        ...parsed,
+        sourceFile: opts.file,
+        dryRun: Boolean(opts.dryRun),
+        autoMarkThreshold: !opts.noAutoMark,
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+const styleMarks = program.command("style-marks").description("风格反馈标记");
+styleMarks
+    .command("list")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--account <uuid>", "socialAccountId")
+    .option("--extract-status <st>", "pending | extracted | rejected | skipped | failed")
+    .option("--approved <bool>", "true | false")
+    .option("-n, --limit <n>", "limit", "50")
+    .option("--offset <n>", "offset", "0")
+    .action(async (opts) => {
+    const res = await requireClient().listStyleMarks(opts.team, {
+        socialAccountId: opts.account,
+        extractStatus: opts.extractStatus,
+        approved: opts.approved === undefined ? undefined : opts.approved === "true",
+        limit: Number(opts.limit),
+        offset: Number(opts.offset),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+styleMarks
+    .command("approve")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--id <styleMarkId>", "Style mark UUID")
+    .option("--note <text>", "Reviewer note")
+    .action(async (opts) => {
+    const res = await requireClient().patchStyleMark(opts.team, opts.id, {
+        approved: true,
+        extractStatus: "pending",
+        note: opts.note,
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+styleMarks
+    .command("reject")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--id <styleMarkId>", "Style mark UUID")
+    .option("--note <text>", "Reviewer note")
+    .action(async (opts) => {
+    const res = await requireClient().patchStyleMark(opts.team, opts.id, {
+        approved: false,
+        extractStatus: "rejected",
+        note: opts.note,
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+styleMarks
+    .command("extract")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--id <styleMarkId>", "Style mark UUID")
+    .option("--dry-run", "只预览提取结果")
+    .action(async (opts) => {
+    const res = await requireClient().extractStyleMark(opts.team, opts.id, {
+        dryRun: Boolean(opts.dryRun),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+const curator = program.command("curator").description("风格沉淀 curator");
+curator
+    .command("run")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--account <ref>", "账号 UUID 或 handle/slot")
+    .option("--dry-run", "只预览")
+    .option("-n, --limit <n>", "最多处理 pending marks", "50")
+    .action(async (opts) => {
+    const res = await requireClient().runStyleCurator(opts.team, opts.account, {
+        dryRun: Boolean(opts.dryRun),
+        limit: Number(opts.limit),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
 // --- dashboard ---
 const dashboard = program.command("dashboard").description("运营总览");
 dashboard
@@ -604,6 +732,28 @@ compliance
     const res = await requireClient().upsertAccountRiskProfile(opts.team, opts.account, body);
     console.log(JSON.stringify(res, null, 2));
 });
+compliance
+    .command("rule-caches-list")
+    .description("GET /subreddit-rule-caches")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--include-expired", "include expired caches")
+    .action(async (opts) => {
+    const res = await requireClient().listSubredditRuleCaches(opts.team, {
+        includeExpired: Boolean(opts.includeExpired),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+compliance
+    .command("rule-caches-upsert")
+    .description("PUT /subreddit-rule-caches/:subreddit")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--sub <name>", "subreddit name")
+    .requiredOption("-j, --json <json>", "{ rulesMarkdown, sourceUrl?, expiresInDays? }")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().upsertSubredditRuleCache(opts.team, opts.sub, body);
+    console.log(JSON.stringify(res, null, 2));
+});
 // --- openclaw ---
 program
     .command("openclaw-ingest")
@@ -716,8 +866,14 @@ agentTeams
     .command("list")
     .description("GET /v1/agent-teams")
     .action(async () => {
-    const res = await requireClient().listAgentTeams();
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "agent-teams list",
+        resource: "agentTeam",
+        action: "list",
+    }, async () => {
+        const res = await requireClient().listAgentTeams();
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 agentTeams
     .command("workspace-docs")
@@ -726,30 +882,71 @@ agentTeams
     .option("--kind <kind>", "file|daily_report|weekly_report|ops_record")
     .option("-n, --limit <n>", "limit", "50")
     .action(async (opts) => {
-    const res = await requireClient().listWorkspaceDocuments(opts.team, {
-        kind: opts.kind,
-        limit: Number(opts.limit),
+    await withPermissionGate({
+        command: "agent-teams workspace-docs",
+        resource: "agentTeam",
+        action: "read",
+        teamId: opts.team,
+    }, async () => {
+        const res = await requireClient().listWorkspaceDocuments(opts.team, {
+            kind: opts.kind,
+            limit: Number(opts.limit),
+        });
+        console.log(JSON.stringify(res, null, 2));
     });
-    console.log(JSON.stringify(res, null, 2));
 });
 agentTeams
     .command("create")
     .description("POST /v1/agent-teams — 新建团队（admin only）")
     .requiredOption("--slug <slug>", "团队 slug（小写字母、数字、横线）")
     .requiredOption("--name <name>", "团队名称")
-    .action(async (opts) => {
-    const res = await requireClient().createTeam({ slug: opts.slug, name: opts.name });
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "agent-teams create",
+        resource: "agentTeam",
+        action: "create",
+    }, async () => {
+        if (!assertApplyOrDryRun(opts, {
+            command: "agent-teams create",
+            danger: "admin",
+            summary: { slug: opts.slug, name: opts.name },
+        })) {
+            return;
+        }
+        const res = await requireClient().createTeam({
+            slug: opts.slug,
+            name: opts.name,
+        });
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 agentTeams
     .command("update")
     .description("PATCH /v1/agent-teams/:teamId — 更新团队（admin only）")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("-j, --json <json>", "{ slug?, name? }")
-    .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().updateTeam(opts.team, body);
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "agent-teams update",
+        resource: "agentTeam",
+        action: "update",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        if (!assertApplyOrDryRun(opts, {
+            command: "agent-teams update",
+            danger: "admin",
+            summary: { teamId: opts.team, ...body },
+        })) {
+            return;
+        }
+        const res = await requireClient().updateTeam(opts.team, body);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 agentTeams
     .command("add-member")
@@ -757,12 +954,32 @@ agentTeams
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("--user <userId>", "User UUID")
     .requiredOption("--role <role>", "admin|manager|supervisor|senior|internal|client")
-    .action(async (opts) => {
-    const res = await requireClient().addTeamMember(opts.team, {
-        userId: opts.user,
-        role: opts.role,
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "agent-teams add-member",
+        resource: "agentTeam",
+        action: "update",
+        teamId: opts.team,
+    }, async () => {
+        if (!assertApplyOrDryRun(opts, {
+            command: "agent-teams add-member",
+            danger: "admin",
+            summary: {
+                teamId: opts.team,
+                userId: opts.user,
+                role: opts.role,
+            },
+        })) {
+            return;
+        }
+        const res = await requireClient().addTeamMember(opts.team, {
+            userId: opts.user,
+            role: opts.role,
+        });
+        console.log(JSON.stringify(res, null, 2));
     });
-    console.log(JSON.stringify(res, null, 2));
 });
 // --- intelligence (subreddit-intelligence) ---
 const intel = program.command("intelligence").description("板块情报与 KOL 挖掘");
@@ -903,6 +1120,192 @@ intel
     const res = await requireClient().dispatchTaskFromHotPost(opts.team, body);
     console.log(JSON.stringify(res, null, 2));
 });
+intel
+    .command("tier-rules-list")
+    .description("GET .../subreddit-intelligence/tier-rules")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--tier <tier>", "tier filter")
+    .option("--enabled <bool>", "true|false")
+    .option("-n, --limit <n>", "limit", "50")
+    .option("--offset <n>", "offset", "0")
+    .action(async (opts) => {
+    const res = await requireClient().listTierRules(opts.team, {
+        tier: opts.tier,
+        enabled: opts.enabled === undefined
+            ? undefined
+            : opts.enabled === "true" || opts.enabled === "1",
+        limit: Number(opts.limit),
+        offset: Number(opts.offset),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("tier-rules-create")
+    .description("POST .../subreddit-intelligence/tier-rules")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "tier rule body")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().createTierRule(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("tier-rules-update")
+    .description("PATCH .../subreddit-intelligence/tier-rules/:id")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--id <uuid>", "Tier rule UUID")
+    .requiredOption("-j, --json <json>", "update body")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().updateTierRule(opts.team, opts.id, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("tier-rules-delete")
+    .description("DELETE .../subreddit-intelligence/tier-rules/:id")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--id <uuid>", "Tier rule UUID")
+    .action(async (opts) => {
+    const res = await requireClient().deleteTierRule(opts.team, opts.id);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("runs-list")
+    .description("GET .../subreddit-intelligence/runs")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--dimension <d>", "industry|keywords|tier")
+    .option("--status <s>", "queued|running|succeeded|failed")
+    .option("-n, --limit <n>", "limit", "50")
+    .option("--offset <n>", "offset", "0")
+    .action(async (opts) => {
+    const res = await requireClient().listIntelRuns(opts.team, {
+        dimension: opts.dimension,
+        status: opts.status,
+        limit: Number(opts.limit),
+        offset: Number(opts.offset),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("kol-profiles-list")
+    .description("GET .../subreddit-intelligence/kol-profiles")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--platform <p>", "reddit")
+    .option("-n, --limit <n>", "limit", "50")
+    .option("--offset <n>", "offset", "0")
+    .action(async (opts) => {
+    const res = await requireClient().listKolProfiles(opts.team, {
+        platform: opts.platform,
+        limit: Number(opts.limit),
+        offset: Number(opts.offset),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("kol-profiles-get")
+    .description("GET .../subreddit-intelligence/kol-profiles/:id")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--id <uuid>", "KOL profile UUID")
+    .action(async (opts) => {
+    const res = await requireClient().getKolProfile(opts.team, opts.id);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("fetch-by-industry")
+    .description("POST .../subreddit-intelligence/hot-posts/fetch-by-industry")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "fetch body")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().fetchHotPostsByIndustry(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("fetch-by-tier")
+    .description("POST .../subreddit-intelligence/hot-posts/fetch-by-tier")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "fetch body")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().fetchHotPostsByTier(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("fetch-by-keywords")
+    .description("POST .../subreddit-intelligence/insights/fetch-by-keywords")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "fetch body")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().fetchInsightsByKeywords(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("brand-mention-radar")
+    .description("POST .../subreddit-intelligence/insights/brand-mention-radar")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "{ keywords, minScore?, minComments? }")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().getBrandMentionRadar(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("opportunity-map")
+    .description("POST .../subreddit-intelligence/insights/opportunity-map")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "{ keywords, minScore?, minComments? }")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().getOpportunityMap(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("sov")
+    .description("POST .../subreddit-intelligence/insights/sov")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "{ brandKeywords, competitorKeywords, minScore?, minComments? }")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().getInsightsSov(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("sentiment-intent")
+    .description("GET .../subreddit-intelligence/insights/sentiment-intent")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .action(async (opts) => {
+    const res = await requireClient().getSentimentIntent(opts.team);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("campaign-lift")
+    .description("POST .../subreddit-intelligence/insights/campaign-lift")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "{ keywords, campaignStartAt, campaignEndAt, windowDays?, minScore?, minComments? }")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().getCampaignLift(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("snapshot-latest")
+    .description("GET .../subreddit-intelligence/insights/snapshot-latest")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .action(async (opts) => {
+    const res = await requireClient().getLatestInsightSnapshot(opts.team);
+    console.log(JSON.stringify(res, null, 2));
+});
+intel
+    .command("snapshot-save")
+    .description("POST .../subreddit-intelligence/insights/snapshot")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("-j, --json <json>", "{ payload: { ... } }")
+    .action(async (opts) => {
+    const body = JSON.parse(opts.json);
+    const res = await requireClient().saveInsightSnapshot(opts.team, body);
+    console.log(JSON.stringify(res, null, 2));
+});
 // --- users ---
 const usersCmd = program.command("users").description("团队成员管理");
 usersCmd
@@ -910,8 +1313,28 @@ usersCmd
     .description("GET /users")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .action(async (opts) => {
-    const res = await requireClient().listUsers(opts.team);
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "users list",
+        resource: "systemMember",
+        action: "list",
+        teamId: opts.team,
+    }, async () => {
+        const res = await requireClient().listUsers(opts.team);
+        console.log(JSON.stringify(res, null, 2));
+    });
+});
+usersCmd
+    .command("system-list")
+    .description("GET /v1/system/users")
+    .action(async () => {
+    await withPermissionGate({
+        command: "users system-list",
+        resource: "systemMember",
+        action: "list",
+    }, async () => {
+        const res = await requireClient().listSystemUsers();
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 usersCmd
     .command("create")
@@ -919,9 +1342,40 @@ usersCmd
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("-j, --json <json>", "{ email, password, role? }")
     .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().createUser(opts.team, body);
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "users create",
+        resource: "systemMember",
+        action: "create",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        const res = await requireClient().createUser(opts.team, body);
+        console.log(JSON.stringify(res, null, 2));
+    });
+});
+usersCmd
+    .command("system-create")
+    .description("POST /v1/system/users")
+    .requiredOption("-j, --json <json>", "{ email, name, password?, role? }")
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "users system-create",
+        resource: "systemMember",
+        action: "create",
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        if (!assertApplyOrDryRun(opts, {
+            command: "users system-create",
+            danger: "write",
+            summary: { email: body.email, name: body.name },
+        })) {
+            return;
+        }
+        const res = await requireClient().createSystemUser(body);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 // --- brand-members ---
 const brandMembersCmd = program.command("brand-members").description("品牌成员");
@@ -930,17 +1384,63 @@ brandMembersCmd
     .description("GET /system/brand-members (preferred)")
     .option("--user <uuid>", "userId 过滤")
     .action(async (opts) => {
-    const res = await requireClient().listSystemBrandMembers({ userId: opts.user });
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "brand-members system-list",
+        resource: "systemBrand",
+        action: "list",
+    }, async () => {
+        const res = await requireClient().listSystemBrandMembers({
+            userId: opts.user,
+        });
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 brandMembersCmd
     .command("system-create")
     .description("POST /system/brand-members (preferred)")
     .requiredOption("-j, --json <json>", "{ brandId, userId, role? }")
-    .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().createSystemBrandMember(body);
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "brand-members system-create",
+        resource: "brandMember",
+        action: "create",
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        if (!assertApplyOrDryRun(opts, {
+            command: "brand-members system-create",
+            danger: "write",
+            summary: body,
+        })) {
+            return;
+        }
+        const res = await requireClient().createSystemBrandMember(body);
+        console.log(JSON.stringify(res, null, 2));
+    });
+});
+brandMembersCmd
+    .command("system-remove")
+    .description("DELETE /system/brand-members/:memberId")
+    .requiredOption("--id <memberId>", "BrandMember UUID")
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "brand-members system-remove",
+        resource: "brandMember",
+        action: "delete",
+    }, async () => {
+        if (!assertApplyOrDryRun(opts, {
+            command: "brand-members system-remove",
+            danger: "delete",
+            summary: { memberId: opts.id },
+        })) {
+            return;
+        }
+        await requireClient().deleteSystemBrandMember(opts.id);
+        console.log("OK");
+    });
 });
 brandMembersCmd
     .command("list")
@@ -948,18 +1448,43 @@ brandMembersCmd
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .option("--user <uuid>", "userId 过滤")
     .action(async (opts) => {
-    const res = await requireClient().listBrandMembers(opts.team, { userId: opts.user });
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "brand-members list",
+        resource: "brandMember",
+        action: "list",
+        teamId: opts.team,
+    }, async () => {
+        const res = await requireClient().listBrandMembers(opts.team, {
+            userId: opts.user,
+        });
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 brandMembersCmd
     .command("create")
     .description("POST /brand-members")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("-j, --json <json>", "{ brandId, userId, role? }")
-    .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().createBrandMember(opts.team, body);
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "brand-members create",
+        resource: "brandMember",
+        action: "create",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        if (!assertApplyOrDryRun(opts, {
+            command: "brand-members create",
+            danger: "write",
+            summary: { teamId: opts.team, ...body },
+        })) {
+            return;
+        }
+        const res = await requireClient().createBrandMember(opts.team, body);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 // --- notification-channels ---
 const notifChannels = program
@@ -1023,56 +1548,147 @@ apiKeys
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .option("-n, --limit <n>", "limit", "50")
     .action(async (opts) => {
-    const res = await requireClient().listApiKeys(opts.team, { limit: Number(opts.limit) });
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "api-keys list",
+        resource: "apiKey",
+        action: "list",
+        teamId: opts.team,
+    }, async () => {
+        const res = await requireClient().listApiKeys(opts.team, {
+            limit: Number(opts.limit),
+        });
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 apiKeys
     .command("create")
     .description("POST /api-keys")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("-j, --json <json>", "{ name, role, visibleCampaignIds? }")
-    .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().createApiKey(opts.team, body);
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "api-keys create",
+        resource: "apiKey",
+        action: "create",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        if (!assertApplyOrDryRun(opts, {
+            command: "api-keys create",
+            danger: "secret",
+            summary: { teamId: opts.team, ...body },
+        })) {
+            return;
+        }
+        const res = await requireClient().createApiKey(opts.team, body);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 apiKeys
     .command("delete")
     .description("DELETE /api-keys/:id")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("--key <uuid>", "API Key UUID")
-    .action(async (opts) => {
-    await requireClient().deleteApiKey(opts.team, opts.key);
-    console.log("OK");
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "api-keys delete",
+        resource: "apiKey",
+        action: "delete",
+        teamId: opts.team,
+    }, async () => {
+        if (!assertApplyOrDryRun(opts, {
+            command: "api-keys delete",
+            danger: "delete",
+            summary: { teamId: opts.team, keyId: opts.key },
+        })) {
+            return;
+        }
+        await requireClient().deleteApiKey(opts.team, opts.key);
+        console.log("OK");
+    });
 });
 apiKeys
     .command("rotate")
     .description("POST /api-keys/:id/rotate")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("--key <uuid>", "API Key UUID")
-    .action(async (opts) => {
-    const res = await requireClient().rotateApiKey(opts.team, opts.key);
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "api-keys rotate",
+        resource: "apiKey",
+        action: "update",
+        teamId: opts.team,
+    }, async () => {
+        if (!assertApplyOrDryRun(opts, {
+            command: "api-keys rotate",
+            danger: "secret",
+            summary: { teamId: opts.team, keyId: opts.key },
+        })) {
+            return;
+        }
+        const res = await requireClient().rotateApiKey(opts.team, opts.key);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 apiKeys
     .command("batch-revoke")
     .description("POST /api-keys/batch/revoke")
     .requiredOption("-t, --team <teamId>", "Team UUID")
-    .requiredOption("-j, --json <json>", '{ "ids": ["uuid1","uuid2"] }')
-    .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().batchRevokeApiKeys(opts.team, body.ids);
-    console.log(JSON.stringify(res, null, 2));
+    .requiredOption("-j, --json <json>", '{ "apiKeyIds": ["uuid1","uuid2"] }')
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "api-keys batch-revoke",
+        resource: "apiKey",
+        action: "delete",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        const apiKeyIds = body.apiKeyIds ?? body.ids ?? [];
+        if (!assertApplyOrDryRun(opts, {
+            command: "api-keys batch-revoke",
+            danger: "delete",
+            summary: { teamId: opts.team, apiKeyIds },
+        })) {
+            return;
+        }
+        const res = await requireClient().batchRevokeApiKeys(opts.team, apiKeyIds);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 apiKeys
     .command("batch-rotate")
     .description("POST /api-keys/batch/rotate")
     .requiredOption("-t, --team <teamId>", "Team UUID")
-    .requiredOption("-j, --json <json>", '{ "ids": ["uuid1","uuid2"] }')
-    .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().batchRotateApiKeys(opts.team, body.ids);
-    console.log(JSON.stringify(res, null, 2));
+    .requiredOption("-j, --json <json>", '{ "apiKeyIds": ["uuid1","uuid2"] }')
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "api-keys batch-rotate",
+        resource: "apiKey",
+        action: "update",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        const apiKeyIds = body.apiKeyIds ?? body.ids ?? [];
+        if (!assertApplyOrDryRun(opts, {
+            command: "api-keys batch-rotate",
+            danger: "secret",
+            summary: { teamId: opts.team, apiKeyIds },
+        })) {
+            return;
+        }
+        const res = await requireClient().batchRotateApiKeys(opts.team, apiKeyIds);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 // ═══════════════════════════════════════════════════════════════════════════
 // Group C: scattered endpoint additions
@@ -1127,9 +1743,16 @@ program
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("-j, --json <json>", "权限矩阵更新 body")
     .action(async (opts) => {
-    const body = JSON.parse(opts.json);
-    const res = await requireClient().updatePermissionsMatrix(opts.team, body);
-    console.log(JSON.stringify(res, null, 2));
+    await withPermissionGate({
+        command: "permissions-update",
+        resource: "permissionMatrix",
+        action: "update",
+        teamId: opts.team,
+    }, async () => {
+        const body = JSON.parse(opts.json);
+        const res = await requireClient().updatePermissionsMatrix(opts.team, body);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 graph
     .command("drilldown")
@@ -1144,6 +1767,114 @@ graph
     });
     console.log(JSON.stringify(res, null, 2));
 });
+graph
+    .command("v2-ego")
+    .description("GET /graph/v2/ego")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--node-id <uuid>", "graph nodeId")
+    .option("--node-ref <id>", "nodeRefId (e.g. account UUID)")
+    .option("--node-type <type>", "account|team|campaign")
+    .option("--relation-type <type>", "relationType filter")
+    .option("--edge-kind <kind>", "edgeKind filter")
+    .option("-n, --limit <n>", "limit", "100")
+    .action(async (opts) => {
+    const res = await requireClient().getGraphV2Ego(opts.team, {
+        nodeId: opts.nodeId,
+        nodeRefId: opts.nodeRef,
+        nodeType: opts.nodeType,
+        relationType: opts.relationType,
+        edgeKind: opts.edgeKind,
+        limit: Number(opts.limit),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+graph
+    .command("v2-timeline")
+    .description("GET /graph/v2/timeline")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--node-id <uuid>", "graph nodeId")
+    .option("--node-ref <id>", "nodeRefId")
+    .option("--node-type <type>", "account|team|campaign")
+    .option("--from <iso>", "from ISO time")
+    .option("--to <iso>", "to ISO time")
+    .option("-n, --limit <n>", "limit", "100")
+    .action(async (opts) => {
+    const res = await requireClient().getGraphV2Timeline(opts.team, {
+        nodeId: opts.nodeId,
+        nodeRefId: opts.nodeRef,
+        nodeType: opts.nodeType,
+        from: opts.from,
+        to: opts.to,
+        limit: Number(opts.limit),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+graph
+    .command("v2-explain")
+    .description("GET /graph/v2/explain/:edgeId")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .requiredOption("--edge-id <id>", "edge UUID")
+    .action(async (opts) => {
+    const res = await requireClient().getGraphV2Explain(opts.team, opts.edgeId);
+    console.log(JSON.stringify(res, null, 2));
+});
+graph
+    .command("v2-path")
+    .description("GET /graph/v2/path")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--source-id <uuid>", "source nodeId")
+    .option("--source-ref <id>", "source nodeRefId")
+    .option("--source-type <type>", "source nodeType")
+    .option("--target-id <uuid>", "target nodeId")
+    .option("--target-ref <id>", "target nodeRefId")
+    .option("--target-type <type>", "target nodeType")
+    .option("--max-depth <n>", "maxDepth", "4")
+    .option("-n, --limit <n>", "limit", "50")
+    .action(async (opts) => {
+    const res = await requireClient().getGraphV2Path(opts.team, {
+        sourceNodeId: opts.sourceId,
+        sourceNodeRefId: opts.sourceRef,
+        sourceNodeType: opts.sourceType,
+        targetNodeId: opts.targetId,
+        targetNodeRefId: opts.targetRef,
+        targetNodeType: opts.targetType,
+        maxDepth: Number(opts.maxDepth),
+        limit: Number(opts.limit),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+graph
+    .command("v2-clusters")
+    .description("GET /graph/v2/clusters")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--scope-ref <id>", "scopeNodeRefId")
+    .option("--scope-type <type>", "scopeNodeType", "account")
+    .option("--min-risk <n>", "minRiskScore", "60")
+    .option("-n, --limit <n>", "limit", "100")
+    .action(async (opts) => {
+    const res = await requireClient().getGraphV2Clusters(opts.team, {
+        scopeNodeRefId: opts.scopeRef,
+        scopeNodeType: opts.scopeType,
+        minRiskScore: Number(opts.minRisk),
+        limit: Number(opts.limit),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
+graph
+    .command("v2-impact")
+    .description("GET /graph/v2/impact")
+    .requiredOption("-t, --team <teamId>", "Team UUID")
+    .option("--campaign-ref <id>", "campaignNodeRefId")
+    .option("--min-reuse <n>", "minReuseCount", "2")
+    .option("-n, --limit <n>", "limit", "100")
+    .action(async (opts) => {
+    const res = await requireClient().getGraphV2Impact(opts.team, {
+        campaignNodeRefId: opts.campaignRef,
+        minReuseCount: Number(opts.minReuse),
+        limit: Number(opts.limit),
+    });
+    console.log(JSON.stringify(res, null, 2));
+});
 // ═══════════════════════════════════════════════════════════════════════════
 // Group D: add filter params to existing list commands
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1380,9 +2111,25 @@ brandMembersCmd
     .description("DELETE /brand-members/:memberId")
     .requiredOption("-t, --team <teamId>", "Team UUID")
     .requiredOption("-m, --member <memberId>", "BrandMember UUID")
-    .action(async (opts) => {
-    const res = await requireClient().deleteBrandMember(opts.team, opts.member);
-    console.log(JSON.stringify(res, null, 2));
+    .option("--dry-run", "预览", false)
+    .option("--apply", "执行写入", false)
+    .action(async (opts) => {
+    await withPermissionGate({
+        command: "brand-members remove",
+        resource: "brandMember",
+        action: "delete",
+        teamId: opts.team,
+    }, async () => {
+        if (!assertApplyOrDryRun(opts, {
+            command: "brand-members remove",
+            danger: "delete",
+            summary: { teamId: opts.team, memberId: opts.member },
+        })) {
+            return;
+        }
+        const res = await requireClient().deleteBrandMember(opts.team, opts.member);
+        console.log(JSON.stringify(res, null, 2));
+    });
 });
 // Only parse when run directly (not when imported for testing)
 if (!process.env["VITEST"]) {