pocket-coding 0.2.1__tar.gz → 0.2.2__tar.gz

pocket_coding-0.2.2/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: pocket-coding
+Version: 0.2.2
+Summary: PoCo: Pocket Coding for Feishu
+Author: PoCo contributors
+Keywords: bot,codex,feishu,lark,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.11
+Requires-Dist: lark-oapi==1.5.3
+Requires-Dist: textual<1,>=0.75
+Description-Content-Type: text/markdown
+
+# PoCo
+
+[中文说明](README.zh-CN.md)
+
+**PoCo** (Pocket-Coding) is a bot runtime that connects different coding agents to workplace chat software.
+
+It currently supports Codex, Claude Code, and Feishu bots.
+
+## Quick Start
+
+See [Quick Start](docs/quickstart.md).
+
+## How It Works
+
+- DM with the bot: management console
+- Group chat with the bot: project workspace
+- Each project group gets its own worker process
+- Each project is configured from the DM console card
+- PoCo uses Feishu long-connection mode, so no public callback URL is required
+
+## Usage
+
+DM console:
+
+- send `poco`
+- use the card UI to create a project and manage projects
+
+Project group:
+
+- just talk to the agent
+- if you want to send an image, send one Feishu post message that contains both the image and the text prompt
+
+## Provider
+
+- `codex`: fully implemented through `codex app-server`
+- `claude`: implemented through the Claude Code CLI with streamed JSON output
+
+Current provider notes:
+
+- Codex is the default runtime path
+- Claude currently supports session attach, image input, and streamed replies
+
+## TUI
+
+The TUI is a two-panel terminal UI:
+
+- left panel: logo and runtime summary
+- right panel: the current interaction panel
+- bottom: an input line that is only enabled when a config field needs text input
+
+Shortcuts:
+
+- `Ctrl+R`: Save and restart
+- `q`: go back one level
+- `↑ / ↓`: move in the main menu or config menu
+- `Enter`: open the selected item
+- `Esc`: go back one level
+
+The default home screen is menu-driven:
+
+- the right panel shows:
+  - `Agent & Model`
+  - `Bot (feishu)`
+  - `PoCo`
+  - `Language`
+  - `Quit`
+- use `↑ / ↓` to select an item
+- press `Enter` to open it
+
+Top-level items open their config sections directly:
+
+- the right panel turns into a selection menu
+- `↑ / ↓` moves between sections or fields
+- `Enter` opens the current selection
+- `Esc` returns to the previous level
+- `Language` lets you switch between English and Chinese
+- `Bot (feishu)` contains Feishu settings such as `App ID` and `App Secret`
+- `Agent & Model` contains `codex` and `claude`
+- `claude` opens a provider menu first
+- choose a provider such as `anthropic`, `minimax`, `deepseek`, or `kimi`
+- then edit that provider's `base_url`, `auth_token`, `model`, and `extra_env`
+- `model` opens another menu; pick a model first, then run `set_as_default`
+- `extra_env` also opens a submenu; manage env entries one by one instead of editing raw JSON
+- `show` opens the current config in a scrollable view
+- the bottom input line is only active while editing a text field
+
+## Files
+
+- Workspace bindings: `~/.config/poco/workspaces.json`
+- Per-bot config file: `~/.config/poco/bindings/<app_id>/config.json`
+- Per-bot state directory: `~/.local/state/poco/<app_id>/`
+- Legacy default config/state are still under:
+  - `~/.config/poco/config.json`
+  - `~/.local/state/poco/`
+
+## Development
+
+Build packages:
+
+```bash
+uv build
+```
+
+Quick syntax check:
+
+```bash
+uv run python -m py_compile poco/__init__.py poco/app.py poco/runtime.py poco/relay/app.py poco/config/store.py poco/tui/app.py
+```

pocket_coding-0.2.2/README.md

