paimon 0.2.6__tar.gz → 0.2.8__tar.gz

paimon-0.2.8/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: paimon
+Version: 0.2.8
+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
+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. 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()` yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes:
+
+```python
+import asyncio
+
+from paimon.agent import Agent, TextDelta
+
+async def main():
+    agent = Agent.open(mode="auto")
+    async for event in agent.run("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`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 --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.
+
+### 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, and on Windows, where cmd.exe runs the commands, 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.py<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        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 -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "spawn_agent" .-> AgentPane
+    AgentLoop -. "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.8/README.md

@@ -0,0 +1,212 @@
+# 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. 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()` yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes:
+
+```python
+import asyncio
+
+from paimon.agent import Agent, TextDelta
+
+async def main():
+    agent = Agent.open(mode="auto")
+    async for event in agent.run("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`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 --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.
+
+### 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, and on Windows, where cmd.exe runs the commands, 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.py<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        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 -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "spawn_agent" .-> AgentPane
+    AgentLoop -. "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.8/README.zh-CN.md

@@ -0,0 +1,210 @@
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+[English](README.md) | 简体中文
+
+Paimon 是一个终端里的 coding agent。它读写当前目录下的文件，执行命令。它也支持无头运行，还可以作为库导入，由更强的 agent 或者你自己的程序来驱动。
+
+## 安装
+
+```bash
+uv tool install paimon   # 或者：pip install paimon
+```
+
+## 快速开始
+
+```bash
+paimon
+```
+
+或者不安装直接运行：
+
+```bash
+uvx paimon
+```
+
+首次启动会询问 provider 及其 API base 和 key，然后选择模型。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
+
+运行时：`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 也能并行干活：让它同时做两件互不相干的事，它会在单独的 tab 里起第二个 agent，你可以在那里看它干活、回答它的授权请求，做完后结果会回到当前会话里，关掉 tab 就是停掉它。它也能把一条命令留在 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
+
+## 网页搜索
+
+Paimon 可以搜索网页，不需要 API key。任何权限模式下都不会询问，因为搜索不会改动本机的任何东西。搜索通过元搜索库 [ddgs](https://github.com/deedy5/ddgs) 进行，所以一条 query 可能被发往多个公共搜索引擎中的任意一个。`--no-web-search` 可以在本次运行中去掉这个工具。
+
+## Skills
+
+Paimon 会从 `~/.config/paimon/skills`、`~/.agents/skills` 以及工作目录到仓库根之间每一层的 `.agents/skills` 加载 [Agent Skills](https://agentskills.io)。system prompt 里只放每个 skill 的名字和描述，任务匹配时模型自己去读 `SKILL.md`，也可以用 `/skill:name 参数` 显式发送（`/` 命令面板里列出了它们）。其他位置可以写进 `config.json` 的 `"skills": ["~/.claude/skills"]`，或者用命令行参数 `--skill PATH`；`--no-skills` 跳过默认位置。同名时显式指定的优先于项目的，项目的优先于全局的。
+
+## 当作 subagent 使用
+
+前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。先登录该模型的 provider，之后每次运行时指定模型：
+
+```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
+```
+
+自带的 skill 会向调用方 agent 说明这套流程：
+
+```bash
+paimon install-skill                  # 安装到 Claude Code（~/.claude/skills/paimon）
+paimon install-skill --target codex   # 安装到 Codex；--dest DIR 安装到任意目录
+npx skills add aisk/paimon            # 通过 skills.sh 安装同一个 skill
+```
+
+## 当作库使用
+
+agent 循环本身是可以导入的，Python 程序不必经过 CLI 就能驱动它。`Agent.open()` 新建或恢复一个会话，`agent.run()` 产出类型化的事件，每段文本、每次工具调用、每个回合结束各一个，调用方自己决定怎么渲染或过滤：
+
+```python
+import asyncio
+
+from paimon.agent import Agent, TextDelta
+
+async def main():
+    agent = Agent.open(mode="auto")
+    async for event in agent.run("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` 恢复。
+
+## 会话
+
+每次对话都会保存，很长的对话在接近上下文上限时会被原地总结。退出时 Paimon 会打印恢复该会话的命令：
+
+```bash
+paimon -r            # 从当前目录的会话中选择
+paimon -r a1b2c3     # 按 id 恢复
+paimon -c            # 恢复最近一个会话
+paimon sessions      # 列出会话（--json 输出机器可读格式）
+paimon log a1b2c3    # 查看会话做了什么，每个事件一行
+```
+
+## 其他运行方式
+
+```bash
+paimon --mode read                  # 以更谨慎的权限模式启动（默认为 yolo）
+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          # 仅本次运行使用该模型
+```
+
+`-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编辑源码。
+
+## 配置
+
+模型设置保存在 `~/.config/paimon/config.json`，由首次启动或 `paimon login` 写入。每个 provider 各自保存凭据，用 `paimon model provider:name` 或命令面板里的 Switch model 选择要用的模型。也可以用 ChatGPT 订阅代替 API key，`paimon login chatgpt` 会通过浏览器登录。会话存放在 `~/.local/share/paimon/sessions/`。
+
+read 和 auto 模式会直接执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉，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。想把 job 显示出来的 UI 挂上 `Agent.open_job` 即可，TUI 就是这样给每个 job 开 pane 的。
+
+```mermaid
+flowchart TD
+    subgraph entry["入口"]
+        CLI["cli.py"]
+        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"]
+        UIWidgets["ui.py<br/>输入框、确认面板"]
+        Diff["diff.py<br/>并排 diff 渲染"]
+    end
+
+    subgraph core["Agent 主循环"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>工具注册表"]
+        SessionMod["session.py<br/>JSONL 持久化"]
+        Compaction["compaction.py"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path 展开"]
+        Jobs["turns.py<br/>回合驱动"]
+    end
+
+    subgraph support["配置与 skills"]
+        Config["config.py<br/>设置、凭证"]
+        Skills["skills.py<br/>Agent Skills 发现"]
+    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 -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "spawn_agent" .-> AgentPane
+    AgentLoop -. "run_background" .-> CommandPane
+
+    PromptMod --> Skills
+
+    Jobs --> AgentLoop
+
+    Skills --> Config
+    Config --> LLM
+```
+
+## 遥测
+
+每次启动会向 Google Analytics 发送一条匿名事件：随机生成的安装 id、启动方式、版本号、操作系统名称、取自 `LC_ALL`/`LANG` 的语言、是否首次启动，以及配置的 provider 和模型名。会话、提示词、文件和密钥一概不上报。设置 `PAIMON_NO_TELEMETRY=1` 或 `DO_NOT_TRACK=1` 可以关闭。

paimon-0.2.8/paimon/_grep_worker.py

@@ -0,0 +1,16 @@
+"""Disposable process for bounded, cancellable code searches."""
+
+import json
+import sys
+from pathlib import Path
+
+from .tools import _grep
+
+
+def main() -> None:
+    args, cwd, sandboxed = json.load(sys.stdin)
+    sys.stdout.write(json.dumps(_grep(args, Path(cwd), sandboxed=sandboxed)))
+
+
+if __name__ == "__main__":
+    main()