larkway 0.3.33 → 0.3.34

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.33**
+**Current release: v0.3.34**
 
 ---
 
@@ -124,6 +124,32 @@ Secrets live only in `~/.larkway/.env` (mode 0600). Config and memory contain no
 - **Session continuity** — every Feishu thread maps to a persistent `session_id`; the agent remembers what it did in prior turns
 - **Agent Workspace** — per-thread git worktrees; the agent can run multiple threads concurrently without git conflicts
 - **Codex runtime pre-checks** — `larkway doctor` validates Codex state directory writability before start
+- **Topic ↔ Feishu task handle** — turn a topic into a Feishu task and the agent claims it, then keeps its lifecycle (done/failed/reopened, stalled, handed off, overdue) in sync automatically — see below
+
+---
+
+## Task handle: topic ↔ Feishu task (optional)
+
+Turn a Feishu topic into a task and the agent will claim it, then keep its whole
+lifecycle in sync on its own — completion, failure/reopen, stall wake-ups,
+handoff-break detection between collaborating bots, and overdue nudges — no
+extra prompting needed.
+
+```bash
+# 1. In the Feishu Task Center, create a tasklist yourself (any name).
+# 2. Adopt it — adds your bot(s) as editors, ownership stays yours:
+larkway tasklist-init --adopt "<tasklist name>" --team <bot1,bot2,…>
+# 3. Right-click "转任务" (convert to task) on any topic message in a group
+#    the bot is in — it auto-claims within about a minute, no further chat needed.
+```
+
+You can also just tell Claude Code / Codex: "set up Agent Team for me" — running
+`larkway tasklist-init` with no arguments already does the right thing for
+every bot configured on this machine.
+
+`larkway doctor` reports each bot's task-handle status (configured/scope
+health) as part of its regular checks. Full design, configuration knobs, and
+platform-fact writeups: [docs/task-handle.md](docs/task-handle.md).
 
 ---
 
@@ -162,6 +188,7 @@ Secrets live only in `~/.larkway/.env` (mode 0600). Config and memory contain no
 | Agent workspace runtime (v0.3) | [docs/agent-workspace.md](docs/agent-workspace.md) |
 | Version history and semver mapping | [docs/versioning.md](docs/versioning.md) |
 | Bridge ↔ Agent prompt contract | [docs/prompt-contract.md](docs/prompt-contract.md) |
+| Topic ↔ Feishu task handle (design + config) | [docs/task-handle.md](docs/task-handle.md) |
 | Bot config + memory templates | [bots-examples/](bots-examples/) |
 
 ---

package/README.zh.md

@@ -8,7 +8,7 @@
 
 你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
 
-**当前版本：v0.3.33**
+**当前版本：v0.3.34**
 
 ---
 
@@ -124,6 +124,29 @@ Larkway 不注入 `ANTHROPIC_API_KEY` 或任何其他 API key。子进程继承
 - **Session 续接** —— 每个飞书话题映射到持久 `session_id`，agent 记得之前做了什么
 - **Agent Workspace** —— 每个话题独立 git worktree，agent 并发处理多个话题不冲突
 - **Codex 运行时预检** —— `larkway doctor` 在启动前验证 Codex 状态目录可写
+- **话题↔飞书任务句柄** —— 把话题转成飞书任务，agent 自动认领并自己维护整个生命周期（完成/失败重开/停滞唤醒/协作断链检测/过期催更）——详见下方
+
+---
+
+## 话题↔飞书任务句柄（可选功能）
+
+把一个飞书话题转成任务，agent 会自动认领它，然后自己维护整个生命周期——完成、
+失败/reopen、停滞唤醒、协作 bot 之间的断链检测、任务过期催更——不需要额外提示。
+
+```bash
+# 1. 先在飞书任务中心自己手动建一个清单（名字随便起）
+# 2. adopt 它 —— 把你的 bot 加为 editor，所有权还是归你自己：
+larkway tasklist-init --adopt "<清单名>" --team <bot1,bot2,…>
+# 3. 在 bot 所在的群里，对任意话题消息右键「转任务」进这个清单——
+#    大约一分钟内自动认领，不用再聊。
+```
+
+也可以直接对 Claude Code / Codex 说：帮我配置 Agent Team —— 不带任何参数跑
+`larkway tasklist-init` 就会自动对本机所有已配置的 bot 做对的事。
+
+`larkway doctor` 的常规检查里会包含每个 bot 的话题↔任务句柄配置状态（是否配置、
+scope 是否健康）。完整设计、配置项、平台事实排查记录见：
+[docs/task-handle.md](docs/task-handle.md)。
 
 ---
 
@@ -162,6 +185,7 @@ Larkway 不注入 `ANTHROPIC_API_KEY` 或任何其他 API key。子进程继承
 | Agent workspace 运行时（v0.3） | [docs/agent-workspace.md](docs/agent-workspace.md) |
 | 版本历史与 semver 映射 | [docs/versioning.md](docs/versioning.md) |
 | Bridge ↔ Agent Prompt 契约 | [docs/prompt-contract.md](docs/prompt-contract.md) |
+| 话题↔飞书任务句柄（设计 + 配置） | [docs/task-handle.md](docs/task-handle.md) |
 | Bot 配置 + memory 模板 | [bots-examples/](bots-examples/) |
 
 ---