@pithosai/pithosai 1.0.0 → 1.0.2

package/README.md

@@ -1,451 +1,151 @@
-# Pithosai (pi-agent)
+# Pithosai (`@pithosai/pithosai`)
 
-Pithosai is a CLI that implements code or projects from a natural-language request. Role prompts are loaded from the SQLite DB at runtime (with optional fallback to `.pithosai/<role>/*.md`). A project-local `.pithosai/` directory holds role-specific prompt files when used and persists conversation sessions under `.pithosai/sessions/`.
-
-**Requirements:** Node.js (ESM), and a model provider — Cursor CLI (browser auth, no API key), DeepSeek API key, or OpenRouter API key.
+**Multi-role AI CLI** for coding and product work: natural-language requests, pluggable models (Cursor, DeepSeek, OpenRouter), and role-based prompts stored in SQLite. **Current version: 1.0.1** — see [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
 ## Install
 
-```bash
-npm install
-```
-
-Set up at least one model provider:
-
-- **Cursor CLI** (recommended — no API key needed):
-  ```bash
-  curl https://cursor.com/install -fsS | bash
-  cursor-agent login
-  export CURSOR_MODEL=auto   # or: sonnet-4.6, opus-4.6, gpt-5.2
-  ```
-- **DeepSeek:** `export DEEPSEEK_API_KEY=sk-...`
-- **OpenRouter:** `export OPENROUTER_API_KEY=sk-or-...`
-
-Provider priority: `CURSOR_MODEL` / `--cursor` > `DEEPSEEK_API_KEY` > `OPENROUTER_API_KEY`.
-
----
-
-## Docker
-
-If you want to build the Docker image, please git clone a new project from the repo, then run the following command:
+**Node.js ≥ 18.12** required.
 
 ```bash
-docker build --no-cache -t pithosai .
+npm install -g @pithosai/pithosai
 ```
 
-**Important:** Never share the project directory that is used by the non-Docker runtime.
+On a **global** install, the package runs a one-time step: if `~/.pithosai/pithosai.db` does not exist, it is created from the bundled schema. Override the path anytime with `PITHOSAI_DB_PATH`.
 
 ---
 
-## Quick start
-
-1. **Create a project**
-
-   ```bash
-   pithosai init
-   # or: pithosai init my-app --type js
-   # or: pithosai init ./backend --type ts --lang zh --role RD
-   ```
-
-   This creates the target directory (if needed), scaffolds by project type (`--type js|ts|python`) and role (`--role RD|PM|QA|CO|SRE` and other template roles), creates `.pithosai/sessions/`, and writes `.settings.json` (lang, project, supportedRoles, tools). Role prompts are loaded from the SQLite DB at runtime; no prompt files are copied into the project by default. For PM, QA, CO, MKT, or SRE roles, a starter `rules/requirements.md` is created for you to fill in.
-
-2. **Run a request**
-
-   ```bash
-   pithosai "Add a REST endpoint that returns the current time"
-   pithosai -C ./my-app "Run tests and fix failures"
-   pithosai "Refactor the auth module" --cursor              # use Cursor models (auto)
-   pithosai --cursor sonnet-4.6 "Explain this codebase"      # specific Cursor model
-   ```
-
-   By default, after the agent replies you get an interactive session to type more requests. Type `exit` or `quit` to leave.
-
-3. **Interactive-only mode (no initial request)**
+## What you get
 
-   ```bash
-   pithosai -i
-   ```
-
-  **Terminal UI (TTY):** When both stdin and stdout are TTYs, the default run command uses **`@mariozechner/pi-tui`**: the **input area stays at the bottom** in a **boxed Editor** (no `You:` prefix on the prompt), **assistant output streams above**, and a **loading row** sits **just above the input box** while the model is working. When output hits the transcript, that row **switches to a simpler running indicator** (same idea as the stderr spinner in non-TUI mode) and **stays until the run finishes**, instead of disappearing immediately. While the TUI is up, **CWD/request banners and run status go through the transcript sink** (and the **log file** via the file-only logger), not raw stdout, so **extra `process.stdout` traffic does not paint over the full-screen layout**; **Ctrl+S** and **Ctrl+P** notices are **appended to the transcript** instead of raw stdout. **Run failures** (including guard timeouts), **dialog/plan `success: false` errors**, and **failed result previews** are **appended to the transcript in red** so they stay visible without corrupting the layout. Slash-command output, `/list` tables, and `/shell` results are drawn in the same transcript (multi-line `/list` output is split into real rows and the view **scrolls to the table header**; use the **mouse wheel**, **arrow keys**, **PgUp/PgDn**, or **Ctrl+U / Ctrl+F** (page) to scroll long output, **including while the agent is running** (**Ctrl+U/Ctrl+F** scroll the log instead of the editor’s usual line-edit shortcuts; **Ctrl+D** remains EOF / exit on an empty line).   Set **`PITHOSAI_NO_TUI=1`** to use the classic readline **`You:`** line instead (e.g. scripts or SSH without a proper terminal).
-
-  In **`agent`** mode (default), prints CWD and short tips (full tools, task-scoped history in the local DB, `/new`, `/shell`, `/list`, `/show`, `/show-task [index]`, `/show-prompt`, **`/list-skill`**, **`/install-skill`**, **`/remove-skill`** — same behavior as `pithosai skills list`, `install`, and `remove` — keyboard controls), then prompts for input. **`dialog`** and **`plan`** show their own tips. After the banner, all three modes start the same input loop when interactive is enabled (plan keeps transcript output minimal until each plan file is written). **Tab** completes slash commands (e.g. `/list`, `/list-skill`, `/show`, `/show-prompt`, `/show-task`, `/install-skill`, `/remove-skill`) and `exit` / `quit` in both the pi-tui **Editor** prompt (dropdown + Enter to apply) and **readline** mode; **`/shell`** is only offered in **agent** mode. Typing **`/`** also opens the slash menu as you continue the command. The pause sub-prompt still uses readline **Tab** for `continue` / `c` and `exit` / `e`.
-
-   While an agent run is in progress, keyboard controls are available:
-   - `Ctrl+S` — stop current run and return to prompt
-   - `Ctrl+P` — pause current run and enter pause sub-prompt
-     - `continue` / `c` resumes with current request
-     - `exit` / `e` exits the CLI
-     - any other non-empty input replaces the pending request
-
-4. **One-shot (no follow-up prompt)**
-
-   ```bash
-   pithosai --no-interactive "One request only"
-   ```
-
-5. **Run variant (`--mode`)**
-
-   The default command supports a run variant:
-
-   | Mode | Behavior |
-   |------|----------|
-   | `agent` (default) | Answer and use tools (implement, run commands via tools, etc.). |
-  | `dialog` | Answer-focused mode with **read-only tools only** (`read`, `list_files`, `read_pdf`, `web_fetch`, `web_search`, `proxy_downloader`, `read_email`). `/shell` is disabled; `/list`, `/select`, `/show`, `/show-prompt`, `/show-task [index]`, `/list-skill`, `/install-skill`, and `/remove-skill` still work. |
-   | `plan` | Writes the model reply only to `<slug>-plan.md` in the **project root** (`-C` / cwd). Same **read-only tools** as dialog; `/shell` is disabled. `/list`, `/select`, `/show`, `/show-prompt`, `/show-task [index]`, `/list-skill`, `/install-skill`, and `/remove-skill` work like dialog. With `-i`, the follow-up prompt runs another plan per line (output stays minimal in the UI until each run completes). |
-
-   **Note:** In `plan` mode the run uses a **discard output sink** by default, so you often will not see streamed tokens in the terminal until the model finishes (or times out). While waiting, a **spinner on stderr** shows progress; when anything writes to **stdout**, the line **switches to a lighter running spinner** (TTY) until the run completes, instead of being cleared immediately. On a non-TTY stderr, the spinner **stops** on first stdout as before. The default max run time is **30 minutes** (`AGENT_RUN_TIMEOUT_MS`); pass `--timeout <seconds>` for a shorter cap.
-
-  **Dialog / plan result preview:** After each run completes, **dialog** and **plan** open a full-screen terminal viewer built on **`@mariozechner/pi-tui`** (`Markdown` with the same themed styling as **pi** via **`@mariozechner/pi-coding-agent`**’s `getMarkdownTheme`): scroll with **↑↓** or **j**/**k**, **PgUp**/**PgDn** or **Ctrl+U**/**Ctrl+D**, **Home**/**End**, **gg** (top), or **G** (bottom); press **q**, **Esc**, or **Ctrl+C** to close. While the preview is open, the interactive agent TUI is suspended so those keys only affect the viewer. If stdin/stdout are not both TTY (e.g. CI), the raw markdown is printed to stdout instead. If you set `PITHOSAI_RESULT_BROWSER=chrome`, preview switches to the browser viewer implemented with Playwright and rendered as **WeChat-style HTML** (inline styles, same pipeline as the `markdown_to_html` tool with `forWechat: true`). In Chrome mode the page includes a **Copy markdown** button (copies the raw markdown via the Clipboard API, with a textarea fallback) and **Close** (closes the whole preview browser via Playwright, not only the tab—needed so Chrome does not keep an empty window after the last tab closes). Content is passed in memory via `page.setContent` (no temp file). The Chrome window is opened with **Chromium app mode** (`--app=about:blank` plus a few flags) using Playwright’s **`launchPersistentContext`** so the omnibox and tab strip stay hidden—plain `browser.newPage()` would open a normal Chrome window and ignore app mode. Only your page content and the in-page toolbar are shown (standard window title bar may still appear). Chrome mode defaults to **Google Chrome stable** (`channel: chrome`) and falls back to bundled Chromium if Chrome is missing (install with `npm run playwright:install` / `npx playwright install chromium`). To always use the bundled browser in Chrome mode, set `PITHOSAI_PLAYWRIGHT_CHANNEL=bundled`. Other channels (e.g. `msedge`, `chrome-beta`) are supported via the same variable.    To disable preview (e.g. CI), set `PITHOSAI_SKIP_RESULT_BROWSER=1`.
-
-   In **`agent`** mode the model may call the **`playwright_view_markdown`** tool to open the same Playwright preview from **either** raw `markdown` **or** a project `path` to a `.md` file (exactly one of the two). The tool blocks until the user closes the preview window and respects `PITHOSAI_SKIP_RESULT_BROWSER` and `PITHOSAI_PLAYWRIGHT_CHANNEL`. It is **not** available in `dialog` / `plan` read-only toolsets.
-
-   ```bash
-   pithosai --mode dialog "Explain this stack trace"
-   pithosai -C ./my-app --mode plan "Sprint plan for the API work"
-   pithosai -l zh --mode plan --timeout 120 "迭代计划"
-   ```
-
-6. **Shell commands in interactive mode**
-
-   ```bash
-   pithosai -i
-   You: /shell ls -la
-   You: /shell git status
-   You: /shell npm test
-   ```
+| You run | Purpose |
+|--------|---------|
+| `pithosai` | Main CLI: `init`, interactive agent, `task`, `heartbeat`, `skills`, `memorize`, and more. |
+| `rdsai`, `pmsai`, `qasai`, `cosai`, `mktai`, `wrsai` | Same CLI with a **default role** (e.g. RD, PM, QA). |
+| `email-monitor` | Heartbeat / email-driven task loop (`heartbeat` bundle). |
+| `render-markdown` | Render Markdown files in the terminal. |
+| `pithosai-init-db` | Manually initialize `~/.pithosai/pithosai.db` if needed (usually automatic after global install). |
 
-   Prefix commands with `/shell` to execute shell commands directly.
-
-  The same prompt also supports **task-scoped commands** (conversation rows live in the local SQLite DB): `/list` lists persisted tasks as a markdown table (`index`, `task id`, `task title`, `description`, `createTime`); `/select <index>` selects the active task id, prints a selected-task line, and then shows current task stats (`/show`); `/show` prints current task stats; **`/show-prompt`** builds the system prompt for the current `--mode`, language, and role (same logic as `pithosai show-prompt`) and opens it in the same result viewer as dialog/plan, with the prompt body rendered as **markdown** (not a fenced code block); **`/show-task`** shows Q&A for the current task, and **`/show-task <index>`** shows Q&A for that persisted task index. Q&A and **`/show-prompt`** use the same configured result viewer (**pi-tui** terminal viewer by default, Playwright preview when `PITHOSAI_RESULT_BROWSER=chrome`); if `PITHOSAI_SKIP_RESULT_BROWSER=1`, markdown is printed to the terminal instead.
-
-  **Skill commands (ClawHub):** **`/list-skill`** lists installed skills under `.pithosai/skills` (like `pithosai skills list`). **`/install-skill`** with no name installs all remote skills from `clawhub list`; **`/install-skill <name>`** installs one skill; add **`--force`** to reinstall. **`/remove-skill <name>`** removes an installed skill (like `pithosai skills remove`). These use the same implementation as the `pithosai skills` CLI; `clawhub install` still uses inherited stdio when run from the REPL.
-
-7. **Add another role**
-
-   ```bash
-   pithosai add-role CO
-   ```
+---
 
-   Creates `.pithosai/<role>/` if it does not exist and adds the role to `supportedRoles` in project settings. If `.pithosai/<role>/` already exists, the command returns without overwriting. Prompts are loaded from the SQLite DB at runtime (with file fallback). Use `-r CO` or project settings to select the role.
+## Choose a model provider
 
-8. **Task mode (watch and process tasks from markdown)**
+Configure **at least one** of:
 
+1. **Cursor CLI** (recommended — subscription auth, no separate API key)  
    ```bash
-   pithosai task --file prompts.md
-   pithosai task -C ./my-app --file prompts.md --model deepSeekCoder
+   curl https://cursor.com/install -fsS | bash
+   cursor-agent login
+   export CURSOR_MODEL=auto
    ```
+   Use **`pithosai "your request" --cursor`** or set `CURSOR_MODEL`.
 
-   The task runner watches the task file and processes one task at a time (prioritizing `processing` tasks first, then `pending` tasks). During a running task:
-   - `Ctrl+S` stops the current task run
-   - `Ctrl+P` pauses and enters the same pause sub-prompt as interactive mode
-   - If you edit request text in pause sub-prompt, the resumed task run uses the edited text as the task request
+2. **DeepSeek** — `export DEEPSEEK_API_KEY=sk-...`
 
-9. **Memorize (role memory file from persisted tasks)**
+3. **OpenRouter** — `export OPENROUTER_API_KEY=sk-or-...`
 
-   ```bash
-   pithosai memorize --start 2026-01-01 --end 2026-01-31 -r RD
-   pithosai -r PM memorize --start 2026-04-01 --end 2026-04-10 -C ./my-app
-   ```
-
-   Reads the local SQLite task store (`~/.pithosai/pithosai.db` unless `PITHOSAI_DB_PATH` is set), finds tasks where the **role** has persisted task messages whose timestamps fall in the inclusive date range, and writes **`.pithosai/<role>/memory.md`** with a short summary per task (title, status, contribution excerpt from assistant output, and a suggested improvement line). Dates are **YYYY-MM-DD** (whole UTC days) or full ISO datetimes. LLM summarization uses the same model selection as the default **`pithosai`** run: **`--reasoner`**, **`--chat`**, **`--cursor [model]`**, and optional **`--model <key>`** (same `KEY_TO_MODEL` keys as **`pithosai task`**). The optional LLM tightening step uses **Chinese** instructions when global **`--lang`** (or project **`lang`** in settings) is Chinese (`zh`…), and **English** otherwise. Use **`--no-llm`** or **`PITHOSAI_MEMORIZE_SKIP_LLM=1`** to write only the structured file without an LLM pass, or if the model is unavailable the command falls back to the structured markdown and prints a notice.
+**Precedence:** `CURSOR_MODEL` / `--cursor` → DeepSeek → OpenRouter.
 
 ---
 
-## Role-specific commands
-
-Besides `pithosai`, you can use role-specific entry points. Each one runs the same CLI with a default **role** (and, for some, the **chat** model). All support the same subcommands and options as `pithosai`.
-
-| Command | Default role | Model | Use case |
-|--------|----------------|-------|----------|
-| **pithosai** | RD | Coder | General coding; implement from natural language. |
-| **rdsai** | RD | Coder | Same as `pithosai`; RD (e.g. R&D) coding agent. |
-| **pmsai** | PM | Chat | Product/project management; uses PM templates + chat model. |
-| **qasai** | QA | Chat | QA; uses QA templates + chat model. |
-| **cosai** | CO | Chat | CO role; uses CO templates + chat model. |
-| **mktai** | MKT | Chat | Professional marketing (positioning, GTM, campaigns); uses MKT templates + chat model. |
-
-Examples:
+## Quick start
 
 ```bash
-rdsai "Refactor the auth module"
-pmsai "Draft a sprint plan for the API work"
-qasai "Generate test cases for the login flow"
-cosai -i
-mktai "Pressure-test our positioning vs two named competitors; output a matrix, proof gaps, and homepage narrative fixes"
+cd your-project
+pithosai init
+pithosai "Describe what you want done"
 ```
 
-You can still override role or model (e.g. `pmsai -r QA`, `qasai --reasoner`, or `rdsai --cursor`). Add a role's templates with `pithosai add-role PM` (or QA, CO, MKT, SRE, etc.) before using that role.
-
----
-
-## Cursor CLI Integration
+- **`pithosai -i`** — interactive session with no initial prompt.  
+- **`pithosai --no-interactive "…"`** — one shot, then exit.  
+- **`pithosai -C ./other-dir "…"`** — use another project directory.
 
-Use models from your Cursor subscription (Claude Sonnet/Opus, GPT-5.2, etc.) without separate API keys. Authentication is handled by the Cursor CLI's browser-based login.
+Prompts load from the **local SQLite database** (default `~/.pithosai/pithosai.db`). Optional overrides live under `.pithosai/<role>/` in your project.
 
-**Setup (one-time):**
-
-```bash
-# Install the Cursor agent CLI
-curl https://cursor.com/install -fsS | bash
-
-# Log in via browser
-cursor-agent login
+---
 
-# Verify auth
-cursor-agent status
-```
+## Run modes (`--mode`)
 
-**Usage:**
+| Mode | Use case |
+|------|----------|
+| **`agent`** (default) | Full tools: edit files, run commands, etc. |
+| **`dialog`** | Answers and read-only tools (no shell tool). |
+| **`plan`** | Writes a plan file (`<slug>-plan.md`) in the project root; read-only tools. |
 
 ```bash
-# Environment variable
-export CURSOR_MODEL=auto
-pithosai "Build a REST API"
-
-# CLI flag (overrides env)
-# Note: `--cursor` has an optional value. To avoid parsing the request as model id,
-# put request before `--cursor`, or use `--` as separator.
-pithosai "Explain this code" --cursor
-pithosai --cursor -- "Explain this code"
-pithosai --cursor sonnet-4.6 "Refactor auth module"
-pithosai --cursor opus-4.6 "Design a database schema"
-pithosai --cursor gpt-5.2 "Write unit tests"
+pithosai --mode dialog "Explain this error"
+pithosai --mode plan "Outline the next sprint"
 ```
 
-**Available models:**
-
-| Model id | Description |
-|----------|-------------|
-| `auto` | Cursor's default model selection |
-| `sonnet-4.6` | Claude Sonnet 4.6 |
-| `sonnet-4.6-thinking` | Claude Sonnet 4.6 with extended thinking |
-| `opus-4.6` | Claude Opus 4.6 |
-| `gpt-5.2` | GPT 5.2 |
-
-Any model id supported by `cursor-agent --list-models` can be used; the above are pre-defined with metadata. Unknown ids are passed through to `cursor-agent` as-is.
+Result previews (terminal or optional Chrome via Playwright) can be tuned with `PITHOSAI_SKIP_RESULT_BROWSER`, `PITHOSAI_RESULT_BROWSER`, and `PITHOSAI_PLAYWRIGHT_CHANNEL`. Details: [Configuration](https://gitee.com/sihuic/pithosai/blob/master/docs/Configuration.md) (repository).
 
 ---
 
-## Heartbeat
-
-Heartbeat polls the role's email inbox for **task emails** (subjects starting with `task:` or `任务：`), enqueues them, and runs the agent on one task per tick. State (processed IDs and unprocessed queue) is stored in `~/.pithosai/heartbeat-state.json` and is keyed by role and optionally by project.
+## Common commands
 
-**Requirements:** The role must have IMAP/SMTP configured in `.settings.json` (see `roles.<role>.imap` and `roles.<role>.smtp`). After each task the agent sends a reply email: on success to the task sender; on failure to the support address (see `SUPPORT_EMAIL` below).
+| Command | What it does |
+|---------|----------------|
+| `pithosai init [dir]` | Scaffold project, `.pithosai/sessions/`, settings. |
+| `pithosai add-role <role>` | Add a role to the project. |
+| `pithosai task --file <md>` | Watch a task file and run tasks sequentially. |
+| `pithosai memorize --start … --end … -r <role>` | Build `.pithosai/<role>/memory.md` from stored tasks. |
+| `pithosai heartbeat` / `heartbeat --once` | Email-driven task pipeline (needs IMAP/SMTP in settings). |
+| `pithosai skills …` | Install / list / remove skills (see repo docs). |
+| `pithosai show-prompt` | Print or preview the system prompt for debugging. |
+| `pithosai shell "cmd"` | Run a shell command via the CLI. |
 
-- **One tick (fetch + process one task, then exit):**
-  ```bash
-  pithosai heartbeat --once
-  ```
-- **Continuous loop (poll every N seconds):**
-  ```bash
-  pithosai heartbeat
-  pithosai heartbeat --interval 120
-  ```
-
-You can pass `-C`, `-r`, `-l`, `--reasoner`, `--chat`, `--cursor`, `--timeout`, etc. as with other commands. Programmatic API: `heartbeatTick(cwd, runOpts)` runs one tick and returns `{ processedCount, ranOne, unprocessedCount }`; `heartbeatLoop(cwd, opts)` runs the loop with `opts.intervalSeconds` (default 60).
+Use **`pithosai --help`** and **`pithosai <command> --help`** for flags (`--timeout`, `--lang`, `--role`, `--log-path`, etc.).
 
 ---
 
-## Skills Management
-
-Install, list, and remove AI skills from Clawhub AI. Skills are stored in `.pithosai/skills/` and can be used by agents via the `read_skill` tool. `clawhub install` output and install/list status messages are written to **stdout** / **stderr** in the terminal (not only to the log file).
-
-**Requirements:** ScraperAPI account and API key (set as `SCRAPERAPI_API_KEY` environment variable).
+## Interactive session (short)
 
-- **Install skills:**
-  ```bash
-  pithosai skills install
-  pithosai skills install greet --api-key your_key
-  pithosai skills install --force --url https://custom-skills.example.com
-  ```
-- **List installed skills:**
-  ```bash
-  pithosai skills list
-  pithosai skills list -l zh
-  ```
-- **Remove skill:**
-  ```bash
-  pithosai skills remove greet
-  ```
-
-See [Skills CLI Documentation](docs/SKILLS-CLI.md) for complete usage.
+In a normal terminal, the default UI uses a **full-screen TUI** (bottom input, scrolling transcript). **`Ctrl+S`** stops a run; **`Ctrl+P`** pauses. Slash commands include `/shell`, `/list`, `/show-task`, `/show-prompt`, and skill helpers. Set **`PITHOSAI_NO_TUI=1`** for a classic line-based prompt (e.g. scripts or minimal terminals).
 
 ---
 
-## Skill Conversion
-
-Automatically convert frequently used skills into permanent tools for better performance and reliability. The system monitors skill usage, analyzes patterns, and generates optimized tool implementations.
-
-**Features:**
-- **Usage Tracking**: Automatically records skill executions, parameters, and success rates
-- **Pattern Analysis**: Identifies common parameter combinations and usage patterns
-- **Smart Conversion**: Suggests when skills are ready for conversion based on usage statistics
-- **Tool Generation**: Creates optimized JavaScript tools with proper parameter validation
-- **Performance Boost**: Converted tools run 50-80% faster than skill-based execution
-
-**Usage:**
-
-- **List convertible skills:**
-  ```bash
-  pithosai skill-convert list
-  pithosai skill-convert list --threshold 70
-  ```
-
-- **Convert a skill:**
-  ```bash
-  pithosai skill-convert convert screenshot
-  pithosai skill-convert convert screenshot --dry-run  # Preview conversion
-  pithosai skill-convert convert screenshot --force    # Force re-conversion
-  ```
-
-- **View statistics:**
-  ```bash
-  pithosai skill-convert stats
-  pithosai skill-convert stats --skill screenshot
-  ```
-
-- **Manage converted tools:**
-  ```bash
-  pithosai skill-convert tools list
-  pithosai skill-convert tools remove screenshot_tool
-  pithosai skill-convert tools enable/disable screenshot_tool
-  ```
-
-- **Clear records:**
-  ```bash
-  pithosai skill-convert clear screenshot
-  pithosai skill-convert clear --all
-  ```
-
-**How it works:**
-1. When you use skills via `read_skill`, the system tracks each execution
-2. After sufficient usage (minimum 3 successful executions), skills become eligible for conversion
-3. The system analyzes parameter patterns and generates optimized tool code
-4. Converted tools are stored in `.pithosai/custom-tools/` and automatically loaded
-5. Future requests use the optimized tool instead of reading skill documentation
-
-**Example workflow:**
-```bash
-# 1. Use a skill multiple times
-pithosai "Take a screenshot of the terminal"
-pithosai "Capture the browser window after 2 seconds"
-pithosai "Take a screenshot of a specific region"
-
-# 2. Check if it's ready for conversion
-pithosai skill-convert list
+## Environment variables (essentials)
 
-# 3. Convert to permanent tool
-pithosai skill-convert convert screenshot
-
-# 4. Use the optimized tool directly
-# (The agent will now use screenshot_tool instead of read_skill screenshot)
-pithosai "Take another screenshot with delay"
-```
+| Variable | Role |
+|----------|------|
+| `CURSOR_MODEL`, `CURSOR_AGENT_BIN` | Cursor CLI integration |
+| `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY` | API providers |
+| `PITHOSAI_DB_PATH` | SQLite DB path (default `~/.pithosai/pithosai.db`) |
+| `PITHOSAI_SKIP_RESULT_BROWSER` | Skip markdown preview (e.g. CI) |
+| `PITHOSAI_RESULT_BROWSER` | `chrome` for Playwright browser preview |
+| `PITHOSAI_TIMEOUT_MS` / `--timeout` | Run time limits |
+| `SCRAPERAPI_API_KEY` | Used by skills / some tools |
 
-See [Skill-to-Tool Design](docs/SKILL-TO-TOOL-DESIGN.md) for technical details.
+A longer list (history limits, security hooks, debug) lives in the [Configuration](https://gitee.com/sihuic/pithosai/blob/master/docs/Configuration.md) doc in the repository.
 
 ---
 
-## Shell Command
+## Documentation and source
 
-Execute shell commands directly or from interactive mode. Useful for file operations, git commands, and system tasks.
+The **npm package** contains the built CLI and runtime assets. **Markdown guides** (architecture, skills, shell, troubleshooting) are maintained in the repository:
 
-- **Standalone command:**
-  ```bash
-  pithosai shell "ls -la"
-  pithosai shell "git status" --cwd ./my-project
-  pithosai shell "npm test" --timeout 60
-  pithosai shell --raw "echo hello"
-  ```
-- **Interactive mode:**
-  ```
-  You: /shell ls -la
-  ```
-  Use `/shell` prefix in interactive sessions to run shell commands.
+| Doc | Link |
+|-----|------|
+| Changelog | [CHANGELOG.md](CHANGELOG.md) (included in package) |
+| Architecture | [docs/ARCHITECTURE.md](https://gitee.com/sihuic/pithosai/blob/master/docs/ARCHITECTURE.md) |
+| Configuration | [docs/Configuration.md](https://gitee.com/sihuic/pithosai/blob/master/docs/Configuration.md) |
+| Troubleshooting | [docs/TROUBLESHOOTING.md](https://gitee.com/sihuic/pithosai/blob/master/docs/TROUBLESHOOTING.md) |
+| Skills CLI | [docs/SKILLS-CLI.md](https://gitee.com/sihuic/pithosai/blob/master/docs/SKILLS-CLI.md) |
+| Shell CLI | [docs/SHELL-CLI.md](https://gitee.com/sihuic/pithosai/blob/master/docs/SHELL-CLI.md) |
 
-See [Shell CLI Documentation](docs/SHELL-CLI.md) for complete usage.
+**Repository:** [gitee.com/sihuic/pithosai](https://gitee.com/sihuic/pithosai)
 
 ---
 
-## Commands and options
-
-| Command / option | Description |
-|------------------|-------------|
-| `pithosai [request]` | Run the agent for `request`. Omit to show help (or use `-i` for interactive mode). |
-| `pithosai init [dir]` | Create project: scaffold by type/role, `.pithosai/sessions/`, and settings. Prompts loaded from SQLite at runtime. |
-| `pithosai add-role <role>` | Add role: create `.pithosai/<role>/` if missing and update `supportedRoles`. |
-| `pithosai skills` | Manage skills from Clawhub AI (install, list, remove). |
-| `pithosai skill-convert` | Convert successful skills to permanent tools (monitor usage, analyze patterns, generate tools). |
-| `pithosai shell <command>` | Execute shell commands with timeout and formatting. |
-| `pithosai task` | Watch a task markdown file and process tasks sequentially (`processing` first, then `pending`). |
-| `pithosai heartbeat` | Poll inbox for task emails (`task:...` / `任务：...`), enqueue and run one per tick. State in `~/.pithosai/heartbeat-state.json`. |
-| `pithosai heartbeat --once` | Run one tick (fetch emails, process one task if any) then exit. |
-| `pithosai heartbeat --interval <seconds>` | Poll interval in seconds (default: 60). |
-| `pithosai show-prompt` | Display the system prompt that would be used for a run. Options: `--mode <agent|dialog|plan>`, `--raw` (show before truncation), `--truncated` (show truncated version). |
-| `-i, --interactive` | Start in interactive mode without a request; load latest session and prompt. |
-| `--no-interactive` | After running a request, do not prompt for more (one-shot). |
-| `-C, --cwd <dir>` | Project directory (default: current directory). |
-| `-l, --lang <lang>` | Language for prompts and init (e.g. `en`, `zh`). |
-| `-r, --role <role>` | Role/template set (e.g. `RD`, `CO`). |
-| `--timeout <seconds>` | Max agent run time (default: 1800). |
-| `--cursor [model]` | Use Cursor CLI model (no API key; auth via `cursor-agent login`). Optional model: `auto`, `sonnet-4.6`, `opus-4.6`, `gpt-5.2`. If model is omitted, use `pithosai "<request>" --cursor` (or `--cursor -- "<request>"`) to avoid argument ambiguity. |
-| `--reasoner` | Use DeepSeek Reasoner (thinking) model. |
-| `--chat` | Use DeepSeek Chat model (general chat). |
-| `--no-markdown` | Disable terminal markdown rendering and print plain text only. |
-| `--skills-dir <dir>` | Directory for `read_skill` (default: `./.pithosai/skills` or `PITHOSAI_SKILLS_DIR`). |
-| `--log-path <file>` | Log file path (default: `<project>/logs/pithosai.log`). |
-
----
-
-## Environment variables
-
-| Variable | Description |
-|----------|-------------|
-| `CURSOR_MODEL` | Cursor CLI model id (e.g. `auto`, `sonnet-4.6`, `opus-4.6`, `gpt-5.2`). No API key needed — uses `cursor-agent login` auth. |
-| `CURSOR_AGENT_BIN` | Path to `cursor-agent` binary (default: `cursor-agent` on `PATH`). |
-| `DEEPSEEK_API_KEY` | API key for DeepSeek (Coder / Chat / Reasoner). |
-| `OPENROUTER_API_KEY` | API key when using OpenRouter. |
-| `SCRAPERAPI_API_KEY` | API key for ScraperAPI (used by skills command and proxy downloader). |
-| `PITHOSAI_TIMEOUT_MS` | Max run time in milliseconds (overrides `--timeout` when set). |
-| `PITHOSAI_SKILLS_DIR` | Default skills directory for `read_skill`. |
-| `PITHOSAI_RESULT_BROWSER` | Result viewer selection. Default: **pi-tui** full-screen markdown viewer. Set to `chrome` to use Playwright browser preview. |
-| `PITHOSAI_PLAYWRIGHT_CHANNEL` | Playwright browser channel for Chrome preview mode (e.g. `chrome`, `msedge`, `chrome-beta`, `bundled`). |
-| `PITHOSAI_SKIP_RESULT_BROWSER` | Set to `1` to skip result preview and print markdown in terminal instead. |
-| `PITHOSAI_DEBUG_STREAM` | Set to `1` to log stream completion (for troubleshooting hangs). |
-| `PITHOSAI_DEBUG_HOOKS` | Set to `1` to enable debug hook handlers (logging, performance, stats). |
-| `PITHOSAI_SECURITY_HOOKS` | Set to `1` to enable security hook handlers (tool blocking, sensitive-info detection). |
-| `PITHOSAI_BLOCKED_TOOLS` | Comma-separated list of tool names to block (requires `PITHOSAI_SECURITY_HOOKS=1`). |
-| `PITHOSAI_DB_PATH` | Override SQLite database path (default: `~/.pithosai/pithosai.db`). |
-| `SUPPORT_EMAIL` | When a heartbeat task fails, the failure reply is sent to this address instead of the customer. Default: `support@pithosai.com`. |
-| `PITHOSAI_MAX_MESSAGE_TOKENS` | Max tokens for conversation messages before compression (defaults to model context minus reserved system tokens). |
-| `PITHOSAI_MAX_HISTORY_MESSAGES` | Max number of recent messages kept before earlier history is dropped (default: 40). |
-| `PITHOSAI_MIN_HISTORY_MESSAGES` | Minimum number of recent messages to keep when aggressively compacting history (default: 10). |
-| `PITHOSAI_MAX_TOOL_RESULT_CHARS` | Max characters per tool result string before truncation (default: 8000). |
-| `PITHOSAI_MIN_TOOL_RESULT_CHARS` | Minimum characters per tool result when aggressively truncating tool outputs (default: 2000). |
-
----
-
-## Testing
-
-Unit tests use [Vitest](https://vitest.dev/). Run all tests:
-
-```bash
-npm test
-```
+## Docker
 
-Tests cover prompts (loader, validator), agent event handlers (message-utils, chat, reasoner), skills (loader, read-skill tool), init (scaffold, templates, init/add-role), models (DeepSeek config, Cursor config, resolution), utils (paths, path-utils, sleep, logger), settings (read/write and merge), heartbeat, and agent tools (common, web, list-files, playwright-markdown-preview, playwright-view-tool, email).
+To build an image from source, clone the repo and run `docker build -t pithosai .`. Do not mount the same directory you use for a normal (non-Docker) install.
 
 ---
 
-## Docs
+## Contributing
 
-- [Changelog](CHANGELOG.md) - Release history ([Keep a Changelog](https://keepachangelog.com/) style).
-- [Architecture](docs/ARCHITECTURE.md) - Layout, data flow, public API.
-- [Configuration](docs/Configuration.md) - Global and project config files (`~/.pithosai/heartbeat-state.json`, `.pithosai/sessions`, `.pithosai/<role>` prompts). In **agent** mode, `.pithosai/<role>/TOOLS.md` (or `TOOLS-zh.md`) can list allowed tools under `# pi-agent-tools` and `# pithosai tools`; if those sections are missing or empty, the full toolset is used. **Dialog** / **plan** modes do not apply this filter.
-- [Troubleshooting](docs/TROUBLESHOOTING.md) - Agent hangs, timeouts, stream debug.
-- [Tools loop](docs/TOOLS-LOOP.md) - How the agent uses tools.
+Clone the repo, run `npm install`, then `npm test`. Development uses the same `package.json`; publishing runs `npm run build` via `prepublishOnly`.
 
 ---
 

package/dist/935.cjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-"use strict";exports.ids=["935"],exports.modules={117(t,e,i){i.d(e,{showMarkdownInPiTui:()=>a});var s=i(895),l=i(950),r=i(168);let h=!1;class n{constructor(t){const{terminal:e,tui:i,markdown:s,hintText:l,documentTitle:r,onClose:h}=t;this.terminal=e,this.tui=i,this._markdown=s,this.hintText=l,this.documentTitle=r?.trim()||"",this.onClose=h,this.scrollTop=0,this._fullLines=null,this._cachedWidth=null,this._ggAwaitingSecondG=!1,this._ggTimer=null}clearGgPrefixState(){null!=this._ggTimer&&(clearTimeout(this._ggTimer),this._ggTimer=null),this._ggAwaitingSecondG=!1}invalidate(){this._markdown.invalidate(),this._fullLines=null,this._cachedWidth=null}handleInput(t){let e=this.terminal.columns,i=Math.max(1,this.terminal.rows-!!this.documentTitle-1),s=Math.max(0,this._getFullLines(e).length-i);if((0,r.matchesKey)(t,"escape")||(0,r.matchesKey)(t,"esc")||(0,r.matchesKey)(t,"q")||(0,r.matchesKey)(t,"shift+q")||(0,r.matchesKey)(t,"ctrl+c")){this.clearGgPrefixState(),this.onClose();return}if((0,r.matchesKey)(t,"shift+g")){this.clearGgPrefixState(),this.scrollTop=s;return}if((0,r.matchesKey)(t,"g")){if(this._ggAwaitingSecondG){this.clearGgPrefixState(),this.scrollTop=0;return}this._ggAwaitingSecondG=!0,null!=this._ggTimer&&clearTimeout(this._ggTimer),this._ggTimer=setTimeout(()=>{this._ggTimer=null,this._ggAwaitingSecondG=!1},500);return}if(this.clearGgPrefixState(),(0,r.matchesKey)(t,"up")||(0,r.matchesKey)(t,"k")){this.scrollTop=Math.max(0,this.scrollTop-1);return}if((0,r.matchesKey)(t,"down")||(0,r.matchesKey)(t,"j")){this.scrollTop=Math.min(s,this.scrollTop+1);return}if((0,r.matchesKey)(t,"pageUp")||(0,r.matchesKey)(t,"ctrl+u")){this.scrollTop=Math.max(0,this.scrollTop-i);return}if((0,r.matchesKey)(t,"pageDown")||(0,r.matchesKey)(t,"ctrl+d")){this.scrollTop=Math.min(s,this.scrollTop+i);return}if((0,r.matchesKey)(t,"home")){this.scrollTop=0;return}if((0,r.matchesKey)(t,"end")){this.scrollTop=s;return}}_getFullLines(t){return this._fullLines&&this._cachedWidth===t||(this._cachedWidth=t,this._fullLines=this._markdown.render(t)),this._fullLines}render(t){let e=this.terminal.rows,i=this.documentTitle?[s.bold.cyan((0,r.truncateToWidth)(this.documentTitle,t))]:[],l=Math.max(1,e-i.length-1);null!=this._cachedWidth&&this._cachedWidth!==t&&this.invalidate();let h=this._getFullLines(t),n=Math.max(0,h.length-l);this.scrollTop=Math.min(this.scrollTop,n);let a=h.slice(this.scrollTop,this.scrollTop+l);for(;a.length<l;)a.push("");return[...i,...a,s.dim((0,r.truncateToWidth)(this.hintText,t))]}}async function a(t){let{markdown:e,t:i,documentTitle:s,tuiSession:a=null}=t;if(!e||"string"!=typeof e||!e.trim())return;if(!(process.stdout.isTTY&&process.stdin.isTTY))return void process.stdout.write(`${e}
-`);let o=a&&"function"==typeof a.suspendForReadline&&"function"==typeof a.resumeFromReadline;o&&a.suspendForReadline();try{h||((0,l.CK)("dark"),h=!0);let t=(0,l.pd)(),a=new r.Markdown(e,1,1,t),o=i("cli.resultPreviewTerminalHint"),c=new r.ProcessTerminal,u=new r.TUI(c);u.setClearOnShrink(!0),await new Promise(t=>{let e,i=new n({terminal:c,tui:u,markdown:a,hintText:o,documentTitle:s,onClose:()=>{e?.clearGgPrefixState(),u.stop(),t()}});e=i;let l=new r.Container;l.addChild(i),u.addChild(l),u.setFocus(i),u.start(),u.requestRender(!0)})}finally{o&&a.resumeFromReadline()}}}};
+"use strict";exports.ids=["935"],exports.modules={117(t,e,i){i.d(e,{showMarkdownInPiTui:()=>a});var s=i(691),l=i(950),r=i(168);let h=!1;class n{constructor(t){const{terminal:e,tui:i,markdown:s,hintText:l,documentTitle:r,onClose:h}=t;this.terminal=e,this.tui=i,this._markdown=s,this.hintText=l,this.documentTitle=r?.trim()||"",this.onClose=h,this.scrollTop=0,this._fullLines=null,this._cachedWidth=null,this._ggAwaitingSecondG=!1,this._ggTimer=null}clearGgPrefixState(){null!=this._ggTimer&&(clearTimeout(this._ggTimer),this._ggTimer=null),this._ggAwaitingSecondG=!1}invalidate(){this._markdown.invalidate(),this._fullLines=null,this._cachedWidth=null}handleInput(t){let e=this.terminal.columns,i=Math.max(1,this.terminal.rows-!!this.documentTitle-1),s=Math.max(0,this._getFullLines(e).length-i);if((0,r.matchesKey)(t,"escape")||(0,r.matchesKey)(t,"esc")||(0,r.matchesKey)(t,"q")||(0,r.matchesKey)(t,"shift+q")||(0,r.matchesKey)(t,"ctrl+c")){this.clearGgPrefixState(),this.onClose();return}if((0,r.matchesKey)(t,"shift+g")){this.clearGgPrefixState(),this.scrollTop=s;return}if((0,r.matchesKey)(t,"g")){if(this._ggAwaitingSecondG){this.clearGgPrefixState(),this.scrollTop=0;return}this._ggAwaitingSecondG=!0,null!=this._ggTimer&&clearTimeout(this._ggTimer),this._ggTimer=setTimeout(()=>{this._ggTimer=null,this._ggAwaitingSecondG=!1},500);return}if(this.clearGgPrefixState(),(0,r.matchesKey)(t,"up")||(0,r.matchesKey)(t,"k")){this.scrollTop=Math.max(0,this.scrollTop-1);return}if((0,r.matchesKey)(t,"down")||(0,r.matchesKey)(t,"j")){this.scrollTop=Math.min(s,this.scrollTop+1);return}if((0,r.matchesKey)(t,"pageUp")||(0,r.matchesKey)(t,"ctrl+u")){this.scrollTop=Math.max(0,this.scrollTop-i);return}if((0,r.matchesKey)(t,"pageDown")||(0,r.matchesKey)(t,"ctrl+d")){this.scrollTop=Math.min(s,this.scrollTop+i);return}if((0,r.matchesKey)(t,"home")){this.scrollTop=0;return}if((0,r.matchesKey)(t,"end")){this.scrollTop=s;return}}_getFullLines(t){return this._fullLines&&this._cachedWidth===t||(this._cachedWidth=t,this._fullLines=this._markdown.render(t)),this._fullLines}render(t){let e=this.terminal.rows,i=this.documentTitle?[s.m.bold.cyan((0,r.truncateToWidth)(this.documentTitle,t))]:[],l=Math.max(1,e-i.length-1);null!=this._cachedWidth&&this._cachedWidth!==t&&this.invalidate();let h=this._getFullLines(t),n=Math.max(0,h.length-l);this.scrollTop=Math.min(this.scrollTop,n);let a=h.slice(this.scrollTop,this.scrollTop+l);for(;a.length<l;)a.push("");return[...i,...a,s.m.dim((0,r.truncateToWidth)(this.hintText,t))]}}async function a(t){let{markdown:e,t:i,documentTitle:s,tuiSession:a=null}=t;if(!e||"string"!=typeof e||!e.trim())return;if(!(process.stdout.isTTY&&process.stdin.isTTY))return void process.stdout.write(`${e}
+`);let o=a&&"function"==typeof a.suspendForReadline&&"function"==typeof a.resumeFromReadline;o&&a.suspendForReadline();try{h||((0,l.CK)("dark"),h=!0);let t=(0,l.pd)(),a=new r.Markdown(e,1,1,t),o=i("cli.resultPreviewTerminalHint"),c=new r.ProcessTerminal,m=new r.TUI(c);m.setClearOnShrink(!0),await new Promise(t=>{let e,i=new n({terminal:c,tui:m,markdown:a,hintText:o,documentTitle:s,onClose:()=>{e?.clearGgPrefixState(),m.stop(),t()}});e=i;let l=new r.Container;l.addChild(i),m.addChild(l),m.setFocus(i),m.start(),m.requestRender(!0)})}finally{o&&a.resumeFromReadline()}}}};