larkway 0.3.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chuck Wu (chuckwu0)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# Larkway
+
+> Turn your Claude Code or Codex subscription into a Feishu (Lark) agent your whole team can @-mention.
+
+[中文版](README.zh.md)
+
+---
+
+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.6**
+
+---
+
+## Why
+
+The engineers on your team know how a feature is actually implemented. Everyone else has to ask them. That friction compounds: a data analyst wondering whether a metric counts deleted records, a PM asking which API endpoint powers a chart, a QA engineer trying to reproduce a bug without context.
+
+A generic AI assistant cannot answer these questions reliably — it has no access to your code. A bot that runs Claude Code or Codex against your real repository can.
+
+Larkway makes that bot trivially installable and persistent: one `larkway start` on an always-on machine, one `@mention` in any Feishu thread, and your team has a self-serve answer to "how is this actually implemented."
+
+---
+
+## How it works
+
+```
+Feishu thread
+  │  @bot "how does the retention metric handle deleted users?"
+  │
+  ▼  WebSocket long-connection (outbound only, no public endpoint needed)
+larkway bridge
+  │  spawns subprocess  ──►  claude --resume <session_id> -p "<prompt>"
+  │                          (or: codex ...)
+  │
+  ▼  stream-json (NDJSON)
+lark.card                ◄──  agent reads repo, runs bash, edits files,
+  │  throttled PATCH           opens MR, starts dev preview
+  │
+  ▼
+Feishu thread
+     "retention.ts line 47: deleted_at IS NULL filter is applied before
+      the aggregation window. Deleted users are excluded."
+```
+
+**What Larkway does** (and only this):
+
+- Feishu long-connection subscriber (inbound events)
+- Subprocess lifecycle: spawn, stream-json parse, session-ID persistence
+- Feishu card: throttled real-time PATCH as the agent streams output
+- Session KV: `thread_id → session_id` so follow-up messages resume context
+- Idle GC: worktree housekeeping
+
+**What Larkway does NOT do** — the agent decides everything else:
+
+- No GitLab/GitHub API calls (the agent runs `glab`/`gh` 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
+
+This boundary is intentional. Workflow changes go into your repository's agent guides, not into Larkway.
+
+---
+
+## Quick start
+
+> **Note:** npm publish is pending. Until then, install straight from the GitHub repo (the `prepack` build runs on install):
+>
+> ```bash
+> npm i -g github:chuckwu0/larkway
+> ```
+>
+> Once published: `npm i -g larkway`
+
+```bash
+# 1. Check your environment
+larkway doctor          # lists missing dependencies; --fix auto-installs some
+
+# 2. Register a Feishu app and configure your first bot
+larkway init            # CLI wizard: scan QR code → name the bot → pick a backend
+
+# 3. Start the bridge
+larkway start           # long-running; runs in background, logs to ~/.larkway/logs/
+
+# 4. Add the bot to a Feishu group
+#    Group settings → Bots → Add bot → pick yours → @-mention it
+```
+
+---
+
+## Backends
+
+| Backend | CLI | Auth | Billing |
+|---|---|---|---|
+| **Claude Code** | `claude` | Local subscription login (`~/.claude/.credentials.json`) | Your existing Claude subscription — no per-token charges |
+| **Codex** | `codex` | `codex login` | Your existing Codex subscription — no per-token charges |
+
+Larkway never injects `ANTHROPIC_API_KEY` or any other API key. The subprocess inherits your local login state. If you switch to API-key mode, that is a deliberate opt-in in `src/claude/runner.ts`.
+
+---
+
+## Defining a bot (three layers)
+
+| Layer | What it is | Where it lives |
+|---|---|---|
+| **L1 permissions** | App credentials, repo path, allowed Feishu users/groups, token scopes | `~/.larkway/bots/<id>.yaml` |
+| **L2 identity memory** | "Who I am, what I must not do, where to find the workflow" (thin) | `~/.larkway/bots/<id>.memory.md` |
+| **L3 workflow** | State machine, gates, commands — the actual job | **Your business repo**: `AGENTS.md`, `CLAUDE.md`, `.agents/skills/`, `.claude/skills/` |
+
+Secrets live only in `~/.larkway/.env` (mode 0600). Config and memory contain no secrets and are safe to share via the central config library.
+
+---
+
+## Features
+
+- **Multiple bots on one bridge** — a read-only Q&A bot and a write-capable engineering bot can share the same process, each with its own L1/L2/L3 definition
+- **Web UI** — `larkway ui` opens a local management dashboard (127.0.0.1 + token); create bots, edit memory, watch live logs
+- **Central config library** — `larkway promote <id>` pushes bot config (no secrets) to a shared git repository so teammates can `larkway sync` and discover bots; the library stores config, not deployment state
+- **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
+
+---
+
+## Requirements
+
+- **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
+- **`glab` + `git`** — for bots that open MRs (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
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `larkway` | Open web UI (recommended for first-time setup) |
+| `larkway init` | CLI wizard: register Feishu app + configure first bot |
+| `larkway doctor [--fix]` | Environment check; auto-fix where possible |
+| `larkway start \| stop \| status \| logs` | Bridge lifecycle (`logs --follow` for streaming) |
+| `larkway bot add \| list \| edit` | Manage bots |
+| `larkway memory edit <id>` | Edit L2 identity memory |
+| `larkway perms <id>` | Adjust L1 permissions |
+| `larkway ui` | Start local web management UI |
+| `larkway central set \| show \| unset` | Connect/disconnect central config library |
+| `larkway promote <id>` | Push bot config (no secrets) to central library |
+| `larkway sync` | Pull bot configs from central library |
+| `larkway update` | Upgrade Larkway and restart bridge |
+
+---
+
+## Documentation
+
+| Topic | File |
+|---|---|
+| Architecture diagram + module I/O | [docs/architecture.md](docs/architecture.md) |
+| Agent capability model (L0–L3) | [docs/agent-capability-model.md](docs/agent-capability-model.md) |
+| 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) |
+| Bot config + memory templates | [bots-examples/](bots-examples/) |
+
+---
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,169 @@
+# Larkway
+
+> 把你的 Claude Code 或 Codex 订阅变成全团队都能 @ 的飞书 Agent。
+
+[English](README.md)
+
+---
+
+你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
+
+**当前版本：v0.3.6**
+
+---
+
+## 背景
+
+工程师知道某个功能是怎么实现的，其他人不知道，只能问。这个摩擦不断叠加：数据分析师想弄清楚某个指标有没有过滤已删除的记录，PM 想知道某个图表背后调的是哪个 API，QA 工程师在没有上下文的情况下试图复现一个 bug。
+
+通用 AI 助手无法可靠地回答这些问题——它访问不到你的代码。而一个在你真实仓库里运行 Claude Code 或 Codex 的 bot 可以。
+
+Larkway 让这个 bot 的安装和持久运行变得简单：在一台常开的机器上 `larkway start`，在任何飞书话题里 @-mention，团队就有了一个自助回答"这个到底是怎么实现的"的入口。
+
+---
+
+## 工作原理
+
+```
+飞书话题
+  │  @bot "留存指标是怎么处理已删除用户的？"
+  │
+  ▼  WebSocket 长连接（纯出网，不需要公网端口）
+larkway bridge
+  │  spawn 子进程  ──►  claude --resume <session_id> -p "<prompt>"
+  │                     （或：codex ...）
+  │
+  ▼  stream-json (NDJSON)
+lark.card              ◄──  agent 读仓库、跑 bash、改代码、
+  │  节流 PATCH               开 MR、起 dev 预览
+  │
+  ▼
+飞书话题
+     "retention.ts 第 47 行：deleted_at IS NULL 过滤在聚合窗口之前
+      生效，已删除用户被排除在外。"
+```
+
+**Larkway 做的事**（仅此而已）：
+
+- 飞书长连接订阅（接收入站事件）
+- 子进程生命周期：spawn、stream-json 解析、session ID 持久化
+- 飞书卡片：agent 流式输出时节流 PATCH 实时更新
+- Session KV：`thread_id → session_id`，后续消息自动续接上下文
+- 空闲 GC：worktree 清理
+
+**Larkway 不做的事**——agent 自己决定：
+
+- 不调 GitLab/GitHub API（agent 自己跑 `glab`/`gh`）
+- 不建 worktree（agent 自己跑 `git worktree add`）
+- 不管 dev server（agent 自己启动）
+- 不做流程编排——agent 读你的 `AGENTS.md` / `CLAUDE.md` / skills，自主规划步骤
+
+这个边界是刻意设计的。流程变化进你仓库的 agent guide，不进 Larkway。
+
+---
+
+## 快速上手
+
+> **注意：** npm 包尚未发布。现阶段直接从 GitHub 仓库安装（`prepack` 会在安装时自动构建）：
+>
+> ```bash
+> npm i -g github:chuckwu0/larkway
+> ```
+>
+> 发布后可直接：`npm i -g larkway`
+
+```bash
+# 1. 检查环境
+larkway doctor          # 列出缺失的依赖；--fix 自动修复部分问题
+
+# 2. 注册飞书 app + 配置第一个 bot
+larkway init            # CLI 向导：扫码 → 命名 bot → 选 backend
+
+# 3. 启动 bridge
+larkway start           # 长驻进程，后台运行，日志写入 ~/.larkway/logs/
+
+# 4. 把 bot 加到飞书群
+#    群设置 → 群机器人 → 添加机器人 → 选你的 bot → @ 它提需求
+```
+
+---
+
+## Backend 选择
+
+| Backend | CLI | 鉴权方式 | 计费方式 |
+|---|---|---|---|
+| **Claude Code** | `claude` | 本地订阅登录态（`~/.claude/.credentials.json`） | 现有 Claude 订阅，不按 token 扣费 |
+| **Codex** | `codex` | `codex login` | 现有 Codex 订阅，不按 token 扣费 |
+
+Larkway 不注入 `ANTHROPIC_API_KEY` 或任何其他 API key。子进程继承你的本地登录态。如需切换到 API key 模式，需在 `src/claude/runner.ts` 显式开启。
+
+---
+
+## 定义一个 bot（三层）
+
+| 层 | 是什么 | 放在哪 |
+|---|---|---|
+| **L1 权限** | App 凭据、repo 路径、允许的飞书用户/群、token scope | `~/.larkway/bots/<id>.yaml` |
+| **L2 身份 memory** | "我是谁、禁止什么、工作流指针"（薄） | `~/.larkway/bots/<id>.memory.md` |
+| **L3 工作流** | 状态机、gate、命令——实际的工作内容 | **业务 repo**：`AGENTS.md`、`CLAUDE.md`、`.agents/skills/`、`.claude/skills/` |
+
+密钥只存在本机 `~/.larkway/.env`（权限 0600）。配置和 memory 不含密钥，可以安全地通过中心配置库共享。
+
+---
+
+## 功能
+
+- **一个 bridge 跑多个 bot** —— 只读答疑 bot 和有写权限的工程 bot 可以共用同一个进程，各自有独立的 L1/L2/L3 定义
+- **Web 管理面** —— `larkway ui` 打开本地管理后台（127.0.0.1 + token），可以建 bot、编辑 memory、查看实时日志
+- **中心配置库** —— `larkway promote <id>` 把 bot 配置（不含密钥）推送到共享 git 仓库，队友可以 `larkway sync` 发现和复用；库只存配置，不存部署状态
+- **Session 续接** —— 每个飞书话题映射到持久 `session_id`，agent 记得之前做了什么
+- **Agent Workspace** —— 每个话题独立 git worktree，agent 并发处理多个话题不冲突
+- **Codex 运行时预检** —— `larkway doctor` 在启动前验证 Codex 状态目录可写
+
+---
+
+## 前置要求
+
+- **Node.js 20+ LTS**
+- **Claude Code 或 Codex 订阅**，本地 CLI 已安装并登录
+- **`lark-cli`** —— 飞书长连接客户端和消息工具
+- **`glab` + `git`** —— 需要开 MR 的 bot 必须；只读 bot 可省
+- **一台常开的机器** —— bridge 必须持续运行才能接收飞书事件；经常休眠的笔记本会漏消息，小服务器或台式机更合适
+
+---
+
+## 命令速查
+
+| 命令 | 作用 |
+|---|---|
+| `larkway` | 打开 Web 管理面（首次配置推荐） |
+| `larkway init` | CLI 向导：注册飞书 app + 配置第一个 bot |
+| `larkway doctor [--fix]` | 环境检查，自动修复部分问题 |
+| `larkway start \| stop \| status \| logs` | Bridge 生命周期（`logs --follow` 实时流） |
+| `larkway bot add \| list \| edit` | 管理 bot |
+| `larkway memory edit <id>` | 编辑 L2 身份 memory |
+| `larkway perms <id>` | 调整 L1 权限 |
+| `larkway ui` | 启动本地 Web 管理面 |
+| `larkway central set \| show \| unset` | 连接/断开中心配置库 |
+| `larkway promote <id>` | 把 bot 配置（不含密钥）推送到中心库 |
+| `larkway sync` | 从中心库拉 bot 配置 |
+| `larkway update` | 升级 Larkway 并重启 bridge |
+
+---
+
+## 文档
+
+| 主题 | 文件 |
+|---|---|
+| 架构图 + 模块 I/O | [docs/architecture.md](docs/architecture.md) |
+| Agent 能力模型（L0–L3） | [docs/agent-capability-model.md](docs/agent-capability-model.md) |
+| 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) |
+| Bot 配置 + memory 模板 | [bots-examples/](bots-examples/) |
+
+---
+
+## License
+
+MIT

package/bin/larkway

@@ -0,0 +1,25 @@
+#!/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