larkway 0.3.57 → 0.3.59

package/README.md

@@ -8,7 +8,7 @@
 
 You @ the bot in a Feishu thread. It runs on your machine — reading your real codebase, executing commands, opening MRs — and posts the result back. You define what the agent knows and what it can do. Larkway just carries the messages.
 
-**Current release: v0.3.57**
+**Current release: v0.3.59**
 
 ---
 
@@ -61,7 +61,7 @@ Feishu thread
 
 **What Larkway does NOT do** — the agent decides everything else:
 
-- No GitLab/GitHub API calls (the agent runs `glab`/`gh` itself)
+- No GitHub/GitLab API calls (the agent runs `gh`/`glab` itself)
 - No worktree creation (the agent runs `git worktree add`)
 - No dev server management (the agent starts it)
 - No orchestration logic — the agent reads your `AGENTS.md` / `CLAUDE.md` / skills and plans its own steps
@@ -194,10 +194,11 @@ platform-fact writeups: [docs/task-handle.md](docs/task-handle.md).
 
 ## Requirements
 
+- **macOS or Linux** — native Windows is not supported yet (the runtime depends on POSIX tooling such as `bash` and `pgrep`); on Windows, install and run everything (Node.js, larkway, Claude Code / Codex, `lark-cli`) inside [WSL](https://learn.microsoft.com/windows/wsl/install)
 - **Node.js 20+ LTS**
 - **A Claude Code or Codex subscription** with local CLI installed and logged in
 - **`lark-cli`** — Feishu long-connection client and message utilities: `npm i -g @larksuite/cli`, then `lark-cli auth login` (the agent uses it to read thread history and attachments; `larkway doctor` checks it's present)
-- **`glab` + `git`** — for bots that open MRs (optional for read-only bots)
+- **`git` + `gh`** — for bots that open PRs (GitHub is the default forge; use `glab` instead for GitLab repos; both optional for read-only bots)
 - **An always-on host machine** — the bridge must stay running to receive Feishu events; a laptop that sleeps will miss messages; a small server or desktop works well
 
 ---

package/README.zh.md

@@ -8,7 +8,7 @@
 
 你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
 
-**当前版本：v0.3.57**
+**当前版本：v0.3.59**
 
 ---
 

package/bin/larkway.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// larkway CLI shim — resolves the package root from this script's own location
+// so it works whether invoked via `bin/larkway`, an absolute path, or a symlink
+// on PATH (e.g. after `npm i -g`).
+//
+// Written in Node (not bash) so npm's cross-platform bin shims work everywhere:
+// a bash shebang made Windows installs fail at startup with
+// `/bin/bash: C:Users...: No such file or directory` before any of our code ran.
+//
+// Startup priority:
+//   1. dist/cli/index.js exists  → import it in-process (installed package / post-build)
+//   2. otherwise                 → `npx tsx src/cli/index.ts` (fresh clone dev mode, no build)
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+if (process.platform === "win32") {
+  // The bridge runtime depends on POSIX tooling (bash supervisor, pgrep, lsof),
+  // so native Windows is not supported yet — fail fast with guidance instead of
+  // crashing later with an obscure error.
+  console.error(
+    [
+      "larkway 暂不支持原生 Windows 运行(依赖 bash / pgrep 等 POSIX 工具)。",
+      "推荐在 WSL(Windows Subsystem for Linux)中安装使用:",
+      "  1. 安装 WSL: https://learn.microsoft.com/windows/wsl/install",
+      "  2. 在 WSL 终端内安装 Node.js 20+,然后 `npm i -g larkway`",
+      "  3. Claude Code / Codex 也需安装在 WSL 内",
+      "",
+      "larkway does not yet support native Windows (it depends on POSIX tooling",
+      "such as bash and pgrep). Please install and run it inside WSL instead.",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+const selfPath = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(selfPath), "..");
+const distEntry = path.join(repoRoot, "dist", "cli", "index.js");
+
+if (existsSync(distEntry)) {
+  await import(pathToFileURL(distEntry).href);
+} else {
+  // Dev fallback: run TypeScript source directly via tsx.
+  const result = spawnSync(
+    "npx",
+    ["tsx", path.join(repoRoot, "src", "cli", "index.ts"), ...process.argv.slice(2)],
+    { stdio: "inherit" },
+  );
+  process.exit(result.status ?? 1);
+}

package/dist/cli/index.js

@@ -109971,6 +109971,70 @@ var init_client = __esm({
           wrapErr(label, err2);
         }
       }
+      /**
+       * task_handle v5 (BL-48, 声明式建卡): create a task under this bot's app
+       * identity. `due.timestamp` is ms-epoch string per task v2; `members` lets
+       * the create carry the originator as follower in one call; `tasklists`
+       * attaches the task to the bot's configured list when present. Response
+       * shape mirrors createTasklist's envelope (`data.task.guid`).
+       */
+      async createTask(input) {
+        const label = `createTask(${input.summary.slice(0, 30)})`;
+        let resp;
+        try {
+          resp = await this.#request(
+            {
+              method: "POST",
+              url: `${TASK_V2_BASE}/tasks`,
+              params: { user_id_type: "open_id" },
+              data: {
+                summary: input.summary,
+                ...input.description ? { description: input.description } : {},
+                ...input.due ? { due: input.due } : {},
+                ...input.members && input.members.length > 0 ? { members: input.members } : {},
+                ...input.tasklists && input.tasklists.length > 0 ? { tasklists: input.tasklists } : {}
+              }
+            },
+            label
+          );
+        } catch (err2) {
+          wrapErr(label, err2);
+        }
+        const guid = resp.data?.task?.["guid"];
+        if (typeof guid !== "string" || guid.length === 0) {
+          throw new TaskApiError(`[tasklist.client] ${label} returned no guid`, {});
+        }
+        return { guid };
+      }
+      /**
+       * task_handle v5: add members (e.g. a late follower) to an existing TASK
+       * (`POST /tasks/:guid/add_members` — task-level counterpart of
+       * addTasklistMembers). Best-effort semantics at the caller, same as every
+       * other write here.
+       */
+      async addTaskMembers(taskGuid, members) {
+        const label = `addTaskMembers(${taskGuid})`;
+        try {
+          await this.#request(
+            {
+              method: "POST",
+              url: `${TASK_V2_BASE}/tasks/${encodeURIComponent(taskGuid)}/add_members`,
+              params: { user_id_type: "open_id" },
+              data: { members }
+            },
+            label
+          );
+        } catch (err2) {
+          wrapErr(label, err2);
+        }
+      }
+      /**
+       * task_handle v5: reschedule (or set) the task due. ms-epoch string per
+       * task v2 `due.timestamp`; same patch semantics as complete()/reopen().
+       */
+      async patchDue(taskGuid, due) {
+        await this.#patchTask(taskGuid, { due }, ["due"]);
+      }
     };
   }
 });
