paimon 0.2.7__tar.gz → 0.3.0__tar.gz

paimon-0.3.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: paimon
+Version: 0.3.0
+Summary: A minimal code agent built on pydantic-ai + textual
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: genai-prices>=0.1.6
+Requires-Dist: pydantic-ai-slim[anthropic,google,openai]>=2.54.0
+Requires-Dist: textual>=8.2.7
+Requires-Dist: textual-serve>=1.1.3
+Requires-Dist: pyyaml>=6
+Requires-Dist: pydantic>=2.10
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: ddgs>=9
+Requires-Dist: pydantic-monty<2,>=1.0
+Dynamic: license-file
+
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+English | [简体中文](README.zh-CN.md)
+
+Paimon is a coding agent that lives in your terminal. It reads and edits files in the current directory and runs commands. It also runs headless and imports as a library, so a stronger agent or a program of your own can drive it.
+
+## Install
+
+```bash
+uv tool install paimon   # or: pip install paimon
+```
+
+## Getting started
+
+```bash
+paimon
+```
+
+Or run it without installing anything:
+
+```bash
+uvx paimon
+```
+
+The first launch asks for a provider, its API base and key, then a model. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
+
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** only reads, **auto** edits inside the working directory and has a second model call approve everything else, **yolo** checks nothing and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
+
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. `Ctrl+L` returns keyboard focus to the current pane's input or pending answer. The status bar identifies input, reading, and answer focus; pane switches preserve reading focus, and background completion does not steal the keyboard. Paimon can work in parallel: ask for two independent things and it starts a second agent in a tab of its own, where you can watch it work and answer what it asks, and whose answer comes back into the conversation when it is done. Closing the tab stops it. It can also leave a command running in a tab, a dev server or a watcher, instead of holding up a turn.
+
+## Web search
+
+Paimon can search the web without an API key. It asks in no permission mode, because a search changes nothing on your machine. Searches go through [ddgs](https://github.com/deedy5/ddgs), a metasearch library, so a query may be sent to any of several public search engines. `--no-web-search` takes the tool away for a run.
+
+## Skills
+
+Paimon loads [Agent Skills](https://agentskills.io) from `~/.config/paimon/skills`, `~/.agents/skills` and every `.agents/skills` from the working directory up to the repository root. Only each skill's name and description go into the system prompt; the model reads the `SKILL.md` when a task matches, and `/skill:name args` sends it explicitly (the `/` command palette lists them). More locations go in `config.json` as `"skills": ["~/.claude/skills"]` or on the command line with `--skill PATH`; `--no-skills` skips the default locations. When two skills share a name, explicit paths beat the project's, which beat the global ones.
+
+## Using Paimon as a subagent
+
+Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. Log in to that model's provider once, then name the model on each run:
+
+```bash
+paimon login zai --api-key-env ZAI_API_KEY
+paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result
+```
+
+The bundled skill teaches the calling agent this workflow:
+
+```bash
+paimon install-skill                  # into Claude Code (~/.claude/skills/paimon)
+paimon install-skill --target codex   # into Codex; --dest DIR for anywhere else
+npx skills add aisk/paimon            # the same skill, via skills.sh
+```
+
+## Using Paimon as a library
+
+The agent loop is importable, so a Python program can drive it without going through the CLI. `Agent.open()` starts or resumes a session and `agent.run_until_idle()` yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes. It returns once the agent is done, including any agents it started along the way: their answers come back later, and it runs the model again on each of them until nothing is left running:
+
+```python
+import asyncio
+
+from paimon.agent import Agent
+from paimon.events import TextDelta
+
+async def main():
+    agent = Agent.open(mode="auto")
+    async for event in agent.run_until_idle("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`agent.run()` runs exactly one turn and returns with those agents possibly still at work; it is the call for a program that wants to decide itself when to run the model again, with `agent.run(None)`. An agent runs one turn or compaction at a time, and starting a second while one is under way raises `AgentBusyError`.
+
+`Agent.open()` also takes a working directory, an async `confirm` callback for the permission prompts that are left, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
+
+## Sessions
+
+Every conversation is saved, and long ones are summarized in place near the context limit. Paimon prints the command that brings a session back when you leave:
+
+```bash
+paimon -r            # choose a session started in this directory
+paimon -r a1b2c3     # resume one by id
+paimon -c            # resume the most recent one
+paimon sessions      # list them (--json for machines)
+paimon log a1b2c3    # what a session did, one line per event
+```
+
+## Other ways to run it
+
+```bash
+paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
+paimon --strict                     # hold every command, even read-only ones
+paimon --no-web-search              # take the web search tool away for this run
+paimon --no-code-mode               # take the run_code tool away (or "code_mode": false in config.json)
+paimon --web                        # the same UI in a browser (--port, default 8000)
+paimon -p "what does cli.py do?"    # one answer on stdout, no UI
+cat log.txt | paimon -p "summarize this"
+paimon --model zai:glm-4.7          # this model for this run only
+```
+
+`-p` never stops to ask, so with the default `yolo` mode it can already write files and run commands. Add `--output-format result` for a single JSON object with the outcome, which is what a calling program should read. `paimon --help` lists the rest.
+
+Inside a [Herdr](https://herdr.dev) pane the UI reports its state and resume command to Herdr on its own, with nothing to install. It also reports its state to the terminal itself with [OSC 7501](https://mitchellh.com/writing/program-status-osc7501), for terminals that show it.
+
+### Debugging the Textual UI
+
+Start with `paimon --textual-debug` (also works with `--web`) when Paimon needs to diagnose its own layout or styling. It is off by default. When enabled, the model receives five tools scoped to the live UI process:
+
+- `textual_inspect` queries the DOM by CSS selector and reports geometry, pseudo-classes, focus and computed CSS;
+- `textual_eval` / `textual_exec` run Python in the UI process, including private APIs, persistent variables and top-level `await`;
+- `textual_apply_css` layers on CSS and relayouts immediately;
+- `textual_screenshot` exports the current render to SVG.
+
+You can ask it, for example, to “find why `#prompt` is narrower than expected, try a live fix, and take a screenshot.” `textual_exec` deliberately provides unrestricted in-process Python and can change any Textual or Paimon state. Use this development option only with trusted prompts. Live changes last only until exit; after confirming a fix, ask Paimon to edit the source.
+
+## Configuration
+
+Model settings are kept in `~/.config/paimon/config.json`, written by the first launch or by `paimon login`. Each provider keeps its own credentials, and `paimon model provider:name` or Switch model in the command palette picks the model to run on. A ChatGPT plan works in place of an API key: `paimon login chatgpt` signs in through the browser. `paimon login antigravity` does the same for an Antigravity plan, which Google does not support outside Antigravity: Paimon signs in as the Antigravity client and calls an internal endpoint, so the account may be limited or closed, and the risk is yours. Sessions live in `~/.local/share/paimon/sessions/`.
+
+Read and auto modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) on their own; `--strict` turns that off. On Windows commands run in Git Bash, found through `git` on your PATH or the standard install locations; without Git for Windows they run in cmd.exe, and then none are recognized. Read mode refuses everything else. Auto mode asks a reviewer model, which sees your messages and the agent's tool calls but not its reasoning or any tool output, and answers allow or block. It asks you instead when the reviewer cannot be reached or has blocked three calls in a row, and under `-p` those are refusals. Current models review with their provider's fast tier by default (GPT with Luna, Claude with Haiku, GLM with Flash) and the rest review with themselves; set `"review_model": "provider:name"` in the config to choose. **All of this is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+
+## Architecture
+
+`Agent.run` is a UI-agnostic stream of events; the TUI, `--web` and headless mode are three renderers over that one stream. An agent holds the subagents and background commands it starts. A subagent is another `Agent` running as a task in the same process, and its answer is delivered to its parent as a message. A UI that wants to show a job hooks `Agent.open_job`, which is how the TUI gives each one a pane.
+
+```mermaid
+flowchart TD
+    subgraph entry["Entry points"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / model / sessions"]
+        Headless["headless.py<br/>-p, one-shot"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI widgets"]
+        Pane["pane.py<br/>SessionPane"]
+        AgentPane["agentpane.py<br/>subagent pane"]
+        CommandPane["commandpane.py<br/>background command pane"]
+        Transcript["transcript.py<br/>conversation log, event renderer"]
+        Tabs["tabs.py<br/>pane strip"]
+        Login["login.py<br/>provider / key"]
+        UIWidgets["ui.py<br/>prompt input, confirmations"]
+        Diff["diff.py<br/>side-by-side diff rendering"]
+    end
+
+    subgraph core["Agent loop"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools/<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        JobMgr["jobs.py<br/>subagents, background commands"]
+        Jobs["turns.py<br/>turn driver"]
+    end
+
+    subgraph support["Config & skills"]
+        Config["config.py<br/>settings, credentials"]
+        Skills["skills.py<br/>Agent Skills discovery"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> AgentPane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Config
+
+    Pane --> Jobs
+    Pane --> AgentLoop
+    Pane --> Diff
+    Pane --> Transcript
+    Pane --> UIWidgets
+    Pane --> LLM
+    AgentPane --> Pane
+    AgentPane --> Transcript
+    CommandPane --> Pane
+    Transcript --> UIWidgets
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop --> JobMgr
+    JobMgr -. "spawn_agent" .-> AgentLoop
+    JobMgr -. "spawn_agent" .-> AgentPane
+    JobMgr -. "run_background" .-> CommandPane
+
+    PromptMod --> Skills
+
+    Jobs --> AgentLoop
+
+    Skills --> Config
+    Config --> LLM
+```
+
+## Telemetry
+
+Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name, the language from `LC_ALL`/`LANG`, whether this is the first launch, and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

paimon-0.3.0/README.md

@@ -0,0 +1,218 @@
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+English | [简体中文](README.zh-CN.md)
+
+Paimon is a coding agent that lives in your terminal. It reads and edits files in the current directory and runs commands. It also runs headless and imports as a library, so a stronger agent or a program of your own can drive it.
+
+## Install
+
+```bash
+uv tool install paimon   # or: pip install paimon
+```
+
+## Getting started
+
+```bash
+paimon
+```
+
+Or run it without installing anything:
+
+```bash
+uvx paimon
+```
+
+The first launch asks for a provider, its API base and key, then a model. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
+
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** only reads, **auto** edits inside the working directory and has a second model call approve everything else, **yolo** checks nothing and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
+
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. `Ctrl+L` returns keyboard focus to the current pane's input or pending answer. The status bar identifies input, reading, and answer focus; pane switches preserve reading focus, and background completion does not steal the keyboard. Paimon can work in parallel: ask for two independent things and it starts a second agent in a tab of its own, where you can watch it work and answer what it asks, and whose answer comes back into the conversation when it is done. Closing the tab stops it. It can also leave a command running in a tab, a dev server or a watcher, instead of holding up a turn.
+
+## Web search
+
+Paimon can search the web without an API key. It asks in no permission mode, because a search changes nothing on your machine. Searches go through [ddgs](https://github.com/deedy5/ddgs), a metasearch library, so a query may be sent to any of several public search engines. `--no-web-search` takes the tool away for a run.
+
+## Skills
+
+Paimon loads [Agent Skills](https://agentskills.io) from `~/.config/paimon/skills`, `~/.agents/skills` and every `.agents/skills` from the working directory up to the repository root. Only each skill's name and description go into the system prompt; the model reads the `SKILL.md` when a task matches, and `/skill:name args` sends it explicitly (the `/` command palette lists them). More locations go in `config.json` as `"skills": ["~/.claude/skills"]` or on the command line with `--skill PATH`; `--no-skills` skips the default locations. When two skills share a name, explicit paths beat the project's, which beat the global ones.
+
+## Using Paimon as a subagent
+
+Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. Log in to that model's provider once, then name the model on each run:
+
+```bash
+paimon login zai --api-key-env ZAI_API_KEY
+paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result
+```
+
+The bundled skill teaches the calling agent this workflow:
+
+```bash
+paimon install-skill                  # into Claude Code (~/.claude/skills/paimon)
+paimon install-skill --target codex   # into Codex; --dest DIR for anywhere else
+npx skills add aisk/paimon            # the same skill, via skills.sh
+```
+
+## Using Paimon as a library
+
+The agent loop is importable, so a Python program can drive it without going through the CLI. `Agent.open()` starts or resumes a session and `agent.run_until_idle()` yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes. It returns once the agent is done, including any agents it started along the way: their answers come back later, and it runs the model again on each of them until nothing is left running:
+
+```python
+import asyncio
+
+from paimon.agent import Agent
+from paimon.events import TextDelta
+
+async def main():
+    agent = Agent.open(mode="auto")
+    async for event in agent.run_until_idle("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`agent.run()` runs exactly one turn and returns with those agents possibly still at work; it is the call for a program that wants to decide itself when to run the model again, with `agent.run(None)`. An agent runs one turn or compaction at a time, and starting a second while one is under way raises `AgentBusyError`.
+
+`Agent.open()` also takes a working directory, an async `confirm` callback for the permission prompts that are left, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
+
+## Sessions
+
+Every conversation is saved, and long ones are summarized in place near the context limit. Paimon prints the command that brings a session back when you leave:
+
+```bash
+paimon -r            # choose a session started in this directory
+paimon -r a1b2c3     # resume one by id
+paimon -c            # resume the most recent one
+paimon sessions      # list them (--json for machines)
+paimon log a1b2c3    # what a session did, one line per event
+```
+
+## Other ways to run it
+
+```bash
+paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
+paimon --strict                     # hold every command, even read-only ones
+paimon --no-web-search              # take the web search tool away for this run
+paimon --no-code-mode               # take the run_code tool away (or "code_mode": false in config.json)
+paimon --web                        # the same UI in a browser (--port, default 8000)
+paimon -p "what does cli.py do?"    # one answer on stdout, no UI
+cat log.txt | paimon -p "summarize this"
+paimon --model zai:glm-4.7          # this model for this run only
+```
+
+`-p` never stops to ask, so with the default `yolo` mode it can already write files and run commands. Add `--output-format result` for a single JSON object with the outcome, which is what a calling program should read. `paimon --help` lists the rest.
+
+Inside a [Herdr](https://herdr.dev) pane the UI reports its state and resume command to Herdr on its own, with nothing to install. It also reports its state to the terminal itself with [OSC 7501](https://mitchellh.com/writing/program-status-osc7501), for terminals that show it.
+
+### Debugging the Textual UI
+
+Start with `paimon --textual-debug` (also works with `--web`) when Paimon needs to diagnose its own layout or styling. It is off by default. When enabled, the model receives five tools scoped to the live UI process:
+
+- `textual_inspect` queries the DOM by CSS selector and reports geometry, pseudo-classes, focus and computed CSS;
+- `textual_eval` / `textual_exec` run Python in the UI process, including private APIs, persistent variables and top-level `await`;
+- `textual_apply_css` layers on CSS and relayouts immediately;
+- `textual_screenshot` exports the current render to SVG.
+
+You can ask it, for example, to “find why `#prompt` is narrower than expected, try a live fix, and take a screenshot.” `textual_exec` deliberately provides unrestricted in-process Python and can change any Textual or Paimon state. Use this development option only with trusted prompts. Live changes last only until exit; after confirming a fix, ask Paimon to edit the source.
+
+## Configuration
+
+Model settings are kept in `~/.config/paimon/config.json`, written by the first launch or by `paimon login`. Each provider keeps its own credentials, and `paimon model provider:name` or Switch model in the command palette picks the model to run on. A ChatGPT plan works in place of an API key: `paimon login chatgpt` signs in through the browser. `paimon login antigravity` does the same for an Antigravity plan, which Google does not support outside Antigravity: Paimon signs in as the Antigravity client and calls an internal endpoint, so the account may be limited or closed, and the risk is yours. Sessions live in `~/.local/share/paimon/sessions/`.
+
+Read and auto modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) on their own; `--strict` turns that off. On Windows commands run in Git Bash, found through `git` on your PATH or the standard install locations; without Git for Windows they run in cmd.exe, and then none are recognized. Read mode refuses everything else. Auto mode asks a reviewer model, which sees your messages and the agent's tool calls but not its reasoning or any tool output, and answers allow or block. It asks you instead when the reviewer cannot be reached or has blocked three calls in a row, and under `-p` those are refusals. Current models review with their provider's fast tier by default (GPT with Luna, Claude with Haiku, GLM with Flash) and the rest review with themselves; set `"review_model": "provider:name"` in the config to choose. **All of this is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+
+## Architecture
+
+`Agent.run` is a UI-agnostic stream of events; the TUI, `--web` and headless mode are three renderers over that one stream. An agent holds the subagents and background commands it starts. A subagent is another `Agent` running as a task in the same process, and its answer is delivered to its parent as a message. A UI that wants to show a job hooks `Agent.open_job`, which is how the TUI gives each one a pane.
+
+```mermaid
+flowchart TD
+    subgraph entry["Entry points"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / model / sessions"]
+        Headless["headless.py<br/>-p, one-shot"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI widgets"]
+        Pane["pane.py<br/>SessionPane"]
+        AgentPane["agentpane.py<br/>subagent pane"]
+        CommandPane["commandpane.py<br/>background command pane"]
+        Transcript["transcript.py<br/>conversation log, event renderer"]
+        Tabs["tabs.py<br/>pane strip"]
+        Login["login.py<br/>provider / key"]
+        UIWidgets["ui.py<br/>prompt input, confirmations"]
+        Diff["diff.py<br/>side-by-side diff rendering"]
+    end
+
+    subgraph core["Agent loop"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools/<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        JobMgr["jobs.py<br/>subagents, background commands"]
+        Jobs["turns.py<br/>turn driver"]
+    end
+
+    subgraph support["Config & skills"]
+        Config["config.py<br/>settings, credentials"]
+        Skills["skills.py<br/>Agent Skills discovery"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> AgentPane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Config
+
+    Pane --> Jobs
+    Pane --> AgentLoop
+    Pane --> Diff
+    Pane --> Transcript
+    Pane --> UIWidgets
+    Pane --> LLM
+    AgentPane --> Pane
+    AgentPane --> Transcript
+    CommandPane --> Pane
+    Transcript --> UIWidgets
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop --> JobMgr
+    JobMgr -. "spawn_agent" .-> AgentLoop
+    JobMgr -. "spawn_agent" .-> AgentPane
+    JobMgr -. "run_background" .-> CommandPane
+
+    PromptMod --> Skills
+
+    Jobs --> AgentLoop
+
+    Skills --> Config
+    Config --> LLM
+```
+
+## Telemetry
+
+Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name, the language from `LC_ALL`/`LANG`, whether this is the first launch, and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

{paimon-0.2.7 → paimon-0.3.0}/README.zh-CN.md

@@ -24,11 +24,11 @@ paimon
 uvx paimon
 ```
 
-首次启动会询问 provider、模型、API base 和 key。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
+首次启动会询问 provider 及其 API base 和 key，然后选择模型。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
 
-运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。以 `!` 开头的一行不发给模型，而是直接在 shell 里执行，输出 Paimon 也能看到。`!!` 则不告诉它。
+运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 只读，**auto** 放行工作目录内的编辑，其余操作交给另一次模型调用审批，**yolo** 不做任何检查，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。以 `!` 开头的一行不发给模型，而是直接在 shell 里执行，输出 Paimon 也能看到。`!!` 则不告诉它。
 
-`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 也能并行干活：让它同时做两件互不相干的事，它会在后台起第二个 agent，做完后结果会回到当前会话里。它也能把一条命令留在单独的 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
+`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane，`Ctrl+L` 将键盘焦点返回当前 pane 的输入框或待回答面板。状态栏会显示键盘当前在输入、阅读还是回答区域；切换 pane 会保留阅读焦点，后台任务完成不会抢走键盘。Paimon 也能并行干活：让它同时做两件互不相干的事，它会在单独的 tab 里起第二个 agent，你可以在那里看它干活、回答它的授权请求，做完后结果会回到当前会话里，关掉 tab 就是停掉它。它也能把一条命令留在 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
 
 ## 网页搜索
 
@@ -40,11 +40,11 @@ Paimon 会从 `~/.config/paimon/skills`、`~/.agents/skills` 以及工作目录
 
 ## 当作 subagent 使用
 
-前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。用一个 profile 单独保存该模型的账号：
+前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。先登录该模型的 provider，之后每次运行时指定模型：
 
 ```bash
-paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
-paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+paimon login zai --api-key-env ZAI_API_KEY
+paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result
 ```
 
 自带的 skill 会向调用方 agent 说明这套流程：
@@ -57,23 +57,26 @@ npx skills add aisk/paimon            # 通过 skills.sh 安装同一个 skill
 
 ## 当作库使用
 
-agent 循环本身是可以导入的，Python 程序不必经过 CLI 就能驱动它。`Agent.open()` 新建或恢复一个会话，`agent.run()` 产出类型化的事件，每段文本、每次工具调用、每个回合结束各一个，调用方自己决定怎么渲染或过滤：
+agent 循环本身是可以导入的，Python 程序不必经过 CLI 就能驱动它。`Agent.open()` 新建或恢复一个会话，`agent.run_until_idle()` 产出类型化的事件，每段文本、每次工具调用、每个回合结束各一个，调用方自己决定怎么渲染或过滤。它在 agent 做完之后才返回，包括它中途启动的其他 agent：这些 agent 的回答稍后才到，每到一个它就让模型再跑一轮，直到没有还在运行的为止：
 
 ```python
 import asyncio
 
-from paimon.agent import Agent, TextDelta
+from paimon.agent import Agent
+from paimon.events import TextDelta
 
 async def main():
-    agent = Agent.open(mode="edit")
-    async for event in agent.run("summarize the tests in this directory"):
+    agent = Agent.open(mode="auto")
+    async for event in agent.run_until_idle("summarize the tests in this directory"):
         if isinstance(event, TextDelta):
             print(event.text, end="", flush=True)
 
 asyncio.run(main())
 ```
 
-`Agent.open()` 还接受工作目录、用于权限确认的异步 `confirm` 回调，以及 `toolset`，可以只给模型一部分工具，或者换成你自己的工具。agent 被回收时会交还会话，想在确定的时刻交还就调 `close()`，或者把它当上下文管理器用。它写的会话文件和 CLI 一样，所以代码里跑出来的会话之后可以用 `paimon -r` 恢复。
+`agent.run()` 只跑一个回合，返回时它启动的 agent 可能还在运行；想自己决定什么时候用 `agent.run(None)` 让模型再跑一轮的程序，用它。同一个 agent 一次只跑一个回合或一次压缩，前一个还没结束就开始下一个会抛出 `AgentBusyError`。
+
+`Agent.open()` 还接受工作目录、用于剩余权限确认的异步 `confirm` 回调，以及 `toolset`，可以只给模型一部分工具，或者换成你自己的工具。agent 被回收时会交还会话，想在确定的时刻交还就调 `close()`，或者把它当上下文管理器用。它写的会话文件和 CLI 一样，所以代码里跑出来的会话之后可以用 `paimon -r` 恢复。
 
 ## 会话
 
@@ -91,41 +94,53 @@ paimon log a1b2c3    # 查看会话做了什么，每个事件一行
 
 ```bash
 paimon --mode read                  # 以更谨慎的权限模式启动（默认为 yolo）
-paimon --strict                     # 每条命令都先询问，包括只读命令
+paimon --strict                     # 不再放行只读命令
 paimon --no-web-search              # 本次运行不提供网页搜索工具
 paimon --web                        # 在浏览器中使用同一套 UI（--port，默认 8000）
 paimon -p "what does cli.py do?"    # 直接在 stdout 输出回答，不启动 UI
 cat log.txt | paimon -p "summarize this"
 paimon --model zai:glm-4.7          # 仅本次运行使用该模型
-paimon --profile work               # 单独配置的另一个账号
 ```
 
 `-p` 不会停下来询问，配合默认的 `yolo` 模式，它已经可以修改文件和执行命令。加 `--output-format result` 会输出一个包含结果的 JSON 对象，调用方程序读这个就够了。其余选项见 `paimon --help`。
 
+### 调试 Textual UI
+
+需要让 Paimon 排查自己的布局或样式时，用 `paimon --textual-debug` 启动（也可与 `--web` 一起使用）。默认不启用；开启后模型会多出五个只作用于当前 UI 进程的工具：
+
+- `textual_inspect`：按 CSS selector 查看 DOM、geometry、pseudo-classes、焦点和 computed CSS；
+- `textual_eval` / `textual_exec`：在 UI 进程里运行 Python，支持 private API、持久变量和 top-level `await`；
+- `textual_apply_css`：动态叠加 CSS 并立即重新布局；
+- `textual_screenshot`：把当前渲染结果导出成 SVG。
+
+例如可以直接让它“检查 `#prompt` 为什么比预期窄，动态试一个修复并截图”。`textual_exec` 有意提供完整的进程内 Python 能力，能修改任意 Textual/Paimon 状态；这个选项只适合开发调试，不应对不受信任的 prompt 开启。动态修改只保留到进程退出，确定修复后仍需让 Paimon编辑源码。
+
 ## 配置
 
-每个 profile 的模型设置保存在 `~/.config/paimon/<name>/config.json`，由首次启动或 `paimon login` 写入。会话存放在 `~/.local/share/paimon/sessions/`。
+模型设置保存在 `~/.config/paimon/config.json`，由首次启动或 `paimon login` 写入。每个 provider 各自保存凭据，用 `paimon model provider:name` 或命令面板里的 Switch model 选择要用的模型。也可以用 ChatGPT 订阅代替 API key，`paimon login chatgpt` 会通过浏览器登录。会话存放在 `~/.local/share/paimon/sessions/`。
 
-read 和 edit 模式会不经询问执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。Windows 上命令由 cmd.exe 执行，每条命令都会询问。**这是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
+read 和 auto 模式会直接执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。Windows 上命令由 Git Bash 执行，通过 PATH 上的 `git` 或默认安装位置找到；没装 Git for Windows 时改由 cmd.exe 执行，这时一条也不识别。read 模式拒绝其余所有操作。auto 模式把它们交给审批模型，它能看到你的消息和 agent 的工具调用，看不到 agent 的推理和工具输出，只回答放行或拦截。审批模型不可用或者连续拦截三次时改为询问你，`-p` 下则直接拒绝。当前的模型默认用同一家里快速档的那个来审批（GPT 用 Luna，Claude 用 Haiku，GLM 用 Flash），其余模型自己审自己，在配置里写 `"review_model": "provider:name"` 可以自行指定。**这些都是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
 
 ## 架构
 
-`Agent.run` 产出一串与 UI 无关的事件流，TUI、`--web` 和无头模式都是这条事件流的渲染器。agent 自己持有它启动的子 agent 和后台命令。子 agent 是同一进程里作为任务运行的另一个 `Agent`，它的结果会作为一条消息送回父 agent。
+`Agent.run` 产出一串与 UI 无关的事件流，TUI、`--web` 和无头模式都是这条事件流的渲染器。agent 自己持有它启动的子 agent 和后台命令。子 agent 是同一进程里作为任务运行的另一个 `Agent`，它的结果会作为一条消息送回父 agent。想把 job 显示出来的 UI 挂上 `Agent.open_job` 即可，TUI 就是这样给每个 job 开 pane 的。
 
 ```mermaid
 flowchart TD
     subgraph entry["入口"]
         CLI["cli.py"]
-        Commands["commands.py<br/>status / login / sessions"]
+        Commands["commands.py<br/>status / login / model / sessions"]
         Headless["headless.py<br/>-p，单次运行"]
         App["app.py<br/>Textual TUI / --web"]
     end
 
     subgraph tui["TUI 组件"]
         Pane["pane.py<br/>SessionPane"]
+        AgentPane["agentpane.py<br/>子 agent pane"]
         CommandPane["commandpane.py<br/>后台命令 pane"]
+        Transcript["transcript.py<br/>对话记录与事件渲染"]
         Tabs["tabs.py<br/>pane 标签栏"]
-        Login["login.py<br/>provider / 模型 / key"]
+        Login["login.py<br/>provider / key"]
         UIWidgets["ui.py<br/>输入框、确认面板"]
         Diff["diff.py<br/>并排 diff 渲染"]
     end
@@ -134,17 +149,17 @@ flowchart TD
         AgentLoop["agent.py<br/>Agent.run()"]
         LLM["llm.py<br/>build_model()"]
         PromptMod["prompt.py<br/>system prompt"]
-        ToolsMod["tools.py<br/>工具注册表"]
+        ToolsMod["tools/<br/>工具注册表"]
         SessionMod["session.py<br/>JSONL 持久化"]
         Compaction["compaction.py"]
-        ModelWindows["model_windows.py<br/>各模型上下文窗口大小"]
         Retry["retry.py"]
         Mentions["mentions.py<br/>@path 展开"]
+        JobMgr["jobs.py<br/>子代理、后台命令"]
         Jobs["turns.py<br/>回合驱动"]
     end
 
     subgraph support["配置与 skills"]
-        Config["config.py<br/>profile、凭证"]
+        Config["config.py<br/>设置、凭证"]
         Skills["skills.py<br/>Agent Skills 发现"]
     end
 
@@ -157,6 +172,7 @@ flowchart TD
     Headless --> Mentions
 
     App --> Pane
+    App --> AgentPane
     App --> CommandPane
     App --> Tabs
     App --> Login
@@ -165,9 +181,13 @@ flowchart TD
     Pane --> Jobs
     Pane --> AgentLoop
     Pane --> Diff
+    Pane --> Transcript
     Pane --> UIWidgets
     Pane --> LLM
+    AgentPane --> Pane
+    AgentPane --> Transcript
     CommandPane --> Pane
+    Transcript --> UIWidgets
     UIWidgets --> Diff
 
     AgentLoop --> LLM
@@ -177,11 +197,12 @@ flowchart TD
     AgentLoop --> Compaction
     AgentLoop --> Retry
     AgentLoop --> Mentions
-    AgentLoop -. "spawn_agent" .-> AgentLoop
-    AgentLoop -. "run_background" .-> CommandPane
+    AgentLoop --> JobMgr
+    JobMgr -. "spawn_agent" .-> AgentLoop
+    JobMgr -. "spawn_agent" .-> AgentPane
+    JobMgr -. "run_background" .-> CommandPane
 
     PromptMod --> Skills
-    Compaction --> ModelWindows
 
     Jobs --> AgentLoop