@@ -0,0 +1,108 @@
+# PoCo
+
+[中文说明](README.zh-CN.md)
+
+**PoCo** (Pocket-Coding) is a bot runtime that connects different coding agents to workplace chat software.
+
+It currently supports Codex, Claude Code, and Feishu bots.
+
+## Quick Start
+
+See [Quick Start](docs/quickstart.md).
+
+## How It Works
+
+- DM with the bot: management console
+- Group chat with the bot: project workspace
+- Each project group gets its own worker process
+- Each project is configured from the DM console card
+- PoCo uses Feishu long-connection mode, so no public callback URL is required
+
+## Usage
+
+DM console:
+
+- send `poco`
+- use the card UI to create a project and manage projects
+
+Project group:
+
+- just talk to the agent
+- if you want to send an image, send one Feishu post message that contains both the image and the text prompt
+
+## Provider
+
+- `codex`: fully implemented through `codex app-server`
+- `claude`: implemented through the Claude Code CLI with streamed JSON output
+
+Current provider notes:
+
+- Codex is the default runtime path
+- Claude currently supports session attach, image input, and streamed replies
+
+## TUI
+
+The TUI is a two-panel terminal UI:
+
+- left panel: logo and runtime summary
+- right panel: the current interaction panel
+- bottom: an input line that is only enabled when a config field needs text input
+
+Shortcuts:
+
+- `Ctrl+R`: Save and restart
+- `q`: go back one level
+- `↑ / ↓`: move in the main menu or config menu
+- `Enter`: open the selected item
+- `Esc`: go back one level
+
+The default home screen is menu-driven:
+
+- the right panel shows:
+  - `Agent & Model`
+  - `Bot (feishu)`
+  - `PoCo`
+  - `Language`
+  - `Quit`
+- use `↑ / ↓` to select an item
+- press `Enter` to open it
+
+Top-level items open their config sections directly:
+
+- the right panel turns into a selection menu
+- `↑ / ↓` moves between sections or fields
+- `Enter` opens the current selection
+- `Esc` returns to the previous level
+- `Language` lets you switch between English and Chinese
+- `Bot (feishu)` contains Feishu settings such as `App ID` and `App Secret`
+- `Agent & Model` contains `codex` and `claude`
+- `claude` opens a provider menu first
+- choose a provider such as `anthropic`, `minimax`, `deepseek`, or `kimi`
+- then edit that provider's `base_url`, `auth_token`, `model`, and `extra_env`
+- `model` opens another menu; pick a model first, then run `set_as_default`
+- `extra_env` also opens a submenu; manage env entries one by one instead of editing raw JSON
+- `show` opens the current config in a scrollable view
+- the bottom input line is only active while editing a text field
+
+## Files
+
+- Workspace bindings: `~/.config/poco/workspaces.json`
+- Per-bot config file: `~/.config/poco/bindings/<app_id>/config.json`
+- Per-bot state directory: `~/.local/state/poco/<app_id>/`
+- Legacy default config/state are still under:
+  - `~/.config/poco/config.json`
+  - `~/.local/state/poco/`
+
+## Development
+
+Build packages:
+
+```bash
+uv build
+```
+
+Quick syntax check:
+
+```bash
+uv run python -m py_compile poco/__init__.py poco/app.py poco/runtime.py poco/relay/app.py poco/config/store.py poco/tui/app.py
+```

pocket_coding-0.2.2/README.zh-CN.md

