larkin 0.3.0 → 0.3.2

package/README.md

@@ -5,7 +5,7 @@ Larkin connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It p
 ## Requirements
 
 - A supported macOS, Linux, or Windows (x64) system
-- `lark-cli`
+- Official `@larksuite/cli >= 1.0.80` (`lark-cli`) (Larkin product policy)
 - At least one supported agent runtime and its authentication
 - Bun 1.3.14 when running the npm package or building from source (standalone binaries bundle their own runtime)
 
@@ -36,6 +36,10 @@ The rest of this document uses the short `larkin` form; it works as-is after `np
 
 Run `larkin --help` or `larkin config --help` for the available commands and configuration options. Local configuration is stored under `~/.larkin` by default; set `LARKIN_CONFIG_DIR` to use another directory.
 
+### Feishu message links
+
+Feishu clients do not reliably render Markdown links such as `[label](URL)` as clickable in text or Markdown messages. When a recipient must be able to open a link, keep the complete bare HTTPS URL visible, for example: Issue 115 — https://github.com/eddiearc/larkin/issues/115. A label may accompany it, but must not replace the bare URL. Larkin does not rewrite exact, verbatim, or user-authored message bodies to enforce this guidance.
+
 During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Pi can use an existing
 official `pi` installation or the official Pi runtime bundled in Larkin. The bundled option supports
 DeepSeek, Kimi/Moonshot, MiniMax, Zhipu/BigModel, and a custom OpenAI-compatible Base URL. Provider keys

package/dist/agent/context-prompt.cjs

@@ -16,7 +16,7 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v19";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v20";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -132,7 +132,9 @@ class ContextPromptBuilder {
             "Only a real Feishu `message_id` beginning with `om_` may be passed to `+messages-reply`; `rem_`, `redeliver_`, and every other synthetic ID must never be replied to. Send with a confirmed `chat_id` and never guess a chat id from a display name.",
             "Before every send/reply/card write, Larkin probes the exact chat or thread history with the current Bot identity. A nonzero `freshness_conflict` includes bounded unseen context and direct-acks that cursor; reconsider it, then retry the ordinary command. Larkin never saves the blocked message body as a draft.",
             "For regular textual message bodies, default to `--markdown`, including brief single-line replies, so Feishu renders Markdown structure instead of showing its markers literally.",
+            "When a URL must be visible, clickable, or openable by the recipient, include the complete bare `https://...` URL as visible text. Do not rely solely on `[label](URL)`, because Feishu client rendering is unreliable. A label may also be included, but the bare URL must remain present.",
             "Use native `--text` only when plain text or verbatim preservation is explicitly needed, such as logs, code, or exact whitespace. Both `--markdown` and `--text` remain supported in the Larkin Runtime.",
+            "Never rewrite or normalize an exact or verbatim user-supplied body to expose a URL; the existing exact-content paths remain authoritative and preserve the supplied body unchanged.",
             "For exact text supplied directly in the current instruction or Inbox event, pass the body unchanged as one literal `--text` argument. A direct literal must not use command substitution, backticks, `eval`, `echo`, or an unquoted variable; if it cannot be represented safely, stop and report the limitation instead of normalizing it.",
             "An explicit exact or verbatim direct literal uses `--text` and overrides the regular markdown default.",
             `For a common exact send with a confirmed chat id, use the complete schematic recipe \`${executable} im +messages-send --chat-id <confirmed_chat_id> --text '<exact_body_as_one_literal_argument>' --json\`; replace each placeholder with the corresponding confirmed or exact literal value.`,

package/dist/agent/context-prompt.mjs

