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

pocket_coding-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+dist/
+build/
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.DS_Store
+.idea/
+.vscode/

pocket_coding-0.2.1/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: pocket-coding
+Version: 0.2.1
+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` is the product name. The Python package name is `pocket-coding`.
+
+PoCo is a local TUI for running coding-agent providers behind a Feishu bot. Codex is fully wired through `app-server`; Claude Code is wired through a CLI-backed provider with streamed output, session discovery, and session attach.
+
+- DM the bot for management
+- Use Feishu groups as project workspaces
+- Run one provider-backed worker per project group
+- Stream progress back by creating and editing Feishu messages
+
+## Quick Start
+
+Install PoCo:
+
+```bash
+pip install pocket-coding
+```
+
+Or from source:
+
+```bash
+pip install .
+```
+
+Then follow this flow:
+
+1. Create one Feishu self-built bot app, then bootstrap it with PoCo.
+
+Create the app manually in the Feishu developer console first. After you get
+the `App ID` and `App Secret`, run:
+
+Before running bootstrap, open this auth page and grant either
+`application:application` or `admin:app.category:update`:
+
+<https://open.feishu.cn/app/cli_a92032ebc97cdbcc/auth?q=application:application,admin:app.category:update&op_from=openapi&token_type=tenant>
+
+Then run:
+
+```bash
+poco feishu-bootstrap
+```
+
+PoCo will rewrite the app into the state it needs, including scopes, event
+subscriptions, and callback subscriptions.
+
+After bootstrap finishes, create and publish a new app version manually in the
+Feishu Open Platform. PoCo will print the suggested next semantic version in
+the bootstrap log.
+
+2. Make sure the machine running PoCo already has `codex` or `claude` / Claude
+Code installed and working.
+
+PoCo does not install these tools for you. If they are missing or broken, fix
+that first on your machine, then continue.
+
+3. Start PoCo, then open a DM with the bot.
+
+```bash
+poco
+```
+
+In the DM, send any message. For example:
+
+```text
+poco
+```
+
+This opens the DM control card. Use `New Project` to create a project group.
+PoCo will create a group named `Pocket-Project: <project_id>`, add you, add the
+bot, and start the default runtime:
+
+- Agent: `codex`
+- Provider: `openai`
+- Model: `gpt-5.4`
+- Reply Mode: `all`
+
+To send images to the current agent, send one Feishu post message that includes
+both the image and the text prompt. PoCo will forward them together.
+
+PoCo also ships with predefined model catalogs. For the Claude provider, the built-in list currently includes:
+
+- `sonnet`
+- `opus`
+- `haiku`
+- `deepseek-chat`
+- `deepseek-reasoner`
+- `kimi-k2.5`
+- `kimi-k2-0905-preview`
+- `kimi-k2-0711-preview`
+- `kimi-k2-turbo-preview`
+- `kimi-k2-thinking`
+- `kimi-k2-thinking-turbo`
+- `moonshot-v1-8k`
+- `moonshot-v1-32k`
+- `moonshot-v1-128k`
+- `moonshot-v1-8k-vision-preview`
+- `moonshot-v1-32k-vision-preview`
+- `moonshot-v1-128k-vision-preview`
+- `MiniMax-M2.1`
+- `MiniMax-M2.5`
+- `MiniMax-M2.7`
+
+Built-in Claude backends currently include:
+
+- `anthropic`
+- `deepseek`
+- `kimi`
+- `minimax`
+
+After that, the default workflow is simple:
+
+- DM the bot with `poco`
+- use the DM console card for project create / status / remove
+- in the project group, just talk to the agent
+
+## 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 connects to Feishu in long-connection mode, so no public callback URL is required
+
+## Usage
+
+DM console:
+
+- send `poco`
+- use the card UI to create a project, inspect a worker, or remove a worker
+
+Project group:
+
+- just talk to the agent
+- send one Feishu post message that contains both the image and the text prompt
+- no setup or lifecycle commands are needed in the group
+
+## Providers
+
+- `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
+
+Views:
+
+The TUI is a two-panel terminal UI:
+
+- left panel: logo and runtime summary
+- right panel: the current menu or interaction view
+- 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
+- `Up` / `Down`: 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 a menu with `Config`, `Restart`, and `Quit`
+- use `Up` / `Down` to select an item
+- press `Enter` to open it
+
+`Config` enters config mode. In that mode:
+
+- the right panel turns into a selection menu
+- `Up` / `Down` 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` contains `feishu` settings such as `App ID` and `App Secret`
+  - `Agent & Model` contains `codex` and `claude`
+  - `claude` opens a backend menu first
+  - choose a backend such as `anthropic`, `minimax`, or a user-added custom backend
+  - the backend marked with `(default)` is the current global Claude default
+  - then edit that backend'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
+  - `set_as_default` on the backend page marks that backend as the global Claude default
+- `show` opens the current config in a scrollable view
+- the bottom input line is only active while editing a text field
+
+## Files
+
+- Config: `~/.config/poco/config.json`
+- State: `~/.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.1/README.md