@@ -127416,6 +127480,9 @@ function repoLooksGitLab(urlOrSlug) {
 function botUsesGitLab(bot) {
   return bot.repos.some((repo) => repoLooksGitLab(repo.url ?? repo.slug));
 }
+function botUsesGitHub(bot) {
+  return bot.repos.some((repo) => !repoLooksGitLab(repo.url ?? repo.slug));
+}
 function addCliRequirement(requirements, input) {
   const existing = requirements.get(`cli:${input.command}`);
   if (existing) {
@@ -127499,6 +127566,16 @@ function runtimeRequirementsForBots(bots) {
         });
       }
     }
+    if (botUsesGitHub(bot)) {
+      addCliRequirement(requirements, {
+        command: "gh",
+        label: "GitHub CLI",
+        severity: "optional",
+        botIds: [bot.id],
+        reason: "Only needed when an agent uses GitHub-specific actions such as PRs, issues, or releases.",
+        installHint: "Install gh only for bots that need GitHub-specific workflow commands."
+      });
+    }
     if (botUsesGitLab(bot)) {
       addCliRequirement(requirements, {
         command: "glab",

package/dist/main.js

@@ -114958,6 +114958,13 @@ function renderStateContract(stateFilePath) {
     "- \u9700\u8981\u8986\u76D6\u5361\u7247\u6B63\u6587:status=ready + last_message(\u4E0D\u5199\u65F6\u6B63\u6587=\u7B54\u6848\u901A\u9053\u5185\u5BB9);dev_url/mr_url \u7B49\u4E1A\u52A1\u5B57\u6BB5\u53EF\u81EA\u7531\u5199\u5165,\u4F46 bridge \u4E0D\u611F\u77E5\u5176\u542B\u4E49,\u8981\u8BA9\u7528\u6237\u770B\u5230\u5C31\u5199\u8FDB\u6B63\u6587\u3002",
     "- \u9700\u8981\u5728\u7EC8\u6001\u5361\u4E0A @ \u4EBA:response_surface \u5199 `{post:{mentions:[{user_id}]}}`;\u8FD9\u53EA\u662F\u89C6\u89C9\u63D0\u793A,\u8981 peer bot \u6D88\u8D39\u6B63\u6587\u5FC5\u987B\u8D70 handoffs \u6216\u53E6\u53D1\u771F\u5B9E post(\u5361\u7247\u5BF9 agent \u4E0D\u53EF\u8BFB)\u3002",
     "- \u4EA4\u63A5\u7ED9 peer bot:handoffs(\u6700\u591A 3 \u6761 `{to, text}`,to \u5199 peer-bots \u540D\u518C\u91CC\u7684\u540D\u5B57)\u3002bridge \u66FF\u4F60\u53D1\u4E00\u6761\u5E26\u771F\u5B9E at \u6807\u7B7E\u7684 post \u7559\u75D5,\u540C\u6865\u8FDB\u7A0B\u5185\u7684 peer \u8FD8\u4F1A\u88AB**\u672C\u5730\u76F4\u9012**\u7ACB\u5373\u5524\u9192\u2014\u2014\u6BD4\u81EA\u5DF1\u7528 lark-cli \u53D1 post \u66F4\u5FEB\u66F4\u53EF\u9760\u3002text \u5FC5\u987B\u81EA\u5305\u542B:\u5BF9\u65B9\u53EA\u770B\u5F97\u5230\u8FD9\u6761\u6587\u672C,\u80CC\u666F\u3001\u8981\u505A\u4EC0\u4E48\u3001\u671F\u671B\u4EA7\u51FA\u90FD\u5199\u6E05\u695A\u3002",
+    "- **\u4EFB\u52A1\u5361(\u4E94\u4FE1\u53F7\u59D4\u6258\u5951\u7EA6,\u503C\u5F97\u8FFD\u8E2A\u7684\u6D3B\u5FC5\u7528)**:\u5224\u65AD\u6807\u51C6\u2014\u2014\u4E09\u4E2A\u6708\u540E\u590D\u76D8\u4F1A\u627E\u5B83\u3001\u6216\u6267\u884C\u8DE8\u8D8A\u672C\u8F6E\u5BF9\u8BDD(\u8981\u8DD1\u5F88\u4E45/\u7B49\u5916\u90E8/\u5206\u9636\u6BB5)\u2192 \u5199 task_handle\u3002\u4E00\u95EE\u4E00\u7B54\u804A\u5B8C\u5C31\u5B8C\u7684**\u4E0D\u5EFA\u5361**\u3002",
+    "  - \u63A5\u4E86:`task_handle: {create: {summary, due?}}`\u2014\u2014bridge \u81EA\u52A8\u5EFA\u5361\u3001\u628A\u8BDD\u9898\u56DE\u94FE\u5199\u8FDB\u4EFB\u52A1\u63CF\u8FF0\u3001\u628A\u53D1\u8D77\u4EBA\u52A0\u8FDB\u5173\u6CE8\u5217\u8868,\u5E76\u7ED1\u5B9A\u672C\u8BDD\u9898\u3002\u5DF2\u6709\u4EFB\u52A1\u5219\u7528 `{guid}` \u8BA4\u9886\u3002",
+    '  - \u8FDB\u5C55:`{note: "\u4E00\u53E5\u8BDD\u91CC\u7A0B\u7891"}` \u53EA\u5728\u5B9E\u8D28\u8FDB\u5C55\u65F6\u5199(\u9636\u6BB5\u7ED3\u8BBA/\u5173\u952E\u8F6C\u6298),bridge \u843D\u5230\u4EFB\u52A1\u4FA7;\u4E0D\u8981\u6BCF\u8F6E\u90FD\u5199\u3002',
+    '  - \u6539\u671F:`{due: "<ISO \u6216 YYYY-MM-DD>", due_reason: "\u4E00\u53E5\u539F\u56E0"}`\u2014\u2014\u5EF6\u671F\u5FC5\u987B\u5E26\u539F\u56E0,bridge \u4F1A\u6539\u5361\u4E0A\u622A\u6B62\u5E76\u8BC4\u8BBA\u8BF4\u660E\u3002',
+    "  - \u5B8C\u6210:`{done: true, note: ...}` \u4EA4\u4ED8\u8F6E\u624D\u5199;\u5931\u8D25\u8BA9\u4EFB\u52A1\u4FDD\u6301 open\u3002",
+    '  - \u963B\u585E:`{blocked: "\u5361\u5728\u54EA\u3001\u9700\u8981\u4EBA\u505A\u4EC0\u4E48"}`\u2014\u2014bridge \u843D\u4EFB\u52A1\u8BC4\u8BBA,\u5173\u6CE8\u4EBA\u4F1A\u6536\u5230\u901A\u77E5;\u540C\u65F6\u5728\u6B63\u6587\u7528 choices \u628A\u51B3\u5B9A\u6536\u655B\u6210\u9009\u9879\u3002',
+    "  - \u4EA4\u4ED8\u53CC\u6307\u9488:\u7ED3\u8BBA\u62A5\u544A\u5148\u7528 lark-cli \u5BFC\u6210**\u98DE\u4E66\u6587\u6863**,\u56DE\u590D\u548C\u4EFB\u52A1\u8BC4\u8BBA\u91CC doc \u94FE\u63A5\u5728\u524D\u3001\u672C\u5730\u7EDD\u5BF9\u8DEF\u5F84\u5728\u540E(\u672C\u5730\u6587\u4EF6\u662F\u53D6\u8BC1\u771F\u76F8,doc \u662F\u7ED9\u4EBA\u770B\u7684\u5F62\u6001)\u3002",
     "",
     "\u8FB9\u754C\u4E0E\u8D23\u4EFB:",
     "- **\u7EDD\u4E0D\u81EA\u5DF1 PATCH/PUT bridge \u7BA1\u7406\u7684\u5361\u7247/post** \u2014\u2014 \u7F51\u7EDC\u66F4\u65B0\u662F bridge \u7684\u6D3B,\u81EA\u5DF1\u6539\u4F1A\u548C\u5361\u7247 finalize\u3001\u6309\u94AE\u56DE\u4F20\u3001\u5D29\u6E83\u6062\u590D\u51B2\u7A81\u3002",
@@ -114970,7 +114977,7 @@ function renderContractAnchor(stateFilePath) {
   const stateTarget = stateFilePath ? `\`${stateFilePath}\`` : "\u5DE5\u4F5C\u76EE\u5F55\u91CC\u7684 `.larkway/state.json`";
   return [
     "<contract-anchor>",
-    `\u5951\u7EA6\u540C\u672C\u8BDD\u9898\u9996\u8F6E\u6CE8\u5165,\u672A\u53D8\u5316:\u7ED9\u7528\u6237\u770B\u7684\u7B54\u6848\u6B63\u6587\u5305\u5728\u72EC\u7ACB\u884C marker \`${ANSWER_BEGIN_MARKER}\` / \`${ANSWER_END_MARKER}\` \u4E4B\u95F4\u8F93\u51FA;\u7ED3\u8BBA\u4E00\u6210\u5F62\u5C31\u5148\u6D41\u51FA\u7B54\u6848\u3002\u7EAF\u6587\u5B57\u56DE\u7B54\u4E0D\u7528\u5199 state.json;\u5931\u8D25/\u7B49\u8865\u5145/choices/\u56FE\u6587\u6DF7\u6392/handoffs \u4EA4\u63A5\u65F6\u624D\u5199 ${stateTarget}(\u539F\u5B50\u5199 + \u5237\u65B0 updated_at)\u3002\u505A\u5B8C\u5E72\u51C0\u9000\u51FA\u8FDB\u7A0B\u3002`,
+    `\u5951\u7EA6\u540C\u672C\u8BDD\u9898\u9996\u8F6E\u6CE8\u5165,\u672A\u53D8\u5316:\u7ED9\u7528\u6237\u770B\u7684\u7B54\u6848\u6B63\u6587\u5305\u5728\u72EC\u7ACB\u884C marker \`${ANSWER_BEGIN_MARKER}\` / \`${ANSWER_END_MARKER}\` \u4E4B\u95F4\u8F93\u51FA;\u7ED3\u8BBA\u4E00\u6210\u5F62\u5C31\u5148\u6D41\u51FA\u7B54\u6848\u3002\u7EAF\u6587\u5B57\u56DE\u7B54\u4E0D\u7528\u5199 state.json;\u5931\u8D25/\u7B49\u8865\u5145/choices/\u56FE\u6587\u6DF7\u6392/handoffs \u4EA4\u63A5/task_handle \u4EFB\u52A1\u4FE1\u53F7(\u5EFA\u5361/\u91CC\u7A0B\u7891/\u6539\u671F/\u963B\u585E/\u4EA4\u4ED8)\u65F6\u624D\u5199 ${stateTarget}(\u539F\u5B50\u5199 + \u5237\u65B0 updated_at)\u3002\u505A\u5B8C\u5E72\u51C0\u9000\u51FA\u8FDB\u7A0B\u3002`,
     "</contract-anchor>"
   ];
 }
@@ -115424,7 +115431,7 @@ async function renderPrompt(input) {
       `    lark-cli docs +get <doc-url>${profileFlag}`,
       "- \u53D6\u672C\u6761\u6D88\u606F\u7684\u9644\u4EF6/\u5185\u8054\u56FE(post \u5185\u8054\u56FE\u4E0D\u5728\u4E0A\u9762 attachments/images \u91CC)\u3001\u62C9\u8BDD\u9898\u5386\u53F2:",
       attachmentHelpLine,
-      "- glab / gh / git API",
+      "- gh / glab / git API",
       "- pnpm / npm",
       "",
       chatHistoryFirst ? "**\u91CD\u8981**:\u8FD9\u662F\u5355\u804A/\u7C98\u8FDE session \u573A\u666F,\u4E0A\u4E0B\u6587\u5386\u53F2\u7528\u4E0A\u9762\u7684 chat-messages-list \u62C9\u53D6;\u4E0D\u8981\u628A `thread_id` \u5F53\u4F5C\u53EF\u62C9\u53D6\u7684\u6D88\u606F id \u4F7F\u7528\u3002" : "**\u91CD\u8981**:`thread_id` \u5C31\u662F\u8BDD\u9898\u9996\u697C\u7684 message_id\u3002\u5982\u679C\u5F53\u524D\u6D88\u606F attachments/feishu_doc_links \u4E3A\u7A7A,\u8BF4\u660E\u8FD0\u8425\u628A\u7D20\u6750\u653E\u5728\u9996\u697C,**\u5148\u62C9\u9996\u697C\u770B\u8FD0\u8425\u539F\u59CB\u9700\u6C42**,\u518D\u51B3\u5B9A\u4E0B\u4E00\u6B65\u3002",
@@ -116921,7 +116928,26 @@ var StateFileSchema = external_exports.object({
    * 不要粘贴完整回复;bridge 侧仍有 sanitizeSummary 的机械截断兜底(见
    * src/tasklist/writeback.ts),但那只防"过长",不防"文不对题"。
    */
-  task_handle: external_exports.object({ guid: external_exports.string().min(1), done: external_exports.boolean().optional(), note: external_exports.string().optional() }).optional(),
+  /**
+   * v5 (BL-48, 五信号委托契约): `guid` becomes optional because `create` is the
+   * new way a task comes into existence — agent 自判「这个活值得追踪」时声明
+   * create,bridge 机械建卡(话题回链 + 发起人进关注列表)并自动认领。其余
+   * 新字段同样是声明式信号:`due`(+`due_reason`)= 改期/设期,`blocked` =
+   * 阻塞需要人(bridge 落任务评论,关注人收到推送)。全部按需、互不依赖;
+   * bridge 不判断该不该建卡/该不该改期 —— 判断永远在 agent 侧(薄通道)。
+   */
+  task_handle: external_exports.object({
+    guid: external_exports.string().min(1).optional(),
+    create: external_exports.object({
+      summary: external_exports.string().trim().min(1).max(500),
+      due: external_exports.string().trim().min(1).optional()
+    }).optional(),
+    due: external_exports.string().trim().min(1).optional(),
+    due_reason: external_exports.string().optional(),
+    blocked: external_exports.string().optional(),
+    done: external_exports.boolean().optional(),
+    note: external_exports.string().optional()
+  }).optional(),
   /**
    * Freshness signal for the handler's stale-guard (it compares this against a
    * pre-run snapshot to decide whether the bot rewrote state THIS turn).
@@ -118766,6 +118792,7 @@ stderr: ${stderr}`));
 var CORE_ALLOW_RULES = [
   "Bash(lark-cli *)",
   "Bash(git *)",
+  "Bash(gh *)",
   "Bash(glab *)",
   "Bash(lsof *)",
   "Bash(curl *)",
@@ -120150,7 +120177,45 @@ var BridgeHandler = class {
                 reason: rawReportedState === null ? "\u672C\u8F6E\u7ED3\u675F\u65F6\u672A\u8BFB\u53D6\u5230 state.json\u3002" : "\u672C\u8F6E state.json \u6CA1\u6709 fresh updated_at\uFF0C\u5DF2\u5FFD\u7565\u65E7\u72B6\u6001\u3002"
               });
             }
-            const claimedTaskGuid = reportedState?.task_handle?.guid;
+            const declaredTaskHandle = reportedState?.task_handle;
+            let bridgeCreatedTaskGuid;
+            if (declaredTaskHandle && (declaredTaskHandle.create || declaredTaskHandle.due || declaredTaskHandle.blocked) && this.deps.taskHandleDeclare && botId) {
+              try {
+                let topicLink;
+                if (declaredTaskHandle.create) {
+                  const direct = realTopicThreadId(parsed.raw.thread_id);
+                  if (direct) {
+                    topicLink = buildTopicDeepLink(parsed.chatId, direct);
+                  } else if (this.deps.messageLookup) {
+                    const refreshed = await this.deps.messageLookup.get(replyAnchorId, { refresh: true }).catch(() => void 0);
+                    const refreshedThreadId = realTopicThreadId(refreshed?.threadId);
+                    if (refreshedThreadId) {
+                      topicLink = buildTopicDeepLink(parsed.chatId, refreshedThreadId);
+                    }
+                  }
+                }
+                const result2 = await this.deps.taskHandleDeclare({
+                  botId,
+                  threadId,
+                  chatId: parsed.chatId,
+                  senderOpenId: parsed.senderOpenId || void 0,
+                  create: declaredTaskHandle.create,
+                  declaredGuid: declaredTaskHandle.guid,
+                  due: declaredTaskHandle.due,
+                  dueReason: declaredTaskHandle.due_reason,
+                  blocked: declaredTaskHandle.blocked,
+                  topicLink,
+                  chatLink: `https://applink.feishu.cn/client/chat/open?openChatId=${parsed.chatId}`
+                });
+                bridgeCreatedTaskGuid = result2?.createdGuid;
+                for (const line of result2?.outcomes ?? []) {
+                  await recordEvent({ status: "running", appendPath: "\u4EFB\u52A1\u4FE1\u53F7", reason: line });
+                }
+              } catch (err) {
+                console.warn("[bridge.handler] taskHandleDeclare hook failed (continuing):", err);
+              }
+            }
+            const claimedTaskGuid = bridgeCreatedTaskGuid ?? reportedState?.task_handle?.guid;
             if (claimedTaskGuid && this.deps.taskHandleClaim && botId) {
               try {
                 await this.deps.taskHandleClaim({
@@ -127630,6 +127695,9 @@ function repoLooksGitLab(urlOrSlug) {
 function botUsesGitLab(bot) {
   return bot.repos.some((repo) => repoLooksGitLab(repo.url ?? repo.slug));
 }
+function botUsesGitHub(bot) {
+  return bot.repos.some((repo) => !repoLooksGitLab(repo.url ?? repo.slug));
+}
 function addCliRequirement(requirements, input) {
   const existing = requirements.get(`cli:${input.command}`);
   if (existing) {
@@ -127713,6 +127781,16 @@ function runtimeRequirementsForBots(bots) {
         });
       }
     }
+    if (botUsesGitHub(bot)) {
+      addCliRequirement(requirements, {
+        command: "gh",
+        label: "GitHub CLI",
+        severity: "optional",
+        botIds: [bot.id],
+        reason: "Only needed when an agent uses GitHub-specific actions such as PRs, issues, or releases.",
+        installHint: "Install gh only for bots that need GitHub-specific workflow commands."
+      });
+    }
     if (botUsesGitLab(bot)) {
       addCliRequirement(requirements, {
         command: "glab",
@@ -128362,6 +128440,70 @@ var TaskListClient = class {
       wrapErr(label, err);
     }
   }
+  /**
+   * task_handle v5 (BL-48, 声明式建卡): create a task under this bot's app
+   * identity. `due.timestamp` is ms-epoch string per task v2; `members` lets
+   * the create carry the originator as follower in one call; `tasklists`
+   * attaches the task to the bot's configured list when present. Response
+   * shape mirrors createTasklist's envelope (`data.task.guid`).
+   */
+  async createTask(input) {
+    const label = `createTask(${input.summary.slice(0, 30)})`;
+    let resp;
+    try {
+      resp = await this.#request(
+        {
+          method: "POST",
+          url: `${TASK_V2_BASE}/tasks`,
+          params: { user_id_type: "open_id" },
+          data: {
+            summary: input.summary,
+            ...input.description ? { description: input.description } : {},
+            ...input.due ? { due: input.due } : {},
+            ...input.members && input.members.length > 0 ? { members: input.members } : {},
+            ...input.tasklists && input.tasklists.length > 0 ? { tasklists: input.tasklists } : {}
+          }
+        },
+        label
+      );
+    } catch (err) {
+      wrapErr(label, err);
+    }
+    const guid = resp.data?.task?.["guid"];
+    if (typeof guid !== "string" || guid.length === 0) {
+      throw new TaskApiError(`[tasklist.client] ${label} returned no guid`, {});
+    }
+    return { guid };
+  }
+  /**
+   * task_handle v5: add members (e.g. a late follower) to an existing TASK
+   * (`POST /tasks/:guid/add_members` — task-level counterpart of
+   * addTasklistMembers). Best-effort semantics at the caller, same as every
+   * other write here.
+   */
+  async addTaskMembers(taskGuid, members) {
+    const label = `addTaskMembers(${taskGuid})`;
+    try {
+      await this.#request(
+        {
+          method: "POST",
+          url: `${TASK_V2_BASE}/tasks/${encodeURIComponent(taskGuid)}/add_members`,
+          params: { user_id_type: "open_id" },
+          data: { members }
+        },
+        label
+      );
+    } catch (err) {
+      wrapErr(label, err);
+    }
+  }
+  /**
+   * task_handle v5: reschedule (or set) the task due. ms-epoch string per
+   * task v2 `due.timestamp`; same patch semantics as complete()/reopen().
+   */
+  async patchDue(taskGuid, due) {
+    await this.#patchTask(taskGuid, { due }, ["due"]);
+  }
 };
 function isNotFoundLikeRaw(err) {
   const rec = asRecord2(err);
@@ -128583,6 +128725,106 @@ async function applyAutoBindConfirmation(taskGuid, client) {
   }
 }
 
+// src/tasklist/declare.ts
+function parseDueInput(raw) {
+  const s = raw.trim();
+  if (/^\d{13}$/.test(s)) return { timestamp: s };
+  if (/^\d{10}$/.test(s)) return { timestamp: `${Number(s) * 1e3}` };
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+    const ms2 = Date.parse(`${s}T00:00:00`);
+    if (Number.isNaN(ms2)) return null;
+    return { timestamp: `${ms2}`, is_all_day: true };
+  }
+  const ms = Date.parse(s);
+  if (Number.isNaN(ms)) return null;
+  return { timestamp: `${ms}` };
+}
+function formatDueForComment(due) {
+  const d = new Date(Number(due.timestamp));
+  if (Number.isNaN(d.getTime())) return due.timestamp;
+  const pad = (n) => String(n).padStart(2, "0");
+  const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+  return due.is_all_day ? date : `${date} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+function renderCreateDescription(patch, botName) {
+  const lines = [];
+  if (patch.topicLink) {
+    lines.push(`\u8BDD\u9898\uFF1A${patch.topicLink}`);
+  } else if (patch.chatLink) {
+    lines.push(`\u8BDD\u9898\u6DF1\u94FE\u4E0D\u53EF\u7528\uFF08\u975E\u8BDD\u9898\u6D88\u606F\uFF09\uFF0C\u6240\u5728\u7FA4\uFF1A${patch.chatLink}`);
+  } else {
+    lines.push("\u8BDD\u9898\u6DF1\u94FE\u4E0D\u53EF\u7528\uFF08\u672A\u89E3\u6790\u5230\u8BDD\u9898/\u7FA4\u94FE\u63A5\uFF09");
+  }
+  lines.push(`\u7531 ${botName ?? patch.botId} \u521B\u5EFA \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  return lines.join("\n");
+}
+async function applyTaskHandleDeclarations(patch, deps) {
+  const outcomes = [];
+  let createdGuid;
+  if (patch.create) {
+    const existing = deps.store.get(patch.threadId);
+    if (existing) {
+      outcomes.push(`create \u8DF3\u8FC7\uFF1A\u8BDD\u9898\u5DF2\u8BA4\u9886\u4EFB\u52A1 ${existing.taskGuid}`);
+    } else {
+      try {
+        const due = patch.create.due ? parseDueInput(patch.create.due) : null;
+        if (patch.create.due && !due) {
+          outcomes.push(`create.due "${patch.create.due}" \u65E0\u6CD5\u89E3\u6790\uFF0C\u4EFB\u52A1\u5C06\u65E0\u622A\u6B62\u65F6\u95F4`);
+        }
+        const members = patch.senderOpenId ? [{ id: patch.senderOpenId, type: "user", role: "follower" }] : [];
+        const { guid } = await deps.client.createTask({
+          summary: patch.create.summary,
+          description: renderCreateDescription(patch, deps.botName),
+          ...due ? { due } : {},
+          ...members.length > 0 ? { members } : {},
+          ...deps.tasklistGuid ? { tasklists: [{ tasklist_guid: deps.tasklistGuid }] } : {}
+        });
+        createdGuid = guid;
+        outcomes.push(
+          `\u5DF2\u5EFA\u4EFB\u52A1 ${guid}\uFF08${patch.create.summary.slice(0, 40)}${due ? ` \xB7 \u622A\u6B62 ${formatDueForComment(due)}` : ""}${patch.senderOpenId ? " \xB7 \u53D1\u8D77\u4EBA\u5DF2\u52A0\u5173\u6CE8" : ""}${patch.topicLink ? "" : "\uFF0C\u8BDD\u9898\u6DF1\u94FE\u7F3A\u5931\u5DF2\u964D\u7EA7\u4E3A\u7FA4\u94FE\u63A5"}\uFF09`
+        );
+      } catch (err) {
+        outcomes.push(`create \u5931\u8D25\uFF08\u672C\u8F6E\u8DF3\u8FC7\uFF0C\u4E0D\u5F71\u54CD\u4EA4\u4ED8\uFF09\uFF1A${String(err.message ?? err)}`);
+      }
+    }
+  }
+  const targetGuid = patch.due || patch.blocked ? createdGuid ?? deps.store.get(patch.threadId)?.taskGuid ?? patch.declaredGuid : void 0;
+  if (patch.due) {
+    if (!targetGuid) {
+      outcomes.push("due \u58F0\u660E\u88AB\u5FFD\u7565\uFF1A\u672C\u8BDD\u9898\u6CA1\u6709\u5DF2\u8BA4\u9886/\u65B0\u5EFA\u7684\u4EFB\u52A1");
+    } else {
+      const due = parseDueInput(patch.due);
+      if (!due) {
+        outcomes.push(`due "${patch.due}" \u65E0\u6CD5\u89E3\u6790\uFF0C\u672A\u6539\u671F`);
+      } else {
+        try {
+          await deps.client.patchDue(targetGuid, due);
+          const line = `\u23F0 \u622A\u6B62\u6539\u4E3A ${formatDueForComment(due)}${patch.dueReason ? `\uFF1A${patch.dueReason}` : ""}`;
+          await deps.client.addComment(targetGuid, line).catch((err) => {
+            console.warn(`[tasklist.declare] due comment failed (due itself applied):`, err);
+          });
+          outcomes.push(`\u5DF2\u6539\u671F ${formatDueForComment(due)}${patch.dueReason ? `\uFF08${patch.dueReason}\uFF09` : ""}`);
+        } catch (err) {
+          outcomes.push(`\u6539\u671F\u5931\u8D25\uFF1A${String(err.message ?? err)}`);
+        }
+      }
+    }
+  }
+  if (patch.blocked) {
+    if (!targetGuid) {
+      outcomes.push("blocked \u58F0\u660E\u88AB\u5FFD\u7565\uFF1A\u672C\u8BDD\u9898\u6CA1\u6709\u5DF2\u8BA4\u9886/\u65B0\u5EFA\u7684\u4EFB\u52A1");
+    } else {
+      try {
+        await deps.client.addComment(targetGuid, `\u{1F6A7} \u963B\u585E\uFF0C\u9700\u8981\u4EBA\u5904\u7406\uFF1A${patch.blocked}`);
+        outcomes.push("\u963B\u585E\u5DF2\u843D\u4EFB\u52A1\u8BC4\u8BBA\uFF08\u5173\u6CE8\u4EBA\u5C06\u6536\u5230\u901A\u77E5\uFF09");
+      } catch (err) {
+        outcomes.push(`\u963B\u585E\u8BC4\u8BBA\u5931\u8D25\uFF1A${String(err.message ?? err)}`);
+      }
+    }
+  }
+  return { createdGuid, outcomes };
+}
+
 // src/tasklist/commentPoller.ts
 var DEFAULT_INTERVAL_MS = 6e4;
 var DEFAULT_JITTER_MS = 1e4;
@@ -130159,6 +130401,7 @@ async function runV2Mode({
     let effectiveTaskHandleTasklistGuid;
     let taskHandleLifecycle;
     let taskHandleClaim;
+    let taskHandleDeclare;
     let taskHandleClaimedLookup;
     let taskHandleClaimGuidLookup;
     let taskGuidClaimedByOtherBot;
@@ -130194,6 +130437,12 @@ async function runV2Mode({
         const taskHandleStore = await TaskHandleStore.load(resolveTaskHandlesPath(bot.id));
         allTaskHandleStores.push({ botId: bot.id, store: taskHandleStore });
         taskHandleLifecycle = (patch) => applyTaskHandleWriteback(patch, { store: taskHandleStore, client: taskListClient });
+        taskHandleDeclare = (patch) => applyTaskHandleDeclarations(patch, {
+          store: taskHandleStore,
+          client: taskListClient,
+          tasklistGuid: effectiveTaskHandleTasklistGuid,
+          botName: bot.name
+        });
         taskHandleClaim = async (patch) => {
           const result = await taskHandleStore.claim(patch);
           if (!result.claimed) {
@@ -130457,6 +130706,7 @@ async function runV2Mode({
       },
       taskHandleLifecycle,
       taskHandleClaim,
+      taskHandleDeclare,
       taskHandleClaimedLookup,
       taskHandleClaimGuidLookup,
       taskGuidClaimedByOtherBot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkway",
-  "version": "0.3.57",
+  "version": "0.3.59",
   "description": "Thin bridge: Feishu thread to local Claude Code CLI",
   "license": "MIT",
   "author": "Chuck Wu (chuckwu0)",
@@ -17,7 +17,7 @@
   },
   "type": "module",
   "bin": {
-    "larkway": "bin/larkway"
+    "larkway": "bin/larkway.mjs"
   },
   "scripts": {
     "start": "tsx src/main.ts",
@@ -54,7 +54,7 @@
   },
   "files": [
     "dist/",
-    "bin/larkway",
+    "bin/larkway.mjs",
     "README.md"
   ]
 }

package/bin/larkway

@@ -1,25 +0,0 @@
-#!/usr/bin/env bash
-# larkway CLI shim — resolves the package root from this script's own location
-# so it works whether invoked via `bin/larkway`, an absolute path, or a symlink
-# on PATH (e.g. after `npm i -g`).
-#
-# Startup priority:
-#   1. dist/cli/index.js exists  → `node dist/cli/index.js` (installed package / post-build)
-#   2. otherwise                 → `npx tsx src/cli/index.ts` (fresh clone dev mode, no build)
-set -euo pipefail
-SOURCE="${BASH_SOURCE[0]}"
-while [ -h "$SOURCE" ]; do
-  DIR="$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
-  SOURCE="$(readlink "$SOURCE")"
-  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-REPO_ROOT="$(cd -P "$(dirname "$SOURCE")/.." >/dev/null 2>&1 && pwd)"
-
-DIST_ENTRY="$REPO_ROOT/dist/cli/index.js"
-
-if [ -f "$DIST_ENTRY" ]; then
-  exec node "$DIST_ENTRY" "$@"
-else
-  # Dev fallback: run TypeScript source directly via tsx.
-  exec npx tsx "$REPO_ROOT/src/cli/index.ts" "$@"
-fi