@@ -13,7 +13,7 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v19";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v20";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -129,7 +129,9 @@ export class ContextPromptBuilder {
             "Only a real Feishu `message_id` beginning with `om_` may be passed to `+messages-reply`; `rem_`, `redeliver_`, and every other synthetic ID must never be replied to. Send with a confirmed `chat_id` and never guess a chat id from a display name.",
             "Before every send/reply/card write, Larkin probes the exact chat or thread history with the current Bot identity. A nonzero `freshness_conflict` includes bounded unseen context and direct-acks that cursor; reconsider it, then retry the ordinary command. Larkin never saves the blocked message body as a draft.",
             "For regular textual message bodies, default to `--markdown`, including brief single-line replies, so Feishu renders Markdown structure instead of showing its markers literally.",
+            "When a URL must be visible, clickable, or openable by the recipient, include the complete bare `https://...` URL as visible text. Do not rely solely on `[label](URL)`, because Feishu client rendering is unreliable. A label may also be included, but the bare URL must remain present.",
             "Use native `--text` only when plain text or verbatim preservation is explicitly needed, such as logs, code, or exact whitespace. Both `--markdown` and `--text` remain supported in the Larkin Runtime.",
+            "Never rewrite or normalize an exact or verbatim user-supplied body to expose a URL; the existing exact-content paths remain authoritative and preserve the supplied body unchanged.",
             "For exact text supplied directly in the current instruction or Inbox event, pass the body unchanged as one literal `--text` argument. A direct literal must not use command substitution, backticks, `eval`, `echo`, or an unquoted variable; if it cannot be represented safely, stop and report the limitation instead of normalizing it.",
             "An explicit exact or verbatim direct literal uses `--text` and overrides the regular markdown default.",
             `For a common exact send with a confirmed chat id, use the complete schematic recipe \`${executable} im +messages-send --chat-id <confirmed_chat_id> --text '<exact_body_as_one_literal_argument>' --json\`; replace each placeholder with the corresponding confirmed or exact literal value.`,

package/dist/app/official-lark-cli.cjs

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OFFICIAL_LARK_CLI_INSTALL = exports.OFFICIAL_LARK_CLI_VERSION = void 0;
+exports.formatOfficialLarkCliConsent = formatOfficialLarkCliConsent;
 exports.invalidateOfficialLarkCliProbeCache = invalidateOfficialLarkCliProbeCache;
 exports.probeOfficialLarkCli = probeOfficialLarkCli;
 exports.resolveOfficialLarkCli = resolveOfficialLarkCli;
@@ -20,8 +21,25 @@ function safeRealpath(target) {
         return null;
     }
 }
-exports.OFFICIAL_LARK_CLI_VERSION = "1.0.79";
+exports.OFFICIAL_LARK_CLI_VERSION = "1.0.80";
 exports.OFFICIAL_LARK_CLI_INSTALL = `npm install --global @larksuite/cli@${exports.OFFICIAL_LARK_CLI_VERSION}`;
