{"_id":"@4t145/lark-acp","_rev":"3-3425a3462b058663dbd30f47289b7d8d","name":"@4t145/lark-acp","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@4t145/lark-acp","version":"0.1.0","keywords":["feishu","lark","acp","agent-client-protocol","ai-agent","bridge"],"license":"MIT","_id":"@4t145/lark-acp@0.1.0","maintainers":[{"name":"4t145","email":"u4t145@163.com"}],"homepage":"https://github.com/4t145/lark-acp#readme","bugs":{"url":"https://github.com/4t145/lark-acp/issues"},"bin":{"lark-acp":"dist/bin/lark-acp.js","lark-acp-mock":"dist/bin/mock-agent.js"},"dist":{"shasum":"d1f792784859b35e64b91345c9e94221e4d085b5","tarball":"https://registry.npmjs.org/@4t145/lark-acp/-/lark-acp-0.1.0.tgz","fileCount":99,"integrity":"sha512-5ktSKk6jjcsvHouxzCPvbPSLkh/NFjhgfGgpO74XRLCdbwfkWXgBgf6Ry8p2IkEDw3Sq7RuZHEXKb1wgL9yDwg==","signatures":[{"sig":"MEYCIQCD9uHf+12L+jG+Iifwj7DZ7fVk8rTtBOApHlqxC+amPwIhAKyMz2jjGjakYA3OknTKZ9pEFYSO0oXqojinE0xigKcG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@4t145%2flark-acp@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":311956},"main":"./dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"gitHead":"71456b437585d65790c8219188be56d5bd4742bc","scripts":{"dev":"tsc --watch","fmt":"prettier --write .","build":"tsc","start":"node dist/bin/lark-acp.js","prepare":"npm run build","fmt:check":"prettier --check ."},"_npmUser":{"name":"4t145","email":"u4t145@163.com"},"repository":{"url":"git+https://github.com/4t145/lark-acp.git","type":"git"},"_npmVersion":"10.9.8","description":"Bridge Feishu/Lark to any ACP-compatible AI agent","directories":{},"_nodeVersion":"22.22.3","dependencies":{"pino":"^10.3.1","marked":"^18.0.4","pino-pretty":"^13.1.3","@larksuiteoapi/node-sdk":"^1.65.0","@agentclientprotocol/sdk":"^0.16.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.8.3","typescript":"^5.9.3","@types/node":"^22.19.19"},"_npmOperationalInternal":{"tmp":"tmp/lark-acp_0.1.0_1779521838666_0.3543170386446277","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@4t145/lark-acp","version":"0.1.1","keywords":["feishu","lark","acp","agent-client-protocol","ai-agent","bridge"],"license":"MIT","_id":"@4t145/lark-acp@0.1.1","maintainers":[{"name":"4t145","email":"u4t145@163.com"}],"homepage":"https://github.com/4t145/lark-acp#readme","bugs":{"url":"https://github.com/4t145/lark-acp/issues"},"bin":{"lark-acp":"dist/bin/lark-acp.js","lark-acp-mock":"dist/bin/mock-agent.js"},"dist":{"shasum":"7136cabe8656d3d4f03554438aa9626b0dca5fe2","tarball":"https://registry.npmjs.org/@4t145/lark-acp/-/lark-acp-0.1.1.tgz","fileCount":99,"integrity":"sha512-Zh2zQd70Rnm1P9LeQRCV1K2tPBGDNTCtq+WSxlsCI0hWCgTDj0Za4uj2XccL0RM0U32/GNGwYC/YhyObEdpFxQ==","signatures":[{"sig":"MEYCIQCmm/uhV7M4W3YraP1O8horVST/nh0kEeSRhwblhVclDQIhAMbZbjfLTzkTBlz6AQfEJI/O097QnmzclLxosiRvOfU6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@4t145%2flark-acp@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":312012},"main":"./dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"gitHead":"ae8947396f00d38f5358431d04da9762069bd79d","scripts":{"dev":"tsc --watch","fmt":"prettier --write .","build":"tsc && chmod +x dist/bin/lark-acp.js dist/bin/mock-agent.js","start":"node dist/bin/lark-acp.js","prepare":"npm run build","fmt:check":"prettier --check ."},"_npmUser":{"name":"4t145","email":"u4t145@163.com"},"repository":{"url":"git+https://github.com/4t145/lark-acp.git","type":"git"},"_npmVersion":"10.9.8","description":"Bridge Feishu/Lark to any ACP-compatible AI agent","directories":{},"_nodeVersion":"22.22.3","dependencies":{"pino":"^10.3.1","marked":"^18.0.4","pino-pretty":"^13.1.3","@larksuiteoapi/node-sdk":"^1.65.0","@agentclientprotocol/sdk":"^0.16.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.8.3","typescript":"^5.9.3","@types/node":"^22.19.19"},"_npmOperationalInternal":{"tmp":"tmp/lark-acp_0.1.1_1779522715109_0.3024105730709281","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@4t145/lark-acp","version":"0.1.2","description":"Bridge Feishu/Lark to any ACP-compatible AI agent","type":"module","publishConfig":{"access":"public"},"bin":{"lark-acp":"dist/bin/lark-acp.js","lark-acp-mock":"dist/bin/mock-agent.js"},"main":"./dist/src/index.js","types":"./dist/src/index.d.ts","exports":{".":{"import":"./dist/src/index.js","types":"./dist/src/index.d.ts"}},"scripts":{"build":"tsc && chmod +x dist/bin/lark-acp.js dist/bin/mock-agent.js","prepare":"npm run build","start":"node dist/bin/lark-acp.js","dev":"tsc --watch","fmt":"prettier --write .","fmt:check":"prettier --check ."},"dependencies":{"@agentclientprotocol/sdk":"^0.16.1","@larksuiteoapi/node-sdk":"^1.65.0","marked":"^18.0.4","pino":"^10.3.1","pino-pretty":"^13.1.3"},"devDependencies":{"@types/node":"^22.19.19","prettier":"^3.8.3","typescript":"^5.9.3"},"engines":{"node":">=20.0.0"},"repository":{"type":"git","url":"git+https://github.com/4t145/lark-acp.git"},"license":"MIT","keywords":["feishu","lark","acp","agent-client-protocol","ai-agent","bridge"],"_id":"@4t145/lark-acp@0.1.2","gitHead":"5501da82bfef80e8316896a5196de222e24f7b24","bugs":{"url":"https://github.com/4t145/lark-acp/issues"},"homepage":"https://github.com/4t145/lark-acp#readme","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-3mqS4VFSUlMd7yq2y2Ggi4XjsooWzzxHqR5ySsiqQ0AhssEBeZTT2EitaIkUwSpQug6NX9E0NYR1fzhrEstiiw==","shasum":"3460ba1e41a81c9f45271a234d7538eb6988a822","tarball":"https://registry.npmjs.org/@4t145/lark-acp/-/lark-acp-0.1.2.tgz","fileCount":99,"unpackedSize":316146,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@4t145%2flark-acp@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHs7W/1EV5enlZN6Gfm7Q2+gvnwgMNVXzineZZRKKZWzAiEA2AdzAE2XsacMrQmH6hi2Fw0oGeOvJfE/p4IGVAe+py4="}]},"_npmUser":{"name":"4t145","email":"u4t145@163.com"},"directories":{},"maintainers":[{"name":"4t145","email":"u4t145@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lark-acp_0.1.2_1779526554639_0.16226019974900407"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-23T07:37:18.493Z","modified":"2026-05-23T08:55:55.063Z","0.1.0":"2026-05-23T07:37:18.895Z","0.1.1":"2026-05-23T07:51:55.256Z","0.1.2":"2026-05-23T08:55:54.779Z"},"bugs":{"url":"https://github.com/4t145/lark-acp/issues"},"license":"MIT","homepage":"https://github.com/4t145/lark-acp#readme","keywords":["feishu","lark","acp","agent-client-protocol","ai-agent","bridge"],"repository":{"type":"git","url":"git+https://github.com/4t145/lark-acp.git"},"description":"Bridge Feishu/Lark to any ACP-compatible AI agent","maintainers":[{"name":"4t145","email":"u4t145@163.com"}],"readme":"# lark-acp\n\n[![npm version](https://img.shields.io/npm/v/@4t145/lark-acp.svg)](https://www.npmjs.com/package/@4t145/lark-acp)\n[![npm downloads](https://img.shields.io/npm/dm/@4t145/lark-acp.svg)](https://www.npmjs.com/package/@4t145/lark-acp)\n[![node version](https://img.shields.io/node/v/@4t145/lark-acp.svg)](https://www.npmjs.com/package/@4t145/lark-acp)\n[![license](https://img.shields.io/npm/l/@4t145/lark-acp.svg)](./LICENSE)\n\n> 💖 觉得本项目有帮助、或者只是看着有点意思？动动发财的小手在右上角点个 ⭐ Star 吧——这是对作者最直接的鼓励。\n\n> ⚠️ **WIP**：仍在迭代中，1.0 之前 CLI 选项与配置字段可能继续调整。\n\n把 [飞书/Lark](https://open.larksuite.com/) 机器人接到任何符合 [ACP（Agent Client Protocol）](https://agentcommunicationprotocol.dev/) 的 AI Agent 上：用户在飞书里发消息，agent 在你的机器上跑，过程和结果都以一张可交互的飞书卡片呈现，工具调用授权、中断、跨进程恢复会话都在卡片里完成。\n\n<p align=\"center\">\n  <img src=\"docs/mock-example.png\" alt=\"lark-acp 在飞书里的演示卡片\" width=\"640\">\n</p>\n\n---\n\n## CLI: `lark-acp`\n\n### 安装与运行\n\n```bash\n# 通过 npm / npx：\nnpx -y @4t145/lark-acp --help\n\n# 或在仓库内本地构建：\nbun install\nbun run build\nnode dist/bin/lark-acp.js --help\n```\n\n### 命令格式\n\n```\nlark-acp [global-options] proxy --agent <preset> [-- <extra-args>...]\nlark-acp [global-options] proxy -- <agent-cmd> [agent-args...]\nlark-acp agents\nlark-acp help\nlark-acp version\n```\n\n两种启动方式：\n\n- **`--agent <preset>`** —— 使用内置预设，最常用。运行 `lark-acp agents` 查看完整列表。\n- **`-- <agent-cmd>`** —— 自定义命令，`--` 后的所有参数原样转发给 agent。\n\n两种方式可以组合：`proxy --agent claude -- --debug` 会在预设末尾追加 `--debug` 再启动。\n\n全局选项必须放在 `proxy` 子命令之前。\n\n### 内置 agent 预设\n\n| Preset         | 说明                                                                          |\n| -------------- | ----------------------------------------------------------------------------- |\n| `claude`       | Claude Code，需先在终端跑过 `claude` 完成登录。                               |\n| `claude-agent` | Claude Agent SDK 适配器，需要 `ANTHROPIC_API_KEY`。                           |\n| `codex`        | OpenAI Codex 适配器。                                                         |\n| `copilot`      | GitHub Copilot CLI。                                                          |\n| `gemini`       | Google Gemini CLI（实验性）。                                                 |\n| `opencode`     | OpenCode，需要 `opencode` 已在 `$PATH` 上。                                   |\n\n不在预设里的 agent，用 raw command：\n\n```bash\nlark-acp proxy -- node ./my-acp-server.js --port 9000\n```\n\n也可以在配置文件的 `agents` 字段里固化自己的预设（详见下文「配置文件」一节）。\n\n### 全局选项\n\n| 选项                    | 说明                                                                                                |\n| ----------------------- | --------------------------------------------------------------------------------------------------- |\n| `--cwd <dir>`           | agent 工作目录（默认当前目录）                                                                      |\n| `--config <path>`       | 覆盖配置文件路径                                                                                    |\n| `--data-dir <dir>`      | 覆盖会话存储目录                                                                                    |\n| `--idle-timeout <min>`  | 闲置 N 分钟后释放会话（`0` 表示永不，默认 1440）                                                    |\n| `--max-chats <n>`       | 最大并发会话数（默认 10）                                                                           |\n| `--hide-thoughts`       | 不在卡片里渲染思考过程                                                                              |\n| `--hide-tools`          | 不在卡片里渲染工具调用                                                                              |\n| `--hide-cancel-button`  | 不渲染卡片底部的\"中断当前任务\"按钮                                                                  |\n| `--permission-mode <m>` | 工具授权策略：`alwaysAsk`（默认，弹卡片让用户选）/ `alwaysAllow`（自动允许）/ `alwaysDeny`（自动拒绝） |\n| `-h`, `--help`          | 显示帮助                                                                                            |\n| `-v`, `--version`       | 显示版本                                                                                            |\n\n### 配置文件\n\nCLI 读取一份配置文件（默认 `~/.config/lark-acp/config.json`），里面包含凭据和运行时默认值。优先级：CLI flag > 环境变量 > 配置文件 > 内置默认。\n\n完整字段（都可选）：\n\n```jsonc\n{\n  \"credentials\": {\n    \"appId\": \"cli_xxxxxxxxxxxxxxxx\",\n    \"appSecret\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  },\n  \"dataDir\": \"./var/lark-acp\",\n  \"runtime\": {\n    \"cwd\": \"/work/project\",\n    \"idleTimeoutMinutes\": 1440,\n    \"maxChats\": 10,\n    \"hideThoughts\": false,\n    \"hideTools\": false,\n    \"hideCancelButton\": false,\n    \"permissionMode\": \"alwaysAsk\",\n  },\n  \"agents\": {\n    // 在已有的内置预设上\"打补丁\"——只需要写要改的字段\n    \"claude\": {\n      \"env\": { \"ANTHROPIC_BASE_URL\": \"https://my-proxy.example.com\" },\n    },\n    // 新增一个用户自己的预设——必须同时给出 label 和 command\n    \"my-agent\": {\n      \"label\": \"My ACP Agent\",\n      \"command\": \"node\",\n      \"args\": [\"./my-agent.js\", \"--acp\"],\n      \"description\": \"本地自研 agent\",\n      \"env\": { \"FOO\": \"bar\" },\n    },\n  },\n}\n```\n\n凭据可以用环境变量代替文件：`LARK_ACP_APP_ID` / `LARK_ACP_APP_SECRET`。\n\n`lark-acp agents` 会列出当前配置下所有可用的预设，并标出来源（`[built-in]` / `[user]` / `[overridden]`）。\n\n> 在飞书开放平台 [开发者后台](https://open.larksuite.com/app) 创建一个\"自建应用\"，从「凭证与基础信息」页拿 `App ID` / `App Secret`；在「事件与回调」里把订阅模式切到 **长连接 (WebSocket)**。具体步骤见下文「飞书开发者后台配置」。\n\n### 飞书开发者后台配置\n\n在 [飞书开放平台](https://open.feishu.cn/app)（海外版 [Lark Developer](https://open.larksuite.com/app)）创建一个\"自建应用\"后，需要配置三块：**权限**、**事件**、**回调**，然后发布版本。\n\n#### 1. 添加权限\n\n「权限管理 → 批量导入/导出权限 → 导入」，粘贴下面这份 JSON 后保存：\n\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"im:message\",\n      \"im:message.group_msg\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message:readonly\",\n      \"im:message:send_as_bot\",\n      \"im:message:update\",\n      \"im:message.reactions:write_only\",\n      \"im:resource\",\n      \"im:chat:readonly\",\n      \"cardkit:card:write\",\n      \"contact:user.base:readonly\"\n    ],\n    \"user\": []\n  }\n}\n```\n\n每条权限对应的能力：\n\n| 权限                                    | 用途                                                |\n| --------------------------------------- | --------------------------------------------------- |\n| `im:message` / `im:message:send_as_bot` | 以机器人身份回复用户消息                            |\n| `im:message.group_msg`                  | 在群聊中接收消息                                    |\n| `im:message.p2p_msg:readonly`           | 在单聊中接收消息                                    |\n| `im:message:readonly`                   | 拉取消息上下文（@提及解析、富文本展开）             |\n| `im:message:update`                     | 更新交互卡片（流式渲染思考 / 工具调用 / 终态）      |\n| `im:message.reactions:write_only`       | 给消息加 / 撤 emoji 反馈，标记任务进度              |\n| `im:resource`                           | 下载用户上传的图片 / 文件二进制（按 `message_id`）  |\n| `im:chat:readonly`                      | 读群信息（注入到 prompt 上下文里：群名、群 id）     |\n| `cardkit:card:write`                    | 发送 / 修改 v2 互动卡片                             |\n| `contact:user.base:readonly`            | 读用户名（注入到 prompt 上下文里：发送者姓名）      |\n\n#### 2. 添加事件\n\n「事件与回调 → 事件配置」，把**订阅方式**切到 **使用长连接接收事件**（不需要配置回调地址）。然后添加这一个事件，订阅身份选\"应用身份\"：\n\n| 事件名   | event_type              | 用途                       |\n| -------- | ----------------------- | -------------------------- |\n| 接收消息 | `im.message.receive_v1` | 用户发的每条消息进入桥接层 |\n\n#### 3. 添加回调\n\n同一页「事件与回调 → 事件配置」下方的\"卡片回调\"区，添加：\n\n| 回调名       | event_type            | 用途                                                |\n| ------------ | --------------------- | --------------------------------------------------- |\n| 卡片回传交互 | `card.action.trigger` | 用户点击卡片按钮（授权选项 / 中断当前任务）         |\n\n#### 4. 发布版本\n\n「版本管理与发布 → 创建版本」，按提示填写资料后提交审核 / 发布。**应用可见范围**根据实际需要选——只有可见范围内的用户才能在飞书里找到这个机器人并对话。\n\n#### 5. 启用\n\n把 `App ID` / `App Secret` 填到 `config.json`（或环境变量 `LARK_ACP_APP_ID` / `LARK_ACP_APP_SECRET`），运行：\n\n```bash\nlark-acp proxy --agent claude\n```\n\n然后在飞书里搜到这个机器人、单聊或拉到群里直接发消息即可。\n\n### 配置示例\n\n#### 最小配置（仅写一个文件，其它走默认）\n\n```bash\n# 1. 准备目录（首次使用时一次性执行）\nmkdir -p \"${XDG_CONFIG_HOME:-$HOME/.config}/lark-acp\"\n\n# 2. 写入凭据\ncat > \"${XDG_CONFIG_HOME:-$HOME/.config}/lark-acp/config.json\" <<'EOF'\n{\n  \"credentials\": {\n    \"appId\":     \"cli_a1b2c3d4e5f60001\",\n    \"appSecret\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n  }\n}\nEOF\nchmod 600 \"${XDG_CONFIG_HOME:-$HOME/.config}/lark-acp/config.json\"\n\n# 3. 启动桥接\nlark-acp proxy --agent claude\n```\n\n#### 完整配置（凭据 + 运行时默认值）\n\n把常用默认值固化到文件，命令行只剩 `proxy --agent`：\n\n```jsonc\n{\n  \"credentials\": {\n    \"appId\": \"cli_a1b2c3d4e5f60001\",\n    \"appSecret\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  },\n  \"runtime\": {\n    \"cwd\": \"/srv/projects/main\",\n    \"idleTimeoutMinutes\": 60,\n    \"maxChats\": 20,\n    \"hideThoughts\": true,\n  },\n}\n```\n\n```bash\nlark-acp proxy --agent claude\n```\n\nCLI flag 会临时覆盖文件里的同名项。\n\n#### systemd 托管\n\n`lark-acp` 是前台进程，由进程管理器托管即可：\n\n```ini\n[Service]\nEnvironment=LARK_ACP_APP_ID=cli_a1b2c3d4e5f60001\nEnvironment=LARK_ACP_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nExecStart=/usr/local/bin/lark-acp --cwd /srv/projects/main proxy --agent claude\nRestart=on-failure\n```\n\n### 快速示例\n\n```bash\n# 1. 接 Claude Code（最常用）\n#    会话自动持久化，重启不丢上下文。\nlark-acp proxy --agent claude\n\n# 2. 接 OpenCode，工作目录指向具体项目\nlark-acp --cwd /work/project proxy --agent opencode\n\n# 3. 接 GitHub Copilot CLI，关掉思考输出\nlark-acp --hide-thoughts proxy --agent copilot\n\n# 4. 自研 ACP server\nlark-acp proxy -- node ./my-acp-server.js --port 9000\n```\n\n\n## 类似的项目\n1. golang 版本，实现也很齐全，https://github.com/ri-char/Lark-ACP\n2. 另一个node版本，本项目由此重构而来 https://github.com/JiaqiZhang-Dev/lark-acp\n\n### 本实现的不同\n1. 经过生产实践上的考虑，对permissionMode添加了代理层的设置\n2. 多个消息合并成一个卡片，避免在群聊中消息轰炸\n3. 作为库提供，方便二次开发\n---\n\n## 参考\n\n- ACP 协议：<https://agentcommunicationprotocol.dev/core-concepts/architecture>\n- 飞书开放平台：<https://open.larksuite.com/document/server-docs/getting-started/getting-started>\n\nLicense: MIT\n","readmeFilename":"README.md"}