@@ -0,0 +1,110 @@
+# PoCo
+
+[English](README.md)
+
+**PoCo** (Pocket-Coding) 是一个把不同 Coding-Agent 接入办公软件机器人程序。
+
+当前已经支持了 Codex, Claude Code 等 Coding-Agent；已经支持了飞书机器人。
+
+## 快速开始
+
+点击这里[快速开始](docs/quickstart.zh-CN.md)。
+
+## 工作方式
+
+- 单聊机器人：管理控制台
+- 群聊机器人：项目工作区
+- 每个项目群会启动一个独立的 worker 进程
+- 每个项目都通过 DM 控制台卡片配置
+- PoCo 使用飞书长连接模式，不需要公网回调地址
+
+## 使用方式
+
+单聊控制台：
+
+- 发 `poco`
+- 用卡片完成新建项目和管理项目
+
+项目群：
+
+- 直接聊天即可
+- 如果要发图片，请发送一条同时包含图片和文字说明的飞书图文消息
+
+## Provider
+
+- `codex`：已通过 `codex app-server` 完整接通
+- `claude`：已通过 Claude Code CLI 接通，支持流式 JSON 输出
+
+当前 provider 能力说明：
+
+- Codex 是默认运行路径
+- Claude 当前支持 session attach、图片输入和流式回复
+
+## TUI
+
+页面：
+
+当前 TUI 是一个双栏终端界面：
+
+- 左侧：logo 和运行状态摘要
+- 右侧：当前交互面板
+- 底部：一个输入栏，但只有在需要输入配置值时才会启用
+
+快捷键：
+
+- `Ctrl+R`：保存并重启
+- `q`：返回上一级
+- `↑ / ↓`：在主菜单或 config 菜单中移动
+- `Enter`：进入当前选项
+- `Esc`：返回上一级
+
+默认首页是菜单驱动的：
+
+- 右侧会显示：
+  - `Agent & Model`
+  - `Bot (feishu)`
+  - `PoCo`
+  - `Language`
+  - `Quit`
+- 用 `↑ / ↓` 选择项目
+- 按 `Enter` 进入
+
+顶层菜单会直接进入对应配置分类：
+
+- 右侧面板会变成选择菜单
+- `↑ / ↓` 可以切换 section 或字段
+- `Enter` 进入当前项
+- `Esc` 返回上一级
+- `Language` 可以切换英文和中文
+- `Bot (feishu)` 里包含 `feishu` 相关设置，比如 `App ID`、`App Secret`
+- `Agent & Model` 里包含 `codex` 和 `claude`
+- `claude` 会先进入 provider 菜单
+- 先选一个 provider，例如 `anthropic`、`minimax`、`deepseek`、`kimi`
+- 再编辑这个 provider 的 `base_url`、`auth_token`、`model`、`extra_env`
+- `model` 会再进入一个模型菜单；先选模型，再执行 `set_as_default`
+- `extra_env` 也会进入子菜单；按项管理环境变量，不再直接编辑原始 JSON
+- `show` 会打开当前配置文件的滚动视图
+- 只有在编辑文本字段时，底部输入栏才会启用
+
+## 文件位置
+
+- 工作区绑定：`~/.config/poco/workspaces.json`
+- 每个 bot 的配置文件：`~/.config/poco/bindings/<app_id>/config.json`
+- 每个 bot 的状态目录：`~/.local/state/poco/<app_id>/`
+- 兼容旧版时，默认配置 / 状态仍在：
+  - `~/.config/poco/config.json`
+  - `~/.local/state/poco/`
+
+## 开发
+
+构建安装包：
+
+```bash
+uv build
+```
+
+快速语法检查：
+
+```bash
+uv run python -m py_compile poco/__init__.py poco/app.py poco/runtime.py poco/relay/app.py poco/config/store.py poco/tui/app.py
+```

{pocket_coding-0.2.1 → pocket_coding-0.2.2}/poco/__init__.py

@@ -1,4 +1,4 @@
 """PoCo package."""
 
 __all__ = ["__version__"]
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{pocket_coding-0.2.1 → pocket_coding-0.2.2}/poco/app.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 import argparse
-import fcntl
 import json
 import logging
 import os
@@ -12,36 +11,10 @@ from .runtime import (
     PoCoService,
     RingLogHandler,
 )
-from .config import CONFIG_PATH, LOG_PATH, STATE_DIR, ConfigStore, ensure_dirs, get_nested
+from .config import ConfigStore, build_paths, ensure_dirs, get_nested, workspace_binding
 from .tui import PoCoTui
 
 
