openclaw-codex-feishu 0.1.1

package/README.md

@@ -0,0 +1,49 @@
+# OpenClaw × Codex × Feishu Plugin
+
+该仓库现在提供了可运行的生产实现骨架（不仅是文档草图），核心能力包括：
+
+- `/codex` 命令路由（`new/resume/status/detach/stop/steer/plan/raw/model/permissions/review/approve/replay/log`）
+- `codex_bridge_send` 工具（给主 agent 做轻量 handoff）
+- `codex app-server` `stdio` transport 与 JSON-RPC 请求/通知处理（当前仅 stdio）
+- 绑定状态持久化（`bindings/*.json`）
+- turn 级 JSONL journal 落盘（`threads/<threadId>/turns/*.jsonl`）
+- raw chunk 渲染与 ANSI/`\r` 规范化
+
+## 运行环境
+
+- Node.js **>= 22.12**（OpenClaw CLI 要求）
+- npm 10+
+
+## 安装与试用
+
+### 一行命令安装（推荐）
+
+```bash
+npx openclaw-codex-feishu install
+```
+
+该命令会自动执行插件安装与启用。
+
+### 本地开发安装
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run validate:json
+openclaw plugins install .
+openclaw plugins enable codex-feishu
+```
+
+## 快速验证
+
+1. 在 Feishu 聊天发送 `/codex new /path/to/workspace`
+2. 发送普通任务文本（attached 模式会转为 `turn/start`）
+3. 发送 `/codex status` 查看绑定状态
+4. 发送 `/codex stop` 中断当前 turn
+5. 查看 `.openclaw-codex-feishu/threads/*/turns/*.jsonl` 确认日志落盘
+
+## 当前实现范围
+
+已实现生产必需基础链路：会话绑定、transport、命令路由、日志先写后渲染。
+若需要进一步增强，可继续补充：Feishu 卡片 API 实发、审批卡按钮回传、diff 文件上传等 UI 细节。

package/dist/commands/codex.schema.d.ts

@@ -0,0 +1,103 @@
+export declare const codexCommandSchema: {
+    readonly name: "codex";
+    readonly description: "Manage Codex sessions bridged to the current Feishu conversation.";
+    readonly subcommands: readonly [{
+        readonly name: "new";
+        readonly args: readonly [{
+            readonly name: "workspaceOrProject";
+            readonly required: false;
+        }];
+    }, {
+        readonly name: "resume";
+        readonly args: readonly [{
+            readonly name: "queryOrThreadId";
+            readonly required: false;
+        }];
+    }, {
+        readonly name: "detach";
+        readonly args: readonly [];
+    }, {
+        readonly name: "stop";
+        readonly args: readonly [];
+    }, {
+        readonly name: "steer";
+        readonly args: readonly [{
+            readonly name: "text";
+            readonly required: true;
+            readonly variadic: true;
+        }];
+    }, {
+        readonly name: "plan";
+        readonly args: readonly [{
+            readonly name: "goal";
+            readonly required: false;
+            readonly variadic: true;
+        }];
+    }, {
+        readonly name: "review";
+        readonly args: readonly [{
+            readonly name: "focus";
+            readonly required: false;
+            readonly variadic: true;
+        }];
+    }, {
+        readonly name: "raw";
+        readonly args: readonly [{
+            readonly name: "mode";
+            readonly required: true;
+            readonly enum: readonly ["off", "cli", "all"];
+        }];
+    }, {
+        readonly name: "model";
+        readonly args: readonly [{
+            readonly name: "name";
+            readonly required: true;
+        }];
+    }, {
+        readonly name: "permissions";
+        readonly args: readonly [{
+            readonly name: "mode";
+            readonly required: true;
+            readonly enum: readonly ["default", "full"];
+        }];
+    }, {
+        readonly name: "log";
+        readonly args: readonly [{
+            readonly name: "turnId";
+            readonly required: false;
+        }];
+    }, {
+        readonly name: "replay";
+        readonly args: readonly [{
+            readonly name: "turnId";
+            readonly required: false;
+        }];
+    }, {
+        readonly name: "status";
+        readonly args: readonly [];
+    }, {
+        readonly name: "approve";
+        readonly args: readonly [{
+            readonly name: "requestId";
+            readonly required: true;
+        }, {
+            readonly name: "action";
+            readonly required: true;
+            readonly enum: readonly ["allow-once", "allow-always", "deny", "cancel", "amend"];
+        }, {
+            readonly name: "amendedCommand";
+            readonly required: false;
+            readonly variadic: true;
+        }];
+    }];
+    readonly aliases: {
+        readonly cas_resume: "codex resume";
+        readonly cas_status: "codex status";
+        readonly cas_stop: "codex stop";
+        readonly cas_steer: "codex steer";
+        readonly cas_plan: "codex plan";
+        readonly cas_review: "codex review";
+        readonly cas_detach: "codex detach";
+    };
+};
+export type CodexCommandSchema = typeof codexCommandSchema;

package/dist/commands/codex.schema.js

@@ -0,0 +1,42 @@
+export const codexCommandSchema = {
+    name: "codex",
+    description: "Manage Codex sessions bridged to the current Feishu conversation.",
+    subcommands: [
+        { name: "new", args: [{ name: "workspaceOrProject", required: false }] },
+        { name: "resume", args: [{ name: "queryOrThreadId", required: false }] },
+        { name: "detach", args: [] },
+        { name: "stop", args: [] },
+        { name: "steer", args: [{ name: "text", required: true, variadic: true }] },
+        { name: "plan", args: [{ name: "goal", required: false, variadic: true }] },
+        { name: "review", args: [{ name: "focus", required: false, variadic: true }] },
+        {
+            name: "raw",
+            args: [{ name: "mode", required: true, enum: ["off", "cli", "all"] }]
+        },
+        { name: "model", args: [{ name: "name", required: true }] },
+        {
+            name: "permissions",
+            args: [{ name: "mode", required: true, enum: ["default", "full"] }]
+        },
+        { name: "log", args: [{ name: "turnId", required: false }] },
+        { name: "replay", args: [{ name: "turnId", required: false }] },
+        { name: "status", args: [] },
+        {
+            name: "approve",
+            args: [
+                { name: "requestId", required: true },
+                { name: "action", required: true, enum: ["allow-once", "allow-always", "deny", "cancel", "amend"] },
+                { name: "amendedCommand", required: false, variadic: true }
+            ]
+        }
+    ],
+    aliases: {
+        cas_resume: "codex resume",
+        cas_status: "codex status",
+        cas_stop: "codex stop",
+        cas_steer: "codex steer",
+        cas_plan: "codex plan",
+        cas_review: "codex review",
+        cas_detach: "codex detach"
+    }
+};

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export type AttachMode = "attached" | "toolOnly";
+export type RawMode = "off" | "cli" | "all";
+export interface PluginConfig {
+    transport: "stdio";
+    command: string;
+    args: string[];
+    defaultWorkspaceDir?: string;
+    defaultModel?: string;
+    attachModeDefault?: AttachMode;
+    rawModeDefault?: RawMode;
+    feishu?: {
+        pinControlCard?: boolean;
+        rotateControlCardAfterDays?: number;
+        controlCardEditMinIntervalMs?: number;
+        streamFlushMs?: number;
+        streamChunkChars?: number;
+        liveTailChars?: number;
+        sendJsonlOnTurnComplete?: boolean;
+        sendReadableTranscriptOnTurnComplete?: boolean;
+        buttonsOnly?: boolean;
+    };
+    dataDir?: string;
+}
+export declare function resolveConfig(raw: unknown): Required<PluginConfig>;

package/dist/config.js

@@ -0,0 +1,24 @@
+export function resolveConfig(raw) {
+    const input = (raw ?? {});
+    return {
+        transport: input.transport ?? "stdio",
+        command: input.command ?? "codex",
+        args: input.args ?? ["app-server", "--listen", "stdio://"],
+        defaultWorkspaceDir: input.defaultWorkspaceDir ?? process.cwd(),
+        defaultModel: input.defaultModel ?? "gpt-5.4",
+        attachModeDefault: input.attachModeDefault ?? "attached",
+        rawModeDefault: input.rawModeDefault ?? "cli",
+        dataDir: input.dataDir ?? ".openclaw-codex-feishu",
+        feishu: {
+            pinControlCard: input.feishu?.pinControlCard ?? true,
+            rotateControlCardAfterDays: input.feishu?.rotateControlCardAfterDays ?? 12,
+            controlCardEditMinIntervalMs: input.feishu?.controlCardEditMinIntervalMs ?? 1000,
+            streamFlushMs: input.feishu?.streamFlushMs ?? 750,
+            streamChunkChars: input.feishu?.streamChunkChars ?? 1500,
+            liveTailChars: input.feishu?.liveTailChars ?? 1200,
+            sendJsonlOnTurnComplete: input.feishu?.sendJsonlOnTurnComplete ?? true,
+            sendReadableTranscriptOnTurnComplete: input.feishu?.sendReadableTranscriptOnTurnComplete ?? false,
+            buttonsOnly: input.feishu?.buttonsOnly ?? true
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind">;
+export default _default;

package/dist/index.js

@@ -0,0 +1,66 @@
+import { Type } from "@sinclair/typebox";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { BridgeRuntime } from "./runtime/bridgeRuntime.js";
+import { noopLogger } from "./utils/logger.js";
+let runtime;
+function resolveIdentity(ctx) {
+    return {
+        channel: String(ctx?.channel ?? "feishu"),
+        accountId: String(ctx?.senderId ?? "unknown"),
+        peerKey: String(ctx?.senderId ?? "unknown")
+    };
+}
+export default definePluginEntry({
+    id: "codex-feishu",
+    name: "OpenClaw Codex Feishu Bridge",
+    description: "Production bridge for Codex app-server sessions in Feishu with journaling and command routing.",
+    register(api) {
+        const logger = api?.logger ?? noopLogger;
+        runtime = new BridgeRuntime(api?.config, logger, {
+            async sendText(identity, text) {
+                logger.info(`[codex-feishu][${identity.channel}:${identity.accountId}:${identity.peerKey}] ${text}`);
+            }
+        });
+        api.registerService({
+            id: "codex-feishu-runtime",
+            start: async () => {
+                await runtime?.start();
+            },
+            stop: () => {
+                runtime?.stop();
+            }
+        });
+        api.registerCommand({
+            name: "codex",
+            description: "Manage Codex session binding and runtime operations.",
+            acceptsArgs: true,
+            requireAuth: true,
+            handler: async (ctx) => {
+                const identity = resolveIdentity(ctx);
+                const text = await runtime?.handleCodexCommand(identity, ctx?.args ?? "");
+                return { text: text ?? "runtime not ready" };
+            }
+        });
+        api.registerTool({
+            name: "codex_bridge_send",
+            label: "Codex Bridge Send",
+            description: "Send a task to the bound Codex thread and return an ACK.",
+            parameters: Type.Object({
+                task: Type.String({ minLength: 1, description: "Task goal or user instruction for Codex." }),
+                context: Type.Optional(Type.String({ description: "Optional context excerpt." }))
+            }),
+            async execute(_id, params) {
+                const identity = { channel: "feishu", accountId: "tool", peerKey: "tool" };
+                const ack = await runtime?.handleCodexToolTask(identity, params.task, params.context);
+                return {
+                    content: [{ type: "text", text: ack ?? "Codex runtime unavailable" }],
+                    details: {
+                        accepted: Boolean(ack),
+                        taskPreview: params.task.slice(0, 120),
+                        hasContext: Boolean(params.context)
+                    }
+                };
+            }
+        });
+    }
+});

package/dist/render/rawChunkRenderer.d.ts

@@ -0,0 +1,12 @@
+export interface ChunkSink {
+    sendChunk(bindingKey: string, chunk: string): Promise<void>;
+}
+export declare class RawChunkRenderer {
+    private readonly sink;
+    private readonly chunkSize;
+    private readonly buffers;
+    constructor(sink: ChunkSink, chunkSize: number);
+    push(bindingKey: string, text: string, forceFlush?: boolean): Promise<void>;
+    flush(bindingKey: string): Promise<void>;
+    private flushCombined;
+}

package/dist/render/rawChunkRenderer.js

@@ -0,0 +1,37 @@
+import { normalizeTranscriptChunk } from "./transcriptNormalizer.js";
+export class RawChunkRenderer {
+    sink;
+    chunkSize;
+    buffers = new Map();
+    constructor(sink, chunkSize) {
+        this.sink = sink;
+        this.chunkSize = chunkSize;
+    }
+    async push(bindingKey, text, forceFlush = false) {
+        const normalized = normalizeTranscriptChunk(text);
+        const current = this.buffers.get(bindingKey) ?? "";
+        const combined = `${current}${normalized}`;
+        if (!forceFlush && combined.length < this.chunkSize) {
+            this.buffers.set(bindingKey, combined);
+            return;
+        }
+        await this.flushCombined(bindingKey, combined);
+    }
+    async flush(bindingKey) {
+        const combined = this.buffers.get(bindingKey);
+        if (!combined)
+            return;
+        await this.flushCombined(bindingKey, combined);
+    }
+    async flushCombined(bindingKey, combined) {
+        this.buffers.set(bindingKey, "");
+        let offset = 0;
+        while (offset < combined.length) {
+            const chunk = combined.slice(offset, offset + this.chunkSize);
+            offset += this.chunkSize;
+            if (!chunk)
+                continue;
+            await this.sink.sendChunk(bindingKey, chunk);
+        }
+    }
+}

package/dist/render/transcriptNormalizer.d.ts

@@ -0,0 +1 @@
+export declare function normalizeTranscriptChunk(input: string): string;

package/dist/render/transcriptNormalizer.js

@@ -0,0 +1,12 @@
+const ANSI_RE = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+export function normalizeTranscriptChunk(input) {
+    const noAnsi = input.replace(ANSI_RE, "");
+    // Handle carriage-return overwrite behavior from terminals.
+    return noAnsi
+        .split("\n")
+        .map((line) => {
+        const lastCarriageReturn = line.lastIndexOf("\r");
+        return lastCarriageReturn >= 0 ? line.slice(lastCarriageReturn + 1) : line;
+    })
+        .join("\n");
+}

package/dist/runtime/bridgeRuntime.d.ts

@@ -0,0 +1,40 @@
+import { type ChunkSink } from "../render/rawChunkRenderer.js";
+import { type BindingIdentity } from "../state/bindingStore.js";
+import type { LoggerLike } from "../utils/logger.js";
+export interface ChatSink {
+    sendText(identity: BindingIdentity, text: string): Promise<void>;
+}
+export declare class BridgeRuntime implements ChunkSink {
+    private readonly logger;
+    private readonly chatSink;
+    private readonly config;
+    private readonly bindingStore;
+    private readonly journalStore;
+    private readonly renderer;
+    private readonly queue;
+    private readonly client;
+    constructor(rawConfig: unknown, logger: LoggerLike, chatSink: ChatSink);
+    start(): Promise<void>;
+    stop(): void;
+    sendChunk(bindingKey: string, chunk: string): Promise<void>;
+    handleCodexToolTask(identity: BindingIdentity, task: string, context?: string): Promise<string>;
+    handleCodexCommand(identity: BindingIdentity, argsRaw: string): Promise<string>;
+    private handleSteer;
+    private handlePlan;
+    private handleNew;
+    private handleResume;
+    private handleStatus;
+    private handleDetach;
+    private handleStop;
+    private handleRaw;
+    private handleModel;
+    private handlePermissions;
+    private handleReview;
+    private handleApprove;
+    private handleReplay;
+    private dispatchUserInput;
+    private handleNotification;
+    private identityFromBindingKey;
+    private shouldRenderRaw;
+    private extractRenderableText;
+}