qi-coding-agent 0.1.0__tar.gz → 0.1.1__tar.gz

qi_coding_agent-0.1.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: qi-coding-agent
+Version: 0.1.1
+Summary: 编码 agent 框架:单 agent core + 扩展(MCP / 多 agent / web)
+Project-URL: Homepage, https://github.com/viewnah/qi
+Project-URL: Repository, https://github.com/viewnah/qi
+Project-URL: Issues, https://github.com/viewnah/qi/issues
+Project-URL: Documentation, https://github.com/viewnah/qi/tree/dev/docs
+License: MIT
+License-File: LICENSE
+Keywords: agent,cli,coding-agent,llm,mcp,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: litellm>=1.40
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qi
+
+[![PyPI](https://img.shields.io/pypi/v/qi-coding-agent?style=flat-square)](https://pypi.org/project/qi-coding-agent/)
+[![Python](https://img.shields.io/pypi/pyversions/qi-coding-agent?style=flat-square)](https://pypi.org/project/qi-coding-agent/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+用 Python 写的编码 agent 框架 —— **pi-coding-agent 的 Python 实现**:同一套形态与用法(单 agent core + 扩展宿主),换到 Python 生态。
+
+* **[qi-coding-agent](https://pypi.org/project/qi-coding-agent/)**:交互式编码 agent CLI(`qi` 命令)
+* **core 就是单 agent**:会话(JSONL + 分支树)· 工具循环 · 系统提示词 · CLI + TUI · 自动压缩 · 认证 · 扩展宿主
+
+想了解 qi:
+
+* 读[手册](docs/index.md),先看[qi 是怎么工作的](docs/how-qi-works.md)
+* 也可以**直接问 qi 自己** —— 自带手册的索引会进提示词,它按需 `read` 那些文件来回答
+
+## 安装
+
+前置:**Python ≥ 3.12**。
+
+```bash
+uv tool install qi-coding-agent     # 推荐:装成全局命令,独立环境
+# 或 pip install qi-coding-agent    # 装进当前 venv
+
+qi --version
+qi doctor                           # 冒烟:配置 / 凭证 / 扩展 / 包声明,一次全报
+```
+
+## 快速开始
+
+第一次用,**在界面里两步**就能跑起来:
+
+```bash
+qi                      # 裸 qi 就是界面(装完直接敲)
+```
+
+进去之后:
+
+```text
+/login                  # 选 provider(预置都在列表里)→ 遮罩输入 API key → 写 ~/.qi/agent/auth.json
+/model                  # 选模型(只列解析得出凭证的;刚才没有模型时 /login 会顺带选中第一个)
+```
+
+然后直接说你要做什么。三种跑法:
+
+```bash
+qi                      # 交互界面
+qi "分析这个仓库"        # 进界面,并把这句话作为首条消息发出
+qi -p "分析这个仓库"     # 无头一次:stdout 只有答案(进度走 stderr)
+qi --mode json "…"      # 事件流:一行一个 JSON,喂给上层程序
+```
+
+想**在命令行里把 provider 与模型配好**(脚本 / CI / 不想进界面):
+
+```bash
+qi init                     # 引导:选 provider → 加模型 → 设为默认
+qi init --list-presets      # 看内置的预置 provider(国产为主:deepseek / qwen / kimi / glm / minimax …)
+qi init --preset deepseek   # 一条命令物化预置并设为默认(只补缺、幂等)
+qi doctor                   # 校验配置与凭证
+```
+
+全部斜杠命令见[斜杠命令](docs/slash-commands.md)。
+
+**零配置也能跑**:基座提示词在代码里,不写任何配置就是一个能用的单 agent。
+逐步说明见[快速开始](docs/quickstart.md)。
+
+## 扩展
+
+qi 的能力可以按需加装 —— 命令、快捷键、工具、事件钩子、终端 UI 组件都走同一套扩展机制。
+**core 不内置、也不默认装**,裸 qi 就是一个能用的单 agent。
+
+```bash
+qi install <来源> [-l]  # 装:调 pip(本地目录只登记)+ 把声明写进 settings.packages(带 -l 写项目)
+qi list                 # 看装了哪些(含目录通道),并与声明双向比对
+qi doctor               # 「声明了没装」「装了没声明」都报出来,并给出可复制的装法
+qi remove <来源>        # 只移除声明(不卸包),并把 pip uninstall 命令打出来
+qi -e <目录>            # 本次运行临时加载一个扩展目录(TUI 与无头都生效,只本进程)
+```
+
+手工放目录也行:用户级 `~/.qi/agent/extensions/<名>/extension.py`,项目级 `.qi/extensions/<名>/extension.py`
+(项目级**未信任不加载**;入口文件名固定)。
+
+三条要点:
+
+* **装到哪**:进的是 **qi 所在的那个解释器环境**(不是当前项目的 venv)—— `uv tool install` 会重建环境,
+  所以**声明**要写在 `settings.packages` 里,重建后用 `qi doctor` 发现并补回。
+* **声明与实装是两件事**:`settings.packages` 说"这个环境该装什么",`settings.extensions` 说"到哪里找扩展目录";
+  `qi list` / `qi doctor` 永远做**两个方向**的比对。
+* **扩展就是任意代码**:只装可信来源。写一个扩展见[写扩展](docs/extensions.md)与[终端 UI 组件](docs/tui.md);
+  装法与声明层的完整写法见[扩展的安装与声明](docs/packages.md)。
+
+## 权限与沙箱
+
+qi **不内置**限制文件系统 / 进程 / 网络 / 凭证访问的权限系统 —— 它默认以启动它的那个用户与进程的权限运行,
+`bash` 工具不做命令级过滤。需要更强的边界就**把它放进容器或沙箱**:见
+[隔离运行](docs/containerization.md),以及完整的安全模型与已知缺口 [安全地运行](docs/security.md)。
+
+## 文档
+
+| 去处 | 内容 |
+| --- | --- |
+| [docs/index.md](docs/index.md) | 手册总入口:开始 / 指南(运行 · 定制 · 构建)/ 参考 |
+| [docs/how-qi-works.md](docs/how-qi-works.md) | agent loop、上下文、会话、工具、信任 —— 先读这一页 |
+| [docs/cli.md](docs/cli.md) | 命令行:全部选项与行为(输出 / 模型 / 会话 / 工具 / 资源 / 凭证 …) |
+| [docs/slash-commands.md](docs/slash-commands.md) | TUI 里的斜杠命令(模型与设置 / 会话与上下文 / 导出 / 运行时) |
+| [docs/extensions.md](docs/extensions.md) | 写扩展:工具、事件、命令、终端 UI 组件 |
+
+手册随 wheel 发布,索引会注入提示词;**正文不塞进上下文** —— 模型按需用 `read` 打开。
+
+## 许可证
+
+MIT(见 [LICENSE](LICENSE))。qi 里有两处素材移植自上游 pi(两份内置调色板与压缩/分支摘要的提示词),
+它们的 MIT 声明与许可全文见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md);
+**qi 与 pi 的维护者没有隶属关系**,也不是官方移植。

qi_coding_agent-0.1.1/README.md

@@ -0,0 +1,114 @@
+# qi
+
+[![PyPI](https://img.shields.io/pypi/v/qi-coding-agent?style=flat-square)](https://pypi.org/project/qi-coding-agent/)
+[![Python](https://img.shields.io/pypi/pyversions/qi-coding-agent?style=flat-square)](https://pypi.org/project/qi-coding-agent/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+用 Python 写的编码 agent 框架 —— **pi-coding-agent 的 Python 实现**:同一套形态与用法(单 agent core + 扩展宿主),换到 Python 生态。
+
+* **[qi-coding-agent](https://pypi.org/project/qi-coding-agent/)**:交互式编码 agent CLI(`qi` 命令)
+* **core 就是单 agent**:会话(JSONL + 分支树)· 工具循环 · 系统提示词 · CLI + TUI · 自动压缩 · 认证 · 扩展宿主
+
+想了解 qi:
+
+* 读[手册](docs/index.md),先看[qi 是怎么工作的](docs/how-qi-works.md)
+* 也可以**直接问 qi 自己** —— 自带手册的索引会进提示词,它按需 `read` 那些文件来回答
+
+## 安装
+
+前置:**Python ≥ 3.12**。
+
+```bash
+uv tool install qi-coding-agent     # 推荐:装成全局命令,独立环境
+# 或 pip install qi-coding-agent    # 装进当前 venv
+
+qi --version
+qi doctor                           # 冒烟:配置 / 凭证 / 扩展 / 包声明,一次全报
+```
+
+## 快速开始
+
+第一次用,**在界面里两步**就能跑起来:
+
+```bash
+qi                      # 裸 qi 就是界面(装完直接敲)
+```
+
+进去之后:
+
+```text
+/login                  # 选 provider(预置都在列表里)→ 遮罩输入 API key → 写 ~/.qi/agent/auth.json
+/model                  # 选模型(只列解析得出凭证的;刚才没有模型时 /login 会顺带选中第一个)
+```
+
+然后直接说你要做什么。三种跑法:
+
+```bash
+qi                      # 交互界面
+qi "分析这个仓库"        # 进界面,并把这句话作为首条消息发出
+qi -p "分析这个仓库"     # 无头一次:stdout 只有答案(进度走 stderr)
+qi --mode json "…"      # 事件流:一行一个 JSON,喂给上层程序
+```
+
+想**在命令行里把 provider 与模型配好**(脚本 / CI / 不想进界面):
+
+```bash
+qi init                     # 引导:选 provider → 加模型 → 设为默认
+qi init --list-presets      # 看内置的预置 provider(国产为主:deepseek / qwen / kimi / glm / minimax …)
+qi init --preset deepseek   # 一条命令物化预置并设为默认(只补缺、幂等)
+qi doctor                   # 校验配置与凭证
+```
+
+全部斜杠命令见[斜杠命令](docs/slash-commands.md)。
+
+**零配置也能跑**:基座提示词在代码里,不写任何配置就是一个能用的单 agent。
+逐步说明见[快速开始](docs/quickstart.md)。
+
+## 扩展
+
+qi 的能力可以按需加装 —— 命令、快捷键、工具、事件钩子、终端 UI 组件都走同一套扩展机制。
+**core 不内置、也不默认装**,裸 qi 就是一个能用的单 agent。
+
+```bash
+qi install <来源> [-l]  # 装:调 pip(本地目录只登记)+ 把声明写进 settings.packages(带 -l 写项目)
+qi list                 # 看装了哪些(含目录通道),并与声明双向比对
+qi doctor               # 「声明了没装」「装了没声明」都报出来,并给出可复制的装法
+qi remove <来源>        # 只移除声明(不卸包),并把 pip uninstall 命令打出来
+qi -e <目录>            # 本次运行临时加载一个扩展目录(TUI 与无头都生效,只本进程)
+```
+
+手工放目录也行:用户级 `~/.qi/agent/extensions/<名>/extension.py`,项目级 `.qi/extensions/<名>/extension.py`
+(项目级**未信任不加载**;入口文件名固定)。
+
+三条要点:
+
+* **装到哪**:进的是 **qi 所在的那个解释器环境**(不是当前项目的 venv)—— `uv tool install` 会重建环境,
+  所以**声明**要写在 `settings.packages` 里,重建后用 `qi doctor` 发现并补回。
+* **声明与实装是两件事**:`settings.packages` 说"这个环境该装什么",`settings.extensions` 说"到哪里找扩展目录";
+  `qi list` / `qi doctor` 永远做**两个方向**的比对。
+* **扩展就是任意代码**:只装可信来源。写一个扩展见[写扩展](docs/extensions.md)与[终端 UI 组件](docs/tui.md);
+  装法与声明层的完整写法见[扩展的安装与声明](docs/packages.md)。
+
+## 权限与沙箱
+
+qi **不内置**限制文件系统 / 进程 / 网络 / 凭证访问的权限系统 —— 它默认以启动它的那个用户与进程的权限运行,
+`bash` 工具不做命令级过滤。需要更强的边界就**把它放进容器或沙箱**:见
+[隔离运行](docs/containerization.md),以及完整的安全模型与已知缺口 [安全地运行](docs/security.md)。
+
+## 文档
+
+| 去处 | 内容 |
+| --- | --- |
+| [docs/index.md](docs/index.md) | 手册总入口:开始 / 指南(运行 · 定制 · 构建)/ 参考 |
+| [docs/how-qi-works.md](docs/how-qi-works.md) | agent loop、上下文、会话、工具、信任 —— 先读这一页 |
+| [docs/cli.md](docs/cli.md) | 命令行:全部选项与行为(输出 / 模型 / 会话 / 工具 / 资源 / 凭证 …) |
+| [docs/slash-commands.md](docs/slash-commands.md) | TUI 里的斜杠命令(模型与设置 / 会话与上下文 / 导出 / 运行时) |
+| [docs/extensions.md](docs/extensions.md) | 写扩展:工具、事件、命令、终端 UI 组件 |
+
+手册随 wheel 发布,索引会注入提示词;**正文不塞进上下文** —— 模型按需用 `read` 打开。
+
+## 许可证
+
+MIT(见 [LICENSE](LICENSE))。qi 里有两处素材移植自上游 pi(两份内置调色板与压缩/分支摘要的提示词),
+它们的 MIT 声明与许可全文见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md);
+**qi 与 pi 的维护者没有隶属关系**,也不是官方移植。

qi_coding_agent-0.1.1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# 第三方声明(Third-Party Notices)
+
+qi 是独立实现,但有**两处素材移植自上游项目 pi**。它们同样在 MIT 许可下分发,因此随附下面的
+版权声明与许可全文 —— 这是 MIT 的明确要求(“the above copyright notice and this permission
+notice shall be included in all copies or substantial portions of the Software”)。
+
+## pi(pi-coding-agent)
+
+- 项目:<https://github.com/earendil-works/pi>(`packages/coding-agent`;本仓记录在案的参照版本:pi v0.85.1)
+- 许可:**MIT License,Copyright (c) 2025 Mario Zechner**
+- 移植清单:
+
+| qi 里的位置 | 情况 |
+| --- | --- |
+| `src/qi_agent/themes/dark.json`、`src/qi_agent/themes/light.json` | 两份内置调色板,取自上游 `theme/dark.json` / `theme/light.json`;键名与语义一致,qi 侧只调整了个别颜色值 |
+| `src/qi_agent/compaction.py` 的 `SUMMARIZATION_SYSTEM_PROMPT` / `SUMMARIZATION_PROMPT` / `UPDATE_SUMMARIZATION_PROMPT` / `TURN_PREFIX_SUMMARIZATION_PROMPT` | 上下文压缩、分支摘要与 split-turn 的**提示词文本**,逐字移植 |
+| 其余部分 | Python 代码、CLI / TUI、扩展宿主、打包与手册都是本仓自己写的;`docs/` 与 `design/pi-alignment.md` 里的上游对照是本仓重写的说明文字,只含少量短引用 |
+
+> qi 与 pi 的维护者**没有隶属关系**,也不是官方移植。README 里"pi-coding-agent 的 Python 实现"
+> 只是说明它对齐上游的形态与用法。
+
+## pi 的 MIT 许可全文
+
+```text
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+qi 自身:MIT License, **Copyright (c) 2026 viewnah**(见仓库根目录的 `LICENSE`)。
+运行时依赖(typer / rich / textual / pydantic / litellm / PyYAML 等)各有自己的许可,
+由 pip 在安装时随各自的 distribution 一并提供。

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/cli.md

@@ -38,7 +38,7 @@ qi --export out.html                # 导出会话后退出
 | `-p`, `--print` | 跑完退出,**只把最终答案写 stdout** |
 | `--mode text` | 文本输出;**stdin/stdout 都是终端时仍进界面**(要一次执行就配 `-p`) |
 | `--mode json` | 输出事件流(一行一个 JSON,**隐含无头**)→ [json.md](json.md) |
-| `--mode rpc` | **未实现**:传了会明确报错(见 [PLAN.md](../design/PLAN.md) 的 v2 清单) |
+| `--mode rpc` | **未实现**:传了会明确报错 |
 | `--export <file>` | 导出会话:`.html` → 自包含 HTML,其余 → 原始 JSONL |
 
 **选项写在消息之前**(`qi -nt "问题"`,不是 `qi "问题" -nt`):顶层选项在遇到消息后不再解析 —— 写反了会报错并提示怎么改。
@@ -56,6 +56,9 @@ qi --export out.html                # 导出会话后退出
 中断退出码 `128+n`:`SIGTERM` / `SIGHUP` → 回收在跑的子进程组 + `exit(143/129)`;`SIGINT` → asyncio 取消 →
 `run_shell` 的 finally 回收 + `exit(130)`,不打 traceback。两条路径的半截回答都会落盘。
 
+> Windows 没有 `SIGHUP`(Python 的 `signal` 模块里不存在这个属性),所以那里只装 `SIGTERM`;
+> 其余行为一致。探测发生在**导入期之前**(代码里先 `getattr` 再登记),不会让 CLI 崩在启动。
+
 ## 模型
 
 ```sh

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/configuration.md

@@ -80,7 +80,6 @@ AGENTS.override.md > AGENTS.md > AGENTS.MD > CLAUDE.md > CLAUDE.MD
 ```
 
 **动态块不受影响**:项目上下文、技能清单、手册索引、工作目录照旧追加 —— 不是"整条提示词只剩你的文件"。
-(实现细节见 [design/internals.md](../design/internals.md)。)
 
 ## qi 没有的配置项
 

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/containerization.md

@@ -76,5 +76,4 @@ qi 只需要能连到模型 provider。要收紧就在容器/防火墙层限制
 
 ## 与其它页面的关系
 
-- [security.md](security.md):有哪些闸门、哪些地方没有闸门;信任门控挡什么。
-- [bash-allowlist.md](../design/bash-allowlist.md):为什么不做命令白名单(以及它为什么不是边界)。
+- [安全地运行](security.md):有哪些闸门、哪些地方没有闸门;信任门控挡什么。

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/index.md

@@ -1,6 +1,6 @@
 # qi 文档
 
-qi 是**可扩展的编码 agent 框架**:裸 core 就是单 agent,跑在终端里;角色、MCP、Web 都是扩展。
+qi 是**可扩展的编码 agent 框架**:裸 core 就是单 agent,跑在终端里;其余能力按需装扩展。
 给它一个目标和一个工作目录,它会读文件、跑命令、改内容,并一步步把任务做完。
 
 机器可读的导航清单是同目录的 [`docs.json`](docs.json)(与下面这些分类同源)。
@@ -34,7 +34,7 @@ qi 能加载按需说明、加可执行集成、换配色,并把这些打包分
 - [命令行](cli.md):`qi -p "…"` 无头一次拿结果,进度走 stderr。
 - [JSON 事件流](json.md):把一轮里的每个事件按行喂给上层程序。
 
-qi 没有 RPC 模式与 SDK —— `--mode rpc` 会明确报未实现(见 [PLAN.md](../design/PLAN.md) 的 v2 清单)。
+qi 没有 RPC 模式与 SDK —— `--mode rpc` 会明确报未实现。
 
 ## 参考
 
@@ -47,15 +47,3 @@ qi 没有 RPC 模式与 SDK —— `--mode rpc` 会明确报未实现(见 [PLAN.
 qi 的工具与扩展以 **qi 进程本身的权限**运行。信任门控只决定"要不要加载项目里的资源",**不是沙箱**。
 动不认识的仓库、扩展或无人值守的自动化之前,先读 [安全地运行](security.md);要真隔离看
 [隔离运行](containerization.md)。
-
-## 读完还想改 qi 本身
-
-| 去处 | 内容 |
-| --- | --- |
-| [development.md](../design/development.md) | 拉起来、测试、静态检查、仓库布局 |
-| [PLAN.md](../design/PLAN.md) | 开发计划、阶段表、未决清单 |
-| [overview.md](../design/overview.md) | 总设计:架构总览、既定决策索引、技术选型、目录布局 |
-| [internals.md](../design/internals.md) | 实现细节与决策记录(手册之外的部分) |
-| [extensions-design.md](../design/extensions-design.md) | 扩展化的阶段拆解、未定清单、决策编号表(E1–E28) |
-| [pi-alignment.md](../design/pi-alignment.md) | 与上游 pi 的逐节对照 |
-| [bash-allowlist.md](../design/bash-allowlist.md) | bash 策略的变更记录(为什么删掉首词白名单) |

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/models.md

@@ -26,7 +26,9 @@ qi 通过 litellm 调各家模型。provider 与模型定义都在 `models.json`
 
 - **唯一来源是 `settings.json`**:`models.json` 里的 `defaultProvider` / `defaultModel`
   **完全不参与**(不是优先级更低),写了会被忽略并在 `qi doctor` 里报出来。
-- 缺任一项就启动失败,并给出可照抄的迁移命令。
+- 缺任一项时:**交互界面(TUI)照常启动**,顶部提示用 `/login` 登录 provider(或用 `qi init` 引导),
+  真正提交消息才报错;无头路径(`-p` / `--mode json`)直接报错退出,并给出可照抄的迁移命令
+  —— 与 pi 的 interactive / 非 interactive 同一取舍。
 - 查看:`qi --list-models [搜索词]`(缺密钥的也列,这是诊断面;解析不出凭证的 provider 不列)。
 
 ## 接本地模型

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/quickstart.md

@@ -2,29 +2,29 @@
 
 从零到第一次对话:装 → 配模型 → 跑。
 
-## 1. 装
+## 1. 安装
 
 qi 需要 **Python ≥ 3.12**。
 
-**发行名是 `qi-coding-agent`**(PyPI 上的 `qi-agent` 属于**别的项目**,别装错;import 包名仍是
-`qi_agent`、命令仍是 `qi`)。目前**还没发布**,所以以从源码安装为主 —— 不要假设
-`pip install qi-coding-agent` 现在就能装到东西。
+**发行名是 [`qi-coding-agent`](https://pypi.org/project/qi-coding-agent/)** —— PyPI 上的
+`qi-agent` 属于**别的项目**,别装错;import 包名仍是 `qi_agent`、命令仍是 `qi`。
 
 ```bash
-git clone https://github.com/viewnah/qi.git
-cd qi
-uv sync                 # 或用你自己习惯的方式装进某个 venv:
-                        #   python -m venv .venv && .venv/bin/pip install -e .
+uv tool install qi-coding-agent     # 推荐:装上 `qi` 命令,独立环境
+# 或:pip install qi-coding-agent    # 装进当前 venv
+# 或:uv add --dev qi-coding-agent   # 只给某个项目用
 ```
 
-装完 `qi` 命令可用(`[project.scripts]` 里的入口):
-
 ```bash
-uv run qi --version     # 或激活 venv 后直接 `qi --version`
+qi --version            # → qi 0.1.1
 ```
 
 首次运行会创建 `~/.qi/agent/`(用户级状态都挂在这里:配置、会话、技能、扩展)。
 
+**要改 qi 本身 / 跑测试**才需要源码:克隆仓库 → `uv sync` → `uv run qi …`(editable,改完立即生效)。
+
+扩展是**独立包**(core 不内置、不默认装),装法与声明层见 [packages.md](packages.md)。
+
 ## 2. 配一个模型
 
 qi 不内置任何 provider 就必须先配一个能用的模型。交互式引导:
@@ -33,6 +33,10 @@ qi 不内置任何 provider 就必须先配一个能用的模型。交互式引
 qi init
 ```
 
+还没配就想先看看界面也没关系:直接 `qi` 会照常进 TUI,并提示用 `/login` 登录一个
+provider(或退出后在终端跑 `qi init`)。`/login` 只解决凭证;provider/模型清单不在
+`models.json` 里时仍要 `qi init` 补上。
+
 它会走三步(样式复刻 QwenPaw 的 `init`):**选 provider**(已有 / 新建 → Base URL → API 类型 → API Key)
 → **Add Models**(`Add a model?` 循环,含 reasoning / contextWindow / maxTokens)
 → **选一个默认模型**。产物是三个文件:`models.json`(provider 与模型清单)、
@@ -81,7 +85,7 @@ qi --mode json "分析这个仓库" # 事件流(一行一个 JSON 对象),给管
 | 想做 | 去哪 |
 | --- | --- |
 | 下次接着这条会话 | `qi -c`(最近一条)或 `qi --session <id>` —— [sessions.md](sessions.md) |
-| 换模型 / 换思考级别 | TUI 里换,或 `--thinking <级别>` —— [tui.md](tui.md) |
+| 换模型 / 换思考级别 | TUI 里换,或 `--thinking <级别>` —— [models.md](models.md) · [usage.md](usage.md) |
 | 加自己的技能 | 写 `SKILL.md` 放进 `~/.qi/agent/skills/` —— [skills.md](skills.md) |
 | 改系统提示词 | 写 `.qi/SYSTEM.md`(**整体替换**默认基座,注意副作用) —— [configuration.md](configuration.md) |
 | 写扩展 | [extensions.md](extensions.md) |

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/security.md

@@ -40,8 +40,8 @@ qi 能执行任意命令、读写任意文件,而**装进来的扩展就是任
 
 ## bash 的边界
 
-**qi 没有命令级过滤**:不筛子命令、不拦重定向、不做只读白名单 —— `bash` 能跑任何东西。这是**刻意的**,
-理由与四种绕过写法见 [bash-allowlist.md](../design/bash-allowlist.md)。
+**qi 没有命令级过滤**:不筛子命令、不拦重定向、不做只读白名单 —— `bash` 能跑任何东西。这是**刻意的**:
+白名单挡不住 `&&` / `;` / `>` / 裸解释器这几种写法,所以它只会给一个“看起来有闸门”的错觉。
 
 限制手段只有两档:
 
@@ -54,8 +54,7 @@ qi 能执行任意命令、读写任意文件,而**装进来的扩展就是任
 - 文件工具的路径限制在**会话工作目录**内(`read` / `ls` / `find` / `grep` / `write` / `edit`),**bash 不受限**。
 - `bash` / `powershell` 的子进程 stdin 是 `DEVNULL`(读不到 TUI 的按键);超时按**进程组**回收。
 - TUI 里 `!` 手动命令不经任何过滤 —— 那是你亲手敲的,不算模型越权。
-- **没有工具级审批弹窗**(那类 workflow 属于扩展或外部工具)。破坏性操作的交互前钩子(HITL)**未做**,
-  见 [PLAN.md](../design/PLAN.md) 的 v2 清单。
+- **没有工具级审批弹窗**(那类 workflow 属于扩展或外部工具)。破坏性操作的交互前钩子(HITL)**未做**。
 
 ## 配置文件里的命令
 
@@ -65,5 +64,5 @@ qi 能执行任意命令、读写任意文件,而**装进来的扩展就是任
 
 ## 报漏洞 / 上报问题
 
-qi 目前没有专门的安全上报渠道;设计层面的取舍记录在 [design/](../design)(尤其
-[bash-allowlist.md](../design/bash-allowlist.md) 与 [PLAN.md](../design/PLAN.md) 的 containerization 条目)。
+qi 目前没有专门的安全上报渠道。**不做进程内沙箱是刻意的取舍**:半步隔离最容易被误当成安全边界 ——
+要么按[隔离运行](containerization.md)那条路真隔离,要么就按“它有你进程的全部权限”来使用。

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/session-format.md

@@ -234,8 +234,7 @@ web 端同理:每轮开跑前 `WebState.bind()`(`bind_session` + `start_session`
 | **内存** | True | — | `--no-session`(`ephemeral()`) | 永不写盘(append/save/set_title 全跳过) |
 
 **为什么要"预留"而不是"启动就建文件"**:本机真实事故 —— `~/.qi/agent/sessions/` 攒了
-3000+ 个只有一行的空会话,全部来自"进来看一眼就走"。同一根因在 web 端也有(见
-[design/web.md](../design/web.md) §18.28 的"懒创建")。
+3000+ 个只有一行的空会话,全部来自"进来看一眼就走"。web 端也有同一个根因(懒创建)。
 
 **为什么留住会话对象、只懒文件**:构造时就 `newSession()`,
 于是"当前会话"这个不变量始终成立 —— 历史、用量、扩展的 `ctx.session_manager`、`/session`

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/docs/tui.md

@@ -101,9 +101,3 @@ def register(api):
 ```
 
 配色请走主题的语义键(别写死 `#rrggbb`),否则换主题时你的组件不会跟着变 —— 见 [themes.md](themes.md)。
-
-## 与其它页面的关系
-
-- 扩展整体的写法(工具、事件、命令、旗标、依赖)见 [extensions.md](extensions.md)。
-- 键位与编辑器行为见 [keybindings.md](keybindings.md)。
-- 实现细节(Textual 的 priority / 焦点坑)见 [design/internals.md](../design/internals.md)。

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/extensions/qi-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qi-agents"
-version = "0.1.0"
+version = "0.1.1"
 description = "qi 的角色系统扩展:角色发现 + 角色选择 + subagent 工具(进程内受管子运行)"
 readme = "README.md"
 requires-python = ">=3.12"

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/extensions/qi-mcp/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qi-mcp"
-version = "0.1.0"
+version = "0.1.1"
 description = "qi 的 MCP 支持:两层 mcp.json 声明表 + 一个 mcp 代理工具 + lazy server"
 readme = "README.md"
 requires-python = ">=3.12"

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/extensions/qi-web/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qi-web"
-version = "0.1.0"
+version = "0.1.1"
 description = "qi 的 Web UI 扩展:HTTP 宿主(REST + SSE)+ AG-UI 桥 + 官方界面"
 readme = "README.md"
 requires-python = ">=3.12"

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qi-coding-agent"
-version = "0.1.0"
+version = "0.1.1"
 description = "编码 agent 框架:单 agent core + 扩展(MCP / 多 agent / web)"
 keywords = ["agent", "coding-agent", "cli", "tui", "llm", "mcp"]
 readme = "README.md"
@@ -49,6 +49,9 @@ packages = ["src/qi_agent"]
 # 手册跟包一起走:提示词里要报出**实际**路径(`paths.docs_dir()`),模型才能自己读。
 # 只打 `docs/`;`design/` 是写给改动者的,不进 wheel、不注入提示词。
 "docs" = "qi_agent/docs"
+# 移植自 pi 的素材(themes / 压缩提示词)要随包带上它们的 MIT 声明 —— 这是 MIT 的要求,
+# 只放在仓库根目录对**装包的用户**不算"随附"。
+"THIRD_PARTY_NOTICES.md" = "qi_agent/THIRD_PARTY_NOTICES.md"
 
 [tool.pytest.ini_options]
 markers = [

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/src/qi_agent/__init__.py

@@ -15,4 +15,4 @@ import os
 # 开关语义见 litellm/litellm_core_utils/get_model_cost_map.py。
 os.environ.setdefault("LITELLM_LOCAL_MODEL_COST_MAP", "True")
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/src/qi_agent/cli.py

@@ -523,8 +523,14 @@ def _run_headless(coro) -> None:
 #
 # SIGINT 不在这里:Python 默认转 KeyboardInterrupt → asyncio 取消主任务 →
 # `run_shell` 的 finally 回收子进程组(见 tools/shell.py)。
-
-_EXIT_CODE_BY_SIGNAL: dict[int, int] = {signal.SIGTERM: 143, signal.SIGHUP: 129}
+#
+# Windows 的 `signal` 模块**没有 SIGHUP**(只有 SIGTERM / SIGINT / SIGBREAK),而这里在
+# **import 时**就要求值 —— 直接写 `signal.SIGHUP` 会让整个 CLI 在 Windows 上崩在导入期。
+# 所以先探测再登记(而不是写 `hasattr` 分支:注册点也要用同一个名字)。
+_SIGHUP: int | None = getattr(signal, "SIGHUP", None)
+_EXIT_CODE_BY_SIGNAL: dict[int, int] = {signal.SIGTERM: 143}
+if _SIGHUP is not None:                  # 非 Windows 才有
+    _EXIT_CODE_BY_SIGNAL[_SIGHUP] = 129
 
 
 def _exit_code_for(signum: int) -> int:
@@ -536,6 +542,15 @@ def _exit_code_for(signum: int) -> int:
     return _EXIT_CODE_BY_SIGNAL.get(signum, 128 + signum)
 
 
+def _exit_signal_numbers() -> list[int]:
+    """要装处理器的信号:**SIGTERM + (非 Windows 的)SIGHUP**。
+
+    抽成函数是因为 Windows 上少一个 —— `_install_exit_signal_handlers` 和测试都要
+    按同一份口径列出它们(见 tests/test_interrupt.py)。
+    """
+    return [signal.SIGTERM] if _SIGHUP is None else [signal.SIGTERM, _SIGHUP]
+
+
 def _install_exit_signal_handlers() -> Callable[[], None]:
     """装 SIGTERM/SIGHUP 处理器:先回收在跑的子进程组,再按信号码退出。
 
@@ -543,16 +558,13 @@ def _install_exit_signal_handlers() -> Callable[[], None]:
     """
     from .tools.shell import kill_live_children
 
-    signals = [signal.SIGTERM]
-    if hasattr(signal, "SIGHUP"):        # Windows 没有 SIGHUP
-        signals.append(signal.SIGHUP)
     previous: dict[int, Any] = {}
 
     def handler(signum: int, _frame: object) -> None:
         kill_live_children()             # 同步:信号处理器里不能 await
         raise SystemExit(_exit_code_for(signum))
 
-    for sig in signals:
+    for sig in _exit_signal_numbers():
         try:
             previous[sig] = signal.signal(sig, handler)
         except (ValueError, OSError):    # 非主线程/平台不支持 → 跳过于净

{qi_coding_agent-0.1.0 → qi_coding_agent-0.1.1}/src/qi_agent/compaction.py

@@ -14,6 +14,10 @@
 
 qi 的差异:`custom`(助手叙述)在 qi 里**不进上下文**(见 runtime._history),所以压缩也当它
 不可见 —— 与上下文语义保持一致,不额外发明规则。
+
+> **许可**:下面的四个提示词文本(`SUMMARIZATION_SYSTEM_PROMPT` / `SUMMARIZATION_PROMPT` /
+> `UPDATE_SUMMARIZATION_PROMPT` / `TURN_PREFIX_SUMMARIZATION_PROMPT`)**逐字移植自 pi**
+> (MIT,Copyright (c) 2025 Mario Zechner)—— 改措辞前先看仓库根的 `THIRD_PARTY_NOTICES.md`。
 """
 
 from __future__ import annotations