-_APP_LOCK = None
-
-
-def _acquire_app_lock() -> bool:
-    """Acquires a process-wide PoCo instance lock.
-
-    Returns:
-        True when this process successfully acquired the lock, or False when
-        another PoCo process is already holding it.
-    """
-    global _APP_LOCK
-    lock_path = Path(STATE_DIR) / "poco.lock"
-    handle = lock_path.open("w", encoding="utf-8")
-    try:
-        fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-    except BlockingIOError:
-        handle.close()
-        return False
-    handle.seek(0)
-    handle.truncate()
-    handle.write(str(os.getpid()))
-    handle.flush()
-    _APP_LOCK = handle
-    return True
-
-
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="PoCo")
     parser.add_argument("--log-level", default="INFO")
@@ -60,15 +33,16 @@ def main() -> None:
         level=getattr(logging, str(getattr(args, "log_level", "INFO")).upper(), logging.INFO),
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
     )
-    ensure_dirs()
-    if not _acquire_app_lock():
-        raise SystemExit("Another PoCo process is already running. Kill the existing process first.")
+    workspace = Path.cwd()
+    binding = workspace_binding(workspace)
+    paths = build_paths(binding or "default")
+    ensure_dirs(paths)
     root_logger = logging.getLogger()
     ring = RingLogHandler()
     ring.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
     root_logger.addHandler(ring)
     file_handler = RotatingFileHandler(
-        LOG_PATH,
+        paths.log_path,
         maxBytes=2_000_000,
         backupCount=3,
         encoding="utf-8",
@@ -76,10 +50,14 @@ def main() -> None:
     )
     file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
     root_logger.addHandler(file_handler)
-    logging.getLogger("poco").info("Persistent log file enabled at %s", LOG_PATH)
+    logging.getLogger("poco").info(
+        "Persistent log file enabled at %s (instance=%s)",
+        paths.log_path,
+        binding or "default",
+    )
 
-    store = ConfigStore(CONFIG_PATH)
-    service = PoCoService(store, ring)
+    store = ConfigStore(paths.config_path, paths)
+    service = PoCoService(store, ring, paths)
 
     if args.command == "config" and args.show:
         print(json.dumps(service.masked_config(), ensure_ascii=False, indent=2))
@@ -92,10 +70,14 @@ def main() -> None:
         print(json.dumps({path: current}, ensure_ascii=False, indent=2))
         return
     if args.command == "feishu-bootstrap":
-        raise SystemExit(run_feishu_bootstrap_cli(store))
+        raise SystemExit(run_feishu_bootstrap_cli(workspace))
 
-    app = PoCoTui(service, focus_config=args.command == "config")
+    skip_bind_once = os.environ.pop("POCO_SKIP_BIND_ONCE", "") == "1"
+    app = PoCoTui(service, focus_config=args.command == "config", skip_bind_once=skip_bind_once)
     result = app.run()
+    if result == "restart-bound":
+        os.environ["POCO_SKIP_BIND_ONCE"] = "1"
+        os.execv(sys.executable, [sys.executable, *sys.argv])
     if result == "restart":
         os.execv(sys.executable, [sys.executable, *sys.argv])
 

{pocket_coding-0.2.1 → pocket_coding-0.2.2}/poco/bootstrap/feishu.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 import getpass
-import re
 from dataclasses import dataclass, field
-from typing import Callable, List, Optional, Set, Tuple
+from pathlib import Path
+from typing import Callable, List, Set
 
 import lark_oapi as lark
 import requests
@@ -15,13 +15,12 @@ from lark_oapi.api.application.v6 import (
     Application,
     Callback,
     GetApplicationRequest,
-    ListApplicationAppVersionRequest,
     ListScopeRequest,
     PatchApplicationRequest,
     SubscribedEvent,
 )
 