+function formatOfficialLarkCliConsent(request) {
+    if (request.action === "upgrade")
+        return {
+            lines: [
+                `[setup 0/5] 检测到官方 lark-cli 需要升级：${request.reason}`,
+                `将执行：${request.command}`,
+            ],
+            question: "是否升级？[y/N] ",
+        };
+    return {
+        lines: [
+            `[setup 0/5] ${request.reason}。Larkin 需要安装未修改的官方 lark-cli 作为 Feishu (Lark) 命令下游。`,
+            `将执行：${request.command}`,
+        ],
+        question: "是否安装？[y/N] ",
+    };
+}
 function loginShellPath(dependencies) {
     const env = dependencies.env ?? process.env;
     if ((dependencies.platform ?? process.platform) === "win32")
@@ -121,7 +139,7 @@ function validateOfficialCommand(command, env, spawn) {
     if (!compatibleVersion(command.version))
         return {
             state: "outdated",
-            reason: `官方 lark-cli ${command.version} 低于最低兼容版本 ${exports.OFFICIAL_LARK_CLI_VERSION}: ${command.command}`,
+            reason: `官方 lark-cli ${command.version} 低于产品策略最低版本 ${exports.OFFICIAL_LARK_CLI_VERSION}: ${command.command}`,
             nextAction: `升级：${exports.OFFICIAL_LARK_CLI_INSTALL}`,
         };
     const version = spawn(command.command, ["--version"], {
@@ -215,7 +233,7 @@ function probeOfficialLarkCliUncached(dependencies) {
     if (!compatibleVersion(command.version))
         return {
             state: "outdated",
-            reason: `真实 login shell 的官方 @larksuite/cli ${command.version} 低于最低兼容版本 ${exports.OFFICIAL_LARK_CLI_VERSION}`,
+            reason: `真实 login shell 的官方 @larksuite/cli ${command.version} 低于产品策略最低版本 ${exports.OFFICIAL_LARK_CLI_VERSION}`,
             nextAction: `升级：${exports.OFFICIAL_LARK_CLI_INSTALL}`,
         };
     return validateOfficialCommand(command, env, dependencies.spawn ?? node_child_process_1.spawnSync);
@@ -239,13 +257,14 @@ function resolveOfficialLarkCli(dependencies = {}) {
         throw new Error(`${result.reason}；${result.nextAction}`);
     return result.command;
 }
-function installOfficialLarkCli(dependencies = {}) {
+function installOfficialLarkCli(dependencies = {}, action = "install") {
     const run = dependencies.spawn ?? node_child_process_1.spawnSync;
     const result = run("npm", ["install", "--global", `@larksuite/cli@${exports.OFFICIAL_LARK_CLI_VERSION}`], {
         encoding: "utf8", env: dependencies.env ?? process.env, stdio: "inherit",
     });
-    if (result.status !== 0 || result.error)
-        throw new Error(`官方 lark-cli 安装失败（exit=${result.status ?? "none"}）`);
+    if (result.status !== 0 || result.error) {
+        throw new Error(`官方 lark-cli ${action === "upgrade" ? "升级" : "安装"}失败（exit=${result.status ?? "none"}）`);
+    }
     invalidateOfficialLarkCliProbeCache();
     return resolveOfficialLarkCli(dependencies);
 }
@@ -258,8 +277,13 @@ async function ensureOfficialLarkCliForSetup(input) {
     if (!input.interactive) {
         throw new Error(`${probe.reason}；非交互 setup 不会安装或升级依赖。请在终端运行 larkin setup，并确认：${exports.OFFICIAL_LARK_CLI_INSTALL}`);
     }
-    if (!await input.confirmInstall(exports.OFFICIAL_LARK_CLI_INSTALL)) {
-        throw new Error("未获得明确同意；没有安装官方 lark-cli，也没有写入 Agent 配置");
+    const request = probe.state === "outdated"
+        ? { action: "upgrade", command: exports.OFFICIAL_LARK_CLI_INSTALL, state: probe.state,
+            reason: probe.reason, nextAction: probe.nextAction }
+        : { action: "install", command: exports.OFFICIAL_LARK_CLI_INSTALL, state: probe.state,
+            reason: probe.reason, nextAction: probe.nextAction };
+    if (!await input.confirmInstall(request)) {
+        throw new Error(`未获得明确同意；没有${request.action === "upgrade" ? "升级" : "安装"}官方 lark-cli，也没有写入 Agent 配置`);
     }
-    return { command: installOfficialLarkCli(input), installed: true };
+    return { command: installOfficialLarkCli(input, request.action), installed: true, setupAction: request.action };
 }

package/dist/app/official-lark-cli.mjs

@@ -9,8 +9,25 @@ function safeRealpath(target) {
         return null;
     }
 }
-export const OFFICIAL_LARK_CLI_VERSION = "1.0.79";
+export const OFFICIAL_LARK_CLI_VERSION = "1.0.80";
 export const OFFICIAL_LARK_CLI_INSTALL = `npm install --global @larksuite/cli@${OFFICIAL_LARK_CLI_VERSION}`;
+export function formatOfficialLarkCliConsent(request) {
+    if (request.action === "upgrade")
+        return {
+            lines: [
+                `[setup 0/5] 检测到官方 lark-cli 需要升级：${request.reason}`,
+                `将执行：${request.command}`,
+            ],
+            question: "是否升级？[y/N] ",
+        };
+    return {
+        lines: [
+            `[setup 0/5] ${request.reason}。Larkin 需要安装未修改的官方 lark-cli 作为 Feishu (Lark) 命令下游。`,
+            `将执行：${request.command}`,
+        ],
+        question: "是否安装？[y/N] ",
+    };
+}
 function loginShellPath(dependencies) {
     const env = dependencies.env ?? process.env;
     if ((dependencies.platform ?? process.platform) === "win32")
@@ -110,7 +127,7 @@ function validateOfficialCommand(command, env, spawn) {
     if (!compatibleVersion(command.version))
         return {
             state: "outdated",
-            reason: `官方 lark-cli ${command.version} 低于最低兼容版本 ${OFFICIAL_LARK_CLI_VERSION}: ${command.command}`,
+            reason: `官方 lark-cli ${command.version} 低于产品策略最低版本 ${OFFICIAL_LARK_CLI_VERSION}: ${command.command}`,
             nextAction: `升级：${OFFICIAL_LARK_CLI_INSTALL}`,
         };
     const version = spawn(command.command, ["--version"], {
@@ -204,7 +221,7 @@ function probeOfficialLarkCliUncached(dependencies) {
     if (!compatibleVersion(command.version))
         return {
             state: "outdated",
-            reason: `真实 login shell 的官方 @larksuite/cli ${command.version} 低于最低兼容版本 ${OFFICIAL_LARK_CLI_VERSION}`,
+            reason: `真实 login shell 的官方 @larksuite/cli ${command.version} 低于产品策略最低版本 ${OFFICIAL_LARK_CLI_VERSION}`,
             nextAction: `升级：${OFFICIAL_LARK_CLI_INSTALL}`,
         };
     return validateOfficialCommand(command, env, dependencies.spawn ?? spawnSync);
@@ -228,13 +245,14 @@ export function resolveOfficialLarkCli(dependencies = {}) {
         throw new Error(`${result.reason}；${result.nextAction}`);
     return result.command;
 }
-export function installOfficialLarkCli(dependencies = {}) {
+export function installOfficialLarkCli(dependencies = {}, action = "install") {
     const run = dependencies.spawn ?? spawnSync;
     const result = run("npm", ["install", "--global", `@larksuite/cli@${OFFICIAL_LARK_CLI_VERSION}`], {
         encoding: "utf8", env: dependencies.env ?? process.env, stdio: "inherit",
     });
-    if (result.status !== 0 || result.error)
-        throw new Error(`官方 lark-cli 安装失败（exit=${result.status ?? "none"}）`);
+    if (result.status !== 0 || result.error) {
+        throw new Error(`官方 lark-cli ${action === "upgrade" ? "升级" : "安装"}失败（exit=${result.status ?? "none"}）`);
+    }
     invalidateOfficialLarkCliProbeCache();
     return resolveOfficialLarkCli(dependencies);
 }
@@ -247,8 +265,13 @@ export async function ensureOfficialLarkCliForSetup(input) {
     if (!input.interactive) {
         throw new Error(`${probe.reason}；非交互 setup 不会安装或升级依赖。请在终端运行 larkin setup，并确认：${OFFICIAL_LARK_CLI_INSTALL}`);
     }
-    if (!await input.confirmInstall(OFFICIAL_LARK_CLI_INSTALL)) {
-        throw new Error("未获得明确同意；没有安装官方 lark-cli，也没有写入 Agent 配置");
+    const request = probe.state === "outdated"
+        ? { action: "upgrade", command: OFFICIAL_LARK_CLI_INSTALL, state: probe.state,
+            reason: probe.reason, nextAction: probe.nextAction }
+        : { action: "install", command: OFFICIAL_LARK_CLI_INSTALL, state: probe.state,
+            reason: probe.reason, nextAction: probe.nextAction };
+    if (!await input.confirmInstall(request)) {
+        throw new Error(`未获得明确同意；没有${request.action === "upgrade" ? "升级" : "安装"}官方 lark-cli，也没有写入 Agent 配置`);
     }
-    return { command: installOfficialLarkCli(input), installed: true };
+    return { command: installOfficialLarkCli(input, request.action), installed: true, setupAction: request.action };
 }

package/dist/app/setup.mjs

@@ -14,7 +14,7 @@ import { requestAgentUpsert } from "./local-control.mjs";
 import { openOwnedDashboardWhenReady } from "./setup-dashboard.mjs";
 import { probeNativeRuntimeReadiness } from "../runtime/runtime-readiness.mjs";
 import { internalCommandSpec, processCommandToken } from "./internal-command.mjs";
-import { ensureOfficialLarkCliForSetup, } from "./official-lark-cli.mjs";
+import { ensureOfficialLarkCliForSetup, formatOfficialLarkCliConsent, } from "./official-lark-cli.mjs";
 const CFG_DIR = process.env.LARKIN_CONFIG_DIR || path.join(os.homedir(), ".larkin");
 const argv = process.argv.slice(2);
 const has = (name) => argv.includes(name);
@@ -127,16 +127,19 @@ export async function main() {
     const official = await ensureOfficialLarkCliForSetup({
         env: process.env,
         interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
-        async confirmInstall(command) {
-            say("[setup 0/5] Larkin 需要未修改的官方 lark-cli 作为 Feishu (Lark) 命令下游。");
-            say(`将执行：${command}`);
+        async confirmInstall(request) {
+            const copy = formatOfficialLarkCliConsent(request);
+            for (const line of copy.lines)
+                say(line);
             const input = readline.createInterface({ input: process.stdin, output: process.stdout });
-            const answer = (await input.question("是否安装？[y/N] ")).trim().toLowerCase();
+            const answer = (await input.question(copy.question)).trim().toLowerCase();
             input.close();
             return answer === "y" || answer === "yes";
         },
     }).catch((error) => die(error instanceof Error ? error.message : String(error)));
-    say(`[setup 0/5] ✓ 官方 lark-cli ${official.command.version}: ${official.command.command}${official.installed ? "（刚刚安装）" : ""}`);
+    const completedAction = official.setupAction === "upgrade" ? "（刚刚升级）"
+        : official.setupAction === "install" ? "（刚刚安装）" : "";
+    say(`[setup 0/5] ✓ 官方 lark-cli ${official.command.version}: ${official.command.command}${completedAction}`);
     say("\nAgent 与飞书（Lark）机器人按 App ID 一一对应：");
     say("  • 网页选择同一个机器人 → 热更新该 Agent，不重启其他 Agent");
     say("  • 网页创建新机器人 → 热挂载新 Agent，状态彼此独立\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkin",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [
@@ -74,6 +74,8 @@
     "test:eval:authoritative-freshness-gate": "bun test --max-concurrency 1 test/unit/evals/authoritative-freshness-gate.test.mjs",
     "test:eval:agent-experience-v6": "bun test --max-concurrency 1 test/unit/evals/agent-experience-v6.test.mjs",
     "test:eval:mention-construction": "bun run build && LARKIN_RUN_MENTION_CONSTRUCTION_EVAL=1 bun test --max-concurrency 1 test/live/mention-construction-agent-eval.test.mjs",
+    "test:eval:clickable-link-delivery": "bun run build && bun test --max-concurrency 1 test/unit/evals/clickable-link-delivery.test.mjs",
+    "test:eval:clickable-link-delivery:native": "bun run build && LARKIN_RUN_CLICKABLE_LINK_DELIVERY_EVAL=1 bun test --max-concurrency 1 test/live/clickable-link-delivery-agent-eval.test.mjs",
     "test:eval:public-contribution-governance": "bun test --max-concurrency 1 test/unit/evals/public-contribution-governance.test.mjs",
     "test:live:public-contribution-governance": "bun test --max-concurrency 1 test/live/public-contribution-governance-live.test.mjs",
     "test:eval:authoritative-freshness-gate:native": "bun run build && LARKIN_RUN_AUTHORITATIVE_FRESHNESS_EVAL=1 bun test --max-concurrency 1 test/live/authoritative-freshness-gate-agent-eval.test.mjs",