@@ -0,0 +1,210 @@
+# PoCo
+
+[中文说明](README.zh-CN.md)
+
+`PoCo` is the product name. The Python package name is `pocket-coding`.
+
+PoCo is a local TUI for running coding-agent providers behind a Feishu bot. Codex is fully wired through `app-server`; Claude Code is wired through a CLI-backed provider with streamed output, session discovery, and session attach.
+
+- DM the bot for management
+- Use Feishu groups as project workspaces
+- Run one provider-backed worker per project group
+- Stream progress back by creating and editing Feishu messages
+
+## Quick Start
+
+Install PoCo:
+
+```bash
+pip install pocket-coding
+```
+
+Or from source:
+
+```bash
+pip install .
+```
+
+Then follow this flow:
+
+1. Create one Feishu self-built bot app, then bootstrap it with PoCo.
+
+Create the app manually in the Feishu developer console first. After you get
+the `App ID` and `App Secret`, run:
+
+Before running bootstrap, open this auth page and grant either
+`application:application` or `admin:app.category:update`:
+
+<https://open.feishu.cn/app/cli_a92032ebc97cdbcc/auth?q=application:application,admin:app.category:update&op_from=openapi&token_type=tenant>
+
+Then run:
+
+```bash
+poco feishu-bootstrap
+```
+
+PoCo will rewrite the app into the state it needs, including scopes, event
+subscriptions, and callback subscriptions.
+
+After bootstrap finishes, create and publish a new app version manually in the
+Feishu Open Platform. PoCo will print the suggested next semantic version in
+the bootstrap log.
+
+2. Make sure the machine running PoCo already has `codex` or `claude` / Claude
+Code installed and working.
+
+PoCo does not install these tools for you. If they are missing or broken, fix
+that first on your machine, then continue.
+
+3. Start PoCo, then open a DM with the bot.
+
+```bash
+poco
+```
+
+In the DM, send any message. For example:
+
+```text
+poco
+```
+
+This opens the DM control card. Use `New Project` to create a project group.
+PoCo will create a group named `Pocket-Project: <project_id>`, add you, add the
+bot, and start the default runtime:
+
+- Agent: `codex`
+- Provider: `openai`
+- Model: `gpt-5.4`
+- Reply Mode: `all`
+
+To send images to the current agent, send one Feishu post message that includes
+both the image and the text prompt. PoCo will forward them together.
+
+PoCo also ships with predefined model catalogs. For the Claude provider, the built-in list currently includes:
+
+- `sonnet`
+- `opus`
+- `haiku`
+- `deepseek-chat`
+- `deepseek-reasoner`
+- `kimi-k2.5`
+- `kimi-k2-0905-preview`
+- `kimi-k2-0711-preview`
+- `kimi-k2-turbo-preview`
+- `kimi-k2-thinking`
+- `kimi-k2-thinking-turbo`
+- `moonshot-v1-8k`
+- `moonshot-v1-32k`
+- `moonshot-v1-128k`
+- `moonshot-v1-8k-vision-preview`
+- `moonshot-v1-32k-vision-preview`
+- `moonshot-v1-128k-vision-preview`
+- `MiniMax-M2.1`
+- `MiniMax-M2.5`
+- `MiniMax-M2.7`
+
+Built-in Claude backends currently include:
+
+- `anthropic`
+- `deepseek`
+- `kimi`
+- `minimax`
+
+After that, the default workflow is simple:
+
+- DM the bot with `poco`
+- use the DM console card for project create / status / remove
+- in the project group, just talk to the agent
+
+## 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 connects to Feishu in long-connection mode, so no public callback URL is required
+
+## Usage
+
+DM console:
+
+- send `poco`
+- use the card UI to create a project, inspect a worker, or remove a worker
+
+Project group:
+
+- just talk to the agent
+- send one Feishu post message that contains both the image and the text prompt
+- no setup or lifecycle commands are needed in the group
+
+## Providers
+
+- `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
+
+Views:
+
+The TUI is a two-panel terminal UI:
+
+- left panel: logo and runtime summary
+- right panel: the current menu or interaction view
+- 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
+- `Up` / `Down`: 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 a menu with `Config`, `Restart`, and `Quit`
+- use `Up` / `Down` to select an item
+- press `Enter` to open it
+
+`Config` enters config mode. In that mode:
+
+- the right panel turns into a selection menu
+- `Up` / `Down` 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` contains `feishu` settings such as `App ID` and `App Secret`
+  - `Agent & Model` contains `codex` and `claude`
+  - `claude` opens a backend menu first
+  - choose a backend such as `anthropic`, `minimax`, or a user-added custom backend
+  - the backend marked with `(default)` is the current global Claude default
+  - then edit that backend'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
+  - `set_as_default` on the backend page marks that backend as the global Claude default
+- `show` opens the current config in a scrollable view
+- the bottom input line is only active while editing a text field
+
+## Files
+
+- Config: `~/.config/poco/config.json`
+- State: `~/.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.1/README.zh-CN.md

@@ -0,0 +1,211 @@
+# PoCo
+
+[English](README.md)
+
+`PoCo` 是产品名，Python 包名是 `pocket-coding`。
+
+PoCo 是一个本地 TUI，用来把不同的 coding-agent provider 接到飞书机器人后面。当前 Codex 已通过 `app-server` 完整接通；Claude Code 也已经通过 CLI 适配接入，支持流式输出、session 发现和 attach。
+
+- 和机器人单聊时，把它当作管理控制台
+- 把飞书群当作项目工作区
+- 每个项目群对应一个独立的 provider worker
+- 通过飞书消息创建和编辑，把进度持续回推到群里
+
+## 快速开始
+
+先安装 PoCo：
+
+```bash
+pip install pocket-coding
+```
+
+如果你是从源码运行：
+
+```bash
+pip install .
+```
+
+然后按下面三步来：
+
+1. 先创建一个飞书企业自建机器人应用，然后用 PoCo 一键补齐配置。
+
+飞书应用本身必须先在开发者后台手动创建。拿到 `App ID` 和
+`App Secret` 之后，运行：
+
+在运行 bootstrap 之前，请先打开下面这个授权页，手动开通以下任意一个权限：
+
+- `application:application`
+- `admin:app.category:update`
+
+授权页：
+
+<https://open.feishu.cn/app/cli_a92032ebc97cdbcc/auth?q=application:application,admin:app.category:update&op_from=openapi&token_type=tenant>
+
+然后再运行：
+
+```bash
+poco feishu-bootstrap
+```
+
+PoCo 会把这个应用改写成它需要的状态，包括权限、事件订阅、回调订阅，
+不包括版本自动发布。
+
+bootstrap 完成后，请你回到飞书开放平台，手动创建并发布一个新版本。
+PoCo 会在 bootstrap 日志里打印建议使用的下一个语义版本号。
+
+2. 确认运行 PoCo 的机器上已经装好并能正常使用 `codex` 或 `claude`
+/ Claude Code。
+
+PoCo 不负责帮你安装这些工具。如果它们不存在或者本机不能正常运行，
+请先自己处理好，再继续。
+
+3. 启动 PoCo，然后去飞书里和机器人单聊。
+
+```bash
+poco
+```
+
+在 DM 里发任意一条消息即可，例如：
+
+```text
+poco
+```
+
+这会打开 DM 控制台卡片。点击 `New Project` 创建一个项目群。
+PoCo 会自动创建名为 `Pocket-Project: <project_id>` 的群，把你和机器人拉进去，
+并启动默认 runtime：
+
+- Agent：`codex`
+- Provider：`openai`
+- Model：`gpt-5.4`
+- Reply Mode：`all`
+
+如果要给当前 agent 发图片，请用一条飞书图文消息同时发送图片和文字说明。
+
+PoCo 还自带一份预定义模型目录。当前 Claude provider 内置了这些模型：
+
+- `sonnet`
+- `opus`
+- `haiku`
+- `deepseek-chat`
+- `deepseek-reasoner`
+- `kimi-k2.5`
+- `kimi-k2-0905-preview`
+- `kimi-k2-0711-preview`
+- `kimi-k2-turbo-preview`
+- `kimi-k2-thinking`
+- `kimi-k2-thinking-turbo`
+- `moonshot-v1-8k`
+- `moonshot-v1-32k`
+- `moonshot-v1-128k`
+- `moonshot-v1-8k-vision-preview`
+- `moonshot-v1-32k-vision-preview`
+- `moonshot-v1-128k-vision-preview`
+- `MiniMax-M2.1`
+- `MiniMax-M2.5`
+- `MiniMax-M2.7`
+
+当前内置的 Claude backend 包括：
+
+- `anthropic`
+- `deepseek`
+- `kimi`
+- `minimax`
+
+之后默认就按这条路径用：
+
+- 在单聊里发 `poco`
+- 用 DM 控制台卡片做项目创建 / 状态查看 / 删除
+- 在项目群里直接和 agent 聊天
+
+## 工作方式
+
+- 单聊机器人：管理控制台
+- 群聊机器人：项目工作区
+- 每个项目群会启动一个独立的 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`：返回上一级
+
+默认首页是菜单驱动的：
+
+- 右侧会显示 `Config`、`Restart`、`Quit`
+- 用 `↑ / ↓` 选择项目
+- 按 `Enter` 进入
+
+进入 `Config` 后：
+
+- 右侧面板会变成选择菜单
+- `↑ / ↓` 可以切换 section 或字段
+- `Enter` 进入当前项
+- `Esc` 返回上一级
+  - `Language` 可以切换英文和中文
+  - `Bot` 里包含 `feishu` 相关设置，比如 `App ID`、`App Secret`
+  - `Agent & Model` 里包含 `codex` 和 `claude`
+  - `claude` 会先进入 backend 菜单
+  - 先选一个 backend，例如 `anthropic`、`minimax`，或用户新增的 custom backend
+  - 带 `(default)` 标记的就是当前全局默认 Claude backend
+  - 再编辑这个 backend 的 `base_url`、`auth_token`、`model`、`extra_env`
+  - `model` 会再进入一个模型菜单；先选模型，再执行 `set_as_default`
+  - `extra_env` 也会进入子菜单；按项管理环境变量，不再直接编辑原始 JSON
+  - backend 页面里的 `set_as_default` 会把当前 backend 设为全局默认 Claude backend
+- `show` 会打开当前配置文件的滚动视图
+- 只有在编辑文本字段时，底部输入栏才会启用
+
+## 文件位置
+
+- 配置文件：`~/.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.1.1 → pocket_coding-0.2.1}/poco/__init__.py

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