-from ..config import ConfigStore, get_nested, normalize_config_key, set_nested
+from ..config import ConfigStore, bind_workspace, build_paths, ensure_dirs, get_nested, normalize_config_key, set_nested, workspace_binding
 
 BASE_URL = "https://open.feishu.cn/open-apis"
 REQUIRED_SCOPES = [
@@ -52,21 +51,9 @@ class CurrentAppState:
     callbacks: Set[str] = field(default_factory=set)
 
 
-@dataclass(slots=True)
-class PublishResult:
-    """Best-effort publish result."""
-
-    created_version: bool = False
-    published: bool = False
-    version_tag: str = ""
-    warnings: List[str] = field(default_factory=list)
-
-
 class FeishuBootstrapper:
     """Applies PoCo's desired configuration to one Feishu app."""
 
-    _SEMVER_RE = re.compile(r"^\s*(\d+)\.(\d+)\.(\d+)\s*$")
-
     def __init__(self, app_id: str, app_secret: str, store: ConfigStore) -> None:
         self.app_id = app_id.strip()
         self.app_secret = app_secret.strip()
@@ -241,87 +228,6 @@ class FeishuBootstrapper:
                 f"log_id={response.get_log_id()}"
             )
 
-    @classmethod
-    def _parse_semver(cls, value: str) -> Optional[Tuple[int, int, int]]:
-        """Parses a semantic version string."""
-        match = cls._SEMVER_RE.match(value or "")
-        if not match:
-            return None
-        return tuple(int(part) for part in match.groups())
-
-    @staticmethod
-    def _format_semver(version: Tuple[int, int, int]) -> str:
-        """Formats a semantic version tuple."""
-        return ".".join(str(part) for part in version)
-
-    def _next_version_tag(self) -> Tuple[str, List[str]]:
-        """Computes the next app version tag.
-
-        Returns:
-            A tuple of (next_version, warnings).
-        """
-        warnings: List[str] = []
-        request = (
-            ListApplicationAppVersionRequest.builder()
-            .app_id(self.app_id)
-            .lang("en_us")
-            .page_size(50)
-            .build()
-        )
-        response = self._client.application.v6.application_app_version.list(request)
-        if response.code != 0:
-            raise RuntimeError(
-                f"Feishu app version list failed: code={response.code}, msg={response.msg}, "
-                f"log_id={response.get_log_id()}"
-            )
-        items = response.data.items if response.data is not None and response.data.items is not None else []
-        if not items:
-            return "0.1.0", warnings
-        parsed_versions: List[Tuple[int, int, int]] = []
-        ignored_versions: List[str] = []
-        for item in items:
-            version = str(getattr(item, "version", "") or "").strip()
-            if not version:
-                continue
-            parsed = self._parse_semver(version)
-            if parsed is None:
-                ignored_versions.append(version)
-                continue
-            parsed_versions.append(parsed)
-        if not parsed_versions:
-            if ignored_versions:
-                warnings.append(
-                    "Existing app versions are not semantic versions and were ignored: "
-                    + ", ".join(sorted(set(ignored_versions))[:5])
-                )
-            return "0.1.0", warnings
-        major, minor, patch = max(parsed_versions)
-        next_version = (major, minor, patch + 1)
-        return self._format_semver(next_version), warnings
-
-    def create_and_publish_version(self, tenant_access_token: str) -> PublishResult:
-        """Best-effort version guidance.
-
-        Feishu's application patch and scope flows are scriptable, but version
-        creation / publish is still unreliable through the current API path
-        used by PoCo. Instead of failing bootstrap, PoCo computes the next
-        semantic version and tells the user what to publish manually.
-        """
-        result = PublishResult()
-        try:
-            version_tag, version_warnings = self._next_version_tag()
-            result.version_tag = version_tag
-            result.warnings.extend(version_warnings)
-        except Exception as exc:
-            result.warnings.append(f"Version lookup failed, fallback to 0.1.0: {exc}")
-            version_tag = "0.1.0"
-            result.version_tag = version_tag
-        result.warnings.append(
-            "App config is ready, but Feishu version creation / publish still needs to be done "
-            f"manually in Open Platform. Suggested next version: {version_tag}."
-        )
-        return result
-
 
 def _prompt_with_default(prompt: str, default: str, *, secret: bool = False) -> str:
     """Prompts for one value, keeping the existing default on empty input."""
@@ -332,9 +238,11 @@ def _prompt_with_default(prompt: str, default: str, *, secret: bool = False) ->
     return value or default
 
 
-def run_feishu_bootstrap_cli(store: ConfigStore) -> int:
+def run_feishu_bootstrap_cli(workspace: Path) -> int:
     """Runs Feishu bootstrap as a simple two-step CLI wizard."""
-    config = store.load()
+    bound_app_id = workspace_binding(workspace)
+    draft_store = ConfigStore(build_paths(bound_app_id or "default").config_path, build_paths(bound_app_id or "default"))
+    config = draft_store.load()
     draft_app_id = str(get_nested(config, "feishu.app_id") or "").strip()
     draft_app_secret = str(get_nested(config, "feishu.app_secret") or "").strip()
 
@@ -353,16 +261,21 @@ def run_feishu_bootstrap_cli(store: ConfigStore) -> int:
         print("ERROR  APP Secret is required.")
         return 1
 
+    bound_paths = build_paths(app_id)
+    ensure_dirs(bound_paths)
+    store = ConfigStore(bound_paths.config_path, bound_paths)
     bootstrapper = FeishuBootstrapper(app_id, app_secret, store)
     try:
         print("INFO   Starting Feishu bootstrap.")
         print("INFO   Validating APP ID / APP Secret.")
-        tenant_token = bootstrapper.validate_credentials()
+        bootstrapper.validate_credentials()
         print("OK     Credentials are valid.")
 
         print("INFO   Saving local PoCo config.")
         bootstrapper.save_local_credentials()
-        print("OK     Saved APP ID / APP Secret into ~/.config/poco/config.json.")
+        bind_workspace(workspace, app_id)
+        print(f"OK     Bound workspace `{workspace}` to `{app_id}`.")
+        print(f"OK     Saved APP ID / APP Secret into {bound_paths.config_path}.")
 
         print("INFO   Reading current Feishu app state.")
         current = bootstrapper.fetch_current_state()
@@ -381,10 +294,7 @@ def run_feishu_bootstrap_cli(store: ConfigStore) -> int:
         bootstrapper.apply_scopes()
         print("OK     Scope application submitted.")
 
-        print("INFO   Checking the next app version.")
-        publish_result = bootstrapper.create_and_publish_version(tenant_token)
-        for warning in publish_result.warnings:
-            print(f"INFO   {warning}")
+        print("INFO   Bootstrap completed. Create and publish the new app version manually in Feishu Open Platform.")
 
         print("FINISH PoCo bootstrap finished.")
         return 0

{pocket_coding-0.2.1 → pocket_coding-0.2.2}/poco/config/__init__.py

@@ -1,4 +1,6 @@
 from .store import (
+    PoCoPaths,
+    WORKSPACE_BINDINGS_PATH,
     CONFIG_KEY_ALIASES,
     CONFIG_PATH,
     DEFAULT_CONFIG,
@@ -8,17 +10,25 @@ from .store import (
     THREAD_STATE_PATH,
     WORKER_STATE_PATH,
     ConfigStore,
+    build_paths,
+    bind_workspace,
     config_ready,
     ensure_dirs,
     get_nested,
+    load_workspace_bindings,
     mask_secret,
     missing_required_config_paths,
+    normalize_instance_name,
     normalize_config_key,
     parse_config_value,
+    saved_feishu_bot_ids,
     set_nested,
+    workspace_binding,
 )
 
 __all__ = [
+    "PoCoPaths",
+    "WORKSPACE_BINDINGS_PATH",
     "CONFIG_KEY_ALIASES",
     "CONFIG_PATH",
     "DEFAULT_CONFIG",
@@ -28,12 +38,18 @@ __all__ = [
     "THREAD_STATE_PATH",
     "WORKER_STATE_PATH",
     "ConfigStore",
+    "build_paths",
+    "bind_workspace",
     "config_ready",
     "ensure_dirs",
     "get_nested",
+    "load_workspace_bindings",
     "mask_secret",
     "missing_required_config_paths",
+    "normalize_instance_name",
     "normalize_config_key",
     "parse_config_value",
+    "saved_feishu_bot_ids",
     "set_nested",
+    "workspace_binding",
 ]